Monte-Carlo Library

`daspi.statistics.montecarlo` ¶

Monte Carlo simulation and specification modelling.

This module provides the building blocks for tolerance analysis and Monte Carlo process simulation. It defines data structures for expressing engineering specifications and generates synthetic process data that can be passed to estimators in the estimation module.

Specification data structures

SpecLimits – an immutable dataclass holding the lower and upper specification limits of a characteristic. Supports membership tests (value in spec_limits) and derives tolerance, nominal, and boundedness from the stored limits.
Specification – a richer specification object that accepts limits, tolerance, and nominal value in any combination and cross-calculates the missing values. Intended to be used as a constant (all properties are uppercase).

Simulation classes

RandomProcessValue – generates random samples from a configurable distribution (normal by default) scaled to a given specification. Useful for building Monte Carlo models of multi-characteristic assemblies.
Binning – discretises a continuous variable into equally spaced bins, simulating the effect of finite measurement resolution.

Utility functions

round_to_nearest – rounds a value to the nearest multiple of a given resolution; used internally by Binning.
inclination_displacement – calculates the systematic displacement introduced by a linearity (inclination) error relative to a specification.
calculate_agreement_and_k – normalises an agreement argument that may be given either as a σ-multiple (≥ 1) or as a coverage fraction (0 < x ≤ 1) and returns both the standardised agreement value and the corresponding coverage factor k.

Notes

SpecLimits and Specification are imported by the estimation module and used by ProcessEstimator and GageEstimator to relate sample statistics to engineering tolerances. calculate_agreement_and_k is a shared helper that is also re-exported from this module.

`SpecLimits(lower=float('-inf'), upper=float('inf'))` `dataclass` ¶

Class to hold the limits of a parameter specification.

PARAMETER	DESCRIPTION
`lower`	The lower limit of the specification. Default is -inf. TYPE: `float` DEFAULT: `float('-inf')`
`upper`	The upper limit of the specification. Default is inf. TYPE: `float` DEFAULT: `float('inf')`

`is_unbounded` `property` ¶

Check if any of lower or upper is -inf or inf.

`are_both_finite` `property` ¶

Check if both lower and upper are finite values.

`both_unbounded` `property` ¶

Check if both lower and upper are -inf and inf, respectively.

`tolerance` `property` ¶

Tolerance range, returns the difference between upper and lower limits. (read-only)

`nominal` `property` ¶

Nominal value, returns the average of upper and lower limits (read-only).

`to_tuple()` ¶

Returns the lower and upper limits as a tuple.

RETURNS	DESCRIPTION
`Tuple[float, float]`	A tuple containing the lower and upper limits in order.

`RandomProcessValue(specification, dist, clip=False, agreement=6)` ¶

Class to generate a random process value.

This class generates random values based on the specified distribution and parameters. The generated values are within the specified limits and tolerance. The class supports five types of distributions: normal, uniform, circular, coaxial, and perpendicular. The generated values can be clipped to the range defined by the tolerance. The class also provides a method to generate an array of random values.

PARAMETER	DESCRIPTION
`specification`	The specification for which the random value will be generated. TYPE: `Specification`
`dist`	The distribution from which the random value will be generated. TYPE: `(normal, uniform, circular, coaxial, perpendicular)` DEFAULT: `'normal'`
`clip`	Whether to clip the generated value to the range defined by the tolerance. Default is False. TYPE: `bool` DEFAULT: `False`
`agreement`	Specify the tolerated process variation for which the scale factor is calculated. - If int, the spread is determined using the normal distribution agreementσ, e.g. agreement = 6 -> 6σ ~ covers 99.75% of the data. - If float, the value must be between 0 and 1. This value is then interpreted as the acceptable proportion for the spread, e.g. 0.9973 (which corresponds to ~ 6σ) Default is 6. TYPE: `int \| float` DEFAULT: `6`

Examples:

Generate a random value from a uniform distribution:

import daspi as dsp

PARAM_I = dsp.Specification(limits=(5, 10))
PARAM_II = dsp.Specification(tolerance=0.1, nominal=3)

rpv = RandomProcessValue(PARAM_I, 'uniform')
value = rpv()

Generate an array from a normal distribution with clipping:

rpv = RandomProcessValue(PARAM_II, 'normal', clip=True)
array = rpv.generate(100_000)

Generate values with custom agreement (4σ instead of default 6σ):

rpv = RandomProcessValue(PARAM_II, 'normal', agreement=4)
value = rpv()
print(f'Scale factor: {rpv.scale}')  # TOLERANCE / 4

Use percentile-based agreement (95% coverage):

rpv = RandomProcessValue(PARAM_II, 'normal', agreement=0.95)
value = rpv()
print(f'Coverage factor k: {rpv.k}')  # ~1.96 for 95% confidence

