bluemira.base.parameter_frame._frame

Classes

`ParameterFrame`	A data class to hold a collection of Parameter objects.
`EmptyFrame`	Class to represent an empty ParameterFrame (one with no Parameters).

Functions

`_validate_parameter_field`(→ tuple[type, Ellipsis])
`_validate_units`(param_data, value_type)
`_remake_units`(→ pint.Unit)	Reconstruct unit from its dimensionality.
`_fix_combined_units`(→ pint.Unit)	Converts base unit to a composite unit if they exist in the defaults.
`_convert_angle_units`(→ pint.Unit)	Converts angle units to the base unit default for angles.
`_fix_weird_units`(→ pint.Unit)	Essentially a crude unit parser for when we have no dimensions
`_non_comutative_unit_conversion`(dimensionality, ...)	Full power years (dimension [time]) and displacements per atom (dimensionless)
`make_parameter_frame`(...)	Factory function to generate a ParameterFrame of a specific type.
`tabulate_values_from_multiple_frames`(→ str)	Tabulate the contents of parameter frames of the same type.

Module Contents

class bluemira.base.parameter_frame._frame.ParameterFrame

A data class to hold a collection of Parameter objects.

The class should be declared using the following form:

@dataclass
class AnotherFrame(ParameterFrame):
    param_1: Parameter[float]
    param_2: Parameter[int]

__post_init__()

Get types from frame

Raises:: TypeError – Inconsistent Parameter name or wrong type

classmethod _get_types() → dict[str, types.GenericAlias]

Gets types for the frame even with annotations imported.

Returns:: The field name to type mapping of the frame
Return type:: dict[str, types.GenericAlias]

__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
Return type:: collections.abc.Iterator[bluemira.base.parameter_frame._parameter.Parameter]

update(new_values: dict[str, bluemira.base.parameter_frame._parameter.ParameterValueType] | bluemira.base.parameter_frame._parameter.ParamDictT | ParameterFrame)

Update the given frame

Parameters:: new_values (dict[str, bluemira.base.parameter_frame._parameter.ParameterValueType] | bluemira.base.parameter_frame._parameter.ParamDictT | ParameterFrame)

get_values(*names: str) → tuple[bluemira.base.parameter_frame._parameter.ParameterValueType, Ellipsis]

Get values of a set of Parameters.

Parameters:: names (str) – 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
Return type:: tuple[bluemira.base.parameter_frame._parameter.ParameterValueType, Ellipsis]

update_values(new_values: dict[str, bluemira.base.parameter_frame._parameter.ParameterValueType], source: str = '')

Update the given parameter values.

Parameters:

new_values (dict[str, bluemira.base.parameter_frame._parameter.ParameterValueType])
source (str)

update_from_dict(new_values: dict[str, bluemira.base.parameter_frame._parameter.ParamDictT], source: str = '')

Update from a dictionary representation of a ParameterFrame

Parameters:

new_values (dict[str, bluemira.base.parameter_frame._parameter.ParamDictT])
source (str)

update_from_frame(frame: bluemira.base.parameter_frame.typed.ParameterFrameT)

Update the frame with the values of another frame

Parameters:: frame (bluemira.base.parameter_frame.typed.ParameterFrameT)

_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

Parameters:

name (str)
o_param (bluemira.base.parameter_frame._parameter.Parameter)

classmethod from_dict(data: dict[str, bluemira.base.parameter_frame._parameter.ParamDictT], *, allow_unknown: bool = False) → bluemira.base.parameter_frame.typed.ParameterFrameT

Initialise an instance from a dictionary.

Returns:

A new ParameterFrame instance

Raises:

ValueError – Parameter data not found or unknown parameter

Parameters:

data (dict[str, bluemira.base.parameter_frame._parameter.ParamDictT])
allow_unknown (bool)

Return type:

bluemira.base.parameter_frame.typed.ParameterFrameT

classmethod from_frame(frame: bluemira.base.parameter_frame.typed.ParameterFrameT) → bluemira.base.parameter_frame.typed.ParameterFrameT

Initialise an instance from another ParameterFrame.

Returns:: A new ParameterFrame instance
Raises:: ValueError – Cannot find Parameter in provided frame
Parameters:: frame (bluemira.base.parameter_frame.typed.ParameterFrameT)
Return type:: bluemira.base.parameter_frame.typed.ParameterFrameT

classmethod from_json(json_in: str | json.SupportsRead, *, allow_unknown: bool = False) → bluemira.base.parameter_frame.typed.ParameterFrameT

Initialise an instance from a JSON file, string, or reader.

Returns:

A new ParameterFrame instance

Raises:

TypeError – Cannot read json data

Parameters:

json_in (str | json.SupportsRead)
allow_unknown (bool)

Return type:

bluemira.base.parameter_frame.typed.ParameterFrameT

