From e7f4fffd25b6ce6dda97792ebbe23f5a115d7514 Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Sat, 14 Nov 2026 18:44:21 -0800 Subject: [PATCH 1/3] Add the Model Sky notebook and local guide preview Follow a modeled star from satellite-trail masking through motion and a planetary transit using cuPhoton. Keep the notebook output-free and generate data and interactive guide output outside the source tree. Signed-off-by: Trent Nelson --- .gitattributes | 3 +- examples/model-sky/.gitignore | 11 + examples/model-sky/PUBLISHING.md | 114 ++ examples/model-sky/README.md | 94 + examples/model-sky/assets/guide-head.html | 31 + examples/model-sky/assets/guide-include.html | 3 + examples/model-sky/assets/guide.css | 112 + examples/model-sky/assets/guide.js | 240 +++ examples/model-sky/assets/story-compare.svg | 83 + examples/model-sky/assets/story-field.svg | 80 + examples/model-sky/assets/story-motion.svg | 69 + examples/model-sky/assets/story-transit.svg | 66 + examples/model-sky/blend.py | 395 ++++ examples/model-sky/model-sky.ipynb | 1911 ++++++++++++++++++ examples/model-sky/model_sky.py | 243 +++ examples/model-sky/notebook_style.py | 108 + examples/model-sky/pipeline.py | 672 ++++++ examples/model-sky/preview.py | 216 ++ examples/model-sky/requirements.txt | 12 + examples/model-sky/run.py | 270 +++ examples/model-sky/scene.py | 627 ++++++ examples/model-sky/sources.md | 49 + examples/model-sky/tests/test_blend.py | 65 + examples/model-sky/tests/test_pipeline.py | 123 ++ examples/model-sky/tests/test_scene.py | 147 ++ examples/model-sky/tests/test_views.py | 42 + examples/model-sky/views.py | 1096 ++++++++++ examples/model-sky/workshop.py | 295 +++ 28 files changed, 7176 insertions(+), 1 deletion(-) create mode 100644 examples/model-sky/.gitignore create mode 100644 examples/model-sky/PUBLISHING.md create mode 100644 examples/model-sky/README.md create mode 100644 examples/model-sky/assets/guide-head.html create mode 100644 examples/model-sky/assets/guide-include.html create mode 100644 examples/model-sky/assets/guide.css create mode 100644 examples/model-sky/assets/guide.js create mode 100644 examples/model-sky/assets/story-compare.svg create mode 100644 examples/model-sky/assets/story-field.svg create mode 100644 examples/model-sky/assets/story-motion.svg create mode 100644 examples/model-sky/assets/story-transit.svg create mode 100644 examples/model-sky/blend.py create mode 100644 examples/model-sky/model-sky.ipynb create mode 100644 examples/model-sky/model_sky.py create mode 100644 examples/model-sky/notebook_style.py create mode 100644 examples/model-sky/pipeline.py create mode 100644 examples/model-sky/preview.py create mode 100644 examples/model-sky/requirements.txt create mode 100644 examples/model-sky/run.py create mode 100644 examples/model-sky/scene.py create mode 100644 examples/model-sky/sources.md create mode 100644 examples/model-sky/tests/test_blend.py create mode 100644 examples/model-sky/tests/test_pipeline.py create mode 100644 examples/model-sky/tests/test_scene.py create mode 100644 examples/model-sky/tests/test_views.py create mode 100644 examples/model-sky/views.py create mode 100644 examples/model-sky/workshop.py diff --git a/.gitattributes b/.gitattributes index 9b4730c3..0bf19937 100644 --- a/.gitattributes +++ b/.gitattributes @@ -35,5 +35,6 @@ *.pptx filter=lfs diff=lfs merge=lfs -text *.ipynb filter=lfs diff=lfs merge=lfs -text -# Keep this small, reviewed, output-free walkthrough readable in code reviews. +# Keep small, output-free walkthroughs readable in code reviews. /examples/imaging-pipeline/run_imaging_pipeline.ipynb -filter diff merge text eol=lf +/examples/model-sky/model-sky.ipynb -filter diff merge text eol=lf diff --git a/examples/model-sky/.gitignore b/examples/model-sky/.gitignore new file mode 100644 index 00000000..559842df --- /dev/null +++ b/examples/model-sky/.gitignore @@ -0,0 +1,11 @@ +# Generated inputs, execution records and rendered results. +data/ +results/ +output/ +model-sky-output/ +*.executed.ipynb +*.html +!assets/guide-include.html +!assets/guide-head.html +__pycache__/ +.pytest_cache/ diff --git a/examples/model-sky/PUBLISHING.md b/examples/model-sky/PUBLISHING.md new file mode 100644 index 00000000..3abee1de --- /dev/null +++ b/examples/model-sky/PUBLISHING.md @@ -0,0 +1,114 @@ + + + +# Publishing the Model Sky HTML + +The repository contains the output-free notebook and its helpers. The rendered +version includes cell outputs, six interactive figures, terminology hovers, +expandable explanations, equations and the guide's light/dark themes. + +This example currently provides a local export workflow. Adding it to the +automatically published, versioned guide requires the integration described +below. Merging the example alone does not add Model Sky to GitHub Pages. + +## Build and review an export + +1. Check out the committed revision you intend to publish. For a release, + use a tag that contains `examples/model-sky/`. Keep the checkout unchanged + through execution and rendering. +2. Prepare a CUDA 13 environment with this checkout's cuPhoton and the + additional dependencies in `requirements.txt`. Use a separate CPU docs + environment with Quarto, following [the docs instructions](../../docs/README.md). +3. Execute the notebook, including both optional investigations, then render + it inside the guide. Replace the environment and output paths below: + + ```sh + export MODEL_SKY_EXPORT=/absolute/path/outside/checkout/model-sky-export + /path/to/gpu-env/bin/python examples/model-sky/run.py \ + --output "$MODEL_SKY_EXPORT/reference" + /path/to/docs-env/bin/python examples/model-sky/preview.py \ + --executed "$MODEL_SKY_EXPORT/reference/model-sky.executed.ipynb" \ + --output "$MODEL_SKY_EXPORT/render" \ + --source-ref "$(git rev-parse HEAD)" + python -m http.server 8796 --bind 0.0.0.0 \ + --directory "$MODEL_SKY_EXPORT/render/guide/_book" + ``` + + The two output destinations must be new or empty. The renderer verifies the + successful execution receipt and source hashes before reusing outputs. + `--source-ref` controls the visible GitHub notebook link; that revision must + have been pushed for the link to work. +4. Open `http://localhost:8796/model-sky.html`. Check all six plots, glossary + hovers, expanded explanations, themes, mobile layout and source links. + Review the measurements and `reference/execution.json` as well as the page. + +## Share a downloadable HTML bundle + +Package the complete rendered directory so guide navigation and source +downloads work. Although the Model Sky page embeds its plot resources, its +navigation and downloads refer to other files in this directory. + +```sh +tar -czf "$MODEL_SKY_EXPORT/model-sky-guide.tar.gz" \ + -C "$MODEL_SKY_EXPORT/render/guide/_book" . +cp "$MODEL_SKY_EXPORT/reference/model-sky.executed.ipynb" \ + "$MODEL_SKY_EXPORT/model-sky.executed.ipynb" +cp "$MODEL_SKY_EXPORT/reference/execution.json" \ + "$MODEL_SKY_EXPORT/model-sky-execution.json" +( + cd "$MODEL_SKY_EXPORT" + sha256sum model-sky-guide.tar.gz model-sky.executed.ipynb \ + model-sky-execution.json > model-sky-SHA256SUMS +) +``` + +After reviewing the bundle, upload these four files as assets of the intended +GitHub Release. Use a release whose tag matches the source used above: + +```sh +gh release upload RELEASE_TAG --repo NVIDIA/cuPhoton \ + "$MODEL_SKY_EXPORT/model-sky-guide.tar.gz" \ + "$MODEL_SKY_EXPORT/model-sky.executed.ipynb" \ + "$MODEL_SKY_EXPORT/model-sky-execution.json" \ + "$MODEL_SKY_EXPORT/model-sky-SHA256SUMS" +``` + +Replace `RELEASE_TAG` with that existing release's tag. The command uploads +assets; it does not create or publish a software release. Keep existing assets +intact rather than replacing them. The generated FITS inputs are reproducible +from the example and are not required to view the HTML. Recipients can extract +the bundle and serve it with `python -m http.server`. + +## Publish a versioned GitHub Pages chapter + +Complete these changes in the developer tooling before enabling automatic +publication: + +1. Stage Model Sky from the selected source revision in `cuphoton dev + docs-build`. Accept an executed notebook with matching example hashes, + cuPhoton source revision and execution dependencies. Reuse its saved outputs + while executing ordinary CPU guide chapters; the builder's current global + `--execute` would try to rerun the GPU notebook in its CPU environment. +2. Pass the rendered guide through the existing version postprocessor and + `docs-check`. Retain the chapter's HTML includes as build inputs only. + Existing source-link conversion should map `main` links to release tags. +3. Add durable storage for the large rendered page and execution artifacts. + Keep a manifest of exact asset locations and hashes in `gh-pages`; restore + declared assets into the temporary deployment directory for every retained + version, then validate the complete site. The current publisher commits + every rendered file, so uploading Release assets alone does not avoid Git + growth. Main needs durable assets keyed to its source revision as well; + expiring PR artifacts and a mutable latest-release fallback are insufficient. +4. Validate a main build, a release containing the example, and an older + release without it. Check source links, navigation, search, version + switching, missing/corrupted assets and preservation of earlier snapshots. + Keep rendering, archive writing and Pages deployment in their existing + separate jobs. +5. Once that integration is merged and validated, use the normal main-push + publication workflow. For an eligible published release, use the existing + `cuphoton dev docs-publish --ref RELEASE_TAG` command when a manual dispatch + is needed. Verify the served chapter and source link after deployment. + +Expected routes are `main/model-sky.html` and, for releases that contain this +example, `vX.Y.Z/model-sky.html` beneath the cuPhoton Pages site. Keep generated +notebooks, data and HTML out of source commits throughout this process. diff --git a/examples/model-sky/README.md b/examples/model-sky/README.md new file mode 100644 index 00000000..ac29a3f2 --- /dev/null +++ b/examples/model-sky/README.md @@ -0,0 +1,94 @@ + + + +# Model Sky + +Follow one star from a satellite-contaminated image through a motion +measurement and a simulated planetary transit. The notebook shows cuPhoton +reprojection (xRep), image matching and subtraction (xPois), and source +measurement (xFit), with interactive figures and explanations of the science. + +Every input is generated from declared models. The example downloads no +astronomical images or catalogs. Known simulation answers remain separate +from the measurement pipeline until the notebook's final reveal. See +[sources.md](sources.md) for the physical assumptions and references. + +## Run the notebook + +Use a Linux CUDA 13 cuPhoton environment with xRep, xPois and xFit available. +Install the example's additional dependencies, then generate the inputs: + +```sh +python -m pip install -r examples/model-sky/requirements.txt +cd examples/model-sky +python model_sky.py --output data +jupyter lab model-sky.ipynb +``` + +These optional example dependencies include `batman-package` (GPLv3) and +Bokeh, ipykernel, JupyterLab, jupyter-bokeh and nbclient (BSD 3-Clause). +scikit-image uses BSD 3-Clause with additional bundled per-file notices. +No third-party source code is vendored in this example. + +Run the cells in order. The source contains 20 code cells without saved +outputs. The short-baseline and blend investigations are initially opt-in. +The inputs occupy approximately 261 MB; generated data and results are +ignored by Git. Use a fresh data directory for preparation. + +`CUPHOTON_MODEL_SKY_DATA` and `CUPHOTON_MODEL_SKY_OUTPUT` override the default +`data/` and `results/` directories, relative to the notebook working directory. + +## Execute a complete reference + +From the repository root, using the GPU environment: + +```sh +python examples/model-sky/run.py --output /path/to/new/model-sky-reference +``` + +The destination must be absent or empty. This copies the example sources, +generates the inputs, and executes a fresh kernel with both investigations +enabled. It writes `model-sky.executed.ipynb`, the measurement results, and +an `execution.json` receipt containing hashes and environment information. +The source notebook and its opt-in defaults stay unchanged. + +To run the example's tests, install pytest in the same GPU development +environment and run this command from the repository root: + +```sh +python -m pytest examples/model-sky/tests +``` + +## Preview inside the user guide + +Use Quarto and the CPU documentation environment described in +[the documentation instructions](../../docs/README.md). The preview renderer +copies the existing guide and adds Model Sky to its navigation and homepage: + +```sh +python examples/model-sky/preview.py \ + --executed /path/to/model-sky-reference/model-sky.executed.ipynb \ + --output /path/to/new/model-sky-guide \ + --site-url http://localhost:8796/ +python -m http.server 8796 --bind 0.0.0.0 \ + --directory /path/to/model-sky-guide/guide/_book +``` + +Open `http://localhost:8796/model-sky.html`. The page retains cell outputs, +terminology hovers, expandable explanations, equations and all six Bokeh +figures. Plot controls run in the browser. Quarto supplies navigation, +search and the page theme; a small adapter connects plot themes and glossary +interactions to the page. + +The preview executes the guide's CPU examples and reuses the completed GPU +notebook outputs. It includes downloads of the unexecuted source notebook +and example files, plus a visible link to the notebook in NVIDIA/cuPhoton. +That link uses `main` by default; pass `--source-ref REF` to link to a branch, +tag or commit when reviewing unpublished changes. Rendering and serving do +not publish anything. + +The full executed notebook, generated images, data and rendered HTML belong +in build or release assets. Keep the notebook committed to Git output-free. + +See [Publishing the Model Sky HTML](PUBLISHING.md) for export commands, +Release-asset packaging and the remaining versioned Pages integration steps. diff --git a/examples/model-sky/assets/guide-head.html b/examples/model-sky/assets/guide-head.html new file mode 100644 index 00000000..3a5e94e4 --- /dev/null +++ b/examples/model-sky/assets/guide-head.html @@ -0,0 +1,31 @@ + + + diff --git a/examples/model-sky/assets/guide-include.html b/examples/model-sky/assets/guide-include.html new file mode 100644 index 00000000..2c8a5ed6 --- /dev/null +++ b/examples/model-sky/assets/guide-include.html @@ -0,0 +1,3 @@ + + + diff --git a/examples/model-sky/assets/guide.css b/examples/model-sky/assets/guide.css new file mode 100644 index 00000000..b0256424 --- /dev/null +++ b/examples/model-sky/assets/guide.css @@ -0,0 +1,112 @@ +/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */ +/* SPDX-License-Identifier: Apache-2.0 */ + +body.quarto-dark { + color-scheme: dark; + --model-sky-background: #0b1008; + --model-sky-panel: #121a0e; + --model-sky-panel-raised: #1a2514; + --model-sky-text: #f0f4eb; + --model-sky-green: #76b900; + --model-sky-accent: #b5ed39; + --model-sky-line: #2b3b20; + --model-sky-plot-background: #10180d; + --model-sky-plot-text: #f0f4eb; + --model-sky-plot-muted: #b7c9a9; + --model-sky-plot-border: #34472b; + --model-sky-plot-cyan: #67d5e5; + --model-sky-plot-pink: #ed91bd; + --model-sky-font: "NVIDIA Sans", ui-sans-serif, system-ui, -apple-system, + BlinkMacSystemFont, "Segoe UI", sans-serif; + --model-sky-mono: ui-monospace, "Cascadia Code", "SFMono-Regular", Consolas, + "Liberation Mono", monospace; +} + +body.quarto-light { + color-scheme: light; + --model-sky-background: #f7f9f4; + --model-sky-panel: #ffffff; + --model-sky-panel-raised: #edf3e6; + --model-sky-text: #20291b; + --model-sky-accent: #426900; + --model-sky-line: #ccd7c2; + --model-sky-plot-background: #ffffff; + --model-sky-plot-text: #20291b; + --model-sky-plot-muted: #4f6043; + --model-sky-plot-border: #ccd7c2; + --model-sky-plot-cyan: #007f99; + --model-sky-plot-pink: #ab3d75; +} + +main.content a.model-sky-glossary-term { + color: inherit; + text-decoration: underline dotted var(--model-sky-accent); + text-underline-offset: 0.2em; + text-decoration-thickness: 1.5px; + cursor: help; +} +main.content a.model-sky-glossary-term:hover, +main.content a.model-sky-glossary-term:focus-visible { color: var(--model-sky-accent); } +.model-sky-glossary-term:focus-visible, .model-sky-science summary:focus-visible { + outline: 2px solid var(--model-sky-accent); + outline-offset: 4px; + border-radius: 2px; +} +main.content .model-sky-glossary dt { + margin-top: 1.25rem; + font-weight: 700; + scroll-margin-top: 7rem; +} +main.content .model-sky-glossary dd { margin: 0.3rem 0 0; max-width: 95ch; } +.model-sky-glossary dt:target, .model-sky-glossary dt:focus { + color: var(--model-sky-accent); + outline: 2px solid var(--model-sky-accent); + outline-offset: 4px; +} +#model-sky-glossary-tip { + position: fixed; + z-index: 10000; + box-sizing: border-box; + width: max-content; + max-width: min(25rem, calc(100vw - 24px)); + max-height: calc(100dvh - 24px); + overflow-y: auto; + padding: 14px 16px; + color: var(--model-sky-text); + background: var(--model-sky-panel-raised); + border: 1px solid var(--model-sky-accent); + border-radius: 8px; + box-shadow: 0 5px 24px rgb(0 0 0 / 35%); + font: 15px/1.55 var(--model-sky-font); + overflow-wrap: break-word; +} +#model-sky-glossary-tip[hidden] { display: none; } +#model-sky-glossary-tip strong { display: block; margin-bottom: 0.35em; color: var(--model-sky-accent); } +main.content details.model-sky-science { + margin: 1.15rem 0; + padding: 0.8rem 1.1rem; + border: 1px solid var(--model-sky-line); + border-left: 3px solid var(--model-sky-green); + border-radius: 6px; + background: var(--model-sky-panel); +} +.model-sky-science summary { cursor: pointer; font-weight: 650; color: var(--model-sky-accent); } +.model-sky-science[open] summary { margin-bottom: 1rem; } +.model-sky-equation { + margin: 1rem 0; + padding: 0.7rem 1rem; + overflow-x: auto; + color: var(--model-sky-text); + background: var(--model-sky-panel-raised); + border-radius: 4px; + font: 1.05rem/1.8 var(--model-sky-mono); +} +@media print { #model-sky-glossary-tip { display: none; } } + +.cell, .cell-output-display { min-width: 0; max-width: 100%; } +.cell-output-display { overflow-x: auto; } +.model-sky-story-card { border: 1px solid var(--model-sky-line); border-radius: 10px; background: var(--model-sky-panel); overflow: hidden; } +.model-sky-story-grid { grid-template-columns: repeat(2, minmax(0, 1fr)) !important; } +@media (max-width: 575px) { + .model-sky-story-grid { grid-template-columns: 1fr !important; } +} diff --git a/examples/model-sky/assets/guide.js b/examples/model-sky/assets/guide.js new file mode 100644 index 00000000..d20fa5d4 --- /dev/null +++ b/examples/model-sky/assets/guide.js @@ -0,0 +1,240 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +(() => { + "use strict"; + const root = document.body; + const original = new WeakMap(); + const sourceColors = new WeakMap(); + const styled = new WeakSet(); + const discovered = new WeakSet(); + const uiTypes = new Set(["Div", "Button", "CheckboxGroup", "RadioButtonGroup", "Slider", "Toolbar"]); + + // Variables cross shadow boundaries and follow dynamic readouts without + // rewriting scientific callbacks or their text. + const uiCSS = ` + :host { color: var(--model-sky-plot-text) !important; color-scheme: inherit; + --bokeh-icon-color: var(--model-sky-plot-muted); + --bokeh-icon-color-disabled: var(--model-sky-plot-border); } + .bk-btn, .bk-input { color: var(--model-sky-plot-text); background: var(--model-sky-panel-raised); + border-color: var(--model-sky-plot-border); } + .bk-btn:hover { background: var(--model-sky-panel); } + .bk-btn.bk-active, .bk-btn-primary, + .bk-btn.bk-active:hover, .bk-btn-primary:hover { color: var(--model-sky-background); + background: var(--model-sky-accent); border-color: var(--model-sky-accent); } + .bk-slider-title, .bk-input-group { color: var(--model-sky-plot-text); } + .bk-toolbar-button { background: var(--model-sky-panel-raised); } + input { accent-color: var(--model-sky-accent); } + [style*="color:#f0f4eb"], [style*="color: #f0f4eb"], + [style*="color:#172b45"], [style*="color: #172b45"] { color: var(--model-sky-plot-text) !important; } + [style*="color:#b7c9a9"], [style*="color: #b7c9a9"], + [style*="color:#52647c"], [style*="color: #52647c"] { color: var(--model-sky-plot-muted) !important; } + [style*="background:#182310"], [style*="background:#f0f6fa"] { + background: var(--model-sky-panel-raised) !important; } + `; + + function remember(model, property) { + if (!original.has(model)) original.set(model, new Map()); + const values = original.get(model); + if (!values.has(property)) values.set(property, model[property]); + return values.get(property); + } + function palette() { + const css = getComputedStyle(root); + const color = (name, fallback) => css.getPropertyValue(`--model-sky-plot-${name}`).trim() || fallback; + return { + background: color("background", "#ffffff"), text: color("text", "#20291b"), + muted: color("muted", "#4f6043"), border: color("border", "#ccd7c2"), + cyan: color("cyan", "#007f99"), pink: color("pink", "#ab3d75"), + }; + } + + function styleDocument(doc, light, colors) { + const replacements = new Map([ + ["#67d5e5", colors.cyan], ["#007f99", colors.cyan], ["#00bed6", colors.cyan], + ["#ed91bd", colors.pink], ["#ab3d75", colors.pink], + ["#82938a", colors.muted], ["#93a6b8", colors.muted], ["#d97a00", "#a35600"], + ]); + const replace = (value) => light && typeof value === "string" + ? (replacements.get(value.toLowerCase()) || value) : value; + for (const model of doc._all_models.values()) { + const type = model.type; + // Never theme image pixels, color maps, limits or palettes. + if (["Image", "ImageRGBA", "LinearColorMapper"].includes(type)) continue; + const set = (property, value) => { + if (!(property in model.properties)) return; + const before = remember(model, property); + const after = light ? value : before; + if (model[property] !== after) model[property] = after; + }; + if (type === "Figure" || type === "Plot") { + set("background_fill_color", colors.background); + set("border_fill_color", colors.background); + set("outline_line_color", colors.border); + } else if (type.endsWith("Axis")) { + set("axis_label_text_color", colors.muted); + set("major_label_text_color", colors.muted); + set("axis_line_color", colors.border); + set("major_tick_line_color", colors.border); + } else if (type === "Grid") { + set("grid_line_color", colors.border); + } else if (type === "Title") { + set("text_color", colors.text); + } else if (type === "ColorBar") { + set("background_fill_color", colors.background); + set("major_label_text_color", colors.muted); + set("title_text_color", colors.text); + set("major_tick_line_color", colors.muted); + } else if (type === "Legend") { + set("background_fill_color", colors.background); + set("label_text_color", colors.text); + set("title_text_color", colors.text); + set("border_line_color", colors.border); + } + // Change only known presentation colors, leaving field transforms intact. + for (const property of ["line_color", "fill_color"]) { + if (!(property in model.properties)) continue; + const before = remember(model, property); + if (typeof before === "string") { + set(property, replace(before)); + } else if (before && typeof before.value === "string") { + const value = replace(before.value); + set(property, value === before.value ? before : {...before, value}); + } + } + if (type === "ColumnDataSource" && Array.isArray(model.data.color) + && model.data.color.every((value) => typeof value === "string")) { + if (!sourceColors.has(model)) sourceColors.set(model, model.data.color.slice()); + const colors = sourceColors.get(model).map(replace); + if (colors.some((value, index) => value !== model.data.color[index])) { + // Numerical arrays and selections retain their current objects. + model.data = {...model.data, color: colors}; + } + } + if (uiTypes.has(type) && !styled.has(model)) { + model.stylesheets = [...model.stylesheets, uiCSS]; + styled.add(model); + } + } + } + + function apply(theme) { + root.dataset.modelSkyTheme = theme; + const light = theme === "light"; + const colors = palette(); + for (const doc of window.Bokeh?.documents || []) { + styleDocument(doc, light, colors); + discovered.add(doc); + } + } + + const sync = () => apply(document.body.classList.contains("quarto-dark") ? "dark" : "light"); + sync(); + new MutationObserver(sync).observe(document.body, {attributes: true, attributeFilter: ["class"]}); + + // Bokeh initializes asynchronously. Discover each document once, stop after + // ten seconds, and let subsequent theme clicks cover any later documents. + let attempts = 80; + function discoverDocuments() { + const colors = palette(); + for (const doc of window.Bokeh?.documents || []) { + if (!discovered.has(doc)) { + styleDocument(doc, root.dataset.modelSkyTheme === "light", colors); + discovered.add(doc); + } + } + if (--attempts > 0) window.setTimeout(discoverDocuments, 125); + } + discoverDocuments(); +})(); + +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +// Definitions remain ordinary document content. Clicking, touching, printing +// and disabled JavaScript all retain the same internal definition links. +(() => { + const links = document.querySelectorAll('a.model-sky-glossary-term'); + if (!links.length) return; + const tip = document.createElement('div'); + tip.id = 'model-sky-glossary-tip'; + tip.setAttribute('role', 'tooltip'); + tip.hidden = true; + document.body.append(tip); + let active = null; + let hideTimer; + + function hide() { + window.clearTimeout(hideTimer); + active?.removeAttribute('aria-describedby'); + active = null; + tip.hidden = true; + } + + function position() { + if (!active || tip.hidden) return; + const anchor = active.getBoundingClientRect(); + const box = tip.getBoundingClientRect(); + const margin = 12; + const left = Math.max(margin, Math.min( + anchor.left + anchor.width / 2 - box.width / 2, + window.innerWidth - box.width - margin, + )); + const below = anchor.bottom + 9; + const above = anchor.top - box.height - 9; + const top = below + box.height <= window.innerHeight - margin ? below : above; + tip.style.left = `${left}px`; + tip.style.top = `${Math.max(margin, Math.min(top, window.innerHeight - box.height - margin))}px`; + } + + function show(link) { + window.clearTimeout(hideTimer); + const term = document.getElementById(link.hash.slice(1)); + const definition = term?.nextElementSibling; + if (definition?.tagName !== 'DD') return; + active?.removeAttribute('aria-describedby'); + active = link; + const heading = document.createElement('strong'); + heading.textContent = term.textContent; + const body = document.createElement('span'); + body.textContent = definition.textContent; + tip.replaceChildren(heading, body); + tip.hidden = false; + link.setAttribute('aria-describedby', tip.id); + position(); + } + + function later() { + window.clearTimeout(hideTimer); + hideTimer = window.setTimeout(hide, 180); + } + + for (const link of links) { + // Avoid a second native title popup only once this enhancement exists. + link.removeAttribute('title'); + link.addEventListener('pointerenter', (event) => { + if (event.pointerType !== 'touch') show(link); + }); + link.addEventListener('pointerleave', () => { + if (document.activeElement !== link) later(); + }); + link.addEventListener('focus', () => show(link)); + link.addEventListener('blur', later); + link.addEventListener('click', () => { + hide(); + const term = document.getElementById(link.hash.slice(1)); + // Preserve native anchor navigation/history; Back restores the reader. + window.setTimeout(() => term?.focus({ preventScroll: true }), 0); + }); + } + tip.addEventListener('pointerenter', () => window.clearTimeout(hideTimer)); + tip.addEventListener('pointerleave', later); + document.addEventListener('keydown', (event) => { + if (event.key === 'Escape') hide(); + }); + document.addEventListener('pointerdown', (event) => { + if (active && !active.contains(event.target) && !tip.contains(event.target)) hide(); + }); + document.addEventListener('scroll', position, true); + window.addEventListener('resize', position); +})(); diff --git a/examples/model-sky/assets/story-compare.svg b/examples/model-sky/assets/story-compare.svg new file mode 100644 index 00000000..066258b9 --- /dev/null +++ b/examples/model-sky/assets/story-compare.svg @@ -0,0 +1,83 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Compare the images + A reference image and a new image share a coordinate frame and matched stellar shapes. Subtraction removes their steady stars and leaves a blue and pink residual where one source changed position. + + + 02 + A COMMON FRAME + REFERENCE + NEW IMAGE + + + + + + + + + + + + + + + + + + + + + new − reference + + WHAT + CHANGED + + + + + + + + negative + + positive + ILLUSTRATIVE SCHEMATIC + + diff --git a/examples/model-sky/assets/story-field.svg b/examples/model-sky/assets/story-field.svg new file mode 100644 index 00000000..20982dd9 --- /dev/null +++ b/examples/model-sky/assets/story-field.svg @@ -0,0 +1,80 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Read the field + A bright diagonal satellite trail crosses a schematic star field. An amber exclusion band covers the trail while the surrounding sky remains available. + + + 01 + ONE EXPOSURE + + + + + + + + + + + trail mask + + unmasked field + + excluded pixels + ILLUSTRATIVE SCHEMATIC + + diff --git a/examples/model-sky/assets/story-motion.svg b/examples/model-sky/assets/story-motion.svg new file mode 100644 index 00000000..6b923d95 --- /dev/null +++ b/examples/model-sky/assets/story-motion.svg @@ -0,0 +1,69 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Follow the star + A single star occupies an earlier and a later position against the same background. Its displacement, divided by the elapsed time, gives its proper motion. The illustrated displacement is exaggerated for clarity. + + + 03 + TWO EPOCHS + + + + + + + + + + + + + + + + earlier + later + same star + Angular shift ÷ elapsed time + ILLUSTRATIVE SCHEMATIC + + diff --git a/examples/model-sky/assets/story-transit.svg b/examples/model-sky/assets/story-transit.svg new file mode 100644 index 00000000..916db147 --- /dev/null +++ b/examples/model-sky/assets/story-transit.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + + + + + + Catch the shadow + A planet passes in front of a star. A schematic light curve below shows the resulting small temporary dimming. Neither the plotted points nor the planet and star sizes represent measured data. + + + 04 + A SMALLER SHADOW + + + + + + planet in front + Transit light curve + + + starlight + time → + + + + + + + + + + + + + + + + ILLUSTRATIVE SCHEMATIC + + diff --git a/examples/model-sky/blend.py b/examples/model-sky/blend.py new file mode 100644 index 00000000..cd9b319f --- /dev/null +++ b/examples/model-sky/blend.py @@ -0,0 +1,395 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Optional experiment: locate the fading light in an unresolved blend. + +Preparation owns injection settings. Measurement opens only the generated +science/variance/mask planes and locates sources from image evidence. +""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path + +import numpy as np +from bokeh.layouts import column +from bokeh.models import Div +from bokeh.plotting import figure +from pipeline import ( + bundle_path, + empirical_psf, + fit_positions, + good_pixels, + gpu, + load_bundle, + local_sky, + read_exposure, + select_stars, + stamp, + write_exposure, +) +from scene import ( + SceneConfig, + add_star, + draw_exposure, + normalized_psf, + transit_flux, +) +from scipy import ndimage +from views import export_html, image_triptych + +from cuphoton.xfit import fit_single_sources, forced_psf_photometry + + +def _brightest_near(exposure, seed, radius=18): + patch = stamp(exposure["science"], seed, 2 * radius + 1) + usable = stamp(good_pixels(exposure), seed, 2 * radius + 1) + y, x = np.unravel_index( + np.argmax(np.where(usable, patch, -np.inf)), patch.shape + ) + return np.rint(seed) + [x - radius, y - radius] + + +def _prepare(bundle, output, config=None): + """Construct independent in/out means; write truth for validation only.""" + root, manifest = load_bundle(bundle) + reference = read_exposure( + bundle_path(root, manifest["files"]["reference_current"]) + ) + target_guess = _brightest_near( + reference, manifest["target_search"]["old_xy"] + ) + target_xy, _, ok = fit_positions(reference, np.array([target_guess])) + if not ok[0]: + raise RuntimeError( + "the independent reference does not locate the target" + ) + target_xy = target_xy[0] + # Three bright, isolated image-selected stars supply independent PSF data. + controls = select_stars(reference, exclude=[target_xy], count=3) + controls, _, controls_ok = fit_positions(reference, controls) + if not controls_ok.all(): + raise RuntimeError( + "the reference does not constrain three control stars" + ) + calibration_dir = bundle_path( + root, manifest.get("calibration_dir", "provenance") + ) + with np.load(calibration_dir / "calibration.npz") as arrays: + background = arrays["background"].astype(float) + psf = normalized_psf(arrays["base_psf"], 1.4) + sky_variance = arrays["sky_variance"] + noise_scale = arrays["noise_scale"] + bad = arrays["quality_mask"].astype(np.uint8) + config = config or SceneConfig() + target_flux = config.target_flux_njy + neighbor_flux = target_flux * 0.05 + neighbor_xy = target_xy + [1.5, 0.7] + loss = target_flux * (1 - float(transit_flux([0], config)[0])) + base = ndimage.gaussian_filter(background, 1.4, mode="reflect") + for index, point in enumerate(controls): + add_star(base, psf, point, target_flux * (0.8 + 0.1 * index)) + out_model = base.copy() + add_star(out_model, psf, target_xy, target_flux) + add_star(out_model, psf, neighbor_xy, neighbor_flux) + cases = {} + rng = np.random.default_rng(260614) + output.mkdir(parents=True, exist_ok=True) + for name, position in (("planet", target_xy), ("blend", neighbor_xy)): + in_model = out_model.copy() + add_star(in_model, psf, position, -loss) + paths = {} + for state, model in (("out", out_model), ("in", in_model)): + data, variance = draw_exposure( + model, sky_variance, noise_scale, rng, n_average=16 + ) + header = reference["header"].copy() + for key in ("SIMMJD", "MJD-OBS", "DATE-OBS", "TREL_MIN"): + header.remove(key, ignore_missing=True) + header["SIMULATE"] = True + header["NCOMBINE"] = 16 + header["TOTALEXP"] = 480.0 + header["SIMSTATE"] = state + header.add_history( + "Independent 16-exposure mean at a held light level." + ) + path = output / name / f"{state}.fits" + write_exposure( + path, + { + "science": data, + "variance": variance, + "mask": bad, + "header": header, + }, + ) + paths[state] = str(path.relative_to(output)) + cases[name] = paths + definition = { + "schema_version": 1, + "cases": cases, + "target_search": manifest["target_search"], + "pixel_scale_arcsec": manifest["pixel_scale_arcsec"], + "description": ( + "Independent 16-exposure means at fixed in/out light levels, " + "with equal lost total flux in both scenarios. These are " + "controlled snapshots, not a time-sampled eclipse model." + ), + "references": { + "centroid_validation": "https://arxiv.org/abs/1303.0052", + "gj1214_discovery": "https://arxiv.org/abs/0912.3229", + }, + } + (output / "cases.json").write_text( + json.dumps(definition, indent=2) + "\n" + ) + (output / "injection-truth.json").write_text( + json.dumps( + { + "purpose": "Validation only; never read by measure_case.", + "target_xy": target_xy.tolist(), + "neighbor_xy": neighbor_xy.tolist(), + "target_flux_njy": target_flux, + "neighbor_flux_njy": neighbor_flux, + "lost_flux_njy": loss, + "neighbor_eclipse_fraction": loss / neighbor_flux, + "combined_aperture_depth": loss + / (target_flux + neighbor_flux), + }, + indent=2, + ) + + "\n" + ) + return definition + + +def measure_case(out_path, in_path, seed): + """Use image evidence and real xFit GPU fits, without injection truth.""" + cp = gpu() + out_frame, in_frame = read_exposure(out_path), read_exposure(in_path) + guess = _brightest_near(out_frame, seed) + center = np.rint(guess) + out_stamp = stamp(out_frame["science"], center) + in_stamp = stamp(in_frame["science"], center) + out_stamp -= local_sky(out_stamp) + in_stamp -= local_sky(in_stamp) + variance_out = stamp(out_frame["variance"], center) + variance_in = stamp(in_frame["variance"], center) + valid_out = stamp(good_pixels(out_frame), center) + valid_in = stamp(good_pixels(in_frame), center) + difference = in_stamp - out_stamp + variance_difference = variance_in + variance_out + images = np.stack([out_stamp, in_stamp, difference]) + variances = np.stack([variance_out, variance_in, variance_difference]) + usable = np.stack([valid_out, valid_in, valid_out & valid_in]) + fit = fit_single_sources( + cp.asarray(images), + cp.asarray(variances), + cp.zeros((3, 2)), + mask=cp.asarray(usable), + sign=cp.asarray([1, 1, -1]), + ) + if not bool(cp.all(fit.converged & fit.uncertainty_valid)): + raise RuntimeError( + "xFit did not constrain the three source centroids" + ) + measured_xy = center + cp.asnumpy(cp.stack([fit.x, fit.y], axis=1)) + errors_xy = cp.asnumpy( + cp.stack([fit.position_error_x, fit.position_error_y], axis=1) + ) + # Build the forced-photometry model from independent isolated field stars. + anchors = select_stars(out_frame, exclude=[measured_xy[0]], count=3) + empirical = empirical_psf(out_frame, anchors) + psf_model = ndimage.shift( + empirical, (measured_xy[2] - center)[::-1], order=3 + ) + flux_fit = forced_psf_photometry( + cp.asarray(difference[None]), + cp.asarray(variance_difference[None]), + cp.asarray((measured_xy[2] - center)[None]), + 1, + mask=cp.asarray((valid_out & valid_in)[None]), + psf=cp.asarray(psf_model[None]), + ) + if not bool(flux_fit.valid[0]): + raise RuntimeError("forced photometry has no usable information") + yy, xx = np.indices(out_stamp.shape) + aperture = (xx - 20) ** 2 + (yy - 20) ** 2 < 10**2 + aperture &= valid_out & valid_in + flux_out, flux_in = out_stamp[aperture].sum(), in_stamp[aperture].sum() + if flux_out <= 0: + raise RuntimeError("aperture has no positive baseline flux") + ratio = flux_in / flux_out + depth_error = ( + np.sqrt( + variance_in[aperture].sum() + + ratio**2 * variance_out[aperture].sum() + ) + / flux_out + ) + cp.cuda.get_current_stream().synchronize() + return { + "out_centroid_xy": measured_xy[0], + "in_centroid_xy": measured_xy[1], + "difference_centroid_xy": measured_xy[2], + "centroid_shift_xy_pixels": measured_xy[1] - measured_xy[0], + "centroid_shift_error_xy_pixels": np.hypot( + errors_xy[0], errors_xy[1] + ), + "fading_source_offset_xy_pixels": measured_xy[2] - measured_xy[0], + "difference_centroid_error_xy_pixels": errors_xy[2], + "lost_flux_njy": -float(flux_fit.flux[0]), + "lost_flux_error_njy": float(flux_fit.flux_error[0]), + "aperture_depth": float(1 - ratio), + "aperture_depth_error": float(depth_error), + "fit_converged": cp.asnumpy(fit.converged), + "backend": "cupy", + "science": in_stamp, + "reference": out_stamp, + "difference": difference, + "valid": valid_out & valid_in, + "stamp_center_xy": center, + "uncertainty_scope": ( + "Formal errors condition on the chosen Gaussian centroid model, " + "empirical PSF and estimated sky; they exclude PSF-model and " + "sky-estimation uncertainty. Difference-source and out-image " + "positions share pixels; no independent sigma claim is made " + "for their separation." + ), + } + + +def _json_safe(value): + if isinstance(value, np.ndarray): + return value.tolist() + if isinstance(value, np.generic): + return value.item() + if isinstance(value, dict): + return {key: _json_safe(item) for key, item in value.items()} + return value + + +def run(bundle: Path, output: Path, *, config=None, sources=None) -> dict: + """Prepare and measure two controlled scenarios; save offline HTML.""" + output = Path(output) + definition = _prepare(Path(bundle), output, config=config) + results, panels = {}, [] + for key, paths in definition["cases"].items(): + measured = measure_case( + output / paths["out"], + output / paths["in"], + definition["target_search"]["old_xy"], + ) + results[key] = measured + offset = np.linalg.norm(measured["fading_source_offset_xy_pixels"]) + shift_value = np.linalg.norm(measured["centroid_shift_xy_pixels"]) + panels.append( + image_triptych( + measured["science"], + measured["reference"], + measured["difference"], + mask=~measured["valid"], + title="Planet on the target" + if key == "planet" + else "Nearby eclipsing blend", + pixel_scale=definition["pixel_scale_arcsec"], + context=( + "Measured aperture dip: " + f"{100 * measured['aperture_depth']:.2f}% " + f"± {100 * measured['aperture_depth_error']:.2f}% " + "formal. " + f"In/out photocenter shift: {shift_value:.3f} pixels. " + "Fading-light offset from baseline photocenter: " + f"{offset:.2f} pixels. The cyan ring marks the baseline " + "photocenter; the orange cross locates fading light." + ), + ) + ) + center = measured["stamp_center_xy"] + baseline = measured["out_centroid_xy"] - center + 20 + fading = measured["difference_centroid_xy"] - center + 20 + for plot in panels[-1].select({"type": figure}): + if "−" not in plot.title.text: + continue + plot.scatter( + [baseline[0]], + [baseline[1]], + marker="circle", + size=18, + fill_alpha=0, + line_color="#00a9d6", + line_width=2, + ) + plot.scatter( + [fading[0]], + [fading[1]], + marker="x", + size=17, + line_color="#ff9500", + line_width=2, + ) + layout = column( + Div( + text=( + "

