designengrlab/fmdtools

DEPRECATED: System modelling and fault-injection-based resilience assessment in Python

This project has moved!!

Current active development of fmdtools (versions > 0.6.2) is hosted at https://github.com/nasa/fmdtools. This repository is not under active development and is here for archival purposes.

---

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.

Key Features:

• 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 chunk 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 of each

• 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
  • the high-level results of a set of simulations in an FMEA-style table of faults, effects, rates, costs, and overall risk
  • fault injection times, responses, and weightings of a fault injection approach

In the future, we would like to add features for optimization/design exploration, uncertainty quantification, non-deterministic fault propagation, and parallelism.

Finally, 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

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 on these packages:

• networkx
• numpy
• ordered-dict
• matplotlib (for plots)
• pandas (for tables)
• jupyter notebook (for notebooks)
• netgraph (for setting graph node positions)
• ffmpeg (for animations)
• quadpy (for quadrature sampling)
• shapely (for multirotor model)

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

While it is not required to use any of the methods, Jupyter notebook is helpful for and for documenting simulation and analysis of a pre-existing model and required to follow through the provided examples.

Documentation and Examples

An overview of fmdtools is provided in the accomanying paper:

Hulse, D., Walsh, H., Dong, A., Hoyle, C., Tumer, I., Kulkarni, C., & Goebel, K. (2020, September 14). fmdtools: A Fault Propagation Toolkit for Resilience Assessment in Early Design. https://doi.org/10.31224/osf.io/d48k6

Additionally, this repo provides a few resources to get familiar with fmdtools:

• Workshop slides and tutorial in docs.Intro to fmdtools.pptx, pump example/ex_pump.py, and pump example/tutorial_complete.py

• A shorter overview the toolkit methods and structure is provided in docs/overview.

• Some documented examples are provided, including:

  • A baseline example of most provided methods in conceptual design-stage pump system in pump example/ex_pump.py and pump example/Pump Example Notebook.ipynb
  • An case study following the modelling process of going from a less detailed to more detailed model is provided in multirotor example\paper demonstration\Demonstration.ipynb for the design of a multirotor drone.
  • An example replicating previous the simple electric power system implemented in IBFM in the eps example directory, with some basic fault propagation and visualization.
  • An example of modelling a dynamical system (without faults) is shown in the \pandemic example directory, with a reference stand-alone model is provided in simple_model.py and fmd_model.py and fmd_model_script.py showing how one might implement a distributed version of this model in fmdtools.
  • Using the component class to model human interactions with the modelled system in hold-up tank example.

• More detailed documentation for each of the classes/methods/modules is provided and can be viewed by going through the fmdtools source code (or by using help(methodname))

---

Contributors

Daniel Hulse

Hannah Walsh : Network analysis codes

Arpan Biswas : Multirotor optimization codes

Hongyang Zhang : Pandemic model

---

License

MIT

fmdtools's Issues

pip installation does not install netgraph

Need to make sure that netgraph gets installed, otherwise resultdisp modules don't import

Need a smarter way of creating sample approach(es) using operational modes

• Model should incorporate function mode information (where mode is discrete changes in state) to automatically determine the phases of operation
• Fxnblock/Component classes should let one associate failure modes with operational modes in addition to/rather than phases
• Need more infrastructure for modes--visualizations of modes over time (e.g. overlaid on behavior graphs) and just the modes of the system at large

Add in ability to run joint-fault scenarios at different times

• propagate needs a method that simulates arbitrary sets of fault modes (((fxn1, fault1), time1),((fxn2, fault2), time2), etc)

Formalize static/dynamic behavior order

Function execution order should differentiate dynamic behaviors (which should run at the end of each time-step according to specified run order) from static behaviors (which can still run/propagate in an un-directed sense)

Ideally this should result in a time-step running as follows:
1.) Run dynamic behaviors in specified order
2.) Run static behaviors (if any) in specified order, and then execute remaining blocks until it converges (current behavior)

Functions should be given helper methods for this which are called at different times. Ideally allows one to use the current behavior() and condfaults() interfaces while making the default dynbehavior() and statbehavior() (or whatever makes sense)

new netgraph major release

Hi,

I saw on the github dashboard that you are using my package netgraph.

This is a heads up that I just released a new major version. I tried to maintain backwards compatibility as much as possible but I did break it in a few cases. Especially if your code uses either the Graph or InteractiveGraph classes, expect a few changes. Also, I have removed some InteractiveGraph derived variants for the time being, as they seem to be used very little but are a pain to maintain. If that affects you, please let me know, so we can work something out.

Hopefully, you will find that the improvements that I have made are worth any pains that might arise from upgrading. ;-)

Best,
Paul

PS: Feel free to close the issue any time.

mdlhist doesn't form histories of states placed in dictionaries

State return should copy states instead of reference them, when possible

graph.set_pos() makes it difficult to iteratively change the model structure

current behavior: set_pos always generates new node positions randomly
desired behavior: ability to re-use node positions from a previous version of the model

Empty model graphs don't return figures

modify line 170 to return figures/axes when desired?

Suggestion.

I notice you have user modelling in your approach.

Have you considered using tool such as cogulator in parallel to capture the analysis if users and then perhaps parse cogulator files into your human component representation?

Need to be able to specify run order

Need to be able to specify run order of modules for dynamic models.

Recommend changing mdl.timelyfxns and activefxns in propagate to an ordered dict (or similar).