Calabi-Yau Geometry Database

Calabi-Yau Geometry Database#

StringForge provides access to large Calabi-Yau geometry datasets through a unified interface. Data are hosted on HuggingFace and downloaded lazily: the constructor performs no network access, catalogue files are fetched on first query, and geometry shards are fetched only when a model is loaded.

Important

There are three related but distinct layers:

TDF/CICY geometry databases store Calabi-Yau data.
KKLT curated subset stores specialised conifold-class provenance and logical links back to TDF rows.
vacua_vault is one shared repository for designated vacuum solutions, with dataset-specific metadata in each record.

Available database interfaces#

TDF models from the Kreuzer-Skarke list, addressed by (ks_id, triang_id), through TDFDatabase and LCSDatabase(dataset="tdf").
CICY models from the complete-intersection Calabi-Yau list, addressed by cicy_id, through CICYDatabase and LCSDatabase(dataset="cicy").
KKLT index, an advanced curated TDF subset indexed by conifold class with curation tags, through KKLTDatabase. See KKLT Database after reading this page.

Each model may carry topological data, Kähler-cone data, optional GV/GW invariants, optional conifold-limit data, and extra precomputed properties.

Two ways to load models#

Pure I/O#

Use CYDatabase, TDFDatabase, or CICYDatabase when you want catalogue rows and raw data without constructing a physics model.

from stringforge import TDFDatabase

db = TDFDatabase()
df = db.query(h11=2)

JAXVacua bridge#

Use LCSDatabase when you want the public surface in mirror convention and want to construct JAXVacua-compatible objects.

from stringforge import LCSDatabase

db = LCSDatabase(dataset="tdf")
rows = db.query(h12=2).head()
row = rows.iloc[0]

tree = db.load(
    h11=int(row["h11"]),
    h12=int(row["h12"]),
    ks_id=int(row["ks_id"]),
    triang_id=int(row["triang_id"]),
)
model = db.load_model(
    h11=int(row["h11"]),
    h12=int(row["h12"]),
    ks_id=int(row["ks_id"]),
    triang_id=int(row["triang_id"]),
)

Geometry data, curated subsets, and model loading

TDF and CICY are geometry sources. KKLT is a curated index that stores conifold-class provenance, tags, and logical links back to TDF; it is not a separate geometry source.

Geometry data sources

cy-database / TDF Kreuzer-Skarke catalogues with sharded geometry, GV, polytope, and conifold data.

cy-database / CICY Complete-intersection catalogues with sharded geometry and derived model data.

Catalogue-convention I/O

CYDatabase Common query, cache, shard-loading, schema, and offline machinery.

TDFDatabase TDF rows addressed by ks_id and triang_id.

CICYDatabase CICY rows addressed by cicy_id.

Convention boundary: catalogue columns use source-geometry labels; LCSDatabase exposes mirror-convention h11 and h12.

Curated index and model bridge

LCSDatabase Builds lcs_tree data and ready-to-use FluxVacuaFinder models.

KKLTDatabase Advanced kklt index: conifold classes, logical TDF links, and tags.

Batch and sample APIs Load, iterate, and sample compatible models for scans.

Downstream use

JAXVacua Flux-vacua physics, periods, sampling, and stability analysis.

VacuaWriter Designated vacua with model identity and provenance.

Future consumers Kähler, axion, and optimisation workflows using the same data conventions.

Lazy downloading and caching#

The cache defaults to .stringforge_cache/ in the current working directory. Change it globally with stringforge.set_data_dir() or the STRINGFORGE_DATA_DIR environment variable, or per instance with cache_dir=.

Step	Network behaviour
Constructor	No network access.
`query(...)`	Downloads the lightweight catalogue once.
`load(...)`	Downloads only the shard containing the requested row.
`load_batch(...)`	Downloads only shards needed by the batch.

Use cache_mode="none" when scanning many models without keeping downloaded shards on disk. Use offline=True after warming a cache for cluster jobs.

Environment variables#

Variable	Default	Description
`STRINGFORGE_DATA_DIR`	`{cwd}/.stringforge_cache`	Global data/cache directory.
`STRINGFORGE_HF_REPO`	`aschachner/cy-database`	Geometry database repository.
`STRINGFORGE_VAULT`	explicit or repo-local	Local designated-vacua directory.
`STRINGFORGE_VAULT_REPO`	`aschachner/vacua_vault`	Shared HuggingFace vault repository.

Calabi-Yau Geometry Database

Contents