Documentation

For Scientists

Use the application to quickly surface rare Calabi-Yau candidates while keeping a reproducible record.

Run searches in the web UI or API to rank candidates by predicted likelihood
Verify top-k hits against each dataset’s target rule and track precision/recall vs a random baseline
Export CSV/JSON artifacts for downstream analysis and sharing
Record random seeds and dataset metadata for reproducibility
Look up offline geometry packs, promote verified hits to the Hall of Fame, and poll async jobs

Installation Prerequisites

Python 3.11 (matches the production Docker image; pins do not resolve on 3.12+)
pip package manager
4GB RAM minimum (8GB recommended)
2GB free disk space for datasets and outputs

Quick Install

                git clone https://github.com/upggr/compute.upg.gr.git

cd compute.upg.gr

python3.11 -m venv venv && source venv/bin/activate

pip install -r requirements.txt

How to Run

Basic Run (CLI)

python cy_search_real.py

Web App

python app.py

Production uses gunicorn (see Dockerfile). Home and Run pages submit with async: true and poll GET /api/jobs/<id>.

Expected Runtime

Typical sync demo sizes (1k–5k candidates) finish in a few seconds on standard hardware. Larger public runs (up to 25k candidates) are forced async so gunicorn workers stay responsive. Offline lab runs may take longer depending on CPU.

Limits

Public max n_candidates: 25,000
Requests with n_candidates > 5,000 are forced async
Heavy endpoints are IP rate-limited (~20 / minute): /api/run-demo, /api/batch, /api/export-physics, /api/score-custom, /api/search

Output Location

All run artifacts are saved under static/data/ (ephemeral results_*.json files are TTL-cleaned; Hall of Fame / geometry SQLite DBs are kept):

static/data/results_<run_id>.json — full run payload
static/data/results_topk.csv, metrics.json, repro.md — seed / demo fixtures
static/data/hall_of_fame.sqlite — persistent verified board
static/data/geometry.sqlite — offline geometry lookup store
static/data/jobs.sqlite — async job progress (when volume-mounted)

Run Exports

The Run page provides download buttons for JSON/CSV plus tool-friendly exports for CYTools, cymetric, Sage, and Mathematica.

Import / Export (API)

Use the REST API to import datasets or export results programmatically.

                # Import: score custom candidates and save a run

curl -X POST https://compute.upg.gr/api/score-custom -H "Content-Type: application/json" \\

  -d '{"dataset_id":"kreuzer-skarke","rows":[[12,45,66,3.75,924]],"top_k":20,"seed":42,"verify":true,"save":true}'

# Async demo / search (poll until completed)

curl -X POST https://compute.upg.gr/api/run-demo -H "Content-Type: application/json" \\

  -d '{"top_k":100,"n_candidates":5000,"async":true}'

curl https://compute.upg.gr/api/jobs/JOB_ID

# Batch identify/search (max 50 jobs)

curl -X POST https://compute.upg.gr/api/batch -H "Content-Type: application/json" \\

  -d '{"jobs":[{"type":"identify","h11":11,"h21":11,"dataset_id":"kreuzer-skarke"}]}'

# Geometry lookup

curl "https://compute.upg.gr/api/geometry/lookup?dataset_id=kreuzer-skarke&h11=11&h21=11"

# Hall of Fame / featured

curl "https://compute.upg.gr/api/featured-candidates?dataset_id=kreuzer-skarke&top_n=12"

# Export: fetch results in tool-friendly formats

curl -o results.json "https://compute.upg.gr/api/export/RUN_ID?format=json"

curl -o results.csv "https://compute.upg.gr/api/export/RUN_ID?format=csv"

curl -o cytools.json "https://compute.upg.gr/api/export/RUN_ID?format=cytools"

curl -o cymetric.json "https://compute.upg.gr/api/export/RUN_ID?format=cymetric"

curl -o candidates.sage "https://compute.upg.gr/api/export/RUN_ID?format=sage"

curl -o candidates.wl "https://compute.upg.gr/api/export/RUN_ID?format=mathematica"

Info-density weights (request-scoped)

POST /api/info-density/weights returns a weight_set_id; it does not mutate global worker state. Pass weight_set_id or inline weights on subsequent /api/run-demo, /api/search, or /api/export-physics calls.

Per-Tool Schemas

Exports share the same candidate objects, packaged per tool. Each candidate includes the fields returned by the dataset formatter.

                # Kreuzer-Skarke candidate fields

rank, h11, h21, euler_char, score, verified_target

# CY5-Folds candidate fields

rank, h11, h21, h31, euler_char, score, verified_target

# Heterotic candidate fields

rank, h11, h21, euler_char, hodge_balance, n_generations, score, verified_target

# CYTools / cymetric JSON wrapper

{ "schema": "cytools-candidates-v1", "run_metadata": {...}, "candidates": [ ... ] }

{ "schema": "cymetric-candidates-v1", "run_metadata": {...}, "candidates": [ ... ] }

# Sage output

candidates = [ { ... }, { ... } ]

# Mathematica output

candidates = {<| "rank" -> 1, "h11" -> 12, ... |>, ...};

Local Export Scripts

Use the adapter script to convert a saved results JSON file into tool-specific formats.

                python scripts/export_adapters.py --input static/data/results_RUN_ID.json --format cytools --output cytools.json

python scripts/export_adapters.py --input static/data/results_RUN_ID.json --format cymetric --output cymetric.json

python scripts/export_adapters.py --input static/data/results_RUN_ID.json --format sage --output candidates.sage

python scripts/export_adapters.py --input static/data/results_RUN_ID.json --format mathematica --output candidates.wl

Bring Your Own Data

Paste custom candidates as CSV rows in the Run page. Each row must include all feature columns for the selected dataset in order:

Kreuzer-Skarke: h11, h21, euler_abs, hodge_ratio, c2_h11
CY5-Folds: h11, h21, h31, euler, euler_abs, hodge_sum
Heterotic: h11, h21, euler, euler_abs, hodge_ratio, hodge_balance, n_gen
Info-density / F-theory: see Run page column hint for the selected dataset

Draft note

Honest landscape dossiers — draft note on honest ML, topological certificates, and how to cite a candidate (Markdown).

Reproducibility Guarantees

Fixed Random Seeds

All stochastic operations (model training, data shuffling) use deterministic seeds. Default seed is 42.

Pinned Dependencies

The requirements.txt file pins exact versions of all Python packages to ensure identical runtime environments (Python 3.11).

Run Metadata

Every API run returns metadata including timestamp, dataset id, checksum slice, held-out features, and seeds. Shareable results are stored under static/data/results_*.json.