Skip to content

four_scene11 PR preparation — 2026-09-08

Subsequent local source-audit and StateFlags fixes are recorded in the repair report. The baseline counts and open issues below describe commit 3014386, not those later edits.

The separate pr/four-scene11-20260908 branch reconciles the selected four-scene snapshot with upstream main and makes its demos load from an installed wheel. It is a review branch, not a release or a passing whole-engine integration. No upstream PR is opened by this preparation; no upstream branch is modified.

Scope and history

  • Target: Novaphy/NovaPhy:main, verified remote default, commit 753894f186bef9c2a692fae0ca72bd8316d0248f. The existing master is not the target.
  • Preserved snapshot: fy-123456/NovaPhy:snapshot/four-scene11-20260908, 1444351cf9ba3c9dee87f1eb47f0d5a5461bf6d5.
  • Common ancestor: 1d5a8ab594ac334a41c803800022aadc7f954eb1; each side had 23 exclusive commits. The snapshot's 18 earlier commits carry MPM foundations, CUDA execution, demos and tests; moving only its final five commits would omit dependencies. Preserve that history and merge upstream into a separate branch.
  • Before synchronization the snapshot's three-dot diff covered 547 files, +280345/-100 lines. This remains a large MPM review, not merely the latest 70-file integration increment. Review math, state, bindings, demos and test migration as separate areas. History preservation does not certify every inherited research script or test as portable.

The original project worktree, independent integration source, snapshot branch, private runtimes, delivery archive and shared conda installation are preserved. The new build and Git checkout live in an independent publication directory.

Resolved compatibility issues

Seven Git conflicts were coordinated without discarding either side's features: MPM and DIFF bindings; MPM symbol checks and upstream Python exports; pytest collection hooks; migration of MPM Config assertions into the upstream signature suite; and both entries in the merge-conflict guide. MPM binders sit outside the optional VBD guard. Upstream NO_EXTRAS and IPO-off binding build settings remain.

Installed scripts now import novaphy.demos.* and novaphy.tools.mpm.*; source path injection is removed except the guide's existing standalone GL debug exception. python/tools is mapped into the wheel. Two relocated source-audit tests now resolve their tools and handoffs from the actual repository root. Their anchor/contract assertions are retained, including the remaining stale D1 source anchor failure. Some research helpers still need checkout files or external Newton data; installing them does not supply those fixtures.

A real wheel install exposed two packaging problems that the private loader had hidden:

  • Shared MPM libraries could not find sibling beam helper libraries. Installed Linux RPATH now includes $ORIGIN as well as its bundled dependency directory.
  • Linking upstream DIFF pulled the host NVIDIA driver into dependency packaging. Exclude libcuda, NVML and their Windows counterparts from the wheel; keep CUDA runtime dependencies. The host supplies its own compatible driver.

The wheel also includes the root license and vendor/warp_native/LICENSE.md. Seven regression checks cover installed imports without top-level demos/tools aliases, license inclusion and absence of packaged host driver libraries. No solver formula or numerical tolerance was changed during this preparation. See merge-conflict guide §3.4.

Fresh validation of this branch

Built a standard scikit-build wheel and installed it into a separate Python 3.11 venv: GCC 11, CUDA 12.6, sm86; MPM CUDA, collision CUDA and DIFF ON; IPC and Featherstone CUDA OFF. The complete native build succeeded. Actual imports and loaded NovaPhy libraries resolve to that venv's installed wheel, without source PYTHONPATH, LD_LIBRARY_PATH, top-level module aliases or checked_entry.py.

Wheel SHA256: a92d079f7f017f6ffa5d342941fa2b8019b1690cec9f9223c1735e6a0bb0b5ad. Third-party dependencies were reused via read-only links, with missing optional pycollada, python-dateutil and six installed only in this venv. This proves installation behavior on this server, not a fresh machine dependency bootstrap.

Check Result
Installed imports, license and host-driver packaging 7 passed
Pytest collection 2018 collected, no collection errors
MPM coloring/diagnostic lifecycle, M3b and beam bindings under Compute Sanitizer 24 passed; 0 reported errors
Four actual Viser servers Each HTTP 200, 10 frame updates, normal exit
Four scene sampled-state sequences under Compute Sanitizer Each 2 frames; finite float32 sampled fields; 4 passed; 0 reported errors
Complete pytest run before test-path/dependency corrections 1861 passed, 25 failed, 132 skipped; 652.89 seconds
Corrected D1/D3 test paths 3 passed, 1 failed at its actual stale source anchor
LBM after installing declared visualization dependencies 7 passed
Original 25 failures rechecked after corrections 6 passed, 19 failed; the order-sensitive blending case remains open
Universal merge guide gates No unresolved conflicts; only documented GL injection/alias exception
Changed C++ binder lines / Python lint delta clang-format dry run passed; no newly introduced Ruff findings; historical lint findings remain

