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: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,6 @@

# Keep this small, reviewed, output-free walkthrough readable in code reviews.
/examples/imaging-pipeline/run_imaging_pipeline.ipynb -filter diff merge text eol=lf

# Model Alerts is reviewed and committed without notebook outputs.
/examples/model-alerts/model-alerts.ipynb -filter diff merge text eol=lf
119 changes: 119 additions & 0 deletions examples/model-alerts/PUBLISHING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Export and future publication

Model Alerts is source plus a local static export workflow. Merging this
example alone does not add it to versioned GitHub Pages. No public application
server is needed: future hosting must consume the static artifacts only.

## Execute, verify and render

1. Select a complete source revision and preserve it throughout execution.
Provision a CUDA 13 environment as described in [README.md](README.md).
Run `run.py --profile full-reference` into a new directory outside Git,
using the shared GPU lock. Keep earlier failed/invalidated runs intact.
2. Inspect `execution.json`, `study/freeze.json`, `study/report.json` and
scientific control outputs. Verify every `source_sha256` against the
matching example source, and every `output_sha256` against the named
artifact using SHA-256. The executed notebook must contain every cell,
warning and figure with no execution errors. A quick-smoke receipt is API
evidence only, even when execution succeeds.
3. Use a separate CPU documentation environment with current Quarto, following
[the guide build instructions](../../docs/README.md). Install this example's
optional requirements and the repository's optional developer tools there.
Export into another new directory:

```sh
/path/to/docs-env/bin/python examples/model-alerts/preview.py \
--executed /absolute/path/full-reference/model-alerts.executed.ipynb \
--output /absolute/path/new-model-alerts-render \
--source-ref PUSHED_SOURCE_COMMIT
```

Replace `PUSHED_SOURCE_COMMIT` with the exact reviewed source SHA. The
renderer verifies executed/source hashes before reusing GPU cell outputs,
executes the ordinary CPU guide chapters, applies the current developer
version postprocessor and runs `docs-check`. Includes remain build inputs
outside published resource trees. No central publisher is changed.
`--allow-smoke` enables an explicitly labeled engineering preview only.
4. Serve only the rendered book, never its parent containing data/weights:

```sh
python -m http.server 8797 --bind 0.0.0.0 \
--directory /absolute/path/new-model-alerts-render/guide/_book
```

Open `http://localhost:8797/model-alerts.html`. Verify every control, term
hover/focus/touch/Escape behavior, equations and light/dark theme. Check
exact pixel values and unchanged numerical data under display changes.
Repeat with scientific runtime network access blocked, zero WebSockets,
`file://` use, mobile/desktop and DPR 1/2, and a nested
`/cuPhoton/main/model-alerts.html` route. Verify visible GitHub source links.
5. Audit final HTML and public receipts for private paths, account/machine
identifiers, unintended remote dependencies and restricted assets. Measure
source/artifact bytes and inspect arrays for avoidable duplication before
considering any precision change. Do not ship training data or weights
inside HTML.

## Package reviewed static assets

After qualification, package the entire book so navigation and downloads work:

```sh
export CUPHOTON_MODEL_ALERTS_EXPORT=/absolute/path/reviewed-export
mkdir "$CUPHOTON_MODEL_ALERTS_EXPORT"
tar -czf "$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts-guide.tar.gz" \
-C /absolute/path/model-alerts-render/guide/_book .
cp /absolute/path/full-reference/model-alerts.executed.ipynb \
"$CUPHOTON_MODEL_ALERTS_EXPORT/"
cp /absolute/path/full-reference/execution.json \
"$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts-execution.json"
cp /absolute/path/full-reference/model-alerts-source.zip \
"$CUPHOTON_MODEL_ALERTS_EXPORT/"
(
cd "$CUPHOTON_MODEL_ALERTS_EXPORT"
sha256sum model-alerts-guide.tar.gz model-alerts.executed.ipynb \
model-alerts-execution.json model-alerts-source.zip > model-alerts-SHA256SUMS
)
```

Verify checksums after copying. An archive extracted locally must still open
without an application server. Python's static HTTP server is optional.

The following is a **future upload action**, after separate authorization and
review of a matching existing Release tag:

```sh
gh release upload RELEASE_TAG --repo NVIDIA/cuPhoton \
"$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts-guide.tar.gz" \
"$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts.executed.ipynb" \
"$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts-execution.json" \
"$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts-source.zip" \
"$CUPHOTON_MODEL_ALERTS_EXPORT/model-alerts-SHA256SUMS"
```

