spicefault 0.1.0__py3-none-any.whl

spicefault/__init__.py

@@ -0,0 +1,36 @@
+"""Reproducible SPICE-based fault injection and reliability assessment of electronic circuits."""
+
+__version__ = "0.1.0"
+
+from .circuit import Circuit, Component  # noqa: E402
+from .conditions import OperatingCondition  # noqa: E402
+from .dataset import Dataset  # noqa: E402
+from .experiments import Experiment, ExperimentResult, FaultCampaign  # noqa: E402
+from .faults import Fault  # noqa: E402
+from .measurements import Measurement, Waveform  # noqa: E402
+from .simulation import (  # noqa: E402
+    SimulationConfig,
+    SimulationResult,
+    SimulationStatus,
+    Simulator,
+)
+from .variation import VariationSet  # noqa: E402
+
+__all__ = [
+    "Circuit",
+    "Component",
+    "Dataset",
+    "Experiment",
+    "ExperimentResult",
+    "Fault",
+    "FaultCampaign",
+    "Measurement",
+    "OperatingCondition",
+    "SimulationConfig",
+    "SimulationResult",
+    "SimulationStatus",
+    "Simulator",
+    "VariationSet",
+    "Waveform",
+    "__version__",
+]

spicefault/circuit.py

@@ -0,0 +1,76 @@
+"""The circuit under investigation: a SPICE netlist seen as components, nodes and parameters."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .netlist import Netlist
+
+
+@dataclass(frozen=True)
+class Component:
+    name: str
+    kind: str  # SPICE element letter: R, C, L, V, X, ...
+    nodes: tuple[str, ...]  # empty if the terminals of this element type are not known
+    parameters: dict[str, float]  # numeric ones only: `value`, `dc`, instance parameters
+
+
+class Circuit:
+    """A nominal circuit. It is never modified: every simulation works on a copy.
+
+    Only the top level of the netlist is exposed; what is inside a subcircuit is
+    reached through the parameters of its instances.
+    """
+
+    def __init__(self, netlist: str, name: str = "circuit"):
+        self.name = name
+        self._text = netlist
+
+    @classmethod
+    def from_netlist(cls, path: str | Path, name: str | None = None) -> Circuit:
+        path = Path(path)
+        return cls(path.read_text(), name or path.stem)
+
+    def to_netlist(self) -> str:
+        return self._text
+
+    def netlist(self) -> Netlist:
+        """A fresh, editable copy of the netlist."""
+        return Netlist(self._text)
+
+    def components(self) -> list[Component]:
+        net = self.netlist()
+        found = []
+        for name in net.components():
+            try:
+                nodes = tuple(net.nodes(name))
+            except NotImplementedError:
+                nodes = ()
+            found.append(Component(name, name[0].upper(), nodes, net.parameters(name)))
+        return found
+
+    def component(self, name: str) -> Component:
+        for component in self.components():
+            if component.name.lower() == name.lower():
+                return component
+        raise KeyError(f"no component named {name!r}")
+
+    def nodes(self) -> list[str]:
+        return sorted({node for c in self.components() for node in c.nodes})
+
+    def parameters(self) -> dict[tuple[str, str], float]:
+        """(component, parameter) -> nominal value, for every numeric parameter."""
+        return {
+            (c.name, parameter): value
+            for c in self.components()
+            for parameter, value in c.parameters.items()
+        }
+
+    def metadata(self) -> dict:
+        digest = hashlib.sha256(self._text.encode()).hexdigest()
+        return {"circuit": self.name, "netlist_sha256": digest}
+
+    def __repr__(self) -> str:
+        return f"Circuit({self.name!r}, {len(self.components())} components)"

spicefault/conditions/__init__.py

@@ -0,0 +1,5 @@
+"""Operating conditions, kept apart from component uncertainty."""
+
+from .operating import OperatingCondition
+
+__all__ = ["OperatingCondition"]

spicefault/conditions/operating.py

@@ -0,0 +1,42 @@
+"""Conditions under which a circuit operates or is tested."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..netlist import Netlist
+
+
+@dataclass(frozen=True)
+class OperatingCondition:
+    """A named set of deterministic settings, applied after the fault.
+
+    `settings` maps (component, parameter) to an absolute value, for example
+    `{("Vcc", "dc"): 3.0}` for a supply or `{("Rload", "value"): 1e3}` for a load.
+    `temperature` is the simulation temperature in degrees Celsius; it only has an
+    effect on devices whose model depends on temperature.
+    """
+
+    name: str = "nominal"
+    temperature: float | None = None
+    settings: dict[tuple[str, str], float] = field(default_factory=dict)
+
+    def apply(self, netlist: Netlist) -> None:
+        for (component, parameter), value in self.settings.items():
+            netlist.set_parameter(component, parameter, "absolute", value)
+        if self.temperature is not None:
+            netlist.add_directive(f".options temp={float(self.temperature)}")
+
+    def metadata(self) -> dict:
+        return {
+            "name": self.name,
+            "temperature": self.temperature,
+            "settings": [
+                {"component": c, "parameter": p, "value": v} for (c, p), v in self.settings.items()
+            ],
+        }
+
+    @classmethod
+    def from_metadata(cls, record: dict) -> OperatingCondition:
+        settings = {(s["component"], s["parameter"]): s["value"] for s in record["settings"]}
+        return cls(record["name"], record["temperature"], settings)

