quactuary package

Subpackages

Submodules

quactuary.backend module

Backend selection and execution module.

Provides plumbing to choose between quantum (Qiskit) and classical execution backends. Abstracts backend management so user-facing models receive numeric results regardless of execution mode.

Examples

>>> from quactuary.backend import get_backend, set_backend
>>> manager = get_backend()
>>> set_backend('quantum', provider='AerSimulator')
class quactuary.backend.BackendManager(backend)

Bases: object

Manager for quantum and classical backends.

Manages backend assignments and executes quantum circuits or classical simulations.

__init__(backend)

Initialize a BackendManager.

Parameters:

backend – Backend instance (e.g., Qiskit backend or custom classical engine).

get_backend()

Retrieve the active backend.

Returns:

The current backend instance.

run(circuit)

Execute a circuit on the active backend.

Parameters:

circuit – QuantumCircuit or equivalent object to run.

Returns:

Execution result or job output.

Return type:

Result

Examples

>>> result = backend_manager.run(qc)
set_backend(backend)

Override the active backend.

Parameters:

backend – New backend instance.

quactuary.backend.get_backend()

Retrieve or initialize the global BackendManager.

Returns:

Singleton backend manager instance.

Return type:

BackendManager

quactuary.backend.set_backend(mode, provider=None, **kwargs)

Configure the global execution backend.

Parameters:

  • mode (str) – Type of execution (‘quantum’ or ‘classical’).

  • provider (Optional[str]) – Quantum provider name (‘AerSimulator’, ‘IBMQ’).

  • **kwargs – Additional settings (e.g., backend credentials, simulation parameters).

Returns:

The newly assigned backend instance.

Raises:

  • ImportError – If Qiskit or packaging dependencies are missing for quantum mode.

  • ValueError – If mode or provider is unsupported.

Examples

>>> set_backend('quantum', provider='AerSimulator')
>>> set_backend('classical', backend='numpy')
quactuary.backend.use_backend(mode, provider=None, **kwargs)

Context manager for temporary backend configuration.

Parameters:

  • mode (str) – Execution mode override (‘quantum’ or ‘classical’).

  • provider (Optional[str]) – Quantum provider name.

  • **kwargs – Additional backend settings.

Yields:

BackendManager – Manager with temporary backend applied.

Examples

>>> with use_backend('quantum', provider='AerSimulator') as mgr:
...     result = mgr.run(circuit)

quactuary.entities module

Insurance entity models for policy terms, inforce buckets, and portfolios.

This module defines the core business objects for representing insurance policy terms (PolicyTerms), aggregation buckets (Inforce), and collections of buckets (Portfolio).

Examples

>>> from quactuary.entities import PolicyTerms, Inforce, Portfolio
>>> terms = PolicyTerms(per_occ_deductible=100.0, coinsurance=0.8)
>>> bucket = Inforce(n_policies=50, freq=freq_model, sev=sev_model, terms=terms)
>>> portfolio = Portfolio([bucket])
class quactuary.entities.Inforce(n_policies: int, freq: FrequencyModel, sev: SeverityModel, terms: PolicyTerms, name: str = 'Unnamed Bucket')

Bases: object

Bucket of policies sharing frequency and severity characteristics.

Parameters:

  • n_policies (int) – Number of policies in this bucket.

  • freq (FrequencyModel) – Claim count distribution.

  • sev (SeverityModel) – Claim severity distribution.

  • terms (PolicyTerms) – Policy terms and layer definitions.

  • name (str, optional) – Bucket label. Defaults to “Unnamed Bucket”.

classical_sample(n_sims

int) -> np.ndarray: Monte Carlo aggregate loss sample.

classical_sample(n_sims: int = 100000)

Generate Monte Carlo aggregate loss samples for the bucket.

Parameters:

n_sims (int, optional) – Number of simulation runs. Defaults to 100000.

Returns:

Aggregate loss per simulation.

Return type:

np.ndarray

Examples

>>> samples = bucket.classical_sample(n_sims=50000)
freq: FrequencyModel
n_policies: int
name: str
sev: SeverityModel
terms: PolicyTerms
class quactuary.entities.PolicyTerms(per_occ_deductible: float = 0.0, coinsurance: float = 1.0, per_occ_limit: float | None = None, agg_limit: float | None = None, attachment: float = 0.0, coverage: str = 'OCC')

Bases: object

Terms defining insurance policy layer details.

per_occ_deductible

Deductible per occurrence.

Type:

float

coinsurance

Insurer share proportion (1.0 = 100%).

Type:

float

per_occ_limit

Per-occurrence limit.

Type:

Optional[float]

agg_limit

Aggregate limit.

Type:

Optional[float]

attachment

Attachment point for excess-of-loss.

Type:

float

coverage

Coverage type (e.g., “OCC”, “CLAIMS-MADE”).

Type:

str

agg_limit: float | None
attachment: float
coinsurance: float
coverage: str
per_occ_deductible: float
per_occ_limit: float | None
class quactuary.entities.Portfolio(iterable=(), /)

Bases: list

Portfolio of in-force buckets.

Extends list to include portfolio-level operations.

Examples

>>> p1 = Portfolio([bucket1])
>>> p2 = Portfolio([bucket2])
>>> combined = p1 + p2
total_policies() → int

Compute the total number of policies in the portfolio.

Returns:

Sum of n_policies across all buckets.

