Online Estimators (m.estimators.online)

Estimators which incrementally adjust estimates for system state.

class moirae.estimators.online.OnlineEstimator(cell_model: CellModel, initial_asoh: HealthVariable, initial_transients: GeneralContainer, initial_inputs: InputQuantities, updatable_asoh: bool | Collection[str] = True)

Bases: object

The interface for all online estimation frameworks

Parameters:

• cell_model – Cell model used to describe the underlying physics of the storage system

• initial_asoh – Initial estimates for the health parameters of the battery, those being estimated or not

• initial_transients – Initial estimates for the transient states of the battery

• initial_inputs – Initial inputs to the system

• updatable_asoh – Whether to estimate values for all updatable parameters (True), none of the updatable parameters (False), or a list of specific parameters.

property control_names: Tuple[str, ...]

Names for each of the control variables

abstract get_estimated_state() → Tuple[GeneralContainer, HealthVariable]

Compute current estimate for the transient states and ASOH

Returns:

• Estimate for the transient state

• Estimator for the ASOH

property num_output_dimensions: int

Expected dimensionality of output measurements

property num_state_dimensions: int

Dimensionality of the state

property output_names: Tuple[str, ...]

Names of each output variable

property state: MultivariateRandomDistribution

Multivariate probability distribution for all state variables

property state_names: Tuple[str, ...]

Names of each state variable

abstract step(inputs: InputQuantities, measurements: OutputQuantities) → Tuple[MultivariateRandomDistribution, MultivariateRandomDistribution]

Function to step the estimator, provided new control variables and output measurements.

Parameters:

• inputs – control variables

• measurements – output measurements

Returns:

• Updated estimate of the hidden state, which includes only the variables defined in state_names

• Estimate of the measurements as predicted by the underlying model

Available frameworks for online estimation include

class moirae.estimators.online.joint.JointEstimator(joint_filter: BaseFilter)

Bases: OnlineEstimator

Estimate the transient vector and A-SOH values are estimated jointly, in a single array, using a single filter.

Create a joint estimator by supplying a single filter.

Parameters:

joint_filter – A filter configured to operate using a CellModel.

get_estimated_state() → Tuple[GeneralContainer, HealthVariable]

Compute current estimate for the transient states and ASOH

Returns:

• Estimate for the transient state

• Estimator for the ASOH

classmethod initialize_ukf_from_wrapper(joint_wrapper: JointCellModelWrapper, covariance_joint: ndarray | None = None, covariance_transient: ndarray | None = None, covariance_asoh: ndarray | None = None, inputs_uncertainty: ndarray | None = None, joint_covariance_process_noise: ndarray | None = None, transient_covariance_process_noise: ndarray | None = None, asoh_covariance_process_noise: ndarray | None = None, covariance_sensor_noise: ndarray | None = None, filter_args: UKFTuningParameters = {'alpha_param': 1.0, 'beta_param': 2.0, 'kappa_param': 0.0}) → Self

Function to help initialize joint estimation based on UKF from the joint (transient + A-SOH) wrapper, which may have been prepared with its own custom moirae.estimators.online.filters.conversions.ConversionOperator

Parameters:

• joint_wrapper – wrapper for the joint state

• covariance_joint – specifies the raw (un-normalized) covariance of the joint state; it is the preferred method of assembling the initial joint state

• covariance_transient – specifies the raw (un-normalized) covariance of the transient state; it is not used if covariance_joint was provided

• covariance_asoh – specifies the raw (un-normalized) covariance of the A-SOH; it is not used if covariance_joint was provided

• inputs_uncertainty – uncertainty matrix of the inputs; if not provided, assumes inputs are exact

• joint_covariance_process_noise – process noise covariance for the joint state, considering transient and A-SOH noises

• transient_covariance_process_noise – process noise for transient update; only used if joint_covariance_process_noise was not provided

• asoh_covariance_process_noise – process noise for A-SOH update; only used if joint_covariance_process_noise was not provided

• covariance_sensor_noise – sensor noise for outputs; if denoising is applied, must match the proper dimensionality

• filter_args – additional dictionary of keywords to be given the the UKF; can include alpha_param, beta_param, and kappa_param

classmethod initialize_unscented_kalman_filter(cell_model: CellModel, initial_asoh: HealthVariable, initial_transients: GeneralContainer, initial_inputs: InputQuantities, covariance_joint: ndarray | None = None, covariance_transient: ndarray | None = None, covariance_asoh: ndarray | None = None, inputs_uncertainty: ndarray | None = None, joint_covariance_process_noise: ndarray | None = None, transient_covariance_process_noise: ndarray | None = None, asoh_covariance_process_noise: ndarray | None = None, covariance_sensor_noise: ndarray | None = None, normalize_asoh: bool = False, filter_args: UKFTuningParameters = {'alpha_param': 1.0, 'beta_param': 2.0, 'kappa_param': 0.0}) → Self

Function to help the user initialize a UKF-based joint estimation without needing to define the filter and model wrapper.

Parameters:

• cell_model – CellModel to be used

• degratation_model – DegradationModel to be used; if None is passed, assume A-SOH degration estimated solely from data

• initial_asoh – initial A-SOH

