Skip to content

particula.util.machine_limit

machine_limit

Machine max or min overflow protection.

get_safe_exp 

get_safe_exp(value: ArrayLike) -> np.ndarray

Compute the exponential of each element in the input array, with overflow protection.

The exponential is calculated using
  • y = exp(x), where x is clipped to avoid exceeding machine limits.

Parameters:

  • - value –

    Array-like of values to exponentiate.

Returns:

  • ndarray –
    • np.ndarray of exponentiated values, with machine-level clipping.

Examples:

Example Usage
import numpy as np
import particula as par

arr = np.array([0, 10, 1000])
print(par.get_safe_exp(arr))
# Output: [1.00000000e+000 2.20264658e+004 1.79769313e+308]
References
  • "Floating Point Arithmetic," NumPy Documentation, NumPy.org.
Source code in particula/util/machine_limit.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def get_safe_exp(value: ArrayLike) -> np.ndarray:
    """Compute the exponential of each element in the input array, with overflow
    protection.

    The exponential is calculated using:
        - y = exp(x), where x is clipped to avoid exceeding machine limits.

    Arguments:
        - value : Array-like of values to exponentiate.

    Returns:
        - np.ndarray of exponentiated values, with machine-level clipping.

    Examples:
        ``` py title="Example Usage"
        import numpy as np
        import particula as par

        arr = np.array([0, 10, 1000])
        print(par.get_safe_exp(arr))
        # Output: [1.00000000e+000 2.20264658e+004 1.79769313e+308]
        ```

    References:
        - "Floating Point Arithmetic," NumPy Documentation, NumPy.org.
    """
    value = np.asarray(value, dtype=np.float64)
    max_exp_input = np.log(np.finfo(value.dtype).max)
    return np.exp(np.clip(value, None, max_exp_input))

get_safe_log 

get_safe_log(value: ArrayLike) -> np.ndarray

Compute the natural logarithm of each element in the input array, with underflow protection.

The natural log is calculated using
  • y = ln(x), where x is clipped away from zero to maintain positivity.

Parameters:

  • - value –

    Array-like of values for logarithm calculation.

Returns:

  • ndarray –
    • np.ndarray of natural logarithms, with machine-level clipping.

Examples:

Example Usage
import numpy as np
import particula as par

arr = np.array([1e-320, 1.0, 10.0])
print(get_safe_log(arr))
# Output: [-7.40545337e+02  0.00000000e+00  2.30258509e+00]
References
  • "Logarithms and Machine Precision," NumPy Documentation, NumPy.org.
Source code in particula/util/machine_limit.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def get_safe_log(value: ArrayLike) -> np.ndarray:
    """Compute the natural logarithm of each element in the input array, with
    underflow protection.

    The natural log is calculated using:
        - y = ln(x), where x is clipped away from zero to maintain positivity.

    Arguments:
        - value : Array-like of values for logarithm calculation.

    Returns:
        - np.ndarray of natural logarithms, with machine-level clipping.

    Examples:
        ``` py title="Example Usage"
        import numpy as np
        import particula as par

        arr = np.array([1e-320, 1.0, 10.0])
        print(get_safe_log(arr))
        # Output: [-7.40545337e+02  0.00000000e+00  2.30258509e+00]
        ```

    References:
        - "Logarithms and Machine Precision," NumPy Documentation, NumPy.org.
    """
    value = np.asarray(value, dtype=np.float64)
    min_positive_value = np.nextafter(0, 1, dtype=value.dtype)
    return np.log(np.clip(value, min_positive_value, None))

get_safe_log10 

get_safe_log10(value: ArrayLike) -> np.ndarray

Compute the base-10 logarithm of each element in the input array, with underflow protection.

The base-10 log is calculated using
  • y = log10(x), x clipped from zero to maintain positivity.

Parameters:

  • - value –

    Array-like of values for base-10 logarithm calculation.

Returns:

  • ndarray –
    • np.ndarray of base-10 logarithms, with machine-level clipping.

Examples:

Example Usage
import numpy as np
import particula as par

arr = np.array([1e-320, 1.0, 1000.0])
print(par.get_safe_log10(arr))
# Output: [-320.           0.           3.        ]
References
  • "Logarithms and Machine Precision," NumPy Documentation, NumPy.org.
Source code in particula/util/machine_limit.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_safe_log10(value: ArrayLike) -> np.ndarray:
    """Compute the base-10 logarithm of each element in the input array, with
    underflow protection.

    The base-10 log is calculated using:
        - y = log10(x), x clipped from zero to maintain positivity.

    Arguments:
        - value : Array-like of values for base-10 logarithm calculation.

    Returns:
        - np.ndarray of base-10 logarithms, with machine-level clipping.

    Examples:
        ``` py title="Example Usage"
        import numpy as np
        import particula as par

        arr = np.array([1e-320, 1.0, 1000.0])
        print(par.get_safe_log10(arr))
        # Output: [-320.           0.           3.        ]
        ```

    References:
        - "Logarithms and Machine Precision," NumPy Documentation, NumPy.org.
    """
    value = np.asarray(value, dtype=np.float64)
    min_positive_value = np.nextafter(0, 1, dtype=value.dtype)
    return np.log10(np.clip(value, min_positive_value, None))

get_safe_power 

get_safe_power(base: ArrayLike, exponent: ArrayLike) -> np.ndarray

Compute the power (base ** exponent) with overflow protection.

The power is computed as: result = exp(exponent * log(base)) where the intermediate value is clipped to avoid overflow beyond the machine limits. This function assumes that base contains positive values. The behavior for non-positive bases is undefined.

Parameters:

  • - base –

    Array-like of positive base values.

  • - exponent –

    Array-like of exponents.

Returns:

  • ndarray –
    • np.ndarray of power values, computed with machine-level clipping.

Examples:

Example Usage
import numpy as np
import particula as par

base = np.array([1, 2, 3])
exponent = np.array([1, 2, 3])
print(par.get_safe_power(base, exponent))
# Output: [ 1.  4. 27.]
References
  • "Floating Point Arithmetic," NumPy Documentation, NumPy.org.
Source code in particula/util/machine_limit.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
@validate_inputs(
    {
        "base": "positive",
    }
)
def get_safe_power(base: ArrayLike, exponent: ArrayLike) -> np.ndarray:
    """Compute the power (base ** exponent) with overflow protection.

    The power is computed as: result = exp(exponent * log(base))
    where the intermediate value is clipped to avoid overflow beyond the
    machine limits. This function assumes that `base` contains positive values.
    The behavior for non-positive bases is undefined.

    Arguments:
        - base : Array-like of positive base values.
        - exponent : Array-like of exponents.

    Returns:
        - np.ndarray of power values, computed with machine-level clipping.

    Examples:
        ``` py title="Example Usage"
        import numpy as np
        import particula as par

        base = np.array([1, 2, 3])
        exponent = np.array([1, 2, 3])
        print(par.get_safe_power(base, exponent))
        # Output: [ 1.  4. 27.]
        ```

    References:
        - "Floating Point Arithmetic," NumPy Documentation, NumPy.org.
    """
    base = np.asarray(base, dtype=np.float64)
    exponent = np.asarray(exponent, dtype=np.float64)

    # Compute the intermediate value using logarithm.
    intermediate = exponent * np.log(base)

    # Compute the maximum safe value for the exponent in np.exp.
    max_exp_input = np.log(MAX_POSITIVE_VALUE)

    # Clip the intermediate result to prevent overflow.
    intermediate_clipped = np.clip(intermediate, None, max_exp_input)

    return np.exp(intermediate_clipped)