Toleranced¶

Package name: jitx/toleranced

Interval Arithmetic Type

The characteristics of many electrical components can't be boiled down to just one number. Often times the values we care about are specified with a precision or tolerance. The first introduction to this for many budding new engineers is resistors and their precision specification. Picking the right precision may not seem important at first, but can end up making or breaking a design when it goes to the field or production.

To help manage the complexity of tolerances in all shapes and sizes, we've developed the Toleranced type. The Toleranced type is a way of specifying the range of possible values that a feature or quantity can be.

The math behind the Toleranced type comes from Interval Arithmetic. Interval arithmetic defines operators on Toleranced values and the limitations of those operators. Typically, where things get hairy is around 0.0. Anytime a Toleranced value straddles zero, extra care needs to be taken to make sure operators like plus, minus, and others do the correct thing.

Instantiating `Toleranced`¶

A Toleranced type consists of:

A Typical Value typ
A Relative Positive Increment tol+
A Relative Negative Increment tol-

Considered another way, a Toleranced consist of:

A Typical Value typ
A Maximum Value typ + tol+
A Minimum Value typ - tol-

These values are limits. These values don't imply a distribution (like a Normal or Triangular distribution). The only implied constraint for a Toleranced value is:

typ - tol- <= typ <= typ + tol+

Typically, we don't instantiate Toleranced values directly, we use a number of helper functions to create Toleranced values in various forms. The most helpful of these are:

Voltage Divider Example¶

val R1 = tol%(10.0e3, (1 %))
val R2 = tol%(27.4e3, (1 %))

val VIN = 12.0

val VOUT = VIN * (R2 / (R1 + R2))
println("VOUT: %_" % [VOUT])

; Prints:
; VOUT: Toleranced(8.61735585323238 <= 8.79144385026738 <= 8.96904877653541)

Toleranced Operators

Notice that operators for multiplication, division, and addition work for both Toleranced + Toleranced and Double * Toleranced

Summary¶

Toleranced ¶

Generic Toleranced Value Type

Constructors¶

Function	Description
Toleranced	Constructor for `defstruct Toleranced`

Functions¶

Function	Description
log	Apply the `log()` function to a Toleranced Value.
max-value	Maximum as an absolute value.
in-range? (+ 2)	Check if the passed `value` is found between the min and max values of `t`
typ	Alias for `Toleranced` with Zero'd `tol+` and `tol-`
min-typ	Toleranced defined by an absolute minimum and typical value.
tol (+ 4)
to-degrees	Convert Degrees to Radians
pow (+ 1)	Apply the `pow(x,y)` function to a `Toleranced` value as the exponent.
exp	Apply the `exp()` function to a Toleranced Value.
sqrt	Apply the `sqrt()` function to a `Toleranced` value.
to-radians	Convert Radians to Degrees
typ-max	Toleranced defined by an absolute maximum and typical value.
log10	Apply the `log10()` function to a Toleranced Value.
min-typ-max	Helper for defining all combinations for Toleranced values
tol-%	Relative Negative Tolerance as a percentage
min-max	Toleranced defined by absolute min and max values
min-%	Relative Negative Tolerance as a `Percentage`
tol+%	Relative Postive Tolerance as a percentage
Exactly
apply	Apply a Monotonic Function to a Toleranced
typ-value	Typical Value
nom-value	Alias for the Typical Value
tol% (+ 3)	Create a Toleranced based on asymetric percentages of the typical value.
min-value	Minimum as an absolute value.
center-value	Mid-point between the `min` and `max` values.
max-%	Relative Postive Tolerance as a `Percentage`
tolerance-range	Compute the span between max-value and min-value

Operators¶

Function	Op.	Description
minus (+ 1)	`-`	Subtraction Operator for `Toleranced` types
divide (+ 1)	`/`	Division Operator for `Toleranced` types
plus (+ 1)	`+`	Addition Operator for `Toleranced` types.
plus-minus (+ 7)	`+/-`	`+/-` Operator for Symmetric Toleranced as Relative Values
times (+ 2)	`*`	Multiplication Operator for `Toleranced` types

