Models (`moirae.models`)#

Models for the physics, state of health, and transient states of energy storage systems

Base Classes (`moirae.models.base`)#

Base classes which define the state of a storage system, the control signals applied to it, the outputs observable from it, and the mathematical models which links state, control, and outputs together.

class moirae.models.base.CellModel#

Bases: object

Base model for an energy storage system.

Cell models describe how to update the transient state of a system and compute expected outputs given the inputs and current A-SOH.

abstract calculate_terminal_voltage(new_inputs: InputQuantities, transient_state: GeneralContainer, asoh: HealthVariable) → OutputQuantities#

Compute expected output (terminal voltage, etc.) of the cell.

Parameters:

new_inputs – Inputs at the current time step
transient_state – Current transient state
asoh – Health parameters of the cell

Returns:

Estimates for all measurable outputs of a cell

abstract update_transient_state(previous_inputs: InputQuantities, new_inputs: InputQuantities, transient_state: GeneralContainer, asoh: HealthVariable) → GeneralContainer#

Update the transient state of a chemical cell

Parameters:

previous_inputs – Inputs at the last time step
new_inputs – Inputs at the current time step
transient_state – Current transient state
asoh – Health parameters of the cell

Returns:

A new transient state

class moirae.models.base.DegradationModel#

Bases: object

Base class for A-SOH aging models.

Degradation models update the A-SOH incrementally given the current transient state, similar to how the CellModel updates the transient state given current A-SOH.

abstract update_asoh(previous_asoh: HealthVariable, new_inputs: InputQuantities, new_transients: GeneralContainer | None, new_measurements: OutputQuantities | None) → HealthVariable#

Degrade previous A-SOH based on inputs.

Parameters:

previous_asoh – previous A-SOH to be updated
new_inputs – new inputs since the previous A-SOH
new_transients – new transient states since the previous A-SOH
new_measurements – new outputs since the previous A-SOH

Returns:

A new A-SOH object representing the degraded state

pydantic model moirae.models.base.GeneralContainer#

Bases: BaseModel

General container class to store numeric variables.

Like the HealthVariable all values are stored as 2d numpy arrays where the first dimension is a batch dimension. Accordingly, denote the types of attributes using the ScalarParameter or ListParameter for scalar and 1-dimensional data, respectively.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

arbitrary_types_allowed: bool = True

expand_names(names: Iterable[str]) → tuple[str, ...]#: Expand a single name per field to a distinct name for each value within the field

from_numpy(values: ndarray) → None#: Updates field values from a numpy array

length_field(field_name: str) → int#: Returns length of provided field name. If the field is a float, returns 1, otherwise, returns length of array. If field is None, returns 0.

make_copy(values: ndarray) → Self#

Helper method that returns a copy of the current object with values specified by numpy.ndarray

Parameters:: values – numpy array containing values to be used in copy

to_numpy() → ndarray#: Outputs everything that is stored as a two-dimensional np.ndarray

property all_fields: tuple[str, ...]#

Names of all fields of the model in the order they appear in to_numpy()

Returns a single name per field, regardless of whether the field is a scalar or vector. See all_names() to get a single name per value.

property all_names: tuple[str, ...]#: Names of each value within the vector

property batch_size: int#: Batch size determined from the batch dimension of all attributes

pydantic model moirae.models.base.HealthVariable#

Bases: BaseModel

Base class for a container which holds the physical parameters of system and which ones are being treated as updatable.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

arbitrary_types_allowed: bool = True

Fields:

updatable (set[str])

Validators:

check_batch_size » all fields

field updatable: set[str] [Optional]#

Which fields are to be treated as updatable by a parameter estimator

Validated by:

check_batch_size

validator check_batch_size » all fields#

expand_names(names: Iterable[str]) → Tuple[str, ...]#

Expand names which define a collection of values to one for each number.

Each member of a list of values become are annotated with [i] notation.

class ListHealth(HealthVariable):
    x: ListParameter = 1.

a = ListHealth()
a.expand_names(['x'])  # == ['x[0]']

Names of values that are themselves HealthVariable are expanded to include all values

class Health(HealthVariable):
    a: ListHealth

h = Health(a=a)
h.expand_names(["a"])  # == ['a.x[0]']
h.expand_names(["a.x"])  # == ['a.x[0]']

Parameters:: names – List of names to be expanded
Returns:: Expanded names

get_parameters(names: Sequence[str] | None = None) → ndarray#

Get updatable parameters as a numpy vector

Parameters:: names – Names of the parameters to gather. If None, then will return all updatable parameters
Returns:: A numpy array of the values

