Reference

Optimization workchain

workchainaiida_optimize.OptimizationWorkChain

Runs an optimization procedure, given an optimization engine that defines the optimization algorithm, and a process which evaluates the function to be optimized.

Inputs:

  • engine, Str, required – Engine that runs the optimization.
  • engine_kwargs, Dict, required – Keyword arguments passed to the optimization engine.
  • evaluate, Namespace – Inputs that are passed to all evaluation processes.
  • evaluate_process, Str, required – Process which produces the result to be optimized.
  • metadata, Namespace
    Namespace Ports
    • call_link_label, str, optional, non_db – The label to use for the CALL link if the process is called by another process.
    • description, str, optional, non_db – Description to set on the process node.
    • label, str, optional, non_db – Label to set on the process node.
    • store_provenance, bool, optional, non_db – If set to False provenance will not be stored in the database.

Outputs:

  • optimal_process_input, None, optional – Input value of the optimal evaluation process.
  • optimal_process_output, None, required – Output value of the optimal evaluation process.
  • optimal_process_uuid, None, required – UUID of the optimal evaluation process.

Outline:

create_optimizer
while(not_finished)
    launch_evaluations(Create evaluations for the current iteration step.)
    get_results(Retrieve results of the current iteration step's evaluations.)
finalize(Return the output after the optimization procedure has finished.)

Engines

This module defines optimization routines to be used with the main optimization WorkChain.

class aiida_optimize.engines.Bisection(lower: float, upper: float, *, tol: float = 1e-06, input_key: str = 'x', result_key: str = 'result', target_value: float = 0.0, logger: Optional[Any] = None)[source]

Optimization engine that performs a bisection.

Parameters
  • lower (float) – Lower boundary for the bisection.

  • upper (float) – Upper boundary for the bisection.

  • tol (float) – Tolerance in the input value.

  • input_key (str) – Name of the input to be varied in the optimization.

  • result_key (str) – Name of the output which contains the evaluated function.

  • target_value (float) – Target value of the function towards which it should be optimized.

class aiida_optimize.engines.Convergence(input_values: List[Any], tol: float, input_key: str, result_key: str, convergence_window: int = 2, array_name: Optional[str] = None, logger: Optional[Any] = None)[source]

Wrapper class for convergence engine

Parameters
  • input_values (iterable object) – List or other iterable of inputs within the desired range to check convergence

  • tol (float) – Roughness tolerance for checking convergence

  • input_key (str) – Name of the input key which should be varied to find convergence

  • result_key (str) – Name of the output / result key which is the value to converge

  • convergence_window (int) – Number of results to consider when checking convergence

  • array_name (str or None) – Name of array within output / result ArrayData (only necessary if the output is given in an ArrayData)

class aiida_optimize.engines.NelderMead(simplex, fun_simplex=None, xtol=0.0001, ftol=0.0001, max_iter=1000, input_key='x', result_key='result', logger=None)[source]

Engine to perform the Nelder-Mead (downhill simplex) method.

Parameters
  • simplex (array) – The current / initial simplex. Must be of shape (N + 1, N), where N is the dimension of the problem.

  • fun_simplex (array) – Function values at the simplex positions.

  • xtol (float) – Tolerance for the input x.

  • ftol (float) – Tolerance for the function value.

  • max_iter (int) – Maximum number of iteration steps.

  • input_key (str) – Name of the input argument in the evaluation process.

  • result_key (str) – Name of the output argument in the evaluation process.

class aiida_optimize.engines.ParameterSweep(parameters, result_key='result', logger=None)[source]

Optimization engine that performs a parameter sweep.

Parameters
  • parameters (list(dict)) – List of parameter dictionaries. For each entry, an evaluation with the given parameters will be run.

  • result_key (str) – Name of the evaluation process output argument.

Engine base classes

Defines the base classes needed to implement an optimization engine.

class aiida_optimize.engines.base.OptimizationEngineImpl(logger: Any, result_state: Optional[Dict[int, aiida_optimize.engines._result_mapping.Result]] = None)[source]

Base class for the stateful optimization engine implementation.

abstract _create_inputs()[source]

Creates the inputs for evaluations that need to be launched. This function needs to be implemented by child classes.

abstract _get_optimal_result() → Tuple[int, Any, Any][source]

Return the index, input value, and output value of the best evaluation process.

abstract property _state

The serialized state of the instance, without the result mapping. This function needs to be implemented by child classes.

abstract _update(outputs: Dict[int, Any])None[source]

Updates the engine instance with the evaluation outputs. This method needs to be implemented by child classes.

create_inputs()[source]

Creates the inputs and adds them to the result mapping.

classmethod from_state(state: Dict[str, Any])aiida_optimize.engines.base.OptimizationEngineImpl[source]

Create an instance of the class from the serialized state.

abstract property is_finished

Returns true if the optimization is finished.

property is_finished_ok

Returns true if the optimization is finished without error.

property result_index

Returns the index (in the result mapping) of the optimal evaluation.

property result_input_value

Return the input value of the optimal evaluation.

property result_output_value

Return the output value of the optimal evaluation.

property state

The serialized state of the instance, including the result mapping.

update(outputs)None[source]

Updates the result mapping and engine instance with the evaluation outputs.

class aiida_optimize.engines.base.OptimizationEngineWrapper(*args, **kwargs)[source]

Base class for wrappers that supply the public interface for optimization engines.

Wrapper workchains

workchainaiida_optimize.wrappers.AddInputsWorkChain

Wrapper workchain that takes inputs as keys and values and passes it on to a sub-process. This enables taking a process which was not designed to be used in optimization, and optimize with respect to some arbitrary input. Inputs which always remain the same can be specified in the ``inputs`` namespace, whereas the inputs to be optimized are given through the ``added_input_keys`` and ``added_input_values`` inputs. The outputs of the wrapper workchain are the same as those of the wrapped process. The “added” inputs can only be BaseType sub-classes, or attributes of a Dict. For each input, its port location is given in the “added_input_keys” input. For example, ``x.y`` would set the ``y`` input in the ``x`` namespace. For cases where the input is a Dict attribute, the (possibly nested) attribute name is given after a colon. That means ``x:a.b`` would set the ``[‘a’][‘b’]`` attribute of the ``Dict`` given in the ``x`` input. In cases where only a single input needs to be added, they can be specified directly instead of wrapped in a List.

Inputs:

  • added_input_keys, (List, Str), required – Specifies the location of each added input.
  • added_input_values, (List, BaseType), required – Values of the added inputs to be passed into the sub-process.
  • inputs, Namespace – Inputs to be passed on to the sub-process.
  • metadata, Namespace
    Namespace Ports
    • call_link_label, str, optional, non_db – The label to use for the CALL link if the process is called by another process.
    • description, str, optional, non_db – Description to set on the process node.
    • label, str, optional, non_db – Label to set on the process node.
    • store_provenance, bool, optional, non_db – If set to False provenance will not be stored in the database.
  • sub_process, Str, required – The class of the process that should be wrapped.

Outputs:

None defined.

Outline:

run_process(Merge the inputs namespace and added inputs, and launch the sub-process.)
finalize(Retrieve outputs of the sub-process.)

workchainaiida_optimize.wrappers.CreateEvaluateWorkChain

Wrapper workchain to combine two processes: The first process _creates_ a result, and the second _evaluates_ that result. The purpose of this workchain is to facilitate optimization of processes which don’t natively produce an output that can be optimized, by only having to add the ‘evaluation’ part.

Inputs:

  • create, Namespace – Inputs which are passed on to the create sub-process.
  • create_process, Str, required – The sub-process which performs the create step.
  • evaluate, Namespace – Inputs which are passed on to the evaluate sub-process.
  • evaluate_process, Str, required – The sub-process which performs the evaluate step.
  • metadata, Namespace
    Namespace Ports
    • call_link_label, str, optional, non_db – The label to use for the CALL link if the process is called by another process.
    • description, str, optional, non_db – Description to set on the process node.
    • label, str, optional, non_db – Label to set on the process node.
    • store_provenance, bool, optional, non_db – If set to False provenance will not be stored in the database.
  • output_input_mapping, Dict, required – A mapping from output names of the create process to input names of the evaluate process. These outputs (if present) are forwarded to the evaluate process.

Outputs:

  • create, Namespace
  • evaluate, Namespace

Outline:

run_create(Launch the first, "create" sub-process.)
run_evaluate(Retrieve outputs of the "create" sub-process, and launch the "evaluate" sub-process.)
finalize(Retrieve outputs of the "evaluate" sub-process.)

Helper functions

Defines helper functions for using aiida-optimize.

aiida_optimize.helpers.get_nested_result(output: Dict[str, aiida.orm.nodes.node.Node], key: str) → aiida.orm.nodes.node.Node[source]

Helper function to retrieve nested outputs from AiiDA processes.

This function supports the nested key syntax:

  • Namespaces are separated by a period

  • A colon : indicates accessing inside an AiiDA Dict

  • Nested access inside the Dict is again separated by a period

Examples:

  • 'x.y': retrieve output y in the x namespace

  • 'x.y:a.b': x.y is a Dict, and we retrieve its content at ['a']['b'].

Parameters
  • output – The outputs of a process, given as a dictionary mapping output labels to values.

  • key – The key for which the output should be retrieved.

Returns

The desired result, as an AiiDA node.

Return type

orm.Node

Internals

This section describes internal modules. Their interface may change without warning.

Result mapping

Defines the datastructures used by optimization engines to keep track of results.

class aiida_optimize.engines._result_mapping.Result(input_: Any, output: Optional[Any] = None)[source]

Data object for storing the input created by the optimization engine, and the output from the evaluation process corresponding to that input.

class aiida_optimize.engines._result_mapping.ResultMapping[source]

Maps the keys used to identify evaluations to their inputs / outputs.

add_inputs(inputs_list: List[Any]) → Dict[int, aiida_optimize.engines._result_mapping.Result][source]

Adds a list of inputs to the mapping, generating new keys. Returns a dict mapping the keys to the inputs.

classmethod from_state(state: Optional[Dict[int, aiida_optimize.engines._result_mapping.Result]])aiida_optimize.engines._result_mapping.ResultMapping[source]

Create a ResultMapping instance from a state.

property state

Uniquely defines the state of the object. This can be used to create an identical copy.

Internal utilities

Defines common helper functions.