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, correlated BS, GSR, and hybrid local-vol models for 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
• Rate quote curvature — immutable calibration snapshots and weighted native portfolios with recalibrated quote gradients and finite-step Hessian products; see the interface
• Segmented Black–Scholes risk — owning script preparation, explicit path/checkpoint budgets and common-path mean gradients/Hessian products; see the interface
• LSMC policy curvature — owning preparation and retained policy metadata distinguish frozen-policy HVPs from differences of the retrained gradient estimator; see the interface
• 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)
• 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

Building the C++ Library

The Python bindings depend on a compiled DAL C++ staging prefix. Build it first:

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:

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 ../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:

# 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

# 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:

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:

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:

./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):

pip install dist/dal_python-2026.10.11.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.10.11.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:

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:

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:

   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

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:

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

For selected scalar outputs and passive weights, use WeightedRiskRequest_ and MonteCarlo_ValueWithWeightedRisk. The weighted script risk reference describes output IDs, owning results, strict inputs and numeric budgets.

Historical and Future FIX

The complete FIX settings example 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:

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 products and products containing neither PAYS nor EXERCISE fail valuation.

Historical EQ, FX, and Libor 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. Correlated BS and hybrid models accept several named future EQ indices; BS accepts one distinct index. Future IR discount-factor, Libor, and swap observations are supported by the single-currency GSR model. Future FX, composite, and delivery-suffixed EQ remain unsupported. default_index gives legacy SPOT() an identity; it does not affect FIX literals. Unbound future-only SPOT() remains supported for one-asset models. Multi-asset SPOT() always requires a default, which also selects the one LSM regressor for early exercise when no explicit regression_features are selected. Historical SPOT requires a default, and mixing SPOT with FIX requires one too. SPOT(index) and FIX() are invalid. See examples/hybrid_script.py for two-equity valuation. The GSR swap and swaption example snapshots an input USD OIS yield curve, supplies g/H, prints both products' script trees, and reports curve fit and prices in tables. Its standard coupon-paying swap compares GSR Monte Carlo PV with static pricing from the same input yield curve; its swaption settles in cash. The model guide links the matching C++ example.

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

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

# 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

Local Volatility in Hybrid

# 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

surface = dal.LocalVolSurfaceData_New("equity_vol", spots, times, vols)
bs = dal.BSModelData_New(100.0, 0.20, 0.05, 0.01)
local_vol_model = dal.BSLocalVolModelData_New(
    "local_vol", "EQ[A]", "USD", "W_EQ", bs, surface
)

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.LocalVolSurfaceData_New(name, spots, times, vols) — serializable local-vol surface
• dal.BSLocalVolModelData_New(name, index, currency, factor, bs, surface) — Hybrid Local Vol with flat BS rate
• dal.CorrelatedBSModelData_New(indices, spots, vols, divs, rate, correlations) — named correlated equities
• dal.HybridModelData_New(name, domestic_currency, components, correlation) — composed named equities and deterministic rate; create components and provider with HybridBSEquityData_New, HybridDeterministicRateData_New, and HybridConstantCorrelationData_New

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 any of the four factories above
• 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.

ScriptProductSettings_(*, default_index="", regression_features=None)
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, lsmc_validation_paths=None,
                   lsmc_rqmc_replicates=None, lsmc_training_seed=None,
                   lsmc_pricing_seed=None, lsmc_policy_risk_mode="Frozen",
                   lsmc_policy_bump_relative=0.001)

For EXERCISE, regression_features selects up to three distinct model-supported EQ/IR observations or scalar VAR[name] states. For example, ScriptProductSettings_(regression_features=["EQ[A]", "VAR[runningAverage]"]) retains equity and accumulated script state for each exercise fit. Rate-only GSR exercise requires explicit features, such as ["IR[USD,SWAP,5Y]"]. The getter returns a new list; assign the property to replace the selection. Product construction copies it, and Product_Describe reports the selection. Model support and feature names are checked during preparation; see LSM basis selection.

For exercise products, training and pricing counts can be set independently:

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. Set lsmc_validation_paths to enable held-out degree selection. The first block fits candidate degrees 1 through lsmc_basis_degree, the next block selects the smallest degree within a descriptive one-standard-error tolerance of the minimum continuation MSE, and the final num_path paths price the selected policy. For example, MonteCarloSettings_(lsmc_training_paths=16_384, lsmc_validation_paths=4_096) uses three disjoint Sobol blocks. Omitting validation retains the faster fixed degree fit. The comparison benchmark reports repeated pricing times and errors against a separate CRR tree oracle.

