Examples¶

Runnable scripts, in the examples/ folder of the repository. The pages below show the same .py files that the tests run. Each also has a paired, executable notebook in binder/notebooks/; the documentation continues to show the scripts, while Binder opens the notebooks.

git clone https://github.com/telmomm/spicefault.git
cd spicefault
pip install -e .
python examples/01_quickstart.py

Example	Script	Binder notebook	What it shows
Quickstart	`01_quickstart.py`	Open	A circuit from a netlist, one fault injected and simulated, then an experiment of fifteen simulations with tolerances and a seed.
Faults and coverage	`02_faults_and_coverage.py`	Open	Fault types and their records, a fault universe generated from rules, its coverage matrix, the faults left out with their reasons, and the parametric faults that lie inside the tolerance band. Nothing is simulated.
A fault campaign	`03_campaign.py`	Open	660 simulations written to a dataset folder; then the same campaign interrupted after two chunks and resumed, giving an identical dataset.
The dataset	`04_dataset.py`	Open	Integrity check, the provenance of one sample, the netlist that was simulated for it, samples simulated again and compared, and arrays for a classifier.
Reliability analysis	`05_reliability.py`	Open	Detection probability with its interval, the smallest detectable deviation, the faults that look alike, and detection against the tolerance scale.
Operating conditions	`06_operating_conditions.py`	Open	The same drawn circuits under three operating conditions, and the detection of each fault under each.
Custom variation and measurement	`07_custom.py`	Open	Two resistors drawn together with a recorded label, and a measurement defined by a function.
Monte Carlo and yield	`08_monte_carlo.py`	Open	A campaign without faults: the distribution of each measurement with the intervals of its quantiles, and the yield against limits that can be changed without simulating again.

They share one study, defined in examples/rc_study.py: an RC low-pass filter with a resistive load, 18 faults, 1 % resistors and 5 % capacitors.

"""The study the examples share: an RC low-pass filter, its faults and its measurements.

The other examples import this module. Datasets are written under `examples/output/`,
or under the folder named by the SPICEFAULT_EXAMPLES_OUTPUT environment variable.
"""

from __future__ import annotations

import os
from pathlib import Path

from spicefault import Circuit, FaultCampaign, Measurement, SimulationConfig, Waveform
from spicefault.faults import FaultUniverse, open_rule, parametric_rule, short_rule
from spicefault.variation import tolerances

HERE = Path(__file__).parent
OUTPUT = Path(os.environ.get("SPICEFAULT_EXAMPLES_OUTPUT", HERE / "output"))
WORKERS = 2

# 10 kOhm, 100 nF and a 10 kOhm load: 0.5 V/V at DC, corner at 318 Hz
circuit = Circuit.from_netlist(HERE / "filter" / "rc_lowpass.cir")

# every resistor and capacitor can be open, shorted, or off its value
universe = FaultUniverse(
    circuit,
    [open_rule(), short_rule(), parametric_rule([-0.5, -0.2, 0.2, 0.5])],
)

# 1 % resistors, 5 % capacitors
population = tolerances(circuit, {"R": 0.01, "C": 0.05})

# an operating point, a frequency sweep and the response to a pulse
config = SimulationConfig(("op", "ac dec 20 1 1e5", "tran 10u 10m"), outputs=("v(out)",))
measurements = [
    Measurement.value("v(out)", name="dc"),
    Measurement.magnitude("v(out)", 100.0, name="gain_100"),
    Measurement.magnitude("v(out)", 1e3, name="gain_1k"),
    Measurement.phase("v(out)", 1e3, name="phase_1k"),
    Measurement.peak("v(out)", name="peak"),
]
waveform = Waveform("v(out)", fs=10e3, duration=10e-3)


def campaign(name: str = "rc_campaign", tolerance_scale: float = 1.0) -> FaultCampaign:
    """300 healthy circuits and 20 of each of the 18 faults: 660 simulations."""
    return FaultCampaign(
        circuit,
        universe.selected(),
        out_dir=OUTPUT / name,
        samples_per_fault=20,
        healthy_samples=300,
        variations=population.scaled(tolerance_scale),
        config=config,
        measurements=measurements,
        waveform=waveform,
        seed=42,
        seeding="content",
    )

Each takes from a second to about a minute. Datasets are written under examples/output/.

A larger one, examples/filter/reliability.py, runs every metric on the same filter at three tolerance scales, with 15,000 simulations.