Variation¶
spicefault.variation.types
¶
The distributions a parameter can follow in the healthy population.
Every draw takes its random numbers from the generator it is given and from nothing else, in a fixed number and order (the truncated ones redraw until in range).
FixedVariation
dataclass
¶
ToleranceVariation
dataclass
¶
Bases: Variation
Value within a tolerance band around the nominal value of the netlist.
Relative (default): nominal * (1 +- tolerance), as for the value of a resistor.
With relative=False: nominal +- tolerance, in the units of the parameter, as for
an offset voltage that is nominally zero. distribution is uniform, or
truncnorm: normal with sigma = tolerance / 3, truncated at the band.
NormalVariation
dataclass
¶
Bases: Variation
Normal with standard deviation sigma around mean (the nominal value if None).
A normal distribution has no bounds, so a physical parameter can come out
negative. truncate limits the draw to mean +- truncate * sigma, by redrawing.
LogNormalVariation
dataclass
¶
Bases: Variation
median * exp(N(0, sigma_log)): always positive, with a multiplicative spread.
median defaults to the nominal value. sigma_log is the standard deviation of
the natural logarithm; for small values it is close to the relative spread.
LogUniformVariation
dataclass
¶
Bases: Variation
median times a factor drawn log-uniformly between 1 / spread and spread.
For parameters known to within a factor, not a percentage.
CustomVariation
dataclass
¶
Bases: Variation
Any distribution of one parameter: sampler(rng, nominal) returns the value.
The function cannot be stored in a record; description is what the provenance
keeps, together with the name of the function.
JointVariation
dataclass
¶
Bases: Variation
Several parameters drawn together, when they are not independent.
For example the parameters of a part whose type is drawn first, or a netlist
parameter computed from two drawn quantities. sampler(rng, netlist) returns the
values of parameters, as {(component, parameter): value}, or a Draw to also
record labels. name identifies it in the provenance.
CatalogueVariation
dataclass
¶
Bases: Variation
A part that is one of several types: the type is drawn first, then its parameters.
options maps each type to the medians of the parameters of component, for
example {"gel": {"r": 2e3, "c": 50e-9}, "steel": {"r": 2e5, "c": 5e-9}}; every
type gives the same parameters. The type is drawn with probabilities proportional
to weights (equal by default), and each parameter is its median times a factor
drawn log-uniformly between 1 / spread and spread, as in
LogUniformVariation. The drawn type is recorded under label, by default
<component>_kind, and becomes a column of the dataset.
It uses the same random numbers whatever type is drawn, and it is rebuilt from its record, since it holds no function.
CorrelatedVariation
dataclass
¶
Bases: Variation
Parameters that keep their own distributions and vary together.
variations are the marginals: each parameter is distributed as its variation
says, whatever the correlation. They are joined by a Gaussian copula: correlated
standard normals are drawn, each is turned into a probability, and each variation
gives the value at that probability, so every one of them needs a quantile
function.
correlation is one number for every pair, or the full matrix. It is the
correlation of the underlying normals. The correlation of the values equals it
only for normal marginals; their rank correlation is (6 / pi) asin(correlation / 2)
for any marginals.
Two resistors from the same reel, or a ratio that is tighter than its parts:
CorrelatedVariation([ToleranceVariation("R1", 0.01), ToleranceVariation("R2", 0.01)],
correlation=0.9)
LotVariation
dataclass
¶
Bases: Variation
Components that share the deviation of their manufacturing lot.
value = nominal * (1 + lot * d0 + within * d_i): d0 is one deviation for the
whole group, drawn once per circuit, and d_i one of each component, all in
[-1, 1] with the given distribution. The components then track each other: their
ratios spread by within alone, while each value spreads by both.
The deviation of the lot, lot * d0, is recorded as a label under name.
variation_from_metadata(record)
¶
Rebuild a variation from its record. Custom and joint ones hold a function, which a record cannot carry.
tolerances(circuit, by_kind, distribution='uniform', overrides=None, components=None)
¶
Relative tolerances for the values of a circuit, in netlist order.
by_kind maps element letters to tolerances, e.g. {"R": 0.01, "C": 0.05};
overrides gives the tolerance of individual components; components restricts
the set to those named.
instance_tolerances(circuit, model, parameters, distribution='uniform')
¶
The same tolerances for the parameters of every instance of a subcircuit or model.
model is the subcircuit of the X instances, or the model of the devices, to
vary (Component.model). parameters maps each instance parameter to its
tolerance: a number for a relative one, or (tolerance, "relative") or
(tolerance, "absolute"), the second for a parameter that is nominally zero:
instance_tolerances(circuit, "opamp", {"vos": (0.5e-3, "absolute"), "aol": 0.5})
The variations come in netlist order, instance by instance. A parameter must be written on every instance, since only what the netlist states can be varied.
spicefault.variation.base
¶
Normal variation of the parameters of a circuit, kept apart from faults.
Draw
dataclass
¶
One realisation of the healthy circuit.
values are written to the netlist. labels are only recorded: quantities that
were drawn but are not netlist parameters, such as the type of a part.
Variation
¶
Bases: ABC
Distribution of one parameter of one component in the healthy population.
sample(rng, nominal)
abstractmethod
¶
Draw the realised value; nominal is the value written in the netlist.
quantile(u, nominal)
¶
The value at probability u in (0, 1): the inverse of the distribution function.
sample draws from a random stream; this turns a given uniform number into a
value of the same distribution. Designs that choose their uniform numbers
jointly (correlated populations, stratified sampling) are built on it. A
variation that holds a function or a discrete choice has none.
bounds(nominal)
¶
The lowest and the highest value it can give. A distribution without limits, or one that holds a function, has none.
nominal(netlist)
¶
The value written in the netlist; NaN if it is an expression, not a number.
scaled(factor)
abstractmethod
¶
The same variation with its spread multiplied by factor.
It must use as many random numbers as the original, so that scaling the spread of one parameter leaves the draws of the others unchanged.
VariationSet
¶
Variations drawn in a fixed order, so that a random stream defines a circuit.
sample(rng, netlist)
¶
Draw every variation in order, reading the nominal values from netlist.
scaled(factor, strict=True)
¶
Every spread multiplied by factor; the draws stay aligned with the original.
Custom and joint variations cannot be scaled: with strict they raise,
otherwise they are kept as they are.