spicefault 0.1.0__tar.gz

spicefault-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+
+# SPICE scratch files
+*.raw
+*.log
+
+# Editors / OS
+.DS_Store
+.vscode/
+.idea/
+
+# Datasets written by the examples
+examples/**/output/
+
+# Datasets of the campaigns (large; regenerated with docs/RUNBOOK.md)
+data/
+
+# Built documentation
+site/
+
+# Coverage
+.coverage
+coverage.xml

spicefault-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/spec/v2.0.0.html). Until version 1.0 the
+public interface may change between minor versions.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-04
+
+First version.
+
+### Added
+
+- `Circuit`: a SPICE netlist seen as components, nodes and parameters.
+- Fault types `OpenCircuit`, `ShortCircuit`, `LeakageFault`, `ParametricFault` and
+  `CompositeFault`, each a list of primitive netlist changes with a record;
+  `FaultSeverity`, `FaultSet`, and `FaultUniverse` with its coverage matrix.
+- Variations of the healthy population (tolerance, normal, log-normal, uniform,
+  log-uniform, fixed, custom, joint) and `VariationSet`.
+- `OperatingCondition`, applied after the fault.
+- `Simulator` with an ngspice backend, and `SimulationResult` with an explicit status.
+- `Experiment` (in memory) and `FaultCampaign` (to disk, in chunks, resumable, one
+  process per folder), with three seeding schemes.
+- `Measurement` and `Waveform`.
+- `Dataset`, `Manifest` and `Provenance`: integrity, traceability and reproduction of
+  a campaign from its folder.
+- `ReliabilityAnalysis`: detection probability, standardised shift, AUC, failure
+  probability, diagnostic coverage, severity response, robustness against tolerance,
+  dependence on operating conditions, separability and ambiguity.
+
+[Unreleased]: https://github.com/telmomm/spicefault/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/telmomm/spicefault/releases/tag/v0.1.0

spicefault-0.1.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "spicefault: reproducible SPICE-based fault injection and reliability assessment of electronic circuits"
+type: software
+authors:
+  - family-names: "Miguel-Medina"
+    given-names: "Telmo"
+repository-code: "https://github.com/telmomm/spicefault"
+url: "https://spicefault.readthedocs.io"
+license: MIT
+version: 0.1.0
+date-released: "2026-10-04"
+keywords:
+  - SPICE
+  - ngspice
+  - fault injection
+  - reliability
+  - analog circuits
+  - Monte Carlo

