fmdtools 1.3.3

System resilience modelling, simulation, and assessment in Python

fmdtools (Fault Model Design tools) is a toolkit for modelling system resilience in the early design phase. With it, one can simulate the effects of faults in a system to build resilience into the system design at a high level. To achieve this, fmdtools provides a Python-based design environment where one can represent the system in a model, simulate the resilience of the model to faults, and analyze the resulting model responses to iteratively improve the resilience of the design.

For full reference and examples, please see the documentation page.

Overview

The main impetus for the development of the fmdtools project was a lack existing tools to enable early function-based fault simulation for early functional hazard assessment. Researchers thus had to re-implement modelling, simulation, and analysis approaches for each new case study or methodological improvement. The fmdtools resolves this problem by separating resilience modelling, simulation, and analysis constructs from the model under study, enabling reuse of methodologies between case studies. Towards this end, the fmdtools package provides three major pieces of functionality:

1. Model definition constructs which enable systematic early specification of the high level structure and behaviors of a system with concise syntax (fmdtools.modeldef).

2. Simulation methods which enable the quantification of system performance and propagation of hazards over a wide range of operational scenarios and model types (fmdtools.faultsim).

3. Analysis methods for quantifying resilience and summarizing and visualizing behaviors and properties of interest (fmdtools.resultdisp).

Key Features

fmdtools was developed with a number of unique features that differentiate it from existing safety/resilience simulation tools.

• fmdtools uses an object-oriented undirected graph-based model representation which enables arbitrary propagation of flow states through a model graph. As opposed to a procedural directed graph-based model representation (a typical strategy for developing fault models in code in which each function or component is represented by a method, the inputs and outputs are which are connected with connected functions/components in a larger model method), this enables one to:

  • propagate behaviors in multiple directions in a model graph, e.g., closing a valve will not just reduce flow in the downstream pipe but also increase pressure in upstream pipes.

  • define the data structures defining a function/component (e.g. states, faults, timed events) with the behavioral methods in a single logical structure that can be re-used and modified for similar components and methods (that is, a class, instead of a set of unstructured variables and methods)

• fmdtools can represent the system at varying levels of fidelity through the design process so that one can start with a simple model and analysis and make it more detailed as the design is elaborated. A typical process of representing the system (from less to more detail) would involve:

  • Creating a network representation of the model functions and flows to visualize the system and identify structurally-important parts of the model’s causal structure

  • Elaborating the flow attributes and function failure logic in a static propagation to simulate the timeless effects of faults in the model

  • Adding dynamic states and behaviors to the functions as well as a simulation times and operational phases in a dynamic propagation model to simulate the dynamic effects of faults simulated during different time-steps

  • Instantiating functions with component architectures to compare the expected resilience and behaviors of each

  • Defining stochastic behavioral and input parameters to simulate and analyze system resilience throughout the operational envelope

  • Using optimization methods to search the space of potential hazardous scenarios and find the optimal response parameters to mitigate these scenarios

• fmdtools provides convenience methods for quickly visualizing the results of fault simulations with commonly-used Python libraries to enable one to quickly assess:

  • effects of faults on functions and flows in the model graph at a given time-step

  • the behavior of system states over time in nominal and faulty scenarios over a range of operational parameters

  • the effect of model input parameters (e.g., ranges, stochastic inputs) on nominal/faulty operations

  • the high-level results of a set of simulations in an FMEA-style table of faults, effects, rates, costs, and overall risk

  • simulation responses over a range or distribution of model and scenario parameters

An overview of an earlier version of fmdtools (0.6.2) is provided in the paper:

Hulse, D., Walsh, H., Dong, A., Hoyle, C., Tumer, I., Kulkarni, C., & Goebel, K. (2021). fmdtools: A Fault Propagation Toolkit for Resilience Assessment in Early Design. International Journal of Prognostics and Health Management, 12(3).

fmdtools is a research code and is under active development. As a result, Some use-cases may not work as desired and may change. If you find a bug or would like to contribute, contact the contributors.

Getting Started

The latest public version of fmdtools can be downloaded from the fmdtools github repository e.g., using:

git clone https://github.com/nasa/fmdtools.git

For development and use of this version (e.g., for tutorials and models), we recommended then installing this package using pip:

pip install -e /path/to/fmdtools

A version of the fmdtools toolkit can also be installed directly from the PyPI package repository using pip install fmdtools.

Prerequisites

fmdtools requires Python 3 and depends directly on these packages (see requirements.txt):

scipy
tqdm
networkx
numpy
matplotlib
pandas
ordered-set
dill

These packages are optional but recommended to enable specific fmdtools use-cases and to work with examples in the repository:

jupyter notebook                     #(for repository notebooks)
graphviz                                     #(to plot using graphviz options)
pyvis                                        #(for interactive html views of model graphs)
quadpy                                       #(for quadrature sampling)
ffmpeg                                       #(for animations)
shapely                                      #(for multirotor model)
deap                                         #(for optimization of rover faults)
pycallgraph2                         #(for model profiling)

These must be installed (e.g. using pip install packagename or conda install packagename) them before running any of the codes in the repository.

Contributions

fmdtools is developed primarily by the Resilience Analysis and Design research project. External contributions are welcome under a Contributor License Agreement:

• Individual CLA

• Corporate CLA

Contributors

Daniel Hulse : Primary Author and point-of-contact

Lukman Irshad : Action Sequence Graph, Degradation Models, Rover Model, etc

Hannah Walsh : Network Analysis Codes

Sequoia Andrade : Graph visualization graphviz options, Code review

Chris Teubert : Feedback and code review.

Notices:

Released under the NASA Open Source Agreement Version 1.3

Copyright © 2022 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.

Disclaimers

No Warranty: THE SUBJECT SOFTWARE IS PROVIDED “AS IS” WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT “AS IS.”

Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT’S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT’S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT’S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT.