bluemira.base.parameter_frame._frame ==================================== .. py:module:: bluemira.base.parameter_frame._frame Classes ------- .. autoapisummary:: bluemira.base.parameter_frame._frame.ParameterFrame bluemira.base.parameter_frame._frame.EmptyFrame Functions --------- .. autoapisummary:: bluemira.base.parameter_frame._frame._validate_parameter_field bluemira.base.parameter_frame._frame.make_parameter_frame bluemira.base.parameter_frame._frame.tabulate_values_from_multiple_frames Module Contents --------------- .. py:class:: ParameterFrame A data class to hold a collection of `Parameter` objects. The class should be declared using the following form: .. code-block:: python @dataclass class AnotherFrame(ParameterFrame): param_1: Parameter[float] param_2: Parameter[int] .. py:method:: __post_init__() Get types from frame :raises TypeError: Inconsistent Parameter name or wrong type .. py:method:: _get_types() -> dict[str, types.GenericAlias] :classmethod: Gets types for the frame even with annotations imported. :returns: The field name to type mapping of the frame .. py:method:: __iter__() -> collections.abc.Iterator[bluemira.base.parameter_frame._parameter.Parameter] Iterate over this frame's parameters. The order is based on the order in which the parameters were declared. :Yields: Each parameter in the frame .. py:method:: update(new_values: dict[str, bluemira.base.parameter_frame._parameter.ParameterValueType] | bluemira.base.parameter_frame._parameter.ParamDictT | ParameterFrame) Update the given frame .. py:method:: get_values(*names: str) -> tuple[bluemira.base.parameter_frame._parameter.ParameterValueType, Ellipsis] Get values of a set of Parameters. :param names: The names of the Parameters to get the values of. :returns: The values of the Parameters in the order they were requested. :raises AttributeError: Unknown Parameter name .. py:method:: update_values(new_values: dict[str, bluemira.base.parameter_frame._parameter.ParameterValueType], source: str = '') Update the given parameter values. .. py:method:: update_from_dict(new_values: dict[str, bluemira.base.parameter_frame._parameter.ParamDictT], source: str = '') Update from a dictionary representation of a ``ParameterFrame`` .. py:method:: update_from_frame(frame: bluemira.base.parameter_frame.typed.ParameterFrameT) Update the frame with the values of another frame .. py:method:: _set_param(name: str, o_param: bluemira.base.parameter_frame._parameter.Parameter) Sets the information from a Parameter to an existing Parameter in this frame. :raises ValueError: if the units are mismatched .. py:method:: from_dict(data: dict[str, bluemira.base.parameter_frame._parameter.ParamDictT], *, allow_unknown: bool = False) -> bluemira.base.parameter_frame.typed.ParameterFrameT :classmethod: Initialise an instance from a dictionary. :returns: A new ParameterFrame instance :raises ValueError: Parameter data not found or unknown parameter .. py:method:: from_frame(frame: bluemira.base.parameter_frame.typed.ParameterFrameT) -> bluemira.base.parameter_frame.typed.ParameterFrameT :classmethod: Initialise an instance from another ParameterFrame. :returns: A new ParameterFrame instance :raises ValueError: Cannot find Parameter in provided frame .. py:method:: from_json(json_in: str | json.SupportsRead, *, allow_unknown: bool = False) -> bluemira.base.parameter_frame.typed.ParameterFrameT :classmethod: Initialise an instance from a JSON file, string, or reader. :returns: A new ParameterFrame instance :raises TypeError: Cannot read json data .. py:method:: from_config_params(config_params: bluemira.base.reactor_config.ConfigParams) -> bluemira.base.parameter_frame.typed.ParameterFrameT :classmethod: Initialise an instance from a :class:`~bluemira.base.reactor_config.ConfigParams` object. A ConfigParams objects holds a ParameterFrame of global_params and a dict of local_params. This function merges the two together to form a unified ParameterFrame. Parameters in global_params will overwrite those in local_params, when defined in both. All references to Parameters in global_params are maintained (i.e. there's no copying). :returns: A new ParameterFrame instance :raises ValueError: Parameter data not found .. py:method:: _member_data_to_parameter(member: str, member_param_data: bluemira.base.parameter_frame._parameter.ParamDictT) -> bluemira.base.parameter_frame._parameter.Parameter :classmethod: Convert a member's data to a Parameter object. :returns: The Parameter object :raises ValueError: Unit conversion failed .. py:method:: to_dict(*, use_last: bool = False) -> dict[str, dict[str, Any]] Serialise this ParameterFrame to a dictionary. :returns: The serialised data .. py:method:: tabulation_data(keys: list[str] | None = None, floatfmt: str = '.5g', value_label: str | None = 'value') -> tuple[list[str], list[list[str]]] Create the tabulated data for use with tabulate. Useful for combining frames for comparison :param keys: table column keys :param floatfmt: Format floats to this precision :param value_label: The header title for the 'value' column :returns: The tabulated data as column headers and a list of rows .. py:method:: tabulate(keys: list[str] | None = None, tablefmt: str = 'fancy_grid', floatfmt: str = '.5g', value_label: str | None = 'value') -> str Tabulate the ParameterFrame :param keys: table column keys :param tablefmt: The format of the table (default="fancy_grid") - see https://github.com/astanin/python-tabulate#table-format :param floatfmt: Format floats to this precision :param value_label: The header title for the 'value' column :returns: The tabulated data .. py:method:: __str__() -> str Pretty print ParameterFrame. :returns: The formatted ParameterFrame .. py:function:: _validate_parameter_field(field, member_type: type) -> tuple[type, Ellipsis] .. py:class:: EmptyFrame Bases: :py:obj:`ParameterFrame` .. autoapi-inheritance-diagram:: bluemira.base.parameter_frame._frame.EmptyFrame :parts: 1 :private-bases: Class to represent an empty `ParameterFrame` (one with no Parameters). Can be used when initialising a :class:`~bluemira.base.reactor_config.ConfigParams` object with no global params. .. py:function:: make_parameter_frame(params: bluemira.base.parameter_frame.typed.ParameterFrameLike, param_cls: type[bluemira.base.parameter_frame.typed.ParameterFrameT] | None, *, allow_unknown: bool = False) -> bluemira.base.parameter_frame.typed.ParameterFrameT | None Factory function to generate a `ParameterFrame` of a specific type. :param params: The parameters to initialise the class with. This parameter can be several types: * dict[str, ParamDictT]: A dict where the keys are parameter names, and the values are the data associated with the corresponding name. * ParameterFrame: A reference to the parameters on this frame will be assigned to the new ParameterFrame's parameters. Note that this makes no copies, so updates to parameters in the new frame will propagate to the old, and vice versa. * :class:`~bluemira.base.reactor_config.ConfigParams`: An object that holds a `global_params` ParameterFrame and a `local_params` dict, which are merged to create a new ParameterFrame. Values defined in `local_params` will be overwritten by those in `global_params` when defined in both. * str: The path to a JSON file, or, if the string starts with '{', a JSON string. * None: For the case where no parameters are actually required. This is intended for internal use, to aid in validation of parameters in `Builder`\s and `Designer`\s. :param param_cls: The `ParameterFrame` class to create a new instance of. :param allow_unknown: Dictionary and json input checks if unknown parameters are passed in. By default this will error unless this flag is set to true :returns: * A frame of the type `param_cls`, or `None` if `params` and * `param_cls` are both `None`. :raises ValueError: No params or param_cls provided :raises TypeError: Cannot interpret params type .. py:function:: tabulate_values_from_multiple_frames(frames: collections.abc.Iterable[bluemira.base.parameter_frame.typed.ParameterFrameT], value_labels: collections.abc.Iterable[str], tablefmt: str = 'fancy_grid', floatfmt: str = '.5g') -> str Tabulate the contents of parameter frames of the same type. :param frames: ParameterFrames to compare :param value_labels: The header title for each 'value' column :param tablefmt: The format of the table (default="fancy_grid") - see https://github.com/astanin/python-tabulate#table-format :param floatfmt: Format floats to this precision :returns: The tabulated data :raises TypeError: The ParameterFrames must all be the same type .. rubric:: Notes This function creates a table with a single "Parameter" column and multiple value columns