simopt.models.facilitysizing

Simulate demand at facilities.

Module Contents

simopt.models.facilitysizing.NUM_FACILITIES: Final[int] = 3

class simopt.models.facilitysizing.FacilitySizeConfig

Bases: pydantic.BaseModel

Configuration model for Facility Sizing simulation.

A model that simulates a facility size problem with a multi-variate normal distribution. Returns the probability of violating demand in each scenario.

mean_vec: Annotated[list[float], Field(default_factory=lambda: [100] * NUM_FACILITIES, description='location parameters of the multivariate normal distribution')]

cov: Annotated[list[list[float]], Field(default_factory=lambda: [[2000, 1500, 500], [1500, 2000, 750], [500, 750, 2000]], description='covariance of multivariate normal distribution')]

capacity: Annotated[list[float], Field(default=[150, 300, 400], description='capacity')]

n_fac: Annotated[int, Field(default=NUM_FACILITIES, description='number of facilities', gt=0, json_schema_extra={'isDatafarmable': False})]

class simopt.models.facilitysizing.FacilitySizingMaxServiceConfig

Bases: pydantic.BaseModel

Configuration model for Facility Sizing Max Service Problem.

Max Service for Facility Sizing simulation-optimization problem.

initial_solution: Annotated[tuple[float, Ellipsis], Field(default_factory=lambda: (100, ) * NUM_FACILITIES, description='Initial solution from which solvers start.')]

budget: Annotated[int, Field(default=10000, description='Max # of replications for a solver to take.', gt=0)]

installation_costs: Annotated[tuple[float, Ellipsis], Field(default_factory=lambda: (1, ) * NUM_FACILITIES, description='Cost to install a unit of capacity at each facility.')]

installation_budget: Annotated[float, Field(default=500.0, description='Total budget for installation costs.', gt=0)]

class simopt.models.facilitysizing.FacilitySizingTotalCostConfig

Bases: pydantic.BaseModel

Configuration model for Facility Sizing Total Cost Problem.

Min Total Cost for Facility Sizing simulation-optimization problem.

initial_solution: Annotated[tuple[float, Ellipsis], Field(default_factory=lambda: (300, ) * NUM_FACILITIES, description='Initial solution from which solvers start.')]

budget: Annotated[int, Field(default=10000, description='Max # of replications for a solver to take.', gt=0, json_schema_extra={'isDatafarmable': False})]

installation_costs: Annotated[tuple[float, Ellipsis], Field(default_factory=lambda: (1, ) * NUM_FACILITIES, description='Cost to install a unit of capacity at each facility.')]

epsilon: Annotated[float, Field(default=0.05, description='Maximum allowed probability of stocking out.', ge=0, le=1)]

class simopt.models.facilitysizing.DemandInputModel

Bases: simopt.input_models.InputModel

Input model for multivariate normal demand at facilities.

rng: random.Random | None = None

random(mean: numpy.ndarray, cov: numpy.ndarray) → numpy.ndarray

Generate a random variate from the input model.

Returns:

A random variate from the input model.

Return type:

T

class simopt.models.facilitysizing.FacilitySize(fixed_factors: dict | None = None)

Bases: simopt.base.Model

Facility Sizing Model.

A model that simulates a facilitysize problem with a multi-variate normal distribution. Returns the probability of violating demand in each scenario.

Initialize the FacilitySize model.

Parameters:

fixed_factors (dict | None) – Fixed factors for the model. If None, default values are used.

class_name_abbr: ClassVar[str] = 'FACSIZE'

Short name of the model class.

class_name: ClassVar[str] = 'Facility Sizing'

Long name of the model class.

config_class: ClassVar[type[pydantic.BaseModel]]

Configuration class for the model.

n_rngs: ClassVar[int] = 1

Number of RNGs used to run a simulation replication.

n_responses: ClassVar[int] = 3

Number of responses (performance measures).

demand_model

before_replicate(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) → None

Prepare the model just before generating a replication.

Parameters:

rng_list (list[MRG32k3a]) – RNGs used to drive the simulation.

Raises:

NotImplementedError – If the subclass does not implement this hook.

replicate() → tuple[dict, dict]

Simulate a single replication using the current model factors.

Parameters:

rng_list (list[MRG32k3a]) – Random number generators for the model to use when simulating a replication.

Returns:

A tuple containing:

• dict: The responses dictionary, with keys:

  • ”stockout_flag” (bool): True if at least one facility failed to satisfy demand;

    False otherwise.

  • ”n_fac_stockout” (int): Number of facilities that could not satisfy demand.

  • ”n_cut” (int): Total number of demand units that could not be satisfied.

• dict: Gradient estimates for each response.

Return type:

tuple

