Skip to content

Author a Python example

Keep an ordinary Python script as the only maintained executable source. Use # %% for code sections and # %% [markdown] for explanatory comments. The source remains downloadable and executable with Python.

From the repository root, in the development Python environment:

Terminal window
python scripts/docs_examples.py refresh distributions
python scripts/docs_examples.py refresh condensation
python scripts/docs_examples.py refresh gpu-coagulation

The CUDA example requires CUDA and never falls back to CPU. A refresh runs in a fresh kernel with temporary working storage and captures figures, text and explicitly declared compact numerical plot data. Outputs live directly in website/results/EXAMPLE_KEY/: manifest.json, source.py, figures, and optional data.json. There are no timestamped run folders or pointer files. Figure filenames use their order within the code section, independent of log message counts. Git preserves earlier versions. Failed execution or rendering keeps the previous successful bundle. Review and commit the bundle together with source changes.

For a plotting-only change, reuse numerical data instead of rerunning physics:

Terminal window
python scripts/docs_examples.py replot gpu-environment-sweep
python scripts/docs_examples.py migrate-results # one-time legacy layout migration

Replottable examples separate simulate() from plot_results(report). The registry declares data_expression, replot_invoke, render_functions and plot_inputs. Only pure rendering functions/helpers belong in these exclusions: they must not change scientific parameters, processes or diagnostics. Replot checks saved-file hashes, the simulation fingerprint and library hash; changes to simulation code or inputs require a full refresh. It executes the renderer on CPU, without requiring CUDA or advancing a simulation. It preserves the original execution timestamp, device, revision and versions, and records rendering time/revision separately. executed_source.py preserves the original source when the renderer changes. Missing numerical data requires one data-saving refresh; images and printed endpoint tables cannot recover missing histories.

The execution banner displays the original script’s elapsed wall time from elapsed_seconds, never render_elapsed_seconds. This measures the complete original execution, including setup and any plotting within that script; it is not an isolated physics-kernel benchmark. Replotting preserves this duration.

Save compact plotted summaries: observation times, counts, histogram bins, quantiles and the settings needed to interpret them. Do not save full particle states, checkpoints, trajectories or unused diagnostics. The serialized numeric JSON has a 10 MiB hard limit per example, enforced while writing. This limits saved plot data, not simulation RAM or figure size. Oversized data fails clearly and preserves the previous successful bundle; it is never silently truncated.

Terminal window
python scripts/docs_examples.py check --changed --base upstream/main

Changed CPU examples execute for validation without replacing publication results. After a plotting-only replot, validation reuses saved data and does not repeat the simulation. Declared CUDA or long-running examples report an explicit execution skip. Syntax, saved-file integrity, and freshness are checked for every example. Use --base with the pull request base revision in CI.

The example registry declares its source, execution policy, device, timeout, optional invocation, and input/helper files. Executable changes and declared input bytes invalidate rendered results; plotting-only changes can be replotted from compatible saved data. Ordinary prose changes do not invalidate results. Changes inside Particula still need the existing scientific tests and a deliberate result refresh when appropriate. The recorded library revision remains visible.

Terminal window
npm --prefix website run build
npm --prefix website run preview

Pages are generated from current prose/code and saved result bundles. Code is expandable; figures remain visible. Older results are labeled and grouped separately from the updated code. Missing results show an awaiting-results note. Generated Markdown, API dumps, and the built website are disposable outputs.

Starlight is the sole documentation build. Retired MkDocs assets and original notebooks remain in Git history at 4f669de11, recorded as archive_revision in website/migration-inventory.json. They are no longer stored in the checkout. Internal execution uses temporary notebook objects to capture rich outputs, without introducing a second maintained source file.

Keep the scientific library unchanged during a refresh. Publication records its source hash before execution and rejects a different hash afterward, preserving the previous bundle. The reported Particula version comes from that checkout; when installed distribution metadata differs, it is retained separately as particula-distribution rather than used to label the executed source.

Figures are exported at 300 DPI. Captured diagnostics retain repository-relative filenames and line numbers; local account and checkout paths are redacted before saving publication bundles. Terminal progress bars render in closed disclosures.

Published GPU examples use policy: "cuda" and require a real CUDA device. Their deliberate refresh can run longer than the routine ten-minute benchmark guide; the registry declares each timeout. CI checks source and saved-result integrity without executing these studies. A timeout or missing GPU must never produce a replacement CPU result.

Declare every imported local helper and data file in inputs. These bytes participate in freshness checks and are included in the downloadable ZIP with example.py, preserving their relative import paths (or input_destinations). The plain Python download remains available; use the ZIP when helpers or data are needed. Test extracted bundles independently before publication.

website/public/llms.txt is a small curated index published at https://uncscode.github.io/particula/llms.txt. Keep roughly 10–15 direct links to maintained guides, executable Python examples and Particula Helper resources. Prefer https://raw.githubusercontent.com/uncscode/particula/main/ file URLs; use the published API Markdown index for generated API documentation. Do not link archives or generated local files. Raw documents retain repository-relative links.

The index explicitly describes development main. If the site later publishes versioned release documentation, update the index and its verifier together to use matching tags or commits. Keep version guidance visible to readers. The normal build checks the published index and its targets offline against the checkout and built site. After deployment, verify the public index and links separately; a local build does not prove that GitHub Pages has updated.

Use the documentation guide for topic placement and the shared scientific narrative framework. The topic registry is website/topics.json; local SVGs live in website/public/topic-icons/. Preparation validates coverage and generates topic MDX adapters. Do not edit website/src/content/docs/ directly. The offline entry remains maintained in docs/guide/topics/index.md.

Review the opening question, code, figures, and conclusion together. Prose-only pilot revisions retain the original scientific outputs when executable cell fingerprints match. Topic icons are conceptual illustrations, never observations.