The complete run is FAIL against AGENTS.md's all-tests-pass threshold. Focused rechecks do not replace it with a new full-suite PASS. No clang-tidy certification is claimed. The new PR wheel has not repeated the historical 300/300/300/1200-frame sequences, and no browser-pixel comparison was performed.

Machine-readable check counts, failed node IDs, bounded scene observations and source provenance are in the validation summary.

Open issues and review gates

  1. Fifteen of sixteen selected MPM runtime failures also reproduce against the saved publication12 runtime and original snapshot tests. They cover cache invalidation, host dirty reporting, AoS/SoA and compact/persistent parity, profile/launch counters, scaling metrics, and CPU access to CUDA DeviceArray. This is evidence of inherited failures, not acceptance of those behaviors.
  2. Zero-mass material blending failed in the full suite but passed in isolation on both old and new libraries. Execution-order/shared-state involvement remains open; the first invalid state transition has not been established.
  3. Some historical source assertions no longer match the retained implementation: the D1 Jp anchor, old mass-scale launch symbol, and a blanket ban on shared memory in the GS kernel. They are recorded without weakening assertions.
  4. The preserved MPM StateFlags.PARTICLE / Particle aliases conflict with the upstream test's exact seven-member API expectation. This requires an explicit API compatibility decision; neither aliases nor the upstream assertion were silently removed. This is a remaining semantic integration issue despite zero Git conflict markers.
  5. Upstream DIFF ball --check-grad fails with source input must be I32. In novaphy/src/collision/diff_soft_contacts.cpp, the contact-buffer input declaration assigns I32 to kShapeMu and F32 to kContactShape, inconsistent with the corresponding loads. The file is byte-identical to upstream main. No DIFF algorithm/type repair is included here. The Featherstone DIFF demo requires the optional CUDA backend that this build does not enable.
  6. Historical PIC-B strict disagreement, snow repeatability, two-way stress and float32/state/backend/capture conformance gaps remain as recorded in the snapshot report. The paused two-way candidate is not promoted. Warp-derived helper acceptance also remains an architecture review item.

Before upstream merge, close or explicitly resolve these review gates under the project's acceptance policy, then rerun affected checks and the full suite. Do not treat the bounded viewer results as whole-engine or strict Newton acceptance.

Standard visualization CLI

After installing a wheel built from this branch, activate that installation's Python environment. These commands use installed modules and do not depend on the private novaviz launcher. Run one command per terminal; the four default URLs below are http://127.0.0.1:8082 through :8085.

python -m novaphy.demos.mpm.newton_ref.demo_mpm_multi_material \
  --m3b-profile newton-parity --gs-official-solve-kernel \
  --newton-fem-cuda-graph --newton-fem-graph-cond-while \
  --newton-fem-rheology-contact-granularity 5 \
  --newton-fem-rheology-contact-tol 0 \
  --no-newton-fem-eval-residual-early-stop --no-gs-device-early-exit \
  --viewer viser --viser-host 127.0.0.1 --viser-port 8082

python -m novaphy.demos.mpm.newton_ref.demo_mpm_viscous \
  --cuda --viscous-profile newton-parity \
  --viewer viser --viser-host 127.0.0.1 --viser-port 8083

python -m novaphy.demos.mpm.newton_ref.demo_mpm_snow_ball \
  --cuda --snow-profile newton-parity --snow-scene-align official \
  --no-snow-project-outside --show-compression \
  --viewer viser --viser-host 127.0.0.1 --viser-port 8084

python -m novaphy.demos.mpm.newton_ref.demo_mpm_beam_twist \
  --cuda --beam-profile newton-parity --show-stress \
  --viewer viser --viser-host 127.0.0.1 --viser-port 8085

For SSH access, forward the chosen ports from your local computer:

ssh -L 8082:127.0.0.1:8082 -L 8083:127.0.0.1:8083 \
    -L 8084:127.0.0.1:8084 -L 8085:127.0.0.1:8085 user@server

See the installation guide for toolchain and dependency setup. Explicitly enable NOVAPHY_WITH_MPM_CUDA=ON, select the actual GPU architecture, and install the resulting wheel with its visualization extras. Build options and the exact validation commands are retained in the JSON summary; server-specific dependency directories must be adapted on another machine.