Where did the light disappear?

A similar dip can " + "come from a small planet crossing the target or a faint " + "neighboring star undergoing a deeper eclipse. The negative " + "difference source helps locate the missing light. These " + "controlled snapshots average 16 independent exposures " + "each; they do not establish periodicity or model an " + "entire eclipse.

" + ) + ), + *panels, + Div( + text=( + "

Interpretation: a displaced fading source argues " + "against a transit on the target. An unresolved source " + "consistent with the target is not proof of a planet; " + "radial velocities, repeated transits, color information " + "and other follow-up remain relevant. Formal uncertainties " + "condition on the fitted PSF and sky.

" + "

Read more: " + "Kepler centroid " + "vetting; " + "GJ 1214 discovery and blend rejection.

" + ) + ), + sizing_mode="stretch_width", + max_width=1200, + ) + html_path = output / "planet-or-blend.html" + export_html( + layout, + html_path, + title="cuPhoton · Planet or blended variable?", + sources=sources, + ) + arrays = {"science", "reference", "difference", "valid"} + measurements = { + case: { + key: value for key, value in result.items() if key not in arrays + } + for case, result in results.items() + } + (output / "measurements.json").write_text( + json.dumps(_json_safe(measurements), indent=2) + "\n" + ) + return { + "measurements": measurements, + "cases": results, + "layout": layout, + "html": html_path, + } + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--bundle", required=True, type=Path) + parser.add_argument("--output", required=True, type=Path) + options = parser.parse_args() + result = run(options.bundle, options.output) + print(result["html"]) diff --git a/examples/model-sky/model-sky.ipynb b/examples/model-sky/model-sky.ipynb new file mode 100644 index 00000000..b1755bf2 --- /dev/null +++ b/examples/model-sky/model-sky.ipynb @@ -0,0 +1,1911 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "title: Model Sky\n", + "subtitle: Follow a star to a hidden world\n", + "execute:\n", + " enabled: false\n", + "code-links:\n", + " - text: Notebook source on GitHub\n", + " icon: github\n", + " href: https://github.com/NVIDIA/cuPhoton/blob/main/examples/model-sky/model-sky.ipynb\n", + " - text: Example code on GitHub\n", + " icon: folder\n", + " href: https://github.com/NVIDIA/cuPhoton/tree/main/examples/model-sky\n", + "---\n", + "\n", + "A planet usually disappears into its star's glare. We can still notice it\n", + "when it crosses in front of the star and hides a little light. That temporary\n", + "dimming is a **transit**. Measuring it requires more than finding a dip in a\n", + "plot: we need to know which star dimmed, whether the images line up, and\n", + "whether the apparent change could come from the camera or atmosphere.\n", + "\n", + "This notebook follows one cumulative experiment. First a satellite spoils\n", + "part of an exposure. We identify those pixels, align the images and subtract\n", + "the steady field. Next, the paired bright and dark footprint of a moving star\n", + "reveals where it went. Finally, we measure that same star's light across a\n", + "simulated transit and ask what the evidence can actually establish.\n", + "\n", + "**Model Sky builds every sky pixel and instrument input from declared\n", + "models.** The stars, satellite trail, observing times, motion and transit are\n", + "simulations. Their known answers stay in a separate file until measurement is\n", + "complete. A controlled sky lets us follow cause and effect: we know what was\n", + "put into the images, then ask whether measurements recover it. These are\n", + "teaching observations of a fictional field, not an observed planet discovery.\n", + "\n", + "The explanations unpack the units, assumptions and interpretation behind each\n", + "measurement. The model is deliberately simpler than a real sky or camera; a\n", + "successful recovery establishes behavior within those assumptions, not accuracy\n", + "for every astronomical observation.\n", + "\n", + "You can follow the main text without knowing astronomy or calculus. Defined\n", + "terms have dotted underlines: hover or focus for a short definition, or follow\n", + "the link to the glossary. On touch screens, tap a term. Each collapsed\n", + "**Science Explanation** supplies the assumptions and equations behind the\n", + "step. Expand it when you want to inspect how the measurement works.\n", + "\n", + "[NVIDIA cuPhoton](https://github.com/NVIDIA/cuPhoton) supplies GPU image\n", + "reprojection (**xRep**), image matching and subtraction (**xPois**), and source\n", + "measurements (**xFit**). The notebook keeps those calls visible. Example\n", + "helpers manage the sequence and displays. **xScan** is not used: this experiment\n", + "includes no trained classifier or classifier-performance claim. The [NVIDIA imaging walkthrough](https://developer.nvidia.com/blog/faster-scientific-image-analysis-with-nvidia-cuphoton/)\n", + "provides further context; its older API examples do not replace the calls\n", + "in this example. The [quickstarts](https://github.com/NVIDIA/cuPhoton/blob/main/docs/quickstarts.md)\n", + "and [other cuPhoton demos](https://nvidia.github.io/cuPhoton/) cover more uses.\n", + "\n", + "The illustrations below are schematics. Actual pixels and measured results follow." + ], + "id": "3281ef009b0e" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "" + ], + "id": "9292996e676b" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## What you will make\n", + "\n", + "You will produce an aligned image pair, a defensible trail mask, a stellar\n", + "displacement with uncertainty, and a light curve with a fitted transit. A\n", + "light curve is brightness plotted against time. The final question is\n", + "whether the measurements support the interpretation, including the possibility\n", + "that the interpretation is wrong.\n", + "\n", + "Prepare the inputs with `python model_sky.py --output data`, then run the cells\n", + "in order. The notebook reads `data/` and writes intermediates under\n", + "`results/`. The baseline and blend switches start disabled in the source.\n", + "The runner (`python run.py --output model-sky-output`) enables both in an\n", + "execution copy and keeps the complete results. Choose a fresh output directory\n", + "for each run. No classifier model or xScan inference is included.\n", + "\n", + "\n", + "\n", + "### Know the arrays before measuring them\n", + "\n", + "A **FITS** file is astronomy's container for arrays and descriptive metadata.\n", + "These modeled exposures have three named image planes with matching shapes:\n", + "\n", + "| Plane | Meaning | What consumes it |\n", + "| --- | --- | --- |\n", + "| `SCI` | Calibrated light assigned to each pixel, in nJy | Registration, subtraction and source fits |\n", + "| `VAR` | Estimated per-pixel variance, in nJy\u00b2 | Weights and conditional error estimates |\n", + "| `MASK` | Integer quality flags; zero means usable here | Pixel exclusion and retained-light checks |\n", + "| `SCI` header | Coordinates, units and observing metadata | WCS mapping and plot labels |\n", + "\n", + "A **nanojansky**, written **nJy**, is a spectral flux-density unit: one nJy is\n", + "10\u207b\u00b3\u2075 W m\u207b\u00b2 Hz\u207b\u00b9. Here it represents the photon-weighted brightness in the\n", + "modeled band, assigned to each pixel. Fitting a normalized star shape combines\n", + "pixels into a stellar flux in nJy. A variance in nJy\u00b2 describes the spread of\n", + "repeated noisy measurements; its square root is a one-sigma error in nJy.\n", + "Negative background-subtracted pixels are possible even though photon counts\n", + "are nonnegative.\n", + "\n", + "The next cell checks the GPU and reports the installed cuPhoton version and\n", + "angular pixel scale. The manifest names measurement inputs and declared\n", + "assumptions; loading it does not read the separate injection-truth file.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "**A noiseless model can still produce noisy references.** Preparation starts\n", + "from a fixed analytic field, with no measured coadd or catalog underneath it.\n", + "That latent field specifies the expected source light before each exposure's\n", + "seeing, pointing offset and transparency. It contains no random detector\n", + "noise. New photon and sky/read fluctuations are drawn independently for every\n", + "exposure; copying one noisy image would instead copy its fluctuations.\n", + "\n", + "For a modeled pixel M in nJy, let M\u208a = max(M, 0), a be the conversion in nJy\n", + "per detected electron, and Vb the sky/read variance in nJy\u00b2:\n", + "\n", + "

Var(pixel) = a M\u208a + Vb.

\n", + "\n", + "Photon arrivals follow Poisson statistics: an electron count's variance equals\n", + "its mean. The source term therefore becomes a M\u208a after conversion to nJy.\n", + "The high sky count and detector read noise are represented by Gaussian draws.\n", + "The mean sky is subtracted, while its noise remains. Averaging N independent\n", + "equal exposures divides the variance by N. Both prepared references represent\n", + "16 such exposures; individual science frames use their own independent draws.\n", + "\n", + "The reference's finite noise matters when subtracting it and when estimating\n", + "positions or a PSF from it. Reusing a reference can couple later measurements,\n", + "even though the latent model was noiseless. Qualification changes exposure\n", + "noise conditional on this one field; it does not cover uncertain source\n", + "populations, unmodeled atmospheric behavior or every possible detector.\n", + "[The FITS standard](https://fits.gsfc.nasa.gov/fits_standard.html) documents\n", + "the file format independently of these modeling choices.\n", + "\n", + "
" + ], + "id": "96a3a51117a5" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "import os\n", + "from pathlib import Path\n", + "import cupy as cp\n", + "import numpy as np\n", + "from astropy.io import fits\n", + "from astropy.wcs import WCS\n", + "from bokeh.io import output_notebook\n", + "from notebook_style import show_dark\n", + "from bokeh.resources import INLINE\n", + "from IPython.display import Markdown, display\n", + "import cuphoton\n", + "import pipeline\n", + "import views\n", + "import workshop\n", + "\n", + "# Input data and generated results have separate directories.\n", + "DATA = Path(os.environ.get(\"CUPHOTON_MODEL_SKY_DATA\", \"data\")).resolve()\n", + "OUTPUT = Path(os.environ.get(\"CUPHOTON_MODEL_SKY_OUTPUT\", \"results\"))\n", + "OUTPUT.mkdir(parents=True, exist_ok=True)\n", + "# Paths and assumptions only; injection truth is read later.\n", + "root, manifest = pipeline.load_bundle(DATA)\n", + "output_notebook(resources=INLINE, hide_banner=True)\n", + "pipeline.gpu()\n", + "# Angular size of one pixel converts displacement into sky motion.\n", + "scale = float(manifest[\"pixel_scale_arcsec\"])\n", + "assumptions = manifest[\"assumptions\"]\n", + "print(\"cuPhoton\", cuphoton.__version__, \"\u00b7 device\", cp.cuda.Device().id)\n", + "print(f\"Pixel scale: {scale:.5f} arcsec/pixel\")" + ], + "id": "a7ef425a0c8e", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The pixel scale converts an image displacement into an angle on the sky. The\n", + "version and device line identify what actually ran. A working GPU does not\n", + "establish scientific correctness; the image and control checks assess that\n", + "within their stated scope." + ], + "id": "12a1d34f8d9c" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## 1 \u00b7 A satellite crosses the field\n", + "\n", + "Start with a prepared Model Sky exposure containing a modeled satellite trail.\n", + "The long feature crosses unrelated stars because the teaching model adds\n", + "light along a path during the exposure. A real nearby satellite can produce\n", + "such a streak by moving while reflecting sunlight into the telescope. Here\n", + "its shape and brightness are chosen explicitly; no satellite image is used.\n", + "\n", + "The next cell reads the same noisy trail exposure that the measurement steps\n", + "will analyze, including the fictional target star. Pan, zoom and hover to\n", + "inspect native pixels. The display stretches brightness to show faint\n", + "structure; its colors are a viewing choice, while hover values retain units.\n", + "The sky-coordinate labels describe our declared grid, not a catalog match.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "`model_sky.py` creates a 480 \u00d7 480 pixel field of isolated fictional stars. All\n", + "stars start with the same normalized Gaussian PSF of width \u03c3 = 1.5 pixels;\n", + "the generator adds a common seeing blur per exposure. A Gaussian is a smooth\n", + "bell-shaped profile. Its width is a model choice, not a measured telescope PSF.\n", + "\n", + "The modeled unobstructed telescope has a 4 m diameter. Its total photon\n", + "response is 0.4 from 560 to 700 nm and zero outside: a simple top-hat bandpass.\n", + "Each exposure lasts 30 seconds. The sky level is 20.5 AB mag/arcsec\u00b2, the\n", + "pixel scale is 0.2 arcsec/pixel, and read noise is 5 electrons RMS per pixel\n", + "per exposure.\n", + "These assumptions set the brightness-to-electron conversion and noise, not\n", + "just the labels on a plot. Scintillation, saturation and color-dependent\n", + "response changes are omitted.\n", + "\n", + "The trail uses an analytic double-lobed cross section with a declared width\n", + "of 2.8 arcsec. It is a teaching approximation, not an optical ray trace or a\n", + "prediction for a particular satellite. A mask can exclude contaminated pixels\n", + "from a fit, but cannot reconstruct the astronomical photons underneath them.\n", + "Masking trades information for a more trustworthy measurement.\n", + "\n", + "[Tyson et al. (2020)](https://doi.org/10.3847/1538-3881/abba3e) discuss real\n", + "satellite-trail effects. The Model Sky inputs and their assumptions are recorded\n", + "in `data/provenance/` and the bundled source list.\n", + "\n", + "
" + ], + "id": "e6c54bc388d7" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "# A modeled noisy exposure; no observed image is loaded.\n", + "opening = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"trail\"]))\n", + "show_dark(views.observed_image(\n", + " opening[\"science\"], title=\"Model Sky field \u00b7 modeled satellite trail\",\n", + " eyebrow=\"Model Sky imagery\",\n", + " pixel_scale=scale, wcs=WCS(opening[\"header\"]), unit=\"nJy\"))" + ], + "id": "5dfea7b7bf76", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The opening picture and the following fits use the same modeled exposure.\n", + "Its known origin makes it possible to test a measurement, but the measurement\n", + "still has to handle noisy pixels, changing blur and the trail. The generator's\n", + "hidden target and transit answers stay out of the image-analysis code." + ], + "id": "9247cfd213c7" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Put the same sky on the same pixels\n", + "\n", + "Keep the same Model Sky exposure and load its comparison frame. The\n", + "**science image** is the exposure whose change we want to measure. The **reference\n", + "image** supplies the comparison sky. Those names describe roles, not different\n", + "file formats.\n", + "\n", + "The World Coordinate System (**WCS**) maps pixel locations to directions on\n", + "the sky. Pointing changes mean a stationary star can occupy different array\n", + "indices in two exposures. **Reprojection** resamples an image onto another sky coordinate grid. xRep receives science, variance and mask planes plus a\n", + "reference-to-science coordinate map, and returns all three planes on the\n", + "reference grid. `aligned` holds reprojected science, not a difference image.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "For output location (x, y), reprojection finds the corresponding input\n", + "location and interpolates nearby input pixels. Interpolation estimates values\n", + "between samples; it cannot restore detail that was never resolved. Neighboring\n", + "output pixels reuse input pixels, so their noise becomes correlated. A variance\n", + "image records individual uncertainties, not the full covariance between pixels.\n", + "\n", + "The coordinate grid is declared exactly as a TAN, or tangent-plane,\n", + "projection centered at right ascension 210\u00b0 and declination \u221210\u00b0. These are\n", + "sky directions, analogous to longitude and latitude. The reference grid's\n", + "scale is 0.2 arcsec/pixel, with increasing x pointing toward decreasing right\n", + "ascension. The WCS is an input to the model, not a solution fitted to observed\n", + "stars, and no empirical sky-calibration accuracy is claimed.\n", + "\n", + "Knowing the model grid does not make sampled images perfectly aligned.\n", + "Subpixel shifts and interpolation affect pixel values; noise affects estimated\n", + "centers. Subsequent motion and cadence helpers refine translation using\n", + "stationary stars and retain their registration scatter in the motion error.\n", + "This checks alignment in the actual image evidence rather than treating the\n", + "header as a guarantee of a perfect residual.\n", + "\n", + "Arrays use [row, column] = [y, x], while source positions use (x, y).\n", + "[Astropy's WCS interface](https://docs.astropy.org/en/stable/wcs/wcsapi.html)\n", + "describes that distinction; [xRep](https://github.com/NVIDIA/cuPhoton/blob/main/docs/components/xrep.md)\n", + "documents mapping and plane propagation.\n", + "\n", + "
" + ], + "id": "8689912cbc5a" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.xrep import (\n", + " BBox, ReprojectionSpec, make_wcs_pair_transform,\n", + " reproject_masked_array,\n", + ")\n", + "# Approximate (x, y) search location, not the injected displacement.\n", + "old_guess = np.asarray(manifest[\"target_search\"][\"old_xy\"], float)\n", + "# Current-position reference: steady light at the transit-era position.\n", + "trail_reference = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"reference_current\"]))\n", + "trail_science = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"trail\"]))\n", + "height, width = trail_reference[\"science\"].shape\n", + "# Map destination/reference pixels to source/science coordinates.\n", + "mapping = make_wcs_pair_transform(\n", + " WCS(trail_reference[\"header\"]), WCS(trail_science[\"header\"]))\n", + "# Reproject SCI [nJy], VAR [nJy\u00b2] and integer MASK together.\n", + "warped = reproject_masked_array(\n", + " trail_science[\"science\"], trail_science[\"variance\"],\n", + " trail_science[\"mask\"],\n", + " ReprojectionSpec(mapping=mapping,\n", + " output_bbox=BBox(0, 0, width, height),\n", + " mapping_grid_step=32), backend=\"cupy\")\n", + "# Registered science still contains all its light; no subtraction yet.\n", + "aligned = dict(science=warped.image, variance=warped.variance,\n", + " mask=warped.mask, header=trail_reference[\"header\"].copy())" + ], + "id": "f570b9faa714", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "`aligned` now has the reference shape and coordinate header. Its pixel values\n", + "still describe a science exposure. Persistent stars that fail to overlap\n", + "will leave structured residuals, so the later motion helper checks their\n", + "alignment independently." + ], + "id": "718136d449c5" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Match the blur before subtracting\n", + "\n", + "Alignment fixes positions, but a stationary star can still have a different\n", + "shape in each image. The **point-spread function**, or **PSF**, describes how\n", + "light from an unresolved source spreads across pixels. Atmospheric turbulence\n", + "changes this blur, called **seeing**. Subtract unmatched stars and rings or\n", + "paired bright/dark edges can overwhelm the small change we want.\n", + "\n", + "xPois fits a **convolution kernel**, a small array of weights that blurs and\n", + "scales the reference to match the registered science image, together with a\n", + "constant background offset. It learns from usable field pixels. We exclude\n", + "the target's search region so a changing target does not teach the fit to\n", + "remove its own signal. The first fit is provisional: it makes the satellite\n", + "trail easier to find before we exclude it and fit again.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "Let R be the reference, S the registered science image, K the fitted kernel,\n", + "and B the fitted background offset. The matched reference M and difference D\n", + "are\n", + "\n", + "

M = K \u2297 R + B;   D = S \u2212 M.

\n", + "\n", + "Here \u2297 means convolution: each output pixel is a weighted sum of nearby\n", + "reference pixels. R, S, M, B and D are in nJy; K's weights are dimensionless.\n", + "Positive D means extra light in science; negative D means less light than in\n", + "the matched reference. The sign convention stays the same throughout.\n", + "\n", + "The 21 \u00d7 21 kernel uses Gaussian-polynomial basis functions at three widths.\n", + "Weighted least squares selects their coefficients to reduce squared residuals\n", + "on fit pixels, weighted here by science variance. `background_degree=0`\n", + "selects one constant offset. This call does not impose `flux_conserve=True`;\n", + "its fitted kernel can absorb throughput differences. It is not a deconvolution\n", + "that sharpens an arbitrarily blurred observation.\n", + "\n", + "The analytic field already has a Gaussian PSF of width \u03c3 = 1.5 pixels.\n", + "Preparation applies further seeing blur to both background and added stars\n", + "in each exposure. In the continuous Gaussian approximation, blur variances\n", + "add: \u03c3\u00b2effective = \u03c3\u00b2base + \u03c3\u00b2seeing.\n", + "The discrete shifted images need not be exact Gaussians. Measuring a sampled\n", + "PSF from image pixels keeps the fit tied to those images; evaluating it more\n", + "finely helps fractional shifts but creates no new telescope resolution. For method context,\n", + "see [Alard & Lupton (1998)](https://arxiv.org/abs/astro-ph/9712287).\n", + "\n", + "
" + ], + "id": "3b71afd1cc86" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.xpois import GaussianBasisComponent, solve_constant_kernel\n", + "# Both frames must supply valid pixels; True means usable here.\n", + "usable = (pipeline.good_pixels(trail_reference)\n", + " & pipeline.good_pixels(aligned))\n", + "# Withhold target light from learning blur and background.\n", + "fit_mask = usable & ~pipeline.exclusion_disks(usable.shape, [old_guess])\n", + "# Gaussian widths in pixels; polynomial degrees permit shape changes.\n", + "basis = [GaussianBasisComponent(sigma=0.7, degree=2),\n", + " GaussianBasisComponent(sigma=1.6, degree=2),\n", + " GaussianBasisComponent(sigma=3.0, degree=0)]\n", + "# A provisional residual exposes contamination for trail detection.\n", + "preliminary = solve_constant_kernel(\n", + " trail_reference[\"science\"], aligned[\"science\"], basis,\n", + " variance=aligned[\"variance\"], fit_mask=fit_mask,\n", + " kernel_shape=(21, 21), background_degree=0, backend=\"cupy\")" + ], + "id": "e9ba676cceda", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "`preliminary.matched` predicts the reference under science-image blur and\n", + "background. `preliminary.residual` is science minus that prediction. The long\n", + "residual now supplies the evidence for proposing the trail mask." + ], + "id": "12698cd22342" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Find the trail, exclude it, refit\n", + "\n", + "The preliminary difference exposes a long coherent feature. A CPU\n", + "helper searches for aligned bright residual pixels and estimates the trail's\n", + "width. This line detector is example code; xPois provides kernel fitting and\n", + "subtraction, not a satellite-identification service.\n", + "\n", + "The next cell takes the proposed trail mask back into xPois. Pixels marked\n", + "`True` in `trail_mask` are excluded; pixels marked `True` in `fit_mask` are\n", + "included. The refit estimates blur and background from the remaining field.\n", + "Its `matched` image predicts the steady sky under science-image conditions;\n", + "its `difference` is what remains after subtracting that prediction.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "The helper uses a noise-scaled residual to propose a line, then measures its\n", + "profile perpendicular to that line. The initial variance sum is a practical\n", + "detection approximation. The measurement helper subsequently propagates\n", + "reference variance through the squared fitted kernel to estimate marginal\n", + "residual variance. Neither treatment supplies full interpolation covariance\n", + "or all kernel-estimation uncertainty.\n", + "\n", + "For independent input pixel errors, the fixed-kernel approximation is\n", + "\n", + "

Var(Di) \u2248 Var(Si) + \u03a3j Kj\u00b2 Var(Ri\u2212j).

\n", + "\n", + "The sum runs over kernel pixels j; i labels an output pixel. The reference has\n", + "uncertainty even when it looks smooth. Additional model and resampling errors\n", + "need separate checks. Morphology alone does not prove an object's orbit or\n", + "identity. The Model Sky quality mask uses zero for usable pixels; the\n", + "Boolean trail and fit masks have the opposite inclusion meanings described above.\n", + "\n", + "
" + ], + "id": "67caa07cd999" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "# True means EXCLUDED here, opposite to the fit-mask convention.\n", + "trail_mask, trail_profile = pipeline.detect_trail(\n", + " preliminary.residual,\n", + " aligned[\"variance\"] + trail_reference[\"variance\"], usable)\n", + "# Refit the same arrays with trail pixels excluded.\n", + "kernel_fit = solve_constant_kernel(\n", + " trail_reference[\"science\"], aligned[\"science\"], basis,\n", + " variance=aligned[\"variance\"], fit_mask=fit_mask & ~trail_mask,\n", + " kernel_shape=(21, 21), background_degree=0, backend=\"cupy\")\n", + "# Distinct products: registered science, matched reference, difference.\n", + "trail = dict(science=aligned[\"science\"],\n", + " reference=trail_reference[\"science\"],\n", + " difference=kernel_fit.residual, matched=kernel_fit.matched,\n", + " trail_mask=trail_mask, trail_profile=trail_profile,\n", + " fit_mask=kernel_fit.fit_mask, kernel=kernel_fit.kernel,\n", + " registered=aligned)\n", + "# Profile coordinates run across the trail rather than along it.\n", + "profile = (dict(x=trail_profile[\"coordinate\"],\n", + " difference=trail_profile[\"profile\"],\n", + " x_label=\"Perpendicular distance from trail [pixel]\",\n", + " y_label=\"Median residual [nJy]\")\n", + " if trail_profile[\"detected\"] else None)\n", + "show_dark(views.trail_view(\n", + " trail[\"science\"], trail[\"matched\"], trail[\"difference\"], trail_mask,\n", + " profile=profile, pixel_scale=scale,\n", + " wcs=WCS(trail_reference[\"header\"]),\n", + " context=\"Amber marks excluded pixels in the controlled scene.\"))" + ], + "id": "c0f1e34c9feb", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Exercise \u00b7 How wide should the mask be?\n", + "\n", + "In the figure, amber marks rejected pixels. Toggle the mask and blink the\n", + "images to see the tradeoff: unmasked wings can bias a fit, while an excessively\n", + "wide mask throws away useful stars and background. The perpendicular profile\n", + "helps distinguish the bright core from fainter trail wings.\n", + "\n", + "Predict what will happen at `width_scale = 0.7` and `1.5`, then compare the\n", + "number of fit pixels and residual RMS, the square root of the average squared\n", + "residual. Use the **same evaluation region** for both trials. Otherwise a lower\n", + "RMS could simply mean you stopped counting the difficult pixels.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "For N evaluation pixels with differences Di in nJy,\n", + "\n", + "

RMS = \u221a[(1/N) \u03a3i Di\u00b2].