spicefault/dataset/__init__.py

@@ -0,0 +1,19 @@
+"""Dataset on disk: one of the representations of the results of a campaign."""
+
+from .dataset import Dataset, Provenance
+from .manifest import MANIFEST, Manifest, file_record
+from .store import METADATA, SAMPLES, WAVEFORMS, assemble, load_dataset, load_metadata
+
+__all__ = [
+    "MANIFEST",
+    "METADATA",
+    "SAMPLES",
+    "WAVEFORMS",
+    "Dataset",
+    "Manifest",
+    "Provenance",
+    "assemble",
+    "file_record",
+    "load_dataset",
+    "load_metadata",
+]

spicefault/dataset/dataset.py

@@ -0,0 +1,289 @@
+"""The dataset of a campaign as an object: traceable, verifiable and reproducible."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable, Sequence
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from ..circuit import Circuit
+from ..conditions import OperatingCondition
+from ..faults import FaultSet
+from ..variation import VariationSet
+from .manifest import Manifest
+from .store import SAMPLES, WAVEFORMS, load_metadata
+
+CIRCUIT_FILE = "circuit.cir"
+HEALTHY_ID = "healthy"
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """Everything that identifies one sample and what produced it."""
+
+    sample_id: int
+    seed: int
+    seeding: str
+    seed_key: str
+    circuit: str
+    netlist_sha256: str
+    fault_id: str
+    fault_type: str
+    fault_location: str
+    fault_magnitude: float | None
+    fault_severity: float | None
+    condition: str
+    status: str
+    message: str
+    simulator: str
+    simulator_version: str
+    spicefault_version: str
+    parameters: dict[str, float]
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class Dataset:
+    """A dataset folder written by `FaultCampaign`.
+
+    `samples` has one row per simulation, failed ones included; `waveforms`, if any,
+    is aligned with it row by row. `metadata` is the definition of the experiment and
+    `manifest` the record of the run.
+    """
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.manifest = Manifest.read(self.path)
+        self.metadata = load_metadata(self.path)
+        self.samples = pd.read_parquet(self.path / SAMPLES)
+        file = self.path / WAVEFORMS
+        self.waveforms = np.load(file, mmap_mode="r") if file.exists() else None
+        columns = self.manifest.summary.get("columns", {})
+        self.features: list[str] = list(columns.get("measurements", []))
+        self.labels: list[str] = list(columns.get("labels", []))
+        self.parameters: dict[str, tuple[str, str]] = {
+            column: tuple(target) for column, target in columns.get("parameters", {}).items()
+        }
+
+    def __len__(self) -> int:
+        return len(self.samples)
+
+    def __repr__(self) -> str:
+        return (
+            f"Dataset({str(self.path)!r}: {len(self)} samples, "
+            f"{len(self.metadata['faults'])} faults, {len(self.features)} measurements)"
+        )
+
+    @property
+    def ok(self) -> np.ndarray:
+        """True for the samples whose simulation gave a usable result."""
+        return self.samples["sim_ok"].to_numpy(dtype=bool)
+
+    @property
+    def circuit(self) -> Circuit:
+        return Circuit((self.path / CIRCUIT_FILE).read_text(), self.metadata["circuit"])
+
+    @property
+    def faults(self) -> FaultSet:
+        return FaultSet.from_metadata(self.metadata["faults"])
+
+    # --- integrity ----------------------------------------------------------------------
+
+    def verify(self) -> list[str]:
+        """Problems with the files or their consistency; an empty list if there are none.
+
+        The files must match the fingerprints of the manifest, the table must have one
+        row per planned sample, and failed samples must carry no result.
+        """
+        problems = self.manifest.verify(self.path)
+        df = self.samples
+        if len(df) != self.manifest.n_samples:
+            problems.append(f"{len(df)} rows, the manifest says {self.manifest.n_samples}")
+        if list(df["sample_id"]) != list(range(len(df))):
+            problems.append("sample_id is not the row number")
+        netlist = (self.path / CIRCUIT_FILE).read_bytes()
+        if hashlib.sha256(netlist).hexdigest() != self.metadata["netlist_sha256"]:
+            problems.append(f"{CIRCUIT_FILE} is not the netlist of the experiment")
+        defined = {HEALTHY_ID, *(f["fault_id"] for f in self.metadata["faults"])}
+        unknown = set(df["fault_id"]) - defined
+        if unknown:
+            problems.append(f"faults not defined in the metadata: {sorted(unknown)}")
+        ok = self.ok
+        if self.features and not np.isfinite(df.loc[ok, self.features].to_numpy(float)).all():
+            problems.append("a successful sample has a measurement that is not finite")
+        if self.features and df.loc[~ok, self.features].notna().any().any():
+            problems.append("a failed sample has a measurement")
+        if self.waveforms is not None:
+            if len(self.waveforms) != len(df):
+                problems.append("waveforms and samples have different lengths")
+            elif np.isnan(self.waveforms[ok]).any() or not np.isnan(self.waveforms[~ok]).all():
+                problems.append("waveforms do not match the status of the samples")
+        return problems
+
+    # --- traceability -------------------------------------------------------------------
+
+    def _row(self, sample_id: int) -> pd.Series:
+        row = self.samples.iloc[sample_id]
+        if row["sample_id"] != sample_id:
+            raise ValueError("sample_id is not the row number: the table was altered")
+        return row
+
+    def provenance(self, sample_id: int) -> Provenance:
+        row, meta = self._row(sample_id), self.metadata
+
+        def number(value) -> float | None:
+            return None if pd.isna(value) else float(value)
+
+        return Provenance(
+            sample_id=int(sample_id),
+            seed=meta["seed"],
+            seeding=meta["seeding"],
+            seed_key=row["seed_key"],
+            circuit=meta["circuit"],
+            netlist_sha256=meta["netlist_sha256"],
+            fault_id=row["fault_id"],
+            fault_type=row["fault_type"],
+            fault_location=row["fault_location"],
+            fault_magnitude=number(row["fault_magnitude"]),
+            fault_severity=number(row["fault_severity"]),
+            condition=row["condition"],
+            status=row["status"],
+            message=row["message"],
+            simulator=meta["simulator"],
+            simulator_version=meta["simulator_version"],
+            spicefault_version=meta["spicefault_version"],
+            parameters={c: float(row[c]) for c in self.parameters if not pd.isna(row[c])},
+        )
+
+    def netlist(self, sample_id: int) -> str:
+        """The netlist that was simulated for a sample, rebuilt from what is stored.
+
+        The realised values are read from the table, not drawn again, so this works
+        whatever variations the experiment used.
+        """
+        row = self._row(sample_id)
+        values = {target: row[column] for column, target in self.parameters.items()}
+        if any(pd.isna(v) for v in values.values()):
+            raise ValueError(f"sample {sample_id} has no realised values: {row['message']}")
+        netlist = self.circuit.netlist()
+        VariationSet.apply(netlist, {target: float(v) for target, v in values.items()})
+        if row["fault_id"] != HEALTHY_ID:
+            self.faults[row["fault_id"]].apply(netlist)
+        conditions = {c["name"]: c for c in self.metadata["conditions"]}
+        OperatingCondition.from_metadata(conditions[row["condition"]]).apply(netlist)
+        return str(netlist)
+
+    # --- reproducibility ----------------------------------------------------------------
+
+    def experiment(self, **overrides):
+        """The experiment that produced the dataset, rebuilt from its metadata.
+
+        Custom or joint variations, custom measurements and custom backends cannot be
+        stored and must be passed again (`variations=`, `measurements=`, `simulator=`).
+        """
+        from ..experiments import Experiment
+
+        return Experiment.from_metadata(
+            self.metadata, (self.path / CIRCUIT_FILE).read_text(), **overrides
+        )
+
+    def reproduce(
+        self,
+        sample_ids: Sequence[int] | None = None,
+        n: int = 20,
+        experiment=None,
+        seed: int = 0,
+    ) -> pd.DataFrame:
+        """Simulate samples again and compare them with what is stored.
+
+        By default `n` samples chosen at random. One row per sample:
+        - `definition`: same fault, condition and seed key;
+        - `parameters`: the redrawn values are exactly the stored ones;
+        - `status`: same simulation status;
+        - `max_abs_diff`, `max_rel_diff`: largest difference over the measurements;
+        - `waveform_abs_diff`: largest difference over the waveform, if stored.
+        On the platform and simulator version that wrote the dataset the differences
+        are expected to be zero; elsewhere they measure the dependence on both.
+        """
+        from ..experiments import simulate_sample
+
+        experiment = experiment or self.experiment()
+        plan = experiment.plan()
+        if len(plan) != len(self):
+            raise ValueError("the experiment does not have the samples of this dataset")
+        if sample_ids is None:
+            rng = np.random.default_rng(seed)
+            sample_ids = np.sort(rng.choice(len(self), min(n, len(self)), replace=False))
+        rows = []
+        for sample_id in map(int, sample_ids):
+            stored = self._row(sample_id)
+            new, waveform = simulate_sample(plan[sample_id], experiment)
+            ours = np.array([new[f] for f in self.features], dtype=float)
+            theirs = stored[self.features].to_numpy(dtype=float)
+            diff = np.abs(ours - theirs)
+            both_missing = np.isnan(ours) & np.isnan(theirs)
+            diff = np.where(both_missing, 0.0, diff)
+            waveform_diff = np.nan
+            if self.waveforms is not None and waveform is not None:
+                waveform_diff = float(np.abs(waveform - self.waveforms[sample_id]).max())
+            rows.append(
+                {
+                    "sample_id": sample_id,
+                    "definition": all(
+                        new[c] == stored[c] for c in ("fault_id", "condition", "seed_key")
+                    ),
+                    "parameters": all(
+                        new.get(c) == stored[c] or (pd.isna(new.get(c)) and pd.isna(stored[c]))
+                        for c in self.parameters
+                    ),
+                    "status": new["status"] == stored["status"],
+                    "max_abs_diff": float(diff.max()) if len(diff) else 0.0,
+                    "max_rel_diff": float(
+                        (diff / np.maximum(np.abs(theirs), 1e-300))[~both_missing].max()
+                    )
+                    if (~both_missing).any()
+                    else 0.0,
+                    "waveform_abs_diff": waveform_diff,
+                }
+            )
+        return pd.DataFrame(rows)
+
+    # --- uses ---------------------------------------------------------------------------
+
+    def to_ml(
+        self,
+        target: str | Callable[[pd.DataFrame], np.ndarray] = "fault_id",
+        features: Sequence[str] | None = None,
+        waveforms: bool = False,
+        drop_failed: bool = True,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """(X, y) for a statistical or machine-learning model.
+
+        X is the table of measurements (or of `features`), or the waveforms with
+        `waveforms`. y is a column of the samples, by default the fault identifier
+        (`fault_type` and `fault_location` are the usual alternatives), or the result
+        of a function of the samples. The library does not depend on any ML framework.
+        """
+        keep = self.ok if drop_failed else np.ones(len(self), dtype=bool)
+        samples = self.samples[keep]
+        if waveforms:
+            if self.waveforms is None:
+                raise ValueError("this dataset has no waveforms")
+            x = np.asarray(self.waveforms[keep])
+        else:
+            x = samples[list(features or self.features)].to_numpy(dtype=float)
+        y = target(samples) if callable(target) else samples[target].to_numpy()
+        return x, np.asarray(y)
+
+    def analysis(self, features: Sequence[str] | None = None, **kwargs):
+        """A `ReliabilityAnalysis` of the dataset."""
+        from ..reliability import ReliabilityAnalysis
+
+        return ReliabilityAnalysis(
+            self.samples, features or self.features, faults=self.metadata["faults"], **kwargs
+        )

spicefault/dataset/manifest.py

@@ -0,0 +1,79 @@
+"""The manifest of a dataset: the record of the run that produced it."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+MANIFEST = "manifest.json"
+
+
+def file_record(path: Path) -> dict:
+    """Size and SHA-256 of a file, read in blocks."""
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1 << 20), b""):
+            digest.update(block)
+    return {"bytes": path.stat().st_size, "sha256": digest.hexdigest()}
+
+
+@dataclass
+class Manifest:
+    """How and with what a dataset was produced, and the fingerprint of its files.
+
+    `summary` holds the counts the application adds (completed, failed, status
+    counts); in the file they are written next to the other fields. The manifest is
+    written last: its presence marks a complete dataset.
+    """
+
+    created: str
+    spicefault_version: str
+    simulator: str
+    python: str
+    numpy: str
+    pandas: str
+    platform: str
+    n_samples: int
+    workers: int
+    chunk: int
+    resumed: bool
+    elapsed_last_run_s: float
+    elapsed_total_s: float
+    files: dict[str, dict] = field(default_factory=dict)
+    summary: dict = field(default_factory=dict)
+    schema_version: int = SCHEMA_VERSION
+
+    def to_dict(self) -> dict:
+        record = asdict(self)
+        return {**{k: v for k, v in record.items() if k != "summary"}, **record["summary"]}
+
+    @classmethod
+    def from_dict(cls, record: dict) -> Manifest:
+        known = {f.name for f in fields(cls)} - {"summary"}
+        if record.get("schema_version") != SCHEMA_VERSION:
+            raise ValueError(f"unsupported manifest schema version {record.get('schema_version')}")
+        return cls(
+            **{k: v for k, v in record.items() if k in known},
+            summary={k: v for k, v in record.items() if k not in known},
+        )
+
+    def write(self, folder: str | Path) -> None:
+        (Path(folder) / MANIFEST).write_text(json.dumps(self.to_dict(), indent=2))
+
+    @classmethod
+    def read(cls, folder: str | Path) -> Manifest:
+        return cls.from_dict(json.loads((Path(folder) / MANIFEST).read_text()))
+
+    def verify(self, folder: str | Path) -> list[str]:
+        """Files that are missing or no longer match their recorded fingerprint."""
+        problems = []
+        for name, expected in self.files.items():
+            path = Path(folder) / name
+            if not path.exists():
+                problems.append(f"{name}: missing")
+            elif file_record(path) != expected:
+                problems.append(f"{name}: content differs from the manifest")
+        return problems

