Getting Started

https://mybinder.org/badge_logo.svg

The NASA Prognostics Models Package is a python framework for defining, building, using, and testing models for prognostics (computation of remaining useful life) of engineering systems, and provides a set of prognostics models for select components developed within this framework, suitable for use in prognostics applications for these components. It can be used in conjunction for the Prognostics Algorithms Library to perform research in prognostics methods.

The foundation of this package is the class prog_models.PrognosticsModel. This class defines the model interface and provides tools for analysis and simulation. New models must either be a subclass of this model or use the model generator method (prog_models.PrognosticsModel.generate_model())

Installing

Installing pre-release versions with GitHub

For users who would like to contribute to prog_models or would like to use pre-release features can do so using the ‘dev’ branch (or a feature branch) on the prog_models GitHub repo. This isn’t recommended for most users as this version may be unstable. To use this version, use the following commands:

$ git clone https://github.com/nasa/prog_models
$ cd prog_algs
$ git checkout dev
$ pip install -e .

Summary

A few definitions to get started:

  • events: something that can be predicted (e.g., system failure). An event has either occurred or not.

  • event state: progress towards event occurring. Defined as a number where an event state of 0 indicates the event has occurred and 1 indicates no progress towards the event (i.e., fully healthy operation for a failure event). For gradually occurring events (e.g., discharge) the number will progress from 1 to 0 as the event nears. In prognostics, event state is frequently called “State of Health”

  • inputs: control applied to the system being modeled (e.g., current drawn from a battery)

  • outputs: measured sensor values from a system (e.g., voltage and temperature of a battery)

  • observables: performance characteristics of a system that are a function of system state, but are not directly measured.

  • states: Internal parameters (typically hidden states) used to represent the state of the system- can be same as inputs/outputs but do not have to be.

  • process noise: stochastic process representing uncertainty in the model transition.

  • measurement noise: stochastic process representing uncertainty in the measurement process; e.g., sensor sensitivity, sensor misalignements, environmental effects

Use

The best way to learn how to use prog_models is through the tutorial. There are also a number of examples which show different aspects of the package, summarized and linked below:

  • examples.sim

    Example of a battery being simulated for a set period of time and then till threshold is met.


  • examples.model_gen

    Example of generating a models from constituant parts.

    Model for this example is that of an object thrown into the air, predicting impact event


  • examples.benchmarking

    Example of benchmarking models.


  • examples.new_model

    Example defining and testing a new model.


  • examples.sensitivity

    Example of a sensitivity analysis on a new model.


  • examples.events

    Example further illustrating the concept of ‘events’ which generalizes the idea of EOL.

    ‘Events’ is the term used to describe something to be predicted. Generally in the PHM community these are referred to as End of Life (EOL). However, they can be much more.

    In the implementation from the prog_models package, events can be anything that needs to be predicted. Events can represent end of life (EOL), end of mission (EOM), warning thresholds, or any event of interest (EOI).

    This example demonstrates how events can be used in your applications.


  • examples.noise

    Example defining and testing a new model.


  • examples.visualize

    Example of Visualization Module.


  • examples.future_loading

    Example demonstrating ways to use future loading.


  • examples.param_est

    Example of the model parameter estimation feature.


  • examples.derived_params

    Example demonstrating ways to use the derived parameters feature for model building.


  • examples.state_limits

    Example demonstrating ways to use state limits.


  • examples.dynamic_step_size

    Example demonstrating ways to use the dynamic step size feature. This feature allows users to define a time-step that changes with time or state.


Model Specific examples

Extending

There are two methods for creating new models: 1. Implementing a new subclass of the base model class (prog_models.PrognosticsModel) or 2. use the model generator method (prog_models.PrognosticsModel.generate_model()). These methods are described more below.

1. Subclass Method

The first method for creating a new prog_model is by creating a new subclass of prog_models.PrognosticsModel. prog_models.PrognosticsModel is described below:

class prog_models.PrognosticsModel(**kwargs)

A general time-variant state space model of system degradation behavior.

The PrognosticsModel class is a wrapper around a mathematical model of a system as represented by a state, output, input, event_state and threshold equations.

A Model also has a parameters structure, which contains fields for various model parameters.

Keyword Arguments
  • process_noise (Optional, float or Dict[Srt, float]) – Process noise (applied at dx/next_state). Can be number (e.g., .2) applied to every state, a dictionary of values for each state (e.g., {‘x1’: 0.2, ‘x2’: 0.3}), or a function (x) -> x

  • process_noise_dist (Optional, String) – distribution for process noise (e.g., normal, uniform, triangular)

  • measurement_noise (Optional, float or Dict[Srt, float]) – Measurement noise (applied in output eqn). Can be number (e.g., .2) applied to every output, a dictionary of values for each output (e.g., {‘z1’: 0.2, ‘z2’: 0.3}), or a function (z) -> z

  • measurement_noise_dist (Optional, String) – distribution for measurement noise (e.g., normal, uniform, triangular)

  • model (Additional parameters specific to the) –

Raises

ProgModelTypeError, ProgModelInputException, ProgModelException

Example

m = PrognosticsModel({‘process_noise’: 3.2})

is_vectorized

True if the model is vectorized, False otherwise. Default is False

Type

bool, optional

default_parameters

Default parameters for the model class

Type

dict[str, float], optional

parameters

Parameters for the specific model object. This is created automatically from the default_parameters and kwargs

Type

dict[str, float]

state_limits

Limits on the state variables format {‘state_name’: (lower_limit, upper_limit)}

Type

dict[str, tuple[float, float]], optional

param_callbacks

Callbacks for derived parameters

Type

dict[str, list[function]], optional

inputs

Identifiers for each input

Type

List[str]

states

Identifiers for each state

Type

List[str]

outputs

Identifiers for each output

Type

List[str]

observables_keys

Identifiers for each observable

Type

List[str], optional

events

Identifiers for each event predicted

Type

List[str], optional

To generate a new model create a new class for your model that inherits from this class. Alternatively, you can copy the template prog_model_template.ProgModelTemplate, replacing the methods with logic defining your specific model.

The analysis and simulation tools defined in prog_models.PrognosticsModel will then work with your new model.

See examples.new_model for an example of this approach.

2. Model Generator Method

The second way to generate a new model is using the model generator method, prog_models.PrognosticsModel.generate_model(). Pass a dictionary of the keys for input, state, output, events (optional), and the required transition into the method, and it will return a constructed model. See prog_models.PrognosticsModel.generate_model() for more detail.

See examples.model_gen for an example of this approach.

Updates in V1.2 (Mini-Release)

  • New Feature: Vectorized Models
    • Distributed models were vectorized to support vectorized sample-based prognostics approaches

  • New Feature: Dynamic Step Sizes
    • Now step size can be a function of time or state

    • See examples.dynamic_step_size for more information

  • New Feature: New method model.apply_bounds
    • This method allows for other classes to use applied bound limits

  • Simulate_to* methods can now specify initial time. Also, outputs are now optional

  • Various bug fixes

Updates in V1.1

  • New Feature: Derived Parameters
    • Users can specify callbacks for parameters that are defined from others. These callbacks will be called when the dependency parameter is updated.

    • See examples.derived_params for more information.

  • New Feature: Parameter Estimation
    • Users can use the estimate_parameters method to estimate all or select parameters.

    • see examples.param_est

  • New Feature: Automatic Noise Generation
    • Now noise is automatically generated when next_state/dx (process_noise) and output (measurement_noise). This removed the need to explicitly call apply_*_noise functions in these methods.

    • See examples.noise for more details in setting noise

    • For any classes users created using V1.0.*, you should remove any call to apply_*_noise functions to prevent double noise application.

  • New Feature: Configurable State Bounds
    • Users can specify the range of valid values for each state (e.g., a temperature in celcius would have to be greater than -273.15 - absolute zero)

  • New Feature: Simulation Result Class
    • Simulations now return a simulation result object for each value (e.g., output, input, state, etc)

    • These simulation result objects can be used just like the previous lists.

    • Output and Event State are now “Lazily Evaluated”. This speeds up simulation when intermediate states are not printed and these properties are not used

    • A plot method has been added directly to the class (e.g., event_states.plot())

  • New Feature: Intermediate Result Printing
    • Use the print parameter to enable printing intermediate results during a simulation

    • e.g., model.simulate_to_threshold(…, print=True)

    • Note: This slows down simulation performance

  • Added support for python 3.9

  • Various bug fixes

ElectroChemistry Model Updates

  • New Feature: Added thermal effects. Now the model include how the temperature is effected by use. Previous implementation only included effects of temperature on performance.

  • New Feature: Added degraded_capacity (i.e., EOL) event to model. There are now three different models: BatteryElectroChemEOL (degraded_capacity only), BatteryElectroChemEOD (discharge only), and BatteryElectroChemEODEOL (combined). BatteryElectroChem is an alias for BatteryElectroChemEODEOL.

  • New Feature: Updated SOC (EOD Event State) calculation to include voltage when near V_EOD. This prevents a situation where the voltage is below lower bound but SOC > 0.

CentrifugalPump Model Updates

  • New Feature: Added CentrifugalPumpBase class where wear rates are parameters instead of part of the state vector.
    • Some users may use this class for prognostics, then use the parameter estimation tool occasionally to update the wear rates, which change very slowly.

  • Bugfix: Fixed bug where some event states were returned as negative

  • Bugfix: Fixed bug where some states were saved as parameters instead of part of the state.

  • Added example on use of CentrifugalPump Model (see examples.sim_pump)

  • Performance improvements

PneumaticValve Model Updates

  • New Feature: Added PneumaticValveBase class where wear rates are parameters instead of part of the state vector.
    • Some users may use this class for prognostics, then use the parameter estimation tool occasionally to update the wear rates, which change very slowly.

  • Added example on use of PneumaticValve Model (see examples.sim_valve)

Tips

  • To predict a certain partial state (e.g., 50% SOH), create a new event (e.g., ‘SOH_50’) override the event_state and threshold_met equations to also predict that additional state

  • If you’re only doing diagnostics without prognostics- just define a next_state equation with no change of state and don’t perform prediction. The state estimator can still be used to estimate if any of the events have occured.

  • Sudden events use a binary event_state (1=healthy, 0=failed)

  • You can predict as many events as you would like, sometimes one event must happen before another, in this case the event occurance for event 1 can be a part of the equation for event 2 (‘event 2’: event_1 and [OTHER LOGIC])