armi.reactor.parameters.parameterDefinitions module

This module contains the code necessary to represent parameter definitions.

ParameterDefinitions are the metadata that describe specific parameters, and aid in enforcing certain rules upon the parameters themselves and the parameter collections that contain them.

This module also describes the ParameterDefinitionCollection class, which serves as a specialized container to manage related parameter definitions.

See also

armi.reactor.parameters

class armi.reactor.parameters.parameterDefinitions.Category

Bases: object

A “namespace” for storing parameter categories.

assignInBlueprints = 'assign in blueprints'

retainOnReplacement = 'retain on replacement'

volumeIntegrated = 'volumeIntegrated'

fluxQuantities = 'fluxQuantities'

multiGroupQuantities = 'multi-group quantities'

detailedAxialExpansion = 'detailedAxialExpansion'

neutronics = 'neutronics'

class armi.reactor.parameters.parameterDefinitions.ParamLocation

Bases: enum.Flag

Represents point which a parameter is physically meaningful.

TOP = 1

CENTROID = 2

BOTTOM = 4

AVERAGE = 10

MAX = 16

CORNERS = 32

EDGES = 64

VOLUME_INTEGRATED = 128

CHILDREN = 256

class armi.reactor.parameters.parameterDefinitions.NoDefault

Bases: object

Class used to allow distinction between not setting a default and setting a default of None

class armi.reactor.parameters.parameterDefinitions._Undefined

Bases: object

Class used to identify a parameter property as being in the undefined state

class armi.reactor.parameters.parameterDefinitions.Serializer

Bases: object

Abstract class describing serialize/deserialize operations for Parameter data.

Parameters need to be stored to and read from database files. This currently requires that the Parameter data be converted to a numpy array of a datatype supported by the h5py package. Some parameters may contain data that are not trivially representable in numpy/HDF5, and need special treatment. Subclassing Serializer and setting it as a Parameters serializer allows for special operations to be performed on the parameter values as they are stored to the database or read back in.

The Database3 already knows how to handle certain cases where the data are not straightforward to get into a numpy array, such as when:

• There are Nones.

• The dimensions of the values stored on each object are inconsistent (e.g., “jagged” arrays)

So, in these cases, a Serializer is not needed. Serializers are necessary for when the actual data need to be converted to a native data type (e.g., int, float, etc.) For example, we use a Serializer to handle writing Flags to the Database, as they tend to be too big to fit into a system-native integer.

Important

Defining a Serializer for a Parameter in part defines the underlying representation of the data within a database file; the data stored in a database are sensitive to the code that wrote them. Changing the method that a Serializer uses to pack or unpack data may break compatibility with old databse files. Therefore, Serializers should be dilligent about signalling changes by updating their version. It is also good practice, whenever possible, to support reading old versions so that database files written by old versions can still be read.

See also

armi.bookkeeping.db.database3.packSpecialData, armi.bookkeeping.db.database3.unpackSpecialData, armi.reactor.flags.FlagSerializer

version = None

static pack(data: Sequence[any]) → Tuple[numpy.ndarray, Dict[str, any]]

Given unpacked data, return packed data and a dictionary of attributes needed to unpack it.

The should perform the fundamental packing operation, returning the packed data and any metadata (“attributes”) that would be necessary to unpack the data. The class’s version is always stored, so no need to provide it as an attribute.

See also

armi.reactor.flags.FlagSerializer.pack()

classmethod unpack(data: numpy.ndarray, version: Any, attrs: Dict[str, any]) → Sequence[any]

Given packed data and attributes, return the unpacked data.

class armi.reactor.parameters.parameterDefinitions.Parameter(name, units, description, location, saveToDB, default, setter, categories, serializer: Optional[Type[armi.reactor.parameters.parameterDefinitions.Serializer]] = None)

Bases: object

Metadata about a specific parameter

_validName = re.compile('^[a-zA-Z0-9_]+$')

collectionType

name

fieldName

location

saveToDB

serializer

description

units

default

categories

assigned

_backup

_getter

_setter

setter(setter)

Decorator method for assigning setter.

Notes

Unlike the traditional Python property class, this does not return a new instance of a Parameter; therefore it cannot be reassigned in the same way that a Python property can be.

Examples

>>> class MyParameterCollection(parameters.ParameterCollection):
...     mass = parameters.Parameter(...)
...     @mass.setter
...     def mass(self, value):
...         if value < 0:
...             raise ValueError("Negative mass is not possible, consider a diet.")
...         self._p_speed = value

backUp()

Back up the assigned state.

restoreBackup(paramsToApply)