`agreement` `property` `writable` ¶

Get the agreement multiplier for the σ (standard deviation).

The agreement is defined as twice the coverage factor k. When setting the agreement using a percentile, provide the acceptable proportion for the spread, such as 0.9973, which corresponds to approximately 6σ (six standard deviations). The agreement value must be specified as either: - A percentage (0.0 < agreement <= 1.0) indicating the acceptable proportion for the spread. - A multiple of the standard deviation (agreement >= 1).

Default is 6 (corresponding to 6σ or k=3).

`k` `property` ¶

Get the coverage factor k used in scale calculations (read-only).

This property returns the coverage factor, which is a multiplier used to determine the scale based on the agreement. The value of k is typically set to reflect the desired confidence level.

`scale` `property` ¶

Scale factor for the distribution based on agreement.

`loc` `property` ¶

Location parameter of the distribution.

`lower` `property` ¶

Lower bound of the distribution.

`upper` `property` ¶

Upper bound of the distribution.

`clip(value, min_value, max_value)` `staticmethod` ¶

Clip a value between a minimum and maximum value.

This function ensures that the provided value is within the specified range, clipping it if it falls outside the range.

PARAMETER	DESCRIPTION
`value`	The value to be clipped. TYPE: `float`
`min_value`	The minimum value of the range. TYPE: `float`
`max_value`	The maximum value of the range. TYPE: `float`

RETURNS	DESCRIPTION
`float`	The clipped value.

`normal()` ¶

Generate a random value within the specified tolerance range.

This function generates a random value within a range defined by the provided nominal and tolerance. The generated value is calculated by a normal distribution with a mean of the nominal and a standard deviation equal to the tolerance divided by 6.

RETURNS	DESCRIPTION
`float`	The generated random value within the specified tolerance range.

`uniform()` ¶

Generate a random value within the specified tolerance range.

This method generates a random value within the specified tolerance range using a uniform distribution.

RETURNS	DESCRIPTION
`float`	The generated random value within the specified tolerance range.

`circular()` ¶

Generate a randomized offset based on a circular distribution.

This function computes a randomized value by applying a circular offset to the provided tolerance. The offset is determined by multiplying the tolerance by the sine of a random angle uniformly distributed between 0 and 2π radians, simulating the effects of coaxiality in all possible directions.

RETURNS	DESCRIPTION
`float`	The modified value after applying the random circular offset.

`coaxial()` ¶

Generate a random coaxiality value.

This method generates a random coaxiality value by applying a circular distribution to the tolerance range. The amplitude of the coaxiality is determined by a normal distribution within the tolerance range, and the direction is randomized using a uniform distribution between 0 and 2π radians.

RETURNS	DESCRIPTION
`float`	The generated random coaxiality value.

`perpendicular()` ¶

Generate a random perpendicularity value.

This method generates a random perpendicularity value by applying a circular distribution to the tolerance range. The amplitude of the perpendicularity is determined by a normal distribution within the tolerance range, and the direction is randomized using a uniform distribution between 0 and 2π radians. In principle, this is exactly the same as coaxiality.

RETURNS	DESCRIPTION
`float`	The generated random perpendicularity value.

Notes

The returned value is in the same unit as the specified tolerance (usually mm). When specifying tolerances according to GPS, a protractor is held against the measuring object, and the maximum gap must not be larger than the specified tolerance. For further information, see: https://www.keyence.de/ss/products/measure-sys/gd-and-t/orientation-tolerance/perpendicularity.jsp

`generate(n)` ¶

Generate an array of random values.

This method generates an array of random values by calling the appropriate distribution method (normal or uniform) for the specified number of times.

PARAMETER	DESCRIPTION
`n`	The number of random values to generate. TYPE: `int`

RETURNS	DESCRIPTION
`NDArray[float64]`	An array of random values.

`Binning(data, num_bins, kind='quantile', distance=None)` ¶

A class for binning precise values into a specified number of bins.

This class is designed to handle scenarios where precise values are available only at certain intervals with a defined tolerance. It provides methods to bin these values using either a linear or quantile approach.

The binning method is determined by the kind parameter: - If kind is set to 'linear', bin edges are calculated based on the minimum and maximum values of the provided data. - If kind is set to 'quantile', bin edges are determined by the quantiles of the input data.

The values method assigns each data point to the nearest bin using a digitizing function. For more accurate results, the round_to_nearest method can be used to round the bin nominal values.

