net.finmath.stochastic
Interface RandomVariableInterface
-
- All Superinterfaces:
- java.io.Serializable
- All Known Subinterfaces:
- RandomVariableAccumulatorInterface
- All Known Implementing Classes:
- RandomVariable, RandomVariableLazyEvaluation, RandomVariableMutableClone
public interface RandomVariableInterface extends java.io.SerializableThis interface describes the methods implemented by an immutable random variable, i.e. methods that leave a random variable unchanged (immutable). This is used to ensure that arguments or return values are not changed. For C++ guys: In C++ you could achieve this by making a return value const.
IMPORTANT: As of version 1.3 / revision 487 the design of RandomVariable, RandomVariableInterface has changed: All methods of RandomVariable leave the object immutable and the interface ImmutableRandomVariableInterface has been renamed to RandomVariableInterface. Your code remains compatible if you perform the following changes:- Change calls to RandomVariableInterface objects value like
value.mult(argument);tovalue = value.mult(argument); - Remove calls to getMutableCopy() since they are no longer needed.
- Remove wrapping in RandomVariableMutableClone since they are no longer needed.
RandomVariableAccumulatorInterface.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method and Description RandomVariableInterfaceabs()Applies x → Math.abs(x), i.e.RandomVariableInterfaceaccrue(RandomVariableInterface rate, double periodLength)Applies x → x * (1.0 + rate * periodLength) to this random variable.RandomVariableInterfaceadd(double value)Applies x → x + value to this random variable.RandomVariableInterfaceadd(RandomVariableInterface randomVariable)Applies x → x+randomVariable to this random variable.RandomVariableInterfaceaddProduct(RandomVariableInterface factor1, double factor2)Applies x → x + factor1 * factor2RandomVariableInterfaceaddProduct(RandomVariableInterface factor1, RandomVariableInterface factor2)Applies x → x + factor1 * factor2RandomVariableInterfaceaddRatio(RandomVariableInterface numerator, RandomVariableInterface denominator)Applies x → x + numerator / denominatorRandomVariableInterfaceapply(java.util.function.DoubleBinaryOperator operator, RandomVariableInterface argument)Applies x → operator(x,y) to this random variable, where x is this random variable and y is a given random variable.RandomVariableInterfaceapply(DoubleTernaryOperator operator, RandomVariableInterface argument1, RandomVariableInterface argument2)Applies x → operator(x,y,z) to this random variable, where x is this random variable and y and z are given random variable.RandomVariableInterfaceapply(java.util.function.DoubleUnaryOperator operator)Applies x → operator(x) to this random variable.RandomVariableInterfacebarrier(RandomVariableInterface trigger, RandomVariableInterface valueIfTriggerNonNegative, double valueIfTriggerNegative)Applies x → (trigger ≥ 0 ? valueIfTriggerNonNegative : valueIfTriggerNegative)RandomVariableInterfacebarrier(RandomVariableInterface trigger, RandomVariableInterface valueIfTriggerNonNegative, RandomVariableInterface valueIfTriggerNegative)Applies x → (trigger ≥ 0 ? valueIfTriggerNonNegative : valueIfTriggerNegative)RandomVariableInterfacecache()Return a cacheable version of this object (often a self-reference).default RandomVariableInterfacecap(double cap)Applies x → min(x,cap) to this random variable.RandomVariableInterfacecap(RandomVariableInterface cap)Applies x → min(x,cap) to this random variable.RandomVariableInterfacecos()Applies x → cos(x) to this random variable.RandomVariableInterfacediscount(RandomVariableInterface rate, double periodLength)Applies x → x / (1.0 + rate * periodLength) to this random variable.RandomVariableInterfacediv(double value)Applies x → x / value to this random variable.RandomVariableInterfacediv(RandomVariableInterface randomVariable)Applies x → x/randomVariable to this random variable.booleanequals(RandomVariableInterface randomVariable)Compare this random variable with a given oneRandomVariableInterfaceexp()Applies x → exp(x) to this random variable.RandomVariableInterfacefloor(double floor)Applies x → max(x,floor) to this random variable.RandomVariableInterfacefloor(RandomVariableInterface floor)Applies x → max(x,floor) to this random variable.doubleget(int pathOrState)Evaluate at a given path or state.doublegetAverage()Returns the expectation of this random variable.doublegetAverage(RandomVariableInterface probabilities)Returns the expectation of this random variable for a given probability measure (weight).doublegetFiltrationTime()Returns the filtration time.double[]getHistogram(double[] intervalPoints)Generates a Histogram based on the realizations stored in this random variable.double[][]getHistogram(int numberOfPoints, double standardDeviations)Generates a histogram based on the realizations stored in this random variable using interval points calculated from the arguments, see alsogetHistogram(double[]).doublegetMax()Returns the maximum value attained by this random variable.doublegetMin()Returns the minimum value attained by this random variable.RandomVariableInterfacegetMutableCopy()Deprecated.java.util.function.IntToDoubleFunctiongetOperator()Returns the operator path -> this.get(path) corresponding to this random variable.doublegetQuantile(double quantile)Returns the quantile value for this given random variable, i.e., the value x such that P(this < x) = quantile, where P denotes the probability measure.doublegetQuantile(double quantile, RandomVariableInterface probabilities)Returns the quantile value for this given random variable, i.e., the value x such that P(this < x) = quantile, where P denotes the probability measure.doublegetQuantileExpectation(double quantileStart, double quantileEnd)Returns the expectation over a quantile for this given random variable.double[]getRealizations()Returns a vector representing the realization of this random variable.double[]getRealizations(int numberOfPaths)Returns the realizations as double array.java.util.stream.DoubleStreamgetRealizationsStream()Returns a stream of doubles corresponding to the realizations of this random variable.doublegetStandardDeviation()Returns the standard deviation of this random variable, i.e., sqrt(V) where V = ((X-m)^2).getAverage() and X = this and m = X.getAverage().doublegetStandardDeviation(RandomVariableInterface probabilities)Returns the standard deviation of this random variable, i.e., sqrt(V) where V = ((X-m)^2).getAverage(probabilities) and X = this and m = X.getAverage(probabilities).doublegetStandardError()Returns the standard error (discretization error) of this random variable.doublegetStandardError(RandomVariableInterface probabilities)Returns the standard error (discretization error) of this random variable.doublegetVariance()Returns the variance of this random variable, i.e., V where V = ((X-m)^2).getAverage() and X = this and m = X.getAverage().doublegetVariance(RandomVariableInterface probabilities)Returns the variance of this random variable, i.e., V where V = ((X-m)^2).getAverage(probabilities) and X = this and m = X.getAverage(probabilities).RandomVariableInterfaceinvert()Applies x → 1/x to this random variable.booleanisDeterministic()Check if this random variable is deterministic in the sense that it is represented by a single double value.RandomVariableInterfaceisNaN()Applies x → (Double.isNaN(x) ? 1.0 : 0.0)RandomVariableInterfacelog()Applies x → log(x) to this random variable.RandomVariableInterfacemult(double value)Applies x → x * value to this random variable.RandomVariableInterfacemult(RandomVariableInterface randomVariable)Applies x → x*randomVariable to this random variable.RandomVariableInterfacepow(double exponent)Applies x → pow(x,exponent) to this random variable.RandomVariableInterfacesin()Applies x → sin(x) to this random variable.intsize()Returns the number of paths or states.RandomVariableInterfacesqrt()Applies x → sqrt(x) to this random variable.RandomVariableInterfacesquared()Applies x → x * x to this random variable.RandomVariableInterfacesub(double value)Applies x → x - value to this random variable.RandomVariableInterfacesub(RandomVariableInterface randomVariable)Applies x → x-randomVariable to this random variable.RandomVariableInterfacesubRatio(RandomVariableInterface numerator, RandomVariableInterface denominator)Applies x → x - numerator / denominator
-
-
-
Method Detail
-
equals
boolean equals(RandomVariableInterface randomVariable)
Compare this random variable with a given one- Parameters:
randomVariable- Random variable to compare with.- Returns:
- True if this random variable and the given one are equal, otherwise false
-
getFiltrationTime
double getFiltrationTime()
Returns the filtration time.- Returns:
- The filtration time.
-
get
double get(int pathOrState)
Evaluate at a given path or state.- Parameters:
pathOrState- Index of the path or state.- Returns:
- Value of this random variable at the given path or state.
-
size
int size()
Returns the number of paths or states.- Returns:
- Number of paths or states.
-
isDeterministic
boolean isDeterministic()
Check if this random variable is deterministic in the sense that it is represented by a single double value. Note that the methods returns false, if the random variable is represented by a vector where each element has the same value.- Returns:
- True if this random variable is deterministic.
-
getRealizations
double[] getRealizations()
Returns a vector representing the realization of this random variable. This method is merely useful for analysis. Its interpretation depends on the context (Monte-Carlo or lattice). The method does not expose an internal data model.- Returns:
- Vector of realizations of this random variable.
-
getRealizations
double[] getRealizations(int numberOfPaths)
Returns the realizations as double array. If the random variable is deterministic, then it is expanded to the given number of paths.- Parameters:
numberOfPaths- The number of paths.- Returns:
- The realization as double array.
-
getOperator
java.util.function.IntToDoubleFunction getOperator()
Returns the operator path -> this.get(path) corresponding to this random variable.- Returns:
- The operator path -> this.get(path) corresponding to this random variable.
-
getRealizationsStream
java.util.stream.DoubleStream getRealizationsStream()
Returns a stream of doubles corresponding to the realizations of this random variable.- Returns:
- A stream of doubles corresponding to the realizations of this random variable.
-
getMin
double getMin()
Returns the minimum value attained by this random variable.- Returns:
- The minimum value.
-
getMax
double getMax()
Returns the maximum value attained by this random variable.- Returns:
- The maximum value.
-
getAverage
double getAverage()
Returns the expectation of this random variable.- Returns:
- The average assuming equi-distribution.
-
getAverage
double getAverage(RandomVariableInterface probabilities)
Returns the expectation of this random variable for a given probability measure (weight). The result of this method is (mathematically) equivalent to
this.mult(probabilities).getAverage() / probabilities.getAverage()
while the internal implementation may differ, e.g. being more efficient by performing multiplication and summation in the same loop.- Parameters:
probabilities- The probability weights.- Returns:
- The average assuming the given probability weights.
-
getVariance
double getVariance()
Returns the variance of this random variable, i.e., V where V = ((X-m)^2).getAverage() and X = this and m = X.getAverage().- Returns:
- The average assuming equi-distribution.
-
getVariance
double getVariance(RandomVariableInterface probabilities)
Returns the variance of this random variable, i.e., V where V = ((X-m)^2).getAverage(probabilities) and X = this and m = X.getAverage(probabilities).- Parameters:
probabilities- The probability weights.- Returns:
- The average assuming the given probability weights.
-
getStandardDeviation
double getStandardDeviation()
Returns the standard deviation of this random variable, i.e., sqrt(V) where V = ((X-m)^2).getAverage() and X = this and m = X.getAverage().- Returns:
- The standard deviation assuming equi-distribution.
-
getStandardDeviation
double getStandardDeviation(RandomVariableInterface probabilities)
Returns the standard deviation of this random variable, i.e., sqrt(V) where V = ((X-m)^2).getAverage(probabilities) and X = this and m = X.getAverage(probabilities).- Parameters:
probabilities- The probability weights.- Returns:
- The standard error assuming the given probability weights.
-
getStandardError
double getStandardError()
Returns the standard error (discretization error) of this random variable. For a Monte-Carlo simulation this is 1/Math.sqrt(n) *getStandardDeviation().- Returns:
- The standard error assuming equi-distribution.
-
getStandardError
double getStandardError(RandomVariableInterface probabilities)
Returns the standard error (discretization error) of this random variable. For a Monte-Carlo simulation this is 1/Math.sqrt(n) *getStandardDeviation(RandomVariableInterface).- Parameters:
probabilities- The probability weights.- Returns:
- The standard error assuming the given probability weights.
-
getQuantile
double getQuantile(double quantile)
Returns the quantile value for this given random variable, i.e., the value x such that P(this < x) = quantile, where P denotes the probability measure. The method will consider picewise constant values (with constant extrapolation) in the random variable. That is getQuantile(0) and getQuantile(1) will return the largest and smallest value.- Parameters:
quantile- The quantile level.- Returns:
- The quantile value assuming equi-distribution.
-
getQuantile
double getQuantile(double quantile, RandomVariableInterface probabilities)Returns the quantile value for this given random variable, i.e., the value x such that P(this < x) = quantile, where P denotes the probability measure.- Parameters:
quantile- The quantile level.probabilities- The probability weights.- Returns:
- The quantile value assuming the given probability weights.
-
getQuantileExpectation
double getQuantileExpectation(double quantileStart, double quantileEnd)Returns the expectation over a quantile for this given random variable. The method will consider picewise constant values (with constant extrapolation) in the random variable. For a ≤ b the method returns (Σa ≤ i ≤ b x[i]) / (b-a+1), where- a = min(max((n+1) * quantileStart - 1, 0, 1);
- b = min(max((n+1) * quantileEnd - 1, 0, 1);
- n = this.size();
- Parameters:
quantileStart- Lower bound of the integral.quantileEnd- Upper bound of the integral.- Returns:
- The (conditional) expectation of the values between two quantile levels assuming equi-distribution.
-
getHistogram
double[] getHistogram(double[] intervalPoints)
Generates a Histogram based on the realizations stored in this random variable. The returnedresultarray's length isintervalPoints.length+1.- The value result[0] equals the relative frequency of values observed in the interval ( -infinity, intervalPoints[0] ].
- The value result[i] equals the relative frequency of values observed in the interval ( intervalPoints[i-1], intervalPoints[i] ].
- The value result[n] equals the relative frequency of values observed in the interval ( intervalPoints[n-1], infinity ).
possibleValues, thenresult = getHistogram(possibleValues)returns an array whereresult[i]is the relative frequency of occurrence ofpossibleValues[i]. The sum of result[i] over all i is equal to 1, except for uninitialized random variables where all values are 0.- Parameters:
intervalPoints- Array of ascending values defining the interval boundaries.- Returns:
- A histogram with respect to a provided interval.
-
getHistogram
double[][] getHistogram(int numberOfPoints, double standardDeviations)Generates a histogram based on the realizations stored in this random variable using interval points calculated from the arguments, see alsogetHistogram(double[]). The interval points are set with equal distance over an the interval of the specified standard deviation. The interval points used are wherex[i] = mean + alpha[i] * standardDeviations * sigma- i = 0,..., numberOfPoints-1,
- alpha[i] = (i - (numberOfPoints-1)/2.0) / ((numberOfPoints-1)/2.0),
- mean =
getAverage(), - sigma =
getStandardDeviation().
resultis an array of two vectors, where result[0] are the intervals center points ('anchor points') and result[1] contains the relative frequency for the interval. The 'anchor point' for the interval (-infinity, x[0]) is x[0] - 1/2 (x[1]-x[0]) and the 'anchor point' for the interval (x[n], infinity) is x[n] + 1/2 (x[n]-x[n-1]). Here n = numberOfPoints is the number of interval points.- Parameters:
numberOfPoints- The number of interval points.standardDeviations- The number of standard deviations defining the discretization radius.- Returns:
- A histogram, given as double[2][], where result[0] are the center point of the intervals and result[1] is the value of
getHistogram(double[])for the given the interval points. The length of result[0] and result[1] is numberOfPoints+1.
-
cache
RandomVariableInterface cache()
Return a cacheable version of this object (often a self-reference). This method should be called when you store the object for later use, i.e., assign it, or when the object is consumed in a function, but later used also in another function.- Returns:
- A cacheable version of this object (often a self-reference).
-
apply
RandomVariableInterface apply(java.util.function.DoubleUnaryOperator operator)
Applies x → operator(x) to this random variable. It returns a new random variable with the result.- Parameters:
operator- An unary operator/function, mapping double to double.- Returns:
- New random variable with the result of the function.
-
apply
RandomVariableInterface apply(java.util.function.DoubleBinaryOperator operator, RandomVariableInterface argument)
Applies x → operator(x,y) to this random variable, where x is this random variable and y is a given random variable. It returns a new random variable with the result.- Parameters:
operator- A binary operator/function, mapping (double,double) to double.argument- A random variable.- Returns:
- New random variable with the result of the function.
-
apply
RandomVariableInterface apply(DoubleTernaryOperator operator, RandomVariableInterface argument1, RandomVariableInterface argument2)
Applies x → operator(x,y,z) to this random variable, where x is this random variable and y and z are given random variable. It returns a new random variable with the result.- Parameters:
operator- A ternary operator/function, mapping (double,double,double) to double.argument1- A random variable representing y.argument2- A random variable representing z.- Returns:
- New random variable with the result of the function.
-
cap
default RandomVariableInterface cap(double cap)
Applies x → min(x,cap) to this random variable. It returns a new random variable with the result.- Parameters:
cap- The cap.- Returns:
- New random variable with the result of the function.
-
floor
RandomVariableInterface floor(double floor)
Applies x → max(x,floor) to this random variable. It returns a new random variable with the result.- Parameters:
floor- The floor.- Returns:
- New random variable with the result of the function.
-
add
RandomVariableInterface add(double value)
Applies x → x + value to this random variable. It returns a new random variable with the result.- Parameters:
value- The value to add.- Returns:
- New random variable with the result of the function.
-
sub
RandomVariableInterface sub(double value)
Applies x → x - value to this random variable.- Parameters:
value- The value to subtract.- Returns:
- New random variable with the result of the function.
-
mult
RandomVariableInterface mult(double value)
Applies x → x * value to this random variable.- Parameters:
value- The value to multiply.- Returns:
- New random variable with the result of the function.
-
div
RandomVariableInterface div(double value)
Applies x → x / value to this random variable.- Parameters:
value- The value to divide.- Returns:
- New random variable with the result of the function.
-
pow
RandomVariableInterface pow(double exponent)
Applies x → pow(x,exponent) to this random variable.- Parameters:
exponent- The exponent.- Returns:
- New random variable with the result of the function.
-
squared
RandomVariableInterface squared()
Applies x → x * x to this random variable.- Returns:
- New random variable with the result of the function.
-
sqrt
RandomVariableInterface sqrt()
Applies x → sqrt(x) to this random variable.- Returns:
- New random variable with the result of the function.
-
exp
RandomVariableInterface exp()
Applies x → exp(x) to this random variable.- Returns:
- New random variable with the result of the function.
-
log
RandomVariableInterface log()
Applies x → log(x) to this random variable.- Returns:
- New random variable with the result of the function.
-
sin
RandomVariableInterface sin()
Applies x → sin(x) to this random variable.- Returns:
- New random variable with the result of the function.
-
cos
RandomVariableInterface cos()
Applies x → cos(x) to this random variable.- Returns:
- New random variable with the result of the function.
-
add
RandomVariableInterface add(RandomVariableInterface randomVariable)
Applies x → x+randomVariable to this random variable.- Parameters:
randomVariable- A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
sub
RandomVariableInterface sub(RandomVariableInterface randomVariable)
Applies x → x-randomVariable to this random variable.- Parameters:
randomVariable- A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
mult
RandomVariableInterface mult(RandomVariableInterface randomVariable)
Applies x → x*randomVariable to this random variable.- Parameters:
randomVariable- A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
div
RandomVariableInterface div(RandomVariableInterface randomVariable)
Applies x → x/randomVariable to this random variable.- Parameters:
randomVariable- A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
cap
RandomVariableInterface cap(RandomVariableInterface cap)
Applies x → min(x,cap) to this random variable.- Parameters:
cap- The cap. A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
floor
RandomVariableInterface floor(RandomVariableInterface floor)
Applies x → max(x,floor) to this random variable.- Parameters:
floor- The floor. A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
accrue
RandomVariableInterface accrue(RandomVariableInterface rate, double periodLength)
Applies x → x * (1.0 + rate * periodLength) to this random variable.- Parameters:
rate- The accruing rate. A random variable (compatible with this random variable).periodLength- The period length- Returns:
- New random variable with the result of the function.
-
discount
RandomVariableInterface discount(RandomVariableInterface rate, double periodLength)
Applies x → x / (1.0 + rate * periodLength) to this random variable.- Parameters:
rate- The discounting rate. A random variable (compatible with this random variable).periodLength- The period length- Returns:
- New random variable with the result of the function.
-
barrier
RandomVariableInterface barrier(RandomVariableInterface trigger, RandomVariableInterface valueIfTriggerNonNegative, RandomVariableInterface valueIfTriggerNegative)
Applies x → (trigger ≥ 0 ? valueIfTriggerNonNegative : valueIfTriggerNegative)- Parameters:
trigger- The trigger. A random variable (compatible with this random variable).valueIfTriggerNonNegative- The value used if the trigger is greater or equal 0valueIfTriggerNegative- The value used if the trigger is less than 0- Returns:
- New random variable with the result of the function.
-
barrier
RandomVariableInterface barrier(RandomVariableInterface trigger, RandomVariableInterface valueIfTriggerNonNegative, double valueIfTriggerNegative)
Applies x → (trigger ≥ 0 ? valueIfTriggerNonNegative : valueIfTriggerNegative)- Parameters:
trigger- The trigger. A random variable (compatible with this random variable).valueIfTriggerNonNegative- The value used if the trigger is greater or equal 0valueIfTriggerNegative- The value used if the trigger is less than 0- Returns:
- New random variable with the result of the function.
-
invert
RandomVariableInterface invert()
Applies x → 1/x to this random variable.- Returns:
- New random variable with the result of the function.
-
abs
RandomVariableInterface abs()
Applies x → Math.abs(x), i.e. x → |x| to this random variable.- Returns:
- New random variable with the result of the function.
-
addProduct
RandomVariableInterface addProduct(RandomVariableInterface factor1, double factor2)
Applies x → x + factor1 * factor2- Parameters:
factor1- The factor 1. A random variable (compatible with this random variable).factor2- The factor 2.- Returns:
- New random variable with the result of the function.
-
addProduct
RandomVariableInterface addProduct(RandomVariableInterface factor1, RandomVariableInterface factor2)
Applies x → x + factor1 * factor2- Parameters:
factor1- The factor 1. A random variable (compatible with this random variable).factor2- The factor 2. A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
addRatio
RandomVariableInterface addRatio(RandomVariableInterface numerator, RandomVariableInterface denominator)
Applies x → x + numerator / denominator- Parameters:
numerator- The numerator of the ratio to add. A random variable (compatible with this random variable).denominator- The denominator of the ratio to add. A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
subRatio
RandomVariableInterface subRatio(RandomVariableInterface numerator, RandomVariableInterface denominator)
Applies x → x - numerator / denominator- Parameters:
numerator- The numerator of the ratio to sub. A random variable (compatible with this random variable).denominator- The denominator of the ratio to sub. A random variable (compatible with this random variable).- Returns:
- New random variable with the result of the function.
-
isNaN
RandomVariableInterface isNaN()
Applies x → (Double.isNaN(x) ? 1.0 : 0.0)- Returns:
- A random variable which is 1.0 for all states that are NaN.
-
getMutableCopy
@Deprecated RandomVariableInterface getMutableCopy()
Deprecated.
-
-
DataMelt 3.0 © DataMelt by jWork.ORG