Return type:

int

Examples

>>> portfolio.total_policies()
1500

quactuary.pricing module

Pricing module for actuarial loss models.

This module provides classes to price excess loss and compute risk measures for insurance portfolios, using classical simulation methods (Monte Carlo, FFT) with optional quantum acceleration via Qiskit.

Notes

Classical methods include Monte Carlo and FFT via external libraries. Quantum acceleration uses Qiskit backends managed by BackendManager.

Examples

>>> from quactuary.pricing import ExcessLossModel, RiskMeasureModel
>>> model = ExcessLossModel(inforce, deductible=1000.0, limit=10000.0)
>>> result = model.compute_excess_loss()
class quactuary.pricing.ActuarialModel(inforce, deductible=None, limit=None, backend=None, **kw)

Bases: QuantumModelMixin

Base class for actuarial pricing models with optional quantum support.

Provides common interface for portfolio-based loss models using classical or quantum backends.

Parameters:

  • inforce (Inforce or Portfolio) – Policy inforce data.

  • deductible (Optional[float]) – Layer deductible.

  • limit (Optional[float]) – Layer limit.

  • backend (Optional[BackendManager]) – Execution backend override.

  • **kw – Additional model-specific settings.

portfolio

Wrapped inforce portfolio.

Type:

Portfolio

layer_deductible

Deductible for the layer.

Type:

Optional[float]

layer_limit

Limit for the layer.

Type:

Optional[float]

backend

Backend manager for execution.

Type:

BackendManager

__init__(inforce, deductible=None, limit=None, backend=None, **kw)

Initialize an ActuarialModel.

Parameters:

  • inforce (Inforce or Portfolio) – Policy inforce data.

  • deductible (Optional[float]) – Layer deductible.

  • limit (Optional[float]) – Layer limit.

  • backend (Optional[BackendManager]) – Execution backend.

  • **kw – Additional settings (ignored).

Raises:

TypeError – If inforce is not an Inforce or Portfolio.

class quactuary.pricing.ExcessLossModel(inforce, deductible=None, limit=None, **kw)

Bases: ActuarialModel

Pricing model for aggregate excess loss.

Computes the loss exceeding a deductible up to a layer limit for an insurance portfolio.

Parameters:

  • inforce (Inforce or Portfolio) – Portfolio data.

  • deductible (Optional[float]) – Layer deductible.

  • limit (Optional[float]) – Layer limit.

  • **kw – Additional settings.

Examples

>>> model = ExcessLossModel(inforce, deductible=1000, limit=10000)
>>> losses = model.compute_excess_loss()
compute_excess_loss(backend=None)

Compute aggregate excess loss for the portfolio.

Parameters:

backend (Optional[BackendManager]) – Execution backend override.

Returns:

Excess loss result (e.g., numeric array or DataFrame).

Return type:

Any

Raises:

NotImplementedError – Method not yet implemented.

class quactuary.pricing.RiskMeasureModel(inforce, deductible=None, limit=None, **kw)

Bases: ActuarialModel

Pricing model for risk measures (VaR, TVaR).

Computes quantile-based risk metrics for insurance portfolios, with optional quantum acceleration.

Parameters:

  • inforce (Inforce or Portfolio) – Portfolio data.

  • deductible (Optional[float]) – Layer deductible.

  • limit (Optional[float]) – Layer limit.

  • **kw – Additional settings.

Examples

>>> rm = RiskMeasureModel(inforce)
>>> var = rm.value_at_risk(alpha=0.99)
tail_value_at_risk(alpha=0.95, backend=None)

Compute the Tail Value at Risk (TVaR) at the given confidence level.

Parameters:

  • alpha (float, optional) – Confidence level (0 < alpha < 1). Defaults to 0.95.

  • backend (Optional[BackendManager]) – Execution backend override.

Returns:

Estimated TVaR value.

Return type:

float

Raises:

NotImplementedError – Method not yet implemented.

value_at_risk(alpha=0.95, backend=None)

Compute the Value at Risk (VaR) at the given confidence level.

Parameters:

  • alpha (float, optional) – Confidence level (0 < alpha < 1). Defaults to 0.95.

  • backend (Optional[BackendManager]) – Execution backend override.

Returns:

Estimated VaR value.

Return type:

float

Raises:

NotImplementedError – Method not yet implemented.

quactuary.quantum module

Quantum actuarial integration module.

Centralizes quantum computing support across actuarial models, providing consistent circuit construction, execution, and result handling.

Examples

>>> from quactuary.quantum import QuantumModelMixin, QuantumResult
>>> class MyModel(QuantumModelMixin):
...     pass
class quactuary.quantum.QuantumModelMixin

Bases: object

Mixin providing quantum circuit creation and execution capabilities.

Include this mixin in model classes to enable quantum algorithms via Qiskit.

class quactuary.quantum.QuantumResult

Bases: object

Container for results from quantum computations.

Models can convert these results into user-facing formats (e.g., numbers or DataFrames).

intervals

Confidence intervals for estimates.

Type:

dict[str, tuple[float, float]]

samples

Raw samples obtained from quantum execution.

Type:

Optional[np.ndarray]

metadata

Additional run details.

Type:

dict

quactuary.quantum.__init__(self)

Initialize the QuantumModelMixin.

This method can perform setup tasks required before building circuits.

quactuary.utils module

Module contents