Definitions¶

Toleranced¶

Generic Toleranced Value Type

public defstruct Toleranced <: Interval
    tol+: Double|False
    tol-: Double|False
    typ: Double

tol+: Double|False - Relative Positive Increment This value defines the Maximum value of a tolerance relative to the typ value. The maximum relative value is optional. It can be set to false which implies that there is no maximum bound for this toleranced value.
tol-: Double|False - Relative Negative Increment This value defines the Minimum value of a tolerance relative to the typ value. The minimum relative value is optional. It can be set to false which implies that there is no minimum bound for this toleranced value.
typ: Double - Typical value for this Toleranced value. This is generally considered the average value. typ() is often used to convert a Toleranced value into a Double when tolerances are not required for a calculation.

This type defines the data type for a Toleranced value.

Reference Only¶

val x = Toleranced(1.0, 0.1, 0.2)
val maxVal = typ(x) + tol+(x)
val minVal = typ(x) - tol-(x)

println("Typ: %_  Max: %_  Min: %_" % [typ(x), maxVal, minVal])
; Prints:
; Typ: 1.0  Max: 1.1  Min: 0.8

We don't usally reference the Toleranced values directly like this.

It is more convenient and easier to read if the code leverages the min-value and max-value functions.

Constructors¶

Toleranced¶

Constructor for defstruct Toleranced

public defn Toleranced (typ:Double, tol+:Double|False, tol-:Double|False)

Functions¶

log¶

Apply the log() function to a Toleranced Value.

public defn log (v:Toleranced) -> Toleranced

v: Toleranced - This value must be greater than 0.0.
Returns Toleranced

max-value¶

Maximum as an absolute value.

public defn max-value (t:Toleranced) -> Double

Returns Double

in-range?¶

Check if the passed value is found between the min and max values of t

public defn in-range? (t:Toleranced, value:Double) -> True|False

Returns True|False

in-range?¶

Check if the passed value is found between the min and max values of t

public defn in-range? (t:Toleranced, value:Toleranced) -> True|False

Returns True|False

This check will return true if value is a complete sub-set of t.

Examples:

Returns True:
value =     |---|
t     =     |--------|

value =       |---|
t     =     |--------|

value =          |---|
t     =     |--------|

Returns False:
value =   |---|
t     =     |--------|

value =            |---|
t     =     |--------|

value =                 |---|
t     =     |--------|

in-range?¶

Check if the passed v is within the percentage range of this toleranced.

public defn in-range? (t:Toleranced, v:Percentage) -> True|False

v: Percentage - If v is positive, then we compare against the positive relative tolerance as a percentage of typ. If v is negative, we compare against the negative relative tolerance as a percentage of typ.
Returns True|False
Throws Exception - When typ is zero

typ¶

Alias for Toleranced with Zero'd tol+ and tol-

public defn typ (typ:Double) -> Toleranced

typ: Double - Typical Value
Returns Toleranced - Returns a Toleranced(typ, 0.0, 0.0)

min-typ¶

Toleranced defined by an absolute minimum and typical value.

public defn min-typ (min:Double, typ:Double) -> Toleranced

Returns Toleranced

This function generates a Toleranced value that does not have an explicit maximum bound.

min must be less than or equal to typ otherwise and exception is thrown.

Example¶

; Vout High-side swing - datasheet defines
;  a guaranteed minimum and a typical value but no
;  explicit maximum. In reality, the maximum is 
;  physically limited by the supply rail.
val VOH = min-typ(2.87, 2.9)

References the LMH32401-Q1 datasheet.

tol¶

public defn tol (typ:Double, tol+:Double, tol-:Double) -> Toleranced

Returns Toleranced

tol¶

