Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -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
11 changes: 11 additions & 0 deletions examples/model-sky/.gitignore
Original file line number Diff line number Diff line change
@@ -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/
114 changes: 114 additions & 0 deletions examples/model-sky/PUBLISHING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# 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.
94 changes: 94 additions & 0 deletions examples/model-sky/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# 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.
31 changes: 31 additions & 0 deletions examples/model-sky/assets/guide-head.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
<script>
// Quarto's navigation and themes use storage. When browser policy blocks it,
// retain current-page interactions without claiming to persist preferences.
(() => {
try {
const storage = window.localStorage;
const probe = `model-sky-storage-check-${Math.random()}`;
storage.setItem(probe, "1");
storage.removeItem(probe);
storage.getItem("quarto-color-scheme");
return;
} catch (_) {
const values = new Map();
const memory = {
get length() { return values.size; },
key(index) { return [...values.keys()][index] ?? null; },
getItem(key) { return values.get(String(key)) ?? null; },
setItem(key, value) { values.set(String(key), String(value)); },
removeItem(key) { values.delete(String(key)); },
clear() { values.clear(); },
};
try {
Object.defineProperty(window, "localStorage", {
configurable: true, enumerable: true, value: memory,
});
} catch (_) { /* A separate script may have locked the global property. */ }
}
})();
</script>
3 changes: 3 additions & 0 deletions examples/model-sky/assets/guide-include.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
<script src="assets/model-sky/guide.js"></script>
112 changes: 112 additions & 0 deletions examples/model-sky/assets/guide.css
Original file line number Diff line number Diff line change
@@ -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; }
}
Loading
Loading