• initial_transients – initial transient vector

• initial_inputs – initial input quantities

• covariance_joint – specifies the raw (un-normalized) covariance of the joint state; it is the preferred method of assembling the initial joint state

• covariance_transient – specifies the raw (un-normalized) covariance of the transient state; it is not used if covariance_joint was provided

• covariance_asoh – specifies the raw (un-normalized) covariance of the A-SOH; it is not used if covariance_joint was provided

• inputs_uncertainty – uncertainty matrix of the inputs; if not provided, assumes inputs are exact

• joint_covariance_process_noise – process noise covariance for the joint state, considering transient and A-SOH noises

• transient_covariance_process_noise – process noise for transient update; only used if joint_covariance_process_noise was not provided

• asoh_covariance_process_noise – process noise for A-SOH update; only used if joint_covariance_process_noise was not provided

• covariance_sensor_noise – sensor noise for outputs; if denoising is applied, must match the proper dimensionality

• normalize_asoh – determines whether A-SOH parameters should be normalized in the filter

• filter_args – additional dictionary of keywords to be given the the UKF; can include alpha_param, beta_param, and kappa_param

property state: MultivariateRandomDistribution

Multivariate probability distribution for all state variables

step(inputs: InputQuantities, measurements: OutputQuantities) → Tuple[MultivariateRandomDistribution, MultivariateRandomDistribution]

Function to step the estimator, provided new control variables and output measurements.

Parameters:

• inputs – control variables

• measurements – output measurements

Returns:

• Updated estimate of the hidden state, which includes only the variables defined in state_names

• Estimate of the measurements as predicted by the underlying model

class moirae.estimators.online.dual.DualEstimator(transient_filter: BaseFilter, asoh_filter: BaseFilter)

Bases: OnlineEstimator

In dual estimation, the transient vector and A-SOH are estimated by separate filters. This framework generally avoids numerical errors related to the magnitude differences between values pertaining to transient quantities and to the A-SOH parameters. However, correlations between these two types of quantities are partially lost, and the framework is more involved.

Parameters:

• transient_filter – base filter to estimate transient vector

• asoh_filter – base filter to estimate A-SOH parameters

get_estimated_state() → Tuple[GeneralContainer, HealthVariable]

Compute current estimate for the transient states and ASOH

Returns:

• Estimate for the transient state

• Estimator for the ASOH

classmethod initialize_ukf_from_wrappers(transient_wrapper: CellModelWrapper, asoh_wrapper: DegradationModelWrapper, covariance_transient: ndarray, covariance_asoh: ndarray, inputs_uncertainty: ndarray | None = None, transient_covariance_process_noise: ndarray | None = None, asoh_covariance_process_noise: ndarray | None = None, covariance_sensor_noise: ndarray | None = None, filter_args: DualUKFTuningParameters | None = {'asoh': {'alpha_param': 1.0, 'beta_param': 2.0, 'kappa_param': 0.0}, 'transient': {'alpha_param': 1.0, 'beta_param': 2.0, 'kappa_param': 0.0}}) → Self

Function to help initialize dual estimation based on UKF from the individual transient and A-SOH wrappers, which may have been prepared with their own custom moirae.estimators.online.filters.conversions.ConversionOperator

Parameters:

• transient_wrapper – wrapper for the transient vector

• asoh_wrapper – wrapper for the A-SOH

• covariance_transient – specifies the raw (un-normalized) covariance of the transient state; it is not used if covariance_joint was provided

• covariance_asoh – specifies the raw (un-normalized) covariance of the A-SOH; it is not used if covariance_joint was provided

• inputs_uncertainty – uncertainty matrix of the inputs; if not provided, assumes inputs are exact

• transient_covariance_process_noise – process noise for transient update; only used if joint_covariance_process_noise was not provided

• asoh_covariance_process_noise – process noise for A-SOH update; only used if joint_covariance_process_noise was not provided

• covariance_sensor_noise – sensor noise for outputs; if denoising is applied, must match the proper dimensionality

• normalize_asoh – determines whether A-SOH parameters should be normalized in the filter

• filter_args – dictionary where keys must be either ‘transient’ or ‘asoh’, and values must be a dictionary in which keys are keyword arguments for the UKFs (such as alpha_param)

Returns:

instance of DualEstimator based on one UKF for the transient state, and one for the A-SOH

classmethod initialize_unscented_kalman_filter(cell_model: CellModel, initial_asoh: HealthVariable, initial_transients: GeneralContainer, initial_inputs: InputQuantities, covariance_transient: ndarray, covariance_asoh: ndarray, inputs_uncertainty: ndarray | None = None, transient_covariance_process_noise: ndarray | None = None, asoh_covariance_process_noise: ndarray | None = None, covariance_sensor_noise: ndarray | None = None, normalize_asoh: bool = False, filter_args: DualUKFTuningParameters | None = {'asoh': {'alpha_param': 1.0, 'beta_param': 2.0, 'kappa_param': 0.0}, 'transient': {'alpha_param': 1.0, 'beta_param': 2.0, 'kappa_param': 0.0}}) → Self

Function to help the user initialize a UKF-based dual estimation without needing to define each filter and model wrapper individually.

Parameters:

• cell_model – CellModel to be used

• degratation_model – DegradationModel to be used; if None is passed, assume A-SOH degration estimated solely from data

• initial_asoh – initial A-SOH

• initial_transients – initial transient vector

• initial_inputs – initial input quantities

• covariance_transient – specifies the raw (un-normalized) covariance of the transient state; it is not used if covariance_joint was provided

• covariance_asoh – specifies the raw (un-normalized) covariance of the A-SOH; it is not used if covariance_joint was provided

• inputs_uncertainty – uncertainty matrix of the inputs; if not provided, assumes inputs are exact

• transient_covariance_process_noise – process noise for transient update; only used if joint_covariance_process_noise was not provided

• asoh_covariance_process_noise – process noise for A-SOH update; only used if joint_covariance_process_noise was not provided

• covariance_sensor_noise – sensor noise for outputs; if denoising is applied, must match the proper dimensionality

• normalize_asoh – determines whether A-SOH parameters should be normalized in the filter

• filter_args – dictionary where keys must be either ‘transient’ or ‘asoh’, and values must be a dictionary in which keys are keyword arguments for the UKFs (such as alpha_param)

property state: MultivariateRandomDistribution

Multivariate probability distribution for all state variables

step(inputs: InputQuantities, measurements: OutputQuantities) → Tuple[MultivariateRandomDistribution, MultivariateRandomDistribution]

Function to step the estimator, provided new control variables and output measurements.

Parameters:

• inputs – control variables

• measurements – output measurements

Returns:

• Updated estimate of the hidden state, which includes only the variables defined in state_names

• Estimate of the measurements as predicted by the underlying model

Filters (m.e.online.filters)

Collection of filters, which define the core logic for online parameter estimation algorithm

class moirae.estimators.online.filters.base.BaseFilter(model: ModelWrapper, initial_hidden: MultivariateRandomDistribution, initial_controls: MultivariateRandomDistribution)

Bases: object

Parameters:

• model – model that describes how to updated_hidden_state as a function of control calculate_output as a function of hidden state and control

• initial_hidden – initial hidden state of the system

• initial_controls – initial control state of the system

abstract step(new_controls: MultivariateRandomDistribution, measurements: MultivariateRandomDistribution) → Tuple[MultivariateRandomDistribution, MultivariateRandomDistribution]

Function to step the filter.

Parameters:

• new_controls – new control state

• measurements – measurement obtained

Returns:

estimate of the hidden state output_prediction: predicted output, which is what the filter predicted the ‘measurements’ argument to be

Return type:

hidden_estimate

class moirae.estimators.online.filters.base.ModelWrapper(hidden_conversion_operator: ConversionOperator = IdentityConversionOperator(), control_conversion_operator: ConversionOperator = IdentityConversionOperator(), output_conversion_operator: ConversionOperator = IdentityConversionOperator())

Bases: object

Base class that dictates how a model has to be wrapped to interface with the filters

All inputs, whether hidden state or controls, are 2D arrays where the first dimension is the batch dimension. The batch dimension must be 1 or, if not, the same value as any other non-unity batch sizes for the purpose of NumPy broadcasting.

Parameters:

• hidden_conversion_operator – operator that determines how the filter hidden states must be converted to be given to the model

• control_conversion_operator – operator that determines how filter controls must be converted to be given to the model

• output_conversion_operator – operator that determines how model outputs must be converted to be given to the filter

abstract property num_hidden_dimensions: int

abstract property num_output_dimensions: int

abstract predict_measurement(hidden_states: ndarray, controls: ndarray) → ndarray

Method to update hidden states.

Parameters:

• hidden_states – numpy array of hidden states, where each row is a hidden state array

• controls – numpy array corresponding to the controls

Returns:

numpy array corresponding to predicted outputs

abstract update_hidden_states(hidden_states: ndarray, previous_controls: ndarray, new_controls: ndarray) → ndarray

Method to update hidden states.

Parameters:

• hidden_states – numpy array of hidden states, where each row is a hidden state array

• previous_controls – numpy array corresponding to the previous controls

• new_controls – numpy array corresponding to the new controls

Returns:

numpy array corresponding to updated hidden states

Kálmán Filters (m.e.o.filters.kalman)

Collection of classes and functions pertinent to Kálmán filters

Unscented

Definition of Unscented Kálmán Filter (UKF)

class moirae.estimators.online.filters.kalman.unscented.UKFTuningParameters

Bases: TypedDict

Auxiliary class to help provide tuning parameters to ~:class:~moirae.estimators.online.filters.kalman.UnscentedKalmanFilter

Parameters:

• alpha_param – alpha parameter to UKF

• beta_param – beta parameter to UKF

• kappa_param – kappa parameter to UKF

alpha_param: typing_extensions.NotRequired[float]

beta_param: typing_extensions.NotRequired[float]

classmethod defaults() → Self

kappa_param: typing_extensions.NotRequired[float | Literal['automatic']]

class moirae.estimators.online.filters.kalman.unscented.UnscentedKalmanFilter(model: ModelWrapper, initial_hidden: MultivariateGaussian, initial_controls: MultivariateRandomDistribution, covariance_process_noise: ndarray | None = None, covariance_sensor_noise: ndarray | None = None, alpha_param: float = 1.0, kappa_param: float | Literal['automatic'] = 0.0, beta_param: float = 2.0)

