Merge branch 'master' into dev

.github/workflows/codeql.yml

@@ -20,6 +20,7 @@ jobs:
   code_ql:
     name: CodeQL Analysis
     runs-on: ubuntu-latest
+
     permissions:
       actions: read
       contents: read
@@ -29,11 +30,7 @@ jobs:
       fail-fast: false
       matrix:
         language: [ 'python' ]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
-        # Use only 'java' to analyze code written in Java, Kotlin or both
-        # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both
-        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
-
+
     steps:
     - name: Checkout repository
       uses: actions/checkout@v3
@@ -47,14 +44,10 @@ jobs:
         # By default, queries listed here will override any specified in a config file.
         # Prefix the list here with "+" to use these queries and those in the config file.
 
-        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-        # queries: security-extended,security-and-quality
-
-
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
+    # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
     # If this step fails, then you should remove it and run the build manually (see below)
-    # - name: Autobuild
-    #   uses: github/codeql-action/autobuild@v2
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun

.github/workflows/coverage.yml

@@ -4,7 +4,7 @@ on:
   push:
   pull_request:
     paths:
-      - prog_models
+      - progpy
 
 jobs:
   coverage:

.github/workflows/greetings.yml

@@ -12,4 +12,4 @@ jobs:
     - uses: actions/first-interaction@v1
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
-        pr-message: "Thank you for your contributions. If you haven't already, please send a signed Contributor License Agreement (CLA) to Christopher Teubert (christopher.a.teubert@nasa.gov). CLAs can be found here: https://github.com/nasa/prog_models/tree/master/forms.  Also, make sure you're familiar with the developer notes and contributing sections of our developers guide, https://nasa.github.io/progpy/dev_guide.html#notes-for-developers"
+        pr-message: "Thank you for your contributions. If you haven't already, please send a signed Contributor License Agreement (CLA) to Christopher Teubert (christopher.a.teubert@nasa.gov). CLAs can be found here: https://github.com/nasa/progpy/tree/master/forms.  Also, make sure you're familiar with the developer notes and contributing sections of our developers guide, https://nasa.github.io/progpy/dev_guide.html#notes-for-developers"

README.md

@@ -31,18 +31,19 @@ Use the following to cite this repository:
 
 ```
 @misc{2023_nasa_progpy,
-    author    = {Christopher Teubert and Matteo Corbetta and Chetan Kulkarni and Katelyn Jarvis and Matthew Daigle},
-    title     = {Prognostics Python Package (ProgPy)},
-    month     = October,
-    year      = 2023,
-    version   = {1.6},
-    url       = {https://github.com/nasa/progpy}
-    }
+  | author    = {Christopher Teubert and Katelyn Jarvis Griffith and Matteo Corbetta and Chetan Kulkarni and Portia Banerjee and Matthew Daigle},
+  | title     = {{ProgPy Python Prognostics Packages}},
+  | month     = Oct,
+  | year      = 2023,
+  | version   = {1.6},
+  | url       = {https://nasa.github.io/progpy}
+  | doi       = {10.5281/ZENODO.8097013}
+  | }
 ```
 
 The corresponding reference should look like this:
 
-C. Teubert, C. Kulkarni, M. Corbetta, K. Jarvis, M. Daigle, ProgPy Prognostics Python Packages, v1.6, October 2023. URL https://nasa.github.io/progpy.
+C. Teubert, K. Jarvis Griffith, M. Corbetta, C. Kulkarni, P. Banerjee, M. Daigle, ProgPy Python Prognostics Packages, v1.6, Oct 2023. URL https://github.com/nasa/progpy.
 
 ## Contributing Organizations
 ProgPy was created by a partnership of multiple organizations, working together to build a set of high-quality prognostic tools for the wider PHM Community. We would like to give a big thank you for the ProgPy community, especially the following contributing organizations:
@@ -53,7 +54,7 @@ ProgPy was created by a partnership of multiple organizations, working together
 * Vanderbilt University
 
 ## Acknowledgements
