simopt.models.ironore
=====================

.. py:module:: simopt.models.ironore

.. autoapi-nested-parse::

   Simulate production and sales over multiple periods for an iron ore inventory.





Module Contents
---------------

.. py:class:: IronOreConfig

   Bases: :py:obj:`pydantic.BaseModel`


   Configuration model for Iron Ore Inventory simulation.

   A model that simulates multiple periods of production and sales for an
   inventory problem with stochastic price determined by a mean-reverting
   random walk. Returns total profit, fraction of days producing iron, and
   mean stock.


   .. py:attribute:: mean_price
      :type:  Annotated[float, Field(default=100.0, description='mean iron ore price per unit', gt=0)]


   .. py:attribute:: max_price
      :type:  Annotated[float, Field(default=200.0, description='maximum iron ore price per unit', gt=0)]


   .. py:attribute:: min_price
      :type:  Annotated[float, Field(default=0.0, description='minimum iron ore price per unit', ge=0)]


   .. py:attribute:: capacity
      :type:  Annotated[int, Field(default=10000, description='maximum holding capacity', ge=0)]


   .. py:attribute:: st_dev
      :type:  Annotated[float, Field(default=7.5, description='standard deviation of random walk steps for price', gt=0)]


   .. py:attribute:: holding_cost
      :type:  Annotated[float, Field(default=1.0, description='holding cost per unit per period', gt=0)]


   .. py:attribute:: prod_cost
      :type:  Annotated[float, Field(default=100.0, description='production cost per unit', gt=0)]


   .. py:attribute:: max_prod_perday
      :type:  Annotated[int, Field(default=100, description='maximum units produced per day', gt=0)]


   .. py:attribute:: price_prod
      :type:  Annotated[float, Field(default=80.0, description='price level to start production', gt=0)]


   .. py:attribute:: inven_stop
      :type:  Annotated[int, Field(default=7000, description='inventory level to cease production', gt=0)]


   .. py:attribute:: price_stop
      :type:  Annotated[float, Field(default=40.0, description='price level to stop production', gt=0)]


   .. py:attribute:: price_sell
      :type:  Annotated[float, Field(default=100.0, description='price level to sell all stock', gt=0)]


   .. py:attribute:: n_days
      :type:  Annotated[int, Field(default=365, description='number of days to simulate', ge=1, json_schema_extra={'isDatafarmable': False})]


.. py:class:: IronOreMaxRevCntConfig

   Bases: :py:obj:`pydantic.BaseModel`


   Configuration model for Iron Ore Max Revenue Continuous Problem.

   Max Revenue for Continuous Iron Ore simulation-optimization problem.


   .. py:attribute:: initial_solution
      :type:  Annotated[tuple[float, Ellipsis], Field(default=(80, 40, 100), description='initial solution')]


   .. py:attribute:: budget
      :type:  Annotated[int, Field(default=1000, description='max # of replications for a solver to take', gt=0)]


.. py:class:: IronOreMaxRevConfig

   Bases: :py:obj:`pydantic.BaseModel`


   Configuration model for Iron Ore Max Revenue Problem.

   Max Revenue for Iron Ore simulation-optimization problem.


   .. py:attribute:: initial_solution
      :type:  Annotated[tuple[float, Ellipsis], Field(default=(80, 7000, 40, 100), description='initial solution')]


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


.. py:class:: MovementInputModel

   Bases: :py:obj:`simopt.input_models.InputModel`


   Input model for mining movement and price shocks.


   .. py:attribute:: rng
      :type:  random.Random | None
      :value: None



   .. py:method:: random(mean: float, std: float) -> float

      Generate a random variate from the input model.

      :returns: A random variate from the input model.
      :rtype: T



