ENH: Refined installation procedure and documentation

.github/workflows/README.md

@@ -11,7 +11,7 @@ Runs on every push and pull request to main branches. Includes:
 - **unit-tests**: Cross-platform unit tests
   - Runs on Ubuntu and Windows
   - Python 3.11 and 3.12
-  - Installs `.[test]` only, so no CUDA toolchain is pulled in
+  - Installs `.[dev]` only, so no CUDA toolchain is pulled in
   - Excludes slow tests and tests requiring external data
   - Generates coverage reports
 
@@ -70,7 +70,7 @@ nightly-health badge in the top-level `README.md` resolves.
 
 Runs at 07:00 UTC daily, or on manual trigger with a `reason` input. On the
 self-hosted Windows GPU runner it installs
-`.[test,docs,cuda13,dev,physicsnemo]` and runs the entire suite with
+`.[dev_cuda13]` and runs the entire suite with
 `--run-all`, which enables every opt-in bucket. The run itself is
 `continue-on-error`, so a failing test records a red status rather than
 failing the workflow.
@@ -162,9 +162,9 @@ GPU tests require self-hosted runners with:
 
 **Option 3: Run Locally**
 ```bash
-# Install with CUDA + PhysicsNeMo (matches the self-hosted GPU runner).
-# Requires Python 3.11-3.13 (the range nvidia-physicsnemo supports).
-uv pip install -e ".[test,cuda13,physicsnemo]"
+# Install with CUDA (matches the self-hosted GPU runner). PhysicsNeMo is a
+# base dependency, requiring Python 3.11-3.13 (the range it supports).
+uv pip install -e ".[dev_cuda13]"
 
 # Run GPU tests
 pytest tests/ -v --run-gpu
@@ -180,7 +180,7 @@ GitHub-hosted runners do **not** have GPU support. All GPU tests require self-ho
 Test dependencies are installed from `pyproject.toml`:
 
 ```bash
-pip install -e ".[test]"
+pip install -e ".[dev]"
 ```
 
 This installs:
@@ -225,7 +225,7 @@ def test_gpu_function():
 ### CPU Tests
 ```bash
 # Install dependencies
-pip install -e ".[test]"
+pip install -e ".[dev]"
 
 # Run unit tests
 pytest tests/ -m "unit and not requires_gpu"
