ns-blowup 0.1.0__tar.gz

ns_blowup-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — research preview
+
+- Import the design conversation with source provenance.
+- Add a JAX periodic Navier–Stokes library, analytical checks and a friendly simulation API.
+- Implement similarity coordinates, viscosity scaling and heat-exterior quadrature.
+- Add the standalone Singularity Observatory for implemented components and numerical precision experiments.
+- Document scientific scope, unimplemented construction steps, validation and prior work.
+- Configure CI, documentation builds and tag-triggered GitHub releases.
+
+The complete smooth blowup construction is not implemented. No production-speed,
+Blender-integration, formal-verification or near-singularity tracking claim is made.

ns_blowup-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+The flagship is the Singularity Observatory. Favor changes that make the mathematical construction executable, testable, and usable, with a reusable Navier–Stokes API beneath it.
+
+Install with `python -m pip install -e '.[dev,plot]'`, then run `JAX_PLATFORMS=cpu python -m pytest -q`. NVIDIA contributors can also run the suite with `JAX_PLATFORMS=cuda XLA_PYTHON_CLIENT_PREALLOCATE=false`. Never silently treat CPU execution as a successful GPU test.
+
+A numerical contribution should explain the equation, discretization, units, data layout, domain, and failure modes. Cite the primary source near any translated formula. For construction components, name the equation/lemma and pin the source commit. Supply a test that can detect a physically meaningful error: independent derivatives, a different discretization, a conserved quantity, analytic substitution, or a convergence study. Tests duplicating the same formula in two places are insufficient.
+
+Do not label a synthetic concentrating field as the full blowup construction. Do not define forcing as a residual and then use the resulting identity to claim force regularity. Finite tests and upstream proofs establish different facts; keep that distinction in the docs and API.
+
+Keep the simple path short: named examples, clear errors, predictable shapes, and portable results. Add a runnable example for a new public workflow. Avoid global changes to JAX device, precision, or memory settings on import. Changes to saved-data formats require a schema revision and migration/compatibility notes.
+
+Update the README status matrix with measured evidence. Use **Not Yet Tested** when code exists without relevant validation, and **Not Implemented** when it does not exist. A CI workflow is not a passed CI run. Performance claims need fair workloads, completed device execution, separated compilation, memory measurements, and matched error targets.
+
+Before a public release, run the built wheel outside the source checkout, execute the documented examples, inspect the observatory in a browser, and have a human reviewer assess the scientific claims and release notes.

ns_blowup-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 ns-blowup contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This license covers original project code and documentation. The imported
+conversation in docs/conversation.md and docs/conversation.json, and referenced
+third-party works, retain their respective rights and are not relicensed here.

ns_blowup-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE README.md CHANGELOG.md CONTRIBUTING.md
+recursive-include src/ns_blowup/assets *.html
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include scripts *.py
+recursive-include docs *.md *.py *.txt *.json *.html

