source: utils/tools/REBUILD_NEMO/README.rst @ 10727

Last change on this file since 10727 was 10338, checked in by mathiot, 2 years ago

Add deflation/chunking to rebuild_nemo tool. Fix #2165

File size: 4.9 KB
Line 
1============
2REBUILD_NEMO
3============
4REBUILD_NEMO is a tool to rebuild NEMO output files from multiple processors (mesh_mask, restart or XIOS output files) into one file.
5
6Description
7===========
8
9NEMO rebuild has the following features:
10 * dynamically works out what variables require rebuilding
11 * does not copy subdomain halo regions
12 * works for 1,2,3 and 4d arrays or types for all valid NetCDF types
13 * utilises OMP shared memory parallelisation where applicable
14 * time 'slicing' for lower memory use  (only for 4D vars with unlimited dimension)
15
16The code reads the filestem and number of subdomains from the namelist file nam_rebuild.
17| The 1st subdomain file is used to determine the dimensions and variables in all the input files.
18It is also used to find which dimensions (and hence which variables) require rebuilding
19as well as information about the global domain.
20| It then opens all the input files (unbuffered) and creates an array of netcdf identifiers
21before looping through all the variables and updating the rebuilt output file (either by direct
22copying or looping over the number of domains and rebuilding as appropriate).
23| The code looks more complicated than it is because it has lots of case statements to deal with all
24the various NetCDF data types and with various data dimensions (up to 4d).
25| Diagnostic output is written to numout (default 6 - stdout)
26and errors are written to numerr (default 0 - stderr).
27| If time slicing is specified the code will use less memory but take a little longer.
28It does this by breaking down the 4D input variables over their 4th dimension
29(generally time) by way of a while loop.
30
31How to compile it
32=================
33REBUILD_NEMO is compiled in the same manner as all the other tools.
34The compilation script is maketools and the option are very similar to makenemo.
35
36Here an example of how to compile REBUILD_NEMO on the MetOffice XC40 HPC:
37
38.. code-block:: console
39                     
40        $ ./maketools -n REBUILD_NEMO -m XC40_METO
41
42Usage
43=====
44There is 2 manners to use REBUILD_NEMO:
45
46* **rebuild_nemo shell script**
47
48If the rebuild_nemo shell script it used, the namelist is filled automatically depending on the on-line arguments.
49
50.. code-block:: console
51
52 $ ./rebuild_nemo
53
54  NEMO Rebuild
55  ************
56
57  usage: rebuild_nemo [-l -p -s -m -n -r -d -x -y -z -t -c] filebase ndomain [rebuild dimensions]
58
59  flags:    -l arch            submit to compute node
60            -p num             use num threads
61            -s num             split 4D vars into time slice of size num
62            -m                 force masking of global arrays (zero if no mdi)
63            -n namelist        full path to namelist file to be created (otherwise default nam_rebuild+_process_id is used)
64            -r memory          Memory to request on compute node including units (Default = 10Gb)
65
66      key_netcdf4 only
67            -d deflate_level     deflate level for output files
68            -x chunksize along x
69            -y chunksize along y
70            -z chunksize along z
71            -t chunksize along t
72            -c total size of the chunk cache
73
74In case the option '-l arch' is used, a template for the batch script and parameter for job submission has to be provided in BATCH_TEMPLATES (param_arch and rebuild_nemo_batch_arch).
75Exemple from the XC40_METO architecture can be found in the directory.
76Some keywords (NTHREADS, MEMORY, INDIR, NAMELIST and NOPEN) from the template are replaced by the rebuild_nemo script.
77
78* **rebuild_nemo.exe + namelist**
79
80If rebuild_nemo.exe is used directly, a namelist has to be provided. Default name is nam_rebuild. A specific name can be provided as argument.
81The minimal namelist required is (here example to rebuild a mesh_mask split in 36 files):
82
83.. code-block:: console
84
85         &nam_rebuild
86         filebase='mesh_mask'
87         ndomain=36
88         /
89
90Some option can be added (the value mentioned here are the default value):
91
92.. code-block:: console
93
94         l_maskout=.false       !(-m option: useful if input file comes from a run using land suppression)
95         nslicesize=0           !(-s option: 0 means no splitting in time slice)
96         deflate_level=0        !(-d option)
97         nc4_xchunk=206         !(-x option)
98         nc4_ychunk=135         !(-y option)
99         nc4_zchunk=1           !(-z option)
100         nc4_tchunk=1           !(-t option)
101         fchunksize=32000000    !(-c option)
102
103Example
104=======
105
106Here is an example of usage of rebuild_nemo shelf script
107(rebuild mesh_mask files on the XC40_METO computer with deflation level set to 1 and chunksize to (1,1,100,100)):
108
109.. code-block:: console
110
111          $ rebuild_nemo -l XC40_METO -m -d 1 -x 100 -y 100 -z 1 -t 1 mesh_mask 36
112
113          output is mask using netcdf missing value (_Fillvalue attribute) or 0 if missing value not in the netcdf.
114
115          file mesh_mask,  num_domains 36, num_threads 1
116          Submitting job to compute node
117          8510610.xcs00
118         $
Note: See TracBrowser for help on using the repository browser.