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: ~pandas.core.series.Series, default_temperature: float = 25, input_class: type[~moirae.models.base.InputQuantities] = <class 'moirae.models.ecm.ins_outs.ECMInput'>, output_class: type[~moirae.models.base.OutputQuantities] = <class 'moirae.models.ecm.ins_outs.ECMMeasurement'>) → 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)

  • input_class – Class to use to store inputs

  • output_class – Class to use to store outputs

Returns:

  • Distribution describing the inputs

  • Distribution describing the measurements (model outputs)

moirae.interface.run_model(model: ~moirae.models.base.CellModel, dataset: ~battdat.data.BatteryDataset, asoh: ~moirae.models.base.HealthVariable, state_0: ~moirae.models.base.GeneralContainer, inout_types: tuple[type[~moirae.models.base.InputQuantities], type[~moirae.models.base.OutputQuantities]] = (<class 'moirae.models.ecm.ins_outs.ECMInput'>, <class 'moirae.models.ecm.ins_outs.ECMMeasurement'>)) → 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

  • inout_types – Types used to represent input and measurement data. Uses those for the Moirae ECM by default

Returns:

Outputs from the model as a function of time

moirae.interface.run_online_estimate(dataset: ~battdat.data.BatteryDataset | str | ~pathlib.Path, estimator: ~moirae.estimators.online.OnlineEstimator, pbar: bool = False, output_states: bool = True, hdf5_output: ~pathlib.Path | str | ~tables.group.Group | ~moirae.interface.hdf5.HDF5Writer | None = None, inout_types: tuple[type[~moirae.models.base.InputQuantities], type[~moirae.models.base.OutputQuantities]] = (<class 'moirae.models.ecm.ins_outs.ECMInput'>, <class 'moirae.models.ecm.ins_outs.ECMMeasurement'>)) → 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.

  • inout_types – Types used to represent input and measurement data. Uses those for the Moirae ECM by default

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_asoh_transient_estimates(data_path: str | Path | Group, per_timestep: bool = True) → Iterator[tuple[float, HealthVariable, GeneralContainer]]#

Read estimates for the battery health and state over time.

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

Yields:

The mean aSOH and battery state at each time step.

moirae.interface.hdf5.read_outputs_to_df(data_path: str | Path | Group, per_timestep: bool = True, read_std: bool = True, read_cov: bool | Collection[tuple[str, str]] = False) → DataFrame#

Read output estimates from the file into a single Pandas DataFrame

Column name convention is the same as read_state_estimates_to_df().

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

  • read_std – Whether to read the standard deviations of each variable

  • read_cov – Which subset of covariances to read. Either none (False), all (True), or only a subset provided in a list of pairs

Returns:

A pandas dataframe with the requested data

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

moirae.interface.hdf5.read_state_estimates_to_df(data_path: str | Path | Group, per_timestep: bool = True, read_std: bool = True, read_cov: bool | Collection[tuple[str, str]] = False) → DataFrame#

Read states estimates from the file into a single Pandas DataFrame

Columns will always include the mean of each estimate and the name of the column will start with mean_.

Columns for the standard deviations start with std_.

Columns for covariance start are of the form cov_(<var1>,<var2>). The names contain reserved characters for Python and, therefore, require using backticks when performing queries in Pandas query().

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

  • read_std – Whether to read the standard deviations of each variable

  • read_cov – Which subset of covariances to read. Either none (False), all (True), or only a subset provided in a list of pairs

Returns:

A pandas dataframe with the requested data

moirae.interface.hdf5.read_to_df(data_path: str | Path | Group, per_timestep: bool = True, read_std: bool = True, read_cov: bool | Collection[tuple[str, str]] = False) → DataFrame#

Read both the states and output estimates to the same dataframe

Column name convention is the same as read_state_estimates_to_df().

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

  • read_std – Whether to read the standard deviations of each variable

  • read_cov – Which subset of covariances to read. Either none (False), all (True), or only a subset provided in a list of pairs. Pairs must either be both state variables or output variables. Covariance between state and output is not available.

Returns:

A pandas dataframe with the requested data