simopt.data_farming_base

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

Module Contents

simopt.data_farming_base.DATA_FARMING_DIR
simopt.data_farming_base.model_directory
simopt.data_farming_base.solver_directory
class simopt.data_farming_base.DesignPoint(model: simopt.base.Model)

Base class for design points represented as dictionaries of factors.

Initialize a design point with a model object.

Parameters:

model (Model) – Model with factors model_factors.

Raises:

TypeError – If model is not an instance of the Model class.

property model: simopt.base.Model

Model to simulate.

property model_factors: dict

Model factor names and values.

property rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a]

RNGs for use when running replications at the solution.

property n_reps: int

Number of replications run at a design point.

property responses: dict

Responses observed from replications.

property gradients: dict

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

attach_rngs(rng_list: list[mrg32k3a.mrg32k3a.MRG32k3a], copy: bool = True) → None

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

Parameters:

  • rng_list (list[MRG32k3a]) – List of random-number generators used to run simulation replications.

  • copy (bool, optional) – Whether to copy the provided rng_list. Defaults to True.

simulate(num_macroreps: int = 1) → None

Simulate macroreplications and update response and gradient data.

Parameters:

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

Raises:

ValueError – If num_macroreps is not positive.

class simopt.data_farming_base.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.

Parameters:

  • model_name (str) – Name of the model to run.

  • factor_headers (list[str]) – Ordered list of factor names in the settings/design file.

  • factor_settings (list[tuple[float, float, int]] | Path | str | None, optional) – 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.

  • design_path (Path | str | None, optional) – Path to the design matrix file. Defaults to None.

  • model_fixed_factors (dict, optional) – Fixed model factor values that are not varied.

  • design_type (Literal["nolhs"], optional) – Design type to use. Defaults to “nolhs”.

  • stacks (int, optional) – Number of stacks in the design. Defaults to 1.

Raises:

  • ValueError – If model_name is invalid or design_type is unsupported.

  • FileNotFoundError – If any specified file path does not exist.

model
n_design_pts
design = []
run(n_reps: int = 10, crn_across_design_pts: bool = True) → None

Run a fixed number of macroreplications at each design point.

Parameters:

  • n_reps (int, optional) – Number of replications run at each design point. Defaults to 10.

  • crn_across_design_pts (bool, optional) – Whether to use common random numbers (CRN) across design points. Defaults to True.

Raises:

ValueError – If n_reps is not positive.

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.

Parameters:

  • csv_file_name (Path | str, optional) – Output file name (with or without .csv extension). Defaults to “raw_results”.

  • overwrite (bool, optional) – If True, overwrite existing file. Otherwise, raises an error if the file already exists. Defaults to False.