docs: reconcile documentation with current implementation#231
Merged
Conversation
Up to standards ✅🟢 Issues
|
Coverage Report for CI Build 29444334518Coverage remained the same at 88.399%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsNo coverage regressions found. Coverage Stats
💛 - Coveralls |
There was a problem hiding this comment.
Pull request overview
Documentation-only reconciliation pass to bring DAL’s published Markdown set (plus supporting .codex audit artifacts) back into agreement with the current C++/Python/Excel implementation—especially around cross-currency (XCCY) pricing/calibration, Jacobian/inverse conventions, and updated methodology details.
Changes:
- Updated root/docs navigation and component READMEs to reflect current XCCY capabilities and surface-specific availability.
- Refreshed quantitative methodology notes (AAD tape rewind semantics, interpolation, matrix algorithms, RNG seeking) to match current behavior.
- Added/updated
.codexspecification/plan/review artifacts to record the audit scope, evidence, and dispositions.
Reviewed changes
Copilot reviewed 17 out of 22 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds XCCY capability mention and links to XCCY examples/methodology. |
| docs/README.md | Fixes heading hierarchy and refreshes indexed methodology summaries. |
| docs/public-api.md | Clarifies staged vs joint XCCY API boundaries across C++/Python/Excel. |
| docs/methodology/yield_curve_jacobian.md | Expands joint XCCY Jacobian/effective-inverse semantics and availability notes. |
| docs/methodology/xccy_calibration.md | Expands fixing snapshot rules, matrix semantics, surface availability, examples, and perf notes. |
| docs/methodology/random.md | Updates RNG SkipTo/clone/branch semantics and MRG32 caveats. |
| docs/methodology/matrix.md | Updates Thomas/Cholesky/band complexity and regularization narrative. |
| docs/methodology/interpolation.md | Tightens linear/cubic descriptions, formulas, and boundary-condition semantics. |
| docs/methodology/aad.md | Clarifies Rewind vs RewindToMark checkpoint semantics. |
| docs/experimental/replicate-ptirds-single-currency-curve.md | Clarifies calendar reproduction and neutralizes comparison language. |
| docs/architecture.md | Documents immutable market-fixing snapshot ownership and XCCY calibration flow branching. |
| dal-python/README.md | Updates Python testing inventory and staged vs joint XCCY exposure semantics. |
| dal-excel/README.md | Clarifies snapshot rules and staged vs joint worksheet visibility of matrices/ranges. |
| CHANGELOG.md | Refreshes capability bullets/wording for current XCCY and Jacobian coverage. |
| .codex/artifacts/specs/repository-documentation-reconciliation.md | Adds reconciliation specification and acceptance criteria. |
| .codex/artifacts/specs/2026-07-12-zero-rate-parameterization-design.md | Stores historical design artifact outside published docs. |
| .codex/artifacts/specs/2026-07-12-ycinstrument-pricing-performance-design.md | Stores historical design artifact outside published docs. |
| .codex/artifacts/reviews/repository-documentation-reconciliation.md | Records evidence-backed 33-row disposition audit and verification gates. |
| .codex/artifacts/plans/2026-07-15-repository-documentation-reconciliation.md | Implementation plan for the documentation reconciliation work. |
| .codex/artifacts/plans/2026-07-12-zero-rate-parameterization.md | Stores historical implementation plan artifact outside published docs. |
| .codex/artifacts/plans/2026-07-12-ycinstrument-pricing-performance.md | Stores historical implementation plan artifact outside published docs. |
| .codex/artifacts/plans/2026-07-12-unified-yield-curve-interpolation-aad.md | Stores historical implementation plan artifact outside published docs. |
Comment on lines
+192
to
+196
| | Surface | Staged XCCY | Joint XCCY | | ||
| |---------|-------------|------------| | ||
| | Core/public C++ | Full options, forward Jacobian, and effective inverse | Full options and both top-level matrices | | ||
| | Python | Default staged solve with market/FX-forward and fit diagnostics; no staged matrix bindings | Options, named ranges, forward Jacobian, and effective inverse | | ||
| | Excel | Basis handle and fit diagnostics; no staged matrix views | Options plus forward-Jacobian/range views; no effective-inverse worksheet getter | |
Comment on lines
238
to
242
| | `RNGType_` | Implementation | Period / structure | `SkipTo` | | ||
| |------------|-----------------------|----------------------------------------------|-----------------------------------------------------| | ||
| | `IRN` | `ShuffledIRN_<55,31,128>` | Knuth-style lagged additive (IRN55) with shuffling, modulus $2^{30}$ | No-op (re-seed via `Branch`/`Clone` for substreams) | | ||
| | `MRG32` | `MRG32k32a_` | L'Ecuyer combined multiple recursive (MRG32k32a), periods $\approx 2^{191}$ | Matrix exponentiation of the recurrence | | ||
| | `IRN` | `ShuffledIRN_<55,31,128>` | Knuth-style lagged additive (IRN55) with shuffling, modulus $2^{30}$ | No-op; `Clone` restarts from the original seed and `Branch` creates another seeded generator | | ||
| | `MRG32` | `MRG32k32a_` | L'Ecuyer combined multiple recursive (MRG32k32a), periods $\approx 2^{191}$ | Matrix jump; fresh-generator `FillUniform` replay at even path offsets only; no normal-path replay | | ||
|
|
Comment on lines
+109
to
+113
| | `order_` | Boundary condition | | ||
| |----------|------------------------------------------------------------------------------------------| | ||
| | 1 | `lhs` pins $f'(x_1)$; `rhs` pins $f'(x_N)$ to its respective `value_` | | ||
| | 2 | `lhs` pins $f''(x_1)$; `rhs` pins $f''(x_N)$ to its respective `value_` | | ||
| | 3 | each endpoint segment's third derivative is pinned to the respective `lhs`/`rhs` `value_` | |
Comment on lines
+112
to
+119
| | Input | Authority | Output | | ||
| |------------------------|------------------------------------------------------------------------|---------------------------------------------------------------------------| | ||
| | Published Markdown set | `.github/scripts/check_docs.py::DOCS` | One 33-row disposition matrix | | ||
| | C++ surface | Core/public headers and generated enums | Exact types, constants, ownership, and solver contracts | | ||
| | Python surface | `dal-python/src/bindings/`, `dal-python/src/dal/`, tests, examples | Callable names, result properties, and supported workflows | | ||
| | Excel surface | `dal-excel/src/`, interface markup, generated help, smoke tests | Worksheet functions, settings, selectors, and documented limitations | | ||
| | Build/runtime surface | CMake, presets, scripts, workflows, web source | Current setup, ownership, execution, and CI descriptions | | ||
| | Numerical behavior | Methodology implementation plus independent tests | Correct formulas, matrix semantics, tolerances, and applicability | |
Comment on lines
+88
to
+90
| x_i=\frac{b_i-c_{i-1}x_{i-1}}{\beta_i}, | ||
| \qquad | ||
| x_{i-1}\leftarrow x_{i-1}-\frac{a_{i-1}}{\beta_{i-1}}x_i |
The linear interpolator (dal-cpp/dal/math/interp/interplinear.cpp) does not enforce a minimum knot count -- unlike log-linear and cubic, which gate on size. It also checks monotonicity with std::less_equal, so it accepts equal (duplicate) abscissae. The prior text overstated both contracts: the Linear section claimed "Requires N >= 2" and the Common Interface stated universally that abscissae "must be strictly increasing". Drop the false minimum-size claim for linear and soften the shared monotonicity statement to non-decreasing, which is the true common floor (cubic and log-linear keep their stricter scheme-specific requirements). Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
python3 .github/scripts/check_docs.py— 28 current-state Markdown filesbuild/Release-linux/dal-cpp/dal_cpp_tests— 985 passedbuild/Release-linux/dal-public/dal_public_tests— 56 passedxccy_perf— exactly 24 unique timing rows