Prognostics Model

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 equation.

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]

performance_metric_keys

Identifiers for each performance metric

Type

List[str], optional

events

Identifiers for each event predicted

Type

List[str], optional

StateContainer

Class for state container - used for representing state

Type

DictLikeMatrixWrapper

OutputContainer

Class for output container - used for representing output

Type

DictLikeMatrixWrapper

InputContainer

Class for input container - used for representing input

Type

DictLikeMatrixWrapper

class SimulationResults(times, inputs, states, outputs, event_states)
count(value, /)

Return number of occurrences of value.

event_states

Alias for field number 4

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

inputs

Alias for field number 1

outputs

Alias for field number 3

states

Alias for field number 2

times

Alias for field number 0

apply_limits(x: dict) dict

Apply state bound limits. Any state outside of limits will be set to the closest limit.

Parameters

x (dict) –

state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Returns

x – Bounded state, with keys defined by model.states e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Return type

dict

apply_measurement_noise(z: dict) dict

Apply measurement noise to the measurement

Parameters

z (dict) –

output, with keys defined by model.outputs

e.g., z = {‘abc’: 332.1, ‘def’: 221.003} given outputs = [‘abc’, ‘def’]

Returns

z – output, with applied noise, with keys defined by model.outputs

e.g., z = {‘abc’: 332.2, ‘def’: 221.043} given outputs = [‘abc’, ‘def’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
z = {‘z1’: 2.2}
z = m.apply_measurement_noise(z)

Note

Configured using parameters measurement_noise and measurement_noise_dist

apply_process_noise(x: dict, dt: int = 1) dict

Apply process noise to the state

Parameters
  • x (dict) –

    state, with keys defined by model.states

    e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

  • dt (Number, optional) – Time step (e.g., dt = 0.1)

Returns

x – state, with applied noise, with keys defined by model.states e.g., x = {‘abc’: 332.2, ‘def’: 221.043} given states = [‘abc’, ‘def’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
x = m.apply_process_noise(x)

Note

Configured using parameters process_noise and process_noise_dist

calc_error(times: List[float], inputs: List[dict], outputs: List[dict], **kwargs) float

Calculate Mean Squared Error (MSE) between simulated and observed

Parameters
  • times ([double]) – array of times for each sample

  • inputs ([dict]) – array of input dictionaries where input[x] corresponds to time[x]

  • outputs ([dict]) – array of output dictionaries where output[x] corresponds to time[x]

  • kwargs

    Configuration parameters, such as:

    x0 [dict]: Initial state
    dt [double] : time step

Returns

Total error

Return type

double

dx(x: dict, u: dict) dict

Calculate the first derivative of state x at a specific time t, given state and input

Parameters
  • x (dict) –

    state, with keys defined by model.states

    e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

  • u (dict) –

    Inputs, with keys defined by model.inputs

    e.g., u = {‘i’:3.2} given inputs = [‘i’]

Returns

dx – First derivitive of state, with keys defined by model.states

e.g., dx = {‘abc’: 3.1, ‘def’: -2.003} given states = [‘abc’, ‘def’]

Return type

dict

Example

m = DerivProgModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
dx = m.dx(x, u) # Returns first derivative of state given input u

See also

next_state

Note

A model should overwrite either next_state or dx. Override dx for continuous models, and next_state for discrete, where the behavior cannot be described by the first derivative

estimate_params(runs: List[tuple], keys: List[str], **kwargs) None

Estimate the model parameters given data. Overrides model parameters

Parameters
  • runs (array[tuple]) – data from all runs, where runs[0] is the data from run 0. Each run consists of a tuple of arrays of times, input dicts, and output dicts

  • keys ([string]) – Parameter keys to optimize

  • kwargs

    Configuration parameters. Supported parameters include:

    method: Optimization method- see scikit.optimize.minimize
    options: Options passed to optimizer

See: examples.param_est

event_state(x: dict) dict

Calculate event states (i.e., measures of progress towards event (0-1, where 0 means event has occured))

Parameters

x (dict) –

state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Returns

event_state – Event States, with keys defined by prognostics_model.events.

e.g., event_state = {‘EOL’:0.32} given events = [‘EOL’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
event_state = m.event_state(x) # Returns {‘e1’: 0.8, ‘e2’: 0.6}

Note

Default is to return an empty array (for system models that do not include any events)

See also

threshold_met

static generate_model(keys: dict, initialize_eqn: Callable, output_eqn: Callable, next_state_eqn: Optional[Callable] = None, dx_eqn: Optional[Callable] = None, event_state_eqn: Optional[Callable] = None, threshold_eqn: Optional[Callable] = None, config: dict = {'process_noise': 0.1}) prog_models.prognostics_model.PrognosticsModel

Generate a new prognostics model from individual model functions

Parameters
  • keys (dict) – Dictionary containing keys required by model. Must include inputs, outputs, and states. Can also include events

  • initialize_eqn (callable) – Equation to initialize first state of the model. See initialize

  • output_eqn (callable) – Equation to calculate the outputs (measurements) for the model. See output

  • next_state_eqn (callable) –

    Equation to calculate next_state from current state. See next_state.

    Use this for discrete functions

  • dx_eqn (callable) –

    Equation to calculate dx from current state. See dx.

    Use this for continuous functions

  • event_state_eqn (callable, optional) – Equation to calculate the state for each event of the model. See event_state

  • threshold_eqn (callable, optional) – Equation to calculate if the threshold has been met for each event in model. See threshold_met

  • config (dict, optional) – Any configuration parameters for the model

Returns

model – A callable PrognosticsModel

Return type

PrognosticsModel

Raises

ProgModelInputException

Example

keys = {
‘inputs’: [‘u1’, ‘u2’],
‘states’: [‘x1’, ‘x2’, ‘x3’],
‘outputs’: [‘z1’],
‘events’: [‘e1’, ‘e2’]
}

m = PrognosticsModel.generate_model(keys, initialize_eqn, next_state_eqn, output_eqn, event_state_eqn, threshold_eqn)
generate_surrogate(load_functions, method='dmd', **kwargs)

Generate a surrogate model to approximate the higher-fidelity model

Parameters
  • load_functions (list of callable functions) – Each index is a callable loading function of (t, x = None) -> z used to predict future loading (output) at a given time (t) and state (x)

  • method (str, optional) – String indicating surrogate modeling method to be used

Keyword Arguments
  • keywords (Includes all keyword arguments from simulate_to_threshold (except save_pts), and the following additional) –

  • dt (Number or function, optional) – Same as in simulate_to_threshold; for DMD, this value is the time step of the training data

  • save_freq (Number, optional) – Same as in simulate_to_threshold; for DMD, this value is the time step with which the surrogate model is generated

  • trim_data_to (int, optional) –

    Value between 0 and 1 that determines fraction of data resulting from simulate_to_threshold that is used to train DMD surrogate model e.g. if trim_data_to = 0.7 and the simulated data spans from t=0 to t=100, the surrogate model is trained on the data from t=0 to t=70

    Note: To trim data to a set time, use the ‘horizon’ parameter

  • states (list, optional) – List of state keys to be included in the surrogate model generation. keys must be a subset of those defined in the PrognosticsModel

  • inputs (list, optional) – List of input keys to be included in the surrogate model generation. keys must be a subset of those defined in the PrognosticsModel

  • outputs (list, optional) – List of output keys to be included in the surrogate model generation. keys must be a subset of those defined in the PrognosticsModel

  • events (list, optional) – List of event_state keys to be included in the surrogate model generation. keys must be a subset of those defined in the PrognosticsModel

  • stability_tol (int, optional) – Value that determines the tolerance for DMD matrix stability

Returns

SurrogateModel() – Instance of SurrogateModel class

Return type

class

Example

See examples/generate_surrogate

Note

This is a first draft of a surrogate model generation using Dynamic Mode Decomposition. DMD does not generate accurate approximations for all models, especially highly non-linear sections, and can be sensitive to the training data time step. In general, the approximation is less accurate if the DMD matrix is unstable. Additionally, this implementation does not yet include all functionalities of DMD (e.g. reducing the system’s dimensions through SVD). Further functionalities will be included in future releases.

abstract initialize(u: Optional[dict] = None, z: Optional[dict] = None) dict

Calculate initial state given inputs and outputs

Parameters
  • u (dict) –

    Inputs, with keys defined by model.inputs

    e.g., u = {‘i’:3.2} given inputs = [‘i’]

  • z (dict) –

    Outputs, with keys defined by model.outputs

    e.g., z = {‘t’:12.4, ‘v’:3.3} given inputs = [‘t’, ‘v’]

Returns

x – First state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
next_state(x: dict, u: dict, dt: int) dict

State transition equation: Calculate next state

Parameters
  • x (dict) –

    state, with keys defined by model.states

    e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

  • u (dict) –

    Inputs, with keys defined by model.inputs

    e.g., u = {‘i’:3.2} given inputs = [‘i’]

  • dt (number) –

    Timestep size in seconds (≥ 0)

    e.g., dt = 0.1

Returns

x – Next state, with keys defined by model.states e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
x = m.next_state(x, u, 0.1) # Returns state at 3.1 seconds given input u

See also

dx

Note

A model should overwrite either next_state or dx. Override dx for continuous models, and next_state for discrete, where the behavior cannot be described by the first derivative

observables(x: dict) dict

Calculate performance metrics where

Parameters

x (dict) –

state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Returns

pm – Performance Metrics, with keys defined by model.performance_metric_keys.

e.g., pm = {‘tMax’:33, ‘iMax’:19} given performance_metric_keys = [‘tMax’, ‘iMax’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
pm = m.performance_metrics(x) # Returns {‘tMax’:33, ‘iMax’:19}
abstract output(x: dict) dict

Calculate outputs given state

Parameters

x (dict) –

state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Returns

z – Outputs, with keys defined by model.outputs.

e.g., z = {‘t’:12.4, ‘v’:3.3} given outputs = [‘t’, ‘v’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
z = m.output(x) # Returns {‘o1’: 1.2}
performance_metrics(x: dict) dict

Calculate performance metrics where

Parameters

x (dict) –

state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Returns

pm – Performance Metrics, with keys defined by model.performance_metric_keys.

e.g., pm = {‘tMax’:33, ‘iMax’:19} given performance_metric_keys = [‘tMax’, ‘iMax’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
pm = m.performance_metrics(x) # Returns {‘tMax’:33, ‘iMax’:19}
simulate_to(time: float, future_loading_eqn: Callable, first_output: Optional[dict] = None, **kwargs) collections.namedtuple

Simulate prognostics model for a given number of seconds

Parameters
  • time (number) –

    Time to which the model will be simulated in seconds (≥ 0.0)

    e.g., time = 200

  • future_loading_eqn (callable) – Function of (t) -> z used to predict future loading (output) at a given time (t)

  • first_output (dict, optional) – First measured output, needed to initialize state for some classes. Can be omitted for classes that dont use this

  • options (kwargs, optional) –

    Configuration options for the simulation

    Note: configuration of the model is set through model.parameters

    Supported parameters: see simulate_to_threshold

Returns

  • times (number) – Times for each simulated point

  • inputs ([dict]) – Future input (from future_loading_eqn) for each time in times

  • states ([dict]) – Estimated states for each time in times

  • outputs ([dict]) – Estimated outputs for each time in times

  • event_states ([dict]) – Estimated event state (e.g., SOH), between 1-0 where 0 is event occurance, for each time in times

Raises

ProgModelInputException

Example

def future_load_eqn(t):
if t< 5.0: # Load is 3.0 for first 5 seconds
return 3.0
else:
return 5.0
first_output = {‘o1’: 3.2, ‘o2’: 1.2}
m = PrognosticsModel() # Replace with specific model being simulated
(times, inputs, states, outputs, event_states) = m.simulate_to(200, future_load_eqn, first_output)
simulate_to_threshold(future_loading_eqn: Callable, first_output: Optional[dict] = None, threshold_keys: Optional[list] = None, **kwargs) collections.namedtuple

Simulate prognostics model until any or specified threshold(s) have been met

Parameters

future_loading_eqn (callable) – Function of (t) -> z used to predict future loading (output) at a given time (t)

Keyword Arguments
  • t0 (Number, optional) – Starting time for simulation in seconds (default: 0.0)

  • dt (Number or function, optional) – time step (s), e.g. dt = 0.1 or function (t, x) -> dt

  • save_freq (Number, optional) – Frequency at which output is saved (s), e.g., save_freq = 10

  • save_pts (List[Number], optional) – Additional ordered list of custom times where output is saved (s), e.g., save_pts= [50, 75]

  • horizon (Number, optional) – maximum time that the model will be simulated forward (s), e.g., horizon = 1000

  • first_output (dict, optional) – First measured output, needed to initialize state for some classes. Can be omitted for classes that dont use this

  • threshold_keys (List[str] or str, optional) – Keys for events that will trigger the end of simulation. If blank, simulation will occur if any event will be met ()

  • x (dict, optional) – initial state dict, e.g., x= {‘x1’: 10, ‘x2’: -5.3}

  • thresholds_met_eqn (function/lambda, optional) – custom equation to indicate logic for when to stop sim f(thresholds_met) -> bool

  • print (bool, optional) –

    toggle intermediate printing, e.g., print = True

    e.g., m.simulate_to_threshold(eqn, z, dt=0.1, save_pts=[1, 2])

  • progress (bool, optional) – toggle progress bar printing, e.g., progress = True

Returns

  • times (Array[number]) – Times for each simulated point

  • inputs (SimResult) – Future input (from future_loading_eqn) for each time in times

  • states (SimResult) – Estimated states for each time in times

  • outputs (SimResult) – Estimated outputs for each time in times

  • event_states (SimResult) – Estimated event state (e.g., SOH), between 1-0 where 0 is event occurance, for each time in times

Raises

ProgModelInputException

See also

simulate_to

Example

def future_load_eqn(t):
if t< 5.0: # Load is 3.0 for first 5 seconds
return {‘load’: 3.0}
else:
return {‘load’: 5.0}
first_output = {‘o1’: 3.2, ‘o2’: 1.2}
m = PrognosticsModel() # Replace with specific model being simulated
(times, inputs, states, outputs, event_states) = m.simulate_to_threshold(future_load_eqn, first_output)

Note

configuration of the model is set through model.parameters.

threshold_met(x: dict) dict

For each event threshold, calculate if it has been met

Parameters

x (dict) –

state, with keys defined by model.states

e.g., x = {‘abc’: 332.1, ‘def’: 221.003} given states = [‘abc’, ‘def’]

Returns

thresholds_met – If each threshold has been met (bool), with keys defined by prognostics_model.events

e.g., thresholds_met = {‘EOL’: False} given events = [‘EOL’]

Return type

dict

Example

m = PrognosticsModel() # Replace with specific model being simulated
u = {‘u1’: 3.2}
z = {‘z1’: 2.2}
x = m.initialize(u, z) # Initialize first state
threshold_met = m.threshold_met(x) # returns {‘e1’: False, ‘e2’: False}

Note

If not overwritten, the default behavior is to say the threshold is met if the event state is <= 0

See also

event_state