Using the RadApp tool
Overview
The RadApp tool is a lightweight application running thru MAPL_Cap that runs the Radiation gridded component as well as the PCHEM gridded component to provide aerosols to the radiation. Since it is run through MAPL_Cap the application can be run for multiple time steps and output any export of the Radiation components through the History, just as in the full GEOS5 model. The application uses ExtData to drive the tool with external data on disc. The user should consult with the documentation on ExtData for details in how this component works. Like any MAPL application it requires a CAP.rc, HISTORY.rc, and ExtData.rc file.
Setup
There are two ways to obtain and build RadApp. You should use the first way unless you are an advanced user.
The first and recommended way build RadApp is to checkout the stand alone RadApp module using the appropriate tag. This will get you a copy of RadApp with appropriate pieces of the GEOS-5 model needed to build RadApp. There is NO NEED for a separate full model checkout. Follow these steps.
- Checkout a tag the standalone RadApp. Currently there is one tag using Ganymed-4_0 which is RadApp_Ganymed-4_0. To check out this tag issue: cvs co -r RadApp_Ganymed-4_0 GEOSdaig
- In the directory you did the check you will see a GEOSdiag directory. This is akin to a full model checkout in that in the GEOSdiag directory you will find a src directory with an Applications applications directory where the RadApp application lives, a GMAO_Shared directory that has the usual things such as MAPL, etc ... , and a Component directory where the science components (Radiation, PChem) live. Set the environment variable $ESMADIR to /path_to_checkout/GEOSdiag
- Source $ESMADIR/src/g5_modules to set the appropriate modules and environment variables
- Go to $ESMADIR/src and issue: make install
- You can also do a parallel build is you are not on a login node by issuing: make -jn pinstall, where n is a number_of_processes
- Under src/Applications/GEOSdiag_App you will find RadApp.x
The second way is to checkout just RadApp and link to a compiled copy of the full GEOS5 model. The current RadApp has been developed and tested with the Ganymed-3_0 and Ganymed-4_0 tags. You should really use the method described above!
- Checkout and built the model tag
- Checkout the application by issuing: cvs co -r tag GEOSdiag_App
- Make sure the environment variable ESMADIR is setup probably for the model build you want to link the application to. Typically this is /path_to_model/GEOSagcm. If this is correct there should be a src and linux directory under ESMADIR. Make you source $ESMADIR/Linx/bin/g5_modules to make sure the modules you need to build are added.
- Now simply issue: make install, and RadApp.x should be built if everything is ok.
Organization of the RadApp Program
The RadApp program is run through the MAPL_Cap. This means there is a lightweight executable that calls the MAPL_Cap. This in turn calls the root component below the cap, as well as the HISTORY and ExtData gridded components. RadApp consists of a Root_Component run from the cap that currently has three children. The first is the Radiation gridded component itself. The second is pchem. Finally there is a third component RadEnv that takes care of provider some imports to radiation and the aerosol bundle if pchem is not being run. In the future other chemistry components besides pchem could be put in place. The following are a list of imports that are expected in ExtData, that are provided by RadEnv, and that are either provided by pchem or ExtData thru RadEnv.
Interactive aerosols: OX, O3, CH4, N2O, CFC11, CFC12, FCFC22
Non-Interactive aerosols: du001,du002,du003,du004,du005,ss001,ss002,ss003,ss004,ss005,SO4,BCphobic,BCphilic,OCphobic,OCphilic
Always produced by RadEnv: PREF, RI, RL
Must come through ExtData: ALBNF, ALBNR, ALBVF, ALBVR, EMIS, TS, TSINST, SWNDSRF, TROPP, PLE, PLEINST, FCLD, PL, QI, QILS, QICN, QL, Q, QV, T, U, QR, QS, RR, RS
Resource File
The following are keywords that can be used in the resource file for RadApp. The name of the resource file for RadApp is specified in the CAP.rc file with the ROOT_CF keyword. Many of these keywords are the same as in the AGCM.rc for the full model.
NX: integer layout in first dimension
NY: integer layout in the second dimension
IM: integer gridsize in first dimension
JM: integer gridsize in second dimension
LM: integer number of vertical levels
GRIDNAME: name of the grid, follows the same convention as model; for example a 2 degree lat-lon grid would be PC144x91-DC
There are a set of several keywords that determine how solar and irrad run such as when the flux is evaluated and if radiation runs less frequently than the timestep in CAP.rc.
SOLAR_DT: integer timestep for full radiation calculation
IRRAD_DT: integer timestep for full radiation calculation
IRRAD_CALLED_LAST: 0 if you want full radiation before flux evaluation, otherwise 1
SOLAR_CALLED_LAST: 0 if you want full radiation before flux evaluation, otherwise 1
Enter FV3 if you are on a cube-sphere grid or FV if on the Lat-Lon or DATMO if this is single column. This is needed for the load balancer.
DYCORE: FV3 or FV or DATMO
You will need to see Peter Norris for a rational for the options for the next keyword if you do not use the default (USE_MODEL_RADCOUPLE_EXPORTS).
RADCOUPLE_METHOD: USE_MODEL_RADCOUPLE_EXPORTS or BASIC_RADCOUPLE_LS_PLUS_CN or BASIC_RADCOUPLE_NOLSCN
You can restart RadApp using a restart for the internal states of SOLAR and IRRAD and checkpoint. Or you can just omit these entirely to bootstrap the internal state. The same conventions and options apply as in the full model.
SOLAR_INTERNAL_RESTART_FILE: solar_internal_rst
SOLAR_INTERNAL_RESTART_TYPE: pnc4
SOLAR_INTERNAL_CHECKPOINT_FILE: solar_internal_checkpoint
SOLAR_INTERNAL_CHECKPOINT_TYPE: pnc4
IRRAD_INTERNAL_RESTART_FILE: irrad_internal_rst
IRRAD_INTERNAL_RESTART_TYPE: pnc4
IRRAD_INTERNAL_CHECKPOINT_FILE: irrad_internal_checkpoint
IRRAD_INTERNAL_CHECKPOINT_TYPE: pnc4
You must also specify the number of bands and the location of the optics files for example:
DU_OPTICS: ExtData/g5chem/x/opticsBands_DU.v11_2.nc
SS_OPTICS: ExtData/g5chem/x/opticsBands_SS.v3_3.nc
SU_OPTICS: ExtData/g5chem/x/opticsBands_SU.v1_3.nc
OC_OPTICS: ExtData/g5chem/x/opticsBands_OC.v1_3.nc
BC_OPTICS: ExtData/g5chem/x/opticsBands_BC.v1_3.nc
NUM_BANDS: 18
You can also specify the RATS and AERO providers. Currently this is only PCHEM for the RATS. For the AEROSOLS you can choose PCHEM or RADENV and fill these through ExtData.
RATS_PROVIDER: PCHEM AERO_PROVIDER: PCHEM or RADENV
If you are running PCHEM for the aerosols you will need to provide the files, for example:
AEROCLIM: ExtData/g5chem/L72/aero_clm/dR_MERRA-AA-r1.aer_Nv.%y4%m2clm.nc4
AEROCLIMDEL: ExtData/g5chem/L72/aero_clm/dR_MERRA-AA-r1.del_aer_Nv.%y4%m2clm.nc4
AEROCLIMYEAR: 2008
Other keywords related to radiation.
SOLAR_CONSTANT: -1
CO2: -1