\n", + "\n", + "This describes residual size, not the probability that a model is correct.\n", + "A structured leftover can matter even when average RMS is small. The exercise\n", + "excludes the widest trial mask from evaluation for every setting, so the\n", + "statistic compares the same sky pixels.\n", + "\n", + "
" + ], + "id": "b42c4e90777a" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "width_scale = 1.0 # Try 0.7 and 1.5 after the first complete run.\n", + "trial_mask, _ = pipeline.detect_trail(\n", + " preliminary.residual,\n", + " aligned[\"variance\"] + trail_reference[\"variance\"], usable,\n", + " width_scale=width_scale)\n", + "trial = solve_constant_kernel(\n", + " trail_reference[\"science\"], aligned[\"science\"], basis,\n", + " variance=aligned[\"variance\"], fit_mask=fit_mask & ~trial_mask,\n", + " kernel_shape=(21, 21), background_degree=0, backend=\"cupy\")\n", + "wide_mask, _ = pipeline.detect_trail(\n", + " preliminary.residual,\n", + " aligned[\"variance\"] + trail_reference[\"variance\"], usable,\n", + " width_scale=1.5)\n", + "# Compare all mask choices on this same fixed region.\n", + "evaluation = fit_mask & ~wide_mask\n", + "print(\"Fit pixels:\", np.count_nonzero(fit_mask & ~trial_mask))\n", + "print(\"Common-region residual RMS [nJy]:\",\n", + " np.sqrt(np.mean(trial.residual[evaluation] ** 2)))" + ], + "id": "8ef01be5e296", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A useful mask removes contaminated wings without discarding unnecessary\n", + "information. Compare the printed common-region RMS with the image structure;\n", + "neither fit-pixel count nor RMS alone chooses the scientific answer." + ], + "id": "01eaf4016ac1" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
Image processing from a terminal\n", + "\n", + "Run these recipes after Chapter 2 saves the motion artifacts:\n", + "\n", + "```bash\n", + "cuphoton xrep reproject-stack --inputs data/motion/science.fits \\\n", + " --hdu 1 --target-wcs data/refs/reference_old.fits --target-hdu 1 \\\n", + " --backend cupy --fits-reader astropy --repeats 1 --warmup 0 \\\n", + " --write-fits --name motion-grid --output-dir results/xrep\n", + "cuphoton xpois fit-kernel \\\n", + " --reference results/motion_reference.fits --reference-hdu 1 \\\n", + " --target results/motion_registered.fits --target-hdu 1 \\\n", + " --variance results/motion_registered.fits --variance-hdu 2 \\\n", + " --fit-mask results/motion_fit_mask.npy \\\n", + " --basis-sigmas 0.7,1.6,3 --basis-degrees 2,2,0 \\\n", + " --kernel-height 21 --kernel-width 21 --background-degree 0 \\\n", + " --backend cupy --fits-reader astropy --no-review \\\n", + " --name motion-match --output-dir results/xpois\n", + "```\n", + "\n", + "These use the bundle's science image and saved fit inputs. See\n", + "[xRep](https://github.com/NVIDIA/cuPhoton/blob/main/docs/components/xrep.md)\n", + "and [xPois](https://github.com/NVIDIA/cuPhoton/blob/main/docs/components/xpois.md)\n", + "for plane selection and artifacts.\n", + "\n", + "
" + ], + "id": "4d9ee3ce9cea" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Exercise \u00b7 What if the reference comes from the wrong epoch?\n", + "\n", + "A reference answers a specific question. For trail rejection and a transit\n", + "series, we want the star at its current position. For motion, we deliberately\n", + "compare its earlier and later positions. An **epoch** is the time an\n", + "observation represents.\n", + "\n", + "The next cell substitutes the old-position reference in the trail example.\n", + "Inspect the target cutout: a bright and a dark patch now survive subtraction\n", + "even though neither is a new object. This is a **dipole**, the two-lobed\n", + "footprint of light disappearing at one position and appearing at another.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "A difference records change relative to the chosen reference. It cannot say\n", + "which reference was appropriate for the question. A motion reference encodes\n", + "the old position; a current reference removes steady light at the later\n", + "position so a transit becomes a negative residual there. A registration error\n", + "can also make dipoles around stationary objects. Neighboring field stars\n", + "distinguish a global alignment problem from one source's displacement.\n", + "\n", + "
" + ], + "id": "a58e2d2e1cbb" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "earlier_reference = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"reference_old\"]))\n", + "# Deliberately change the comparison epoch, not the image grid.\n", + "wrong_reference = pipeline.subtract(\n", + " earlier_reference, aligned, exclude=[old_guess])\n", + "x, y = np.rint(old_guess).astype(int)\n", + "# Array slices use [y, x]; source positions use (x, y).\n", + "region = (slice(y - 35, y + 36), slice(x - 35, x + 36))\n", + "show_dark(views.image_triptych(\n", + " wrong_reference[\"science\"][region],\n", + " wrong_reference[\"matched\"][region],\n", + " wrong_reference[\"difference\"][region],\n", + " title=\"Earlier reference \u00b7 target residual\", pixel_scale=scale,\n", + " wcs=WCS(earlier_reference[\"header\"]).slice(region)))" + ], + "id": "016b5759e81c", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## 2 \u00b7 The star moves; the field stays put\n", + "\n", + "The old and new target positions now become the signal we want. The motion\n", + "helper registers the later exposure using neighboring stars, matches the old\n", + "reference's blur, and fits the two-lobed residual with xFit. A **lobe** is one\n", + "bright or dark patch; a **dipole** is the pair. The negative lobe marks the old\n", + "position, and the positive lobe marks the new one.\n", + "\n", + "A stationary neighbor should largely cancel. Dipoles around many neighbors\n", + "would instead implicate registration. The helper measures independent compact\n", + "field stars to refine alignment and estimates a registration error floor from\n", + "their scatter. It also checks that the fitted old lobe belongs to the searched\n", + "star, rather than attaching an unrelated residual to it.\n", + "\n", + "The output is a displacement in pixels and an uncertainty. Converting it to\n", + "**proper motion**, angular travel per year across the sky, requires a pixel\n", + "scale and time interval. The ten-year interval is a declared part of this simulation, not the\n", + "elapsed duration of notebook execution or a measured observing campaign.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "For fitted positions (x\u208a, y\u208a) and (x\u208b, y\u208b), the displacement length d is\n", + "\n", + "

d = \u221a[(x\u208a \u2212 x\u208b)\u00b2 + (y\u208a \u2212 y\u208b)\u00b2];   \u03bc = 1000 s d / \u0394t.

\n", + "\n", + "Coordinates and d are in pixels, s is arcsec/pixel, \u0394t is years, and \u03bc is\n", + "milliarcseconds/year (mas/year). One arcsecond is 1/3600 degree; a\n", + "milliarcsecond is one thousandth of that. The scalar scale is the declared 0.2 arcsec/pixel\n", + "scale, used locally across this small modeled field.\n", + "\n", + "The sampled PSF comes from the matched reference. xFit estimates both centers\n", + "and a shared amplitude; its covariance describes how their fitted errors vary\n", + "together. The helper adds a field-registration floor in quadrature:\n", + "\u03c3d = \u221a(\u03c3fit\u00b2 + 2 \u03c3reg\u00b2). Both terms are in\n", + "pixels: \u03c3fit is the fit error and \u03c3reg is stationary-star\n", + "alignment scatter. These are conditional\n", + "uncertainties, not a complete survey astrometric error budget.\n", + "\n", + "Proper motion reflects relative travel across the sky. **Parallax** is the\n", + "apparent annual shift caused by our changing viewpoint as Earth orbits the\n", + "Sun. Two simulated epochs here do not determine parallax, acceleration,\n", + "distance or a three-dimensional space velocity. [ESA's Gaia overview](https://www.esa.int/articles/about-us/directorates/science/gaia/how-does-gaia-study-the-milky-way)\n", + "explains the distinction. The [GJ 1214 discovery](https://arxiv.org/abs/0912.3229)\n", + "shows how motion and archival images can help rule out background blends.\n", + "\n", + "
" + ], + "id": "e5d1f3fc829e" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "reference_old = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"reference_old\"]))\n", + "motion_science = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"motion\"]))\n", + "# Field stars refine alignment; xFit measures a PSF-shaped dipole.\n", + "motion = pipeline.measure_motion(\n", + " reference_old, motion_science, old_guess,\n", + " search_radius=manifest[\"target_search\"][\"radius_pixels\"])\n", + "# Simulated elapsed time between the modeled observing epochs.\n", + "baseline = float(assumptions[\"baseline_years\"])\n", + "# Pixels \u00d7 arcsec/pixel \u00d7 1000 mas/arcsec \u00f7 elapsed years.\n", + "motion_masyr = motion[\"separation_pixels\"] * scale * 1000 / baseline\n", + "motion_error = motion[\"separation_error_pixels\"] * scale * 1000 / baseline\n", + "print(f\"Motion: {motion_masyr:.2f} \u00b1 {motion_error:.2f} mas/year\")\n", + "print(\"Registration floor [pixel]:\", motion[\"registration_floor_pixels\"])" + ], + "id": "ca5c25881397", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The printed motion includes dipole-fit error and the registration floor.\n", + "The next view lets you check its spatial interpretation rather than accepting\n", + "a successful numerical fit as sufficient evidence." + ], + "id": "e5cb0606ec2a" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show_dark(views.motion_view(\n", + " motion[\"matched\"], motion[\"science\"], motion[\"difference\"],\n", + " old_xy=motion[\"old_xy\"], new_xy=motion[\"new_xy\"],\n", + " baseline_years=baseline, pixel_scale=scale,\n", + " wcs=WCS(reference_old[\"header\"]),\n", + " epoch_labels=(\"Injected earlier position\", \"Injected later position\"),\n", + " context=\"Independent stationary stars set registration.\"))\n", + "# Save exact inputs for the terminal recipes below.\n", + "workshop.save_motion(OUTPUT, motion, reference_old)" + ], + "id": "caf1eb65f727", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Exercise \u00b7 Is the dipole measurement stable?\n", + "\n", + "Blink the motion figure: only the injected star should visibly move after\n", + "alignment. Follow the negative lobe to the old location and the positive lobe\n", + "to the new one. The displayed motion includes registration uncertainty; a\n", + "direct cutout fit alone does not.\n", + "\n", + "The next cell exposes the actual xFit call. A **stamp** is a small image\n", + "cutout around a source. Its measured PSF is sampled at quarter-pixel spacing\n", + "to evaluate fractional shifts accurately. Fit the unchanged stamp first, then\n", + "optionally trim two or four pixels from its edge. Preserve both lobes and\n", + "compare the result with the original uncertainty.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "The model is a positive shifted PSF minus a negative shifted copy:\n", + "\n", + "

D(x, y) \u2248 A [P(x \u2212 x\u208a, y \u2212 y\u208a) \u2212 P(x \u2212 x\u208b, y \u2212 y\u208b)].

