# SPDX-License-Identifier: LicenseRef-Rateslib-Dual

#

# Copyright (c) 2026 Siffrorna Technology Limited

#

# Dual-licensed: Free Educational Licence or Paid Commercial Licence (commercial/professional use)

# Source-available, not open source.

#

# See LICENSE and https://rateslib.com/py/en/latest/i_licence.html for details,

# and/or contact info (at) rateslib (dot) com

####################################################################################################

from __future__ import annotations

import warnings

from itertools import combinations

from math import log

from time import time

from typing import TYPE_CHECKING, ParamSpec

from uuid import uuid4

import numpy as np

from pandas import DataFrame, MultiIndex, Series, concat

from pandas.errors import PerformanceWarning

from rateslib import defaults

from rateslib.curves import (

CompositeCurve,

Curve,

MultiCsaCurve,

ProxyCurve,

RolledCurve,

ShiftedCurve,

TranslatedCurve,

_BaseCurve,

)

from rateslib.dual import Dual, Dual2, dual_solve, gradient

from rateslib.dual.newton import _solver_result

from rateslib.dual.utils import _dual_float

from rateslib.enums.generics import NoInput, _drb

from rateslib.fx import FXForwards, FXRates

from rateslib.mutability import (

_new_state_post,

_no_interior_validation,

_validate_states,

_WithState,

)

from rateslib.volatility.fx import FXVols

from rateslib.volatility.ir import IRVols, _BaseIRCube, _BaseIRSmile

P = ParamSpec("P")

if TYPE_CHECKING:

from numpy import float64 as Nf64 # noqa: N812

from numpy import object_ as Nobject # noqa: N812

from numpy.typing import NDArray

from rateslib.local_types import (

FX_,

Any,

Callable,

DualTypes,

FXForwards_,

Sequence,

SupportsRate,

SupportsSolverMutability,

Variable,

str_,

)

class Gradients:

"""

A catalogue of all the gradients used in optimisation routines and risk

sensitivties.

"""

_grad_s_vT_method: str = "_grad_s_vT_final_iteration_analytical"

_grad_s_vT_final_iteration_algo: str = "gauss_newton_final"

_J: NDArray[Nf64] | None

_J_pre: NDArray[Nf64] | None

_J2: NDArray[Nf64] | None

_J2_pre: NDArray[Nf64] | None

_grad_v_g: NDArray[Nf64] | None

_grad_s_vT: NDArray[Nf64] | None

_grad_s_vT_pre: NDArray[Nf64] | None

_grad_s_s_vT: NDArray[Nf64] | None

_grad_s_s_vT_pre: NDArray[Nf64] | None

_reset_properties_: Callable[..., None]

_update_step_: Callable[[str], NDArray[Nobject]]

_set_ad_order: Callable[[int], None]

iterate: Callable[..., None]

func_tol: float

conv_tol: float

pre_solvers: tuple[Solver, ...]

r: NDArray[Nobject] # instrument rates at iterate

r_pre: NDArray[Nobject] # instrument rates at iterate including pre_

s: NDArray[Nobject] # target instrument rates

m: int # number of instruments

pre_m: int # number of instruments including pre_

n: int # number of parameters/variables

pre_n: int # number of parameters/variables in all solvers including pre_

g: Dual | Dual2 # solver objective function value

variables: tuple[str, ...] # string tags for AD coordination

pre_variables: tuple[str, ...] # string tags for AD coordination

pre_rate_scalars: list[float] # scalars for the rate attribute of instruments

_ad: int # ad order

instruments: tuple[tuple[SupportsRate, dict[str, Any]], ...] # calibrators

@property

def J(self) -> NDArray[Nf64]:

"""

2d Jacobian array of calibrating instrument rates with respect to curve

variables, of size (n, m);

.. math::

[J]_{i,j} = [\\nabla_\\mathbf{v} \\mathbf{r^T}]_{i,j} = \\frac{\\partial r_j}{\\partial v_i}

Depends on ``self.r``.

""" # noqa: E501

if self._J is None:

self._J = np.array([gradient(rate, self.variables) for rate in self.r]).T

return self._J

@property

def grad_v_rT(self) -> NDArray[Nf64]:

"""

Alias of ``J``.

"""

return self.J

@property

def J2(self) -> NDArray[Nf64]:

"""

3d array of second derivatives of calibrating instrument rates with

respect to curve variables, of size (n, n, m);

.. math::

[J2]_{i,j,k} = [\\nabla_\\mathbf{v} \\nabla_\\mathbf{v} \\mathbf{r^T}]_{i,j,k} = \\frac{\\partial^2 r_k}{\\partial v_i \\partial v_j}

Depends on ``self.r``.

""" # noqa: E501

if self._J2 is None:

if self._ad != 2:

raise ValueError(

f"Cannot perform second derivative calculations when ad mode is {self._ad}.",

)

rates = np.array([_[0].rate(**_[1]) for _ in self.instruments])

