wcc-sim 0.1.0__tar.gz

wcc_sim-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Schmidt Observatories
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wcc_sim-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: wcc-sim
+Version: 0.1.0
+Summary: End-to-end photometric image simulator for the Lazuli Wide-field Context Camera (WCC)
+Author-email: Gudmundur Stefansson <gstefansson@schmidtsciences.org>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/schmidt-observatories/wcc-sim
+Project-URL: Documentation, https://wcc-sim.readthedocs.io/
+Project-URL: Issues, https://github.com/schmidt-observatories/wcc-sim/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wcc_etc>=0.1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: astropy>=5.3
+Requires-Dist: astroquery>=0.4.7
+Requires-Dist: synphot>=1.2
+Requires-Dist: photutils>=2.0
+Requires-Dist: dust_extinction>=1.2
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Dynamic: license-file
+
+![Logo](docs/logo_schmidt_observatory_system.png)
+
+[![Tests](https://github.com/schmidt-observatories/wcc-sim/actions/workflows/tests.yml/badge.svg)](https://github.com/schmidt-observatories/wcc-sim/actions/workflows/tests.yml)
+
+# wcc-sim
+End-to-end image simulator and differential-photometry pipeline for the
+Wide-field Context Camera (WCC) on Lazuli.
+
+`wcc-sim` queries Gaia DR3 for a pointing, converts Gaia photometry to detector
+count rates through the [wcc-etc](https://github.com/schmidt-observatories/wcc-etc)
+instrument model, renders every star with the in-focus (Airy) or +1/+2-wave
+defocus (Zemax Huygens) PSF plus its diffraction wings and the scattered-light
+halo, adds photon/sky/dark/read noise with full-well and ADC saturation, and
+writes a multi-extension FITS image (SCI + SATMASK + CAT + CLEAN) with a TAN
+WCS. The sibling `wcc-phot` package extracts a relative light curve from a
+series of such frames.
+
+# Installation
+
+```sh
+pip install wcc-sim
+```
+
+[`wcc_etc`](https://pypi.org/project/wcc-etc/) provides the instrument model
+and is pulled in from PyPI as a dependency. From source:
+```sh
+git clone https://github.com/schmidt-observatories/wcc-sim.git
+cd wcc-sim
+pip install -e .
+```
+
+With optional extras:
+```sh
+pip install -e ".[test]"   # pytest
+pip install -e ".[docs]"   # documentation build (Sphinx, nbsphinx, etc.)
+```
+
+Python 3.11 or newer is required. A default run queries the Gaia archive, so
+it needs network access. Pass `cache_dir=` (CLI: `--cache-dir`) to keep the
+Gaia result on disk so repeat runs work offline.
+
+# Quick Start
+
+```python
+from wcc_sim import simulate_field
+
+# Simulate one 90 s frame of the field at (RA, Dec) = (150.1, 2.2) deg on the
+# Sony IMX455 detector in the r band, +1 wave defocused, and save it as FITS.
+field = simulate_field(150.1, 2.2, sensorfilter="zwo:r", focus=1,
+                       exptime=90, seed=42, output="field_1wave.fits")
+
+field.image_adu       # the detector image (ADU)
+field.catalog         # the Gaia table with pixel positions and count rates
+field.params          # everything the run used (rates, noise, PSF, wing floor)
+field.plot(catalog=True)      # the image with the catalog circled (ax=None -> new figure)
+field.plot_psf_profile()      # Airy core, scatter halo and the rendered radial profile
+```
+
+The same from the command line:
+```sh
+wcc-sim --ra 150.1 --dec 2.2 --sensorfilter zwo:r --focus 1 \
+        --exptime 90 --seed 42 -o field_1wave.fits
+```
+
+Then recover a light curve from a series of frames of the same field:
+```python
+from wcc_phot import run_photometry
+
+result = run_photometry(["f0.fits", "f1.fits", "f2.fits"], target=(150.1, 2.2),
+                        method="aperture", n_ref=10)
+result.lightcurve     # per frame: rel_flux_norm, errors, flags
+result.plot()         # the relative light curve; result.plot_field(frame), .report(path)
+```
+```sh
+wcc-phot f*.fits --ra 150.1 --dec 2.2 --method psf -o phot.fits --report report.pdf
+```
+
+`sensorfilter` is `kind:band` as in wcc-etc: `zwo:*` is the Sony IMX455
+(9568 x 6380 px, 16.87 mas/pix) and `qcmos:*` the Hamamatsu HWK4123
+(4096 x 2304 px, 20.64 mas/pix). `focus=0|1|2` selects in-focus, +1 wave or
++2 waves of defocus. `extended_sources=[SersicComponent(...)]` adds analytic
+galaxy light and `chromatic=True` switches to spectrum-weighted PSFs (in focus
+only).
+
+# Tutorial
+See the `notebooks/` directory for example tutorials (executed outputs
+included; the Gaia queries they need are cached in `notebooks/gaia_cache/`,
+so they run offline):
+
+| Notebook | What it covers |
+|---|---|
+| `01_getting_started.ipynb` | Simulate a full frame, overlay the Gaia catalog, compare the three PSF modes on one star, and write the FITS file. |
+| `02_verification.ipynb` | The checks: PSF peak ordering, astrometric residuals, photometric closure on the ETC rates, noise statistics, saturation flags, and the FITS round trip. |
+| `03_psf_focus_modes.ipynb` | In-focus Airy vs +1/+2-wave defocus PSFs and what they do to peak pixel and saturation. |
+| `04_detectors_and_filters.ipynb` | The two detectors, the filter sets, and Gaia-to-count-rate conversion per spectral type. |
+| `05_noise_and_saturation.ipynb` | Photon, sky, dark and read noise; full well and ADC clipping; the SATMASK extension. |
+| `06_astrometry_and_catalogs.ipynb` | The TAN WCS and its round trip, where stars land, position angle, edges and user-supplied catalogs. |
+| `07_cli_and_fits.ipynb` | The `wcc-sim` command line and the layout of the output FITS file. |
+| `08_psf_wings.ipynb` | Diffraction wings beyond the PSF stamp: the wing model, seam smoothness, encircled energy and how far stars extend. |
+| `09_wcc_phot_photometry.ipynb` | `wcc-phot`: simulate a dithered series, pick a target, aperture and PSF photometry, centroid drift, the live viewer. |
+| `10_plotting.ipynb` | Every `.plot_*` method once: images with catalog and saturation overlays, cutouts, the PSF radial profile, stamps, encircled energy, the photometry panels. |
+
+Ready-to-run CLI examples are in `scripts/example_*.sh`. Two end-to-end
+validations live next to them: `scripts/transit_trappist1b.py` injects the
+TRAPPIST-1b transit into the Gaia catalog, simulates 36 x 300 s defocused
+frames, runs `wcc-phot` and checks the recovered depth; `scripts/cepheids_m101.py`
+places synthetic Cepheids on the M101 disk (Sersic galaxy light plus the real
+Gaia foreground) and recovers a period-luminosity relation.
+
+# Notes
+Instrument configuration (detectors, filters, throughput, PSFs, the stray-light
+model) comes from wcc-etc and is not duplicated here. The one data product
+wcc-sim ships is the azimuthally averaged scattered-light profile in
+`src/wcc_sim/data/psfs/`, regenerated by `scripts/build_scatter_profile.py`.
+
+## Model assumptions and validation status
+
+wcc-sim takes its instrument model from wcc-etc. Some choices in that model
+are deliberate margins or simplifications rather than best estimates, and
+they move the numbers you get:
+
+- **Read noise carries a x2 margin.** Both detector configurations multiply
+  the datasheet read noise by `read_noise_margin = 2` to cover unmodelled
+  noise sources (RTS, non-linearity), and every simulated frame inherits it.
+  In a 90 s `zwo:r` frame most of the per-pixel variance is read noise, so
+  faint-source depth is about 0.6 mag shallower than the datasheet value
+  would give. There is no switch for it yet (issue #23).
+- **Unobscured pupil.** The collecting area is pi (D/2)^2 and the in-focus
+  Airy PSF has no central obscuration or spiders. The defocused PSFs are
+  Zemax Huygens images of the real system.
+- **Constant zodiacal background** at V = 22.5 mag/arcsec^2, with no
+  dependence on ecliptic latitude or Sun angle.
+- **Gaia G normalisation** uses a synthetic Vega-system zero point about 1%
+  below the published DR3 value, so all count rates are about 1% low.
+- **The scattered-light halo is monochromatic.** It comes from a single
+  450 nm stray-light run and is applied with the same shape and fraction in
+  every band; surface scatter falls with wavelength, so the halo is
+  over-predicted in the red bands.
+- **"N waves" of defocus** is a Fringe Zernike Z4 coefficient of N waves
+  (2N waves peak-to-valley), the convention of the Zemax runs.
+
+Not modelled: cosmic rays, PRNU, non-linearity, random telegraph noise,
+charge diffusion and intrapixel response, Earthshine, the pointing dependence
+of the zodiacal light, and giant or reddened-star templates (every star gets
+a dwarf template).
+
+**Validation status.** The count-rate chain, PSF energy, astrometry and
+noise model have been checked against first-principles calculations and
+against the wcc-etc exposure-time calculator, including a Monte Carlo
+cross-check of the ETC's signal and noise predictions on simulated frames.
+Nothing has yet been compared with measured data; issue #25 holds the plan.
+
+## Documentation
+
+The full documentation site (installation, a user guide, rendered tutorial
+notebooks, a CLI reference and an auto-generated API reference) is built with
+**Sphinx** and the *Read the Docs* theme. It lives under `docs/sphinx/`:
+
+```bash
+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
+```
+
+The rendered site is published on Read the Docs at
+<https://wcc-sim.readthedocs.io/>; `.readthedocs.yaml` configures the build.
+
+## Tests
+
+```sh
+pip install -e ".[test]"
+python -m pytest
+```
+
+## Acknowledgements
+This work has made use of data from the European Space Agency (ESA) mission
+*Gaia* (https://www.cosmos.esa.int/gaia), processed by the Gaia Data
+Processing and Analysis Consortium (DPAC); the Gaia tables redistributed in
+`notebooks/gaia_cache/` are subject to the
+[Gaia data credits](https://www.cosmos.esa.int/web/gaia-users/credits).
+Stellar spectra are the Pickles (1998, PASP 110, 863) library; the Gaia
+passbands come from the SVO Filter Profile Service (Rodrigo & Solano 2020,
+http://svo2.cab.inta-csic.es/theory/fps/); reddening uses the Fitzpatrick
+(1999) curve via [dust_extinction](https://dust-extinction.readthedocs.io).
+Simulations are built on [Astropy](https://www.astropy.org),
+[photutils](https://photutils.readthedocs.io) and
+[synphot](https://synphot.readthedocs.io).

wcc_sim-0.1.0/README.md

@@ -0,0 +1,188 @@
+![Logo](docs/logo_schmidt_observatory_system.png)
+
+[![Tests](https://github.com/schmidt-observatories/wcc-sim/actions/workflows/tests.yml/badge.svg)](https://github.com/schmidt-observatories/wcc-sim/actions/workflows/tests.yml)
+
+# wcc-sim
+End-to-end image simulator and differential-photometry pipeline for the
+Wide-field Context Camera (WCC) on Lazuli.
+
+`wcc-sim` queries Gaia DR3 for a pointing, converts Gaia photometry to detector
+count rates through the [wcc-etc](https://github.com/schmidt-observatories/wcc-etc)
+instrument model, renders every star with the in-focus (Airy) or +1/+2-wave
+defocus (Zemax Huygens) PSF plus its diffraction wings and the scattered-light
+halo, adds photon/sky/dark/read noise with full-well and ADC saturation, and
+writes a multi-extension FITS image (SCI + SATMASK + CAT + CLEAN) with a TAN
+WCS. The sibling `wcc-phot` package extracts a relative light curve from a
+series of such frames.
+
+# Installation
+
+```sh
+pip install wcc-sim
+```
+
+[`wcc_etc`](https://pypi.org/project/wcc-etc/) provides the instrument model
+and is pulled in from PyPI as a dependency. From source:
+```sh
+git clone https://github.com/schmidt-observatories/wcc-sim.git
+cd wcc-sim
+pip install -e .
+```
+
+With optional extras:
+```sh
+pip install -e ".[test]"   # pytest
+pip install -e ".[docs]"   # documentation build (Sphinx, nbsphinx, etc.)
+```
+
+Python 3.11 or newer is required. A default run queries the Gaia archive, so
+it needs network access. Pass `cache_dir=` (CLI: `--cache-dir`) to keep the
+Gaia result on disk so repeat runs work offline.
+
+# Quick Start
+
+```python
+from wcc_sim import simulate_field
+
+# Simulate one 90 s frame of the field at (RA, Dec) = (150.1, 2.2) deg on the
+# Sony IMX455 detector in the r band, +1 wave defocused, and save it as FITS.
+field = simulate_field(150.1, 2.2, sensorfilter="zwo:r", focus=1,
+                       exptime=90, seed=42, output="field_1wave.fits")
+
+field.image_adu       # the detector image (ADU)
+field.catalog         # the Gaia table with pixel positions and count rates
+field.params          # everything the run used (rates, noise, PSF, wing floor)
+field.plot(catalog=True)      # the image with the catalog circled (ax=None -> new figure)
+field.plot_psf_profile()      # Airy core, scatter halo and the rendered radial profile
+```
+
+The same from the command line:
+```sh
+wcc-sim --ra 150.1 --dec 2.2 --sensorfilter zwo:r --focus 1 \
+        --exptime 90 --seed 42 -o field_1wave.fits
+```
+
+Then recover a light curve from a series of frames of the same field:
+```python
+from wcc_phot import run_photometry
+
+result = run_photometry(["f0.fits", "f1.fits", "f2.fits"], target=(150.1, 2.2),
+                        method="aperture", n_ref=10)
+result.lightcurve     # per frame: rel_flux_norm, errors, flags
+result.plot()         # the relative light curve; result.plot_field(frame), .report(path)
+```
+```sh
+wcc-phot f*.fits --ra 150.1 --dec 2.2 --method psf -o phot.fits --report report.pdf
+```
+
+`sensorfilter` is `kind:band` as in wcc-etc: `zwo:*` is the Sony IMX455
+(9568 x 6380 px, 16.87 mas/pix) and `qcmos:*` the Hamamatsu HWK4123
+(4096 x 2304 px, 20.64 mas/pix). `focus=0|1|2` selects in-focus, +1 wave or
++2 waves of defocus. `extended_sources=[SersicComponent(...)]` adds analytic
+galaxy light and `chromatic=True` switches to spectrum-weighted PSFs (in focus
+only).
+
+# Tutorial
+See the `notebooks/` directory for example tutorials (executed outputs
+included; the Gaia queries they need are cached in `notebooks/gaia_cache/`,
+so they run offline):
+
+| Notebook | What it covers |
+|---|---|
+| `01_getting_started.ipynb` | Simulate a full frame, overlay the Gaia catalog, compare the three PSF modes on one star, and write the FITS file. |
+| `02_verification.ipynb` | The checks: PSF peak ordering, astrometric residuals, photometric closure on the ETC rates, noise statistics, saturation flags, and the FITS round trip. |
+| `03_psf_focus_modes.ipynb` | In-focus Airy vs +1/+2-wave defocus PSFs and what they do to peak pixel and saturation. |
+| `04_detectors_and_filters.ipynb` | The two detectors, the filter sets, and Gaia-to-count-rate conversion per spectral type. |
+| `05_noise_and_saturation.ipynb` | Photon, sky, dark and read noise; full well and ADC clipping; the SATMASK extension. |
+| `06_astrometry_and_catalogs.ipynb` | The TAN WCS and its round trip, where stars land, position angle, edges and user-supplied catalogs. |
+| `07_cli_and_fits.ipynb` | The `wcc-sim` command line and the layout of the output FITS file. |
+| `08_psf_wings.ipynb` | Diffraction wings beyond the PSF stamp: the wing model, seam smoothness, encircled energy and how far stars extend. |
+| `09_wcc_phot_photometry.ipynb` | `wcc-phot`: simulate a dithered series, pick a target, aperture and PSF photometry, centroid drift, the live viewer. |
+| `10_plotting.ipynb` | Every `.plot_*` method once: images with catalog and saturation overlays, cutouts, the PSF radial profile, stamps, encircled energy, the photometry panels. |
+
+Ready-to-run CLI examples are in `scripts/example_*.sh`. Two end-to-end
+validations live next to them: `scripts/transit_trappist1b.py` injects the
+TRAPPIST-1b transit into the Gaia catalog, simulates 36 x 300 s defocused
+frames, runs `wcc-phot` and checks the recovered depth; `scripts/cepheids_m101.py`
+places synthetic Cepheids on the M101 disk (Sersic galaxy light plus the real
+Gaia foreground) and recovers a period-luminosity relation.
+
+# Notes
+Instrument configuration (detectors, filters, throughput, PSFs, the stray-light
+model) comes from wcc-etc and is not duplicated here. The one data product
+wcc-sim ships is the azimuthally averaged scattered-light profile in
+`src/wcc_sim/data/psfs/`, regenerated by `scripts/build_scatter_profile.py`.
+
+## Model assumptions and validation status
+
+wcc-sim takes its instrument model from wcc-etc. Some choices in that model
+are deliberate margins or simplifications rather than best estimates, and
+they move the numbers you get:
+
+- **Read noise carries a x2 margin.** Both detector configurations multiply
+  the datasheet read noise by `read_noise_margin = 2` to cover unmodelled
+  noise sources (RTS, non-linearity), and every simulated frame inherits it.
+  In a 90 s `zwo:r` frame most of the per-pixel variance is read noise, so
+  faint-source depth is about 0.6 mag shallower than the datasheet value
+  would give. There is no switch for it yet (issue #23).
+- **Unobscured pupil.** The collecting area is pi (D/2)^2 and the in-focus
+  Airy PSF has no central obscuration or spiders. The defocused PSFs are
+  Zemax Huygens images of the real system.
+- **Constant zodiacal background** at V = 22.5 mag/arcsec^2, with no
+  dependence on ecliptic latitude or Sun angle.
+- **Gaia G normalisation** uses a synthetic Vega-system zero point about 1%
+  below the published DR3 value, so all count rates are about 1% low.
+- **The scattered-light halo is monochromatic.** It comes from a single
+  450 nm stray-light run and is applied with the same shape and fraction in
+  every band; surface scatter falls with wavelength, so the halo is
+  over-predicted in the red bands.
+- **"N waves" of defocus** is a Fringe Zernike Z4 coefficient of N waves
+  (2N waves peak-to-valley), the convention of the Zemax runs.
+
+Not modelled: cosmic rays, PRNU, non-linearity, random telegraph noise,
+charge diffusion and intrapixel response, Earthshine, the pointing dependence
+of the zodiacal light, and giant or reddened-star templates (every star gets
+a dwarf template).
+
+**Validation status.** The count-rate chain, PSF energy, astrometry and
+noise model have been checked against first-principles calculations and
+against the wcc-etc exposure-time calculator, including a Monte Carlo
+cross-check of the ETC's signal and noise predictions on simulated frames.
+Nothing has yet been compared with measured data; issue #25 holds the plan.
+
+## Documentation
+
+The full documentation site (installation, a user guide, rendered tutorial
+notebooks, a CLI reference and an auto-generated API reference) is built with
+**Sphinx** and the *Read the Docs* theme. It lives under `docs/sphinx/`:
+
+```bash
+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
+```
+
+The rendered site is published on Read the Docs at
+<https://wcc-sim.readthedocs.io/>; `.readthedocs.yaml` configures the build.
+
+## Tests
+
+```sh
+pip install -e ".[test]"
+python -m pytest
+```
+
+## Acknowledgements
+This work has made use of data from the European Space Agency (ESA) mission
+*Gaia* (https://www.cosmos.esa.int/gaia), processed by the Gaia Data
+Processing and Analysis Consortium (DPAC); the Gaia tables redistributed in
+`notebooks/gaia_cache/` are subject to the
+[Gaia data credits](https://www.cosmos.esa.int/web/gaia-users/credits).
+Stellar spectra are the Pickles (1998, PASP 110, 863) library; the Gaia
+passbands come from the SVO Filter Profile Service (Rodrigo & Solano 2020,
+http://svo2.cab.inta-csic.es/theory/fps/); reddening uses the Fitzpatrick
+(1999) curve via [dust_extinction](https://dust-extinction.readthedocs.io).
+Simulations are built on [Astropy](https://www.astropy.org),
+[photutils](https://photutils.readthedocs.io) and
+[synphot](https://synphot.readthedocs.io).

wcc_sim-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wcc-sim"
+version = "0.1.0"
+description = "End-to-end photometric image simulator for the Lazuli Wide-field Context Camera (WCC)"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Gudmundur Stefansson", email = "gstefansson@schmidtsciences.org" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "wcc_etc>=0.1.0",      # instrument model; public io names since 0.1.0
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "astropy>=5.3",
+    "astroquery>=0.4.7",
+    "synphot>=1.2",
+    "photutils>=2.0",      # ImagePSF
+    "dust_extinction>=1.2",
+    "matplotlib>=3.7",     # wcc_phot report/live view, wcc_sim.psfreport
+]
+
+[project.urls]
+Homepage = "https://github.com/schmidt-observatories/wcc-sim"
+Documentation = "https://wcc-sim.readthedocs.io/"
+Issues = "https://github.com/schmidt-observatories/wcc-sim/issues"
+
+[project.scripts]
+wcc-sim = "wcc_sim.cli:main"
+wcc-phot = "wcc_phot.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest", "ruff"]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+    "nbsphinx",
+    "myst-parser",
+    "ipykernel",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+wcc_sim = ["data/*", "data/psfs/*.ecsv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# `pytest -m "not slow"` skips the Monte Carlo cross-check (~30 s); nothing
+# in the suite needs the network, `network` is reserved for tests that will.
+markers = [
+    "slow: takes more than ~10 s (Monte Carlo cross-checks)",
+    "network: needs the Gaia archive or VizieR",
+]
+
+[tool.ruff.lint]
+# Pin the rule set so local runs and CI agree whatever ruff defaults do:
+# pyflakes plus the pycodestyle error classes ruff enables by default.
+select = ["E4", "E7", "E9", "F"]

wcc_sim-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wcc_sim-0.1.0/src/wcc_phot/__init__.py

@@ -0,0 +1,6 @@
+__version__ = "0.1.0"
+
+from .geometry import PhotGeometry  # noqa: E402,F401
+from .live import LiveViewer  # noqa: E402,F401
+from .pipeline import PhotometryResult, run_photometry  # noqa: E402,F401
+from .report import make_report  # noqa: E402,F401

wcc_sim-0.1.0/src/wcc_phot/apphot.py

@@ -0,0 +1,69 @@
+"""Aperture photometry with CCD-equation errors from the frame header rates."""
+
+import numpy as np
+from astropy.stats import SigmaClip
+from photutils.aperture import ApertureStats, CircularAnnulus, CircularAperture
+
+from .flags import FLAG_EDGE, FLAG_SATURATED
+
+
+def _saturated_within(satmask, x, y, radius):
+    """True if any saturated pixel lies within `radius` px of (x, y)."""
+    ny, nx = satmask.shape
+    r = int(np.ceil(radius))
+    x0, y0 = int(round(x)), int(round(y))
+    y_lo, y_hi = max(y0 - r, 0), min(y0 + r + 1, ny)
+    x_lo, x_hi = max(x0 - r, 0), min(x0 + r + 1, nx)
+    if y_lo >= y_hi or x_lo >= x_hi:
+        return False
+    return bool(satmask[y_lo:y_hi, x_lo:x_hi].any())
+
+
+def aperture_photometry_frame(frame, x, y, geom):
+    """Background-subtracted aperture fluxes at (x, y) on the electron image.
+
+    Returns (flux_e, flux_err_e, bkg_e_pix, flags). Background is the
+    sigma-clipped annulus median; the variance is Poisson of the star plus
+    the per-pixel background variance from the header rates
+    ((sky+dark)*exptime + n_reads*read_noise^2), including the
+    background-estimate term (area^2/n_annulus).
+    """
+    x = np.atleast_1d(np.asarray(x, dtype=float))
+    y = np.atleast_1d(np.asarray(y, dtype=float))
+    positions = np.column_stack([x, y])
+    aper = CircularAperture(positions, r=geom.r_ap)
+    annulus = CircularAnnulus(positions, r_in=geom.r_in, r_out=geom.r_out)
+
+    bkg = np.asarray(
+        ApertureStats(
+            frame.image_e, annulus, sigma_clip=SigmaClip(sigma=3.0)
+        ).median,
+        dtype=float,
+    )
+    raw = np.asarray(ApertureStats(frame.image_e, aper).sum, dtype=float)
+    area = aper.area
+    flux = raw - bkg * area
+
+    m = frame.meta
+    var_pix = (
+        (float(m["sky_e_s"]) + float(m["dark_e_s"])) * float(m["exptime"])
+        + int(m["n_reads"]) * float(m["read_noise"]) ** 2
+    )
+    variance = np.clip(flux, 0, None) + area * var_pix * (
+        1.0 + area / annulus.area
+    )
+    flux_err = np.sqrt(variance)
+
+    ny, nx = frame.image_e.shape
+    flags = np.zeros(x.size, dtype=int)
+    edge = (
+        (x < geom.r_out)
+        | (x > nx - 1 - geom.r_out)
+        | (y < geom.r_out)
+        | (y > ny - 1 - geom.r_out)
+    )
+    flags[edge] |= FLAG_EDGE
+    for i in range(x.size):
+        if _saturated_within(frame.satmask, x[i], y[i], geom.r_ap):
+            flags[i] |= FLAG_SATURATED
+    return flux, flux_err, bkg, flags

wcc_sim-0.1.0/src/wcc_phot/centroid.py

@@ -0,0 +1,41 @@
+"""Per-frame re-centroiding of WCS-predicted star positions.
+
+Center-of-mass (not a Gaussian fit) because the +1/+2-wave defocus PSFs are
+centrally-depressed donuts; COM in a box sized to the PSF works for both.
+"""
+
+import warnings
+
+import numpy as np
+from photutils.centroids import centroid_com, centroid_sources
+
+from .flags import FLAG_CENTROID
+
+
+def centroid_stars(frame, x0, y0, box):
+    """Refine (x0, y0) with a background-subtracted COM in a `box` px window.
+
+    Returns (x, y, flags); a failed or runaway centroid (>box px from the
+    start) falls back to the input position with FLAG_CENTROID set.
+    """
+    x0 = np.atleast_1d(np.asarray(x0, dtype=float))
+    y0 = np.atleast_1d(np.asarray(y0, dtype=float))
+    data = frame.image_e - np.median(frame.image_e)
+    ny, nx = data.shape
+    x_start = np.clip(x0, 0, nx - 1)
+    y_start = np.clip(y0, 0, ny - 1)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")  # partial-overlap warnings at edges
+        x, y = centroid_sources(
+            data, x_start, y_start, box_size=box, centroid_func=centroid_com
+        )
+    flags = np.zeros(x0.size, dtype=int)
+    bad = (
+        ~np.isfinite(x)
+        | ~np.isfinite(y)
+        | (np.hypot(x - x_start, y - y_start) > box)
+    )
+    flags[bad] |= FLAG_CENTROID
+    x[bad] = x0[bad]
+    y[bad] = y0[bad]
+    return x, y, flags