Follow the WSL Installation tab first to set up Windows Subsystem for Linux, then proceed to the VECTRI Installation tab.

Skip directly to the VECTRI Installation tab if you're already running Ubuntu 22.04 LTS.

🪟 Windows Subsystem for Linux (WSL)¶

What is WSL?¶

Windows Subsystem for Linux (WSL) is a feature of Windows that allows you to run a Linux environment directly on Windows, without the need for a separate virtual machine or dual booting.

Why Use WSL for VECTRI?¶

Prerequisites¶

Before you start, ensure you have:

• ✅ Administrator access on your PC
• ✅ Hardware virtualization enabled in BIOS/UEFI (Intel VT-x / AMD-V)
• ✅ A reasonably up-to-date Windows build (Windows 10 version 2004+ or Windows 11)

Step 0: Enable Windows Features (GUI Method)¶

Before installing WSL, you can manually enable the required Windows features:

How to Open CMD as Administrator¶

1. Press Start (Windows key)
2. Type cmd
3. Right-click Command Prompt
4. Select Run as administrator

Installation Instructions¶

wsl --install

wsl --status

wsl -l -v

wsl --update

wsl --list --online

wsl --install -d Ubuntu-22.04

wsl --install

wsl --status

wsl -l -v

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

wsl --set-default-version 2

🔧 Troubleshooting¶

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

wsl -l -v

wsl --set-version Ubuntu-22.04 2

wsl --set-default-version 2

wsl -l -v

wsl --shutdown

wsl --update

wsl --unregister Ubuntu-22.04

📦 Post-Install: Prepare Ubuntu for VECTRI¶

Once inside your Ubuntu terminal, update packages and install essential tools:

sudo apt update && sudo apt upgrade -y

sudo apt install -y build-essential git curl wget unzip gfortran

📚 Quick Reference: WSL Commands¶

📖 Additional Resources¶

For more detailed WSL tutorials and guides, visit:

• WSL Installation Tutorial - Comprehensive guide with screenshots
• Microsoft WSL Documentation
• WSL GitHub Repository

🐍 WSL Post-Install Data Science Setup¶

Focused on Python, Conda/Mamba, Jupyter, VS Code Remote WSL, and NetCDF/xarray

1️⃣ Update Ubuntu Packages¶

Open your Ubuntu terminal:

sudo apt update

sudo apt upgrade -y

Install core build and utility tools:

sudo apt install -y build-essential git curl wget unzip ca-certificates

2️⃣ Install Miniconda (Recommended)¶

Download Miniconda:

cd ~

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

Install:

bash Miniconda3-latest-Linux-x86_64.sh

Follow prompts, then restart the terminal or run:

source ~/.bashrc

3️⃣ Install Mamba (Optional but Recommended)¶

Mamba is a faster drop-in replacement for conda:

conda install -n base -c conda-forge mamba -y

4️⃣ Create a Data Science Environment¶

mamba create -n ds python=3.11 -y

conda activate ds

Install the core scientific stack:

mamba install -c conda-forge -y numpy pandas scipy scikit-learn

mamba install -c conda-forge -y matplotlib seaborn

mamba install -c conda-forge -y jupyterlab ipykernel

mamba install -c conda-forge -y xarray netcdf4 h5netcdf dask

mamba install -c conda-forge -y cftime bottleneck

mamba install -c conda-forge -y cartopy geopandas rasterio rioxarray

mamba install -c conda-forge -y cfgrib eccodes

Register the Jupyter kernel:

python -m ipykernel install --user --name ds --display-name "Python (WSL ds)"

5️⃣ Install Node.js (Optional)¶

Required for some Jupyter extensions:

sudo apt install -y nodejs npm

6️⃣ JupyterLab Quick Start¶

jupyter lab

WSL usually auto-forwards localhost links to Windows.
If not, copy the URL and open it in your Windows browser.

7️⃣ VS Code + Remote WSL Workflow¶

On Windows¶

1. Install Visual Studio Code from code.visualstudio.com
2. Install the WSL extension from the Extensions tab

From Ubuntu¶

Open any folder in VS Code using the WSL backend:

code .

This opens the current folder in Windows VS Code, connected to WSL.

8️⃣ Recommended Folder Structure¶

Create organized directories inside Ubuntu:

mkdir -p ~/projects ~/data ~/notebooks

9️⃣ Accessing Windows Files¶

Your Windows drives are mounted under /mnt/:

Access C: drive:

cd /mnt/c

Access your Windows Documents folder:

cd /mnt/c/Users/<YourWindowsUser>/Documents

🔟 Climate/Geo Add-ons¶

Additional packages for climate and geospatial analysis:

mamba install -c conda-forge -y xclim xesmf regionmask

mamba install -c conda-forge -y intake intake-xarray

mamba install -c conda-forge -y zarr kerchunk

mamba install -c conda-forge -y metpy

1️⃣1️⃣ Quick Test Script¶

Verify your installation:

import xarray as xr

import numpy as np

print("xarray:", xr.__version__)

da = xr.DataArray(np.random.rand(10, 5, 5), dims=("time", "lat", "lon"))

print("Random data mean:", da.mean().item())

1️⃣2️⃣ GPU Support in WSL (Optional)¶

For machine learning with GPU acceleration:

Create a separate environment:

mamba create -n torch python=3.11 -y

conda activate torch

mamba install -c pytorch -c nvidia pytorch torchvision torchaudio pytorch-cuda=12.1 -y

Test GPU availability:

python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'No GPU')"

🔧 Common Fixes¶

sudo apt install -y ca-certificates

sudo update-ca-certificates

wsl --shutdown

1️⃣3️⃣ Minimal Alternative (Lighter Environment)¶

For a lighter setup without geospatial libraries:

mamba create -n light python=3.11 -y

conda activate light

mamba install -c conda-forge -y numpy pandas matplotlib xarray netcdf4 dask jupyterlab

📚 Environment Summary¶

🐳 Docker on WSL 2¶

Docker enables containerized applications, making it easy to run reproducible environments for scientific computing and VECTRI workflows.

Confirm WSL 2 is Ready¶

Open Windows CMD as Administrator:

wsl --status

wsl -l -v

✅ Your distro should show VERSION 2.

Choose Your Installation Path¶

Path A: Docker Desktop (Recommended)¶

Step 1: Remove Old Docker (Optional)¶

If you have old Docker installations inside WSL, remove them first:

sudo apt remove -y docker docker-engine docker.io containerd runc docker-compose docker-compose-v2 docker-doc podman-docker

Step 2: Install Docker Desktop on Windows¶

1. Download Docker Desktop for Windows from docker.com/products/docker-desktop
2. Run the installer
3. Start Docker Desktop

Step 3: Enable WSL 2 Engine¶

In Docker Desktop:

1. Go to Settings → General
2. ✅ Check Use the WSL 2 based engine
3. Click Apply & Restart

Step 4: Enable WSL Integration¶

In Docker Desktop:

1. Go to Settings → Resources → WSL Integration
2. ✅ Enable your Ubuntu distro
3. Click Apply & Restart

Step 5: Test Docker in Ubuntu¶

Open your Ubuntu terminal and run:

docker --version

docker compose version

docker run hello-world

✅ If hello-world succeeds, Docker is ready!

Best Performance Tip¶

Always work in the Linux filesystem for best Docker performance:

mkdir -p ~/projects

cd ~/projects

Path B: Docker Engine Inside WSL (Advanced)¶

This installs Docker directly inside WSL without Docker Desktop.

Step 1: Install Docker Engine¶

Update packages:

sudo apt update && sudo apt upgrade -y

Install prerequisites:

sudo apt-get install -y ca-certificates curl gnupg

Add Docker's official GPG key:

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

Add Docker repository:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine:

sudo apt update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 2: Start Docker Daemon¶

sudo service docker start

Step 3: Run Docker Without Sudo (Optional)¶

Add your user to the docker group:

sudo usermod -aG docker $USER

Restart WSL from Windows CMD:

wsl --shutdown

Then reopen Ubuntu.

Step 4: Test Docker¶

docker run hello-world

✅ If successful, Docker Engine is ready!

🔧 Troubleshooting¶

sudo service docker start

sudo usermod -aG docker $USER

wsl --shutdown

📚 Essential Docker Commands¶

🚀 Quick Start Examples¶

Run Ubuntu Container¶

docker run -it ubuntu:22.04 bash

Run Python Container¶

docker run -it python:3.11 python

Run Jupyter Notebook¶

docker run -p 8888:8888 jupyter/scipy-notebook

Then open the URL shown in the terminal.

📖 Additional Resources¶

• Docker Documentation
• Docker Desktop WSL 2 Backend
• Docker Hub

🧬 VECTRI Installation Guide¶

Target OS: Ubuntu 22.04 LTS (native or via WSL)
Purpose: Install all required libraries and build the VECTRI malaria model

1️⃣ Set Compilers and Flags¶

Check compiler availability:

which gcc g++ gfortran

gcc --version

gfortran --version

Export compiler environment variables:

export CC=gcc

export CXX=g++

export FC=gfortran

export F77=gfortran

Enable Fortran-10+ argument compatibility flags:

gcc_version=$(gcc -dumpversion | cut -d. -f1)
if [ "$gcc_version" -ge 10 ]; then
  export fallow_argument="-fallow-argument-mismatch"
  export boz_argument="-fallow-invalid-boz"
else
  export fallow_argument=""
  export boz_argument=""
fi

export FFLAGS="$fallow_argument $boz_argument"

export FCFLAGS="$fallow_argument $boz_argument"

2️⃣ Create Installation Prefix Directories¶

Create a workspace for source downloads:

cd ~

mkdir -p ~/download_lib

cd ~/download_lib

sudo apt update

sudo mkdir -p /opt/apps/libs

BASE_DIR=/opt/apps/libs

Set shared prefix for each library:

ZPFX=$BASE_DIR/zlib/1.2.12

SPFX=$BASE_DIR/szip/2.1.1

JPFX=$BASE_DIR/jasper/1.900.1

HPFX=$BASE_DIR/hdf5/1.12.2

NPFX=$BASE_DIR/netcdf/4.9.0

Create the prefix directories:

sudo mkdir -p $ZPFX $SPFX $JPFX $HPFX $NPFX

3️⃣ Download Sources¶

cd ~/download_lib

Download ZLIB:

wget -c -4 https://github.com/madler/zlib/archive/refs/tags/v1.2.12.tar.gz

Download SZIP:

wget -c -4 https://support.hdfgroup.org/ftp/lib-external/szip/2.1.1/src/szip-2.1.1.tar.gz

Download JasPer (JPEG-2000):

wget -c -4 https://www.ece.uvic.ca/~frodo/jasper/software/jasper-1.900.1.zip

Download HDF5:

wget -c -4 https://github.com/HDFGroup/hdf5/archive/refs/tags/hdf5-1_12_2.tar.gz

Download NetCDF-C:

wget -c -4 https://github.com/Unidata/netcdf-c/archive/refs/tags/v4.9.0.tar.gz

Download NetCDF-Fortran:

wget -c -4 https://github.com/Unidata/netcdf-fortran/archive/refs/tags/v4.6.0.tar.gz

4️⃣ Build and Install Each Library¶

🔹 ZLIB¶

tar xf v1.2.12.tar.gz

cd zlib-1.2.12

./configure --prefix=$ZPFX

make 

sudo make install

cd ..

🔹 SZIP¶

tar xf szip-2.1.1.tar.gz

cd szip-2.1.1

./configure --prefix=$SPFX

make 

sudo make install

cd ..

🔹 JasPer¶

unzip jasper-1.900.1.zip

cd jasper-1.900.1

Regenerate configure scripts:

autoreconf -i

./configure --prefix=$JPFX

make

sudo make install

cd ..

🔹 HDF5 (Serial build)¶

tar xf hdf5-1_12_2.tar.gz

cd hdf5-hdf5-1_12_2

export CPPFLAGS="-I$ZPFX/include -I$SPFX/include"

export LDFLAGS="-L$ZPFX/lib -L$SPFX/lib"

./configure --prefix=$HPFX --enable-hl --enable-fortran --with-zlib=$ZPFX --with-szlib=$SPFX

make

sudo make install

cd ..

🔹 NetCDF-C¶

tar xf v4.9.0.tar.gz

cd netcdf-c-4.9.0

export CPPFLAGS="-I$HPFX/include"

export LDFLAGS="-L$HPFX/lib -L$ZPFX/lib -L$SPFX/lib"

./configure --prefix=$NPFX --enable-netcdf-4 --disable-dap

make 

sudo make install

cd ..

🔹 NetCDF-Fortran¶

tar xf v4.6.0.tar.gz

cd netcdf-fortran-4.6.0

export CPPFLAGS="-I$NPFX/include"

export LDFLAGS="-L$NPFX/lib -Wl,-rpath,$NPFX/lib"

./configure --prefix=$NPFX

make 

sudo make install

cd ..

5️⃣ Set Environment Variables¶

Add the following to your ~/.bashrc to make the libraries available:

cat <<'EOF' >> ~/.bashrc
# NetCDF libraries for VECTRI
export PATH=/opt/apps/libs/netcdf/4.9.0/bin:$PATH
export LD_LIBRARY_PATH=/opt/apps/libs/netcdf/4.9.0/lib:/opt/apps/libs/hdf5/1.12.2/lib:/opt/apps/libs/zlib/1.2.12/lib:/opt/apps/libs/szip/2.1.1/lib:$LD_LIBRARY_PATH
export CPATH=/opt/apps/libs/netcdf/4.9.0/include:$CPATH
EOF

source ~/.bashrc

Verify Installation¶

which nc-config

which nf-config

nc-config --version