public defn tol (typ:Double, tol+:False, tol-:Double) -> Toleranced

Returns Toleranced

tol¶

public defn tol (typ:Double, tol+:Double, tol-:False) -> Toleranced

Returns Toleranced

tol¶

Create a Toleranced with symmetric relative values.

public defn tol (typ:Double, tol+-:Double) -> Toleranced

typ: Double - Typical Value
tol+-: Double - Relative tolerance values for both tol+ and tol-
Returns Toleranced

tol¶

Create a Toleranced with Zero'd tol+ and tol-

public defn tol (typ:Double) -> Toleranced

typ: Double - Typical Value
Returns Toleranced - Returns a Toleranced(typ, 0.0, 0.0)

to-degrees¶

Convert Degrees to Radians

public defn to-degrees (x:Toleranced) -> Toleranced

Returns Toleranced

pow¶

Apply the pow(x,y) function to a Toleranced value as the exponent.

public defn pow (x:Double, y:Toleranced) -> Toleranced

x: Double - Base of the exponential function.
y: Toleranced - Exponent as a Toleranced.
Returns Toleranced
Throws RuntimeError - If the base x is not greater than 1. This condition is required for monotonicity requirements to hold.

pow¶

Apply the pow(x,y) function to a Toleranced value as the base.

public defn pow (x:Toleranced, y:Double) -> Toleranced

x: Toleranced - Base of the exponential function as a toleranced value.
y: Double - Exponent as a constant value.
Returns Toleranced

It is the user's responsibility to call this function correctly given the constraints below. Failure to call correctly may result in invalid Toleranced result values.

Integer values of `y`¶

If y is an odd, integer value - then this function works for the entire domain of x. if y is an even, integer value - then this function works only for the domain of x that is greater than or equal to zero.

Fractional values of `y`¶

If y is not an integer - then this function works only for the domain of x that is greater than or equal to zero.

exp¶

Apply the exp() function to a Toleranced Value.

public defn exp (v:Toleranced) -> Toleranced

Returns Toleranced

sqrt¶

Apply the sqrt() function to a Toleranced value.

public defn sqrt (v:Toleranced) -> Toleranced

Returns Toleranced

This function assumes that the domain of v is greater than or equal to 0.0

to-radians¶

Convert Radians to Degrees

public defn to-radians (x:Toleranced) -> Toleranced

Returns Toleranced

typ-max¶

Toleranced defined by an absolute maximum and typical value.

public defn typ-max (typ:Double, max:Double) -> Toleranced

Returns Toleranced

This function generates a Toleranced value that does not have an explicit minimum bound.

max must be greater than or equal to typ

Example¶

; Vout Low-side swing - datasheet defines
;  a guaranteed maximum and a typical value but no
;  explicit minimum. In reality, the minimum is 
;  physically limited by the ground reference.
val VOH = typ-max(0.36, 0.39)

References the LMH32401-Q1 datasheet.

log10¶

Apply the log10() function to a Toleranced Value.

public defn log10 (v:Toleranced) -> Toleranced

v: Toleranced - This value must be greater than 0.0.
Returns Toleranced

min-typ-max¶

Helper for defining all combinations for Toleranced values

public defn min-typ-max (min:Double|False, typ:Double|False, max:Double|False) -> Toleranced

Returns Toleranced

This function defines a toleranced value in terms of absolute values as opposed to relative values.

This function requires at least 2 of passed arguments be Double types. If less than 2 of the passed arguments are Double type - then an exception is thrown.

By definition:

min <= typ <= max

Otherwise, this function will throw an exception.

References¶

tol-%¶

Relative Negative Tolerance as a percentage

public defn tol-% (t:Toleranced) -> Double

Returns Double - Extracts the tol- value and converts it to a percentage value relative to typ in the range 0 to 100.

min-max¶

Toleranced defined by absolute min and max values

public defn min-max (min:Double, max:Double) -> Toleranced

Returns Toleranced

