bluemira.codes.interface ======================== .. py:module:: bluemira.codes.interface .. autoapi-nested-parse:: Base classes for solvers using external codes. Classes ------- .. autoapisummary:: bluemira.codes.interface.BaseRunMode bluemira.codes.interface.CodesTask bluemira.codes.interface.NoOpTask bluemira.codes.interface.CodesSetup bluemira.codes.interface.CodesTeardown bluemira.codes.interface.CodesSolver Module Contents --------------- .. py:class:: BaseRunMode(*args, **kwds) Bases: :py:obj:`enum.Enum` .. autoapi-inheritance-diagram:: bluemira.codes.interface.BaseRunMode :parts: 1 :private-bases: Base enum class for defining run modes within a solver. Note that no two enumeration's names should be case-insensitively equal. .. py:method:: to_string() -> str Convert the enum name to a string; its name in lower-case. .. py:method:: from_string(mode_str: str) :classmethod: Retrieve an enum value from a case-insensitive string. :param mode_str: The run mode's name. :raises ValueError: Unknown run mode .. py:class:: CodesTask(params: bluemira.codes.params.MappedParameterFrame, codes_name: str) Bases: :py:obj:`abc.ABC` .. autoapi-inheritance-diagram:: bluemira.codes.interface.CodesTask :parts: 1 :private-bases: Base class for a task used by a solver for an external code. .. py:attribute:: params .. py:attribute:: _name .. py:method:: run() :abstractmethod: Run the task. .. py:method:: _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 .. py:class:: NoOpTask(params: bluemira.codes.params.MappedParameterFrame, codes_name: str) Bases: :py:obj:`CodesTask` .. autoapi-inheritance-diagram:: bluemira.codes.interface.NoOpTask :parts: 1 :private-bases: A task that does nothing. This can be assigned to a solver to skip any of the setup, run, or teardown stages. .. py:method:: run() -> None :staticmethod: Do nothing. .. py:class:: CodesSetup(params: bluemira.codes.params.MappedParameterFrame, codes_name: str) Bases: :py:obj:`CodesTask` .. autoapi-inheritance-diagram:: bluemira.codes.interface.CodesSetup :parts: 1 :private-bases: Base class for setup tasks of a solver for an external code. .. py:method:: _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. :param remapper: 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 .. py:method:: _convert_units(param, target_unit: str | None) :staticmethod: .. py:class:: CodesTeardown(params: bluemira.codes.params.MappedParameterFrame, codes_name: str) Bases: :py:obj:`CodesTask` .. autoapi-inheritance-diagram:: bluemira.codes.interface.CodesTeardown :parts: 1 :private-bases: Base class for teardown tasks of a solver for an external code. :param params: The parameters for this task. :param codes_name: The name of the external code the task is associated with. .. py:method:: _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. :param outputs: Key are the external code's parameter names, the values are the values for those parameters. :param recv_all: 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. .. py:method:: _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. :param external_outputs: 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). :param recv_all: 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).* .. py:method:: _get_output_or_raise(external_outputs: dict[str, Any], parameter_name: str) .. py:class:: CodesSolver(params: bluemira.codes.params.MappedParameterFrame) Bases: :py:obj:`abc.ABC` .. autoapi-inheritance-diagram:: bluemira.codes.interface.CodesSolver :parts: 1 :private-bases: Base class for solvers running an external code. .. py:attribute:: params :type: bluemira.codes.params.MappedParameterFrame .. py:attribute:: _setup .. py:attribute:: _run .. py:attribute:: _teardown .. py:property:: name :abstractmethod: The name of the solver. In the base class, this is used to find mappings and specialise error messages for the concrete solver. .. py:property:: setup_cls :type: type[CodesTask] :abstractmethod: 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. .. py:property:: run_cls :type: type[CodesTask] :abstractmethod: 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. .. py:property:: teardown_cls :type: type[CodesTask] :abstractmethod: 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. .. py:property:: run_mode_cls :type: type[BaseRunMode] :abstractmethod: Class enumerating the run modes for this solver. Common run modes are RUN, MOCK, READ, etc,. .. py:method:: execute(run_mode: str | BaseRunMode) -> Any Execute the setup, run, and teardown tasks, in order. .. py:method:: 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. :param send_recv: A dictionary where keys are variables to change the mappings of, and values specify 'send', and or, 'recv' booleans. E.g., .. code-block:: python { "var1": {"send": False, "recv": True}, "var2": {"recv": False} } .. py:method:: _get_execution_method(task: CodesTask, run_mode: BaseRunMode) -> collections.abc.Callable | None :staticmethod: :returns: The method on the task corresponding to this solver's run mode (e.g., :code:`task.run`). If the method on the task does not exist, return :code:`None`.