How to Set Up the WeatherNext Environment for Development: Complete Setup Guide

To set up the WeatherNext development environment, clone the google-deepmind/weathernext repository, create a Python 3 virtual environment, install the package in editable mode with pip install -e ., install JAX for your specific hardware (GPU or TPU), and verify the installation by running pytest -q weathernext.

The google-deepmind/weathernext repository provides a research-grade atmospheric forecasting codebase built on JAX and Xarray. Whether you are running inference on local GPUs or developing on Cloud TPUs, properly configuring your development environment ensures access to the model architectures in weathernext/weathernext2/architecture.py, checkpoint utilities in weathernext/utils/model_utils.py, and cyclone tracking tools.

Prerequisites and System Requirements

WeatherNext requires Python 3 and supports both GPU and TPU backends via JAX. The codebase is designed for Linux workstations and Google Colab environments.

Hardware Backends: GPU vs. TPU

• GPU Development: Standard CUDA 12.x compatible wheels work for local workstations. Install using pip install "jax[cuda12]" with the JAX CUDA release URL.
• TPU Development: Required for Cloud TPU or Colab environments. Install using pip install "jax[tpu]" with the libtpu release URL.

Step-by-Step WeatherNext Environment Setup

1. Clone the Repository and Create an Isolated Environment

Create a dedicated virtual environment to avoid conflicts with system packages. Using venv or conda both work, though the repository documentation emphasizes standard Python environments.

# Clone the repository

git clone https://github.com/google-deepmind/weathernext.git
cd weathernext

# Create and activate virtual environment

python3 -m venv venv
source venv/bin/activate

2. Install the Core Package and Dependencies

The repository ships with a setup.py that declares dependencies including JAX, NumPy, Xarray, and other scientific libraries. Install in editable mode to enable development changes.

pip install -e .

This command pulls in the core dependencies required by weathernext/weathernext2/architecture.py and the utilities in weathernext/utils/model_utils.py.

3. Configure JAX for Your Hardware

After installing the base package, install the JAX distribution matching your accelerator.

# For GPU (CUDA 12.x)

pip install "jax[cuda12]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

# For TPU (Colab or Cloud TPU)

pip install "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html

4. Install Optional Dependencies

If you plan to work with older GraphCast or GenCast models referenced in the codebase, install their respective packages from the DeepMind repositories.

# Optional: GraphCast support

pip install git+https://github.com/deepmind/graphcast.git

# Optional: GenCast support  

pip install git+https://github.com/deepmind/gencast.git

Additionally, install Jupyter for running the demonstration notebooks and tf-nightly if utilizing TensorFlow-based utilities within the codebase.

5. Verify the Installation

Run the test suite to confirm that JAX, NumPy, and the WeatherNext utilities initialize correctly.

pytest -q weathernext

A successful run indicates that weathernext/cyclones/tracker_base.py and other core modules load without import errors.

Running Your First Inference

Once the environment is configured, load pre-trained weights from the public Google Cloud bucket and execute an auto-regressive rollout. The load_checkpoint and init_state functions in weathernext/utils/model_utils.py handle checkpoint fetching and state initialization.

import jax
import weathernext.weathernext2.architecture as wn2
from weathernext.utils.model_utils import load_checkpoint, init_state

# Load pre-trained weights (e.g., Mini model)

ckpt_url = "gs://weather-next-bucket/WeatherNextCyclones_Mini_2024.npz"
params = load_checkpoint(ckpt_url)

# Initialize state with random keys

rng = jax.random.PRNGKey(0)
state = init_state(rng, params)

# Run single auto-regressive step defined in architecture.py

next_state = wn2.autoregressive_step(state, params)
print("Forecast step completed, shape:", next_state.fields.shape)

Key Source Files for Developers

Understanding the repository structure helps navigate the development environment:

• setup.py: Declares Python package dependencies and entry points used during pip install.
• docs/weathernext2/wn2_demo.ipynb: Interactive Colab notebook demonstrating end-to-end inference, cyclone tracking, and visualization.
• weathernext/weathernext2/architecture.py: Core model definition containing autoregressive_step and network architectures.
• weathernext/utils/model_utils.py: Implements load_checkpoint(), init_state(), and TPU-compatible sharding helpers.
• weathernext/cyclones/tracker_base.py: Base implementation for the direct cyclone tracker used in demonstration workflows.
• CONTRIBUTING.md: Guidelines for code style, testing requirements, and CI workflows when submitting changes.

Summary

• Clone google-deepmind/weathernext and create a Python virtual environment to isolate dependencies.
• Install the package in editable mode with pip install -e . using the provided setup.py.
• Install JAX with CUDA 12 support for GPUs or TPU support for Cloud TPU/Colab environments.
• Verify functionality by running pytest -q weathernext to test the installation.
• Use weathernext/utils/model_utils.py for checkpoint loading and docs/weathernext2/wn2_demo.ipynb for reference implementations.

Frequently Asked Questions

Do I need a TPU to run WeatherNext?

No. While the codebase supports TPU acceleration via jax[tpu], it runs efficiently on NVIDIA GPUs with CUDA 12 using the jax[cuda12] wheels. The docs/weathernext2/wn2_demo.ipynb notebook works on both local GPU workstations and Colab TPU runtimes.

What Python version is required for WeatherNext?

The repository requires Python 3 and follows standard scientific Python packaging. The setup.py file specifies exact dependency versions compatible with JAX 0.4.x and NumPy 1.24+ for numerical stability.

How do I load pre-trained model weights?

Use the load_checkpoint() function from weathernext/utils/model_utils.py, which automatically fetches weights from Google Cloud Storage URLs (e.g., gs://weather-next-bucket/WeatherNextCyclones_Mini_2024.npz) and handles deserialization.

Where can I find the official demo notebook?

The official demonstration notebook is located at docs/weathernext2/wn2_demo.ipynb in the repository root. You can open it directly in Google Colab via the GitHub integration or run it locally after completing the environment setup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}