a-earthperson/fault-tree-generator

Stochastic generation of fault trees

Fault Tree Generator

A python utility for parametrically creating and exporting synthetic fault trees of varying complexities.

Table of Contents

• Installation
• Command Line Arguments
• Usage
• Features
• Performance
• Constraints
• Testing
  • Running Tests
  • Test Coverage
  • Continuous Integration
  • Adding New Tests
• License
• Acknowledgments

Installation

To install Fault Tree Generator, you can use pip:

pip install fault-tree-generator

Alternatively, you can clone the repository and install it manually:

git clone https://github.com/arjun372/fault-tree-generator.git
cd fault-tree-generator
python setup.py install

Usage

The Fault Tree Generator can be customized using various command-line arguments. Below is the usage information:

usage: fault-tree-generator [--ft-name NCNAME] [--root NCNAME] [--seed int] [-b int] [-a float] [--weights-g float [float ...]]
                            [--common-b float] [--common-g float] [--parents-b float] [--parents-g float] [-g int] [--max-prob float]
                            [--min-prob float] [--num-house int] [--num-ccf int] [-o path] [--aralia] [--nest]

Utility for creating synthetic fault trees.

options:
  -h, --help                Show this help message and exit
  --ft-name NCNAME          Name for the fault tree (default: "Autogenerated")
  --root NCNAME             Name for the root gate (default: "root")
  --seed int                Seed for the PRNG (default: 123)
  -b, --num-basic int       Number of basic events (default: 100)
  -a, --num-args float      Average number of gate arguments (default: 3.0)
  --weights-g float [...]   Weights for [AND, OR, K/N, NOT, XOR] gates (default: [1, 1, 0, 0, 0])
  --common-b float          Average percentage of common basic events per gate (default: 0.1)
  --common-g float          Average percentage of common gates per gate (default: 0.1)
  --parents-b float         Average number of parents for common basic events (default: 2)
  --parents-g float         Average number of parents for common gates (default: 2)
  -g, --num-gate int        Number of gates (overrides parents-b/g and common-b/g if set) (default: 0)
  --max-prob float          Maximum probability for basic events (default: 0.1)
  --min-prob float          Minimum probability for basic events (default: 0.01)
  --num-house int           Number of house events (default: 0)
  --num-ccf int             Number of CCF groups (default: 0)
  -o, --out path            File to write the fault tree (default: standard output)
  --aralia                  Apply the Aralia format to the output (default: False)
  --nest                    Nest NOT connectives in Boolean formulae (default: False)

To generate a fault tree with default settings, simply run:

fault-tree-generator

For a more customized fault tree, you can use the command-line arguments to specify various options. Here are a few examples:

To specify a name for the fault tree and the root gate, and to write the output to a file:

fault-tree-generator --ft-name "ExampleTree" --root "MainGate" --out "example_tree.xml"

To set a custom seed for the pseudo-random number generator and adjust the number of basic events:

fault-tree-generator --seed 456 --num-basic 150

To use custom weights for the gate types and specify the maximum and minimum probabilities for basic events:

fault-tree-generator --weights-g 2 1 0.5 0 0 --max-prob 0.05 --min-prob 0.001

Features

• Generation of synthetic fault trees based on user-defined parameters.
• Exporting fault trees to various formats for further analysis, including boolean expression strings with topologically sorted elements.
• A user-friendly command-line interface.

Performance

The time complexity for generating fault trees is approximately:

O(N) + O((N/Ratio)^2 * exp(-NumArgs/Ratio)) + O(CommonG * exp(CommonB))

Where:

• N is the number of basic events,
• Ratio is N / num_gate,
• NumArgs is the average number of gate arguments,
• CommonG is the average percentage of common gates per gate,
• CommonB is the average percentage of common basic events per gate.

Constraints

When generating a fault tree with both the number of basic events and the number of gates constrained, other user-set factors may be affected. However, if the number of gates is not constrained by the user, all other user-defined factors are preserved and utilized as specified.

Testing

To ensure the reliability and stability of the Fault Tree Generator, a suite of tests has been provided. These tests cover the core functionality of the package, including the generation of fault trees, event handling, and probability calculations.

Running Tests

To run the tests, you will need to have pytest installed. If you have not already installed the development dependencies, you can do so by running:

pip install -e '.[dev]'

Once you have the necessary dependencies, you can run the tests using the following command:

pytest

Test Coverage

To measure the test coverage of the Fault Tree Generator, we use the pytest-cov plugin. This tool allows us to generate reports that show which parts of the code are covered by tests and which are not, helping to identify areas that may need additional testing.

To run the tests with coverage reporting, use the following command:

pytest --cov=fault_tree --cov-report term-missing

This will output the coverage report to the terminal, including information on any lines of code that are missing coverage. For a more detailed HTML report that you can view in a web browser, use:

pytest --cov=fault_tree --cov-report html

The HTML report will be saved in a directory named htmlcov. Open htmlcov/index.html in your web browser to view it.

Continuous Integration

Continuous integration is set up to run tests automatically on every push and pull request. This ensures that new changes do not break existing functionality.

Adding New Tests

Contributors are encouraged to add tests for new features or to improve existing tests. When contributing new code, please include tests that cover the new functionality and ensure that all tests pass before submitting a pull request.

License

Fault Tree Generator is released under the MIT License. See the LICENSE file for more information.

Acknowledgments

Acknowledge any individuals or organizations that have contributed to the project.

• Olzhas Rakhimov for writing the initial scripts