rateslib 3.0.0.dev4__cp311-abi3-win32.whl

rateslib/__init__.py

@@ -0,0 +1,258 @@
+# 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
+####################################################################################################
+
+__docformat__ = "restructuredtext"
+__version__ = "3.0.0.dev4"
+
+# Let users know if they're missing any of our hard dependencies
+_hard_dependencies = ("pandas", "matplotlib", "numpy")
+_missing_dependencies: list[str] = []
+
+for _dependency in _hard_dependencies:
+    try:
+        __import__(_dependency)
+    except ImportError as _e:  # pragma: no cover
+        raise ImportError(f"`rateslib` requires installation of {_dependency}: {_e}")
+
+## User warnings convert from Rust::log
+import logging
+import warnings
+import rateslib.rs
+
+
+class RustLogToUserWarningHandler(logging.Handler):
+    def emit(self, record):
+        if record.levelno >= logging.WARNING:
+            warnings.warn(
+                f"[{record.levelname}] {record.getMessage()}",
+                category=UserWarning,
+                stacklevel=3,  # Adjusts the stack trace so it points to the Python user's line
+            )
+
+
+logger = logging.getLogger("rateslib")
+logger.addHandler(RustLogToUserWarningHandler())
+logger.setLevel(logging.WARNING)
+logger.propagate = False
+##
+
+from datetime import datetime as dt
+
+from rateslib.default import *
+
+defaults = DefaultManager()
+calendars = CalendarManager()
+specs = SpecManager()
+indexes = IndexManager()
+
+from rateslib.licence import *
+
+licence = LicenceManager()
+
+from rateslib.fixings import *
+
+fixings = FixingsManager()
+
+from rateslib.ad import *
+from rateslib.enums import *
+from rateslib.display import *
+from rateslib.curves import *
+from rateslib.scheduling import *
+from rateslib.periods import *
+from rateslib.periods.parameters import *
+from rateslib.fx import *
+from rateslib.solver import *
+from rateslib.legs import *
+from rateslib.instruments import *
+from rateslib.trait_protocols import *
+
+# fixings.set_data_directory(os.path.dirname(os.path.abspath(__file__)) + "/historical")
+
+from contextlib import ContextDecorator
+
+
+class default_context(ContextDecorator):
+    """
+    Context manager to temporarily set options in the `with` statement context.
+
+    You need to invoke as ``option_context(key, val, key2, val2, ...)``.
+
+    Examples
+    --------
+    >>> with default_context('convention', "act360", 'frequency', 'S'):
+    ...     pass
+    """
+
+    def __init__(self, *args) -> None:  # type: ignore[no-untyped-def]
+        if len(args) % 2 != 0 or len(args) < 2:
+            raise ValueError("Need to invoke as default_context(key, val, key2, val2, ...).")
+
+        self.ops = list(zip(args[::2], args[1::2], strict=False))
+
+    def __enter__(self) -> None:
+        self.undo = [(key, defaults.get(key)) for key, _ in self.ops]
+
+        for key, val in self.ops:
+            defaults.set(key, val)
+
+    def __exit__(self, *args) -> None:  # type: ignore[no-untyped-def]
+        if self.undo:
+            for key, val in self.undo:
+                defaults.set(key, val)
+
+
+__all__ = [
+    # globals
+    "dt",
+    "defaults",
+    "calendars",
+    "specs",
+    "indexes",
+    "fixings",
+    "licence",
+    # ad
+    "Dual",
+    "Dual2",
+    "Variable",
+    "ADOrder",
+    "gradient",
+    # curves
+    "CurveMetricsTrait",
+    "Curve",
+    "CurvesContext",
+    "CompositeCurve",
+    "CreditImpliedCurve",
+    "ProxyCurve",
+    "MultiCsaCurve",
+    "RolledCurve",
+    "TranslatedCurve",
+    "TenorsCurve",
+    "CurveMeta",
+    "CurvesContext",
+    "index_left",
+    "SmithWilsonCurve",
+    "NelsonSiegelCurve",
+    "NelsonSiegelSvenssonCurve",
+    "UserCurve",
+    # display
+    "frame",
+    "plot",
+    # scheduling
+    "Schedule",
+    "Tenor",
+    "Frequency",
+    "RollDay",
+    "Adjuster",
+    "Cal",
+    "UnionCal",
+    "NamedCal",
+    "Imm",
+    "Convention",
+    "StubInference",
+    "next_imm",
+    "get_imm",
+    "add_tenor",
+    "dcf",
+    # fx
+    "Ccy",
+    "FXPair",
+    "FXRate",
+    "FXRates",
+    "FXForwards",
+    "FXAggregator",
+    # solver
+    "Solver",
+    # periods
+    "Cashflow",
+    "MtmCashflow",
+    "FixedPeriod",
+    "FloatPeriod",
+    "ZeroFixedPeriod",
+    "ZeroFloatPeriod",
+    "CreditPremiumPeriod",
+    "CreditProtectionPeriod",
+    # periods.parameters
+    "SettlementParams",
+    "ScheduleParams",
+    "IndexParams",
+    "NonDeliverableParams",
+    "FixedRateParams",
+    "CreditParams",
+    "FloatRateParams",
+    "FixedRateParams",
+    "MtmParams",
+    # legs
+    "FixedLeg",
+    "FloatLeg",
+    "ZeroFloatLeg",
+    "ZeroFixedLeg",
+    "CreditPremiumLeg",
+    "CreditProtectionLeg",
+    "CustomLeg",
+    # instruments
+    "MetricsTrait",
+    "Bill",
+    "BondFuture",
+    "FixedRateLoan",
+    "FixedRateBond",
+    "FloatRateLoan",
+    "FloatRateNote",
+    "Fee",
+    "FXForward",
+    "FXSwap",
+    "NDF",
+    "FRA",
+    "IRS",
+    "SBS",
+    "STIRFuture",
+    "IIRS",
+    "YoYIS",
+    "XCS",
+    "XCSFixed",
+    "XCSFixedFixed",
+    "ZCIS",
+    "ZCS",
+    "CDS",
+    "Value",
+    "Portfolio",
+    "Spread",
+    "Fly",
+    # user defined object traits
+    "CurveMetrics",
+    "CurveMetricsMut",
+    "Metrics",
+    # enums
+    "AccrualMethod",
+    "Amortization",
+    "BillConvention",
+    "ConversionFactorConvention",
+    "CurveType",
+    "FloatFixingMethod",
+    "FXDeltaMethod",
+    "IndexMethod",
+    "IROptionMetric",
+    "LegIndexBase",
+    "LegMtm",
+    "LocalInterpolation",
+    "PPSplineEndpoint",
+    "RateMetric",
+    "SecurityMetric",
+    "SolverAlgo",
+    "SolverStatus",
+    "SpreadCompoundMethod",
+    "SwaptionSettlementMethod",
+    "Transform",
+    "YtmConvention",
+    "YtmC",
+    "YtmV1",
+    "YtmV2",
+    "YtmV3",
+]

