# How To Use (Quick Start) @tableofcontents SIREN is a software to set up regional configuration with [NEMO](http://www.nemo-ocean.eu).
Actually SIREN creates all the input files you need to run a NEMO regional configuration.
SIREN is composed of a set of 5 Fortran programs : @warning SIREN can not: Here after we briefly describe how to use each programs, and so how to create your own regional configuration. @note A set of GLORYS files (global reanalysis on *ORCA025* grid), as well as examples of namelists are available in dods repository.
You could create and forced a first release of your own regional configuration, with those files. # Create coordinates file # {#coord} To create your own configuration, you first have to create a coordinates file on your domain of study.
SIREN allows you to create this coordinates file from a wider coordinates file.
The coordinates file created could simply be an extraction, or a refinment of the wide grid.
To create this new cooridnates file, you have to run : ~~~~~~~~~~~~~~~~~~ ./SIREN/create_coord.exe create_coord.nam ~~~~~~~~~~~~~~~~~~ Here after is an example of namelist for *create_coord.exe*.
In this example, you create a coordinates file named *coord_fine.nc*.
This new coordinates file is refined from an extraction of *coordinates_ORCA025.nc*. ~~~~~~~~~~~ &namlog / &namcfg cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg" / &namcrs cn_coord0 = "PATH/coordinates_ORCA025.nc" in_perio0 = 4 / &namvar / &namnst in_imin0 = 1070 in_imax0 = 1072 in_jmin0 = 607 in_jmax0 = 609 in_rhoi = 2 in_rhoj = 3 / &namout cn_fileout = "PATH/coord_fine.nc" / ~~~~~~~~~~~ Let's get describe this namelist.
First we have the **namlog** sub-namelist. This sub-namelist set parameters of the log file.
All the parameters of this sub-namelist have default value, so you could let it empty, as done here.
This will create a log file named *create_coord.log* The **namcfg** sub-namelist defines where found SIREN configuration file.
This configuration file defines standard name, default interpolation method, axis,... to be used for some known variables.
Obviously, you could add other variables to those already list, in this file. @note You could find the generic version of *variable.cfg* in the directory *NEMOGCM/TOOLS/SIREN/cfg*. The **namcrs** sub-namelist set parameters of the wide coordinates file,
as path to find it, and NEMO periodicity of the wide grid.
@note the NEMO periodicity could be choose between 0 to 6:
in_perio=0
standard regional model
in_perio=1
east-west cyclic model
in_perio=2
model with symmetric boundary condition across the equator
in_perio=3
regional model with North fold boundary and T-point pivot
in_perio=4
global model with a T-point pivot.
example: ORCA2, ORCA025, ORCA12
in_perio=5
regional model with North fold boundary and F-point pivot
in_perio=6
global model with a F-point pivot
example: ORCA05
@sa For more information see @ref md_docsrc_6_perio The **namvar** sub-namelist lists variables to be used.
By default all the variables of the wider coordinates file are used to create the new coordinates file.
The interpolation methods to be used are defined in the configuration variables file (see below). So you do not need to fill this sub-namelist too. The **namnst** sub-namelist defines the subdomain to be used as well as refinment factor.
@note Subdomain is defined by indices of the coarse/wide grid.
Finally the **namout** sub-namelist defines the output file.
@note All the output files created by SIREN include information about NEMO periodicity, as well as source file, indices and refinment used. @sa For more information about how to create coordinates, see create_coord.f90 # Create bathymetry file # {#bathy} Then you need a Bathymetry file.
SIREN allows you to create a Bathymetry extracted or refined from a wider Bathymetry grid.
To create this new bathymetry, you have to run : ~~~~~~~~~~~~~~~~~~ ./SIREN/create_bathy.exe create_bathy.nam ~~~~~~~~~~~~~~~~~~ Here after is an example of namelist for *create_bathy.exe*.
In this example, you create a bathymetry file named *bathy_fine.nc*.
This new bathymetry file is refined from an extraction of *bathy_meter_ORCA025.nc*.
Moreover a minimum value of 5m is imposed to the output Bathymetry. ~~~~~~~~~~~~~~~~~~ &namlog / &namcfg cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg" / &namcrs cn_coord0 = "PATH/coordinates_ORCA025.nc" in_perio0 = 4 / &namfin cn_coord1 = "PATH/coord_fine.nc" / &namvar cn_varfile = "Bathymetry:PATH/bathy_meter_ORCA025.nc" cn_varinfo = "Bathymetry: min=5" / &namnst in_rhoi = 2 in_rhoj = 3 / &namout cn_fileout = "PATH/bathy_fine.nc" / ~~~~~~~~~~~~~~~~~~ Let's get describe this namelist.
First as previously, we have the **namlog** and **namcfg** sub-namelist (see above for more explanation).
Then the **namcrs** sub-namelist set parameters of the wide coordinates file.
@note in all SIREN namelist:
0 referred to the coarse/wide grid.
1 referred to the fine grid. In the same way, the **namfin** sub-namelist set parameters of the fine coordinates file.
@note in this namelist example, there is no need to set the variable *in_perio1* to define the NEMO periodicity of the fine grid.
Indeed, if this variable is not inform, SIREN tries to read it in the attributes of the file.
So if you created the fine coordinates with SIREN, you do not have to fill it. In other case, you should add it to the namelist. The **namvar** sub-namelist lists variables to be used:
cn_varfile
defines the variable name ("Bathymetry" here) and the input file associated with. @warning The domain of the input Bathymetry have to be larger than the output domain. @note
cn_varinfo
defines user's requests for a variable. @note Default interpolation method for the Bathymetry, is *cubic* interpolation.
So you may want to specify a minimum value to avoid negative value, or to change interpolation method.
example:
The **namnst** sub-namelist defines the subdomain refinment factor.
Of course those refinment factors have to be convenient with refinment from coarse grid *cn_coord0* to fine grid *cn_coord1*. @note subdomain indices are automatically deduced from fine and coarse grid coordinates. Finally, this **namout** sub-namelist defines the output file.
@note All the output files create by SIREN include information about source file, indices, refinment and interpolation method used. @sa For more information about how to create bathymetry, see create_bathy.f90 # Merge bathymetry file # {#merge} The Bathymetry you build differs from the wider one.
To avoid issue with boundaries forcing fields, you should merge fine and coarse Bathymetry on boundaries.
SIREN allows you to do this.
To create this merged bathymetry, you have to run : ~~~~~~~~~~~~~~~~~~ ./SIREN/merge_bathy.exe merge_bathy.nam ~~~~~~~~~~~~~~~~~~ Here after is an example of namelist for *merge_bathy.exe*.
~~~~~~~~~~~~~~~~~~ &namlog / &namcfg cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg" / &namcrs cn_bathy0 = "PATH/bathy_meter_ORCA025.nc" in_perio0 = 4 / &namfin cn_bathy1 = "PATH/bathy_fine.nc" / &namnst in_rhoi = 3 in_rhoj = 3 / &nambdy / &namout cn_fileout = "PATH/bathy_merged.nc" / ~~~~~~~~~~~~~~~~~~ In this namelist, you find again the **namlog**, **namcfg** describe above. Then the **namcrs** sub-namelist sets parameters of the wider grid. However this time, this is the coarse/wide grid Bathymetry wich have to be informed. The **namfin** sub-namelist defines parameters of the fine grid Bathymetry. @note here again you could add the *in_perio1* parameter if need be i.e. if your fine grid Bathymetry was not created by SIREN. The **namnst** sub-namelist defines the subdomain refinment factor. The **nambdy** sub-namelist defines the subdomain boundaries.
By 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. @sa For more information about boundaries, see @ref boundary Finally, this **namout** sub-namelist defines the output file.
@sa For more information about how to merge bathymetry, see merge_bathy.f90 # Create initial state # {#restart} To run your configuration you need an inital state of the ocean.
You could start from a restart file (with all NEMO variables fields at one time step). Or you could start from "partial" information about ocean state (Temperature and Salinity for example). Siren allows you to create both of those initial state.
To create the initial state, you have to run:
~~~~~~~~~~~~~~~~~~ ./SIREN/create_restart.exe create_restart.nam ~~~~~~~~~~~~~~~~~~ Here after is an example of namelist for *create_restart.exe*.
In this example, you create an initial state split on 81 "processors", and named restar_out.nc.
The initial state is composed of temperature and salinity refined from an extraction of GLORYS fields. ~~~~~~~~~~~~~~~~~~ &namlog / &namcfg cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg" / &namcrs cn_coord0 = "PATH/coordinates_ORCA025.nc" in_perio0 = 4 / &namfin cn_coord1 = "PATH/coord_fine.nc" cn_bathy1 = "PATH/bathy_merged.nc" / &namzgr / &namzps / &namvar cn_varfile = "votemper:GLORYS_gridT.nc", "vosaline:GLORYS_gridS.nc" / &namnst in_rhoi = 3 in_rhoj = 3 / &namout cn_fileout = "PATH/restart_out.nc" in_nproc = 81 / ~~~~~~~~~~~~~~~~~~ Let's get describe this namelist more accurately.
As previously, we have the **namlog** and **namcfg** sub-namelists, as well as the **namcrs** sub-namelist to set parameters of the wide coordinates file (see above for more explanation).
Then the **namfin** sub-namelist set parameters of the fine grid coordinates and bathymetry.
The **namzgr** and **namzps** sub-namelists define respectively parameters for vertical grid and partial step.
By default, those parameters are defined the same way than in GLORYS (i.e. 75 vertical levels).
So you could let it empty. @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). the **namvar** sub-namelist lists variables to be used.
Here we use *votemper* (temperature) get from *GLORYS_gridT.nc* file, and *vosaline* (salinity) get from *GLORYS_gridS.nc* file. @note To get all variables of a restart file. You have to use: ~~~~~~~~~~~~~~~~~~ cn_varfile = "all:PATH/restart.dimg" ~~~~~~~~~~~~~~~~~~ The **namnst** sub-namelist defines the subdomain refinment factor, as seen previously.
Finally, this **namout** sub-namelist defines the output files.
Here we ask for output on 81 processors, with *restart_out.nc* as file "basename".
So SIREN computes the optimal layout for 81 porcessors available,
and split restart on output files named *restart_out_num.nc*, where *num* is the porc number. @note SIREN could also create the other fields you may need for your configuration.
To do so, you just have to run *create_restart.exe* with other variable(s) from other input file(s).
For example, to get runoff fields, you could use: ~~~~~~~~~~~~~~~~~~ cn_varfile = "sorunoff:PATH/runoff_GLORYS.nc" ... cn_fileout = "PATH/runoff_out.nc" ~~~~~~~~~~~~~~~~~~ @sa For more information about how to create initial state or other fields, see create_restart.f90 # Create boundaries conditions # {#boundary} Finally to force your configuration, you may need boundaries conditions.
NEMO read physical boundaries conditions from temperature, salinity, currents, and sea surface height. To create the boundaries condition with SIREN, you have to run:
~~~~~~~~~~~~~~~~~~ ./SIREN/create_boundary.exe create_boundary.nam ~~~~~~~~~~~~~~~~~~ Here after is an example of namelist for *create_boundary.exe*.
In this example, you create boundaries conditions named *boundary_out.nc* on each side of the domain.
The boundaries contain information about temperature, salinity, currents and sea surface height refined from an extraction of GLORYS fields. ~~~~~~~~~~~~~~~~~~ &namlog / &namcfg cn_varcfg = "PATH/NEMOGCM/TOOLS/SIREN/cfg/variable.cfg" / &namcrs cn_coord0 = "PATH/coordinates_ORCA025.nc" in_perio0 = 4 / &namfin cn_coord1 = "PATH/coord_fine.nc" cn_bathy1 = "PATH/bathy_fine.nc" / &namzgr / &namzps / &namvar cn_varfile="votemper:GLORYS_gridT.nc", "vosaline:GLORYS_gridS.nc", "vozocrtx:GLORYS_gridU.nc", "vomecrty:GLORYS_gridV.nc", "sossheig:GLORYS_grid2D.nc" / &namnst in_rhoi = 3 in_rhoj = 3 / &nambdy / &namout cn_fileout = "PATH/boundary_out.nc" / ~~~~~~~~~~~~~~~~~~ Let's get describe this namelist more accurately.
As previously, we have the **namlog** and **namcfg** sub-namelists, as well as the **namcrs** sub-namelist to set parameters of the wide coordinates file (see above for more explanation).
Then the **namfin** sub-namelist set parameters of the fine grid coordinates and bathymetry.
The **namzgr** and **namzps** sub-namelists define respectively parameters for vertical grid and partial step.
By default, those parameters are defined the same way than in GLORYS (i.e. 75 vertical levels).
So you could let it empty. @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). the **namvar** sub-namelist lists variables to be used.
Here we get *votemper* (temperature) from *GLORYS_gridT.nc* file, *vosaline* (salinity) from *GLORYS_gridS.nc* file, *vozocrtx* (zonal velocity) from *GLORYS_gridU.nc*, *vomecrty* (meridional velocity) from *GLORYS_gridV.nc*, and sossheig (sea surface height) from *GLORYS_grid2D.nc*. The **namnst** sub-namelist defines the subdomain refinment factor.
The **nambdy** sub-namelist defines the subdomain boundaries.
By default SIREN tries to create boundaries for each side (Boundary is created if sea point exist on the second row of each side).
So you could let this namelist empty. @note SIREN allows you to place boundaries away from the side of the domain. To do so you have to define your boundary.
That means you have to give on fine grid the index of the boundary (how far from the border your boundary is), the width of your boundary, and finally first and last point of your boundary (the length of your boundary).
So to define a north boundary, you have to add in the sub-namelist *nambdy*, the parameter: ~~~~~~~~~~~~~~~~~~ cn_north="index,first:last(width)" ~~~~~~~~~~~~~~~~~~ Finally, this **namout** sub-namelist defines the output files.
Here we ask for output with *boundary_out.nc* as file "basename".
So SIREN creates output files named *boundary_out_west.nc*, *boundary_out_east.nc*, *boundary_out_north.nc*, and *boundary_out_south.nc* depending if boundary exist or not. @sa For more information about how to create boundaries condition, see create_boundary.F90 # Create and run NEMO configuration # {#NEMOconf} So now you created all the input files you need for your physical configuration, you have to create the "NEMO configuration".
To do so, go to the directory *NEMOGCM/CONFIG/*, and run: ~~~~~~~~~~~~~~~~~~ ./makenemo -n MY_CONFIG -d "OPA_SRC" ~~~~~~~~~~~~~~~~~~ This creates your configuration "MY_CONFIG" in the directory *NEMOGCM/CONFIG*.
you could check the cpp_keys used in file *cpp_MY_CONFIG.fcm*, and re-run *makenemo* if need be. Once *makenemo* has run successfully, the *opa* executable is available in directory *NEMOGCM/CONFIG/MY_CONFIG/EXP00*.
Then you just have to put all your input files in this directory, fill the namelist *namelist_cfg*, and run: ~~~~~~~~~~~~~~~~~~ mpirun ./opa ~~~~~~~~~~~~~~~~~~ @note no surface forcing here. weighted function needed to do interpolation on the fly, could be created by WEIGHT tools already inside NEMO. @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).
- @ref index - @ref md_docsrc_1_install - @ref md_docsrc_2_quickstart - @ref md_docsrc_3_support_bug - @ref md_docsrc_4_codingRules - @ref md_docsrc_5_changeLog - @ref todo