> ## Documentation Index > Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt > Use this file to discover all available pages before exploring further. # Interpolation APIs The Atoti Market Data Library provides an interpolation API separated from the market data retrieval. The API is mostly contained in the `market-data-lib` module, with Spring configuration classes available in the `market-data-config` module. ## Supported interpolation types This API supports linear, linear with volatility-to-variance transformations for surfaces, cubic and spline interpolation, with the `InterpolationMode` class in the `com.activeviam.marketdata.lib.interpolation.services.intf` package providing valid options. | Value | Details | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `InterpolationMode.LINEAR` | Linear interpolation is required for missing data points. | | `InterpolationMode.VOL_TO_VARIANCE` | Linear interpolation with volatility-to-variance/variance-to-volatility pre- and post-interpolation transformations is required for missing data points. | | `InterpolationMode.CUBIC` | Cubic interpolation is required for missing data points. | | `InterpolationMode.SPLINE` | Spline interpolation is required for missing data points. | ## Handling market data The interpolation API expects the known data points to be expressed as an array of doubles with corresponding double arrays of coordinates (tenors/moneyness). The [retrieval interfaces](./retrieval) packaged with the market data API allow you to retrieve curves or surfaces as values and associated coordinates. ### Data mapping Market data values are always expressed as doubles, whereas coordinates will likely be expressed as other data types, based on the structure of the underlying market data store. To map these data types to the required interpolation double values, the following interfaces and implementations are provided: | Class | Details | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `ITenorMapper` | A mapper that converts a tenor into a different type. Its only method is `C map(T tenor)`. | | `IMoneynessMapper` | A mapper that converts a moneyness value into a different type. Its only method is `C map(M moneyness)`. | | `DefaultStringToDoubleTenorMapper` | A tenor mapper that converts `String` into `Double`. Supports a variety of standard tenor patterns (e.g. `5Y`, `O/N`). | | `DefaultStringToDoubleMoneynessMapper` | A tenor mapper that converts `String` into `Double`. Supports a variety of standard moneyness patterns (e.g. `ATM`, `10c`, `+2.5%`). | ## Interpolator Interfaces Interpolators are objects that return an interpolated point when provided with correctly configured known data points and the required coordinates. All interpolators must implement the `IInterpolator` interface: | Method | Return type | Details | | ------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `value(double... coordinates)` | `double` | Returns the interpolated value given the coordinates. A helper default `validateCoordinates(double... coordinates)` method is provided on the `IInterpolatorSettings` interface (see below) to check the validity of the requested coordinates against the supported axes. | Each interpolator is constructed with a factory that formats the input data correctly for that specific interpolator. These factories implement the `IInterpolatorFactory` interface: | Method | Return type | Details | | ------------------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from(double[] values, double[]... coordinates)` | `IInterpolator` | Sets up the interpolator with known data points. The implementation has to check that the number of coordinate arrays matches the result of `getAxis()`. | Both `IInterpolator` and `IInterpolatorFactory` interfaces extend the `IInterpolatorSettings` interface, which contains methods that describe the type of interpolation handled by that interpolator. | Method | Return type | Details | | ----------- | ------------------- | --------------------------------------------------------------- | | `getMode()` | `InterpolationMode` | The type of interpolation performed by the interpolator object. | | `getAxis()` | `int` | The number of axes of the known data points. | You can also find a number of convenient interfaces, which extend the `IInterpolationSettings` interface and provide common settings as default methods. | Interface | Details | | ------------------------------------------- | ------------------------------------------------------------------- | | `IUnivariate` | Returns `1` on `getAxis()`. | | `IBivariate` | Returns `2` on `getAxis()`. | | `ILinear` | Returns `InterpolationMode.LINEAR` on `getMode()`. | | `IVolToVariance` | Returns `InterpolationMode.VOL_TO_VARIANCE` on `getMode()`. | | `ICubic` | Returns `InterpolationMode.CUBIC` on `getMode()`. | | `ISpline` | Returns `InterpolationMode.SPLINE` on `getMode()`. | | `ILinearUnivariateInterpolatorFactory` | Extends `IInterpolatorFactory`, `ILinear`, and `IUnivariate`. | | `IBilinearInterpolatorFactory` | Extends `IInterpolatorFactory`, `ILinear`, and `IBivariate`. | | `IVolToVarianceBilinearInterpolatorFactory` | Extends `IInterpolatorFactory`, `IVolToVariance`, and `IBivariate`. | | `IBicubicInterpolatorFactory` | Extends `IInterpolatorFactory`, `ICubic`, and `IBivariate`. | | `ISplineUnivariateInterpolatorFactory` | Extends `IInterpolatorFactory`, `ISpline`, and `IUnivariate`. | | `ISplineBicubicInterpolatorFactory` | Extends `IInterpolatorFactory`, `ISpline`, and `IBivariate`. | ## Interpolation transformation For some use cases, both the input data for an interpolator and the result of the interpolation need to be transformed. To simplify the creation and configuration of transformations, we provide the following classes: | Class | Details | | ------------------------------------ | ------------------------------------------------------------------------------------- | | `IInterpolationTransformation` | An interface for an object that transforms a market data quote based on a coordinate. | | `VolatilityToVarianceTransformation` | Applies the volatility-to-variance formula to a tenor and a market data quote. | | `VarianceToVolatilityTransformation` | Applies the variance-to-volatility formula to a tenor and a market data quote. | ## Interpolator Implementations The majority of interpolators provided in Atoti Market Data use the Apache Commons Math library. As the Apache library expects unflattened matrices, conversion and sorting is handled through data classes in the `com.activeviam.marketdata.lib.interpolation.interpolators.commonsmath.data` package: | Class | Input | Details | | -------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------- | | `CurveInterpolationData` | Tenors and values | Sorts the tenors as `double[]` and stores the associated values as `double[]`. | | `SurfaceInterpolationData` | Tenors, moneyness, and values | Sorts the tenors and moneyness as `double[]`, and stores the associated values as `double[][]`. | Several interpolators are provided in the `com.activeviam.marketdata.lib.interpolation.interpolators.commonsmath.impl` package. | Interpolator | Interpolation type | Axes | Interface | Details | | ------------------------------ | ------------------ | ---- | ----------------------------------------- | -------------------------------------------------------------- | | `BicubicInterpolator` | `CUBIC` | 2 | `IInterpolator`, `ICubic`, `IBivariate` | Extends the Commons Math `BicubicIntepolator`. | | `SplineUnivariateInterpolator` | `SPLINE` | 1 | `IInterpolator`, `ISpline`, `IUnivariate` | Extends the Commons Math `SplineInterpolator`. | | `SplineBicubicInterpolator` | `SPLINE` | 2 | `IInterpolator`, `ISpline`, `IBivariate` | Extends the Commons Math `PiecewiseBicubicSplineInterpolator`. | Further, custom interpolators let you carry out linear interpolation on any number of axes. You can find them in the `com.activeviam.marketdata.lib.interpolation.interpolators.impl` package. | Interpolator | Interpolation type | Axes | Interface | Details | | -------------------------------------- | ------------------------------------------------------------------------- | ---- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `LinearInterpolator` | `LINEAR` | any | `IInterpolator`, `ILinear` | Custom implementation of a linear interpolator. | | `PostTransformationLinearInterpolator` | Any type configured to provide a post-transformation linear interpolator. | any | `IInterpolator`, `ILinear` | Custom implementation of a linear interpolator, which allows the definition of post-interpolation transformations on any axis. | ## Interpolator factories The following interpolator factory classes are available. Implementations of `IInterpolatorFactory` are available in the same package and these construct interpolators that work along one, two, or three axes, as follows: | InterpolatorFactory | Interpolation type | Axes | Interface | Details | | ------------------------------------------ | ------------------ | ---- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `LinearUnivariateInterpolatorFactory` | `LINEAR` | 1 | `ILinearUnivariateInterpolatorFactory` (`IInterpolatorFactory`, `ILinear`, `IUnivariate`) | Constructs linear interpolators that operate on a single axis. | | `BilinearInterpolatorFactory` | `LINEAR` | 2 | `IBilinearInterpolatorFactory` (`IInterpolatorFactory`, `ILinear`, `IBivariate`) | Constructs linear interpolators that operate on two axes. | | `VolToVarianceBilinearInterpolatorFactory` | `VOL_TO_VARIANCE` | 2 | `IVolToVarianceBilinearInterpolatorFactory` (`IInterpolatorFactory`, `IVolToVariance`, `IBivariate`) | Applies the volatility-to-variance pre-interpolation transformation to surface market data and constructs interpolators that apply the variance-to-volatility post-interpolation transformation on the tenor axis. | | `BicubicInterpolatorFactory` | `CUBIC` | 1 | `IBicubicInterpolatorFactory` (`IInterpolatorFactory`, `ICubic`, `IUnivariate`) | Constructs cubic interpolators that operate on a single axis. | | `SplineBicubicInterpolatorFactory` | `SPLINE` | 2 | `ISplineBicubicInterpolatorFactory` (`IInterpolatorFactory`, `ISpline`, `IBivariate`) | Constructs spline interpolators that operate on two axes. | ## Interpolation services The following interpolation services are available: * The `IInterpolatorBuilderService` interface, with corresponding `InterpolatorBuilderService` implementation, collects the interpolator factories and allows the retrieval of an interpolator for the given mode, values, and number of coordinate axes. The retrieved interpolator is constructed with the correct known data points. * The `IInterpolationService` interface, providing a method for interpolating a `V` value for a specific `P` point, using a `CompositeKey` cache key, an `InterpolationMode` and `D` known data and a specific `P` point. The interfaces can be found in the `com.activeviam.marketdata.lib.interpolation.services.intf` package with the implementations in the `com.activeviam.marketdata.lib.interpolation.services.impl` package. | Class | Details | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `IInterpolatorBuilderService` | Provides a single `build(InterpolationMode mode, double[] values, double[]... coordinates)` method returning an `IInterpolator`. | | `InterpolatorBuilderService` | Implementation of `IInterpolationService` that stores a set of interpolator factories and returns the correct interpolator for the given mode, values, and number of coordinate axes. | | `IInterpolationService` | Provides a single `V interpolate(CompositeKey cacheKey, InterpolationMode interpolationMode, D knownData, P requestedPoint)` method returning the interpolated value for the requested point. | | `CurveMarketDataInterpolationService` | An implementation of `IInterpolationService, CurvePoint

