Architecture

This page records the package boundaries. The guiding rule is simple: StringForge owns shared infrastructure; sibling packages own physics engines.

Owner / consumer matrix

stringforge — shared infrastructure

Module	Public symbols	Purpose
stringforge.cy_io	CYDatabase, TDFDatabase, CICYDatabase	Pure catalogue I/O, HuggingFace downloads, cache management, schema checks.
stringforge.lcs_database	LCSDatabase, load_tdf_model, load_cicy_model	Mirror-convention model loading; builds lcs_tree or FluxVacuaFinder objects when JAXVacua is available.
stringforge.kklt_database	KKLTDatabase	Advanced curated kklt TDF subset indexed by conifold class, with logical TDF links and curation tags.
stringforge.vacua_writer	VacuaWriter and database delegations	Vacuum-solution persistence, designation, retraction, purge, and HuggingFace vault push/fetch.
stringforge.vacuavault	validation and curation helpers	Schema validation and catalogue rebuild tooling for the public vacua vault.

jaxvacua — flux-vacua engine

JAXVacua owns the layered physics pipeline:

lcs_tree -> periods -> css -> FluxEFT -> FluxVacuaFinder

StringForge can construct lcs_tree and FluxVacuaFinder objects, but it does not own period calculations, flux sampling, scalar potentials, vacuum solvers, or mass-spectrum computations.

Planned packages

KahlerJAX and JAXiverse are planned ecosystem consumers. Their planning pages describe intent only. They are not imported by StringForge, not installed as default dependencies, and not treated as stable public APIs in this release.

External packages

CYTools remains the external toric geometry package used by selected workflows. JAXPolyLog is the public differentiable polylogarithm package consumed by JAXVacua and planned downstream physics packages.

What StringForge is not

• Not a replacement for JAXVacua.

• Not a complete string-phenomenology framework by itself.

• Not a public release vehicle for KahlerJAX/JAXiverse.

• Not the owner of every collaborator-generated dataset referenced in examples.

Convention boundaries

Two conventions cross package boundaries and are easy to get wrong:

• Catalog versus mirror Hodge numbers. CYDatabase exposes parquet catalogue convention. LCSDatabase exposes mirror convention to match lcs_tree and JAXVacua. Translation happens at the public API boundary.

• Float64 precision. Model-construction workflows assume JAX x64 support. Set precision before importing JAX-heavy physics packages.

Duck-typed model identity

VacuaWriter accepts either a JAXVacua model with .periods.lcs_tree or an lcs_tree-like object directly. This keeps StringForge free of eager physics imports while still recording model identity and hashes for vault entries.

Background belongs in docs

Source docstrings should document signatures, side effects, convention boundaries, and failure modes. Conceptual explanations belong in these Sphinx pages, where they can be expanded with notes, warnings, and figures.