The typ value for this toleranced is defined as the mid-point between the min and max value.

min must be less than or equal to max

Example¶

val a = min-max(10.0, 20.0) 
println(a)
; Prints:
Toleranced(10.0 <= 15.0 <= 20.0)

min-%¶

Relative Negative Tolerance as a Percentage

public defn min-% (t:Toleranced) -> Percentage

Returns Percentage - Extracts the tol- value and converts it to a Percentage type value relative to typ.

tol+%¶

Relative Postive Tolerance as a percentage

public defn tol+% (t:Toleranced) -> Double

Returns Double - Extracts the tol+ value and converts it to a percentage value relative to typ in the range 0 to 100.

Exactly¶

public defn Exactly (x:Double) -> Toleranced

Returns Toleranced

apply¶

Apply a Monotonic Function to a Toleranced

public defn apply (f:(Double) -> Double, v:Toleranced) -> Toleranced

f: (Double) -> Double - Monotonic, continuous function over Double
v: Toleranced - Value to convert. The structure of this toleranced value is preserved. For example, if there is no lower bound in the argument v, then the resulting Toleranced will also not have a lower bound.
Returns Toleranced
Throws RuntimeError - If an invalid Toleranced value is passed that has neither lower nor upper bounds.

typ-value¶

Typical Value

public defn typ-value (t:Toleranced) -> Double

Returns Double

nom-value¶

Alias for the Typical Value

public defn nom-value (t:Toleranced) -> Double

Returns Double

tol%¶

Create a Toleranced based on asymetric percentages of the typical value.

public defn tol% (typ:Double, tol+:Double, tol-:Double) -> Toleranced

Returns Toleranced

The tol+ and tol- arguments are percentages defined as values in the range 0.0 to 100.0. Values outside of this range will throw an exception.

Example¶

val x = tol%(-1.0, 10.0, 20.0)
println(x)
; Prints:
; Toleranced(-1.2 <= -1.0 <= -0.9)

Negative Numbers

Notice that the toleranced values can be created for negative values as well.

tol%¶

Create a Toleranced based on asymmetric Percentage tolerances

public defn tol% (typ:Double, tol+:Percentage, tol-:Percentage) -> Toleranced

typ: Double - Typical Value
tol+: Percentage - Percentage of typ for defining the relative maximum value. Note that the tol+ value must be greater than zero but is otherwise unconstrained.
tol-: Percentage - Percentage of Typical for defining the minimum value. Note that the tol- value must be greater than zero but is otherwise unconstrained. A value of tol- greater than 100% can result in a Toleranced that straddles zero.
Returns Toleranced

Example¶

val x = tol%(10.0, (5 %), (7 %))
println(x)
; Prints: 
; Toleranced(9.3 <= 10.0 <= 10.5)

tol%¶

Create Toleranced based on symmetric percentage relative value.

public defn tol% (typ:Double, tol:Double) -> Toleranced

typ: Double - Typical Value
tol: Double - Percentage of typ for defining the relative tolerance value. This defines both the tol- and tol+ values of the tolerance to be equal. The tol percentage is restricted to the range 0.0 to 100.0
Returns Toleranced

Example¶

val x = tol%(10.0, 13.0)
println(x)
; Prints: 
; Toleranced(8.7 <= 10.0 <= 11.3)

tol%¶

Create Toleranced based on symmetric percentage relative value.

public defn tol% (typ:Double, tol:Percentage) -> Toleranced

typ: Double - Typical Value
tol: Percentage - Percentage of typ for defining the relative tolerance value. This defines both the tol- and tol+ values of the tolerance to be equal.
Returns Toleranced

Example¶

val x = tol%(54.0, (9 %))
println(x)
; Prints: 
; Toleranced(49.14 <= 54.0 <= 58.86)

min-value¶

Minimum as an absolute value.

public defn min-value (t:Toleranced) -> Double

Returns Double

center-value¶

Mid-point between the min and max values.

