README
M. Sulprizio (Aug 20, 2026)

Overview
========

This folder contains scripts needed to crop global MERRA-2 meteorology fields
to regional domains supported by GEOS-Chem (geos-chem.org).  It is the
MERRA-2 counterpart of the GEOS-FP cropping scripts located at:

    ExtData/GEOS_0.25x0.3125/crop_met_fields

At 0.5 x 0.625 resolution, pre-cut MERRA-2 meteorological files are available
for the following domains:

    Asia (AS)          : 11S-55N, 60E-150E

    Europe (EU)        : 30N-70N, 30W-50E

    North America (NA) : 10N-70N, 140W-40W

You may utilize other regions, but this requires either using global
meteorological fields which can be computationally expensive (not
recommended) or by cropping global meteorological fields via a
pre-processing step.

To facilitate cropping global meteorological fields at 0.5 x 0.625
resolution, a sample script (crop_met.sh) is included here.  This script
utilizes the Climate Data Operators (CDO).  It also includes an option to
first download the global meteorological fields.  The global files are large
(approx. 3 GB per day, or 100 GB per month), so when using that option it is
recommended that you process short periods at a time and delete the global
files before processing additional periods.

NOTE: Unlike GEOS-FP, the global 0.5 x 0.625 MERRA-2 archive is no longer
hosted at the GEOS-Chem Input Data portal.  It is hosted on Amazon Web
Services at:

    s3://geos-chem/GEOS_0.5x0.625/MERRA2
    https://geos-chem.s3.amazonaws.com/GEOS_0.5x0.625/MERRA2

The download option in crop_met.sh retrieves the files from AWS, either with
the AWS CLI (DownloadMethod="aws", recommended) or with wget over HTTPS
(DownloadMethod="wget").  Neither method requires an AWS account.

Requirements
============

   - Climate Data Operators (CDO)
   - netCDF Operators (NCO), which provide the nccopy and ncdump commands
     used by nc_chunk.pl
   - AWS CLI, if DownloadMethod="aws" (not needed if you already have the
     global files on your system, or if you use DownloadMethod="wget")

Instructions
============

In a text editor, modify the user settings section in crop_met.sh.

   - RegionID          : Two-letter string to identify region (e.g. SA for South
                         America).
   - LonMin            : Minimum longitude edge of the region of interest.
   - LonMax            : Maximum longitude edge of the region of interest.
   - LatMin            : Minimum latitude edge of the region of interest.
   - LatMax            : Maximum latitude edge of the region of interest.
   - DownloadGlobalMet : Boolean for downloading global 0.5 x 0.625
                         meteorology fields for cropping. Default is true.
                         Set to false if you already have these files on your
                         system.
   - RemoveGlobalMet   : Boolean for deleting each global meteorology file
                         after it has been cropped. Default is false. Set to
                         true once you are sure the cropped meteorology files
                         are working properly in the model and you do not plan
                         to generate cropped files for additional regions.
   - GlobalDir         : Directory containing the global meteorology fields.
   - RegionalDir       : Directory where the cropped meteorology files will be
                         placed.
   - DownloadMethod    : Either "aws" (use the AWS CLI, recommended) or "wget"
                         (download each file over HTTPS).
   - ProcessConstantFields : Boolean for cropping the constant (CN) fields
                         file. This file is required by GEOS-Chem, but only
                         needs to be processed once per region.
   - Year, StartMonth, EndMonth : Dates to process.

The cropped meteorology files can be generated by then executing ./crop_met.sh
at the command line or submitting the script to your cluster's scheduler if
available. Headers for the SLURM scheduler are included at the top of the
script, but you can modify or remove those as needed.

Notes
=====

1. File naming.  GEOS-Chem expects the region ID to be inserted between the
   grid resolution and the file extension, and MERRA-2 files use the .nc4
   extension (GEOS-FP files use .nc).  The script handles this for you, e.g.

       MERRA2.20190701.A1.05x0625.SA.nc4
       MERRA2.20150101.CN.05x0625.SA.nc4

2. Constant fields.  The MERRA-2 constant (CN) fields file is timestamped
   20150101 (the GEOS-FP CN file is timestamped 20110101).  It only needs to
   be cropped once per region.

3. Domain extent.  The nested-grid buffer zone (3 grid boxes per side by
   default) lies inside the simulation domain, so the cropped meteorology
   only needs to cover the domain you intend to simulate.  Cropping a small
   margin beyond it is harmless.

4. Updating your run directory.  createRunDir.sh only offers the pre-cut
   domains listed above.  For any other domain you will need to edit:

     - geoschem_config.yml, to set your longitude and latitude ranges in
       the "grid" section; and
     - HEMCO_Config.rc.gmao_metfields, to point METDIR at your cropped
       archive and to add the region ID to the met field file names.

5. Metadata.  CDO does not carry over the scale_factor and add_offset
   attributes (which are 1.0 and 0.0 for all MERRA-2 met fields, i.e. they
   perform no scaling) and adds CDI and CDO global attributes.  This matches
   the pre-cut nested-grid files that we distribute and has no effect on
   GEOS-Chem.