simopt.experiment_base
======================

.. py:module:: simopt.experiment_base

.. autoapi-nested-parse::

   Base classes for problem-solver pairs and I/O/plotting helper functions.







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

.. py:data:: model_directory

.. py:data:: problem_directory

.. py:data:: solver_directory

.. py:function:: read_experiment_results(file_name_path: pathlib.Path | str) -> simopt.experiment.ProblemSolver

   Reads a ProblemSolver object from a .pickle file.

   :param file_name_path: Path to the .pickle file.
   :type file_name_path: Path | str

   :returns:

             Loaded problem-solver pair that was previously run or
                 post-processed.
   :rtype: ProblemSolver

   :raises ValueError: If the file does not exist.


.. py:function:: read_group_experiment_results(file_path: pathlib.Path | str) -> simopt.experiment.ProblemsSolvers

   Reads a ProblemsSolvers object from a .pickle file.

   :param file_path: Path to the .pickle file.
   :type file_path: Path

   :returns:

             A group of problem-solver experiments that were run
                 or post-processed.
   :rtype: ProblemsSolvers

   :raises FileNotFoundError: If the file does not exist.


.. py:function:: find_unique_solvers_problems(experiments: list[simopt.experiment.ProblemSolver]) -> tuple[list[simopt.base.Solver], list[simopt.base.Problem]]

   Finds unique solvers and problems from a list of ProblemSolver experiments.

   :param experiments: List of problem-solver pairs.
   :type experiments: list[ProblemSolver]

   :returns:

             A tuple containing:
                 - A list of unique solvers.
                 - A list of unique problems.
   :rtype: tuple[list[Solver], list[Problem]]


.. py:function:: find_missing_experiments(experiments: list[simopt.experiment.ProblemSolver]) -> tuple[list[simopt.base.Solver], list[simopt.base.Problem], list[tuple[simopt.base.Solver, simopt.base.Problem]]]

   Finds missing problem-solver pairs from a list of experiments.

   :param experiments: List of problem-solver pairs.
   :type experiments: list[ProblemSolver]

   :returns:

             A tuple containing:
                 - list[Solver]: Unique solvers present in the experiments.
                 - list[Problem]: Unique problems present in the experiments.
                 - list[tuple[Solver, Problem]]: Problem-solver pairs that are missing.
   :rtype: tuple


.. py:function:: make_full_metaexperiment(existing_experiments: list[simopt.experiment.ProblemSolver], unique_solvers: list[simopt.base.Solver], unique_problems: list[simopt.base.Problem], missing_experiments: list[tuple[simopt.base.Solver, simopt.base.Problem]]) -> simopt.experiment.ProblemsSolvers

   Creates experiments for missing problem-solver pairs.

   :param existing_experiments: Existing problem-solver experiments.
   :type existing_experiments: list[ProblemSolver]
   :param unique_solvers: Solvers present in the existing experiments.
   :type unique_solvers: list[Solver]
   :param unique_problems: Problems present in the existing experiments.
   :type unique_problems: list[Problem]
   :param missing_experiments: Problem-solver pairs that
                               have not yet been run.
   :type missing_experiments: list[tuple[Solver, Problem]]

   :returns: A new ProblemsSolvers object containing the completed set.
   :rtype: ProblemsSolvers


.. py:function:: create_design_list_from_table(design_table: pandas.DataFrame) -> list[dict[str, Any]]

   Create a list of solver or problem objects for each design point.

   :param design_table: DataFrame containing the design table.
                        Each row represents a design point, and each column represents a factor.
   :type design_table: DataFrame

   :returns: List of dictionaries, where each list entry corresponds
             to a design point, and each dictionary contains the name and values for each
             factor in that design point.
   :rtype: list[dict[str, Any]]


.. py:function:: create_design(name: str, factor_headers: list[str], factor_settings: list[tuple[float, float, int]] | pathlib.Path, fixed_factors: dict | None = None, cross_design_factors: dict | None = None, design_type: Literal['nolhs'] = 'nolhs', n_stacks: int = 1) -> list[dict[str, Any]]

   Creates a design of solver, problem, or model factors.

   Please ensure the indexing of the factor_headers argument matches the indexing of
   the factor_settings argument.

   :param name: Name of the solver, problem, or model.
   :type name: str
   :param factor_headers: Names of factors that vary in the design.
   :type factor_headers: list[str]
   :param factor_settings: A list of tuples, each of the form (min, max, # decimals)
                           or a Path to a .txt file containing those factor settings.
   :type factor_settings: list[tuple[float, float, int]] | Path
   :param fixed_factors: Dictionary of fixed factor values that
                         override defaults.
   :type fixed_factors: dict, optional
   :param cross_design_factors: Dictionary of lists of cross-design
                                factor values. Defaults to None.
   :type cross_design_factors: dict, optional
   :param design_type: Type of design. Defaults to "nolhs".
   :type design_type: Literal["nolhs"], optional
   :param n_stacks: Number of stacks. Defaults to 1.
   :type n_stacks: int, optional

   :returns:

             A list of dictionaries, where each dictionary represents
                 a design.
   :rtype: list[dict[str, Any]]

   :raises ValueError: If input validation fails.
   :raises Exception: If the design type is unsupported.