Faults¶
spicefault.faults.types
¶
The fault types of the first release (docs/FAULT_MODEL.md, section 3).
Every type has a physical interpretation, stated in its docstring, and is a list of
primitives. fault_type is the reported type; it defaults to the name of the class
and can be overridden when an application reports a fault under another name.
OpenCircuit
¶
Bases: Fault
Broken connection: cracked solder joint, lifted lead, open track or open component.
One terminal is reconnected through r_open. An ideal open would leave a node
floating and make the operating point singular, so r_open is finite; it belongs
to the model and is recorded. It must be large against the impedances around the
component. On a two-terminal component either terminal gives the same circuit.
ShortCircuit
¶
Bases: Fault
Solder bridge, dielectric breakdown or conductive contamination across a component.
r_short is added between two terminals. It is a model parameter: small against
the impedances around the component, and not zero, which would create a loop of
ideal elements.
LeakageFault
¶
Bases: Fault
Finite parasitic conduction: capacitor insulation loss, board contamination, degraded junction.
The same primitive as a short, graded: resistance is the magnitude of the fault,
usually studied over decades. With r_min and r_max the severity is taken on a
logarithmic scale, 0 at r_max and 1 at r_min.
SeriesResistanceFault
¶
ParametricFault
¶
Bases: Fault
A parameter outside its tolerance band: wrong part fitted, aged or stressed component, degraded device parameter.
Exactly one of:
- deviation: x -> x (1 + deviation), on the value the component has after its
normal variation;
- factor: x -> factor * x, likewise;
- divisor: x -> x / divisor, likewise;
- fault_value: x -> fault_value, whatever the component had.
The first three compound with the manufacturing spread of the faulty component;
the last one replaces it. Severity is |deviation| (|factor - 1|, |1/divisor - 1|)
for the relative forms. For fault_value it is |fault_value - nominal_value| /
reference, with reference defaulting to nominal_value; a parameter that is
nominally zero, such as an offset voltage, needs an explicit reference.
parameter may be resistance, capacitance or inductance for the value of a
passive component.
spicefault.faults.base
¶
Primitives and the fault built from them (docs/FAULT_MODEL.md, sections 1 and 7).
Fault
dataclass
¶
One fault condition: what is injected, and what is recorded about it.
magnitude is the physical size of the fault, with unit; severity is an
optional dimensionless number on a declared scale (a bare number is taken as
declared by the user). model_parameters holds values that belong to the model
and not to the defect, such as the resistance that stands for an open circuit.
tags are application labels.
This class builds a fault directly from primitives; OpenCircuit,
ShortCircuit, LeakageFault, ParametricFault and CompositeFault are the
usual ways to write one.
components
property
¶
Components the fault acts on, in order of first appearance.
with_tags(tags)
¶
The same fault with tags added to its own; a tag of the same name is replaced.
apply(netlist)
¶
Inject the fault into an already realised netlist, primitive by primitive.
from_metadata(record)
classmethod
¶
Rebuild a fault from its record, as an instance of the class that wrote it.
register(name)
¶
Class decorator: faults of this class are recorded and rebuilt under name.
spicefault.faults.severity
¶
Severity of a fault: a dimensionless number on a declared scale.
There is no universal formula. Each scale below is one definition, named in the record of the fault together with its parameters, and severities on different scales are not comparable (docs/FAULT_MODEL.md, section 5).
FaultSeverity
dataclass
¶
declared(value, scale='declared')
classmethod
¶
A value given by the user, on a scale the user names.
relative_deviation(deviation)
classmethod
¶
s = |delta| for a parameter moved to x (1 + delta). Unbounded above.
deviation_over_reference(fault_value, nominal_value, reference)
classmethod
¶
s = |x_f - x_0| / x_ref. The reference must be given when x_0 is zero.
log_resistance(resistance, r_min, r_max)
classmethod
¶
s = log(r_max / r) / log(r_max / r_min): 0 at r_max, 1 at r_min.
log_series_resistance(resistance, r_min, r_max)
classmethod
¶
s = log(r / r_min) / log(r_max / r_min): 0 at r_min, 1 at r_max.
spicefault.faults.faultset
¶
An ordered set of fault conditions: the fault list of an experiment.
FaultSet
¶
Bases: Sequence
Faults in a fixed order, each with a unique identifier.
The order matters: with positional seeding, the random stream of a fault depends on its place in the list.
select(ids)
¶
The faults with these identifiers, in the order given.
filter(fault_type=None, component=None, tags=None, where=None)
¶
Faults that meet every condition given, in their original order.
tolerance_overlap(variations, circuit=None)
¶
How much of each parametric fault population lies inside the healthy band.
A fault on a parameter with tolerance t moves the realised value, so the total deviation from nominal covers an interval; where it overlaps +-t, faulty samples are healthy by definition and nothing can detect them. One row per fault made of a single parameter change on a toleranced parameter:
deviation_min,deviation_max: total relative deviation from nominal;inside_fraction: share of the fault population within +-t, for the distribution of the tolerance.
Faults that set an absolute value need circuit, for the nominal value. This
is a report: an overlapping fault is legitimate, but it must be visible.
spicefault.faults.universe
¶
The fault universe of a circuit and the coverage of a campaign over it.
The universe is generated from applicability rules: which fault types apply to which components, and with which magnitudes. A campaign simulates a selection of it, and every fault left out carries a reason. That record is what makes the coverage of a campaign auditable (docs/FAULT_MODEL.md, section 8).
FaultRule
dataclass
¶
Faults of one type (name, a column of the coverage matrix) on the components
it applies to: those whose element letter is in kinds (any, if empty), whose
name is listed if components is given, and whose subcircuit or device model
(Component.model) is listed if models is given.
tags are added to every fault of the rule: a dictionary, or a function of the
component that returns one, for labels that depend on where the fault is (the
part to locate, the origin of the defect).
faults(component)
¶
The faults of the rule on a component, with the tags of the rule.
FaultUniverse
¶
exclude(which, reason)
¶
Leave faults out of the campaign, by identifier or by predicate, with a reason.
Returns how many were excluded by this call.
selected()
¶
The faults to simulate, in universe order.
coverage()
¶
Structural coverage: simulated conditions over conditions in the universe.
coverage_matrix(counts='selected')
¶
Components x fault types. NaN where the fault type does not apply.
counts: selected (conditions to simulate), universe (conditions that
exist) or fraction (their ratio).
metadata()
¶
The record that makes the coverage auditable.
open_rule(kinds='RCL', r_open=1000000000.0, **kwargs)
¶
An open at the second terminal of every component of these kinds.
parametric_rule(deviations=(), kinds='RCL', parameter='value', *, factors=(), fault_values=(), fault_type='parametric', **kwargs)
¶
One fault of parameter per relative deviation, per factor and per absolute value.
deviations and factors act on the value the component has after its normal
variation; fault_values replace it (see ParametricFault), with a severity
relative to the nominal value when that is not zero. fault_type is the type the
faults are reported under and the name of the rule, so that several parametric
rules (an offset, a gain) can share a universe.
leakage_rule(resistances, kinds='C', **kwargs)
¶
One fault per leakage resistance; severity on the log scale they span.
series_rule(resistances, kinds='RCL', **kwargs)
¶
One graded series-resistance fault per magnitude; severity grows with resistance.