# solver is passed in order to extract curves as string

_ = np.array([gradient(rate, self.variables, order=2) for rate in rates])

self._J2 = np.transpose(_, (1, 2, 0))

return self._J2

@property

def grad_v_v_rT(self) -> NDArray[Nf64]:

"""

Alias of ``J2``.

"""

return self.J2 # pragma: no cover

@property

def grad_v_g(self) -> NDArray[Nf64]:

"""

1d array of objective function value with respect to curve variables,

of size (n,);

.. math::

[\\nabla_\\mathbf{v} g(\\mathbf{v}; \\mathbf{s}) = \\frac{\\partial g}{\\partial v_i}

""" # noqa: E501

if self._grad_v_g is None:

self._grad_v_g = gradient(self.g, self.variables)

return self._grad_v_g

@property

def grad_s_vT(self) -> NDArray[Nf64]:

"""

2d Jacobian array of curve variables with respect to calibrating instruments,

of size (m, n);

.. math::

[\\nabla_\\mathbf{s}\\mathbf{v^T}]_{i,j} = \\frac{\\partial v_j}{\\partial s_i} = \\mathbf{J^+}

""" # noqa: E501

if self._grad_s_vT is None:

self._grad_s_vT = getattr(self, self._grad_s_vT_method)()

return self._grad_s_vT

def _grad_s_vT_final_iteration_dual(self, algorithm: str | None = None) -> NDArray[Nf64]:

"""

This is not the ideal method since it requires reset_properties to reassess.

"""

algorithm = algorithm or self._grad_s_vT_final_iteration_algo

_s = self.s

self.s = np.array([Dual(v, [f"s{i}"], []) for i, v in enumerate(self.s)])

self._reset_properties_()

v_1 = self._update_step_(algorithm)

s_vars = [f"s{i}" for i in range(self.m)]

grad_s_vT = np.array([gradient(v, s_vars) for v in v_1]).T

self.s = _s

return grad_s_vT

def _grad_s_vT_final_iteration_analytical(self) -> NDArray[Nf64]:

"""Uses a pseudoinverse algorithm on floats"""

if self.n == 0:

# then there are no instruments: self is only a Solver container of `pre_solvers`

grad_s_vT: NDArray[Nf64] = np.array([[]], dtype=float)

else:

grad_s_vT = np.linalg.pinv(self.J) # type: ignore[assignment]

return grad_s_vT

def _grad_s_vT_fixed_point_iteration(self) -> NDArray[Nf64]:

"""

This is not the ideal method because it requires second order and reset props.

"""

self._set_ad_order(2)

self._reset_properties_()

_s = self.s

self.s = np.array([Dual2(v, [f"s{i}"], [], []) for i, v in enumerate(self.s)])

s_vars = tuple(f"s{i}" for i in range(self.m))

grad2 = gradient(self.g, self.variables + s_vars, order=2)

grad_v_vT_f = grad2[: self.n, : self.n]

grad_s_vT_f = grad2[self.n :, : self.n]

grad_s_vT: NDArray[Nf64] = np.linalg.solve(grad_v_vT_f, -grad_s_vT_f.T).T # type: ignore[assignment]

# The following are alternative representations. Actually faster to calculate and

# do not require sensitivity against S variables to be measured.

# See 'coding interest rates' equation 12.38

# _1 = np.einsum("iy, yz, jz", self.J, self.W, self.J)

# _2 = np.einsum("z, zy, ijy", self.x.astype(float), self.W, self.J2)

# _3 = 2* (_1 + _2)

# _11 = -2 * np.einsum("iz,zj->ji", self.J, self.W)

self.s = _s

self._set_ad_order(1)

self._reset_properties_()

return grad_s_vT

@property

def grad_s_s_vT(self) -> NDArray[Nf64]:

"""

3d array of second derivatives of curve variables with respect to

calibrating instruments, of size (m, m, n);

.. math::

[\\nabla_\\mathbf{s} \\nabla_\\mathbf{s} \\mathbf{v^T}]_{i,j,k} = \\frac{\\partial^2 v_k}{\\partial s_i \\partial s_j}

""" # noqa: E501

if self._grad_s_s_vT is None:

self._grad_s_s_vT = self._grad_s_s_vT_final_iteration_analytical()

return self._grad_s_s_vT

def _grad_s_s_vT_fwd_difference_method(self) -> NDArray[Nf64]:

"""Use a numerical method, iterating through changes in s to calculate."""

ds = 10 ** (int(log(self.func_tol, 10) / 2))

grad_s_vT_0 = np.copy(self.grad_s_vT)

grad_s_s_vT = np.zeros(shape=(self.m, self.m, self.n))

for i in range(self.m):

self.s[i] += ds

self.iterate()

grad_s_s_vT[:, i, :] = (self.grad_s_vT - grad_s_vT_0) / ds

self.s[i] -= ds