ns_blowup-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: ns-blowup
+Version: 0.1.0
+Summary: Differentiable JAX Navier–Stokes simulation and analytical validation
+License-Expression: MIT
+Project-URL: Repository, https://github.com/james-coder/navier-stokes-blowup
+Project-URL: Documentation, https://github.com/james-coder/navier-stokes-blowup/tree/main/docs
+Project-URL: Issues, https://github.com/james-coder/navier-stokes-blowup/issues
+Project-URL: Changelog, https://github.com/james-coder/navier-stokes-blowup/blob/main/CHANGELOG.md
+Keywords: navier-stokes,fluid-dynamics,jax,differentiable-simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax>=0.11.1
+Requires-Dist: numpy>=1.26
+Provides-Extra: cuda12
+Requires-Dist: jax[cuda12]>=0.11.1; extra == "cuda12"
+Provides-Extra: cuda13
+Requires-Dist: jax[cuda13]>=0.11.1; extra == "cuda13"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ns-blowup
+
+**A Navier–Stokes library with one flagship: the Singularity Observatory.**
+
+The aim is to make a new mathematical construction something people can inspect, evaluate, and eventually use to challenge numerical solvers. A friendly Python API provides the simulation and diagnostics underneath it.
+
+**Version 0.1.0 is a research preview.** The library runs real 2D/3D periodic simulations and evaluates specific components of OpenAI’s published construction. **The complete smooth blowup solution is Not Implemented.** This release does not yet support the claim that it reproduces the theorem or enables previously impossible fluid simulation.
+
+[Open the observatory](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/observatory.html) · [Getting started](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/tutorial.md) · [API](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/api.md) · [Research and implementation gaps](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/research.md) · [Original conversation](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/conversation.md)
+
+## The flagship application
+
+**“How close to a known singularity can a numerical solver remain accurate—and why does it fail?”**
+
+That is the question the completed Singularity Observatory should answer. OpenAI’s paper supplies the motivating construction; its accompanying repository contains Lean formalizations. These are mathematical sources, not a ready-made GPU fluid solver. [Paper](https://cdn.openai.com/pdf/32d9f210-8b73-45e0-91bc-82a30aef8a9a/navier-stokes.pdf), [formalization](https://github.com/openai/NavierStokesAndEuler/tree/8937a8f4cbc7abaab5e9e97d1cc7f5d2319d9538).
+
+The **working preview** lets you:
+
+- Move toward the singular time and inspect the similarity-coordinate geometry.
+- Compare normalized velocity and core-energy scaling.
+- Change a hypothetical grid resolution and see its spatial coverage.
+- Inspect an actual FP32/FP64 refinement experiment for the outer heat-flow component.
+- Download every numerical dataset behind the display.
+
+The geometry sampling threshold is a heuristic. The scaling plots are not measured norms of a completed blowup solution. The heat exterior is valid away from the axis and is itself singular on the axis at all times; it must not be used as smooth initial data for a purported blowup reproduction. The implementation boundary follows equations (3.2), (4.1), and Lemma A.6 of the [paper](https://cdn.openai.com/pdf/32d9f210-8b73-45e0-91bc-82a30aef8a9a/navier-stokes.pdf).
+
+To use the checked-in app, download/open `docs/observatory.html` in a browser. GitHub’s file viewer displays its source. The app is standalone: no server, account, CDN, or Python installation is needed to view it. To regenerate it:
+
+```bash
+python -m ns_blowup.observatory --output outputs/observatory.html
+```
+
+Its data are also saved as `outputs/observatory.json`. The intended mature application and its acceptance criteria are described in [the roadmap](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/roadmap.md).
+
+## Install
+
+Requires **Python 3.12+**. Install the research preview from [PyPI](https://pypi.org/project/ns-blowup/):
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install 'ns-blowup[plot]==0.1.0'
+```
+
+For an NVIDIA GPU on Linux/WSL2:
+
+```bash
+python -m pip install 'ns-blowup[cuda12,plot]==0.1.0'
+export XLA_PYTHON_CLIENT_PREALLOCATE=false
+```
+
+CUDA 12 was exercised on the local RTX 4090. A `cuda13` extra is provided but **Not Yet Tested**. Driver/platform requirements come from the [JAX installation guide](https://docs.jax.dev/en/latest/installation.html). Disabling preallocation helps when sharing a GPU; it does not make an oversized calculation fit in memory. See [JAX GPU memory allocation](https://docs.jax.dev/en/latest/gpu_memory_allocation.html).
+
+For development, clone this repository and run `python -m pip install -e '.[dev,plot]'` from its root.
+
+## Your first simulation
+
+```python
+from ns_blowup import Simulation
+
+result = Simulation((32, 32), nu=0.05).run(
+    initial="taylor-green",
+    t_end=1.0,
+    frames=21,
+)
+
+result.plot(quantity="vorticity", path="outputs/vorticity.png")
+result.save("outputs/flow.npz")
+print(result.diagnostics()["energy"])
+```
+
+`Simulation` chooses a JAX device, projects the initial velocity, adapts the timestep, checks for nonfinite states, and returns uniformly timed snapshots. `result.final` is the last velocity field. No array-layout knowledge is needed for the built-in examples.
+
+For a genuinely three-dimensional exact benchmark:
+
+```python
+result = Simulation((24, 24, 24), nu=0.02).run("abc", t_end=0.5)
+result.export_vtk("outputs/final.vtk")
+```
+
+Or run the CLI:
+
+```bash
+python -m ns_blowup --dim 3 --flow abc --resolution 24 --time 0.5 --plot
+```
+
+The CLI writes `flow.npz`, `final.vtk`, and `diagnostics.json` to `outputs/demo/`. VTK exports follow the structured-points layout with x varying fastest. [VTK file-format documentation](https://docs.vtk.org/en/latest/vtk_file_formats/vtk_legacy_file_format.html).
+
+## Analytical evaluation and numerical checks
+
+```python
+import jax.numpy as jnp
+from ns_blowup import ABCFlow, FieldDiagnostics
+
+flow = ABCFlow(nu=0.01)
+points = jnp.array([[0.2, 0.4, 0.6], [1.0, 2.0, 3.0]])
+checks = FieldDiagnostics(flow.velocity, flow.pressure, flow.nu, flow.forcing)
+
+velocity = flow.velocity(points, 0.3)
+vorticity = checks.vorticity(points, 0.3)
+residual = checks.residual(points, 0.3)
+divergence = checks.divergence(points, 0.3)
+```
+
+The momentum residual is
+
+```text
+R = ∂t u + (u · ∇)u + ∇p − ν Δu − f
+```
+
+Pointwise checks differentiate field callbacks independently of the spectral solver. Tests include wrong-pressure/wrong-force controls so a residual that always returns zero would fail. The implemented exact flows are documented with their formulas in [the numerical-methods note](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/numerics.md).
+
+## Differentiable simulation
+
+The lower-level API composes with `jax.jit`, `jax.grad`, and `jax.vmap`:
+
+```python
+import jax
+from ns_blowup import PeriodicGrid, SpectralSolver, TaylorGreen, kinetic_energy
+
+grid = PeriodicGrid((16, 16))
+solver = SpectralSolver(grid, nu=0.05)
+u0 = TaylorGreen(nu=0.05).velocity(grid.points(), 0.0)
+
+def final_energy(amplitude):
+    final = solver.integrate(amplitude * u0, dt=0.01, steps=50)
+    return kinetic_energy(final, grid)
+
+d_energy_d_amplitude = jax.jit(jax.grad(final_energy))(1.0)
+```
+
+[The forcing-optimization example](https://github.com/james-coder/navier-stokes-blowup/blob/main/examples/optimize_forcing.py) infers a scalar forcing amplitude through the numerical evolution. It is a small reproducible inverse problem, not evidence of globally optimal engineering designs. Differentiable CFD predates this project and the cited blowup result: see [JAX-Fluids](https://arxiv.org/abs/2203.13760) and [PhiFlow](https://github.com/tum-pbs/PhiFlow).
+
+## What works, and what does not
+
+“Tested” means the listed checks passed in this checkout on the recorded environment, not that all physical regimes are validated.
+
+| Capability | Status | Evidence / limit |
+|---|---|---|
+| 2D/3D periodic, constant-density incompressible flow | Tested | Projection, analytic decay, forced nonlinear flow, energy identity |
+| JAX CPU / NVIDIA CUDA 12 execution | Tested | Local CPU and RTX 4090 reports below; small grids |
+| FP32 and FP64 | Tested | Precision-specific numerical reports; FP64 needs x64 enabled |
+| Fourth-order time convergence | Tested | Timestep refinement on a resolved analytic flow |
+| Nonlinear dealiasing | Tested | Comparison against a 4× finer grid and inviscid energy production |
+| Gradients through initial amplitude and forcing | Tested | Analytic derivative and centered finite-difference comparison |
+| Adaptive convenience API, plots, NPZ round-trip | Tested | Workflow tests and executed examples |
+| VTK writer | Tested: format/order | **Not Yet Tested** in the ParaView GUI |
+| Similarity coordinates / viscosity rescaling | Tested: component identities | Implicit derivatives and equation residuals |
+| Heat exterior | Tested: bounded sample ranges | Independent adaptive quadrature and momentum/heat residuals |
+| Observatory browser controls and responsive layout | Tested in Chromium | Desktop/mobile viewport, sliders, animation, no JS errors |
+| Full smooth blowup construction | **Not Implemented / Not Yet Tested** | Missing inner profiles, matching, pulses, corrections, localization |
+| Formal certification of Python results | **Not Yet Tested** | Lean build and Comparator were not run here |
+| Near-singularity solver tracking | **Not Yet Tested** | Needs complete executable field and certified truncation control |
+| CUDA 13, AMD, Apple GPU, TPU, multi-GPU | **Not Yet Tested** | No hardware/runtime validation here; multi-GPU API not implemented |
+| Large turbulent production cases / arbitrary precision | **Not Yet Tested** | No production qualification; arbitrary-precision backend not implemented |
+| Walls, obstacles, free surfaces, FLIP/APIC, smoke/fire | **Not Implemented** | Current domain is periodic and single-phase |
+| Blender add-on / OpenVDB exporter | **Not Implemented / Not Yet Tested** | Integration research only |
+| Speedup over Blender or other CFD packages | **Not Yet Tested** | No comparative benchmark or speed claim |
+| Hosted CI | Configured; see [live runs](https://github.com/james-coder/navier-stokes-blowup/actions/workflows/ci.yml) | CPU tests, docs and distribution builds; CUDA remains locally tested |
+| Tag-triggered releases / PyPI | Automated validation and Trusted Publishing | Check the [release run](https://github.com/james-coder/navier-stokes-blowup/actions/workflows/release.yml) for publication status |
+
+## Reproducible validation
+
+```bash
+JAX_PLATFORMS=cpu python -m pytest -q
+XLA_PYTHON_CLIENT_PREALLOCATE=false JAX_PLATFORMS=cuda python -m pytest -q
+JAX_PLATFORMS=cpu python scripts/validate.py --output outputs/validation-cpu.json
+XLA_PYTHON_CLIENT_PREALLOCATE=false JAX_PLATFORMS=cuda \
+  python scripts/validate.py --output outputs/validation-gpu.json
+python examples/quickstart.py
+python examples/optimize_forcing.py
+```
+
+**Final local test runs: 34 passed on CPU and 34 passed on CUDA (2026-09-10).**
+
+Recorded environments and measurements: [CPU](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/validation-cpu.json), [GPU](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/validation-gpu.json), [validation explanation](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/validation.md). Tests enable x64 within the test process. The installed library never enables global x64 or memory preallocation on import.
+
+The reports separate compilation from repeated execution and wait for device completion. That follows [JAX’s benchmarking guidance](https://docs.jax.dev/en/latest/benchmarking.html). These small checks, on an occupied GPU, are **not** a fair performance ranking.
+
+## Numerical scope
+
+The current solver uses periodic Fourier differentiation, a pressure projection, strict two-thirds truncation, and explicit RK4. It solves in physical units chosen consistently by the caller; `nu` is kinematic viscosity and pressure is per unit density. The default box has side length `2π`.
+
+Periodic spectral methods are an established route for this problem; [Mortensen and Langtangen (2016)](https://arxiv.org/abs/1602.03638) and [spectralDNS](https://github.com/spectralDNS/spectralDNS) provide important prior art. Our choices and independent tests are described in [Numerics](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/numerics.md).
+
+Use `JAX_ENABLE_X64=1` and `dtype="float64"` for tighter numerical checks. FP64 is not arbitrary precision. See [JAX’s default-dtype documentation](https://docs.jax.dev/en/latest/default_dtypes.html). The convenience API checks timestep estimates on the host; use `SpectralSolver.integrate` for compiled fixed-step loops and differentiation. An adaptive timestep cannot rescue inadequate spatial resolution.
+
+## Position among existing libraries
+
+| Need today | Existing project worth examining | This project’s role |
+|---|---|---|
+| Differentiable simulation with multiple ML backends | [PhiFlow](https://github.com/tum-pbs/PhiFlow) | Construction-focused evaluation and an approachable periodic solver |
+| Compressible and two-phase differentiable CFD | [JAX-Fluids](https://arxiv.org/abs/2203.13760) | Different equation/domain scope; those features are not implemented here |
+| Distributed pseudospectral DNS | [spectralDNS](https://github.com/spectralDNS/spectralDNS) | Single-device JAX reference and diagnostics |
+| Historical JAX finite-volume/spectral research | [JAX-CFD](https://github.com/google/jax-cfd) | Useful prior art; its README now states it is no longer maintained |
+| Mathematical certificates for the new result | [NavierStokesAndEuler](https://github.com/openai/NavierStokesAndEuler) | Numerical component evaluation, not a substitute for proof checking |
+
+Becoming a widely trusted library requires reliable examples, stable interfaces, independent validation, documented failure modes, and sustained maintenance. That is the development direction, not a release claim.
+
+## NVIDIA Warp and Read the Docs
+
+**Warp:** a promising optional kernel backend, with no performance claim yet. Keep the JAX reference and evaluate targeted kernels first; Warp’s JAX autodiff integration has documented restrictions. [Warp JAX interoperability](https://nvidia.github.io/warp/stable/user_guide/interoperability/jax.html).
+
+**Read the Docs:** configuration and a Sphinx/MyST site are included. The local build is tested; hosted deployment is **Not Yet Tested / Not Connected**. [Build instructions and assessment](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/platforms.md), [Read the Docs Sphinx guide](https://docs.readthedocs.com/platform/stable/intro/sphinx.html).
+
+## Blender
+
+Blender remains a possible presentation frontend for the flagship, rather than the initial killer application. Blender documents OpenVDB volume sequences and Mantaflow cache/script workflows. This repository currently exports NPZ and VTK; it has **no Blender cache integration**. [Blender volume objects](https://docs.blender.org/manual/en/4.5/modeling/volumes/introduction.html), [fluid cache](https://docs.blender.org/manual/en/4.5/physics/fluid/type/domain/cache.html), [OpenVDB Python API](https://www.openvdb.org/documentation/doxygen/python.html).
+
+## Builds and releases
+
+GitHub Actions tests Python 3.12/3.13, builds the documentation, builds and checks wheel/source distributions, and exercises the installed wheel. Matching `v*` tags run the same validation before publishing to PyPI through Trusted Publishing, then attaching the same distributions, documentation, and checksums to a GitHub Release. No stored PyPI API token is needed. See [the release workflow](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/releases.md) and [PyPI's Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/using-a-publisher/). Read the Docs hosting is not connected.
+
+## Sources and provenance
+
+The shared conversation was extracted with the existing `chatgpt-import-share` checkout. The [Markdown transcript](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/conversation.md), [structured export](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/conversation.json), and [source manifest](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/source-manifest.json) preserve provenance and redacted/unavailable-message markers. The conversation is a design input, not independent evidence for its claims.
+
+The manifest pins the inspected Lean commit and records the paper hash. Read the [research note](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/research.md) and [annotated sources](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/sources.md) for the implementation decisions and unresolved questions. [Contributing](https://github.com/james-coder/navier-stokes-blowup/blob/main/CONTRIBUTING.md) describes the evidence required for new features. Code is MIT licensed; the imported conversation and referenced third-party works retain their respective rights.

ns_blowup-0.1.0/README.md

@@ -0,0 +1,218 @@
+# ns-blowup
+
+**A Navier–Stokes library with one flagship: the Singularity Observatory.**
+
+The aim is to make a new mathematical construction something people can inspect, evaluate, and eventually use to challenge numerical solvers. A friendly Python API provides the simulation and diagnostics underneath it.
+
+**Version 0.1.0 is a research preview.** The library runs real 2D/3D periodic simulations and evaluates specific components of OpenAI’s published construction. **The complete smooth blowup solution is Not Implemented.** This release does not yet support the claim that it reproduces the theorem or enables previously impossible fluid simulation.
+
+[Open the observatory](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/observatory.html) · [Getting started](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/tutorial.md) · [API](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/api.md) · [Research and implementation gaps](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/research.md) · [Original conversation](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/conversation.md)
+
+## The flagship application
+
+**“How close to a known singularity can a numerical solver remain accurate—and why does it fail?”**
+
+That is the question the completed Singularity Observatory should answer. OpenAI’s paper supplies the motivating construction; its accompanying repository contains Lean formalizations. These are mathematical sources, not a ready-made GPU fluid solver. [Paper](https://cdn.openai.com/pdf/32d9f210-8b73-45e0-91bc-82a30aef8a9a/navier-stokes.pdf), [formalization](https://github.com/openai/NavierStokesAndEuler/tree/8937a8f4cbc7abaab5e9e97d1cc7f5d2319d9538).
+
+The **working preview** lets you:
+
+- Move toward the singular time and inspect the similarity-coordinate geometry.
+- Compare normalized velocity and core-energy scaling.
+- Change a hypothetical grid resolution and see its spatial coverage.
+- Inspect an actual FP32/FP64 refinement experiment for the outer heat-flow component.
+- Download every numerical dataset behind the display.
+
+The geometry sampling threshold is a heuristic. The scaling plots are not measured norms of a completed blowup solution. The heat exterior is valid away from the axis and is itself singular on the axis at all times; it must not be used as smooth initial data for a purported blowup reproduction. The implementation boundary follows equations (3.2), (4.1), and Lemma A.6 of the [paper](https://cdn.openai.com/pdf/32d9f210-8b73-45e0-91bc-82a30aef8a9a/navier-stokes.pdf).
+
+To use the checked-in app, download/open `docs/observatory.html` in a browser. GitHub’s file viewer displays its source. The app is standalone: no server, account, CDN, or Python installation is needed to view it. To regenerate it:
+
+```bash
+python -m ns_blowup.observatory --output outputs/observatory.html
+```
+
+Its data are also saved as `outputs/observatory.json`. The intended mature application and its acceptance criteria are described in [the roadmap](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/roadmap.md).
+
+## Install
+
+Requires **Python 3.12+**. Install the research preview from [PyPI](https://pypi.org/project/ns-blowup/):
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install 'ns-blowup[plot]==0.1.0'
+```
+
+For an NVIDIA GPU on Linux/WSL2:
+
+```bash
+python -m pip install 'ns-blowup[cuda12,plot]==0.1.0'
+export XLA_PYTHON_CLIENT_PREALLOCATE=false
+```
+
+CUDA 12 was exercised on the local RTX 4090. A `cuda13` extra is provided but **Not Yet Tested**. Driver/platform requirements come from the [JAX installation guide](https://docs.jax.dev/en/latest/installation.html). Disabling preallocation helps when sharing a GPU; it does not make an oversized calculation fit in memory. See [JAX GPU memory allocation](https://docs.jax.dev/en/latest/gpu_memory_allocation.html).
+
+For development, clone this repository and run `python -m pip install -e '.[dev,plot]'` from its root.
+
+## Your first simulation
+
+```python
+from ns_blowup import Simulation
+
+result = Simulation((32, 32), nu=0.05).run(
+    initial="taylor-green",
+    t_end=1.0,
+    frames=21,
+)
+
+result.plot(quantity="vorticity", path="outputs/vorticity.png")
+result.save("outputs/flow.npz")
+print(result.diagnostics()["energy"])
+```
+
+`Simulation` chooses a JAX device, projects the initial velocity, adapts the timestep, checks for nonfinite states, and returns uniformly timed snapshots. `result.final` is the last velocity field. No array-layout knowledge is needed for the built-in examples.
+
+For a genuinely three-dimensional exact benchmark:
+
+```python
+result = Simulation((24, 24, 24), nu=0.02).run("abc", t_end=0.5)
+result.export_vtk("outputs/final.vtk")
+```
+
+Or run the CLI:
+
+```bash
+python -m ns_blowup --dim 3 --flow abc --resolution 24 --time 0.5 --plot
+```
+
+The CLI writes `flow.npz`, `final.vtk`, and `diagnostics.json` to `outputs/demo/`. VTK exports follow the structured-points layout with x varying fastest. [VTK file-format documentation](https://docs.vtk.org/en/latest/vtk_file_formats/vtk_legacy_file_format.html).
+
+## Analytical evaluation and numerical checks
+
+```python
+import jax.numpy as jnp
+from ns_blowup import ABCFlow, FieldDiagnostics
+
+flow = ABCFlow(nu=0.01)
+points = jnp.array([[0.2, 0.4, 0.6], [1.0, 2.0, 3.0]])
+checks = FieldDiagnostics(flow.velocity, flow.pressure, flow.nu, flow.forcing)
+
+velocity = flow.velocity(points, 0.3)
+vorticity = checks.vorticity(points, 0.3)
+residual = checks.residual(points, 0.3)
+divergence = checks.divergence(points, 0.3)
+```
+
+The momentum residual is
+
+```text
+R = ∂t u + (u · ∇)u + ∇p − ν Δu − f
+```
+
+Pointwise checks differentiate field callbacks independently of the spectral solver. Tests include wrong-pressure/wrong-force controls so a residual that always returns zero would fail. The implemented exact flows are documented with their formulas in [the numerical-methods note](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/numerics.md).
+
+## Differentiable simulation
+
+The lower-level API composes with `jax.jit`, `jax.grad`, and `jax.vmap`:
+
+```python
+import jax
+from ns_blowup import PeriodicGrid, SpectralSolver, TaylorGreen, kinetic_energy
+
+grid = PeriodicGrid((16, 16))
+solver = SpectralSolver(grid, nu=0.05)
+u0 = TaylorGreen(nu=0.05).velocity(grid.points(), 0.0)
+
+def final_energy(amplitude):
+    final = solver.integrate(amplitude * u0, dt=0.01, steps=50)
+    return kinetic_energy(final, grid)
+
+d_energy_d_amplitude = jax.jit(jax.grad(final_energy))(1.0)
+```
+
+[The forcing-optimization example](https://github.com/james-coder/navier-stokes-blowup/blob/main/examples/optimize_forcing.py) infers a scalar forcing amplitude through the numerical evolution. It is a small reproducible inverse problem, not evidence of globally optimal engineering designs. Differentiable CFD predates this project and the cited blowup result: see [JAX-Fluids](https://arxiv.org/abs/2203.13760) and [PhiFlow](https://github.com/tum-pbs/PhiFlow).
+
+## What works, and what does not
+
+“Tested” means the listed checks passed in this checkout on the recorded environment, not that all physical regimes are validated.
+
+| Capability | Status | Evidence / limit |
+|---|---|---|
+| 2D/3D periodic, constant-density incompressible flow | Tested | Projection, analytic decay, forced nonlinear flow, energy identity |
+| JAX CPU / NVIDIA CUDA 12 execution | Tested | Local CPU and RTX 4090 reports below; small grids |
+| FP32 and FP64 | Tested | Precision-specific numerical reports; FP64 needs x64 enabled |
+| Fourth-order time convergence | Tested | Timestep refinement on a resolved analytic flow |
+| Nonlinear dealiasing | Tested | Comparison against a 4× finer grid and inviscid energy production |
+| Gradients through initial amplitude and forcing | Tested | Analytic derivative and centered finite-difference comparison |
+| Adaptive convenience API, plots, NPZ round-trip | Tested | Workflow tests and executed examples |
+| VTK writer | Tested: format/order | **Not Yet Tested** in the ParaView GUI |
+| Similarity coordinates / viscosity rescaling | Tested: component identities | Implicit derivatives and equation residuals |
+| Heat exterior | Tested: bounded sample ranges | Independent adaptive quadrature and momentum/heat residuals |
+| Observatory browser controls and responsive layout | Tested in Chromium | Desktop/mobile viewport, sliders, animation, no JS errors |
+| Full smooth blowup construction | **Not Implemented / Not Yet Tested** | Missing inner profiles, matching, pulses, corrections, localization |
+| Formal certification of Python results | **Not Yet Tested** | Lean build and Comparator were not run here |
+| Near-singularity solver tracking | **Not Yet Tested** | Needs complete executable field and certified truncation control |
+| CUDA 13, AMD, Apple GPU, TPU, multi-GPU | **Not Yet Tested** | No hardware/runtime validation here; multi-GPU API not implemented |
+| Large turbulent production cases / arbitrary precision | **Not Yet Tested** | No production qualification; arbitrary-precision backend not implemented |
+| Walls, obstacles, free surfaces, FLIP/APIC, smoke/fire | **Not Implemented** | Current domain is periodic and single-phase |
+| Blender add-on / OpenVDB exporter | **Not Implemented / Not Yet Tested** | Integration research only |
+| Speedup over Blender or other CFD packages | **Not Yet Tested** | No comparative benchmark or speed claim |
+| Hosted CI | Configured; see [live runs](https://github.com/james-coder/navier-stokes-blowup/actions/workflows/ci.yml) | CPU tests, docs and distribution builds; CUDA remains locally tested |
+| Tag-triggered releases / PyPI | Automated validation and Trusted Publishing | Check the [release run](https://github.com/james-coder/navier-stokes-blowup/actions/workflows/release.yml) for publication status |
+
+## Reproducible validation
+
+```bash
+JAX_PLATFORMS=cpu python -m pytest -q
+XLA_PYTHON_CLIENT_PREALLOCATE=false JAX_PLATFORMS=cuda python -m pytest -q
+JAX_PLATFORMS=cpu python scripts/validate.py --output outputs/validation-cpu.json
+XLA_PYTHON_CLIENT_PREALLOCATE=false JAX_PLATFORMS=cuda \
+  python scripts/validate.py --output outputs/validation-gpu.json
+python examples/quickstart.py
+python examples/optimize_forcing.py
+```
+
+**Final local test runs: 34 passed on CPU and 34 passed on CUDA (2026-09-10).**
+
+Recorded environments and measurements: [CPU](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/validation-cpu.json), [GPU](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/validation-gpu.json), [validation explanation](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/validation.md). Tests enable x64 within the test process. The installed library never enables global x64 or memory preallocation on import.
+
+The reports separate compilation from repeated execution and wait for device completion. That follows [JAX’s benchmarking guidance](https://docs.jax.dev/en/latest/benchmarking.html). These small checks, on an occupied GPU, are **not** a fair performance ranking.
+
+## Numerical scope
+
+The current solver uses periodic Fourier differentiation, a pressure projection, strict two-thirds truncation, and explicit RK4. It solves in physical units chosen consistently by the caller; `nu` is kinematic viscosity and pressure is per unit density. The default box has side length `2π`.
+
+Periodic spectral methods are an established route for this problem; [Mortensen and Langtangen (2016)](https://arxiv.org/abs/1602.03638) and [spectralDNS](https://github.com/spectralDNS/spectralDNS) provide important prior art. Our choices and independent tests are described in [Numerics](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/numerics.md).
+
+Use `JAX_ENABLE_X64=1` and `dtype="float64"` for tighter numerical checks. FP64 is not arbitrary precision. See [JAX’s default-dtype documentation](https://docs.jax.dev/en/latest/default_dtypes.html). The convenience API checks timestep estimates on the host; use `SpectralSolver.integrate` for compiled fixed-step loops and differentiation. An adaptive timestep cannot rescue inadequate spatial resolution.
+
+## Position among existing libraries
+
+| Need today | Existing project worth examining | This project’s role |
+|---|---|---|
+| Differentiable simulation with multiple ML backends | [PhiFlow](https://github.com/tum-pbs/PhiFlow) | Construction-focused evaluation and an approachable periodic solver |
+| Compressible and two-phase differentiable CFD | [JAX-Fluids](https://arxiv.org/abs/2203.13760) | Different equation/domain scope; those features are not implemented here |
+| Distributed pseudospectral DNS | [spectralDNS](https://github.com/spectralDNS/spectralDNS) | Single-device JAX reference and diagnostics |
+| Historical JAX finite-volume/spectral research | [JAX-CFD](https://github.com/google/jax-cfd) | Useful prior art; its README now states it is no longer maintained |
+| Mathematical certificates for the new result | [NavierStokesAndEuler](https://github.com/openai/NavierStokesAndEuler) | Numerical component evaluation, not a substitute for proof checking |
+
+Becoming a widely trusted library requires reliable examples, stable interfaces, independent validation, documented failure modes, and sustained maintenance. That is the development direction, not a release claim.
+
+## NVIDIA Warp and Read the Docs
+
+**Warp:** a promising optional kernel backend, with no performance claim yet. Keep the JAX reference and evaluate targeted kernels first; Warp’s JAX autodiff integration has documented restrictions. [Warp JAX interoperability](https://nvidia.github.io/warp/stable/user_guide/interoperability/jax.html).
+
+**Read the Docs:** configuration and a Sphinx/MyST site are included. The local build is tested; hosted deployment is **Not Yet Tested / Not Connected**. [Build instructions and assessment](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/platforms.md), [Read the Docs Sphinx guide](https://docs.readthedocs.com/platform/stable/intro/sphinx.html).
+
+## Blender
+
+Blender remains a possible presentation frontend for the flagship, rather than the initial killer application. Blender documents OpenVDB volume sequences and Mantaflow cache/script workflows. This repository currently exports NPZ and VTK; it has **no Blender cache integration**. [Blender volume objects](https://docs.blender.org/manual/en/4.5/modeling/volumes/introduction.html), [fluid cache](https://docs.blender.org/manual/en/4.5/physics/fluid/type/domain/cache.html), [OpenVDB Python API](https://www.openvdb.org/documentation/doxygen/python.html).
+
+## Builds and releases
+
+GitHub Actions tests Python 3.12/3.13, builds the documentation, builds and checks wheel/source distributions, and exercises the installed wheel. Matching `v*` tags run the same validation before publishing to PyPI through Trusted Publishing, then attaching the same distributions, documentation, and checksums to a GitHub Release. No stored PyPI API token is needed. See [the release workflow](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/releases.md) and [PyPI's Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/using-a-publisher/). Read the Docs hosting is not connected.
+
+## Sources and provenance
+
+The shared conversation was extracted with the existing `chatgpt-import-share` checkout. The [Markdown transcript](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/conversation.md), [structured export](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/conversation.json), and [source manifest](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/source-manifest.json) preserve provenance and redacted/unavailable-message markers. The conversation is a design input, not independent evidence for its claims.
+
+The manifest pins the inspected Lean commit and records the paper hash. Read the [research note](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/research.md) and [annotated sources](https://github.com/james-coder/navier-stokes-blowup/blob/main/docs/sources.md) for the implementation decisions and unresolved questions. [Contributing](https://github.com/james-coder/navier-stokes-blowup/blob/main/CONTRIBUTING.md) describes the evidence required for new features. Code is MIT licensed; the imported conversation and referenced third-party works retain their respective rights.

ns_blowup-0.1.0/docs/api.md

@@ -0,0 +1,46 @@
+# API guide
+
+All primary names are imported from `ns_blowup`. Python docstrings describe arguments and array conventions. Version 0.1 is a preview; additions should preserve these conventions, and breaking changes must be called out before release.
+
+| API | Purpose | Returns |
+|---|---|---|
+| `Simulation(shape, nu=..., lengths=..., dtype=..., device=...)` | Friendly simulation setup | Simulation object |
+| `sim.run(initial, t_end=..., frames=..., dt=..., forcing=...)` | Adaptively evolve a flow | `SimulationResult` |
+| `SimulationResult.load(path)` | Read a saved NPZ without pickle | Result object |
+| `result.final` | Last saved velocity | JAX array |
+| `result.diagnostics()` | Per-frame energy, speed, curl and divergence maxima | Dictionary of NumPy arrays |
+| `result.plot(quantity=..., path=...)` | 2D image or middle xy slice in 3D | Matplotlib Axes |
+| `result.save(path)` | NPZ with grid, time and metadata | Path |
+| `result.export_vtk(path, frame=-1)` | Legacy structured-point velocity export | Path |
+| `PeriodicGrid(shape, lengths=None)` | Endpoint-excluding 2D/3D box | Grid object |
+| `grid.points(dtype=None)` | Coordinates in physical units | `(*shape, dimension)` array |
+| `SpectralSolver(grid, nu=...)` | Compilable periodic solver | Solver object |
+| `solver.project(u)` | Truncate and make velocity divergence free | Velocity array |
+| `solver.rhs(u, t=..., forcing=...)` | Semidiscrete time derivative | Velocity array |
+| `solver.step(u, t, dt, forcing=None)` | One RK4 step; caller controls positive stable dt | Velocity array |
+| `solver.integrate(u, dt, steps, t0=..., forcing=..., save_every=...)` | Fixed-step differentiable evolution | Final velocity, or `(times, frames)` |
+| `solver.pressure(u, t=..., forcing=...)` | Recover zero-mean pressure | Scalar grid array |
+| `solver.divergence(u)`, `solver.vorticity(u)` | Fourier diagnostics | Scalar/vector grid array |
+| `solver.suggest_dt(u, safety=0.4)` | Instantaneous step estimate | Scalar |
+| `TaylorGreen(nu=..., amplitude=..., wavenumber=...)` | Exact 2D vortex, with optional 3D embedding | Field object |
+| `ABCFlow(nu=..., a=..., b=..., c=..., wavenumber=...)` | Exact 3D Beltrami flow | Field object |
+| `FieldDiagnostics(velocity, pressure, nu, forcing=None)` | Autodiff diagnostics | Diagnostic object |
+| `checks.residual(points,t)`, `.divergence(...)`, `.vorticity(...)`, `.gradient(...)` | Batched analytical checks | JAX array |
+| `kinetic_energy(u, grid)` | Integral energy estimate | Scalar |
+| `sampled_norms(u, omega, gradient)` | Sampled norm maxima | Dictionary |
+| `SimilarityCoordinates(h=0.005)(xyz,tau)` | Positive-branch similarity coordinates | Named tuple `(q, eta, X)` |
+| `SimilarityCoordinates(h).scales(tau)` | Unit-normalized power laws | Dictionary |
+| `ViscosityScaled(base, nu)` | Rescale a supplied viscosity-one field | Field object |
+| `HeatExterior(h=..., c=..., nu=..., order=...)` | Outer-flow quadrature, away from axis | Field object |
+| `exterior.factor(Z)` | Heat-factor integral approximation | Scalar/batched array |
+| `exterior.azimuthal_velocity(radius,tau)` | Swirl speed with direct time remaining | Scalar/batched array |
+
+Analytical field objects expose `.velocity(points,t)`, `.pressure(points,t)`, and `.forcing(points,t)`. Diagnostics require callbacks that accept a **single point** and return respectively `(d,)`, `()`, and `(d,)`; the supplied field objects also support batches. Time is scalar per evaluation. Use `jax.vmap` for multiple times.
+
+Simulation initial callbacks accept the **whole point grid** and return a velocity grid. Solver forcing callbacks accept `(points, time)` and must return exactly the velocity-grid shape. Uniform forces should explicitly broadcast to that shape.
+
+Choose `device="gpu"` to require a GPU, `"cpu"` to require CPU, or `"auto"` to use JAX's default. `JAX_PLATFORMS` can restrict which backends exist in a process. A required unavailable device produces an error, rather than a hidden fallback. The observatory generator is the exception: it prefers CPU for its small report and uses the enabled device if CPU is disabled.
+
+Construct grids, solver objects, and quadrature objects outside JIT. Close over them in a compiled function; keep `steps` and `save_every` static. The friendly `Simulation.run` driver, plotting, filesystem operations, and data loading are host APIs and do not belong inside JIT.
+
+Positive `tau` is required for similarity coordinates; the heat exterior permits `tau=0` only at positive radius. Invalid mathematical-domain inputs return NaN even under JIT. Validate evaluation ranges before large batched work. Geometry h is a selected static parameter; this library does not supply the theorem's complete parameter-selection machinery.

ns_blowup-0.1.0/docs/conf.py

@@ -0,0 +1,18 @@
+"""Documentation-only build: no GPU runtime or simulation execution required."""
+from pathlib import Path
+import os
+
+project = "ns-blowup"
+author = "ns-blowup contributors"
+release = "0.1.0"
+extensions = ["myst_parser", "sphinx.ext.mathjax"]
+myst_enable_extensions = ["dollarmath", "colon_fence"]
+source_suffix = {".md": "markdown"}
+exclude_patterns = ["conversation.md", "_build", "requirements.txt"]
+html_theme = "sphinx_rtd_theme"
+html_title = "ns-blowup — Singularity Observatory"
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+# Preserve source artifacts as downloads without parsing the imported conversation.
+root = Path(__file__).parent
+html_extra_path = [p.name for p in root.iterdir() if p.suffix in (".json", ".txt", ".html")
+                   and p.name != "requirements.txt"] + ["conversation.md"]