@@ -236,9 +236,9 @@ pytest tests/ -m "unit and not requires_gpu" --cov=monai_physio
 
 ### GPU Tests
 ```bash
-# Install with CUDA + PhysicsNeMo (matches the self-hosted GPU runner).
-# Requires Python 3.11-3.13 (the range nvidia-physicsnemo supports).
-uv pip install -e ".[test,cuda13,physicsnemo]"
+# Install with CUDA (matches the self-hosted GPU runner). PhysicsNeMo is a
+# base dependency, requiring Python 3.11-3.13 (the range it supports).
+uv pip install -e ".[dev_cuda13]"
 
 # Run GPU tests
 pytest tests/ --run-gpu

.github/workflows/ci.yml

@@ -12,7 +12,8 @@ name: CI
 # - slow                 -> --run-slow
 # - requires_gpu         -> --run-gpu
 # - requires_simpleware  -> --run-simpleware  (also implies GPU)
-# - requires_physicsnemo -> --run-physicsnemo (needs the [physicsnemo] extra)
+# - requires_physicsnemo -> --run-physicsnemo (nvidia-physicsnemo is a base
+#                            dependency; no extra needed)
 # - tutorial             -> --run-tutorials
 # --run-all enables every bucket above at once.
 # Tests that need external data download it automatically via fixtures.
@@ -95,8 +96,12 @@ jobs:
         python -m pip install --upgrade pip setuptools wheel
 
     - name: Install package with test dependencies
+      # torch-scatter (a base dependency) compiles against torch and needs
+      # build isolation disabled; pip has no per-package flag for this, so
+      # --no-build-isolation applies to the whole install (setuptools/wheel
+      # are already present from the previous step).
       run: |
-        pip install -e ".[test]"
+        pip install -e ".[dev]" --no-build-isolation
 
     - name: Clear pip cache
       run: |
@@ -210,8 +215,12 @@ jobs:
         python -m pip install --upgrade pip setuptools wheel
 
     - name: Install package with test dependencies
+      # torch-scatter (a base dependency) compiles against torch and needs
+      # build isolation disabled; pip has no per-package flag for this, so
+      # --no-build-isolation applies to the whole install (setuptools/wheel
+      # are already present from the previous step).
       run: |
-        pip install -e ".[test]"
+        pip install -e ".[dev]" --no-build-isolation
 
     - name: Clear pip cache
       run: |
@@ -319,13 +328,20 @@ jobs:
 
     - name: Install package with test dependencies
       # uv respects [tool.uv.sources], routing torch to pytorch-cu130 for cuda13.
-      # The [physicsnemo] extra brings in nvidia-physicsnemo so Tutorial 9 and
-      # requires_physicsnemo-marked tests can run on this GPU runner.
+      # nvidia-physicsnemo/torch-geometric/torch-scatter are base dependencies
+      # (installed unconditionally), so Tutorial 9 and requires_physicsnemo-
+      # marked tests can run on this GPU runner without a separate extra.
+      # torch-scatter compiles against torch and needs --no-build-isolation-
+      # package from the very first install, since it's pulled in as soon as
+      # any extra resolves the base dependencies. The source build is
+      # unavoidable on CUDA 13 -- data.pyg.org publishes no torch-scatter
+      # wheel for it on Windows -- and is only needed at all because
+      # physicsnemo hard-imports torch_scatter instead of using PyG's
+      # native-backed torch_geometric.utils.scatter; see the AI-surrogate
+      # comment in pyproject.toml.
       # Invoke via python -m uv so uv targets the active venv interpreter.
       run: |
-        python -m uv pip install -e ".[cuda13]"
-        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-        python -m uv pip install -e ".[test,cuda13,physicsnemo]" --no-build-isolation-package torch-scatter
+        python -m uv pip install -e ".[dev_cuda13]" --no-build-isolation-package torch-scatter
 
     - name: Assert CUDA is accessible
       run: |
@@ -408,12 +424,16 @@ jobs:
         cache: 'pip'
 
     - name: Install dev dependencies
+      # torch-scatter (a base dependency) compiles against torch and needs
+      # setuptools present and build isolation disabled; pip has no
+      # per-package flag for this, so --no-build-isolation applies to the
+      # whole install.
       run: |
-        python -m pip install --upgrade pip
+        python -m pip install --upgrade pip setuptools
         # Ruff runs via pre-commit so its version is pinned in one place
         # (.pre-commit-config.yaml); mypy is still invoked directly below.
         pip install pre-commit mypy
-        pip install -e ".[dev]"
+        pip install -e ".[dev]" --no-build-isolation
 
     - name: Check formatting with Ruff (via pre-commit)
       run: |
@@ -455,7 +475,7 @@ jobs:
 #
 # Self-hosted GPU runner enables ALL buckets via --run-all
 # (--run-gpu --run-slow --run-simpleware --run-physicsnemo --run-tutorials).
-# That runner installs the [physicsnemo] extra in addition to [test,cuda13].
+# That runner installs [dev_cuda13] (nvidia-physicsnemo is a base dependency).
 #
 # To run tutorial tests (manual only, slow):
 #   pytest tests/test_tutorials.py -v --run-tutorials

.github/workflows/docs.yml

@@ -58,7 +58,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip uv
-        uv pip install --system -e ".[docs]"
+        uv pip install --system -e ".[dev]"
 
     - name: Clear pip cache
       run: |

.github/workflows/nightly-health.yml

@@ -101,16 +101,19 @@ jobs:
 
       - name: Install uv and package
         # Invoke via python -m uv so uv targets the active venv interpreter.
-        # The [physicsnemo] extra is required for --run-physicsnemo (Tutorial 9
-        # and any tests marked requires_physicsnemo).
+        # nvidia-physicsnemo/torch-geometric/torch-scatter are base
+        # dependencies (installed unconditionally), so --run-physicsnemo
+        # (Tutorial 9 and any tests marked requires_physicsnemo) works without
+        # a separate extra.
         #
         # torch-scatter compiles against torch and imports it at build time, but
         # declares neither torch nor setuptools as a build dependency. Its build
         # therefore runs with isolation disabled (--no-build-isolation-package,
         # passed explicitly rather than relying on uv discovering
         # no-build-isolation-package in pyproject.toml), which makes the venv
         # itself the build environment: setuptools, wheel, and torch must all be
-        # installed before the physicsnemo extra is resolved.
+        # installed before ANY monai-physio extra is resolved, since
+        # torch-scatter is now a base dependency and is pulled in immediately.
         #
         # torch, torchvision, and torchaudio are all pinned to the pytorch-cu130
         # index here because the uv pip interface ignores tool.uv.sources.
@@ -133,9 +136,7 @@ jobs:
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           python -c "import torch; print(f'build-time torch {torch.__version__} (CUDA {torch.version.cuda})')"
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          python -m uv pip install -e ".[cuda13]"
-          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          python -m uv pip install -e ".[test,docs,cuda13,dev,physicsnemo]" --no-build-isolation-package torch-scatter
+          python -m uv pip install -e ".[dev_cuda13]" --no-build-isolation-package torch-scatter
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
       - name: Assert CUDA is accessible

.github/workflows/test-slow.yml

@@ -21,8 +21,8 @@ jobs:
         lfs: true
 
     - name: Create venv in RUNNER_TEMP
-      # Python 3.11 is required because the [physicsnemo] extra pulls in
-      # nvidia-physicsnemo, which requires Python >= 3.11.
+      # Python 3.11 is required because the base dependency nvidia-physicsnemo
+      # requires Python >= 3.11.
       run: |
         & "C:\Program Files\Python311\python.exe" -m venv "$env:RUNNER_TEMP\monai-physio-venv"
         echo "$env:RUNNER_TEMP\monai-physio-venv\Scripts" >> $env:GITHUB_PATH
@@ -54,11 +54,12 @@ jobs:
 
     - name: Install package with test dependencies
       # uv respects [tool.uv.sources], routing torch to pytorch-cu130 for cuda13.
-      # The [physicsnemo] extra is required for --run-physicsnemo (Tutorial 9
-      # and any tests marked requires_physicsnemo).
+      # PhysicsNeMo is a base dependency, so it is always installed; it is
+      # what --run-physicsnemo (Tutorial 9 and any tests marked
+      # requires_physicsnemo) needs.
       # Invoke via python -m uv so uv targets the active venv interpreter.
       run: |
-        python -m uv pip install -e ".[test,cuda13,physicsnemo]"
+        python -m uv pip install -e ".[dev_cuda13]" --no-build-isolation-package torch-scatter
 
     - name: Assert CUDA is accessible
       run: |

CONTRIBUTING.md

@@ -30,21 +30,13 @@ Thank you for your interest in contributing to MONAI Physio! This guide will hel
 4. **Install in development mode**:
 
    ```bash