# ensure exact symmetry (maybe redundant)

grad_s_s_vT = (grad_s_s_vT + np.swapaxes(grad_s_s_vT, 0, 1)) / 2

self.iterate()

return grad_s_s_vT

def _grad_s_s_vT_final_iteration_analytical(self, use_pre: bool = False) -> NDArray[Nf64]:

"""

Use an analytical formula and second order AD to calculate.

Not: must have 2nd order AD set to function, and valid properties set to

function

"""

if use_pre:

J2, grad_s_vT = self.J2_pre, self.grad_s_vT_pre

else:

J2, grad_s_vT = self.J2, self.grad_s_vT

# dv/dr_l * d2r_l / dvdv

_: NDArray[Nf64] = np.tensordot(J2, grad_s_vT, (2, 0))

# dv_z /ds * d2v / dv_zdv

_ = np.tensordot(grad_s_vT, _, (1, 0))

# dv_h /ds * d2v /dvdv_h

_ = -np.tensordot(grad_s_vT, _, (1, 1))

grad_s_s_vT = _

return grad_s_s_vT

# _ = np.matmul(grad_s_vT, np.matmul(J2, grad_s_vT))

# grad_s_s_vT = -np.tensordot(grad_s_vT, _, (1, 0))

# return grad_s_s_vT

# _pre versions incorporate all variables of solver and pre_solvers

