Package com.opengamma.strata.market.surface

Interface Surface

  • All Superinterfaces:
    ParameterizedData
    All Known Subinterfaces:
    NodalSurface
    All Known Implementing Classes:
    ConstantSurface, DeformedSurface, InterpolatedNodalSurface
    public interface Surface
extends ParameterizedData
    A surface that maps a double x-value and y-value to a double z-value.

    Implementations of this interface provide the ability to find a z-value on the surface from the x-value and y-value.

    Each implementation will be backed by a number of parameters. The meaning of the parameters is implementation dependent. The sensitivity of the result to each of the parameters can also be obtained.

    See Also:
    InterpolatedNodalSurface

    • Method Detail

      • getMetadata

        SurfaceMetadata getMetadata()
        Gets the surface metadata.

        This method returns metadata about the surface and the surface parameters.

        The metadata includes an optional list of parameter metadata. If parameter metadata is present, the size of the list will match the number of parameters of this surface.

        Returns:
        the metadata

      • withMetadata

        Surface withMetadata​(SurfaceMetadata metadata)
        Returns a new surface with the specified metadata.

        This allows the metadata of the surface to be changed while retaining all other information. If parameter metadata is present, the size of the list must match the number of parameters of this surface.

        Parameters:
        metadata - the new metadata for the surface
        Returns:
        the new surface

      • getName

        default SurfaceName getName()
        Gets the surface name.
        Returns:
        the surface name

      • getParameterMetadata

        default ParameterMetadata getParameterMetadata​(int parameterIndex)
        Description copied from interface: ParameterizedData
        Gets the metadata of the parameter at the specified index.

        If there is no specific parameter metadata, an empty instance will be returned.

        Specified by:
        getParameterMetadata in interface ParameterizedData
        Parameters:
        parameterIndex - the zero-based index of the parameter to get
        Returns:
        the metadata of the parameter

      • findParameterIndex

        default OptionalInt findParameterIndex​(ParameterMetadata metadata)
        Description copied from interface: ParameterizedData
        Finds the parameter index of the specified metadata.

        If the parameter metadata is not matched, an empty optional will be returned.

        Specified by:
        findParameterIndex in interface ParameterizedData
        Parameters:
        metadata - the parameter metadata to find the index of
        Returns:
        the index of the parameter

      • withParameter

        Surface withParameter​(int parameterIndex,
                      double newValue)
        Description copied from interface: ParameterizedData
        Returns a copy of the data with the value at the specified index altered.

        This instance is immutable and unaffected by this method call.

        Specified by:
        withParameter in interface ParameterizedData
        Parameters:
        parameterIndex - the zero-based index of the parameter to get
        newValue - the new value for the specified parameter
        Returns:
        a parameterized data instance based on this with the specified parameter altered

      • withPerturbation

        default Surface withPerturbation​(ParameterPerturbation perturbation)
        Description copied from interface: ParameterizedData
        Returns a perturbed copy of the data.

        The perturbation instance will be invoked once for each parameter in this instance, returning the perturbed value for that parameter. The result of this method is a new instance that is based on those perturbed values.

        This instance is immutable and unaffected by this method call.

        Specified by:
        withPerturbation in interface ParameterizedData
        Parameters:
        perturbation - the perturbation to apply
        Returns:
        a parameterized data instance based on this with the specified perturbation applied

      • zValue

        double zValue​(double x,
              double y)
        Computes the z-value for the specified x-value and y-value.
        Parameters:
        x - the x-value to find the z-value for
        y - the y-value to find the z-value for
        Returns:
        the value at the x/y point

      • zValue

        default double zValue​(DoublesPair xyPair)
        Computes the z-value for the specified pair of x-value and y-value.
        Parameters:
        xyPair - the pair of x-value and y-value to find the z-value for
        Returns:
        the value at the x/y point

      • zValueParameterSensitivity

        UnitParameterSensitivity zValueParameterSensitivity​(double x,
                                                    double y)
        Computes the sensitivity of the z-value with respect to the surface parameters.

        This returns an array with one element for each x-y parameter of the surface. The array contains one a sensitivity value for each parameter used to create the surface.

        Parameters:
        x - the x-value at which the parameter sensitivity is computed
        y - the y-value at which the parameter sensitivity is computed
        Returns:
        the sensitivity at the x/y/ point
        Throws:
        RuntimeException - if the sensitivity cannot be calculated

      • zValueParameterSensitivity

        default UnitParameterSensitivity zValueParameterSensitivity​(DoublesPair xyPair)
        Computes the sensitivity of the z-value with respect to the surface parameters.

        This returns an array with one element for each x-y parameter of the surface. The array contains one sensitivity value for each parameter used to create the surface.

        Parameters:
        xyPair - the pair of x-value and y-value at which the parameter sensitivity is computed
        Returns:
        the sensitivity at the x/y/ point
        Throws:
        RuntimeException - if the sensitivity cannot be calculated

      • firstPartialDerivatives

        ValueDerivatives firstPartialDerivatives​(double x,
                                         double y)
        Computes the partial derivatives of the surface.

        The first derivatives are dz/dx and dz/dy. The derivatives are in the following order:

        • [0] derivative with respect to x
        • [1] derivative with respect to y
        Parameters:
        x - the x-value at which the partial derivative is taken
        y - the y-value at which the partial derivative is taken
        Returns:
        the z-value and it's partial first derivatives
        Throws:
        RuntimeException - if the derivative cannot be calculated

      • createParameterSensitivity

        default UnitParameterSensitivity createParameterSensitivity​(DoubleArray sensitivities)
        Creates a parameter sensitivity instance for this surface when the sensitivity values are known.

        In most cases, zValueParameterSensitivity(double, double) should be used and manipulated. However, it can be useful to create a UnitParameterSensitivity from pre-computed sensitivity values.

        Parameters:
        sensitivities - the sensitivity values, which must match the parameter count of the surface
        Returns:
        the sensitivity

      • createParameterSensitivity

        default CurrencyParameterSensitivity createParameterSensitivity​(Currency currency,
                                                                DoubleArray sensitivities)
        Creates a parameter sensitivity instance for this surface when the sensitivity values are known.

        In most cases, zValueParameterSensitivity(double, double) should be used and manipulated. However, it can be useful to create a CurrencyParameterSensitivity from pre-computed sensitivity values.

        Parameters:
        currency - the currency
        sensitivities - the sensitivity values, which must match the parameter count of the surface
        Returns:
        the sensitivity