Bases: BaseFilter

Class that defines the functionality of the Unscented Kalman Filter

Parameters:

• model – model describing the system

• initial_hidden – initial hidden state of the system

• initial_controls – initial control on the system

• alpha_param – tuning parameter 0.001 <= alpha <= 1 used to control the spread of the sigma points; lower values keep sigma points closer to the mean, alpha=1 effectively brings the KF closer to Central Difference KF (default = 1.)

• kappa_param – tuning parameter kappa >= 3 - aug_len; choose values of kappa >=0 for positive semidefiniteness. (default = 0.)

• beta_param – tuning parameter beta >=0 used to incorporate knowledge of prior distribution; for Gaussian use beta = 2 (default = 2.)

• covariance_process_noise – covariance of process noise (default = 1.0e-8 * identity)

• covariance_sensor_noise – covariance of sensor noise as (default = 1.0e-8 * identity)

build_sigma_points() → ndarray

Function to build Sigma points.

Returns:

2D numpy array, where each row represents an “augmented state” consisting of hidden state, process noise, and sensor noise, in that order.

correction_update(x_k_minus: MultivariateGaussian, y_hat: MultivariateGaussian, cov_xy: ndarray, y: DeltaDistribution) → None

Function to perform the correction update of the hidden state, based on the real measured output values.

Parameters:

• x_k_minus – estimate of the hidden state P(x_k|y_(k-1))

• y_hat – output predictions P(y_k|y_k-1)

• cov_xy – covariance between hidden state and predicted output

• y – real measured output values

property cov_weights: ndarray

estimation_update(sigma_pts: ndarray, new_controls: MultivariateRandomDistribution, **kwargs) → Tuple[MultivariateGaussian, MultivariateGaussian, ndarray]

Function to perform the estimation update from the Sigma points

Parameters:

• sigma_pts – numpy array corresponding to the Sigma points built

• new_controls – new control to be used to evolve Sigma points

• **kwargs – keyword arguments that are given to the model

Returns:

new estimate of the hidden state corresponding to x_k_minus (includes mean and covariance!) - y_k: estimate of the output measurement (includes mean and covariance!) - cov_xy: covariance matrix between hidden state and output

Return type:

• x_k_minus

property gamma_param: float

property lambda_param: float

property mean_weights: ndarray

step(new_controls: MultivariateRandomDistribution, measurements: DeltaDistribution, **kwargs) → Tuple[MultivariateRandomDistribution, MultivariateRandomDistribution]

Steps the UKF

Parameters:

• new_controls – new control variables

• measurements – new measurements

• **kwargs – keyword arguments to be given to the model

Returns:

Predicted output based on model evolution, as well as corrected hidden state

moirae.estimators.online.filters.kalman.unscented.assemble_unscented_estimate_from_samples(samples: ndarray, mean_weights: ndarray, cov_weights: ndarray) → Dict

Function that takes a collection of samples and computes the relative mean and covariance based on the weights provided

Parameters:

• samples – array of evolved hidden states

• mean_weights – weights to be used by the computation of the mean

• cov_weights – weights to be used by the computation of the covariance

Returns:

Dictionary of containing ‘mean’ and ‘covariance’

moirae.estimators.online.filters.kalman.unscented.compute_unscented_covariance(cov_weights: ndarray, array0: ndarray, array1: ndarray | None = None) → ndarray

Function that computes the unscented covariance between zero-mean arrays. If second array is not provided, this is equivalent to computing the unscented variance of the only provided array.

Multivariate Distributions (m.e.o.filters.distributions)

Classes defining different multivariate probability distributions

pydantic model moirae.estimators.online.filters.distributions.DeltaDistribution

Bases: MultivariateRandomDistribution

A distribution with only one set of allowed values

Parameters:

mean – a 1D array containing allowed values; can be passed as flattened array or array with shapes (1, dim) or (dim, 1)

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

• validate_assignment: bool = True

Fields:

• mean (numpy.ndarray)

Validators:

• mean_1d » mean

field mean: ndarray = None

Mean of the distribution.

Validated by:

• mean_1d

combine_with(random_dists: Iterable[Self]) → Self

Provides an easy way to combine several multivariate independent random variables of the same distribution type (delta, gaussian, etc.), but not necessarily of the same dimensions or from the same PDFs. It must not change self!

convert(conversion_operator: ConversionOperator, inverse: bool = False) → Self

Uses the methods available in the BaseTransform to transform the underlying distribution and return a copy of the transformed MultivariateRandomDistribution

Parameters:

• transform_operator – operator to perform necessary transformations

• inverse – whether to use the inverse operations available instead of the usual “forward” ones

Returns:

transformed distribution

Return type:

transformed_dist

get_covariance() → ndarray

Provides the covariance of the distribution

get_mean() → ndarray

Provides mean (first moment) of distribution

validator mean_1d  »  mean

Making sure the mean is a vector

pydantic model moirae.estimators.online.filters.distributions.MultivariateGaussian

Bases: MultivariateRandomDistribution

