stringforge.toric_db

stringforge.toric_db#

Consumer for the unified, sharded toric cy-database sub-dataset (FRST + VEX).

ToricCYDatabase subclasses stringforge.cy_io.CYDatabase, but note that the inheritance is nominal: the base class assumes a monolithic {dataset}/catalog.parquet, which the toric sub-dataset does not have, so the whole catalogue layer is replaced rather than extended and every inherited member that assumes the monolithic layout is explicitly closed (see query_conifolds()). What is reused is the download/cache machinery.

The toric layout (built by private/database/frst_vex_merge/build_toric_database.py) stores everything as per-h11 sharded parts, so the catalog is never loaded whole:

  • Point lookups are O(1) via the per-h11 _ksid_index (ks_id → (part, row0, n)): load(), get_polytope(), and query(mode, h11, ks_id=…) read one part slice.

  • Attribute queries (fav_N/h12/…) stream the per-h11 catalog via pyarrow.dataset + filter pushdown (using _metadata when present) — never materialising billions of rows.

The thin phase catalog omits polytope_hash (joined via ks_id from the polytope catalog on load()) and phase_id (derived "{mode}:{h11}:{ks_id}:{triang_id}"); wall_hash is a 32-byte digest, exposed as .hex(). Per-polytope VEX counts live in polytope_vex_counts and are left-joined by query_polytopes().

Access is currently local only (from_local()); lazy download of the sharded layout from the Hub is not yet implemented. Example:

from stringforge import ToricCYDatabase
db = ToricCYDatabase.from_local("/path/to/build")     # the dir containing toric/, or toric/
polys = db.query_polytopes(h11=4, fav_N=True)          # n_frst_classes AND n_vex_classes
frst  = db.query("frst", h11=4)
geom  = db.load("frst", h11=4, ks_id=0, triang_id=0, in_basis=True)
poly  = db.get_polytope(h11=4, ks_id=0)

Note

Access is currently local only — build or download the toric/ tree and open it with ToricCYDatabase.from_local(). Lazy per-shard download from the Hub is not yet implemented.

Overview#

ToricCYDatabase exposes the toric sub-dataset of cy-database: Calabi–Yau hypersurface phases obtained from the Kreuzer–Skarke list (arXiv:hep-th/0002240), together with the polytope data they share. Two kinds of phase live side by side, distinguished by mode:

mode

What one row is

frst

A distinct CYTools CalabiYau class of a fine, regular, star triangulation — the standard notion of a toric CY hypersurface phase. Classes are deduplicated by CYTools cy()-equivalence, following arXiv:2310.06820. Available for \(h^{1,1} = 1 \dots 12\).

vex

A distinct Wall class — equal in-basis \((\kappa, c_2)\) — of a not necessarily fine star triangulation of the polytope’s vector configuration, following arXiv:2512.14817. Available for \(h^{1,1} = 2 \dots 7\).

Important

The two modes are built over the same polytopes, which is why the polytope layer is shared and stored once. Every VEX polytope is also an FRST polytope, so vex \(\subseteq\) frst as sets of polytopes.

This is not a containment on phases, and the class counts are not comparable as one. The two modes apply different equivalences to different triangulation families: cy()-equivalence on fine star triangulations versus \((\kappa, c_2)\)-equivalence on not-necessarily-fine ones. Because the non-fine family is much larger, a polytope routinely has more VEX classes than FRST classes — at \(h^{1,1} = 4\) the totals are 1,774 FRST against 2,536 VEX.

Note

Neither notion is yet a diffeomorphism class: both are equivalences in a fixed GLSM basis. wall_hash is a necessary diffeomorphism pre-filter (Wall’s theorem), not a sufficient one; the full \(GL(h^{1,1}, \mathbb{Z})\)-canonical identification is not implemented.

Unlike the other sub-datasets, toric has no monolithic catalog.parquet: both the phase catalogue and the geometry are sharded per \(h^{1,1}\), which is what makes billions of rows tractable. Point lookups stay \(O(1)\) through a per-\(h^{1,1}\) _ksid_index (ks_id \(\to\) (part, row0, n)); attribute queries stream the relevant shard with pyarrow filter pushdown.

Warning

ks_id is the Kreuzer–Skarke emission order and is unique only within a given \(h^{1,1}\). A phase key therefore needs all four of (mode, h11, ks_id, triang_id); from_database() raises if the key it is given is not unique.

ToricCYDatabase(**kwargs)

Consumer for the sharded toric sub-dataset (shared polytopes; FRST/VEX phases).

Curated method index#

Discovery:

  • ToricCYDatabase.info()

  • ToricCYDatabase.query()

  • ToricCYDatabase.query_polytopes()

Point lookups:

  • ToricCYDatabase.load()

  • ToricCYDatabase.get_polytope()

  • ToricCYDatabase.from_local()

Deliberately unsupported#

The base class’s monolithic-catalogue members cannot work on a sharded layout and are closed with an explanatory NotImplementedError rather than left to fail obscurely — chiefly ToricCYDatabase.query_conifolds() (the toric sub-dataset carries no conifold index; see stringforge.kklt_database.KKLTDatabase for that).

Vacua-vault namespace. There is no toric/ namespace in the shared vacua vault, so vacua found on a toric phase currently have no canonical remote location: a phase routed through to_lcs_tree() does not carry its (h11, ks_id, triang_id, mode) identity into the resulting lcs_tree, and VacuaWriter’s remote-path resolution returns None rather than misfiling it under tdf/. Defining such a namespace is a vault data-format decision: unlike tdf/, a toric key needs \(h^{1,1}\) (ks_id is unique only within one \(h^{1,1}\)) and mode. Until it is defined, treat vault persistence of toric vacua as unsupported.