User Guide to SOCRATES (Planet Radiation) in ROCKE-3D
This document contains a guide on how to setup and use SOCRATES (Suite of Community Radiative Transfer codes based on Edwards and Slingo), the new radiation scheme adopted in ROCKE-3D. SOCRATES is available under a BSD 3-clause license, with its repository hosted at the UK Met Office (access to the repository is password protected). If you do not plan to become a SOCRATES developer you do not need access to the repository as the code is available on Discover. However, if you would like to make contributions to the code please contact James Manners at the Met Office in order to get an account set up for you at james.manners@metoffice.gov.uk.
For additional documentation please refer to the pdf documents contained in the same Google Drive folder as this document. There is also a wiki hosted on the Met Office repository (password protected):
https://code.metoffice.gov.uk/trac/socrates/wiki/SocratesDoc
The SOCRATES source code is not contained within the GISS ModelE. This is done in order to ease future updates as the code is in active development and already under version control at the Met Office. In order to start using it you will have to tell ModelE where to find the SOCRATES source code by adding the following to your .modelErc file:
# Path to SOCRATES
SOCRATESPATH=/discover/nobackup/projects/giss/socrates/modele_branch
This path is a symbolic link to a checked out version of the SOCRATES source code. Its target may change with time as new developments will be made to separate branches of the code, and will ensure that ModelE is always using the most up-to-date version available.
At the moment there are three template rundecks using SOCRATES; P4SM40, P4SqM40 and P1SoM40. These are equivalent versions of the rundecks P4M40, P4qM40 and P1oM40, which use the default GISS radiation scheme, and are based on the standard Earth template rundecks E4M20 and E1oM20. Differences between the planet (P) and Earth (E) versions of the rundecks are minimal, the most important of which is to turn off stratospheric production of H2O by CH4 (H2ObyCH4=0), set the mixing ratios of all prescribed greenhouse gases to be uniform (l_uniform_ghg=1) and adopt 40 layer atmosphere.
P4SM40, P4SqM40 and P1SoM40 can be used like any other rundecks, and provide a quick and easy way to start using SOCRATES.
In the current implementation in ModelE, SOCRATES requires four input files. They replace the GISS radiation scheme’s RADN2, RADN3, RADN4, RADN5, RADN9 and RADNE files[1]. These four input files can be divided into two categories: spectral files and aerosol optical properties files. For each there is one file for long-wave radiation and one for short-wave radiation.
Spectral files are the primary input files. They are human readable and contain all tables necessary to run the radiation code without aerosols[2] including radiation bands, k-coefficients, water continuum, Planck function (long-wave spectral files), Sun TOA fluxes (short-wave spectral files), Rayleigh scattering coefficients (short-wave spectral files), and optical properties of both water droplets and ice crystals.
The spectral files are specified in the &&PARAMETERS section of the rundeck as follows:
spectral_file_lw='sp_lw_ga7/sp_lw_ga7'
spectral_file_sw='sp_sw_ga7/sp_sw_ga7'
A high resolution stellar spectrum is needed to derive appropriate albedos in each SOCRATES band. The solar spectrum is set in the &&PARAMETERS section of the rundeck as follows:
solar_spec=’sun’
This will automatically select the short-wave spectral file and short-wave aerosol optical properties file with the appropriate stellar spectrum.
The tables of aerosol optical properties are specific to the interface between ModelE and SOCRATES. They are also specific to the spectral files used, i.e. changing a spectral file most likely means that the aerosol optical properties files will also have to be changed. They are netCDF files containing tables of optical properties for various aerosols as a function of effective radius and humidity for each radiation band specified in the spectral file.
The aerosol optical properties files are specified in the &&PARAMETERS section of the rundeck as follows:
aer_opt_prop_lw='sp_lw_ga7/aer_lw_ga7.nc'
aer_opt_prop_sw='sp_sw_ga7/aer_sw_ga7.nc'
Leaving any of these files out of the rundeck will cause aerosols to be switched off for the corresponding radiation component (e.g. not specifying aer_opt_prop_lw will cause the radiative effects of aerosols to be turned off for long-wave radiation).
All rundeck parameters used with the GISS radiation scheme, such as O3X, CO2_PPM, KSIALB and H2ObyCH4, can be used with SOCRATES too. Two important exceptions are KSOLAR and S0X, neither of which will have any effect on a SOCRATES run.
The Solar/star spectrum contained in the short-wave spectral file is normalized to unity, and the spectral file does not contain any information on what the solar/star constant is. The irradiation at the top of the atmosphere is set by the rundeck parameter planet_s0, the default value of which is 1360.67 W/m2. As an example, if you would like the irradiation at the top of the atmosphere to be 800 W/m2, add the following to your rundeck:
planet_s0=800.
It is straightforward to take an existing rundeck that uses the default GISS radiation scheme and convert it to use SOCRATES instead:
spectral_file_sw='sp_sw_ga7/sp_sw_ga7_dsa'
aer_opt_prop_lw='sp_lw_ga7/aer_lw_ga7.nc'
aer_opt_prop_sw='sp_sw_ga7/aer_sw_ga7.nc'
Important: Note that changing the radiation scheme should be accompanied by a change to the tuning parameters. For the correct tuning please refer to the template rundecks P4SM40, P4SqM40 and P1SoM40.
As a rule of thumb, the more bands a spectral file has the more accurate fluxes and heating rates will be. With each spectral file for use in the GCM comes a corresponding high resolution spectral file with many bands. This can be used to verify the accuracy of a given long-wave or short-wave GCM spectral file. The spectral files are described in more detail in the “Spectral files” document.
For example, the 6-band Earth short-wave spectral file with an extended temperature range, sp_sw_ga7_dsa, comes with the high resolution spectral file sp_sw_280_jm2dsa (280 bands). Comparing fluxes and heating rates obtained with sp_sw_ga7_dsa to those obtained with sp_sw_280_jm2dsa will give a good estimate of the accuracy of sp_sw_ga7_dsa. The same is true for the long-wave, where the equivalent high resolution spectral file normally has 350 bands.
To compare fluxes calculated with two spectral files you will need to run the GCM in radiation debugging mode. To do this, simply add the following line to the preprocessor section of your rundeck:
#define DEBUG_RADIATION_KEEP
Then compile the code and run it using one thread only on an interactive node on Discover:
$ make -j setup RUN=RUNID
$ ../exec/runE RUNID -np 1
Calculated fluxes will be printed to the terminal. The GCM column for which fluxes are calculated is determined by the rundeck parameters dbrad_ilon and dbrad_jlat, which is the model index of the longitude and latitude for which fluxes should be calculated and printed.
In the output, the following abbreviations are used:
PLB: Pressure at lower layer boundaries in mbar
HLB: Height of lower layer boundaries in km
TLB: Temperature at lower layer boundaries in K
TLT: Temperature upper layer boundaries in K
TRDFLB: Thermal (long-wave) downwelling flux at lower layer boundaries in W/m2
TRUFLB: Thermal (long-wave) upwelling flux at lower layer boundaries in W/m2
TRNFLB: Thermal (long-wave) net flux at lower layer boundaries in W/m2
SRDFLB: Stellar (short-wave) downwelling flux at lower layer boundaries in W/m2
SRUFLB: Stellar (short-wave) upwelling flux at lower layer boundaries in W/m2
SRNFLB: Stellar (short-wave) net flux at lower layer boundaries in W/m2
CR: Cooling rate in K/day
HR: Heating rate in K/day
You can watch the recording of the tutorial on how to change the stellar spectrum here:
All band-integrated quantities such as k-coefficients, cloud optical properties, Rayleigh scattering coefficients and aerosol optical properties are weighted by the spectral energy distribution (SED) of the star within each band in order to improve accuracy. Consequently, changing the stellar spectrum is not as straight-forward as changing the TOA irradiance in each short-wave band and leaving other quantities unchanged as this will lead to incorrect weighting of the remaining quantities in the spectral file, causing potentially large errors.
Below is a description of how to update the stellar spectrum in an existing spectral file. This includes calculating new k-coefficients, cloud optical properties, TOA irradiances, Rayleigh scattering coefficients and aerosol optical properties, and only affects the short-wave spectral file. The first step is to get a hold of the new stellar spectrum, and then convert it to the format SOCRATES expects.
The computation of new spectral files needs to be performed on the server venus (gs611-venus.giss.nasa.gov, IP 128.183.2.175). If you do not already have an account, please email Mike Way (michael.way@nasa.gov). Remote ssh access can be obtained via VPN, the bastion host or discover. For access to bastion please contact Sabrina (sabrina.hosein@nasa.gov). You’ll need an RSA keyfob either way. The machine is bound to the NDC, so your login password on other nasa computer will be the same as on venus.
To ease access you may want to set add the following to your .ssh/config file on the machine you are logging into venus from:
# gs611-venus (gs611-venus.giss.nasa.gov)
Host venus
HostName 128.183.2.175
User damundse
Please replace “damundse” with your username. This will enable you to simply type “ssh venus” in order to log in. If you also wish to enable passwordless ssh, see e.g. http://www.linuxproblem.org/art_9.html.
Minimal setup is required in order to generate k-coefficients with SOCRATES on venus. For an example .bashrc files see e.g. ~damundse/.bashrc or ~mway/.bashrc. The only requirement for a user is that the following should be in the .bashrc file:
# Set permissions
umask u=rwx,g=rx,o=rx
# Add netCDF to library path
export LD_LIBRARY_PATH=/opt/netcdf/gcc-4.9.2/usr/lib64:$LD_LIBRARY_PATH
# Add fcm (Met Office svn interface) to path
export PATH=/scr2/socrates/fcm/bin:$PATH
# Set stack size to unlimited
ulimit -s unlimited
That is it.
The very first step is acquire the stellar spectrum. One possible source is the stellar atmosphere model PHOENIX:
http://svo2.cab.inta-csic.es/theory/newov/index.php
I recommend choosing “BT-Settl” (Allard et al. 2012). Then select the appropriate range for the effective temperature, gravity (log g, where [g] = cm/s2), and metallicity. The spectrum you download will have two columns, the first being the wavelength in Å, and the second being the flux at the surface of the star in erg/cm2/s/Å. Both columns will need to be converted to the correct units for SOCRATES (wavelength in m, and flux in W/m2/m at 1 AU), as described below using the *SCALE_DATA statement:
*SCALE_DATA
1.0E-10 SF
Where the scaling of the flux, SF, can be calculated using the following formula:
Where RS is the star radius in m (the denominator is the square of 1 AU in m).
Existing stellar spectra, on the correct format, can be found on venus here:
/scr2/socrates/stellar_spectra
And on discover here:
/discover/nobackup/projects/giss/socrates/stellar_spectra
SOCRATES requires a high resolution stellar spectrum on the following format as input:
Header with information about where the spectrum was obtained etc., this can be as large as desired.
*SCALE_DATA
1.0 1.0
*RADIUS
6.957E+08
*TEMPERATURE
5.785E+03
Wavelength Irradiance
(m) (W/m2/m)
*BEGIN_DATA
1.205000E-07 1.583206E+05
1.215000E-07 6.541584E+06
1.225000E-07 5.949728E+04
1.235000E-07 3.917651E+04
... ...
*END
The header can be as large as desired, and the three first blocks (SCALE_DATA, RADIUS and TEMPERATURE) are all optional, but RADIUS and TEMPERATURE should always be set if the star is not the present day Sun. SCALE_DATA is used to scale both the wavelength and irradiance to the correct units if they are not provided in SI (m for wavelength and W/m2/m for irradiance) at 1 AU, both of the scaling factors default to unity if this block is left out.
RADIUS and TEMPERATURE are the radius and effective temperature of the star (again in SI units), and will default to the Sun values if omitted. The radius and temperature is used to compute the Rayleigh-Jeans tail of the SED of the star at long wavelengths.
The actual irradiance follows after *BEGIN_DATA, with the wavelength in the first column and irradiance at 1 AU in the second column. There is no stringent requirement to the formatting of the numbers, but the wavelength should be increasing, and the wavelength and irradiance should be separated by at least a single space or tab character.
Once the stellar spectrum has been obtained and converted to the correct format, put copies on both venus and discover in the directories specified above:
$ scp starname venus:/scr2/socrates/stellar_spectra
$ scp starname dali:/discover/nobackup/projects/giss/socrates/stellar_spectra
Make sure that everyone is able to read these files on both venus and discover, and also add your abbreviated star name to the names listed at the end of the spectral files doc. If possible, put the original spectrum without any modifications in the orig folder.
To generate new spectral files, you will need both access to the scripts used to produce the spectral files, in addition to SOCRATES itself. In order to get access to the SOCRATES tools run the following command on venus:
$ . /scr2/socrates/modele_branch/set_rad_env
To get the scripts needed to generate the spectral files, clone the socrates_tools GitHub repository:
$ git clone https://github.com/DavidSAmundsen/socrates_tools.git
All spectral file scripts are located in the socrates_tools/gen_spec_files/ folder, in subfolders with the name of the various spectral files. In the following we will change the stellar spectrum in the sp_sw_dsa_ar spectral file as an example.
Move into the directory of the spectral file scripts, in our case:
$ cd socrates_tools/gen_spec_files/sp_sw_dsa_ar
First we will generate a new high resolution reference spectral file. Edit the file param_280 and set the variable SOLAR_SPEC equal to the name of your new solar spectrum. Do not make any other changes. Then run the script to generate the high resolution spectral file, the name of the script is generally mk_sp_sw_SP_ID, where SP_ID is the spectral file ID (e.g. dsa_ar):
$ ./mk_sp_sw_dsa_ar param_280
This script may take up to a few hours to run. Once completed, a message will be printed that the spectral file has been created.
Next we will create a new low resolution spectral file. Look for the script mk_sp_sw_NBANDS_SP_ID, where NBANDS is the number of bands in the spectral file (e.g. 29) and SP_ID is again the spectral file ID (e.g. dsa_ar). (Do not use the non-executable file with the ending *_skel.) Open the script and set the SOLAR_SPEC variable equal to the name of your new solar spectrum. Then execute the script. For our example:
$ ./mk_sp_sw_29_dsa_ar
This script may also take a while to run, up to a few hours. Once completed, a message will be printed that the spectral file has been created. Both spectral files are located in ${HOME}/spectral_files. Please copy it to the communal /scr2/socrates/spectral_files directory.
If aerosols are not required this step can be skipped, proceed to “Copy new files to discover”. Aerosol optical properties files are generated with a combination of BASH scripts using SOCRATES and Python scripts. These files are specific to the implementation of aerosols in ROCKE-3D. Note that to use aerosol/chemistry schemes such as MATRIX with SOCRATES, a new MATRIX interface will be required that can adaptively calculate the aerosol optical properties in the bands used by SOCRATES. The aer_opt_prop files generated here replace the RADN3 GISS radiation input file.
In the following a Python 3 installation with pylab and netCDF4 is required.
First cd into the socrates_tools/aerosol directory. Then run the script run_setup:
$ ./run_setup
Next, edit the spectral file name, folder and stellar spectrum in the script run_scatter_average_aerosol. In our example we have:
SPECTRAL_FILE_NAME="sp_sw_29_dsa_ar"
SPECTRAL_FILE_FOLDER="sp_sw_dsa_ar"
SOLAR_SPEC="sun"
Running this script will generate all the aerosol optical properties and should not take more than a few seconds. The final step is to assemble output from the previous script into the netCDF files required by ROCKE-3D. This is done using the Python program mk_aer_nc.py. Simply edit the variables spectral_file_name, spectral_file_folder and solar_spec. In our example:
spectral_file_name = 'sp_sw_29_dsa_ar'
spectral_file_folder = sp_sw_dsa_ar
solar_spec='sun'
Then run it:
$ python mk_aer_nc.py
A new aerosol optical properties file will have been created in the specified spectral file directory. Please copy it to the communal /scr2/socrates/spectral_files.
The new spectral files have now been created and should be located in the default directory /scr2/socrates/spectral_files on venus. The final step is to copy these file over to discover. For our example:
$ rsync -r -v --update /scr2/socrates/spectral_files/sp_sw_dsa_ar/ /discover/nobackup/projects/giss/socrates/spectral_files/sp_sw_dsa_ar/
ROCKE-3D can now be run with the new stellar spectrum.
Each spectral file is optimized for a given range of compositions. The document “Spectral files” in this Google Drive directory provides guidelines for the use of each spectral file. In general gas amounts can be decreased, and even set to zero, without significant loss of accuracy (the main exception here being H2O, which, if set to zero, may result non-negligible errors). However, this should be verified by using the accompanying high resolution spectral file for both the short-wave and long-wave components.
Setting gases to zero causes the radiation calculation to speed up as the computation time is proportional to the sum of the number of k-terms for each gas.
[1] When using SOCRATES, all these input files, except RADN3, can be removed from the rundeck.
[2]The aerosol data in the spectral files is not used in ModelE.