Getting Started with Any Use Case

Objectives

Clone and set up any WP7 demonstrator repository
Understand the common repository layout
Run the demonstrator notebook end-to-end
Use AI coding assistants with AGENT.md files

Common Repository Layout

Every completed WP7 demonstrator follows a consistent layout:

<repo-root>/
├── README.md                           # Project overview
├── requirements.txt                    # Python dependencies (full VM)
├── requirements-test.txt               # Lean CI dependencies
├── setup.sh or vm-init.sh              # One-command setup script
├── demonstrator-v1.orchestrator.ipynb  # Interactive notebook
├── dataset/ or data/                   # Training data (included or downloaded)
├── scripts/ or src/                    # Source code
├── results/                            # Pre-computed results (optional)
├── tests/                              # Automated test suite
├── content/                            # Sphinx tutorial (all repos)
├── AGENT.md                            # AI assistant instructions (all except UC4)
└── .github/workflows/                  # CI/CD pipelines

Quick Start (Any Use Case)

Once connected to your NAIC VM (see Episode 02):

1. Clone the repository

# Replace <REPO_NAME> with the actual repository name
git clone https://github.com/NAICNO/<REPO_NAME>.git
cd <REPO_NAME>

2. Set up the environment

One-command setup

bash setup.sh

3. Launch Jupyter

# Start Jupyter in the background
jupyter notebook --no-browser --port=8888 &

On your local machine, create an SSH tunnel:

ssh -i /path/to/key.pem -L 8888:localhost:8888 ubuntu@<VM_IP>

Then open http://localhost:8888 in your browser.

4. Run the notebook

Open demonstrator-v1.orchestrator.ipynb (or the use case’s main notebook) and run all cells.

Use Case Quick Reference

UC	Repository	Clone Command
UC1	d7.2-Use-case1	`git clone https://github.com/NAICNO/wp7-UC1-climate-indices-teleconnection.git`
UC2	uc2-pem-electrolyzer-pinn-optimizer	`git clone https://github.com/NAICNO/wp7-UC2-pem-electrolyzer-digital-twin.git`
UC3	pseudo-hamiltonian-neural-networks	`git clone https://github.com/NAICNO/wp7-UC3-pseudo-hamiltonian-neural-networks.git`
UC4	3D-medical-image-registration-segmentation	`git clone https://github.com/NAICNO/wp7-UC4-medical-image-registration.git`
UC5	graph-based-classification-of-ais-time-series-data	`git clone https://github.com/NAICNO/wp7-UC5-ais-classification-gnn.git`
UC6	multi-modal-optimization	`git clone https://github.com/NAICNO/wp7-UC6-multimodal-optimization.git`
UC7	latent-representation-of-pde-solutions	`git clone https://github.com/NAICNO/wp7-UC7-latent-pde-representation.git`

Using AI Coding Assistants

Six repositories (UC1, UC2, UC3, UC5, UC6, UC7) include AGENT.md files with machine-readable instructions for AI coding assistants like Claude Code, GitHub Copilot, or Cursor.

To use this:

> "Read AGENT.md and help me run the demonstrator on my NAIC VM."

The assistant will be able to set up the environment and run experiments automatically.

GPU Requirements

UC	GPU Required?	Typical Training Time
UC1	No (CPU sufficient)	5–30 min per model
UC2	Recommended	~10 min (teacher + student)
UC3	Recommended	Varies by system
UC4	No (CPU sufficient)	~5 min per subject
UC5	Recommended (CUDA 11.8)	~15 min training
UC6	No (CPU, multi-core helps)	~5 min per function
UC7	Recommended	~20 min (autoencoder training)

Running Tests

Every repository includes a test suite that runs without GPU or heavy dependencies:

pip install -r requirements-test.txt
pytest tests/ -v --tb=short

Tests are designed to skip gracefully when optional dependencies (e.g., DGL, TensorFlow, requests) are not installed.

Keypoints

All WP7 repositories follow a consistent layout: notebook + data + setup script + tests
One-command setup scripts (setup.sh, vm-init.sh) handle environment creation
SSH tunneling provides Jupyter access from your local browser
AI coding assistants can use AGENT.md files for automated setup (all except UC4)
Tests skip gracefully in CI environments without GPU or heavy dependencies