Class to describe a multivariate Gaussian distribution.

Parameters:

• mean – a 1D array containing allowed values; can be passed as flattened array or array with shapes (1, dim) or (dim, 1)

• covariance – a 2D array of shape (dim, dim) describing the covariance of the distribution

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

• validate_assignment: bool = True

Fields:

• covariance (numpy.ndarray)

• mean (numpy.ndarray)

Validators:

• cov_2d » covariance

• fields_dim » all fields

• mean_1d » mean

field covariance: ndarray = array([[1]])

Covariance of the multivariate Gaussian distribution

Constraints:

• min_length = 1

Validated by:

• cov_2d

• fields_dim

field mean: ndarray = array([0])

Mean of the multivariate Gaussian distribution

Constraints:

• min_length = 1

Validated by:

• fields_dim

• mean_1d

combine_with(random_dists: Iterable[Self]) → Self

Provides an easy way to combine several multivariate independent random variables of the same distribution type (delta, gaussian, etc.), but not necessarily of the same dimensions or from the same PDFs. It must not change self!

convert(conversion_operator: ConversionOperator, inverse: bool = False) → Self

Uses the methods available in the BaseTransform to transform the underlying distribution and return a copy of the transformed MultivariateRandomDistribution

Parameters:

• transform_operator – operator to perform necessary transformations

• inverse – whether to use the inverse operations available instead of the usual “forward” ones

Returns:

transformed distribution

Return type:

transformed_dist

validator cov_2d  »  covariance

Making sure the covariance is a 2D matrix

validator fields_dim  »  all fields

Making sure dimensions match between mean and covariance

get_covariance() → ndarray

Provides the covariance of the distribution

get_mean() → ndarray

Provides mean (first moment) of distribution

validator mean_1d  »  mean

Making sure the mean is a vector

pydantic model moirae.estimators.online.filters.distributions.MultivariateRandomDistribution

Bases: BaseModel

Base class to help represent a multivariate random variable.

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

abstract combine_with(random_dists: Iterable[Self]) → Self

Provides an easy way to combine several multivariate independent random variables of the same distribution type (delta, gaussian, etc.), but not necessarily of the same dimensions or from the same PDFs. It must not change self!

abstract convert(conversion_operator: ConversionOperator, inverse: bool = False) → Self

Uses the methods available in the BaseTransform to transform the underlying distribution and return a copy of the transformed MultivariateRandomDistribution

Parameters:

• transform_operator – operator to perform necessary transformations

• inverse – whether to use the inverse operations available instead of the usual “forward” ones

Returns:

transformed distribution

Return type:

transformed_dist

abstract get_covariance() → ndarray

Provides the covariance of the distribution

abstract get_mean() → ndarray

Provides mean (first moment) of distribution

property num_dimensions: int

Number of dimensions of random variable

Coordinate Conversion (m.e.o.filters.conversions)

Tools to convert between coordinate systems

pydantic model moirae.estimators.online.filters.conversions.AbsoluteValueConversionOperator

Bases: FirstOrderTaylorConversionOperator

Class that performs an absolute value transformation to the samples.

This is particularly relevant in cases where the estimators used treat values as unbounded, but the underlying models (such as an equivalent circuit) only accept positive parameters. Since the absolute value function is not invertible, the following choice was made for its inverse operations: the inverted values always belong to the positive quadrant of space, that is, they are always positive.

Parameters:

indices – indices to which the absolute value transformation should be applied; if not provided, applies absolute value to all values

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:

• indices (List[int] | None)

field indices: List[int] | None = None

indices to apply transformation

get_inverse_jacobian(transformed_pivot: ndarray) → ndarray

Method to compute the Jacobian matrix of the inverse transformation.

Parameters:

transformed_pivot – point to be used as the transformed pivot

Returns:

Jacobian matrix of the reverse transformation

Return type:

inverse_jacobian

get_jacobian(pivot: ndarray) → ndarray

Method to calculate the Jacobian matrix of the transformation at specified pivot point

Parameters:

pivot – point to be used as the pivot of the Taylor expansion

Returns:

Jacobian matrix

Return type:

jacobian

inverse_transform_samples(transformed_samples: ndarray) → ndarray

Performs the inverse tranformation of that given by transform_points().

Parameters:

transformed_samples – np.ndarray of points to be inverse transformed

Returns:

np.ndarray corresponding to re-converted points

Return type:

samples

transform_samples(samples: ndarray) → ndarray

Transforms a set of individual points, considered to be independent samples of the same MultivariateRandomDistribution.

Parameters:

samples – np.ndarray of samples to be transformed. Its shape must be (num_samples, num_coordinates) or (num_coordinates,)

Returns:

np.ndarray of the transformed points

Return type:

transformed_samples

pydantic model moirae.estimators.online.filters.conversions.ConversionOperator

Bases: BaseModel

Base class used to convert between CellModel and BaseFilter coordinate systems.

Each implementation provides the ability to convert both points and covariances, as required to map MultivariateRandomDistribution() between the coordinate systems employed by BaseFilter and CellModel.

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

abstract inverse_transform_covariance(transformed_covariance: ndarray, transformed_pivot: ndarray) → ndarray

Performs the inverse transformation of that given by transform_covariance().

