FAQ and Troubleshooting

Objectives

  • Resolve common setup and runtime issues

  • Understand PHNN-specific design choices

  • Know how to extend the framework with new systems

General Setup

Q: What Python version is required?

Python 3.8 or higher. The setup.sh script validates this automatically. We recommend Python 3.10+ for best compatibility with current PyTorch versions.

Q: Do I need a GPU?

No. All examples run on CPU. However, GPU acceleration (CUDA) significantly speeds up PDE training. For ODE examples, CPU is sufficient. The NAIC Orchestrator VMs provide L40S GPUs.

Q: How do I check GPU availability?

# Check NVIDIA driver
nvidia-smi

# Check PyTorch CUDA support
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"CPU\"}')"

Common Errors

Q: ModuleNotFoundError: No module named 'phlearn'

The phlearn package must be installed from the local source:

cd ~/pseudo-hamiltonian-neural-networks
source venv/bin/activate
pip install -e phlearn

Q: CUDA out of memory

Reduce batch size or spatial grid resolution. For PDE systems, try a coarser grid (e.g., 64 instead of 256 points). You can also force CPU training:

model = model.to('cpu')

Q: Notebook kernel dies during training

Check available RAM with free -h. If memory is low, reduce the number of training trajectories or close other notebooks. Restart the kernel and try again.

Q: Integration diverges (NaN values)

  • Reduce the learning rate (e.g., from 0.001 to 0.0001)

  • Reduce the time step in trajectory generation

  • Use the midpoint integrator (more stable than symmetric for stiff systems)

  • Check that initial conditions are within a reasonable range

Q: Host key verification failed when SSHing

A new VM was created at the same IP address. Remove the old key:

ssh-keygen -R <VM_IP>

PHNN-Specific Questions

Q: What is the difference between PHNN and HNN (Hamiltonian Neural Networks)?

Feature

HNN

PHNN

Dissipation

Not modeled

Explicit R-network

External forces

Not modeled

Explicit F-network

Scope

Conservative systems only

Conservative + dissipative + forced

Real-world applicability

Limited (no friction)

Broad (friction, damping, forcing)

HNNs (Greydanus et al., 2019) only model conservative systems. PHNNs extend this to dissipative and forced systems, which covers most real-world applications.

Q: How do I choose an integrator?

Integrator

Speed

Accuracy

Use Case

midpoint

Fast

Good

Default choice, most systems

symmetric

Slower

Best

Sparse/noisy data, long horizons

Start with midpoint. Switch to symmetric if you observe energy drift or are working with sparse data.

Q: Can I add a new ODE system?

Yes. Create a new system class that defines:

  1. The Hamiltonian function H(x)

  2. The gradient grad_H(x)

  3. The dissipation matrix R(x) (can be zero)

  4. Optional external force F(x)

See phlearn/phlearn/phsystems/ode/msd_system.py for a reference implementation.

Q: Can I add a new PDE system?

Yes. Subclass PseudoHamiltonianPDESystem and define:

  1. The Hamiltonian functional H[u]

  2. The structure operator S

  3. The dissipation operator R (if applicable)

  4. Boundary conditions

See phlearn/phlearn/phsystems/pde/kdv_system.py for a reference implementation.

Q: How do I save and load trained models?

import torch

# Save
torch.save(model.state_dict(), 'phnn_model.pt')

# Load
model.load_state_dict(torch.load('phnn_model.pt'))
model.eval()

Resources

  • phlearn documentation: https://pseudo-hamiltonian-neural-networks.readthedocs.io/en/latest/

  • NAIC Portal: https://www.naic.no/

  • Orchestrator: https://orchestrator.naic.no/

  • Repository: https://github.com/NAICNO/wp7-UC3-pseudo-hamiltonian-neural-networks

Keypoints

  • Python 3.8+ is required; GPU is optional but recommended for PDE training

  • Install phlearn with pip install -e phlearn from the repository root

  • PHNNs extend HNNs by adding dissipation (R-network) and external forces (F-network)

  • Use midpoint integrator as default; switch to symmetric for sparse/noisy data

  • New ODE/PDE systems can be added by subclassing the provided base classes

  • Check nvidia-smi and torch.cuda.is_available() to verify GPU setup