def grad_f_rT_pre(self, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

2d Jacobian array of calibrating instrument rates with respect to FX rate

variables, of size (len(fx_vars), pre_m);

.. math::

[\\nabla_\\mathbf{f}\\mathbf{r^T}]_{i,j} = \\frac{\\partial r_j}{\\partial f_i}

Parameters

----------

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities.

"""

grad_f_rT = np.array([gradient(rate, fx_vars) for rate in self.r_pre]).T

return grad_f_rT

@property

def J2_pre(self) -> NDArray[Nf64]:

"""

3d array of second derivatives of calibrating instrument rates with

respect to curve variables for all ``Solvers`` including ``pre_solvers``,

of size (pre_n, pre_n, pre_m);

.. math::

[J2]_{i,j,k} = [\\nabla_\\mathbf{v} \\nabla_\\mathbf{v} \\mathbf{r^T}]_{i,j,k} = \\frac{\\partial^2 r_k}{\\partial v_i \\partial v_j}

Depends on ``self.r`` and ``pre_solvers.J2``.

""" # noqa: E501

if len(self.pre_solvers) == 0:

return self.J2

if self._J2_pre is None:

if self._ad != 2:

raise ValueError(

f"Cannot perform second derivative calculations when ad mode is {self._ad}.",

)

J2 = np.zeros(shape=(self.pre_n, self.pre_n, self.pre_m))

i, j = 0, 0

for pre_slvr in self.pre_solvers:

J2[

i : i + pre_slvr.pre_n,

i : i + pre_slvr.pre_n,

j : j + pre_slvr.pre_m,

] = pre_slvr.J2_pre

i, j = i + pre_slvr.pre_n, j + pre_slvr.pre_m

if self.m > 0:

# then self is not only a container for `pre_solvers`

rates = np.array([_[0].rate(**_[1]) for _ in self.instruments])

# solver is passed in order to extract curves as string

_ = np.array([gradient(r, self.pre_variables, order=2) for r in rates])

J2[:, :, -self.m :] = np.transpose(_, (1, 2, 0))

self._J2_pre = J2

return self._J2_pre

def grad_f_v_rT_pre(self, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

3d array of second derivatives of calibrating instrument rates with respect to

FX rates and curve variables, of size (len(fx_vars), pre_n, pre_m);

.. math::

[\\nabla_\\mathbf{f} \\nabla_\\mathbf{v} \\mathbf{r^T}]_{i,j,k} = \\frac{\\partial^2 r_k}{\\partial f_i \\partial v_j}

Parameters

----------

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities.

""" # noqa: E501

# FX sensitivity requires reverting through all pre-solvers rates.

all_gradients = np.array(

[gradient(rate, self.pre_variables + tuple(fx_vars), order=2) for rate in self.r_pre],

).swapaxes(0, 2)

grad_f_v_rT = all_gradients[self.pre_n :, : self.pre_n, :]

return grad_f_v_rT

def grad_f_f_rT_pre(self, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

3d array of second derivatives of calibrating instrument rates with respect to

FX rates, of size (len(fx_vars), len(fx_vars), pre_m);

.. math::

[\\nabla_\\mathbf{f} \\nabla_\\mathbf{f} \\mathbf{r^T}]_{i,j,k} = \\frac{\\partial^2 r_k}{\\partial f_i \\partial f_j}

Parameters

----------

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities.

""" # noqa: E501

# FX sensitivity requires reverting through all pre-solvers rates.

grad_f_f_rT = np.array([gradient(rate, fx_vars, order=2) for rate in self.r_pre]).swapaxes(

0,

2,

)

return grad_f_f_rT

@property

def grad_s_s_vT_pre(self) -> NDArray[Nf64]:

"""

3d array of second derivatives of curve variables with respect to

calibrating instruments, of size (pre_m, pre_m, pre_n);

.. math::

[\\nabla_\\mathbf{s} \\nabla_\\mathbf{s} \\mathbf{v^T}]_{i,j,k} = \\frac{\\partial^2 v_k}{\\partial s_i \\partial s_j}

""" # noqa: E501

if len(self.pre_solvers) == 0:

return self.grad_s_s_vT

if self._grad_s_s_vT_pre is None:

self._grad_s_s_vT_pre = self._grad_s_s_vT_final_iteration_analytical(use_pre=True)

return self._grad_s_s_vT_pre

@property

def grad_v_v_rT_pre(self) -> NDArray[Nf64]:

"""

Alias of ``J2_pre``.

"""

return self.J2_pre # pragma: no cover

def grad_f_s_vT_pre(self, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

3d array of second derivatives of curve variables with respect to

FX rates and calibrating instrument rates, of size (len(fx_vars), pre_m, pre_n);

.. math::

[\\nabla_\\mathbf{f} \\nabla_\\mathbf{s} \\mathbf{v^T}]_{i,j,k} = \\frac{\\partial^2 v_k}{\\partial f_i \\partial s_j}

Parameters

----------

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities.

""" # noqa: E501

# FX sensitivity requires reverting through all pre-solvers rates.

_ = -np.tensordot(self.grad_f_v_rT_pre(fx_vars), self.grad_s_vT_pre, (1, 1)).swapaxes(1, 2)

_ = np.tensordot(_, self.grad_s_vT_pre, (2, 0))

grad_f_s_vT: NDArray[Nf64] = _

return grad_f_s_vT

def grad_f_f_vT_pre(self, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

3d array of second derivatives of curve variables with respect to

FX rates, of size (len(fx_vars), len(fx_vars), pre_n);

.. math::

[\\nabla_\\mathbf{f} \\nabla_\\mathbf{f} \\mathbf{v^T}]_{i,j,k} = \\frac{\\partial^2 v_k}{\\partial f_i \\partial f_j}

Parameters

----------

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities.

""" # noqa: E501

# FX sensitivity requires reverting through all pre-solvers rates.

_ = -np.tensordot(self.grad_f_f_rT_pre(fx_vars), self.grad_s_vT_pre, (2, 0))

_ -= np.tensordot(self.grad_f_rT_pre(fx_vars), self.grad_f_s_vT_pre(fx_vars), (1, 1))

grad_f_f_vT: NDArray[Nf64] = _

return grad_f_f_vT

def grad_f_vT_pre(self, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

2d array of the derivatives of curve variables with respect to FX rates, of

size (len(fx_vars), pre_n).

.. math::

[\\nabla_\\mathbf{f}\\mathbf{v^T}]_{i,j} = \\frac{\\partial v_j}{\\partial f_i} = -\\frac{\\partial r_z}{\\partial f_i} \\frac{\\partial v_j}{\\partial s_z}

Parameters

----------

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities

""" # noqa: E501

# FX sensitivity requires reverting through all pre-solvers rates.

grad_f_rT = np.array([gradient(rate, fx_vars) for rate in self.r_pre]).T

_: NDArray[Nf64] = -np.matmul(grad_f_rT, self.grad_s_vT_pre)

return _

def grad_f_f(self, f: Dual | Dual2 | Variable, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

1d array of total derivatives of FX conversion rate with respect to

FX rate variables, of size (len(fx_vars));

.. math::

[\\nabla_\\mathbf{f} f_{loc:bas}]_{i} = \\frac{d f}{d f_i}

Parameters

----------

f : Dual or Dual2

The value of the local to base FX conversion rate.

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities

"""

grad_f_f = gradient(f, fx_vars)

grad_f_f += np.matmul(self.grad_f_vT_pre(fx_vars), gradient(f, self.pre_variables))

ret: NDArray[Nf64] = grad_f_f

return ret

@property

def grad_s_vT_pre(self) -> NDArray[Nf64]:

"""

2d Jacobian array of curve variables with respect to calibrating instruments

including all pre solvers attached to the Solver, of size (pre_m, pre_n).

.. math::

[\\nabla_\\mathbf{s}\\mathbf{v^T}]_{i,j} = \\frac{\\partial v_j}{\\partial s_i} = \\mathbf{J^+}

""" # noqa: E501

if len(self.pre_solvers) == 0:

return self.grad_s_vT

if self._grad_s_vT_pre is None:

grad_s_vT = np.zeros(shape=(self.pre_m, self.pre_n))

i, j = 0, 0

for pre_solver in self.pre_solvers:

# create the left side block matrix

m, n = pre_solver.pre_m, pre_solver.pre_n

grad_s_vT[i : i + m, j : j + n] = pre_solver.grad_s_vT_pre

# create the right column dependencies, only if self contains some instruments

# and variable of its own and is not only a container of `pre_solvers`

if self.n > 0:

grad_v_r = np.array([gradient(r, pre_solver.pre_variables) for r in self.r]).T

block = np.matmul(grad_v_r, self.grad_s_vT)

block = -1 * np.matmul(pre_solver.grad_s_vT_pre, block)

grad_s_vT[i : i + m, -self.n :] = block

i, j = i + m, j + n

if self.n > 0:

# create bottom right block, only if self contains some instruments

# and variables of its own and is not only a container of `pre_solvers`

grad_s_vT[-self.m :, -self.n :] = self.grad_s_vT

self._grad_s_vT_pre = grad_s_vT

return self._grad_s_vT_pre

def grad_s_f_pre(self, f: Dual | Dual2 | Variable) -> NDArray[Nf64]:

"""

1d array of FX conversion rate with respect to calibrating instruments,

of size (pre_m);

.. math::

[\\nabla_\\mathbf{s} f_{loc:bas}]_{i} = \\frac{\\partial f}{\\partial s_i}

Parameters

----------

f : Dual or Dual2

The value of the local to base FX conversion rate.

"""

grad_s_f: NDArray[Nf64] = np.tensordot(

self.grad_s_vT_pre, gradient(f, self.pre_variables), (1, 0)

)

return grad_s_f

def grad_s_sT_f_pre(self, f: Dual | Dual2 | Variable) -> NDArray[Nf64]:

"""

2d array of derivatives of FX conversion rate with respect to

calibrating instruments, of size (pre_m, pre_m);

.. math::

[\\nabla_\\mathbf{s} \\nabla_\\mathbf{s}^\\mathbf{T} f_{loc:bas}]_{i,j} = \\frac{\\partial^2 f}{\\partial s_i \\partial s_j}

Parameters

----------

f : Dual or Dual2

The value of the local to base FX conversion rate.

""" # noqa: E501

grad_s_vT = self.grad_s_vT_pre

grad_v_vT_f = gradient(f, self.pre_variables, order=2)

_: NDArray[Nf64] = np.tensordot(grad_s_vT, grad_v_vT_f, (1, 0))

_ = np.tensordot(_, grad_s_vT, (1, 1))

grad_s_sT_f = _

return grad_s_sT_f

def grad_f_sT_f_pre(self, f: Dual | Dual2 | Variable, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

2d array of derivatives of FX conversion rate with respect to

calibrating instruments, of size (pre_m, pre_m);

.. math::

[\\nabla_\\mathbf{f} \\nabla_\\mathbf{s}^\\mathbf{T} f_{loc:bas}(\\mathbf{v(s, f), f)})]_{i,j} = \\frac{d^2 f}{d f_i \\partial s_j}

Parameters

----------

f : Dual or Dual2

The value of the local to base FX conversion rate.

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities

""" # noqa: E501

grad_s_vT = self.grad_s_vT_pre

grad_v_f = gradient(f, self.pre_variables)

grad_f_sT_v = self.grad_f_s_vT_pre(fx_vars)

_ = gradient(f, self.pre_variables + tuple(fx_vars), order=2)

grad_v_vT_f = _[: self.pre_n, : self.pre_n]

grad_f_vT_f = _[self.pre_n :, : self.pre_n]

# grad_f_fT_f = _[self.pre_n :, self.pre_n :]

grad_f_vT = self.grad_f_vT_pre(fx_vars)

_ = np.tensordot(grad_f_sT_v, grad_v_f, (2, 0))

_ += np.tensordot(grad_f_vT_f, grad_s_vT, (1, 1))

__ = np.tensordot(grad_f_vT, grad_v_vT_f, (1, 0))

__ = np.tensordot(__, grad_s_vT, (1, 1))

grad_f_sT_f: NDArray[Nf64] = _ + __

return grad_f_sT_f

def grad_f_fT_f_pre(self, f: Dual | Dual2 | Variable, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

2d array of derivatives of FX conversion rate with respect to

calibrating instruments, of size (pre_m, pre_m);

.. math::

[\\nabla_\\mathbf{f} \\nabla_\\mathbf{f}^\\mathbf{T} f_{loc:bas}(\\mathbf{v(s, f), f)})]_{i,j} = \\frac{d^2 f}{d f_i d f_j}

Parameters

----------

f : Dual or Dual2

The value of the local to base FX conversion rate.

fx_vars : list or tuple of str

The variable name tags for the FX rate sensitivities

""" # noqa: E501

# grad_s_vT = self.grad_s_vT_pre

grad_v_f = gradient(f, self.pre_variables)

# grad_f_sT_v = self.grad_f_s_vT_pre(fx_vars)

_ = gradient(f, self.pre_variables + tuple(fx_vars), order=2)

grad_v_vT_f = _[: self.pre_n, : self.pre_n]

grad_f_vT_f = _[self.pre_n :, : self.pre_n]

grad_f_fT_f = _[self.pre_n :, self.pre_n :]

grad_f_vT = self.grad_f_vT_pre(fx_vars)

grad_f_fT_v = self.grad_f_f_vT_pre(fx_vars)

_ = grad_f_fT_f

_ += 2.0 * np.tensordot(grad_f_vT_f, grad_f_vT, (1, 1))

_ += np.tensordot(grad_f_fT_v, grad_v_f, (2, 0))

__ = np.tensordot(grad_f_vT, grad_v_vT_f, (1, 0))

__ = np.tensordot(__, grad_f_vT, (1, 1))

grad_f_fT_f = _ + __

return grad_f_fT_f

# grad_v_v_f: calculated within grad_s_vT_fixed_point_iteration

# delta and gamma calculations require all solver and pre_solver variables

def grad_s_Ploc(self, npv: Dual | Dual2 | Variable) -> NDArray[Nf64]:

"""

1d array of derivatives of local currency PV with respect to calibrating

instruments, of size (pre_m).

.. math::

\\nabla_\\mathbf{s} P^{loc} = \\frac{\\partial P^{loc}}{\\partial s_i}

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

"""

grad_s_P: NDArray[Nf64] = np.matmul(self.grad_s_vT_pre, gradient(npv, self.pre_variables))

return grad_s_P

def grad_f_Ploc(self, npv: Dual | Dual2 | Variable, fx_vars: Sequence[str]) -> NDArray[Nf64]:

r"""

1d array of derivatives of local currency PV with respect to FX rate variable,

of size (len(fx_vars)).

.. math::

\\nabla_\\mathbf{f} P^{loc}(\\mathbf{v(s, f), f}) = \\frac{\\partial P^{loc}}{\\partial f_i}+ \\frac{\partial v_z}{\\partial f_i} \\frac{\\partial P^{loc}}{\\partial v_z}

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

""" # noqa: E501

grad_f_P = gradient(npv, fx_vars)

grad_f_P += np.matmul(self.grad_f_vT_pre(fx_vars), gradient(npv, self.pre_variables))

ret: NDArray[Nf64] = grad_f_P

return ret

def grad_s_Pbase(

self, npv: Dual | Dual2 | Variable, grad_s_P: NDArray[Nf64], f: Dual | Dual2 | Variable

) -> NDArray[Nf64]:

"""

1d array of derivatives of base currency PV with respect to calibrating

instruments, of size (pre_m).

.. math::

\\nabla_\\mathbf{s} P^{bas}(\\mathbf{v(s, f)}) = \\nabla_\\mathbf{s} P^{loc}(\\mathbf{v(s, f)}) f_{loc:bas} + P^{loc} \\nabla_\\mathbf{s} f_{loc:bas}

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

grad_s_P : ndarray

The local currency delta risks w.r.t. calibrating instruments.

f : Dual or Dual2

The local:base FX rate.

""" # noqa: E501

grad_s_Pbas: NDArray[Nf64] = _dual_float(npv) * np.matmul(

self.grad_s_vT_pre, gradient(f, self.pre_variables)

)

grad_s_Pbas += grad_s_P * _dual_float(f) # <- use float to cast float array not Dual

return grad_s_Pbas

def grad_f_Pbase(

self,

npv: Dual | Dual2 | Variable,

grad_f_P: NDArray[Nf64],

f: Dual | Dual2 | Variable,

fx_vars: Sequence[str],

) -> NDArray[Nf64]:

"""

1d array of derivatives of base currency PV with respect to FX rate variables,

of size (len(fx_vars)).

.. math::

\\nabla_\\mathbf{s} P^{bas}(\\mathbf{v(s, f)}) = \\nabla_\\mathbf{s} P^{loc}(\\mathbf{v(s, f)}) f_{loc:bas} + P^{loc} \\nabla_\\mathbf{s} f_{loc:bas}

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

grad_f_P : ndarray

The local currency delta risks w.r.t. FX pair variables.

f : Dual or Dual2

The local:base FX rate.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

""" # noqa: E501

# use float here to cast float array not Dual

ret: NDArray[Nf64] = grad_f_P * _dual_float(f)

ret += _dual_float(npv) * self.grad_f_f(f, fx_vars)

return ret

def grad_s_sT_Ploc(self, npv: Dual2 | Variable) -> NDArray[Nf64]:

"""

2d array of derivatives of local currency PV with respect to calibrating

instruments, of size (pre_m, pre_m).

.. math::

\\nabla_\\mathbf{s} \\nabla_\\mathbf{s}^\\mathbf{T} P^{loc}(\\mathbf{v, f}) = \\frac{ \\partial^2 P^{loc}(\\mathbf{v(s, f)}) }{\\partial s_i \\partial s_j}

Parameters:

npv : Dual2

A local currency NPV of a period of a leg.

""" # noqa: E501

# instrument-instrument cross gamma:

_ = np.tensordot(gradient(npv, self.pre_variables, order=2), self.grad_s_vT_pre, (1, 1))

_ = np.tensordot(self.grad_s_vT_pre, _, (1, 0))

_ += np.tensordot(self.grad_s_s_vT_pre, gradient(npv, self.pre_variables), (2, 0))

grad_s_sT_P: NDArray[Nf64] = _

return grad_s_sT_P

# grad_s_sT_P = np.matmul(

# self.grad_s_vT_pre,

# np.matmul(

# npv.gradient(self.pre_variables, order=2), self.grad_s_vT_pre.T

# ),

# )

# grad_s_sT_P += np.matmul(

# self.grad_s_s_vT_pre, npv.gradient(self.pre_variables)[:, None]

# )[:, :, 0]

def gradp_f_vT_Ploc(

self, npv: Dual | Dual2 | Variable, fx_vars: Sequence[str]

) -> NDArray[Nf64]:

"""

2d array of (partial) derivatives of local currency PV with respect to

FX rate variables and curve variables, of size (len(fx_vars), pre_n).

.. math::

\\nabla_\\mathbf{f} \\nabla_\\mathbf{v}^\\mathbf{T} P^{loc}(\\mathbf{v, f}) = \\frac{ \\partial ^2 P^{loc}(\\mathbf{v, f)}) }{\\partial f_i \\partial v_j}

Parameters:

npv : Dual2

A local currency NPV of a period of a leg.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

""" # noqa: E501

grad_x_xT_Ploc = gradient(npv, self.pre_variables + tuple(fx_vars), order=2)

grad_f_vT_Ploc = grad_x_xT_Ploc[self.pre_n :, : self.pre_n]

return grad_f_vT_Ploc

def grad_f_sT_Ploc(self, npv: Dual | Dual2 | Variable, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

2d array of derivatives of local currency PV with respect to calibrating

instruments, of size (pre_m, pre_m).

.. math::

\\nabla_\\mathbf{f} \\nabla_\\mathbf{s}^\\mathbf{T} P^{loc}(\\mathbf{v(s, f), f}) = \\frac{ d^2 P^{loc}(\\mathbf{v(s, f), f)}) }{d f_i \\partial s_j}

Parameters:

npv : Dual2

A local currency NPV of a period of a leg.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

""" # noqa: E501

# fx_rate-instrument cross gamma:

_ = np.tensordot(

self.grad_f_vT_pre(fx_vars),

gradient(npv, self.pre_variables, order=2),

(1, 0),

)

_ += self.gradp_f_vT_Ploc(npv, fx_vars)

_ = np.tensordot(_, self.grad_s_vT_pre, (1, 1))

_ += np.tensordot(self.grad_f_s_vT_pre(fx_vars), gradient(npv, self.pre_variables), (2, 0))

grad_f_sT_Ploc: NDArray[Nf64] = _

return grad_f_sT_Ploc

def grad_f_fT_Ploc(self, npv: Dual | Dual2 | Variable, fx_vars: Sequence[str]) -> NDArray[Nf64]:

"""

2d array of derivatives of local currency PV with respect to FX rate variables,

of size (len(fx_vars), len(fx_vars)).

.. math::

\\nabla_\\mathbf{f} \\nabla_\\mathbf{s}^\\mathbf{T} P^{loc}(\\mathbf{v(s, f), f}) = \\frac{ d^2 P^{loc}(\\mathbf{v(s, f), f)}) }{d f_i d f_j}

Parameters:

npv : Dual2

A local currency NPV of a period of a leg.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

""" # noqa: E501

# fx_rate-instrument cross gamma:

gradp_f_vT_Ploc = self.gradp_f_vT_Ploc(npv, fx_vars)

grad_f_vT_pre = self.grad_f_vT_pre(fx_vars)

grad_v_Ploc = gradient(npv, self.pre_variables)

grad_v_vT_Ploc = gradient(npv, self.pre_variables, order=2)

_ = gradient(npv, fx_vars, order=2)

_ += np.tensordot(self.grad_f_f_vT_pre(fx_vars), grad_v_Ploc, (2, 0))

_ += np.tensordot(grad_f_vT_pre, gradp_f_vT_Ploc, (1, 1))

_ += np.tensordot(gradp_f_vT_Ploc, grad_f_vT_pre, (1, 1))

__ = np.tensordot(grad_f_vT_pre, grad_v_vT_Ploc, (1, 0))

__ = np.tensordot(__, grad_f_vT_pre, (1, 1))

grad_f_f_Ploc: NDArray[Nf64] = _ + __

return grad_f_f_Ploc

def grad_s_sT_Pbase(

self,

npv: Dual | Dual2 | Variable,

grad_s_sT_P: NDArray[Nf64],

f: Dual | Dual2 | Variable,

) -> NDArray[Nf64]:

"""

2d array of derivatives of base currency PV with respect to calibrating

instrument rate variables, of size (pre_m, pre_m).

.. math::

\\nabla_\\mathbf{s} \\nabla_\\mathbf{s}^\\mathbf{T} P^{bas}(\\mathbf{v(s, f), f})

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

grad_s_sT_P : ndarray

The local currency gamma risks w.r.t. calibrating instrument variables.

f : Dual or Dual2

The local:base FX rate.

"""

grad_s_f = self.grad_s_f_pre(f)

grad_s_sT_f = self.grad_s_sT_f_pre(f)

grad_s_P = self.grad_s_Ploc(npv)

_ = _dual_float(f) * grad_s_sT_P

_ += np.tensordot(grad_s_f[:, None], grad_s_P[None, :], (1, 0))

_ += np.tensordot(grad_s_P[:, None], grad_s_f[None, :], (1, 0))

_ += _dual_float(npv) * grad_s_sT_f # <- use float to cast float array not Dual

grad_s_sT_Pbas: NDArray[Nf64] = _

return grad_s_sT_Pbas

def grad_f_sT_Pbase(

self,

npv: Dual | Dual2 | Variable,

grad_f_sT_P: NDArray[Nf64],

f: Dual | Dual2 | Variable,

fx_vars: Sequence[str],

) -> NDArray[Nf64]:

"""

2d array of derivatives of base currency PV with respect to FX variables and

calibrating instrument rate variables, of size (len(fx_vars), pre_m).

.. math::

\\nabla_\\mathbf{f} \\nabla_\\mathbf{s}^\\mathbf{T} P^{bas}(\\mathbf{v(s, f), f})

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

grad_f_sT_P : ndarray

The local currency gamma risks w.r.t. FX rate variables and

calibrating instrument variables.

f : Dual or Dual2

The local:base FX rate.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

"""

grad_s_f = self.grad_s_f_pre(f)

grad_f_f = self.grad_f_f(f, fx_vars)

grad_s_P = self.grad_s_Ploc(npv)

grad_f_P = self.grad_f_Ploc(npv, fx_vars)

grad_f_sT_f = self.grad_f_sT_f_pre(f, fx_vars)

_ = _dual_float(f) * grad_f_sT_P

_ += np.tensordot(grad_f_f[:, None], grad_s_P[None, :], (1, 0))

_ += np.tensordot(grad_f_P[:, None], grad_s_f[None, :], (1, 0))

_ += _dual_float(npv) * grad_f_sT_f # <- use float to cast float array not Dual

grad_s_sT_Pbas: NDArray[Nf64] = _

return grad_s_sT_Pbas

def grad_f_fT_Pbase(

self,

npv: Dual | Dual2 | Variable,

grad_f_fT_P: NDArray[Nf64],

f: Dual | Dual2 | Variable,

fx_vars: Sequence[str],

) -> NDArray[Nf64]:

"""

2d array of derivatives of base currency PV with respect to calibrating

instrument rate variables, of size (pre_m, pre_m).

.. math::

\\nabla_\\mathbf{s} \\nabla_\\mathbf{s}^\\mathbf{T} P^{bas}(\\mathbf{v(s, f), f})

Parameters:

npv : Dual or Dual2

A local currency NPV of a period of a leg.

grad_f_fT_P : ndarray

The local currency gamma risks w.r.t. FX rate variables.

f : Dual or Dual2

The local:base FX rate.

fx_vars : list or tuple of str

The variable tags for automatic differentiation of FX rate sensitivity

"""

# grad_s_f = self.grad_s_f_pre(f)

grad_f_f = self.grad_f_f(f, fx_vars)

# grad_s_P = self.grad_s_Ploc(npv)

grad_f_P = self.grad_f_Ploc(npv, fx_vars)

grad_f_fT_f = self.grad_f_fT_f_pre(f, fx_vars)

_ = _dual_float(f) * grad_f_fT_P

_ += np.tensordot(grad_f_f[:, None], grad_f_P[None, :], (1, 0))

_ += np.tensordot(grad_f_P[:, None], grad_f_f[None, :], (1, 0))

_ += _dual_float(npv) * grad_f_fT_f # <- use float to cast float array not Dual

grad_s_sT_Pbas: NDArray[Nf64] = _

return grad_s_sT_Pbas

NO_PARAMETER_CURVES = [

ProxyCurve,

CompositeCurve,

MultiCsaCurve,

RolledCurve,

ShiftedCurve,

TranslatedCurve,

]

class Solver(Gradients, _WithState):

r"""

A numerical solver to determine parameter values on multiple pricing objects simultaneously.

.. ipython:: python

:suppress:

from rateslib import Solver, Curve, IRS, dt

Parameters

----------

curves : sequence

Sequence of :class:`Curve` or :class:`Smile` objects where each one

has been individually configured for its node dates and interpolation structures,