Parameters:

• transformed_covariance – np.ndarray of transformed covariance to be converted back

• transformed_pivot – in cases where Taylor-expansion is employed, it should be performed around this transformed pivot point

Returns:

np.ndarray corresponding to re-converted covariance

Return type:

covariance

abstract inverse_transform_samples(transformed_samples: ndarray) → ndarray

Performs the inverse tranformation of that given by transform_points().

Parameters:

transformed_samples – np.ndarray of points to be inverse transformed

Returns:

np.ndarray corresponding to re-converted points

Return type:

samples

abstract transform_covariance(covariance: ndarray, pivot: ndarray) → ndarray

Transforms the covariance of a MultivariateRandomDistribution.

Parameters:

• covariance – 2D np.ndarray corresponding to the covariance to be transformed

• pivot – central value around which covariance must be propagated (akin to first moment of distribution)

Returns:

transformed covariance matrix

Return type:

transformed_covariance

abstract transform_samples(samples: ndarray) → ndarray

Transforms a set of individual points, considered to be independent samples of the same MultivariateRandomDistribution.

Parameters:

samples – np.ndarray of samples to be transformed. Its shape must be (num_samples, num_coordinates) or (num_coordinates,)

Returns:

np.ndarray of the transformed points

Return type:

transformed_samples

pydantic model moirae.estimators.online.filters.conversions.FirstOrderTaylorConversionOperator

Bases: ConversionOperator

Base class that specifies the necessary machinery to perform non-linear conversions assuming a first order Taylor expansion around a pivot point is sufficient to propagate uncertainties (through covariances).

Assumes the transformation can be expressed as \(f = f_0 + J (x-p)\), where \(f_0\) represents the value of the transformation at the pivot point \(p\), and \(J\) is the Jacobian matrix at the pivot. Based on this, the covariance of the transformed vector \(f\) can be simply expressed as \({\Sigma}_f = J {\Sigma}_X J^T\), exactly like that in the LinearConversionOperator Full explanation on Wikipedia.

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

abstract get_inverse_jacobian(transformed_pivot: ndarray) → ndarray

Method to compute the Jacobian matrix of the inverse transformation.

Parameters:

transformed_pivot – point to be used as the transformed pivot

Returns:

Jacobian matrix of the reverse transformation

Return type:

inverse_jacobian

abstract get_jacobian(pivot: ndarray) → ndarray

Method to calculate the Jacobian matrix of the transformation at specified pivot point

Parameters:

pivot – point to be used as the pivot of the Taylor expansion

Returns:

Jacobian matrix

Return type:

jacobian

inverse_transform_covariance(transformed_covariance: ndarray, transformed_pivot: ndarray) → ndarray

Performs the inverse transformation of that given by transform_covariance().

Parameters:

• transformed_covariance – np.ndarray of transformed covariance to be converted back

• transformed_pivot – in cases where Taylor-expansion is employed, it should be performed around this transformed pivot point

Returns:

np.ndarray corresponding to re-converted covariance

Return type:

covariance

transform_covariance(covariance: ndarray, pivot: ndarray) → ndarray

Transforms the covariance of a MultivariateRandomDistribution.

Parameters:

• covariance – 2D np.ndarray corresponding to the covariance to be transformed

• pivot – central value around which covariance must be propagated (akin to first moment of distribution)

Returns:

transformed covariance matrix

Return type:

transformed_covariance

pydantic model moirae.estimators.online.filters.conversions.IdentityConversionOperator

Bases: ConversionOperator

Class that implements simple identity operation, that is, it does not change the inputs.

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

inverse_transform_covariance(transformed_covariance: ndarray, transformed_pivot: ndarray | None = None) → ndarray

Performs the inverse transformation of that given by transform_covariance().

Parameters:

• transformed_covariance – np.ndarray of transformed covariance to be converted back

• transformed_pivot – in cases where Taylor-expansion is employed, it should be performed around this transformed pivot point

Returns:

np.ndarray corresponding to re-converted covariance

Return type:

covariance

inverse_transform_samples(transformed_samples: ndarray) → ndarray

Performs the inverse tranformation of that given by transform_points().

Parameters:

transformed_samples – np.ndarray of points to be inverse transformed

Returns:

np.ndarray corresponding to re-converted points

Return type:

samples

transform_covariance(covariance: ndarray, pivot: ndarray | None = None) → ndarray

Transforms the covariance of a MultivariateRandomDistribution.

Parameters:

• covariance – 2D np.ndarray corresponding to the covariance to be transformed

• pivot – central value around which covariance must be propagated (akin to first moment of distribution)

Returns:

transformed covariance matrix

Return type:

transformed_covariance

transform_samples(samples: ndarray) → ndarray

Transforms a set of individual points, considered to be independent samples of the same MultivariateRandomDistribution.

Parameters:

samples – np.ndarray of samples to be transformed. Its shape must be (num_samples, num_coordinates) or (num_coordinates,)

Returns:

np.ndarray of the transformed points

Return type:

transformed_samples

pydantic model moirae.estimators.online.filters.conversions.LinearConversionOperator

Bases: ConversionOperator

A linear transformation, \(y = (multi * x) + basis\)

