SPISEA Web — Cluster CMD Explorer

A small web app that wraps SPISEA with a FastAPI backend and a React + Vite + TypeScript frontend so you can explore synthetic clusters, isochrones, color–magnitude diagrams, and unresolved spectra interactively in the browser.

This repository is a thin client around the SPISEA Python package. It does not modify or vendor SPISEA — spisea must be importable in the Python environment that runs the backend.

Originally created for Dan Weisz's Stellar Pops class. Code and documentation generated with support from Cursor.

Requirements

• Python 3.10+ (the backend uses PEP 604 union syntax such as list[str] | None).
• Node.js 18+ and npm for the frontend.
• A working SPISEA install plus its data dependencies. See SPISEA's setup notes for the full list. At a minimum you need:
  • pysynphot and a CDBS data tree (typically pointed to via PYSYN_CDBS)
  • SPISEA's evolution / atmosphere model data (SPISEA_MODELS)
  • SPISEA's filt_func/ directory (SPISEA_FILT_FUNC, see below)
• The COSMIC evolution model is optional. To use it (and edit its BSEDict binary-evolution parameters in the UI) you must also install COSMIC (pip install cosmic-popsynth) in the backend environment. COSMIC evolves binaries directly, so it requires a multiplicity model; the IFMR and unresolved-spectrum options are ignored when it is selected.

Installing SPISEA

The backend imports spisea directly. Pick one of:

# Option 1: install from GitHub (cleanest for deployments)
pip install git+https://github.com/astropy/SPISEA.git

# Option 2: install an editable copy from a local SPISEA checkout
pip install -e /path/to/SPISEA

If you use Option 1, the SPISEA filt_func/ data directory (which lives at the SPISEA repo root, not inside the spisea/ package) will not be present. In that case set SPISEA_FILT_FUNC to point at a filt_func/ directory from a SPISEA checkout, e.g.:

export SPISEA_FILT_FUNC=/path/to/SPISEA/filt_func

If you use Option 2, the bridge auto-discovers filt_func/ next to the SPISEA checkout, so SPISEA_FILT_FUNC is optional.

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# plus SPISEA itself, see above
uvicorn app.main:app --reload --port 8000

The API listens on http://127.0.0.1:8000 and exposes /api/meta, /api/cluster, /api/cluster-fits, /api/cluster-fits-batch, /api/cluster-notebook, and /api/isochrone-cmd.

Useful environment variables

Variable	Purpose
SPISEA_FILT_FUNC	Path to SPISEA's filt_func/ directory (filter discovery).
PYSYN_CDBS	CDBS root for pysynphot (atmosphere & throughput tables).
SPISEA_MODELS	SPISEA evolution/atmosphere model directory.
SPISEA_WEB_ISO_DIR	Where the backend caches IsochronePhot FITS files.
SPISEA_WEB_CDBS_FILTER_MAX	Cap on CDBS throughput files enumerated for filter list.

Tests

cd backend
pytest

The API tests reuse SPISEA's bundled isochrone fixtures via os.path.dirname(spisea.__file__)/tests/isochrones, so they require an installed SPISEA whose tests/isochrones/ directory is present (e.g. an editable install from a SPISEA git checkout).

Frontend

cd frontend
npm install
npm run dev

Vite serves on http://127.0.0.1:5173 and proxies /api/* to the backend at http://127.0.0.1:8000 (see frontend/vite.config.ts).

For a production build:

npm run build
npm run preview

Layout

spisea-web/
  backend/            FastAPI app + SPISEA bridge
    app/
      main.py         FastAPI routes
      bridge.py       SPISEA object construction, isochrone cache, serializers
      models.py       Pydantic request/response models
      web_filter_aliases.py
    tests/
    requirements.txt
  frontend/           React + Vite + TS SPA
    src/App.tsx       Main UI (CMD, mass function, spectrum panels)
    vite.config.ts    Dev proxy to the backend

License

GPL v3+ (see LICENSE). SPISEA itself is GPL v3+.