.. py:class:: IronOre(fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Model`


   Iron Ore Inventory Model.

   A model that simulates multiple periods of production and sales for an
   inventory problem with stochastic price determined by a mean-reverting
   random walk. Returns total profit, fraction of days producing iron, and
   mean stock.

   Initialize the Iron Ore Inventory Model.

   :param fixed_factors: Fixed factors for the model.
                         Defaults to None.
   :type fixed_factors: dict, optional


   .. py:attribute:: class_name_abbr
      :type:  ClassVar[str]
      :value: 'IRONORE'


      Short name of the model class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'Iron Ore'


      Long name of the model class.


   .. py:attribute:: config_class
      :type:  ClassVar[type[pydantic.BaseModel]]

      Configuration class for the model.


   .. py:attribute:: n_rngs
      :type:  ClassVar[int]
      :value: 1


      Number of RNGs used to run a simulation replication.


   .. py:attribute:: n_responses
      :type:  ClassVar[int]
      :value: 3


      Number of responses (performance measures).


   .. py:attribute:: movement_model


   .. py:method:: before_replicate(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]) -> None

      Prepare the model just before generating a replication.

      :param rng_list: RNGs used to drive the simulation.
      :type rng_list: list[MRG32k3a]

      :raises NotImplementedError: If the subclass does not implement this hook.



   .. py:method:: replicate() -> tuple[dict, dict]

      Simulate a single replication for the current model factors.

      :param rng_list: Random number generators used to simulate
                       the replication.
      :type rng_list: list[MRG32k3a]

      :returns:

                A tuple containing:
                    - responses (dict): Performance measures of interest, including:
                        - "total_profit": The total profit over the time period.
                        - "frac_producing": The fraction of days spent producing iron ore.
                        - "mean_stock": The average stock over the time period.
                    - gradients (dict): A dictionary of gradient estimates for each
                        response.
      :rtype: tuple[dict, dict]



.. py:class:: IronOreMaxRev(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Problem`


   Class to make iron ore inventory simulation-optimization problems.

   Initialize a problem object.

   :param name: Name of the problem.
   :type name: str
   :param fixed_factors: Dictionary of user-specified problem factors.
   :type fixed_factors: dict | None
   :param model_fixed_factors: Subset of user-specified non-decision
                               factors passed to the model.
   :type model_fixed_factors: dict | None


   .. py:attribute:: class_name_abbr
      :type:  ClassVar[str]
      :value: 'IRONORE-1'


      Short name of the problem class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'Max Revenue for Iron Ore'


      Long name of the problem class.


   .. py:attribute:: config_class
      :type:  ClassVar[type[pydantic.BaseModel]]

      Configuration class for problem.


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

      Simulation model class for problem.


   .. py:attribute:: n_objectives
      :type:  ClassVar[int]
      :value: 1


      Number of objectives.


   .. py:attribute:: n_stochastic_constraints
      :type:  ClassVar[int]
      :value: 0


      Number of stochastic constraints.


   .. py:attribute:: minmax
      :type:  ClassVar[tuple[int, Ellipsis]]
      :value: (1,)


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


   .. py:attribute:: constraint_type
      :type:  ClassVar[simopt.base.ConstraintType]

      Description of constraints types.


   .. py:attribute:: variable_type
      :type:  ClassVar[simopt.base.VariableType]

      Description of variable types.


   .. py:attribute:: gradient_available
      :type:  ClassVar[bool]
      :value: False


      Indicates whether the solver provides direct gradient information.


   .. py:attribute:: optimal_value
      :type:  ClassVar[float | None]
      :value: None


      Optimal objective function value (if known).


   .. py:attribute:: optimal_solution
      :type:  tuple | None
      :value: None


      Optimal solution if known; defaults to None.


   .. py:attribute:: model_default_factors
      :type:  ClassVar[dict]

      Default values for overriding model-level default factors.


   .. py:attribute:: model_decision_factors
      :type:  ClassVar[set[str]]

      Set of keys for factors that are decision variables.


   .. py:property:: dim
      :type: int


      Number of decision variables.


   .. py:property:: lower_bounds
      :type: tuple


      Lower bound for each decision variable.


   .. py:property:: upper_bounds
      :type: tuple


      Upper bound for each decision variable.


   .. py:method:: vector_to_factor_dict(vector: tuple) -> dict

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

      :param vector: A vector of values associated with decision variables.
      :type vector: tuple

      :returns: Dictionary with factor keys and associated values.
      :rtype: dict



   .. py:method:: factor_dict_to_vector(factor_dict: dict) -> tuple

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

      :param factor_dict: Dictionary with factor keys and associated values.
      :type factor_dict: dict

      :returns: Vector of values associated with decision variables.
      :rtype: tuple



   .. py:method:: replicate(_x: tuple) -> simopt.base.RepResult

      Replicate the problem for a given solution.

      :param x: The solution to evaluate.
      :type x: tuple



   .. py:method:: get_random_solution(rand_sol_rng: mrg32k3a.mrg32k3a.MRG32k3a) -> tuple

      Generate a random solution for starting or restarting solvers.

      :param rand_sol_rng: Random number generator used to sample the
                           solution.
      :type rand_sol_rng: MRG32k3a

      :returns:

                A tuple representing a randomly generated vector of decision
                    variables.
      :rtype: tuple



.. py:class:: IronOreMaxRevCnt(name: str = '', fixed_factors: dict | None = None, model_fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Problem`


   Class to make iron ore inventory simulation-optimization problems.

   Initialize a problem object.

   :param name: Name of the problem.
   :type name: str
   :param fixed_factors: Dictionary of user-specified problem factors.
   :type fixed_factors: dict | None
   :param model_fixed_factors: Subset of user-specified non-decision
                               factors passed to the model.
   :type model_fixed_factors: dict | None


   .. py:attribute:: class_name_abbr
      :type:  ClassVar[str]
      :value: 'IRONORECONT-1'


      Short name of the problem class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'Max Revenue for Continuous Iron Ore'


      Long name of the problem class.


   .. py:attribute:: config_class
      :type:  ClassVar[type[pydantic.BaseModel]]

      Configuration class for problem.


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

      Simulation model class for problem.


   .. py:attribute:: n_objectives
      :type:  ClassVar[int]
      :value: 1


      Number of objectives.


   .. py:attribute:: n_stochastic_constraints
      :type:  ClassVar[int]
      :value: 0


      Number of stochastic constraints.


   .. py:attribute:: minmax
      :type:  ClassVar[tuple[int, Ellipsis]]
      :value: (1,)


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


   .. py:attribute:: constraint_type
      :type:  ClassVar[simopt.base.ConstraintType]

      Description of constraints types.


   .. py:attribute:: variable_type
      :type:  ClassVar[simopt.base.VariableType]

      Description of variable types.


   .. py:attribute:: gradient_available
      :type:  ClassVar[bool]
      :value: False


      Indicates whether the solver provides direct gradient information.


   .. py:attribute:: optimal_value
      :type:  ClassVar[float | None]
      :value: None


      Optimal objective function value (if known).


   .. py:attribute:: optimal_solution
      :type:  tuple | None
      :value: None


      Optimal solution if known; defaults to None.


   .. py:attribute:: model_default_factors
      :type:  ClassVar[dict]

      Default values for overriding model-level default factors.


   .. py:attribute:: model_decision_factors
      :type:  ClassVar[set[str]]

      Set of keys for factors that are decision variables.


   .. py:property:: dim
      :type: int


      Number of decision variables.


   .. py:property:: lower_bounds
      :type: tuple


      Lower bound for each decision variable.


   .. py:property:: upper_bounds
      :type: tuple


      Upper bound for each decision variable.


   .. py:method:: vector_to_factor_dict(vector: tuple) -> dict

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

      :param vector: A vector of values associated with decision variables.
      :type vector: tuple

      :returns: Dictionary with factor keys and associated values.
      :rtype: dict



   .. py:method:: factor_dict_to_vector(factor_dict: dict) -> tuple

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

      :param factor_dict: Dictionary with factor keys and associated values.
      :type factor_dict: dict

      :returns: Vector of values associated with decision variables.
      :rtype: tuple



   .. py:method:: replicate(_x: tuple) -> simopt.base.RepResult

      Replicate the problem for a given solution.

      :param x: The solution to evaluate.
      :type x: tuple



   .. py:method:: check_deterministic_constraints(x: tuple) -> bool

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

      :param x: A vector of decision variables.
      :type x: tuple

      :returns:

                True if the solution satisfies all deterministic constraints;
                    False otherwise.
      :rtype: bool



   .. py:method:: get_random_solution(rand_sol_rng: mrg32k3a.mrg32k3a.MRG32k3a) -> tuple

      Generate a random solution for starting or restarting solvers.

      :param rand_sol_rng: Random number generator used to sample the
                           solution.
      :type rand_sol_rng: MRG32k3a

      :returns:

                A tuple representing a randomly generated vector of decision
                    variables.
      :rtype: tuple