Design principles

Design principles#

The StringJAX member packages share a small set of technical commitments. They are deliberate constraints that make the ecosystem composable rather than a loose collection of independent projects.

Differentiability is a first-class requirement#

Every primitive that maps compactification data to four-dimensional effective-theory data is implemented as a JAX-traceable function: period vectors, prepotentials, Kähler potentials, gauge-kinetic matrices, the flux superpotential, \(F\)-terms, scalar potentials, Hessians, and mass matrices. Higher-level routines such as ISD sampling, Newton-type vacuum finding, and the reduced (freezer) effective theories compose these primitives.

The consequence is that derivatives are available everywhere by construction: gradients for Newton refinement and gradient flow, Jacobians for \(F\)-term solving, Hessians for stability analysis, and higher-order derivatives for surrogate construction and sensitivity analyses.

Concretely this means:

  • Numerical stability is a property of the autodiff trace, not just of the primal evaluation. Helper utilities such as jaxpolylog are designed so that arbitrary-order differentiation remains numerically stable in regimes where the closed-form expressions would lose precision.

  • Performance bottlenecks shift from per-step finite differences to batched JIT-compiled traces.

  • Surrogate construction (Taylor expansions around vacua, learned emulators, etc.) is a routine downstream operation rather than a separate codebase.

Modular, layered architecture#

The ecosystem is layered to keep the boundary between data, special functions, physics, and glue clear.

                    user code
                        |
                stringjax (glue)
                /       |       \
     jaxvacua  ----  jaxpolylog  ----  stringforge
       (physics)     (special funcs)      (data)
                        |
                       jax

Each package owns one layer. This is what makes it possible to update one layer (a new database, a new polylog method, a new vacuum sampler) without rebuilding the others.

Specifically:

  • stringforge is intentionally solver-light. It does not evaluate physics; it serves curated geometry data and persists vacua.

  • jaxvacua consumes data from stringforge and the polylog primitive from jaxpolylog but does not own data movement or special-function implementations.

  • jaxpolylog is a pure leaf with no string-theory content.

This split has a practical pay-off: the same stringforge data layer will support future member packages without modification.

Reproducibility is a feature, not an after-thought#

Compactification calculations have many degrees of freedom (basis choices, normalisations, sign conventions, sampling seeds, version windows of intermediate libraries). Reproducing a published result years later is hard if those choices are buried in private scripts. StringJAX makes them explicit.

Concrete commitments:

  • Pinned versions. The umbrella stringjax pins compatibility windows for every member package; stringjax doctor reports the actual installed versions and flags drift.

  • Conventions. The mirror-symmetry convention used by jaxvacua, the stringforge catalogue convention, and the conifold basis-change conventions are documented and version-tagged.

  • Persistent storage. Vacuum solutions live in a vault (stringforge.VacuaWriter) with provenance fields: solver, configuration hash, seed, git SHA, wall clock, and primary-key geometry identifiers.

  • Citeable snapshots. Curated dataset and solver snapshots are archived with DOIs.

A search performed today on a flux-vacuum problem should be runnable, byte-for-byte, by another researcher with no shared infrastructure.

Data and code are coupled, not separated#

A unified computational framework is also a vehicle for coupling code to compactification data. Curated databases of geometries and vacua are first-class consumers of the same APIs that user code uses.

In practice:

  • stringforge.LCSDatabase(...) returns objects in exactly the form jaxvacua.FluxVacuaFinder expects.

  • Vacuum records produced by jaxvacua are written back into the same vault that the input geometry came from, so that follow-up studies can locate them by the same primary key.

  • Notebooks and scripts that build the catalogue use the same conventions and primitives as user code, so that the “build” and “use” workflows stay aligned.

Boundaries with jax, mpmath, scipy, and cytools#

StringJAX does not re-implement what general-purpose ecosystems already do well. It uses them and bridges them.

  • jax – autodiff, JIT, vmap, hardware acceleration. StringJAX consumes the public JAX API and adds primitives where none exist (jaxpolylog).

  • mpmath – arbitrary-precision reference for testing and benchmarking. jaxpolylog’s accuracy tests pin its output against mpmath to twelve digits.

  • scipy – general numerical primitives such as scipy.optimize.root are used inside jaxvacua as drop-in solvers when JAX-native solvers are not the best fit.

  • cytools – toric Calabi–Yau geometry. StringJAX provides the bridges that turn cytools objects into pull-once-cache-forever ecosystem datasets.

What this rules out#

The principles above also identify things StringJAX deliberately is not:

  • It is not a single monolithic package. Member packages are independently versioned, independently released, and independently citeable.

  • It is not a replacement for mpmath or scipy – those are first-class dependencies.

  • It is not the public release vehicle for every planned sibling package. Future siblings (Kähler-sector, axion-sector) will arrive with their own DOIs and authoritative documentation.

  • It is not coupled to a particular execution environment. The same code paths run on CPU, GPU, and TPU, and (where supported) under Apple-Silicon JAX with the documented complex-arithmetic fallback.

These commitments are what make the umbrella thin enough to remain useful as the ecosystem grows.