net.finmath.montecarlo.model.ProcessModel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of finmath-lib Show documentation
finmath lib is a Mathematical Finance Library in Java. It provides algorithms and methodologies related to mathematical finance.
There is a newer version: 6.0.19
Show newest version
/*
 * (c) Copyright Christian P. Fries, Germany. Contact: [email protected].
 *
 * Created on 28.03.2008
 */
package net.finmath.montecarlo.model;

import java.time.LocalDateTime;
import java.util.Map;

import net.finmath.exception.CalculationException;
import net.finmath.montecarlo.process.MonteCarloProcess;
import net.finmath.stochastic.RandomVariable;

/**
 * The interface for a model of a stochastic process X where
 * X(t) = f(t,Y(t)) and 

 * \[
 * dY_{j} = \mu_{j} dt + \lambda_{1,j} dW_{1} + \ldots + \lambda_{m,j} dW_{m}
 * \]
 *
 * 
 * The value of Y(0) is provided by the method {@link net.finmath.montecarlo.model.ProcessModel#getInitialState}.
 * 
The value of μ is provided by the method {@link net.finmath.montecarlo.model.ProcessModel#getDrift}.
 * 
The value λ_j is provided by the method {@link net.finmath.montecarlo.model.ProcessModel#getFactorLoading}.
 * 
The function f is provided by the method {@link net.finmath.montecarlo.model.ProcessModel#applyStateSpaceTransform}.
 * 
 * Here, μ and λ_j may depend on X, which allows to implement stochastic drifts (like in a LIBOR market model)
 * of local volatility models.
 *
 * 

 * Examples:
 * 
 * 	
 * 		The Black Scholes model can be modeled by S = X = Y (i.e. f is the identity)
 * 		and μ₁ = r S and λ_1,1 = σ S.
 * 	
 * 	
 * 		Alternatively, the Black Scholes model can be modeled by S = X = exp(Y) (i.e. f is exp)
 * 		and μ₁ = r - 0.5 σ σ and λ_1,1 = σ.
 * 	
 * 
 *
 * @author Christian Fries
 * @version 2.0
 */
public interface ProcessModel {

	/**
	 * Returns the model's date corresponding to the time discretization's \( t = 0 \).
	 *
	 * Note: Currently not all models provide a reference date. This will change in future versions.
	 *
	 * @return The model's date corresponding to the time discretization's \( t = 0 \).
	 */
	LocalDateTime getReferenceDate();

	/**
	 * Returns the number of components
	 *
	 * @return The number of components
	 */
	int getNumberOfComponents();

	/**
	 * Applies the state space transform f_i to the given state random variable
	 * such that Y_i → f_i(Y_i) =: X_i.
	 *
	 * @param process The discretization process generating this model. The process provides call backs for TimeDiscretization and allows calls to getProcessValue for timeIndices less or equal the given one.
	 * @param timeIndex The time index (related to the model times discretization).
	 * @param componentIndex The component index i.
	 * @param randomVariable The state random variable Y_i.
	 * @return New random variable holding the result of the state space transformation.
	 */
	RandomVariable applyStateSpaceTransform(MonteCarloProcess process, int timeIndex, int componentIndex, RandomVariable randomVariable);

	/**
	 * Applies the inverse state space transform f^-1_i to the given random variable
	 * such that X_i → f^-1_i(X_i) =: Y_i.
	 *
	 * @param process The discretization process generating this model. The process provides call backs for TimeDiscretization and allows calls to getProcessValue for timeIndices less or equal the given one.
	 * @param timeIndex The time index (related to the model times discretization).
	 * @param componentIndex The component index i.
	 * @param randomVariable The state random variable X_i.
	 * @return New random variable holding the result of the state space transformation.
	 */
	default RandomVariable applyStateSpaceTransformInverse(MonteCarloProcess process, int timeIndex, final int componentIndex, final RandomVariable randomVariable) {
		throw new UnsupportedOperationException("Inverse of statespace transform not set");
	}

	/**
	 * Returns the initial value of the state variable of the process Y, not to be
	 * confused with the initial value of the model X (which is the state space transform
	 * applied to this state value.
	 *
	 * @param process The discretization process generating this model. The process provides call backs for TimeDiscretization and allows calls to getProcessValue for timeIndices less or equal the given one.
	 * @return The initial value of the state variable of the process Y(t=0).
	 */
	RandomVariable[] getInitialState(MonteCarloProcess process);

