diff --git a/.gitattributes b/.gitattributes index 9b4730c3..11176343 100644 --- a/.gitattributes +++ b/.gitattributes @@ -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 + +# Original output-free Model Scene notebook. +/examples/model-scene/model-scene.ipynb -filter diff merge text eol=lf diff --git a/examples/model-scene/PUBLISHING.md b/examples/model-scene/PUBLISHING.md new file mode 100644 index 00000000..2ececa39 --- /dev/null +++ b/examples/model-scene/PUBLISHING.md @@ -0,0 +1,99 @@ + + + +# Publishing Model Scene + +The source notebook is output-free. The interactive HTML and numerical study +are generated artifacts kept outside Git. This example exports a local static +chapter inside the user guide; merging its source does not add it to the +automatically published versioned site. + +## Build a reviewable artifact + +1. Check out the intended committed source revision and keep it unchanged + through execution and rendering. Install that checkout's cuPhoton with + xImage and the optional example requirements, as described in README.md. +2. Execute the reference profile in a CUDA 13 environment, retaining the shared + GPU lock. Use a fresh destination outside the source checkout: + + ```sh + python examples/model-scene/run.py --profile reference --device cuda \ + --gpu-lock /path/shared-by-all-gpu-users/gpu0.lock \ + --output /path/new-scene-reference + ``` + +3. Check `execution.json`, `protocol.json`, `execution.log`, and the study + diagnostics. Verify source hashes against this checkout, protocol hashes + against the executed protocol, and artifact hashes against the actual files. + Inspect the independent-truth endpoints and calibration controls; a successful + process exit alone does not establish scientific fidelity. +4. In the CPU documentation environment, render the completed notebook with + `preview.py --executed ... --output ... --source-ref COMMITTED_PUSHED_REF`. + The command verifies input hashes and invokes the existing postprocessor + and snapshot checks. Normal CPU guide chapters execute; the GPU notebook + retains its saved outputs. Build include fragments stay outside the + published guide resource tree. +5. Test the chapter under `file://` and static HTTP, including a versioned + `/cuPhoton//` prefix. Check desktop/mobile, light/dark, keyboard, + touch, terminology definitions, all selectors, linked pixel values and + display scales. Block scientific runtime network access and verify that + there are no WebSocket connections. Audit the HTML and public receipt for + private paths and restricted material. Confirm GitHub source links resolve. + +## Package static files + +The complete `_book` directory retains guide navigation and source downloads. +The chapter embeds its plot resources; a local static web server is sufficient. +After verification, package the rendered directory and executed notebook: + +```sh +tar -czf /path/model-scene-guide.tar.gz \ + -C /path/new-scene-preview/guide/_book . +cp /path/new-scene-preview/guide/_book/source/model-scene.executed.ipynb \ + /path/model-scene.executed.ipynb +cp /path/new-scene-preview/guide/_book/source/model-scene-execution.json \ + /path/model-scene-execution.json +sha256sum /path/model-scene-guide.tar.gz \ + /path/model-scene.executed.ipynb /path/model-scene-execution.json \ + > /path/model-scene-SHA256SUMS +``` + +Use the sanitized exported notebook/receipt for public distribution. Retain raw +native workflow records privately when they contain machine-local paths. +Full repeated-trial arrays can be archived separately; the HTML contains selected +experiments and the complete summary diagnostics. Measure the archive and page +sizes before distribution. Preserve numeric precision and avoid embedding +repeated-trial arrays merely to make them accessible from a selector. + +Uploading assets is a separate future action. After approval, use an existing +GitHub Release whose tag contains the exact validated source: + +```sh +gh release upload RELEASE_TAG --repo NVIDIA/cuPhoton \ + /path/model-scene-guide.tar.gz /path/model-scene.executed.ipynb \ + /path/model-scene-execution.json /path/model-scene-SHA256SUMS +``` + +This uploads assets; it neither creates a software release nor updates Pages. +Preserve existing assets. No Release upload is part of this example's local +preview or PR workflow. + +## Versioned Pages integration still required + +The current CPU builder globally requests execution. It needs a verified way to +stage the pre-executed GPU notebook with matching source/protocol/dependency +receipts while continuing to execute the ordinary CPU chapters. The local +preview demonstrates that separation without changing the central publisher. + +The publisher also needs durable storage and restoration of large static +artifacts keyed to the exact source revision. A Release upload alone does not +make the publisher consume those assets. Main needs durable revision-keyed +artifacts too; expiring PR artifacts and a mutable latest-release fallback do +not satisfy source provenance. Keep rendered HTML out of `gh-pages` source +commits until that integration has an approved storage design. + +Before enabling automatic publication, validate main, a release that contains +Model Scene, and an older release without it. Verify source links, navigation, +search, version switching, artifact integrity and preservation of earlier +snapshots. Future `nvidia.github.io` hosting must consume static artifacts only. +No public Python or Bokeh server is available or required. diff --git a/examples/model-scene/README.md b/examples/model-scene/README.md new file mode 100644 index 00000000..fc638de1 --- /dev/null +++ b/examples/model-scene/README.md @@ -0,0 +1,129 @@ + + + +# Model Scene + +What can blurred exposures actually reveal? This notebook reconstructs a +static modeled scene with xImage, calibrates PSFs from separate modeled star +observations, and measures recovery against independent truth. Interactive +figures connect individual exposures with predictions and residuals. + +Every input comes from the analytic generator in this directory. The example +uses no survey images, calibration products, catalogs or downloaded fixtures. +The physical renderer integrates continuous Gaussian mixtures over detector +pixels. A separate discrete-operator control quantifies representation error. +A 96×96 fitting region provides context around the central 48×48 science +window. A separate compact-context case demonstrates halo contamination. +The experiment uses a zero-dither grid and makes no alignment qualification. + +## Execute + +Use a fresh Linux Python 3.12+ environment with CUDA 13 and a compatible NVIDIA +GPU. From a checkout of the exact cuPhoton revision being evaluated: + +```sh +python -m pip install -e '.[ximage]' +python -m pip install -r examples/model-scene/requirements.txt +python examples/model-scene/run.py --profile quick --device cuda \ + --gpu-lock /path/shared-by-all-gpu-users/gpu0.lock \ + --output /path/outside/git/new-scene-smoke +``` + +Pass the same advisory lock path to other cooperating GPU workloads. The runner +retains that lock through the study and the fresh notebook kernel. Inspect GPU +use before launching; a process that ignores the advisory lock is not blocked +by it. The destination must be absent, including absent as a symbolic link. +The runner never overwrites an earlier execution. + +The quick profile exercises the bundle contracts, solver APIs, investigations +and plots with two trials and ten scene iterations. It substantiates no +scientific-performance claim. `--device cpu` provides an API smoke route. +The reference profile runs the frozen protocol, including at least 50 paired +science-noise realizations and 50 independent calibration draws: + +```sh +python examples/model-scene/run.py --profile reference --device cuda \ + --gpu-lock /path/shared-by-all-gpu-users/gpu0.lock \ + --output /path/outside/git/new-scene-reference +``` + +`protocol.json` records the measurement definitions and seed ranges. A reference +run refuses an unfrozen protocol or a change to its scientific source hashes. +The reproducible development sweep uses separate seeds and a catalog that shifts the two isolated stars by two pixels: + +```sh +python examples/model-scene/develop.py --device cuda \ + --gpu-lock /path/shared-by-all-gpu-users/gpu0.lock \ + --output /path/outside/git/new-scene-development +``` + +Development evidence determines the iteration budget before +test draws. The Huber threshold is declared in advance, not tuned by this sweep. +An invalidating scientific fix requires a new protocol revision +and fresh test seeds; retain the failed attempt and its receipt. + +The source notebook has no outputs, execution counts, attachments or datasets. +`run.py` creates a source copy, native workflow artifacts, numerical study, +execution log, executed notebook and an execution receipt. It records source, +protocol and output hashes, exact source revision and package versions. +`CUPHOTON_MODEL_SCENE_OUTPUT` locates those results for notebook execution. +The notebook preserves warnings and recorded outputs. Work offline after +installing dependencies; no data download is part of generation or execution. + +## Interpret the measurements + +The primary endpoint is fractional error of radius-three-pixel aperture flux +at a common 2.4-pixel Gaussian resolution. Compare each fixed aperture with +the identical aperture on target truth. Apertures include neighboring light; +they do not measure deblended total source flux. Per-source summaries retain +brightness and crowding labels. This is inference about the fixed modeled +catalog and independent noise draws, rather than a population calibration. + +The reference compares L2, Huber and a coadd on paired draws, then investigates +PSF-width errors, finite calibration, outliers, explicit masking, variance +rescaling, photon/read noise and a transient. Held-out frames test forward +predictions. Native coadd-relative metrics are secondary diagnostics. See the +notebook's derivations and caveats before interpreting a residual statistic +or a visually sharp feature. + +## Inspect a static export + +Use the CPU documentation environment and Quarto described in +[the documentation guide](../../docs/README.md) and +[developer tooling](../../dev/README.md): + +```sh +python examples/model-scene/preview.py \ + --executed /path/new-scene-reference/model-scene.executed.ipynb \ + --output /path/outside/git/new-scene-preview \ + --source-ref YOUR_PUSHED_SOURCE_REF \ + --controller-python /path/to/developer-env/bin/python +python -m http.server 8798 --bind 0.0.0.0 \ + --directory /path/new-scene-preview/guide/_book +``` + +Open `http://localhost:8798/model-scene.html`. The chapter embeds its JavaScript +and numeric data. Each experiment selector chooses saved results. It requires +no Python server callbacks, kernel, WebSocket, API or CDN. Individual standalone +chapter viewing also works with `file://`; guide navigation needs the rest of +the exported directory. Display-range changes retain the original pixel values. + +Use `--controller-python` when the developer tooling dependencies (including +Beautiful Soup) live in a separate environment from the CPU guide renderer. + +The preview verifies the execution receipt and source hashes, executes the +ordinary CPU guide chapters, preserves the completed GPU notebook outputs, +and invokes the current version postprocessor and snapshot checks. It does +not modify the central publisher. Source links must name a pushed ref. + +Run the numerical tests with `python -m pytest examples/model-scene/tests`. +Workflow controls additionally require the xImage dependencies. + +[Publishing instructions](PUBLISHING.md) describe packaging and the current +versioned-Pages integration gap. Opening or merging this source PR does not +publish the rendered chapter. + +The frozen scientific source was replayed with the development command above. +Its twelve rows agree numerically with the selection sweep. The external +`development-v2-replay/development.json` receipt has SHA-256 +`355ce588c2ccc039a1d1bbfe312576d9f4b53206c8e36e27c4c720e3a6304d6f`. diff --git a/examples/model-scene/assets/scene.css b/examples/model-scene/assets/scene.css new file mode 100644 index 00000000..b6fc14cb --- /dev/null +++ b/examples/model-scene/assets/scene.css @@ -0,0 +1,31 @@ +/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */ +/* SPDX-License-Identifier: Apache-2.0 */ +:root { --scene-accent:#247359; } +body.quarto-dark { color-scheme:dark; --scene-accent:#a6df36; } +body.quarto-light { color-scheme:light; } +main { line-height:1.65; min-width:0; } +.scene-term { color:var(--scene-accent); text-decoration:underline dotted; + cursor:help; border:0; background:none; font:inherit; padding:0; } +.scene-term:focus-visible { outline:2px solid currentColor; outline-offset:3px; } +#scene-definition { position:fixed; z-index:9999; max-width:min(27rem,90vw); + background:Canvas; color:CanvasText; border:1px solid currentColor; + padding:.8rem; border-radius:.4rem; box-shadow:0 4px 24px #0003; } +details.science { border-left:3px solid var(--scene-accent); padding:1rem; + margin:1.4rem 0; background:color-mix(in srgb, CanvasText 4%, Canvas); } +details.science summary { cursor:pointer; font-weight:600; } +.cell-output-display { max-width:100%; overflow-x:auto; } +@media(max-width:700px) { main { padding:.5rem; } } +.scene-pipeline { margin:1.5rem 0; padding:1rem; border:1px solid color-mix(in srgb, CanvasText 30%, Canvas); border-radius:.5rem; } +.scene-pipeline-preparation { display:flex; align-items:center; justify-content:center; gap:1rem; } +.scene-pipeline-node { display:flex; flex-direction:column; gap:.2rem; padding:.7rem 1rem; border:1px solid currentColor; border-radius:.35rem; } +.scene-pipeline-node strong { font-size:1.15em; } +.scene-pipeline-arrow { font-size:1.8em; } +.scene-pipeline-junction { text-align:center; padding:.8rem 0; border-bottom:1px solid currentColor; } +.scene-pipeline-branches { display:grid; grid-template-columns:1fr 1fr; gap:1rem; } +.scene-pipeline-branch { min-width:0; padding:1rem; border:1px solid color-mix(in srgb, CanvasText 30%, Canvas); border-radius:.4rem; } +.scene-pipeline-current { border:3px solid var(--scene-accent); background:color-mix(in srgb, var(--scene-accent) 8%, Canvas); } +.scene-pipeline-label { font-weight:700; margin-top:0; } +.scene-pipeline-current .scene-pipeline-label { color:var(--scene-accent); } +.scene-pipeline-connector { border-left:2px solid currentColor; margin-left:1rem; padding:.5rem .8rem; } +.scene-pipeline figcaption { margin-top:1rem; font-size:.9em; } +@media(max-width:700px) { .scene-pipeline-branches { grid-template-columns:1fr; } .scene-pipeline-preparation { flex-direction:column; } .scene-pipeline-arrow { transform:rotate(90deg); } } diff --git a/examples/model-scene/assets/scene.js b/examples/model-scene/assets/scene.js new file mode 100644 index 00000000..95fc3551 --- /dev/null +++ b/examples/model-scene/assets/scene.js @@ -0,0 +1,90 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +(() => { + function start() { + function themePlots() { + const dark = document.body.classList.contains('quarto-dark'); + const background = dark ? '#181b16' : '#ffffff'; + const text = dark ? '#e6eddf' : '#172b45'; + for (const doc of window.Bokeh?.documents ?? []) { + for (const model of doc.all_models.values()) { + if (model.type === 'Figure') { + model.background_fill_color = background; + model.border_fill_color = background; + } + if (model.type === 'Title') model.text_color = text; + if (model.type.endsWith('Axis')) { + model.axis_label_text_color = text; + model.major_label_text_color = text; + } + if (model.type === 'Legend') { + model.background_fill_color = background; + model.label_text_color = text; + } + if (model.type === 'ColorBar') { + model.background_fill_color = background; + model.major_label_text_color = text; + model.title_text_color = text; + } + } + } + } + new MutationObserver(themePlots).observe(document.body, + {attributes:true, attributeFilter:['class']}); + // Bokeh embeds initialize after DOM parsing; the load event follows them. + addEventListener('load', themePlots); + themePlots(); + document.querySelectorAll('.cell-output-display').forEach(region => { + if (region.querySelector('[data-root-id]')) { + region.tabIndex = 0; + region.setAttribute('aria-label', 'Interactive figure; arrow keys scroll this region'); + } + }); + const popup = document.createElement('div'); + popup.id = 'scene-definition'; popup.role = 'tooltip'; popup.hidden = true; + document.body.appendChild(popup); + let active = null; + function close() { + popup.hidden = true; + if (active) active.removeAttribute('aria-describedby'); + active = null; + } + function open(term) { + close(); active = term; + popup.textContent = term.dataset.definition; + term.setAttribute('aria-describedby', popup.id); popup.hidden = false; + const rect = term.getBoundingClientRect(); + popup.style.left = Math.max(8, Math.min(rect.left, + innerWidth - popup.offsetWidth - 8)) + 'px'; + const below = rect.bottom + 6; + const top = below + popup.offsetHeight <= innerHeight - 8 + ? below : rect.top - popup.offsetHeight - 6; + popup.style.top = Math.max(8, top) + 'px'; + } + document.querySelectorAll('.scene-term').forEach(term => { + let pointerWasOpen; + term.addEventListener('pointerdown', () => { pointerWasOpen = active === term; }); + term.addEventListener('mouseenter', () => open(term)); + term.addEventListener('focus', () => open(term)); + term.addEventListener('mouseleave', close); + term.addEventListener('blur', close); + term.addEventListener('click', event => { + event.stopPropagation(); + if (pointerWasOpen ?? active === term) close(); else open(term); + pointerWasOpen = undefined; + }); + }); + document.addEventListener('keydown', e => { if(e.key === 'Escape') close(); }); + document.addEventListener('click', close); + addEventListener('scroll', () => { + // Keyboard focus can scroll a term into view after its focus event. + if (active && document.activeElement === active) { + const rect = active.getBoundingClientRect(); + if (rect.bottom > 0 && rect.top < innerHeight) open(active); + else close(); + } else close(); + }, {passive:true}); + } + if (document.readyState === 'loading') + document.addEventListener('DOMContentLoaded', start); else start(); +})(); diff --git a/examples/model-scene/controls.py b/examples/model-scene/controls.py new file mode 100644 index 00000000..ab9011bb --- /dev/null +++ b/examples/model-scene/controls.py @@ -0,0 +1,148 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Workflow-level controls for units, weights and CPU/CUDA agreement.""" + +import numpy as np +from experiment import forward_prediction, reconstruct +from scene import generate + + +def numerical_controls(root, *, device="cpu"): + """Exercise actual workflow preprocessing and solvers on paired inputs.""" + root.mkdir(parents=True, exist_ok=False) + arrays, truth = generate(1901, development=True, matched=True) + + def fit(name, data, algorithm="l2", delta=2): + return reconstruct( + root, + data, + name=name, + device=device, + algorithm=algorithm, + iterations=30, + delta=delta, + )[0] + + baseline = fit("rates", arrays) + times = np.linspace(10, 40, 12) + counts = {key: value.copy() for key, value in arrays.items()} + counts["images"] *= times + counts["variances"] *= times**2 + counts["exp_times"] = times + normalized = fit("counts", counts) + np.testing.assert_allclose(normalized, baseline, rtol=1e-10, atol=1e-10) + scaled_variance = {key: value.copy() for key, value in arrays.items()} + scaled_variance["variances"] *= 4 + weighted = fit("variance-four", scaled_variance) + np.testing.assert_allclose( + weighted[7:-7, 7:-7], baseline[7:-7, 7:-7], rtol=1e-10, atol=1e-10 + ) + np.testing.assert_allclose( + forward_prediction(weighted, arrays["psfs"]), + forward_prediction(baseline, arrays["psfs"]), + rtol=1e-8, + atol=1e-8, + ) + robust_scaled = fit("robust-variance-four", scaled_variance, "rho") + robust_delta = fit("robust-delta-four", arrays, "rho", delta=4) + np.testing.assert_allclose( + robust_scaled[7:-7, 7:-7], + robust_delta[7:-7, 7:-7], + rtol=1e-10, + atol=1e-10, + ) + from measure import comparison_products + + common = comparison_products( + arrays, truth, {"base": baseline, "weighted": weighted} + ) + common_error = float(np.max(np.abs(common["base"] - common["weighted"]))) + np.testing.assert_allclose( + common["base"], common["weighted"], rtol=1e-10, atol=1e-10 + ) + return { + "science_window_variance_scale_max_abs": common_error, + "l2_variance_scale_roi_max_abs": float( + np.max(np.abs(weighted[7:-7, 7:-7] - baseline[7:-7, 7:-7])) + ), + "l2_variance_scale_prediction_max_abs": float( + np.max( + np.abs( + forward_prediction(weighted, arrays["psfs"]) + - forward_prediction(baseline, arrays["psfs"]) + ) + ) + ), + "huber_variance_delta_roi_max_abs": float( + np.max( + np.abs(robust_scaled[7:-7, 7:-7] - robust_delta[7:-7, 7:-7]) + ) + ), + "counts_rates_max_abs": float(np.max(np.abs(normalized - baseline))), + "l2_variance_scale_full_halo_max_abs": float( + np.max(np.abs(weighted - baseline)) + ), + "huber_variance_delta_full_halo_max_abs": float( + np.max(np.abs(robust_scaled - robust_delta)) + ), + } + + +def asymmetric_operator_control(root): + """Check torch preprocessing against asymmetric truth.""" + import torch + from scene import write_bundle + from scipy.signal import convolve2d + + from cuphoton.ximage.backends.torch_gpu_preprocess import ( + prepare_torch_reconstruction_inputs, + ) + from cuphoton.ximage.config import ReconstructionConfig + from cuphoton.ximage.data import load_ximage_bundle + + arrays, truth = generate(1902, development=True, matched=True) + psfs = arrays["psfs"].copy() + psfs[8, 10, 0, :] += 0.1 + psfs /= psfs.sum(axis=(0, 1), keepdims=True) + arrays["psfs"] = psfs + arrays["images"] = np.stack( + [ + convolve2d(truth["truth"], psfs[:, :, 0, i], mode="same") + for i in range(12) + ], + axis=-1, + )[None] + write_bundle(root, arrays) + config = ReconstructionConfig( + algorithm="l2", device="cpu", roi=dict(height=96, width=96) + ) + with load_ximage_bundle(root) as bundle: + prepared = prepare_torch_reconstruction_inputs( + bundle, + config, + device=torch.device("cpu"), + dtype=torch.float64, + psfs=psfs, + ) + latent = torch.tensor(truth["truth"][5:-5, 5:-5])[None, None] + predicted = torch.nn.functional.conv2d(latent, prepared.f) + np.testing.assert_allclose( + predicted.numpy(), prepared.y.numpy(), atol=1e-12, rtol=1e-12 + ) + wrong = torch.nn.functional.conv2d(latent, prepared.f.flip((-2, -1))) + transposed = torch.nn.functional.conv2d( + latent, prepared.f.transpose(-2, -1) + ) + permuted = torch.nn.functional.conv2d(latent, prepared.f.flip((0,))) + errors = { + "correct_max_abs": float((predicted - prepared.y).abs().max()), + "flipped_max_abs": float((wrong - prepared.y).abs().max()), + "transposed_max_abs": float((transposed - prepared.y).abs().max()), + "frame_permutation_max_abs": float( + (permuted - prepared.y).abs().max() + ), + } + assert min(errors[key] for key in errors if key != "correct_max_abs") > 1 + return errors diff --git a/examples/model-scene/develop.py b/examples/model-scene/develop.py new file mode 100644 index 00000000..bf511fb3 --- /dev/null +++ b/examples/model-scene/develop.py @@ -0,0 +1,101 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Reproduce the development iteration sweep before freezing.""" + +import argparse +import fcntl +import hashlib +import json +from pathlib import Path + +import numpy as np +from experiment import reconstruct +from measure import evaluate +from scene import generate + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--device", choices=["cpu", "cuda"], default="cpu") + parser.add_argument("--gpu-lock", type=Path, required=True) + parser.add_argument( + "--iterations", type=int, nargs="+", default=[25, 75, 150, 300] + ) + parser.add_argument( + "--seeds", type=int, nargs="+", default=[1005, 1006, 1007] + ) + args = parser.parse_args() + if args.output.exists() or args.output.is_symlink(): + parser.error("Use a fresh output destination") + args.output.mkdir(parents=True) + sources = { + p.name: hashlib.sha256(p.read_bytes()).hexdigest() + for p in Path(__file__).parent.glob("*.py") + } + rows = [] + with open(args.gpu_lock, "a") as lock: + if args.device == "cuda": + fcntl.flock(lock, fcntl.LOCK_EX) + import torch + + torch.set_num_threads(4) + for seed in args.seeds: + arrays, truth = generate(seed, development=True) + for iterations in args.iterations: + images = {} + for name, algorithm in [("l2", "l2"), ("huber", "rho")]: + image, _, _ = reconstruct( + args.output, + arrays, + name=f"{seed}-{iterations}-{name}", + algorithm=algorithm, + device=args.device, + iterations=iterations, + ) + images[name] = image + measured, products, _ = evaluate(arrays, truth, images) + rows.append( + dict( + seed=seed, + iterations=iterations, + results=measured, + ranges={ + name: [float(im.min()), float(im.max())] + for name, im in products.items() + }, + ) + ) + (args.output / "development.json").write_text( + json.dumps( + dict( + source_hashes=sources, + development_only=True, + rows=rows, + ), + indent=2, + ) + + "\n" + ) + print( + seed, + iterations, + { + name: float( + np.mean( + [ + abs(s["fractional_flux_error"]) + for s in result["sources"] + ] + ) + ) + for name, result in measured.items() + }, + flush=True, + ) + + +if __name__ == "__main__": + main() diff --git a/examples/model-scene/experiment.py b/examples/model-scene/experiment.py new file mode 100644 index 00000000..f2d09a50 --- /dev/null +++ b/examples/model-scene/experiment.py @@ -0,0 +1,168 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Visible workflow adapters; truth is used only by evaluation functions.""" + +from pathlib import Path + +import numpy as np +import yaml +from scene import TRAIN_FRAMES, pixel_gaussian, write_bundle +from scipy.signal import convolve2d + + +def reconstruct( + root, + arrays, + *, + name, + algorithm="l2", + masked=False, + device="cpu", + iterations=75, + delta=2.0, +): + """Fit eight frames and save artifacts and secondary diagnostics.""" + from cuphoton.ximage.data import load_ximage_bundle, validate_bundle + from cuphoton.ximage.evaluation import evaluate_reconstruction_run + from cuphoton.ximage.workflows import run_reconstruction + + root = Path(root) + bundle_path = root / f"{name}-bundle" + write_bundle(bundle_path, arrays) + with load_ximage_bundle(bundle_path) as bundle: + errors = validate_bundle(bundle) + if errors: + raise ValueError(errors) + config = { + "backend": "torch", + "device": device, + "dtype": "float64", + "algorithm": algorithm, + "data": { + "base": str(bundle_path.resolve()), + "exposure_indices": list(TRAIN_FRAMES), + }, + "output": {"root_dir": str((root / "runs").resolve()), "name": name}, + "roi": { + "height": arrays["images"].shape[1] - 24, + "width": arrays["images"].shape[2] - 24, + }, + "mask": {"mode": "provided" if masked else "none"}, + "padding": "VALID", + "srf": 1, + "max_iter": iterations, + "stop_tol": 1e-12, + "rho_loss": "huber", + "delta_rho_start": delta, + "delta_rho_end": delta, + } + config_path = root / f"{name}.yaml" + config_path.write_text(yaml.safe_dump(config)) + run = run_reconstruction(config_path) + secondary = evaluate_reconstruction_run( + run.run_dir, metrics_backend="cpu", write_artifacts=True + ) + image = np.load(run.run_dir / "artifacts/image.npy").squeeze() + return image, run, secondary + + +def calibrate( + root, *, seed=300, method="mm", device="cpu", target_override=None +): + """Measure separate calibration stars and solve reference PSFs. + + Calibration stars have known locations and flux 100,000 electrons. + Poisson counts and Gaussian read noise are independent of science noise. + These star stamps are the observations; analytic widths are never passed + to the calibration solver. Background is known and subtracted. Negative + noisy samples are clipped before unit-sum normalization; quantify this + processing bias against the perfect-kernel control. + """ + from cuphoton.ximage.workflows import run_psf_solve + + rng = np.random.default_rng(seed) + widths = np.linspace(0.9, 1.7, 12) + stars = np.stack( + [pixel_gaussian(15, 7, 7, width) for width in widths], axis=-1 + ) + counts = rng.poisson(stars * 100000) + rng.normal(0, 2, stars.shape) + measured = np.maximum(counts, 0) + measured /= measured.sum(axis=(0, 1), keepdims=True) + if target_override is not None: + measured = np.asarray(target_override, dtype=float).copy() + counts = measured * 100000 + measured /= measured.sum(axis=(0, 1), keepdims=True) + path = Path(root) / f"calibration-{method}" + # Loader requires only the explicitly requested PSF artifact here. + path.mkdir(parents=True, exist_ok=False) + np.save(path / "psfs.npy", measured[:, :, None, :]) + np.save(path / "star-counts.npy", counts) + config = { + "backend": "torch", + "device": device, + "dtype": "float64", + "method": method, + "data": {"base": str(path.resolve())}, + "output": { + "root_dir": str((Path(root) / "runs").resolve()), + "name": f"calibration-{method}", + }, + "sigma_g": 0.55, + "padding": "VALID", + "max_iter": 100, + "num_steps": 500, + "lr": 0.01, + } + cfg = Path(root) / f"calibration-{method}.yaml" + cfg.write_text(yaml.safe_dump(config)) + run = run_psf_solve(cfg) + return run, measured + + +def aperture_measurements(image, sources, *, origin=12, radius=3): + """Fixed circular-aperture flux, centroid and radial light profile. + + Flux includes neighbors inside the aperture and excludes known constant + background. Compare with the same aperture on the appropriate target + truth, rather than labeling this a deblended total source flux. Exclude + apertures less than radius+2 from the measurement boundary. + """ + y, x = np.indices(image.shape) + rows = [] + for source in sources: + cx, cy = source.x - origin, source.y - origin + if ( + min(cx, cy, image.shape[1] - 1 - cx, image.shape[0] - 1 - cy) + < radius + 2 + ): + continue + r = np.hypot(x - cx, y - cy) + light = (image - 2) * (r <= radius) + flux = light.sum() + rows.append( + { + "kind": source.kind, + "input_flux": source.flux, + "flux": float(flux), + "x": float((light * x).sum() / flux + origin), + "y": float((light * y).sum() / flux + origin), + "profile": [ + float((image - 2)[(r >= a) & (r < a + 1)].mean()) + for a in range(5) + ], + } + ) + return rows + + +def forward_prediction(image, psfs): + """Predict the valid interior using real surrounding pixels.""" + return np.stack( + [ + convolve2d(image, psfs[:, :, 0, i], mode="valid") + for i in range(12) + ], + axis=-1, + ) diff --git a/examples/model-scene/measure.py b/examples/model-scene/measure.py new file mode 100644 index 00000000..a86193a7 --- /dev/null +++ b/examples/model-scene/measure.py @@ -0,0 +1,259 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Declared evaluation protocol; never used by the reconstruction solver.""" + +import numpy as np +from experiment import aperture_measurements, forward_prediction +from scene import ( + HELDOUT_FRAMES, + TRAIN_FRAMES, + catalog, + render, + science_window, +) +from scipy.ndimage import gaussian_filter + +TARGET_SIGMA = 2.4 + + +def comparison_products(arrays, truth, reconstructions, reference_sigma=0.0): + """Bring all products to a Gaussian target broader than every input PSF. + + Coadd is an ordinary arithmetic mean. For its comparison version, blur + each constituent exposure to the common target before averaging. This + avoids treating the mixture of exposure PSFs as a single Gaussian. + Discrete Gaussian filtering approximates continuous smoothing; measure + its noiseless discrepancy explicitly rather than claiming exact equality. + """ + widths = truth["widths"][list(TRAIN_FRAMES)] + data = arrays["images"][0] + common_coadd = science_window( + np.mean( + [ + gaussian_filter( + data[..., TRAIN_FRAMES[i]], + np.sqrt(TARGET_SIGMA**2 - width**2), + mode="constant", + cval=2, + ) + for i, width in enumerate(widths) + ], + axis=0, + ) + ) + products = {"coadd": common_coadd} + for name, image in reconstructions.items(): + expected_size = arrays["images"].shape[1] - 10 + if image.shape != (expected_size, expected_size): + raise ValueError( + f"Unexpected VALID restoration shape {image.shape}" + ) + products[name] = science_window( + gaussian_filter( + image, + np.sqrt(TARGET_SIGMA**2 - reference_sigma**2), + mode="constant", + cval=2, + ) + ) + return products + + +def evaluate( + arrays, truth, reconstructions, *, development=None, reference_sigma=0.0 +): + """Compare apertures and frame predictions with independent truth.""" + if development is None: + development = truth.get("development", False) + sources = catalog(development, offset=truth["source_offset"]) + origin = truth["view_origin"] + target = science_window( + gaussian_filter(truth["truth"], TARGET_SIGMA, mode="constant", cval=2) + if truth.get("matched", False) + else render( + sources, sigma=TARGET_SIGMA, size=arrays["images"].shape[1] + ) + ) + if not truth.get("boundary_failure", False): + last_fit_pixel = arrays["images"].shape[1] - 13 + for source in sources: + margin = min( + source.x - 12, + source.y - 12, + last_fit_pixel - source.x, + last_fit_pixel - source.y, + ) + if margin < 13: + raise ValueError( + "Insufficient fitting context for blur and aperture" + ) + expected = aperture_measurements(target, sources, origin=origin) + products = comparison_products( + arrays, truth, reconstructions, reference_sigma=reference_sigma + ) + results = {} + for name, image in products.items(): + measured = aperture_measurements(image, sources, origin=origin) + errors = [] + for got, reference in zip(measured, expected, strict=True): + errors.append( + { + "kind": reference["kind"], + "input_flux": reference["input_flux"], + "fractional_flux_error": got["flux"] / reference["flux"] + - 1, + "centroid_error_px": float( + np.hypot( + got["x"] - reference["x"], + got["y"] - reference["y"], + ) + ), + "profile_error": ( + np.asarray(got["profile"]) - reference["profile"] + ).tolist(), + } + ) + blend = [row for row in measured if row["kind"] == "blend"] + source_blend = [ + source for source in sources if source.kind == "blend" + ] + separation = float( + np.hypot( + blend[0]["x"] - blend[1]["x"], blend[0]["y"] - blend[1]["y"] + ) + ) + intrinsic = float( + np.hypot( + source_blend[0].x - source_blend[1].x, + source_blend[0].y - source_blend[1].y, + ) + ) + results[name] = { + "sources": errors, + "blend_aperture_centroid_separation_px": separation, + "intrinsic_blend_separation_px": intrinsic, + "separation_error_px": separation - intrinsic, + "separation_estimator": "overlapping aperture centroid distance", + } + if name in reconstructions: + prediction = forward_prediction( + reconstructions[name], arrays["psfs"] + ) + full_residual = arrays["images"][0, 12:-12, 12:-12] - prediction + results[name]["context_prediction_mse_by_frame"] = np.mean( + full_residual**2, axis=(0, 1) + ).tolist() + residual = science_window(full_residual) + variance = science_window(arrays["variances"][0]) + results[name]["prediction_mse_by_frame"] = np.mean( + residual**2, axis=(0, 1) + ).tolist() + results[name]["standardized_residual_ms_by_frame"] = np.mean( + residual**2 / variance, axis=(0, 1) + ).tolist() + results[name]["heldout_mean_residual"] = float( + residual[..., list(HELDOUT_FRAMES)].mean() + ) + return results, products, target + + +def paired_summary(trials): + """Estimate uncertainty over independent realizations. + + Aggregate source classes within each realization first. + sources within a trial are not treated as independent replicates. + """ + summary = {} + for method in trials[0]: + summary[method] = {} + for kind in ("isolated", "blend", "extended"): + values = np.array( + [ + np.mean( + [ + source["fractional_flux_error"] + for source in trial[method]["sources"] + if source["kind"] == kind + ] + ) + for trial in trials + ] + ) + summary[method][kind] = { + "mean_fractional_bias": float(values.mean()), + "realization_scatter": float(values.std(ddof=1)), + "bias_standard_error": float( + values.std(ddof=1) / np.sqrt(len(values)) + ), + "n_independent_noise_realizations": len(values), + } + for method in trials[0]: + summary[method]["by_source"] = [] + for index, source in enumerate(trials[0][method]["sources"]): + errors = np.array( + [ + trial[method]["sources"][index]["fractional_flux_error"] + for trial in trials + ] + ) + standard_error = float(errors.std(ddof=1) / np.sqrt(len(errors))) + summary[method]["by_source"].append( + { + "kind": source["kind"], + "input_flux": source["input_flux"], + "mean_fractional_bias": float(errors.mean()), + "scatter": float(errors.std(ddof=1)), + "bias_standard_error": standard_error, + "approx_80pct_power_detectable_bias": 2.8 + * standard_error, + } + ) + for method in ("l2", "huber"): + summary[method]["forward_prediction"] = {} + if "standardized_residual_ms_by_frame" in trials[0][method]: + for label, indices in ( + ("fitted", TRAIN_FRAMES), + ("heldout", HELDOUT_FRAMES), + ): + values = np.array( + [ + np.mean( + np.asarray( + t[method]["standardized_residual_ms_by_frame"] + )[list(indices)] + ) + for t in trials + ] + ) + summary[method]["forward_prediction"][label] = { + "mean_standardized_residual_ms": float(values.mean()), + "standard_error": float( + values.std(ddof=1) / np.sqrt(len(values)) + ), + } + differences = np.array( + [ + np.mean( + [ + s["fractional_flux_error"] + for s in trial[method]["sources"] + ] + ) + - np.mean( + [ + s["fractional_flux_error"] + for s in trial["coadd"]["sources"] + ] + ) + for trial in trials + ] + ) + summary[method]["paired_difference_vs_coadd"] = { + "mean": float(differences.mean()), + "standard_error": float( + differences.std(ddof=1) / np.sqrt(len(differences)) + ), + } + return summary diff --git a/examples/model-scene/model-scene.ipynb b/examples/model-scene/model-scene.ipynb new file mode 100644 index 00000000..ccc0af51 --- /dev/null +++ b/examples/model-scene/model-scene.ipynb @@ -0,0 +1,629 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "title: \"Model Scene\"\n", + "subtitle: \"What can blurred exposures actually reveal?\"\n", + "format:\n", + " html:\n", + " embed-resources: true\n", + " html-math-method: mathml\n", + " toc: true\n", + " code-fold: true\n", + " css: assets/scene.css\n", + "execute:\n", + " echo: true\n", + "---\n", + "\n", + "\n", + "\n", + "\n", + "This notebook exercises **xImage (`cuphoton.ximage`)**, cuPhoton's component for\n", + "reconstructing a common static scene from registered exposures. We also use\n", + "its separate PSF-calibration workflow to estimate the blur of each exposure.\n", + "\n", + "
\n", + "
\n", + "
xDataReaderRead FITS pixels
\n", + "\u2192\n", + "
xRepRegister images on a common grid
\n", + "
\n", + "

