dal-python 2026.9.25__cp314-cp314-win_amd64.whl

dal/__init__.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+# Import the C extension first to avoid circular imports when dal.py
+# executes "from . import _dal" during package initialization.
+from . import _dal  # noqa: F401
+from .dal import *
+from .api import *
+
+__author__ = 'The Derivatives Algorithms Group'
+__email__ = 'wegamekinglc@hotmail.com'
+__version__ = "2026.9.25"

dal/api.py

@@ -0,0 +1,148 @@
+import json as _json
+
+from . import dal as _bindings
+
+
+def Product_New(events_dates: list, events: list[str], *, settings=None):
+    wrapped = []
+    for row, value in enumerate(events_dates, 1):
+        if isinstance(value, str) and "\0" in value:
+            raise RuntimeError(
+                f"InvalidSetting: Product_New; events_dates / dates/events row={row}; "
+                f"value={value!r}; expected text without NUL"
+            )
+        try:
+            wrapped.append(value if isinstance(value, _bindings.Cell_) else _bindings.Cell_(value))
+        except TypeError as error:
+            raise TypeError(
+                f"InvalidSetting: Product_New; events_dates / dates/events row={row}; "
+                f"type={type(value).__name__}; expected Cell_ or a Cell_-convertible value"
+            ) from error
+    return _bindings.Product_New(wrapped, events, settings=settings)
+
+
+def Product_Describe(product):
+    return _json.loads(_bindings.Product_Describe(product))
+
+
+def ScriptValuation_Explain(product, modelData, *, valuation=None):
+    return _json.loads(_bindings.ScriptValuation_Explain(product, modelData, valuation=valuation))
+
+
+def ScriptSimulation_Explain(product, modelData, num_path, *, valuation=None, simulation=None):
+    return _json.loads(
+        _bindings.ScriptSimulation_Explain(product, modelData, num_path, valuation=valuation, simulation=simulation)
+    )
+
+
+# Settings whose target fields expect DAL value types — plain Python str
+# must be wrapped before setattr so pybind11 can convert them correctly.
+# DAL objects (String_, CollateralType_ etc.) pass through as-is.
+_DAL_TYPE_CONVERTERS = {
+    'curve_name': lambda v: _bindings.String_(v) if isinstance(v, str) else v,
+    'target_collateral': lambda v: _bindings.CollateralType_(v) if isinstance(v, str) else v,
+    'target_tenor': lambda v: _bindings.PeriodLength_(v) if isinstance(v, str) else v,
+    'libor_basis': lambda v: _bindings.DayBasis_(v) if isinstance(v, str) else v,
+}
+
+_OPTIONAL_SETTING_ATTRS = {
+    'curve_name': 'curveName_',
+    'target_collateral': 'targetCollateral_',
+    'target_tenor': 'targetTenor_',
+    'calibrate_discount': 'calibrateDiscountCurve_',
+    'libor_basis': 'liborBasis_',
+    'smoothing_weight': 'smoothingWeight_',
+    'tolerance': 'tolerance_',
+    'fit_tolerance': 'fitTolerance_',
+    'max_evaluations': 'maxEvaluations_',
+    'max_restarts': 'maxRestarts_',
+    'initial_guess': 'initialGuess_',
+    'solve_mode': 'solveMode_',
+    'parameterization': 'parameterization_',
+    'log_df_scheme': 'logDfScheme_',
+}
+
+
+def _apply_optional_setting(spec, name, value):
+    """Apply a single optional setting to a spec builder if the value is not None."""
+    if name not in _OPTIONAL_SETTING_ATTRS:
+        valid = ', '.join(sorted(_OPTIONAL_SETTING_ATTRS))
+        raise ValueError(f"Unknown calibration setting {name!r}. Supported settings: {valid}")
+    if value is None:
+        return
+    attr = _OPTIONAL_SETTING_ATTRS[name]
+    convert = _DAL_TYPE_CONVERTERS.get(name)
+    setattr(spec, attr, convert(value) if convert else value)
+
+
+def _build_calibration_spec(today, ccy, instruments, knot_dates, settings, base_curve=None):
+    """Build a CurveCalibrationSpec_ with sensible defaults and optional overrides."""
+    spec = _bindings.CurveCalibrationSpecBuilder_()
+    spec.today_ = today
+    spec.ccy_ = ccy if isinstance(ccy, _bindings.String_) else _bindings.String_(ccy)
+
+    spec.curveName_ = _bindings.String_("calibrated")
+    spec.calibrateDiscountCurve_ = True
+    spec.smoothingWeight_ = 1.0
+    spec.tolerance_ = 1e-8
+    spec.fitTolerance_ = 1e-6
+    spec.maxEvaluations_ = 200
+    spec.maxRestarts_ = 20
+    spec.initialGuess_ = 0.05
+
+    spec.instruments_ = instruments
+    spec.knotDates_ = knot_dates
+    if base_curve is not None:
+        spec.baseCurve_ = base_curve
+
+    if settings:
+        for key, value in settings.items():
+            _apply_optional_setting(spec, key, value)
+
+    return spec
+
+
+def calibrate_curve(
+    today,
+    ccy,
+    instruments,
+    knot_dates,
+    settings=None,
+    jacobian_mode=None,
+    base_curve=None,
+):
+    """High-level single-curve calibration with sensible defaults.
+
+    Only discount-curve calibration (calibrate_discount=True) is supported here;
+    forward-curve calibration needs a preloaded discount curve, so build a
+    CurveCalibrationSpecBuilder_ directly (set discountCurves_) and call
+    dal.CalibrateSingleCurve.
+
+    Args:
+        today: Date_ for the calibration date
+        ccy: Currency string (e.g. "USD")
+        instruments: List of YCInstrument_ handles
+        knot_dates: List of Date_ knot points
+        settings: Optional dict of override settings. Supported keys:
+            curve_name, target_collateral, target_tenor, calibrate_discount
+            (must be True), libor_basis, smoothing_weight, tolerance,
+            fit_tolerance, max_evaluations, max_restarts, initial_guess,
+            solve_mode, parameterization, log_df_scheme
+        jacobian_mode: CurveJacobianMode enum (None = default without Jacobian)
+        base_curve: Optional discount curve multiplied into the calibrated curve.
+
+    Returns:
+        CalibrationResult_ with curve_ and diagnostics_
+    """
+    if settings and settings.get("calibrate_discount") is False:
+        raise ValueError(
+            "calibrate_curve() only supports discount-curve calibration "
+            "(calibrate_discount=True). For forward-curve calibration, build a "
+            "CurveCalibrationSpecBuilder_ with discountCurves_ and call "
+            "dal.CalibrateSingleCurve directly."
+        )
+    spec = _build_calibration_spec(today, ccy, instruments, knot_dates, settings, base_curve)
+    if jacobian_mode is not None:
+        return _bindings.CalibrateSingleCurve(spec.Build(), jacobian_mode)
+    else:
+        return _bindings.CalibrateSingleCurve(spec.Build())

dal/dal.py

@@ -0,0 +1,2 @@
+# Auto-generated pybind11 shim -- re-exports all symbols from _dal
+from ._dal import *

dal_python-2026.9.25.dist-info/METADATA