This task does not upload assets, merge, deploy or publish a software release.
Keep existing Release assets intact; avoid replacement flags.

## Versioned Pages integration gap

The current CPU builder executes ordinary chapters with global `--execute`.
It needs a receipt-verified pre-executed GPU notebook path, while continuing
normal CPU execution. The local preview demonstrates staging that distinction;
it does not change automatic publication.

A future integration must stage this chapter only for revisions containing
its source, rewrite source links to the selected tag/ref, and pass all current
version postprocessing and documentation checks. Main and eligible release
versions need durable checksummed storage for the large static export and its
companions. The current publisher commits rendered files to `gh-pages`;
Release-asset upload by itself does not prevent that growth. Restore verified
static assets into temporary deployment trees rather than silently committing
large HTML or falling back to a mutable latest release.

Qualify a main build, an eligible release and an older release without this
example. Check navigation/search/version switching, missing or corrupted
assets, source links and preservation of existing versions. Expected future
routes are `main/model-alerts.html` and `vX.Y.Z/model-alerts.html` beneath the
cuPhoton Pages site. Normal publication/deployment remains a separate action.
147 changes: 147 additions & 0 deletions examples/model-alerts/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Model Alerts — Which changes deserve attention?

Generate independent reference/search exposures, detect positive xPois
residuals, and train fresh native xScan pair/triplet classifiers. Follow the
notebook from electron counts through labels, grouped splits, operating
points, mistakes and a human review queue. Expanded science panels derive
the assumptions; terminology links support hover, keyboard focus and touch.

Every image, source, detector defect and noise realization is generated from
declared analytic models. No survey imagery, calibration products, old demo
datasets or pretrained checkpoints are inputs. The classifier results apply
to this modeled population. They do not establish survey performance or
calibrated astrophysical probabilities.

## Execute in a clean environment

Use Linux, Python 3.12 or newer supported by cuPhoton, and a CUDA 13-capable
GPU with its driver. From a complete cuPhoton source checkout:

```sh
uv venv --python 3.12 .venv-model-alerts
uv pip install --python .venv-model-alerts/bin/python -e '.[gpu]'
uv pip install --python .venv-model-alerts/bin/python \
-r examples/model-alerts/requirements.txt
```

Use the appropriate CUDA 13 PyTorch index for your platform if it is needed
by your package installation. Keep these example dependencies optional;
ordinary cuPhoton installations do not install them. Bokeh, Jupyter and
Matplotlib are used for visualization/execution; Beautiful Soup supports the
repository's documentation checks. No third-party source is vendored.

Choose an output directory outside the checkout that does not yet exist.
Every session sharing a GPU must use the same advisory lock. This process
retains that lock for the complete scientific workload:

```sh
export CUPHOTON_MODEL_ALERTS_GPU_LOCK=/absolute/path/shared/gpu0.lock
.venv-model-alerts/bin/python examples/model-alerts/run.py \
--profile quick-smoke --output /absolute/path/new-api-smoke \
--gpu-lock "$CUPHOTON_MODEL_ALERTS_GPU_LOCK"
.venv-model-alerts/bin/python examples/model-alerts/run.py \
--profile full-reference --output /absolute/path/new-full-reference \
--gpu-lock "$CUPHOTON_MODEL_ALERTS_GPU_LOCK"
```

Create the shared lock's parent directory first. Check actual GPU ownership
as well as the lock before starting; do not interrupt another workload.
Provision dependencies before blocking network access for scientific
execution. Generation, training and inference make no network requests.

Quick smoke uses small field counts and one training epoch. It exercises the
APIs and export path and cannot substantiate scientific performance. Full
reference starts with 180 training and 60 validation fields, reserves 60 test
fields, and adds 60 shifted fields. Every field has three epochs. Development
counts double if the primary validation field-bootstrap half-width exceeds
five percentage points. All reference models complete 12 training epochs;
minimum validation loss selects the checkpoint. Validation fields are reused
for checkpoint and threshold selection, so the precision rule is a conditional
development heuristic. Runtime and artifact sizes follow the actual counts.

The runner snapshots source, executes a fresh notebook kernel and preserves
stdout, warnings and figures. It writes `model-alerts.executed.ipynb`,
`model-alerts-source.zip`, `execution.json`, and the separate `study/` data,
weights and scientific receipts. The committed notebook stays output-free.
`CUPHOTON_MODEL_ALERTS_OUTPUT` and `CUPHOTON_MODEL_ALERTS_PROFILE` are set by the
runner for its kernel; a direct notebook session must set them and the shared
lock explicitly.

