risksim

Portfolio Monte Carlo simulation and risk measures: simulate aggregate outcomes across a portfolio of contracts and summarize the distribution with standard risk measures. numpy only.

The package builds a portfolio from contract definitions, simulates aggregate outcomes, and reports risk measures (such as value-at-risk and tail value-at-risk) over the simulated distribution — the capital view that sits at the end of the experience → pricing → loss → tail → capital pipeline.

var and tvar follow the ecosystem-wide empirical estimators (inverted-CDF order statistic; Acerbi–Tasche), so a portfolio’s risk measures here match the same quantities computed in lossmodels or extremeloss byte for byte, and every simulation accepts the shared rng argument (None, seed, or Generator) for bit-reproducible runs — see Conventions.

See the API reference below for the full surface; each object’s docstring carries its own usage.

API reference

class AggregateLayer(attachment: float = 0.0, limit: float | None = None, share: float = 1.0, name: str | None = None)

Bases: object

Aggregate annual layer applied to simulated aggregate losses.

For aggregate annual loss S, ceded loss is:

C = share * min((S - attachment)+, limit)

with no cap if limit is None.

attachment_probability(losses: ndarray | list[float]) → float

Probability that a loss reaches the layer, i.e. P(loss > attachment).

This depends only on the attachment point, not on share or limit, so it stays correct under degenerate parameters (e.g. share=0).

apply_contract(losses: ndarray | list[float], contract: AggregateLayer | ContractProgram) → tuple[ndarray, ndarray]

Return (ceded, retained) arrays for a single aggregate layer or a multi-layer contract program.

class ContractProgram(layers: Sequence[AggregateLayer], name: str = 'contract_program')

Bases: object

Collection of aggregate layers applied to the same gross loss.

This first version assumes the layers are intended to work together without overlap. For a standard non-overlapping tower, total ceded loss is the row-wise sum of ceded loss by layer.

class Portfolio(items: Sequence[PortfolioItem], name: str = 'portfolio')

Bases: object

Portfolio of aggregate-loss components.

This first version assumes components are sampled independently.

variance() → float

Analytic variance under the independence assumption.

class PortfolioItem(name: 'str', model: 'SupportsSample', weight: 'float' = 1.0)

Bases: object

class SimulationResult(gross_losses: ndarray, ceded_losses: ndarray | None = None, retained_losses: ndarray | None = None, component_losses: ndarray | None = None, component_names: Sequence[str] | None = None, layer_losses: ndarray | None = None, layer_names: Sequence[str] | None = None, contract_name: str | None = None)

Bases: object

Container for portfolio simulation outputs.

If retained_losses is present, the primary losses view is retained/net loss. Otherwise, the primary losses view is gross loss.