public defn center-value (t:Toleranced) -> Double

Returns Double

This value is not necessarily the typ value.

max-%¶

Relative Postive Tolerance as a Percentage

public defn max-% (t:Toleranced) -> Percentage

Returns Percentage - Extracts the tol+ value and converts it to a Percentage type value relative to typ.

tolerance-range¶

Compute the span between max-value and min-value

public defn tolerance-range (t:Toleranced) -> Double

Returns Double - max-value(t) - min-value(t)

Operators¶

minus `-`¶

Subtraction Operator for Toleranced types

public defn minus (a:Toleranced, b:Toleranced) -> Toleranced

Returns Toleranced

minus `-`¶

Subtraction Operator for Double - Toleranced

public defn minus (a:Double, b:Toleranced) -> Toleranced

Returns Toleranced

divide `/`¶

Division Operator for Toleranced types

public defn divide (a:Toleranced, b:Toleranced) -> Toleranced

Returns Toleranced

References¶

https://en.wikipedia.org/wiki/Interval_arithmetic#Interval_operators

divide `/`¶

Division Operator for Double / Toleranced

public defn divide (a:Double, b:Toleranced) -> Toleranced

Returns Toleranced

plus `+`¶

Addition Operator for Toleranced types.

public defn plus (a:Toleranced, b:Toleranced) -> Toleranced

Returns Toleranced

plus `+`¶

Addition Operator for Double + Toleranced

public defn plus (a:Double, b:Toleranced)

plus-minus `+/-`¶

+/- Operator for Symmetric Toleranced as Relative Values

public defn plus-minus (a:Double, b:Double) -> Toleranced

a: Double - Typical Value for Resultant Toleranced
b: Double - Relative Positive & Negative (tol+ and tol-) for Resultant Toleranced
Returns Toleranced

Example¶

val a = 10.0 +/- 1.0
println(a)
; Prints: 
; Toleranced(9.0 <= 10.0 <= 11.0)

plus-minus `+/-`¶

+/- Operator for Symmetric Toleranced as Relative Percentages

public defn plus-minus (a:Double, b:Percentage) -> Toleranced

a: Double - Typical Value for Resultant Toleranced
b: Percentage - Relative Positive & Negative (tol+ and tol-) as a percentage of typ.
Returns Toleranced

Example¶

val a = 10.0 +/- (6 %)
println(a)
; Prints: 
; Toleranced(9.4 <= 10.0 <= 10.6)

plus-minus `+/-`¶

Alias for +/- Operator for Symmetric Toleranced as Relative Values

public defn plus-minus (a:Int, b:Double) -> Toleranced

a: Int - Typical Value for Resultant Toleranced. Converts from Int -> Double
b: Double - Relative Positive & Negative (tol+ and tol-) for Resultant Toleranced
Returns Toleranced

Example¶

val a = 10 +/- 1.0
println(a)
; Prints: 
; Toleranced(9.0 <= 10.0 <= 11.0)

plus-minus `+/-`¶

Alias for +/- Operator for Symmetric Toleranced as Relative Percentages

public defn plus-minus (a:Int, b:Percentage) -> Toleranced

a: Int - Typical Value for Resultant Toleranced. Converts from Int -> Double
b: Percentage - Relative Positive & Negative (tol+ and tol-) as a percentage of typ.
Returns Toleranced

Example¶

val a = 10 +/- (7 %)
println(a)
; Prints: 
; Toleranced(9.3 <= 10.0 <= 10.7)

plus-minus `+/-`¶

+/- Operator for Asymmetric Toleranced as Relative Values

public defn plus-minus (a:Double, b:[Double, Double]) -> Toleranced

a: Double - Typical Value for Resultant Toleranced
b: [Double, Double] - Relative [tol+, tol-] for Resultant Toleranced
Returns Toleranced

Example¶

val a = 10.0 +/- [0.5, 0.75]
println(a)
; Prints: 
; Toleranced(9.25 <= 10.0 <= 10.5)