@@ -0,0 +1,1057 @@
+Metadata-Version: 2.4
+Name: dal-python
+Version: 2026.9.25
+Summary: Python bindings for the DAL quantitative finance library
+Author-Email: The Derivatives Algorithms Group <wegamekinglc@hotmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Documentation, https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/tree/master/dal-python
+Project-URL: Repository, https://github.com/wegamekinglc/Derivatives-Algorithms-Lib
+Requires-Python: <3.15,>=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: numpy>=1.24; extra == "test"
+Description-Content-Type: text/markdown
+
+# dal-python
+
+Python bindings for the Derivatives Algorithms Library (DAL) — a high-performance C++17 quantitative finance library with Automatic Adjoint Differentiation (AAD) support.
+
+## Features
+
+- **Black-Scholes and Dupire models** for equity derivatives pricing
+- **Monte Carlo simulation** with pseudo-random and Sobol sequence generators
+- **AAD Greeks** — compute pathwise sensitivities (delta, vega, rho, etc.) in a single simulation
+- **Script engine** — define exotic payoffs using a domain-specific language
+- **Named FIX valuation** — explicit dates, immutable history snapshots, and contract/valuation diagnostics
+- **Curve calibration** — single-curve, multi-curve, staged XCCY, and joint domestic/foreign/basis calibration with resettable and MTM instruments plus AAD analytic Jacobians
+- **Rate cashflow pricing** — typed planning, batch PV, and AAD node sensitivities for deposit, FRA, future, OIS, IRS, basis-swap, and cross-currency trades
+- **Type-safe wrappers** for `Date_`, `Matrix_`, `Cell_`, and vector types
+
+## Prerequisites
+
+- **CPython 3.9-3.14** with development headers (`Requires-Python: >=3.9,<3.15`)
+- **uv** — fast Python package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/))
+- **pybind11 3.1.0** — installed automatically for isolated package builds;
+  local helpers install it before non-isolated builds. Older repository builds
+  can fall back to the pinned `dal-cpp/externals/pybind11` submodule, so run
+  `git submodule update --init --recursive` on fresh clones
+- **CMake 3.21+** and a C++17 compiler (GCC 13+, Clang 18+, or MSVC 2022)
+- **DAL C++ staged install** — build core/public first; the canonical workflow is
+  in the [installation guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/installation.md#python-bindings)
+
+### Building the C++ Library
+
+The Python bindings depend on a compiled DAL C++ staging prefix. Build it first:
+
+```bash
+cd /path/to/Derivatives-Algorithms-Lib
+./build_linux.sh
+```
+
+This produces `build/stage/Release-linux/`, containing the installed core/public
+libraries, headers, and CMake package metadata.
+
+## Installation
+
+### Development Install (Recommended)
+
+Clone the repository and install in editable mode:
+
+```bash
+cd Derivatives-Algorithms-Lib/dal-python
+
+# Create a virtual environment with uv
+uv venv --python ">=3.9,<3.15"
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies and build the extension
+uv pip install -e ".[test]" "--config-settings=cmake.define.DAL_INSTALL_PREFIX=/absolute/path/to/Derivatives-Algorithms-Lib/build/stage/<platform-preset>"
+```
+
+Use an absolute staged-prefix path and replace `<platform-preset>` with the
+preset that built DAL, such as `Release-linux` or `Release-windows`. Standalone
+`dal-python` reads the installed CMake packages and automatically applies their
+configuration-aware MSVC runtime contract to `_dal`.
+
+### Workspace Build and Test
+
+To provision Python test dependencies and run the bindings through the workspace
+CTest integration:
+
+```bash
+bash ../build_linux.sh --full
+```
+
+The workspace script creates or reuses `dal-python/.venv`, builds the extension,
+and runs the configured C++/public/Python tests.
+
+### Selecting a CPython Version
+
+The local helpers accept an exact supported minor. On POSIX entry points use
+`--python`; on PowerShell entry points use `-Python`:
+
+```bash
+# From the repository root; --python also enables the Python bindings.
+bash ./build_linux.sh --python 3.9
+
+# From dal-python/.
+./build_sdist.sh --python 3.9
+./build_wheel.sh --python 3.9
+./run_tests.sh --python 3.9
+```
+
+```powershell
+# From dal-python/.
+.\build_wheel.ps1 -Python 3.9
+.\run_tests.ps1 -Python 3.9
+```
+
+The accepted values are 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14. When the selector is
+omitted, the helpers resolve a CPython in `>=3.9,<3.15`. A reused `.venv` must
+already use the selected CPython minor; mismatches fail without replacing the
+environment.
+
+## Building Distribution Packages
+
+For production deployment, you can build pre-compiled binary wheels or source distributions.
+Official PyPI releases contain precompiled wheels only.
+
+### Building a Binary Wheel
+
+Binary wheels contain the compiled C++ extension and can be installed without requiring compilation:
+
+```bash
+DAL_INSTALL_PREFIX=/absolute/path/to/build/stage/Release-linux ./build_wheel.sh
+DAL_INSTALL_PREFIX=/absolute/path/to/build/stage/Release-linux ./build_wheel.sh --python 3.9
+DAL_INSTALL_PREFIX=/absolute/path/to/build/stage/Release-linux ./build_wheel.sh --clean
+```
+
+The platform- and interpreter-tagged wheel is created under `dist/`.
+
+Install the wheel:
+```bash
+uv pip install dist/dal_python-*.whl
+```
+
+**Note:** Binary wheels are platform-specific. DAL keeps native-CPU tuning off by
+default so distributable builds use the compiler's portable baseline. Do not set
+`DAL_ENABLE_NATIVE_ARCH=ON` for a wheel that must run on unknown machines.
+
+### Building a Source Distribution
+
+Source distributions allow users to build from source on any platform:
+
+```bash
+./build_sdist.sh         # Build source distribution
+./build_sdist.sh --python 3.9 # Select an exact supported CPython
+./build_sdist.sh --clean # Clean build artifacts before building
+```
+
+The source archive is created under `dist/`.
+
+Install from source (requires C++ build tools):
+```bash
+pip install dist/dal_python-2026.9.25.tar.gz \
+  "--config-settings=cmake.define.DAL_INSTALL_PREFIX=/absolute/path/to/Derivatives-Algorithms-Lib/build/stage/<platform-preset>"
+# or
+uv pip install dist/dal_python-2026.9.25.tar.gz \
+  "--config-settings=cmake.define.DAL_INSTALL_PREFIX=/absolute/path/to/Derivatives-Algorithms-Lib/build/stage/<platform-preset>"
+```
+
+**Requirements for building from source:**
+- C++17 compiler (GCC 13+, Clang 18+, or MSVC 2022)
+- CMake 3.21+
+- pybind11 3.1.0 (declared as an isolated build requirement and installed
+  automatically; Python 3.14 builds require pybind11 3.0 or newer)
+- CPython 3.9-3.14 development headers
+- DAL staged install containing the `dal-public`/`dal-cpp` CMake packages and
+  platform libraries
+
+## PyPI Binary Release
+
+Release tags build and test this wheel matrix:
+
+| Operating system | Architecture | Wheel platform tag      | CPython versions |
+|------------------|--------------|-------------------------|------------------|
+| Linux            | x86-64       | `manylinux_2_28_x86_64` | 3.9-3.14         |
+| Windows          | x86-64       | `win_amd64`             | 3.9-3.14         |
+| macOS 14+        | x86-64       | `macosx_*_x86_64`      | 3.9-3.14         |
+| macOS 14+        | Apple Silicon | `macosx_*_arm64`      | 3.9-3.14         |
+
+Every release artifact is a CPython-specific native wheel. Python/ABI tags run
+from `cp39-cp39` through `cp314-cp314`; DAL does not publish `abi3` or universal
+wheels. An annotated `dal-python-v<version>` tag on the current `master` commit
+builds all six supported interpreters on four platform/architecture targets, for 24 wheels.
+After each wheel is built, cibuildwheel runs the installed-wheel Python unit
+suite. The separate Python wheel CI runs on path-matched pull requests: it
+builds `cp39` and `cp314` on all four targets (eight wheels), runs the same unit
+suite, and smoke-tests the installed `cp39` wheels. Pull requests and manual
+dispatches do not run the release workflow.
+
+Linux filenames always include `manylinux_2_28_x86_64` and may also contain
+unique compatible PEP 600 x86-64 components for glibc baselines no newer than
+2.28. Mixed platform families, other architectures, raw Linux, legacy manylinux,
+and musllinux tags are rejected. macOS wheels use one native architecture tag;
+mixed or universal2 tags are rejected. Linux ARM, PyPy, free-threaded CPython,
+and source distributions are outside the current PyPI release contract.
+
+Before building, the workflow checks that the annotated tag points to the
+current `master` commit and that the version is unused on PyPI. Before upload,
+the publish job rechecks the tag target, PyPI version, complete wheel matrix,
+and package metadata. It uploads the same downloaded wheel files that passed
+those checks. The toolchain is pinned (full action SHAs,
+exact build dependency versions, named manylinux/runner images), but
+byte-for-byte reproducibility across independent rebuilds is not currently
+enforced.
+
+### One-time PyPI setup
+
+Configure a Trusted Publisher on the existing `dal-python` PyPI project with:
+
+| Field              | Value                        |
+|--------------------|------------------------------|
+| PyPI project       | `dal-python`                 |
+| GitHub owner       | `wegamekinglc`               |
+| GitHub repository  | `Derivatives-Algorithms-Lib` |
+| Workflow filename  | `dal-python-release.yml`     |
+| GitHub environment | `pypi`                       |
+
+Create the matching `pypi` environment in the GitHub repository and require a
+manual deployment approval if the repository plan supports it. The workflow uses
+OIDC short-lived credentials; do not add a long-lived PyPI API token.
+
+### Release procedure
+
+1. Choose a new PEP 440 version that does not exist on PyPI. Update both
+   `pyproject.toml` and `src/dal/__init__.py`.
+2. Review and merge the version and release-note changes to `master` after the
+   normal pull-request checks pass.
+3. Tag that reviewed `master` commit and push only the tag:
+
+   ```bash
+   git tag -a dal-python-v<version> -m "Release dal-python <version>"
+   git push origin dal-python-v<version>
+   ```
+
+4. The tag run builds and unit-tests every wheel, validates the complete wheel
+   set and unused PyPI version, then publishes those wheel files through the
+   `pypi` environment. Confirm that PyPI lists all 24 wheels.
+
+PyPI versions and files are immutable. Never use a skip-existing option to repair
+an incomplete release; correct the issue, increment the version, and run the full
+process again. Local `build_wheel.*` scripts are for diagnostics and private
+deployment only; their output is not a PyPI release artifact.
+
+## Usage
+
+### Basic Pricing Example
+
+```python
+import dal
+
+# Set evaluation date
+dal.EvaluationDate_Set(dal.Date_(2022, 9, 25))
+
+# Define model parameters
+spot, vol, rate, div = 100.0, 0.2, 0.05, 0.02
+model = dal.BSModelData_New(spot=spot, vol=vol, rate=rate, div=div)
+
+# Define a European call option
+strike = 100.0
+maturity = dal.Date_(2023, 9, 25)
+product = dal.Product_New(
+    ["STRIKE", dal.Cell_(maturity)],
+    [str(strike), "call pays MAX(spot() - STRIKE, 0.0)"]
+)
+
+# Price using Monte Carlo (65,536 paths, Sobol sequences)
+result = dal.MonteCarlo_Value(product, model, 2**16, "sobol")
+print(f"Call PV: {result['PV']:.4f}")
+# Output: Call PV: 9.2259
+```
+
+### Computing AAD Greeks
+
+Enable AAD to compute pathwise sensitivities in a single simulation:
+
+```python
+result = dal.MonteCarlo_Value(
+    product, model,
+    2**14,        # num_paths
+    "sobol",      # method
+    False,        # use_bb
+    True          # enable_aad
+)
+
+print(f"PV: {result['PV']:.6f}")
+for key in sorted(result.keys()):
+    if key.startswith('d_'):
+        print(f"  {key}: {result[key]:.6f}")
+```
+
+Output:
+```
+PV: 9.223019
+  d_STRIKE: -0.494542
+  d_div: -58.677195
+  d_rate: 49.454176
+  d_spot: 0.586772
+  d_vol: 37.873346
+```
+
+### Historical and Future FIX
+
+The complete [FIX settings example](examples/012.fix_settings.py) constructs a
+zero-volatility Black-Scholes model, an explicit valuation date and a midnight
+history snapshot. Run it from the repository root with the current `dal` package:
+
+```bash
+python dal-python/examples/012.fix_settings.py
+```
+
+Its script first assigns `x = SCALE * FIX(EQ[DAL196_TEST])` on 2026-09-11,
+then pays `x + FIX(EQ[DAL196_TEST], 2026-09-15)` on 2026-09-22. With valuation
+date 2026-09-12, SCALE 2, history 80, model spot 100 and zero rates, the result
+is `PV=260` and `d_SCALE=80`. The example checks both numbers, the result keys,
+and both diagnostic schemas, including under optimized Python.
+
+The index inside `FIX(index[,date])` is unquoted script syntax; the containing
+Python string still uses quotes. The optional date is a literal `YYYY-MM-DD`;
+omitting it uses the event date. With valuation date `D`, event date `E`, and
+fixing date `F`:
+
+- `F < D` requires exact history; a missing fixing raises `MissingFixing`.
+- `F = D` uses the model by default; `RequireHistorical` requires today's history.
+- `F > D` uses the model, regardless of future values in the snapshot.
+- `F > E` raises `LookAheadObservation`, including in an unused branch.
+
+Wholly expired products still validate syntax, dates and settings, but skip
+history reads and return zero. Empty or no-PAYS products fail valuation.
+
+Historical EQ/FX observations can coexist. A model-sourced FIX, including today
+under `Model`, is always bound to the script's own future FIX index by name; the
+`model_bindings` settings argument was removed. Two or more distinct future FIX
+indices fail with `MultipleModelIndices`. Future FX, IR, composite, and
+delivery-suffixed EQ remain unsupported. `default_index` gives legacy `SPOT()`
+an identity; it does not affect the model binding. Unbound future-only `SPOT()`
+remains supported. Historical SPOT requires a default, and mixing SPOT with FIX
+requires one too. `SPOT(index)` and `FIX()` are invalid.
+
+Snapshot keys are native `DateTime_` values. Use `dal.DateTime_(date, 0)` for
+midnight; a quote at 11:00 cannot satisfy a daily FIX. Python `datetime` objects
+are not automatically converted. Snapshot construction copies the nested input
+dictionary, and the resulting native handle is immutable.
+
+`fixings=None` captures required global history afresh on each call.
+`dal.MarketFixingSnapshot_New({})` is an explicit empty snapshot: missing history
+fails even if the global store contains it. Global capture copies sequences
+one by one and is not an atomic snapshot across sequences; exclude concurrent
+fixing writes during capture. Reusing an explicit snapshot can retain history
+80 after global history changes to 90. It fixes historical input only; every
+Value or Explain prepares again with its current date and model inputs, without
+caching future prices.
+
+### Working with Dates
+
+```python
+import dal
+
+# Create dates
+d = dal.Date_(2022, 9, 25)
+print(d)  # 2022-09-25
+
+# Date arithmetic
+d2 = d.AddDays(30)
+print(f"Year: {dal.Year(d)}, Month: {dal.Month(d)}, Day: {dal.Day(d)}")
+
+# Date comparisons
+d3 = dal.Date_(2022, 10, 25)
+print(d < d3)  # True
+```
+
+### Random Number Generation
+
+```python
+# Pseudo-random generator (MRG32k32a algorithm)
+pseudo = dal.PseudoRSG_New(42, 3)  # seed=42, ndim=3
+uniform_samples = dal.PseudoRSG_Get_Uniform(pseudo, 1000)  # Returns DoubleMatrix_
+normal_samples = dal.PseudoRSG_Get_Normal(pseudo, 1000)
+
+# Sobol quasi-random sequences (better convergence for MC)
+sobol = dal.SobolRSG_New(0, 3)  # i_path=0, ndim=3
+sobol_samples = dal.SobolRSG_Get_Uniform(sobol, 1000)
+precise_sobol = dal.SobolRSG_New(
+    0, 3, precise=True, polish=True
+)  # opt in to the precise-CDF Newton correction
+```
+
+### Dupire Local Volatility Model
+
+```python
+# Define a local volatility surface with flat 20% vol
+spots = [80.0, 90.0, 100.0, 110.0, 120.0]
+times = [0.5, 1.0, 2.0]
+vols = dal.DoubleMatrix_(len(spots), len(times), 0.2)  # Fill with 20% vol
+
+dupire_model = dal.DupireModelData_New(
+    spot=100.0,
+    rate=0.05,
+    repo=0.01,
+    spots=spots,
+    times=times,
+    vols=vols
+)
+```
+
+`DoubleMatrix_` also accepts rectangular nested sequences and supports mutable
+`matrix[i, j]` access, so non-flat surfaces can be populated directly.
+
+## API Reference
+
+### Core Types
+
+- `dal.Date_(year, month, day)` — Date object with arithmetic operations
+- `dal.String_(value)` — String wrapper
+- `dal.Cell_(value)` — Polymorphic value container (bool, double, Date, String)
+- `dal.DoubleVector()` — Vector of doubles
+- `dal.DoubleMatrix_(rows, cols, fill=0.0)` or `dal.DoubleMatrix_(nested_rows)` — mutable 2D matrix of doubles
+
+### Models
+
+- `dal.BSModelData_New(spot, vol, rate, div)` — Black-Scholes model
+- `dal.DupireModelData_New(spot, rate, repo, spots, times, vols)` — Dupire local vol model
+
+### Products
+
+- `dal.Product_New(events_dates, events, *, settings=None)` — Create a script product; `settings` is a `ScriptProductSettings_` or `None`
+- `dal.Product_Describe(product)` — Return a contract dictionary with schema `dal.script-product/2`
+- `dal.Product_Debug(product)` — Return the legacy human-readable product structure as a string
+- `dal.Product_DebugJson(product)` — Legacy JSON string (schema `dal.script-product/1`); rejects FIX and nonempty defaults with `DebugSchemaUnsupported`
+- `dal.Product_DebugTree(product, ascii=False, width=125)` — Width-aware Unicode (or ASCII) product tree
+
+### Valuation
+
+- `dal.MonteCarlo_Value(product, modelData, num_path, method="sobol", use_bb=False, enable_aad=False, smooth=0.01, compiled=None)` — Monte Carlo pricing with optional AAD Greeks
+- `dal.MonteCarlo_ValueWithSettings(product, modelData, num_path, *, valuation=None, simulation=None)` — Price with `ScriptValuationSettings_` and `MonteCarloSettings_`
+- `dal.ScriptValuation_Explain(product, modelData, *, valuation=None)` — Return a dictionary describing one default price preparation
+- `dal.ScriptSimulation_Explain(product, modelData, num_path, *, valuation=None, simulation=None)` — Run the full double valuation and return the `dal.script-simulation/1` exercise diagnostics dictionary
+
+**Parameters:**
+- `product` — Script product (from `Product_New`)
+- `modelData` — Model data (from `BSModelData_New` or `DupireModelData_New`)
+- `num_path` — Integer or valid `__index__` value in `1..2147483647`, excluding booleans and enums; floats such as `1.0` are rejected in both Value entries
+- `method` — Random generator: `"sobol"` (default), `"mrg32"`, or `"irn"`
+- `use_bb` — Use Brownian bridge construction (default `False`)
+- `enable_aad` — Enable AAD for pathwise Greeks (default `False`)
+- `smooth` — Finite, strictly positive fuzzy smoothing width (default `0.01`), validated even without AAD
+- `compiled` — `True` selects the compiled evaluator; `None`/`False` uses tree-walk
+
+**Returns:** Dictionary with keys:
+- `"PV"` — Present value
+- `"d_spot"`, `"d_vol"`, `"d_rate"`, `"d_div"` — Black-Scholes model AAD Greeks (only if `enable_aad=True`)
+- `"d_<name>"` — AAD sensitivity to a named product constant, such as `"d_STRIKE"`
+  when the product declares a `STRIKE` constant
+
+Both Value entries return `dict[str, float]` containing only `PV` and optional
+`d_` parameter risks. PV is a path mean and risks are already normalized;
+neither should be divided by the path count again. Historical fixing values
+carry no fixing-risk keys. AAD preserves historical parameter dependencies,
+uses hard historical decisions, and smooths future comparisons. Its PV can
+differ from exact non-AAD pricing near a future discontinuity; `compiled` only
+selects the evaluator implementation.
+
+### Script Settings and Copies
+
+The constructor signatures are below (`*` makes every field keyword-only).
+Default construction followed by assignment to the same snake_case properties
+is also supported.
+
+```text
+ScriptProductSettings_(*, default_index="")
+ScriptValuationSettings_(*, evaluation_date=None, today_fixing="Model",
+                         fixings=None)
+MonteCarloSettings_(*, method="sobol", use_bb=False, enable_aad=False,
+                   smooth=0.01, compiled=None, lsmc_basis_degree=3,
+                   lsmc_training_paths=None)
+```
+
+| Field                  | Accepted input / default                                                                                     | Property result                     |
+|------------------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------|
+| `default_index`        | `str` or `String_`; empty means unbound                                                                      | `str`, preserving spelling          |
+| `evaluation_date`      | Valid DAL `Date_`, or `None` to capture global date at each call                                             | A date copy or `None`               |
+| `today_fixing`         | Policy enum or exact `Model` / `RequireHistorical` string; default `Model`                                   | `TodayFixingPolicy_` member         |
+| `fixings`              | `MarketFixingSnapshot_`, or `None` for global capture                                                        | Immutable snapshot handle or `None` |
+| `method`               | `str` / `String_`: `sobol`, `mrg32`, `irn` (case-insensitive); default `sobol`                               | `str`, preserving spelling          |
+| `use_bb`, `enable_aad` | Python `bool` only; default `False`                                                                          | `bool`                              |
+| `smooth`               | Finite positive Python `int` / `float`, excluding bool and enums; default `0.01`                             | `float`                             |
+| `compiled`             | Python `bool` or `None`; default `None` selects tree                                                         | `bool` or `None`                    |
+| `lsmc_basis_degree`    | Integer or valid `__index__` in `1..8`, excluding bool, enums, floats; default `3`                           | `int`                               |
+| `lsmc_training_paths`  | Positive integer or valid `__index__` up to `2**31-1`, excluding bool, enums, floats; `None` uses `num_path` | `int` or `None`                     |
+
+For exercise products, training and pricing counts can be set independently:
+
+```python
+simulation = dal.MonteCarloSettings_(lsmc_training_paths=16_384)
+result = dal.MonteCarlo_ValueWithSettings(
+    product, model, 262_144, simulation=simulation
+)
+```
+
+This fits the exercise policy on 16,384 paths and values it on the next 262,144
+paths. Fixing `lsmc_training_paths` keeps the fitted policy unchanged when
+`num_path` changes. The setting has no effect on products without `EXERCISE`.
+
+The policy enum members are `dal.TodayFixingPolicy_.MODEL` and
+`dal.TodayFixingPolicy_.REQUIREHISTORICAL`. Policy strings also accept DAL
+`String_`, but must match the exact spelling and case with no extra whitespace.
+Unknown names list the two allowed policies. `evaluation_date` does not accept
+date strings, numeric serials, Python `datetime`, `DateTime_`, or `Cell_`.
+An explicit date neither reads nor changes the global date.
+
+For `default_index`, `method`, and the string form of `today_fixing`, ordinary
+`str` subclasses and DAL `String_` are accepted. Python enum values, including
+`str, enum.Enum` and `enum.StrEnum` members, raise `TypeError` in constructors
+and setters; the native `TodayFixingPolicy_` members above remain valid policies.
+Event text accepts string-derived enum members under its usual text validation
+rules.
+
+Settings parameters accept their corresponding native settings object or `None`
+(fresh defaults), not an entire settings dictionary.
+
+`copy.copy` and `copy.deepcopy` create independent settings values; both share
+the immutable snapshot handle. Ordinary Python assignment aliases the object.
+Changing a returned date copy does not update settings: assign the property to
+replace it. Failed setters preserve the old value. Product construction copies the table and settings; Value and Explain
+copy settings and native handles while holding the GIL, then release it for
+native work. Workers use native data and never call Python callbacks or read
+mutable Python dictionaries. Avoid modifying inputs during their conversion.
+Native valuations still serialize through DAL's valuation/mutation barrier.
+
+### Script Compatibility and Errors
+
+The high-level product keyword remains `events_dates`; the low-level
+`dal._dal.Product_New` keyword is `dates` and its date-table elements must
+already be `Cell_`. The high-level wrapper preserves existing cells and wraps
+only non-Cell values. Use DAL dates for event rows and strings for definitions
+or schedules; numeric cells do not gain an Excel-date interpretation.
+Event text accepts `str` or `String_`. Text with embedded NUL is rejected.
+
+Legacy `MonteCarlo_Value` retains all valid three-to-eight positional calls
+and the original keywords/defaults. Its valid flag and float conversions are
+preserved. New settings cannot be mixed into that call; flat `method`,
+`compiled`, and other simulation options belong inside `MonteCarloSettings_`
+when using `MonteCarlo_ValueWithSettings`.
+
+Unknown/duplicate keywords, extra positional arguments, wrong settings types,
+and invalid input types raise `TypeError`; unknown settings attributes raise
+`AttributeError`. Invalid values and native failures raise `RuntimeError`, with
+identifiers such as `InvalidPathCount`, `InvalidSetting`, `InvalidSmoothing`,
+`InvalidTodayFixingPolicy`, `InvalidFixingDate`, `MissingFixing`,
+`InvalidLsmcBasisDegree`, and
+`MultipleModelIndices`, plus field
+and constraint context. Script errors retain source row/position and index/date
+details. Validation may occur at construction/assignment (types, policy, date,
+smoothing), description (syntax/default index), or preparation (history).
+Empty or no-PAYS products can be described but Value/Explain reject them with
+`InvalidScriptStructure`. Valid wholly expired products return zero only after
+validation; errors never become successful `PV=0` results.
+
+### Script Diagnostics
+
+High-level `dal.Product_Describe` and `dal.ScriptValuation_Explain` return ordinary
+dictionaries. Their low-level counterparts in `dal._dal` (also re-exported by
+`dal.dal`) return the C++ JSON as `str`; the high-level wrappers apply `json.loads`
+without renaming keys or converting date strings into DAL dates.
+`dal.ScriptSimulation_Explain(product, modelData, num_path, *, valuation=None,
+simulation=None)` follows the same split and returns the `dal.script-simulation/1`
+dictionary. Unlike the valuation Explain it runs the full double valuation with
+`num_path` pricing paths plus a separate block of `lsmc_training_paths`
+training paths (defaulting to `num_path`)
+(path generation plus workers plus the exercise regressions),
+requires the same integer path count as the Value entries, rejects
+`enable_aad=True` settings with `UnsupportedExecutionMode`, and reports the
+simulation echo with `lsmc_basis_degree` and `lsmc_training_paths` (null when
+unset), the explicit pricing count `n_paths`, and one
+`exercise_events` entry per exercise date (degree, regressor index,
+in-the-money condition-true count, coefficients, degenerate flag/reason,
+exercise rate).
+Regression counts describe the training block; exercise rates describe the
+pricing block. Both blocks use deterministic Sobol points and do not overlap.
+Products without `EXERCISE` return an empty `exercise_events` list. The
+[early-exercise example](examples/013.exercise_bermudan.py) prices the
+Bermudan and weekly-exercise puts and reads the diagnostic. The example runs
+3 x 2^18-path LSMC valuations by default; set `DAL_EXAMPLE_NPATHS` to a
+smaller path count for a quicker smoke run.
+
+- **Describe**, schema `dal.script-product/2`, parses all contract syntax with
+  original/canonical identities, input rows, events, source positions and nodes.
+  It has no market I/O, model, global-date read or valuation phase. Success does
+  not establish that the product can be priced.
+- **Explain**, schema `dal.script-valuation/1`, prepares independently on every
+  call. It may read history, initialize a model and replay past state, but starts
+  no workers and generates no paths. Its fixed simulation is exact non-AAD,
+  Sobol, no bridge, smoothing `0.01`, tree. It accepts no path count or simulation
+  settings and does not describe a preceding compiled/AAD call or cache the next
+  Value. Its requests/uses, history IDs, model slots, live-event/sample mappings
+  and numeraire requests come from that preparation.
+
+JSON null/bool/array/object values become Python None/bool/list/dict. Date strings,
+policy/source names, and schema versions retain the
+[C++ diagnostic contract](../docs/methodology/script_engine.md#product-archive-and-diagnostics).
+`request_id` and `history_value_id` address different arrays; use `live_events`
+to map all-event IDs to future-event indices. Diagnostics are not loadable
+product archives. Python provides no public script-product serializer or pickle
+API; `Product_DebugJson` remains the separate legacy JSON-string interface.
+
+### Random Generators
+
+- `dal.PseudoRSG_New(seed, ndim=1)` — Pseudo-random generator (MRG32k32a)
+- `dal.SobolRSG_New(i_path, ndim=1, precise=False, polish=False)` — Sobol
+  quasi-random generator; `polish` enables the Newton correction and `precise`
+  selects its CDF, so the precise-CDF correction requires both flags to be `True`
+- `dal.PseudoRSG_Get_Uniform(rsg, num_paths)` — Uniform samples [0, 1]
+- `dal.PseudoRSG_Get_Normal(rsg, num_paths)` — Standard normal samples
+- `dal.SobolRSG_Get_Uniform(rsg, num_paths)` — Sobol uniform samples
+- `dal.SobolRSG_Get_Normal(rsg, num_paths)` — Sobol normal samples
+
+### Global State
+
+- `dal.EvaluationDate_Set(date)` — Set the process-wide evaluation date; waits
+  for an in-progress native valuation or scoped override
+- `dal.EvaluationDate_Get()` — Read the stable process-wide evaluation date;
+  remains available while valuation runs
+
+Both bindings release the GIL before entering native synchronization.
+
+## Testing
+
+Build and run the full workspace suite:
+
+```bash
+bash ../build_linux.sh --full
+```
+
+After an editable install, run focused Python tests directly:
+
+```bash
+python -m pytest tests -k "test_date" -v
+```
+
+Tests are located in `tests/` and cover:
+
+- Date arithmetic and comparisons
+- Vector and matrix operations
+- Model construction (BS, Dupire)
+- Monte Carlo pricing accuracy vs Black-Scholes analytical formulas
+- AAD Greek computation and validation
+- Random number generator properties
+- Curve construction plus single and staged multi-curve calibration
+- Rate cashflow planning, pricing, and node sensitivities
+- Staged XCCY basis calibration, sensitivity matrices, axes, and availability metadata
+- Resettable/MTM XCCY construction with immutable fixing snapshots
+- Joint domestic/foreign/basis XCCY calibration, including matrix and named-range contracts
+
+## Performance Benchmarks
+
+The [Python benchmark suite](benchmarks/README.md) provides 90 public-interface
+workloads mapped to the C++ benchmark inventory: RNG, script construction and MC,
+single/multi-curve and XCCY calibration, node risk, and quote-risk provenance/aggregation.
+It records raw samples, workload sizes, native-module identity, and a Markdown summary.
+
+From `dal-python/`, using a current installed wheel or editable build:
+
+```bash
+python benchmarks/run_benchmarks.py --smoke
+python benchmarks/run_benchmarks.py --samples 10 --warmups 2
+python benchmarks/run_benchmarks.py --group rate_risk_perf --filter generic
+```
+
+The normal pytest suite checks every workload at smoke scale without a speed
+threshold. Linux CI also gates all 90 full-scale cases against independent base/head
+builds, using two rounds of ten interleaved processes and a strict 4% threshold in
+both rounds. The coverage map explicitly records unbound C++ kernels and fixture
+differences; Python timings include binding and result-conversion costs.
+
+The Linux gate also checks 31 comparison workloads against DAL,
+QuantLib-Python and rateslib with independent numerical oracles. Its report covers
+discount queries, IRS PV and DV01, Monte Carlo vanilla/barrier prices and
+Delta/Vega/Rho, plus single, staged/joint multi-curve and XCCY calibration.
+Rateslib equity MC and QuantLib simultaneous joint calibration are explicitly
+unsupported; every other case must complete successfully.
+Node risk uses DAL reverse AAD, rateslib forward AD and QuantLib finite differences,
+with each algorithm identified in the evidence. Third-party dependencies are pinned
+separately for benchmarks; they are not DAL runtime dependencies. See the
+[comparison methodology and commands](benchmarks/README.md#third-party-comparison).
+
+## Project Structure
+
+```
+dal-python/
+├── CMakeLists.txt          # Build configuration
+├── pyproject.toml          # Python package metadata (scikit-build-core)
+├── build_sdist.sh          # Source distribution helper
+├── build_wheel.sh          # Wheel build helpers (POSIX and PowerShell)
+├── build_wheel.ps1
+├── run_tests.sh            # Standalone binding test helpers (POSIX and PowerShell)
+├── run_tests.ps1
+├── examples/               # Numbered end-to-end Python examples
+├── benchmarks/             # Public-interface performance runner and C++ coverage map
+├── scripts/                # Release verification and installed-wheel smoke helpers
+├── src/
+│   ├── bindings/
+│   │   ├── module.cpp        # pybind11 module definition
+│   │   ├── bindings.h        # shared binding helpers
+│   │   ├── core.cpp          # core types (Date_, String_, Cell_, vectors, DoubleMatrix_)
+│   │   ├── global.cpp         # Handle_<T> opaque types, EvaluationDate_Get/Set
+│   │   ├── models.cpp         # model types (BSModelData_, etc.)
+│   │   ├── random.cpp          # random number generators
+│   │   ├── script.cpp          # scripting engine bindings
+│   │   ├── calendar.cpp        # holiday calendars and business-day conventions
+│   │   ├── curve.cpp           # curve calibration, instruments, and interpolation
+│   │   └── value.cpp           # Monte Carlo valuation (MonteCarlo_Value)
+│   └── dal/
+│       ├── __init__.py     # Package initialization
+│       └── api.py          # High-level Python API wrappers
+├── tests/
+│   ├── conftest.py        # Pytest fixtures
+│   └── test_*.py          # Test modules
+```
+
+## Architecture
+
+The Python bindings are generated by pybind11 from domain-organized binding files. The build process:
+
+1. **CMake** configures the build and locates the DAL C++ libraries plus either
+   the isolated pybind11 build requirement or the pinned repository fallback
+2. **C++ compiler** builds `_dal.cpython-*.so` extension module from the domain-organized `src/bindings/*.cpp` files
+3. **scikit-build-core** packages everything into an installable wheel
+
+When consuming an installed DAL package under MSVC, CMake applies the package's
+`DAL_CPP_MSVC_RUNTIME_LIBRARY` value to `_dal` through
+`dal_cpp_apply_msvc_runtime`. The helper is a no-op on other toolchains.
+
+The hand-written Python code in `src/dal/` provides:
+- `__init__.py` — Re-exports all pybind11-generated symbols
+- `api.py` — Convenience wrappers (e.g., `Product_New` with automatic type conversion, `calibrate_curve(...)` for curve calibration)
+
+## Curve Calibration
+
+The `curve` bindings (`dal-python/src/bindings/curve.cpp`) expose the supported Python
+curve-construction and calibration workflows:
+
+- **Instrument builders** — `Deposit_New`, `FRA_New`, `Future_New`, `Swap_New`, `OISSwap_New`, `BasisSwap_New`, `CrossCurrencySwap_New`
+- **Curve factories** — `DiscountPWLF_New`, `DiscountZeroRate_New`
+- **Calibration entry points** — `CalibrateSingleCurve`, `CalibrateMultiCurveBundle`, `CalibrateXccyMarket`, `CalibrateJointXccyMarket`
+- **Enums** — `CurveParameterization` (`PIECEWISE_LINEAR_FWD`, `PIECEWISE_CONSTANT_FWD`, `ZERO_RATE`, `LOG_DISCOUNT`), `CurveSolveMode` (`EXACT`, `APPROXIMATE`), `CurveJacobianMode` (`ANALYTIC`, `BUMPED`), `LogDfScheme` (`LOG_LINEAR`, `LOG_CUBIC_NATURAL`, `MIXED`), `XccyNotionalMode` (`FIXED`, `RESETTABLE`, `MARK_TO_MARKET`)
+- **Spec builders** — `CurveCalibrationSpecBuilder_`, `CrossCurrencyCalibrationSpecBuilder_`, and `JointXccyCalibrationSpecBuilder_`
+
+The `dal.calibrate_curve(...)` helper in `api.py` wraps the common single-curve path with Python-friendly defaults. The underlying C++ methodology is documented in the [yield-curve guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/methodology/yield_curve.md) and [Jacobian guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/methodology/yield_curve_jacobian.md).
+
+### Continuously Compounded Zero-Rate Curves
+
+Build a persistent zero-rate curve directly with future-only nodes:
+
+```python
+today = dal.Date_(2026, 1, 2)
+node_dates = [dal.Date_(2027, 1, 2), dal.Date_(2028, 1, 2)]
+
+curve = dal.DiscountZeroRate_New(
+    "usd_zero",
+    "USD",
+    today,
+    node_dates,
+    [0.02, 0.025],
+    day_count=dal.DayBasis_("ACT_365F"),
+    log_df_scheme=dal.LogDfScheme.LOG_LINEAR,
+)
+```
+
+Each continuously compounded decimal rate $z_i$ is mapped to
+`logDF_i = -z_i * YearFrac(today, node_date_i)`. The anchor log DF is fixed at zero
+and has no zero-rate parameter. `LOG_LINEAR`, `LOG_CUBIC_NATURAL`, and `MIXED` all
+interpolate the mapped log DFs. Before the anchor, `LOG_LINEAR` and `MIXED` clamp the
+log DF to zero, while `LOG_CUBIC_NATURAL` extends its first cubic segment. Beyond the
+last node, every scheme uses the last two mapped log-DF nodes as a secant. The returned
+`DiscountZeroRate_` exposes read-only `anchor_date`, `node_dates`, `zero_rates`,
+`day_count`, and `log_df_scheme` properties.
+
+For calibration, select `CurveParameterization.ZERO_RATE` and supply strictly-future
+knots. `initialGuess_` is a decimal continuously compounded zero rate copied to every
+node. Both low-level `CalibrateSingleCurve` and the convenience helper use the analytic
+AAD Jacobian when the normal single-discount-curve eligibility gates are met:
+
+```python
+result = dal.calibrate_curve(
+    today,
+    "USD",
+    instruments,
+    node_dates,
+    settings={
+        "parameterization": dal.CurveParameterization.ZERO_RATE,
+        "log_df_scheme": dal.LogDfScheme.LOG_CUBIC_NATURAL,
+        "initial_guess": 0.02,
+    },
+    jacobian_mode=dal.CurveJacobianMode.ANALYTIC,
+    base_curve=base_curve,  # optional: zero rates are spread coordinates over this base
+)
+```
+
+Python exposes single, staged multi-curve, staged XCCY basis, and simultaneous
+joint XCCY calibration. A base curve is multiplied into the calibrated component;
+it is not a replacement for the pricing discount curve required by a forward-curve stage.
+Staged XCCY supports both the backward-compatible
+`CalibrateXccyMarket(spec)` call and `CalibrateXccyMarket(spec, options)`.
+`CrossCurrencyCalibrationOptions_` defaults to `ANALYTIC` with
+`compute_forward_jacobian = True` and
+`compute_eff_jacobian_inverse = True`; trailing-underscore property names are
+available alongside the snake-case names.
+
+The matrices remain on `result.diagnostics`. `diagnostics.jacobian` has
+instrument rows and basis-parameter columns;
+`diagnostics.eff_jacobian_inverse` has the reversed axes.
+`instrument_names` follows input order and may contain duplicate labels.
+`parameter_knot_dates` follows the spec's knot order and labels the
+piecewise-constant basis curve's right-forward parameters. The diagnostics also
+publish `residual_tolerance`, `jacobian_scaling == "unscaled"`,
+`eff_jacobian_inverse_scaling == "solver_scaled"`, and independent
+`jacobian_availability` / `eff_jacobian_inverse_availability` values:
+`available`, `not_requested`, or `not_available_for_mode`.
+
+For a raw decimal quote-bump vector `dq`, the solver-scaled effective inverse
+`E` maps parameters as `dx = E * dq / residual_tolerance`. An unavailable
+matrix is empty; inspect its availability property to distinguish an explicit
+opt-out from a mode limitation.
+
+### Resettable and Joint XCCY Calibration
+
+Use `CrossCurrencySwapConfigBuilder_` to set the currency pair, notionals, leg
+conventions, `notional_mode`, `fx_reset`, and explicit `domestic_rate_fixing` /
+`foreign_rate_fixing` identities. `MarketFixingSnapshot_New` takes a nested
+dictionary whose keys are index names and whose values map `DateTime_` objects to
+observations. One immutable snapshot can hold domestic rate, foreign rate, and FX
+fixings for an already-started swap:
+
+```python
+snapshot = dal.MarketFixingSnapshot_New({
+    "USD-JOINT-3M": {historical_fixing: 0.040},
+    "EUR-JOINT-3M": {historical_fixing: 0.030},
+    "FX[EUR/USD]": {historical_fixing: 1.20},
+})
+```
+
+`JointCurrencyCurveSpec_` holds the ordered domestic or foreign
+`JointCurveDeclaration_` objects. `XccyBasisCurveDeclaration_` holds configured
+XCCY instruments and basis knots. Assemble those groups with
+`JointXccyCalibrationSpecBuilder_`, then call
+`CalibrateJointXccyMarket(builder.build())`. The result exposes the domestic and
+foreign curve blocks, `fx_forward_curve`, basis curve, retained snapshot, group
+diagnostics, full market/model/residual vectors, analytic Jacobian, effective
+inverse, and named `parameter_ranges` / `residual_ranges`. Pass
+`JointXccyCalibrationOptions_` to select `ANALYTIC` or `BUMPED` and to disable
+either diagnostic matrix. The `eff_jacobian_inverse` matrix has shape
+`totalParameters x totalResiduals` and is the weighted inverse of the solver's
+tolerance-scaled Jacobian. Transforming a raw decimal quote bump therefore
+requires division by the spec's `tolerance_`; see the
+[Jacobian methodology](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/methodology/yield_curve_jacobian.md#joint-xccy-jacobian-layout).
+
+The runnable [joint XCCY calibration example](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/dal-python/examples/007.xccy_joint_calibration.py)
+uses an explicit fixing snapshot for a started MTM trade. It prints convergence,
+the maximum absolute residual, Jacobian dimensions, named parameter and residual
+half-open ranges, and every FX-forward date and value. With the `dal` package
+installed in the active environment, run it from the repository root:
+
+```bash
+python dal-python/examples/007.xccy_joint_calibration.py
+```
+
+## Rate Cashflow Pricing and Node Risk
+
+Typed rate trades price and produce AAD node sensitivities against a
+component-keyed market. Every pricing and sensitivity function is keyword-only,
+returns read-only results, and releases the GIL around native work. A complete
+deposit example, mirroring the fixtures in `tests/test_curve_pricing.py`:
+
+```python
+import dal
+
+today, maturity = dal.Date_(2026, 1, 15), dal.Date_(2027, 1, 15)
+
+# 1) Curve and market: curves are registered by component key; trade terms
+#    address them through their *_component_key fields.
+curve = dal.DiscountPWC_New("usd", "USD", [maturity], [0.04])
+market = dal.RatePricingMarket_(
+    valuation_time=dal.DateTime_(today, 10, 30),
+    result_currency="USD",
+    curve_components={"discount": curve, "forecast": curve},
+    fixings=dal.MarketFixingSnapshot_New({}),
+)
+
+# 2) Index convention, terms, and trade
+index = dal.RateIndexConvention_New(
+    dal.PeriodLength_New("3M"), dal.DayBasis_New("ACT_365F"), dal.CollateralType_OIS())
+terms = dal.DepositTradeTerms_(
+    notional=100.0, contract_rate=0.05, lend=True,
+    index=index, discount_component_key="discount")
+trade = dal.RateTradeDefinition_(
+    instrument_id="deposit-1", instrument_type=dal.RateInstrumentType.DEPOSIT,
+    trade_date=today, start_date=today, maturity_date=maturity,
+    currency="USD", terms=terms)
+
+# 3) Single-trade sensitivity (a deposit depends only on the discount component,
+#    so a "forecast" request returns reason="TRADE_DOES_NOT_DEPEND_ON_COMPONENT")
+r = dal.RateTradeNodeSensitivities(trade=trade, market=market, component_key="discount")
+assert r.eligible and len(r.gradient) == 1 and r.reason == ""
+
+# 4) Batch: component_keys must be a list — a tuple raises TypeError before any
+#    native work starts. Deterministic trade-major then key order.
+cells = dal.RateTradeNodeSensitivitiesBatch(
+    trades=[trade], market=market, component_keys=["discount", "forecast"])
+for c in cells:
+    print(c.instrument_id, c.component_key, c.result.eligible, c.result.reason)
+
+# 5) Portfolio aggregation
+agg = dal.AggregateRatePortfolioNodeRisk(
+    trades=[trade], market=market, component_keys=["discount"])
+print(agg.policy)                    # UnconvertedByActualPvCcy
+comp = agg.components[0]             # .component_key / .node_count / .node_dates /
+                                     # .node_components / .values
+print(dict(agg.pv_by_actual_pv_ccy)) # {'USD': ...}
+print(agg.meta[0].reason, agg.meta[0].actual_pv_ccy)
+```
+
+Native per-trade pricing and sensitivity failures are returned as data. Invalid
+Python argument types or shapes can still raise before native execution.
+A trade that fails passive pricing — for example
+`notional=float("nan")` — keeps `PriceRateTrades` field-level detail in
+`result[0].error`, while every sensitivity call returns the canonical read-only
+four-field result: `eligible=False`, `pv=0.0`, `gradient=[]`, and a stable
+`reason` token (`"TRADE_VALIDATION_FAILED"` here). In a batch, failed entries
+are isolated per (trade, component) cell; the remaining entries are unaffected.
+
+All seven families — deposit, FRA, future, OIS, IRS, basis swap, and XCCY —
+share this call pattern and differ only in their terms class. The per-family
+terms fields, the addressable components, and the C++ and Excel equivalents are
+in the [public API guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/public-api.md#c-rate-cashflow-pricing).
+
+For repeated valuation, `PreparedRateTrades_New(trades=trades)` owns an immutable
+copy of the portfolio and prepares IRS/OIS/basis coupon geometry once. Pass the
+current market on every call:
+
+```python
+prepared = dal.PreparedRateTrades_New(trades=[trade])
+prices = dal.PreparedRateTrades_Get_Prices(prepared=prepared, market=market)
+cells = dal.PreparedRateTrades_Get_NodeSensitivities(
+    prepared=prepared, market=market, component_keys=["discount"])
+assert prepared.size == 1
+```
+
+The results and failure rules match the ordinary APIs. Market, fixing, PV and AAD
+values are recomputed; only trade geometry is retained. Create a new prepared
+object when trade terms or calendar definitions change. Concurrent calls may
+share a prepared object with independent immutable markets. The
+[prepared IRS example](examples/011.prepared_rate_pricing.py) changes market
+rates and checks every PV and node derivative against ordinary pricing.
+
+## Quote-Space DV01
+
+Freeze calibration provenance with
+`BuildSingleCurveQuoteRiskProvenance`,
+`BuildJointXccyQuoteRiskProvenance`,
+`BuildStagedXccyBasisQuoteRiskProvenance`, or
+`BuildJointMultiCurveQuoteRiskProvenance`, then call
+`AggregateRatePortfolioQuoteRisk(trades=..., market=..., provenances=...)`.
+All five functions are keyword-only, release the GIL around native work, and
+return read-only results.
+
+Each bucket contains its calibration/axis identity, ordered quote coordinate,
+actual PV currency, `d_pv_d_decimal_quote`, and `dv01`. The former is price per
+`+1.0` decimal quote move; `dv01` is price per `+1 bp` and therefore equals the
+former times `1e-4`. Axis/state schemes are
+`dal.quote-risk-axis/1+jcs+sha256` and
+`dal.quote-risk-state/1+jcs+sha256` for the three existing domains. Generic joint
+provenance uses the corresponding `/2+jcs+sha256` schemes; fingerprint values begin with `sha256:`.
+Aggregation verifies the current market state and performs neither quote bumps
+nor recalibration.
+
+The policy is `UnconvertedByActualPvCcy`: PV and quote-risk buckets remain
+separate by each trade's actual PV currency, without FX conversion. Ordinary
+staged multi-curve chain rules are not supported. `JointMultiCurveCalibrationSpec_`,
+`JointMultiCurveCalibrationOptions_`, and `CalibrateJointMultiCurveBundle`
+provide a reachable generic joint calibration with read-only results and owning
+curve maps. Its inverse request defaults to false; enabling it for an
+underdetermined EXACT system selects a fixed initial-Jacobian subspace and can
+change the selected solution. See the
+[generic joint example](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/dal-python/examples/010.generic_joint_quote_risk.py)
+and [mapping contract](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/methodology/generic_joint_quote_risk.md).
+The runnable
+[single-curve example](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/dal-python/examples/009.quote_risk.py)
+prints the policy, both fingerprints, and all buckets; the
+[joint XCCY example](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/dal-python/examples/007.xccy_joint_calibration.py)
+constructs joint provenance.
+
+## Troubleshooting
+
+### "Cannot find DAL::public" during build
+
+Ensure `DAL_INSTALL_PREFIX` points to the correct staged DAL installation:
+
+```text
+<stage>/lib/cmake/dal-public/dal-publicConfig.cmake
+<stage>/lib/cmake/dal-cpp/dal-cppConfig.cmake
+<stage>/include/dal/
+```
+
+The library files beside the package metadata use the platform's native suffix,
+such as `.a` on Linux or `.lib` on Windows; do not diagnose the prefix by
+assuming one suffix.
+
+### "ImportError: No module named _dal"
+
+The extension module failed to build. Check the build logs:
+
+```bash
+uv pip install --reinstall -e . -v "--config-settings=cmake.define.DAL_INSTALL_PREFIX=/absolute/path/to/build/stage/<platform-preset>"
+```
+
+Replace `<platform-preset>` with the stage produced by the active compiler and
+configuration.
+
+### Tests fail with "ModuleNotFoundError"
+
+Ensure you're using the virtual environment:
+
+```bash
+uv run --no-sync python -c "import dal; print(dal.__version__)"
+```
+
+## License
+
+MIT License. See the repository [LICENSE](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/LICENSE).
+
+## Contributing
+
+Follow the repository [contributor guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/CONTRIBUTING.md). Binding changes
+should include Python tests and updates to the
+[public API guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/public-api.md) when the supported surface changes.
+
+## See Also
+
+- [DAL C++ Library](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib) — Workspace overview
+- [Installation guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/installation.md) — Canonical setup commands
+- [Public API guide](https://github.com/wegamekinglc/Derivatives-Algorithms-Lib/blob/master/docs/public-api.md) — C++, Python, and Excel entry points
+- [pybind11 Documentation](https://pybind11.readthedocs.io/) — pybind11 binding syntax

dal_python-2026.9.25.dist-info/RECORD

@@ -0,0 +1,7 @@
+dal/__init__.py,sha256=iDfJa7nvriQpy_zYr2zcddleGkrIB9mQL9gHdF4-U68,342
+dal/_dal.cp314-win_amd64.pyd,sha256=IUdSsoJdXrd5-KG-woTHiBfI6ubTfTdrsz1hAUww91E,8000000
+dal/api.py,sha256=ruk1aFwsBvUja93HOLUCDtr7C4RZ1GvvWkZVqlDTSU0,5872
+dal/dal.py,sha256=b0-41lZPe9kLS9tlVBJJkYQEzp83e5PXxnrrJ8_23hc,89
+dal_python-2026.9.25.dist-info/METADATA,sha256=CHc3vqlb5OLettIWYAKIduRONshmAXo7hv-EQU0jofo,51900
+dal_python-2026.9.25.dist-info/WHEEL,sha256=itfEIwM024rWDKIUM5IIFma0LGtWvvW7z4i7fizC-AU,105
+dal_python-2026.9.25.dist-info/RECORD,,

dal_python-2026.9.25.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 1.0.3
+Root-Is-Purelib: false
+Tag: cp314-cp314-win_amd64
+