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 simulatedz = {‘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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statex = 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 statedt [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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statedx = m.dx(x, u) # Returns first derivative of state given input uSee also
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.minimizeoptions: 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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first stateevent_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
- 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
- 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 simulatedu = {‘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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statex = m.next_state(x, u, 0.1) # Returns state at 3.1 seconds given input uSee also
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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statepm = 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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statez = 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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statepm = 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 –
See also
Example
def future_load_eqn(t):if t< 5.0: # Load is 3.0 for first 5 secondsreturn 3.0else:return 5.0first_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
Example
def future_load_eqn(t):if t< 5.0: # Load is 3.0 for first 5 secondsreturn {‘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 simulatedu = {‘u1’: 3.2}z = {‘z1’: 2.2}x = m.initialize(u, z) # Initialize first statethreshold_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