From 65dda10b4149024caf84693c4ba873cdd7018e6e Mon Sep 17 00:00:00 2001 From: Christopher Teubert Date: Wed, 18 Oct 2023 11:38:19 -0700 Subject: [PATCH] Update documentation --- .../api_ref/prog_algs/UncertainData.rst | 28 ---- sphinx-config/api_ref/prog_models.rst | 13 -- .../api_ref/prog_models/DataSets.rst | 15 --- .../api_ref/{prog_algs.rst => progpy.rst} | 6 +- .../CompositeModel.rst | 2 +- .../{prog_models => progpy}/DataModel.rst | 22 +-- sphinx-config/api_ref/progpy/DataSets.rst | 15 +++ .../{prog_models => progpy}/EnsembleModel.rst | 2 +- .../IncludedModels.rst | 40 +++--- .../{prog_models => progpy}/LinearModel.rst | 2 +- .../{prog_models => progpy}/Loading.rst | 12 +- .../{prog_algs => progpy}/Prediction.rst | 4 +- .../{prog_algs => progpy}/Predictor.rst | 12 +- .../PrognosticModel.rst | 2 +- .../{prog_models => progpy}/SimResult.rst | 2 +- .../{prog_algs => progpy}/StateEstimator.rst | 16 +-- .../ToEPredictionProfile.rst | 2 +- .../api_ref/progpy/UncertainData.rst | 28 ++++ .../api_ref/{prog_models => progpy}/Utils.rst | 4 +- sphinx-config/dev_guide.rst | 14 +- sphinx-config/glossary.rst | 22 +-- sphinx-config/guide.rst | 14 +- sphinx-config/index.rst | 13 +- sphinx-config/npr7150.rst | 68 +++------- sphinx-config/prog_algs_guide.rst | 118 ++++++++-------- sphinx-config/prog_models_guide.rst | 126 +++++++++--------- sphinx-config/prog_server_guide.rst | 6 +- sphinx-config/releases.rst | 19 +++ 28 files changed, 305 insertions(+), 322 deletions(-) delete mode 100644 sphinx-config/api_ref/prog_algs/UncertainData.rst delete mode 100644 sphinx-config/api_ref/prog_models.rst delete mode 100644 sphinx-config/api_ref/prog_models/DataSets.rst rename sphinx-config/api_ref/{prog_algs.rst => progpy.rst} (80%) rename sphinx-config/api_ref/{prog_models => progpy}/CompositeModel.rst (57%) rename sphinx-config/api_ref/{prog_models => progpy}/DataModel.rst (81%) create mode 100644 sphinx-config/api_ref/progpy/DataSets.rst rename sphinx-config/api_ref/{prog_models => progpy}/EnsembleModel.rst (57%) rename sphinx-config/api_ref/{prog_models => progpy}/IncludedModels.rst (50%) rename sphinx-config/api_ref/{prog_models => progpy}/LinearModel.rst (80%) rename sphinx-config/api_ref/{prog_models => progpy}/Loading.rst (79%) rename sphinx-config/api_ref/{prog_algs => progpy}/Prediction.rst (88%) rename sphinx-config/api_ref/{prog_algs => progpy}/Predictor.rst (72%) rename sphinx-config/api_ref/{prog_models => progpy}/PrognosticModel.rst (76%) rename sphinx-config/api_ref/{prog_models => progpy}/SimResult.rst (73%) rename sphinx-config/api_ref/{prog_algs => progpy}/StateEstimator.rst (55%) rename sphinx-config/api_ref/{prog_algs => progpy}/ToEPredictionProfile.rst (66%) create mode 100644 sphinx-config/api_ref/progpy/UncertainData.rst rename sphinx-config/api_ref/{prog_models => progpy}/Utils.rst (62%) diff --git a/sphinx-config/api_ref/prog_algs/UncertainData.rst b/sphinx-config/api_ref/prog_algs/UncertainData.rst deleted file mode 100644 index efdcdb0..0000000 --- a/sphinx-config/api_ref/prog_algs/UncertainData.rst +++ /dev/null @@ -1,28 +0,0 @@ -Uncertain Data -======================= - -The `prog_algs.uncertain_data` package includes classes for representing data with uncertainty. All types of UncertainData can be operated on using `the interface <#interface>`__. Inidividual classes for representing uncertain data of different kinds are described below, in `Implemented UncertainData Types <#implemented-uncertaindata-types>`__. - -Interface ------------------------- -.. autoclass:: prog_algs.uncertain_data.UncertainData - :members: - :inherited-members: - -Implemented UncertainData Types --------------------------------- - -.. tabs:: - - .. tab:: Unweighted Samples - - .. autoclass:: prog_algs.uncertain_data.UnweightedSamples - :members: key - - .. tab:: Multivariate Normal Distribution - - .. autoclass:: prog_algs.uncertain_data.MultivariateNormalDist - - .. tab:: Scalar - - .. autoclass:: prog_algs.uncertain_data.ScalarData diff --git a/sphinx-config/api_ref/prog_models.rst b/sphinx-config/api_ref/prog_models.rst deleted file mode 100644 index 9779e6f..0000000 --- a/sphinx-config/api_ref/prog_models.rst +++ /dev/null @@ -1,13 +0,0 @@ -prog_models API Reference -================================== - -.. raw:: html - - - -.. toctree:: - :glob: - - prog_models/* - -.. image:: ../images/prog_models_UML.png diff --git a/sphinx-config/api_ref/prog_models/DataSets.rst b/sphinx-config/api_ref/prog_models/DataSets.rst deleted file mode 100644 index eece37d..0000000 --- a/sphinx-config/api_ref/prog_models/DataSets.rst +++ /dev/null @@ -1,15 +0,0 @@ -Datasets -================================================================ - -The `prog_models` dataset subpackage is used to download labeled prognostics data for use in model building, analysis, or validation. Every dataset comes equipped with a `load_data` function which loads the specified data. Some datasets require a dataset number or id. This indicates the specific data to load from the larger dataset. The format of the data is specific to the dataset downloaded. Details of the specific datasets are summarized below: - -.. note:: To use the dataset feature, you must install the requests package. - -Variable Load Battery Data (nasa_battery) ----------------------------------------------------- -.. autofunction:: prog_models.datasets.nasa_battery.load_data - -CMAPSS Jet Engine Data (nasa_cmapss) ----------------------------------------------------- -.. autofunction:: prog_models.datasets.nasa_cmapss.load_data - \ No newline at end of file diff --git a/sphinx-config/api_ref/prog_algs.rst b/sphinx-config/api_ref/progpy.rst similarity index 80% rename from sphinx-config/api_ref/prog_algs.rst rename to sphinx-config/api_ref/progpy.rst index 6e3c4fc..ea4c6cf 100644 --- a/sphinx-config/api_ref/prog_algs.rst +++ b/sphinx-config/api_ref/progpy.rst @@ -1,4 +1,4 @@ -prog_algs API Reference +ProgPy API Reference ================================== .. raw:: html @@ -8,6 +8,8 @@ prog_algs API Reference .. toctree:: :glob: - prog_algs/* + progpy/* .. image:: ../images/prog_algs_UML.png + +.. image:: ../images/prog_models_UML.png diff --git a/sphinx-config/api_ref/prog_models/CompositeModel.rst b/sphinx-config/api_ref/progpy/CompositeModel.rst similarity index 57% rename from sphinx-config/api_ref/prog_models/CompositeModel.rst rename to sphinx-config/api_ref/progpy/CompositeModel.rst index 7234179..625e199 100644 --- a/sphinx-config/api_ref/prog_models/CompositeModel.rst +++ b/sphinx-config/api_ref/progpy/CompositeModel.rst @@ -1,5 +1,5 @@ CompositeModel ================ -.. autoclass:: prog_models.CompositeModel +.. autoclass:: progpy.CompositeModel :show-inheritance: diff --git a/sphinx-config/api_ref/prog_models/DataModel.rst b/sphinx-config/api_ref/progpy/DataModel.rst similarity index 81% rename from sphinx-config/api_ref/prog_models/DataModel.rst rename to sphinx-config/api_ref/progpy/DataModel.rst index 88170b4..d3a490c 100644 --- a/sphinx-config/api_ref/prog_models/DataModel.rst +++ b/sphinx-config/api_ref/progpy/DataModel.rst @@ -8,9 +8,9 @@ The :py:class:`DataModel` class is the base class for all data-based models. It Examples: -* :download:`examples.lstm_model <../../../../prog_models/examples/lstm_model.py>` -* :download:`examples.full_lstm_model <../../../../prog_models/examples/full_lstm_model.py>` -* :download:`examples.custom_model <../../../../prog_models/examples/custom_model.py>` +* :download:`examples.lstm_model <../../../../progpy/examples/lstm_model.py>` +* :download:`examples.full_lstm_model <../../../../progpy/examples/full_lstm_model.py>` +* :download:`examples.custom_model <../../../../progpy/examples/custom_model.py>` Training DataModels ----------------------- @@ -24,7 +24,7 @@ This is the most common way to construct a :py:class:`DataModel` object, using t .. code-block:: python - >>> from prog_models.models import LSTMStateTransitionModel + >>> from progpy.models import LSTMStateTransitionModel >>> input_data = [run1.inputs, run2.inputs, run3.inputs] >>> output_data = [run1.outputs, run2.outputs, run3.outputs] >>> m = LSTMStateTransitionModel.from_data(input_data, output_data) @@ -37,8 +37,8 @@ Surrogate models are constructed using the :py:func:`DataModel.from_model` Class .. code-block:: python - >>> from prog_models.models import ThrownObject - >>> from prog_models.models import LSTMStateTransitionModel + >>> from progpy.models import ThrownObject + >>> from progpy.models import LSTMStateTransitionModel >>> m = ThrownObject() >>> def future_loading(t, x=None): >>> return m.InputContainer({}) # No input for thrown object @@ -56,7 +56,7 @@ Using Constructor ********************** This method is the least frequently used, and it is very specific to the :py:class:`DataModel` class being constructed. For example: :py:class:`DMDModel` classes are constructed using the DMD Matrix, and :py:class:`LSTMStateTransitionModel` classes are constructed using a trained Keras Model. -See example :download:`examples.custom_model <../../../../prog_models/examples/custom_model.py>` +See example :download:`examples.custom_model <../../../../progpy/examples/custom_model.py>` Included DataModels ------------------------- @@ -64,22 +64,22 @@ The following DataModels are included in the package. A new DataModel can be cre DMDModel ************************** -.. autoclass:: prog_models.data_models.DMDModel +.. autoclass:: progpy.data_models.DMDModel :members: from_data, from_model LSTMStateTransitionModel ************************** -.. autoclass:: prog_models.data_models.LSTMStateTransitionModel +.. autoclass:: progpy.data_models.LSTMStateTransitionModel :members: from_data, from_model PolynomialChaosExpansion ************************** -.. autoclass:: prog_models.data_models.PolynomialChaosExpansion +.. autoclass:: progpy.data_models.PolynomialChaosExpansion :members: from_data, from_model DataModel Interface --------------------------- -.. autoclass:: prog_models.data_models.DataModel +.. autoclass:: progpy.data_models.DataModel :members: :show-inheritance: :inherited-members: diff --git a/sphinx-config/api_ref/progpy/DataSets.rst b/sphinx-config/api_ref/progpy/DataSets.rst new file mode 100644 index 0000000..2bb9edb --- /dev/null +++ b/sphinx-config/api_ref/progpy/DataSets.rst @@ -0,0 +1,15 @@ +Datasets +================================================================ + +The `progpy` dataset subpackage is used to download labeled prognostics data for use in model building, analysis, or validation. Every dataset comes equipped with a `load_data` function which loads the specified data. Some datasets require a dataset number or id. This indicates the specific data to load from the larger dataset. The format of the data is specific to the dataset downloaded. Details of the specific datasets are summarized below: + +.. note:: To use the dataset feature, you must install the requests package. + +Variable Load Battery Data (nasa_battery) +---------------------------------------------------- +.. autofunction:: progpy.datasets.nasa_battery.load_data + +CMAPSS Jet Engine Data (nasa_cmapss) +---------------------------------------------------- +.. autofunction:: progpy.datasets.nasa_cmapss.load_data + \ No newline at end of file diff --git a/sphinx-config/api_ref/prog_models/EnsembleModel.rst b/sphinx-config/api_ref/progpy/EnsembleModel.rst similarity index 57% rename from sphinx-config/api_ref/prog_models/EnsembleModel.rst rename to sphinx-config/api_ref/progpy/EnsembleModel.rst index e4c54ea..20a0268 100644 --- a/sphinx-config/api_ref/prog_models/EnsembleModel.rst +++ b/sphinx-config/api_ref/progpy/EnsembleModel.rst @@ -1,5 +1,5 @@ EnsembleModel ================ -.. autoclass:: prog_models.EnsembleModel +.. autoclass:: progpy.EnsembleModel :show-inheritance: diff --git a/sphinx-config/api_ref/prog_models/IncludedModels.rst b/sphinx-config/api_ref/progpy/IncludedModels.rst similarity index 50% rename from sphinx-config/api_ref/prog_models/IncludedModels.rst rename to sphinx-config/api_ref/progpy/IncludedModels.rst index 2f97e75..2d43049 100644 --- a/sphinx-config/api_ref/prog_models/IncludedModels.rst +++ b/sphinx-config/api_ref/progpy/IncludedModels.rst @@ -1,6 +1,6 @@ Included Models =================== -The :ref:`prog_models` package is distributed with a few pre-constructed models that can be used in simulation or prognostics (with the :ref:`prog_algs ` package). These models are summarized in the following sections. +The progpy package is distributed with a few pre-constructed models that can be used in simulation or prognostics. These models are summarized in the following sections. .. .. contents:: .. :backlinks: top @@ -12,21 +12,21 @@ Battery Model .. tab:: ElectroChem (EOD) - .. autoclass:: prog_models.models.BatteryElectroChemEOD + .. autoclass:: progpy.models.BatteryElectroChemEOD .. tab:: ElectroChem (EOL) - .. autoclass:: prog_models.models.BatteryElectroChemEOL + .. autoclass:: progpy.models.BatteryElectroChemEOL .. tab:: ElectroChem (Combo) - .. autoclass:: prog_models.models.BatteryElectroChem + .. autoclass:: progpy.models.BatteryElectroChem - .. autoclass:: prog_models.models.BatteryElectroChemEODEOL + .. autoclass:: progpy.models.BatteryElectroChemEODEOL .. tab:: Circuit - .. autoclass:: prog_models.models.BatteryCircuit + .. autoclass:: progpy.models.BatteryCircuit Pump Model @@ -38,13 +38,13 @@ There are two variants of the pump model based on if the wear parameters are est .. tab:: Base Model - .. autoclass:: prog_models.models.CentrifugalPumpBase + .. autoclass:: progpy.models.CentrifugalPumpBase .. tab:: With Wear As State - .. autoclass:: prog_models.models.CentrifugalPump + .. autoclass:: progpy.models.CentrifugalPump - .. autoclass:: prog_models.models.CentrifugalPumpWithWear + .. autoclass:: progpy.models.CentrifugalPumpWithWear Pneumatic Valve ------------------------------------------------------------- @@ -55,13 +55,13 @@ There are two variants of the valve model based on if the wear parameters are es .. tab:: Base Model - .. autoclass:: prog_models.models.PneumaticValveBase + .. autoclass:: progpy.models.PneumaticValveBase .. tab:: With Wear As State - .. autoclass:: prog_models.models.PneumaticValve + .. autoclass:: progpy.models.PneumaticValve - .. autoclass:: prog_models.models.PneumaticValveWithWear + .. autoclass:: progpy.models.PneumaticValveWithWear DC Motor ------------------------------------------------------------- @@ -70,30 +70,30 @@ DC Motor .. tab:: Single Phase - .. autoclass:: prog_models.models.DCMotorSP + .. autoclass:: progpy.models.DCMotorSP .. tab:: Triple Phase - .. autoclass:: prog_models.models.DCMotor + .. autoclass:: progpy.models.DCMotor ESC ------------------------------------------------------------- -.. autoclass:: prog_models.models.ESC +.. autoclass:: progpy.models.ESC Powertrain ------------------------------------------------------------- -.. autoclass:: prog_models.models.Powertrain +.. autoclass:: progpy.models.Powertrain PropellerLoad ------------------------------------------------------------- -.. autoclass:: prog_models.models.PropellerLoad +.. autoclass:: progpy.models.PropellerLoad Aircraft Models ------------------------------------------------------------- -Aircraft model simulate the flight of an aircraft. All aircraft models inherit from :py:class:`prog_models.models.aircraft_model.AricraftModel`. Included models are listed below: +Aircraft model simulate the flight of an aircraft. All aircraft models inherit from :py:class:`progpy.models.aircraft_model.AricraftModel`. Included models are listed below: -.. autoclass:: prog_models.models.aircraft_model.SmallRotorcraft +.. autoclass:: progpy.models.aircraft_model.SmallRotorcraft ThrownObject ------------------------------------------------------------- -.. autoclass:: prog_models.models.ThrownObject +.. autoclass:: progpy.models.ThrownObject diff --git a/sphinx-config/api_ref/prog_models/LinearModel.rst b/sphinx-config/api_ref/progpy/LinearModel.rst similarity index 80% rename from sphinx-config/api_ref/prog_models/LinearModel.rst rename to sphinx-config/api_ref/progpy/LinearModel.rst index f29b0cb..dffa2bc 100644 --- a/sphinx-config/api_ref/prog_models/LinearModel.rst +++ b/sphinx-config/api_ref/progpy/LinearModel.rst @@ -1,7 +1,7 @@ LinearModel ================= -.. autoclass:: prog_models.LinearModel +.. autoclass:: progpy.LinearModel :members: :inherited-members: :exclude-members: SimulationResults, generate_model, observables diff --git a/sphinx-config/api_ref/prog_models/Loading.rst b/sphinx-config/api_ref/progpy/Loading.rst similarity index 79% rename from sphinx-config/api_ref/prog_models/Loading.rst rename to sphinx-config/api_ref/progpy/Loading.rst index cced4b3..e6731ad 100644 --- a/sphinx-config/api_ref/prog_models/Loading.rst +++ b/sphinx-config/api_ref/progpy/Loading.rst @@ -1,7 +1,7 @@ Loading ========= -The loading subpackage includes some classes for complex load estimation algorithms. See :download:`examples.future_loading <../../../../prog_models/examples/future_loading.py>` for more details. +The loading subpackage includes some classes for complex load estimation algorithms. See :download:`examples.future_loading <../../../../progpy/examples/future_loading.py>` for more details. Load Estimator Class interface ------------------------------ @@ -32,15 +32,15 @@ The second approach for load estimators is a load estimation class. This is used Load Estimator Classes ---------------------- -.. autoclass:: prog_models.loading.Piecewise +.. autoclass:: progpy.loading.Piecewise -.. autoclass:: prog_models.loading.MovingAverage +.. autoclass:: progpy.loading.MovingAverage -.. autoclass:: prog_models.loading.GaussianNoiseLoadWrapper +.. autoclass:: progpy.loading.GaussianNoiseLoadWrapper Controllers ------------------ -.. autoclass:: prog_models.loading.controllers.LQR +.. autoclass:: progpy.loading.controllers.LQR -.. autoclass:: prog_models.loading.controllers.LQR_I +.. autoclass:: progpy.loading.controllers.LQR_I diff --git a/sphinx-config/api_ref/prog_algs/Prediction.rst b/sphinx-config/api_ref/progpy/Prediction.rst similarity index 88% rename from sphinx-config/api_ref/prog_algs/Prediction.rst rename to sphinx-config/api_ref/progpy/Prediction.rst index 5832786..b3eba37 100644 --- a/sphinx-config/api_ref/prog_algs/Prediction.rst +++ b/sphinx-config/api_ref/progpy/Prediction.rst @@ -8,13 +8,13 @@ Two types of predictions are distributed with this package: `Prediction` and `Un .. tabs:: .. tab:: Prediction - .. autoclass:: prog_algs.predictors.Prediction + .. autoclass:: progpy.predictors.Prediction :members: :inherited-members: .. tab:: UnweightedSamplesPrediction - .. autoclass:: prog_algs.predictors.UnweightedSamplesPrediction + .. autoclass:: progpy.predictors.UnweightedSamplesPrediction :members: :inherited-members: :exclude-members: append, extend, clear, pop, remove, reverse, insert diff --git a/sphinx-config/api_ref/prog_algs/Predictor.rst b/sphinx-config/api_ref/progpy/Predictor.rst similarity index 72% rename from sphinx-config/api_ref/prog_algs/Predictor.rst rename to sphinx-config/api_ref/progpy/Predictor.rst index 62c927e..9ca5119 100644 --- a/sphinx-config/api_ref/prog_algs/Predictor.rst +++ b/sphinx-config/api_ref/progpy/Predictor.rst @@ -1,15 +1,15 @@ Predictors =========================== -The :py:class:`Predictor` uses a state estimate (type :py:class:`UncertainData` subclass, output of a :py:class:`StateEstimator`), information about expected future loading, and a :py:class:`PrognosticsModel` (see: `prog_models package `__) to predict both future states (also outputs, performance metrics, event_states) at predefined points and the time that an event will occur (Time of Event, ToE) with uncertainty. +The :py:class:`Predictor` uses a state estimate (type :py:class:`UncertainData` subclass, output of a :py:class:`StateEstimator`), information about expected future loading, and a :py:class:`PrognosticsModel` to predict both future states (also outputs, performance metrics, event_states) at predefined points and the time that an event will occur (Time of Event, ToE) with uncertainty. Here's an example of its use. In this example we use the :py:class:`ThrownObject` model and the :py:class:`MonteCarlo` predictor, and we save the state every 1s. We also use a scalar first state (i.e., no uncertainty). .. code-block:: python >>> from prog_models.models import ThrownObject - >>> from prog_algs.predictors import MonteCarlo - >>> from prog_algs.uncertain_data import ScalarData + >>> from progpy.predictors import MonteCarlo + >>> from progpy.uncertain_data import ScalarData >>> >>> m = ThrownObject() >>> pred = MonteCarlo(m) @@ -30,14 +30,14 @@ The following predictors are included with this package. A new predictor can be .. tab:: Monte Carlo Predictor - .. autoclass:: prog_algs.predictors.MonteCarlo + .. autoclass:: progpy.predictors.MonteCarlo .. tab:: Unscented Transform Predictor - .. autoclass:: prog_algs.predictors.UnscentedTransformPredictor + .. autoclass:: progpy.predictors.UnscentedTransformPredictor Predictor Interface ----------------------- -.. autoclass:: prog_algs.predictors.Predictor +.. autoclass:: progpy.predictors.Predictor :members: :inherited-members: diff --git a/sphinx-config/api_ref/prog_models/PrognosticModel.rst b/sphinx-config/api_ref/progpy/PrognosticModel.rst similarity index 76% rename from sphinx-config/api_ref/prog_models/PrognosticModel.rst rename to sphinx-config/api_ref/progpy/PrognosticModel.rst index 9602cc1..7565e4f 100644 --- a/sphinx-config/api_ref/prog_models/PrognosticModel.rst +++ b/sphinx-config/api_ref/progpy/PrognosticModel.rst @@ -1,7 +1,7 @@ PrognosticsModel ==================== -.. autoclass:: prog_models.PrognosticsModel +.. autoclass:: progpy.PrognosticsModel :members: :inherited-members: :exclude-members: SimulationResults, generate_model, observables diff --git a/sphinx-config/api_ref/prog_models/SimResult.rst b/sphinx-config/api_ref/progpy/SimResult.rst similarity index 73% rename from sphinx-config/api_ref/prog_models/SimResult.rst rename to sphinx-config/api_ref/progpy/SimResult.rst index 496f991..fee59c9 100644 --- a/sphinx-config/api_ref/prog_models/SimResult.rst +++ b/sphinx-config/api_ref/progpy/SimResult.rst @@ -1,7 +1,7 @@ SimResult ================================ -.. autoclass:: prog_models.sim_result.SimResult +.. autoclass:: progpy.sim_result.SimResult :members: :inherited-members: :exclude-members: append, reverse, count, insert diff --git a/sphinx-config/api_ref/prog_algs/StateEstimator.rst b/sphinx-config/api_ref/progpy/StateEstimator.rst similarity index 55% rename from sphinx-config/api_ref/prog_algs/StateEstimator.rst rename to sphinx-config/api_ref/progpy/StateEstimator.rst index b9a008b..16f6062 100644 --- a/sphinx-config/api_ref/prog_algs/StateEstimator.rst +++ b/sphinx-config/api_ref/progpy/StateEstimator.rst @@ -1,13 +1,13 @@ State Estimators =========================== -The State Estimator uses sensor information and a Prognostics Model (see: `prog_models package `__) to produce an estimate of system state (which can be used to estimate outputs, event_states, and performance metrics). This state estimate can either be used by itself or as input to a `Predictor `__. A state estimator is typically run each time new information is available. +The State Estimator uses sensor information and a Prognostics Model to produce an estimate of system state (which can be used to estimate outputs, event_states, and performance metrics). This state estimate can either be used by itself or as input to a `Predictor `__. A state estimator is typically run each time new information is available. Here's an example of its use. In this example we use the unscented kalman filter state estimator and the ThrownObject model. .. code-block:: python >>> from prog_models.models import ThrownObject - >>> from prog_algs.state_estimators import UnscentedKalmanFilter + >>> from progpy.state_estimators import UnscentedKalmanFilter >>> >>> m = ThrownObject() >>> initial_state = m.initialize() @@ -23,24 +23,24 @@ See tutorial and examples for more information and additional features. Included State Estimators ------------------------- -The following state estimators are included with this package. A new state estimator can be created by subclassing `prog_algs.state_estimators.StateEstimator`. See also: `state_estimator_template.py` +The following state estimators are included with this package. A new state estimator can be created by subclassing `progpy.state_estimators.StateEstimator`. See also: `state_estimator_template.py` -.. tabs:: prog_algs +.. tabs:: progpy .. tab:: Particle Filter - .. autoclass:: prog_algs.state_estimators.ParticleFilter + .. autoclass:: progpy.state_estimators.ParticleFilter .. tab:: Unscented Kalman Filter - .. autoclass:: prog_algs.state_estimators.UnscentedKalmanFilter + .. autoclass:: progpy.state_estimators.UnscentedKalmanFilter .. tab:: Kalman Filter - .. autoclass:: prog_algs.state_estimators.KalmanFilter + .. autoclass:: progpy.state_estimators.KalmanFilter State Estimator Interface ------------------------- -.. autoclass:: prog_algs.state_estimators.StateEstimator +.. autoclass:: progpy.state_estimators.StateEstimator :members: :inherited-members: diff --git a/sphinx-config/api_ref/prog_algs/ToEPredictionProfile.rst b/sphinx-config/api_ref/progpy/ToEPredictionProfile.rst similarity index 66% rename from sphinx-config/api_ref/prog_algs/ToEPredictionProfile.rst rename to sphinx-config/api_ref/progpy/ToEPredictionProfile.rst index a917250..6fd141f 100644 --- a/sphinx-config/api_ref/prog_algs/ToEPredictionProfile.rst +++ b/sphinx-config/api_ref/progpy/ToEPredictionProfile.rst @@ -1,6 +1,6 @@ ToEPredictionProfile ---------------------- -.. autoclass:: prog_algs.predictors.ToEPredictionProfile +.. autoclass:: progpy.predictors.ToEPredictionProfile :members: :inherited-members: :exclude-members: setdefault diff --git a/sphinx-config/api_ref/progpy/UncertainData.rst b/sphinx-config/api_ref/progpy/UncertainData.rst new file mode 100644 index 0000000..863cd13 --- /dev/null +++ b/sphinx-config/api_ref/progpy/UncertainData.rst @@ -0,0 +1,28 @@ +Uncertain Data +======================= + +The `progpy.uncertain_data` package includes classes for representing data with uncertainty. All types of UncertainData can be operated on using `the interface <#interface>`__. Inidividual classes for representing uncertain data of different kinds are described below, in `Implemented UncertainData Types <#implemented-uncertaindata-types>`__. + +Interface +------------------------ +.. autoclass:: progpy.uncertain_data.UncertainData + :members: + :inherited-members: + +Implemented UncertainData Types +-------------------------------- + +.. tabs:: + + .. tab:: Unweighted Samples + + .. autoclass:: progpy.uncertain_data.UnweightedSamples + :members: key + + .. tab:: Multivariate Normal Distribution + + .. autoclass:: progpy.uncertain_data.MultivariateNormalDist + + .. tab:: Scalar + + .. autoclass:: progpy.uncertain_data.ScalarData diff --git a/sphinx-config/api_ref/prog_models/Utils.rst b/sphinx-config/api_ref/progpy/Utils.rst similarity index 62% rename from sphinx-config/api_ref/prog_models/Utils.rst rename to sphinx-config/api_ref/progpy/Utils.rst index 83152f5..ca7757d 100644 --- a/sphinx-config/api_ref/prog_models/Utils.rst +++ b/sphinx-config/api_ref/progpy/Utils.rst @@ -1,12 +1,12 @@ Utils ================================================================ -There are a number of support functions and classes included in prog_models.utils. These utilities are used throughout the package, but are also available for use in your own code. +There are a number of support functions and classes included in progpy.utils. These utilities are used throughout the package, but are also available for use in your own code. .. .. contents:: .. :backlinks: top Trajectory ---------------------------------------------------------------- -.. autoclass:: prog_models.utils.traj_gen.Trajectory +.. autoclass:: progpy.utils.traj_gen.Trajectory :members: ref_traj, generate diff --git a/sphinx-config/dev_guide.rst b/sphinx-config/dev_guide.rst index b708536..2ade525 100644 --- a/sphinx-config/dev_guide.rst +++ b/sphinx-config/dev_guide.rst @@ -8,7 +8,7 @@ Developers Guide & Project Plan npr7150 -This document includes some details relevant for developers working on any of the Python Prognostics Packages Tools (prog_models, prog_algs, prog_server) +This document includes some details relevant for developers working on any of the Python Prognostics Packages Tools (progpy, prog_server) Installing from a Branch ------------------------ @@ -29,9 +29,9 @@ Then run the tests using the following command: Contributing --------------- -New external (non-NASA or NASA contractor) developers must complete either the `organizational or individual Contributor License Agreement (CLA) `__. +New external (non-NASA or NASA contractor) developers must complete either the `organizational or individual Contributor License Agreement (CLA) `__. -Curious about what needs to be done? Have an idea for a new feature? Find a bug? Check out open issues `prog_models `__, `prog_algs `__, `prog_server `__. +Curious about what needs to be done? Have an idea for a new feature? Find a bug? Check out open issues `progpy `__, `prog_server `__. Project Roles -------------------- @@ -39,7 +39,7 @@ Project Roles * Software Assurance Officer: Christopher Teubert * Deputy Software Lead: Katelyn Jarvis * Software Management Team: Software Lead, Software Assurance Officer, and Deputy Software Lead -* Developers: See `prog_models developers `__, `prog_algs developers `__, `prog_server developers `_ +* Developers: See `progpy developers `__, `prog_server developers `_ Branching Strategy ------------------ @@ -170,7 +170,7 @@ Notes for Developers * Each new feature should have a test. Check this in each PR review. * Check test coverage to improve completeness, automatically reported by bot in each PR. * For tests- make sure test are quality. They should cover expected input ranges, error handling. - * There are some example models in prog_models.models.test_models which are useful for testing + * There are some example models in progpy.models.test_models which are useful for testing * Documentation * Documentation is autogenerated using sphinx from progpy repository * Configuration is in sphinx_config. @@ -180,7 +180,7 @@ Notes for Developers * Automated tests are defined in the .github/ directory. * The repository administrator can add tests to the set required to pass for each PR must be done by . * Template - * An empty template of a prognostics model is maintained at `prog_models/prog_model_template.py`. - * An empty template of a state estimator and predictor is maintained at `prog_algs/state_estimator_template.py` and `prog_algs/predictor_template.py`. + * An empty template of a prognostics model is maintained at `progpy/prog_model_template.py`. + * An empty template of a state estimator and predictor is maintained at `progpy/state_estimator_template.py` and `progpy/predictor_template.py`. * Any changes to the basic model setup should be documented there. * A tutorial is included in tutorial.ipynb. This required Juypter Notebooks. All major features should be illustrated here. diff --git a/sphinx-config/glossary.rst b/sphinx-config/glossary.rst index e691692..ec8d4f9 100644 --- a/sphinx-config/glossary.rst +++ b/sphinx-config/glossary.rst @@ -5,7 +5,7 @@ Glossary :sorted: controller - A closed loop future loading method. Calculates future loading as a function of state, like the :py:class:`prog_models.loading.controllers.LQR` controller used by the :py:class:`prog_models.models.aircraft_model.SmallRotorcraft` model. + A closed loop future loading method. Calculates future loading as a function of state, like the :py:class:`progpy.loading.controllers.LQR` controller used by the :py:class:`progpy.models.aircraft_model.SmallRotorcraft` model. trajectory Path a vehicle takes through space, represented by a set of 4-dimensional points (position + time), represented by the `prog_modals.utils.traj_gen.Trajectory` class. @@ -35,19 +35,19 @@ Glossary :term:`state` that is not directly measurable state estimator - An algorithm that is used to estimate the :term:`state` of the system, given measurements and a model, defined in the :py:mod:`prog_algs.state_estimators` subpackage (e.g., :py:class:`prog_algs.state_estimators.UnscentedKalmanFilter`). + An algorithm that is used to estimate the :term:`state` of the system, given measurements and a model, defined in the :py:mod:`progpy.state_estimators` subpackage (e.g., :py:class:`progpy.state_estimators.UnscentedKalmanFilter`). predictor - An algorithm that is used to predict future states, given the initial state, a model, and an estimate of :term:`future load`. E.g., :py:class:`prog_algs.predictors.MonteCarlo`. + An algorithm that is used to predict future states, given the initial state, a model, and an estimate of :term:`future load`. E.g., :py:class:`progpy.predictors.MonteCarlo`. prediction - A prediction of something (e.g., :term:`input`, :term:`state`, :term:`output`, :term:`event state`, etc.), with uncertainty, at one or more future times, as a result of a :term:`predictor` prediction step (:py:func:`prog_algs.predictors.Predictor.predict`). For example- a prediction of the future :term:`state` of a system at certain specified savepoints, returned from prediction using a :py:class:`prog_algs.predictors.MonteCarlo` predictor. + A prediction of something (e.g., :term:`input`, :term:`state`, :term:`output`, :term:`event state`, etc.), with uncertainty, at one or more future times, as a result of a :term:`predictor` prediction step (:py:func:`progpy.predictors.Predictor.predict`). For example- a prediction of the future :term:`state` of a system at certain specified savepoints, returned from prediction using a :py:class:`progpy.predictors.MonteCarlo` predictor. surrogate - A model that approximates the behavior of another model. Often used to generate a faster version of a model (e.g., for resource-constrained applications or to be used in optimization) or to test a data model. Generated using :py:func:`prog_models.PrognosticsModel.generate_surrogate` method. + A model that approximates the behavior of another model. Often used to generate a faster version of a model (e.g., for resource-constrained applications or to be used in optimization) or to test a data model. Generated using :py:func:`progpy.PrognosticsModel.generate_surrogate` method. model - A subclass of :py:class:`prog_models.PrognosticsModel` the describes the behavior of a system. Models are typically physics-based, data-driven (i.e., subclasses of :py:class:`prog_models.data_models.DataModel`), or some hybrid approach (e.g., physics informed machine learning). + A subclass of :py:class:`progpy.PrognosticsModel` the describes the behavior of a system. Models are typically physics-based, data-driven (i.e., subclasses of :py:class:`progpy.data_models.DataModel`), or some hybrid approach (e.g., physics informed machine learning). threshold The conditions under which an :term:`event` is considered to have occurred. @@ -56,7 +56,7 @@ Glossary Prediction of (a) future performance and/or (b) the time at which one or more events of interest occur, for a system or a system of systems data-driven model - A model where the behavior is learned from data. In ProgPy, data-driven models derive from the parent class :py:class:`prog_models.data_models.DataModel`. A common example of data-driven models is models using neural networks (e.g., :py:class:`prog_models.data_models.LSTMStateTransitionModel`). + A model where the behavior is learned from data. In ProgPy, data-driven models derive from the parent class :py:class:`progpy.data_models.DataModel`. A common example of data-driven models is models using neural networks (e.g., :py:class:`progpy.data_models.LSTMStateTransitionModel`). physics-based model A model where behavior is described by the physics of the system. Physics-based models are typically :term:`parameterized`, so that exact behavior of the system can be configured or learned (through parameter estimation). @@ -74,7 +74,7 @@ Glossary Noise applied in the user provided :term:`future load` function. This is used to represent uncertainty in how the system is loaded in the future. state estimation - State estimation is the process from which the internal model :term:`state` (x) is estimated using :term:`input` (i.e., loading) and :term:`output` (i.e., sensor data). State estimation is necessary for cases where model state isn't directly measurable (i.e., `hidden state`) or where there is sensor noise. Most state estimators estimate the state with some representation of uncertainty. An algorithm that performs state estimation is called a :term:`state estimator` and is included in the prog_algs.state_estimators package + State estimation is the process from which the internal model :term:`state` (x) is estimated using :term:`input` (i.e., loading) and :term:`output` (i.e., sensor data). State estimation is necessary for cases where model state isn't directly measurable (i.e., `hidden state`) or where there is sensor noise. Most state estimators estimate the state with some representation of uncertainty. An algorithm that performs state estimation is called a :term:`state estimator` and is included in the progpy.state_estimators package time of event The time at which an :term:`event` is predicted to occur (i.e., when :term:`threshold` is reached). Sometimes abbreviated as ToE. When the event of interest is failure, this is frequently referred to as End of Life (EOL). @@ -89,13 +89,13 @@ Glossary The time at which the last measurement was performed that was used for state estimation. Sometimes abbreviated as ToM or :math:`t_m`. direct-prediction model - A model where the :term:`time of event` is directly estimated from the current state and/or :term:`future load`, instead of predicted through simulation to threshold. These are implemented using the :py:meth:`prog_models.PrognosticsModel.time_to_event` method. + A model where the :term:`time of event` is directly estimated from the current state and/or :term:`future load`, instead of predicted through simulation to threshold. These are implemented using the :py:meth:`progpy.PrognosticsModel.time_to_event` method. state-transition model A model where the :term:`time of event` is predicted through simulation to threshold. Most prognostic models are state-transition models. composite model - A model consisting of multiple inter-related Prognostics Models, where the :term:`input` of one :term:`model` is a function of the :term:`output` or :term:`state` of another. This is a tool for representing system-of-systems. Composite models are implemented using the :py:class:`prog_models.CompositeModel` class. + A model consisting of multiple inter-related Prognostics Models, where the :term:`input` of one :term:`model` is a function of the :term:`output` or :term:`state` of another. This is a tool for representing system-of-systems. Composite models are implemented using the :py:class:`progpy.CompositeModel` class. system-of-systems - A system consisting of multiple inter-related systems, where one system affects the others. In ProgPy, system-of-systems are reporsented using :term:`composite models `. Composite models are implemented using the :py:class:`prog_models.CompositeModel` class. + A system consisting of multiple inter-related systems, where one system affects the others. In ProgPy, system-of-systems are reporsented using :term:`composite models `. Composite models are implemented using the :py:class:`progpy.CompositeModel` class. diff --git a/sphinx-config/guide.rst b/sphinx-config/guide.rst index 895078e..74e8464 100644 --- a/sphinx-config/guide.rst +++ b/sphinx-config/guide.rst @@ -10,7 +10,7 @@ ProgPy Guide prog_algs_guide prog_server_guide -This page is a general guide for ProgPy. ProgPy consists of three packages: prog_models, prog_algs, prog_server. To access a guide specific to the package you're using, select it in the menu below. +This page is a general guide for ProgPy. To access a guide specific to the features you're using, select it in the menu below. .. panels:: :img-top-cls: pt-2, pb-2 @@ -23,7 +23,7 @@ This page is a general guide for ProgPy. ProgPy consists of three packages: prog .. link-button:: prog_models Guide :type: ref - :text: prog_models + :text: Modeling and Simulation :classes: stretched-link btn-outline-primary btn-block --- @@ -31,7 +31,7 @@ This page is a general guide for ProgPy. ProgPy consists of three packages: prog .. link-button:: prog_algs Guide :type: ref - :text: prog_algs + :text: State Estimation and Prediction :classes: stretched-link btn-outline-primary btn-block --- @@ -59,13 +59,13 @@ In general, the ProgPy prognostic approach is illustrated below. The foundation of prognostics is a :term:`model`. Models describe the behavior of a system or system of systems. A prognostics model specifically describes how the state of the system evolves with time. Prognostic models typically come in one of 4 categories: knowledge-based, :term:`physics-based`, :term:`data-driven`, or some combination of those three (i.e., hybrid). -Functionality for creation, simulation, and analysis of models can be found in the :ref:`prog_models` package. That package also includes some example models and tools to access relevant data for model creation. For more information see the :ref:`prog_models Guide`. +Details on functionality for creation, simulation, and analysis of models can be found in the :ref:`Modeling and Simulation Guide ` package. That package also includes some example models and tools to access relevant data for model creation. ProgPy divides the prognostic process into two steps: :term:`state estimation` and :term:`prediction`. State estimation is the process of determining the current system state (x), with some uncertainty, given the system parameters (:math:`\Theta`), system loading (u) and measurements (z). There are various methods used for this, such as Kalman Filters and Particle Filters. These methods utilize a prognostics model, comparing measurements (z) with those predicted from the system output equation. In the prediction step, the state estimate at the prediction time and system model are used together to estimate system degradation with time. This is most commonly done using a variant of the Monte Carlo method with the model state transition equation. Prediction is often computationally expensive, especially for sample-based approaches with strict precision requirements (which therefore require large number of samples). ProgPy provides some potential solutions to combat this, such as :term:`surrogate` models, vectorization, and model configuration options. -Algorithms for :term:`state estimation` and :term:`prediction` along with tools analyzing and visualizing results of state estimation and prediction, managing uncertainty, and creating new state estimators or predictors can be found in the :ref:`prog_algs` package. For more information see the :ref:`prog_algs Guide`. +Algorithms for :term:`state estimation` and :term:`prediction` along with tools analyzing and visualizing results of state estimation and prediction, managing uncertainty, and creating new state estimators or predictors, see the :ref:`State Estimation and Prediction Guide`. More information ------------------------------ @@ -81,7 +81,7 @@ For more information, see the inidividual pages for each of the three ProgPy Pac --- :img-top: images/cube.png - .. link-button:: prog_models Guide + .. link-button:: Modeling and Simulation Guide :type: ref :text: prog_models :classes: stretched-link btn-outline-primary btn-block @@ -89,7 +89,7 @@ For more information, see the inidividual pages for each of the three ProgPy Pac --- :img-top: images/Gear-icon.png - .. link-button:: prog_algs Guide + .. link-button:: State Estimation and Prediction :type: ref :text: prog_algs :classes: stretched-link btn-outline-primary btn-block diff --git a/sphinx-config/index.rst b/sphinx-config/index.rst index 4a3bed4..1e4d2c1 100644 --- a/sphinx-config/index.rst +++ b/sphinx-config/index.rst @@ -8,10 +8,9 @@ ProgPy Prognostics Python Packages NASA's ProgPy is an open-sourced python packages supporting research and development of prognostics and health management and predictive maintenance tools. It implements architectures and common functionality of prognostics, supporting researchers and practitioners. The ProgPy package is a combination of the original prog_models and prog_algs packages. -ProgPy consists of a set of packages, described below. See the documentation specific to each package for more information. - -* :ref:`prog_models` : Tools for defining, building, using, and testing models for prognostics -* :ref:`prog_algs` : Tools for performing and benchmarking prognostics and state estimation +ProgPy documentation is split into three senctions described below. +* :ref:`Modeling and Simulation` : Tools for defining, building, using, and testing models for prognostics +* :ref:`State Estimation and Prediction` : Tools for performing and benchmarking prognostics and state estimation * :ref:`prog_server` and :ref:`prog_client` : A simplified implementation of a Service-Oriented Architecture (SOA) for performing prognostics and associated client .. toctree:: @@ -33,15 +32,15 @@ Use the following to cite this repository: @misc{2022_nasa_progpy, | author = {Christopher Teubert and Katelyn Jarvis and Matteo Corbetta and Chetan Kulkarni and Matthew Daigle}, | title = {{ProgPy Python Prognostics Packages}}, - | month = May, + | month = Oct, | year = 2023, - | version = {1.5}, + | version = {1.6}, | url = {https://nasa.github.io/progpy} | } The corresponding reference should look like this: -C. Teubert, K. Jarvis, M. Corbetta, C. Kulkarni, M. Daigle, ProgPy Python Prognostics Packages, v1.5, May 2022. URL https://github.com/nasa/progpy. +C. Teubert, K. Jarvis, M. Corbetta, C. Kulkarni, M. Daigle, ProgPy Python Prognostics Packages, v1.6, Oct 2023. URL https://github.com/nasa/progpy. Contributing and Partnering ----------------------------- diff --git a/sphinx-config/npr7150.rst b/sphinx-config/npr7150.rst index 69b1472..3d2779b 100644 --- a/sphinx-config/npr7150.rst +++ b/sphinx-config/npr7150.rst @@ -64,9 +64,7 @@ Life Cycle Management +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 036 | Software Processes | FC | See notes below | +-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 037M | Document Milestones | FC | `Milestones `__ | -+-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 037A | Document Milestones | FC | `Milestones `__ | +| 037M | Document Milestones | FC | `Milestones `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 037S | Document Milestones | FC | `Milestones `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ @@ -80,9 +78,7 @@ Life Cycle Management +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 039e | Software Reviews | FC | Software Assurance Officer gives final approval after reviews | +-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 040aM | Products | FC | Kept in `Repo `__ | -+-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 040aA | Products | FC | Kept in `Repo `__ | +| 040aM | Products | FC | Kept in `Repo `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 040aS | Products | FC | Kept in `Repo `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ @@ -90,9 +86,7 @@ Life Cycle Management +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 040c | Non-conformances | FC | See github issues | +-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 040dM | Change tracking | FC | See `Commits `__ | -+-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 040dA | Change tracking | FC | See `Commits `__ | +| 040dM | Change tracking | FC | See `Commits `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 040dS | Change tracking | FC | See `Commits `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ @@ -143,9 +137,7 @@ Schedules +-------+----------------------------------+------------+-----------------------------------------------------------------+ | SWE # | Description | Compliance | Evidence | +=======+==================================+============+=================================================================+ -| 016M | Schedule Requirements | FC | `Milestones `__ | -+-------+----------------------------------+------------+-----------------------------------------------------------------+ -| 016A | Schedule Requirements | FC | `Milestones `__ | +| 016M | Schedule Requirements | FC | `Milestones `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ | 016S | Schedule Requirements | FC | `Milestones `__ | +-------+----------------------------------+------------+-----------------------------------------------------------------+ @@ -288,9 +280,7 @@ Requirements +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ | SWE # | Description | Compliance | Evidence | +=======+==================================+============+================================================================================+ -| 050M | Software Requirements | FC | `Enhancement Issues `__| -+-------+----------------------------------+------------+--------------------------------------------------------------------------------+ -| 050A | Software Requirements | FC | `Enhancement Issues `__ | +| 050M | Software Requirements | FC | `Enhancement Issues `__ | +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ | 050S | Software Requirements | FC | `Enhancement Issues `__| +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ @@ -320,18 +310,16 @@ Implementation +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ | 186 | Unit Test Repeatability | FC | Unit tests are created with each enhancement, run automatically with each PR. | +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ -| 063M | Software Version Description | FC | `See here `__ | -+-------+----------------------------------+------------+--------------------------------------------------------------------------------+ -| 063A | Software Version Description | FC | `See here `__ | +| 063M | Software Version Description | FC | `See here `__ | +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ | 063S | Software Version Description | FC | `See here `__ | +-------+----------------------------------+------------+--------------------------------------------------------------------------------+ Static Analysis Methods Used: -* CodeFactor.io (`prog_models `__, `prog_algs `__, `prog_server `__): Runs automatically in each PR. If issues are detected, they are noted in the PR chat. -* LGTM (`prog_models `__, `prog_algs `__, `prog_server `__): Runs automatically in each PR. If issues are detected, they are noted in the PR chat. -* Codecov (`prog_models `__, `prog_algs `__, `prog_server `__): Runs automatically in each PR. If issues are detected, they are noted in the PR chat. +* CodeFactor.io (`progpy `__, `prog_server `__): Runs automatically in each PR. If issues are detected, they are noted in the PR chat. +* LGTM (`progpy `__, `prog_server `__): Runs automatically in each PR. If issues are detected, they are noted in the PR chat. +* Codecov (`progpy `__, `prog_server `__): Runs automatically in each PR. If issues are detected, they are noted in the PR chat. * CodeQL Scanning: Runs automatically in each PR. If issues are detected, they are noted in the PR chat. * Github Dependabot Alerts: Tracks dependencies, alerts of any issues. @@ -343,21 +331,15 @@ Testing +=======+==================================+============+======================================================================================================+ | 065a | Test Plan | FC | See this document. | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 065bM | Test Procedures | FC | See `GitHub Actions Workflows `__.| -+-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 065bA | Test Procedures | FC | See `GitHub Actions Workflows `__. | +| 065bM | Test Procedures | FC | See `GitHub Actions Workflows `__. | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ | 065bS | Test Procedures | FC | See `GitHub Actions Workflows `__.| +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 065cM | Tests | FC | See `tests directory `__. | -+-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 065cA | Tests | FC | See `tests directory `__. | +| 065cM | Tests | FC | See `tests directory `__. | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ | 065cS | Tests | FC | See `tests directory `__. | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 065dM | Test Reports | FC | See `Github Actions Results `__. | -+-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 065dA | Test Reports | FC | See `Github Actions Results `__. | +| 065dM | Test Reports | FC | See `Github Actions Results `__. | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ | 065dS | Test Reports | FC | See `Github Actions Results `__. | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ @@ -367,9 +349,7 @@ Testing +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ | 071 | Update Test Plans | FC | Workflow, tests, and this document are updated as requirements change | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 186M | Code Coverage | FC | See `Codecov `__ | -+-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ -| 186A | Code Coverage | FC | See `Codecov `__ | +| 186M | Code Coverage | FC | See `Codecov `__ | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ | 186S | Code Coverage | FC | See `Codecov `__ | +-------+----------------------------------+------------+------------------------------------------------------------------------------------------------------+ @@ -431,9 +411,7 @@ Configuration Management +=======+==================================+============+===================================================================+ | 079 | Configuration Management Plan | FC | See this document | +-------+----------------------------------+------------+-------------------------------------------------------------------+ -| 080M | Evaluate Sotware Product Changes | FC | See `PRs `__ | -+-------+----------------------------------+------------+-------------------------------------------------------------------+ -| 080A | Evaluate Sotware Product Changes | FC | See `PRs `__ | +| 080M | Evaluate Sotware Product Changes | FC | See `PRs `__ | +-------+----------------------------------+------------+-------------------------------------------------------------------+ | 080S | Evaluate Sotware Product Changes | FC | See `PRs `__ | +-------+----------------------------------+------------+-------------------------------------------------------------------+ @@ -445,9 +423,7 @@ Configuration Management +-------+----------------------------------+------------+-------------------------------------------------------------------+ | 082c | Authorization Authority | FC | See this document | +-------+----------------------------------+------------+-------------------------------------------------------------------+ -| 083M | Configuration Status | FC | See `Branches `__ | -+-------+----------------------------------+------------+-------------------------------------------------------------------+ -| 083A | Configuration Status | FC | See `Branches `__ | +| 083M | Configuration Status | FC | See `Branches `__ | +-------+----------------------------------+------------+-------------------------------------------------------------------+ | 083S | Configuration Status | FC | See `Branches `__ | +-------+----------------------------------+------------+-------------------------------------------------------------------+ @@ -482,9 +458,7 @@ Non-Conformances +-------+----------------------------------+------------+-------------------------------------------------------------------+ | SWE # | Description | Compliance | Evidence | +=======+==================================+============+===================================================================+ -| 201M | Track non-conformances | FC | See `Github Issues `__| -+-------+----------------------------------+------------+-------------------------------------------------------------------+ -| 201A | Track non-conformances | FC | See `Github Issues `__ | +| 201M | Track non-conformances | FC | See `Github Issues `__ | +-------+----------------------------------+------------+-------------------------------------------------------------------+ | 201S | Track non-conformances | FC | See `Github Issues `__| +-------+----------------------------------+------------+-------------------------------------------------------------------+ @@ -503,7 +477,7 @@ Assessed, there are some existing prognostics tools but no general Python packag Requirement Tracking ******************** -Requirements are tracked as issues with the "Enhancement" label (See `prog_models `__, `prog_algs `__, `prog_server `__ Enhancement Issues). An issue template is used to ensure that the requirement has the desired information. Issues are closed to indicate the requirement has been met. Closing a requirement issue is done with a pull request, which is linked to the relevant requirement, for tracability. Closing the requirement issue requires a code review (see above for details), and requires implementation of passing tests that test the requirement (i.e., verification tests). The tests are reviewed with the code implementing the requirement. Issues are assigned to a milestone (i.e., release) indicating the requirements for that release. Github automatically tracks any changes to the issues (i.e., requirements) +Requirements are tracked as issues with the "Enhancement" label (See `progpy `__, `prog_server `__ Enhancement Issues). An issue template is used to ensure that the requirement has the desired information. Issues are closed to indicate the requirement has been met. Closing a requirement issue is done with a pull request, which is linked to the relevant requirement, for tracability. Closing the requirement issue requires a code review (see above for details), and requires implementation of passing tests that test the requirement (i.e., verification tests). The tests are reviewed with the code implementing the requirement. Issues are assigned to a milestone (i.e., release) indicating the requirements for that release. Github automatically tracks any changes to the issues (i.e., requirements) Dependencies ************** @@ -551,7 +525,7 @@ The following dependencies are used in the project: * Usage Rights: Released under the MIT License * Future Support: expected- Chaospy is a common tool still under development and actively supported -* `FilterPy `__ (prog_algs only) +* `FilterPy `__ * Requirements met: Algorithms for state estimators and predictors * Documentation: https://filterpy.readthedocs.io @@ -579,7 +553,7 @@ The following dependencies are used in the project: * Usage Rights: Released under the MIT License * Future Support: expected- urllib3 is a common tool still under development and actively supported -* `fastdtw `__ (prog_models only) +* `fastdtw `__ * Requirements met: Dynamic time warping (for dtw metric used in calc_error) * Documentation: https://github.com/slaypni/fastdtw @@ -596,7 +570,7 @@ Notes for all: Tracability Notes ***************** -Hazards and non-conformances are tracked as issues with the label bug (See `prog_models `__, `prog_algs `__, `prog_server `__). In the template for a bug report, there is a section asking for relevant enhancement issues (i.e., requirements). This linking establishes tracability from hazards/non-conformances to the underlying requirement. These linkings are automatically marked by the github system in the requirement issue. Additionally, to close an enhancement issue (i.e., requirement), passing verification tests must be created and checked in. The PR where these tests are created and the implementation is completed is linked to the issue establishing tracability from requirement -> verification test. These tests run automatically at every change/PR. +Hazards and non-conformances are tracked as issues with the label bug (See `progpy `__, `prog_server `__). In the template for a bug report, there is a section asking for relevant enhancement issues (i.e., requirements). This linking establishes tracability from hazards/non-conformances to the underlying requirement. These linkings are automatically marked by the github system in the requirement issue. Additionally, to close an enhancement issue (i.e., requirement), passing verification tests must be created and checked in. The PR where these tests are created and the implementation is completed is linked to the issue establishing tracability from requirement -> verification test. These tests run automatically at every change/PR. Additionally, requirements are assigned to milestones/releases, establishing bi-directional tracability to these @@ -607,3 +581,5 @@ Summary: The following tracabilities are maintained: * Requirement <-> Verification Test & Results * Requirement <-> Implementation * Release/Milestone <-> Requirement + +For past bugs, enhancements, pull requests, etc. look at the previously used prog_models and prog_algs servers. diff --git a/sphinx-config/prog_algs_guide.rst b/sphinx-config/prog_algs_guide.rst index bb8005e..e782ece 100644 --- a/sphinx-config/prog_algs_guide.rst +++ b/sphinx-config/prog_algs_guide.rst @@ -1,4 +1,4 @@ -prog_algs Guide +State Estimation and Prediction Guide =================================================== .. role:: pythoncode(code) @@ -6,34 +6,34 @@ prog_algs Guide .. raw:: html - + .. image:: https://mybinder.org/badge_logo.svg - :target: https://mybinder.org/v2/gh/nasa/prog_algs/master?labpath=tutorial.ipynb + :target: https://mybinder.org/v2/gh/nasa/progpy/master?labpath=tutorial.ipynb -The Prognostic Algorithms Package is a python framework for prognostics (computation of remaining useful life or future states) of engineering systems. The package provides an extendable set of algorithms for state estimation and prediction, including uncertainty propagation. The package also include metrics, visualization, and analysis tools needed to measure the prognostic performance. The algorithms use prognostic models (from :ref:`prog_models`) to perform estimation and prediction functions. The package enables the rapid development of prognostics solutions for given models of components and systems. Different algorithms can be easily swapped to do comparative studies and evaluations of different algorithms to select the best for the application at hand. +The Prognostic Python Package (progpy) is a python framework for prognostics (computation of remaining useful life or future states) of engineering systems. The package provides an extendable set of algorithms for state estimation and prediction, including uncertainty propagation. The package also include metrics, visualization, and analysis tools needed to measure the prognostic performance. The algorithms use prognostic models (from :ref:`Modeling and Simulation Guide`) to perform estimation and prediction functions. The package enables the rapid development of prognostics solutions for given models of components and systems. Different algorithms can be easily swapped to do comparative studies and evaluations of different algorithms to select the best for the application at hand. -Installing prog_algs +Installing progpy ----------------------- .. tabs:: .. tab:: Stable Version (Recommended) - The latest stable release of prog_algs is hosted on PyPi. For most users (unless you want to contribute to the development of `prog_algs`), this version will be adequate. To install from the command line, use the following command: + The latest stable release of progpy is hosted on PyPi. For most users (unless you want to contribute to the development of `progpy`), this version will be adequate. To install from the command line, use the following command: .. code-block:: console - $ pip install prog_algs + $ pip install progpy .. tab:: Pre-Release - Users who would like to contribute to prog_algs or would like to use pre-release features can do so using the `prog_algs GitHub repo `__. This isn't recommended for most users as this version may be unstable. To do this, use the following commands: + Users who would like to contribute to progpy or would like to use pre-release features can do so using the `progpy GitHub repo `__. This isn't recommended for most users as this version may be unstable. To do this, use the following commands: .. code-block:: console - $ git clone https://github.com/nasa/prog_algs - $ cd prog_algs + $ git clone https://github.com/nasa/progpy + $ cd progpy $ git checkout dev $ pip install -e . @@ -44,16 +44,16 @@ The structure of the packages is illustrated below: .. image:: images/package_structure.png -Prognostics is performed using :ref:`State Estimators ` and :ref:`Predictors `. State Estimators are resposible for estimating the current state of the modeled system using sensor data and a prognostics model (see: :ref:`prog_models package `). The state estimator then produces an estimate of the system state with uncertainty in the form of an :ref:`uncertain data object `. This state estimate is used by the predictor to predict when events will occur (Time of Event, ToE - returned as an :ref:`uncertain data object `), and future system states (returned as a :ref:`Prediction object `). +Prognostics is performed using :ref:`State Estimators ` and :ref:`Predictors `. State Estimators are resposible for estimating the current state of the modeled system using sensor data and a prognostics model (see: :ref:`Modeling and Simulation Guide `). The state estimator then produces an estimate of the system state with uncertainty in the form of an :ref:`uncertain data object `. This state estimate is used by the predictor to predict when events will occur (Time of Event, ToE - returned as an :ref:`uncertain data object `), and future system states (returned as a :ref:`Prediction object `). Data Structures *************** A few custom data structures are available for storing and manipulating prognostics data of various forms. These structures are listed below and desribed on their respective pages: - * :py:class:`prog_models.sim_result.SimResult` : The result of a single simulation (without uncertainty). Can be used to store inputs, outputs, states, event_states, observables, etc. Is returned by the model.simulate_to* methods. - * :py:class:`prog_algs.uncertain_data.UncertainData`: Used throughout the package to represent data with uncertainty. There are a variety of subclasses of UncertainData to represent data with uncertainty in different forms (e.g., :py:class:`prog_algs.uncertain_data.ScalarData`, :py:class:`prog_algs.uncertain_data.MultivariateNormalDist`, :py:class:`prog_algs.uncertain_data.UnweightedSamples`). Notably, this is used to represent the output of a StateEstimator's `estimate` method, individual snapshots of a prediction, and the time of event estimate from a predictor's `predict` method. - * :py:class:`prog_algs.predictors.Prediction`: Prediction of future values (with uncertainty) of some variable (e.g., :term:`input`, :term:`state`, :term:`output`, :term:`event state`, etc.). The `predict` method of predictors return this. - * :py:class:`prog_algs.predictors.ToEPredictionProfile` : The time of prediction estimates from multiple predictions. This data structure can be treated as a dictionary of time of prediction to toe prediction. + * :py:class:`progpy.sim_result.SimResult` : The result of a single simulation (without uncertainty). Can be used to store inputs, outputs, states, event_states, observables, etc. Is returned by the model.simulate_to* methods. + * :py:class:`progpy.uncertain_data.UncertainData`: Used throughout the package to represent data with uncertainty. There are a variety of subclasses of UncertainData to represent data with uncertainty in different forms (e.g., :py:class:`progpy.uncertain_data.ScalarData`, :py:class:`progpy.uncertain_data.MultivariateNormalDist`, :py:class:`progpy.uncertain_data.UnweightedSamples`). Notably, this is used to represent the output of a StateEstimator's `estimate` method, individual snapshots of a prediction, and the time of event estimate from a predictor's `predict` method. + * :py:class:`progpy.predictors.Prediction`: Prediction of future values (with uncertainty) of some variable (e.g., :term:`input`, :term:`state`, :term:`output`, :term:`event state`, etc.). The `predict` method of predictors return this. + * :py:class:`progpy.predictors.ToEPredictionProfile` : The time of prediction estimates from multiple predictions. This data structure can be treated as a dictionary of time of prediction to toe prediction. State Estimation ----------------- @@ -66,27 +66,27 @@ The foundation of state estimators is the estimate method. The estimate method i >>> estimator.estimate(time, inputs, outputs) -The internal state is stored in the estimators x property as a UncertainData subclass (see `UncertainData `__). State is accessed like so :pythoncode:`x_est = estimator.x`. +The internal state is stored in the estimators x property as a UncertainData subclass (see `UncertainData `__). State is accessed like so :pythoncode:`x_est = estimator.x`. .. dropdown:: Included State Estimators - ProgPy includes a number of state estimators in the *prog_algs.state_estimators* package. The most commonly used of these are highlighted below. See `State Estimators `__ for a full list of supported state estimators. + ProgPy includes a number of state estimators in the *progpy.state_estimators* package. The most commonly used of these are highlighted below. See `State Estimators `__ for a full list of supported state estimators. - * **Unscented Kalman Filter (UKF)**: A type of kalman filter for non-linear models where the state distribution is represented by a set of sigma points, calculated by an unscented tranform. Sigma points are propogated forward and then compared with the measurement to update the distribution. The resulting state is represented by a :py:class:`prog_algs.uncertain_data.MultivariateNormalDist`. By it's nature, UKFs are much faster than Particle Filters, but they fit the data to a normal distribution, resulting in some loss of information. - * **Particle Filter (PF)**: A sample-based state estimation algorithm, where the distribution of likely states is represented by a set of unweighted samples. These samples are propagated forward and then weighted according to the likelihood of the measurement (given those samples) to update the distribution. The resulting state is represented by a :py:class:`prog_algs.uncertain_data.UnweightedSamples`. By its nature, PF is more accurate than a UKF, but much slower. Full accuracy of PF can be adjusted by increasing or decreasing the number of samples - * **Kalman Filter (KF)**: A Simple efficient Kalman Filter for linear systems where state is represented by a mean and covariance matrix. The resulting state is represented by a :py:class:`prog_algs.uncertain_data.MultivariateNormalDist`. Only works with Prognostic Models inheriting from :py:class:`prog_models.LinearModel`. + * **Unscented Kalman Filter (UKF)**: A type of kalman filter for non-linear models where the state distribution is represented by a set of sigma points, calculated by an unscented tranform. Sigma points are propogated forward and then compared with the measurement to update the distribution. The resulting state is represented by a :py:class:`progpy.uncertain_data.MultivariateNormalDist`. By it's nature, UKFs are much faster than Particle Filters, but they fit the data to a normal distribution, resulting in some loss of information. + * **Particle Filter (PF)**: A sample-based state estimation algorithm, where the distribution of likely states is represented by a set of unweighted samples. These samples are propagated forward and then weighted according to the likelihood of the measurement (given those samples) to update the distribution. The resulting state is represented by a :py:class:`progpy.uncertain_data.UnweightedSamples`. By its nature, PF is more accurate than a UKF, but much slower. Full accuracy of PF can be adjusted by increasing or decreasing the number of samples + * **Kalman Filter (KF)**: A Simple efficient Kalman Filter for linear systems where state is represented by a mean and covariance matrix. The resulting state is represented by a :py:class:`progpy.uncertain_data.MultivariateNormalDist`. Only works with Prognostic Models inheriting from :py:class:`progpy.LinearModel`. .. dropdown:: UKF Details - .. autoclass:: prog_algs.state_estimators.UnscentedKalmanFilter + .. autoclass:: progpy.state_estimators.UnscentedKalmanFilter .. dropdown:: PF Details - .. autoclass:: prog_algs.state_estimators.ParticleFilter + .. autoclass:: progpy.state_estimators.ParticleFilter .. dropdown:: KF Details - .. autoclass:: prog_algs.state_estimators.KalmanFilter + .. autoclass:: progpy.state_estimators.KalmanFilter .. dropdown:: Example @@ -94,8 +94,8 @@ The internal state is stored in the estimators x property as a UncertainData sub .. code-block:: python - >>> from prog_models.models import ThrownObject - >>> from prog_algs.state_estimators import UnscentedKalmanFilter + >>> from progpy.models import ThrownObject + >>> from progpy.state_estimators import UnscentedKalmanFilter >>> >>> m = ThrownObject() >>> initial_state = m.initialize() @@ -110,14 +110,14 @@ The internal state is stored in the estimators x property as a UncertainData sub Extending ************ -New :term:`state estimator` are created by extending the :class:`prog_algs.state_estimators.StateEstimator` class. +New :term:`state estimator` are created by extending the :class:`progpy.state_estimators.StateEstimator` class. -See :download:`examples.new_state_estimator_example <../../prog_algs/examples/new_state_estimator_example.py>` for an example of this approach. +See :download:`examples.new_state_estimator_example <../../progpy/examples/new_state_estimator_example.py>` for an example of this approach. Example ^^^^^^^^^^^ -* :download:`examples.new_state_estimator_example <../../prog_algs/examples/new_state_estimator_example.py>` +* :download:`examples.new_state_estimator_example <../../progpy/examples/new_state_estimator_example.py>` .. automodule:: new_state_estimator_example Prediction @@ -135,39 +135,39 @@ A predictors ``predict`` method is used to perform prediction, generally defined result = predictor.predict(x0, future_loading, **config) -Where x0 is the initial state as an UncertainData object (often the output of state estimation), future_loading is a function defining future loading as a function of state and time, and config is a dictionary of any additional configuration parameters, specific to the predictor being used. See `Predictors `__ for options available for each predictor +Where x0 is the initial state as an UncertainData object (often the output of state estimation), future_loading is a function defining future loading as a function of state and time, and config is a dictionary of any additional configuration parameters, specific to the predictor being used. See `Predictors `__ for options available for each predictor The result of the predict method is a named tuple with the following members: * **times**: array of times for each savepoint such that times[i] corresponds to inputs.snapshot(i) -* **inputs**: :py:class:`prog_algs.predictors.Prediction` object containing inputs used to perform prediction such that inputs.snapshot(i) corresponds to times[i] -* **outputs**: :py:class:`prog_algs.predictors.Prediction` object containing predicted outputs at each savepoint such that outputs.snapshot(i) corresponds to times[i] -* **event_states**: :py:class:`prog_algs.predictors.Prediction` object containing predicted event states at each savepoint such that event_states.snapshot(i) corresponds to times[i] -* **time_of_event**: :py:class:`prog_algs.uncertain_data.UncertainData` object containing the predicted Time of Event (ToE) for each event. Additionally, final state at time of event is saved at time_of_event.final_state -> :py:class:`prog_algs.uncertain_data.UncertainData` for each event +* **inputs**: :py:class:`progpy.predictors.Prediction` object containing inputs used to perform prediction such that inputs.snapshot(i) corresponds to times[i] +* **outputs**: :py:class:`progpy.predictors.Prediction` object containing predicted outputs at each savepoint such that outputs.snapshot(i) corresponds to times[i] +* **event_states**: :py:class:`progpy.predictors.Prediction` object containing predicted event states at each savepoint such that event_states.snapshot(i) corresponds to times[i] +* **time_of_event**: :py:class:`progpy.uncertain_data.UncertainData` object containing the predicted Time of Event (ToE) for each event. Additionally, final state at time of event is saved at time_of_event.final_state -> :py:class:`progpy.uncertain_data.UncertainData` for each event The stepsize and times at which results are saved can be defined like in a simulation. See `Simulation `__. .. dropdown:: Included Predictors - ProgPy includes a number of predictors in the *prog_algs.predictors* package. The most commonly used of these are highlighted below. See `Predictors `__ for a full list of supported predictors. + ProgPy includes a number of predictors in the *progpy.predictors* package. The most commonly used of these are highlighted below. See `Predictors `__ for a full list of supported predictors. - * **Unscented Transform (UT)**: A type of predictor for non-linear models where the state distribution is represented by a set of sigma points, calculated by an unscented tranform. Sigma points are propogated forward with time until the pass the threshold. The times at which each sigma point passes the threshold are converted to a distribution of time of event. The predicted future states and time of event are represented by a :py:class:`prog_algs.uncertain_data.MultivariateNormalDist`. By it's nature, UTs are much faster than MCs, but they fit the data to a normal distribution, resulting in some loss of information. - * **Monte Carlo (MC)**: A sample-based prediction algorithm, where the distribution of likely states is represented by a set of unweighted samples. These samples are propagated forward with time. By its nature, MC is more accurate than a PF, but much slower. The predicted future states and time of event are represented by a :py:class:`prog_algs.uncertain_data.UnweightedSamples`. Full accuracy of MC can be adjusted by increasing or decreasing the number of samples + * **Unscented Transform (UT)**: A type of predictor for non-linear models where the state distribution is represented by a set of sigma points, calculated by an unscented tranform. Sigma points are propogated forward with time until the pass the threshold. The times at which each sigma point passes the threshold are converted to a distribution of time of event. The predicted future states and time of event are represented by a :py:class:`progpy.uncertain_data.MultivariateNormalDist`. By it's nature, UTs are much faster than MCs, but they fit the data to a normal distribution, resulting in some loss of information. + * **Monte Carlo (MC)**: A sample-based prediction algorithm, where the distribution of likely states is represented by a set of unweighted samples. These samples are propagated forward with time. By its nature, MC is more accurate than a PF, but much slower. The predicted future states and time of event are represented by a :py:class:`progpy.uncertain_data.UnweightedSamples`. Full accuracy of MC can be adjusted by increasing or decreasing the number of samples .. dropdown:: UT Details - .. autoclass:: prog_algs.predictors.UnscentedTransformPredictor + .. autoclass:: progpy.predictors.UnscentedTransformPredictor .. dropdown:: MC Details - .. autoclass:: prog_algs.predictors.MonteCarlo + .. autoclass:: progpy.predictors.MonteCarlo - .. autoclass:: prog_algs.predictors.MonteCarloPredictor + .. autoclass:: progpy.predictors.MonteCarloPredictor Extending ************* -New :term:`predictor` are created by extending the :class:`prog_algs.predictors.Predictor` class. +New :term:`predictor` are created by extending the :class:`progpy.predictors.Predictor` class. Analyzing Results @@ -176,7 +176,7 @@ Analyzing Results State Estimation ******************* -The results of the state estimation are stored in an object of type :class:`prog_algs.uncertain_data.UncertainData`. This class contains a number of methods for analyzing a state estimate. This includes methods for obtaining statistics about the distribution, including the following: +The results of the state estimation are stored in an object of type :class:`progpy.uncertain_data.UncertainData`. This class contains a number of methods for analyzing a state estimate. This includes methods for obtaining statistics about the distribution, including the following: * **mean**: The mean value of the state estimate distribution. * **median**: The median value of the state estimate distribution. @@ -238,12 +238,12 @@ There are also a number of figures available to describe a state estimate, descr -See :class:`prog_algs.uncertain_data.UncertainData` documentation for more details. +See :class:`progpy.uncertain_data.UncertainData` documentation for more details. Predicted Future States ************************** -Predicted future states, inputs, outputs, and event states come in the form of a :class:`prog_algs.predictors.Prediction` object. Predictions store distributions of predicted future values at multiple future times. Predictions contain a number of tools for analyzing the results, some of which are described below: +Predicted future states, inputs, outputs, and event states come in the form of a :class:`progpy.predictors.Prediction` object. Predictions store distributions of predicted future values at multiple future times. Predictions contain a number of tools for analyzing the results, some of which are described below: * **mean**: Estimate the mean value at each time. The result is a list of dictionaries such that prediction.mean[i] corresponds to times[i] * **monotonicity**: Given a single prediction, for each event: go through all predicted states and compare those to the next one. @@ -253,7 +253,7 @@ Predicted future states, inputs, outputs, and event states come in the form of a Time of Event (ToE) ************************** -Time of Event is also stored as an object of type :class:`prog_algs.uncertain_data.UncertainData`, so the analysis functions described in :ref:`State Estimation` are also available for a ToE estimate. See :ref:`State Estimation` or :class:`prog_algs.uncertain_data.UncertainData` documentation for details. +Time of Event is also stored as an object of type :class:`progpy.uncertain_data.UncertainData`, so the analysis functions described in :ref:`State Estimation` are also available for a ToE estimate. See :ref:`State Estimation` or :class:`progpy.uncertain_data.UncertainData` documentation for details. In addition to these standard UncertainData metrics, Probability of Success (PoS) is an important metric for prognostics. Probability of Success is the probability that a event will not occur before a defined time. For example, in aeronautics, PoS might be the probability that no failure will occur before end of mission. @@ -261,13 +261,13 @@ Below is an example calculating probability of success: .. code-block:: python - >>> from prog_algs.metrics import prob_success + >>> from progpy.metrics import prob_success >>> ps = prob_success(some_distribution, end_of_mission) ToE Prediction Profile ************************** -A :class:`prog_algs.predictors.ToEPredictionProfile` contains Time of Event (ToE) predictions performed at multiple points. ToEPredictionProfile is frequently used to evaluate the prognostic quality for a given prognostic solution. It contains a number of methods to help with this, including: +A :class:`progpy.predictors.ToEPredictionProfile` contains Time of Event (ToE) predictions performed at multiple points. ToEPredictionProfile is frequently used to evaluate the prognostic quality for a given prognostic solution. It contains a number of methods to help with this, including: * **alpha_lambda**: Whether the prediction falls within specified limits at particular times with respect to a performance measure [#Goebel2017]_ [#Saxena2010]_ * **cumulate_relative_accuracy**: The sum of the relative accuracies of each prediction, given a ground truth @@ -284,41 +284,41 @@ Examples ---------- .. image:: https://mybinder.org/badge_logo.svg - :target: https://mybinder.org/v2/gh/nasa/prog_algs/master?labpath=tutorial.ipynb + :target: https://mybinder.org/v2/gh/nasa/progpy/master?labpath=tutorial.ipynb -The best way to learn how to use `prog_algs` is through the `tutorial `__. There are also a number of examples which show different aspects of the package, summarized and linked below: +The best way to learn how to use `progpy` is through the `tutorial `__. There are also a number of examples which show different aspects of the package, summarized and linked below: -* :download:`examples.basic_example <../../prog_algs/examples/basic_example.py>` +* :download:`examples.basic_example <../../progpy/examples/basic_example.py>` .. automodule:: basic_example -* :download:`examples.basic_example_battery <../../prog_algs/examples/basic_example_battery.py>` +* :download:`examples.basic_example_battery <../../progpy/examples/basic_example_battery.py>` .. automodule:: basic_example_battery -.. * :download:`examples.benchmarking_example <../../prog_algs/examples/benchmarking_example.py>` +.. * :download:`examples.benchmarking_example <../../progpy/examples/benchmarking_example.py>` .. .. automodule:: benchmarking_example -* :download:`examples.eol_event <../../prog_algs/examples/eol_event.py>` +* :download:`examples.eol_event <../../progpy/examples/eol_event.py>` .. automodule:: eol_event -* :download:`examples.new_state_estimator_example <../../prog_algs/examples/new_state_estimator_example.py>` +* :download:`examples.new_state_estimator_example <../../progpy/examples/new_state_estimator_example.py>` .. automodule:: new_state_estimator_example -* :download:`examples.horizon <../../prog_algs/examples/horizon.py>` +* :download:`examples.horizon <../../progpy/examples/horizon.py>` .. automodule:: horizon -* :download:`examples.kalman_filter <../../prog_algs/examples/kalman_filter.py>` +* :download:`examples.kalman_filter <../../progpy/examples/kalman_filter.py>` .. automodule:: kalman_filter -* :download:`examples.measurement_eqn_example <../../prog_algs/examples/measurement_eqn_example.py>` +* :download:`examples.measurement_eqn_example <../../progpy/examples/measurement_eqn_example.py>` .. automodule:: measurement_eqn_example -* :download:`examples.playback <../../prog_algs/examples/playback.py>` +* :download:`examples.playback <../../progpy/examples/playback.py>` .. automodule:: playback -* :download:`examples.predict_specific_event <../../prog_algs/examples/predict_specific_event.py>` +* :download:`examples.predict_specific_event <../../progpy/examples/predict_specific_event.py>` .. automodule:: predict_specific_event -* :download:`examples.particle_filter_battery_example <../../prog_algs/examples/particle_filter_battery_example.py>` +* :download:`examples.particle_filter_battery_example <../../progpy/examples/particle_filter_battery_example.py>` .. automodule:: particle_filter_battery_example References diff --git a/sphinx-config/prog_models_guide.rst b/sphinx-config/prog_models_guide.rst index dee9260..9a2b30e 100644 --- a/sphinx-config/prog_models_guide.rst +++ b/sphinx-config/prog_models_guide.rst @@ -1,33 +1,33 @@ -prog_models Guide +Modeling and Sim Guide =================================================== .. raw:: html - + -The Prognostics Models Package (prog_models) is a Python framework for defining, building, using, and testing models for :term:`prognostics` of engineering systems. It also provides a set of prognostics models for select components developed within this framework, suitable for use in prognostics applications for these components and can be used in conjunction with the Prognostics Algorithms Package (:ref:`prog_algs`) to perform research in prognostics methods. +The Prognostics Python Package (progpy) includes tools for defining, building, using, and testing models for :term:`prognostics` of engineering systems. It also provides a set of prognostics models for select components developed within this framework, suitable for use in prognostics applications for these components and can be used in conjunction with the state estimation and prediction features (:ref:`prog_algs`) to perform research in prognostics methods. -Installing prog_models +Installing progpy ----------------------- .. tabs:: .. tab:: Stable Version (Recommended) - The latest stable release of prog_models is hosted on PyPi. For most users (unless you want to contribute to the development of prog_models), the version on PyPi will be adequate. To install from the command line, use the following command: + The latest stable release of progpy is hosted on PyPi. For most users (unless you want to contribute to the development of progpy), the version on PyPi will be adequate. To install from the command line, use the following command: .. code-block:: console - $ pip install prog_models + $ pip install progpy .. tab:: Pre-Release - Users who would like to contribute to prog_models or would like to use pre-release features can do so using the `prog_models GitHub repo `__. This isn't recommended for most users as this version may be unstable. To do this, use the following commands: + Users who would like to contribute to progpy or would like to use pre-release features can do so using the `progpy GitHub repo `__. This isn't recommended for most users as this version may be unstable. To do this, use the following commands: .. code-block:: console - $ git clone https://github.com/nasa/prog_models - $ cd prog_models + $ git clone https://github.com/nasa/progpy + $ cd progpy $ git checkout dev $ pip install -e . @@ -35,9 +35,9 @@ Getting Started ------------------ .. image:: https://mybinder.org/badge_logo.svg - :target: https://mybinder.org/v2/gh/nasa/prog_models/master?labpath=tutorial.ipynb + :target: https://mybinder.org/v2/gh/nasa/progpy/master?labpath=tutorial.ipynb -The best way to learn how to use prog_models is through the `tutorial `__. There are also a number of examples that show different aspects of the package, summarized and linked in the below sections +The best way to learn how to use progpy is through the `tutorial `__. There are also a number of examples that show different aspects of the package, summarized and linked in the below sections ProgPy Prognostic Model Format ---------------------------------- @@ -71,7 +71,7 @@ States are transitioned forward in time using the state transition equation. where :math:`x(t)` is :term:`state`, at time :math:`t`, :math:`u(t)` is :term:`input` at time :math:`t`, :math:`dt` is the stepsize, and :math:`\Theta` are the model :term:`parameters`. -In a ProgPy model, this state transition can be represented one of two ways, either discrete or continuous, depending on the nature of state transition. In the case of continuous models, state transition behavior is defined by defining the first derivative, using the :py:func:`prog_models.PrognosticsModel.dx` method. For discrete models, state transition behavior is defined using the :py:func:`prog_models.PrognosticsModel.next_state` method. The continuous state transition behavior is recommended, because defining the first derivative enables some approaches that rely on that information. +In a ProgPy model, this state transition can be represented one of two ways, either discrete or continuous, depending on the nature of state transition. In the case of continuous models, state transition behavior is defined by defining the first derivative, using the :py:func:`progpy.PrognosticsModel.dx` method. For discrete models, state transition behavior is defined using the :py:func:`progpy.PrognosticsModel.next_state` method. The continuous state transition behavior is recommended, because defining the first derivative enables some approaches that rely on that information. .. image:: images/next_state.png @@ -106,7 +106,7 @@ Output (Measurements) The next important part of a prognostic model is the outputs. Outputs are measurable quantities of a system that are a function of system state. When applied in prognostics, generally the outputs are what is being measured or observed in some way. State estimators use the different between predicted and measured values of these outputs to estimate the system state. -Outputs are a function of only the system state (x) and :term:`parameters` (:math:`\Theta`), as described below. The expected outputs for a model are defined by its *outputs* property. The logic of calculating outputs from system state is provided by the user in the model :py:func:`prog_models.PrognosticsModel.output` method. +Outputs are a function of only the system state (x) and :term:`parameters` (:math:`\Theta`), as described below. The expected outputs for a model are defined by its *outputs* property. The logic of calculating outputs from system state is provided by the user in the model :py:func:`progpy.PrognosticsModel.output` method. .. image:: images/output.png @@ -137,9 +137,9 @@ Traditionally users may have heard the prognostic problem as estimating the Rema Additionally, events can be used to predict other events of interest beyond failure, such as special system states or warning thresholds. For example, the above battery model might also have an warning event for when battery capacity reaches 50% of the original capacity because of battery aging with use. -The expected events for a model are defined by its *events* property. The logic of events can be defined in two methods: :py:func:`prog_models.PrognosticsModel.threshold_met` and :py:func:`prog_models.PrognosticsModel.event_state`. +The expected events for a model are defined by its *events* property. The logic of events can be defined in two methods: :py:func:`progpy.PrognosticsModel.threshold_met` and :py:func:`progpy.PrognosticsModel.event_state`. -:term:`Thresholds` are the conditions under which an event occurs. The logic of the threshold is defined in the :py:func:`prog_models.PrognosticsModel.threshold_met` method. This method returns boolean for each event specifying if the event has occured. +:term:`Thresholds` are the conditions under which an event occurs. The logic of the threshold is defined in the :py:func:`progpy.PrognosticsModel.threshold_met` method. This method returns boolean for each event specifying if the event has occured. .. image:: images/threshold_met.png @@ -154,7 +154,7 @@ The expected events for a model are defined by its *events* property. The logic -:term:`Event states` are an estimate of the progress towards a threshold. Where thresholds are boolean, event states are a number between 0 and 1, where 0 means the event has occured, 1 means no progress towards an event. Event states are a generalization of State of Health (SOH) for systems with multiple events and non-failure events. The logic of the event states is defined in the :py:func:`prog_models.PrognosticsModel.event_state` method. +:term:`Event states` are an estimate of the progress towards a threshold. Where thresholds are boolean, event states are a number between 0 and 1, where 0 means the event has occured, 1 means no progress towards an event. Event states are a generalization of State of Health (SOH) for systems with multiple events and non-failure events. The logic of the event states is defined in the :py:func:`progpy.PrognosticsModel.event_state` method. .. image:: images/event_state.png @@ -224,7 +224,7 @@ The specific parameters are very specific to the system being modeled. For examp Sometimes users would like to specify parameters as a function of other parameters. This feature is called "derived parameters". See example below for more details on this feature. - * :download:`examples.derived_params <../../prog_models/examples/derived_params.py>` + * :download:`examples.derived_params <../../progpy/examples/derived_params.py>` .. automodule:: derived_params Noise @@ -250,7 +250,7 @@ In practice, it is impossible to have absolute knowledge of future states due to See example below for details on how to configure proccess and measurement noise in ProgPy -* :download:`examples.noise <../../prog_models/examples/noise.py>` +* :download:`examples.noise <../../progpy/examples/noise.py>` .. automodule:: noise Future Loading @@ -268,13 +268,13 @@ Future loading is provided to the user as a function of time and optional state. See example below for details on how to provide future loading information in ProgPy. -* :download:`examples.future_loading <../../prog_models/examples/future_loading.py>` +* :download:`examples.future_loading <../../progpy/examples/future_loading.py>` .. automodule:: future_loading General Notes ^^^^^^^^^^^^^^^^ -Users of ProgPy will need a model describing the behavior of the system of interest. Users will likely either use one of the models distribued with ProgPy (see `Included Models `__), configuring it to their own system using parameter estimation (see :download:`examples.param_est <../../prog_models/examples/param_est.py>`), use a :term:`data-driven model` class to learn system behavior from data, or build their own model (see `Building New Models`_ section, below). +Users of ProgPy will need a model describing the behavior of the system of interest. Users will likely either use one of the models distribued with ProgPy (see `Included Models `__), configuring it to their own system using parameter estimation (see :download:`examples.param_est <../../progpy/examples/param_est.py>`), use a :term:`data-driven model` class to learn system behavior from data, or build their own model (see `Building New Models`_ section, below). Building New Models ---------------------- @@ -288,48 +288,48 @@ State-transition Models .. tab:: physics-based - New :term:`physics-based models` are constructed by subclassing :py:class:`prog_models.PrognosticsModel` as illustrated in the first example. To generate a new model, create a new class for your model that inherits from this class. Alternatively, you can copy the template :download:`prog_model_template.ProgModelTemplate <../../prog_models/prog_model_template.py>`, replacing the methods with logic defining your specific model. The analysis and simulation tools defined in :class:`prog_models.PrognosticsModel` will then work with your new model. + New :term:`physics-based models` are constructed by subclassing :py:class:`progpy.PrognosticsModel` as illustrated in the first example. To generate a new model, create a new class for your model that inherits from this class. Alternatively, you can copy the template :download:`prog_model_template.ProgModelTemplate <../../progpy/prog_model_template.py>`, replacing the methods with logic defining your specific model. The analysis and simulation tools defined in :class:`progpy.PrognosticsModel` will then work with your new model. - For simple linear models, users can choose to subclass the simpler :py:class:`prog_models.LinearModel` class, as illustrated in the second example. Some methods and algorithms only function on linear models. + For simple linear models, users can choose to subclass the simpler :py:class:`progpy.LinearModel` class, as illustrated in the second example. Some methods and algorithms only function on linear models. - * :download:`examples.new_model <../../prog_models/examples/new_model.py>` + * :download:`examples.new_model <../../progpy/examples/new_model.py>` .. automodule:: new_model - * :download:`examples.linear_model <../../prog_models/examples/linear_model.py>` + * :download:`examples.linear_model <../../progpy/examples/linear_model.py>` .. automodule:: linear_model .. dropdown:: Advanced features in model building - * :download:`examples.derived_params <../../prog_models/examples/derived_params.py>` + * :download:`examples.derived_params <../../progpy/examples/derived_params.py>` .. automodule:: derived_params - * :download:`examples.state_limits <../../prog_models/examples/state_limits.py>` + * :download:`examples.state_limits <../../progpy/examples/state_limits.py>` .. automodule:: state_limits - * :download:`examples.events <../../prog_models/examples/events.py>` + * :download:`examples.events <../../progpy/examples/events.py>` .. automodule:: events .. tab:: data-driven - New :term:`data-driven models`, such as those using neural networks, are created by subclassing the :py:class:`prog_models.data_models.DataModel` class, overriding the ``from_data`` method. + New :term:`data-driven models`, such as those using neural networks, are created by subclassing the :py:class:`progpy.data_models.DataModel` class, overriding the ``from_data`` method. - The :py:func:`prog_models.data_models.DataModel.from_data` and :py:func:`prog_models.data_models.DataModel.from_model` methods are used to construct new models from data or an existing model (i.e., :term:`surrogate`), respectively. The use of these is demonstrated in the following examples. + The :py:func:`progpy.data_models.DataModel.from_data` and :py:func:`progpy.data_models.DataModel.from_model` methods are used to construct new models from data or an existing model (i.e., :term:`surrogate`), respectively. The use of these is demonstrated in the following examples. - * :download:`examples.lstm_model <../../prog_models/examples/lstm_model.py>` + * :download:`examples.lstm_model <../../progpy/examples/lstm_model.py>` .. automodule:: lstm_model - * :download:`examples.full_lstm_model <../../prog_models/examples/full_lstm_model.py>` + * :download:`examples.full_lstm_model <../../progpy/examples/full_lstm_model.py>` .. automodule:: full_lstm_model - * :download:`examples.pce <../../prog_models/examples/pce.py>` + * :download:`examples.pce <../../progpy/examples/pce.py>` .. automodule:: pce - * :download:`examples.generate_surrogate <../../prog_models/examples/generate_surrogate.py>` + * :download:`examples.generate_surrogate <../../progpy/examples/generate_surrogate.py>` .. automodule:: generate_surrogate .. dropdown:: Advanced features in data models - * :download:`examples.custom_model <../../prog_models/examples/custom_model.py>` + * :download:`examples.custom_model <../../progpy/examples/custom_model.py>` .. automodule:: custom_model Direct-prediction models @@ -337,7 +337,7 @@ Direct-prediction models :term:`Direct-prediction models` are models that estimate :term:`time of event` directly from the current state and :term:`future load`, instead of being predicted through state transition. When models are pure direct-prediction models, future states cannot be predicted. See example below for more information. -* :download:`examples.direct_model <../../prog_models/examples/direct_model.py>` +* :download:`examples.direct_model <../../progpy/examples/direct_model.py>` .. automodule:: direct_model Using Data @@ -345,9 +345,9 @@ Using Data Wether you're using :term:`data-driven`, :term:`physics-based`, expert knowledge, or some hybrid approach, building and validating a model requires data. In the case of data-driven approaches, data is used to train and validate the model. In the case of physics-based, data is used to estimate parameters (see `Parameter Estimation`) and validate the model. -ProgPy includes some example datasets. See `ProgPy Datasets `_ and the example below for details. +ProgPy includes some example datasets. See `ProgPy Datasets `_ and the example below for details. -* :download:`examples.dataset <../../prog_models/examples/dataset.py>` +* :download:`examples.dataset <../../progpy/examples/dataset.py>` .. automodule:: dataset .. note:: To use the dataset feature, you must install the requests package. @@ -355,42 +355,42 @@ ProgPy includes some example datasets. See `ProgPy Datasets `__. The examples below illustrate use of some of the models provided in the :py:mod:`prog_models.models` module. +For details on the included models see `Included Models `__. The examples below illustrate use of some of the models provided in the :py:mod:`progpy.models` module. -* :download:`examples.sim <../../prog_models/examples/sim.py>` +* :download:`examples.sim <../../progpy/examples/sim.py>` .. automodule:: sim -* :download:`examples.sim_battery_eol <../../prog_models/examples/sim_battery_eol.py>` +* :download:`examples.sim_battery_eol <../../progpy/examples/sim_battery_eol.py>` .. automodule:: sim_battery_eol -* :download:`examples.sim_pump <../../prog_models/examples/sim_pump.py>` +* :download:`examples.sim_pump <../../progpy/examples/sim_pump.py>` .. automodule:: sim_pump -* :download:`examples.sim_valve <../../prog_models/examples/sim_valve.py>` +* :download:`examples.sim_valve <../../progpy/examples/sim_valve.py>` .. automodule:: sim_valve -* :download:`examples.sim_powertrain <../../prog_models/examples/sim_powertrain.py>` +* :download:`examples.sim_powertrain <../../progpy/examples/sim_powertrain.py>` .. automodule:: sim_powertrain -* :download:`examples.sim_dcmotor_singlephase <../../prog_models/examples/sim_dcmotor_singlephase.py>` +* :download:`examples.sim_dcmotor_singlephase <../../progpy/examples/sim_dcmotor_singlephase.py>` .. automodule:: sim_dcmotor_singlephase -* :download:`examples.uav_dynamics_model <../../prog_models/examples/uav_dynamics_model.py>` +* :download:`examples.uav_dynamics_model <../../progpy/examples/uav_dynamics_model.py>` .. automodule:: uav_dynamics_model Simulation ---------------------------- -One of the most basic of functions using a model is simulation. Simulation is the process of predicting the evolution of system :term:`state` with time, given a specific :term:`future load` profile. Unlike full prognostics, simulation does not include uncertainty in the state and other product (e.g., :term:`output`) representation. For a prognostics model, simulation is done using the :py:meth:`prog_models.PrognosticsModel.simulate_to` and :py:meth:`prog_models.PrognosticsModel.simulate_to_threshold` methods. +One of the most basic of functions using a model is simulation. Simulation is the process of predicting the evolution of system :term:`state` with time, given a specific :term:`future load` profile. Unlike full prognostics, simulation does not include uncertainty in the state and other product (e.g., :term:`output`) representation. For a prognostics model, simulation is done using the :py:meth:`progpy.PrognosticsModel.simulate_to` and :py:meth:`progpy.PrognosticsModel.simulate_to_threshold` methods. .. role:: pythoncode(code) :language: python .. dropdown:: Saving results - :py:meth:`prog_models.PrognosticsModel.simulate_to` and :py:meth:`prog_models.PrognosticsModel.simulate_to_threshold` return the inputs, states, outputs, and event states at various points in the simulation. Returning these values for every timestep would require a lot of memory, and is not necessary for most use cases, so ProgPy provides an ability for users to specify what data to save. + :py:meth:`progpy.PrognosticsModel.simulate_to` and :py:meth:`progpy.PrognosticsModel.simulate_to_threshold` return the inputs, states, outputs, and event states at various points in the simulation. Returning these values for every timestep would require a lot of memory, and is not necessary for most use cases, so ProgPy provides an ability for users to specify what data to save. There are two formats to specify what data to save: the ``save_freq`` and ``save_pts`` arguments, described below @@ -424,12 +424,12 @@ One of the most basic of functions using a model is simulation. Simulation is th For more details on dynamic step sizes, see the following example: - * :download:`examples.dynamic_step_size <../../prog_models/examples/dynamic_step_size.py>` + * :download:`examples.dynamic_step_size <../../progpy/examples/dynamic_step_size.py>` .. automodule:: dynamic_step_size .. dropdown:: Integration Methods - Simulation is essentially the process of integrating the model forward with time. By default, simple euler integration is used to propogate the model forward. Advanced users can change the numerical integration method to affect the simulation quality and runtime. This is done using the ``integration_method`` argument in :py:meth:`prog_models.PrognosticsModel.simulate_to_threshold` and :py:meth:`prog_models.PrognosticsModel.simulate_to`. + Simulation is essentially the process of integrating the model forward with time. By default, simple euler integration is used to propogate the model forward. Advanced users can change the numerical integration method to affect the simulation quality and runtime. This is done using the ``integration_method`` argument in :py:meth:`progpy.PrognosticsModel.simulate_to_threshold` and :py:meth:`progpy.PrognosticsModel.simulate_to`. For example, users can use the commonly-used Runge Kutta 4 numerical integration method using the following method call for model m: @@ -439,7 +439,7 @@ One of the most basic of functions using a model is simulation. Simulation is th .. dropdown:: Eval Points - Sometimes users would like to ensure that simulation hits a specific point exactly, regardless of the step size (``dt``). This can be done using the ``eval_pts`` argument in :py:meth:`prog_models.PrognosticsModel.simulate_to_threshold` and :py:meth:`prog_models.PrognosticsModel.simulate_to`. This argument takes a list of times at which simulation should include. For example, for simulation to evaluate at 10 and 20 seconds, use the following method call for model m: + Sometimes users would like to ensure that simulation hits a specific point exactly, regardless of the step size (``dt``). This can be done using the ``eval_pts`` argument in :py:meth:`progpy.PrognosticsModel.simulate_to_threshold` and :py:meth:`progpy.PrognosticsModel.simulate_to`. This argument takes a list of times at which simulation should include. For example, for simulation to evaluate at 10 and 20 seconds, use the following method call for model m: .. code-block:: python @@ -461,13 +461,13 @@ One of the most basic of functions using a model is simulation. Simulation is th Use of simulation is described further in the following examples: -* :download:`examples.sim <../../prog_models/examples/sim.py>` +* :download:`examples.sim <../../progpy/examples/sim.py>` .. automodule:: sim -* :download:`examples.noise <../../prog_models/examples/noise.py>` +* :download:`examples.noise <../../progpy/examples/noise.py>` .. automodule:: noise -* :download:`examples.future_loading <../../prog_models/examples/future_loading.py>` +* :download:`examples.future_loading <../../progpy/examples/future_loading.py>` .. automodule:: future_loading Parameter Estimation @@ -477,7 +477,7 @@ Parameter estimation is an important step in prognostics. Parameter estimation i Sometimes model parameters are directly measurable (e.g., dimensions of blades on rotor). For these parameters, estimating them is a simple act of direct measurement. For parameters that cannot be directly measured, they're typically estimated using observed data. -Generally, parameter estimation is done by tuning the parameters of the model so that simulation best matches the behavior observed in some available data. In ProgPy, this is done using the :py:meth:`prog_models.PrognosticsModel.estimate_params` method. This method takes :term:`input` and :term:`output` data from one or more runs, and uses scipy.optimize.minimize function to estimate the parameters of the model. +Generally, parameter estimation is done by tuning the parameters of the model so that simulation best matches the behavior observed in some available data. In ProgPy, this is done using the :py:meth:`progpy.PrognosticsModel.estimate_params` method. This method takes :term:`input` and :term:`output` data from one or more runs, and uses scipy.optimize.minimize function to estimate the parameters of the model. .. code-block:: python @@ -486,7 +486,7 @@ Generally, parameter estimation is done by tuning the parameters of the model so See the example below for more details -* :download:`examples.param_est <../../prog_models/examples/param_est.py>` +* :download:`examples.param_est <../../progpy/examples/param_est.py>` .. automodule:: param_est .. admonition:: Note @@ -505,12 +505,12 @@ Results of a simulation can be visualized using the plot method. For example: >>> results.outputs.plot() >>> results.states.plot() -See :py:meth:`prog_models.sim_result.SimResult.plot` for more details on plotting capabilities +See :py:meth:`progpy.sim_result.SimResult.plot` for more details on plotting capabilities Combination Models ---------------------------- -There are two methods in prog_models through which multiple models can be combined and used together: composite models and ensemble models, described below. +There are two methods in progpy through which multiple models can be combined and used together: composite models and ensemble models, described below. .. tabs:: @@ -530,7 +530,7 @@ There are two methods in prog_models through which multiple models can be combin For more information, see the example below: - * :download:`examples.composite_model <../../prog_models/examples/composite_model.py>` + * :download:`examples.composite_model <../../progpy/examples/composite_model.py>` .. tab:: Ensemble models @@ -545,18 +545,18 @@ There are two methods in prog_models through which multiple models can be combin For more information, see the example below: - * :download:`examples.ensemble <../../prog_models/examples/ensemble.py>` + * :download:`examples.ensemble <../../progpy/examples/ensemble.py>` Other Examples ---------------------------- -* :download:`examples.benchmarking <../../prog_models/examples/benchmarking.py>` +* :download:`examples.benchmarking <../../progpy/examples/benchmarking.py>` .. automodule:: benchmarking -* :download:`examples.sensitivity <../../prog_models/examples/sensitivity.py>` +* :download:`examples.sensitivity <../../progpy/examples/sensitivity.py>` .. automodule:: sensitivity -* :download:`examples.serialization <../../prog_models/examples/serialization.py>` +* :download:`examples.serialization <../../progpy/examples/serialization.py>` .. automodule:: serialization Tips diff --git a/sphinx-config/prog_server_guide.rst b/sphinx-config/prog_server_guide.rst index 3c3d766..e107981 100644 --- a/sphinx-config/prog_server_guide.rst +++ b/sphinx-config/prog_server_guide.rst @@ -8,11 +8,11 @@ prog_server Guide -The Prognostics As-A-Service (PaaS) Sandbox (a.k.a., prog_server) is a simplified implementation of a Service-Oriented Architecture (SOA) for performing prognostics (estimation of time until events and future system states) of engineering systems. The PaaS Sandbox is a wrapper around the :ref:`Prognostics Algorithms Package ` and :ref:`Prognostics Models Package `, allowing one or more users to access the features of these packages through a REST API. The package is intended to be used as a research tool to prototype and benchmark Prognostics As-A-Service (PaaS) architectures and work on the challenges facing such architectures, including Generality, Communication, Security, Environmental Complexity, Utility, and Trust. +The Prognostics As-A-Service (PaaS) Sandbox (a.k.a., prog_server) is a simplified implementation of a Service-Oriented Architecture (SOA) for performing prognostics (estimation of time until events and future system states) of engineering systems. The PaaS Sandbox is a wrapper around the ProgPy package, allowing one or more users to access the features of these packages through a REST API. The package is intended to be used as a research tool to prototype and benchmark Prognostics As-A-Service (PaaS) architectures and work on the challenges facing such architectures, including Generality, Communication, Security, Environmental Complexity, Utility, and Trust. The PaaS Sandbox is actually two packages, prog_server and prog_client. The prog_server package is a prognostics server that provides the REST API. The prog_client package is a python client that provides functions to interact with the server via the REST API. -prog_server uses the :ref:`Prognostics Algorithms Package ` and :ref:`Prognostics Models Package `. +prog_server uses ProgPy. See the :ref:`State Estimation and Prediction Guide ` and :ref:`Modeling and Simulation Guide `. The PaaS Sandbox is a simplified version of the Prognostics As-A-Service Architecture implented as the PaaS/SWS Safety Service software by the NASA System Wide Safety (SWS) project, building upon the original work of the Convergent Aeronautics Solutions (CAS) project. This implementation is a research tool, and is therefore missing important features that should be present in a full implementation of the PaaS architecture such as authentication and persistent state management. @@ -43,7 +43,7 @@ Installing prog_server About --------- -`prog_server` uses the :ref:`Prognostics Algorithms Package ` and :ref:`Prognostics Models Package `. The best way to learn how to use prog_server is to first learn how to use these packages. See :ref:`Prognostics Algorithms Package Docs ` and :ref:`Prognostics Models Package Docs ` for more details. +`prog_server` uses progpy. The best way to learn how to use prog_server is to first learn how to use that package. See :ref:`State Estimation and Prediction Guide ` and :ref:`Modeling and Simulation Guide ` for more details. The PaaS Sandbox is actually two packages, ``prog_server`` and ``prog_client``. The ``prog_server`` package is the server that provides the REST API. The ``prog_client`` package is a python client that uses the REST API (see :py:class:`prog_client.Session`). The ``prog_server`` package is the PaaS Sandbox Server. Once started the server can accept requests from one or more applications requesting prognostics, using its REST API (described in :ref:`prog_server API Reference`). diff --git a/sphinx-config/releases.rst b/sphinx-config/releases.rst index 23c9043..1f066a7 100644 --- a/sphinx-config/releases.rst +++ b/sphinx-config/releases.rst @@ -4,6 +4,25 @@ Release Notes .. .. contents:: .. :backlinks: top +Updates in V1.6 +---------------------- + +progpy +************** +* Combined previous prog_models and prog_algs packages into a single package, progpy. +* Added new MixtureOfExperts model, which combines multiple models of the same system into a single model, where only the best of the comprised models will be used at each timestep. +* Improvements to future load estimation: + + * Added ability to set random seed in GaussianLoadWrapper, allowing for repeatable experiments + * Added wedge noise to GaussianLoadWrapper, this was a frequently requested feature that will increase noise levels as time goes on, representing the increased uncertainty further into the future. + +* Various bug fixes and performance improvements + +prog_server +************ + + + Updates in V1.5 -----------------------