classmethod from_config_params(config_params: bluemira.base.reactor_config.ConfigParams) → bluemira.base.parameter_frame.typed.ParameterFrameT

Initialise an instance from a 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
Parameters:: config_params (bluemira.base.reactor_config.ConfigParams)
Return type:: bluemira.base.parameter_frame.typed.ParameterFrameT

classmethod _member_data_to_parameter(member: str, member_param_data: bluemira.base.parameter_frame._parameter.ParamDictT) → bluemira.base.parameter_frame._parameter.Parameter

Convert a member’s data to a Parameter object.

Returns:

The Parameter object

Raises:

ValueError – Unit conversion failed

Parameters:

member (str)
member_param_data (bluemira.base.parameter_frame._parameter.ParamDictT)

Return type:

bluemira.base.parameter_frame._parameter.Parameter

to_dict(*, use_last: bool = False) → dict[str, dict[str, Any]]

Serialise this ParameterFrame to a dictionary.

Returns:: The serialised data
Parameters:: use_last (bool)
Return type:: dict[str, dict[str, Any]]

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

Parameters:

keys (list[str] | None) – table column keys
floatfmt (str) – Format floats to this precision
value_label (str | None) – The header title for the ‘value’ column

Returns:

The tabulated data as column headers and a list of rows

Return type:

tuple[list[str], list[list[str]]]

tabulate(keys: list[str] | None = None, tablefmt: str = 'fancy_grid', floatfmt: str = '.5g', value_label: str | None = 'value') → str

Tabulate the ParameterFrame

Parameters:

keys (list[str] | None) – table column keys
tablefmt (str) – The format of the table (default=”fancy_grid”) - see https://github.com/astanin/python-tabulate#table-format
floatfmt (str) – Format floats to this precision
value_label (str | None) – The header title for the ‘value’ column

Returns:

The tabulated data

Return type:

str

__str__() → str

Pretty print ParameterFrame.

Returns:: The formatted ParameterFrame
Return type:: str

bluemira.base.parameter_frame._frame._validate_parameter_field(field, member_type: type) → tuple[type, Ellipsis]

Parameters:: member_type (type)
Return type:: tuple[type, Ellipsis]

bluemira.base.parameter_frame._frame._validate_units(param_data: bluemira.base.parameter_frame._parameter.ParamDictT, value_type: collections.abc.Iterable[type])

Parameters:

param_data (bluemira.base.parameter_frame._parameter.ParamDictT)
value_type (collections.abc.Iterable[type])

bluemira.base.parameter_frame._frame._remake_units(dimensionality: dict | pint.util.UnitsContainer) → pint.Unit

Reconstruct unit from its dimensionality.

Parameters:: dimensionality (dict | pint.util.UnitsContainer) – The dimensionality of the unit
Returns:: The reconstructed unit
Return type:: pint.Unit

bluemira.base.parameter_frame._frame._fix_combined_units(unit: pint.Unit) → pint.Unit

Converts base unit to a composite unit if they exist in the defaults.

Parameters:: unit (pint.Unit) – The unit to convert
Returns:: The converted unit
Return type:: pint.Unit

bluemira.base.parameter_frame._frame._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.

Parameters:

modified_unit (pint.Unit) – reconstructed unit without the angle
orig_unit_str (str) – the user supplied unit (without spaces)
angle_unit (str) – the angle unit in orig_unit

Returns:

The converted unit

Return type:

pint.Unit

bluemira.base.parameter_frame._frame._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

Parameters:

modified_unit (pint.Unit)
orig_unit (pint.Unit)

Return type:

pint.Unit

bluemira.base.parameter_frame._frame._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

class bluemira.base.parameter_frame._frame.EmptyFrame

Bases: ParameterFrame

Class to represent an empty ParameterFrame (one with no Parameters).

Can be used when initialising a ConfigParams object with no global params.

bluemira.base.parameter_frame._frame.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.

Parameters:

params (bluemira.base.parameter_frame.typed.ParameterFrameLike) –
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.
- 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 Builders and Designers.
param_cls (type[bluemira.base.parameter_frame.typed.ParameterFrameT] | None) – The ParameterFrame class to create a new instance of.
allow_unknown (bool) – 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
TypeError – Cannot interpret params type

Return type:

bluemira.base.parameter_frame.typed.ParameterFrameT | None

bluemira.base.parameter_frame._frame.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.

Parameters:

frames (collections.abc.Iterable[bluemira.base.parameter_frame.typed.ParameterFrameT]) – ParameterFrames to compare
value_labels (collections.abc.Iterable[str]) – The header title for each ‘value’ column
tablefmt (str) – The format of the table (default=”fancy_grid”) - see https://github.com/astanin/python-tabulate#table-format
floatfmt (str) – Format floats to this precision

Returns:

The tabulated data

Raises:

TypeError – The ParameterFrames must all be the same type

Return type:

str

Notes

This function creates a table with a single “Parameter” column and multiple value columns