Difference between revisions of "UKCA & UMUI Tutorial 4"
| Line 290: | Line 290: | ||
* Go to the ''Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration''' panel, scroll down the table and change the ''Y'' next to the ''fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src'' branch to '''N'''. |
* Go to the ''Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration''' panel, scroll down the table and change the ''Y'' next to the ''fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src'' branch to '''N'''. |
||
* Add your own branch to this table. The revision URL will be off the form <br/> '''fcm:um_br/dev/<span style="color:blue">your PUMA username</span>/vn8.2_<span style="color:blue">your_branch_name</span>/src''' <br/> Leave the '''revision''' number column empty and put a '''N''' in the '''Use Y/N''' column. |
* Add your own branch to this table. The revision URL will be off the form <br/> '''fcm:um_br/dev/<span style="color:blue">your PUMA username</span>/vn8.2_<span style="color:blue">your_branch_name</span>/src''' <br/> Leave the '''revision''' number column empty and put a '''N''' in the '''Use Y/N''' column. |
||
| − | * Turn on the button which says '''Include modifications from a user working copy''' and put the path to your source directory on PUMA in this box (e.g. somthing like '''/home/<span style="color:blue">your PUMA username</span>/...''' etc.). |
+ | * Turn on the button which says '''Include modifications from a user working copy''' and put the path to your source directory on PUMA in this box (e.g. somthing like '''/home/<span style="color:blue">your PUMA username</span>/.../vn8.2_<span style="color:blue">your_branch_name</span>/src''' etc.). |
| − | |||
| + | Using a '''working copy''' means that FCM will pick up any changes that you have made to your branch without you needed to <tt>fcm commit</tt> it. However, '''frequent committing of code to the FCM respository is encouraged'''. You don't even need to commit working code, as committing is a useful way of backing-up code changes. |
||
---- |
---- |
||
Revision as of 11:37, 17 June 2013
Adding new chemical tracers
As UKCA is a framework, it must have the infrastructure around it to allow it to work, with the infrastructure being the UM itself. In this tutorial you will add in two new chemical tracers. While you may think that you should start this by editing the UKCA code, in fact you should first adapt the UM and the UMUI so that it knows that these new tracers exist. Once you have created them you can then edit the UKCA code to use them to transport chemical species around.
For this tutorial you will need to make a new branch in the usual way. You should do this now.
1. Adding a tracer into the UMUI
1. Pick a free UKCA tracer slot
The UM has 150 tracers available for use by UKCA in STASH section 34. The first 100 of these are chemical tracers, which may (or may not) be in use by the various schemes that are currently available. The last 101-150 are reserved for aerosol and diagnostic tracers. You should therefore ensure that the tracers that you add are in one of the 1-100 slots, although many of these slots will already be in use by the scheme that you are using.
To choose the correct slot(s), you should first examine the nm_spec array which is in the ukca_setd1defs.F90 routine. To do this, cd into
vn8.2_your_branch/src/atmosphere/UKCA
and view the ukca_setd1defs.F90 file. This will give the following for the nm_spec array which is found around line 360:
IF (L_UKCA_RAQ) THEN
!This list of tracers is valid for the RAQ chemistry.
!If MODE aerosols are used with it but their positions
!change in the array then the list needs to be updated.
nm_spec(1:n_all_tracers) = (/ &
'O3 ','NO ','NO3 ','NO2 ','N2O5 ', &
'HO2NO2 ','HONO2 ','H2O2 ','CH4 ','CO ', &
'HCHO ','MeOOH ','HONO ','C2H6 ','ETOOH ', &
'MeCHO ','PAN ','C3H8 ','N-PrOOH ','I-PrOOH ', &
'EtCHO ','Me2CO ','MeCOCH2OOH','PPAN ','MeONO2 ', &
'O3S ','C5H8 ','ISOOH ','ISON ','MACR ', &
'MACROOH ','MPAN ','HACET ','MGLY ','NALD ', &
'HCOOH ','MeCO3H ','MeCO2H ','MVK ','MVKOOH ', &
'Cl ','ClO ','Cl2O2 ','OClO ','Br ', &
'BrO ','BrCl ','BrONO2 ','N2O ','HCl ', &
'HOCl ','HBr ','HOBr ','ClONO2 ','CFCl3 ', &
'CF2Cl2 ','MeBr ','N ','O(3P) ','ORGNIT ', &
'MeCl ','CF2ClBr ','CCl4 ','CF2ClCFCl2','CHF2Cl ', &
'MeCCl3 ','CF3Br ','H2OS ','CH3OH ','H2 ', &
'SO2 ','H2SO4 ','DMS ','MSA ','DMSO ', &
'NH3 ','CS2 ','COS ','H2S ','H ', &
'OH ','HO2 ','MeOO ','EtOO ','MeCO3 ', &
'n-PrOO ','i-PrOO ','EtCO3 ','MeCOCH2OO ','RNC2H4 ', &
'RNC3H6 ','C2H4 ','C3H6 ','C4H10 ','C4H9OOH ', &
'MEK ','TOLUENE ','MEMALD ','GLYOXAL ','oXYLENE ', &
'ND_Nuc_SOL','Nuc_SOL_SU','ND_Ait_SOL','Ait_SOL_SU','Ait_SOL_BC', &
'Ait_SOL_OC','ND_Acc_SOL','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC', &
'Acc_SOL_SS','Acc_SOL_DU','ND_Cor_SOL','Cor_SOL_SU','Cor_SOL_BC', &
'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','ND_Ait_INS','Ait_INS_BC', &
'Ait_INS_OC','ND_Acc_INS','Acc_INS_DU','ND_Cor_INS','Cor_INS_Du', &
'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_OZ','Ait_SOL_OZ','Acc_SOL_OZ', &
'Cor_SOL_OZ','Nuc_SOL_NH','Ait_SOL_NH','Acc_SOL_NH','Cor_SOL_NH', &
'Nuc_SOL_NT','Ait_SOL_NT','Acc_SOL_NT','Cor_SOL_NT','XXX ', &
'Dust_Div_1','Dust_Div_2','Dust_Div_3','Dust_Div_4','Dust_Div_5', &
'Dust_Div_6','Rn-222 ','Pb-210 ','XXX ','XXX ' &
/)
ELSE
! Tracers 98,99 & 100 are for lumped Nitrogen, Br and Cl for stratospheric chemistry,
! but can only be renamed in STASHmaster file not in advt or nm_spec.
nm_spec(1:n_all_tracers) = (/ &
'O3 ','NO ','NO3 ','NO2 ','N2O5 ', &
'HO2NO2 ','HONO2 ','H2O2 ','CH4 ','CO ', & !10
'HCHO ','MeOOH ','HONO ','C2H6 ','EtOOH ', &
'MeCHO ','PAN ','C3H8 ','n-PrOOH ','i-PrOOH ', & !20
'EtCHO ','Me2CO ','MeCOCH2OOH','PPAN ','MeONO2 ', &
'O3_S ','C5H8 ','ISOOH ','ISON ','MACR ', & !30
'MACROOH ','MPAN ','HACET ','MGLY ','NALD ', &
'HCOOH ','MeCO3H ','MeCO2H ','H2O ','ISO2 ', & !40
'Cl ','ClO ','Cl2O2 ','OClO ','Br ', &
'BrO ','BrCl ','BrONO2 ','N2O ','HCl ', & !50
'HOCl ','HBr ','HOBr ','ClONO2 ','CFCl3 ', &
'CF2Cl2 ','MeBr ','N ','O(3P) ','MACRO2 ', & !60
'MeCl ','CF2ClBr ','CCl4 ','CF2ClCFCl2','CHF2Cl ', &
'MeCCl3 ','CF3Br ','H2OS ','CH2Br2 ','H2 ', & !70
'DMS ','SO2 ','H2SO4 ','MSA ','DMSO ', &
'NH3 ','CS2 ','COS ','H2S ','H ', & !80
'OH ','HO2 ','MeOO ','EtOO ','MeCO3 ', &
'n-PrOO ','i-PrOO ','EtCO3 ','MeCOCH2OO ','MeOH ', & !90
'Monoterp ','Sec_Org ','SESQUITERP','SO3 ','AROM ', &
'O(3P)_S ','O(1D)_S ','NO2 ','BrO ','HCl ', & !100
'ND_Nuc_SOL','Nuc_SOL_SU','ND_Ait_SOL','Ait_SOL_SU','Ait_SOL_BC', &
'Ait_SOL_OC','ND_Acc_SOL','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC', & !110
'Acc_SOL_SS','Acc_SOL_DU','ND_Cor_SOL','Cor_SOL_SU','Cor_SOL_BC', &
'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','ND_Ait_INS','Ait_INS_BC', & !120
'Ait_INS_OC','ND_Acc_INS','Acc_INS_DU','ND_Cor_INS','Cor_INS_Du', &
'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_OZ','Ait_SOL_OZ','Acc_SOL_OZ', & !130
'Cor_SOL_OZ','Nuc_SOL_NH','Ait_SOL_NH','Acc_SOL_NH','Cor_SOL_NH', &
'Nuc_SOL_NT','Ait_SOL_NT','Acc_SOL_NT','Cor_SOL_NT','XXX ', & !140
'Anth_Prec ','Bio_Prec ','Anth_Cond ','Bio_Cond ','XXX ', &
'XXX ','XXX ','XXX ','PASSIVE O3','AGE OF AIR' & !150
/)
END IF
! Mode components: Su: sulphate, BC: black carbon, OC: organic carbon
! SS: sea-salt, Du: dust, OZ: organic carbon 2
! NH: ammonium, NT: nitrate, ND: number density
The settings in the UMUI UKCA panel will tell you whether you are using the RAQ chemistry or not (in this tutorial you are not). If you look through the ukca_chem_scheme.F90 file (e.g. ukca_chem_strattrop.F90) then you will see a list of the species that you are using. The following list gives the CheST/strattrop chemical species in black. Red species are either used by the aerosol chemistry or should be avoided, and species in green are not currently used by any scheme and so can be over-written.
'O3 ','NO ','NO3 ','NO2 ','N2O5 ', & 'HO2NO2 ','HONO2 ','H2O2 ','CH4 ','CO ', & !10 'HCHO ','MeOOH ','HONO ','C2H6 ','EtOOH ', & 'MeCHO ','PAN ','C3H8 ','n-PrOOH ','i-PrOOH ', & !20 'EtCHO ','Me2CO ','MeCOCH2OOH','PPAN ','MeONO2 ', & 'O3_S ','C5H8 ','ISOOH ','ISON ','MACR ', & !30 'MACROOH ','MPAN ','HACET ','MGLY ','NALD ', & 'HCOOH ','MeCO3H ','MeCO2H ','H2O ','ISO2 ', & !40 'Cl ','ClO ','Cl2O2 ','OClO ','Br ', & 'BrO ','BrCl ','BrONO2 ','N2O ','HCl ', & !50 'HOCl ','HBr ','HOBr ','ClONO2 ','CFCl3 ', & 'CF2Cl2 ','MeBr ','N ','O(3P) ','MACRO2 ', & !60 'MeCl ','CF2ClBr ','CCl4 ','CF2ClCFCl2','CHF2Cl ', & 'MeCCl3 ','CF3Br ','H2OS ','CH2Br2 ','H2 ', & !70 'DMS ','SO2 ','H2SO4 ','MSA ','DMSO ', & 'NH3 ','CS2 ','COS ','H2S ','H ', & !80 'OH ','HO2 ','MeOO ','EtOO ','MeCO3 ', & 'n-PrOO ','i-PrOO ','EtCO3 ','MeCOCH2OO ','MeOH ', & !90 'Monoterp ','Sec_Org ','SESQUITERP','SO3 ','AROM ', & 'O(3P)_S ','O(1D)_S ','NO2 ','BrO ','HCl ', & !100
You should pick one of the green slots (although if you are adding more than 13 new tracers and you know that you will not need any of the red ones, these can also be used. In the future the number of UKCA tracers will be extended.
In this example we will over-write tracer number 65 (CHF2Cl).
2. Edit your user STASHmaster file
In your UMUI job go to Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. This will contain a listing of a file that describes the UKCA tracers that you are using, in this tutorial it is called UKCA_Tr_StratTrop.prestash. Take a copy of this file to your local direcory on PUMA. If you open this file you will see that each tracer has a listing which looks like
# 1| 1 | 34 | 1 |O3 MASS MIXING RATIO AFTER TIMESTEP | 2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 | 3| 000000000000000000000000000001 | 00000000000000000001 | 1 | 4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 | 5| 0 | 1861 | 0 | 65 | 0 | 0 | 0 | 0 | 0 | #
Each of the areas coloured in red above is unique to each tracer, i.e. the name of the tracer and the number of the tracer. Since we are over-writing tracer 65, you would make a new entry in the STASHmaster file which reads
# 1| 1 | 34 | 65 |MY TRACERS NAME | 2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 | 3| 000000000000000000000000000065 | 00000000000000000001 | 1 | 4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 | 5| 0 | 1861 | 0 | 65 | 0 | 0 | 0 | 0 | 0 | #
Note: the spacing of the pipes (|) in this file is important, so be careful not to change this.
Now, in the Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. panel replace the original user STASHmaster file with your new one containing the additional tracer(s).
3. Initialise your tracer(s)
Now you need to initialise your tracer. By placing it in a STASHmaster file which the UM reads, as a tracer is a prognostic field, it will need to be initialised to a value in the model start dump (which is done by the reconfiguration step). To set this go to Model Selection → Atmosphere → STASH → Initialisation of User Prognostics. This will open a panel containing a table listing all the STASH items listed in all your STASHmaster files. Scroll down this list until you get to your new tracer. While the STASH number and name of the tracer (which you set in your STASHmaster file) is present, all other columns will be blank.
The simplest options are either to set the Option column to 3 (which sets the field to zero) or to 6 and then give a value to set the field to in the If 6: CONSTANT column. In either case this will set every single gridcell to be the same value. You can, if needed, make up an ancillary file containing an initial condition (option 7) if you required there to be spatial variation in your field (e.g. the ukca ozone field must always be initialised to an approximate initial condition in this way). This can be done using Xancil. Xancil will be covered in more detail in the adding new emissions tutorial. If these fields existed in the start dump you are providing then you could set this option to 1.
4. Tell the UMUI about your new tracer
Unfortunately you cannot edit the UMUI directly to add-in your new tracer(s), and instead you must use a hand-edit. This is a script which run when you click the Process button, and what it does is to directly make changes to one or more of the scripts that is held in your $HOME/umui_jobs/jobid directory (you can think of the UMUI as making indirect changes), and it is these scripts which are copied across to the supercomputer when you click Submit.
If you go to your $HOME/umui_jobs/jobid directory and view the SIZES script, you will see that it contains the entries
TR_UKCA=72,
and
TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0, 0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1,1,
TR_UKCA is the number of UKCA tracers, and TC_UKCA is a list of which tracers are on or not (1 being on, 0 being off). If you were to go through the TC_UKCA list and add-up all the 1s you would find that they add-up to 72, and that you would only have a 1 where you have a corresponding number in the user STASHmaster file.
You will need to make up a new list. However, rather than you having to put the 1 in the correct place by hand (not easy to do!), there is the make_tracer_list script on PUMA which is located in
/home/ukca/bin/make_tracer_list
This script is run on a STASHmaster file. If this script is run on the edited user STASHmaster file (which has tracer 65 included) the output is
$ make_tracer_list UKCA_Tr_StratTrop.prestash TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0, 0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1,1, TR_UKCA=73,
(with the changes from before highlighted in blue). You will now need to add this data into the SIZES script using a hand-edit.
Hand-edits use the ed text editor, which can be run in a batch mode. We will need to make a script (e.g. add_UKCA_Tr_StratTrop.ed) which contains the following
ed SIZES<<\EOF /TC_UKCA=/ d d d d d i TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0, 0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1,1, . w q EOF ed SIZES<<\EOF /TR_UKCA=/ d i TR_UKCA=73, . w q EOF
The first block tells ed to search for the line TC_UKCA= and the delete this line and the next 4 lines, before inserting the text (i.e. this replaces the block in SIZES with the text here). The second block does the same but for the TR_UKCA value, hence only needed to delete 1 line.
You will need to make this file executable so that the UM can run it. To do this, in the directory where the file exists do
chmod a+rx add_UKCA_Tr_StratTrop.ed
Now, in the UMUI we go to Model Selectiom → Input/Output Control and Resource → User hand edit files. Put the full path to this file at the end of the list in the table and put a Y in the Include Y/N column.
Task 4.1
TASK4.1: Add in two new tracers in to slots 64 and 65. The tracer in slot 64 will be called ALICE and the tracer in slot 65 will be called BOB.
Adding new a new chemical tracer to UKCA
Now that you have created the new tracer(s) in the UM/UMUI, you can then tell UKCA to use this tracer slot to transport round a chemical species. To do this you will need to edit the UKCA source code.
FCM branches and merging
Before we can do this we need to check and see if there are any possible conflicts that may arise by making these changes. If you go to the FCM Atmosphere panel at Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration you can view the current branches used by this job, e.g.:
fcm:um_br/dev/odarbysh/VN8.2_reinstate_ISCCP/src 9617 Y fcm:um_br/pkg/Config/VN8.2_GlobalAtmos4p0/src 9630 Y fcm:um_br/dev/odarbysh/VN8.2_qpos_col_fix/src 9619 Y fcm:um_br/dev/nhsavage/vn8.2_pkg_ukca_bugfixes/src 9882 Y fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src 9984 Y fcm:um_br/dev/jeff/VN8.2_hector_monsoon_archiving/src Y fcm:um_br/dev/luke/vn8.2_RCP_scenario/src 12080 Y fcm:um_br/pkg/Config/vn8.2_ncas/src Y fcm:um_br/dev/luke/vn8.2_UKCA_HECToR_cce_Fixes/src 12133 Y
Most of these branches will not clash with our required changes. However, the fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src branch will, as it directly changes parts of the chemistry scheme routines that we want to use. Before we can make our code changes we must first make a copy of this branch. While ideally you should be able to make a new branch and edit the source-code as is, often you need to make changes to an existing branch. The recommended way to do this is to make a new branch and then merge in the clashing branch with your own, then stop using the clashing branch in the UMUI.
You should already have made a new branch that you used to find the free tracer slots. Now cd into the highest-level directory of the branch, which contains
CodeOwners.txt COPYRIGHT.txt src/
From here you will need to merge in the vn8.2_ukca_update_rate_coeffs branch. Do
$ fcm merge fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src Eligible merge(s) from /UM/branches/dev/foconnor/vn8.2_ukca_update_rate_coeffs@12142: 9984 9983 9982 9981 9980 9979 Enter a revision (or just press <return> for "9984"): -------------------------------------------------------------------------------- Merge: /UM/branches/dev/foconnor/vn8.2_ukca_update_rate_coeffs@9984 c.f.: /UM/trunk@9602 -------------------------------------------------------------------------dry-run --- Merging r9603 through r9984 into '.': U src/atmosphere/UKCA/asad_flux_dat.F90 U src/atmosphere/UKCA/asad_bimol.F90 U src/atmosphere/UKCA/asad_trimol.F90 U src/atmosphere/UKCA/ukca_chem_strattrop.F90 -------------------------------------------------------------------------dry-run Would you like to go ahead with the merge? Enter "y" or "n" (or just press <return> for "n"): y Merge succeeded.
After typing the fcm merge command you will need to confirm the revision number and that you wish to go ahead with the merge. Confirm these. Now if you type fcm status you can see which routines have been changed:
$ fcm status M src/atmosphere/UKCA/asad_flux_dat.F90 M src/atmosphere/UKCA/asad_bimol.F90 M src/atmosphere/UKCA/asad_trimol.F90 M src/atmosphere/UKCA/ukca_chem_strattrop.F90
Before you make any further changes you should commit these changes. Do this now.
Now you need to add this branch into the UMUI, and turn off the original vn8.2_ukca_update_rate_coeffs branch. We will initially use a working copy.
- Go to the Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration' panel, scroll down the table and change the Y next to the fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src branch to N.
- Add your own branch to this table. The revision URL will be off the form
fcm:um_br/dev/your PUMA username/vn8.2_your_branch_name/src
Leave the revision number column empty and put a N in the Use Y/N column. - Turn on the button which says Include modifications from a user working copy and put the path to your source directory on PUMA in this box (e.g. somthing like /home/your PUMA username/.../vn8.2_your_branch_name/src etc.).
Using a working copy means that FCM will pick up any changes that you have made to your branch without you needed to fcm commit it. However, frequent committing of code to the FCM respository is encouraged. You don't even need to commit working code, as committing is a useful way of backing-up code changes.
Written by Luke Abraham 2013
