The minimize and maximize Functions

Both optimization functions have the exactly same interface. In fact, maximize just switches the sign of your criterion function and calls minimize.

estimagic.optimization.optimize.minimize(criterion, params, algorithm, criterion_kwargs=None, constraints=None, general_options=None, algo_options=None, gradient_options=None, logging='logging.db', log_options=None, dashboard=False, dash_options=None)[source]

Minimize criterion using algorithm subject to constraints and bounds.

Each argument except for general_options can also be replaced by a list of arguments in which case several optimizations are run in parallel. For this, either all arguments must be lists of the same length, or some arguments can be provided as single arguments in which case they are automatically broadcasted.

Parameters
  • criterion (callable or list of callables) –

    Python callable that takes a pandas DataFrame with parameters as the first argument. Supported outputs are:

    • scalar floating point

    • np.ndarray: contributions for the tao Pounders algorithm.

    • tuple of a scalar floating point and a pd.DataFrame:

      In this case the first output is the criterion value. The second output are the comparison_plot_data.

  • params (pd.DataFrame or list of pd.DataFrames) – See The params Argument.

  • algorithm (str or list of strings) – Specifies the optimization algorithm. See The algorithm Argument.

  • criterion_kwargs (dict or list of dicts) – Additional keyword arguments for criterion.

  • constraints (list or list of lists) – List with constraint dictionaries. See The constraints Argument.

  • general_options (dict) –

    Additional configurations for the optimization. Keys can include:

    • keep_dashboard_alive (bool): Do not terminate the dashboard process

      after the optimization(s) finish(es).

  • algo_options (dict or list of dicts) – Algorithm specific configurations for the optimization.

  • gradient_options (dict) – Options for the gradient function.

  • logging (str or pathlib.Path or list) – Path(s) to (an) sqlite3 file(s) which typically has the file extension .db. If the file does not exist, it will be created. See The logging and log_options Arguments for details.

  • log_options (dict or list of dict) – Keyword arguments to influence the logging. See The logging and log_options Arguments for details.

  • dashboard (bool) – Whether to create and show a dashboard, default is False. See The dashboard and dash_options Arguments for details.

  • dash_options (dict or list of dict, optional) –

    Options passed to the dashboard. Supported keys are:

    • port (int): port where to display the dashboard.

    • no_browser (bool): whether to display the dashboard in a browser.

    • rollover (int): how many iterations to keep in the convergence plots.

Returns

Each tuple consists of the harmonized result info dictionary and the params DataFrame with the minimizing parameter values of the untransformed problem as specified of the user.

Return type

results (tuple or list of tuples)

estimagic.optimization.optimize.maximize(criterion, params, algorithm, criterion_kwargs=None, constraints=None, general_options=None, algo_options=None, gradient_options=None, logging='logging.db', log_options=None, dashboard=False, dash_options=None)[source]

Maximize criterion using algorithm subject to constraints and bounds.

Each argument except for general_options can also be replaced by a list of arguments in which case several optimizations are run in parallel. For this, either all arguments must be lists of the same length, or some arguments can be provided as single arguments in which case they are automatically broadcasted.

Parameters
  • criterion (callable or list of callables) –

    Python callable that takes a pandas DataFrame with parameters as the first argument. Supported outputs are:

    • scalar floating point

    • np.ndarray: contributions for the tao Pounders algorithm.

    • tuple of a scalar floating point and a pd.DataFrame:

      In this case the first output is the criterion value. The second output are the comparison_plot_data.

  • params (pd.DataFrame or list of pd.DataFrames) – See The params Argument.

  • algorithm (str or list of strings) – Specifies the optimization algorithm. See The algorithm Argument.

  • criterion_kwargs (dict or list of dicts) – Additional keyword arguments for criterion.

  • constraints (list or list of lists) – List with constraint dictionaries. See The constraints Argument.

  • general_options (dict) –

    Additional configurations for the optimization. Keys can include:

    • keep_dashboard_alive (bool): Do not terminate the dashboard process

      after the optimization(s) finish(es).

  • algo_options (dict or list of dicts) – Algorithm specific configurations for the optimization.

  • gradient_options (dict) – Options for the gradient function.

  • logging (str or pathlib.Path or list) – Path(s) to (an) sqlite3 file(s) which typically has the file extension .db. If the file does not exist, it will be created. See The logging and log_options Arguments for details.

  • log_options (dict or list of dict) – Keyword arguments to influence the logging. See The logging and log_options Arguments for details.

  • dashboard (bool) – Whether to create and show a dashboard, default is False. See The dashboard and dash_options Arguments for details.

  • dash_options (dict or list of dict, optional) –

    Options passed to the dashboard. Supported keys are:

    • port (int): port where to display the dashboard.

    • no_browser (bool): whether to display the dashboard in a browser.

    • rollover (int): how many iterations to keep in the convergence plots.

Returns

Each tuple consists of the harmonized result info dictionary and the params DataFrame with the minimizing parameter values of the untransformed problem as specified of the user.

Return type

results (tuple or list of tuples)

The most noteworthy point is that only the algo_options depend on the optimizer used. All the rest, including all types of constraints work with all optimizers! The next pages will describe the more complex arguments of maximize and minimize in more detail.