Annau, Cannon, and Monahan 2023

Quick start

Analysis and plots for the paper.

Cite the paper

@article { AlgorithmicHallucinationsofNearSurfaceWindsStatisticalDownscalingwithGenerativeAdversarialNetworkstoConvectionPermittingScales,
      author = "Nicolaas J. Annau and Alex J. Cannon and Adam H. Monahan",
      title = "Algorithmic Hallucinations of Near-Surface Winds: Statistical Downscaling with Generative Adversarial Networks to Convection-Permitting Scales",
      journal = "Artificial Intelligence for the Earth Systems",
      year = "2023",
      publisher = "American Meteorological Society",
      address = "Boston MA, USA",
      volume = "2",
      number = "4",
      doi = "10.1175/AIES-D-23-0015.1",
      pages=      "e230015",
      url = "https://journals.ametsoc.org/view/journals/aies/2/4/AIES-D-23-0015.1.xml"
}

Docker Hub Image analysis+data+environment

Analysis only

Data only

Data availability

Data is not stored on GitHub because of repo size limits. Therefore, the analysis code and data are hosted separately. However, an image with the analysis code and data is hosted on Docker Hub in an isolated PyTorch environment. Instructions for use are below, and I recommend using the docker image. If you decide you want to build the Docker image yourself, you can find the entire repo plus data hosted by Zenodo with its own DOI (the Data only DOI).

Requirements

• Docker
• NVidia Container Toolkit

Getting started

You have a few options on how to get the repo working on your machine. I recommend using the docker image from Docker Hub because it includes the relevant dataset, and requires the least configuration to reproduce our results.

From Docker Hub [recommended]

The most recent stable version is tagged latest.

docker run -p 8888:8888 --gpus all --ipc=host --network host --ulimit memlock=-1 --ulimit stack=67108864 -it --rm nannau/annau-2023:latest

The default password is set to annau2023.

---

Docker Locally

Set Jupyter Password

If building the docker image locally, to make accessing JupyterLab easier, I've enabled setting a Jupyter password as an environment variable on the host machine. Set a local environment variable as:

export JUPYTER_PASSWORD=password

Clone this repo and cd into it

Build docker locally using docker compose with:

docker compose up --build

---

Without Docker Locally

python3 -m venv myvenv

source myvenv/bin/activate

pip install -e .

pip install -r requirements.txt

jupyter lab

Accessing Jupyter Lab

Each option will run a Jupyter Lab server. The process to connect may change for each:

Using Docker, go to http://localhost:8888/lab? and enter annau2023 as the password.

You might have to refresh if the files don't show up immediately.

A quick word on security

Please do not use this repo and assume the Jupyter Lab instance running on Docker is secure. I am not a security expert! This repo is intended only to reproduce our results so use it responsibly and don't run it publicly without taking percautions.

A note about GPUs

I can't guarantee that this code will run on all hardware.

I've developed this repo using a GPU. The results might work without one, and I've tried to enable this, but if you run into issues and don't have a GPU, please change the source code to meet your needs (i.e. make sure the PyTorch tensors are loaded onto the CPU instead of the GPU). CPU will be much slower.