wcc-etc

Exposure Time Calculator (ETC) for the Widefield Context Camera on Lazuli.

A web-based ETC is available here: https://simulators.schmidtobservatorysystem.org/wcc/

Installation

1. Clone the Repository

git clone https://github.com/schmidt-observatories/wcc-etc.git
cd wcc-etc

2. Install the Package

Core install:

pip install -e .

The transit models come from lazuli-exo (lazuli_exo.transit), pulled in as a dependency.

With optional extras:

pip install -e ".[dev]"    # development tools (pytest, ruff, mypy, pre-commit)
pip install -e ".[docs]"   # documentation build (Sphinx, nbsphinx, etc.)
pip install -e ".[lightcurve]"   # transit light-curve modelling (jaxoplanet)
pip install -e ".[exoarchive]"   # NASA Exoplanet Archive queries

Quick Start

import numpy as np
from wcc_etc import get_scene, Simulation

# Create a simple scene (stellar source only)
scene = get_scene("K3IV", mag=20, host=None, background="zodi")

# Create a simulation for a sensor (kind:band format) and the scene
sim = Simulation.from_sensor_and_scene("sony:bb", scene)

# Compute SNR for a single exposure time (seconds). get_snr uses the 2D image
# simulation and returns a dict; ["snr"] is the signal-to-noise ratio.
snr = sim.get_snr(10)["snr"]

# Update scene or instrument parameters (example: change source magnitude)
sim.update(source__mag=22)

# Recompute SNR after the change
snr_new = sim.get_snr(10)["snr"]

# Plot SNR vs exposure time, or the peak pixel against the saturation ceiling
sim.plot_snr(np.linspace(1, 300, 100))
sim.plot_peak_pixel(np.logspace(-1, 3, 200))

# A transient on a galaxy: give the host a Sersic profile (arcsec / degrees).
# mag is the total host magnitude; dx/dy offset the source from the nucleus.
scene = get_scene(
    "G5V", mag=21,
    host="G5V",
    host_prop={"mag": 16, "profile": "sersic", "r_eff": 0.5, "n": 4, "dx": 0.3},
)

Tutorial

See the notebooks/ directory for example tutorials:

Known limitations (0.1.0)

• The zodiacal background is a fixed V = 22.5 mag/arcsec² (Vega) with no dependence on ecliptic latitude, solar elongation or season. The L3 requirement value is 22.1 (#98).
• The noise model has photon, dark and read terms only: no systematic floor (flat field, intrapixel × jitter, gain drift), no sky-estimation variance, no cosmic rays, no stray-light background (#100).
• The pupil is unobscured (correct for the WCC) but there is no wavefront-error / Strehl term, so the in-focus Airy PSF is diffraction-perfect and peak-pixel fractions (hence saturation limits) are optimistic (#99).
• Not yet validated against as-measured detector, throughput, PSF or on-sky data (#104).

Notes

Configuration files (.toml) are in the src/wcc_etc/data/config/ directory. Notebooks show that it is easy to change default configuration parameters on the fly.

Documentation

The full documentation site (installation, a user guide, rendered tutorial notebooks, and an auto-generated API reference) is built with Sphinx and the Read the Docs theme. It lives under docs/sphinx/:

pip install -e ".[docs]"   # Sphinx + theme + nbsphinx (+ the package itself)
brew install pandoc        # or: conda install pandoc / apt-get install pandoc
cd docs/sphinx
make html                  # output in _build/html/index.html

A .readthedocs.yaml is included so the site builds automatically once the repository is connected to Read the Docs.

Releasing

Releases are tag-driven (.github/workflows/publish.yml); nothing is uploaded by hand.

1. Bump version in pyproject.toml and move the Unreleased entries in docs/changelog.md under the new version.
2. Tag and push. A tag containing rc (for example v0.1.0rc1) publishes to TestPyPI; a plain vX.Y.Z tag publishes to PyPI.
3. CI checks that the tag matches the version, that no dependency is a direct URL (PyPI rejects those), builds and audits the artifacts, and installs the wheel in a fresh venv before publishing.

Trusted publishing is used, so there are no API tokens: the repository, workflow file and GitHub environment (pypi, testpypi) are registered once on each index.