-The structure and algorithms of this package are strongly inspired by the [MATLAB Prognostics Model Library](https://github.com/nasa/PrognosticsModelLibrary), [MATLAB Prognostics Algorithm Library](https://github.com/nasa/PrognosticsAlgorithmLibrary), and the [MATLAB Prognostics Metrics Library](https://github.com/nasa/PrognosticsMetricsLibrary). We would like to recognize Matthew Daigle and the rest of the team that contributed to the Prognostics Model Library for the contributions their work on the MATLAB library made to the design of prog_models.
+The structure and algorithms of this package are strongly inspired by the [MATLAB Prognostics Model Library](https://github.com/nasa/PrognosticsModelLibrary), [MATLAB Prognostics Algorithm Library](https://github.com/nasa/PrognosticsAlgorithmLibrary), and the [MATLAB Prognostics Metrics Library](https://github.com/nasa/PrognosticsMetricsLibrary). We would like to recognize Matthew Daigle and the rest of the team that contributed to the Prognostics Models, Algorithms, and Metrics Libraries for the contributions their work on the MATLAB library made to the design of progpy.
 
 ## Notices
 Copyright © 2021 United States Government as represented by the Administrator of the National Aeronautics and Space Administration.  All Rights Reserved.

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: b60ead7db2a2a1e95459b22ec2cb783c
+config: e5348f79dd5ab46a199baa607858f4a9
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_downloads/00d36657bdd9c3fc811494e7586f6a86/horizon.py

@@ -0,0 +1,57 @@
+# Copyright © 2021 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.
+
+"""
+This example performs a state estimation and prediction with uncertainty given a Prognostics Model with a specific prediction horizon. This prediction horizon marks the end of the "time of interest" for the prediction. Often this represents the end of a mission or sufficiently in the future where the user is unconcerned with the events
+ 
+Method: An instance of the Thrown Object model in progpy is created, and the prediction process is achieved in three steps:
+    1) State estimation of the current state is performed using a chosen state_estimator, and samples are drawn from this estimate
+    2) Prediction of future states (with uncertainty) and the times at which the event thresholds will be reached, within the prediction horizon. All events outside the horizon come back as None and are ignored in metrics
+
+Results: 
+    i) Predicted future values (inputs, states, outputs, event_states) with uncertainty from prediction
+    ii) Time event is predicted to occur (with uncertainty)
+"""
+
+import numpy as np
+from progpy.models.thrown_object import ThrownObject
+from progpy.predictors import MonteCarlo
+from progpy.uncertain_data import MultivariateNormalDist
+from pprint import pprint
+
+def run_example():
+    # Step 1: Setup model & future loading
+    m = ThrownObject(process_noise=0.5, measurement_noise=0.15)
+    initial_state = m.initialize()
+
+    NUM_SAMPLES = 1000
+    x = MultivariateNormalDist(initial_state.keys(), initial_state.values(), np.diag([x_i*0.01 for x_i in initial_state.values()]))
+
+    # Step 2: Demonstrating Predictor
+    print("\nPerforming Prediction Step...")
+
+    # Step 2a: Setup Predictor
+    mc = MonteCarlo(m)
+
+    # Step 2b: Perform a prediction
+    # THIS IS WHERE WE DIVERGE FROM THE THROWN_OBJECT_EXAMPLE
+    # Here we set a prediction horizon
+    # We're saying we are not interested in any events that occur after this time
+    PREDICTION_HORIZON = 7.7
+    STEP_SIZE = 0.01
+    mc_results = mc.predict(x, n_samples=NUM_SAMPLES,dt=STEP_SIZE, horizon = PREDICTION_HORIZON)
+
+    print("\nPredicted Time of Event:")
+    metrics = mc_results.time_of_event.metrics()
+    pprint(metrics)  # Note this takes some time
+    mc_results.time_of_event.plot_hist(keys = 'impact')
+    mc_results.time_of_event.plot_hist(keys = 'falling')
+
+    print("\nSamples where impact occurs before horizon: {:.2f}%".format(metrics['impact']['number of samples']/NUM_SAMPLES*100))
+
+    # Step 4: Show all plots
+    import matplotlib.pyplot as plt  # For plotting
+    plt.show()
+
+# This allows the module to be executed directly 
+if __name__ == '__main__':
+    run_example()

docs/_downloads/05795c561b0fb31137ef5fd753641074/new_state_estimator_example.py

@@ -6,8 +6,8 @@
 In this example a basic state estimator is constructed by subclassing the StateEstimator class. This StateEstimator is then demonstrated with a ThrownObject model
 """
 
-from prog_algs.state_estimators import StateEstimator
-from prog_algs.uncertain_data import ScalarData
+from progpy.state_estimators import StateEstimator
+from progpy.uncertain_data import ScalarData
 import random
 
 

docs/_downloads/06717c7dc69742382bea70d35e4e63b5/sim_pump.py

@@ -5,7 +5,7 @@
 Example of a centrifugal pump being simulated until threshold is met. 
 """
 
-from prog_models.models import CentrifugalPump
+from progpy.models import CentrifugalPump
 
 def run_example(): 
     # Step 1: Setup Pump
@@ -43,7 +43,7 @@ def future_loading(t, x=None):
     simulated_results = pump.simulate_to_threshold(future_loading, first_output, **config)
 
     # Step 4: Plot Results
-    from prog_models.visualize import plot_timeseries
+    from progpy.visualize import plot_timeseries
     plot_timeseries(simulated_results.times, simulated_results.inputs, options={'compact': False, 'title': 'Inputs',
                                                     'xlabel': 'time', 'ylabel':{lbl: lbl for lbl in pump.inputs}})
     plot_timeseries(simulated_results.times, simulated_results.states, options={'compact': False, 'title': 'States', 'xlabel': 'time', 'ylabel': ''})

docs/_downloads/07264e8f18b6dbc8f0f634b492ebee76/benchmarking.py

@@ -6,7 +6,7 @@
 """
 
 from timeit import timeit
-from prog_models.models import BatteryCircuit
+from progpy.models import BatteryCircuit
 
 def run_example():
     # Step 1: Create a model object

docs/_downloads/07c9eb121dbb5de8d48ddffc704c521d/new_state_estimator_example.py

@@ -0,0 +1,146 @@
+# Copyright © 2021 United States Government as represented by the Administrator of the National Aeronautics and Space Administration.  All Rights Reserved.
+
+"""
+An example illustrating the creation of a new state estimator.
+
+In this example a basic state estimator is constructed by subclassing the StateEstimator class. This StateEstimator is then demonstrated with a ThrownObject model
+"""
+
+from progpy.state_estimators import StateEstimator
+from progpy.uncertain_data import ScalarData
+import random
+
+
+class BlindlyStumbleEstimator(StateEstimator):
+    """
+    A new state estimator. This is not a very effective state estimator, but one that technically works. It blindly stumbles towards the correct state by randomly generating a new state each timestep and selecting the state that's most consistant with the measurements.
+
+    I do not in any universe recommend using this state estimator for anything other then demonstrating a bad state estimator. It's intended as an example of creating a new state estimation algorithm.
+
+    This state estimator was created by copying the state estimator template and filling out each function with the logic for this algorithm
+    """
+    def __init__(self, model, x0, measurement = None):
+        """
+        Initialize the state estimator
+
+        Args:
+            model (PrognosticsModel): Model to be used in state estimation
+            x0 (dict): Initial State
+        """
+        self.m = model
+        self.state = x0
+
+    def estimate(self, t, u, z):
+        """
+        Update the state estimate
+
+        Args:
+            t (Number): Time
+            u (dict): Inputs (load) for time t
+            z (dict): Measured output at time t
+        """
+        # Generate new candidate state
+        x2 = {key : float(value) + 10*(random.random()-0.5) for (key,value) in self.state.items()}
+
+        # Calculate outputs
+        z_est = self.m.output(t, self.state)
+        z_est2 = self.m.output(t, x2)
+
+        # Now score them each by how close they are to the measured z
+        z_est_score = sum([abs(z_est[key] - z[key]) for key in self.m.outputs])
+        z_est2_score = sum([abs(z_est2[key] - z[key]) for key in self.m.outputs])
+
+        # Now choose the closer one
+        if z_est2_score < z_est_score: 
+            self.state = x2
+
+    @property
+    def x(self):
+        """
+        Measured state
+        """
+        return ScalarData(self.state)
+
+# Model used in example
+class ThrownObject():
+    """
+    Model that similates an object thrown into the air without air resistance
+    """
+
+    inputs = [] # no inputs, no way to control
+    states = [
+        'x', # Position (m) 
+        'v'  # Velocity (m/s)
+        ]
+    outputs = [ # Anything we can measure
+        'x' # Position (m)
+    ]
+    events = [
+        'falling', # Event- object is falling
+        'impact' # Event- object has impacted ground
+    ]
+
+    # The Default parameters. Overwritten by passing parameters dictionary into constructor
+    parameters = {
+        'thrower_height': 1.83, # m
+        'throwing_speed': 40, # m/s
+        'g': -9.81, # Acceleration due to gravity in m/s^2
+        'process_noise': 0.0 # amount of noise in each step
+    }
+
+    def initialize(self, u = None, z = None):
+        self.max_x = 0.0
+        return {
+            'x': self.parameters['thrower_height'], # Thrown, so initial altitude is height of thrower
+            'v': self.parameters['throwing_speed'] # Velocity at which the ball is thrown - this guy is an professional baseball pitcher
+            }
+
+    def dx(self, t, x, u = None):
+        # apply_process_noise is used to add process noise to each step
+        return {
+            'x': x['v'],
+            'v': self.parameters['g'] # Acceleration of gravity
+        }
+
+    def output(self, t, x):
+        return {
+            'x': x['x']
+        }
+
+    def event_state(self, t, x): 
+        self.max_x = max(self.max_x, x['x']) # Maximum altitude
+        return {
+            'falling': max(x['v']/self.parameters['throwing_speed'],0), # Throwing speed is max speed
+            'impact': max(x['x']/self.max_x,0) # 1 until falling begins, then it's fraction of height
+        }
+
+def run_example():
+    # This example creates a new state estimator, instead of using the included algorihtms. 
+    # The new state estimator was defined above and can now be used like the UKF or PF
+
+    # First we define the model to be used with the state estimator
+    m = ThrownObject()
+
+    # Lets pretend we have no idea what the state is, we'll provide an estimate of 0
+    x0 = {key : 0 for key in m.states}
+    filt = BlindlyStumbleEstimator(m, x0)
+
+    # Now lets simulate it forward and see what it looks like
+    dt = 0.1
+    x = m.initialize()
+    print('t: {}. State: {} (Ground truth: {})'.format(0, filt.x.mean, x))
+    for i in range(1, int(8.4/dt)):
+        # Update ground truth state
+        x = {key : x[key] + m.dx(i*dt, x)[key] * dt for key in m.states}
+
+        # Run estimation step
+        filt.estimate(i*dt, None, m.output(i*dt, x))
+
+        # Print result
+        print('t: {}. State: {} (Ground truth: {})'.format(i*dt, filt.x.mean, x))
+
+    # The results probably should show that it is estimating the state with a significant delay
+
+# This allows the module to be executed directly 
+if __name__ == '__main__':
+    run_example()