rateslib/ad/__init__.py

@@ -0,0 +1,376 @@
+# 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 math
+from functools import partial
+from statistics import NormalDist
+from typing import TYPE_CHECKING, TypeAlias, Union
+import numpy as np
+
+from rateslib.rs import (
+    Dual,
+    Dual2,
+    Variable,
+    ADOrder,
+    _dsolve1,
+    _dsolve2,
+    _fdsolve1,
+    _fdsolve2,
+    set_order,
+    ift_1dim,
+    newton_1dim,
+    newton_ndim,
+)
+
+PRECISION = 1e-14
+FLOATS = float | np.float16 | np.float32 | np.float64 | np.longdouble
+INTS = int | np.int8 | np.int16 | np.int32 | np.int32 | np.int64
+
+Number: TypeAlias = Union[float, Dual, Dual2, Variable]
+
+if TYPE_CHECKING:
+    from rateslib.typing_rateslib import (
+        # Any,
+        Arr1dF64,
+        Arr1dObj,
+        Arr2dF64,
+        Arr2dObj,
+        # DualTypes,
+        # Number,
+        # Result,
+        Sequence,
+    )
+
+
+def set_order_convert(
+    val: Number, order: int, tag: list[str] | None, vars_from: Dual | Dual2 | None = None
+) -> Number:
+    """
+    Convert a float, :class:`Dual` or :class:`Dual2` type to a specified alternate type with
+    tagged variables.
+
+    Parameters
+    ----------
+    val : float, Dual, Dual2, Variable
+        The value to convert.
+    order : int
+        The AD order to convert the value to if necessary.
+    tag : list of str, optional
+        The variable name(s) if upcasting a float to a Dual or Dual2
+    vars_from : optional, Dual or Dual2
+        A pre-existing Dual of correct order from which the Vars are extracted. Improves efficiency
+        when given.
+
+    Returns
+    -------
+    float, Dual, Dual2
+
+    Notes
+    -----
+    This function is used for AD variable management.
+
+    ``tag`` and ``vars_from`` are only used when floats are upcast and the variables need to be
+    specifically define.
+
+    """
+    if isinstance(val, FLOATS | INTS):
+        _ = [] if tag is None else tag
+        if order == 0:
+            return float(val)
+        elif order == 1:
+            if vars_from is None:
+                return Dual(val, _, [])
+            elif isinstance(vars_from, Dual):
+                return Dual.vars_from(vars_from, val, _, [])
+            else:
+                raise TypeError("`vars_from` must be a Dual when converting to ADOrder:1.")
+        elif order == 2:
+            if vars_from is None:
+                return Dual2(val, _, [], [])
+            elif isinstance(vars_from, Dual2):
+                return Dual2.vars_from(vars_from, val, _, [], [])
+            else:
+                raise TypeError("`vars_from` must be a Dual2 when converting to ADOrder:2.")
+    # else val is Dual or Dual2 so convert directly
+    return set_order(val, order)
+
+
+def gradient(
+    dual: Number,
+    vars: Sequence[str] | None = None,  # noqa: A002
+    order: int = 1,
+    keep_manifold: bool = False,
+) -> Arr1dF64 | Arr2dF64:
+    """
+    Return derivatives of a dual number.
+
+    Parameters
+    ----------
+    dual : Dual, Dual2, Variable, float
+        The dual variable from which to derive derivatives.
+    vars : str, tuple, list optional
+        Name of the variables which to return gradients for. If not given
+        defaults to all vars attributed to the instance.
+    order : {1, 2}
+        Whether to return the first or second derivative of the dual number.
+        Second order will raise if applied to a ``Dual`` and not ``Dual2`` instance.
+    keep_manifold : bool
+        If ``order`` is 1 and the type is ``Dual2`` one can return a ``Dual2``
+        where the ``dual2`` values are converted to ``dual`` values to represent
+        a first order manifold of the first derivative (and the ``dual2`` values
+        set to zero). Useful for propagation in iterations.
+
+    Returns
+    -------
+    float, ndarray, Dual2
+    """
+    _validate_keep_manifold(keep_manifold, order, dual)
+
+    if order == 1:
+        if not isinstance(dual, Dual | Dual2 | Variable):
+            if isinstance(dual, float | int):
+                return np.zeros(shape=(len(vars) if vars is not None else 0,))
+            else:
+                raise TypeError("Can call `gradient` only on dual-type variables.")
+        if isinstance(dual, Variable):
+            dual = Dual(dual.real, vars=dual.vars, dual=dual.dual)
+        if vars is None and not keep_manifold:
+            return dual.dual
+        elif vars is not None and not keep_manifold:
+            return dual.grad1(vars)
+        _ = dual.grad1_manifold(dual.vars if vars is None else vars)  # type: ignore[union-attr]
+        return np.asarray(_)
+
+    elif order == 2:
+        if not isinstance(dual, Dual | Dual2 | Variable):
+            if isinstance(dual, float | int):
+                n = len(vars) if vars is not None else 0
+                return np.zeros(shape=(n, n))
+            else:
+                raise TypeError("Can call `gradient` only on dual-type variables.")
+        if isinstance(dual, Variable):
+            dual = Dual2(dual.real, vars=dual.vars, dual=dual.dual, dual2=[])
+        elif isinstance(dual, Dual):
+            raise TypeError("Dual type cannot derive second order automatic derivatives.")
+
+        if vars is None:
+            return 2.0 * dual.dual2
+        else:
+            return dual.grad2(vars)
+    else:
+        raise ValueError("`order` must be in {1, 2} for gradient calculation.")
+
+
+def _validate_keep_manifold(keep_manifold: bool, order: int, dual: Number) -> None:
+    """Validate the keep_manifold argument for gradient."""
+    if keep_manifold and not isinstance(dual, Dual2):
+        if isinstance(dual, Dual):
+            raise TypeError("Dual type cannot perform `keep_manifold`.")
+        elif isinstance(dual, Variable):
+            raise TypeError("Variable type cannot perform `keep_manifold`.")
+        else:
+            raise TypeError("Float type cannot perform `keep_manifold`.")
+
+
+def dual_exp(x: Number) -> Number:
+    """
+    Calculate the exponential value of a regular int or float or a dual number.
+
+    Parameters
+    ----------
+    x : int, float, Dual, Dual2, Variable
+        Value to calculate exponent of.
+
+    Returns
+    -------
+    float, Dual, Dual2
+    """
+    if isinstance(x, Dual | Dual2 | Variable | Variable):
+        return x.__exp__()
+    return math.exp(x)
+
+
+def dual_log(x: Number, base: int | None = None) -> Number:
+    """
+    Calculate the logarithm of a regular int or float or a dual number.
+
+    Parameters
+    ----------
+    x : int, float, Dual, Dual2, Variable
+        Value to calculate exponent of.
+    base : int, float, optional
+        Base of the logarithm. Defaults to e to compute natural logarithm
+
+    Returns
+    -------
+    float, Dual, Dual2
+    """
+    if isinstance(x, Dual | Dual2 | Variable | Variable):
+        val = x.__log__()
+        if base is None:
+            return val
+        else:
+            return val * (1 / math.log(base))
+    elif base is None:
+        return math.log(x)
+    else:
+        return math.log(x, base)
+
+
+def dual_norm_pdf(x: Number) -> Number:
+    """
+    Return the standard normal probability density function.
+
+    Parameters
+    ----------
+    x : float, Dual, Dual2, Variable
+
+    Returns
+    -------
+    float, Dual, Dual2
+    """
+    return dual_exp(-0.5 * x**2) / math.sqrt(2.0 * math.pi)
+
+
+def dual_norm_cdf(x: Number) -> Number:
+    """
+    Return the cumulative standard normal distribution for given value.
+
+    Parameters
+    ----------
+    x : float, Dual, Dual2, Variable
+
+    Returns
+    -------
+    float, Dual, Dual2
+    """
+    if isinstance(x, Dual | Dual2 | Variable):
+        return x.__norm_cdf__()
+    else:
+        return NormalDist().cdf(x)
+
+
+def dual_inv_norm_cdf(x: Number) -> Number:
+    """
+    Return the inverse cumulative standard normal distribution for given value.
+
+    Parameters
+    ----------
+    x : float, Dual, Dual2, Variable
+
+    Returns
+    -------
+    float, Dual, Dual2
+    """
+    if isinstance(x, Dual | Dual2 | Variable):
+        return x.__norm_inv_cdf__()
+    else:
+        return NormalDist().inv_cdf(x)
+
+
+def dual_solve(
+    A: Arr2dObj | Arr2dF64,
+    b: Arr1dObj | Arr1dF64,
+    allow_lsq: bool = False,
+    types: tuple[type[float] | type[Dual] | type[Dual2], type[float] | type[Dual] | type[Dual2]] = (
+        Dual,
+        Dual,
+    ),
+) -> Arr1dObj | Arr1dF64:
+    """
+    Solve a linear system of equations involving dual number data types.
+
+    The `x` value is found for the equation :math:`Ax=b`.
+
+    .. warning::
+
+       This method has not yet implemented :class:`~rateslib.dual.Variable` types.
+
+    Parameters
+    ----------
+    A: 2-d array
+        Left side matrix of values.
+    b: 1-d array
+        Right side vector of values.
+    allow_lsq: bool
+        Whether to allow solutions for non-square `A`, i.e. when `len(b) > len(x)`.
+    types: tuple
+        Defining the input data type elements of `A` and `b`, e.g. (float, float) or (Dual, Dual).
+
+    Returns
+    -------
+    1-d array
+    """
+    if types == (float, float):
+        # Use basic Numpy LinAlg
+        if allow_lsq:
+            return np.linalg.lstsq(A, b, rcond=None)[0]  # type: ignore[arg-type]
+        else:
+            return np.linalg.solve(A, b)  # type: ignore[arg-type]
+
+    # Move to Rust implementation
+    if types in [(Dual, float), (Dual2, float)]:
+        raise TypeError(
+            "Not implemented for type crossing. Use (Dual, Dual) or (Dual2, Dual2). It is no less"
+            "efficient to preconvert `b` to dual types and then solve.",
+        )
+
+    def order_from_type(t: float | Dual | Dual2):
+        if t is float:
+            return 0
+        elif t is Dual:
+            return 1
+        else:
+            return 2
+
+    A_ = np.vectorize(
+        partial(set_order_convert, tag=[], order=order_from_type(types[0]), vars_from=None)
+    )(A)
+    b_ = np.vectorize(
+        partial(set_order_convert, tag=[], order=order_from_type(types[1]), vars_from=None)
+    )(b)
+
+    a_ = [item for sublist in A_.tolist() for item in sublist]  # 1D array of A_
+    b_ = b_[:, 0].tolist()
+
+    if types == (Dual, Dual):
+        return np.array(_dsolve1(a_, b_, allow_lsq))[:, None]
+    elif types == (Dual2, Dual2):
+        return np.array(_dsolve2(a_, b_, allow_lsq))[:, None]
+    elif types == (float, Dual):
+        return np.array(_fdsolve1(A_, b_, allow_lsq))[:, None]
+    elif types == (float, Dual2):
+        return np.array(_fdsolve2(A_, b_, allow_lsq))[:, None]
+    else:
+        raise TypeError(
+            "Provided `types` argument are not permitted. Must be a 2-tuple with "
+            "elements from {float, Dual, Dual2}"
+        )
+
+
+__all__ = [
+    "Dual",
+    "Dual2",
+    "Variable",
+    "ADOrder",
+    "dual_exp",
+    "dual_log",
+    "dual_solve",
+    "dual_norm_cdf",
+    "dual_inv_norm_cdf",
+    "gradient",
+    "set_order",
+    "ift_1dim",
+    "newton_1dim",
+    "newton_ndim",
+]

rateslib/ad/utils.py

@@ -0,0 +1,22 @@
+# 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
+
+from rateslib.rs import Dual, Dual2, Variable
+
+
+def _abs_float(val: float | Dual | Dual2 | Variable) -> float:
+    """Overload the abs() builtin to return the abs of the real component only"""
+    if isinstance(val, Dual | Dual2 | Variable):
+        return abs(val.real)
+    else:
+        return abs(val)