User Guide

A practical walkthrough of the Refined Index Calculator — from loading a SnapPy census manifold to publishing a pre-computed data pack. Written against v1.1.4.

Overview

The app has two modes, selectable from the buttons in the top-right of the window:

Calculator — the primary workflow. Load a single manifold and step through four cards: Manifold → Refined Index → Dehn Filling → Export. Results update live; you can ⌘+Enter to run the current card or press Run All to execute every card top-to-bottom.
Data Hub — manage pre-computed caches. Download shared data packs from GitHub Releases, generate your own kernel / I^ref / NC-cycle caches at scale, or bundle yours up and publish them for others to use.

Every result is cached to disk under ~/.manifold_index/ (macOS & Linux) or %APPDATA%\manifold_index\ (Windows), so reopening a session is instant and repeat computations hit the cache rather than recomputing.

First launch

On first launch the app creates its cache directory and opens in Calculator mode with all four cards collapsed. To get a quick end-to-end result:

Click the Manifold card header to expand it.
Type m004 in the name field and click Load. (The field auto-completes from the SnapPy census.)
Press the Run All button at the top of the window. The app loads the manifold, computes the refined index, and stops at the Dehn Filling card waiting for slopes.

Tip. The first computation for any manifold is the slowest — it builds the underlying kernel cache. Subsequent runs reuse the cache and finish in seconds.

Calculator mode

Each of the four cards is independently collapsible and shows a status tag in its header: Ready, Running, Done ✓, or Error. A card only runs once its inputs are valid and any required upstream cards have completed.

① Manifold

Loads a cusped hyperbolic 3-manifold and fixes the computation's global truncation parameter.

Field	Meaning
Manifold name	Any name SnapPy accepts — census label (`m004`, `s776`), knot (`4_1`, `K12n123`), or a link complement such as `L6a1`.
Nmax	The truncation level used throughout the pipeline. Higher N gives more terms of the q-series but costs quadratically more time and memory. N = 10 is a reasonable default for exploration.

On the Nmax choice. The refined index is computed as a q-series truncated at q^N. If you are checking identities or looking for cancellation patterns, start at N = 10, verify the pattern, then re-run at higher N only if you need confirmation.

② Refined Index

Computes the refined (q, t)-index I(m, e) over a rectangular lattice of (m, e) values and renders it in α / β basis notation.

Field	Meaning
P ∈ [−P, P]	Symmetric range for the charge variable m. The app enforces Weyl symmetry, so only non-negative m is actually evaluated; negative values are read off by reflection.
Q ≤ Qmax	Upper bound for the flux variable e. Together with P this defines the (m, e) grid.
Workers	Number of parallel worker threads used for the computation. Set to the number of physical CPU cores (not hyperthreads). The default auto-detects.

Results are displayed as a table of (m, e) ↔ q-series, with α and β basis labels in the header. Click any cell to copy the raw LaTeX of that series to the clipboard.

③ Dehn Filling

Fills one or more cusps with (P, Q) slopes and returns the filled index, with an option to search systematically for non-closable cycles — slopes whose filled index is identically zero.

Single fill

The card shows one row per cusp. Set m and e for each unfilled cusp; cusps left blank are treated as closed. The result is the filled q-series plus a Weyl compatibility diagnostic indicating whether the chosen slope respects the manifold's symmetries.

NC-cycle search

Use this to find slopes whose contributions cancel. Set the search rectangle (P range, Q max) and workers, then click Search. Progress is live — the card shows Tested X / Y slopes… and you can Stop at any time without losing partial results.

The auto-Weyl check (when enabled) runs in parallel and filters out slopes that would fail the compatibility test anyway, speeding the search substantially for manifolds with high symmetry.

Collapsed edges. Some manifold triangulations produce degenerate edges on certain slopes. The app detects these, marks the affected slopes with ✗ in the results, and skips them — you don't need to filter manually.

④ Export

Saves the pipeline's output as JSON, LaTeX, or a rendered PDF report.