Parameters:

• multiplicative_array – np.ndarray corresponding to multiplicative factors in the linear function

• additive_array – np.ndarray corresponding to additive factors in the linear function

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:

• additive_array (numpy.ndarray | None)

• multiplicative_array (numpy.ndarray)

Validators:

• additive_1d » additive_array

• multiplicative_2d » multiplicative_array

field additive_array: ndarray | None = array([0.])

Additive factors of linear function

Validated by:

• additive_1d

field multiplicative_array: ndarray = array(1.)

Multiplicative factors of linear function

Validated by:

• multiplicative_2d

validator additive_1d  »  additive_array

Ensures the additive array is a 1D vector, and not a matrix

inverse_transform_covariance(transformed_covariance: ndarray, transformed_pivot: ndarray | None = None) → ndarray

Performs the inverse transformation of that given by transform_covariance().

Parameters:

• transformed_covariance – np.ndarray of transformed covariance to be converted back

• transformed_pivot – in cases where Taylor-expansion is employed, it should be performed around this transformed pivot point

Returns:

np.ndarray corresponding to re-converted covariance

Return type:

covariance

inverse_transform_samples(transformed_samples: ndarray) → ndarray

Performs the inverse tranformation of that given by transform_points().

Parameters:

transformed_samples – np.ndarray of points to be inverse transformed

Returns:

np.ndarray corresponding to re-converted points

Return type:

samples

validator multiplicative_2d  »  multiplicative_array

Ensures the multiplicative array is stored as a 2D array (or as a shapeless object)

transform_covariance(covariance: ndarray, pivot: ndarray | None = None) → ndarray

Transforms the covariance of a MultivariateRandomDistribution.

Parameters:

• covariance – 2D np.ndarray corresponding to the covariance to be transformed

• pivot – central value around which covariance must be propagated (akin to first moment of distribution)

Returns:

transformed covariance matrix

Return type:

transformed_covariance

transform_samples(samples: ndarray) → ndarray

Transforms a set of individual points, considered to be independent samples of the same MultivariateRandomDistribution.

Parameters:

samples – np.ndarray of samples to be transformed. Its shape must be (num_samples, num_coordinates) or (num_coordinates,)

Returns:

np.ndarray of the transformed points

Return type:

transformed_samples

property inv_multi: ndarray

Stores the inverse of the multiplicative array, which is needed for the inverse operations

Utilities (m.e.online.utils)

Utility functions used by many types of estimators

Cell Model Wrappers (m.e.o.utils.model)

Tools to reduce operations on CellModel to functions which act only on widely-used Python types, such as Numpy Arrays.

class moirae.estimators.online.utils.model.BaseCellWrapper(cell_model: CellModel, asoh: HealthVariable, transients: GeneralContainer, inputs: InputQuantities, converters: ModelWrapperConverters = {'control_conversion_operator': IdentityConversionOperator(), 'hidden_conversion_operator': IdentityConversionOperator(), 'output_conversion_operator': IdentityConversionOperator()})

Bases: ModelWrapper

Base link between the CellModel and the numpy-only interface of the filter implementations.

Parameters:

• cell_model – Model which defines the physics of the system being modeled

• asoh – Values for all state of health parameters of the model

• transients – Current values of the transient state of the system

• inputs – Example input values for the model

• converters – set of converters to be used to translate between filter-coordinate system and model coordinate-system

asoh: HealthVariable

ASOH values passed to each call of the cell model

cell_model: CellModel

Cell model underpinning the update functions

property num_output_dimensions: int

transients: GeneralContainer

Transient states used for the inputs of the model

class moirae.estimators.online.utils.model.CellModelWrapper(cell_model: CellModel, asoh: HealthVariable, transients: GeneralContainer, inputs: InputQuantities, converters: ModelWrapperConverters = {'control_conversion_operator': IdentityConversionOperator(), 'hidden_conversion_operator': IdentityConversionOperator(), 'output_conversion_operator': IdentityConversionOperator()})

Bases: BaseCellWrapper

This particular wrapper does not touch the A-SOH, but only uses it for predictions.

property num_hidden_dimensions: int

predict_measurement(hidden_states: ndarray, controls: ndarray) → ndarray

Function that takes a numpy representation of the transient state and of the controls, and predicts measurements from it

update_hidden_states(hidden_states: ndarray, previous_controls: ndarray, new_controls: ndarray) → ndarray

Method to update hidden states.

Parameters:

• hidden_states – numpy array of hidden states, where each row is a hidden state array

• previous_controls – numpy array corresponding to the previous controls

• new_controls – numpy array corresponding to the new controls

Returns:

numpy array corresponding to updated hidden states

class moirae.estimators.online.utils.model.DegradationModelWrapper(cell_model: ~moirae.models.base.CellModel, asoh: ~moirae.models.base.HealthVariable, transients: ~moirae.models.base.GeneralContainer, inputs: ~moirae.models.base.InputQuantities, asoh_inputs: ~typing.Tuple[str] | None = None, degradation_model: ~moirae.models.base.DegradationModel = <moirae.models.utils.NoDegradation object>, converters: ~moirae.estimators.online.filters.base.ModelWrapperConverters = {'control_conversion_operator': IdentityConversionOperator(), 'hidden_conversion_operator': IdentityConversionOperator(), 'output_conversion_operator': IdentityConversionOperator()})