Restore the backed up state.

atLocation(loc)

True if parameter is defined at location.

class armi.reactor.parameters.parameterDefinitions.ParameterDefinitionCollection

Bases: object

A very specialized container for managing parameter definitions.

Notes

_representedTypes is used to detect if this ParameterDefinitionCollection contains definitions for only one type. If the collection only exists for 1 type, the lookup (__getitem__) can short circuit O(n) logic for O(1) dictionary lookup.

_paramDefs

_paramDefDict

_representedTypes

_locked

add(paramDef)

add a Parameter to this collection.

_filter(filterFunc)

items()

extend(other)

Grow a parameter definition collection by another parameter definition collection

inCategory(categoryName)

Create a ParameterDefinitionCollection that contains definitions that are in a specific category.

atLocation(paramLoc)

Make a param definition collection with all defs defined at a specific location.

Parameters can be defined at various locations within their container based on ParamLocation. This allows selection by those values.

since(mask)

Create a ParameterDefinitionCollection that contains definitions that have been modified since a specific set of actions.

unchanged_since(mask)

Create a ParameterDefinitionCollection that contains definitions that have not been modified since a specific set of actions. This is the complementary set of the collection returned by since.

forType(compositeType)

Create a ParameterDefinitionCollection that contains definitions for a specific composite type.

resetAssignmentFlag(mask)

Clear the assigned flag for a certain operation on all parameters.

These flags will get set by the param definition setters if they get changed again.

Notes

See http://www.vipan.com/htdocs/bitwisehelp.html to understand the bitwise operations

setAssignmentFlag(mask)

byNameAndType(name, compositeType)

Get a Parameter by compositeType and name.

byNameAndCollectionType(name, collectionType)

Get a Parameter by compositeType and name.

property categories

Get the categories of all the Parameter instances within this collection

property names

lock()

property locked

toWriteToDB(assignedMask: Optional[int] = None)

Get a list of acceptable parameters to store to the database for a level of the data model.

Parameters

assignedMask (int) – a bitmask to down-filter which params to use based on how “stale” they are.

createBuilder(*args, **kwargs)

Create an associated object that can create definitions into this collection

Using the returned ParameterBuilder will add all defined parameters to this ParameterDefinitionCollection, using the passed arguments as defaults. Arguments should be valid arguments to ParameterBuilder.__init__()

class armi.reactor.parameters.parameterDefinitions.ParameterBuilder(location=<ParamLocation.AVERAGE: 10>, default=<class 'armi.reactor.parameters.parameterDefinitions.NoDefault'>, categories=None, saveToDB=True)

Bases: object

Factory for creating Parameter and parameter properties

Create a ParameterBuilder

static _assertDefaultIsProperType(default)

associateParameterDefinitionCollection(paramDefs)

Associate this parameter factory with a specific ParameterDefinitionCollection

Subsequent calls to defParam will automatically add the created ParameterDefinitions to this ParameterDefinitionCollection. This results in a cleaner syntax when defining many ParameterDefinitions.

defParam(name, units, description, location=None, saveToDB=<class 'armi.reactor.parameters.parameterDefinitions.NoDefault'>, default=<class 'armi.reactor.parameters.parameterDefinitions.NoDefault'>, setter=<class 'armi.reactor.parameters.parameterDefinitions.NoDefault'>, categories=None, serializer: Optional[Type[armi.reactor.parameters.parameterDefinitions.Serializer]] = None)

Create a parameter as a property (with get/set) on a class

Parameters

• name (str) – the official name of the parameter

• units (str) – string representation of the units

• description (str) – a brief, but precise-as-possible description of what the parameter is used for.

• location (str) – string representation of the location the attribute is applicable to, such as average, max, etc.

• saveToDB (bool) – indicator as to whether the parameter should be written to the database. The actual default is defined by the ParameterBuilder, and is True.

• default (immutable type) – a default value for this parameter which must be an immutable type. If the type is mutable, e.g. a list, dict, an exception should be raised, or unknown behavior.

• setter (None or callable) – If None, there is no direct way to set the parameter. If some other callable method, (which may have the same name as the property!) then the setter method is used instead.

• categories (List of str) – A list of categories to which this Parameter should belong. Categories are typically used to engage special treatment for certain Parameters.

• serializer (Optional subclass of Serializer) – A class describing how the parameter data should be stored to the database. This is usually only needed in exceptional cases where it is difficult to store a parameter in a numpy array.

Notes

It is not possible to initialize the parameter on the class this method would be used on, because there is no instance (i.e. self) when this method is run. However, this method could access a globally available set of definitions, if one existed.