Quick start

Install AuroraChem, set up the input data, and run a rollout

Requirements

  • A CUDA-capable GPU
  • Python 3.12 or later
  1. Install AuroraChem

    git clone https://github.com/AuroraChem/AuroraChem.git
    cd AuroraChem
    pip install -r requirements.txt

    The repository includes a modified copy of Microsoft Aurora 1.8.0 in aurora/. Do not install the microsoft-aurora package separately.

  2. Set up the input data

    Set data_dir and output_dir in the configuration files in configs/. The data directory has one folder per data source:

    data_dir/
    ├── GEOS_Chem/     chemical fields
    ├── era5_interp/   ERA5 meteorology and static fields
    ├── emissions/     CAMS monthly emissions
    ├── MERRA2/        only if met_type is "merra2"
    └── TROPOMI/       only for TROPOMI NO2 insertion

    All fields are on the 4°×5° grid and 13 pressure levels listed on the Model description page.

  3. Get the model weights

    Download the pretrained AuroraChem weights from the Model weights page and place both files in output_dir/Weights/.

    To train your own weights instead, run the training script. It downloads the pretrained Aurora weights from Hugging Face on the first run.

    python -m scripts.aurora_train --config configs/aurora_train_config.yml
  4. Run a rollout

    Run the evaluation script from the repository root. The configuration file sets the start and end times and the type of rollout.

    python -m scripts.aurora_eval --config configs/aurora_eval_config.yml

    The default configuration runs from 00 UTC on 1 January 2019 to 12 UTC on 31 December 2019.

  5. Insert fields during a rollout (optional)

    The rollout block of the configuration file controls direct insertion. nudge_int is the number of 6 h steps between insertions, so 20 inserts every 5 days.

    rollout:
        rollout_bool: True
        rollout_type: "nudged_met"
        nudge_int: 20
        met_nudge_fields: ["t", "q", "u", "v", "z"]
        chem_nudge_fields: ["OH", "NO", "NO2", "Cl", "O3", "CO", "C14O"]
    rollout_typeFields inserted
    freeNone
    nudgedAll meteorological and chemical fields
    nudged_metMeteorological fields only
    nudged_chemChemical fields only
    nudged_partialThe fields listed in met_nudge_fields and chem_nudge_fields
    nudged_tropomi_no2NO2 profiles in grid cells with valid TROPOMI pixels
    nudged_tropomi_no2_akNO2 columns computed with a TROPOMI averaging kernel

Output

Rollouts are written as netCDF files to output_dir. The file name contains the run name, the start and end dates, and the rollout type.

For technical support, please open an issue on GitHub.