>`, it interpolates the requested point based on the known data. It allows for the data tenor mapper and the point tenor mapper to be defined separately. | | `DefaultCurveMarketDataInterpolationService` | An extension of `CurveMarketDataInterpolationService`, it assumes both data tenors and point tenors are of type `String` and uses the `StringToDoubleTenorMapper` for both. | | `SurfaceMarketDataInterpolationService` | An implementation of `IInterpolationService, SurfacePoint>`, it interpolates the requested point based on the known data. It allows for the data tenor and moneyness mappers, as well as the point tenor and moneyness mappers to be defined separately. | | `DefaultSurfaceMarketDataInterpolationService` | An extension of `SurfaceMarketDataInterpolationService`, it assumes all data and point tenors and moneyness values are of type `String` and uses `DefaultStringToDoubleTenorMapper` for tenors and `DefaultStringToDoubleMoneynessMapper` for moneyness values. | | `CurvePoint` | A wrapper around a `T` tenor. | | `SurfacePoint` | A wrapper around a `T` tenor and `M` moneyness. | ## Spring configuration classes Several Spring configuration classes are provided in the `com.activeviam.marketdata.config.interpolation` package of the `market-data-config` module, providing interpolation services and interpolator factory Spring beans. When you add the `market-data-spring-boot-starter` as a dependency in your project, the `AllMarketDataInterpolationConfig` class will be autoconfigured. | Class | Details | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AllMarketDataInterpolationConfig` | Imports all other `*InterpolatorConfig` classes. | | `InterpolatorBuilderServiceConfig` | Collects all `IInterpolatorFactory` beans and publishes an `IInterpolatorBuilderService` bean that can be overridden by creating a custom bean of the same type. | | `LinearUnivariateInterpolatorConfig` | Publishes a `LinearUnivariateInterpolatorFactory` as an `ILinearUnivariateInterpolatorFactory` bean that can be overridden by creating a custom bean of the same type. | | `BilinearInterpolatorConfig` | Publishes a `BilinearInterpolatorFactory` as an `IBilinearInterpolatorFactory` bean that can be overridden by creating a custom bean of the same type. | | `VolToVarianceBilinearInterpolatorConfig` | Publishes a `VolToVarianceBilinearInterpolatorFactory` as an `IVolToVarianceBilinearInterpolatorFactory` bean that can be overridden by creating a custom bean of the same type. | | `BicubicInterpolatorConfig` | Publishes a `BicubicInterpolatorFactory` as an `IBicubicInterpolatorFactoryFactory` bean that can be overridden by creating a custom bean of the same type. | | `SplineUnivariateInterpolatorConfig` | Publishes a `SplineUnivariateInterpolatorFactory` as an `ISplineUnivariateInterpolatorFactory` bean that can be overridden by creating a custom bean of the same type. | | `SplineBicubicInterpolatorConfig` | Publishes a `SplineBicubicInterpolatorFactory` as an `ISplineBicubicInterpolatorFactory` bean that can be overridden by creating a custom bean of the same type. |