spicefault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telmo Miguel-Medina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spicefault-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: spicefault
+Version: 0.1.0
+Summary: Reproducible SPICE-based fault injection and reliability assessment of electronic circuits
+Project-URL: Homepage, https://github.com/telmomm/spicefault
+Project-URL: Documentation, https://spicefault.readthedocs.io
+Project-URL: Repository, https://github.com/telmomm/spicefault
+Project-URL: Issues, https://github.com/telmomm/spicefault/issues
+Project-URL: Changelog, https://github.com/telmomm/spicefault/blob/main/CHANGELOG.md
+Author: Telmo Miguel-Medina
+License: MIT
+License-File: LICENSE
+Keywords: Monte Carlo,SPICE,analog circuits,fault diagnosis,fault injection,ngspice,reliability,testability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: pyarrow>=15
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# spicefault
+
+[![PyPI](https://img.shields.io/pypi/v/spicefault)](https://pypi.org/project/spicefault/)
+[![Python](https://img.shields.io/pypi/pyversions/spicefault)](https://pypi.org/project/spicefault/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/telmomm/spicefault/blob/main/LICENSE)
+[![CI](https://github.com/telmomm/spicefault/actions/workflows/ci.yml/badge.svg)](https://github.com/telmomm/spicefault/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/spicefault/badge/?version=latest)](https://spicefault.readthedocs.io/en/latest/)
+[![Quality gate](https://sonarcloud.io/api/project_badges/measure?project=telmomm_spicefault&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=telmomm_spicefault)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=telmomm_spicefault&metric=coverage)](https://sonarcloud.io/summary/new_code?id=telmomm_spicefault)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/telmomm/spicefault/main?labpath=examples%2Fquickstart.ipynb)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+<!-- DOI: after the first release archived by Zenodo, add its badge here:
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX) -->
+
+**Reproducible SPICE-based fault injection and reliability assessment of electronic
+circuits.**
+
+`spicefault` is a Python framework for studying how a circuit behaves when something
+in it fails, under realistic component tolerances and operating conditions. You
+describe a circuit, the faults it can have and how its good units vary; the framework
+simulates the campaign with [ngspice](https://ngspice.sourceforge.io/), keeps a record
+of every sample, and computes what the results say: which faults are detected, which
+are confused with each other, and how tolerance erodes both.
+
+It is not another Python interface to SPICE. It works one level above: the fault, the
+normal variation of the components and the operating conditions are defined
+explicitly, simulated as one experiment, and recorded so that every sample can be
+traced and simulated again.
+
+**[Documentation](https://spicefault.readthedocs.io)** ·
+**[Examples](https://github.com/telmomm/spicefault/tree/main/examples/)** ·
+**[Changelog](https://github.com/telmomm/spicefault/blob/main/CHANGELOG.md)**
+
+## Install
+
+```bash
+pip install spicefault
+```
+
+and ngspice, which does the simulations (`brew install ngspice` on macOS,
+`sudo apt install ngspice` on Debian and Ubuntu). Python 3.10 or later.
+
+## A first experiment
+
+A resistive divider with 1 % resistors, two faults and two operating conditions:
+
+```python
+from spicefault import Circuit, Experiment, OperatingCondition, SimulationConfig
+from spicefault.faults import OpenCircuit, ParametricFault
+from spicefault.variation import ToleranceVariation
+
+circuit = Circuit("""divider
+V1 in 0 dc 1
+R1 in out 10k
+R2 out 0 10k
+.end
+""", name="divider")
+
+experiment = Experiment(
+    circuit,
+    config=SimulationConfig(analyses=("op",), outputs=("v(out)",)),
+    faults=[OpenCircuit("R2"), ParametricFault("R1", deviation=0.2)],
+    variations=[ToleranceVariation("R1", 0.01), ToleranceVariation("R2", 0.01)],
+    conditions=[
+        OperatingCondition(),
+        OperatingCondition("low supply", settings={("V1", "dc"): 0.5}),
+    ],
+    samples=100,
+    seed=42,
+)
+result = experiment.run(workers=4)
+
+print(result.status_counts())      # {'SUCCESS': 600}
+table = result.to_frame()          # sample definitions, status and realised values
+vout = [s.result.plot("op")["v(out)"][0] for s in result]
+```
+
+- The component values are drawn first, the fault is injected into that drawn
+  circuit, and then the operating condition is set.
+- Each sample has its own random stream: the result is the same on one worker or on
+  sixteen.
+- A simulation that fails stays in the results, with a status and a message.
+
+## What it gives you
+
+| | |
+|---|---|
+| **Faults as objects** | Open, short, leakage, parametric and composite faults, each a recorded change of the netlist with a physical interpretation |
+| **An auditable fault list** | A fault universe generated from rules, a coverage matrix, and a reason for every fault left out |
+| **A healthy population** | Tolerance, normal, log-normal, uniform and joint distributions, kept apart from the faults |
+| **Reproducible campaigns** | To disk in chunks, resumable; the same samples for any number of workers; five explicit simulation statuses |
+| **Datasets that stand on their own** | Integrity check, provenance of each sample, the netlist that was simulated for it, and simulation again from the folder |
+| **Reliability metrics with intervals** | Detection probability, diagnostic coverage, minimum detectable deviation, robustness against tolerance, ambiguity groups |
+
+```python
+from spicefault import FaultCampaign, Dataset
+from spicefault.reliability import ReliabilityAnalysis
+
+campaign = FaultCampaign(circuit, faults, out_dir="data/study", samples_per_fault=200,
+                         healthy_samples=2000, variations=population, config=config,
+                         measurements=measurements, seed=1)
+campaign.run(workers=8)                       # resumes if it was interrupted
+
+dataset = Dataset("data/study")
+dataset.verify()                              # the files match their fingerprints
+dataset.provenance(1234)                      # everything about one sample
+dataset.reproduce(n=50)                       # simulate again, compare with what is stored
+
+analysis = ReliabilityAnalysis.from_dataset("data/study")
+analysis.detectability(alpha=0.01).table      # per fault: P(detect) and its interval
+analysis.minimum_detectable()                 # smallest deviation that is visible
+analysis.ambiguity()                          # faults that cannot be told apart
+```
+
+## Examples
+
+Runnable scripts in [examples/](https://github.com/telmomm/spicefault/tree/main/examples/), the same ones shown in the documentation:
+
+| Script | What it shows |
+|---|---|
+| `01_quickstart.py` | A circuit, a fault, a simulation, a small experiment |
+| `02_faults_and_coverage.py` | Fault types, a fault universe from rules, coverage |
+| `03_campaign.py` | A campaign to disk, interrupted and resumed |
+| `04_dataset.py` | Integrity, provenance and reproduction of a dataset |
+| `05_reliability.py` | Detection, minimum detectable deviation, ambiguity, tolerance |
+| `06_operating_conditions.py` | The same circuits under several conditions |
+| `07_custom.py` | Your own distributions and measurements |
+
+```bash
+git clone https://github.com/telmomm/spicefault.git && cd spicefault
+pip install -e .
+python examples/01_quickstart.py
+```
+
+Or try the quickstart in the browser, without installing anything, with the Binder
+badge above.
+
+## Limits
+
+- One simulator: ngspice.
+- One fault per sample; faults do not change during a simulation.
+- Faults act on the top level of the netlist. A component inside a subcircuit is
+  reached through the parameters of its instance.
+- Opens and shorts are finite resistances, recorded with the fault.
+- Simulated evidence does not replace testing hardware.
+
+## Project
+
+The library is the instrument of a research project on reproducible fault-injection
+experiments. Its definitions and plan are part of the documentation:
+[fault model](https://github.com/telmomm/spicefault/blob/main/docs/FAULT_MODEL.md),
+[reliability metrics](https://github.com/telmomm/spicefault/blob/main/docs/RELIABILITY_METRICS.md),
+[scientific scope](https://github.com/telmomm/spicefault/blob/main/docs/SCIENTIFIC_SCOPE.md),
+[experiment plan](https://github.com/telmomm/spicefault/blob/main/docs/EXPERIMENT_PLAN.md),
+[related work](https://github.com/telmomm/spicefault/blob/main/docs/RELATED_WORK.md) and
+[comparison with other tools](https://github.com/telmomm/spicefault/blob/main/docs/COMPARISON.md).
+The circuits it is validated on are in [validation/](https://github.com/telmomm/spicefault/tree/main/validation/), the benchmarks in
+[benchmarks/](https://github.com/telmomm/spicefault/blob/main/benchmarks/README.md), and the results obtained so far in `results/`.
+
+It was extracted from the simulation code of a study on self-diagnosis of ECG analog
+front-ends
+([ecg-frontend-fault-diagnosis](https://github.com/telmomm/ecg-frontend-fault-diagnosis)),
+which uses it. Nothing in it is specific to that study.
+
+## Contributing
+
+Bug reports and contributions are welcome: see [CONTRIBUTING.md](https://github.com/telmomm/spicefault/blob/main/CONTRIBUTING.md) and
+the [code of conduct](https://github.com/telmomm/spicefault/blob/main/CODE_OF_CONDUCT.md).
+
+## Citing
+
+If you use `spicefault` in your work, please cite it. The citation data are in
+[CITATION.cff](https://github.com/telmomm/spicefault/blob/main/CITATION.cff); GitHub shows them under "Cite this repository".
+
+## Licence
+
+[MIT](https://github.com/telmomm/spicefault/blob/main/LICENSE).

spicefault-0.1.0/README.md

@@ -0,0 +1,177 @@
+# spicefault
+
+[![PyPI](https://img.shields.io/pypi/v/spicefault)](https://pypi.org/project/spicefault/)
+[![Python](https://img.shields.io/pypi/pyversions/spicefault)](https://pypi.org/project/spicefault/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/telmomm/spicefault/blob/main/LICENSE)
+[![CI](https://github.com/telmomm/spicefault/actions/workflows/ci.yml/badge.svg)](https://github.com/telmomm/spicefault/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/spicefault/badge/?version=latest)](https://spicefault.readthedocs.io/en/latest/)
+[![Quality gate](https://sonarcloud.io/api/project_badges/measure?project=telmomm_spicefault&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=telmomm_spicefault)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=telmomm_spicefault&metric=coverage)](https://sonarcloud.io/summary/new_code?id=telmomm_spicefault)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/telmomm/spicefault/main?labpath=examples%2Fquickstart.ipynb)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+<!-- DOI: after the first release archived by Zenodo, add its badge here:
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX) -->
+
+**Reproducible SPICE-based fault injection and reliability assessment of electronic
+circuits.**
+
+`spicefault` is a Python framework for studying how a circuit behaves when something
+in it fails, under realistic component tolerances and operating conditions. You
+describe a circuit, the faults it can have and how its good units vary; the framework
+simulates the campaign with [ngspice](https://ngspice.sourceforge.io/), keeps a record
+of every sample, and computes what the results say: which faults are detected, which
+are confused with each other, and how tolerance erodes both.
+
+It is not another Python interface to SPICE. It works one level above: the fault, the
+normal variation of the components and the operating conditions are defined
+explicitly, simulated as one experiment, and recorded so that every sample can be
+traced and simulated again.
+
+**[Documentation](https://spicefault.readthedocs.io)** ·
+**[Examples](https://github.com/telmomm/spicefault/tree/main/examples/)** ·
+**[Changelog](https://github.com/telmomm/spicefault/blob/main/CHANGELOG.md)**
+
+## Install
+
+```bash
+pip install spicefault
+```
+
+and ngspice, which does the simulations (`brew install ngspice` on macOS,
+`sudo apt install ngspice` on Debian and Ubuntu). Python 3.10 or later.
+
+## A first experiment
+
+A resistive divider with 1 % resistors, two faults and two operating conditions:
+
+```python
+from spicefault import Circuit, Experiment, OperatingCondition, SimulationConfig
+from spicefault.faults import OpenCircuit, ParametricFault
+from spicefault.variation import ToleranceVariation
+
+circuit = Circuit("""divider
+V1 in 0 dc 1
+R1 in out 10k
+R2 out 0 10k
+.end
+""", name="divider")
+
+experiment = Experiment(
+    circuit,
+    config=SimulationConfig(analyses=("op",), outputs=("v(out)",)),
+    faults=[OpenCircuit("R2"), ParametricFault("R1", deviation=0.2)],
+    variations=[ToleranceVariation("R1", 0.01), ToleranceVariation("R2", 0.01)],
+    conditions=[
+        OperatingCondition(),
+        OperatingCondition("low supply", settings={("V1", "dc"): 0.5}),
+    ],
+    samples=100,
+    seed=42,
+)
+result = experiment.run(workers=4)
+
+print(result.status_counts())      # {'SUCCESS': 600}
+table = result.to_frame()          # sample definitions, status and realised values
+vout = [s.result.plot("op")["v(out)"][0] for s in result]
+```
+
+- The component values are drawn first, the fault is injected into that drawn
+  circuit, and then the operating condition is set.
+- Each sample has its own random stream: the result is the same on one worker or on
+  sixteen.
+- A simulation that fails stays in the results, with a status and a message.
+
+## What it gives you
+
+| | |
+|---|---|
+| **Faults as objects** | Open, short, leakage, parametric and composite faults, each a recorded change of the netlist with a physical interpretation |
+| **An auditable fault list** | A fault universe generated from rules, a coverage matrix, and a reason for every fault left out |
+| **A healthy population** | Tolerance, normal, log-normal, uniform and joint distributions, kept apart from the faults |
+| **Reproducible campaigns** | To disk in chunks, resumable; the same samples for any number of workers; five explicit simulation statuses |
+| **Datasets that stand on their own** | Integrity check, provenance of each sample, the netlist that was simulated for it, and simulation again from the folder |
+| **Reliability metrics with intervals** | Detection probability, diagnostic coverage, minimum detectable deviation, robustness against tolerance, ambiguity groups |
+
+```python
+from spicefault import FaultCampaign, Dataset
+from spicefault.reliability import ReliabilityAnalysis
+
+campaign = FaultCampaign(circuit, faults, out_dir="data/study", samples_per_fault=200,
+                         healthy_samples=2000, variations=population, config=config,
+                         measurements=measurements, seed=1)
+campaign.run(workers=8)                       # resumes if it was interrupted
+
+dataset = Dataset("data/study")
+dataset.verify()                              # the files match their fingerprints
+dataset.provenance(1234)                      # everything about one sample
+dataset.reproduce(n=50)                       # simulate again, compare with what is stored
+
+analysis = ReliabilityAnalysis.from_dataset("data/study")
+analysis.detectability(alpha=0.01).table      # per fault: P(detect) and its interval
+analysis.minimum_detectable()                 # smallest deviation that is visible
+analysis.ambiguity()                          # faults that cannot be told apart
+```
+
+## Examples
+
+Runnable scripts in [examples/](https://github.com/telmomm/spicefault/tree/main/examples/), the same ones shown in the documentation:
+
+| Script | What it shows |
+|---|---|
+| `01_quickstart.py` | A circuit, a fault, a simulation, a small experiment |
+| `02_faults_and_coverage.py` | Fault types, a fault universe from rules, coverage |
+| `03_campaign.py` | A campaign to disk, interrupted and resumed |
+| `04_dataset.py` | Integrity, provenance and reproduction of a dataset |
+| `05_reliability.py` | Detection, minimum detectable deviation, ambiguity, tolerance |
+| `06_operating_conditions.py` | The same circuits under several conditions |
+| `07_custom.py` | Your own distributions and measurements |
+
+```bash
+git clone https://github.com/telmomm/spicefault.git && cd spicefault
+pip install -e .
+python examples/01_quickstart.py
+```
+
+Or try the quickstart in the browser, without installing anything, with the Binder
+badge above.
+
+## Limits
+
+- One simulator: ngspice.
+- One fault per sample; faults do not change during a simulation.
+- Faults act on the top level of the netlist. A component inside a subcircuit is
+  reached through the parameters of its instance.
+- Opens and shorts are finite resistances, recorded with the fault.
+- Simulated evidence does not replace testing hardware.
+
+## Project
+
+The library is the instrument of a research project on reproducible fault-injection
+experiments. Its definitions and plan are part of the documentation:
+[fault model](https://github.com/telmomm/spicefault/blob/main/docs/FAULT_MODEL.md),
+[reliability metrics](https://github.com/telmomm/spicefault/blob/main/docs/RELIABILITY_METRICS.md),
+[scientific scope](https://github.com/telmomm/spicefault/blob/main/docs/SCIENTIFIC_SCOPE.md),
+[experiment plan](https://github.com/telmomm/spicefault/blob/main/docs/EXPERIMENT_PLAN.md),
+[related work](https://github.com/telmomm/spicefault/blob/main/docs/RELATED_WORK.md) and
+[comparison with other tools](https://github.com/telmomm/spicefault/blob/main/docs/COMPARISON.md).
+The circuits it is validated on are in [validation/](https://github.com/telmomm/spicefault/tree/main/validation/), the benchmarks in
+[benchmarks/](https://github.com/telmomm/spicefault/blob/main/benchmarks/README.md), and the results obtained so far in `results/`.
+
+It was extracted from the simulation code of a study on self-diagnosis of ECG analog
+front-ends
+([ecg-frontend-fault-diagnosis](https://github.com/telmomm/ecg-frontend-fault-diagnosis)),
+which uses it. Nothing in it is specific to that study.
+
+## Contributing
+
+Bug reports and contributions are welcome: see [CONTRIBUTING.md](https://github.com/telmomm/spicefault/blob/main/CONTRIBUTING.md) and
+the [code of conduct](https://github.com/telmomm/spicefault/blob/main/CODE_OF_CONDUCT.md).
+
+## Citing
+
+If you use `spicefault` in your work, please cite it. The citation data are in
+[CITATION.cff](https://github.com/telmomm/spicefault/blob/main/CITATION.cff); GitHub shows them under "Cite this repository".
+
+## Licence
+
+[MIT](https://github.com/telmomm/spicefault/blob/main/LICENSE).

spicefault-0.1.0/examples/01_quickstart.py

@@ -0,0 +1,54 @@
+"""Quickstart: a circuit, one fault, one simulation; then a small experiment.
+
+    python examples/01_quickstart.py
+"""
+
+from spicefault import Circuit, Experiment, Measurement, SimulationConfig, Simulator
+from spicefault.faults import OpenCircuit, ParametricFault
+from spicefault.variation import ToleranceVariation
+
+# --- a circuit is a SPICE netlist -----------------------------------------------------
+circuit = Circuit(
+    """resistive divider
+V1 in 0 dc 1
+R1 in out 10k
+R2 out 0 10k
+.end
+""",
+    name="divider",
+)
+print("components:", [c.name for c in circuit.components()])
+print("parameters:", circuit.parameters())
+
+# --- a fault changes a copy of the netlist --------------------------------------------
+fault = OpenCircuit("R2")
+netlist = circuit.netlist()
+fault.apply(netlist)
+print("\nnetlist with", fault.fault_id, "injected:")
+print(netlist)
+
+# --- one simulation, with an explicit status -------------------------------------------
+config = SimulationConfig(analyses=("op",), outputs=("v(out)",))
+output = Measurement.value("v(out)", name="vout")
+simulator = Simulator("ngspice")
+for label, text in (("healthy", circuit.to_netlist()), (fault.fault_id, str(netlist))):
+    result = simulator.run(text, config)
+    print(f"{label}: {result.status.value}, vout = {output(result):.4f} V")
+
+# --- an experiment: tolerances, faults, a seed -----------------------------------------
+experiment = Experiment(
+    circuit,
+    config=config,
+    faults=[OpenCircuit("R2"), ParametricFault("R1", deviation=0.2)],
+    variations=[ToleranceVariation("R1", 0.01), ToleranceVariation("R2", 0.01)],
+    measurements=[output],
+    samples=5,
+    seed=42,
+)
+table = experiment.run().to_frame()
+print("\n15 simulations: 5 healthy circuits and 5 of each fault")
+print(table[["fault_id", "replica", "status", "p_R1_value", "p_R2_value", "vout"]].round(4))
+
+# the same seed gives the same circuits, whatever the number of workers
+again = experiment.run().to_frame()
+print("\nsame results when run again:", table["vout"].equals(again["vout"]))

spicefault-0.1.0/examples/02_faults_and_coverage.py

@@ -0,0 +1,75 @@
+"""Faults as objects, a fault universe from rules, and what a campaign covers.
+
+    python examples/02_faults_and_coverage.py
+
+Nothing is simulated here.
+"""
+
+import json
+
+from rc_study import circuit, population
+
+from spicefault.faults import (
+    CompositeFault,
+    Fault,
+    FaultSet,
+    FaultUniverse,
+    LeakageFault,
+    OpenCircuit,
+    ParametricFault,
+    ShortCircuit,
+    leakage_rule,
+    open_rule,
+    parametric_rule,
+    short_rule,
+)
+
+# --- every fault is a list of primitive changes, with a record ------------------------
+faults = FaultSet(
+    [
+        OpenCircuit("R1"),
+        ShortCircuit("C1"),
+        LeakageFault("C1", 1e6, r_min=1e4, r_max=1e8),
+        ParametricFault("R2", deviation=-0.2),
+        # an ageing capacitor: less capacitance and more series resistance, one cause
+        CompositeFault(
+            "capacitor_ageing",
+            [ParametricFault("C1", factor=0.7), OpenCircuit("C1", r_open=50.0)],
+            magnitude=0.3,
+            unit="capacitance loss",
+        ),
+    ]
+)
+for fault in faults:
+    severity = "-" if fault.severity is None else f"{fault.severity.value:.2f}"
+    print(f"{fault.fault_id:28s} type {fault.fault_type:18s} severity {severity}")
+
+print("\nthe record of one fault:")
+record = faults["R2:parametric:-0.2"].metadata()
+print(json.dumps(record, indent=2))
+print("rebuilt from its record, it is the same fault:", Fault.from_metadata(record) == faults[3])
+
+# --- a universe generated from rules ---------------------------------------------------
+universe = FaultUniverse(
+    circuit,
+    [
+        open_rule(),
+        short_rule(),
+        parametric_rule([-0.2, -0.05, 0.05, 0.2]),
+        leakage_rule([1e5, 1e6, 1e7], kinds="C"),
+    ],
+)
+universe.exclude("R2:short", reason="ties the output to ground: same effect as C1:short")
+print(f"\n{len(universe)} fault conditions in the universe, {len(universe.selected())} selected")
+print("\nconditions to simulate, by component and fault type:")
+print(universe.coverage_matrix())
+print("\nleft out, with the reason:")
+print(universe.exclusions().to_string(index=False))
+print(f"\nstructural coverage: {universe.coverage():.0%}")
+print("components outside the fault model:", universe.metadata()["components_without_faults"])
+
+# --- faults that are not faults: inside the tolerance band ----------------------------
+overlap = universe.selected().tolerance_overlap(population, circuit)
+inside = overlap[overlap["inside_fraction"] > 0]
+print("\nparametric faults partly inside the tolerance band of their component:")
+print(inside[["fault_id", "tolerance", "inside_fraction"]].to_string(index=False))