Field	Meaning
Format	`json` (machine-readable, round-trippable), `tex` (LaTeX source for inclusion in a paper), or `pdf` (auto-compiled if a TeX distribution is on your PATH).
Output	Destination folder. Defaults to `~/Desktop/ManifoldIndex_exports/`; click the folder icon to choose another.

If PDF compilation fails (no TeX installed, missing package, etc.), the app shows the last 40 lines of the compiler log so you can diagnose without leaving the app.

Data Hub

Switch to Data Hub from the top-right button. It has three tabs.

Download

Lists all data packs registered in the public registry. Each pack is a .tar.gz of pre-computed caches — kernels, refined indices, or NC-cycle search results — that someone has published to a GitHub Release.

Search / Filter by manifold name, census, or data type.
Select one or more packs and click Download. Downloads run sequentially with per-pack progress; you can pause or cancel at any time.
Downloaded packs are extracted into the appropriate cache subdirectory automatically (kernel_cache/, iref_cache/, or nc_cycle_cache/).

When to download vs. generate. If a pack exists that covers the range you need (right N_max, right P / Q bounds), downloading is faster — frequently by orders of magnitude. The Generate tab is for ranges or manifolds no-one has published yet.

Generate

Batch-generates caches across a range of manifolds. Choose the Data Type (kernels, I^ref, or NC cycles), the Census and manifold filter, and the computation parameters. Press Start.

Jobs run one at a time in a queue; the currently-running job shows live progress.
Pause / Resume keeps the queue; Cancel stops the current job and marks it cancelled in the queue row.
The queue is coverage-aware: jobs that overlap with an existing cache are skipped automatically. Re-running with a wider range computes only the uncovered grid.

Export & Share

Packages local caches into a shareable .tar.gz data pack and (optionally) uploads it to a GitHub Release for inclusion in the registry.

Browse your local cache and tick the files to include. You can mix only files of the same type — packs are homogeneous so the downloader can file them correctly.
Fill in the pack metadata:
- Pack ID — machine-readable identifier (e.g. kernels-qq50). Required.
- Display name — human-readable title shown in the Download tab.
- Description — short blurb explaining coverage or intent.
- Release tag — the GitHub Release tag the pack will live on, e.g. data-v2.
Click Create archive. The tarball is written to disk and, if you provided a release tag, uploaded via gh release upload.
Open a PR on the registry repo adding the new pack's metadata so it appears in every user's Download tab.

Keyboard shortcuts

Shortcut	Action
`⌘`/`Ctrl`+`1`–`4`	Expand the corresponding card (Manifold / Index / Filling / Export).
`⌘`/`Ctrl`+`Enter`	Run the currently-expanded card.
`⌘`/`Ctrl`+`S`	Save session (manifold name, card inputs, expanded state) to the last path.
`⌘`/`Ctrl`+`⇧`+`S`	Save session as… (prompts for a new path).
`⌘`/`Ctrl`+`O`	Open a saved session.

Troubleshooting

Window title shows the wrong version

Fixed in v1.0.0. If you downloaded before 17 April 2026, grab the latest .zip / .exe from the download page — the old build bundled stale package metadata.

macOS: "ManifoldIndex.app cannot be opened because the developer cannot be verified"

The app is ad-hoc signed, not notarised. Run once:

xattr -cr /Applications/ManifoldIndex.app

Then launch normally. Or open System Settings → Privacy & Security and click Open Anyway next to the quarantined app.

Windows: SmartScreen blocks the exe

Click More info → Run anyway. The exe isn't signed with an EV certificate; SmartScreen will stop warning once enough people have run it without issue.

SnapPy census error on load

Some exotic manifold names require snap-py subpackages that aren't in every build. Check the status bar — if it says "census module not available", try a different census (e.g. m004 instead of o9_00000) or install from source where you can add the missing package to the dev environment.

Computation is unexpectedly slow

Check the Workers field on cards ②–③. The default usually auto-detects correctly, but on systems with aggressive CPU-throttling you may need to bump it manually. If the cache directory is on a network drive, move it to local SSD — the I/O patterns are small-random and perform badly over networks.

Still stuck? Open an issue on GitHub with your OS, the app version (shown in the window title), and the steps to reproduce. A screenshot of the error state is worth a thousand words.