Interface (moirae.interface)#

Interfaces for running common workflows with Moirae, with a particular emphasis on data built with battery-data-toolkit

moirae.interface.row_to_inputs(row: Series, default_temperature: float = 25) → Tuple[InputQuantities, OutputQuantities]#

Convert a row from the time series data to a distribution object

Parameters:

  • row – Row from the dataset.raw_data dataframe

  • default_temperature – Default temperature for the cells (units: C)

Returns:

  • Distribution describing the inputs

  • Distribution describing the measurements (model outputs)

moirae.interface.run_model(model: CellModel, dataset: BatteryDataset, asoh: HealthVariable, state_0: GeneralContainer) → DataFrame#

Run a cell model following data provided by a BatteryDataset

Parameters:

  • model – Model describing the cell

  • dataset – Observations of current and voltage used when running th emodel

  • asoh – Parameters for the cell

  • state_0 – Starting state for the model

Returns:

Outputs from the model as a function of time

moirae.interface.run_online_estimate(dataset: BatteryDataset | str | Path, estimator: OnlineEstimator, pbar: bool = False, output_states: bool = True, hdf5_output: Path | str | Group | HDF5Writer | None = None) → Tuple[DataFrame, OnlineEstimator]#

Run an online estimation of battery parameters given a fixed dataset for the

Parameters:

  • dataset – Dataset containing the time series of a battery’s performance. Provide either the path to a battdata HDF5 file or BatteryDataset object.

  • estimator – Technique used to estimate the state of health, which is built using a physics model which describes the cell and initial guesses for the battery transient and health states.

  • pbar – Whether to display a progress bar

  • output_states – Whether to return summaries of the per-step states. Can require a large amount of memory for full datasets.

  • hdf5_output – Path to an HDF5 file or group within an already-open file in which to write the estimated parameter values. Writes the mean for each timestep and the full state for the first timestep in each cycle by default. Modify what is written by providing a HDF5Writer.

Returns:

  • Estimates of the parameters at all timesteps from the input dataset

  • Estimator after updating with the data in dataset

HDF5 Output (m.interface.hdf5)#

Tools for writing state estimates to HDF5 files

pydantic model moirae.interface.hdf5.HDF5Writer#

Bases: BaseModel, AbstractContextManager

Write state estimation data to an HDF5 file incrementally

Parameters:

  • hdf5_output – Path to an HDF5 file or group within a file in which to write data

  • storage_key – Name of the group within the file to store all states

  • table_options – Option used when initializing storage. See Filters(). Default is to use LZF compression.

  • per_timestep – Which information to store at each timestep: - full: All available information about the estimated state - mean_cov: The mean and covariance of the estimated state - mean_var: The mean and variance (i.e., diagonal of covariance matrix) of the estimated state - mean: Only the mean - none: No information

  • per_cycle – Which information to write at the first step of a cycle. The options are the same as per_timestep.

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:
field hdf5_output: Path | str | File [Required]#

File or already-open HDF5 file in which to store data

field per_cycle: Literal['full', 'mean_cov', 'mean_var', 'mean', 'none'] = 'full'#

What information to store at the first timestep each cycle

field per_timestep: Literal['full', 'mean_cov', 'mean_var', 'mean', 'none'] = 'mean'#

What information to write each timestep

field storage_key: str = 'state_estimates'#

Name of the group in which to store the estimates

field table_options: Dict[str, Any] [Optional]#

Option used when initializing storage. See Filters

append_step(time: float, cycle: int, state: MultivariateRandomDistribution, output: MultivariateRandomDistribution)#

Add a state estimate to the dataset

Parameters:

  • time – Test time of timestep

  • cycle – Cycle associated with the timestep

  • state – State to be stored

  • output – Outputs predicted from the estimator

model_post_init(context: Any, /) → None#

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

  • self – The BaseModel instance.

  • context – The context.

prepare(estimator: OnlineEstimator, expected_steps: int | None = None, expected_cycles: int | None = None)#

Create the necessary groups and store metadata about the OnlineEstimator

Parameters:

  • estimator – Estimator being used to create estimates

  • expected_steps – Expected number of estimation timesteps. Required if not resizable.

  • expected_cycles – Expected number of cycles.

property is_ready: bool#

Whether the class is ready to write estimates

moirae.interface.hdf5.read_state_estimates(data_path: str | ~pathlib.Path | ~tables.group.Group, per_timestep: bool = True, dist_type: type[~moirae.estimators.online.filters.distributions.MultivariateRandomDistribution] = <class 'moirae.estimators.online.filters.distributions.MultivariateGaussian'>) → Iterator[tuple[float, MultivariateRandomDistribution, MultivariateRandomDistribution]]#

Read the state estimates from a file into progressive streams

Parameters:

  • data_path – Path to the HDF5 file or the group holding state estimates from an already-open file.

  • per_timestep – Whether to read per-timestep rather than per-cycle estimates

  • dist_type – Distribution type to create if the “full” distribution is stored

Yields:

  • Time associated with estimate

  • Distribution of state estimates

  • Distribution of the output estimates