1) Official documentation form ECCC

Official wiki page form ECCC

The following link points to the official GenPhysX wiki page from ECCC, accessible from outside of ECCC: GenPhysX

2) Create geophysical fields with GenPhysX at UQAM

At UQAM GenPhysX is currently only working on alea!!!

a) Create tictacs for model grid

As input GenPhysX needs to know the model grid. It reads it form of the tictacs of the full model grid. On our UQAM servers you can create them from your 'gem_settings.nml' with the command:

~winger/ovbin/k.grille

The file you need as input for GenPhysX is called "tape1_model".

b) Acquire GenPhysX & SPI

To get access to GenPhysX (which uses SPI) you need to load:

module load utils/SPI

c) Create & execute script to run GenPhysX

For the different available datasets check here.

When using USGS set:

    TOPO=USGS
    VEGE=USGS_R
    MASK=USGS_R
    SOIL=JPL

When using CCI-LC set:

    TOPO=GMTED75 # missing Antarctica and Greenland!!! or     TOPO=GMTED30 # lower resolution
    VEGE=CCI_LC
    MASK=CCI_LC
    SOIL=BNU

Example script to create geophysical fields:

#!/bin/bash

# Set the following parameters exp=domain_name # Domain name (name of geophys files) geo_dir=/Full/path/of/Geophys/directory # Full(!) path of destination directory containing already(!!!) the file 'tape1.model' # -> must NOT be in the home!!! # Example: exp=/Full/path/of/Geophys/directory/Geophys_${exp} email="your.email@address" # Email address to which a confirmation email will get send after completion # Set following parameters to dataset of your choice, following above examples: TOPO=... VEGE=... MASK=... SOIL=... # ======================================================================================

module load utils/SPI
geophys=geophys_${exp}
GENPHYSX=GenPhysX
tictacs=tape1_model

cd ${geo_dir}

# Using Ayrton's new sharp low pass filter:
cat > parameter_file.txt << EOF
set GenX::Param(DBase)                      /home/data/Geophys/Database/Dorval

set GenX::Settings(GRD_TYP_S)               LU
set GenX::Settings(TOPO_DGFMS_L)            False
set GenX::Settings(TOPO_DGFMX_L)            False
set GenX::Settings(TOPO_FILMX_L)            False
set GenX::Settings(TOPO_CLIP_ORO_L)         False
#
set Log::Param(Level)                       DEBUG
set GeoPhysX::Opt(LegacyMode)               False
set GenX::Param(Z0Topo)                     LEGACY
set GenX::Settings(TOPO_ZREF_ZV_RATIO_C)    True
set GenX::Settings(TOPO_RUGV_ZVG2)          True
set GenX::Settings(TOPO_RUGV_MG)            True
set GenX::Settings(TOPO_ZV_MIN_THRESHOLD)   0.0003
set GenX::Settings(TOPO_WATER_RUGV)         0.001

# ne pas filter le champs MENF a l entree du calcul de Z0, ZP
set GenX::Param(MEFilterForZ0)              None

# Ayrton's new sharp low pass filter
set GenX::Settings(LPASSFLT_RC_DELTAX)         5.0
set GenX::Settings(LPASSFLT_P)                 20
set GenX::Settings(LPASSFLT_MASK_OPERATOR)     1
set GenX::Settings(LPASSFLT_MASK_THRESHOLD)    100.0
set GenX::Settings(LPASSFLT_APPLY_MINMAX)      True

# Mapping tables
set GenX::Path(CCILC_LUT_CSV)              /home/winger/Scripts/GenPhysX/CCI_LC/CCI_LC_lut.csv
set GenX::Path(USGS_GLCC_LUT_CSV)          /home/winger/Scripts/GenPhysX/CCI_LC/USGS_GLCC_lut2.csv
set GenX::Path(NALCMS_LUT_CSV)             /home/winger/Scripts/GenPhysX/CCI_LC/NALCMS_lut2.csv
set GenX::Param(UseVegeLUT)                True
#set GenX::Param(AddHydroLakesToMask)       True

EOF

# Execute GenPhysX
$GENPHYSX -gridfile ${tictacs} -param parameter_file.txt -mask $MASK -vege $VEGE -topo $TOPO -soil $SOIL -check STD -celldim 2 -z0topo LEGACY -mefilter LPASS -result ${geophys} -subgrid STD -mail ${email}

Once you executed the above script and it ended successfully you should see the message:

Status : Job has terminated successfully.
...

Note: Depending on the dataset and the domain the time to create geophysical fields with the above script varies between a few minutes and several hours. The higher the original resolution of the dataset and the larger the domain the longer the script will run for. So you might want to submit it with 'soumet'.

Mapping tables

The original datasets do in general not have the same 26 surface types GEM reads from the geophysical fields. Therefore, mapping tables are used to map a surface type from the original dataset to our 26 surface types. Depending on the dataset the following different mapping tables are used:

CCI-LC: /home/winger/Scripts/GenPhysX/CCI_LC/CCI_LC_lut.csv
USGS : /home/winger/Scripts/GenPhysX/CCI_LC/USGS_GLCC_lut2.csv
NALCMS: /home/winger/Scripts/GenPhysX/CCI_LC/NALCMS_lut2.csv

See in the above script example under "# Mapping tables". If you want to modify a mapping table, just take a copy of the existing one, modify it to your liking and then specify its name it in your script instead of the existing one.

The mapping table for CCI-LC is build the following way:

- There is one row per original surface type - plus a header.

- The first column contains the number of said surface type. The following columns are for each of GEM's 26 surface types.

- The values written in the table are the fraction of the original surface type that will be mapped to one of GEM's surface types. Therefore, the sum of all the values in one row needs to be 1.

The mapping tables for USGS and NALCMS are build the following way:

- There is one row per original surface type - plus a header.

- The first column contains the number of said surface type. The second column contains the number of GEM surface type this one will get mapped to. This is a one-to-one mapping. There are no fractions as for CCI-LC.

d) Copy geophys to running machine

You need to copy the whole directory, ${geo_dir} (defined in your script), to the machine on which you want to run the model, for example, Narval.

e) Add missing fields

GenPhysX does not create all the fields one might need to run GEM:

If running FLake one needs to add the lake depth, 'LDEP'.
If running CLASS one needs to add the depth to bedrock, 'DPTH', and well as the sand and clay fields, 'SAND' and 'CLAY'

On Narval, I have scripts which add the above fields plus the link 'Gem_geophy.fst', depending on the datasets you were using. They can all be found under:

~winger/Scripts/Geophys

add_SAND_CLAY_DBRK_LDPTyLDEP-USGS.scr - if you used USGS
add_SAND_CLAY_DBRK_LDPTyLDEP-CCI_LC.scr - if you used CCI-LC and SOIL=JPL
add_BNUsoil_DBRK_LDPTyLDEP-CCI_LC.scr - if you used CCI-LC and SOIL=BNU

Go into the directory with your geophys files on Narval and execute the apropriate script, followed by the name of the main geophys file. The main geophys file is the one ending on '*.fst' (not '*_aux.fst' nor ' _meta.txt'). For example:

~winger/Scripts/Geophys/add_BNUsoil_DBRK_LDPTyLDEP-CCI_LC.scr geophys_${exp}.fst

f) Use your new geophys

In your 'configexp.cfg' set 'GEM_geophy' to the name of the directory(!) in which you have your new geophys and the new link 'Gem_geophy.fst', pointing to the new file created by one of the 'add_*' scripts above.