This tutorial focuses on running a 0.25-degree air quality simulation for China and processing the model output data. For other types of simulations, please refer to additional tutorials. The process generally consists of two steps: running the global model and the regional model. The global model provides boundary conditions for the regional model.

Contents:
1. Global Model
1.1 Copying the Code
1.2 Code Compilation
1.3 Run Directory
1.4 Running the Program
2. Regional Model
2.1 Code Compilation
2.2 Run Directory
2.3 Emissions Modification (optional)
2.3.1 Enabling MIX Inventory
2.3.2 Modifying Emissions Files
2.4 Running the Program
2.5 More Information
3. Output Data Processing
3.1 Data Format
3.2 Data Processing
3.3 Data Results

1. Global Model

1.1 Copying the Code
The GEOS-Chem code is located at: `/data/Lab/GEOS-Chem/Code.12.1.0`.
First, create a new GEOS-Chem directory in your home folder:

mkdir ~/GEOS-Chem

Next, copy the public code version from the research group to this directory:

cp -r /data/Lab/GEOS-Chem/Code.12.1.0 ~/GEOS-Chem
cp -r /data/Lab/GEOS-Chem/env.gc ~/GEOS-Chem

1.2 Code Compilation
The GEOS-Chem code is written in Fortran and must be compiled into an executable file. Navigate to the code directory:

cd ~/GEOS-Chem/Code.12.1.0

Load the required environment variables for compilation:

source ~/GEOS-Chem/env.gc

Then, use the `make` command to compile the model, specifying the required meteorological data, grid type, and chemistry. Detailed explanations can be found in Chapter 3 of the GEOS-Chem User’s Guide [1].

make realclean
make -j12 MET=geosfp GRID=4x5 CHEM=tropchem BPCH_TPBC=y

This command uses 12 CPU cores for parallel compilation (since the login node has 24 cores, it’s recommended to use no more than 12 to avoid affecting others). The model uses GEOSFP meteorological data, a 4×5 grid, and tropospheric chemistry. Compilation will take a few minutes. If any errors occur, they will be highlighted in red, making them easy to spot.

1.3 Run Directory
First, copy the public run directory from the research group to your GEOS-Chem directory:

cp -r /data/Lab/GEOS-Chem/rundir/geosfp_4x5_tropchem_12.1.0 ~/GEOS-Chem

Then, copy the compiled executable file (`geos`) to your run directory:

cd ~/GEOS-Chem/geosfp_4x5_tropchem_12.1.0
cp ../Code.12.1.0/bin/geos ./

1.4 Running the Program
To run the program, submit the task script to the Caramel server:

cd ~/GEOS-Chem/geosfp_4x5_tropchem_12.1.0
bsub < run.GC.geosfp.4x5

You can use the following command to continuously monitor the output log:

tail -f geos.log

If any errors occur, they will be shown here. To exit the display, press `Ctrl + C`.

2. Regional Model

The regional model runs slightly differently from the global model. Follow these steps:

2.1 Code Compilation
Enter the code directory (both the regional and global models use the same code):

cd ~/GEOS-Chem/Code.12.1.0

Next, compile the model:

make realclean
make -j12 MET=geosfp GRID=0.25x0.3125 NEST=ch CHEM=tropchem

Here, `NEST=ch` indicates that the nested region is China.

2.2 Run Directory
First, copy the public run directory to your GEOS-Chem directory:

cp -r /data/Lab/GEOS-Chem/rundir/geosfp_025x03125_tropchem_ch_12.1.0 ~/GEOS-Chem

Then, copy the compiled executable file (`geos`) to your run directory:

cd ~/GEOS-Chem/geosfp_025x03125_tropchem_ch_12.1.0
cp ../Code.12.1.0/bin/geos ./

Note: There is a folder named `BC_4x5_CH` in this directory, which is a symbolic link to the global model’s output results. If you want to use pre-generated boundary conditions, you can remove this symbolic link and link to my results instead:

rm BC_4x5_CH
ln -s /data/home/yxzhang/GEOS-Chem/geosfp_4x5_tropchem/BC_4x5_CH .

(However, this link has expired, so it is recommended to generate your own `BC_4x5_CH` folder or use another valid source.)

.3 Emissions Modification (Optional)
Since the global model is only used to provide boundary conditions, we can use the default emissions inventory. However, for the regional model, emissions need to be modified, and we can add a custom inventory. Emissions are controlled by HEMCO.

2.3.1 Enabling MIX Inventory
The MIX inventory is specifically tailored for Asian emissions. Open the `HEMCO_Config.rc` file with a text editor:

gedit HEMCO_Config.rc

Around line 121, ensure that the MIX inventory is enabled:

--> MIX : true

Ensure it says `true` instead of `false`.

2.3.2 Modifying Emissions Files
To modify the emissions files, starting around line 735, you’ll see the following code:

#==============================================================================
# --- MIX v1.1 (Asia) ---
#==============================================================================
(((MIX
0 MIX_NO_IND $ROOT/MIX/v2015-03/MIX_Asia_NO.generic.025x025.nc NO_INDUSTRY 2008-2010/1-12/1/0 C xy kg/m2/s NO 1/27/25/1006 1/2 45
0 MIX_NO_POW $ROOT/MIX/v2015-03/MIX_Asia_NO.generic.025x025.nc NO_POWER 2008-2010/1-12/1/0 C xy kg/m2/s NO 1/27/25/1006 1/2 45
...
)))

This configuration sets the specific parameters for the MIX inventory. You can modify or add entries as needed. For example, to add a new NO emission source for heating, you could add a line like this:

0 MIX_NO_HEAT /data/home/yxzhang/Heat_NO.generic.025x025.nc NO_INDUSTRY 2008-2010/1-12/1/0 C xy kg/m2/s NO 1/27/25/1006 1/2 45

For more examples, refer to the tutorial text.

2.4 Running the Program
Submit the task script to the Caramel server to run the simulation:

cd ~/GEOS-Chem/geosfp_025x03125_tropchem_ch
bsub < run.geosfp.0.25x0.3125

Keep in mind that the program may take several days to complete a year-long simulation. You can run multiple scenarios simultaneously in different directories.

2.5 More Information
Use `bjobs` to check the job status and `bkill` to terminate the job early. For more details, refer to section 6 of this wiki.

3. Output Data Processing

3.1 Data Format
The output data is located in the run directory:

cd ~/GEOS-Chem/geosfp_025x03125_tropchem_ch_12.1.0

The output files are typically named `trac_avg.geosfp_025x03125_tropchem_ch.YYYYMMDDHHMM`, where `YYYYMM` represents the time of your simulation. These files are in binary format (`bpch`). The next version will use NetCDF format.

3.2 Data Processing
To process the data, especially for PM2.5, a script is needed. Here is an example script you can copy to your run directory:

cp /data/Lab/GEOS-Chem/scripts/get_conc.pro ~/GEOS-Chem/geosfp_025x03125_tropchem_ch_12.1.0

This script is well-documented and can be modified as needed. To run it, enter the IDL environment and execute the script:

idl
.r get_conc
a=get_conc('trac_avg.geosfp_025x03125_tropchem_ch.201412010000','pm2.5',2014)
a=get_conc('trac_avg.geosfp_025x03125_tropchem_ch.201412010000','o3',2014)

3.3 Data Results
The result of running the script includes a `.ps` file (pollutant concentration distribution over China) and a `.txt` file (containing longitude, latitude, and concentration). You can use familiar programming languages (e.g., MATLAB) to further process the data, such as calculating mean concentrations or differences between scenarios.