Skip to content

docs: index.md and architecture_overview.md claim Jacobians use JAX autodiff but production uses OpenVAF analytical Jacobians #128

@github-actions

Description

@github-actions

Problem

Two docs describe Jacobian computation as using JAX autodiff (jacfwd/jvp), but the production hot path uses analytical Jacobians generated by OpenVAF's symbolic differentiation.

Affected locations

docs/index.md line 5:

  • Automatic differentiation for computing device Jacobians without explicit derivatives

docs/architecture_overview.md line 8:

  1. Automatic Differentiation: Jacobians computed via JAX autodiff, no explicit derivatives

docs/architecture_overview.md lines 54–57 (diagram):

│     │   Autodiff         │
│     │ (Jacobians via     │
│     │  jacfwd/jvp)       │

Why it's wrong

vajax/analysis/homotopy.py line 16 explicitly states:

"uses analytic jacobians from OpenVAF. This avoids jax.jacfwd() autodiff"

The production transient solver path (solver_factories.py) receives Jacobians directly from OpenVAF's MIR-compiled functions. JAX's jacfwd/jvp is only used in analysis/solver.py (the DC utility solver), not in the transient hot path.

docs/gpu_solver_jacobian.md documents the full history of this migration from autodiff to analytical Jacobians.

Fix

Update the design principle description in both files to say something like:

Analytical Jacobians: Jacobians computed symbolically by OpenVAF's MIR compiler — no runtime autodiff overhead

The diagram in architecture_overview.md should replace the "Autodiff (Jacobians via jacfwd/jvp)" box with "Analytical Jacobians (via OpenVAF MIR)".

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation issues

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions