bluemira.codes.interface

Base classes for solvers using external codes.

Classes

`BaseRunMode`	Base enum class for defining run modes within a solver.
`CodesTask`	Base class for a task used by a solver for an external code.
`NoOpTask`	A task that does nothing.
`CodesSetup`	Base class for setup tasks of a solver for an external code.
`CodesTeardown`	Base class for teardown tasks of a solver for an external code.
`CodesSolver`	Base class for solvers running an external code.

Module Contents

class bluemira.codes.interface.BaseRunMode(*args, **kwds)

Bases: enum.Enum

Base enum class for defining run modes within a solver.

Note that no two enumeration’s names should be case-insensitively equal.

to_string() → str

Convert the enum name to a string; its name in lower-case.

Return type:: str

classmethod from_string(mode_str: str)

Retrieve an enum value from a case-insensitive string.

Parameters:: mode_str (str) – The run mode’s name.
Raises:: ValueError – Unknown run mode

class bluemira.codes.interface.CodesTask(params: bluemira.codes.params.MappedParameterFrame, codes_name: str)

Bases: abc.ABC

Base class for a task used by a solver for an external code.

Parameters:

params (bluemira.codes.params.MappedParameterFrame)
codes_name (str)

params

_name

abstract run(): Run the task.

_run_subprocess(command: list[str], **kwargs)

Run a subprocess command and raise a CodesError if it returns a non-zero exit code.

Raises:: CodesError – Non zero exit code
Parameters:: command (list[str])

class bluemira.codes.interface.NoOpTask(params: bluemira.codes.params.MappedParameterFrame, codes_name: str)

Bases: CodesTask

A task that does nothing.

This can be assigned to a solver to skip any of the setup, run, or teardown stages.

Parameters:

params (bluemira.codes.params.MappedParameterFrame)
codes_name (str)

static run() → None

Do nothing.

Return type:: None

class bluemira.codes.interface.CodesSetup(params: bluemira.codes.params.MappedParameterFrame, codes_name: str)

Bases: CodesTask

Base class for setup tasks of a solver for an external code.

Parameters:

params (bluemira.codes.params.MappedParameterFrame)
codes_name (str)

_get_new_inputs(remapper: collections.abc.Callable | dict[str, str] | None = None) → dict[str, float]

Retrieve inputs values to the external code from this task’s ParameterFrame.

Convert the inputs’ units to those used by the external code.

Parameters:

remapper (collections.abc.Callable | dict[str, str] | None) – A function or dictionary for remapping variable names. Useful for renaming old variables

Returns:

Keys are external code parameter names, values are the input
values for those parameters.

Raises:

TypeError – remapper must be callable or a dictionary

Return type:

dict[str, float]

static _convert_units(param, target_unit: str | None)

Parameters:: target_unit (str | None)

class bluemira.codes.interface.CodesTeardown(params: bluemira.codes.params.MappedParameterFrame, codes_name: str)

Bases: CodesTask

Base class for teardown tasks of a solver for an external code.

Parameters:

params (bluemira.codes.params.MappedParameterFrame) – The parameters for this task.
codes_name (str) – The name of the external code the task is associated with.

_update_params_with_outputs(outputs: dict[str, float], *, recv_all: bool = False)

Update this task’s parameters with the external code’s outputs.

This implicitly performs any unit conversions.

Parameters:

outputs (dict[str, float]) – Key are the external code’s parameter names, the values are the values for those parameters.
recv_all (bool) – Whether to ignore the ‘recv’ attribute on the parameter mapping, and update all output parameter values.

Raises:

CodesError: – If any output does not have a mapping to a bluemira parameter, or the output maps to a bluemira parameter that does not exist in this object’s ParameterFrame.

_map_external_outputs_to_bluemira_params(external_outputs: dict[str, Any], *, recv_all: bool) → dict[str, dict[str, Any]]

Loop through external outputs, find the corresponding bluemira parameter name, and map it to the output’s value and unit.

Parameters:

external_outputs (dict[str, Any]) – An output produced by an external code. The keys are the outputs’ names (not the bluemira version of the name), the values are the output’s value (in the external code’s unit).
recv_all (bool) – Whether to ignore the ‘recv’ attribute on the parameter mapping, and update all output parameter values.

Returns:

The keys are bluemira parameter names and the values are the
external codes’ outputs for those parameters (with necessary
unit conversions made).

Return type:

dict[str, dict[str, Any]]

_get_output_or_raise(external_outputs: dict[str, Any], parameter_name: str)

Parameters:

external_outputs (dict[str, Any])
parameter_name (str)

class bluemira.codes.interface.CodesSolver(params: bluemira.codes.params.MappedParameterFrame)

Bases: abc.ABC

Base class for solvers running an external code.

Parameters:: params (bluemira.codes.params.MappedParameterFrame)

params: bluemira.codes.params.MappedParameterFrame

_setup

_run

_teardown

abstract property name

The name of the solver.

In the base class, this is used to find mappings and specialise error messages for the concrete solver.

property setup_cls: type[CodesTask]

Abstractmethod:
Return type:: type[CodesTask]

Class defining the run modes for the setup stage of the solver.

Typically, this class performs parameter mappings for some external code, or derives dependent parameters. But it can also define any required non-computational set up.

property run_cls: type[CodesTask]

Abstractmethod:
Return type:: type[CodesTask]

Class defining the run modes for the computational stage of the solver.

This class is where computations should be defined. This may be something like calling a bluemira problem, or executing some external code or process.

property teardown_cls: type[CodesTask]

Abstractmethod:
Return type:: type[CodesTask]

Class defining the run modes for the teardown stage of the solver.

This class should perform any clean-up operations required by the solver. This may be deleting temporary files, or could involve mapping parameters from some external code to bluemira parameters.

property run_mode_cls: type[BaseRunMode]

Abstractmethod:
Return type:: type[BaseRunMode]

Class enumerating the run modes for this solver.

Common run modes are RUN, MOCK, READ, etc,.

execute(run_mode: str | BaseRunMode) → Any

Execute the setup, run, and teardown tasks, in order.

Parameters:: run_mode (str | BaseRunMode)
Return type:: Any

modify_mappings(send_recv: dict[str, dict[str, bool]])

Modify the send/receive truth values of a parameter.

If a parameter’s ‘send’ is set to False, its value will not be passed to the external code (a default will be used). Likewise, if a parameter’s ‘recv’ is False, its value will not be updated from the external code’s outputs.

Parameters:

send_recv (dict[str, dict[str, bool]]) –

A dictionary where keys are variables to change the mappings of, and values specify ‘send’, and or, ‘recv’ booleans.

E.g.,

{
    "var1": {"send": False, "recv": True},
    "var2": {"recv": False}
}

static _get_execution_method(task: CodesTask, run_mode: BaseRunMode) → collections.abc.Callable | None

Returns:

The method on the task corresponding to this solver’s run mode (e.g., task.run).

If the method on the task does not exist, return None.

Parameters:

task (CodesTask)
run_mode (BaseRunMode)

Return type:

collections.abc.Callable | None