net.finmath.montecarlo.model.AbstractModelInterface 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. All rights reserved. Contact: [email protected].
 *
 * Created on 28.03.2008
 */
package net.finmath.montecarlo.model;

import net.finmath.exception.CalculationException;
import net.finmath.montecarlo.process.AbstractProcessInterface;
import net.finmath.stochastic.RandomVariableInterface;
import net.finmath.time.TimeDiscretizationInterface;

/**
 * The interface for a model of a stochastic process X where
 * X = f(Y) 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.AbstractModelInterface#getInitialState}.
 * 
The value of μ is provided by the method {@link net.finmath.montecarlo.model.AbstractModelInterface#getDrift}.
 * 
The value λ_j is provided by the method {@link net.finmath.montecarlo.model.AbstractModelInterface#getFactorLoading}.
 * 
The function f is provided by the method {@link net.finmath.montecarlo.model.AbstractModelInterface#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
 */
public interface AbstractModelInterface {

	/**
	 * Returns the time discretization of the model parameters. It is not necessary that this time discretization agrees
	 * with the discretization of the implementation.
	 * 
	 * @return The time discretization
	 */
	TimeDiscretizationInterface getTimeDiscretization();

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

	/**
	 * Applied the state space transform f_i to the given state random variable
	 * such that Y_i → f_i(Y_i) =: X_i.
	 * 
	 * @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.
	 */
	RandomVariableInterface applyStateSpaceTransform(int componentIndex, RandomVariableInterface randomVariable);

	/**
	 * 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.
	 * 
	 * @return The initial value of the state variable of the process Y(t=0).
	 */
	RandomVariableInterface[] getInitialState();

	/**
	 * Return the numeraire at a given time index.
	 * Note: The random variable returned is a defensive copy and may be modified.
	 * 
	 * @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.
	 */
	RandomVariableInterface getNumeraire(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.
	 * 
	 * @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 of no predictor is available.
	 * @return The (average) drift from timeIndex to timeIndex+1
	 */
	RandomVariableInterface[] getDrift(int timeIndex, RandomVariableInterface[] realizationAtTimeIndex, RandomVariableInterface[] 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 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.
	 */
	RandomVariableInterface[] getFactorLoading(int timeIndex, int componentIndex, RandomVariableInterface[] realizationAtTimeIndex);

	/**
	 * Set the numerical scheme used to generate the stochastic process.
	 * 
	 * The model needs the numerical scheme to calculate, e.g., the numeraire.
	 * 
	 * @param process The process.
	 */
	void setProcess(AbstractProcessInterface process);

	/**
	 * Get the numerical scheme used to generate the stochastic process.
	 * 
	 * The model needs the numerical scheme to calculate, e.g., the numeraire.
	 * 
	 * @return the process
	 */
	AbstractProcessInterface getProcess();

}