For conditional randomized-QMC error bars, set lsmc_rqmc_replicates to at least 2. Training (and optional validation) fits one frozen policy; each pricing replicate then uses num_path fresh Sobol points with an independent 32-bit digital shift. The returned PV is the mean of replicate prices. lsmc_training_seed and lsmc_pricing_seed select reproducible streams; when omitted, both effective seeds are 0 and distinct role keys keep the streams separate. Seeds without a replicate count, and replicates with a non-Sobol method, are errors. For example:

simulation = dal.MonteCarloSettings_(
    lsmc_training_paths=8_192,
    lsmc_rqmc_replicates=8,
    lsmc_training_seed=17,
    lsmc_pricing_seed=29,
)
diagnostic = dal.ScriptSimulation_Explain(
    product, model, 2_048, simulation=simulation
)
error_bar = diagnostic["uncertainty"]["replicate_mean_se"]

For AAD Greeks that include the fitted exercise policy's response, use lsmc_policy_risk_mode="RetrainedBump" with enable_aad=True. This adds the common-path finite difference of policies retrained at each model-parameter or script-constant bump to the frozen-policy adjoint. The bump is lsmc_policy_bump_relative * max(1, abs(input)), with a forward secant at a spot or volatility lower boundary. The PV is identical in both modes. Retraining costs roughly two extra fits and two value-only pricing passes per unconstrained input; a finite bump can cross exercise, inclusion, degree-selection, or solver boundaries. The default Frozen mode remains the cheaper exact gradient of the fixed-policy fuzzy estimator.

error_bar estimates pricing error conditional on that policy. It does not cover retraining variation or approximation bias. The coverage experiment reports observed mean ± two-standard-error coverage against analytic European and independent PDE Bermudan references. The default deterministic Sobol mode retains its original values and only reports a descriptive payoff-dispersion statistic.

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 products and products without either PAYS or EXERCISE 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 separate lsmc_training_paths training paths (defaulting to num_path) and optional lsmc_validation_paths paths (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, lsmc_training_paths, and lsmc_validation_paths, lsmc_rqmc_replicates, lsmc_training_seed, and lsmc_pricing_seed (null when unset), the explicit per-replicate pricing count n_paths, an uncertainty object with replicate means and their conditional standard error, and one exercise_events entry per exercise date (degree, basis, solver, effective rank, fallback reason, validation MSE, 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. The blocks do not overlap; they use deterministic Sobol points unless RQMC replicates are enabled. Products without EXERCISE return an empty exercise_events list. The early-exercise example 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. 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 ../build_linux.sh --full

After an editable install, run focused Python tests directly:

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, Hybrid Local Vol)
• 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 provides 98 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:

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 98 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 43 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, single, staged/joint multi-curve and XCCY calibration, and the GSR example's standard swap with and without cashflow reuse and its European swaption under QuantLib MC and Gaussian1d integration. Rateslib equity MC and GSR swaption, 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.

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 and Jacobian guide.

CalibrationPullback_New(calibration) creates an owning common boundary from a frozen Dupire snapshot or captured native curve provenance. CalibrationParameterAdjoints_New(boundary, adjoints) takes a two-dimensional node-adjoint matrix; PullbackCalibration(boundary, parameters, *, direct=None) returns separate calibration/direct/total quote matrices and the original source. For curves, enable retain_calibration_record=True in RateQuoteRiskProvenanceConfig_ before provenance construction and supply an M-by-one seed in global parameter order. Matrices may be DoubleMatrix_ or rectangular numeric lists/tuples. See the common pullback example and ownership rules.

Continuously Compounded Zero-Rate Curves

Build a persistent zero-rate curve directly with future-only nodes:

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:

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:

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.

The runnable joint XCCY calibration example 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:

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:

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.

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:

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 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 and mapping contract. The runnable single-curve example prints the policy, both fingerprints, and all buckets; the joint XCCY example constructs joint provenance.

Troubleshooting

"Cannot find DAL::public" during build

Ensure DAL_INSTALL_PREFIX points to the correct staged DAL installation:

<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:

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:

uv run --no-sync python -c "import dal; print(dal.__version__)"

License

MIT License. See the repository LICENSE.

Contributing

Follow the repository contributor guide. Binding changes should include Python tests and updates to the Python interface chapter when the supported surface changes.

See Also

• DAL C++ Library — Workspace overview
• Installation guide — Canonical setup commands
• Python interface chapter — Python entry points and examples
• C++ public API guide — underlying public facade
• pybind11 Documentation — pybind11 binding syntax