iter_parameters(updatable_only: bool = True, recurse: bool = True) → Iterator[tuple[str, ndarray]]#

Iterate over all parameters which are treated as updatable

Parameters:

updatable_only – Only iterate over variables which are updatable
recurse – Whether to gather parameters from attributes which are also HealthVariable classes.

Yields:

Tuple of names and parameter values as numpy arrays. The name of parameters from attributes which are HealthVariable will start will be “<name of attribute in this class>.<name of attribute in submodel>”

make_copy(values: ndarray, names: Sequence[str] | None = None) → Self#

Create a copy of the current object with values specified by numpy.ndarray

Parameters:

values – numpy array containing values to be used in copy
names – sequence of the names of attributes to be returned with the values passed. If None, changes all updatable parameters

mark_all_fixed(recurse: bool = True)#

Mark all fields in the model as not updatable

Parameters:: recurse – Whether to mark all variables of submodels as not updatable

mark_all_updatable(recurse: bool = True)#

Make all fields in the model updatable

Parameters:: recurse – Make all parameters of each submodel updatable too

mark_updatable(name: str)#

Mark a specific variable as updatable

Will mark any submodel along the path to the requested name as updatable.

Parameters:: name – Name of the variable to be set as updatable

set_value(name: str, value: float | ndarray)#

Set the value of a certain variable by name

Parameters:

name – Name of the parameter to set.
value – Updated value

update_parameters(values: ndarray | list[float], names: Sequence[str] | None = None)#

Set the value for updatable parameters given their names

Parameters:

values – Values of the parameters to set
names – Names of the parameters to set. If None, then will set all updatable parameters

property all_names: Tuple[str, ...]#: Names of all updatable parameters

property batch_size: int#: Batch size of this parameter

property num_updatable#: Number of updatable parameters in this HealthVariable

property updatable_names: Tuple[str, ...]#: Names of all updatable parameters

pydantic model moirae.models.base.InputQuantities#

Bases: GeneralContainer

The control of a battery system, such as the terminal current

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

arbitrary_types_allowed: bool = True

Fields:

current (numpy.ndarray)
time (numpy.ndarray)

field current: _encode_ndarray, return_type=PydanticUndefined, when_used=json-unless-none)] = 0.0#

Current applied to the storage system. Units: A

Constraints:

func = <function _encode_ndarray at 0x7f9155b8b250>
json_schema_input_type = PydanticUndefined
return_type = PydanticUndefined
when_used = json-unless-none

field time: _encode_ndarray, return_type=PydanticUndefined, when_used=json-unless-none)] = 0.0#

Timestamp(s) of inputs. Units: s

Constraints:

func = <function _encode_ndarray at 0x7f9155b8b250>
json_schema_input_type = PydanticUndefined
return_type = PydanticUndefined
when_used = json-unless-none

moirae.models.base.ListParameter#

Type annotation for parameters which can be any number of values

alias of Annotated[ndarray, BeforeValidator(func=~moirae.models.base., json_schema_input_type=PydanticUndefined), FieldInfo(annotation=NoneType, required=True, validate_default=True), WrapSerializer(func=_encode_ndarray, return_type=PydanticUndefined, when_used=json-unless-none)]

pydantic model moirae.models.base.OutputQuantities#

Bases: GeneralContainer

Output for observables from a battery system

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

arbitrary_types_allowed: bool = True

Fields:

terminal_voltage (numpy.ndarray)

field terminal_voltage: _encode_ndarray, return_type=PydanticUndefined, when_used=json-unless-none)] [Required]#

Voltage output of a battery cell/model. Units: V

Constraints:

func = <function _encode_ndarray at 0x7f9155b8b250>
json_schema_input_type = PydanticUndefined
return_type = PydanticUndefined
when_used = json-unless-none

moirae.models.base.ScalarParameter#

Type annotation for parameters which are exactly one value

moirae.models.base.enforce_dimensions(x: Any, dim=1) → ndarray#

Make sure an array is the desired shape for batching

Arrays must be 2D or greater and the first dimension is always the batch dimension. That means arrays which represent “scalar values” (dim == 0), have shape (batches, 1).

Parameters:

x – Value to be altered
dim – Dimensionality of numbers being represented

Returns:

Array ready for use in a HealthVariable, etc

Cell Models#

Each cell model is in its own submodule to limit dependency conflicts.

Models (moirae.models)#

Base Classes (moirae.models.base)#

Cell Models#

Models (`moirae.models`)#

Base Classes (`moirae.models.base`)#