Skip to content

Monte Carlo

riskpy.mc is for the case where the formula is too awkward to solve. Instead of integrating, you feed it random inputs a few hundred thousand times and read the distribution that falls out.

pip install "open-riskpy[sim]"

The shape of it

from riskpy import viz
from riskpy.mc import (
    Model, Compound, Poisson, LogNormal, Normal, PERT,
    Gamma, NegativeBinomial, Pareto, Mixture, Truncated, Categorical,
)

model = Model(
    claims               = Compound(Poisson(mean=140), LogNormal.from_moments(mean=18_000, sd=42_000)),
    inflation            = Normal(mean=0.043, sd=0.012),
    reinsurance_recovery = PERT(low=0.0, mode=0.15, high=0.45),
)

@model.formula
def annual_loss(claims, inflation, reinsurance_recovery):
    gross = claims * (1 + inflation)
    return gross * (1 - reinsurance_recovery)

result = model.run(200_000, seed=42)

Compound(frequency, severity) is the year's total: it draws a claim count, then one claim size per claim, and adds them up. Writing claim_count * severity instead multiplies a single claim size by the count — as if all 140 claims were the same size — and puts the 1-in-200 loss for this book at 34 million instead of 4.5 million.

Your formula is called once, with NumPy arrays of length trials — not once per trial. Two hundred thousand trials is a single vectorised expression.

If your formula has branching NumPy cannot express, pass vectorised=False and it is looped instead. Correct, just slower.

Always pass a seed

seed=42 makes a run reproducible. Without one you get a different answer every time, which is fine for exploring and miserable for a report someone else has to check.

Without the decorator

simulate() is the same engine with no Model object, which reads better when you are sweeping scenarios in a loop:

from riskpy.mc import simulate, Constant

result = simulate(
    lambda claims: claims,
    trials=100_000, seed=42, label="annual loss",
    claims=Compound(Poisson(mean=140), LogNormal.from_moments(mean=18_000, sd=42_000)),
)

Or let the model sweep for you — same seed for every scenario, so the differences are the scenarios and not the noise:

scenarios = model.sweep("reinsurance_recovery", {
    "no cover":        Constant(0.0),
    "quota share 15%": Constant(0.15),
    "negotiated":      PERT(0.05, 0.25, 0.5),
}, trials=100_000, seed=42)
viz.compare(scenarios)

Distributions

Continuous Discrete Composite
Normal(mean, sd) Poisson(mean) Constant(value)
LogNormal(mu, sigma) NegativeBinomial(n_success, p) Empirical(data)
Uniform(low, high) Bernoulli(p) Categorical(values, probs)
Triangular(low, mode, high) Binomial(trials, p) Mixture([dists], weights)
Compound(frequency, severity)
PERT(low, mode, high, lam=4) Truncated(dist, low, high)
Exponential(scale)
Gamma(shape, scale)
Beta(a, b)
Pareto(xm, alpha)
Weibull(shape, scale)
StudentT(df, loc, scale)

Alternative constructors exist where the raw parameters are never the numbers you actually have:

LogNormal.from_moments(mean=18_000, sd=42_000)     # not mu and sigma of the log
LogNormal.from_median_cv(median=12_000, cv=1.8)    # how reinsurance quotes them
Gamma.from_moments(mean=12, sd=4)
NegativeBinomial.from_mean_dispersion(mean=140, dispersion=2.4)

Pareto with a light tail index

Pareto has an infinite mean for alpha <= 1 and infinite variance for alpha <= 2. The sample mean will still print a number. It will not mean anything — and Pareto(...).moments() will say inf, which is the honest answer.

Parameters are validated when the distribution is constructed, not when it is sampled — a negative standard deviation is a typo, and finding out after a ten-second run is worse than useless.

The analytic layer

Every distribution knows more than how to sample itself:

d = Gamma(2.5, 1.7)
d.pdf(x), d.cdf(x), d.ppf(q)     # vectorised; scalar in, scalar out
d.moments()                       # Moments(mean=4.25, variance=7.225) with .sd and .cv
d.support()                       # (0.0, inf)

The quantile functions are accurate to around 1e-10 relative or better across the whole range, and to machine precision in the extreme tails, where the survival function is inverted directly rather than the CDF. They are what make Latin hypercube sampling, truncation and correlated inputs possible, and they are built on a dependency-free special-function layer (incomplete gamma and beta, Student-t) that is checked against SciPy in the test suite without ever requiring it.

Composites

Mixture([LogNormal(8, 1), Pareto(50_000, 2.5)], weights=[0.9, 0.1])   # attritional + large
Truncated(LogNormal(8, 1), high=1_000_000)                            # a policy limit
Truncated(Normal(0.04, 0.02), low=0.0)                                # a rate that cannot go negative
Categorical([0.9, 1.0, 1.15], probs=[0.2, 0.6, 0.2])                  # scenario weights
Compound(NegativeBinomial(5, 0.04), LogNormal(9, 1.5))                # a year's total: sum of N claims

Truncated samples by inversion, so it never rejects and never loops, and its moments are integrated numerically to about 1e-8 relative.

Dependence

Inputs are independent unless you say otherwise. Two ways to say otherwise:

model.correlate("claims", "inflation", 0.3)                   # Spearman rank correlation
model.correlate("inflation", "reinsurance_recovery", -0.2)

result = simulate(fn, ..., correlation={("a", "b"): 0.7})   # or a full matrix

This is Iman–Conover: the samples are drawn independently and then re-paired so their ranks follow a correlated normal score matrix. The marginals are untouched — every sampled value is kept — which is why it works with any distribution and with Latin hypercube draws. The recovered rank correlation lands within 0.01 of the target at 100k trials.

