Optimization functions

estimagic.optimization.optimize.maximize(criterion, params, algorithm, *, criterion_kwargs=None, constraints=None, algo_options=None, derivative=None, derivative_kwargs=None, criterion_and_derivative=None, criterion_and_derivative_kwargs=None, numdiff_options=None, logging='logging.db', log_options=None, error_handling='raise', error_penalty=None, batch_evaluator='joblib', batch_evaluator_options=None, cache_size=100)

Maximize criterion using algorithm subject to constraints.

Each argument except for batch_evaluator and batch_evaluator_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) –

  A function that takes a pandas DataFrame (see How to specify start parameters) as first argument and returns one of the following:

  • scalar floating point or a numpy.ndarray (depending on the algorithm)

  • a dictionary that contains at the entries “value” (a scalar float), “contributions” or “root_contributions” (depending on the algortihm) and any number of additional entries. The additional dict entries will be logged and (if supported) displayed in the dashboard. Check the documentation of your algorithm to see which entries or output type are required.

• params (pandas.DataFrame) – A DataFrame with a column called “value” and optional additional columns. See How to specify start parameters for detail.

• algorithm (str or callable) – Specifies the optimization algorithm. For supported algorithms this is a string with the name of the algorithm. Otherwise it can be a callable with the estimagic algorithm interface. See How to specify algorithms and algorithm specific options.

• criterion_kwargs (dict) – Additional keyword arguments for criterion

• constraints (list) – List with constraint dictionaries. See .. _link: ../../docs/source/how_to_guides/how_to_use_constraints.ipynb

• algo_options (dict) – Algorithm specific configuration of the optimization. See Supported Algorithms for supported options of each algorithm.

• derivative (callable, optional) – Function that calculates the first derivative of criterion. For most algorithm, this is the gradient of the scalar output (or “value” entry of the dict). However some algorithms (e.g. bhhh) require the jacobian of the “contributions” entry of the dict. You will get an error if you provide the wrong type of derivative.

• derivative_kwargs (dict) – Additional keyword arguments for derivative.

• criterion_and_derivative (callable) – Function that returns criterion and derivative as a tuple. This can be used to exploit synergies in the evaluation of both functions. The fist element of the tuple has to be exactly the same as the output of criterion. The second has to be exactly the same as the output of derivative.

• criterion_and_derivative_kwargs (dict) – Additional keyword arguments for criterion and derivative.

• numdiff_options (dict) – Keyword arguments for the calculation of numerical derivatives. See Numerical first derivatives for details. Note that the default method is changed to “forward” for speed reasons.

• logging (pathlib.Path, str or False) – Path to sqlite3 file (which typically has the file extension .db. If the file does not exist, it will be created. When doing parallel optimizations and logging is provided, you have to provide a different path for each optimization you are running. You can disable logging completely by setting it to False, but we highly recommend not to do so. The dashboard can only be used when logging is used.

• log_options (dict) –

  Additional keyword arguments to configure the logging. - “suffix”: A string that is appended to the default table names, separated by an underscore. You can use this if you want to write the log into an existing database where the default names “optimization_iterations”, “optimization_status” and “optimization_problem” are already in use. - “fast_logging”: A boolean that determines if “unsafe” settings are used to speed up write processes to the database. This should only be used for very short running criterion functions where the main purpose of the log is a real-time dashboard and it would not be catastrophic to get a corrupted database in case of a sudden system shutdown. If one evaluation of the criterion function (and gradient if applicable) takes more than 100 ms, the logging overhead is negligible. - “if_exists”: (str) One of “extend”, “replace”, “raise” - “save_all_arguments”: (bool). If True, all arguments to maximize

  that can be pickled are saved in the log file. Otherwise, only the information needed by the dashboard is saved. Default False.

• error_handling (str) – Either “raise” or “continue”. Note that “continue” does not absolutely guarantee that no error is raised but we try to handle as many errors as possible in that case without aborting the optimization.

• error_penalty (dict) – Dict with the entries “constant” (float) and “slope” (float). If the criterion or gradient raise an error and error_handling is “continue”, return constant + slope * norm(params - start_params) where norm is the euclidean distance as criterion value and adjust the derivative accordingly. This is meant to guide the optimizer back into a valid region of parameter space (in direction of the start parameters). Note that the constant has to be high enough to ensure that the penalty is actually a bad function value. The default constant is f0 + abs(f0) + 100 for minimizations and f0 - abs(f0) - 100 for maximizations, where f0 is the criterion value at start parameters. The default slope is 0.1.

• batch_evaluator (str or Callable) – Name of a pre-implemented batch evaluator (currently ‘joblib’ and ‘pathos_mp’) or Callable with the same interface as the estimagic batch_evaluators. See Batch evaluators.

• batch_evaluator_options (dict) – Additional configurations for the batch batch evaluator. See Batch evaluators.

• cache_size (int) – Number of criterion and derivative evaluations that are cached in memory in case they are needed.

estimagic.optimization.optimize.minimize(criterion, params, algorithm, *, criterion_kwargs=None, constraints=None, algo_options=None, derivative=None, derivative_kwargs=None, criterion_and_derivative=None, criterion_and_derivative_kwargs=None, numdiff_options=None, logging='logging.db', log_options=None, error_handling='raise', error_penalty=None, batch_evaluator='joblib', batch_evaluator_options=None, cache_size=100)

Minimize criterion using algorithm subject to constraints.

Each argument except for batch_evaluator and batch_evaluator_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) – A function that takes a pandas DataFrame (see How to specify start parameters) as first argument and returns one of the following: - scalar floating point or a numpy array (depending on the algorithm) - a dictionary that contains at the entries “value” (a scalar float), “contributions” or “root_contributions” (depending on the algortihm) and any number of additional entries. The additional dict entries will be logged and (if supported) displayed in the dashboard. Check the documentation of your algorithm to see which entries or output type are required.

