SOCOLv3 - Chemie - Wiki

<!--
   * Set DENYTOPICVIEW =
-->
---+ !!SOCOL v3
%TOC%

---++ EULER cluster

Before you start running SOCOL, make yourself familiar with Euler, ETHZ's Linux custer: [[http://brutuswiki.ethz.ch/brutus/Getting_started_with_Euler]]

We belong to a shareholder group, the Euler Climate group. Find some more information on this collaboration [[https://wiki.iac.ethz.ch/Collaboration/EulerUsers][here.]]

---++ Documentation

Now that you know the basic stuff about Euler, we come to the second step: [[https://en.wikipedia.org/wiki/RTFM][RTFM!!!]]

Slides with a lot of tips & tricks around SOCOL from a SOCOL hands-on session in October 2019: [[%ATTACHURL%/SOCOL_workshop_Oct2019.pdf][SOCOL_workshop_Oct2019.pdf]]

---+++ ECHAM5 GCM
   * [[%ATTACHURL%/getting_started_with_echam5.pdf][Getting started with ECHAM5]] (how to implement new tracers, additional output, etc.)
   * [[%ATTACHURL%/ECHAM5_Namelists.pdf][ECHAM5 namelists]]
   * [[%ATTACHURL%/Echam_code_numbers.pdf][ECHAM5 output variables]]
   * [[http://www.mpimet.mpg.de/fileadmin/publikationen/Reports/max_scirep_349.pdf][The atmospheric general circulation model ECHAM 5. PART I: Model description]]
   * [[http://www.mpimet.mpg.de/fileadmin/publikationen/Reports/max_scirep_354.pdf][The atmospheric general circulation model ECHAM5 Part II: Sensitivity of simulated climate to horizontal and vertical resolution]]
   * [[%ATTACHURL%/echam5_doc.tar.gz][collection of technical manuals, partly only drafts]]
   * [[%ATTACHURL%/physc.pdf][hand written call tree of the physics routine]]
---+++ MEZON Chemistry
Unfortunately, we haven´t found a technical documentation of the MEZON chemistry scheme so far. If you have one, please put it here.

   * [[%ATTACHURL%/Mezon_Call-tree.pdf][Call tree chemistry module MEZON]]
   * [[%ATTACHURL%/Chem_Reactions_SOCOLvs3.pdf][List of chemical reactions]]
   * [[%ATTACHURL%/Chem_Species_SOCOLvs3.pdf][List of tracers]]
   * [[%ATTACHURL%/SOCOLv3.1_namelist.pdf][SOCOL specific namelist]]

---+++ Mixed-Layer Ocean

SOCOL can be run with a mixed-layer ocean (MLO), which considers a water column with a fixed depth of 50m and a thermodynamic sea ice module. This model configuration does not consider active ocean dynamics, but captures the shorter term response of the ocean’s surface temperature to the atmosphere. The heat budget of the oceanic mixed-layer is described by
<verbatim>
Cm*dTm/dt = H - Q
</verbatim>
where Tm denotes the temperature of the mixed-layer, which substitutes the sea surface temperature in the model version without ocean. Cm and H describe the effective heat capacity of the mixed-layer and the net heat flux at the atmosphere–ocean surface, respectively. The oceanic heat transport Q (also called flux correction term) is intended to compensate for the energy transport by ocean currents, which is not simulated by the MLO model itself [[https://www.sciencedirect.com/science/article/pii/S0031018206002045][(Steppuhn et al., 2006)]].

The respective source code (just in case your model version does not come with the correct MLO source files) as well as some instructions on how to run the MLO can be found here: [[%ATTACHURL%/mlo.tar]] 

---++ Get the model code

to be updated

<!--The latest source code version is available from our svn project repository: https://svn.iac.ethz.ch/repos/projects/socol3. If your are interested in the model code and not yet registered, send a mail to andrea.stenke@env.ethz.ch to ask for access. If you find any bugs or make other changes to the model code that are supposed to be part of the operational model version, please commit your changes to the repository (*including a useful log message!*). Thus everybody can easily update his own working copy. Information about how to use subversion can be found on the [[https://wiki.iac.ethz.ch/IT/ServiceSvn][IACWiki]] and on the [[http://svnbook.red-bean.com/][web]].!-->

<!--*Check out the repository and create a working copy on your local machine:*
 <verbatim>
svn co https://svn.iac.ethz.ch/repos/projects/socol3/socolv3 socolv3
</verbatim>
This places your working copy in the new directory socolv3 on your local machine. Of course you can also choose a different name for your working copy.!-->

---++ Compile 

---+++ Set stacksize to unlimited in case of intel compiler

%X% *IMPORTANT*: The model will crash with segmentation fault, if the stacksize is too small. Set it to unlimited when using intel compiler.

   * For bash shell
 <verbatim>
ulimit -s unlimited
</verbatim>
   * For tcsh shell
 <verbatim>
limit stacksize unlimited
</verbatim>

It's recommended to set the stacksize also in the run script (see further down).

---+++ On ETH cluster Euler

%X% *IMPORTANT*: Do not use intel/11.0.081. The model will crash with segmentation fault.

   * Load compiler module
 <verbatim>
module load intel
</verbatim>
   * Load openMPI module 
 <verbatim>
module load open_mpi
</verbatim>
   * Load netcdf module
 <verbatim>
module load netcdf
</verbatim>
   * *IMPORTANT* You have to load first the compiler and afterwards the modules for openmpi and netcdf. Otherwise you don't get the openmpi and netcdf versions which correspond to your compiler !! If you like you can load a modules at once with
 <verbatim>
module load intel open_mpi netcdf
</verbatim>
   * Run make
 <verbatim>
make
</verbatim>

---++ Run the model

---+++ On ETH cluster Euler
   * Run script, for example */home/beyerleu/echam5/run_00040.run-for-brutus*
   * Load the right modules !
 <verbatim>
module load intel netcdf open_mpi
</verbatim>
   * Submit the job to the queuing system with
 <verbatim>
bsub < run_00040.run-for-brutus
</verbatim>
   * What's important in *run_00040.run-for-brutus*
      * Define parameters for the queuing system
 <verbatim>
#BSUB -J run_00040
#BSUB -n 4
#BSUB -W 0:59
</verbatim>
      * *IMPORTANT*: The requested cores, number after *-n* has to be equal the the value of *NCPUS* further down.
      * Set the wallclock time *-W* to something higher than your model will run. There are 1 hour and 7 hour and 24 hours(?) queues.
      * Load the correct modules and set stacksize to unlimited
 <verbatim>
# load modules
source /etc/profile.d/modules.sh
module purge
module load intel/10.1.018 netcdf open_mpi/1.3.3
module list

# set stacksize to unlimted
ulimit -s unlimited
</verbatim>
      * Remark: The stacksize on brutus has also to be increased on the nodes (=/etc/security/limits.conf=). This has been already be done be the brutus administrators.
      * Set NCPUS, NPROCA, NPROCB, for example
 <verbatim>
NCPUS=2
NPROCA=2
NPROCB=1
</verbatim>
      * Set correct WORKDIR, for example
 <verbatim>
WORKDIR=/cluster/work/uwis/$USER/echam5
</verbatim>
      * Call model
 <verbatim>
ompirun $MODEL
</verbatim>


---++ Chemical Preprocessor for SOCOLv3

The chemical preprocessor sets up the chemical equation system and creates the respective model code.

Members of the SOCOL Git group can download the preprocessor package (Fortran code and run scripts) from the IAC !GitLab server:

<verbatim>
git clone https://git.iac.ethz.ch/stenkea/socolv3_chemical_preprocessor.git
</verbatim>

*How to run Chemical Code Generator (CEDR)*
   * go to the *work* directory
   * edit the reaction table (Retab.d, Retab_tropo.d)
   * edit the script *cedr.csh*: choose between standard SOCOL chemistry (*STRATO*) or more comprehensive tropospheric chemistry (*TROPO*):
 <verbatim>
echo "Chemical code generator"
ifort -o chegen.x CHEGEN.f
chegen.x TROPO   # <- replace TROPO with STRATO if you want the standard SOCOL chemistry scheme
</verbatim>
   * run cedr.csh
   * that's it, the output files are in the *output* directory
   * copy the new source files to the respective source code directories */src* and */modules*
   * compile the model

*Notes*
   * new chemical species (= tracers) have to be included manually into mo_socol_tracers.f90
   * same for photolysis rates (mo_socol_sun.f90)

---++ Preparation of photolysis rates (LUT) for SOCOLv3

SOCOLv3 reads pre-calculated photolysis rates as a function of O2 and O3 columns (modules/mo_socol_sun.f90). The actual photolysis rates are calculated online by bi-linear interpolation of the tabulated data onto actual values of total oxygen (XO2) and ozone (XO3) above the respective grid point (src/socol_dis.f90).

Members of the SOCOL Git group can download the LUT package (Fortran code and run scripts) from the IAC !GitLab server:

<verbatim>
git clone https://git.iac.ethz.ch/stenkea/socolv3_lut_code.git
</verbatim>

Step-by-step introduction on how to use git can be found [[%PUBURL%/Chemie/SOCOLMeetings/How_to_use_git.pdf][here.]]

Instructions on the LUT code are given here: [[%ATTACHURL%/how_to_lut.pdf][How to lut]]

---++ List of model simulations

---+++ Google spreadsheet

   * [[https://docs.google.com/spreadsheets/d/1qj4YnmaoEHKf20_jxFJl2x3TKXUoS0W0XY0MjAiiMG0/edit#gid=1156465638][Google spreadsheet SOCOL simulations]]

---+++ SOCOL vs3

The model output from the CCMI model simulations is available at [[http://data.ceda.ac.uk/badc/wcrp-ccmi/data/CCMI-1/output/ETH-PMOD/SOCOL3/][BADC]] (you might have to request an account there).

%EDITTABLE{format="| text,20| text,20| text,20| text,20| text,20|"}%
| *EXPNO* | *RES* | *YEARS* | *DATA* | *NOTE* |
| 00050 | =T31L39= | 1975-2005 | /net/hydro/chemie/stenkea/afterburner/run00050 and /net/hydro/chemie/stenkea/brutus/raw/run00050 | reference run SOCOL v3 (Stenke et al., 2013) |
| 00060 | =T42L39= | 1975-2005 | /net/hydro/chemie/stenkea/afterburner/run00060 and /net/hydro/chemie/stenkea/brutus/raw/run00060 | reference run SOCOL v3 (Stenke et al., 2013) |
| 00360 | =T42L90= | 1975-2000 | /net/hydro/chemie/stenkea/brutus/raw/run00360 | reference run SOCOL v3 |

View

Attach