Usage Guide

This guide provides comprehensive examples of using the Proteus Actuarial Library (PAL).

Creating Stochastic Variables

Basic Stochastic Variables

Stochastic variables can be created with the StochasticScalar class:

from pal import StochasticScalar

# Create from array
svariable = StochasticScalar([1, 2, 3, 4])

Statistical Distributions

Statistical distributions are available in the distributions module:

from pal import distributions

# Create gamma distribution
gamma_var = distributions.Gamma(alpha=2.5, theta=2).generate()

# Create log-normal distribution
lognormal_var = distributions.LogNormal(mu=1, sigma=0.5).generate()

Variable Containers

Variables can be grouped into containers with the ProteusVariable class:

from pal import ProteusVariable, distributions

# Create individual variables
motor_losses = distributions.Gamma(alpha=2.5, theta=2).generate()
property_losses = distributions.LogNormal(mu=1, sigma=0.5).generate()

# Group into container
portfolio = ProteusVariable(
    dim_name="line",
    values={"Motor": motor_losses, "Property": property_losses}
)

Variable containers support numpy operations and can be added, multiplied together etc. Operations involving multiple variable containers will attempt to match on dictionary labels.

Copulas and Dependencies

Statistical dependencies between PAL variables can be modeled using copulas:

from pal import copulas, distributions

# Create independent variables
var1 = distributions.Gamma(alpha=2.5, theta=2).generate()
var2 = distributions.LogNormal(mu=1, sigma=0.5).generate()

# Apply copula to create dependency
copulas.GumbelCopula(theta=1.2).apply([var1, var2])

Variable Coupling

PAL automatically tracks variables that have been used in formulas together (coupled variables):

from pal import distributions
# These variables become coupled
var1 = distributions.Gamma(alpha=2.5, theta=2).generate()
var2 = distributions.LogNormal(mu=1, sigma=0.5).generate()
var3 = var1 + var2  # var1, var2, and var3 are now coupled

# If a copula reorders var3, var1 and var2 are automatically reordered too

Configuration

Simulation Settings

Configure the global number of simulations:

from pal import config, set_random_seed

# Change simulation count (default is 100,000)
config.n_sims = 1000000

# Set random seed for reproducibility
set_random_seed(123456)

PAL uses the default_rng class from numpy.random, which can also be configured via config.rng.

GPU Acceleration

For CUDA-compatible GPUs, install GPU dependencies:

pdm install -G gpu

Enable GPU mode by setting the environment variable:

# Linux
export PAL_USE_GPU=1

# Windows
set PAL_USE_GPU=1

Set to any other value to revert to CPU mode.

Advanced Examples

For more complex examples including reinsurance modeling and catastrophe simulations, see the examples directory in the GitHub repository.

Performance Tips

Use appropriate simulation counts - Start with smaller counts for development
Leverage GPU acceleration for large simulations if available
Consider memory usage when working with very large portfolios
Use vectorized operations where possible for better performance