spicefault

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, 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 · Examples · Changelog

Install

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:

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

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/, the same ones shown in the documentation:

Open the executable Binder notebooks for the same examples, paired to the .py sources that the documentation includes, or launch one directly:

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, reliability metrics, scientific scope, experiment plan, related work and comparison with other tools. The circuits it is validated on are in validation/, the benchmarks in benchmarks/, 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), which uses it. Nothing in it is specific to that study.

Contributing

Bug reports and contributions are welcome: see CONTRIBUTING.md and the code of conduct.

Citing

If you use spicefault in your work, please cite it. The citation data are in CITATION.cff; GitHub shows them under "Cite this repository".

Evaluation data

The datasets of the campaigns on the validation circuits (validation/), with the results of the experiments and of the benchmarks, are archived on Zenodo: doi:10.5281/zenodo.23322016. That DOI resolves to the latest version; the version made with spicefault 0.4.0 is doi:10.5281/zenodo.23322017.

Licence

MIT.

One exception, in the repository and not in the package: the device models of the regulator of the validation suite (validation/netlists/regulator.cir) are SPICE models of Diodes Incorporated. They are not under the MIT licence: they are copied intact under the notice of their manufacturer, reproduced in that file, which allows their use for research and design only.