Troubleshooting

Common issues and solutions for PhysioTwin4D.

Installation Issues

CUDA Out of Memory

Problem: RuntimeError: CUDA out of memory

Solutions:

Resample or crop the input image before running the workflow.
Use --registration-method Greedy when CUDA is unavailable.
Process fewer frames per run.

Process Killed During Registration (Host Out of Memory)

Problem: a run stops with a bare Killed and no traceback, typically just after a line of ICON finetuning output:

ICONLoss(all_loss=tensor(1.0676, device='cuda:0', ...), ...)
Killed

Cause: the Linux OOM killer, not CUDA. A GPU shortage raises a catchable RuntimeError: CUDA out of memory with a Python traceback; Killed is the shell reporting that the kernel sent SIGKILL because the machine ran out of host RAM.

Confirm it, and see how much was in use at the time:

dmesg | grep -i "killed process"

Read anon-rss in that line. It is the process’s own heap; if file-rss is near zero the memory was genuinely allocated, rather than reclaimable file cache.

Cause on WSL2: WSL2 caps its virtual machine at half the host’s RAM by default, so a 128 GB machine gives Linux only about 64 GB and the OOM killer fires at that ceiling rather than at the physical limit. Check what Linux actually sees:

grep MemTotal /proc/meminfo

Solutions:

On WSL2, raise the ceiling in the Windows-side .wslconfig (in your user profile directory), then run wsl --shutdown and restart the distribution:
```
[wsl2]
memory=112GB
swap=32GB
```
Process fewer cases or frames per run. The cohort workflows cache every artifact they write, so a re-run resumes where it stopped rather than starting over.
Coarsen the registration grid, which sets the size of the distance maps and displacement fields held during a registration.

CUDA Version Mismatch

Problem: Errors such as cupy failing to import, torch.cuda.is_available() returning False, or runtime messages indicating a CUDA library version conflict.

Cause: The installed cupy or PyTorch wheel was built for a different CUDA version than the one present on the system.

Solution: Install the CUDA 13 extra:

uv pip install "physiotwin4d[cuda13]"

The extra installs CuPy. In uv-managed source environments, PyTorch resolves from the CUDA 13.0 wheel index.

Verify the active CUDA version before reinstalling:

nvidia-smi   # shows driver and CUDA version

Note

If you have no NVIDIA GPU, a plain pip install physiotwin4d installs a CPU-only build. CuPy is absent and a UserWarning is emitted at import time. CPU execution of all operations is supported but will be significantly slower than a GPU-enabled install.

Import Errors

Problem: ImportError: No module named 'itk'

Solution: Reinstall with all dependencies:

pip install --upgrade physiotwin4d

Processing Issues

Poor Segmentation Quality

Problem: Segmentation masks are inaccurate

Solutions:

Check if image is contrast-enhanced. Use SegmentChestTotalSegmentatorWithContrast instead of SegmentChestTotalSegmentator for contrast-enhanced studies:

from physiotwin4d import (
    SegmentChestTotalSegmentatorWithContrast,
    WorkflowConvertImageToUSD,
)

workflow = WorkflowConvertImageToUSD(
    ...,
    segmentation_method=SegmentChestTotalSegmentatorWithContrast(),
)

Preprocess intensity, spacing, and field of view before invoking the workflow.

Registration Not Converging

Problem: Registration produces poor results

Solutions:

Increase --registration-iterations for the heart-gated CT CLI.

Try different method:

physiotwin4d-convert-image-to-usd cardiac_4d.nrrd --registration-method Greedy

Check image orientation and spacing

USD Issues

USD Not Animating

Problem: USD file loads but doesn’t animate

Solutions:

Validate USD file:
```
usdchecker model.usd
```
usdchecker is not part of the usd-core package installed with PhysioTwin4D; it ships with the OpenUSD toolset, available pre-built from https://developer.nvidia.com/usd.
Open the scene in an Omniverse Kit application, switch the viewport to the scene’s /World/Camera, and press Play; see Viewing USD Files.
Verify that the generated USD contains time samples.

USD File Too Large

Problem: USD files are very large

Solutions:

Reduce mesh complexity before USD export.
Export fewer anatomy groups or fewer time points.

Performance Issues

Slow Processing

Problem: Processing takes too long

Solutions:

Install physiotwin4d[cuda13] with uv for CUDA acceleration.
Reduce --registration-iterations during exploratory runs.
Run tutorial workflows with reduced frame counts where supported.

Getting Help

If you still have issues:

Check FAQ
Search GitHub Issues
Open a new issue with:
- Python version
- CUDA version
- Complete error message
- Minimal code to reproduce