spicefault/dataset/store.py

@@ -0,0 +1,53 @@
+"""Reading and writing of a dataset directory.
+
+A dataset is a directory with:
+- samples.parquet  one row per simulation;
+- waveforms.npy    float32 [n_samples, n_points], row-aligned with the table (optional);
+- metadata.json    the definition of what was simulated: enough to regenerate it;
+- manifest.json    the record of the run: versions, counts, fingerprints of the files;
+- any other file the application adds, such as the source netlist.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .manifest import MANIFEST
+
+SAMPLES, WAVEFORMS, METADATA = "samples.parquet", "waveforms.npy", "metadata.json"
+
+
+def assemble(stems: list[Path], out_dir: str | Path) -> tuple[pd.DataFrame, np.ndarray | None]:
+    """Join the chunks written by a campaign into `out_dir`; returns (samples, waveforms)."""
+    out_dir = Path(out_dir)
+    df = pd.concat([pd.read_parquet(s.with_suffix(".parquet")) for s in stems], ignore_index=True)
+    df.to_parquet(out_dir / SAMPLES, index=False)
+    if not all(s.with_suffix(".npy").exists() for s in stems):
+        return df, None
+    waveforms = np.concatenate([np.load(s.with_suffix(".npy")) for s in stems])
+    np.save(out_dir / WAVEFORMS, waveforms)
+    return df, waveforms
+
+
+def load_metadata(path: str | Path) -> dict:
+    """The definition of the campaign that wrote the dataset."""
+    return json.loads((Path(path) / METADATA).read_text())
+
+
+def load_dataset(
+    path: str | Path, drop_failed: bool = True, ok_column: str = "sim_ok"
+) -> tuple[pd.DataFrame, np.ndarray | None, dict]:
+    """Return (samples, waveforms, manifest). Failed simulations are dropped on request."""
+    path = Path(path)
+    df = pd.read_parquet(path / SAMPLES)
+    waveforms = np.load(path / WAVEFORMS) if (path / WAVEFORMS).exists() else None
+    manifest = json.loads((path / MANIFEST).read_text())
+    if drop_failed and ok_column in df:
+        keep = df[ok_column].to_numpy()
+        df = df[keep].reset_index(drop=True)
+        waveforms = waveforms[keep] if waveforms is not None else None
+    return df, waveforms, manifest

spicefault/experiments/__init__.py

@@ -0,0 +1,21 @@
+"""Experiments: deterministic sampling and parallel, resumable execution."""
+
+from .campaign import FaultCampaign, ValidationReport, simulate_sample
+from .engine import config_key, run_campaign, run_chunks
+from .experiment import Experiment, ExperimentResult, Realisation, Sample, SampleResult
+from .seeding import sample_stream
+
+__all__ = [
+    "Experiment",
+    "ExperimentResult",
+    "FaultCampaign",
+    "Realisation",
+    "Sample",
+    "SampleResult",
+    "ValidationReport",
+    "config_key",
+    "run_campaign",
+    "run_chunks",
+    "sample_stream",
+    "simulate_sample",
+]