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:: DesignType(*args, **kwds) Bases: :py:obj:`enum.Enum` Enum for design types. .. py:attribute:: NOLHS :value: 'nolhs' .. 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 .. py:class:: 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. :param solver_name: Name of the solver. :type solver_name: str, optional :param solver_factor_headers: Ordered list of solver factor names from the settings/design file. :type solver_factor_headers: list[str], optional :param n_stacks: Number of stacks in the design. Must be > 0. :type n_stacks: int :param design_type: Design type to use. Defaults to "nolhs". :type design_type: Literal["nolhs"], optional :param solver_factor_settings_file_path: Path to the .txt file defining solver factor ranges and precision. :type solver_factor_settings_file_path: Path | str | None, optional :param design_file_path: Path to the design matrix file. :type design_file_path: Path | str | None, optional :param csv_file_path: Path to the CSV file containing design data. :type csv_file_path: Path | str | None, optional :param solver_fixed_factors: Solver factors to hold fixed. :type solver_fixed_factors: dict, optional :param cross_design_factors: Cross-design factor values to include. :type cross_design_factors: dict, optional :raises ValueError: If solver name is invalid, stacks ≤ 0, or design type is unsupported. :raises FileNotFoundError: If any given path does not exist. .. py:attribute:: design_table_path :value: None .. py:method:: 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. :param problem_name: Name of the problem. :type problem_name: str :param problem_fixed_factors: Dictionary of user-specified problem factors that will not be varied. :type problem_fixed_factors: dict | None, optional :param model_fixed_factors: Dictionary of user-specified model factors that will not be varied. :type model_fixed_factors: dict | None, optional :param n_macroreps: Number of macroreplications for each design point. :type n_macroreps: int :raises ValueError: If `n_macroreps` is less than or equal to 0. .. py:method:: 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. :param n_postreps: Number of postreplications per recommended solution. :type n_postreps: int :param crn_across_budget: If True, use CRN across solutions from different time budgets. Defaults to True. :type crn_across_budget: bool, optional :param crn_across_macroreps: If True, use CRN across different macroreplications. Defaults to False. :type crn_across_macroreps: bool, optional :raises ValueError: If `n_postreps` is not positive. .. py:method:: post_normalize(n_postreps_init_opt: int, crn_across_init_opt: bool = True) -> None Post-normalizes all problem-solver pairs in the design. :param n_postreps_init_opt: Number of postreplications at x0 and x*. :type n_postreps_init_opt: int :param crn_across_init_opt: If True, use CRN across x0 and x*. Defaults to True. :type crn_across_init_opt: bool, optional :raises ValueError: If `n_postreps_init_opt` is not positive. .. py:method:: 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. :param solve_tols: Optimality gaps for considering a problem solved (values in (0, 1]). Defaults to [0.05, 0.10, 0.20, 0.50]. :type solve_tols: list[float], optional :param csv_file_name: Name of the output CSV file. Defaults to "df_solver_results.csv". :type csv_file_name: Path | str | None, optional