	/**
	 * Return the numeraire at a given time index.
	 * Note: The random variable returned is a defensive copy and may be modified.
	 *
	 * @param process The discretization process generating this model. The process provides call backs for TimeDiscretization and allows calls to getProcessValue for timeIndices less or equal the given one.
	 * @param time The time t for which the numeraire N(t) should be returned.
	 * @return The numeraire at the specified time as RandomVariable
	 * @throws net.finmath.exception.CalculationException Thrown if the valuation fails, specific cause may be available via the cause() method.
	 */
	RandomVariable getNumeraire(MonteCarloProcess process, double time) throws CalculationException;

	/**
	 * This method has to be implemented to return the drift, i.e.
	 * the coefficient vector 

	 * μ =  (μ₁, ..., μ_n) such that X = f(Y) and 

	 * dY_j = μ_j dt + λ_1,j dW₁ + ... + λ_m,j dW_m 

	 * in an m-factor model. Here j denotes index of the component of the resulting
	 * process.
	 *
	 * Since the model is provided only on a time discretization, the method may also (should try to) return the drift
	 * as \( \frac{1}{t_{i+1}-t_{i}} \int_{t_{i}}^{t_{i+1}} \mu(\tau) \mathrm{d}\tau \).
	 *
	 * @param process The discretization process generating this model. The process provides call backs for TimeDiscretization and allows calls to getProcessValue for timeIndices less or equal the given one.
	 * @param timeIndex The time index (related to the model times discretization).
	 * @param realizationAtTimeIndex The given realization at timeIndex
	 * @param realizationPredictor The given realization at timeIndex+1 or null if no predictor is available.
	 * @return The drift or average drift from timeIndex to timeIndex+1, i.e. \( \frac{1}{t_{i+1}-t_{i}} \int_{t_{i}}^{t_{i+1}} \mu(\tau) \mathrm{d}\tau \) (or a suitable approximation).
	 */
	RandomVariable[] getDrift(MonteCarloProcess process, int timeIndex, RandomVariable[] realizationAtTimeIndex, RandomVariable[] realizationPredictor);

	/**
	 * Returns the number of factors m, i.e., the number of independent Brownian drivers.
	 *
	 * @return The number of factors.
	 */
	int getNumberOfFactors();

	/**
	 * This method has to be implemented to return the factor loadings, i.e.
	 * the coefficient vector 

	 * λ_j =  (λ_1,j, ..., λ_m,j) such that X = f(Y) and 

	 * dY_j = μ_j dt + λ_1,j dW₁ + ... + λ_m,j dW_m 

	 * in an m-factor model. Here j denotes index of the component of the resulting
	 * process.
	 *
	 * @param process The discretization process generating this model. The process provides call backs for TimeDiscretization and allows calls to getProcessValue for timeIndices less or equal the given one.
	 * @param timeIndex The time index (related to the model times discretization).
	 * @param componentIndex The index j of the driven component.
	 * @param realizationAtTimeIndex The realization of X at the time corresponding to timeIndex (in order to implement local and stochastic volatlity models).
	 * @return The factor loading for given factor and component.
	 */
	RandomVariable[] getFactorLoading(MonteCarloProcess process, int timeIndex, int componentIndex, RandomVariable[] realizationAtTimeIndex);

	/**
	 * Return a random variable initialized with a constant using the models random variable factory.
	 *
	 * @param value The constant value.
	 * @return A new random variable initialized with a constant value.
	 */
	RandomVariable getRandomVariableForConstant(double value);

	/**
	 * Returns a clone of this model where the specified properties have been modified.
	 *
	 * Note that there is no guarantee that a model reacts on a specification of a properties in the
	 * parameter map dataModified. If data is provided which is ignored by the model
	 * no exception may be thrown.
	 *
	 * @param dataModified Key-value-map of parameters to modify.
	 * @return A clone of this model (or this model if no parameter was modified).
	 * @throws CalculationException Thrown when the model could not be created.
	 */
	ProcessModel getCloneWithModifiedData(Map dataModified) throws CalculationException;
}