nf-config --version

6️⃣ VECTRI Model Installation¶

Download VECTRI¶

cd ~

git clone https://gitlab.com/tompkins/vectri.git

cd vectri

ls

Set Environment Variables¶

export VECTRI="$HOME/vectri"

export NETCDF_LIB="$(nf-config --flibs)"

export NETCDF_INCLUDE="$(nf-config --fflags)"

export FC="$(nf-config --fc)"

Verify the variables:

echo $VECTRI

Persist Across Logins¶

Append to ~/.bashrc:

cat <<'EOF' >> ~/.bashrc
export VECTRI="$HOME/vectri"
export NETCDF_LIB="$(nf-config --flibs)"
export NETCDF_INCLUDE="$(nf-config --fflags)"
export FC="$(nf-config --fc)"
EOF

source ~/.bashrc

Create a Separate Workspace and Run¶

cd ~

mkdir -p ~/run

cd run

View command line options:

$VECTRI/vectri

Run example simulation:

$VECTRI/vectri -c $VECTRI/data/example_sys5.nc -d $VECTRI/data/example_data.nc

If the model compiles successfully, you should see:

• A compile phase producing vectri.exe
• Runtime logs (vector/disease, climate variable aliases, etc.)
• Simulation progress and completion status

• If successful 🎉, typing ls should show the output file vectri.nc

7️⃣ Verification and Troubleshooting¶

📖 Additional Resources¶

• VECTRI GitLab Repository
• VECTRI Documentation
• ICTP VECTRI Resources

🐳 VECTRI Docker Image – User Guide¶

Run the VECTRI malaria transmission model using Docker

📌 Overview¶

This Docker image provides a clean, reproducible environment for running the VECTRI malaria model.

✅ 1. Pull the VECTRI Docker Image¶

Use this command to download the latest stable build:

docker pull yonasmersha/vectri:latest

Verify the image was downloaded:

docker images | grep vectri

Expected output:

yonasmersha/vectri   latest   abc123def456   2 days ago   1.2GB

📂 2. Prepare a Working Directory¶

VECTRI writes outputs to a run directory. Create one on your host machine:

mkdir -p vectri_runs

cd vectri_runs

This directory will be mounted inside the container, allowing you to:

• Pass input files to VECTRI
• Retrieve output files after the simulation

▶️ 3. Start the VECTRI Docker Container¶

Run an interactive shell inside the image and mount your vectri_runs directory:

docker run --rm -it -v "$PWD:/home/vectriuser/runs" yonasmersha/vectri:latest

docker run --rm -it -v "${PWD}:/home/vectriuser/runs" yonasmersha/vectri:latest

docker run --rm -it -v "%cd%:/home/vectriuser/runs" yonasmersha/vectri:latest

You should now see a prompt like:

vectriuser@<container-id>:~$

🧪 4. Run a Sample VECTRI Simulation¶

Inside the container, navigate to your mounted run directory:

cd ~/runs

mkdir demo_run

cd demo_run

Run VECTRI using example input files included in the image:

vectri -c $VECTRI/data/example_sys5.nc -d $VECTRI/data/example_data.nc -o vectri_output.nc

When successful, your folder will contain:

vectri_output.nc

🧾 5. Understanding Input and Output Files¶

Input Files¶

Output File¶

Inspect Output (Optional)¶

View the output file structure:

ncdump -h vectri_output.nc

Or use Python (if available on your host):

import xarray as xr

ds = xr.open_dataset("vectri_runs/demo_run/vectri_output.nc")

print(ds)

🔁 6. Run VECTRI With Your Own Input Files¶

Step 1: Place Your Files in the Mounted Directory¶

On your host machine, copy your input files to vectri_runs/:

vectri_runs/
 ├── my_climate.nc
 ├── my_population.nc
 └── ...

Step 2: Start the Container¶

docker run --rm -it -v "$PWD:/home/vectriuser/runs" yonasmersha/vectri:latest

Step 3: Run VECTRI¶

Inside the container:

cd ~/runs

vectri -c ~/runs/my_climate.nc -d ~/runs/my_population.nc -o my_vectri_results.nc

Step 4: Access Results¶

Exit the container (exit or Ctrl+D) and find your results in:

vectri_runs/my_vectri_results.nc

⚠️ 7. Troubleshooting¶

cd ~/runs

🧹 8. Manage Docker Resources¶

Remove the VECTRI Image¶

docker rmi yonasmersha/vectri:latest

Clean Up Unused Docker Resources¶

docker system prune

Check Disk Usage¶

docker system df

📚 Quick Reference¶

📖 Citation¶

If you use VECTRI in research, please cite the original authors:

👤 Contact¶