-   pip install -e ".[dev]"
+   uv pip install -e ".[dev_cuda12]"
    ```
 
-   To install the full developer environment with CUDA 13, documentation, test,
-   and development dependencies:
-
-   ```bash
-   uv pip install -e ".[cuda13,docs,test,dev]"
-   ```
-
-   Or install every declared extra, including `physicsnemo`:
-
-   ```bash
-   uv pip install -e . --all-extras
-   ```
+   `dev_cuda12` is the full developer environment: CUDA 12.6 acceleration
+   plus the test, lint, and documentation tooling. Use `dev_cuda13` for
+   CUDA 13, or `dev` alone for the tooling without CuPy. See the
+   [installation guide](https://project-monai.github.io/monai-physio/installation.html).
 
 5. **Install pre-commit hooks**:
 
@@ -124,10 +116,8 @@ feature.
 After cloning the repository:
 
 1. Install Python 3.11+ and create virtual environment
-2. Install development dependencies: `pip install -e ".[dev]"`,
-   or install all extras with
-   `uv pip install -e ".[cuda13,docs,test,dev]"` or
-   `uv pip install -e . --all-extras`
+2. Install development dependencies: `uv pip install -e ".[dev_cuda12]"`
+   (or `dev_cuda13` for CUDA 13, `dev` for tooling only)
 3. Install pre-commit hooks: `pre-commit install`
 4. Install Ruff extension in VS Code/Cursor
 5. Remove old formatter extensions (black, isort, flake8, pylint)
@@ -262,7 +252,7 @@ pytest tests/
 # Opt into specific buckets
 pytest tests/ --run-slow
 pytest tests/ --run-gpu --run-slow   # typical local GPU profile
-pytest tests/ --run-physicsnemo      # needs [physicsnemo] extra; requires Python >= 3.11
+pytest tests/ --run-physicsnemo      # needs PhysicsNeMo; requires Python >= 3.11
 # --run-all turns on every --run-* bucket at once (used by self-hosted CI):
 pytest tests/ --run-all
 ```
@@ -275,7 +265,7 @@ Documentation is built with Sphinx and hosted on ReadTheDocs.
 
 ```bash
 # Install documentation dependencies
-pip install -e ".[docs]"
+pip install -e ".[dev]"
 
 # Build HTML documentation
 cd docs

README.md

@@ -49,10 +49,14 @@ for users and contributors. Key sections:
 ### Install
 
 ```
-uv pip install "monai-physio[all]"
+uv pip install "monai-physio[cuda12]"
 ```
 
-See the [installation guide](https://project-monai.github.io/monai-physio/installation.html) for GPU setup, source installs, and optional extras (PhysicsNeMo). 
+Installs entirely from prebuilt wheels. On CUDA 13 use `monai-physio[cuda13]`,
+which additionally needs a CUDA toolkit and C++ toolchain to build
+`torch-scatter`. See the
+[installation guide](https://project-monai.github.io/monai-physio/installation.html)
+for source installs, pip, and CPU-only.
 
 ### Download Tutorials
 

docs/README.md

@@ -8,7 +8,7 @@ note for contributors editing the docs.
 ## Building locally
 
 ```bash