• params (pandas.DataFrame) – A DataFrame with a column called “value” and optional additional columns. See How to specify start parameters for detail.

• algorithm (str or callable) – Specifies the optimization algorithm. For supported algorithms this is a string with the name of the algorithm. Otherwise it can be a callable with the estimagic algorithm interface. See How to specify algorithms and algorithm specific options.

• criterion_kwargs (dict) – Additional keyword arguments for criterion

• constraints (list) – List with constraint dictionaries. See .. _link: ../../docs/source/how_to_guides/how_to_use_constranits.ipynb

• algo_options (dict) – Algorithm specific configuration of the optimization. See Supported Algorithms for supported options of each algorithm.

• derivative (callable, optional) – Function that calculates the first derivative of criterion. For most algorithm, this is the gradient of the scalar output (or “value” entry of the dict). However some algorithms (e.g. bhhh) require the jacobian of the “contributions” entry of the dict. You will get an error if you provide the wrong type of derivative.

• derivative_kwargs (dict) – Additional keyword arguments for derivative.

• criterion_and_derivative (callable) – Function that returns criterion and derivative as a tuple. This can be used to exploit synergies in the evaluation of both functions. The fist element of the tuple has to be exactly the same as the output of criterion. The second has to be exactly the same as the output of derivative.

• criterion_and_derivative_kwargs (dict) – Additional keyword arguments for criterion and derivative.

• numdiff_options (dict) – Keyword arguments for the calculation of numerical derivatives. See Numerical first derivatives for details. Note that the default method is changed to “forward” for speed reasons.

• logging (pathlib.Path, str or False) – Path to sqlite3 file (which typically has the file extension .db. If the file does not exist, it will be created. When doing parallel optimizations and logging is provided, you have to provide a different path for each optimization you are running. You can disable logging completely by setting it to False, but we highly recommend not to do so. The dashboard can only be used when logging is used.

• log_options (dict) –

  Additional keyword arguments to configure the logging. - “suffix”: A string that is appended to the default table names, separated by an underscore. You can use this if you want to write the log into an existing database where the default names “optimization_iterations”, “optimization_status” and “optimization_problem” are already in use. - “fast_logging”: A boolean that determines if “unsafe” settings are used to speed up write processes to the database. This should only be used for very short running criterion functions where the main purpose of the log is a real-time dashboard and it would not be catastrophic to get a corrupted database in case of a sudden system shutdown. If one evaluation of the criterion function (and gradient if applicable) takes more than 100 ms, the logging overhead is negligible. - “if_exists”: (str) One of “extend”, “replace”, “raise” - “save_all_arguments”: (bool). If True, all arguments to minimize

  that can be pickled are saved in the log file. Otherwise, only the information needed by the dashboard is saved. Default False.

• error_handling (str) – Either “raise” or “continue”. Note that “continue” does not absolutely guarantee that no error is raised but we try to handle as many errors as possible in that case without aborting the optimization.

• error_penalty (dict) – Dict with the entries “constant” (float) and “slope” (float). If the criterion or gradient raise an error and error_handling is “continue”, return constant + slope * norm(params - start_params) where norm is the euclidean distance as criterion value and adjust the derivative accordingly. This is meant to guide the optimizer back into a valid region of parameter space (in direction of the start parameters). Note that the constant has to be high enough to ensure that the penalty is actually a bad function value. The default constant is f0 + abs(f0) + 100 for minimizations and f0 - abs(f0) - 100 for maximizations, where f0 is the criterion value at start parameters. The default slope is 0.1.

• batch_evaluator (str or Callable) – Name of a pre-implemented batch evaluator (currently ‘joblib’ and ‘pathos_mp’) or Callable with the same interface as the estimagic batch_evaluators. See Batch evaluators.

• batch_evaluator_options (dict) – Additional configurations for the batch batch evaluator. See Batch evaluators.

• cache_size (int) – Number of criterion and derivative evaluations that are cached in memory in case they are needed.

Optimization Tools Processing constraints