inventory.safety-stock

def safety_stock(input: SafetyStockInput) -> int

SafetyStockMethod = Literal["service-level", "max-minus-average"]

@dataclass(frozen=True)
class SafetyStockInput:
    """What each method needs; fields the chosen method does not use may be null."""

    method: SafetyStockMethod
    #: service-level: cycle service level, 9500 = 95%; one of the levels in the z-score table
    service_level_basis_points: Optional[int]
    #: service-level: standard deviation of demand per period (a day, a week)
    demand_std_dev: Optional[float]
    #: lead time in the same periods; the average lead time for max-minus-average
    lead_time: float
    #: average demand per period; max-minus-average, and service-level when lead time varies
    average_demand: Optional[float]
    #: service-level: standard deviation of lead time, in periods; null when lead time is fixed
    lead_time_std_dev: Optional[float]
    #: max-minus-average: the highest demand in one period
    max_demand: Optional[float]
    #: max-minus-average: the longest lead time, in periods
    max_lead_time: Optional[float]

from fune.inventory.safety_stock import safety_stock  # inventory.safety-stock@^1

import math
from typing import Optional

from .inventory_safety_stock_data import Z_SCORES  ← this capability’s own data, compiled from data/z-scores.json into the same file by fune build
from .inventory_safety_stock_types import SafetyStockInput


def _amount(name: str, value: Optional[float], method: str) -> float:
    if value is None:
        raise ValueError("%s needs %s" % (method, name))
    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0:
        raise ValueError("%s must be a finite number, not negative, received %r" % (name, value))
    return float(value)


def _whole_units_up(x: float) -> int:
    # Six decimal places, half away from zero, then up to whole units: float
    # noise such as 55.00000000000001 must not cost a whole extra unit.
    y = x * 1e6
    micro = math.floor(y)
    if y - micro >= 0.5:
        micro += 1
    return (micro + 999999) // 1000000


def safety_stock(input: SafetyStockInput) -> int:
    """Safety stock in whole units, by the service-level or max-minus-average method."""
    lead_time = _amount("leadTime", input.lead_time, input.method)
    if input.method == "service-level":
        level = input.service_level_basis_points
        if level is None:
            raise ValueError("service-level needs serviceLevelBasisPoints")
        row = next((r for r in Z_SCORES if r.service_level_basis_points == level), None)
        if row is None:
            raise ValueError(
                "no z-score for a service level of %s basis points: use one of %s"
                % (level, ", ".join(str(r.service_level_basis_points) for r in Z_SCORES))
            )
        sd = _amount("demandStdDev", input.demand_std_dev, input.method)
        variance = lead_time * sd * sd
        sl = _amount("leadTimeStdDev", 0.0 if input.lead_time_std_dev is None else input.lead_time_std_dev, input.method)
        if sl > 0:
            d = _amount("averageDemand", input.average_demand, "service-level with a varying lead time")
            variance = variance + d * d * sl * sl
        return _whole_units_up((row.z_ten_thousandths / 10000) * math.sqrt(variance))
    if input.method == "max-minus-average":
        max_demand = _amount("maxDemand", input.max_demand, input.method)
        max_lead_time = _amount("maxLeadTime", input.max_lead_time, input.method)
        average_demand = _amount("averageDemand", input.average_demand, input.method)
        worst = max_demand * max_lead_time
        usual = average_demand * lead_time
        if worst < usual:
            raise ValueError(
                "maxDemand x maxLeadTime (%s) must not be less than averageDemand x leadTime (%s)" % (worst, usual)
            )
        return _whole_units_up(worst - usual)
    raise ValueError('unknown safety stock method "%s"' % (input.method,))

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add inventory.safety-stock

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./inventory.safety-stock-1.0.0-python.fune, or fetch it from a terminal with fune pull inventory.safety-stock@1.0.0:python.

The whole function, every language, is one file too: inventory.safety-stock-1.0.0.fune, 23,713 bytes, sha256 d75657642e13f1c5f479aa6efcabc22b9f8cbee52afacec946682c4e660bdb76. It installs into a project of any language.

# fune: before inventory.safety-stock

# fune: after inventory.safety-stock

# fune: step inventory.safety-stock after <n|label>

More from the author

safety stock = z x sqrt(L x sd^2 + d^2 x sL^2)

where `z` is the standard normal quantile for the service level, `L` the average lead time, `sd` the standard deviation of demand per period, `d` the average demand per period and `sL` the standard deviation of the lead time. When lead time is fixed (`leadTimeStdDev` null or 0) this is the familiar `z x sd x sqrt(L)`, and `averageDemand` is not needed. Demand and lead time must be in the same period: a daily standard deviation with a lead time in days. `stats.standard-deviation` gives `sd` from a demand history.

The service level is the **cycle service level**: the chance of not running out during one replenishment cycle. It is not the fill rate. `z` comes from a table (`data/z-scores.json`) of the levels people actually use, 50% to 99.9%, rather than an inverse normal function, which would be approximated differently in each language. Each value is the quantile rounded to four decimal places, e.g. 95% is 1.6449 and 97.5% is 1.9600. A level not in the table is an error; round to one that is.

**`max-minus-average`** - the rule of thumb that needs no statistics:

safety stock = maxDemand x maxLeadTime - averageDemand x leadTime

It is an error for the worst case to be below the average case.

**Rounding.** Both methods compute in floating point, which is fine for a statistical estimate but can land a whisker above a whole number (`2.2 x 25` is `55.00000000000001`). The figure is rounded to 6 decimal places (half away from zero) and then **up** to whole units, so 50.000000000000014 is 50 and not 51, and 98.694 is 99. All values must be finite and not negative.

Sources: z values are the standard normal quantiles, checked against NIST/SEMATECH e-Handbook of Statistical Methods, section 1.3.6.7.1, "Cumulative Distribution Function of the Standard Normal Distribution" (https://www.itl.nist.gov/div898/handbook/eda/section3/eda3671.htm), and computed to four places with Python's `statistics.NormalDist().inv_cdf`. The combined-variability formula is the standard one in Silver, Pyke and Thomas, *Inventory and Production Management in Supply Chains*, 4th ed., ch. 6.

Files