A set of pairwise correlations can be jointly impossible; the error names the smallest eigenvalue rather than letting a Cholesky failure surface later, and the refused pair is not kept on the model. A matrix with a NaN or infinite entry is refused with RP101.

For tail dependence a correlation cannot express, run, sample and simulate accept copula=. riskpy.capital has five — Gaussian, Student t, Clayton, Gumbel and Frank — each with its closed-form Kendall's tau and tail dependence:

from riskpy.capital import StudentTCopula

result = model.run(100_000, seed=42, copula=StudentTCopula(0.3, df=4))

The copula's uniforms are pushed through each distribution's ppf, in the order the variables were declared. A variable with no quantile function (a Compound) is simulated and reordered to the copula's ranks instead. Any object with .dim and .uniforms(n, rng) returning an (n, dim) array works. Note that a copula's correlation is that of its latent variables, not the Spearman correlation correlate takes; GaussianCopula(rho).spearman_rho() converts.

Scatter

Latin hypercube sampling

result = model.run(200_000, seed=42, sampling="lhs")

One draw from each of n equal-probability strata, in random order. Same marginal, far less noise: the standard deviation of the estimated mean falls by a factor of two to three for typical loss models, at no cost. Distributions without a quantile function fall back to plain sampling for that input.

It combines with correlate (the stratified draws are re-paired) and, since 0.8.0, with copula=. Under a copula each variable keeps the copula's ranks, which carry all of the dependence, and its uniform is moved into the stratum its rank points to: (rank + V) / n with V uniform. So the marginals are stratified and the dependence is exactly the copula's. A Compound is drawn with its own Latin hypercube method and put in the copula's order. Before 0.8.0 sampling="lhs" was silently ignored when a copula was given.

Reading the result

result.mean, result.std, result.median
result.skewness, result.kurtosis    # how badly a normal approximation will do
result.standard_error               # how much the mean would move on a new seed
result.percentile(99.5)
result.var(0.995)                   # Value at Risk
result.tvar(0.995)                  # expected shortfall (Acerbi–Tasche; = mean beyond VaR when no ties)
result.cdf(5e6)                     # P(output <= x)
result.prob_above(5e6)
result.describe()                   # a dict of the lot
result.values                       # the raw array

summary() returns the headline table as a string. For the model on this page, with its two correlations and sampling="lhs":

Monte Carlo — annual_loss
  trials       200,000   seed 42
  mean         2,178,785.66   ± 23,229.21 (95% CI)
  std dev      5,300,213.95   skew +25.06
  min / max    1,809.39 / 737,951,531.59

  level        VaR              TVaR
  50.000%          847,483.26     3,988,906.14
  75.000%        2,134,575.78     6,608,175.09
  90.000%        4,916,632.64    11,708,574.21
  95.000%        8,128,962.41    17,180,392.03
  99.000%       20,664,267.01    37,318,456.01
  99.500%       29,220,862.23    50,413,329.25

Quantile queries sort once and cache the order, so asking for a dozen VaR levels costs one sort, not twelve.

VaR and TVaR

var(0.995) is the loss exceeded 0.5% of the time. tvar(0.995) is the average of those worst 0.5% of outcomes, so it is always at least as large.

Prefer TVaR for the reason regulators do: VaR tells you where the threshold is and nothing whatsoever about how bad things get past it. Two portfolios with identical VaR can have wildly different tails.

Did I run enough trials?

standard_error is how much the mean would wobble on a different seed. It shrinks with the square root of the trial count, so ten times the precision costs a hundred times the work — or one switch to sampling="lhs".

n, running_mean, half_width = result.convergence()
result.plot("convergence")

What is driving the answer?

for name, correlation in result.sensitivity():
    print(f"{name:24} {correlation:+.2f}")
claims                   +0.88
reinsurance_recovery     -0.44
inflation                +0.05

Spearman rank correlation by default — the relationship between an input and a total is usually monotonic and rarely linear. method="pearson" for the linear case and method="contribution" for each input's share of explained variance. Plot it with result.plot("tornado").

What if? Stress and reverse stress

model.stress({...}) re-evaluates the formula under named scenarios on the same random draws as the base run, and result.reverse_stress(0.995) reports what the inputs looked like in the worst trials. Both are covered in Stress and scenario testing.

stress = model.stress({"inflation 8%": {"inflation": 0.08}}, trials=100_000, seed=42)
stress.delta("inflation 8%", "var", 0.995)

result.reverse_stress(0.995).scenario      # {'claims': …, 'inflation': …}

Exporting

result.to_frame()      # pandas DataFrame (needs pandas): every input column plus the output
result.histogram(60)   # (edges, counts)
result.exceedance_curve()

Common errors, and what they mean

"The formula returned shape (), expected (200000,)" — your formula collapsed the arrays to a scalar. Usually an if (use np.where), a min() (use np.minimum), or a sum() that should not be there.

"12,431 of 200,000 trials produced NaN or infinity" — nearly always a division by a variable that can reach zero, or a log of one that can go negative. The count tells you how much of the tail is involved.

"claim_count must be a Distribution, got float" — wrap fixed numbers in Constant(...). This is deliberate: silently accepting a bare number makes it easy to freeze an input you meant to vary.

"'formula' is a function, but Model() takes only distributions" — the keywords of Model(...) and simulate(...) are the random inputs. Register the formula with @model.formula (or model.formula(fn)), pass it to model.run(fn=...), or give it to simulate as the first argument.

"trials must be a whole number >= 1" (RP107) — trials is an integer: 100_000, not 1e5. seed is None or an integer >= 0 (a NumPy SeedSequence or Generator also works); a negative seed is RP102.

"correlation matrix is not positive semi-definite" — the pairwise correlations you asked for cannot all hold at once. Reduce the strongest ones.