finmath lib

finmath lib is a mathematical finance library providing JVM implementations of various financial methodologies. Key capabilities include:

• Analytic Formulas: Distributions (Normal, Gamma, etc.) and Models (Black Scholes, Bachelier, SABR, ZABR, CEV).
• Numerical Algorithms: Random number generation and optimization (Levenberg–Marquardt).
• Valuation Methods:
  • Fourier transforms / characteristic functions: Black-Scholes, Heston, Bates, Merton, and Variance Gamma models.
  • Finite difference methods: Theta-scheme for Black-Scholes and CEV models.
  • Monte-Carlo simulation: Multi-dimensional SDEs (Hull-White, LIBOR Market Model, Heston, etc.) and American Monte-Carlo.
• Calibration: Interest rate curves (OIS, basis-swaps), bond curves, and volatility surfaces (SABR smile, Swaption cubes).
• Advanced Features:
  • Stochastic Automatic Differentiation (AAD): Located in net.finmath.montecarlo.automaticdifferentiation.
  • GPGPU Acceleration: Monte-Carlo simulations via CUDA (requires finmath-lib-cuda-extensions).
  • Climate Modeling: DICE model via net.finmath.climate.

The Model interface is a marker interface used to represent different market environments and numerical frameworks. Depending on the required valuation method, you will interact with specific sub-interfaces:

Monte Carlo Models

• MonteCarloSimulationModel: Provides discretization parameters, number of paths, random variable generators, and weights via getTimeDiscretization(), getNumberOfPaths(), getRandomVariableForConstant(), and getMonteCarloWeights().
• AssetModelMonteCarloSimulationModel: An extension for equity models providing getNumeraire() and getAsset().
• TermStructureMonteCarloSimulationModel: An extension for interest rate models providing getNumeraire() and getLIBOR(double, double, double).

Fourier Transform Models

• CharacteristicFunctionModel (in package net.finmath.fouriermethod): Provides the apply(double) method which returns a CharacteristicFunction.

Names should be as descriptive as possible, using camel notation from general to specific properties, appending implementation details at the end.

Naming Patterns

• Interfaces: Use names describing the core concept (e.g., BrownianMotion, RandomVariable).
• Implementations: Use the interface name followed by the implementation aspect (e.g., RandomVariableFromDoubleArray).
• Collections: Use the plural of the item (e.g., periods) or the collection type as a suffix for clarity (e.g., sensitivityMap).
• Arguments: When constructor or setter arguments are used to set fields, use the same name for both the field and the argument.

Avoid Reassignment

Do not reassign a reference in a way that alters its semantic meaning. If a calculation requires a different meaning, use a new variable name.

// Correct: Using distinct names for different meanings
var forwardBond = (1 + forwardRate * periodLength);
var discountFactor = 1.0 / forwardBond;

// Wrong: Reassigning a variable to a different meaning
var discountFactor = (1 + forwardRate * periodLength);
discountFactor = 1.0 / discountFactor;

Automatic tracking of measurability is a feature in finmath-lib that allows random variables to inspect when they become measurable with respect to a filtration $\mathcal{F}_t$.

Concept

For any random variable $X$, there exists a filtration time $T(X)$ such that for all $t \ge T(X)$, $X$ is guaranteed to be $\mathcal{F}_t$-measurable. This is implemented using a mechanism similar to forward-mode automatic differentiation, where every operator on random variables is augmented with an operation that tracks the filtration time.

Rules for Filtration Time $T(X)$:

• Constants (Deterministic): $T(C) = -\infty$
• Brownian Increments: For $W(t+\Delta t) - W(t)$, the filtration time is $t+\Delta t$.
• Operators: For an operator $f(X_1, ..., X_n) = Z$, the filtration time is $T(Z) = \max(T(X_1), ..., T(X_n))$.

Optimization Benefit

This tracking allows for optimizations in stochastic automatic differentiation. Specifically, it can detect when the computationally expensive conditional expectation operator can be bypassed using the identity: $$E(X | \mathcal{F}_t) = X \text{ if } t \ge T(X)$$ If the current time $t$ is already greater than or equal to the tracked filtration time of $X$, the conditional expectation is simply $X$ itself.

The library uses a decoupled architecture to separate the mathematical description of a market (the Model) from the financial instrument being valued (the Product).

This separation allows for a combinatorial approach to valuation:

1. Models define asset classes (e.g., single asset, interest rate term structures), numerical methods (e.g., Monte Carlo, Fourier Transform, Finite Difference), and specific modeling assumptions.
2. Products define the payoff structure and use double-dispatch via the getValue(Model<?> model) method. This means a product implementation will inspect the type of the provided model (e.g., casting to a MonteCarloSimulationModel) to determine the appropriate valuation logic.

Common pairings include:

• Analytic: AnalyticModel + AnalyticProduct
• Monte Carlo (Equity): AssetModelMonteCarloSimulationModel + AssetMonteCarloProduct
• Monte Carlo (Interest Rates): TermStructureMonteCarloSimulationModel + TermStructureMonteCarloProduct
• Fourier Transform: CharacteristicFunctionModel + FourierTransformProduct

The library implements stochastic automatic differentiation (AAD) by extending the standard RandomVariable interface with RandomVariableDifferentiable. This allows for fast, memory-efficient, and thread-safe automatic differentiation of conditional expectations (e.g., in American Monte-Carlo contexts).

Key Abstractions

• RandomVariableDifferentiable: An interface that extends RandomVariable. It supports standard arithmetic operations (like add, mult, exp) and provides methods to retrieve gradients.
• RandomVariableDifferentiableAADFactory: A factory used to create RandomVariableDifferentiable instances using the backward (adjoint) method.
• RandomVariableDifferentiableAAD: The implementation class containing the backward automatic differentiation logic.

Retrieving Gradients

To obtain the first-order differentiation of a random variable with respect to all its input leaf nodes, use getGradient(). To find the derivative with respect to a specific input, use the input's unique ID.

/* Get the gradient of X with respect to all its leaf nodes */
Map<Long, RandomVariable> gradientOfX = X.getGradient();

/* Get the derivative of X with respect to Y */
RandomVariable derivative = gradientOfX.get(Y.getID());

/* Get the gradient of X with respect to all its leaf nodes: */
Map<Long, RandomVariable> gradientOfX = X.getGradient();

/* Get the derivative of X with respect to Y: */
RandomVariable derivative = gradientOfX.get(Y.getID());