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.DesignType(*args, **kwds)

Bases: enum.Enum

Enum for design types.

NOLHS = 'nolhs'
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.

class simopt.data_farming_base.DataFarmingMetaExperiment(solver_name: str | None = None, solver_factor_headers: list[str] | None = None, n_stacks: int = 1, design_type: Literal['nolhs'] = 'nolhs', solver_factor_settings_file_path: pathlib.Path | str | None = None, design_file_path: pathlib.Path | str | None = None, csv_file_path: pathlib.Path | str | None = None, solver_fixed_factors: dict | None = None, cross_design_factors: dict | None = None)

Base class for data-farming meta-experiments with problem-solver designs.

Initializes a meta-experiment with a solver and a factor design.

Parameters:

  • solver_name (str, optional) – Name of the solver.

  • solver_factor_headers (list[str], optional) – Ordered list of solver factor names from the settings/design file.

  • n_stacks (int) – Number of stacks in the design. Must be > 0.

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

  • solver_factor_settings_file_path (Path | str | None, optional) – Path to the .txt file defining solver factor ranges and precision.

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

  • csv_file_path (Path | str | None, optional) – Path to the CSV file containing design data.

  • solver_fixed_factors (dict, optional) – Solver factors to hold fixed.

  • cross_design_factors (dict, optional) – Cross-design factor values to include.

Raises:

  • ValueError – If solver name is invalid, stacks ≤ 0, or design type is unsupported.

  • FileNotFoundError – If any given path does not exist.

design_table_path = None
run(problem_name: str, problem_fixed_factors: dict | None = None, model_fixed_factors: dict | None = None, n_macroreps: int = 10) → None

Run n_macroreps of each problem-solver design point.

Parameters:

  • problem_name (str) – Name of the problem.

  • problem_fixed_factors (dict | None, optional) – Dictionary of user-specified problem factors that will not be varied.

  • model_fixed_factors (dict | None, optional) – Dictionary of user-specified model factors that will not be varied.

  • n_macroreps (int) – Number of macroreplications for each design point.

Raises:

ValueError – If n_macroreps is less than or equal to 0.

post_replicate(n_postreps: int, crn_across_budget: bool = True, crn_across_macroreps: bool = False) → None

Runs postreplications for each design point on all macroreplications.

Parameters:

  • n_postreps (int) – Number of postreplications per recommended solution.

  • crn_across_budget (bool, optional) – If True, use CRN across solutions from different time budgets. Defaults to True.

  • crn_across_macroreps (bool, optional) – If True, use CRN across different macroreplications. Defaults to False.

Raises:

ValueError – If n_postreps is not positive.

post_normalize(n_postreps_init_opt: int, crn_across_init_opt: bool = True) → None

Post-normalizes all problem-solver pairs in the design.

Parameters:

  • n_postreps_init_opt (int) – Number of postreplications at x0 and x*.

  • crn_across_init_opt (bool, optional) – If True, use CRN across x0 and x*. Defaults to True.

Raises:

ValueError – If n_postreps_init_opt is not positive.

report_statistics(solve_tols: list[float] | None = None, csv_file_name: pathlib.Path | str | None = None) → None

Calculates and writes macroreplication statistics for each design point.

Parameters:

  • solve_tols (list[float], optional) – Optimality gaps for considering a problem solved (values in (0, 1]). Defaults to [0.05, 0.10, 0.20, 0.50].

  • csv_file_name (Path | str | None, optional) – Name of the output CSV file. Defaults to “df_solver_results.csv”.