Quick Start

Quick Start

Move from a working installation to your first fitted spectrum with the smallest number of decisions.

Begin with Installation if the local environment is not yet set up.

---

Overview

Speculate exposes several tools, but most users only need one or two for any given task. This page lays out the shortest viable route through the suite for the most common goals: a quick-look fit on a hosted Space, a full local fit with GP plus MCMC, or a fast point estimate with the lightweight Quick Fit surrogate.

The local app and the public HuggingFace Space share the same notebooks, but the Space deliberately exposes only the lightweight tools. Choose the path that matches your environment.

Choose A Path

Goal	Recommended path
Browse a published grid or run a quick-look fit without installing	Open the HuggingFace Space and use Grid Inspector or Quick Fit
Get a fast point estimate from your own observation, locally	Quick Fit (Stages 1–4 self-contained)
Produce a full posterior for publication	Training Tool → Inference Tool (MLE then MCMC)
Audit emulator quality	Benchmark Suite

Local Five-Minute Startup

1. Activate the environment created during Installation:

   source speculate_env/bin/activate     # or: conda activate speculate_env

2. Launch the app from the repository root:

   python run.py

   run.py defaults to port 8080 and opens a browser. If 8080 is taken it picks a random free port between 8000 and 8800. To override:

   python run.py --port 7860

3. The Home tab should display Local Mode Active with the full sidebar (Home, Model Downloader, Grid Inspector, Training Tool, Inference Tool, Quick Fit, Benchmark Suite). If only Home, Grid Inspector, and Quick Fit appear, you are in HuggingFace simulation mode — see Home Tab.

First Local Workflow

A typical first session looks like this:

1. Use Model Downloader to fetch a published Sirocco grid into sirocco_grids/.
2. Open Grid Inspector to confirm the grid contents and wavelength coverage and to overlay any observation you intend to fit.
3. Choose a fitting path:
   • Quick Fit for a fast NN or grid-interpolation surrogate plus χ² point estimate.
   • Training Tool to build a Gaussian-process emulator, then Inference Tool for MLE and MCMC posterior sampling.
4. Review emulator quality in the Benchmark Suite when the result matters scientifically.

Hosted Quick-Look Path

The HuggingFace deployment is bandwidth-bound and locked to lightweight operations:

• Available: Home Tab, Grid Inspector, Quick Fit.
• Locked: Model Downloader, Training Tool, Inference Tool, Benchmark Suite.

Quick Fit on the Space cannot train new models — it auto-caches the small pre-trained Quick Fit .npz files and loads them locally. For anything beyond inspection or pre-trained χ² fits, switch to a local install.

Working Directories

Speculate uses these directories under the repository root:

Directory	Holds
sirocco_grids/	Downloaded and decompressed raw Sirocco spectra
Grid-Emulator_Files/	Processed grids, trained GP emulators, Quick Fit models
observation_files/	Uploaded or staged observation CSVs
exports/	Quick Fit and Inference Tool exports (.csv, .json, .pf)
benchmark_results/	Saved benchmark JSON reports

Observation tables must contain at least Wavelength and Flux columns; an optional error column supplies per-pixel uncertainty. Without error, Speculate uses a continuum-based fallback documented per tool.

Where To Go Next

• Quick Fit — fastest path to a fitted spectrum.
• Inference Tool — full posterior workflow with MCMC.
• Troubleshooting, FAQ, and Glossary — cross-cutting notes and terminology.