Bases: BaseCellWrapper

Link between A-SOH degradation models and the numpy-only interface of the BaseFilter. It provides the model wrapper need for dual estimation frameworks

It takes an additional argument compared to the moirae.estimators.online.utils.model.BaseCellWrapper, as it needs to know the degrataion model being used. If none is passed, defaults to dummy degradation.

Parameters:

• cell_model – Model which defines the physics of the system being modeled

• asoh – Values for all state of health parameters of the model

• transients – Current values of the transient state of the system

• inputs – Example input values for the model

• asoh_inputs – Names of the ASOH parameters to include as part of the hidden state

• degradation_model – degradation model to be used; if not passed, degradation will be fully derived from data

• converters – set of converters to be used to translate between filter-coordinate system and model coordinate-system

asoh_inputs: Tuple[str]

Names of the parameters from the ASOH which are used as inputs to the model

property num_hidden_dimensions: int

predict_measurement(hidden_states: ndarray, controls: ndarray) → ndarray

Function that takes the numpy-representation of the estimated of A-SOH and computes predictions of the measurement. Recall that, for that, we first need to propagate the transients through the A-SOH estimates

update_hidden_states(hidden_states: ndarray, previous_controls: ndarray, new_controls: ndarray) → ndarray

Function that takes a numpy representation of the A-SOH and degrades it using the degradation model and the previous and new controls. If the degradation model needs information for further in the past, it is responsible for keeping track of that. The degration model will also be provided the current estimate of the transient vector.

class moirae.estimators.online.utils.model.JointCellModelWrapper(cell_model: ~moirae.models.base.CellModel, asoh: ~moirae.models.base.HealthVariable, transients: ~moirae.models.base.GeneralContainer, inputs: ~moirae.models.base.InputQuantities, asoh_inputs: ~typing.Tuple[str] | None = None, degradation_model: ~moirae.models.base.DegradationModel = <moirae.models.utils.NoDegradation object>, converters: ~moirae.estimators.online.filters.base.ModelWrapperConverters = {'control_conversion_operator': IdentityConversionOperator(), 'hidden_conversion_operator': IdentityConversionOperator(), 'output_conversion_operator': IdentityConversionOperator()})

Bases: BaseCellWrapper

Interface used when the hidden state used by a filter includes the transient states.

Create the interface by defining

• Which portions of the ASOH are used as inputs to function

• Values for the ASOH parameters that remain fixed

• An example transient state and input to be passed to the function which will be used as a template

The resultant function will take numpy arrays as inputs and produce numpy arrays as outputs

Parameters:

• cell_model – Model which defines the physics of the system being modeled

• asoh – Values for all state of health parameters of the model

• transients – Current values of the transient state of the system

• inputs – Example input values for the model

• asoh_inputs – Names of the ASOH parameters to include as part of the hidden state

• degradation_model – degradation model to be used; if not passed, degradation will be fully derived from data

• converters – set of converters to be used to translate between filter-coordinate system and model coordinate-system

asoh_inputs: Tuple[str]

Names of the parameters from the ASOH which are used as inputs to the model

create_cell_model_inputs(hidden_states: ndarray) → Tuple[HealthVariable, GeneralContainer]

Convert the hidden states into the forms used by CellModel

Parameters:

hidden_states – Hidden states as used by the estimator

Returns:

• ASOH with values from the hidden states

• Transients state from the hidden states

create_hidden_state(asoh: HealthVariable, transients: GeneralContainer) → ndarray

Transform the state of health and transients states (quantities used by CellModel) into the “hidden state” vector used by the actual filter

Parameters:

• asoh – Values of the ASOH parameter

• transients – Values of the transient states

Returns:

A hidden state vector ready for use in a filter

property num_hidden_dimensions: int

predict_measurement(hidden_states: ndarray, controls: ndarray) → ndarray

Method to update hidden states.

Parameters:

• hidden_states – numpy array of hidden states, where each row is a hidden state array

• controls – numpy array corresponding to the controls

Returns:

numpy array corresponding to predicted outputs

update_hidden_states(hidden_states: ndarray, previous_controls: ndarray, new_controls: ndarray) → ndarray

Method to update hidden states.

Parameters:

• hidden_states – numpy array of hidden states, where each row is a hidden state array

• previous_controls – numpy array corresponding to the previous controls

• new_controls – numpy array corresponding to the new controls

Returns:

numpy array corresponding to updated hidden states

moirae.estimators.online.utils.model.convert_vals_model_to_filter(model_quantities: GeneralContainer, uncertainty_matrix: ndarray | None = None) → DeltaDistribution | MultivariateGaussian

Function that converts GeneralContainer object to filter-related quantities. If uncertainty is provided, assumes a MultivariateGaussian. Otherwise, assumes DeltaDistribution.

Parameters:

• model_quantities – model-related object to be converted into filter-related object

• uncertainty_matrix – 2D array to be used as covariance matrix; if not provided, returns DeltaDistribution

Returns:

a corresponding MultivariateRandomDistribution (either Gaussian or Delta)