simopt.data_farming_base
========================

.. py:module:: simopt.data_farming_base

.. autoapi-nested-parse::

   Base classes for data-farming experiments and meta-experiments.







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

.. py:data:: DATA_FARMING_DIR

.. py:data:: model_directory

.. py:data:: solver_directory

.. py:class:: DesignPoint(model: simopt.base.Model)

   Base class for design points represented as dictionaries of factors.

   Initialize a design point with a model object.

   :param model: Model with factors `model_factors`.
   :type model: Model

   :raises TypeError: If `model` is not an instance of the `Model` class.


   .. py:property:: model
      :type: simopt.base.Model


      Model to simulate.


   .. py:property:: model_factors
      :type: dict


      Model factor names and values.


   .. py:property:: rng_list
      :type: list[mrg32k3a.mrg32k3a.MRG32k3a]


      RNGs for use when running replications at the solution.


   .. py:property:: n_reps
      :type: int


      Number of replications run at a design point.


   .. py:property:: responses
      :type: dict


      Responses observed from replications.


   .. py:property:: gradients
      :type: dict


      Gradients of responses (with respect to model factors) from replications.


   .. py:method:: attach_rngs(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a], copy: bool = True) -> None

      Attach a list of random-number generators to the design point.

      :param rng_list: List of random-number generators used to run
                       simulation replications.
      :type rng_list: list[MRG32k3a]
      :param copy: Whether to copy the provided `rng_list`.
                   Defaults to True.
      :type copy: bool, optional



   .. py:method:: simulate(num_macroreps: int = 1) -> None

      Simulate macroreplications and update response and gradient data.

      :param num_macroreps: Number of macroreplications to run (> 0).
                            Defaults to 1.
      :type num_macroreps: int, optional

      :raises ValueError: If `num_macroreps` is not positive.



.. py:class:: DataFarmingExperiment(model_name: str, factor_headers: list[str], factor_settings: list[tuple[float, float, int]] | pathlib.Path | str | None = None, design_path: pathlib.Path | str | None = None, model_fixed_factors: dict | None = None, design_type: Literal['nolhs'] = 'nolhs', stacks: int = 1)

   Base class for data-farming experiments with a model and factor design.

   Initializes a data-farming experiment with a model and factor design.

   Either `factor_settings` or `design_path` must be provided.

   :param model_name: Name of the model to run.
   :type model_name: str
   :param factor_headers: Ordered list of factor names in the
                          settings/design file.
   :type factor_headers: list[str]
   :param factor_settings: Either a list of tuples (min, max, decimals) specifying factor ranges
                           and precision digits, or a Path/str to a .txt file containing
                           this information.
   :type factor_settings: list[tuple[float, float, int]] | Path | str | None, optional
   :param design_path: Path to the design matrix file.
                       Defaults to None.
   :type design_path: Path | str | None, optional
   :param model_fixed_factors: Fixed model factor values that are
                               not varied.
   :type model_fixed_factors: dict, optional
   :param design_type: Design type to use.
                       Defaults to "nolhs".
   :type design_type: Literal["nolhs"], optional
   :param stacks: Number of stacks in the design. Defaults to 1.
   :type stacks: int, optional

   :raises ValueError: If `model_name` is invalid or `design_type` is unsupported.
   :raises FileNotFoundError: If any specified file path does not exist.


   .. py:attribute:: model


   .. py:attribute:: n_design_pts


   .. py:attribute:: design
      :value: []



   .. py:method:: run(n_reps: int = 10, crn_across_design_pts: bool = True) -> None

      Run a fixed number of macroreplications at each design point.

      :param n_reps: Number of replications run at each design point.
                     Defaults to 10.
      :type n_reps: int, optional
      :param crn_across_design_pts: Whether to use common random numbers
                                    (CRN) across design points. Defaults to True.
      :type crn_across_design_pts: bool, optional

      :raises ValueError: If `n_reps` is not positive.



   .. py:method:: print_to_csv(csv_file_name: pathlib.Path | str = 'raw_results', overwrite: bool = False) -> None

      Writes simulated responses for all design points to a CSV file.

      :param csv_file_name: Output file name (with or without
                            .csv extension). Defaults to "raw_results".
      :type csv_file_name: Path | str, optional
      :param overwrite: If True, overwrite existing file. Otherwise,
                        raises an error if the file already exists. Defaults to False.
      :type overwrite: bool, optional