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._validate_units bluemira.base.parameter_frame._frame._remake_units bluemira.base.parameter_frame._frame._fix_combined_units bluemira.base.parameter_frame._frame._convert_angle_units bluemira.base.parameter_frame._frame._fix_weird_units bluemira.base.parameter_frame._frame._non_comutative_unit_conversion 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:function:: _validate_units(param_data: bluemira.base.parameter_frame._parameter.ParamDictT, value_type: collections.abc.Iterable[type]) .. py:function:: _remake_units(dimensionality: dict | pint.util.UnitsContainer) -> pint.Unit Reconstruct unit from its dimensionality. :param dimensionality: The dimensionality of the unit :returns: The reconstructed unit .. py:function:: _fix_combined_units(unit: pint.Unit) -> pint.Unit Converts base unit to a composite unit if they exist in the defaults. :param unit: The unit to convert :returns: The converted unit .. py:function:: _convert_angle_units(modified_unit: pint.Unit, orig_unit_str: str, angle_unit: str) -> pint.Unit Converts angle units to the base unit default for angles. Angles are dimensionless therefore dimensionality conversion from pint doesn't work. Conversions between angle units is also not very robust. :param modified_unit: reconstructed unit without the angle :param orig_unit_str: the user supplied unit (without spaces) :param angle_unit: the angle unit in `orig_unit` :returns: The converted unit .. py:function:: _fix_weird_units(modified_unit: pint.Unit, orig_unit: pint.Unit) -> pint.Unit Essentially a crude unit parser for when we have no dimensions or non-commutative dimensions. Full power years (dimension [time]) and displacements per atom (dimensionless) need to be readded to units as they will be removed by the dimensionality conversion. Angle units are dimensionless and conversions between them are not robust :returns: The fixed unit :raises ValueError: Multiple angle units provided .. py:function:: _non_comutative_unit_conversion(dimensionality, numerator, dpa, fpy) Full power years (dimension [time]) and displacements per atom (dimensionless) need to be readded to units as they will be removed by the dimensionality conversion. Full power years even though time based is not the same as straight 'time' and is therefore dealt with after other standard unit conversions. Only first order of both of these units is dealt with. :returns: The converted unit .. 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