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, NoneType), optional, non_db – Description to set on the process node.
- label, (str, NoneType), 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:

engine_outputs, Namespace
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: Any | None = 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: str | None = None, logger: Any | None = 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.

class aiida_optimize.engines.ParticleSwarm(particles, max_iter=20, input_key='x', result_key='result', logger=None)[source]

Engine to perform the Particle-Swarm optimization (http://dx.doi.org/10.1109/CEC.2003.1299391).

Parameters:

particles (array) – The current / initial set of particles. Must be a list of shape (M, N), where N is the dimension of the problem and M is free to choose, it will be the number of particles!
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.

Engine base classes

Defines the base classes needed to implement an optimization engine.

class aiida_optimize.engines.base.OptimizationEngineImpl(logger: Any, result_state: Dict[int, Result] | None = 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: Dict[str, Any]: 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]) → OptimizationEngineImpl[source]: Create an instance of the class from the serialized state.

abstract property is_finished: bool: Returns true if the optimization is finished.

property is_finished_ok: bool: Returns true if the optimization is finished without error.

property result_index: int: Returns the index (in the result mapping) of the optimal evaluation.

property result_input_value: Any: Return the input value of the optimal evaluation.

property result_output_value: Any: Return the output value of the optimal evaluation.

property state: Dict[str, Any]: 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.OptimizationEngineImplWithOutputs[source]

Base class for the optimization engine implementation emitting custom outputs.

abstract get_engine_outputs() → Dict[str, Any][source]

Return the custom outputs created by the engine, at the end of the run.

The result must be compatible with WorkChain.out, i.e. its keys are labels, and the values are either AiiDA nodes, or nested dictionaries.

All AiiDA nodes returned must already be stored.

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, NoneType), optional, non_db – Description to set on the process node.
- label, (str, NoneType), 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, NoneType), optional, non_db – Description to set on the process node.
- label, (str, NoneType), 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.)

workchainaiida_optimize.wrappers.ConcatenateWorkChain

Allows concatenating an arbitrary number of sub-processes. A wrapper workchain that allows concatenating an arbitrary number of sub-processes. Outputs of one processes can be configured to be passed to the next one.

Inputs:

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, NoneType), optional, non_db – Description to set on the process node.
- label, (str, NoneType), 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_mappings, List, required – Defines how inputs are passed between sub-processes. Each list entry entry has the form ((process_label_a, process_label_b), mapping), and defines outputs of process A to be passed to process B. The mapping values are dictionaries {‘output_name’: ‘input_name’} giving the output name (in process A) and input name (in process B) for each value to pass.
process_inputs, Namespace – Inputs which are passed on to the sub-processes. The inputs should be grouped into a namespace identified by the process label.
process_labels, List, required – A list of pairs (label, process_name). The labels can be any string, the process_name needs to be loadable by aiida_optimize.process_inputs.load_object, and defines which process is being run.

Outputs:

process_outputs, Namespace

Outline:

_initialize
while(_not_finished)
    _run_sub_process
    _retrieve_sub_process

Helper functions

Defines helper functions for using aiida-optimize.

aiida_optimize.helpers.get_nested_result(output: Dict[str, Node], key: str) → 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: Any | None = 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, 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: Dict[int, Result] | None) → ResultMapping[source]: Create a ResultMapping instance from a state.

property state: Dict[int, Result]: Uniquely defines the state of the object. This can be used to create an identical copy.

Internal utilities

Defines common helper functions.