modelling/math_utils.py

import numpy as np
from scipy.stats import norm as _scipy_norm


def natural_log(value):
    """Return natural logarithm (base e)."""
    return np.log(float(value))


def normal_quantile_bound(std, q):
    """Upper bound of N(0, std²) at one-sided tail probability q.

    Returns ppf(1-q) * std so that P(X > result) = q for X ~ N(0, std²).

    Examples:
      q=0.1  → z≈1.282 → inner shading band (±10% one-sided tails, 80% coverage)
      q=0.01 → z≈2.326 → outer shading band (±1% one-sided tails, 98% coverage)

    Works element-wise on numpy arrays or plain Python lists.
    """
    return float(_scipy_norm.ppf(1.0 - q)) * np.asarray(std, dtype=float)