plus-minus `+/-`¶

+/- Operator for Asymmetric Toleranced as Relative Percentages

public defn plus-minus (a:Double, b:[Percentage, Percentage]) -> Toleranced

a: Double - Typical Value for Resultant Toleranced
b: [Percentage, Percentage] - Relative [tol+%, tol-%] for Resultant Toleranced as Percentages of typ
Returns Toleranced

Example¶

val a = 10.0 +/- [(5 %), (7 %)]
println(a)
; Prints: 
; Toleranced(9.3 <= 10.0 <= 10.5)

plus-minus `+/-`¶

Alias for +/- Operator for Asymmetric Toleranced as Relative Values

public defn plus-minus (a:Int, b:[Double, Double]) -> Toleranced

a: Int - Typical Value for Resultant Toleranced. Converts Int -> Double
b: [Double, Double] - Relative [tol+, tol-] for Resultant Toleranced
Returns Toleranced

Example¶

val a = 10 +/- [0.5, 0.75]
println(a)
; Prints: 
; Toleranced(9.25 <= 10.0 <= 10.5)

plus-minus `+/-`¶

Alias +/- Operator for Asymmetric Toleranced as Relative Percentages

public defn plus-minus (a:Int, b:[Percentage, Percentage]) -> Toleranced

a: Int - Typical Value for Resultant Toleranced. Converts Int -> Double
b: [Percentage, Percentage] - Relative [tol+%, tol-%] for Resultant Toleranced as Percentages of typ
Returns Toleranced

Example¶

val a = 10 +/- [(5 %), (7 %)]
println(a)
; Prints: 
; Toleranced(9.3 <= 10.0 <= 10.5)

times `*`¶

Multiplication Operator for Toleranced types

public defn times (a:Toleranced, b:Toleranced) -> Toleranced

Returns Toleranced

times `*`¶

Multiplication Operator for Double * Toleranced

public defn times (a:Double, b:Toleranced) -> Toleranced

Returns Toleranced

times `*`¶

Multiplication Operator for Percentage * Toleranced

public defn times (a:Percentage, b:Toleranced) -> Toleranced

Returns Toleranced

Forwarded by package: jitx

Toleranced¶

Instantiating Toleranced¶

Voltage Divider Example¶

Summary¶

Toleranced¶

Constructors¶

Functions¶

Operators¶

Definitions¶

Toleranced¶

Reference Only¶

Constructors¶

Toleranced¶

Functions¶

log¶

max-value¶

in-range?¶

in-range?¶

in-range?¶

typ¶

min-typ¶

Example¶

tol¶

tol¶

tol¶

tol¶

tol¶

to-degrees¶

pow¶

pow¶

Integer values of y¶

Fractional values of y¶

exp¶

sqrt¶

to-radians¶

typ-max¶

Example¶

log10¶

min-typ-max¶

References¶

tol-%¶

min-max¶

Example¶

min-%¶

tol+%¶

Exactly¶

apply¶

typ-value¶

nom-value¶

tol%¶

Example¶

tol%¶

Example¶

tol%¶

Example¶

tol%¶

Example¶

min-value¶

center-value¶

max-%¶

tolerance-range¶

Operators¶

minus -¶

minus -¶

divide /¶

References¶

divide /¶

plus +¶

plus +¶

plus-minus +/-¶

Example¶

plus-minus +/-¶

Example¶

plus-minus +/-¶

Example¶

plus-minus +/-¶

Example¶

plus-minus +/-¶

Example¶

plus-minus +/-¶

Instantiating `Toleranced`¶

Toleranced ¶

Integer values of `y`¶

Fractional values of `y`¶

minus `-`¶

minus `-`¶

divide `/`¶

divide `/`¶

plus `+`¶

plus `+`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

plus-minus `+/-`¶

times `*`¶

times `*`¶

times `*`¶