## Scientific controls and frozen evaluation

The ontology precedes training. Unmatched detections stay negative; movers
are separate astrophysical challenges. Ambiguous associations remain counted
in coverage, separately from overlapping causes. Injection retention separates
losses from detection, eligibility exclusions and classification. Training excludes those two special categories from primary
binary fitting and evaluation states the same coverage boundary.

Native xScan validation and label-provenance checks guard independent fields.
All shared template noise, persistent defects and epochs remain together.
Model inputs contain only measured image channels or explicitly enabled
measured xFit features. Scaling is fitted on training data. Pair/triplet use
the same candidate pool and three initialization seeds. Controls include
SNR-only and measured-statistics baselines, one fixed training-label
permutation, nested development learning curves and a rejected invalid split.
xFit fusion uses native exact-candidate/stamp correspondence checks and
reports failed-fit coverage. Raw nonfinite and repeated-extreme fractions
are measured by binary class to check trivial generator signatures.

Each model/seed uses the highest inclusive score threshold achieving at least
95% validation recall, including tied scores. The final endpoint is test FPR
at that frozen threshold; achieved test and shift recall are reported
separately. Field bootstrap preserves epoch dependence and pairs comparisons
on the same fields. Seed outcomes are shown individually. Both evaluation
populations include family, SNR and overlapping-cause breakdowns. Local
registration offsets vary by star; brightening hosts are randomized among
non-mismatch stars. The development receipt counts bipolar registration
residuals. All generator mixture amplitudes are declared in `Design`.

`study/freeze.json` precedes reserved-field generation. Never retune after
unblinding. If a bug invalidates final evaluation, retain that attempt and set
fresh disjoint `CUPHOTON_MODEL_ALERTS_TEST_SEED_BASE` and
`CUPHOTON_MODEL_ALERTS_SHIFT_SEED_BASE` blocks for a new full reference. Smoke
uses different default blocks from the full reference. Unexpected permutation
predictability stops full execution before freeze for diagnosis.

## Static interactions

| Live feature | Static equivalent or local operation |
| --- | --- |
| Image panels, linked pan/zoom and tapped pixels | Reused xScan Bokeh image/inspector primitives with browser callbacks |
| Raw versus display transformations | Browser-only transforms; exact raw values retained |
| Candidate navigation and family/outcome filters | Saved deterministic gallery of at most 96 candidates |
| Score/SNR and failure inspection | Complete evaluation score plot and stratified failure gallery |
| Threshold and queue choices | Saved scores for all eligible evaluation candidates |
| Prevalence changes | Fixed-class-conditional-mixture projection from complete TPR/FPR |
| Annotation persistence | Optional local `cuphoton xscan review-bokeh --review-dir /path/to/generated-review` after preparing a queue from this generated dataset |
| Training, inference or new data | Local execution only; browser controls do not rerun them |

The gallery is selected by round-robin confusion category, SNR bin and family,
then candidate-ID order. Empty categories remain empty. Metrics and queue
projections use complete evaluation arrays, never gallery counts. The HTML
contains gallery pixels and evaluation statistics; full training arrays and
weights are separate artifacts.

The source reuses Model Sky's public notebook presentation code and the
existing xScan raw-comparison/Alard-Lupton display helpers. It does not read
live demo fixtures or open a Bokeh server. Existing server viewer behavior
is unchanged. See [PUBLISHING.md](PUBLISHING.md) for Quarto export, source/hash
verification, packaging and the future versioned Pages integration work.

## Check source and interactions

```sh
PYTHONPATH=src .venv-model-alerts/bin/python -m pytest \
examples/model-alerts/tests
CUPHOTON_MODEL_ALERTS_CHROMIUM=/absolute/path/to/chromium \
PYTHONPATH=src .venv-model-alerts/bin/python -m pytest \
examples/model-alerts/tests/test_static_browser.py
ruff check examples/model-alerts
```

The browser regression runs standalone HTML with network APIs blocked.
Complete qualification also covers the final rendered chapter on desktop and
mobile, themes, DPR, keyboard/touch, source links and a versioned static route.
31 changes: 31 additions & 0 deletions examples/model-alerts/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-alerts-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-alerts/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-alerts/guide.js"></script>
Loading
Loading