\n", + "\n", + "P is the dimensionless sampled PSF, A its fitted amplitude in nJy, and the four\n", + "center coordinates are in pixels relative to the stamp center. The fit\n", + "weights residuals by variance and ignores excluded pixels. A free Gaussian\n", + "width can trade against lobe separation when the lobes overlap. Even with\n", + "an analytic Gaussian starting profile, seeing, pixel sampling and reprojection\n", + "alter the observed shape. A fixed sampled PSF measured from the matched\n", + "reference avoids introducing a free width into this dipole fit; it does not\n", + "make the measured PSF noise-free.\n", + "\n", + "If C is the parameter covariance and g the gradient of separation with respect\n", + "to those parameters, the local fit error is \u03c3\u00b2d,fit = g\u1d40Cg. A\n", + "gradient describes how much a result changes when each parameter changes\n", + "slightly. This includes correlations between center coordinates. Convergence\n", + "means the solver stopped successfully, not that the model is scientifically\n", + "adequate. Check residuals, association and registration evidence too. See\n", + "[xFit's model documentation](https://github.com/NVIDIA/cuPhoton/blob/main/docs/components/xfit.md).\n", + "\n", + "
" + ], + "id": "6913b869b3ca" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.xfit import StampDipoleModel, fit_dipoles\n", + "# One residual stamp: (batch=1, height, width).\n", + "dipole_input = motion[\"fit_input\"]\n", + "dipole_mask = dipole_input[\"mask\"].copy()\n", + "trim_pixels = 0 # Try 2 or 4; preserve both source lobes.\n", + "if trim_pixels:\n", + " dipole_mask[:, :trim_pixels, :] = False\n", + " dipole_mask[:, -trim_pixels:, :] = False\n", + " dipole_mask[:, :, :trim_pixels] = False\n", + " dipole_mask[:, :, -trim_pixels:] = False\n", + "# PSF measured from the matched reference, not injection truth.\n", + "fit = fit_dipoles(\n", + " dipole_input[\"images\"],\n", + " model=StampDipoleModel(dipole_input[\"stamp_basis\"][0],\n", + " scale=float(dipole_input[\"stamp_scale\"]),\n", + " image_shape=dipole_input[\"images\"].shape[-2:],\n", + " backend=\"cupy\"),\n", + " variance=dipole_input[\"variance\"], mask=dipole_mask, backend=\"cupy\")\n", + "# Parameters: positive (x,y), negative (x,y), shared amplitude.\n", + "displacement = fit.parameters[0, :2] - fit.parameters[0, 2:4]\n", + "separation = np.linalg.norm(displacement)\n", + "# Propagate full covariance into scalar separation.\n", + "gradient = np.r_[displacement, -displacement, 0.] / separation\n", + "separation_error = np.sqrt(gradient @ fit.covariance[0] @ gradient)\n", + "print(\"Converged:\", bool(fit.converged[0]))\n", + "print(\"Separation and formal fit error [pixel]:\",\n", + " float(separation), float(separation_error))\n", + "# The direct fit error excludes the separate registration floor above." + ], + "id": "df10740ffb1b", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
Motion measurement from a terminal\n", + "\n", + "The notebook saves residual, variance and valid-pixel mask as a numeric\n", + "NPZ input for the standard xFit interface:\n", + "\n", + "```bash\n", + "cuphoton xfit fit-dipoles --input results/motion_candidates.npz \\\n", + " --model stamp --stamp-scale 0.25 --backend cupy \\\n", + " --fits-reader astropy \\\n", + " --output-dir results/fitted-dipole\n", + "```\n", + "\n", + "[xFit documentation](https://github.com/NVIDIA/cuPhoton/blob/main/docs/components/xfit.md)\n", + "explains derived quantities. A dipole fit alone does not identify a\n", + "star, asteroid or registration artifact; time and field evidence\n", + "supply that interpretation.\n", + "\n", + "
" + ], + "id": "37d3f6b3a264" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## 3 \u00b7 A smaller shadow, on the same star\n", + "\n", + "We know where the star is now. Next we measure its light repeatedly at that\n", + "position, looking for a short decrease. **Forced photometry** fits the amount\n", + "of light at an already measured position, even when a faint residual would\n", + "not trigger a new detection. Fitting a fresh position in every noisy exposure\n", + "would give noise another way to change the measured brightness.\n", + "\n", + "The fictional system is inspired by GJ 1214, a small cool star with a planet\n", + "found using ground-based observations. We place a similar star at 146.42\n", + "parsecs and choose 120 exposures, each 30 seconds long, one minute apart.\n", + "A parsec is a distance unit, about 3.26 light-years. The roughly 52-minute\n", + "transit and dense cadence are designed for the exercise. They are simulated\n", + "observations of our fictional system, not observations of GJ 1214.\n", + "\n", + "The next cell refines the recovered position in an independent current-position\n", + "reference. It registers the first exposure, estimates its PSF from neighboring\n", + "stars, removes a local background, and measures target flux. The output is a\n", + "brightness in nJy and an error, not yet a planet radius.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "For background-subtracted stamp pixels Ii, a fixed normalized PSF\n", + "Pi, and variances Vi, forced PSF photometry is a weighted\n", + "amplitude fit. In the independent-pixel approximation,\n", + "\n", + "

F = [\u03a3i PiIi/Vi] / [\u03a3i Pi\u00b2/Vi];   \u03c3\u00b2F = 1 / [\u03a3i Pi\u00b2/Vi].

\n", + "\n", + "F and \u03c3F are in nJy when P sums to one; sums include only usable\n", + "pixels. The conditional error treats position, PSF and local sky estimate as\n", + "fixed. The local sky is estimated from an outer annulus, a ring around the\n", + "source cutout. Imperfect PSFs, neighbors or interpolation can add errors beyond\n", + "this formula.\n", + "\n", + "**From a model star to detected electrons.** We specify a 3100 K blackbody,\n", + "radius R = 0.2162 solar radii and distance d = 146.42 parsecs. A blackbody is\n", + "an ideal thermal spectrum; its Planck radiance B\u03bb depends on\n", + "wavelength \u03bb and temperature T. With h the Planck constant, c the speed of\n", + "light and kB the Boltzmann constant, preparation computes\n", + "\n", + "

B\u03bb(T) = (2hc\u00b2/\u03bb\u2075) / [exp(hc/(\u03bbkBT)) \u2212 1];   F\u03bb = \u03c0 B\u03bb(R/d)\u00b2.

\n", + "\n", + "F\u03bb is the spectral flux at Earth in W m\u207b\u00b2 m\u207b\u00b9 when SI units are\n", + "used. The squared radius-to-distance ratio expresses geometric dilution.\n", + "Throughput \u03b7(\u03bb) is the fraction of photons detected: here 0.4 in the declared\n", + "560\u2013700 nm band. A photon has energy hc/\u03bb. The 4 m diameter telescope has\n", + "collecting area A = \u03c0(2 m)\u00b2 \u2248 12.566 m\u00b2; this area and exposure duration t\n", + "convert the spectrum into an expected electron count:\n", + "\n", + "

Ne = At \u222b F\u03bb \u03b7(\u03bb) \u03bb/(hc) d\u03bb.

\n", + "\n", + "For comparison with calibrated image flux, the photon-weighted spectral flux\n", + "density is f\u0304\u03bd = \u222bF\u03bb \u03bb\u03b7(\u03bb)d\u03bb / [c \u222b\u03b7(\u03bb)d\u03bb/\u03bb].\n", + "The declared model gives **348775 nJy**, **AB magnitude 17.54**, and about\n", + "**177119 target electrons in 30 seconds** before exposure-specific modulation.\n", + "The AB conversion is mAB = \u22122.5 log\u2081\u2080[f\u0304\u03bd/(3631 Jy)];\n", + "lower magnitudes mean brighter sources. This uses the modeled band, not a\n", + "measured r-filter response.\n", + "\n", + "A cool M dwarf has molecular absorption absent from this smooth continuum.\n", + "Extinction by intervening material is also omitted. The brightness and\n", + "precision are therefore predictions of this explicit teaching model, not of\n", + "a real telescope observing GJ 1214. The limb-darkening law used below is a\n", + "separately declared illustrative surface-brightness pattern; a uniform\n", + "blackbody does not derive those coefficients. See\n", + "[Astropy's Planck-model documentation](https://docs.astropy.org/en/stable/modeling/physical_models.html#blackbody)\n", + "and the [recorded system reference](https://arxiv.org/html/2402.05991v2).\n", + "\n", + "
" + ], + "id": "0bba40614916" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.xfit import forced_psf_photometry\n", + "from scipy.ndimage import shift\n", + "\n", + "# Transit uses the current-position reference; motion uses the older one.\n", + "current_reference = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"files\"][\"reference_current\"]))\n", + "# Start at the recovered position and refine once in the reference.\n", + "target_xy = motion[\"new_xy\"]\n", + "target_fit, _, target_ok = pipeline.fit_positions(\n", + " current_reference, np.array([target_xy]))\n", + "assert target_ok[0], \"Target position must be measured before photometry\"\n", + "target_xy = target_fit[0]\n", + "# Other stars define alignment and PSF independently of target variability.\n", + "anchors = pipeline.select_stars(current_reference, exclude=[target_xy])\n", + "first_exposure = pipeline.read_exposure(\n", + " pipeline.bundle_path(root, manifest[\"epochs\"][0][\"path\"]))\n", + "first_aligned = pipeline.register(\n", + " first_exposure, current_reference, anchors=anchors)\n", + "psf = pipeline.empirical_psf(first_aligned, anchors)\n", + "# Background-subtracted science stamp [nJy]; variance stays in nJy\u00b2.\n", + "patch = pipeline.stamp(first_aligned[\"science\"], target_xy)\n", + "patch -= pipeline.local_sky(patch)\n", + "patch_variance = pipeline.stamp(first_aligned[\"variance\"], target_xy)\n", + "patch_mask = pipeline.stamp(\n", + " pipeline.good_pixels(first_aligned), target_xy)\n", + "# Subpixel (x,y) offset; scipy shifts use array order (y,x).\n", + "offset = target_xy - np.rint(target_xy)\n", + "shifted_psf = shift(psf, offset[::-1], order=3)\n", + "# Add batch dimension; a fixed measured PSF leaves flux as the unknown.\n", + "one_flux = forced_psf_photometry(\n", + " cp.asarray(patch[None]), cp.asarray(patch_variance[None]),\n", + " cp.asarray(offset[None]), 1, mask=cp.asarray(patch_mask[None]),\n", + " psf=cp.asarray(shifted_psf[None]))\n", + "print(\"First-exposure flux and conditional error [nJy]:\",\n", + " float(one_flux.flux[0]), float(one_flux.flux_error[0]))" + ], + "id": "4dcbfb61dd32", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The first-exposure result measures brightness under a fixed position and PSF\n", + "model. Its conditional error describes fluctuations within that model. The\n", + "time series and comparison stars will help separate a brief target dimming\n", + "from changes affecting the whole frame." + ], + "id": "7ed845f2f984" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Build a light curve without letting the reference set the answer\n", + "\n", + "One flux cannot reveal a transit. The next helper repeats registration, trail\n", + "masking, PSF matching and photometry across the sequence. It batches the target,\n", + "a check star and comparison stars within each exposure. It returns time-indexed\n", + "fluxes, errors, validity flags and image stamps, then fits the light curve.\n", + "\n", + "The current reference matters: the star is already at the position we monitor.\n", + "At each cadence, the pipeline measures **reference flux + difference flux**\n", + "with the same PSF, weights and pixel mask. It divides the target's relative\n", + "brightness by a weighted comparison-star ensemble. Stars that should stay\n", + "steady reveal common transmission changes. A separate check star stays out\n", + "of that ensemble to test the remaining scatter.\n", + "\n", + "A fitted flux can still be unreliable if a trail removes the star's core.\n", + "The helper requires at least 90% of the PSF's light to survive the mask.\n", + "A rejected cadence is unavailable information, not zero brightness.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "Write the linear flux estimator as L. With the same weights and masks,\n", + "\n", + "

Ftotal = L(M) + L(S \u2212 M) = L(S).

\n", + "\n", + "The matched-reference contribution cancels algebraically. Adding the two\n", + "formal variances as if these terms were independent would double-count shared\n", + "reference noise. The implementation therefore uses science-image variance\n", + "for total-flux error. This cancellation does not erase errors in estimated\n", + "positions, PSFs, sky or kernel decisions. Here the latent analytic sky is\n", + "noiseless, but estimated quantities still depend on finite-noise reference\n", + "images that are reused across the sequence. The fixed-pixel algebra does not\n", + "turn those estimated quantities into exact knowledge.\n", + "\n", + "For comparison-star relative fluxes fj and errors \u03c3j,\n", + "the ensemble E = \u03a3(wjfj)/\u03a3wj, with\n", + "wj = 1/\u03c3j\u00b2. The normalized target is ftarget/E.\n", + "The helper propagates target and ensemble errors, then increases the error\n", + "scale if robust check-star scatter exceeds the formal expectation. It never\n", + "shrinks the scale below one. This empirical calibration does not supply a\n", + "full model of time-correlated systematics.\n", + "\n", + "
" + ], + "id": "525b258ff409" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "def progress(done, total):\n", + " print(f\"Measured {done}/{total} cadences\",\n", + " end=\"\\r\" if done < total else \"\\n\")\n", + "\n", + "# Per-cadence target/check/comparison fluxes, errors and quality flags.\n", + "transit = pipeline.measure_transit(\n", + " root, manifest, target_xy, progress=progress)\n", + "workshop.save_transit(OUTPUT, transit)\n", + "print(f\"{transit['valid'].sum()} usable cadences \u00b7 \"\n", + " f\"{transit['elapsed_seconds']:.1f} s \u00b7 \"\n", + " f\"error scale {transit['error_scale']:.2f}\")" + ], + "id": "eca5564ba19a", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Read the dip and the images together\n", + "\n", + "The progress output reports usable cadences and the empirical error scale.\n", + "The reference execution should retain 119 of 120 cadences: the trail-crossed\n", + "exposure is rejected. A different count deserves inspection before interpreting\n", + "a fit. Time spent here describes this run and cache state, not a benchmark.\n", + "\n", + "In the next figure, tap a light-curve point or move the cadence slider. The\n", + "native image stamp and difference stamp update together. During the transit,\n", + "missing light appears negative at the recovered star position. The check-star\n", + "curve should not share the target's dip. Inspect fit residuals, measured flux\n", + "minus the model, for leftover trends or clusters.\n", + "\n", + "The stacked difference subtracts a mean baseline residual from a mean\n", + "in-transit residual. It helps locate missing light and suppress persistent\n", + "PSF mismatch. The fitted model selects those intervals, so this panel is a\n", + "visualization of the fit rather than an independent detection statistic.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "**A finite-exposure transit model.** A planet blocks part of the stellar disk.\n", + "Stars generally look dimmer near the visible edge, an effect called limb\n", + "darkening. The adopted quadratic law is\n", + "\n", + "

I(q)/I(1) = 1 \u2212 u\u2081(1 \u2212 q) \u2212 u\u2082(1 \u2212 q)\u00b2.

\n", + "\n", + "I is surface brightness, q is the cosine of the angle between the local\n", + "surface normal and our line of sight (one at disk center, zero at the edge),\n", + "and u\u2081, u\u2082 are dimensionless coefficients. Here u\u2081 = 0.6 and u\u2082 = 0.15\n", + "are declared illustrative values. They are neither atmosphere-table values\n", + "for a measured filter nor a consequence of the blackbody continuum. The\n", + "intensity is normalized to one at disk center; the adopted law gives 0.25 at\n", + "the edge. Changing it tests how inferred radius depends on assumed stellar\n", + "brightness structure.\n", + "\n", + "The model averages blocked light over each 30-second exposure, smoothing rapid\n", + "ingress and egress, the beginning and end of the crossing. `batman` uses seven\n", + "sub-times per exposure in the fit; the generator uses eleven. The fit varies\n", + "radius ratio k = Rp/R\u2605, event midpoint t\u2080, and two\n", + "baseline light-curve terms: a normalization and a linear time slope. Period,\n", + "orbital geometry and limb darkening stay fixed at declared assumptions.\n", + "\n", + "For a uniform disk and a small fully overlapping planet, fractional depth is\n", + "approximately k\u00b2. With limb darkening, peak measured dimming also depends on\n", + "which stellar surface the planet crosses. A physical planet radius requires\n", + "Rp = k R\u2605, hence an assumed or independently measured\n", + "stellar radius. One event does not measure the orbital period. Reported\n", + "parameter errors condition on the fixed assumptions and adopted noise model.\n", + "\n", + "See [Mandel & Agol (2002)](https://arxiv.org/abs/astro-ph/0210099),\n", + "[Kreidberg's batman paper](https://arxiv.org/abs/1507.08285) and\n", + "[the batman tutorial](https://lkreidberg.github.io/batman/docs/html/tutorial.html).\n", + "\n", + "
" + ], + "id": "c30a1117b701" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "transit_fit = transit[\"fit\"]\n", + "tx, ty = np.rint(transit[\"positions\"][0]).astype(int)\n", + "half = transit[\"stamps\"].shape[-1] // 2\n", + "# Preserve sky coordinates for the native-pixel target cutout.\n", + "transit_wcs = WCS(current_reference[\"header\"]).slice(\n", + " (slice(ty - half, ty + half + 1), slice(tx - half, tx + half + 1)))\n", + "show_dark(views.transit_view(\n", + " transit[\"times_minutes\"], transit[\"flux\"], transit[\"flux_error\"],\n", + " transit_fit[\"model\"], stamps=transit[\"stamps\"],\n", + " difference_stamps=transit[\"difference_stamps\"],\n", + " valid=transit[\"valid\"], check_flux=transit[\"check_flux\"],\n", + " reference_stamp=transit[\"reference_stamp\"], pixel_scale=scale,\n", + " wcs=transit_wcs,\n", + " summary={\n", + " \"Radius ratio\": f\"{transit_fit['radius_ratio']:.4f}\",\n", + " \"Conditional 1\u03c3\": f\"{transit_fit['radius_ratio_error']:.4f}\",\n", + " \"Mid-transit [min]\": f\"{transit_fit['midtime_min']:.2f}\",\n", + " }))" + ], + "id": "d920f3d807a1", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Exercise \u00b7 Which comparison stars help?\n", + "\n", + "Reuse the measured flux table to change the comparison ensemble. Columns are\n", + "target, check star, then comparison stars; rows are cadences. Changing\n", + "`comparison_count` changes the common-brightness correction without rerunning\n", + "images. More stars help only if their measurements are useful.\n", + "\n", + "Predict whether using one rather than five comparisons will change the fitted\n", + "radius ratio or residual scatter. Check whether the held-out star also becomes\n", + "steadier. A favorable fit to the target alone is weak evidence for a better\n", + "normalization, because the target contains the signal we want to preserve.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "Inverse-variance weighting gives more influence to a precise comparison star.\n", + "It assumes quoted errors describe useful scatter. A variable, blended or\n", + "systematically biased comparison can make the correction worse despite a\n", + "small formal error. Dividing every star by its own median first puts them on\n", + "a common dimensionless scale. The check star tests the ensemble without taking\n", + "part in its weighted average.\n", + "\n", + "The exercise retains the original quality flags and empirical error scale.\n", + "It changes one analysis choice rather than establishing a new independent\n", + "uncertainty calibration.\n", + "\n", + "
" + ], + "id": "69523b419b52" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "comparison_count = 3 # Choose 1\u20135 from the measured ensemble.\n", + "# Columns: target, check star, comparisons. Rows: cadences.\n", + "raw, raw_error = transit[\"raw_flux\"], transit[\"raw_error\"]\n", + "# Normalize each star by its own median before averaging comparisons.\n", + "med = np.nanmedian(raw, axis=0)\n", + "relative, relative_error = raw / med, raw_error / med\n", + "# Skip target and held-out check columns in the correction ensemble.\n", + "selected = slice(2, 2 + comparison_count)\n", + "comp, comp_error = relative[:, selected], relative_error[:, selected]\n", + "good = np.isfinite(comp) & np.isfinite(comp_error) & (comp_error > 0)\n", + "# Inverse-variance weights: uncertain comparisons contribute less.\n", + "weights = np.where(good, 1 / comp_error**2, 0)\n", + "weight_sum = weights.sum(axis=1)\n", + "ensemble = np.sum(np.where(good, comp, 0) * weights, axis=1) / weight_sum\n", + "trial_flux = relative[:, 0] / ensemble\n", + "# Include target and ensemble noise; retain the original error scale.\n", + "trial_error = np.hypot(relative_error[:, 0] / ensemble,\n", + " trial_flux / np.sqrt(weight_sum) / ensemble)\n", + "trial_valid = transit[\"valid\"] & (weight_sum > 0)\n", + "# Normalize without selecting epochs using hidden truth.\n", + "baseline_flux = np.nanpercentile(trial_flux[trial_valid], 70)\n", + "trial_flux /= baseline_flux\n", + "trial_error *= transit[\"error_scale\"] / baseline_flux\n", + "trial_fit = pipeline.fit_transit(\n", + " transit[\"times_minutes\"], trial_flux, trial_error,\n", + " trial_valid, assumptions)\n", + "print(\"Radius ratio:\", trial_fit[\"radius_ratio\"])\n", + "print(\"Residual scatter:\",\n", + " np.nanstd((trial_flux - trial_fit[\"model\"])[trial_valid]))" + ], + "id": "d951794edc34", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Compare this trial's radius ratio and scatter with the original result. If the\n", + "shift exceeds the quoted error, inspect comparison-star behavior and residuals\n", + "before attributing the change to the planet." + ], + "id": "040c2baa2da0" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Exercise \u00b7 What do we know about the planet?\n", + "\n", + "Change the assumed limb darkening and refit the same measured light curve.\n", + "Compare the radius-ratio shift with the original conditional error. A precise\n", + "answer under one assumed star model can move when that model changes.\n", + "\n", + "The data directly constrain a dimming pattern and its timing. The planet-size\n", + "interpretation additionally depends on stellar brightness structure, crossing\n", + "geometry and stellar radius. A small error printed by an optimizer does not\n", + "include all of those uncertainties.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "If k and stellar radius R\u2605 had independent errors, a first-order\n", + "propagation would give\n", + "\n", + "

(\u03c3Rp/Rp)\u00b2 \u2248 (\u03c3k/k)\u00b2 + (\u03c3R\u2605/R\u2605)\u00b2.

\n", + "\n", + "This illustrates the missing stellar-radius contribution; this notebook does\n", + "not perform that broader inference or assume these terms are independent in\n", + "a real stellar analysis. Changing limb darkening is a sensitivity experiment,\n", + "not a replacement for propagating uncertain assumptions jointly.\n", + "\n", + "
" + ], + "id": "9acb21a847c9" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "# Change one assumption while preserving the measured light curve.\n", + "alternative_assumptions = {**assumptions, \"limb_darkening\": [0.5, 0.2]}\n", + "alternative_fit = pipeline.fit_transit(\n", + " transit[\"times_minutes\"], transit[\"flux\"], transit[\"flux_error\"],\n", + " transit[\"valid\"], alternative_assumptions)\n", + "print(\"Radius-ratio shift:\",\n", + " alternative_fit[\"radius_ratio\"] - transit_fit[\"radius_ratio\"])\n", + "print(\"Original conditional 1\u03c3 error:\", transit_fit[\"radius_ratio_error\"])" + ], + "id": "4253d74ff881", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This shift comes from changing the star's assumed brightness pattern with the\n", + "measured data held fixed. A physical planet radius needs an uncertainty budget\n", + "beyond the local optimizer's error bars." + ], + "id": "f730a9c3f0e2" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## Open the experiment's envelope\n", + "\n", + "Write down your measured motion, radius ratio and event midpoint before running\n", + "the next cell. Injection truth now becomes available for comparison. It was\n", + "not used by the measurement pipeline. A controlled experiment can expose a\n", + "biased answer even when its plots look convincing.\n", + "\n", + "Compare like quantities. Geometric depth k\u00b2 is a ratio of projected areas;\n", + "maximum dimming of a limb-darkened star is different. The designed area ratio\n", + "is about 1.343%; peak dimming additionally depends on the adopted intensity\n", + "law, trajectory and exposure integration. The motion target is about\n", + "94.8 mas/year across ten simulated years. Compare deviations with the stated\n", + "errors rather than rounding them away.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "Existing qualification repeated the pipeline with five independent exposure-\n", + "noise seeds on this fixed scene. All motion, radius-ratio and timing recoveries\n", + "fell within three reported errors. Five draws give only a rough check, not a\n", + "precise estimate of statistical coverage across arbitrary fields. They do not\n", + "sample different stellar populations or uncertain orbital, spectrum,\n", + "limb-darkening and instrument parameters. The underlying analytic field has\n", + "no coadd-measurement error; this simplification is part of the qualification\n", + "boundary. These historical checks describe this Model Sky configuration;\n", + "results from other scenes are not substituted for them.\n", + "\n", + "Negative controls ask whether the procedure reports a signal when it should\n", + "not: stationary targets, constant light, deliberately incompatible reference\n", + "coordinates and fully masked inputs. The contaminated cadence should be rejected. An intentionally wrong\n", + "PSF tests model sensitivity; earlier qualification found biased flux and worse\n", + "residuals. These are historical tests with their own package receipts, not\n", + "additional experiments silently performed by this truth-display cell. Fresh\n", + "execution establishes that this notebook runs; it does not expand those\n", + "scientific coverage claims.\n", + "\n", + "
" + ], + "id": "eb8bb31b5653" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "import json\n", + "# First access to injected answers: measurement and fitting are complete.\n", + "truth_path = pipeline.bundle_path(root, manifest[\"truth\"][\"json\"])\n", + "truth = json.loads(truth_path.read_text())\n", + "display(Markdown(\"```json\\n\" + json.dumps(truth, indent=2) + \"\\n```\"))" + ], + "id": "dc6f17bc48ed", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "### Extension \u00b7 Shorten the baseline, keep the star\n", + "\n", + "The optional cell rebuilds a separate controlled bundle with two years of\n", + "motion instead of ten. It reuses the Model Sky analytic calibration and\n", + "physical configuration, preserves the shared inputs, and writes a separate\n", + "bundle under `results/`. Predict whether the dipole still determines a\n", + "unique displacement. A shorter interval makes the lobes overlap more closely.\n", + "\n", + "Run once in a fresh output directory. A message that motion is unconstrained\n", + "is informative for this case; it is not an instruction to relax the guard\n", + "until the intended answer appears.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "For a small shift vector \u0394, a difference between nearly overlapping PSFs is\n", + "approximately proportional to source flux times \u0394 times the PSF gradient.\n", + "A brighter source moving less can resemble a fainter source moving more.\n", + "This is an identifiability problem: the data constrain a combination of\n", + "parameters more strongly than each parameter alone.\n", + "\n", + "The example rejects a fit when the absolute flux/separation correlation\n", + "exceeds 0.98. That conservative guard is not a universal telescope resolution\n", + "limit. A longer baseline or direct position fits in separate epochs can\n", + "supply different information. Even with a fixed position error, converting\n", + "to motion divides by elapsed time, so a shorter baseline increases the error\n", + "in mas/year.\n", + "\n", + "
" + ], + "id": "b384f11ef903" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "# Attendee opt-in; the executed reference enables this block.\n", + "RUN_BASELINE_EXERCISE = False\n", + "if RUN_BASELINE_EXERCISE:\n", + " from dataclasses import replace\n", + " from model_sky import SceneConfig, prepare_bundle\n", + " # Separate generated dataset; refuse to overwrite an earlier experiment.\n", + " variant_dir = OUTPUT / \"baseline-2yr\"\n", + " if variant_dir.exists():\n", + " raise FileExistsError(\"Choose a new output for this experiment\")\n", + " config = replace(SceneConfig(), baseline_years=2.0)\n", + " prepare_bundle(root / manifest[\"calibration_dir\"], variant_dir,\n", + " config=config)\n", + " variant_root, variant_manifest = pipeline.load_bundle(variant_dir)\n", + " variant_files = variant_manifest[\"files\"]\n", + " earlier = pipeline.read_exposure(pipeline.bundle_path(\n", + " variant_root, variant_files[\"reference_old\"]))\n", + " later = pipeline.read_exposure(pipeline.bundle_path(\n", + " variant_root, variant_files[\"motion\"]))\n", + " try:\n", + " # Rejection can be correct when flux and separation are degenerate.\n", + " recovered = pipeline.measure_motion(\n", + " earlier, later, variant_manifest[\"target_search\"][\"old_xy\"])\n", + " except RuntimeError as exc:\n", + " print(\"Motion is unconstrained for this experiment:\", exc)\n", + " else:\n", + " factor = 1000 * variant_manifest[\"pixel_scale_arcsec\"] / 2\n", + " print(\"Two-year motion [mas/year]:\",\n", + " recovered[\"separation_pixels\"] * factor,\n", + " \"+/-\", recovered[\"separation_error_pixels\"] * factor)" + ], + "id": "97beefe1b3d6", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For the prepared two-year case, the flux/separation guard reports that the\n", + "motion is unconstrained. That outcome is part of the experiment: reducing\n", + "the baseline removes information even though the same GPU fitting routine\n", + "still runs. Preserve the rejection alongside the ten-year result instead of\n", + "reporting the unstable fit as a second precise measurement." + ], + "id": "fa5b23d0716c" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## Keep the result inspectable\n", + "\n", + "Save arrays, summaries and the three interactive chapter views. Their HTML\n", + "embeds plots and displayed data for offline inspection. Moving a slider selects\n", + "existing measurements; changing a scientific assumption still requires\n", + "rerunning the corresponding Python or CLI step.\n", + "\n", + "Chapter files and intermediates live under `results/`. The runner saves\n", + "`model-sky.executed.ipynb` alongside that directory and records input and source\n", + "hashes in `execution.json`. Its output directory contains the source, prepared\n", + "inputs and measured results needed to inspect that execution. The source\n", + "notebook remains free of stored outputs." + ], + "id": "4ca6a4c84b1d" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "workshop.export_views(OUTPUT, manifest, trail, motion, transit)\n", + "print(\"Saved measurement arrays and standalone HTML to\", OUTPUT)" + ], + "id": "a19444cd9109", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
Run the prepared experiment from a terminal\n", + "\n", + "```bash\n", + "python workshop.py all --bundle data --output results\n", + "```\n", + "\n", + "This example runner connects registration, masks, photometry and the\n", + "transit model. Product commands serve individual stages; this runner\n", + "is an example workflow, not an additional cuPhoton product command.\n", + "\n", + "
" + ], + "id": "7bf2a38ed942" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## Optional investigation \u00b7 Could another system make this dip?\n", + "\n", + "A dip alone does not establish a planet. An unresolved **blend** combines light\n", + "from multiple sources in the same footprint. Two stars eclipsing each other\n", + "can lose a great deal of their own light; a brighter neighbor dilutes that\n", + "loss into a shallow dip that resembles a planetary transit.\n", + "\n", + "The optional paired experiment uses the same Model Sky calibration and\n", + "physical star model to compare a planet on the target with a fading neighbor.\n", + "The nearby contaminant is added for this experiment; it is not an observed\n", + "companion or a catalog entry. Each case supplies out-of-event and in-event images, independent\n", + "16-exposure averages at those light levels rather than complete time series.\n", + "xFit fits centers of the source light profiles, a model-based centroid\n", + "measurement, and locates the negative difference signal. A similar aperture depth can hide a\n", + "different location for missing light. An aperture is a region whose pixels\n", + "are summed.\n", + "\n", + "Inspect the cyan reference-position marker and measured fading-light position.\n", + "These controlled snapshots demonstrate source localization. They cannot reveal\n", + "alternating eclipse depths or a second eclipse that was never observed, and a\n", + "small offset does not prove a planet. Repeated events, additional colors,\n", + "spectra and longer time coverage provide different tests.\n", + "\n", + "\n", + "
Science Explanation\n", + "\n", + "Here D = Iin \u2212 Iout, so the fitted fading source has\n", + "negative amplitude. Aperture depth is 1 \u2212 Fin/Fout.\n", + "Extra constant neighbor light contributes to both sums and reduces fractional\n", + "depth. The difference image can instead locate the changing light.\n", + "\n", + "Formal centroid errors condition on a chosen Gaussian model and estimated sky.\n", + "The difference-source and reference centroid share pixels, so their separation\n", + "has no independent significance claim. This does not propagate every PSF or\n", + "background-model uncertainty. [Bryson et al. (2013)](https://arxiv.org/abs/1303.0052)\n", + "describe centroid vetting for Kepler false positives.\n", + "\n", + "Transit photometry measures light loss. Other planet searches measure different\n", + "effects: radial velocity detects a star's motion toward and away from us;\n", + "astrometry detects its wobble across the sky; microlensing detects gravitational\n", + "magnification; direct imaging separates companion light. Combining a mass\n", + "constraint with radius can constrain density. See\n", + "[NASA's detection-method overview](https://science.nasa.gov/exoplanets/how-we-find-and-characterize/)\n", + "and [AAVSO follow-up photometry](https://aavso.org/exoplanet-photometry/).\n", + "\n", + "
" + ], + "id": "b80dba05b8bc" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "# Independent in/out snapshots locate missing light in two cases.\n", + "RUN_BLEND_EXTENSION = False\n", + "if RUN_BLEND_EXTENSION:\n", + " import blend\n", + " from model_sky import SceneConfig\n", + " blend_result = blend.run(root, OUTPUT / \"blend\", config=SceneConfig(), sources=Path(\"sources.md\"))\n", + " show_dark(blend_result[\"layout\"])\n", + " print(\"Saved blend diagnostics to\", blend_result[\"html\"])" + ], + "id": "54f7533ad5d6", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Compare the location of missing light with the target's reference position.\n", + "Similar total dimming can have different spatial explanations. These paired\n", + "images support a localization lesson; they do not establish a planet or\n", + "supply an independent significance for every centroid offset.\n", + "\n", + "xScan is omitted from Model Sky. No trained model, classifier performance or\n", + "inference is claimed for these images." + ], + "id": "669b61844d83" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## Further reading\n", + "\n", + "The bundled source list records scientific techniques, data attribution and\n", + "model inputs. The text and glossary explain terms locally; these links support\n", + "deeper reading when you have a network connection. Opening external references\n", + "is optional for running or viewing the example." + ], + "id": "3bca48f7339d" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "display(Markdown(Path(\"sources.md\").read_text()))" + ], + "id": "7cb52faf0f5a", + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "\n", + "## Science glossary\n", + "\n", + "Dotted terms show a definition on hover or keyboard focus in the HTML. Click or tap one to jump to its entry here; your browser's Back button returns to the reading position. In a notebook, the same links and native hover text work without an extension.\n", + "\n", + "
\n", + "
Adding errors in quadrature
\n", + "
Squaring independent uncertainty sizes, adding those squares, then taking the square root. This combines independent variance contributions; correlations require additional covariance terms.
\n", + "
Angular scale / pixel scale
\n", + "
How much angle on the sky corresponds to one image pixel. The model declares 0.20 arcseconds per pixel. Multiplying pixel separation by this scale gives an angle; converting that angle to a physical distance also requires the distance to the star.
\n", + "
Aperture / annulus
\n", + "
For photometry, an aperture is a selected region around a source; an annulus is a surrounding ring often used to estimate local sky. Aperture can also mean the telescope's light-collecting opening.
\n", + "
Arcsecond / milliarcsecond
\n", + "
An arcsecond is 1/3,600 of a degree, a unit of angle. A milliarcsecond (mas) is 1/1,000 of an arcsecond. mas/yr measures angular change per year; neither unit is a time interval despite the word second.
\n", + "
Astrometry
\n", + "
Measuring where objects appear on the sky and how those positions change. Image alignment and the moving star's position measurement are astrometric tasks.
\n", + "
Background / sky level
\n", + "
Light or detector signal surrounding the source being measured. A local sky estimate removes a nearby baseline level. The modeled background scene contains fixed fictional stars. Diffuse sky light contributes noise even though its mean level has been subtracted.
\n", + "
Bandpass / modeled band
\n", + "
The range of light wavelengths admitted by an instrument, weighted by its sensitivity. Model Sky uses a declared response from 560 to 700 nanometres. This interval is an idealized model, not a measured filter curve or a standard astronomical band.
\n", + "
Blackbody / Planck spectrum
\n", + "
An ideal thermal emitter whose smooth spectrum is set by its temperature through Planck's law. Here 3100 K, an assumed stellar radius and distance set the received light. Real cool stars have molecular absorption missing from this approximation; it is not a measured stellar spectrum.
\n", + "
Blend / unresolved source
\n", + "
Light from different objects overlaps too closely for the image to separate them. A faint eclipsing star behind the target can produce a dip attributed to the wrong object. Unresolved means the components are not separately distinguished.
\n", + "
Cadence
\n", + "
The timing or spacing of observations. Here one 30-second exposure starts each minute. A cadence can also mean one sample in that sequence; rejecting a cadence excludes that exposure from the measurement.
\n", + "
Calibration / calibrated flux
\n", + "
Putting measurements on a common physical or positional scale. Here the electron-to-nJy conversion, pixel scale and coordinate grid are declared model inputs. They keep units consistent within the experiment and do not represent calibration measurements from an actual camera.
\n", + "
Centroid
\n", + "
The estimated centre of an object's light distribution. Fitting several pixels can locate it to a fraction of a pixel. A changing centroid can reveal a blend or an alignment problem.
\n", + "
Check star
\n", + "
A separate star treated as steady and measured like the target, but kept out of the brightness correction. Its remaining fluctuations check whether quoted errors describe the scatter in this field.
\n", + "
Chi-square / reduced chi-square
\n", + "
A sum of squared data-minus-model differences divided by expected variances. Reduced chi-square divides by independent constraints left after fitting. Values above roughly one can signal underestimated errors or a poor model; correlations complicate that rule.
\n", + "
Coadd / averaged reference
\n", + "
An image combining aligned exposures, often by averaging. Each Model Sky reference is generated with the noise of a mean of 16 independent, equal-duration exposures. It still has noise shared by later measurements that reuse it. The underlying model sky itself is noiseless.
\n", + "
Comparison star / ensemble
\n", + "
A nearby star assumed steady during the sequence. Changes common to several such stars estimate changes in observing conditions. An ensemble combines their measurements to correct the target's light curve.
\n", + "
Conditional uncertainty
\n", + "
An error estimate holding stated assumptions fixed. Here the analytic sky, stellar properties, orbit and much of the detector model are fixed while exposure noise varies. Repeated noise realizations do not cover every way those model assumptions could be wrong.
\n", + "
Convolution
\n", + "
Replacing each pixel with a weighted combination of nearby pixels. The weights form a small array called a kernel. Here convolution broadens reference stars to match the science image's blur.
\n", + "
Correlated noise
\n", + "
Errors that move together. Resampling can reuse one input pixel in several output pixels, correlating their errors. A shared reference can also correlate measurements from different exposures.
\n", + "
Cosine / surface normal
\n", + "
Cosine describes the projection of one direction onto another: 1 when aligned and 0 at a right angle. A surface normal is perpendicular to a surface. In limb darkening, the angle describes how directly we view a patch of the star.
\n", + "
Covariance
\n", + "
A measure of how errors in two quantities vary together. A covariance matrix records these relationships as well as each quantity's variance. It matters when combining fitted positions into a separation error.
\n", + "
Degrees of freedom
\n", + "
Independent constraints remaining after fitting parameters. For a simple fit with independent errors, this is the number of data points minus the number of fitted parameters.
\n", + "
Difference image / difference flux
\n", + "
Science minus the PSF-matched reference and fitted background. Positive pixels mean extra light relative to that reference; negative pixels mean less. Difference flux measures the change, not all the light from a source.
\n", + "
Dipole
\n", + "
A paired positive and negative patch in a difference image. When a star moves, its new position leaves added light and its old position leaves missing light after subtraction. Dipole means two lobes here, not an electrical property of the star. Misaligned images can make similar patterns.
\n", + "
Direct imaging
\n", + "
Separating and detecting light from a planet beside its much brighter host star. This differs from inferring a planet through a change in the star's total light.
\n", + "
Displacement
\n", + "
A change in position with both size and direction. New position minus old position gives a two-component displacement in pixels. Its length is the separation.
\n", + "
Eccentricity
\n", + "
How stretched an orbit is: zero is a circle, while larger values below one describe increasingly elongated bound orbits. The adopted shape affects how fast a planet crosses the star.
\n", + "
Eclipse / eclipsing binary
\n", + "
Dimming when one body passes in front of another. An eclipsing binary is a pair of orbiting stars whose alignment causes dips. Its light can mimic a planet transit, especially when mixed with another star's light.
\n", + "
Electron / detector count
\n", + "
A particle carrying electric charge. A camera records charge produced when light is detected. Here electron counts are simulated using the declared telescope area, exposure time and efficiency, then converted to nJy. Photon-counting fluctuations and read noise enter in these count units; no raw camera counts are imported.
\n", + "
Empirical
\n", + "
Estimated from measurements rather than supplied as a model parameter. Here the measurement pipeline estimates PSFs from stars in the simulated images and error scales from their measured scatter. These estimates are independent of the withheld injection truth; empirical does not mean an observed astronomical image was imported.
\n", + "
Epoch
\n", + "
The time associated with an observation or reference position. The old and current motion epochs are simulated points ten years apart; the short transit sequence samples the current epoch.
\n", + "
Exoplanet
\n", + "
A planet outside our Solar System. A transit-shaped dip is evidence to investigate, not sufficient proof that an exoplanet caused it.
\n", + "
Exposure / visit
\n", + "
A period during which a detector collects light, and the resulting measurement. A visit is a telescope observation with timing and pointing. Each simulated exposure here averages incoming light over 30 seconds.
\n", + "
Exposure integration
\n", + "
Averaging the model over the time the detector collects light. A 30-second exposure does not measure a single instant; averaging can soften the transit's entry and exit compared with an instantaneous model.
\n", + "
Extinction
\n", + "
Dimming of starlight by absorption or scattering along its path, for example by interstellar dust. The Model Sky brightness calculation sets interstellar extinction to zero. That assumption is distinct from the instrument's modeled photon-detection efficiency.
\n", + "
False positive
\n", + "
A signal accepted as the event of interest even though another cause produced it. Blended eclipsing stars and instrumental changes can produce planet-like brightness dips.
\n", + "
FITS / HDU / plane
\n", + "
FITS is an astronomy file format for numerical arrays and metadata. Each header/data unit (HDU) is one named or numbered section. A plane here is a two-dimensional array: brightness, estimated variance, or pixel-quality flags on matching coordinates.
\n", + "
Flux / flux density
\n", + "
A measure of received light. This example uses nJy, a flux-density unit describing brightness per unit frequency. Summing or fitting a star's pixel pattern estimates its total brightness in that band.
\n", + "
Forced PSF photometry
\n", + "
Fitting a known star-shaped light pattern at a supplied position to measure brightness. Forced means the position is supplied even if that exposure alone has too little signal to detect the source.
\n", + "
Gaussian
\n", + "
A smooth bell-shaped function used to approximate blur or random-error distributions. A Gaussian-polynomial basis combines bell shapes with coordinate-dependent terms to describe more varied kernels.
\n", + "
Gradient / propagated error
\n", + "
A gradient records how a result changes for a small change in each input. Error propagation uses those sensitivities and the input covariance to estimate the result's uncertainty. This approximation is local to the fitted values.
\n", + "
Gravitational microlensing
\n", + "
Temporary brightening when a foreground object's gravity bends and magnifies light from a more distant star. A planet can alter that pattern, providing a detection method distinct from transits.
\n", + "
Ground truth / injection
\n", + "
Known values used to create a simulated signal, such as position or planet radius. An injection adds that controlled signal to the scene. Truth is withheld from measurement so recovery can be checked afterward.
\n", + "
Identifiability / degeneracy
\n", + "
Whether data can distinguish parameter choices. A brighter star with smaller motion can produce nearly the same pattern as a fainter star with larger motion; their values are then degenerate. A converged fit does not resolve this ambiguity by itself.
\n", + "
Image-matching kernel / basis
\n", + "
A small array of convolution weights reshaping the reference to match the science image. The basis supplies allowed patterns whose coefficients are fitted. This differs from a GPU program kernel or a notebook's Python process.
\n", + "
Impact parameter
\n", + "
How far from the star's apparent centre the planet passes at mid-transit, measured in stellar radii. Zero crosses the centre; a value near one passes near the edge and changes the shape and duration.
\n", + "
Interpolation / resampling
\n", + "
Estimating values between existing samples. Here, reprojection resamples input pixels onto a new grid using weighted neighbours. This changes how noise is shared between pixels; it does not create new independent data.
\n", + "
Latent sky / noiseless scene
\n", + "
The underlying expected image before random measurement noise is drawn. Here it is built from fictional stars and analytic light profiles. Each exposure applies its own blur, shift and brightness changes before receiving independent noise. Reusing this noiseless model does not reuse a previous exposure's random errors.
\n", + "
Least-squares fit
\n", + "
Choosing parameters to minimize squared data-minus-model differences. Weighting gives more reliable measurements more influence, often by dividing each squared difference by its estimated variance.
\n", + "
Light curve
\n", + "
Brightness plotted against time. Here each point is one exposure's brightness after correcting changes shared with comparison stars. A transit appears as a temporary downward dip.
\n", + "
Light-year
\n", + "
The distance light travels in one year in vacuum, about 9.46 trillion kilometres. It is a distance, not a duration.
\n", + "
Limb darkening
\n", + "
The star's visible edge is dimmer than its centre, so a crossing planet blocks different amounts of light along its path. This experiment declares a quadratic intensity law with coefficients 0.6 and 0.15. That shape is prescribed separately from the blackbody calculation of the star's total brightness.
\n", + "
Magnitude / AB magnitude
\n", + "
Astronomy's logarithmic brightness scale: smaller numbers mean brighter objects, and five magnitudes correspond to a factor of 100 in brightness. The AB convention uses a reference flux density of 3631 Jy. The modeled star has AB magnitude about 17.54 through the declared bandpass.
\n", + "
Marginal variance / uncertainty
\n", + "
Here marginal variance means one pixel's individual variance, a diagonal entry of the joint covariance. It does not include cross-pixel covariance or imply that kernel-fit uncertainty was integrated out. In other contexts marginalizing parameters means averaging over their possible values.
\n", + "
Mask
\n", + "
Flags or Boolean selections describing which measurements a stage may use. A quality mask records defects; a fit mask selects allowed pixels. Check the convention: True can mean included for a fit mask and excluded for a trail mask. Masking discards information.
\n", + "
Mid-transit time
\n", + "
The time at the centre of the transit. The fit estimates when the crossing is centred relative to the sequence's time origin. This differs from measuring the orbital period between repeated transits.
\n", + "
NaN / invalid measurement
\n", + "
A missing or invalid numerical result. A rejected exposure receives NaN flux rather than zero: zero would be a real brightness measurement and could falsely imply that the star disappeared.
\n", + "
nJy (nanojansky)
\n", + "
One nanojansky is 10\u207b\u2079 jansky, or 10\u207b\u00b3\u2075 watts per square metre per hertz. Here each pixel contains its contribution to modeled flux density. Summing or fitting a star's pattern estimates its brightness in the declared band. Variance in nJy\u00b2 describes squared brightness uncertainty.
\n", + "
Noise / photon noise
\n", + "
Random variation in a measurement. Photon arrivals fluctuate even for a steady star; sky light and the detector add variation too. Reusing one noisy image copies its errors instead of generating independent exposures.
\n", + "
Normalization / relative flux
\n", + "
Rescaling to a chosen reference. A normalized PSF has pixel weights adding to 1. A light curve divided by its usual brightness is near 1; 0.99 is one per cent dimmer. Comparison-star normalization corrects changes shared across the field.
\n", + "
Orbit / orbital period
\n", + "
The path of one body around another under gravity. The orbital period is the time for a full circuit. The example assumes a period from its chosen model; one short transit sequence does not measure it.
\n", + "
Orbital inclination
\n", + "
The tilt of the orbit relative to the sky plane. In the transit model, 90 degrees means the orbit is viewed edge-on, making a crossing possible.
\n", + "
Parallax
\n", + "
An apparent position shift caused by a changing viewpoint. Annual parallax follows Earth's orbit and helps measure distance. This experiment models a star's linear proper motion only; it includes no annual parallax signal and does not measure the assumed stellar distance.
\n", + "
Parsec (pc)
\n", + "
A distance unit of about 3.26 light-years. One parsec corresponds to a star with annual parallax of one arcsecond. The simulated star's 146.42 pc distance is an assumption, not a distance measured here.
\n", + "
Photometry
\n", + "
Measuring an object's brightness. This notebook fits the star's expected pattern to pixels and repeats the measurement through time to obtain a light curve.
\n", + "
Photon
\n", + "
A quantum, or discrete packet, of light. A detector converts incoming photons into an electrical signal. Photon arrival counts fluctuate, so even a perfectly steady source has measurement noise.
\n", + "
Poisson statistics
\n", + "
A model for independent random event counts. For a mean count N, count variance is N and standard deviation is \u221aN. Calibrated flux units and detector/background effects must be included before applying this rule to image values.
\n", + "
Positive / negative lobe
\n", + "
One patch of a dipole's two-part pattern. The positive lobe has more light in science than reference; the negative lobe has less. Negative values describe subtraction, not physically negative light.
\n", + "
Proper motion
\n", + "
A star's gradual angular movement across the sky, usually in milliarcseconds per year. It is not the full three-dimensional speed; converting to a sideways physical speed also requires distance.
\n", + "
PSF (point-spread function)
\n", + "
The pixel pattern made by one unresolved point of light. Preparation uses a Gaussian profile plus each exposure's common seeing blur for both field and target stars. Measurement estimates a PSF from image stars without reading that input profile. Matching PSFs makes images comparable before subtraction.
\n", + "
Radial velocity
\n", + "
Speed toward or away from the observer. A planet and star orbit their common centre of mass; changes in the star's radial velocity can reveal the planet. This needs spectral observations, not just the transit light curve.
\n", + "
Radius ratio / transit depth
\n", + "
Radius ratio k is planet radius divided by star radius. For a small planet crossing a uniformly bright star, fractional blocked light is about k\u00b2. Limb darkening and the crossing path change the actual dip. Physical planet radius also needs an assumed stellar radius.
\n", + "
Read noise
\n", + "
Random variation introduced when detector electronics read accumulated charge. It can occur even with no incoming light. The model assigns 5 electrons of standard deviation per pixel per exposure and combines its variance with sky noise before converting to nJy\u00b2.
\n", + "
Reference / template
\n", + "
The comparison image against which science is measured. An old-position reference reveals motion. A current-position, outside-transit reference measures dimming at the present location. The reference also has noise.
\n", + "
Registration
\n", + "
Aligning images so the same array coordinates describe the same sky position. WCS metadata gives the initial mapping; stationary neighbouring stars check the remaining alignment error.
\n", + "
Residual
\n", + "
What remains after subtracting a model from data. In image subtraction it highlights changes and mismatches. After a dipole or transit fit, structured leftovers can show that the model missed something.
\n", + "
RMS (root mean square)
\n", + "
Square each value, average the squares, then take the square root. For residuals this summarizes typical size in original units without positive and negative values cancelling. Large outliers strongly affect it.
\n", + "
Sampling / undersampling
\n", + "
Representing a continuous pattern with finite pixels or time steps. Undersampling means too few samples to resolve its shape. Subpixel describes positions or model steps finer than one detector pixel; it does not add new observed pixels.
\n", + "
Saturation
\n", + "
A detector or recorded value reaching its usable upper limit. Such a pixel no longer reliably measures how much light arrived. Model Sky does not simulate saturation; real-camera data would need suitable quality flags and detector-specific limits.
\n", + "
Science image
\n", + "
The exposure being investigated, compared with a reference image. Registered science is that measurement resampled onto the reference grid. Science here labels the image's role in the comparison.
\n", + "
Seeing
\n", + "
Blurring and distortion caused by Earth's turbulent atmosphere. Here a declared blur varies across exposures and affects all stars in each exposure consistently. It illustrates changing image quality without importing an atmospheric measurement or simulating all turbulence effects.
\n", + "
Signal-to-noise ratio (S/N)
\n", + "
Signal size compared with estimated random uncertainty. Higher values make random fluctuations a less plausible explanation, but do not rule out systematic errors or a wrong model.
\n", + "
Sky plane / line of sight
\n", + "
The sky plane describes directions across the image, perpendicular to the direction toward the observer. Motion in this plane changes apparent position; line-of-sight motion is toward or away from us.
\n", + "
Spectrum / stellar atmosphere
\n", + "
A spectrum describes light at each wavelength or frequency. A stellar atmosphere is the outer gas that shapes a star's escaping light. Model Sky uses a smooth blackbody spectrum in place of an atmosphere model; molecular absorption and other spectral features are omitted.
\n", + "
Stamp
\n", + "
A small image cutout around an object or candidate. Fitting a stamp uses nearby pixels without processing the full field for each source.
\n", + "
Standard deviation / sigma
\n", + "
A measure of spread, equal to the square root of variance. For an accurate Gaussian error model about 68% of repeated errors fall within \u00b11 sigma. That interpretation needs the model assumptions to hold.
\n", + "
Stellar radius / solar radius
\n", + "
The distance from a star's centre to its visible surface. A solar radius uses the Sun's radius as a unit. Here an assumed stellar radius turns the fitted planet-to-star radius ratio into a planet size.
\n", + "
Sum / summation
\n", + "
Adding a collection of numbers. The symbol \u03a3 means sum over the stated index. A weighted sum first multiplies each value by its weight; a weighted average divides by the total weight.
\n", + "
Systematic errors / systematics
\n", + "
Repeatable biases or patterns left by calibration, observing conditions or a wrong model. More samples may not average them away. Comparison stars and residuals help expose some of them.
\n", + "
Throughput / instrument response
\n", + "
The fraction of incoming light converted into recorded signal after all optical and detector losses. Here the declared total photon efficiency is 0.4 from 560 to 700 nanometres and zero outside that band. This is an optical model input, not GPU operations per second.
\n", + "
Time baseline
\n", + "
Elapsed time between position measurements. A longer interval lets a slowly moving star travel farther in the image. The default ten-year interval is an input to the simulated motion experiment; it is not elapsed observing time or the length of the short transit sequence.
\n", + "
Top-hat response
\n", + "
An idealized response that is constant inside a specified interval and zero outside it, with sharp edges. The Model Sky passband has this shape from 560 to 700 nanometres. Real filters generally have rounded edges and wavelength-dependent sensitivity.
\n", + "
Transit / ingress / egress
\n", + "
A planet or other body crossing in front of its star as seen by us, temporarily blocking starlight. Ingress is entry onto the visible disc; egress is exit. The example creates a simulated planet transit with a physical light-curve model.
\n", + "
Uncertainty / formal error
\n", + "
An estimate of precision under stated assumptions. Formal fit error comes from the fit model and supplied noise. It can omit alignment errors, shared-reference errors or wrong assumptions; it is not a guaranteed bound.
\n", + "
Uncertainty coverage
\n", + "
For uncertainty checks, the fraction of repeated experiments whose error interval contains the true value. A few successful trials cannot establish that fraction precisely. Image coverage means which sky area or pixels are available.
\n", + "
Variance
\n", + "
Expected squared fluctuation around a mean. Its square root is the standard deviation. Brightness in nJy has variance in nJy\u00b2. A per-pixel variance plane records individual error sizes but not all correlations between pixels.
\n", + "
Wavelength / frequency
\n", + "
Wavelength is the spacing between successive crests of a light wave. Frequency counts its oscillations per second. Higher frequency means shorter wavelength; visible colours correspond to different wavelengths.
\n", + "
WCS (World Coordinate System)
\n", + "
Metadata mapping pixels to sky coordinates. Right ascension and declination locate a direction, like longitude and latitude on Earth. Here the grid and exposure shifts are declared inputs around RA 210 degrees and Dec \u221210 degrees, not a solution fitted to a catalog. Stationary stars still check the image-registration accuracy.
\n", + "
Reprojection
\n", + "
Resampling an image onto a specified sky coordinate grid using a supplied coordinate mapping. It does not itself estimate alignment corrections from stars.
\n", + "
\n", + "\n", + "These definitions describe the Model Sky experiment. See the [NASA FITS primer](https://fits.gsfc.nasa.gov/fits_primer.html), [Astropy WCS documentation](https://docs.astropy.org/en/stable/wcs/wcsapi.html), [Astropy blackbody model](https://docs.astropy.org/en/stable/modeling/physical_models.html#blackbody), [NASA planet-detection overview](https://science.nasa.gov/exoplanets/how-we-find-and-characterize/) and the primary papers linked beside each Science Explanation." + ], + "id": "c6479296eacb" + } + ], + "nbformat": 4, + "nbformat_minor": 5, + "metadata": { + "kernelspec": { + "display_name": "Python 3 (cuPhoton)", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "version": "3.12" + }, + "license": "Apache-2.0", + "copyright": "Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES.", + "cuphoton_edition": "model-sky", + "title": "Model Sky", + "execute": { + "enabled": false + } + } +} diff --git a/examples/model-sky/model_sky.py b/examples/model-sky/model_sky.py new file mode 100644 index 00000000..c2f9623a --- /dev/null +++ b/examples/model-sky/model_sky.py @@ -0,0 +1,243 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Independent analytic sky and instrument for Model Sky. + +No downloads, observed catalogs, measured PSFs or empirical calibrations. +Only preparation reads the physical model; pipeline.py measures image planes. +""" + +from __future__ import annotations + +import argparse +import json +from dataclasses import dataclass +from pathlib import Path + +import numpy as np +from astropy.constants import R_sun, c, h, k_B, pc +from astropy.io import fits +from astropy.wcs import WCS +from scene import SceneConfig as BaseConfig +from scene import _source_positions, add_star, prepare_bundle, sha256 + + +def brightness(): + """Photon-weighted AB flux and electrons, using SI Planck radiance.""" + wavelength = np.linspace(560e-9, 700e-9, 4097) + response = np.full(wavelength.shape, 0.4) + dilution = (0.2162 * R_sun.value / (146.42 * pc.value)) ** 2 + surface = (2 * h.value * c.value**2 / wavelength**5) / np.expm1( + h.value * c.value / (wavelength * k_B.value * 3100) + ) + flam = np.pi * surface * dilution # W m^-2 m^-1 at Earth + fnu = np.trapezoid(flam * wavelength * response, wavelength) / ( + c.value * np.trapezoid(response / wavelength, wavelength) + ) + area = np.pi * (4.0 / 2) ** 2 # modeled unobstructed 4 m telescope + electrons_per_njy = ( + area + * 30 + * 1e-35 + / h.value + * np.trapezoid(response / wavelength, wavelength) + ) + return { + "flux_njy": float(fnu / 1e-35), + "ab_magnitude": float(-2.5 * np.log10(fnu / (3631e-26))), + "electrons_per_njy": float(electrons_per_njy), + "nJy_per_electron": float(1 / electrons_per_njy), + "temperature_k": 3100, + "radius_solar": 0.2162, + "distance_pc": 146.42, + "effective_area_m2": area, + "exposure_s": 30, + "bandpass": "modeled 560-700 nm top hat; total efficiency 0.4", + "spectrum": "Planck blackbody; pi B_lambda (R/d)^2; zero extinction", + "limb_darkening": [0.6, 0.15], + "limb_darkening_scope": ( + "Explicit illustrative quadratic intensity law; not an " + "atmosphere table or derived from the blackbody." + ), + "limitations": ( + "An M dwarf has molecular absorption absent from a " + "blackbody. This is a declared idealized instrument and " + "star, not calibrated r-band photometry or a prediction for" + " GJ 1214." + ), + } + + +@dataclass(frozen=True) +class SceneConfig(BaseConfig): + target_flux_njy: float = brightness()["flux_njy"] + limb_darkening_u1: float = 0.6 + limb_darkening_u2: float = 0.15 + + +def prepare(output, *, force=False): + output = Path(output) + if ( + output.exists() + and not force + and (not output.is_dir() or any(output.iterdir())) + ): + raise ValueError( + "output must be absent or empty; use --force to regenerate" + ) + calibration = output / "provenance" + calibration.mkdir(parents=True, exist_ok=True) + audit = brightness() + shape = (480, 480) + y, x = np.indices((41, 41)) + psf = np.exp(-0.5 * ((x - 20) ** 2 + (y - 20) ** 2) / 1.5**2) + psf /= psf.sum() + background = np.zeros(shape) + bad = np.zeros(shape, np.uint8) + # Reserve the same geometric anchor regions for injected target/standards. + anchors = _source_positions(background, bad) + rng = np.random.default_rng(260630) + positions = [] + for _ in range(120): + point = rng.uniform(36, 444, 2) + if np.min(np.linalg.norm(anchors - point, axis=1)) < 48: + continue + if ( + positions + and np.min(np.linalg.norm(np.array(positions) - point, axis=1)) + < 24 + ): + continue + positions.append(point) + add_star( + background, + psf, + point, + audit["flux_njy"] * rng.uniform(0.25, 0.95), + ) + # Sky of 20.5 AB mag/arcsec^2 in the modeled band; mean sky subtracted. + sky_njy_pixel = 3631e9 * 10 ** (-0.4 * 20.5) * 0.2**2 + noise_scale = audit["nJy_per_electron"] + sky_variance = sky_njy_pixel * noise_scale + (5 * noise_scale) ** 2 + wcs = WCS(naxis=2) + wcs.wcs.crpix = [240.5, 240.5] + wcs.wcs.crval = [210, -10] + wcs.wcs.cdelt = [-0.2 / 3600, 0.2 / 3600] + wcs.wcs.ctype = ["RA---TAN", "DEC--TAN"] + np.savez_compressed( + calibration / "calibration.npz", + background=background, + base_psf=psf, + sky_variance=np.full(shape, sky_variance), + noise_scale=np.full(shape, noise_scale), + quality_mask=bad, + ) + fits.PrimaryHDU( + background.astype(np.float32), header=wcs.to_header() + ).writeto(calibration / "calibration.fits", overwrite=True, checksum=True) + metadata = { + "edition": "Model Sky", + "modeled_scene": True, + "quality_mask_is_binary": True, + "pixel_scale_arcsec": 0.2, + "origin": "Analytic models in model_sky.py; fixed RNG seed 260630", + "license": "NVIDIA-generated modeled arrays; Apache-2.0", + "catalog": "Uniform isolated fictional stars; no observed catalog", + "wcs": ( + "Declared TAN grid at RA 210 deg, Dec -10 deg, 0.2 " + "arcsec/pixel; no observed solution" + ), + "psf": ( + "Normalized analytic Gaussian sigma 1.5 pixels; identical " + "base for background and target, common seeing blur per " + "exposure" + ), + "sky_ab_mag_arcsec2": 20.5, + "read_noise_electrons": 5, + "background_stars": len(positions), + "photometric_model": audit, + "simulation_notes": [ + ( + "All pixels, WCS, stars, masks, PSFs, variance and " + "throughput are generated independently of " + "observational data." + ), + ( + "30 second exposures once per minute, 120 epochs; " + "separate old/current 16-exposure references and a " + "ten-year proper-motion baseline." + ), + ( + "Field, target and comparison stars share analytic base" + " PSF and per-exposure seeing, transparency and dither." + ), + ( + "Source Poisson electrons and independent Gaussian " + "sky/read noise: variance [nJy^2] = a * source [nJy] + " + "sky_variance; a is nJy/electron. References divide " + "variance by 16." + ), + ( + "Sky Gaussian approximation applies to the high " + "sky-electron count; sky mean is subtracted. Constant " + "gain, no saturation, no scintillation or color terms " + "are modeled." + ), + ( + "The fixed latent sky is noiseless; independent " + "exposure noise is sampled after transformation. Truth " + "is written separately; empirical PSFs and comparisons " + "are selected from images." + ), + ( + "Transit uses batman, 11 subexposures per 30 second " + "integration, declared quadratic limb darkening " + "(0.6,0.15), circular orbit and GJ 1214-inspired " + "geometry. This is not an observed planet discovery." + ), + ( + "Trail is an analytic double-lobed teaching model with " + "width 2.8 arcsec, not an instrument measurement or " + "satellite ray trace." + ), + ( + "Blackbody flux is computed at 146.42 pc, radius 0.2162" + " solar, 3100 K, through modeled 560-700 nm response. " + "Molecular absorption is omitted; no empirical r-band " + "calibration is claimed." + ), + ( + "xScan omitted: no trained classifier or performance " + "claim is included." + ), + ], + "references": { + "gj1214_discovery": "https://arxiv.org/abs/0912.3229", + "system_parameters": "https://arxiv.org/html/2402.05991v2", + "batman": "https://arxiv.org/abs/1507.08285", + "subtraction": "https://arxiv.org/abs/astro-ph/9712287", + }, + "generator_sha256": sha256(Path(__file__)), + } + (calibration / "calibration.json").write_text( + json.dumps(metadata, indent=2) + "\n" + ) + # Stage beside the output so provenance copies use distinct paths. + import shutil + import tempfile + + with tempfile.TemporaryDirectory(dir=output.parent) as temporary: + for path in calibration.glob("calibration.*"): + shutil.copy2(path, Path(temporary) / path.name) + manifest = prepare_bundle( + temporary, output, config=SceneConfig(), force=force + ) + return manifest + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, default=Path("data")) + parser.add_argument("--force", action="store_true") + args = parser.parse_args() + prepare(args.output, force=args.force) + print(json.dumps(brightness(), indent=2)) diff --git a/examples/model-sky/notebook_style.py b/examples/model-sky/notebook_style.py new file mode 100644 index 00000000..1f44fe21 --- /dev/null +++ b/examples/model-sky/notebook_style.py @@ -0,0 +1,108 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Presentation-only styling for the Model Sky notebook figures.""" + +from bokeh.io import show +from bokeh.models import ( + Axis, + ColorBar, + ColumnDataSource, + CustomJS, + Div, + Glyph, + Grid, + Legend, + Plot, + Title, + Toolbar, + Widget, +) + +_BACKGROUND = "#10180d" +_TEXT = "#f0f4eb" +_MUTED = "#b7c9a9" +_BORDER = "#34472b" +_TEXT_COLORS = { + "#172b45": _TEXT, + "#52647c": _MUTED, + "#f0f6fa": "#182310", + "#f7f9fc": _BACKGROUND, +} +_GLYPH_COLORS = { + "#007f99": "#67d5e5", + "#ab3d75": "#ed91bd", + "#657385": "#82938a", + "#8190a3": "#93a6b8", +} +_WIDGET_CSS = """ +:host { color: #f0f4eb; color-scheme: dark; } +.bk-btn { color: #f0f4eb; background: #1c2815; border-color: #465d35; } +.bk-btn:hover { background: #2b3d1c; } +.bk-btn.bk-active, .bk-btn-primary { + color: #0b1008; background: #b5ed39; border-color: #b5ed39; +} +.bk-input { color: #f0f4eb; background: #121a0e; border-color: #465d35; } +.bk-slider-title, .bk-input-group { color: #f0f4eb; } +.bk-toolbar-button { background-color: #1c2815; } +""" + + +def _text_colors(text): + for before, after in _TEXT_COLORS.items(): + text = text.replace(before, after) + return text + + +def show_dark(layout): + """Show a dark Bokeh layout, preserving data and scientific palettes.""" + for model in layout.references(): + if isinstance(model, Plot): + model.background_fill_color = _BACKGROUND + model.border_fill_color = _BACKGROUND + model.outline_line_color = _BORDER + elif isinstance(model, Axis): + model.axis_label_text_color = _MUTED + model.major_label_text_color = _MUTED + model.axis_line_color = _BORDER + model.major_tick_line_color = _BORDER + elif isinstance(model, Grid): + model.grid_line_color = _BORDER + model.grid_line_alpha = 0.5 + elif isinstance(model, Title): + model.text_color = _TEXT + elif isinstance(model, ColorBar): + model.background_fill_color = _BACKGROUND + model.major_label_text_color = _MUTED + model.title_text_color = _TEXT + model.major_tick_line_color = _MUTED + elif isinstance(model, Legend): + model.background_fill_color = _BACKGROUND + model.label_text_color = _TEXT + model.border_line_color = _BORDER + elif isinstance(model, Div): + model.text = _text_colors(model.text) + model.styles = { + key: _text_colors(value) if isinstance(value, str) else value + for key, value in model.styles.items() + } + elif isinstance(model, CustomJS): + # Dynamic readouts use the same explicit CSS colors as the Divs. + model.code = _text_colors(model.code) + if isinstance(model, ColumnDataSource) and "color" in model.data: + colors = model.data["color"] + if all(isinstance(color, str) for color in colors): + model.data = { + **model.data, + "color": [ + _GLYPH_COLORS.get(color, color) for color in colors + ], + } + if isinstance(model, Glyph): + for attr in ("line_color", "fill_color"): + if attr in model.properties(): + color = getattr(model, attr) + if isinstance(color, str) and color in _GLYPH_COLORS: + setattr(model, attr, _GLYPH_COLORS[color]) + if isinstance(model, (Widget, Toolbar)): + model.stylesheets = [*model.stylesheets, _WIDGET_CSS] + return show(layout) diff --git a/examples/model-sky/pipeline.py b/examples/model-sky/pipeline.py new file mode 100644 index 00000000..0c1b9d87 --- /dev/null +++ b/examples/model-sky/pipeline.py @@ -0,0 +1,672 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Workshop measurements using cuPhoton. Never reads injection truth.""" + +from __future__ import annotations + +import json +from pathlib import Path +from time import perf_counter + +import numpy as np +from astropy.io import fits +from astropy.wcs import WCS +from scipy import ndimage +from scipy.optimize import least_squares + +from cuphoton.xfit import ( + StampDipoleModel, + fit_dipoles, + fit_single_sources, + forced_psf_photometry, +) +from cuphoton.xpois import ( + GaussianBasisComponent, + solve_constant_kernel, + standardize_constant_kernel_residual, +) +from cuphoton.xrep import ( + BBox, + ReprojectionSpec, + make_wcs_pair_transform, + reproject_masked_array, +) + + +def gpu(): + """Require CUDA rather than silently demonstrate a CPU fallback.""" + import cupy as cp + + cp.cuda.runtime.getDeviceCount() + cp.cuda.Device().use() + return cp + + +def load_bundle(root): + root = Path(root).resolve() + return root, json.loads((root / "bundle.json").read_text()) + + +def bundle_path(root, relative): + root = Path(root).resolve() + path = (root / relative).resolve() + if not path.is_relative_to(root): + raise ValueError("bundle paths must remain within the bundle") + return path + + +def read_exposure(path): + with fits.open(path) as hdus: + return { + "science": np.asarray(hdus["SCI"].data, dtype=float), + "variance": np.asarray(hdus["VAR"].data, dtype=float), + "mask": np.asarray(hdus["MASK"].data, dtype=np.uint32), + "header": hdus["SCI"].header.copy(), + } + + +def write_exposure(path, exposure): + Path(path).parent.mkdir(parents=True, exist_ok=True) + fits.HDUList( + [ + fits.PrimaryHDU(), + fits.ImageHDU( + exposure["science"], exposure["header"], name="SCI" + ), + fits.ImageHDU(exposure["variance"], name="VAR"), + fits.ImageHDU(exposure["mask"].astype(np.uint32), name="MASK"), + ] + ).writeto(path, overwrite=True) + + +def good_pixels(exposure): + return ( + (exposure["mask"] == 0) + & np.isfinite(exposure["science"]) + & np.isfinite(exposure["variance"]) + & (exposure["variance"] > 0) + ) + + +def stamp(image, xy, size=41): + x, y = np.rint(xy).astype(int) + half = size // 2 + part = image[y - half : y + half + 1, x - half : x + half + 1] + if part.shape != (size, size): + raise ValueError("source too close to an image boundary") + return part.copy() + + +def local_sky(image): + yy, xx = np.indices(image.shape) + radius = np.hypot( + xx - (image.shape[1] - 1) / 2, yy - (image.shape[0] - 1) / 2 + ) + annulus = image[ + (radius > image.shape[0] * 0.34) & (radius < image.shape[0] * 0.49) + ] + return float(np.nanmedian(annulus)) + + +def select_stars(exposure, *, exclude=(), count=12, margin=28): + """Example helper: separated compact peaks selected from the image.""" + data = exposure["science"] + smoothed = ndimage.gaussian_filter(np.nan_to_num(data), 1.2) + noise = np.sqrt(np.nanmedian(exposure["variance"])) + peaks = smoothed == ndimage.maximum_filter(smoothed, size=15) + peaks &= smoothed > np.nanmedian(smoothed) + 10 * noise + peaks &= good_pixels(exposure) + peaks[:margin] = peaks[-margin:] = False + peaks[:, :margin] = peaks[:, -margin:] = False + ys, xs = np.where(peaks) + selected = [] + for i in np.argsort(smoothed[ys, xs])[::-1]: + xy = np.array([xs[i], ys[i]], dtype=float) + if any(np.linalg.norm(xy - p) < 32 for p in [*exclude, *selected]): + continue + patch = stamp(data, xy, 31) + signal = np.maximum(patch - local_sky(patch), 0) + yy, xx = np.indices(signal.shape) + radius2 = (xx - 15) ** 2 + (yy - 15) ** 2 + signal[radius2 > 8**2] = 0 + if signal.sum() <= 0: + continue + sigma = np.sqrt((signal * radius2).sum() / signal.sum() / 2) + if 1.2 < sigma < 4.5 and stamp(good_pixels(exposure), xy, 17).all(): + selected.append(xy) + if len(selected) == count: + break + if len(selected) < 3: + raise ValueError("need three independent compact field stars") + positions, widths, converged = fit_positions(exposure, np.array(selected)) + # Extended galaxies can pass a peak/moment cut. The bright, narrow locus + # supplies a data-derived stellar width; retain only consistent sources. + locus = np.median(widths[:5][converged[:5]]) + keep = converged & (widths > 0.8 * locus) & (widths < 1.25 * locus) + if keep.sum() < 3: + raise ValueError("need three sources in the stellar width locus") + return positions[keep] + + +def fit_positions(exposure, positions): + cp = gpu() + images = np.stack([stamp(exposure["science"], p) for p in positions]) + images -= np.array([local_sky(s) for s in images])[:, None, None] + variance = np.stack([stamp(exposure["variance"], p) for p in positions]) + good = np.stack([stamp(good_pixels(exposure), p) for p in positions]) + fit = fit_single_sources( + cp.asarray(images), + cp.asarray(variance), + cp.asarray(positions - np.rint(positions)), + mask=cp.asarray(good), + ) + xy = np.rint(positions) + cp.asnumpy(cp.stack([fit.x, fit.y], axis=1)) + sigma = cp.asnumpy(cp.sqrt(fit.parameters[:, 1] * fit.parameters[:, 2])) + return xy, sigma, cp.asnumpy(fit.converged) + + +def register(science, reference, *, anchors=None): + """Warp all planes with xRep; refine translation on stationary stars.""" + mapping = make_wcs_pair_transform( + WCS(reference["header"]), WCS(science["header"]) + ) + height, width = reference["science"].shape + + def warp(transform): + result = reproject_masked_array( + science["science"], + science["variance"], + science["mask"], + ReprojectionSpec( + mapping=transform, + output_bbox=BBox(0, 0, width, height), + mapping_grid_step=32, + ), + backend="cupy", + ) + return { + "science": result.image, + "variance": result.variance, + "mask": result.mask, + "header": reference["header"].copy(), + "registration": result.metadata, + } + + coarse = warp(mapping) + offset, floor = np.zeros(2), 0.0 + if anchors is not None: + ref_xy, _, ref_ok = fit_positions(reference, anchors) + sci_xy, _, sci_ok = fit_positions(coarse, anchors) + valid = ref_ok & sci_ok & np.isfinite(sci_xy).all(axis=1) + delta = sci_xy[valid] - ref_xy[valid] + if len(delta) < 3: + raise ValueError("registration needs three stationary stars") + offset = np.median(delta, axis=0) + floor = float(np.sqrt(np.mean((delta - offset) ** 2))) + if np.linalg.norm(offset) > 2: + raise ValueError("registration correction exceeds two pixels") + coarse = warp(lambda xy: mapping(xy + offset)) + coarse["registration_offset"] = offset + coarse["registration_floor"] = floor + return coarse + + +def exclusion_disks(shape, positions, radius=22): + yy, xx = np.indices(shape) + excluded = np.zeros(shape, dtype=bool) + for x, y in positions: + excluded |= (xx - x) ** 2 + (yy - y) ** 2 < radius**2 + return excluded + + +def detect_trail(difference, variance, good=None, *, width_scale=1.0): + """CPU line voting proposes a mask; this is not a cuPhoton detector.""" + from skimage.transform import hough_line, hough_line_peaks + + good = np.ones(difference.shape, bool) if good is None else good + snr = np.divide( + difference, + np.sqrt(variance), + out=np.zeros_like(difference), + where=good & (variance > 0), + ) + votes, angles, distances = hough_line(good & (snr > 5)) + peaks, theta, rho = hough_line_peaks( + votes, + angles, + distances, + num_peaks=1, + threshold=max(40, min(difference.shape) * 0.25), + ) + mask = np.zeros_like(good) + if not len(peaks): + return mask, {"detected": False} + yy, xx = np.indices(difference.shape) + perpendicular = xx * np.cos(theta[0]) + yy * np.sin(theta[0]) - rho[0] + # A localized elongated source can win a line vote. Require persistence + # along most of a field-crossing track before proposing a trail mask. + along = -xx * np.sin(theta[0]) + yy * np.cos(theta[0]) + corridor = good & (np.abs(perpendicular) < 3) + bins = np.linspace(along[corridor].min(), along[corridor].max(), 13) + supported, _ = np.histogram(along[corridor & (snr > 5)], bins) + if np.count_nonzero(supported >= 3) < 9: + return mask, {"detected": False} + coordinate = np.arange(-35, 36) + profile = np.array( + [ + np.nanmedian( + np.where( + good & (np.abs(perpendicular - t) < 0.5), + difference, + np.nan, + ) + ) + for t in coordinate + ] + ) + base = np.nanmedian(profile[np.abs(coordinate) > 25]) + positive = np.maximum(profile - base, 0) + center = coordinate[np.nanargmax(positive)] + half = coordinate[positive > np.nanmax(positive) / 2] + sigma = max(2.0, (half.max() - half.min()) / 2.355) + mask = np.abs(perpendicular - center) < 3.5 * sigma * width_scale + return mask, { + "detected": True, + "theta": float(theta[0]), + "rho": float(rho[0] + center), + "sigma_pixels": float(sigma), + "votes": int(peaks[0]), + "coordinate": coordinate, + "profile": profile, + } + + +def subtract(reference, science, *, exclude=(), trail_width=1.0): + """Fit, detect a trail, exclude it, then refit the xPois kernel.""" + usable = good_pixels(reference) & good_pixels(science) + fitting = usable & ~exclusion_disks(usable.shape, exclude) + components = [ + GaussianBasisComponent(sigma=0.7, degree=2), + GaussianBasisComponent(sigma=1.6, degree=2), + GaussianBasisComponent(sigma=3.0, degree=0), + ] + + def solve(mask): + return solve_constant_kernel( + reference["science"], + science["science"], + components, + variance=science["variance"], + fit_mask=mask, + kernel_shape=(21, 21), + background_degree=0, + backend="cupy", + ) + + preliminary = solve(fitting) + trail, profile = detect_trail( + preliminary.residual, + science["variance"] + reference["variance"], + usable, + width_scale=trail_width, + ) + fit = solve(fitting & ~trail) if trail.any() else preliminary + noise = standardize_constant_kernel_residual( + fit.residual, + kernel=fit.kernel, + target_variance=science["variance"], + reference_variance=reference["variance"], + valid_mask=usable & ~trail, + ) + return { + "science": science["science"], + "reference": reference["science"], + "matched": fit.matched, + "difference": fit.residual, + "variance": np.asarray(noise.marginal_residual_variance), + "valid": np.asarray(noise.valid_mask), + "trail_mask": trail, + "trail_profile": profile, + "kernel": fit.kernel, + "background": fit.background, + "fit_mask": fit.fit_mask, + "backend": fit.backend, + "preliminary": preliminary.residual, + "registered": science, + } + + +def measure_motion(reference, science, old_guess, *, search_radius=15): + anchors = select_stars(reference, exclude=[old_guess]) + registered = register(science, reference, anchors=anchors) + subtraction = subtract(reference, registered, exclude=[old_guess]) + size = 2 * int(search_radius) + 21 + image = stamp(subtraction["difference"], old_guess, size) + variance = stamp(subtraction["variance"], old_guess, size) + valid = stamp(subtraction["valid"], old_guess, size) + # Measure the sampled PSF in the matched reference. A free Gaussian + # width can trade against dipole separation when the lobes overlap. + matched_exposure = {**reference, "science": subtraction["matched"]} + basis_xy, _, _ = fit_positions(matched_exposure, np.array([old_guess])) + basis = stamp(subtraction["matched"], basis_xy[0]) + basis -= local_sky(basis) + basis = ndimage.shift( + basis, (np.rint(basis_xy[0]) - basis_xy[0])[::-1], order=3 + ) + basis = np.maximum(basis, 0) + basis /= basis.sum() + # A native-pixel bilinear interpolant broadens fractional shifts and + # can trade that broadening against dipole separation. Sample the + # measured PSF on quarter-pixel centers before xFit evaluates it. + factor = 4 + yy, xx = np.meshgrid( + np.arange((basis.shape[0] - 1) * factor + 1) / factor, + np.arange((basis.shape[1] - 1) * factor + 1) / factor, + indexing="ij", + ) + basis = np.maximum(ndimage.map_coordinates(basis, [yy, xx], order=3), 0) + basis /= basis.sum() + basis_scale = 1 / factor + fit = fit_dipoles( + image[None], + model=StampDipoleModel( + basis, image_shape=image.shape, scale=basis_scale, backend="cupy" + ), + variance=variance[None], + mask=valid[None], + backend="cupy", + ) + center = np.rint(old_guess) + positive = center + fit.parameters[0, :2] + negative = center + fit.parameters[0, 2:4] + # A stationary target can leave only noise while an unrelated object + # supplies residual lobes. Associate the fading lobe with the star + # measured in the old image, and keep the new lobe in the search area. + if ( + np.linalg.norm(negative - basis_xy[0]) > 2 + or np.linalg.norm(positive - basis_xy[0]) > search_radius + ): + raise RuntimeError("dipole is not associated with the searched star") + offset = positive - negative + separation = float(np.linalg.norm(offset)) + if not np.isfinite(separation) or separation == 0: + raise RuntimeError("moving-star displacement is not constrained") + gradient = np.r_[offset, -offset, 0.0] / separation + covariance = fit.covariance[0] + separation_variance = float(gradient @ covariance @ gradient) + flux_variance = float(covariance[4, 4]) + if separation_variance <= 0 or flux_variance <= 0: + raise RuntimeError("moving-star covariance is not constrained") + correlation = float( + (gradient @ covariance[:, 4]) + / np.sqrt(separation_variance * flux_variance) + ) + # Closely overlapping lobes mostly constrain flux times displacement. + # This conservative example guard avoids quoting a misleading local + # Hessian error along that degeneracy; it is not a resolution limit. + if abs(correlation) > 0.98: + raise RuntimeError( + "overlapping dipole lobes trade flux against separation; " + "use a longer baseline or direct epoch astrometry" + ) + statistical = float(np.sqrt(separation_variance)) + floor = registered["registration_floor"] + error = float(np.hypot(statistical, np.sqrt(2) * floor)) + if ( + not fit.converged[0] + or not np.isfinite(error) + or error > separation / 2 + ): + raise RuntimeError("moving-star displacement is not constrained") + return { + **subtraction, + "old_xy": negative, + "new_xy": positive, + "separation_pixels": separation, + "separation_error_pixels": error, + "registration_floor_pixels": floor, + "flux_separation_correlation": correlation, + "fit": fit, + "fit_input": { + "images": image[None], + "variance": variance[None], + "mask": valid[None], + "stamp_basis": basis[None], + "stamp_scale": np.asarray(basis_scale), + }, + "anchors": anchors, + } + + +def empirical_psf(exposure, anchors, size=41): + xy, sigma, converged = fit_positions(exposure, anchors) + samples = [] + for point, good, width in zip(xy, converged, sigma, strict=True): + if not good or not 1 < width < 6: + continue + patch = stamp(exposure["science"], point, size) + patch -= local_sky(patch) + patch = ndimage.shift(patch, (np.rint(point) - point)[::-1], order=3) + if patch.sum() > 0: + samples.append(patch / patch.sum()) + if len(samples) < 3: + raise ValueError("too few field stars to estimate an empirical PSF") + psf = np.median(samples, axis=0) + yy, xx = np.indices(psf.shape) + psf[np.hypot(xx - size // 2, yy - size // 2) > size * 0.34] = 0 + psf = np.maximum(psf, 0) + return psf / psf.sum() + + +def photometry(subtraction, positions, psf): + """F_ref + delta F, using identical linear weights for both terms. + + The reference contribution cancels in the total, leaving science-image + formal variance. Position, PSF, sky and resampling errors are conditional; + calibrate them with check stars and independently simulated exposures. + """ + cp = gpu() + science = subtraction["registered"] + reference, delta, models, variance, valid = [], [], [], [], [] + for point in positions: + target = stamp(science["science"], point) + matched = stamp(subtraction["matched"], point) + sky_target, sky_matched = local_sky(target), local_sky(matched) + reference.append(matched - sky_matched) + delta.append(target - matched - (sky_target - sky_matched)) + models.append( + ndimage.shift(psf, (point - np.rint(point))[::-1], order=3) + ) + variance.append(stamp(science["variance"], point)) + valid.append(stamp(subtraction["valid"], point)) + weights = cp.asarray(np.array(variance)) + mask = cp.asarray(np.array(valid)) + models = cp.asarray(np.array(models)) + offsets = cp.asarray(positions - np.rint(positions)) + reference_flux = forced_psf_photometry( + cp.asarray(np.array(reference)), + weights, + offsets, + 1, + mask=mask, + psf=models, + ) + difference_flux = forced_psf_photometry( + cp.asarray(np.array(delta)), + weights, + offsets, + 1, + mask=mask, + psf=models, + ) + # A formal fit to the surviving wings is not reliable when a trail + # removes the core. Require at least 90% of the measured PSF mass. + retained = cp.sum(cp.maximum(models, 0) * mask, axis=(1, 2)) + retained /= cp.sum(cp.maximum(models, 0), axis=(1, 2)) + reliable = difference_flux.valid & (retained >= 0.9) + total = reference_flux.flux + difference_flux.flux + return ( + cp.asnumpy(cp.where(reliable, total, cp.nan)), + cp.asnumpy(cp.where(reliable, difference_flux.flux_error, cp.nan)), + cp.asnumpy(reliable), + cp.asnumpy(cp.where(reliable, difference_flux.flux, cp.nan)), + ) + + +def transit_shape(times, radius_ratio, midtime, assumptions): + import batman + + params = batman.TransitParams() + params.t0 = midtime / 1440 + params.per = assumptions.get("period_days", 1.580404531) + params.rp = radius_ratio + params.a = assumptions.get("a_over_rstar", 14.97) + params.inc = assumptions.get("inclination_deg", 88.980) + params.ecc, params.w = assumptions.get("eccentricity", 0), 90 + params.u = assumptions.get("limb_darkening", [0.6, 0.15]) + params.limb_dark = "quadratic" + model = batman.TransitModel( + params, + np.asarray(times) / 1440, + supersample_factor=7, + exp_time=assumptions.get("exposure_s", 30) / 86400, + ) + return model.light_curve(params) + + +def fit_transit(times, flux, errors, valid, assumptions): + valid = valid & np.isfinite(flux) & np.isfinite(errors) & (errors > 0) + t, y, err = times[valid], flux[valid], errors[valid] + if len(t) < 30: + raise ValueError("not enough valid epochs for a transit fit") + + def model(p, x): + return (p[2] + p[3] * x / 60) * transit_shape( + x, p[0], p[1], assumptions + ) + + result = least_squares( + lambda p: (model(p, t) - y) / err, + [0.1, 0, 1, 0], + bounds=([0.01, -25, 0.95, -0.05], [0.3, 25, 1.05, 0.05]), + ) + covariance = np.linalg.pinv(result.jac.T @ result.jac) + return { + "parameters": result.x, + "covariance": covariance, + "model": model(result.x, times), + "success": bool(result.success), + "radius_ratio": float(result.x[0]), + "radius_ratio_error": float(np.sqrt(covariance[0, 0])), + "geometric_depth": float(result.x[0] ** 2), + "midtime_min": float(result.x[1]), + "midtime_error_min": float(np.sqrt(covariance[1, 1])), + } + + +def measure_transit( + root, + manifest, + target_xy, + *, + comparison_count=5, + trail_width=1.0, + progress=None, +): + reference = read_exposure( + bundle_path(root, manifest["files"]["reference_current"]) + ) + # Motion finds the star; refine its fixed position on the independent + # current reference, rather than fitting each noisy transit frame. + target_fit, _, target_ok = fit_positions(reference, np.array([target_xy])) + if not target_ok[0]: + raise RuntimeError( + "current-reference target position is not measured" + ) + target_xy = target_fit[0] + stars = select_stars(reference, exclude=[target_xy], count=12) + check = stars[0] + comparisons = stars[1 : comparison_count + 1] + anchors = stars[1:] + positions = np.vstack([target_xy, check, comparisons]) + rows, errors, good, deltas = [], [], [], [] + stamps, differences, flags = [], [], [] + started = perf_counter() + for index, epoch in enumerate(manifest["epochs"]): + science = read_exposure(bundle_path(root, epoch["path"])) + aligned = register(science, reference, anchors=anchors) + difference = subtract( + reference, + aligned, + exclude=[target_xy, check], + trail_width=trail_width, + ) + psf = empirical_psf(aligned, anchors) + f, e, ok, df = photometry(difference, positions, psf) + rows.append(f) + errors.append(e) + good.append(ok) + deltas.append(df) + stamps.append(stamp(aligned["science"], target_xy, 65)) + differences.append(stamp(difference["difference"], target_xy, 65)) + flags.append(int(difference["trail_mask"].sum())) + if progress and ( + index % 10 == 0 or index == len(manifest["epochs"]) - 1 + ): + progress(index + 1, len(manifest["epochs"])) + gpu().cuda.get_current_stream().synchronize() + flux, error, good = np.array(rows), np.array(errors), np.array(good) + medians = np.nanmedian(np.where(good, flux, np.nan), axis=0) + relative, relative_error = flux / medians, error / medians + comp_good = good[:, 2:] & np.isfinite(relative[:, 2:]) + weight = np.where(comp_good, 1 / relative_error[:, 2:] ** 2, 0) + denom = weight.sum(axis=1) + ensemble = ( + np.sum(np.where(comp_good, relative[:, 2:], 0) * weight, axis=1) + / denom + ) + ensemble_error = np.sqrt(1 / denom) + target, check_flux = relative[:, 0] / ensemble, relative[:, 1] / ensemble + check_error = np.hypot( + relative_error[:, 1] / ensemble, + check_flux * ensemble_error / ensemble, + ) + check_good = good[:, 1] & (denom > 0) & np.isfinite(check_flux) + checks = check_flux[check_good] + scatter = 1.4826 * np.median(np.abs(checks - np.median(checks))) + scale = max(1.0, float(scatter / np.nanmedian(check_error[check_good]))) + formal = np.hypot( + relative_error[:, 0] / ensemble, target * ensemble_error / ensemble + ) + target_error = formal * scale + valid = good[:, 0] & (denom > 0) & np.isfinite(target) + baseline = np.nanpercentile(target[valid], 70) + target /= baseline + target_error /= baseline + times = np.array([e["time_min"] for e in manifest["epochs"]]) + fit = fit_transit( + times, target, target_error, valid, manifest.get("assumptions", {}) + ) + return { + "times_minutes": times, + "flux": target, + "flux_error": target_error, + "formal_error": formal / baseline, + "valid": valid, + "check_flux": check_flux, + "check_error": check_error * scale, + "error_scale": scale, + "raw_flux": flux, + "raw_error": error, + "difference_flux": np.array(deltas), + "positions": positions, + "stamps": np.array(stamps), + "difference_stamps": np.array(differences), + "trail_mask_pixels": np.array(flags), + "fit": fit, + "reference_stamp": stamp(reference["science"], target_xy, 65), + "elapsed_seconds": perf_counter() - started, + "backend": "cupy", + } diff --git a/examples/model-sky/preview.py b/examples/model-sky/preview.py new file mode 100644 index 00000000..d67b8287 --- /dev/null +++ b/examples/model-sky/preview.py @@ -0,0 +1,216 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Render a local guide preview with a completed Model Sky reference. + +The source notebook stays output-free. This stages its executed counterpart +in a copy of the guide, leaving the checkout and publication workflows alone. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import re +import shutil +import subprocess +import sys +from pathlib import Path +from urllib.parse import quote +from zipfile import ZIP_DEFLATED, ZipFile + +import nbformat +import yaml + +HERE = Path(__file__).resolve().parent +REPO = HERE.parents[1] + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--executed", type=Path, required=True) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--site-url", default="http://localhost:8796/") + parser.add_argument( + "--source-ref", + default="main", + help="GitHub branch, tag or commit for the visible notebook link", + ) + options = parser.parse_args() + output = options.output.resolve() + if output == HERE or output.is_relative_to(HERE): + parser.error("--output must be outside the example source directory") + if output.exists() and any(output.iterdir()): + parser.error("--output must be absent or empty") + + executed = options.executed.resolve() + receipt = json.loads(executed.with_name("execution.json").read_text()) + if receipt["status"] != "passed": + raise ValueError("The reference execution has not passed") + expected_notebook = receipt["output_sha256"][executed.name] + if hashlib.sha256(executed.read_bytes()).hexdigest() != expected_notebook: + raise ValueError("Executed notebook does not match its receipt") + for name, expected in receipt["source_sha256"].items(): + actual = hashlib.sha256((HERE / name).read_bytes()).hexdigest() + if actual != expected: + raise ValueError(f"Reference source no longer matches: {name}") + notebook = nbformat.read(executed, as_version=4) + code = [cell for cell in notebook.cells if cell.cell_type == "code"] + if len(code) != 20 or any(cell.execution_count is None for cell in code): + raise ValueError("A completed 20-cell reference is required") + if any(o.output_type == "error" for c in code for o in c.outputs): + raise ValueError("Reference contains an execution error") + if ( + sum( + "application/vnd.bokehjs_exec.v0+json" in o.get("data", {}) + for c in code + for o in c.outputs + ) + != 6 + ): + raise ValueError("Reference must contain all six interactive plots") + + guide = output / "guide" + shutil.copytree( + REPO / "docs/guide", + guide, + ignore=shutil.ignore_patterns( + "_book", "_freeze", ".quarto", "__pycache__" + ), + ) + shutil.copytree( + HERE / "assets", + guide / "assets/model-sky", + ignore=shutil.ignore_patterns("*.html"), + ) + includes = output / "includes" + includes.mkdir() + for name in ("guide-head.html", "guide-include.html"): + shutil.copy2(HERE / "assets" / name, includes / name) + (guide / "_environment").write_text(f"CUPHOTON_REPO={REPO}\n") + config_path = guide / "_quarto.yml" + config = yaml.safe_load(config_path.read_text()) + config["book"]["site-url"] = options.site_url + config["book"]["chapters"].insert( + 2, {"part": "Examples", "chapters": ["model-sky.ipynb"]} + ) + config["project"].setdefault("resources", []).append("source/**") + config_path.write_text(yaml.safe_dump(config, sort_keys=False)) + index = guide / "index.qmd" + index.write_text( + index.read_text().replace( + "## About this guide", + "## Model Sky\n\n" + "[Follow a star to a hidden world](model-sky.ipynb): " + "identify a satellite trail, measure stellar motion, and recover " + "a simulated planetary transit. The notebook includes executed " + "cell outputs, interactive figures, terminology definitions " + "and expandable scientific explanations.\n\n" + "## About this guide", + ) + ) + + for cell in notebook.cells: + if cell.cell_type == "markdown": + cell.source = cell.source.replace( + "assets/story-", "assets/model-sky/story-" + ) + first = notebook.cells[0] + match = re.match(r"\A---\n(.*?)\n---\n", first.source, flags=re.S) + metadata = yaml.safe_load(match[1]) if match else {} + body = first.source[match.end() :] if match else first.source + metadata.update( + title="Model Sky", subtitle="Follow a star to a hidden world" + ) + metadata["execute"] = {"enabled": False, "warning": True} + metadata["number-sections"] = False + metadata["format"] = { + "html": { + "css": "assets/model-sky/guide.css", + "include-in-header": "../includes/guide-head.html", + "include-after-body": "../includes/guide-include.html", + "embed-resources": True, + } + } + metadata["code-links"] = [ + { + "text": "Download source notebook", + "icon": "file-code", + "href": "source/model-sky/model-sky.ipynb", + }, + { + "text": "Download example sources", + "icon": "download", + "href": "source/model-sky.zip", + }, + { + "text": "cuPhoton on GitHub", + "icon": "github", + "href": "https://github.com/NVIDIA/cuPhoton", + }, + ] + source_link = ( + "[View the source Jupyter notebook in NVIDIA/cuPhoton]" + "(https://github.com/NVIDIA/cuPhoton/blob/" + f"{quote(options.source_ref, safe='')}/" + "examples/model-sky/model-sky.ipynb).\n\n" + ) + first.source = ( + "---\n" + + yaml.safe_dump(metadata, sort_keys=False) + + "---\n\n" + + source_link + + body.lstrip() + ) + nbformat.write(notebook, guide / "model-sky.ipynb") + + sources = output / "example-sources/model-sky" + shutil.copytree( + HERE, + sources, + ignore=shutil.ignore_patterns( + "__pycache__", + ".pytest_cache", + ".ruff_cache", + "data", + "results", + "*.executed.ipynb", + "model-sky-output", + "model-sky-guide-output", + ), + ) + shutil.copy2(REPO / "LICENSE", sources / "LICENSE") + # HTML includes are build inputs, not standalone documentation pages. + shutil.copytree( + sources, + guide / "source/model-sky", + ignore=shutil.ignore_patterns("*.html"), + ) + with ZipFile( + guide / "source/model-sky.zip", "w", ZIP_DEFLATED + ) as archive: + for path in sorted(sources.rglob("*")): + if path.is_file(): + archive.write( + path, "model-sky/" + path.relative_to(sources).as_posix() + ) + + env = os.environ.copy() + env.update( + QUARTO_PYTHON=sys.executable, + CUPHOTON_REPO=str(REPO), + CUPHOTON_XREP_TORCH_DEVICE="cpu", + CUDA_VISIBLE_DEVICES="", + MPLBACKEND="Agg", + PATH=str(Path(sys.executable).parent) + os.pathsep + env["PATH"], + ) + # QMD CPU examples execute; the prepared IPYNB retains its saved outputs. + subprocess.run( + ["quarto", "render", str(guide), "--no-cache"], env=env, check=True + ) + print(guide / "_book/model-sky.html") + + +if __name__ == "__main__": + main() diff --git a/examples/model-sky/requirements.txt b/examples/model-sky/requirements.txt new file mode 100644 index 00000000..b951e3db --- /dev/null +++ b/examples/model-sky/requirements.txt @@ -0,0 +1,12 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Notebook additions to an existing CUDA 13 cuPhoton installation. +batman-package==2.5.3; platform_machine != "aarch64" +batman-package @ git+https://github.com/lkreidberg/batman.git@6fc570e209fa2e3dadd2ffa4c535f528a7bef495 ; platform_machine == "aarch64" +bokeh==3.9.1 +ipykernel==7.4.0 +jupyterlab==4.6.5 +jupyter-bokeh==4.1.0 +nbclient==0.11.0 +scikit-image==0.26.0 diff --git a/examples/model-sky/run.py b/examples/model-sky/run.py new file mode 100644 index 00000000..0eab8485 --- /dev/null +++ b/examples/model-sky/run.py @@ -0,0 +1,270 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Prepare Model Sky inputs and execute the notebook and both exercises. + +All generated files and a copy of the example sources go under --output. The +directory must be absent or empty; existing runs are never overwritten. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import platform +import shutil +import subprocess +import sys +import time +from datetime import UTC, datetime +from importlib.metadata import version +from pathlib import Path + +import nbformat +from jupyter_client import KernelManager +from nbclient import NotebookClient + +HERE = Path(__file__).resolve().parent +FLAGS = ("RUN_BASELINE_EXERCISE", "RUN_BLEND_EXTENSION") + + +def sha256(path: Path) -> str: + with path.open("rb") as stream: + return hashlib.file_digest(stream, "sha256").hexdigest() + + +def write_receipt(path: Path, receipt: dict) -> None: + path.write_text(json.dumps(receipt, indent=2, allow_nan=False) + "\n") + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--output", + type=Path, + default=Path("model-sky-output"), + help="Absent or empty directory for inputs, results and notebook", + ) + options = parser.parse_args() + output = options.output.resolve() + if output.exists() and (not output.is_dir() or any(output.iterdir())): + parser.error( + "--output must be absent or empty; keep existing runs intact" + ) + + source = HERE / "model-sky.ipynb" + notebook = nbformat.read(source, as_version=4) + code = [cell for cell in notebook.cells if cell.cell_type == "code"] + if len(code) != 20 or any( + cell.outputs or cell.execution_count is not None for cell in code + ): + raise ValueError("Expected the unexecuted 20-cell Model Sky source") + for flag in FLAGS: + matches = [cell for cell in code if f"{flag} = False" in cell.source] + if len(matches) != 1: + raise ValueError(f"Expected one disabled source flag: {flag}") + matches[0].source = matches[0].source.replace( + f"{flag} = False", f"{flag} = True" + ) + notebook.metadata["reference_execution"] = { + "enabled_optional_flags": list(FLAGS), + "source_defaults_unchanged": True, + "relative_data": "data", + "relative_output": "results", + } + + sources = [ + source, + *( + HERE / name + for name in ( + "sources.md", + "requirements.txt", + "model_sky.py", + "scene.py", + "pipeline.py", + "workshop.py", + "views.py", + "blend.py", + "notebook_style.py", + "run.py", + ) + ), + *( + HERE / "assets" / f"story-{name}.svg" + for name in ("field", "compare", "motion", "transit") + ), + ] + source_hashes = { + path.relative_to(HERE).as_posix(): sha256(path) for path in sources + } + output.mkdir(parents=True, exist_ok=True) + for path in sources: + destination = output / path.relative_to(HERE) + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(path, destination) + + env = os.environ.copy() + env["PATH"] = ( + str(Path(sys.executable).parent) + os.pathsep + env.get("PATH", "") + ) + env["CUPHOTON_MODEL_SKY_DATA"] = "data" + env["CUPHOTON_MODEL_SKY_OUTPUT"] = "results" + env.setdefault("CUDA_VISIBLE_DEVICES", "0") + receipt_path = output / "execution.json" + receipt = { + "schema_version": 1, + "status": "incomplete", + "created_utc": datetime.now(UTC).isoformat(), + "source_sha256": source_hashes, + "optional_flags_enabled": list(FLAGS), + } + write_receipt(receipt_path, receipt) + + print("Preparing Model Sky inputs", flush=True) + subprocess.run( + [sys.executable, "model_sky.py", "--output", "data"], + cwd=output, + env=env, + check=True, + ) + inputs = sorted( + path for path in (output / "data").rglob("*") if path.is_file() + ) + input_hashes = { + path.relative_to(output).as_posix(): sha256(path) for path in inputs + } + manager = KernelManager(kernel_name="python3") + manager.kernel_spec.argv = [ + sys.executable, + "-m", + "ipykernel_launcher", + "-f", + "{connection_file}", + ] + + def cell_start(cell, cell_index, **kwargs): + if cell.cell_type == "code": + print( + f"Cell {cell_index + 1}/{len(notebook.cells)}: " + f"{cell.source.splitlines()[0][:80]}", + flush=True, + ) + + client = NotebookClient( + notebook, + km=manager, + timeout=600, + allow_errors=False, + record_timing=True, + on_cell_start=cell_start, + ) + executed = output / "model-sky.executed.ipynb" + started = time.monotonic() + try: + client.execute(cwd=str(output), env=env) + finally: + if manager.has_kernel: + manager.shutdown_kernel(now=True) + # Preserve every output, including warnings. Only machine-local path + # prefixes in streams are replaced; figures and numbers are untouched. + for cell in code: + for item in cell.outputs: + if item.output_type == "stream": + for prefix in { + sys.prefix, + str(Path(sys.prefix).resolve()), + }: + item.text = item.text.replace( + prefix, "" + ) + item.text = item.text.replace(str(output), ".") + nbformat.write(notebook, executed) + elapsed = time.monotonic() - started + if any(cell.execution_count is None for cell in code): + raise RuntimeError("Notebook execution did not finish") + bokeh_count = sum( + "application/vnd.bokehjs_exec.v0+json" in item.get("data", {}) + for cell in code + for item in cell.outputs + ) + if bokeh_count != 6: + raise RuntimeError( + f"Expected six interactive figures, got {bokeh_count}" + ) + for name, expected in source_hashes.items(): + if ( + sha256(HERE / name) != expected + or sha256(output / name) != expected + ): + raise RuntimeError(f"Source changed during execution: {name}") + for name, expected in input_hashes.items(): + if sha256(output / name) != expected: + raise RuntimeError(f"Input changed during execution: {name}") + + environment = { + "python": platform.python_version(), + "architecture": platform.machine(), + "cuda_visible_devices": env["CUDA_VISIBLE_DEVICES"], + "packages": { + name: version(name) + for name in ( + "cuphoton", + "cupy-cuda13x", + "numpy", + "scipy", + "astropy", + "batman-package", + "bokeh", + "nbclient", + "nbformat", + "ipykernel", + ) + }, + } + cuda = subprocess.check_output( + [ + sys.executable, + "-c", + "import json, cupy as cp; " + "p = cp.cuda.runtime.getDeviceProperties(0); " + "print(json.dumps({'gpu': p['name'].decode(), " + "'compute_capability': [p['major'], p['minor']], " + "'cuda_runtime': cp.cuda.runtime.runtimeGetVersion(), " + "'cuda_driver': cp.cuda.runtime.driverGetVersion()}))", + ], + env=env, + text=True, + ) + environment.update(json.loads(cuda)) + products = sorted( + path for path in (output / "results").rglob("*") if path.is_file() + ) + receipt.update( + status="passed", + code_cells_executed=len(code), + bokeh_documents=bokeh_count, + elapsed_seconds=elapsed, + input_sha256=input_hashes, + output_sha256={ + path.relative_to(output).as_posix(): sha256(path) + for path in [executed, *products] + }, + environment=environment, + environment_sha256=hashlib.sha256( + json.dumps(environment, sort_keys=True).encode() + ).hexdigest(), + stream_path_normalization=( + "Python environment and output directory prefixes only" + ), + ) + write_receipt(receipt_path, receipt) + print( + "Executed 20 cells and six interactive figures; see execution.json", + flush=True, + ) + + +if __name__ == "__main__": + main() diff --git a/examples/model-sky/scene.py b/examples/model-sky/scene.py new file mode 100644 index 00000000..332899a8 --- /dev/null +++ b/examples/model-sky/scene.py @@ -0,0 +1,627 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Model Sky exposures; injection truth lives separately.""" + +from __future__ import annotations + +import hashlib +import importlib.metadata +import json +import shutil +from dataclasses import asdict, dataclass +from pathlib import Path + +import astropy.units as u +import numpy as np +from astropy.io import fits +from astropy.time import Time +from astropy.wcs import WCS +from scipy.ndimage import gaussian_filter, maximum_filter, shift + + +@dataclass(frozen=True) +class SceneConfig: + """One fictional M dwarf, with GJ 1214 inspired geometry.""" + + seed: int = 260611 + n_epochs: int = 120 + exposure_s: float = 30.0 + cadence_s: float = 60.0 + reference_exposures: int = 16 + distance_pc: float = 146.42 + proper_motion_ra_mas_yr: float = 58.0202 + proper_motion_dec_mas_yr: float = -74.9713 + baseline_years: float = 10.0 + target_flux_njy: float = 348775.3294253341 + stellar_radius_solar: float = 0.2162 + stellar_mass_solar: float = 0.1820 + stellar_temperature_k: float = 3100.0 + period_days: float = 1.580404531 + radius_ratio: float = 0.11589 + a_over_rstar: float = 14.97 + inclination_deg: float = 88.980 + eccentricity: float = 0.0 + # Declared illustrative quadratic limb-darkening coefficients. + limb_darkening_u1: float = 0.6 + limb_darkening_u2: float = 0.15 + reference_blur_sigma_px: float = 1.0 + trail_width_arcsec: float = 2.8 + trail_epoch: int = 43 + simulation_midpoint_mjd: float = 61354.25 + + +def sha256(path): + digest = hashlib.sha256() + with Path(path).open("rb") as stream: + for block in iter(lambda: stream.read(1024 * 1024), b""): + digest.update(block) + return digest.hexdigest() + + +def transit_flux(time_min, config): + """Exposure-integrated quadratic limb-darkened relative flux.""" + import batman + + params = batman.TransitParams() + params.t0 = 0.0 + params.per = config.period_days + params.rp = config.radius_ratio + params.a = config.a_over_rstar + params.inc = config.inclination_deg + params.ecc = config.eccentricity + params.w = 90.0 + params.u = [config.limb_darkening_u1, config.limb_darkening_u2] + params.limb_dark = "quadratic" + times = np.atleast_1d(np.asarray(time_min, dtype=float)) / 1440.0 + model = batman.TransitModel( + params, + times, + supersample_factor=11, + exp_time=config.exposure_s / 86400.0, + ) + return model.light_curve(params) + + +def draw_exposure(model, sky_variance, noise_scale, rng, n_average=1): + """Draw calibrated pixels with source variance a*M and sky/read variance. + + a is nJy per effective electron: a*Poisson(max(M,0)/a). Negative + model values retain their mean but contribute no source Poisson noise. + n_average generates the mean of independent equal-duration exposures. + """ + model = np.asarray(model, dtype=float) + sky_variance = np.broadcast_to(sky_variance, model.shape) + noise_scale = np.broadcast_to(noise_scale, model.shape) + if not np.all(np.isfinite(model)): + raise ValueError("latent scene must be finite") + if not np.all(np.isfinite(noise_scale) & (noise_scale > 0)): + raise ValueError( + "noise_scale must be positive nJy/effective-electron" + ) + if not np.all(np.isfinite(sky_variance) & (sky_variance >= 0)): + raise ValueError("sky_variance must be finite and nonnegative") + if not isinstance(n_average, int) or n_average < 1: + raise ValueError("n_average must be a positive integer") + positive = np.maximum(model, 0) + electrons = rng.poisson(positive * n_average / noise_scale) + image = model + electrons * noise_scale / n_average - positive + image += rng.normal(size=model.shape) * np.sqrt(sky_variance / n_average) + variance = (sky_variance + noise_scale * positive) / n_average + return image.astype(np.float32), variance.astype(np.float32) + + +def normalized_psf(base_psf, blur_sigma_px): + base = np.asarray(base_psf, dtype=float) + if base.ndim != 2 or not np.all(np.isfinite(base)): + raise ValueError("base_psf must be a finite two-dimensional kernel") + # Empirical interpolation may leave small unphysical negative wings. + base = np.maximum(base, 0) + if base.sum() <= 0: + raise ValueError("base_psf must have positive integrated flux") + padding = int(np.ceil(5 * blur_sigma_px)) + 3 + base = np.pad(base, padding) + base = np.pad(base, [(0, 1 - size % 2) for size in base.shape]) + psf = gaussian_filter(base, blur_sigma_px, mode="constant") + return psf / psf.sum() + + +def add_star(image, psf, xy, flux): + """Add an integrated-flux source at zero-based x,y coordinates.""" + xy = np.asarray(xy, dtype=float) + center = np.rint(xy).astype(int) + shifted = shift(psf, (xy - center)[::-1], order=3, mode="constant") + shifted = np.maximum(shifted, 0) + shifted *= flux / shifted.sum() + x0, y0 = center - np.asarray(psf.shape[::-1]) // 2 + x1, y1 = x0 + psf.shape[1], y0 + psf.shape[0] + left, right = max(0, x0), min(image.shape[1], x1) + bottom, top = max(0, y0), min(image.shape[0], y1) + if right > left and top > bottom: + image[bottom:top, left:right] += shifted[ + bottom - y0 : top - y0, left - x0 : right - x0 + ] + + +def satellite_trail( + shape, + target_xy, + pixel_scale_arcsec, + width_arcsec=2.8, + peak_njy=1800, +): + """Finite-distance, double-lobed cross section across a target wing. + + An analytic teaching profile, not an optical ray trace or a prediction + for a particular satellite. + """ + yy, xx = np.indices(shape, dtype=float) + angle = np.deg2rad(29.0) + dx, dy = xx - target_xy[0], yy - target_xy[1] + width = width_arcsec / pixel_scale_arcsec + across = -np.sin(angle) * dx + np.cos(angle) * dy - 0.48 * width + along = np.cos(angle) * dx + np.sin(angle) * dy + sigma = 0.21 * width + profile = np.exp(-0.5 * ((across - 0.25 * width) / sigma) ** 2) + profile += np.exp(-0.5 * ((across + 0.25 * width) / sigma) ** 2) + profile /= profile.max() + return peak_njy * profile * (1 + 0.08 * np.sin(2 * np.pi * along / 170)) + + +def binary_quality_mask(raw, metadata): + """Translate documented bad flags; DETECTED alone is not a bad pixel.""" + raw = np.asarray(raw) + if metadata.get("quality_mask_is_binary", False): + return (raw != 0).astype(np.uint8) + bad_bits = metadata.get("bad_mask_bits") + if bad_bits is None and "mask_planes" in metadata: + names = ( + "BAD", + "SAT", + "CR", + "EDGE", + "NO_DATA", + "INTRP", + "SUSPECT", + "STREAK", + ) + bad_bits = sum( + 1 << int(metadata["mask_planes"][name]) + for name in names + if name in metadata["mask_planes"] + ) + if bad_bits is not None: + return ((raw.astype(np.uint64) & int(bad_bits)) != 0).astype(np.uint8) + if not np.any(raw): + return np.zeros(raw.shape, dtype=np.uint8) + raise ValueError("nonzero quality_mask needs its documented bit mapping") + + +def _source_positions(background, bad): + """Place isolated sources; their identities are not measurement priors.""" + anchors = [ + (0.52, 0.48), + (0.23, 0.23), + (0.76, 0.22), + (0.24, 0.76), + (0.77, 0.76), + (0.51, 0.20), + ] + score = gaussian_filter(np.abs(background), 4) + score[maximum_filter(bad, size=25) != 0] = np.inf + radius = max(4, min(background.shape) // 30) + positions = [] + for fx, fy in anchors: + cx, cy = int(fx * background.shape[1]), int(fy * background.shape[0]) + y0, y1, x0, x1 = ( + cy - radius, + cy + radius + 1, + cx - radius, + cx + radius + 1, + ) + region = score[y0:y1, x0:x1] + if not np.any(np.isfinite(region)): + raise ValueError("no clean injection location near an anchor") + y, x = np.unravel_index(np.argmin(region), region.shape) + positions.append([float(x + x0), float(y + y0)]) + return np.asarray(positions) + + +def _motion_offset(wcs, xy, config): + coordinate = wcs.pixel_to_world(*xy) + moved = coordinate.spherical_offsets_by( + config.proper_motion_ra_mas_yr * config.baseline_years * u.mas, + config.proper_motion_dec_mas_yr * config.baseline_years * u.mas, + ) + return np.asarray(wcs.world_to_pixel(moved)) - xy + + +def _write_exposure( + path, + science, + variance, + mask, + wcs_header, + time_min, + config, + dither=(0.0, 0.0), + n_average=1, + modeled_scene=False, +): + header = wcs_header.copy() + header["CRPIX1"] += float(dither[0]) + header["CRPIX2"] += float(dither[1]) + mjd = config.simulation_midpoint_mjd + time_min / 1440.0 + header["SIMULATE"] = (True, "Model Sky simulated exposure") + header["SIMMJD"] = (mjd, "SIMULATED midpoint MJD, UTC") + span_s = (n_average - 1) * config.cadence_s + config.exposure_s + header["MJD-OBS"] = ( + mjd - span_s / 172800, + "SIMULATED exposure/block start", + ) + header["DATE-OBS"] = Time(header["MJD-OBS"], format="mjd").isot + header["TIMESYS"] = "UTC" + header["EXPTIME"] = ( + config.exposure_s, + "Seconds per constituent exposure", + ) + header["NCOMBINE"] = n_average + header["TOTALEXP"] = config.exposure_s * n_average + header["TREL_MIN"] = ( + float(time_min), + "Minutes from simulated series center", + ) + header["BUNIT"] = "nJy" + header.add_history("All sky and instrument inputs are analytic models.") + header.add_history( + "MASK: 0 usable; 1 bad. Injected trails are not pre-masked." + ) + path.parent.mkdir(parents=True, exist_ok=True) + fits.HDUList( + [ + fits.PrimaryHDU(header=header), + fits.ImageHDU(science, header=header, name="SCI"), + fits.ImageHDU( + variance, header=fits.Header({"BUNIT": "nJy2"}), name="VAR" + ), + fits.ImageHDU(mask.astype(np.uint8), name="MASK"), + ] + ).writeto(path, overwrite=True, checksum=True) + + +def load_exposure(path): + """Read measurement planes without opening any truth product.""" + with fits.open(path) as hdus: + return { + "science": np.array(hdus["SCI"].data), + "variance": np.array(hdus["VAR"].data), + "mask": np.array(hdus["MASK"].data), + "header": hdus["SCI"].header.copy(), + } + + +def prepare_bundle( + calibration_dir, output_dir, *, seed=260611, force=False, config=None +): + """Generate Model Sky FITS exposures from analytic calibration. + + Preparation generates the expected sky, then draws independent exposure + noise. Measurement opens the generated planes without injection truth. + """ + calibration_dir, output_dir = Path(calibration_dir), Path(output_dir) + config = config or SceneConfig(seed=seed) + inputs = [ + calibration_dir / f"calibration.{suffix}" + for suffix in ("npz", "fits", "json") + ] + for path in inputs: + if not path.is_file(): + raise FileNotFoundError(path) + fingerprint = { + "calibration_sha256": {path.name: sha256(path) for path in inputs}, + "generator_sha256": sha256(Path(__file__)), + # Keep injected values out of the measurement manifest. + "config_sha256": hashlib.sha256( + json.dumps(asdict(config), sort_keys=True).encode() + ).hexdigest(), + } + manifest_path = output_dir / "bundle.json" + if manifest_path.exists() and not force: + previous = json.loads(manifest_path.read_text()) + if previous.get("fingerprint") != fingerprint: + raise ValueError( + "bundle inputs changed; use --force to regenerate" + ) + for relative in previous["sha256"]: + if not (output_dir / relative).is_file(): + raise FileNotFoundError(output_dir / relative) + return previous + metadata = json.loads(inputs[2].read_text()) + with np.load(inputs[0]) as arrays: + background = arrays["background"].astype(float) + base_psf = arrays["base_psf"].astype(float) + sky_variance = arrays["sky_variance"].astype(float) + noise_scale = arrays["noise_scale"].astype(float) + bad = binary_quality_mask(arrays["quality_mask"], metadata) + if background.ndim != 2 or min(background.shape) < 96: + raise ValueError("calibration scene must be at least 96 by 96 pixels") + if bad.shape != background.shape: + raise ValueError("quality_mask and background must share their grid") + with fits.open(inputs[1]) as hdus: + header = hdus["SCI"].header if "SCI" in hdus else hdus[0].header + wcs_header = WCS(header).celestial.to_header(relax=True) + wcs = WCS(wcs_header) + pixel_scale = float(metadata["pixel_scale_arcsec"]) + if pixel_scale <= 0: + raise ValueError("pixel_scale_arcsec must be positive") + border = min(14, min(background.shape) // 10) + bad[:border] = bad[-border:] = 1 + bad[:, :border] = bad[:, -border:] = 1 + source_xy = _source_positions(background, bad) + old_xy = source_xy[0] + offset = _motion_offset(wcs, old_xy, config) + current_xy = old_xy + offset + stable_xy = source_xy[1:] + stable_flux = config.target_flux_njy * np.array( + [0.72, 1.08, 0.58, 0.92, 0.80] + ) + rng = np.random.default_rng(config.seed) + times = ( + (np.arange(config.n_epochs) - (config.n_epochs - 1) / 2) + * config.cadence_s + / 60 + ) + relative_flux = transit_flux(times, config) + + def render( + time_min, + target_xy, + blur, + throughput=1.0, + dither=(0.0, 0.0), + n_average=1, + with_trail=False, + ): + psf = normalized_psf(base_psf, blur) + scene = gaussian_filter(background, blur, mode="reflect") + scene = shift(scene, dither[::-1], order=3, mode="reflect") + location = target_xy + np.asarray(dither) + constituent_times = ( + time_min + + (np.arange(n_average) - (n_average - 1) / 2) + * config.cadence_s + / 60 + ) + factor = float(np.mean(transit_flux(constituent_times, config))) + add_star(scene, psf, location, config.target_flux_njy * factor) + for xy, flux in zip(stable_xy, stable_flux, strict=True): + add_star(scene, psf, xy + np.asarray(dither), flux) + scene *= throughput + trail = np.zeros(background.shape) + if with_trail: + trail = satellite_trail( + background.shape, + location, + pixel_scale, + config.trail_width_arcsec, + ) + scene += trail + image, variance = draw_exposure( + scene, sky_variance, noise_scale, rng, n_average + ) + shifted_bad = shift( + bad, dither[::-1], order=0, mode="constant", cval=1 + ) + mask = np.maximum(bad, shifted_bad) + return image, variance, mask, psf, trail + + files = { + "reference_old": "refs/reference_old.fits", + "reference_current": "refs/reference_current.fits", + "motion": "motion/science.fits", + "trail": "trail/science.fits", + "epochs": [ + f"epochs/epoch_{index:03d}.fits" + for index in range(config.n_epochs) + ], + } + specifications = [ + ( + "reference_old", + -config.baseline_years * 365.25 * 1440 - 120, + old_xy, + config.reference_blur_sigma_px, + config.reference_exposures, + False, + ), + ( + "reference_current", + -120, + current_xy, + config.reference_blur_sigma_px, + config.reference_exposures, + False, + ), + ("motion", -90, current_xy, 1.4, 1, False), + ("trail", -45, current_xy, 1.4, 1, True), + ] + reference_psfs, all_paths = [], [] + for key, time_min, xy, blur, n_average, with_trail in specifications: + image, variance, mask, psf, trail = render( + time_min, + xy, + blur, + n_average=n_average, + with_trail=with_trail, + ) + path = output_dir / files[key] + _write_exposure( + path, + image, + variance, + mask, + wcs_header, + time_min, + config, + modeled_scene=metadata.get("modeled_scene", True), + n_average=n_average, + ) + all_paths.append(files[key]) + if key.startswith("reference_"): + reference_psfs.append(psf) + if with_trail: + standalone_trail = trail + epochs, epoch_psfs, nuisance = [], [], [] + for index, time_min in enumerate(times): + phase = index / max(config.n_epochs - 1, 1) + blur = 1.2 + 0.35 * (1 + np.sin(2 * np.pi * phase + 0.3)) / 2 + throughput = ( + 1 + + 0.018 * np.sin(2 * np.pi * phase + 0.7) + + 0.006 * (phase - 0.5) + ) + dither = ( + 0.24 * np.sin(4 * np.pi * phase), + 0.22 * np.cos(3 * np.pi * phase), + ) + image, variance, mask, psf, _ = render( + time_min, + current_xy, + blur, + throughput, + dither, + with_trail=index == config.trail_epoch, + ) + relative = files["epochs"][index] + _write_exposure( + output_dir / relative, + image, + variance, + mask, + wcs_header, + time_min, + config, + modeled_scene=metadata.get("modeled_scene", True), + dither=dither, + ) + all_paths.append(relative) + epochs.append( + { + "index": index, + "path": relative, + "time_min": float(time_min), + "exposure_s": config.exposure_s, + "mjd_sim": config.simulation_midpoint_mjd + time_min / 1440, + } + ) + epoch_psfs.append(psf) + nuisance.append([throughput, blur, *dither]) + nuisance = np.asarray(nuisance) + psfs = reference_psfs + epoch_psfs + max_shape = np.max([psf.shape for psf in psfs], axis=0) + padded_psfs = np.array( + [ + np.pad( + psf, + [ + (int((outer - inner) // 2), int((outer - inner) // 2)) + for outer, inner in zip(max_shape, psf.shape, strict=True) + ], + ) + for psf in psfs + ] + ) + truth_paths = {"json": "truth/truth.json", "npz": "truth/truth.npz"} + (output_dir / "truth").mkdir(parents=True, exist_ok=True) + np.savez_compressed( + output_dir / truth_paths["npz"], + psf_reference=padded_psfs[:2], + psfs_epochs=padded_psfs[2:], + relative_flux=relative_flux, + epoch_target_flux=config.target_flux_njy + * relative_flux + * nuisance[:, 0], + epoch_target_xy=current_xy[None, :] + nuisance[:, 2:], + throughput=nuisance[:, 0], + blur_sigma_px=nuisance[:, 1], + dither_xy=nuisance[:, 2:], + old_target_xy=old_xy, + current_target_xy=current_xy, + stable_source_xy=stable_xy, + stable_source_flux=stable_flux, + trail_mask=standalone_trail > 0.01 * standalone_trail.max(), + ) + motion_arcsec_yr = float( + np.hypot( + config.proper_motion_ra_mas_yr, config.proper_motion_dec_mas_yr + ) + / 1000 + ) + truth = { + "purpose": ( + "Injection recovery validation only; not a measurement input." + ), + "physical_system": asdict(config), + "old_target_xy": old_xy.tolist(), + "current_target_xy": current_xy.tolist(), + "displacement_xy_pixels": offset.tolist(), + "proper_motion_arcsec_yr": motion_arcsec_yr, + "transverse_velocity_km_s": 4.74047 + * motion_arcsec_yr + * config.distance_pc, + "contaminated_epoch": config.trail_epoch, + } + (output_dir / truth_paths["json"]).write_text( + json.dumps(truth, indent=2) + "\n" + ) + all_paths.extend(truth_paths.values()) + observed = {} + (output_dir / "provenance").mkdir(parents=True, exist_ok=True) + for source in inputs: + relative = f"provenance/{source.name}" + shutil.copy2(source, output_dir / relative) + all_paths.append(relative) + versions = { + package: importlib.metadata.version(package) + for package in ("numpy", "scipy", "astropy", "batman-package") + } + manifest = { + "schema_version": 1, + "files": files, + "observed": observed, + "calibration_dir": "provenance", + "epochs": epochs, + "shape": list(background.shape), + "units": "nJy", + "pixel_scale_arcsec": pixel_scale, + "target_search": {"old_xy": old_xy.tolist(), "radius_pixels": 18}, + "assumptions": { + "period_days": config.period_days, + "a_over_rstar": config.a_over_rstar, + "inclination_deg": config.inclination_deg, + "eccentricity": config.eccentricity, + "limb_darkening": [ + config.limb_darkening_u1, + config.limb_darkening_u2, + ], + "stellar_radius_solar": config.stellar_radius_solar, + "exposure_s": config.exposure_s, + "baseline_years": config.baseline_years, + "description": ( + "Supplied geometry priors; fit radius ratio and time." + ), + }, + "truth": truth_paths, + "fingerprint": fingerprint, + "dependencies": versions, + "provenance": metadata, + "sha256": { + relative: sha256(output_dir / relative) for relative in all_paths + }, + "simulation_notes": metadata.get("simulation_notes", []), + "references": metadata.get("references", {}), + "photometric_model": metadata.get("photometric_model", {}), + } + manifest_path.write_text(json.dumps(manifest, indent=2) + "\n") + return manifest diff --git a/examples/model-sky/sources.md b/examples/model-sky/sources.md new file mode 100644 index 00000000..cf433f97 --- /dev/null +++ b/examples/model-sky/sources.md @@ -0,0 +1,49 @@ + + + +# Sources and model assumptions · Model Sky + +All astronomical arrays and instrument inputs are generated by `model_sky.py` +and `scene.py`. No observational pixels, catalogs, coordinate solutions, +measured PSFs, masks, calibration, filter curves or trained models are inputs. +The modeled arrays and example code are provided under Apache-2.0. +The four overview SVGs in `assets/` are original teaching schematics. + +The sky is a fixed noiseless field of fictional stars. Each exposure receives +independent source Poisson and Gaussian sky/read noise, after seeing, dither +and transparency. Pixels use nJy; variance uses nJy². The 4 m telescope, +560–700 nm top-hat band at 40% total efficiency, 0.2 arcsec/pixel, 20.5 AB +mag/arcsec² sky and 5 electron read noise are explicit models. None describes +an actual instrument. A 3100 K Planck spectrum sets the brightness at +146.42 pc for radius 0.2162 solar. It omits M-dwarf molecular absorption and +extinction. The illustrative quadratic limb-darkening law (0.6, 0.15) is +independently declared; it is not derived from uniform blackbody emission. +The orbit is circular and the geometry fixed during radius/time fitting. + +- [Charbonneau et al. (2009), GJ 1214 discovery](https://arxiv.org/abs/0912.3229) + inspires the story; our simulated star is at a different distance. +- [Updated GJ 1214 parameters](https://arxiv.org/html/2402.05991v2) inform the + stellar radius and illustrative orbital geometry. +- [Mandel & Agol (2002)](https://arxiv.org/abs/astro-ph/0210099) and + [Kreidberg (2015), batman](https://arxiv.org/abs/1507.08285) describe physical + limb-darkened transit models. We integrate over each 30 second exposure. +- [Alard & Lupton (1998)](https://arxiv.org/abs/astro-ph/9712287) provides the + image-subtraction context. Actual cuPhoton xRep, xPois and xFit GPU calls + reproject planes, fit kernels and measure stars in this example. +- [Tyson et al. (2020)](https://doi.org/10.3847/1538-3881/abba3e) discusses + real satellite trails; ours is a separately modeled teaching approximation. +- [Bryson et al. (2013)](https://arxiv.org/abs/1303.0052) explains centroid + vetting; a displaced source can explain a dip. A transit-like candidate + still needs repeated events, spectra and other follow-up for confirmation. +- [AAVSO exoplanet photometry](https://aavso.org/exoplanet-photometry/) connects + calibrated light curves to follow-up work. +- [cuPhoton documentation](https://github.com/NVIDIA/cuPhoton/tree/main/docs) + describes the product interfaces. xScan is explicitly omitted here; no + classifier weights, scores or training stamps are included. +- [Bokeh standalone documents](https://docs.bokeh.org/en/latest/docs/user_guide/output/embed.html) + explain embedded offline interactions. Inspecting a view does not rerun fits. + +Truth is stored separately and revealed only after measurement. Five noise +realizations test conditional uncertainties, not all astrophysical systematics. +Incorrect PSFs and limb-darkening changes probe model sensitivity; they do not +fully marginalize over real atmosphere or instrument uncertainty. diff --git a/examples/model-sky/tests/test_blend.py b/examples/model-sky/tests/test_blend.py new file mode 100644 index 00000000..8bc3d55e --- /dev/null +++ b/examples/model-sky/tests/test_blend.py @@ -0,0 +1,65 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""A centroid control distinguishes equal-depth, differently located dips.""" + +import sys +from pathlib import Path + +import numpy as np +import pytest +from astropy.io import fits + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from blend import measure_case # noqa: E402 +from pipeline import write_exposure # noqa: E402 +from scene import add_star, draw_exposure, normalized_psf # noqa: E402 + + +@pytest.mark.gpu +def test_gpu_localizes_fading_neighbor_despite_similar_aperture_depth( + tmp_path, +): + cp = pytest.importorskip("cupy") + if not cp.cuda.runtime.getDeviceCount(): + pytest.skip("CUDA device required") + yy, xx = np.indices((25, 25)) + psf = normalized_psf(np.exp(-((xx - 12) ** 2 + (yy - 12) ** 2) / 8), 1.2) + base = np.zeros((256, 256)) + target = np.array([128.2, 127.7]) + neighbor = target + [1.5, 0.7] + for point in ([48, 48], [208, 48], [48, 208]): + add_star(base, psf, point, 100_000) + add_star(base, psf, target, 100_000) + add_star(base, psf, neighbor, 5_000) + rng = np.random.default_rng(31415) + measured = [] + for index, source in enumerate((target, neighbor)): + dimmed = base.copy() + add_star(dimmed, psf, source, -1800) + paths = [] + for state, model in (("out", base), ("in", dimmed)): + data, variance = draw_exposure(model, 316, 0.562, rng, 16) + path = tmp_path / f"{index}-{state}.fits" + write_exposure( + path, + { + "science": data, + "variance": variance, + "mask": np.zeros(data.shape, np.uint8), + "header": fits.Header({"SIMULATE": True}), + }, + ) + paths.append(path) + # No injection truth file or PSF truth is supplied to measurement. + measured.append(measure_case(*paths, target)) + planet, blend = measured + assert planet["backend"] == blend["backend"] == "cupy" + assert np.linalg.norm(planet["fading_source_offset_xy_pixels"]) < 0.6 + assert np.linalg.norm(blend["fading_source_offset_xy_pixels"]) > 1.0 + assert abs( + planet["aperture_depth"] - blend["aperture_depth"] + ) < 3 * np.hypot( + planet["aperture_depth_error"], blend["aperture_depth_error"] + ) diff --git a/examples/model-sky/tests/test_pipeline.py b/examples/model-sky/tests/test_pipeline.py new file mode 100644 index 00000000..1117977d --- /dev/null +++ b/examples/model-sky/tests/test_pipeline.py @@ -0,0 +1,123 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Behavioral controls for the Model Sky measurements.""" + +import sys +from pathlib import Path + +import numpy as np +import pytest +from astropy.wcs import WCS +from scipy.ndimage import gaussian_filter + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import pipeline # noqa: E402 + + +def test_trail_mask_leaves_a_localized_galaxy_alone(): + yy, xx = np.indices((240, 240)) + rng = np.random.default_rng(41) + galaxy = 80 * np.exp(-(((xx - 65) / 18) ** 2) - ((yy - 100) / 2) ** 2) + galaxy += rng.normal(size=galaxy.shape) + mask, _ = pipeline.detect_trail(galaxy, np.ones_like(galaxy)) + assert not mask.any() + trail = 30 * np.exp(-(((yy - 0.45 * xx - 45) / 5) ** 2)) + mask, result = pipeline.detect_trail(trail + galaxy, np.ones_like(galaxy)) + assert result["detected"] + assert mask[99, 120] + assert not mask[200, 20] + + +@pytest.mark.parametrize("exposure_s,eccentricity", [(30, 0), (180, 0.12)]) +def test_physical_transit_depth_and_time_recovery(exposure_s, eccentricity): + from model_sky import SceneConfig + from scene import transit_flux + + times = np.arange(120) - 59.5 + rng = np.random.default_rng(18) + config = SceneConfig( + radius_ratio=0.116, exposure_s=exposure_s, eccentricity=eccentricity + ) + shape = transit_flux(times - 3.5, config) + error = np.full(120, 0.001) + data = shape + rng.normal(scale=error) + fit = pipeline.fit_transit( + times, + data, + error, + np.ones(120, bool), + dict( + exposure_s=exposure_s, + eccentricity=eccentricity, + limb_darkening=[ + config.limb_darkening_u1, + config.limb_darkening_u2, + ], + ), + ) + assert abs(fit["radius_ratio"] - 0.116) < 3 * fit["radius_ratio_error"] + assert abs(fit["midtime_min"] - 3.5) < 3 * fit["midtime_error_min"] + + +def test_rejects_insufficient_photometry(): + with pytest.raises(ValueError, match="not enough"): + pipeline.fit_transit( + np.arange(10), np.ones(10), np.ones(10), np.ones(10, bool), {} + ) + + +def test_cuda_motion_recovers_shift_with_broader_seeing(): + pytest.importorskip("cupy") + wcs = WCS(naxis=2) + wcs.wcs.ctype = ["RA---TAN", "DEC--TAN"] + wcs.wcs.crval = [53, -28] + wcs.wcs.crpix = [128, 128] + wcs.wcs.cdelt = [-0.2 / 3600, 0.2 / 3600] + rng = np.random.default_rng(8) + yy, xx = np.indices((256, 256)) + old = np.zeros((256, 256)) + for x, y, flux in [ + (60, 60, 8000), + (120, 60, 6000), + (190, 60, 5000), + (60, 190, 4000), + (190, 190, 3000), + ]: + old += flux * np.exp(-((xx - x) ** 2 + (yy - y) ** 2) / 8) + new = old.copy() + old += 5000 * np.exp(-((xx - 130) ** 2 + (yy - 130) ** 2) / 8) + new += 5000 * np.exp(-((xx - 135) ** 2 + (yy - 132) ** 2) / 8) + new = gaussian_filter(new, 1) + + def exposure(data): + return { + "science": data + rng.normal(0, 10, data.shape), + "variance": np.full(data.shape, 100.0), + "mask": np.zeros(data.shape, dtype="uint32"), + "header": wcs.to_header(), + } + + result = pipeline.measure_motion( + exposure(old), exposure(new), np.array([130.0, 130.0]) + ) + assert result["backend"] == "cupy" + np.testing.assert_allclose(result["new_xy"], [135, 132], atol=0.1) + np.testing.assert_allclose(result["old_xy"], [130, 130], atol=0.1) + assert abs(result["separation_pixels"] - np.hypot(5, 2)) < 0.1 + + +def test_fully_masked_forced_fit_is_invalid(): + cp = pytest.importorskip("cupy") + from cuphoton.xfit import forced_psf_photometry + + result = forced_psf_photometry( + cp.ones((1, 21, 21)), + cp.ones((1, 21, 21)), + cp.zeros((1, 2)), + 2, + mask=cp.zeros((1, 21, 21), dtype=bool), + ) + assert not result.valid.item() + assert cp.isnan(result.flux).item() diff --git a/examples/model-sky/tests/test_scene.py b/examples/model-sky/tests/test_scene.py new file mode 100644 index 00000000..ad3b0815 --- /dev/null +++ b/examples/model-sky/tests/test_scene.py @@ -0,0 +1,147 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Physical checks for the workshop's calibration-unit simulation.""" + +import json +import sys +from pathlib import Path + +import numpy as np +import pytest +from astropy.io import fits +from astropy.wcs import WCS + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from model_sky import SceneConfig, prepare # noqa: E402 +from scene import ( # noqa: E402 + add_star, + binary_quality_mask, + draw_exposure, + load_exposure, + normalized_psf, + prepare_bundle, + transit_flux, +) + + +def test_preparation_refuses_existing_data_without_changing_it(tmp_path): + provenance = tmp_path / "provenance" + provenance.mkdir() + calibration = provenance / "calibration.json" + calibration.write_text('{"original": true}\n') + with pytest.raises(ValueError, match="absent or empty"): + prepare(tmp_path) + assert calibration.read_text() == '{"original": true}\n' + assert sorted(p.name for p in provenance.iterdir()) == [calibration.name] + + +@pytest.mark.parametrize("scale", [0.25, 0.562, 2.0, 10.0]) +@pytest.mark.parametrize("n_average", [1, 16]) +def test_calibrated_noise_mean_and_variance(scale, n_average): + # A Monte Carlo check distinguishes a*M from the reciprocal-gain mistake. + sample, declared = draw_exposure( + np.full(200_000, 100.0), + 316.0, + scale, + np.random.default_rng(721), + n_average, + ) + expected_variance = (316 + scale * 100) / n_average + assert abs(sample.mean() - 100) < 5 * np.sqrt( + expected_variance / sample.size + ) + assert sample.var() / expected_variance == pytest.approx(1, abs=0.012) + assert declared[0] == pytest.approx(expected_variance) + + +def test_detected_pixels_are_usable_but_saturation_is_bad(): + raw = np.array([[0, 1 << 5, 1 << 1, (1 << 1) | (1 << 5)]]) + result = binary_quality_mask( + raw, {"mask_planes": {"DETECTED": 5, "SAT": 1}} + ) + np.testing.assert_array_equal(result, [[0, 0, 1, 1]]) + + +def test_subpixel_source_preserves_flux_and_centroid(): + yy, xx = np.indices((25, 25)) + psf = normalized_psf(np.exp(-((xx - 12) ** 2 + (yy - 12) ** 2) / 8), 1.2) + image = np.zeros((128, 128)) + xy = np.array([63.27, 62.61]) + add_star(image, psf, xy, 12345.0) + yy, xx = np.indices(image.shape) + assert image.sum() == pytest.approx(12345.0) + np.testing.assert_allclose( + [(image * xx).sum() / image.sum(), (image * yy).sum() / image.sum()], + xy, + atol=0.002, + ) + + +def test_geometric_transit_has_ingress_and_52_minute_duration(): + config = SceneConfig() + times = np.arange(-60, 60, 0.02) + flux = transit_flux(times, config) + assert flux[0] == flux[-1] == 1.0 + assert 0.015 < 1 - flux.min() < 0.02 + active = times[flux < 1 - 1e-7] + assert 51 < active[-1] - active[0] < 53 + assert np.all(np.diff(flux[(times > -24) & (times < -20)]) < 0) + + +def test_bundle_preserves_astrometry_and_keeps_truth_separate(tmp_path): + calibration = tmp_path / "calibration" + calibration.mkdir() + wcs = WCS(naxis=2) + wcs.wcs.crpix = [64.5, 64.5] + wcs.wcs.crval = [53.0, -28.0] + wcs.wcs.cdelt = [-0.2 / 3600, 0.2 / 3600] + wcs.wcs.ctype = ["RA---TAN", "DEC--TAN"] + yy, xx = np.indices((25, 25)) + np.savez( + calibration / "calibration.npz", + background=np.zeros((128, 128)), + base_psf=np.exp(-((xx - 12) ** 2 + (yy - 12) ** 2) / 8), + sky_variance=np.full((128, 128), 316.0), + noise_scale=np.full((128, 128), 0.562), + quality_mask=np.zeros((128, 128), dtype=np.uint8), + ) + fits.PrimaryHDU(header=wcs.to_header()).writeto( + calibration / "calibration.fits" + ) + (calibration / "calibration.json").write_text( + json.dumps( + { + "pixel_scale_arcsec": 0.2, + "quality_mask_is_binary": True, + } + ) + ) + config = SceneConfig(n_epochs=8, trail_epoch=3) + output = tmp_path / "bundle" + manifest = prepare_bundle(calibration, output, config=config) + truth = json.loads((output / manifest["truth"]["json"]).read_text()) + old = load_exposure(output / manifest["files"]["reference_old"]) + current = load_exposure(output / manifest["files"]["reference_current"]) + sky_old = WCS(old["header"]).pixel_to_world(*truth["old_target_xy"]) + sky_new = WCS(current["header"]).pixel_to_world( + *truth["current_target_xy"] + ) + assert sky_old.separation(sky_new).arcsec == pytest.approx( + 0.948, abs=0.001 + ) + assert current["header"]["SIMULATE"] + assert current["header"]["NCOMBINE"] == 16 + assert "radius_ratio" not in manifest["assumptions"] + assert "config" not in manifest["fingerprint"] + with np.load(output / manifest["truth"]["npz"]) as latent: + for epoch, xy in zip( + manifest["epochs"], latent["epoch_target_xy"], strict=True + ): + exposure = load_exposure(output / epoch["path"]) + sky_epoch = WCS(exposure["header"]).pixel_to_world(*xy) + assert sky_epoch.separation(sky_new).arcsec < 1e-6 + assert np.all(exposure["variance"] > 0) + assert set(np.unique(exposure["mask"])) <= {0, 1} + assert prepare_bundle(calibration, output, config=config) == manifest diff --git a/examples/model-sky/tests/test_views.py b/examples/model-sky/tests/test_views.py new file mode 100644 index 00000000..68320a37 --- /dev/null +++ b/examples/model-sky/tests/test_views.py @@ -0,0 +1,42 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Standalone export must leave figures available for notebook display.""" + +import sys +from pathlib import Path + +from bokeh.io import notebook, showing +from bokeh.io.state import State +from bokeh.layouts import column +from bokeh.models import Div +from bokeh.plotting import figure + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from notebook_style import show_dark # noqa: E402 +from views import export_html # noqa: E402 + + +def test_export_then_inline_display(tmp_path, monkeypatch): + plot = figure() + plot.scatter([1, 2], [3, 4]) + layout = column(Div(text="Fading-light diagnostic"), plot) + path = export_html(layout, tmp_path / "view.html") + assert "Fading-light diagnostic" in path.read_text() + assert "Bokeh" in path.read_text() + + displayed = [] + monkeypatch.setattr( + notebook, + "publish_display_data", + lambda data, **kwargs: displayed.append(data), + ) + state = State() + state.output_notebook(notebook_type="jupyter") + monkeypatch.setattr(showing, "curstate", lambda: state) + # Exercise the actual blend export/display sequence. Only the frontend + # publishing step and notebook output state are supplied by the test. + show_dark(layout) + assert any("text/html" in output for output in displayed) + assert any("application/javascript" in output for output in displayed) diff --git a/examples/model-sky/views.py b/examples/model-sky/views.py new file mode 100644 index 00000000..bbc3e8fa --- /dev/null +++ b/examples/model-sky/views.py @@ -0,0 +1,1096 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Offline, linked scientific views for the Model Sky notebook. + +Images retain their native pixels. Pixel (0, 0) is at the lower left, as in +FITS/WCS; a supplied WCS must describe the supplied cutout, not its parent. +All factories return fresh Bokeh models. JavaScript changes only the display; +scientific fits and learner parameter changes run in Python or the CLI. +""" + +from __future__ import annotations + +from collections.abc import Mapping +from html import escape +from pathlib import Path + +import numpy as np +from bokeh.embed import file_html +from bokeh.layouts import column, row +from bokeh.models import ( + Arrow, + Button, + CheckboxGroup, + ColorBar, + ColumnDataSource, + CustomJS, + Div, + HoverTool, + Label, + LinearColorMapper, + NormalHead, + RadioButtonGroup, + Range1d, + Slider, + Span, +) +from bokeh.palettes import Greys256, RdBu11 +from bokeh.plotting import figure +from bokeh.resources import INLINE + +_INK = "#172b45" +_MUTED = "#52647c" +_BLUE = "#007f99" +_AMBER = "#d97a00" +_SURFACE = "#f7f9fc" +_DIVERGING = list(RdBu11) # Negative blue; positive red. +_GRAY = list(Greys256) # Low dark; high light. + + +def _text(title, body="", *, eyebrow=""): + return Div( + text=( + '
' + f'
{escape(eyebrow.upper())}
' + f'
{escape(title)}
' + '
' + f"{escape(body)}
" + "
" + ), + sizing_mode="stretch_width", + ) + + +def _note(body): + return Div( + text=f'
{escape(body)}
', + sizing_mode="stretch_width", + ) + + +def _style(plot): + plot.background_fill_color = "#ffffff" + plot.border_fill_color = "#ffffff" + plot.outline_line_color = "#d8e1ec" + plot.title.text_color = _INK + plot.title.text_font = "Arial" + plot.title.text_font_size = "14px" + plot.title.text_font_style = "bold" + plot.axis.axis_label_text_font = "Arial" + plot.axis.axis_label_text_font_style = "normal" + plot.axis.axis_label_text_font_size = "12px" + plot.axis.major_label_text_font_size = "11px" + plot.axis.axis_label_text_color = _MUTED + plot.axis.major_label_text_color = _MUTED + plot.axis.axis_line_color = "#bdcad9" + plot.axis.major_tick_line_color = "#bdcad9" + plot.axis.minor_tick_line_color = None + plot.grid.grid_line_color = "#e9eef4" + plot.toolbar.logo = None + plot.min_border = 12 + plot.hidpi = True + return plot + + +def _image(array): + result = np.asarray(array, dtype=np.float32) + if result.ndim != 2 or min(result.shape) < 1: + raise ValueError("An image must be a nonempty two-dimensional array.") + return result + + +def _bounds(*arrays): + finite = np.concatenate([a[np.isfinite(a)] for a in arrays]) + if not finite.size: + return 0.0, 1.0 + low, high = np.percentile(finite, [1, 99.7]) + if low == high: + high = low + max(abs(low) * 0.01, 1.0) + return float(low), float(high) + + +def _limit(array): + finite = np.abs(array[np.isfinite(array)]) + limit = float(np.percentile(finite, 99.5)) if finite.size else 1.0 + return limit if limit > 0 else 1.0 + + +def _sky(shape, wcs): + if wcs is None: + return {} + yy, xx = np.indices(shape, dtype=float) + ra, dec = wcs.celestial.pixel_to_world_values(xx, yy) + return {"ra": [np.asarray(ra)], "dec": [np.asarray(dec)]} + + +def _scale_bar(plot, shape, pixel_scale): + if pixel_scale <= 0: + raise ValueError("pixel_scale must be positive arcseconds per pixel.") + height, width = shape + target = width * pixel_scale / 4 + decade = 10 ** np.floor(np.log10(target)) + length = max(v for v in (1, 2, 5, 10) if v <= target / decade) * decade + x, y = width * 0.07, height * 0.08 + plot.line( + [x, x + length / pixel_scale], + [y, y], + line_width=5, + line_color="#152436", + line_alpha=0.7, + ) + plot.line( + [x, x + length / pixel_scale], + [y, y], + line_width=2, + line_color="white", + ) + plot.add_layout( + Label( + x=x, + y=y, + y_offset=5, + text=f"{length:g} arcsec", + text_font_size="11px", + text_color="white", + background_fill_color="#152436", + background_fill_alpha=0.8, + border_line_color=None, + ) + ) + + +def _image_panel( + array, + title, + *, + mapper, + pixel_scale=0.2, + unit="nJy", + mask=None, + wcs=None, + ranges=None, + width=350, +): + array = _image(array) + height, image_width = array.shape + mask_array = ( + np.zeros_like(array, dtype=np.uint8) + if mask is None + else np.asarray(mask, dtype=bool).astype(np.uint8) + ) + if mask_array.shape != array.shape: + raise ValueError( + "mask must have the image shape; True means excluded." + ) + source = ColumnDataSource( + dict(image=[array], mask=[mask_array], **_sky(array.shape, wcs)) + ) + if ranges is None: + ranges = ( + Range1d(-0.5, image_width - 0.5), + Range1d(-0.5, height - 0.5), + ) + plot = _style( + figure( + title=title, + width=width + 40, + height=round((width - 85) * height / image_width) + 85, + sizing_mode="fixed", + x_range=ranges[0], + y_range=ranges[1], + match_aspect=True, + x_axis_label="Cutout x [pixel]", + y_axis_label="Cutout y [pixel]", + tools="pan,wheel_zoom,box_zoom,reset,save", + toolbar_location="above", + name=title, + ) + ) + plot.min_border_left = 50 + plot.min_border_right = 75 + plot.min_border_top = 35 + plot.min_border_bottom = 50 + plot.grid.visible = False + renderer = plot.image( + image="image", + source=source, + x=-0.5, + y=-0.5, + dw=image_width, + dh=height, + color_mapper=mapper, + ) + tooltips = [ + ("Pixel (x, y)", "($x{0.0}, $y{0.0})"), + (f"Signal [{unit}]", "@image{0.0000}"), + ] + if mask is not None: + tooltips.append(("Excluded pixel", "@mask")) + if wcs is not None: + tooltips += [ + ("RA [deg]", "@ra{0.000000}"), + ("Dec [deg]", "@dec{0.000000}"), + ] + plot.add_tools(HoverTool(renderers=[renderer], tooltips=tooltips)) + plot.add_layout( + ColorBar( + color_mapper=mapper, + title=unit, + width=8, + padding=7, + title_text_font_size="11px", + title_text_font_style="normal", + major_label_text_font_size="10px", + label_standoff=4, + ), + "right", + ) + _scale_bar(plot, array.shape, pixel_scale) + overlay = None + if mask is not None: + rgba = np.zeros((*array.shape, 4), dtype=np.uint8) + rgba[mask_array != 0] = [245, 173, 50, 100] + overlay = plot.image_rgba( + image=[rgba.view(np.uint32).reshape(array.shape)], + x=-0.5, + y=-0.5, + dw=image_width, + dh=height, + ) + return plot, source, overlay + + +def _triptych( + science, reference, difference, *, mask, pixel_scale, unit, wcs +): + science, reference, difference = map( + _image, (science, reference, difference) + ) + if reference.shape != science.shape or difference.shape != science.shape: + raise ValueError( + "The three registered images must have equal shapes." + ) + low, high = _bounds(science, reference) + raw_mapper = LinearColorMapper(palette=_GRAY, low=low, high=high) + limit = _limit(difference) + residual_mapper = LinearColorMapper( + palette=_DIVERGING, low=-limit, high=limit, nan_color="#b8c3d1" + ) + ranges = ( + Range1d(-0.5, science.shape[1] - 0.5), + Range1d(-0.5, science.shape[0] - 0.5), + ) + panels, overlays = [], [] + for array, title, mapper in ( + (reference, "Reference", raw_mapper), + (science, "Science", raw_mapper), + (difference, "Science − matched reference", residual_mapper), + ): + panel, _, overlay = _image_panel( + array, + title, + mapper=mapper, + mask=mask, + ranges=ranges, + pixel_scale=pixel_scale, + unit=unit, + wcs=wcs, + ) + panels.append(panel) + if overlay is not None: + overlays.append(overlay) + items = [row(*panels, sizing_mode="stretch_width")] + if overlays: + toggle = CheckboxGroup( + labels=["Show excluded pixels in amber"], active=[0] + ) + toggle.js_on_change( + "active", + CustomJS( + args=dict(overlays=overlays), + code=""" + for (const overlay of overlays) { + overlay.visible = cb_obj.active.includes(0); + } + """, + ), + ) + items.insert(0, toggle) + items.append( + _note( + "Pan and zoom are linked. Raw panels share a linear color scale " + "(1st–99.7th percentile); residuals use a symmetric scale " + "(99.5th percentile of absolute signal). Blue is negative; red " + "is " + "positive. Color clipping changes only the display, not the data." + ) + ) + return items + + +def observed_image( + image, + *, + title="Model Sky · modeled field", + eyebrow="Model Sky imagery", + pixel_scale=0.2, + wcs=None, + unit="nJy", + context="", +): + """Display one exposure without invented comparison planes.""" + image = _image(image) + low, high = _bounds(image) + plot, _, _ = _image_panel( + image, + title, + mapper=LinearColorMapper(palette=_GRAY, low=low, high=high), + pixel_scale=pixel_scale, + wcs=wcs, + unit=unit, + width=760, + ) + return column( + _text(title, context, eyebrow=eyebrow), + plot, + _note( + "Native image pixels. The linear display clips at the 1st " + "and 99.7th percentiles; hover reports original values." + ), + sizing_mode="stretch_width", + max_width=1200, + ) + + +def image_triptych( + science, + reference, + difference, + *, + mask=None, + title="", + pixel_scale=0.2, + wcs=None, + unit="nJy", + context="", +): + """Compare registered images; ``mask=True`` identifies excluded pixels.""" + return column( + _text( + title or "What changed in the sky?", + context, + eyebrow="Image evidence", + ), + *_triptych( + science, + reference, + difference, + mask=mask, + pixel_scale=pixel_scale, + unit=unit, + wcs=wcs, + ), + sizing_mode="stretch_width", + max_width=1200, + ) + + +def trail_view( + science, + reference, + difference, + mask, + *, + profile=None, + pixel_scale=0.2, + wcs=None, + unit="nJy", + context="", +): + """Inspect a trail, its exclusion mask and an optional supplied profile. + + A profile mapping contains ``x``, ``science``, ``reference`` and optional + ``difference`` arrays; ``x_label`` describes the supplied coordinate. + Without a profile, show the literal mean of each complete image row. + """ + science, reference, difference = map( + _image, (science, reference, difference) + ) + count = np.count_nonzero(mask) + body = ( + f"{count:,} of {science.size:,} pixels marked for exclusion. " + + context + ) + if profile is None: + + def row_mean(values): + finite = np.isfinite(values) + count = finite.sum(axis=1) + return np.divide( + np.nansum(values, axis=1), + count, + out=np.full(len(count), np.nan), + where=count > 0, + ) + + profile = dict( + x=np.arange(science.shape[0]), + science=row_mean(science), + reference=row_mean(reference), + difference=row_mean(difference), + x_label="Cutout y [pixel] · mean over every column", + y_label=f"Mean signal [{unit}]", + ) + p = _style( + figure( + title="Where does the trail contribute signal?", + height=240, + width=1050, + sizing_mode="stretch_width", + x_axis_label=str(profile.get("x_label", "Profile coordinate")), + y_axis_label=str(profile.get("y_label", f"Signal [{unit}]")), + tools="pan,wheel_zoom,reset,save", + ) + ) + for key, color in ( + ("science", _AMBER), + ("reference", _BLUE), + ("difference", "#9a497c"), + ): + if key in profile: + p.line( + profile["x"], + profile[key], + line_width=2, + line_color=color, + legend_label=key.capitalize(), + ) + p.legend.click_policy = "hide" + p.legend.location = "top_right" + return column( + _text( + "A satellite crosses the field", + body, + eyebrow="01 · Satellite trail", + ), + *_triptych( + science, + reference, + difference, + mask=mask, + pixel_scale=pixel_scale, + unit=unit, + wcs=wcs, + ), + p, + sizing_mode="stretch_width", + max_width=1200, + ) + + +def motion_view( + old, + new, + difference, + *, + old_xy, + new_xy, + uncertainty=None, + baseline_years=10, + pixel_scale=0.2, + wcs=None, + unit="nJy", + context="", + epoch_labels=("Earlier epoch", "Later epoch"), +): + """Blink epochs and show measured centroids in cutout pixel coordinates. + + ``uncertainty`` optionally maps ``old``/``new`` to (sigma_x, sigma_y), + in pixels. Ellipses mark one standard deviation along each coordinate; + they do not imply a fitted covariance or confidence region. + """ + old, new, difference = map(_image, (old, new, difference)) + if old.shape != new.shape or old.shape != difference.shape: + raise ValueError("Motion images must have equal registered shapes.") + if baseline_years <= 0: + raise ValueError("baseline_years must be positive.") + old_xy, new_xy = np.asarray(old_xy, float), np.asarray(new_xy, float) + displacement = np.linalg.norm(new_xy - old_xy) * pixel_scale + # Keep the small motion legible without resampling or smoothing pixels. + if max(old.shape) > 120: + center = np.rint((old_xy + new_xy) / 2).astype(int) + x0 = max(0, min(int(center[0]) - 48, old.shape[1] - 96)) + y0 = max(0, min(int(center[1]) - 48, old.shape[0] - 96)) + region = (slice(y0, y0 + 96), slice(x0, x0 + 96)) + old, new, difference = (a[region] for a in (old, new, difference)) + old_xy, new_xy = old_xy - (x0, y0), new_xy - (x0, y0) + if wcs is not None: + wcs = wcs.slice(region) + context = ( + context + f" Native target cutout; parent pixel origin " + f"({x0}, {y0})." + ).strip() + low, high = _bounds(old, new) + mapper = LinearColorMapper(palette=_GRAY, low=low, high=high) + ranges = ( + Range1d(-0.5, old.shape[1] - 0.5), + Range1d(-0.5, old.shape[0] - 0.5), + ) + blink, display, _ = _image_panel( + old, + str(epoch_labels[0]), + mapper=mapper, + ranges=ranges, + pixel_scale=pixel_scale, + wcs=wcs, + unit=unit, + width=490, + ) + limit = _limit(difference) + residual, _, _ = _image_panel( + difference, + "Later − matched earlier", + ranges=ranges, + mapper=LinearColorMapper(palette=_DIVERGING, low=-limit, high=limit), + pixel_scale=pixel_scale, + wcs=wcs, + unit=unit, + width=490, + ) + for plot in (blink, residual): + for key, point, color, label in ( + ("old", old_xy, _AMBER, str(epoch_labels[0])), + ("new", new_xy, "#00bed6", str(epoch_labels[1])), + ): + plot.scatter( + [point[0]], + [point[1]], + marker="circle", + size=17, + fill_alpha=0, + line_width=2, + line_color=color, + legend_label=label, + ) + if uncertainty is not None and key in uncertainty: + sx, sy = uncertainty[key] + plot.ellipse( + [point[0]], + [point[1]], + width=[2 * sx], + height=[2 * sy], + fill_alpha=0.15, + fill_color=color, + line_color=color, + ) + plot.add_layout( + Arrow( + x_start=old_xy[0], + y_start=old_xy[1], + x_end=new_xy[0], + y_end=new_xy[1], + line_color="#00bed6", + end=NormalHead( + size=8, fill_color="#00bed6", line_color="#00bed6" + ), + ) + ) + plot.legend.label_text_font_size = "11px" + plot.legend.background_fill_alpha = 0.85 + plot.legend.location = "top_left" + frames = ColumnDataSource(dict(image=[old, new])) + epochs = RadioButtonGroup(labels=list(map(str, epoch_labels)), active=0) + epochs.js_on_change( + "active", + CustomJS( + args=dict( + display=display, + frames=frames, + plot=blink, + labels=list(epoch_labels), + ), + code=""" + const i = cb_obj.active; + display.data.image = [frames.data.image[i]]; + display.change.emit(); + plot.title.text = labels[i]; + """, + ), + ) + play = Button( + label="Blink for 8 seconds", button_type="primary", width=180 + ) + play.js_on_click( + CustomJS( + args=dict(epochs=epochs, button=play), + code=""" + if (button.disabled) return; + button.disabled = true; + let steps = 0; + const timer = setInterval(() => { + epochs.active = 1 - epochs.active; + if (++steps >= 16) { + clearInterval(timer); button.disabled = false; + } + }, 500); + """, + ) + ) + return column( + _text( + "The star moves; the field stays put", + context, + eyebrow="02 · Controlled proper motion", + ), + _note( + f"Centroid displacement: {displacement:.3f} arcsec " + f"over {baseline_years:g} years " + f"→ {1000 * displacement / baseline_years:.1f} mas/year. " + "Positions are supplied measurements. The time baseline " + "belongs to the injection experiment." + ), + row(epochs, play, sizing_mode="stretch_width"), + row(blink, residual, sizing_mode="stretch_width"), + _note( + "Raw epochs share one linear scale; the difference has a " + "symmetric scale about zero. The blue/red dipole records " + "displaced light. Amber/cyan rings mark the two centroids. " + "Pan and zoom are linked; the blink uses the native image pixels." + ), + sizing_mode="stretch_width", + max_width=1200, + ) + + +def transit_view( + times_minutes, + flux, + flux_error, + model, + *, + stamps, + difference_stamps, + valid=None, + check_flux=None, + reference_stamp=None, + summary=None, + unit="Relative flux", + pixel_scale=0.2, + image_unit="nJy", + wcs=None, +): + """Link light curve, model residual, stamps and in-minus-baseline mean. + + Arrays share cadence order and units. Excluded points remain visible + but are excluded from both means. ``model`` is the supplied fit, + not a fit performed here. Transit membership is defined by + the model lying below half-depth; baseline uses less than 5% of depth. + """ + times, flux, error, model = map( + lambda a: np.asarray(a, dtype=float), + (times_minutes, flux, flux_error, model), + ) + n = len(times) + stamps = np.asarray(stamps, dtype=np.float32) + differences = np.asarray(difference_stamps, dtype=np.float32) + if n < 2 or any(a.shape != (n,) for a in (times, flux, error, model)): + raise ValueError( + "Light-curve arrays must be 1D with at least two cadences." + ) + if ( + stamps.ndim != 3 + or differences.shape != stamps.shape + or len(stamps) != n + ): + raise ValueError( + "Stamp arrays must have equal (cadence, y, x) shapes." + ) + if not np.all(np.isfinite(times)) or np.any(np.diff(times) <= 0): + raise ValueError( + "times_minutes must be finite and strictly increasing." + ) + if np.any(error[np.isfinite(error)] < 0): + raise ValueError("Flux uncertainties must be nonnegative.") + valid = ( + np.ones(n, bool) if valid is None else np.asarray(valid, dtype=bool) + ) + if valid.shape != (n,): + raise ValueError("valid must have one Boolean per cadence.") + usable = ( + valid & np.isfinite(flux) & np.isfinite(error) & np.isfinite(model) + ) + model_finite = model[np.isfinite(model)] + if not model_finite.size: + raise ValueError( + "The supplied model needs at least one finite value." + ) + floor, ceiling = np.min(model_finite), np.max(model_finite) + in_transit = usable & (model < (floor + ceiling) / 2) + baseline = usable & (model > ceiling - 0.05 * (ceiling - floor)) + coadd = ( + np.nanmean(differences[in_transit], axis=0) + - np.nanmean(differences[baseline], axis=0) + if in_transit.any() and baseline.any() + else np.full(stamps.shape[1:], np.nan, dtype=np.float32) + ) + first = ( + int(np.flatnonzero(in_transit)[len(np.flatnonzero(in_transit)) // 2]) + if in_transit.any() + else 0 + ) + source = ColumnDataSource( + dict( + time=times, + flux=flux, + error=error, + model=model, + lower=flux - error, + upper=flux + error, + residual=flux - model, + res_lower=flux - model - error, + res_upper=flux - model + error, + cadence=np.arange(n), + status=np.where(usable, "Used", "Excluded"), + color=np.where(usable, _BLUE, _AMBER), + marker=np.where(usable, "circle", "x"), + ) + ) + lc = _style( + figure( + title="How much light is missing?", + height=310, + width=1050, + sizing_mode="stretch_width", + y_axis_label=unit, + tools="pan,wheel_zoom,box_zoom,tap,reset,save", + ) + ) + lc.segment( + "time", + "lower", + "time", + "upper", + source=source, + line_color="color", + line_alpha=0.55, + ) + lc.line( + times, + model, + line_color="#ab3d75", + line_width=2, + legend_label="Fitted transit model", + ) + points = lc.scatter( + "time", + "flux", + source=source, + size=7, + marker="marker", + color="color", + alpha=0.85, + selection_color="#ec8c18", + nonselection_alpha=0.6, + legend_label="Measured flux (amber × = excluded)", + ) + if check_flux is not None: + check = np.asarray(check_flux, float) + if check.shape != (n,): + raise ValueError( + "check_flux needs one value per cadence in the same units." + ) + lc.line( + times, + check, + line_color="#657385", + line_alpha=0.75, + line_width=1.5, + legend_label="Check star", + ) + lc.add_tools( + HoverTool( + renderers=[points], + tooltips=[ + ("Cadence", "@cadence"), + ("Time [min]", "@time{0.00}"), + (unit, "@flux{0.00000}"), + ("1σ uncertainty", "@error{0.00000}"), + ("Use", "@status"), + ], + ) + ) + lc.legend.location = "top_right" + lc.legend.label_text_font_size = "11px" + lc.legend.click_policy = "hide" + residual = _style( + figure( + title="Measured − model", + height=180, + width=1050, + sizing_mode="stretch_width", + x_range=lc.x_range, + x_axis_label="Time from mid-transit [minutes]", + y_axis_label=f"Residual [{unit}]", + tools="pan,wheel_zoom,tap,reset,save", + ) + ) + residual.segment( + "time", + "res_lower", + "time", + "res_upper", + source=source, + line_color="color", + line_alpha=0.5, + ) + residual.scatter( + "time", + "residual", + source=source, + size=6, + marker="marker", + color="color", + nonselection_alpha=0.6, + ) + residual.add_layout( + Span( + location=0, + dimension="width", + line_color="#8190a3", + line_dash="dashed", + ) + ) + cursors = [] + for plot in (lc, residual): + cursor = Span( + location=times[first], + dimension="height", + line_color=_AMBER, + line_width=2, + line_alpha=0.65, + ) + plot.add_layout(cursor) + cursors.append(cursor) + low, high = _bounds(stamps) + raw_mapper = LinearColorMapper(palette=_GRAY, low=low, high=high) + limit = _limit(differences) + diff_mapper = LinearColorMapper( + palette=_DIVERGING, low=-limit, high=limit, nan_color="#b8c3d1" + ) + ranges = ( + Range1d(-0.5, stamps.shape[2] - 0.5), + Range1d(-0.5, stamps.shape[1] - 0.5), + ) + image_panels, image_sources = [], [] + for image, title, mapper in ( + (stamps[first], "Selected cadence", raw_mapper), + (differences[first], "Selected difference", diff_mapper), + ( + coadd, + "In-transit − baseline mean", + diff_mapper, + ), + ): + panel, image_source, _ = _image_panel( + image, + title, + mapper=mapper, + ranges=ranges, + pixel_scale=pixel_scale, + unit=image_unit, + wcs=wcs, + ) + image_panels.append(panel) + image_sources.append(image_source) + slider = Slider( + start=0, + end=n - 1, + value=first, + step=1, + title="Selected cadence · tap a point or move the slider", + sizing_mode="stretch_width", + name="cadence_slider", + ) + frames = ColumnDataSource( + dict(image=list(stamps), difference=list(differences)) + ) + readout = Div(sizing_mode="stretch_width", name="cadence_readout") + + def caption(i): + measurement = ( + f"flux = {flux[i]:.5f} ± {error[i]:.5f}" + if np.isfinite(flux[i]) and np.isfinite(error[i]) + else "flux unavailable after masking" + ) + return ( + f"Cadence {i} · t = {times[i]:.2f} min · " + f"{measurement} · " + f"{'Used' if usable[i] else 'Excluded'}" + ) + + readout.text = caption(first) + slider.js_on_change( + "value", + CustomJS( + args=dict( + source=source, + frames=frames, + raw=image_sources[0], + diff=image_sources[1], + cursors=cursors, + readout=readout, + ), + code=""" + const i = Math.round(cb_obj.value), d = source.data; + raw.data.image = [frames.data.image[i]]; + diff.data.image = [frames.data.difference[i]]; + raw.change.emit(); diff.change.emit(); + for (const cursor of cursors) cursor.location = d.time[i]; + const measurement = Number.isFinite(d.flux[i]) && + Number.isFinite(d.error[i]) ? + `flux = ${d.flux[i].toFixed(5)} ± ${d.error[i].toFixed(5)}` : + 'flux unavailable after masking'; + readout.text = `Cadence ${i} · t = ${d.time[i].toFixed(2)} min · ` + + `${measurement} · ${d.status[i]}`; + """, + ), + ) + source.selected.js_on_change( + "indices", + CustomJS( + args=dict(slider=slider), + code=""" + const indices = cb_obj.indices; + if (indices.length) slider.value = indices[indices.length - 1]; + """, + ), + ) + details = ( + "" + if summary is None + else ( + " · ".join(f"{k}: {v}" for k, v in summary.items()) + if isinstance(summary, Mapping) + else str(summary) + ) + ) + extras = [] + if reference_stamp is not None: + ref, _, _ = _image_panel( + reference_stamp, + "Out-of-transit reference", + mapper=raw_mapper, + pixel_scale=pixel_scale, + unit=image_unit, + wcs=wcs, + width=350, + ) + extras = [ + row( + ref, + _note( + "The supplied reference uses the cadence stamps' scale. " + "It is not reconstructed from a difference image." + ), + sizing_mode="stretch_width", + ) + ] + return column( + _text( + "A smaller shadow, on the same star", + details, + eyebrow="03 · Controlled transit", + ), + lc, + residual, + slider, + readout, + row(*image_panels, sizing_mode="stretch_width"), + _note( + "Image scales stay fixed across cadences. The difference and " + "stack share a symmetric scale: dimming is blue. " + f"Stack: {in_transit.sum()} in-transit minus " + f"{baseline.sum()} baseline cadences, all valid. The baseline " + "mean removes persistent residual structure. Model-selected " + "intervals (below half-depth / within 5% of full light) " + "illustrate the fit; this is not an independent detection or " + "significance map. Error " + "bars show supplied 1σ uncertainties. The light curve is a " + "controlled injection." + ), + *extras, + sizing_mode="stretch_width", + max_width=1200, + ) + + +def export_html( + layout, path, *, title="cuPhoton · A changing sky", sources=None +): + """Write a self-contained HTML document with inline BokehJS and data.""" + import mistune + + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + references = Path( + sources or Path(__file__).with_name("sources.md") + ).read_text() + footer = Div( + text=( + "
Sources and further reading" + + mistune.html(references) + + "
" + ), + styles={"color": _INK, "font-size": "13px", "padding": "16px"}, + sizing_mode="stretch_width", + max_width=1200, + ) + document = column(layout, footer, sizing_mode="stretch_width") + try: + path.write_text( + file_html(document, INLINE, title=title), encoding="utf-8" + ) + finally: + # file_html gives an unowned layout a persistent Document. Release + # this export-only wrapper so the caller can show its layout inline. + if document.document is not None: + document.document.remove_root(document) + return path + + +def export_png(layout, path, *, scale_factor=2): + """Export a native high-DPI PNG using preparation-only Chrome tooling. + + Selenium Manager resolves a matching driver for installed Chrome. + Its cache can be relocated with ``SE_CACHE_PATH``; the first export + may download the driver. HTML and notebook viewing do not use it. + """ + from bokeh.io import export_png as bokeh_export_png + from selenium import webdriver + + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + options = webdriver.ChromeOptions() + options.add_argument("--headless=new") + options.add_argument("--hide-scrollbars") + options.add_argument(f"--force-device-scale-factor={scale_factor}") + options.add_argument("--force-color-profile=srgb") + # A fixed outer width keeps responsive children independent of the + # initial headless browser viewport, which can be only 400 CSS pixels. + document = column(layout, width=1200) + with webdriver.Chrome(options=options) as driver: + bokeh_export_png( + document, + filename=str(path), + scale_factor=scale_factor, + webdriver=driver, + timeout=30, + ) + return path diff --git a/examples/model-sky/workshop.py b/examples/model-sky/workshop.py new file mode 100644 index 00000000..d48c19a2 --- /dev/null +++ b/examples/model-sky/workshop.py @@ -0,0 +1,295 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Command-line entry points for the example's measurements and artifacts.""" + +from __future__ import annotations + +import argparse +import json +import platform +from pathlib import Path + +import numpy as np +import pipeline + + +def json_default(value): + if isinstance(value, np.ndarray): + return value.tolist() + if isinstance(value, np.generic): + return value.item() + if isinstance(value, Path): + return str(value) + raise TypeError(type(value).__name__) + + +def write_json(path, value): + Path(path).write_text( + json.dumps(value, indent=2, default=json_default) + "\n" + ) + + +def save_motion(output, motion, reference): + output = Path(output) + output.mkdir(parents=True, exist_ok=True) + pipeline.write_exposure( + output / "motion_registered.fits", motion["registered"] + ) + pipeline.write_exposure(output / "motion_reference.fits", reference) + np.save( + output / "motion_fit_mask.npy", motion["fit_mask"], allow_pickle=False + ) + np.savez( + output / "motion_candidates.npz", + candidate_id=np.array(["target"]), + **{ + key: value + for key, value in motion["fit_input"].items() + if key != "stamp_scale" + }, + ) + np.savez_compressed( + output / "motion.npz", + **{ + key: value + for key, value in motion.items() + if isinstance(value, np.ndarray) + }, + ) + summary = { + key: motion[key] + for key in ( + "old_xy", + "new_xy", + "separation_pixels", + "separation_error_pixels", + "registration_floor_pixels", + "backend", + ) + } + summary["stamp_scale"] = float(motion["fit_input"]["stamp_scale"]) + write_json(output / "motion.json", summary) + return summary + + +def save_transit(output, transit): + output = Path(output) + output.mkdir(parents=True, exist_ok=True) + arrays = { + key: value + for key, value in transit.items() + if isinstance(value, np.ndarray) + } + arrays["model"] = transit["fit"]["model"] + np.savez_compressed(output / "transit.npz", **arrays) + summary = { + key: value + for key, value in transit["fit"].items() + if key not in {"model", "covariance", "parameters"} + } + summary.update( + error_scale=transit["error_scale"], + elapsed_seconds=transit["elapsed_seconds"], + backend=transit["backend"], + valid_epochs=int(transit["valid"].sum()), + trail_epochs=np.flatnonzero(transit["trail_mask_pixels"]).tolist(), + ) + write_json(output / "transit.json", summary) + np.savetxt( + output / "light_curve.csv", + np.column_stack( + [ + transit["times_minutes"], + transit["flux"], + transit["flux_error"], + transit["valid"], + transit["check_flux"], + transit["fit"]["model"], + ] + ), + delimiter=",", + header="time_min,relative_flux,error,valid,check_flux,model", + comments="", + ) + return summary + + +def export_views(output, manifest, trail, motion, transit, *, png=False): + import views + from astropy.wcs import WCS + + output = Path(output) + output.mkdir(parents=True, exist_ok=True) + scale = manifest["pixel_scale_arcsec"] + image_wcs = WCS(motion["registered"]["header"]) + x, y = np.rint(transit["positions"][0]).astype(int) + half = transit["stamps"].shape[-1] // 2 + stamp_wcs = image_wcs.slice( + (slice(y - half, y + half + 1), slice(x - half, x + half + 1)) + ) + profile_data = trail.get("trail_profile", {}) + profile = ( + dict( + x=profile_data["coordinate"], + difference=profile_data["profile"], + x_label="Perpendicular distance from trail [pixel]", + y_label="Median residual [nJy]", + ) + if profile_data.get("detected") + else None + ) + factories = { + "01_satellite": lambda: views.trail_view( + trail["science"], + trail["matched"], + trail["difference"], + trail["trail_mask"], + pixel_scale=scale, + profile=profile, + wcs=image_wcs, + context="Model Sky · simulated satellite trail.", + ), + "02_motion": lambda: views.motion_view( + motion["matched"], + motion["science"], + motion["difference"], + old_xy=motion["old_xy"], + new_xy=motion["new_xy"], + baseline_years=manifest["assumptions"]["baseline_years"], + pixel_scale=scale, + wcs=image_wcs, + context=( + f"Displacement {motion['separation_pixels']:.3f} ± " + f"{motion['separation_error_pixels']:.3f} pixel; " + "uncertainty includes the registration floor." + ), + ), + "03_transit": lambda: views.transit_view( + transit["times_minutes"], + transit["flux"], + transit["flux_error"], + transit["fit"]["model"], + stamps=transit["stamps"], + difference_stamps=transit["difference_stamps"], + valid=transit["valid"], + check_flux=transit["check_flux"], + reference_stamp=transit["reference_stamp"], + pixel_scale=scale, + wcs=stamp_wcs, + summary={ + "Geometric depth (Rp/Rstar)²": ( + f"{100 * transit['fit']['geometric_depth']:.3f}%" + ), + "Measurement": "Model Sky · simulated system and field", + }, + ), + } + for name, factory in factories.items(): + views.export_html( + factory(), + output / f"{name}.html", + sources=Path(__file__).with_name("sources.md"), + ) + if png: + views.export_png(factory(), output / f"{name}.png") + + +def run(bundle, output, *, stage="all", png=False): + import cuphoton + + root, manifest = pipeline.load_bundle(bundle) + output = Path(output).resolve() + output.mkdir(parents=True, exist_ok=True) + cp = pipeline.gpu() + properties = cp.cuda.runtime.getDeviceProperties(cp.cuda.Device().id) + write_json( + output / "runtime.json", + { + "cuphoton": cuphoton.__version__, + "python": platform.python_version(), + "machine": platform.machine(), + "host": platform.node(), + "gpu": properties["name"].decode(), + "cupy": cp.__version__, + "cuda_runtime": cp.cuda.runtime.runtimeGetVersion(), + "cuda_driver": cp.cuda.runtime.driverGetVersion(), + "backend": "cupy", + "truth_used_for_measurement": False, + }, + ) + old = pipeline.read_exposure( + pipeline.bundle_path(root, manifest["files"]["reference_old"]) + ) + current = pipeline.read_exposure( + pipeline.bundle_path(root, manifest["files"]["reference_current"]) + ) + seed = np.asarray(manifest["target_search"]["old_xy"]) + motion = pipeline.measure_motion( + old, + pipeline.read_exposure( + pipeline.bundle_path(root, manifest["files"]["motion"]) + ), + seed, + search_radius=manifest["target_search"].get("radius_pixels", 18), + ) + summary = {"motion": save_motion(output, motion, old)} + if stage == "motion": + return summary + anchors = pipeline.select_stars(current, exclude=[motion["new_xy"]]) + trail = pipeline.subtract( + current, + pipeline.register( + pipeline.read_exposure( + pipeline.bundle_path(root, manifest["files"]["trail"]) + ), + current, + anchors=anchors, + ), + exclude=[motion["new_xy"]], + ) + np.savez_compressed( + output / "trail.npz", + **{ + key: value + for key, value in trail.items() + if isinstance(value, np.ndarray) + }, + ) + if stage == "trail": + return {**summary, "trail_pixels": int(trail["trail_mask"].sum())} + transit = pipeline.measure_transit( + root, + manifest, + motion["new_xy"], + progress=lambda n, total: print( + f"Measured {n}/{total} exposures", flush=True + ), + ) + summary["transit"] = save_transit(output, transit) + export_views(output, manifest, trail, motion, transit, png=png) + write_json(output / "summary.json", summary) + return summary + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "stage", choices=["motion", "trail", "transit", "all"] + ) + parser.add_argument("--bundle", type=Path, required=True) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--png", action="store_true") + args = parser.parse_args() + print( + json.dumps( + run(args.bundle, args.output, stage=args.stage, png=args.png), + indent=2, + default=json_default, + ) + ) + + +if __name__ == "__main__": + main() From 45b8822f3d80bbd846b1eb1df3108a640bcd6c47 Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Mon, 16 Nov 2026 12:10:55 -0800 Subject: [PATCH 2/3] Guard Model Sky measurements and notebook execution Reject unconstrained transit fits and keep masked reference pixels out of convolution fits and residuals. Select transit images from the baseline-normalized model and preserve bundle and execution integrity. Signed-off-by: Trent Nelson --- examples/model-sky/model-sky.ipynb | 3 +- examples/model-sky/pipeline.py | 13 +++- examples/model-sky/preview.py | 2 + examples/model-sky/run.py | 8 +- examples/model-sky/scene.py | 12 ++- examples/model-sky/tests/test_pipeline.py | 44 +++++++++++ examples/model-sky/tests/test_runner.py | 89 +++++++++++++++++++++++ examples/model-sky/tests/test_scene.py | 23 +++++- examples/model-sky/tests/test_views.py | 32 +++++++- examples/model-sky/views.py | 25 +++++-- examples/model-sky/workshop.py | 1 + 11 files changed, 231 insertions(+), 21 deletions(-) create mode 100644 examples/model-sky/tests/test_runner.py diff --git a/examples/model-sky/model-sky.ipynb b/examples/model-sky/model-sky.ipynb index b1755bf2..035f48df 100644 --- a/examples/model-sky/model-sky.ipynb +++ b/examples/model-sky/model-sky.ipynb @@ -1204,6 +1204,7 @@ "show_dark(views.transit_view(\n", " transit[\"times_minutes\"], transit[\"flux\"], transit[\"flux_error\"],\n", " transit_fit[\"model\"], stamps=transit[\"stamps\"],\n", + " transit_model=transit_fit[\"transit_model\"],\n", " difference_stamps=transit[\"difference_stamps\"],\n", " valid=transit[\"valid\"], check_flux=transit[\"check_flux\"],\n", " reference_stamp=transit[\"reference_stamp\"], pixel_scale=scale,\n", @@ -1666,7 +1667,7 @@ "cell_type": "code", "metadata": {}, "source": [ - "display(Markdown(Path(\"sources.md\").read_text()))" + "display(Markdown(Path(\"sources.md\").read_text(encoding=\"utf-8\")))" ], "id": "7cb52faf0f5a", "execution_count": null, diff --git a/examples/model-sky/pipeline.py b/examples/model-sky/pipeline.py index 0c1b9d87..6e75036e 100644 --- a/examples/model-sky/pipeline.py +++ b/examples/model-sky/pipeline.py @@ -285,7 +285,11 @@ def detect_trail(difference, variance, good=None, *, width_scale=1.0): def subtract(reference, science, *, exclude=(), trail_width=1.0): """Fit, detect a trail, exclude it, then refit the xPois kernel.""" - usable = good_pixels(reference) & good_pixels(science) + kernel_shape = (21, 21) + contaminated = ndimage.binary_dilation( + ~good_pixels(reference), structure=np.ones(kernel_shape, dtype=bool) + ) + usable = ~contaminated & good_pixels(science) fitting = usable & ~exclusion_disks(usable.shape, exclude) components = [ GaussianBasisComponent(sigma=0.7, degree=2), @@ -300,7 +304,7 @@ def solve(mask): components, variance=science["variance"], fit_mask=mask, - kernel_shape=(21, 21), + kernel_shape=kernel_shape, background_degree=0, backend="cupy", ) @@ -552,11 +556,16 @@ def model(p, x): [0.1, 0, 1, 0], bounds=([0.01, -25, 0.95, -0.05], [0.3, 25, 1.05, 0.05]), ) + if np.linalg.matrix_rank(result.jac) < len(result.x): + raise ValueError("transit fit is unconstrained") covariance = np.linalg.pinv(result.jac.T @ result.jac) return { "parameters": result.x, "covariance": covariance, "model": model(result.x, times), + "transit_model": transit_shape( + times, result.x[0], result.x[1], assumptions + ), "success": bool(result.success), "radius_ratio": float(result.x[0]), "radius_ratio_error": float(np.sqrt(covariance[0, 0])), diff --git a/examples/model-sky/preview.py b/examples/model-sky/preview.py index d67b8287..61786d80 100644 --- a/examples/model-sky/preview.py +++ b/examples/model-sky/preview.py @@ -41,6 +41,8 @@ def main() -> None: output = options.output.resolve() if output == HERE or output.is_relative_to(HERE): parser.error("--output must be outside the example source directory") + if output.is_relative_to((REPO / "docs/guide").resolve()): + parser.error("--output must be outside the guide source directory") if output.exists() and any(output.iterdir()): parser.error("--output must be absent or empty") diff --git a/examples/model-sky/run.py b/examples/model-sky/run.py index 0eab8485..460f6656 100644 --- a/examples/model-sky/run.py +++ b/examples/model-sky/run.py @@ -22,7 +22,7 @@ from pathlib import Path import nbformat -from jupyter_client import KernelManager +from jupyter_client import AsyncKernelManager from nbclient import NotebookClient HERE = Path(__file__).resolve().parent @@ -135,7 +135,7 @@ def main() -> None: input_hashes = { path.relative_to(output).as_posix(): sha256(path) for path in inputs } - manager = KernelManager(kernel_name="python3") + manager = AsyncKernelManager(kernel_name="python3") manager.kernel_spec.argv = [ sys.executable, "-m", @@ -163,10 +163,8 @@ def cell_start(cell, cell_index, **kwargs): executed = output / "model-sky.executed.ipynb" started = time.monotonic() try: - client.execute(cwd=str(output), env=env) + client.execute(cwd=str(output), env=env, cleanup_kc=True) finally: - if manager.has_kernel: - manager.shutdown_kernel(now=True) # Preserve every output, including warnings. Only machine-local path # prefixes in streams are replaced; figures and numbers are untouched. for cell in code: diff --git a/examples/model-sky/scene.py b/examples/model-sky/scene.py index 332899a8..7da4e6b1 100644 --- a/examples/model-sky/scene.py +++ b/examples/model-sky/scene.py @@ -333,9 +333,12 @@ def prepare_bundle( raise ValueError( "bundle inputs changed; use --force to regenerate" ) - for relative in previous["sha256"]: - if not (output_dir / relative).is_file(): - raise FileNotFoundError(output_dir / relative) + for relative, expected in previous["sha256"].items(): + path = output_dir / relative + if not path.is_file(): + raise FileNotFoundError(path) + if sha256(path) != expected: + raise ValueError(f"bundle file hash mismatch: {relative}") return previous metadata = json.loads(inputs[2].read_text()) with np.load(inputs[0]) as arrays: @@ -447,6 +450,9 @@ def render( ("trail", -45, current_xy, 1.4, 1, True), ] reference_psfs, all_paths = [], [] + # An interrupted forced rebuild must not leave a completion marker for + # a mixture of old and newly written exposures. + manifest_path.unlink(missing_ok=True) for key, time_min, xy, blur, n_average, with_trail in specifications: image, variance, mask, psf, trail = render( time_min, diff --git a/examples/model-sky/tests/test_pipeline.py b/examples/model-sky/tests/test_pipeline.py index 1117977d..c7956507 100644 --- a/examples/model-sky/tests/test_pipeline.py +++ b/examples/model-sky/tests/test_pipeline.py @@ -6,6 +6,7 @@ import sys from pathlib import Path +from types import SimpleNamespace import numpy as np import pytest @@ -68,6 +69,49 @@ def test_rejects_insufficient_photometry(): ) +def test_rejects_epochs_that_do_not_constrain_the_transit(): + times = np.linspace(60, 120, 60) + with pytest.raises(ValueError, match="unconstrained"): + pipeline.fit_transit( + times, np.ones(60), np.full(60, 0.001), np.ones(60, bool), {} + ) + + +def test_bad_reference_pixel_excludes_its_full_kernel_footprint(monkeypatch): + clean = np.random.default_rng(53).normal(100, 5, (64, 64)) + reference = { + "science": clean.copy(), + "variance": np.ones_like(clean), + "mask": np.zeros_like(clean, dtype=np.uint8), + } + reference["science"][32, 32] = 1e7 + reference["mask"][32, 32] = 1 + science = { + "science": gaussian_filter(clean, 0.8) + 3, + "variance": np.ones_like(clean), + "mask": np.zeros_like(clean, dtype=np.uint8), + } + + def solve( + reference, target, components, *, fit_mask, kernel_shape, **kwargs + ): + return SimpleNamespace( + residual=np.zeros_like(target), + kernel=np.ones(kernel_shape) / np.prod(kernel_shape), + matched=target, + background=np.zeros_like(target), + fit_mask=fit_mask, + backend="test", + ) + + monkeypatch.setattr(pipeline, "solve_constant_kernel", solve) + result = pipeline.subtract(reference, science) + assert not result["fit_mask"][22:43, 22:43].any() + assert not result["valid"][22:43, 22:43].any() + assert result["fit_mask"][21, 21] + assert result["valid"][21, 21] + + def test_cuda_motion_recovers_shift_with_broader_seeing(): pytest.importorskip("cupy") wcs = WCS(naxis=2) diff --git a/examples/model-sky/tests/test_runner.py b/examples/model-sky/tests/test_runner.py new file mode 100644 index 00000000..093b2489 --- /dev/null +++ b/examples/model-sky/tests/test_runner.py @@ -0,0 +1,89 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Check preview destinations and real notebook timeout cleanup.""" + +import importlib.util +import sys +from pathlib import Path +from types import SimpleNamespace + +import nbformat +import pytest +from nbclient.exceptions import CellTimeoutError + +HERE = Path(__file__).resolve().parents[1] + + +def load_script(name): + spec = importlib.util.spec_from_file_location( + f"model_sky_{name}", HERE / f"{name}.py" + ) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def test_preview_rejects_output_inside_guide(tmp_path, monkeypatch, capsys): + preview = load_script("preview") + repo = tmp_path / "repo" + output = repo / "docs/guide/local-preview" + output.mkdir(parents=True) + monkeypatch.setattr(preview, "REPO", repo) + monkeypatch.setattr( + sys, + "argv", + ["preview.py", "--executed", "unused.ipynb", "--output", str(output)], + ) + with pytest.raises(SystemExit) as exc: + preview.main() + assert exc.value.code == 2 + assert "outside the guide source" in capsys.readouterr().err + assert list(output.iterdir()) == [] + + +def test_stalled_notebook_times_out_and_stops_kernel(tmp_path, monkeypatch): + runner = load_script("run") + source = tmp_path / "source" + source.mkdir() + cells = [ + nbformat.v4.new_code_cell(f"{flag} = False") for flag in runner.FLAGS + ] + cells += [nbformat.v4.new_code_cell("import time; time.sleep(60)")] + cells += [nbformat.v4.new_code_cell("pass") for _ in range(17)] + nbformat.write( + nbformat.v4.new_notebook(cells=cells), source / "model-sky.ipynb" + ) + output = tmp_path / "output" + monkeypatch.setattr(runner, "HERE", source) + monkeypatch.setattr(sys, "argv", ["run.py", "--output", str(output)]) + # Isolate input preparation; notebook execution and cleanup remain real. + monkeypatch.setattr(runner, "sha256", lambda path: "unused") + monkeypatch.setattr( + runner, "shutil", SimpleNamespace(copy2=lambda *args: None) + ) + monkeypatch.setattr( + runner, + "subprocess", + SimpleNamespace(run=lambda *args, **kwargs: None), + ) + manager = runner.AsyncKernelManager(kernel_name="python3") + monkeypatch.setattr( + runner, "AsyncKernelManager", lambda **kwargs: manager + ) + client_class = runner.NotebookClient + + def short_timeout(notebook, **kwargs): + kwargs["timeout"] = 1 + return client_class(notebook, **kwargs) + + monkeypatch.setattr(runner, "NotebookClient", short_timeout) + with pytest.raises(CellTimeoutError): + runner.main() + assert not manager.has_kernel + executed = nbformat.read( + output / "model-sky.executed.ipynb", as_version=4 + ) + assert executed.cells[0].execution_count is not None + assert executed.cells[-1].execution_count is None diff --git a/examples/model-sky/tests/test_scene.py b/examples/model-sky/tests/test_scene.py index ad3b0815..f100013b 100644 --- a/examples/model-sky/tests/test_scene.py +++ b/examples/model-sky/tests/test_scene.py @@ -90,7 +90,9 @@ def test_geometric_transit_has_ingress_and_52_minute_duration(): assert np.all(np.diff(flux[(times > -24) & (times < -20)]) < 0) -def test_bundle_preserves_astrometry_and_keeps_truth_separate(tmp_path): +def test_bundle_preserves_astrometry_and_keeps_truth_separate( + tmp_path, monkeypatch +): calibration = tmp_path / "calibration" calibration.mkdir() wcs = WCS(naxis=2) @@ -145,3 +147,22 @@ def test_bundle_preserves_astrometry_and_keeps_truth_separate(tmp_path): assert np.all(exposure["variance"] > 0) assert set(np.unique(exposure["mask"])) <= {0, 1} assert prepare_bundle(calibration, output, config=config) == manifest + reference = output / manifest["files"]["reference_old"] + reference.write_bytes(reference.read_bytes() + b"changed") + with pytest.raises(ValueError, match="hash mismatch"): + prepare_bundle(calibration, output, config=config) + + import scene + + write_exposure = scene._write_exposure + + def fail_after_write(*args, **kwargs): + write_exposure(*args, **kwargs) + raise RuntimeError("interrupted regeneration") + + with monkeypatch.context() as patch: + patch.setattr(scene, "_write_exposure", fail_after_write) + with pytest.raises(RuntimeError, match="interrupted regeneration"): + prepare_bundle(calibration, output, config=config, force=True) + assert not (output / "bundle.json").exists() + assert prepare_bundle(calibration, output, config=config) == manifest diff --git a/examples/model-sky/tests/test_views.py b/examples/model-sky/tests/test_views.py index 68320a37..7162cd66 100644 --- a/examples/model-sky/tests/test_views.py +++ b/examples/model-sky/tests/test_views.py @@ -7,6 +7,7 @@ import sys from pathlib import Path +import numpy as np from bokeh.io import notebook, showing from bokeh.io.state import State from bokeh.layouts import column @@ -15,7 +16,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1])) from notebook_style import show_dark # noqa: E402 -from views import export_html # noqa: E402 +from views import export_html, transit_view # noqa: E402 def test_export_then_inline_display(tmp_path, monkeypatch): @@ -40,3 +41,32 @@ def test_export_then_inline_display(tmp_path, monkeypatch): show_dark(layout) assert any("text/html" in output for output in displayed) assert any("application/javascript" in output for output in displayed) + + +def test_transit_image_selection_ignores_the_fitted_linear_baseline(): + times = np.array([-60, -30, 0, 30, 60]) + component = np.array([1, 0.99, 0.98, 0.99, 1]) + model = (1 + 0.03 * times / 60) * component + differences = np.broadcast_to( + np.array([0, 2, -8, 5, 6])[:, None, None], (5, 3, 3) + ) + layout = transit_view( + times, + model, + np.full(5, 0.001), + model, + transit_model=component, + stamps=np.ones((5, 3, 3)), + difference_stamps=differences, + ) + coadd = next( + p + for p in layout.select({"type": figure}) + if p.title.text == "In-transit − baseline mean" + ) + image = next( + r.data_source.data["image"][0] + for r in coadd.renderers + if "image" in getattr(r.data_source, "data", {}) + ) + np.testing.assert_array_equal(image, np.full((3, 3), -11)) diff --git a/examples/model-sky/views.py b/examples/model-sky/views.py index bbc3e8fa..0054505d 100644 --- a/examples/model-sky/views.py +++ b/examples/model-sky/views.py @@ -675,6 +675,7 @@ def transit_view( flux_error, model, *, + transit_model, stamps, difference_stamps, valid=None, @@ -690,17 +691,21 @@ def transit_view( Arrays share cadence order and units. Excluded points remain visible but are excluded from both means. ``model`` is the supplied fit, - not a fit performed here. Transit membership is defined by - the model lying below half-depth; baseline uses less than 5% of depth. + not a fit performed here. ``transit_model`` is its baseline-normalized + transit component: membership uses half-depth and the baseline uses + less than 5% of depth. The full model remains the light-curve line. """ times, flux, error, model = map( lambda a: np.asarray(a, dtype=float), (times_minutes, flux, flux_error, model), ) n = len(times) + transit_model = np.asarray(transit_model, dtype=float) stamps = np.asarray(stamps, dtype=np.float32) differences = np.asarray(difference_stamps, dtype=np.float32) - if n < 2 or any(a.shape != (n,) for a in (times, flux, error, model)): + if n < 2 or any( + a.shape != (n,) for a in (times, flux, error, model, transit_model) + ): raise ValueError( "Light-curve arrays must be 1D with at least two cadences." ) @@ -724,16 +729,20 @@ def transit_view( if valid.shape != (n,): raise ValueError("valid must have one Boolean per cadence.") usable = ( - valid & np.isfinite(flux) & np.isfinite(error) & np.isfinite(model) + valid + & np.isfinite(flux) + & np.isfinite(error) + & np.isfinite(model) + & np.isfinite(transit_model) ) - model_finite = model[np.isfinite(model)] + model_finite = transit_model[np.isfinite(transit_model)] if not model_finite.size: raise ValueError( "The supplied model needs at least one finite value." ) floor, ceiling = np.min(model_finite), np.max(model_finite) - in_transit = usable & (model < (floor + ceiling) / 2) - baseline = usable & (model > ceiling - 0.05 * (ceiling - floor)) + in_transit = usable & (transit_model < (floor + ceiling) / 2) + baseline = usable & (transit_model > ceiling - 0.05 * (ceiling - floor)) coadd = ( np.nanmean(differences[in_transit], axis=0) - np.nanmean(differences[baseline], axis=0) @@ -1041,7 +1050,7 @@ def export_html( path.parent.mkdir(parents=True, exist_ok=True) references = Path( sources or Path(__file__).with_name("sources.md") - ).read_text() + ).read_text(encoding="utf-8") footer = Div( text=( "
Sources and further reading" diff --git a/examples/model-sky/workshop.py b/examples/model-sky/workshop.py index d48c19a2..d4161d08 100644 --- a/examples/model-sky/workshop.py +++ b/examples/model-sky/workshop.py @@ -171,6 +171,7 @@ def export_views(output, manifest, trail, motion, transit, *, png=False): transit["flux"], transit["flux_error"], transit["fit"]["model"], + transit_model=transit["fit"]["transit_model"], stamps=transit["stamps"], difference_stamps=transit["difference_stamps"], valid=transit["valid"], From 4ebbafbaa154698edfb13ee5fe984a3e1aab1243 Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Mon, 16 Nov 2026 12:21:39 -0800 Subject: [PATCH 3/3] Compare recovered bundle science independently of FITS timestamps Signed-off-by: Trent Nelson --- examples/model-sky/tests/test_scene.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/examples/model-sky/tests/test_scene.py b/examples/model-sky/tests/test_scene.py index f100013b..738e6929 100644 --- a/examples/model-sky/tests/test_scene.py +++ b/examples/model-sky/tests/test_scene.py @@ -165,4 +165,13 @@ def fail_after_write(*args, **kwargs): with pytest.raises(RuntimeError, match="interrupted regeneration"): prepare_bundle(calibration, output, config=config, force=True) assert not (output / "bundle.json").exists() - assert prepare_bundle(calibration, output, config=config) == manifest + recovered = prepare_bundle(calibration, output, config=config) + assert recovered["fingerprint"] == manifest["fingerprint"] + recovered_old = load_exposure( + output / recovered["files"]["reference_old"] + ) + for plane in ("science", "variance", "mask"): + np.testing.assert_array_equal(recovered_old[plane], old[plane]) + for relative, expected in recovered["sha256"].items(): + assert scene.sha256(output / relative) == expected + assert prepare_bundle(calibration, output, config=config) == recovered