INDEQS: Informed Neural controlled Differential EQuationS

This repository contains two distinct codebases: the core deep learning model (indeqs) and the CPU-based data simulation (simulation) to simulate advection along graph edges.

Each of the two parts has its own isolated virtual environment managed by uv. Make sure uv is installed and if you desire animation creation for the simulation install ffmpeg (for both, see last section).

---

📂 Project Structure

repository_root/
├── ...
├── indeqs/              # Deep Learning Model (PyTorch, CUDA 11.8, GPU advised for training)
│   ├── pyproject.toml   
│   ├── uv.lock          # Locked GPU environment
|   └──...
└── simulation/          # Advection Data Simulation (Dask, NetworkX, CPU-only)
    ├── pyproject.toml
    ├── uv.lock          # Locked CPU environment
    └──...

---

🚀 Setup & Execution

Because the indeqs and simulation environments are strictly separated, you must navigate into the specific project folder.

---

Training and evaluating INDEQS on three different datasets:

1. Change directory:

cd indeqs/run_indeqs/

2. Run experiments:

• Advection Simulation:

  bash run_advection_simulation_prediction.sh

• River Discharge:

  bash run_river_discharge_prediction.sh

• Traffic Prediction:

  bash run_traffic_prediction.sh

For each run the training progress and the evaluation on the test set is written as a run log (together with tensorboard logs and predictions/ground truth of the test set) to indeqs/run_indeqs/output/. For more details, especially on where to insert graph adjacency data see here.

---

Generate data with the advection simulation:

cd simulation/
bash run_simulation.sh

The generated graph time series, together with the adjacency matrices and other assets are stored into simulation/output. For more details see here.

---

⚙️ Prerequisites

Before starting, ensure you have the following installed on your system:

1. uv (Package Manager):

curl -LsSf https://astral.sh/uv/install.sh | sh

(For other installation methods, see the official uv documentation.)

2. FFmpeg (Required for Simulation Animations): The simulation scripts use Matplotlib to generate video outputs. This requires the system-level FFmpeg binary.

• Ubuntu/Debian: sudo apt install ffmpeg
• macOS: brew install ffmpeg
• Without Admin Rights (via Conda): conda install -c conda-forge ffmpeg

---