PARAMETER	DESCRIPTION
`data`	The precise values to be binned and used for calculations. TYPE: `NDArray[float64] \| Series`
`num_bins`	The total number of bins to create. TYPE: `int`
`kind`	The method to calculate the bin edges, default is 'quantile'. TYPE: `Literal['linear', 'quantile']` DEFAULT: `'quantile'`
`distance`	The distance between the bins, representing the process tolerance. This parameter is only relevant when `kind` is 'linear' and must be specified in that case. Default is None. TYPE: `float \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`AssertionError`	If the `distance` is not specified when `kind` is 'linear'.

Examples:

Example 1: Binning with linear approach

import numpy as np
import daspi as dsp
data = np.array([1.5, 2.3, 3.7, 4.1, 5.0])
binning = dsp.Binning(data, num_bins=3, distance=1.0, kind='linear')
binned_values = binning.values()
print(f'{binning.nominals=}')
print(f'{binning.indices=}')
print(binned_values)

binning.nominals=array([2.32, 3.32, 4.32])
binning.indices=array([0, 0, 1, 2, 2])
[2.32, 2.32, 3.32, 4.32, 4.32]

Example 2: Binning with quantile approach

data = np.array([1.5, 2.3, 3.7, 4.1, 5.0])
binning = dsp.Binning(data, num_bins=3, kind='quantile')
binned_values = binning.values()
print(f'{binning.nominals=}')
print(f'{binning.indices=}')
print(binned_values)

binning.nominals=array([2.3, 3.7, 4.1])
binning.indices=array([0, 0, 1, 2, 2])
[2.3, 2.3, 3.7, 4.1, 4.1]

Example 3: Rounding nominals

data = np.array([1.5, 2.3, 3.7, 4.1, 5.0])
binning = dsp.Binning(data, num_bins=3, kind='quantile')
binning.round_to_nearest(nearest=5, digit=1)
binned_values = binning.values()
print(f'{binning.nominals=}')
print(binned_values)

binning.nominals=array([2.5, 3.5, 4.0])
[2.5, 2.5, 3.5, 4.0, 4.0]

`round_to_nearest(nearest=5, digit=3)` ¶

Round to the nearest multiple of nearest.

This function rounds the input data to the nearest multiple of the specified nearest value at the specified digit.

PARAMETER	DESCRIPTION
`nearest`	The multiple to round to, by default 5. TYPE: `int` DEFAULT: `5`
`digit`	The number of decimal places to round to, by default 3. TYPE: `int` DEFAULT: `3`

RETURNS	DESCRIPTION
`Self`	The instance with the rounded nominals.

`values()` ¶

Get the binned values based on the calculated indices and nominals.

RETURNS	DESCRIPTION
`NDArray[float64]`	The binned values.

`round_to_nearest(x, nearest=5, digit=3)` ¶

Round to the nearest multiple of nearest.

This function rounds the input data to the nearest multiple of the specified nearest value at the specified digit.

PARAMETER	DESCRIPTION
`x`	The input data to be rounded. TYPE: `float \| NDArray[float64] \| Series`
`nearest`	The multiple to round to, by default 5. TYPE: `int` DEFAULT: `5`
`digit`	The number of decimal places to round to, by default 3. TYPE: `int` DEFAULT: `3`

RETURNS	DESCRIPTION
`float \| NDArray[float64] \| Series`	The rounded data as the same type as the input.

`inclination_displacement(perpendicularity, height, distance)` ¶

Calculate the displacement from a distant point due to perpendicularity deviation. Perpendicularity is measured in mm. To calculate the angle, the height at which perpendicularity is measured is required as the maximum distance in the drawing.

\[ displacement = distance * sin(arctan(perpendicularity/height)) \]

PARAMETER	DESCRIPTION
`perpendicularity`	The perpendicularity of the surface. TYPE: `float \| NDArray[float64] \| Series`
`distance`	The distance from the point to the surface. TYPE: `float`

RETURNS	DESCRIPTION
`float \| NDArray[float64] \| Series`	The displacement of the point.

Monte-Carlo Library

daspi.statistics.montecarlo ¶

SpecLimits(lower=float('-inf'), upper=float('inf')) dataclass ¶

is_unbounded property ¶

are_both_finite property ¶

both_unbounded property ¶

tolerance property ¶

nominal property ¶

to_tuple() ¶

RandomProcessValue(specification, dist, clip=False, agreement=6) ¶

agreement property writable ¶

k property ¶

scale property ¶

loc property ¶

lower property ¶

upper property ¶

clip(value, min_value, max_value) staticmethod ¶

normal() ¶

uniform() ¶

circular() ¶

coaxial() ¶

perpendicular() ¶

generate(n) ¶

Binning(data, num_bins, kind='quantile', distance=None) ¶

round_to_nearest(nearest=5, digit=3) ¶

values() ¶

round_to_nearest(x, nearest=5, digit=3) ¶

inclination_displacement(perpendicularity, height, distance) ¶