-pip install -e ".[docs]"
+pip install -e ".[dev]"
 python -m sphinx -b html docs docs/_build/html
 ```
 

docs/api/physicsnemo/index.rst

@@ -40,13 +40,10 @@ network.
        implies comes from ``NeoHookeanResidual.cauchy_stress`` afterwards, as
        Tutorial 18 does it
 
-PhysicsNeMo is an optional dependency::
-
-   pip install "monai-physio[physicsnemo]"
-   pip install torch-geometric          # MeshGraphNet only
-
-It requires Python >= 3.11. ``import monai_physio`` works without it; the
-imports happen lazily inside the methods that need them.
+PhysicsNeMo and PyTorch Geometric are base dependencies of monai-physio, so
+installing the package is enough; it requires Python >= 3.11. The imports
+still happen lazily inside the methods that need them, so ``import
+monai_physio`` stays lightweight.
 
 .. toctree::
    :maxdepth: 2

docs/api/workflows.rst

@@ -48,8 +48,8 @@ Available Workflows
 
 The PhysicsNeMo AI-surrogate workflows — :class:`WorkflowTrainPhysicsNeMo`,
 :class:`WorkflowInferPhysicsNeMo`, :class:`WorkflowInferMovement` and
-:class:`WorkflowEvaluateMovement` — have their own section, since they need the
-optional ``[physicsnemo]`` extra. See :doc:`physicsnemo/index`.
+:class:`WorkflowEvaluateMovement` — have their own section. See
+:doc:`physicsnemo/index`.
 
 Convert Image to USD
 ====================

docs/architecture.rst

@@ -117,8 +117,8 @@ inference time:
    then evaluates the held-out cases with ``WorkflowInferPhysicsNeMo`` wrapped
    in ``WorkflowInferMovement``, turning predicted displacements back into
    surfaces without running registration — i.e. the AI surrogate stands in for
-   ``WorkflowReconstructHighres4DCT`` at inference time. Requires the
-   ``[physicsnemo]`` extra and ``torch-geometric``; Python >= 3.11.
+   ``WorkflowReconstructHighres4DCT`` at inference time. Requires PhysicsNeMo
+   and ``torch-geometric`` (base dependencies); Python >= 3.11.
 
 ``tutorial_10_lung_infer_physicsnemo_mgn.py``
    Loads that checkpoint and predicts the case's surface at a requested stage
@@ -223,7 +223,6 @@ workflow classes. They are the preferred examples for executable API usage:
 * ``monai-physio-visualize-pca-modes``
 
 ``monai-physio-train-physicsnemo`` and ``monai-physio-infer-physicsnemo`` wrap
-``WorkflowTrainPhysicsNeMo`` and ``WorkflowInferPhysicsNeMo`` and need the
-optional ``[physicsnemo]`` extra. There is no CLI wrapper for
+``WorkflowTrainPhysicsNeMo`` and ``WorkflowInferPhysicsNeMo``. There is no CLI wrapper for
 ``WorkflowFinetuneICONRegistration``; it is used through the Python API and
 tutorial scripts.

docs/cli_scripts/byod_tutorials.rst

@@ -17,8 +17,14 @@ or the CPU-only variant:
 
 .. code-block:: bash
 
-   # Recommended - CUDA-enabled
-   pip install monai-physio[cuda13]
+   # Recommended - CUDA 12.6, everything installs from prebuilt wheels
+   uv pip install "monai-physio[cuda12]"
+
+   # CUDA 13 - same, but torch-scatter compiles from source
+   uv pip install "monai-physio[cuda13]"
+
+   # Auto-detected GPU torch, no CUDA version to specify, no CuPy
+   uv pip install --torch-backend=auto monai-physio
 
    # CPU-only
    pip install monai-physio

docs/cli_scripts/train_physicsnemo.rst

@@ -8,11 +8,6 @@ shared template mesh. It is the command-line form of
 :class:`~monai_physio.WorkflowTrainPhysicsNeMo`; Tutorial 9 in
 :doc:`../tutorials` is the same thing as a script.
 
-Requires the optional extra::
-
-   pip install "monai-physio[physicsnemo]"
-   pip install torch-geometric          # MeshGraphNet only
-
 PhysicsNeMo needs Python >= 3.11.
 
 Basic Usage

docs/cookbook/train_and_infer_on_your_own_data.rst

@@ -16,12 +16,7 @@ Ingredients
 * **One held-out subject**, kept out of training, for scoring.
 * **A segmentation backend** that covers your anatomy — see
   :doc:`add_a_segmentation_method` if none does.
-* **The optional extra**, plus a CUDA GPU::
-
-     pip install "monai-physio[physicsnemo]"
-     pip install torch-geometric      # MeshGraphNet only
-
-  PhysicsNeMo requires Python >= 3.11.
+* **A CUDA GPU**, and Python >= 3.11.
 
 Steps
 =====