Registered exposures: choose the scientific task

\n", + "
\n", + "
\n", + "

This notebook \u00b7 Model Scene

\n", + "
xImageInfer one static scene from many exposuresCalibrate PSFs in a separate solve
\n", + "

Common-scene image, forward predictions and measurement checks

\n", + "
\n", + "
\n", + "

Model Sky / Model Alerts

\n", + "
xPoisMatch images and subtract
\n", + "

Then detect candidates and extract cutouts

\n", + "
xScan \u00b7 Model AlertsScore candidates for review
\n", + "

xFit \u00b7 Model Sky measures source or residual shapes. Model Alerts also investigates these measurements as optional classifier features.

\n", + "
\n", + "
\n", + "
Optical components within cuPhoton. The branches answer different questions; applications connect stages with suitable data adapters. Each example exercises the components listed below.
\n", + "
\n", + "\n", + "Model Scene starts with generated, already registered arrays, supplied noise\n", + "variances and per-exposure PSFs. The FITS-reading and registration boxes show\n", + "where xImage fits in a broader workflow. A reconstructed scene could become a\n", + "reference for subtraction, but its effective PSF and output uncertainty need\n", + "qualification before use with xPois. See the\n", + "[component architecture](https://github.com/NVIDIA/cuPhoton/blob/main/docs/architecture.md#how-the-science-components-fit-together)\n", + "for the data contracts between stages.\n", + "\n", + "These three examples use independently modeled inputs and can be read separately:\n", + "\n", + "| Example | Scientific question | cuPhoton components exercised |\n", + "| --- | --- | --- |\n", + "| [Model Sky](https://github.com/NVIDIA/cuPhoton/blob/codex/model-sky-guide-preview/examples/model-sky/model-sky.ipynb) ([PR #198](https://github.com/NVIDIA/cuPhoton/pull/198)) | How do masking, alignment and source measurements reveal motion and a modeled transit? | xRep, xPois, xFit |\n", + "| **Model Scene (here)** | What can blurred exposures reveal about one static scene, and how do wrong assumptions bias it? | **xImage:** reconstruction and separate PSF calibration |\n", + "| [Model Alerts](https://github.com/NVIDIA/cuPhoton/blob/codex/model-alerts-20261115/examples/model-alerts/model-alerts.ipynb) ([PR #200](https://github.com/NVIDIA/cuPhoton/pull/200)) | Which detected positive changes deserve attention, and how does a trained classifier fail? | xPois, xScan; an additional xFit feature investigation |\n", + "\n", + "A sharp-looking image can give a biased measurement. Here we reconstruct one\n", + "static modeled field from eight blurred exposures and ask whether the result\n", + "predicts four exposures that the solver never saw. We measure flux against\n", + "independent modeled truth, then deliberately break the PSF, noise and static-scene\n", + "assumptions. Every pixel comes from the analytic models distributed with this\n", + "example. No astronomical imagery, survey calibration, or downloaded catalog is used.\n", + "\n", + "[Notebook source on GitHub](https://github.com/NVIDIA/cuPhoton/blob/main/examples/model-scene/model-scene.ipynb)\n", + "\n", + "The full reference contains at least 50 independent noise realizations, with\n", + "identical draws shared between methods. A quick run exercises the APIs and\n", + "plots; its small sample supports no performance conclusion. All HTML selectors\n", + "choose saved results. They do not rerun a solver." + ], + "id": "scene-000" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## A scene, a detector, and a unit\n", + "\n", + "The contains two isolated stars, a close pair, and two extended Gaussian galaxies. Each source has a declared integrated flux, position and intrinsic width. A uniform background contributes two electrons per pixel per unit exposure. The stars have a small finite width of 0.22 pixel; their fine structure is deliberately undersampled.\n", + "\n", + " matters when light changes appreciably within a pixel. Our physical renderer integrates continuous Gaussians over square pixels using normal-distribution CDF differences. Coordinates name pixel centers, and pixel edges lie half a pixel away. Flux units are electrons per unit exposure. Variance has the square of those units. All principal exposures have duration one, so counts and rates have the same numeric values.\n", + "\n", + "
Science Explanation: Continuous truth and discrete inference\n", + "\n", + "For a Gaussian source of intrinsic width $s$ blurred by a Gaussian PSF of\n", + "width $p$, the continuous width is $\\sqrt{s^2+p^2}$. The integral of a unit\n", + "one-dimensional Gaussian over pixel $j$ is\n", + "\n", + "$$P_j=\\Phi((j+1/2-\\mu)/\\sigma)-\\Phi((j-1/2-\\mu)/\\sigma).$$\n", + "\n", + "The two-dimensional integral is the product of the two axis integrals. Source\n", + "flux multiplies this unit integral. Finite-stamp losses remain visible; we do\n", + "not renormalize each source into the image. The renderer uses no xImage\n", + "convolution, torch operation or PSF helper. This independence exposes model\n", + "representation errors that a shared generator and solver could conceal.\n", + "\n", + "
\n", + "The fixed catalog samples one on-grid pixel phase. Noise repetitions do not\n", + "qualify other subpixel phases or a general source population.\n" + ], + "id": "scene-001" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "import json, os\n", + "from pathlib import Path\n", + "import numpy as np\n", + "from bokeh.io import output_notebook, show\n", + "from bokeh.resources import INLINE\n", + "from IPython.display import display, HTML\n", + "from cuphoton import __version__\n", + "from presentation import products, exposures, diagnostics, calibration_diagnostics\n", + "from scene import catalog\n", + "ROOT = Path(os.environ.get(\"CUPHOTON_MODEL_SCENE_OUTPUT\", \"results\"))\n", + "STUDY = ROOT / \"study\"\n", + "output_notebook(resources=INLINE, hide_banner=True)\n", + "print(\"cuPhoton\", __version__)\n", + "print(\"Profile:\", json.loads((ROOT / \"execution-profile.json\").read_text()))\n", + "development = json.loads((ROOT / \"execution-profile.json\").read_text())[\"profile\"] == \"quick\"\n", + "for source in catalog(development=development):\n", + " print(source)" + ], + "outputs": [], + "execution_count": null, + "id": "scene-002" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What an exposure measures\n", + "\n", + " describes how source light spreads across neighboring pixels. Twelve exposures have widths from 0.9 to 1.7 pixels and independent noise. They share a . This experiment tests neither nor .\n", + "\n", + "In the main case, has exactly known four. The physical generator performs continuous convolution before pixel integration. xImage applies finite, sampled kernels to a discrete latent image. Those operators differ slightly, especially for undersampled stars. The matched-operator control isolates that discrepancy by generating observations with a separate SciPy discrete convolution.\n", + "\n", + "
Science Explanation: The forward model\n", + "\n", + "For exposure $e$ and pixel $i$, the inference model is\n", + "\n", + "$$y_{ei}=(H_e x)_i+n_{ei},\\qquad n_{ei}\\sim\\mathcal N(0,v_{ei}).$$\n", + "\n", + "Here $x$ includes the known constant background, $H_e$ denotes the supplied\n", + "fixed PSF convolution, and the independent variances $v_{ei}$ are positive.\n", + "A symmetric Gaussian PSF simplifies the teaching field; separate asymmetric\n", + "operator controls are needed to detect a kernel flip or transpose. Four\n", + "held-out frames test a different blur of the same scene. Their noise is\n", + "independent, although their comes from the fitted image.\n", + "\n", + "
" + ], + "id": "scene-003" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Read the array contract before fitting\n", + "\n", + "Images, variances, masks and background use `(batch, y, x, frame)`. PSFs use `(kernel_y, kernel_x, channel, frame)`. The singleton batch and channel axes have different meanings. A transpose that preserves array rank can still change the science.\n", + "\n", + "Masks are boolean: **True means good**. The outlier generator records which pixels it contaminated, and the explicit-mask investigation uses that record. This is an idealized quality flag, not a claim that a detector would identify all outliers. The example rejects nonfinite or nonpositive variances before starting a fit. Exposure divides intensity by time and variance by time squared, exactly once. Counts-versus-rates controls exercise the actual workflow preprocessing." + ], + "id": "scene-004" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.ximage.data import load_ximage_bundle, validate_bundle\n", + "with load_ximage_bundle(STUDY / \"trial-000/l2-bundle\") as bundle:\n", + " print(\"Bundle validation:\", validate_bundle(bundle))\n", + " print(\"Images:\", bundle.images.shape, \"PSFs:\", bundle.psfs.shape)\n", + " print(\"Good-mask dtype:\", bundle.masks.dtype)\n", + " assert np.all(np.isfinite(bundle.variances))\n", + " assert np.all(bundle.variances > 0)" + ], + "outputs": [], + "execution_count": null, + "id": "scene-005" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Build the ordinary coadd\n", + "\n", + " reduces independent noise. It also mixes the exposure PSFs. Averaging eight images does not by itself establish finer spatial resolution. Equal Gaussian variances make equal weights appropriate for this experiment. The image-level comparison first blurs each constituent to a common attainable Gaussian width of 2.4 pixels, then averages. Reconstruction receives the corresponding additional blur. This comparison spends resolution to make flux measurements comparable. Discrete smoothing approximates continuous blur, and the noiseless physical control measures the residual floor.\n", + "\n", + "
Science Explanation: Why the target resolution is broader\n", + "\n", + "A Gaussian blur adds variances. To turn a width $p_e$ exposure into a\n", + "width $q$ target, the additional blur has width $\\sqrt{q^2-p_e^2}$, which\n", + "requires $q\\ge p_e$. We choose $q=2.4$ before evaluating the test scene.\n", + "A coadd PSF is a mixture of the exposure PSFs; it generally has no single\n", + "Gaussian width. Blurring each constituent separately avoids replacing that\n", + "mixture with an unjustified single Gaussian. The source's intrinsic width\n", + "remains part of the target image.\n", + "\n", + "
" + ], + "id": "scene-006" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Reconstruct with xImage L2\n", + "\n", + " uses eight frames and fixed kernels. It solves no PSF parameters. The visible call below repeats the first saved fit with the same recorded configuration. The full study performs paired L2 and Huber fits on each noise realization.\n", + "\n", + "
Science Explanation: The weighted objective\n", + "\n", + "The L2 objective is proportional to\n", + "\n", + "$$L(x)=\\frac12\\sum_{e,i}m_{ei}\\frac{[y_{ei}-(H_ex)_i]^2}{v_{ei}},\\qquad x\\ge0.$$\n", + "\n", + "The mask $m$ is one for valid pixels. Pixels with larger variance receive\n", + "less weight. Multiplicative updates preserve under their\n", + "supported positive-kernel assumptions. An update stopping score is not a\n", + ". Iteration count regularizes this finite inverse problem;\n", + "the reference fixes 300 iterations, a constant Huber threshold, and a very\n", + "small stopping tolerance after a separate development-scene iteration sweep. The Huber threshold of two was declared in advance and was not tuned by that sweep.\n", + "\n", + "
" + ], + "id": "scene-007" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "import yaml\n", + "from cuphoton.ximage.workflows import run_reconstruction\n", + "config = yaml.safe_load((STUDY / \"trial-000/l2.yaml\").read_text())\n", + "config[\"output\"][\"name\"] = \"notebook-l2\"\n", + "config_path = ROOT / \"notebook-l2.yaml\"\n", + "config_path.write_text(yaml.safe_dump(config))\n", + "l2_run = run_reconstruction(config_path)\n", + "print(l2_run.summary[\"trace_summary\"])\n", + "huber_config = yaml.safe_load((STUDY / \"trial-000/huber.yaml\").read_text())\n", + "huber_config[\"output\"][\"name\"] = \"notebook-huber\"\n", + "huber_path = ROOT / \"notebook-huber.yaml\"\n", + "huber_path.write_text(yaml.safe_dump(huber_config))\n", + "huber_run = run_reconstruction(huber_path)\n", + "print(huber_run.summary[\"trace_summary\"])\n" + ], + "outputs": [], + "execution_count": null, + "id": "scene-008" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Compare robust losses\n", + "\n", + " limits the influence of large . It can help when a small fraction of pixels have large positive artifacts. Robustness also changes the response to ordinary noise and model mismatch. It need not improve every source or metric. Our threshold is two standardized residual units throughout the fit. A changing threshold would make the loss trace a sequence of different objectives.\n", + "\n", + "
Science Explanation: Residual scale and weighting\n", + "\n", + "For $r=(y-Hx)/\\sqrt v$, the Huber loss is\n", + "\n", + "$$\\rho_\\delta(r)=\\begin{cases}r^2/2,&|r|\\le\\delta,\\\\\n", + "\\delta(|r|-\\delta/2),&|r|>\\delta.\\end{cases}$$\n", + "\n", + "Scaling all variances by four divides standardized residuals by two. It changes\n", + "the effective Huber transition in the original intensity units. The numerical\n", + "control compares this with doubling the threshold. L2's exact minimizer is\n", + "unchanged by a global variance factor, while its reported objective rescales.\n", + "Finite arithmetic and weakly constrained halo pixels can break exact numeric\n", + "invariance; the controls record that boundary sensitivity.\n", + "\n", + "
" + ], + "id": "scene-009" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(products(STUDY, {\"Principal Gaussian case\": \"trial-000\",\n", + " \"Outliers\": \"outliers\", \"Explicit quality mask\": \"explicit-mask\"}))" + ], + "outputs": [], + "execution_count": null, + "id": "scene-010" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Keep real border context\n", + "\n", + "The 15\u00d715 kernel acts on a 96\u00d796 fitting region inside a 120\u00d7120 generated\n", + "field. The saved reconstruction is 110\u00d7110 because retains\n", + "a seven-pixel latent halo. Forward convolution produces 96\u00d796 context\n", + "predictions. The page and primary measurements use the central 48\u00d748 science\n", + "window, with pixel origin (36, 36) in the generated field. Kernels and noise\n", + "are generated over the whole field; the science window has real surrounding\n", + "measurements as well as latent kernel support.\n", + "\n", + "The initial compact fitting experiment had enough support for convolution but\n", + "insufficient separation from the poorly constrained latent boundary for the\n", + "subsequent common-resolution blur. Some outer latent pixels grew very large\n", + "and contaminated that blur. The compact experiment remains a deliberate\n", + "boundary-failure control, and its original reference is retained separately.\n", + "The revised context geometry was checked on development data before freezing\n", + "fresh test seeds. Numerical records retain full-context prediction errors\n", + "alongside the central-window errors, so the boundary limitation stays visible.\n", + "\n", + "Apertures must lie at least five pixels from the science-window boundary.\n", + "That exclusion defines the catalog measurement region; the larger fitting\n", + "context supplies the additional support needed before blurring. Zero-valued\n", + "padding never substitutes for a detector measurement in the fitting ROI.\n", + "\n", + "The compact control shown here is a single draw and may have little source-aperture bias. In the preserved first 50-draw compact study, L2 mean errors at the two edge sources were +1.29% (SE 0.23%) and +0.66% (SE 0.16%). That failed study used its own split and seeds; these are historical failure evidence, not paired comparisons with revision 2. Its external `reference-01/study/summary.json` has SHA-256 `27ae33705230110e6aafac7ea9112834b092702c966ae7c6cb5164cc4be5809c`.\n" + ], + "id": "scene-011" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(products(STUDY, {\"Compact context: boundary failure\": \"boundary-failure\"}))\n" + ], + "outputs": [], + "execution_count": null, + "id": "scene-boundary-failure" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Calibrate a PSF from independent star data\n", + "\n", + " has two distinct steps here. First, an example-authored estimator uses centered, zero-background calibration stars, clips negative noisy samples, and normalizes the stamp. Each idealized on-grid star supplies 100,000 electrons and independent Poisson photon counts plus Gaussian read noise. Its known centering avoids a shift-estimation problem. Second, `run_psf_solve` factors that measured stamp through a Gaussian reference. The public solver receives PSF images; it does not locate or fit stars.\n", + "\n", + "
Science Explanation: The Gaussian reference changes the target\n", + "\n", + "PSF factorization approximates $f_e=g*h_e$, with reference width\n", + "$\\sigma_g=0.55$ pixel. Reconstructing with $h_e$ targets $g*x$, rather than\n", + "the unconvolved scene $x$. The common-resolution comparison therefore adds\n", + "only $\\sqrt{2.4^2-0.55^2}$ pixels of Gaussian blur to that product.\n", + "Finite , stamp clipping and imperfect factorization each\n", + "contribute error. Perfect-known-kernel and independently repeated calibration\n", + "draws separate those effects. A calibration error shared by several science\n", + "realizations is a common , not additional independent science noise.\n", + "\n", + "
\n", + "The 0.55-pixel reference width is xImage's package default and an explicit\n", + "teaching choice in this protocol.\n" + ], + "id": "scene-012" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.ximage.workflows import run_psf_solve\n", + "psf_config = yaml.safe_load((STUDY / \"calibration/calibration-mm.yaml\").read_text())\n", + "psf_config[\"output\"][\"name\"] = \"notebook-psf-mm\"\n", + "psf_path = ROOT / \"notebook-psf-mm.yaml\"\n", + "psf_path.write_text(yaml.safe_dump(psf_config))\n", + "psf_run = run_psf_solve(psf_path)\n", + "print(psf_run.summary[\"method\"], psf_run.summary[\"psfs_shape\"])\n", + "show(calibration_diagnostics(STUDY))\n", + "print((STUDY / \"calibration/diagnostics.json\").read_text())\n" + ], + "outputs": [], + "execution_count": null, + "id": "scene-013" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Inspect the saved calibration kernels\n", + "\n", + "Multiplicative PSF updates are the main investigation. Adam supplies an additional optimizer comparison. Adam can return negative kernel elements. The reference records its minimum, normalization and prediction error; such a kernel is excluded from multiplicative scene reconstruction when it violates positive-kernel assumptions. A small optimization loss alone does not establish a physically admissible calibrated kernel. The finite-calibration experiment repeats independent calibration draws on the same noiseless science scene. The plot reports noisy-calibration minus noiseless-calibration flux error, on the same noiseless science scene. Its scatter describes the chosen calibration model at the declared star flux. It does not establish survey calibration quality." + ], + "id": "scene-014" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Reveal truth at a fair resolution\n", + "\n", + "The truth image below comes from the independent physical model. All four panels target the same 2.4-pixel Gaussian resolution. Pan or zoom one panel to move the others. Tap a pixel to inspect its saved numeric value. The exact pixel values remain available independently of the display range. Use the noiseless and matched-operator cases to distinguish observational noise from or finite-iteration bias." + ], + "id": "scene-015" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(products(STUDY, {\"Physical renderer\": \"trial-000\",\n", + " \"Noiseless physical control\": \"noiseless-physical\",\n", + " \"Matched discrete operator\": \"matched-operator\",\n", + " \"Calibrated MM kernels\": \"calibrated-mm\",\n", + " \"Perfect kernels through factorization\": \"perfect-factorization\"}))" + ], + "outputs": [], + "execution_count": null, + "id": "scene-016" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Declare the flux endpoint\n", + "\n", + " is the primary endpoint: radius three pixels around each fixed catalog position, after matching resolution. We compare each aperture with the identical aperture on known target truth. These are local light measurements. They include neighbors and are not deblended total source fluxes. is `(measured \u2212 truth) / truth`. We report every fixed source by input brightness and environment, plus class summaries. The catalog is small and fixed, so the experiment estimates noise sensitivity for these sources; it does not estimate a population-wide brightness or law.\n", + "\n", + "
Science Explanation: Paired uncertainty and detectable bias\n", + "\n", + "Each independent noise realization supplies one result per method. We form\n", + "method differences within the same realization, preserving the from\n", + "shared input noise. We average sources within a class before estimating a\n", + "class across realizations. Sources in one image are not counted\n", + "as independent noise realizations.\n", + "\n", + "For $N$ independent trials, the estimated standard error of mean bias is\n", + "$s/\\sqrt N$. The page shows approximate 95% mean-bias intervals and reports\n", + "$2.8s/\\sqrt N$ as an approximate detectable bias at for a two-sided\n", + "5% test. Scatter estimates at $N=50$ remain relatively imprecise. No broad\n", + "method ranking follows from a difference smaller than its measured precision.\n", + "\n", + "
" + ], + "id": "scene-017" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "summary = json.loads((STUDY / \"summary.json\").read_text())\n", + "print(json.dumps(summary, indent=2))\n", + "show(diagnostics(STUDY))\n", + "print(\"Recorded workflow controls:\")\n", + "print((ROOT / \"controls.json\").read_text())\n", + "\n", + "from presentation import posthoc_comparisons\n", + "display(HTML(posthoc_comparisons(STUDY)))\n", + "protocol = json.loads((STUDY / \"protocol.json\").read_text())\n", + "expected = 10 if development else protocol[\"iterations\"]\n", + "traces = [trial / \"runs\" / method / \"trace/loss.npy\"\n", + " for trial in sorted(STUDY.glob(\"trial-*\"))\n", + " for method in (\"l2\", \"huber\")]\n", + "assert all(len(np.load(path)) == expected for path in traces)\n", + "print(\"Verified fixed-length primary loss traces:\", len(traces))\n" + ], + "outputs": [], + "execution_count": null, + "id": "scene-018" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Positions, blends and extended light\n", + "\n", + " shifts when neighboring light enters an aperture. We compare measured centroids with target-truth aperture centroids. For the close pair we also record the distance between the two overlapping-aperture centroids and compare it with the intrinsic three-pixel separation. This deliberately simple estimator is biased by blending. A clean-looking pair cannot establish an unbiased deblended separation measurement. mean-light profiles retain the extended-source evidence that a single number discards. The complete numerical artifacts include per-source profiles and centroid errors for every realization." + ], + "id": "scene-019" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Predict exposures the solver never saw\n", + "\n", + " tests whether one reconstructed scene explains different blurs. Select a frame below. Frames 1, 2, 4, 5, 7, 8, 9 and 11 were fitted; frames 3, 6, 10 and 12 were held out. This interleaves PSF widths rather than holding out only the broadest blurs. Residual means and spatial patterns matter alongside their magnitude. A residual second moment divided by known pixel variance is a diagnostic, not an automatic chi-square test with mean one. Fitting, positivity, spatial correlations and uncertainty in the predicted image change its interpretation. An independently noisy held-out frame removes one source of circularity, but it does not remove prediction uncertainty." + ], + "id": "scene-020" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(exposures(STUDY))" + ], + "outputs": [], + "execution_count": null, + "id": "scene-021" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Make the PSF wrong by five percent\n", + "\n", + "The next selector supplies kernels that are uniformly 5% too narrow or 5% too broad. Every exposure shares the sign of that error, including held-out kernels. A common PSF error can be absorbed partly into the inferred scene and evade a residual-only check. Truth-based aperture, centroid and profile errors quantify its measurement consequences. Small apertures and native-resolution profile fits can be more sensitive than common-resolution . A weak flux effect is retained as a finite-sensitivity result.\n", + "The coadd display uses the declared true widths for common-resolution\n", + "smoothing in these controls. Its unchanged row is a known-model baseline,\n", + "not a competing pipeline calibrated with the erroneous kernels.\n" + ], + "id": "scene-022" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(products(STUDY, {\"Supplied true kernels\": \"trial-000\",\n", + " \"PSF width \u22125%\": \"psf-width-0.95\", \"PSF width +5%\": \"psf-width-1.05\"}))" + ], + "outputs": [], + "execution_count": null, + "id": "scene-023" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Separate outliers, variances and photon noise\n", + "\n", + "The outlier case adds 100 electrons to roughly 0.3% of pixels. L2, Huber and an ideal explicit mask receive the same realization. Masking removes known contaminated measurements; Huber reduces influence according to residual size. They use different information, so the mask comparison is an idealized control.\n", + "\n", + "Multiplying variances by four changes the interpretation of standardized residuals and Huber weighting. The photon/read-noise case instead draws electrons and adds Gaussian read noise. Its known variance equals expectation plus read variance. That likelihood differs from the exactly Gaussian principal case even though its first two moments are supplied. The page preserves the distinction when reporting results.\n", + "The explicit quality mask applies to L2 and Huber reconstruction. The coadd\n", + "remains the ordinary unmasked baseline in that control.\n", + "\n", + "The photon/read example is one unpaired draw. It cannot resolve sub-percent bias.\n" + ], + "id": "scene-024" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(products(STUDY, {\"Known Gaussian variance\": \"trial-000\",\n", + " \"Variance multiplied by four\": \"variance-times-four\",\n", + " \"Photon plus read noise\": \"photon-read\"}))\n", + "from presentation import case_measurement_table\n", + "display(HTML(case_measurement_table(STUDY)))\n" + ], + "outputs": [], + "execution_count": null, + "id": "scene-025" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Break the static-scene assumption\n", + "\n", + " appears in a minority of frames at a new position in the central science window. A static fit can dilute its flux across the compromise image, redistribute light, or leave inconsistent frame residuals. The transient is present in fitted frames 2 and 7 and held-out frame 10. Select those frames and compare them with their neighbors. A robust loss may suppress variability that a time-domain analysis would want to preserve. This experiment has no classifier or alert stream; the evidence is the inconsistency of individual image predictions." + ], + "id": "scene-026" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "show(products(STUDY, {\"Static source model\": \"trial-000\", \"Transient input\": \"transient\"}))\n", + "show(exposures(STUDY, \"transient\", method=\"compare\"))" + ], + "outputs": [], + "execution_count": null, + "id": "scene-027" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What the native metrics can establish\n", + "\n", + "The native evaluator records coadd-relative , and sharpness. These diagnostics share input information and compare different effective resolutions. They describe image differences; they cannot establish reconstruction accuracy. The primary truth-based endpoint, independent calibration controls and individual held-out predictions supply the scientific qualification. The zero-dither experiment supports no claim about shift recovery, resampling covariance, WCS alignment or arbitrary super-resolution.\n", + "The native evaluator uses its own median-coadd diagnostic reference. The\n", + "primary comparison uses the separately constructed arithmetic coadd at the\n", + "common target resolution.\n" + ], + "id": "scene-028" + }, + { + "cell_type": "code", + "metadata": {}, + "source": [ + "from cuphoton.ximage.evaluation import evaluate_reconstruction_run\n", + "secondary = evaluate_reconstruction_run(l2_run.run_dir, metrics_backend=\"cpu\")\n", + "print(json.dumps(secondary, indent=2, default=str))" + ], + "outputs": [], + "execution_count": null, + "id": "scene-029" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Reproduce and inspect the evidence\n", + "\n", + "The execution receipt records source hashes, protocol hash, seeds, dependency versions and artifact hashes. The full numerical study stays outside Git. The page embeds selected first-realization arrays and complete summary diagnostics, keeping repeated-trial arrays out of the HTML. Every selector is a precomputed experiment selector. Reading the exported page requires no Python process, kernel, WebSocket, API, CDN or network connection.\n", + "\n", + "See `README.md` for clean-environment execution and `PUBLISHING.md` for static packaging and the remaining versioned-Pages integration work. Opening or merging the source PR does not publish this chapter.\n", + "\n", + "The reconstruction follows the ImageMM approach: Yashil Sukurdeep, Tam\u00e1s Budav\u00e1ri, Andrew J. Connolly and Fausto Navarro, [ImageMM: Joint Multi-frame Image Restoration and Super-resolution](https://doi.org/10.3847/1538-3881/adfb72), *The Astronomical Journal* 170, 233 (2025). Cite that paper and the cuPhoton version printed by this execution. The declared teaching models and source catalog are original to this example." + ], + "id": "scene-030" + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "version": "3.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/examples/model-scene/presentation.py b/examples/model-scene/presentation.py new file mode 100644 index 00000000..d571c846 --- /dev/null +++ b/examples/model-scene/presentation.py @@ -0,0 +1,372 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Saved-result views and accessible explanatory HTML for Model Scene.""" + +import html +import json +from pathlib import Path + +import numpy as np +from bokeh.layouts import column, row +from bokeh.models import ColumnDataSource, CustomJS, Div, Select +from bokeh.plotting import figure +from experiment import aperture_measurements, forward_prediction +from scene import HELDOUT_FRAMES, TRAIN_FRAMES, catalog, science_window +from views import linked_panels + + +def products(root, names): + cases = {} + for label, directory in names.items(): + with np.load(Path(root) / directory / "page.npz") as saved: + cases[label] = [ + saved[key].copy() for key in ("truth", "coadd", "l2", "huber") + ] + return linked_panels(cases, ["Target truth", "Coadd", "L2", "Huber"]) + + +def exposures(root, case="trial-000", method="huber"): + methods = ("l2", "huber") if method == "compare" else (method,) + cases = {} + with np.load(Path(root) / case / "page.npz") as saved: + observations = saved["observations"] + frames = [observations[..., i].copy() for i in range(12)] + for current in methods: + predicted = science_window( + forward_prediction( + saved[f"{current}_native"], saved["kernels"] + ) + ) + for i in range(12): + split = "fit" if i in saved["train_frames"] else "held out" + label = f"{current.upper()} {i + 1:02} ({split})" + cases[label] = [ + frames[i], + predicted[..., i], + frames[i] - predicted[..., i], + ] + return column( + Div( + text="

" + + " / ".join(m.upper() for m in methods) + + " forward predictions

" + ), + linked_panels( + cases, ["Observation", "Prediction", "Residual"], signed=(2,) + ), + ) + + +def diagnostics(root): + root = Path(root) + summary = json.loads((root / "summary.json").read_text()) + colors = {"coadd": "#3377bb", "l2": "#cc5533", "huber": "#228855"} + flux = figure( + title="Aperture flux bias with ±1.96 standard errors", + x_axis_label="Fixed catalog source index", + y_axis_label="Fractional aperture flux error", + width=760, + height=330, + tools="pan,wheel_zoom,reset,save", + ) + centroid = figure( + title="Centroid error by source", + x_axis_label="Fixed catalog source index", + y_axis_label="Mean error (pixel)", + width=760, + height=280, + ) + trials = json.loads((root / "trials.json").read_text()) + for method, color in colors.items(): + rows = summary[method]["by_source"] + x = np.arange(len(rows)) + y = np.array([r["mean_fractional_bias"] for r in rows]) + se = np.array([r["bias_standard_error"] for r in rows]) + flux.scatter(x, y, color=color, legend_label=method, size=8) + flux.segment(x, y - 1.96 * se, x, y + 1.96 * se, color=color) + values = np.array( + [ + [s["centroid_error_px"] for s in trial[method]["sources"]] + for trial in trials + ] + ) + center = values.mean(axis=0) + se_centroid = values.std(axis=0, ddof=1) / np.sqrt(len(values)) + centroid.line(x, center, color=color, legend_label=method) + centroid.segment( + x, + center - 1.96 * se_centroid, + x, + center + 1.96 * se_centroid, + color=color, + ) + convergence = figure( + title="Fixed-objective loss traces (first trial)", + x_axis_label="Iteration", + y_axis_label="Native loss", + width=760, + height=280, + y_axis_type="log", + ) + with np.load(root / "trial-000/page.npz") as data: + for method in ("l2", "huber"): + loss = data[f"{method}_loss"] + convergence.line( + np.arange(len(loss)), + loss, + color=colors[method], + legend_label=method, + ) + profile = figure( + title="Annular profile error with ±1.96 standard errors", + x_axis_label="Radius (pixel)", + y_axis_label="Mean intensity error (electron / exposure)", + width=760, + height=300, + ) + profile_bank = [] + for index in range(len(trials[0]["coadd"]["sources"])): + data = {"radius": np.arange(5) + 0.5} + for method in colors: + values = np.array( + [ + trial[method]["sources"][index]["profile_error"] + for trial in trials + ] + ) + mean = values.mean(axis=0) + se = values.std(axis=0, ddof=1) / np.sqrt(len(values)) + data[method] = mean + data[method + "_low"] = mean - 1.96 * se + data[method + "_high"] = mean + 1.96 * se + profile_bank.append(ColumnDataSource(data)) + source = ColumnDataSource(dict(profile_bank[0].data)) + for method, color in colors.items(): + profile.line( + "radius", method, source=source, color=color, legend_label=method + ) + profile.segment( + "radius", + method + "_low", + "radius", + method + "_high", + source=source, + color=color, + ) + selector = Select( + title="Precomputed source profile", + value="0", + options=[str(i) for i in range(len(profile_bank))], + ) + selector.js_on_change( + "value", + CustomJS( + args=dict(source=source, bank=profile_bank), + code=""" +source.data = {...bank[Number(cb_obj.value)].data}; +source.change.emit(); +""", + ), + ) + return column(flux, centroid, selector, profile, convergence) + + +def calibration_diagnostics(root): + root = Path(root) / "calibration" + diagnostics = json.loads((root / "diagnostics.json").read_text()) + plot = figure( + title="Saved kernel normalization after factorization", + x_axis_label="Exposure", + y_axis_label="Kernel sum", + width=700, + height=280, + ) + for method, color in [("mm", "#228855"), ("adam", "#cc5533")]: + plot.line( + np.arange(1, 13), + diagnostics[method]["sums"], + color=color, + legend_label=method, + ) + trials = json.loads((root / "finite-calibration.json").read_text()) + errors = np.array( + [ + [ + s["calibration_flux_error_increment"] + for s in trial["l2"]["sources"] + ] + for trial in trials + ] + ) + uncertainty = figure( + title="Calibration draws minus noiseless control: L2 ±1 SD", + x_axis_label="Source", + y_axis_label="Fractional aperture error", + width=700, + height=280, + ) + x = np.arange(errors.shape[1]) + mean = errors.mean(axis=0) + scatter = errors.std(axis=0, ddof=1) + uncertainty.scatter(x, mean, size=8) + uncertainty.segment(x, mean - scatter, x, mean + scatter) + return row(plot, uncertainty, sizing_mode="stretch_width") + + +def case_measurement_table(root): + """Show quantitative controls from the first noise realization.""" + rows = [] + for case in ( + "trial-000", + "boundary-failure", + "outliers", + "explicit-mask", + "psf-width-0.95", + "psf-width-1.05", + "variance-times-four", + "photon-read", + "transient", + "matched-operator", + "noiseless-physical", + "calibrated-mm", + "perfect-factorization", + ): + values = json.loads( + (Path(root) / case / "measurements.json").read_text() + ) + for method, result in values.items(): + bias = np.mean( + [s["fractional_flux_error"] for s in result["sources"]] + ) + centroid = np.mean( + [s["centroid_error_px"] for s in result["sources"]] + ) + residual = result.get("standardized_residual_ms_by_frame") + fit = ( + f"{np.mean(np.asarray(residual)[list(TRAIN_FRAMES)]):.5f}" + if residual is not None + else "n/a" + ) + held = ( + f"{np.mean(np.asarray(residual)[list(HELDOUT_FRAMES)]):.5f}" + if residual is not None + else "n/a" + ) + qualifier = ( + " (noiseless science)" + if case in ("noiseless-physical", "perfect-factorization") + else " (noisy science)" + ) + rows.append( + f"{html.escape(case + qualifier)}" + f"{html.escape(method)}{bias:.5f}" + f"{centroid:.5f}{fit}{held}" + ) + floors = [] + for case in ( + "matched-operator", + "noiseless-physical", + "perfect-factorization", + ): + values = json.loads( + (Path(root) / case / "measurements.json").read_text() + ) + for method, result in values.items(): + for source in result["sources"]: + floors.append( + f"{case}{method}" + f"{source['kind']}" + f"{source['input_flux']}" + f"{source['fractional_flux_error']:.6f}" + "" + ) + floor_table = ( + "
Per-source numerical bias floors" + "" + "" + "" + + "".join(floors) + + "
ControlMethodEnvironmentInput fluxFractional aperture error
" + ) + return ( + "" + "" + "" + "" + "" + "" + + "".join(rows) + + "
Case controls; " + "photon/read and compact context use separate draws. " + "No trial error bars.
CaseMethodMean fractional aperture errorMean centroid error (pixel)Fitted mean standardized residual²Held-out mean standardized residual²
" + + floor_table + ) + + +def posthoc_comparisons(root): + """Report descriptive additions to the frozen primary analysis.""" + root = Path(root) + trials = json.loads((root / "trials.json").read_text()) + protocol = json.loads((root / "protocol.json").read_text()) + profile = json.loads((root.parent / "execution-profile.json").read_text()) + sources = catalog(development=profile["profile"] == "quick") + rows = [] + for index, source in enumerate(sources): + for first, second in ( + ("l2", "coadd"), + ("huber", "coadd"), + ("huber", "l2"), + ): + values = np.array( + [ + trial[first]["sources"][index]["fractional_flux_error"] + - trial[second]["sources"][index]["fractional_flux_error"] + for trial in trials + ] + ) + se = values.std(ddof=1) / np.sqrt(len(values)) + rows.append( + f"{index}: {source.kind}, {source.flux:g} e" + f"{first} minus {second}" + f"{values.mean():.6f}{se:.6f}" + ) + with np.load(root / "trial-000/page.npz") as saved: + target_rows = aperture_measurements( + saved["truth"], sources, origin=protocol["science_window_origin"] + ) + pair = [row for row in target_rows if row["kind"] == "blend"] + target_separation = np.hypot( + pair[0]["x"] - pair[1]["x"], pair[0]["y"] - pair[1]["y"] + ) + separations = [] + for method in ("coadd", "l2", "huber"): + values = ( + np.array( + [ + t[method]["blend_aperture_centroid_separation_px"] + for t in trials + ] + ) + - target_separation + ) + separations.append( + f"
  • {method}: mean {values.mean():.6f} px, " + f"SE {values.std(ddof=1) / np.sqrt(len(values)):.6f} px
  • " + ) + return ( + "
    Post hoc paired source and separation " + "diagnostics" + "

    Descriptive comparisons on frozen draws, added after inspection; " + "they did not select parameters or change the primary endpoint.

    " + "" + "" + "" + "".join(rows) + "
    Fixed sourcePaired contrastMean fractional differenceStandard error
    " + f"

    The aperture-centroid estimator on target truth gives " + f"{target_separation:.6f} px; the intrinsic separation is 3 px. " + "The following errors use that same target estimator, and do not " + "establish deblended separation recovery.

    " + ) diff --git a/examples/model-scene/preview.py b/examples/model-scene/preview.py new file mode 100644 index 00000000..75dd4b9d --- /dev/null +++ b/examples/model-scene/preview.py @@ -0,0 +1,221 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Export an executed notebook and CPU guide as a local static preview.""" + +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 digest(path): + return hashlib.sha256(Path(path).read_bytes()).hexdigest() + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--executed", type=Path, required=True) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument("--source-ref", default="main") + parser.add_argument("--controller-python", default=sys.executable) + args = parser.parse_args() + if args.output.exists() or args.output.is_symlink(): + parser.error("Use an absent destination") + output = args.output.resolve() + if output.is_relative_to(REPO): + parser.error("Build outside the source checkout") + executed = args.executed.resolve() + receipt = json.loads(executed.with_name("execution.json").read_text()) + if not receipt.get("completed"): + raise ValueError("A completed execution receipt is required") + if digest(executed) != receipt["artifact_hashes"][executed.name]: + raise ValueError("Executed notebook hash mismatch") + for name, expected in receipt["source_hashes"].items(): + if digest(HERE / name) != expected: + raise ValueError(f"Changed source since execution: {name}") + notebook = nbformat.read(executed, as_version=4) + code = [cell for cell in notebook.cells if cell.cell_type == "code"] + if any(cell.execution_count is None for cell in code): + raise ValueError("Incomplete notebook execution") + if any(o.output_type == "error" for cell in code for o in cell.outputs): + raise ValueError("Notebook contains execution errors") + guide = output / "guide" + shutil.copytree( + REPO / "docs/guide", + guide, + ignore=shutil.ignore_patterns( + "_book", "_freeze", ".quarto", "__pycache__" + ), + ) + # Includes are build inputs outside the guide resource tree. + includes = output / "includes" + includes.mkdir() + (includes / "scene.js.html").write_text( + "\n" + ) + (guide / "assets/model-scene").mkdir() + shutil.copy2( + HERE / "assets/scene.css", guide / "assets/model-scene/scene.css" + ) + config_path = guide / "_quarto.yml" + config = yaml.safe_load(config_path.read_text()) + config["book"]["chapters"].insert( + 2, {"part": "Examples", "chapters": ["model-scene.ipynb"]} + ) + config["project"].setdefault("resources", []).append("source/**") + config_path.write_text(yaml.safe_dump(config, sort_keys=False)) + first = notebook.cells[0] + match = re.match(r"\A---\n(.*?)\n---\n", first.source, re.S) + metadata = yaml.safe_load(match[1]) + metadata["execute"] = {"enabled": False, "warning": True} + metadata["format"]["html"].update( + { + "css": "assets/model-scene/scene.css", + "include-after-body": "../includes/scene.js.html", + } + ) + first.source = ( + "---\n" + + yaml.safe_dump(metadata, sort_keys=False) + + "---\n" + + first.source[match.end() :] + ) + source_url = ( + "https://github.com/NVIDIA/cuPhoton/blob/" + + quote(args.source_ref, safe="") + + "/examples/model-scene/model-scene.ipynb" + ) + for cell in notebook.cells: + if cell.cell_type == "markdown": + cell.source = cell.source.replace( + "https://github.com/NVIDIA/cuPhoton/blob/main/examples/model-scene/model-scene.ipynb", + source_url, + ) + for item in cell.get("outputs", []): + if item.output_type == "stream": + text = item.text + text = text.replace(str(executed.parent), ".") + text = text.replace(str(REPO), "") + # Warnings retain their message and source-relative filename. + text = re.sub( + r"/[^\s\"\']*/site-packages/", + "/site-packages/", + text, + ) + cell.outputs[cell.outputs.index(item)].text = text + downloads = guide / "source" + downloads.mkdir(exist_ok=True) + public_notebook = downloads / "model-scene.executed.ipynb" + nbformat.write(notebook, public_notebook) + public_receipt = { + "profile": receipt["profile"], + "completed": True, + "source_revision": receipt["source_revision"], + "source_hashes": receipt["source_hashes"], + "protocol_sha256": receipt["protocol_sha256"], + "packages": receipt["packages"], + "architecture": receipt["architecture"], + "gpu": receipt.get("gpu"), + "device": receipt["device"], + "science_seeds": receipt["science_seeds"], + "calibration_seeds": receipt["calibration_seeds"], + "source_import": receipt["source_import"], + "source_tree_clean": receipt["source_tree_clean"], + "artifact_hashes": receipt["artifact_hashes"], + "runtime_cuphoton_version": receipt.get("runtime_cuphoton_version"), + "original_receipt_sha256": digest( + executed.with_name("execution.json") + ), + "public_notebook_sha256": digest(public_notebook), + "notebook_sanitization": "local paths replaced in text streams", + } + (downloads / "model-scene-execution.json").write_text( + json.dumps(public_receipt, indent=2) + "\n" + ) + first.source += ( + "\n\n[Download the executed notebook]" + "(source/model-scene.executed.ipynb) · " + "[Public execution receipt]" + "(source/model-scene-execution.json)\n" + ) + nbformat.write(notebook, guide / "model-scene.ipynb") + sources = guide / "source/model-scene" + for name in receipt["source_hashes"]: + target = sources / name + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(HERE / name, target) + shutil.copy2(REPO / "LICENSE", sources / "LICENSE") + with ZipFile( + guide / "source/model-scene.zip", "w", ZIP_DEFLATED + ) as archive: + for path in sources.rglob("*"): + if path.is_file(): + archive.write( + path, + "model-scene/" + 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", + ) + # CPU chapters execute; the IPYNB preserves saved GPU outputs. + subprocess.run( + ["quarto", "render", str(guide), "--no-cache"], env=env, check=True + ) + revision = subprocess.check_output( + ["git", "rev-parse", "HEAD"], cwd=REPO, text=True + ).strip() + controller = """ +import sys +from pathlib import Path +from cuphoton_dev.transforms import postprocess, check_snapshot +root = Path(sys.argv[1]) +postprocess(root, version="main", source_sha=sys.argv[2], + controller_sha=sys.argv[2], renderer=sys.argv[3], + lock_sha256=sys.argv[4]) +check_snapshot(root) +""" + env["PYTHONPATH"] = ( + str(REPO / "dev/src") + os.pathsep + env.get("PYTHONPATH", "") + ) + subprocess.run( + [ + args.controller_python, + "-c", + controller, + str(guide / "_book"), + revision, + subprocess.check_output( + ["quarto", "--version"], text=True + ).strip(), + digest(REPO / "uv.lock"), + ], + env=env, + check=True, + ) + print(guide / "_book/model-scene.html") + + +if __name__ == "__main__": + main() diff --git a/examples/model-scene/protocol.json b/examples/model-scene/protocol.json new file mode 100644 index 00000000..45d4668e --- /dev/null +++ b/examples/model-scene/protocol.json @@ -0,0 +1,70 @@ +{ + "revision": 2, + "frozen": true, + "iterations": 300, + "noise_realizations": 50, + "test_seed_start": 82000, + "calibration_seed_start": 46000, + "development_seeds": [ + 1005, + 1006, + 1007 + ], + "huber_delta": 2.0, + "stop_tolerance": 1e-12, + "background_electrons_per_pixel": 2.0, + "common_gaussian_sigma_pixels": 2.4, + "aperture_radius_pixels": 3, + "edge_exclusion_pixels": 5, + "primary_endpoint": "fractional aperture flux error against target truth", + "minimum_bias_of_interest": 0.01, + "precision_reporting": "per-source standard error and approximate 2.8 SE detectable bias", + "inference_scope": "fixed modeled source catalog and independent noise realizations", + "image_size": 120, + "fit_size": 96, + "science_window_size": 48, + "science_window_origin": 36, + "supersedes": "Revision 1 retained: unconstrained halo contaminated common-resolution image boundary", + "calibration_example_seed": 46099, + "train_frames": [ + 0, + 1, + 3, + 4, + 6, + 7, + 8, + 10 + ], + "heldout_frames": [ + 2, + 5, + 9, + 11 + ], + "pixel_phase": "integer-centered fixed catalog only", + "calibration_noise": "Poisson photons plus Gaussian read sigma 2 electrons", + "development_evidence": { + "artifact": "development-v2/development.json", + "sha256": "97c18564473895f99fb6c07d166c23ef7a3112a78b3c0be6a28c761b285e4962", + "iterations": [ + 25, + 75, + 150, + 300 + ], + "seeds": [ + 1005, + 1006, + 1007 + ], + "selection": "300 chosen from development bias plateau; no test truth used" + }, + "science_source_hashes": { + "scene.py": "558c336b677e0ad3f578613c127a64efaa6ee7216dd7046eb59a001a64dbadc9", + "experiment.py": "30db0c8c285a2b074893d529b7c101d55228309041355cc4bc7772828e30cecc", + "measure.py": "e63151b6c036fc3503cd35b6d5f020c652fbffd3e8b40a20dec04be94c0c3522", + "study.py": "96d74f48c49f30e6983356be1eac696652af614105f28693b8ae555b132bdab0", + "controls.py": "197dd327315efdee7fd334d2b8988c97ba42dd86d082dfa89f7f2ba72fb7dccd" + } +} diff --git a/examples/model-scene/requirements.txt b/examples/model-scene/requirements.txt new file mode 100644 index 00000000..1543ce15 --- /dev/null +++ b/examples/model-scene/requirements.txt @@ -0,0 +1,8 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# Optional additions to a cuPhoton[ximage] environment. +bokeh==3.9.1 +nbclient==0.11.0 +ipykernel==7.4.0 +nbformat==5.10.4 +pytest>=8 diff --git a/examples/model-scene/run.py b/examples/model-scene/run.py new file mode 100644 index 00000000..187ebd78 --- /dev/null +++ b/examples/model-scene/run.py @@ -0,0 +1,264 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Run a fresh study and notebook, retaining outputs outside Git.""" + +import argparse +import contextlib +import fcntl +import hashlib +import json +import os +import platform +import shutil +import subprocess +import sys +from importlib.metadata import version +from pathlib import Path + +import nbformat +import numpy as np +from controls import asymmetric_operator_control, numerical_controls +from jupyter_client import AsyncKernelManager +from nbclient import NotebookClient +from scene import science_window +from study import execute_study + +import cuphoton + +HERE = Path(__file__).resolve().parent + + +def digest(path): + return hashlib.sha256(Path(path).read_bytes()).hexdigest() + + +def check_source(repo, receipt): + """Reject a changed revision or uncommitted reference inputs.""" + receipt["source_tree_clean"] = not subprocess.check_output( + ["git", "status", "--porcelain"], cwd=repo, text=True + ).strip() + revision = subprocess.check_output( + ["git", "rev-parse", "HEAD"], cwd=repo, text=True + ).strip() + if revision != receipt["source_revision"]: + raise RuntimeError("Source revision changed during execution") + if receipt["profile"] == "reference" and not receipt["source_tree_clean"]: + raise RuntimeError("Source tree changed during reference execution") + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, required=True) + parser.add_argument( + "--profile", choices=["quick", "reference"], default="quick" + ) + parser.add_argument("--device", choices=["cpu", "cuda"], default="cuda") + parser.add_argument("--gpu-lock", type=Path) + args = parser.parse_args() + if args.output.exists() or args.output.is_symlink(): + parser.error("Use an absent output directory; preserve earlier runs") + if args.device == "cuda" and args.gpu_lock is None: + parser.error("CUDA execution requires the coordinated --gpu-lock") + repo = HERE.parents[1] + if args.output.resolve().is_relative_to(repo): + parser.error("Build outside the source checkout") + clean = not subprocess.check_output( + ["git", "status", "--porcelain"], cwd=repo, text=True + ).strip() + if args.profile == "reference" and not clean: + parser.error("Reference execution requires a clean committed source") + import_path = Path(cuphoton.__file__).resolve() + if not import_path.is_relative_to(repo / "src"): + parser.error("cuPhoton must import from this exact source checkout") + protocol_path = HERE / "protocol.json" + protocol = json.loads(protocol_path.read_text()) + if args.profile == "reference" and not protocol["frozen"]: + parser.error("Reference execution requires a frozen protocol") + if args.profile == "reference" and not protocol.get( + "science_source_hashes" + ): + parser.error( + "Reference protocol must include scientific source hashes" + ) + tracked = ( + subprocess.check_output(["git", "ls-files", "-z", "."], cwd=HERE) + .decode() + .split("\0") + ) + source_hashes = {name: digest(HERE / name) for name in tracked if name} + for name, expected in protocol.get("science_source_hashes", {}).items(): + if digest(HERE / name) != expected: + parser.error(f"Frozen scientific source changed: {name}") + output = args.output.resolve() + output.mkdir(parents=True) + for name in source_hashes: + target = output / "source" / name + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(HERE / name, target) + os.environ.setdefault("CUDA_VISIBLE_DEVICES", "0") + env = os.environ.copy() + env["CUPHOTON_MODEL_SCENE_OUTPUT"] = str(output) + env.setdefault("CUDA_VISIBLE_DEVICES", "0") + env["PYTHONPATH"] = os.pathsep.join( + [str(HERE), env.get("PYTHONPATH", "")] + ) + quick = args.profile == "quick" + science_start = ( + protocol["development_seeds"][0] + if quick + else protocol["test_seed_start"] + ) + calibration_start = 2000 if quick else protocol["calibration_seed_start"] + receipt = dict( + completed=False, + source_tree_clean=clean, + source_import=import_path.relative_to(repo).as_posix(), + visible_devices=env["CUDA_VISIBLE_DEVICES"], + science_seeds=list( + range( + science_start, + science_start + + (2 if quick else protocol["noise_realizations"]), + ) + ), + calibration_seeds=list( + range(calibration_start, calibration_start + (2 if quick else 50)) + ), + profile=args.profile, + device=args.device, + source_hashes=source_hashes, + protocol_sha256=digest(protocol_path), + python=platform.python_version(), + architecture=platform.machine(), + runtime_cuphoton_version=cuphoton.__version__, + source_revision=subprocess.check_output( + ["git", "rev-parse", "HEAD"], cwd=HERE, text=True + ).strip(), + packages={ + name: version(name) + for name in ( + "cuphoton", + "torch", + "numpy", + "scipy", + "bokeh", + "nbclient", + ) + }, + ) + (output / "execution-profile.json").write_text( + json.dumps( + { + "profile": args.profile, + "full_study_requested": args.profile == "reference", + } + ) + ) + try: + lock_context = ( + open(args.gpu_lock, "a") + if args.gpu_lock + else contextlib.nullcontext() + ) + with lock_context as lock: + if args.device == "cuda": + fcntl.flock(lock, fcntl.LOCK_EX) + check_source(repo, receipt) + import torch + + torch.set_num_threads(4) + if args.device == "cuda": + receipt["gpu"] = { + "model": torch.cuda.get_device_name(0), + "capability": list(torch.cuda.get_device_capability(0)), + "cuda_runtime": torch.version.cuda, + } + controls = { + "cpu": numerical_controls(output / "controls-cpu"), + "asymmetric": asymmetric_operator_control( + output / "controls-asymmetric" + ), + } + if args.device == "cuda": + controls["cuda"] = numerical_controls( + output / "controls-cuda", device="cuda" + ) + cpu = np.load( + output / "controls-cpu/runs/rates/artifacts/image.npy" + ).squeeze() + gpu = np.load( + output / "controls-cuda/runs/rates/artifacts/image.npy" + ).squeeze() + np.testing.assert_allclose( + science_window(cpu), + science_window(gpu), + rtol=1e-8, + atol=1e-8, + ) + controls["cpu_cuda_max_abs"] = float( + np.max(np.abs(science_window(cpu) - science_window(gpu))) + ) + (output / "controls.json").write_text( + json.dumps(controls, indent=2) + "\n" + ) + with (output / "execution.log").open("w") as log: + with ( + contextlib.redirect_stdout(log), + contextlib.redirect_stderr(log), + ): + execute_study( + output / "study", + protocol, + device=args.device, + quick=args.profile == "quick", + ) + notebook = nbformat.read(HERE / "model-scene.ipynb", as_version=4) + manager = AsyncKernelManager(kernel_name="python3") + manager.kernel_spec.argv = [ + sys.executable, + "-m", + "ipykernel_launcher", + "-f", + "{connection_file}", + ] + client = NotebookClient( + notebook, + km=manager, + timeout=1200, + allow_errors=False, + record_timing=True, + ) + try: + client.execute(cwd=str(HERE), env=env, cleanup_kc=True) + finally: + nbformat.write( + notebook, output / "model-scene.executed.ipynb" + ) + check_source(repo, receipt) + for name, expected in source_hashes.items(): + if digest(HERE / name) != expected: + raise RuntimeError(f"Source changed during execution: {name}") + receipt["completed"] = True + receipt["artifact_hashes"] = { + p.relative_to(output).as_posix(): digest(p) + for p in output.rglob("*") + if p.is_file() and "source" not in p.relative_to(output).parts + } + (output / "execution.json").write_text( + json.dumps(receipt, indent=2) + "\n" + ) + except BaseException as exc: + receipt.update( + completed=False, error_type=type(exc).__name__, error=str(exc) + ) + (output / "execution.json").write_text( + json.dumps(receipt, indent=2) + "\n" + ) + raise + print(f"Completed {args.profile} execution: {output}") + + +if __name__ == "__main__": + main() diff --git a/examples/model-scene/scene.py b/examples/model-scene/scene.py new file mode 100644 index 00000000..c70547a0 --- /dev/null +++ b/examples/model-scene/scene.py @@ -0,0 +1,192 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Independent pixel-integrated Gaussian scene and exposure models. + +No dataset, survey adapter, or solver implementation is used by this renderer. +Coordinates denote pixel centers. Flux is the integral on the infinite plane; +finite-stamp losses are retained rather than silently renormalizing sources. +""" + +import json +from dataclasses import dataclass +from pathlib import Path + +import numpy as np +from scipy.signal import convolve2d +from scipy.special import ndtr + +TRAIN_FRAMES = (0, 1, 3, 4, 6, 7, 8, 10) +HELDOUT_FRAMES = (2, 5, 9, 11) + + +@dataclass(frozen=True) +class Source: + x: float + y: float + flux: float + sigma: float + kind: str + + +def catalog(development=False, offset=24): + """Declare catalogs before noise draws or reconstruction measurements.""" + shift = offset + offset = 2.0 if development else 0.0 + sources = ( + Source(18 + offset, 20, 1200, 0.22, "isolated"), + Source(46, 19 + offset, 300, 0.22, "isolated"), + Source(30, 38, 900, 0.22, "blend"), + Source(33, 38, 450, 0.22, "blend"), + Source(20, 53, 2200, 2.5, "extended"), + Source(49, 50, 3200, 4.0, "extended"), + ) + return tuple( + Source(s.x + shift, s.y + shift, s.flux, s.sigma, s.kind) + for s in sources + ) + + +def pixel_gaussian(size, x, y, sigma): + """Integrate an axis-aligned unit Gaussian over each square pixel.""" + if sigma <= 0 or not np.isfinite(sigma): + raise ValueError("sigma must be finite and positive") + edges = np.arange(size + 1, dtype=float) - 0.5 + px = np.diff(ndtr((edges - x) / sigma)) + py = np.diff(ndtr((edges - y) / sigma)) + return py[:, None] * px[None, :] + + +def render(sources, sigma=0.0, size=120, background=2.0): + """Continuous Gaussian convolution followed by detector pixel integration. + + This differs deliberately from convolving an already pixel-integrated + latent grid with a sampled finite kernel. That discretization discrepancy + is measured separately with the matched-operator control. + """ + image = np.full((size, size), background, dtype=float) + for source in sources: + image += source.flux * pixel_gaussian( + size, source.x, source.y, np.hypot(source.sigma, sigma) + ) + return image + + +def kernels(widths, support=15): + """Sample normalized finite kernels for the discrete operator.""" + axis = np.arange(support) - support // 2 + radius2 = axis[:, None] ** 2 + axis[None, :] ** 2 + result = np.exp(-radius2[..., None] / (2 * np.asarray(widths) ** 2)) + return result / result.sum(axis=(0, 1), keepdims=True) + + +def generate( + seed, *, development=False, matched=False, case="gaussian", compact=False +): + """Return twelve shared-grid frames: eight training and four held out. + + Units are electrons per unit exposure; all exposure times are exactly one. + Known Gaussian variance is 4 electrons squared in the principal case. + Noise draws are paired across methods by saving and reusing this bundle. + """ + size = 72 if compact else 120 + offset = 0 if compact else 24 + sources = catalog(development, offset=offset) + truth = render(sources, size=size) + widths = np.linspace(0.9, 1.7, 12) + psfs = kernels(widths) + expectation = np.stack( + [ + convolve2d(truth, psfs[..., i], mode="same", boundary="fill") + if matched + else render(sources, sigma=width, size=size) + for i, width in enumerate(widths) + ], + axis=-1, + ) + rng = np.random.default_rng(seed) + images = expectation + rng.normal(0, 2, expectation.shape) + good = np.ones(images.shape, dtype=bool) + variances = np.full(images.shape, 4.0) + if case == "outliers": + bad = rng.random(images.shape) < 0.003 + images[bad] += 100 + good[bad] = False + elif case == "photon-read": + images = rng.poisson(expectation) + rng.normal( + 0, 2, expectation.shape + ) + variances = expectation + 4 + elif case == "transient": + for i in (1, 6, 9): + images[..., i] += 1200 * pixel_gaussian( + size, 43 + offset, 36 + offset, np.hypot(0.22, widths[i]) + ) + elif case != "gaussian": + raise ValueError(f"Unknown case: {case}") + return { + "images": images[None], + "variances": variances[None], + "masks": good[None], + "psfs": psfs[:, :, None, :], + "sky": np.full_like(images[None], 2), + "exp_times": np.ones(12), + }, { + "truth": truth, + "expectation": expectation, + "widths": widths, + "matched": matched, + "development": development, + "boundary_failure": compact, + "source_offset": offset, + "view_origin": (size - 48) // 2, + } + + +def write_bundle(destination: Path, arrays): + """Refuse pre-existing destinations, including symbolic links.""" + images = np.asarray(arrays["images"]) + variance = np.asarray(arrays["variances"]) + psfs = np.asarray(arrays["psfs"]) + if images.ndim != 4 or variance.shape != images.shape: + raise ValueError("Images and variances need matching rank-four axes") + if not np.all(np.isfinite(images)): + raise ValueError("Nonfinite image values") + if not np.all(np.isfinite(variance) & (variance > 0)): + raise ValueError("Variances must be finite and positive") + if not np.all(np.isfinite(psfs) & (psfs >= 0)): + raise ValueError("Multiplicative reconstruction needs positive PSFs") + masks = np.asarray(arrays["masks"]) + if masks.dtype != bool or masks.shape != images.shape: + raise ValueError( + "Masks must be boolean, True = good, matching images" + ) + times = np.asarray(arrays["exp_times"]) + if not np.all(np.isfinite(times) & (times > 0)): + raise ValueError("Exposure times must be finite and positive") + destination = Path(destination) + if destination.exists() or destination.is_symlink(): + raise FileExistsError(destination) + destination.mkdir(parents=True) + for key, array in arrays.items(): + np.save(destination / f"{key}.npy", array, allow_pickle=False) + (destination / "metadata.json").write_text( + json.dumps( + { + "source": "independent analytic Gaussian mixture", + "image_units": "electrons per unit exposure", + "variance_units": "(electrons / unit exposure)^2", + "mask_convention": "True = good", + "dither_pixels": 0, + }, + indent=2, + ) + + "\n" + ) + + +def science_window(image): + """Select the central 48-pixel science window after support operations.""" + start = (image.shape[0] - 48) // 2 + return image[start : start + 48, start : start + 48, ...] diff --git a/examples/model-scene/study.py b/examples/model-scene/study.py new file mode 100644 index 00000000..3d700534 --- /dev/null +++ b/examples/model-scene/study.py @@ -0,0 +1,316 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Execute scene experiments and save data-only page diagnostics.""" + +import hashlib +import json +from pathlib import Path + +import numpy as np +from experiment import calibrate, reconstruct +from measure import evaluate, paired_summary +from scene import ( + HELDOUT_FRAMES, + TRAIN_FRAMES, + generate, + kernels, + pixel_gaussian, + science_window, +) +from scipy.signal import convolve2d + + +def write_json(path, value): + Path(path).write_text(json.dumps(value, indent=2, allow_nan=False) + "\n") + + +def run_case( + root, + arrays, + truth, + *, + device, + iterations, + masked=False, + reference_sigma=0.0, +): + root = Path(root) + root.mkdir(exist_ok=False, parents=True) + images, runs = {}, {} + for label, algorithm in [("l2", "l2"), ("huber", "rho")]: + image, run, _ = reconstruct( + root, + arrays, + name=label, + algorithm=algorithm, + masked=masked, + device=device, + iterations=iterations, + ) + images[label] = image + runs[label] = run + result, products, target = evaluate( + arrays, truth, images, reference_sigma=reference_sigma + ) + np.savez_compressed( + root / "page.npz", + truth=target, + coadd=products["coadd"], + l2=products["l2"], + huber=products["huber"], + l2_native=images["l2"], + huber_native=images["huber"], + observations=science_window(arrays["images"][0]), + variances=science_window(arrays["variances"][0]), + kernels=arrays["psfs"], + train_frames=np.array(TRAIN_FRAMES), + l2_loss=np.load(runs["l2"].run_dir / "trace/loss.npy"), + huber_loss=np.load(runs["huber"].run_dir / "trace/loss.npy"), + ) + write_json(root / "measurements.json", result) + return result + + +def validate_protocol(protocol): + """Reject descriptive protocol fields that contradict this fixed model.""" + expected = { + "huber_delta": 2.0, + "stop_tolerance": 1e-12, + "background_electrons_per_pixel": 2.0, + "common_gaussian_sigma_pixels": 2.4, + "aperture_radius_pixels": 3, + "edge_exclusion_pixels": 5, + "image_size": 120, + "fit_size": 96, + "science_window_size": 48, + "science_window_origin": 36, + "train_frames": list(TRAIN_FRAMES), + "heldout_frames": list(HELDOUT_FRAMES), + } + for key, value in expected.items(): + if protocol.get(key) != value: + raise ValueError(f"Protocol contradicts fixed model: {key}") + + +def execute_study(root, protocol, *, device="cpu", quick=False): + """Run a previously frozen protocol; evaluate truth after fitting.""" + validate_protocol(protocol) + root = Path(root) + if root.exists() or root.is_symlink(): + raise FileExistsError(root) + root.mkdir(parents=True) + iterations = 10 if quick else protocol["iterations"] + count = 2 if quick else protocol["noise_realizations"] + write_json(root / "protocol.json", protocol) + trials = [] + + def make_data(seed, **kwargs): + return generate(seed, development=quick, **kwargs) + + science_seed = ( + protocol["development_seeds"][0] + if quick + else protocol["test_seed_start"] + ) + calibration_seed = 2000 if quick else protocol["calibration_seed_start"] + example_seed = 2099 if quick else protocol["calibration_example_seed"] + for index in range(count): + arrays, truth = make_data(science_seed + index) + trials.append( + run_case( + root / f"trial-{index:03}", + arrays, + truth, + device=device, + iterations=iterations, + ) + ) + print( + f"Completed paired noise realization {index + 1}/{count}", + flush=True, + ) + write_json(root / "trials.json", trials) + write_json(root / "summary.json", paired_summary(trials)) + # Gaussian cases share noise; other noise models use separate draws. + seed = science_seed + for case in ("outliers", "photon-read", "transient"): + arrays, truth = make_data(seed, case=case) + run_case( + root / case, arrays, truth, device=device, iterations=iterations + ) + if case == "outliers": + run_case( + root / "explicit-mask", + arrays, + truth, + device=device, + iterations=iterations, + masked=True, + ) + for factor in (0.95, 1.05): + arrays, truth = make_data(seed) + arrays["psfs"] = kernels(truth["widths"] * factor)[:, :, None, :] + run_case( + root / f"psf-width-{factor}", + arrays, + truth, + device=device, + iterations=iterations, + ) + arrays, truth = make_data(seed) + arrays["variances"] *= 4 + run_case( + root / "variance-times-four", + arrays, + truth, + device=device, + iterations=iterations, + ) + arrays, truth = make_data(seed, compact=True) + run_case( + root / "boundary-failure", + arrays, + truth, + device=device, + iterations=iterations, + ) + arrays, truth = make_data(seed, matched=True) + run_case( + root / "matched-operator", + arrays, + truth, + device=device, + iterations=iterations, + ) + arrays, truth = make_data(seed) + arrays["images"] = truth["expectation"][None].copy() + run_case( + root / "noiseless-physical", + arrays, + truth, + device=device, + iterations=iterations, + ) + # PSF factorization is separate from estimating the observed star stamp. + calibration_root = root / "calibration" + calibration_root.mkdir() + calibration_report = {} + for method in ("mm", "adam"): + run, measured = calibrate( + calibration_root, + method=method, + device=device, + seed=example_seed, + ) + solved = np.load(run.run_dir / "artifacts/psfs.npy") + np.save(calibration_root / f"{method}-measured.npy", measured) + arrays, truth = make_data(seed) + arrays["psfs"] = solved + if method == "mm": + run_case( + root / "calibrated-mm", + arrays, + truth, + device=device, + iterations=iterations, + reference_sigma=0.55, + ) + # Adam permits negative kernels. Keep this factorization diagnostic + # separate from multiplicative reconstruction with positive kernels. + reference = np.load( + run.run_dir / "artifacts/gaussian_psf.npy" + ).squeeze() + reproduced = np.stack( + [ + convolve2d(solved[:, :, 0, i], reference, mode="same") + for i in range(12) + ], + axis=-1, + ) + np.save(calibration_root / f"{method}-reproduced.npy", reproduced) + y, x = np.indices(solved.shape[:2]) + total = solved.sum(axis=(0, 1, 2)) + centroid_x = (solved[:, :, 0] * x[..., None]).sum(axis=(0, 1)) / total + centroid_y = (solved[:, :, 0] * y[..., None]).sum(axis=(0, 1)) / total + calibration_report[method] = { + "target_reproduction_rms_by_frame": np.sqrt( + np.mean((reproduced - measured) ** 2, axis=(0, 1)) + ).tolist(), + "centroid_xy_by_frame": np.stack( + [centroid_x, centroid_y], axis=-1 + ).tolist(), + "minimum": float(solved.min()), + "sums": solved.sum(axis=(0, 1, 2)).tolist(), + "shape": list(solved.shape), + } + # Noise-free integrated stamps isolate finite calibration uncertainty. + exact_root = calibration_root / "perfect" + exact_root.mkdir() + run, _ = calibrate( + exact_root, + device=device, + target_override=np.stack( + [ + pixel_gaussian(15, 7, 7, width) + for width in np.linspace(0.9, 1.7, 12) + ], + axis=-1, + ), + ) + arrays, truth = make_data(seed) + arrays["psfs"] = np.load(run.run_dir / "artifacts/psfs.npy") + arrays["images"] = truth["expectation"][None].copy() + perfect_result = run_case( + root / "perfect-factorization", + arrays, + truth, + device=device, + iterations=iterations, + reference_sigma=0.55, + ) + finite_calibration = [] + for index in range(2 if quick else 50): + draw_root = calibration_root / f"draw-{index:03}" + draw_root.mkdir() + run, measured = calibrate( + draw_root, + seed=calibration_seed + index, + device=device, + ) + arrays, truth = make_data(seed) + arrays["images"] = truth["expectation"][None].copy() + arrays["psfs"] = np.load(run.run_dir / "artifacts/psfs.npy") + result = run_case( + draw_root / "scene", + arrays, + truth, + device=device, + iterations=iterations, + reference_sigma=0.55, + ) + for method in ("l2", "huber"): + for measured, reference in zip( + result[method]["sources"], + perfect_result[method]["sources"], + strict=True, + ): + measured["calibration_flux_error_increment"] = ( + measured["fractional_flux_error"] + - reference["fractional_flux_error"] + ) + finite_calibration.append(result) + write_json( + calibration_root / "finite-calibration.json", finite_calibration + ) + print(f"Calibration draw {index + 1}", flush=True) + write_json(calibration_root / "diagnostics.json", calibration_report) + hashes = { + p.relative_to(root).as_posix(): hashlib.sha256( + p.read_bytes() + ).hexdigest() + for p in root.rglob("page.npz") + } + write_json(root / "page-hashes.json", hashes) + return paired_summary(trials) diff --git a/examples/model-scene/tests/test_measure.py b/examples/model-scene/tests/test_measure.py new file mode 100644 index 00000000..341b4f88 --- /dev/null +++ b/examples/model-scene/tests/test_measure.py @@ -0,0 +1,92 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Tests for failure modes in scientific comparison, rather than snapshots.""" + +import sys +from pathlib import Path + +import numpy as np + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from experiment import forward_prediction +from measure import paired_summary +from scene import generate + + +def test_independent_renderer_discrepancy_is_visible(): + physical, p = generate(19) + discrete, d = generate(19, matched=True) + # Independent generation must not accidentally reuse solver convolution. + delta = p["expectation"][12:60, 12:60] - d["expectation"][12:60, 12:60] + assert np.max(np.abs(delta)) > 1 + # The same Gaussian noise is paired even across renderer controls. + np.testing.assert_allclose( + physical["images"][0] - p["expectation"], + discrete["images"][0] - d["expectation"], + atol=2e-14, + ) + + +def test_valid_forward_prediction_uses_real_halo(): + arrays, truth = generate(9, matched=True) + full = truth["truth"][5:-5, 5:-5] + prediction = forward_prediction(full, arrays["psfs"]) + assert prediction.shape == (96, 96, 12) + np.testing.assert_allclose( + prediction, truth["expectation"][12:-12, 12:-12], atol=1e-12 + ) + + +def test_uncertainty_uses_independent_realizations(): + trials = [] + for noise in [-0.02, -0.01, 0.01, 0.02]: + trials.append( + { + m: { + "sources": [ + { + "kind": kind, + "input_flux": 1000, + "fractional_flux_error": noise + offset, + } + for kind in ("isolated", "blend", "extended") + ] + } + for m, offset in [("coadd", 0), ("l2", 0.01), ("huber", 0.02)] + } + ) + result = paired_summary(trials) + assert result["l2"]["isolated"]["n_independent_noise_realizations"] == 4 + assert result["l2"]["isolated"]["bias_standard_error"] > 0.005 + assert ( + result["l2"]["paired_difference_vs_coadd"]["standard_error"] < 1e-15 + ) + + +def test_truth_reconstruction_has_zero_error_for_matched_operator(): + from measure import evaluate + + arrays, truth = generate(1005, development=True, matched=True) + arrays["images"] = truth["expectation"][None].copy() + latent = truth["truth"][5:-5, 5:-5] + measured, _, _ = evaluate(arrays, truth, {"l2": latent, "huber": latent}) + assert ( + max( + abs(s["fractional_flux_error"]) for s in measured["l2"]["sources"] + ) + < 1e-12 + ) + assert max(measured["l2"]["prediction_mse_by_frame"]) < 1e-24 + + +def test_primary_evaluation_refuses_insufficient_context(): + import pytest + from measure import evaluate + + arrays, truth = generate(1005, compact=True) + truth["boundary_failure"] = False + latent = truth["truth"][5:-5, 5:-5] + with pytest.raises(ValueError, match="Insufficient fitting context"): + evaluate(arrays, truth, {"l2": latent}) diff --git a/examples/model-scene/tests/test_run.py b/examples/model-scene/tests/test_run.py new file mode 100644 index 00000000..6961cc2c --- /dev/null +++ b/examples/model-scene/tests/test_run.py @@ -0,0 +1,144 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Execution receipts must retain lock failures and reject changed sources.""" + +import json +import subprocess +import sys +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import run as runner + + +@pytest.fixture +def source_tree(tmp_path, monkeypatch): + repo = tmp_path / "repo" + here = repo / "examples/model-scene" + here.mkdir(parents=True) + source = repo / "src/cuphoton/__init__.py" + source.parent.mkdir(parents=True) + source.write_text("# package source\n") + (here / "scene.py").write_text("# frozen science\n") + (here / "protocol.json").write_text( + json.dumps( + dict( + frozen=True, + development_seeds=[1000], + test_seed_start=3000, + calibration_seed_start=5000, + noise_realizations=50, + science_source_hashes={ + "scene.py": runner.digest(here / "scene.py") + }, + ) + ) + ) + subprocess.run(["git", "init", "-q", str(repo)], check=True) + for key, value in ( + ("user.name", "Test"), + ("user.email", "test@example.com"), + ): + subprocess.run(["git", "config", key, value], cwd=repo, check=True) + subprocess.run(["git", "add", "."], cwd=repo, check=True) + subprocess.run( + ["git", "-c", "commit.gpgsign=false", "commit", "-qm", "Fixture"], + cwd=repo, + check=True, + ) + monkeypatch.setattr(runner, "HERE", here) + monkeypatch.setattr(runner.cuphoton, "__file__", str(source)) + monkeypatch.setattr(runner, "version", lambda name: "test") + return repo, source + + +@pytest.mark.parametrize("failure", ["lock_open", "source_edit"]) +def test_failure_before_science_retains_receipt( + source_tree, tmp_path, monkeypatch, failure +): + _, source = source_tree + output = tmp_path / "output" + lock = ( + tmp_path / "missing/lock" + if failure == "lock_open" + else tmp_path / "lock" + ) + monkeypatch.setattr( + sys, + "argv", + [ + "run.py", + "--output", + str(output), + "--profile", + "reference", + "--gpu-lock", + str(lock), + ], + ) + + def edit_while_waiting(*args): + source.write_text("# changed while waiting for the GPU lock\n") + + monkeypatch.setattr(runner.fcntl, "flock", edit_while_waiting) + error = FileNotFoundError if failure == "lock_open" else RuntimeError + with pytest.raises(error): + runner.main() + receipt = json.loads((output / "execution.json").read_text()) + assert receipt["completed"] is False + assert receipt["error_type"] == error.__name__ + assert receipt["source_tree_clean"] is (failure == "lock_open") + assert not (output / "controls-cpu").exists() + + +def test_source_guard_rejects_clean_revision_change(source_tree): + repo, source = source_tree + receipt = { + "profile": "reference", + "source_revision": subprocess.check_output( + ["git", "rev-parse", "HEAD"], cwd=repo, text=True + ).strip(), + } + source.write_text("# new committed package source\n") + subprocess.run(["git", "add", "."], cwd=repo, check=True) + subprocess.run( + [ + "git", + "-c", + "commit.gpgsign=false", + "commit", + "-qm", + "Changed source", + ], + cwd=repo, + check=True, + ) + with pytest.raises(RuntimeError, match="Source revision changed"): + runner.check_source(repo, receipt) + assert receipt["source_tree_clean"] is True + + +def test_notebook_timeout_stops_and_cleans_the_kernel(): + import nbformat + from nbclient.exceptions import CellTimeoutError + + notebook = nbformat.v4.new_notebook( + cells=[nbformat.v4.new_code_cell("import time; time.sleep(30)")] + ) + manager = runner.AsyncKernelManager(kernel_name="python3") + manager.kernel_spec.argv = [ + sys.executable, + "-m", + "ipykernel_launcher", + "-f", + "{connection_file}", + ] + client = runner.NotebookClient(notebook, km=manager, timeout=1) + with pytest.raises(CellTimeoutError): + client.execute(cleanup_kc=True) + assert not manager.has_kernel + assert client.kc is None diff --git a/examples/model-scene/tests/test_scene.py b/examples/model-scene/tests/test_scene.py new file mode 100644 index 00000000..ee888fda --- /dev/null +++ b/examples/model-scene/tests/test_scene.py @@ -0,0 +1,90 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Numerical contracts that could invalidate scene inference.""" + +import sys +from pathlib import Path + +import numpy as np +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from scene import ( + Source, + generate, + kernels, + pixel_gaussian, + render, + write_bundle, +) + + +def test_integrated_flux_centroid_and_width(): + image = pixel_gaussian(101, 50, 50, 2) + y, x = np.indices(image.shape) + assert image.sum() == pytest.approx(1, abs=1e-13) + assert (image * x).sum() == pytest.approx(50) + assert (image * y).sum() == pytest.approx(50) + assert (image * (x - 50) ** 2).sum() == pytest.approx( + 4 + 1 / 12, abs=1e-6 + ) + + +def test_independent_convolution_against_quadrature(): + from scipy.integrate import quad + + source = Source(18.3, 17.8, 100, 1.2, "control") + image = render([source], sigma=1.4, size=40, background=0) + width = np.hypot(1.2, 1.4) + + def integral(center, pixel): + return quad( + lambda t: ( + np.exp(-((t - center) ** 2) / (2 * width**2)) + / (np.sqrt(2 * np.pi) * width) + ), + pixel - 0.5, + pixel + 0.5, + )[0] + + assert image[18, 19] == pytest.approx( + 100 * integral(source.x, 19) * integral(source.y, 18), rel=1e-12 + ) + + +def test_bundle_axes_mask_polarity_and_noise_pairing(): + arrays, _ = generate(101, case="outliers") + assert arrays["images"].shape == (1, 120, 120, 12) + assert arrays["psfs"].shape == (15, 15, 1, 12) + assert arrays["masks"].dtype == bool + assert np.all(arrays["variances"] > 0) + clean, _ = generate(101) + good = arrays["masks"] + np.testing.assert_array_equal( + arrays["images"][good], clean["images"][good] + ) + assert np.all(arrays["images"][~good] - clean["images"][~good] > 99) + np.testing.assert_allclose(arrays["psfs"].sum(axis=(0, 1)), 1) + + +def test_real_border_context_and_refuse_overwrite(tmp_path): + arrays, _ = generate(5) + # The 96-pixel fitting ROI retains real support for the radius-7 PSF. + assert (120 - 96) // 2 > kernels([1.7]).shape[0] // 2 + assert np.all(arrays["images"][:, :7].std(axis=-1) > 0) + destination = tmp_path / "bundle" + write_bundle(destination, arrays) + with pytest.raises(FileExistsError): + write_bundle(destination, arrays) + + +@pytest.mark.parametrize("bad", [0, -1, float("nan"), float("inf")]) +def test_invalid_variance_refused_before_writes(tmp_path, bad): + arrays, _ = generate(5) + arrays["variances"][0, 20, 20, 0] = bad + destination = tmp_path / "invalid" + with pytest.raises(ValueError, match="finite and positive"): + write_bundle(destination, arrays) + assert not destination.exists() diff --git a/examples/model-scene/views.py b/examples/model-scene/views.py new file mode 100644 index 00000000..ca42d998 --- /dev/null +++ b/examples/model-scene/views.py @@ -0,0 +1,205 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Browser adapters over data-only primitives in the public xScan source.""" + +import numpy as np +from bokeh.events import Tap +from bokeh.layouts import column, row +from bokeh.models import ( + ColumnDataSource, + CustomJS, + Div, + LinearColorMapper, + Range1d, + Select, +) +from bokeh.palettes import Greys256, RdBu11 + +from cuphoton.xscan.raw_compare_review import ( + _image_figure, + _image_payload, + _pixel_inspector_callback, + _pixel_label_source, +) + + +def linked_panels(cases, labels, *, signed=(), units="electrons / exposure"): + """Select saved experiments, retaining shared zoom, taps and raw values. + + ``cases`` maps each explicit precomputed experiment name to a sequence + of equally shaped numeric images. Display bounds stay fixed across cases. + No paths, fixtures, server callbacks, or implicit data loading are used. + """ + names = list(cases) + images = list(cases.values()) + shape = np.asarray(images[0][0]).shape + if any(np.asarray(a).shape != shape for group in images for a in group): + raise ValueError("Linked panels need identical array shapes") + height, width = shape + xr, yr = Range1d(0, width), Range1d(0, height) + selection = ColumnDataSource(dict(x=[], y=[], width=[], height=[])) + sources, mappers, annotations, plots, banks = [], [], [], [], [] + unsigned_values = np.concatenate( + [ + np.asarray(group[i]).ravel() + for group in images + for i in range(len(labels)) + if i not in signed + ] + ) + shared_low, shared_high = ( + float(unsigned_values.min()), + float(unsigned_values.max()), + ) + payload_cache = {} + for index, label in enumerate(labels): + payloads = [] + for group in images: + key = id(group[index]) + if key not in payload_cache: + payload_cache[key] = _image_payload(group[index]) + payloads.append(payload_cache[key]) + source = ColumnDataSource(payloads[0]) + bank = ColumnDataSource( + { + key: [payload[key][0] for payload in payloads] + for key in payloads[0] + } + ) + values = np.concatenate( + [np.asarray(group[index]).ravel() for group in images] + ) + if index in signed: + bound = float(np.max(np.abs(values))) or 1 + mapper = LinearColorMapper(palette=RdBu11, low=-bound, high=bound) + else: + mapper = LinearColorMapper( + palette=Greys256, + low=shared_low, + high=shared_high, + ) + annotation = _pixel_label_source() + plot = _image_figure( + f"{label} [{units}]", + source, + mapper, + selection, + annotation, + shared_x_range=xr, + shared_y_range=yr, + stamp_width=width, + stamp_height=height, + ) + plot.name = f"model-scene-panel-{index}" + sources.append(source) + banks.append(bank) + mappers.append(mapper) + annotations.append(annotation) + plots.append(plot) + inspector = _pixel_inspector_callback( + labels=labels, + sources=sources, + mappers=mappers, + label_sources=annotations, + selection_source=selection, + stamp_width=width, + stamp_height=height, + ) + for plot in plots: + plot.js_on_event(Tap, inspector) + selector = Select( + title="Precomputed experiment", value=names[0], options=names + ) + selector.js_on_change( + "value", + CustomJS( + args=dict( + names=names, + sources=sources, + banks=banks, + annotations=annotations, + selection=selection, + ), + code=""" +selection.data = {x:[],y:[],width:[],height:[]}; +const i = names.indexOf(cb_obj.value); +for (let j=0; j { + const flat=source.data.flat[0]; + const value=typeof flat.get === 'function' + ? flat.get(index) : flat[index]; + return labels[i]+': '+Number(value).toString(); + }); + const lines=['Pixel ('+col+', '+row+')', ...values]; + exact.text=''+ + lines.join(String.fromCharCode(10))+''; +} +""", + ), + ) + return column( + Div( + text="

    Pan and zoom are linked. Tap a pixel for exact saved " + "values. Selection changes show saved experiments.

    " + ), + row(selector, display_range), + row(*plots, sizing_mode="stretch_width"), + exact, + )