New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
2_quickstart.md in NEMO/releases/release-3.6/NEMOGCM/TOOLS/SIREN/src/docsrc – NEMO

source: NEMO/releases/release-3.6/NEMOGCM/TOOLS/SIREN/src/docsrc/2_quickstart.md @ 10211

Last change on this file since 10211 was 10211, checked in by jpaul, 5 years ago

# Change

  • change url of SIREN test inputs' files
File size: 20.2 KB
Line 
1# How To Use (Quick Start)
2
3@tableofcontents
4
5SIREN is a software to set up regional configuration with
6 [NEMO](http://www.nemo-ocean.eu).<br/>
7Actually SIREN creates all the input files you need to run a NEMO regional configuration.<br/>
8 
9SIREN is composed of a set of 5 Fortran programs :
10<ul>
11 <li>create_coord.f90 to create regional grid coordinates.</li>
12 <li>create_bathy.f90 to create regional grid bathymetry.</li>
13 <li>merge_bathy.f90 to merge regional grid bathymetry with wider grid bathymetry
14 at boundaries.
15 @note the goal of this step is to avoid break in Bathymetry.
16 This break may cause inconsistency between forcing fields  at boundary and regional fields.
17 </li>
18 <li>create_restart.f90 to create initial state file from coarse grid restart
19 or standard outputs.
20 @note this program could also be used to refined other input fields from a wider
21 configuations (as runoff, chlorophyll etc...)
22 </li>
23 <li>create_boundary.F90 to create boundaries conditions from wider configurations
24 output fields.
25 </li>
26</ul>
27
28@warning SIREN can not:
29<ul>
30<li>create global configuration.</li>
31<li>create configuarion around or close to North pole.</li>
32<li>change number of vertical level.</li>
33</ul>
34
35Here after we briefly describe how to use each programs,
36and so how to create your own regional configuration.
37@note As demonstrator for a first start a set of GLORYS files (global reanalysis on *ORCA025* grid), as well as examples of namelists are available [here](https://atlas.mercator-ocean.fr/s/TwoSPc5ZG4GXEeD).
38
39<!-- ######################################################################  -->
40# Create coordinates file # {#coord}
41
42To create your own configuration, you first have to create a coordinates file on your domain of study.<br/>
43SIREN allows you to create this coordinates file from a wider coordinates file.<br/>
44The coordinates file created could simply be an extraction, or a refinment of
45the wide grid.<br/>
46
47To create this new cooridnates file, you have to run :
48~~~~~~~~~~~~~~~~~~
49./SIREN/create_coord.exe create_coord.nam
50~~~~~~~~~~~~~~~~~~
51
52Here after is an example of namelist for *create_coord.exe*.<br/>
53In this example, you create a coordinates file named *coord_fine.nc*.<br/>
54This new coordinates file is refined from an extraction of *coordinates_ORCA025.nc*.
55~~~~~~~~~~~
56&namlog
57/
58
59&namcfg
60   cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg"
61   cn_dimcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/dimension.cfg"
62/
63
64&namcrs
65   cn_coord0 = "PATH/coordinates_ORCA025.nc"
66   in_perio0 = 4
67/
68
69&namvar
70/
71
72&namnst
73   in_imin0 = 1070
74   in_imax0 = 1072
75   in_jmin0 = 607
76   in_jmax0 = 609
77
78   in_rhoi = 2
79   in_rhoj = 3
80/
81
82&namout
83   cn_fileout = "PATH/coord_fine.nc"
84/
85~~~~~~~~~~~
86
87@note you could define sub domain with coarse grid indices or with coordinates.
88
89Let's get describe this namelist.<br/>
90First we have the **namlog** sub-namelist. This sub-namelist set parameters of the log
91file.<br/>
92All the parameters of this sub-namelist have default value, so you could let it
93empty, as done here.<br/> This will create a log file named *create_coord.log*
94
95The **namcfg** sub-namelist defines where found SIREN configuration files.<br/>
96- The variable configuration file defines standard name, default interpolation method,
97axis,... to be used for some known variables.<br/>
98Obviously, you could add other variables to those already list, in this file.
99- The dimension configuration file defines dimensions allowed.
100
101@note You could find the generic version of those configuration files in the directory *NEMOGCM/TOOLS/SIREN/cfg*.
102
103The **namcrs** sub-namelist set parameters of the wide
104coordinates file, as path to find it, and NEMO periodicity of the wide grid.<br/>
105
106@note the NEMO periodicity could be choose between 0 to 6:
107<dl>
108<dt>in_perio=0</dt>
109<dd>standard regional model</dd>
110<dt>in_perio=1</dt>
111<dd>east-west cyclic model</dd>
112<dt>in_perio=2</dt>
113<dd>model with symmetric boundary condition across the equator</dd>
114<dt>in_perio=3</dt>
115<dd>regional model with North fold boundary and T-point pivot</dd>
116<dt>in_perio=4</dt>
117<dd>global model with a T-point pivot.<br/>
118example: ORCA2, ORCA025, ORCA12</dd>
119<dt>in_perio=5</dt>
120<dd>regional model with North fold boundary and F-point pivot</dd>
121<dt>in_perio=6</dt>
122<dd>global model with a F-point pivot<br/>
123example: ORCA05</dd>
124</dl>
125@sa For more information see @ref md_src_docsrc_6_perio
126</dd>
127</dl>
128
129The **namvar** sub-namelist lists variables to be used.<br/>
130By default all the variables of the wider coordinates file are used to create
131the new coordinates file.<br/>
132The interpolation methods to be used are defined in the configuration variables file (see
133below). So you do not need to fill this sub-namelist too.
134
135The **namnst** sub-namelist defines the subdomain to be used as well as refinment factor.<br/>
136
137<ul>
138<li> you could define sub domain with coarse grid indices</li>
139
140~~~~~~~~~~~
141&namnst
142   in_imin0 = 1070
143   in_imax0 = 1072
144   in_jmin0 = 607
145   in_jmax0 = 609
146/
147~~~~~~~~~~~
148
149<li>or with coordinates</li>
150
151~~~~~~~~~~~
152&namnst
153   rn_lonmin0 = -97.9
154   rn_lonmax0 = -62.3
155   rn_latmin0 =   7.7
156   rn_latmax0 =  30.8
157/
158~~~~~~~~~~~
159
160<li>you can select area quite every where (excepted too close from the North
161pole), and use the refinment factor you want.</li>
162
163~~~~~~~~~~~
164&namnst
165   in_imin0 = 1070
166   in_imax0 = 1072
167   in_jmin0 = 607
168   in_jmax0 = 609
169
170   in_rhoi = 2
171   in_rhoj = 3
172/
173~~~~~~~~~~~
174@image html grid_zoom_60.png
175<center>@image latex grid_zoom_40.png
176</center>
177<!-- @note ghost cells all around the grid are not shown here. -->
178
179
180
181<li>you can select area crossing the east-west overlap of the global ORCA grid.</li>
182
183~~~~~~~~~~~
184&namnst         
185   in_imin0 = 1402
186   in_imax0 = 62
187   in_jmin0 = 490
188   in_jmax0 = 570
189
190   in_rhoi = 5
191   in_rhoj = 5
192/               
193~~~~~~~~~~~
194@image html grid_glob_over_30.png
195<center>@image latex grid_glob_over_20.png
196</center>
197<!-- @note in blue, the east-west overlap band of ORCA grid. -->
198
199<li>you can select east-west cyclic area.</li>
200
201~~~~~~~~~~~
202&namnst
203   in_imin0 = 0
204   in_imax0 = 0
205   in_jmin0 = 390
206   in_jmax0 = 450
207
208   in_rhoi = 1
209   in_rhoj = 1
210/
211~~~~~~~~~~~
212@image html grid_glob_band_30.png
213<center>@image latex grid_glob_band_20.png
214</center>
215
216</ul>
217
218Finally the **namout** sub-namelist defines the output file.<br/>
219
220@note All the output files created by SIREN include information about NEMO
221periodicity, as well as source file, indices and refinment used.
222
223@sa For more information about how to create coordinates, see create_coord.f90
224
225<!-- ######################################################################  -->
226# Create bathymetry file # {#bathy}
227
228Then you need a Bathymetry file.<br/>
229SIREN allows you to create a Bathymetry extracted or refined from a wider
230Bathymetry grid.<br/>
231
232To create this new bathymetry, you have to run :
233~~~~~~~~~~~~~~~~~~
234./SIREN/create_bathy.exe create_bathy.nam
235~~~~~~~~~~~~~~~~~~
236
237Here after is an example of namelist for *create_bathy.exe*.<br/>
238In this example, you create a bathymetry file named *bathy_fine.nc*.<br/>
239This new bathymetry file is refined from an extraction of *bathy_meter_ORCA025.nc*.<br/>
240Moreover a minimum value of 5m is imposed to the output Bathymetry.
241~~~~~~~~~~~~~~~~~~
242&namlog
243/
244
245&namcfg
246   cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg"
247   cn_dimcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/dimension.cfg"
248/
249
250&namcrs
251   cn_coord0 = "PATH/coordinates_ORCA025.nc"
252   in_perio0 = 4
253/
254
255&namfin
256   cn_coord1 = "PATH/coord_fine.nc"
257/
258
259&namvar
260   cn_varfile = "Bathymetry:PATH/bathy_meter_ORCA025.nc"
261   cn_varinfo = "Bathymetry: min=5"
262/
263
264&namnst
265   in_rhoi = 2
266   in_rhoj = 3
267/
268
269&namout
270   cn_fileout = "PATH/bathy_fine.nc"     
271/
272~~~~~~~~~~~~~~~~~~
273
274Let's get describe this namelist.<br/>
275
276First as previously, we have the **namlog** and **namcfg** sub-namelist (see above for more
277explanation).<br/>
278
279Then the **namcrs** sub-namelist set parameters of the wide
280coordinates file.<br/>
281@note in all SIREN namelist: <br/>
282**0** referred to the coarse/wide grid.<br/>
283**1** referred to the fine grid.
284
285In the same way, the **namfin** sub-namelist  set parameters of the fine
286coordinates file.<br/>
287@note in this namelist example, there is no need to set the variable *in_perio1* to define the NEMO
288periodicity of the fine grid. Indeed, if this variable is not inform, SIREN tries to read it
289in the global attributes of the file. So if you created the fine coordinates with SIREN, you do not have to
290fill it. In other case, you should add it to the namelist.
291
292The **namvar** sub-namelist lists variables to be used:
293<dl>
294   <dt>cn_varfile</dt>
295      <dd> defines the variable name ("Bathymetry" here) and the input file associated with.
296            @warning The domain of the input Bathymetry have to be larger than the output domain.
297         @note
298         <ul>
299            <li>if the input file is at coarse grid resolution (same than *cn_coord0*), the ouptut Bathymetry will be refined on fine grid.</li>
300            <li>if the input file is a wider bathymetry (already at fine grid resolution), the output Bathymetry will be extracted from this one.</li>
301         </ul>
302      </dd>
303   <dt>cn_varinfo</dt>
304      <dd> defines user's requests for a variable.
305         @note Default interpolation method for the Bathymetry, is *cubic* interpolation.<br/>
306         So you may want to specify a minimum value to avoid negative value, or to change interpolation method.<br/>
307         example: <ul><li>cn_varinfo="Bathymetry: min=1"'</li>
308                      <li>cn_varinfo="Bathymetry: int=linear"</li></ul>
309      </dd>
310</dl>
311
312The **namnst** sub-namelist defines the subdomain refinment factor.<br/>
313Of course those refinment factors have to be convenient with refinment
314from coarse grid *cn_coord0* to fine grid *cn_coord1*.
315@note subdomain indices are automatically deduced from fine and coarse grid
316coordinates.
317
318Finally, this **namout** sub-namelist defines the output file.<br/>
319
320@note All the output files create by SIREN include information about
321source file, indices, refinment and interpolation method used.
322
323@sa For more information about how to create bathymetry, see
324create_bathy.f90
325
326<!-- ######################################################################  -->
327# Merge bathymetry file # {#merge}
328
329The Bathymetry you build, may differ from the wider one.<br/>
330To avoid issue with boundaries forcing fields, you should merge fine and coarse Bathymetry on boundaries.<br/>
331SIREN allows you to do this.<br/>
332
333To create this merged bathymetry, you have to run :
334~~~~~~~~~~~~~~~~~~
335./SIREN/merge_bathy.exe merge_bathy.nam
336~~~~~~~~~~~~~~~~~~
337
338Here after is an example of namelist for *merge_bathy.exe*.<br/>
339~~~~~~~~~~~~~~~~~~
340&namlog
341/
342
343&namcfg
344   cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg"
345   cn_dimcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/dimension.cfg"
346/
347
348&namcrs
349   cn_bathy0 = "PATH/bathy_meter_ORCA025.nc"
350   in_perio0 = 4
351/
352
353&namfin
354   cn_bathy1 = "PATH/bathy_fine.nc"
355/
356
357&namnst
358   in_rhoi = 3
359   in_rhoj = 3
360/
361
362&nambdy
363/
364
365&namout
366   cn_fileout = "PATH/bathy_merged.nc"     
367/
368~~~~~~~~~~~~~~~~~~
369In this namelist, you find again the **namlog**, **namcfg** describe above.
370
371Then the **namcrs** sub-namelist sets parameters of the wider grid.
372However this time, this is the coarse/wide grid Bathymetry wich have to be informed.
373
374The **namfin** sub-namelist defines parameters of the fine grid Bathymetry.
375@note here again you could add the *in_perio1* parameter if need be i.e. if your
376fine grid Bathymetry was not created by SIREN.
377
378The **namnst** sub-namelist defines the subdomain refinment factor.
379
380
381The **nambdy** sub-namelist defines the subdomain boundaries.<br/>
382By default SIREN tries to create boundaries for each side. Boundary exist if there is at least one sea point on the second row of each side. So you could let this namelist empty.
383@sa For more information about boundaries, see @ref boundary
384
385Finally, this **namout** sub-namelist defines the output file.<br/>
386
387@sa For more information about how to merge bathymetry, see
388merge_bathy.f90
389
390<!-- ######################################################################  -->
391# Create initial state # {#restart}
392
393To run your configuration you need an inital state of the ocean.<br/>
394You could start from a restart file (with all NEMO variables fields at one
395time step). Or you could start from "partial" information about ocean state (Temperature and Salinity for example).
396
397SIREN allows you to create both of those initial state.<br/>
398To create the initial state, you have to run:<br/>
399~~~~~~~~~~~~~~~~~~
400./SIREN/create_restart.exe create_restart.nam
401~~~~~~~~~~~~~~~~~~
402
403Here after is an example of namelist for *create_restart.exe*.<br/>
404In this example, you create an initial state split on 81 "processors", and named restart_out.nc.<br/>
405The initial state is composed of temperature and salinity refined from an extraction of GLORYS fields.
406~~~~~~~~~~~~~~~~~~
407&namlog
408/
409
410&namcfg
411   cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg"
412   cn_dimcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/dimension.cfg"
413/
414
415&namcrs
416   cn_coord0 = "PATH/coordinates_ORCA025.nc"
417   in_perio0 = 4
418/
419
420&namfin
421   cn_coord1 = "PATH/coord_fine.nc"
422   cn_bathy1 = "PATH/bathy_merged.nc"
423/
424
425&namzgr
426/
427
428&namzps
429/
430
431&namvar
432   cn_varfile = "votemper:GLORYS_gridT.nc",
433                "vosaline:GLORYS_gridS.nc"
434/
435
436&namnst
437   in_rhoi = 3
438   in_rhoj = 3
439/
440
441&namout
442   cn_fileout = "PATH/restart_out.nc"     
443   in_nproc = 81
444/
445~~~~~~~~~~~~~~~~~~
446Let's get describe this namelist more accurately.<br/>
447
448As previously, we have the **namlog** and **namcfg** sub-namelists, as well as
449the **namcrs** sub-namelist to set parameters of the wide coordinates file (see above for more
450explanation).<br/>
451
452Then the **namfin** sub-namelist set parameters of the fine
453grid coordinates and bathymetry.<br/>
454
455The **namzgr** and **namzps** sub-namelists define respectively parameters for vertical grid
456and partial step.<br>
457By default, those parameters are defined the same way than in GLORYS (i.e. 75 vertical levels).<br/>
458So you could let it empty.
459@note If you use forcing fields other than GLORYS, you have to be sure it uses the same vertical grid. In other case, you need to get information about the parametrisation use, and to put it in those sub-namelist (see create_restart.f90).
460
461the **namvar** sub-namelist lists variables to be used.<br/>
462Here we use *votemper* (temperature) get from *GLORYS_gridT.nc* file, and *vosaline*
463(salinity) get from *GLORYS_gridS.nc* file.
464@note To get all variables of a restart file. You have to use:
465~~~~~~~~~~~~~~~~~~
466cn_varfile = "all:PATH/restart.dimg"
467~~~~~~~~~~~~~~~~~~
468
469The **namnst** sub-namelist defines the subdomain refinment factor, as seen previously.<br/>
470
471Finally, this **namout** sub-namelist defines the output files.<br/>
472Here we ask for output on 81 processors, with *restart_out.nc* as file "basename".<br/>
473So SIREN computes the optimal layout for 81 processors
474available,<br/>
475and split restart on output files named *restart_out_num.nc*, where *num* is the proc number.
476
477@note SIREN could also create the other fields you may need for
478your configuration.<br/>
479To do so, you just have to run *create_restart.exe* with other variable(s) from other input file(s).<br/>
480For example, to get runoff fields, you could use:
481~~~~~~~~~~~~~~~~~~
482cn_varfile = "sorunoff:PATH/runoff_GLORYS.nc"
483...
484cn_fileout = "PATH/runoff_out.nc"
485~~~~~~~~~~~~~~~~~~
486
487@sa For more information about how to create initial state or other fields, see
488create_restart.f90
489
490<!-- ######################################################################  -->
491# Create boundaries conditions # {#boundary}
492
493Finally to force your configuration, you may need boundaries conditions.<br/>
494NEMO read physical boundaries conditions from temperature, salinity, currents, and sea
495surface height.
496
497To create the boundaries condition with SIREN, you have to run:<br/>
498~~~~~~~~~~~~~~~~~~
499./SIREN/create_boundary.exe create_boundary.nam
500~~~~~~~~~~~~~~~~~~
501
502Here after is an example of namelist for *create_boundary.exe*.<br/>
503In this example, you create boundaries conditions named *boundary_out.nc* on
504each side of the domain.<br/>
505The boundaries contain information about temperature, salinity, currents and sea surface height refined from an extraction of GLORYS fields.
506~~~~~~~~~~~~~~~~~~
507&namlog
508/
509
510&namcfg
511   cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg"
512   cn_dimcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/dimension.cfg"
513/
514
515&namcrs
516   cn_coord0 = "PATH/coordinates_ORCA025.nc"
517   in_perio0 = 4
518/
519
520&namfin
521   cn_coord1 = "PATH/coord_fine.nc"
522   cn_bathy1 = "PATH/bathy_fine.nc"
523/
524
525&namzgr
526/
527
528&namzps
529/
530
531&namvar
532   cn_varfile="votemper:GLORYS_gridT.nc",
533              "vosaline:GLORYS_gridS.nc",
534              "vozocrtx:GLORYS_gridU.nc",
535              "vomecrty:GLORYS_gridV.nc",
536              "sossheig:GLORYS_grid2D.nc"
537/
538
539&namnst
540   in_rhoi = 3
541   in_rhoj = 3
542/
543
544&nambdy
545/
546
547&namout
548   cn_fileout = "PATH/boundary_out.nc"     
549/
550~~~~~~~~~~~~~~~~~~
551
552Let's get describe this namelist more accurately.<br/>
553
554As previously, we have the **namlog** and **namcfg** sub-namelists, as well as
555the **namcrs** sub-namelist to set parameters of the wide coordinates file (see above for more
556explanation).<br/>
557
558Then the **namfin** sub-namelist set parameters of the fine
559grid coordinates and bathymetry.<br/>
560
561The **namzgr** and **namzps** sub-namelists define respectively parameters for vertical grid
562and partial step.<br>
563By default, those parameters are defined the same way than in GLORYS (i.e. 75 vertical levels).<br/>
564So you could let it empty.
565@note If you use forcing fields other than GLORYS, you have to be sure it uses the same vertical grid. In other case, you need to get information about the parametrisation use, and to put it in those sub-namelist (see create_boundary.F90).
566
567the **namvar** sub-namelist lists variables to be used.<br/>
568Here we get *votemper* (temperature) from *GLORYS_gridT.nc* file, *vosaline*
569(salinity) from *GLORYS_gridS.nc* file, *vozocrtx* (zonal velocity) from
570*GLORYS_gridU.nc*, *vomecrty* (meridional velocity) from *GLORYS_gridV.nc*, and sossheig (sea surface
571height) from *GLORYS_grid2D.nc*.
572
573The **namnst** sub-namelist defines the subdomain refinment factor.<br/>
574
575The **nambdy** sub-namelist defines the subdomain boundaries.<br/>
576By default SIREN tries to create boundaries for each side (Boundary is created if sea point exist on the second row of each side).<br/>
577So you could let this namelist empty.
578
579@note SIREN allows you to place boundaries away from the side of the domain.
580To do so you have to define your boundary.<br/>
581That means you have to give on fine
582grid the index of the boundary (how far from the border your boundary is),
583the width of your boundary, and finally first and last point of your boundary (the length of your boundary).<br/>
584So to define a north boundary, you have to add in the sub-namelist *nambdy*, the parameter:
585~~~~~~~~~~~~~~~~~~
586cn_north="index,first:last(width)"
587~~~~~~~~~~~~~~~~~~
588
589Finally, this **namout** sub-namelist defines the output files.<br/>
590Here we ask for output with *boundary_out.nc* as file "basename".<br/>
591So SIREN creates output files named *boundary_out_west.nc*,
592*boundary_out_east.nc*, *boundary_out_north.nc*, and *boundary_out_south.nc*
593depending if boundary exist or not.
594
595@sa For more information about how to create boundaries condition, see
596create_boundary.F90
597
598# Create and run NEMO configuration # {#NEMOconf}
599
600So now you created all the input files you need for your physical configuration, you have to create the "NEMO configuration".<br/>
601To do so, go to the directory *NEMOGCM/CONFIG/*, and run:
602~~~~~~~~~~~~~~~~~~
603./makenemo -n MY_CONFIG -d "OPA_SRC"
604~~~~~~~~~~~~~~~~~~
605This creates your configuration "MY_CONFIG" in the directory *NEMOGCM/CONFIG*.<br/>
606you could check the cpp_keys used in file *cpp_MY_CONFIG.fcm*, and re-run *makenemo*
607if need be.
608
609Once *makenemo* has run successfully, the *opa* executable is available in
610directory *NEMOGCM/CONFIG/MY_CONFIG/EXP00*.<br/>
611Then you just have to put all your input files in this directory, fill the namelist *namelist_cfg*, and run:
612~~~~~~~~~~~~~~~~~~
613mpirun ./opa
614~~~~~~~~~~~~~~~~~~
615
616@note no surface forcing here.
617weighted function needed to do interpolation on the fly, could be created by WEIGHT tools already inside NEMO.
618
619@sa For more information about how to create NEMO configuration see [NEMO Quick Start Guide](http://www.nemo-ocean.eu/Using-NEMO/User-Guides/Basics/NEMO-Quick-Start-Guide).
620
621 <HR>
622   <b>
623   - @ref index
624   - @ref md_src_docsrc_1_install
625   - @ref md_src_docsrc_2_quickstart
626   - @ref md_src_docsrc_3_support_bug
627   - @ref md_src_docsrc_4_codingRules
628   - @ref md_src_docsrc_5_changeLog
629   - @ref todo
630   </b>
Note: See TracBrowser for help on using the repository browser.