class simopt.models.facilitysizing.FacilitySizingTotalCost(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

Bases: simopt.base.Problem

Base class to implement simulation-optimization problems.

Initialize a problem object.

Parameters:

• name (str) – Name of the problem.

• fixed_factors (dict | None) – Dictionary of user-specified problem factors.

• model_fixed_factors (dict | None) – Subset of user-specified non-decision factors passed to the model.

class_name_abbr: ClassVar[str] = 'FACSIZE-1'

Short name of the problem class.

class_name: ClassVar[str] = 'Min Total Cost for Facility Sizing'

Long name of the problem class.

config_class: ClassVar[type[pydantic.BaseModel]]

Configuration class for problem.

model_class: ClassVar[type[simopt.base.Model]]

Simulation model class for problem.

n_objectives: ClassVar[int] = 1

Number of objectives.

n_stochastic_constraints: ClassVar[int] = 1

Number of stochastic constraints.

minmax: ClassVar[tuple[int, Ellipsis]]

Indicators of maximization (+1) or minimization (-1) for each objective.

constraint_type: ClassVar[simopt.base.ConstraintType]

Description of constraints types.

variable_type: ClassVar[simopt.base.VariableType]

Description of variable types.

gradient_available: ClassVar[bool] = True

Indicates whether the solver provides direct gradient information.

optimal_value: ClassVar[float | None] = None

Optimal objective function value (if known).

optimal_solution: tuple | None = None

Optimal solution if known; defaults to None.

model_default_factors: ClassVar[dict]

Default values for overriding model-level default factors.

model_decision_factors: ClassVar[set[str]]

Set of keys for factors that are decision variables.

property dim: int

Number of decision variables.

property lower_bounds: tuple

Lower bound for each decision variable.

property upper_bounds: tuple

Upper bound for each decision variable.

vector_to_factor_dict(vector: tuple) → dict

Convert a vector of variables to a dictionary with factor keys.

Parameters:

vector (tuple) – A vector of values associated with decision variables.

Returns:

Dictionary with factor keys and associated values.

Return type:

dict

factor_dict_to_vector(factor_dict: dict) → tuple

Convert a dictionary with factor keys to a vector of variables.

Parameters:

factor_dict (dict) – Dictionary with factor keys and associated values.

Returns:

Vector of values associated with decision variables.

Return type:

tuple

replicate(x: tuple) → simopt.base.RepResult

Replicate the problem for a given solution.

Parameters:

x (tuple) – The solution to evaluate.

get_random_solution(rand_sol_rng: mrg32k3a.mrg32k3a.MRG32k3a) → tuple

Generate a random solution for starting or restarting solvers.

Parameters:

rand_sol_rng (MRG32k3a) – Random number generator used to sample the solution.

Returns:

A tuple representing a randomly generated vector of decision

variables.

Return type:

tuple

class simopt.models.facilitysizing.FacilitySizingMaxService(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

Bases: simopt.base.Problem

Base class to implement simulation-optimization problems.

Initialize a problem object.

Parameters:

• name (str) – Name of the problem.

• fixed_factors (dict | None) – Dictionary of user-specified problem factors.

• model_fixed_factors (dict | None) – Subset of user-specified non-decision factors passed to the model.

class_name_abbr: ClassVar[str] = 'FACSIZE-2'

Short name of the problem class.

class_name: ClassVar[str] = 'Max Service for Facility Sizing'

Long name of the problem class.

config_class: ClassVar[type[pydantic.BaseModel]]

Configuration class for problem.

model_class: ClassVar[type[simopt.base.Model]]

Simulation model class for problem.

n_objectives: ClassVar[int] = 1

Number of objectives.

n_stochastic_constraints: ClassVar[int] = 0

Number of stochastic constraints.

minmax: ClassVar[tuple[int, Ellipsis]] = (1,)

Indicators of maximization (+1) or minimization (-1) for each objective.

constraint_type: ClassVar[simopt.base.ConstraintType]

Description of constraints types.

variable_type: ClassVar[simopt.base.VariableType]

Description of variable types.

gradient_available: ClassVar[bool] = False

Indicates whether the solver provides direct gradient information.

optimal_value: ClassVar[float | None] = None

Optimal objective function value (if known).

optimal_solution: tuple | None = None

Optimal solution if known; defaults to None.

model_default_factors: ClassVar[dict]

Default values for overriding model-level default factors.

model_decision_factors: ClassVar[set[str]]

Set of keys for factors that are decision variables.

property dim: int

Number of decision variables.

property lower_bounds: tuple

Lower bound for each decision variable.

property upper_bounds: tuple

Upper bound for each decision variable.

vector_to_factor_dict(vector: tuple) → dict

Convert a vector of variables to a dictionary with factor keys.

Parameters:

vector (tuple) – A vector of values associated with decision variables.

Returns:

Dictionary with factor keys and associated values.

Return type:

dict

factor_dict_to_vector(factor_dict: dict) → tuple

Convert a dictionary with factor keys to a vector of variables.

Parameters:

factor_dict (dict) – Dictionary with factor keys and associated values.

Returns:

Vector of values associated with decision variables.

Return type:

tuple

replicate(_x: tuple) → simopt.base.RepResult

Replicate the problem for a given solution.

Parameters:

x (tuple) – The solution to evaluate.

check_deterministic_constraints(x: tuple) → bool

Check if a solution x satisfies the problem’s deterministic constraints.

Parameters:

x (tuple) – A vector of decision variables.

Returns:

True if the solution satisfies all deterministic constraints;

False otherwise.

Return type:

bool

get_random_solution(rand_sol_rng: mrg32k3a.mrg32k3a.MRG32k3a) → tuple

Generate a random solution for starting or restarting solvers.

Parameters:

rand_sol_rng (MRG32k3a) – Random number generator used to sample the solution.

Returns:

A tuple representing a randomly generated vector of decision

variables.

Return type:

tuple