== Salt and Temperature Nudging in SELFE ==
Salt and temperature nudging is available by means of analysis nudging (Newtonian relaxation). The nudging allows the model state to be reconciled with observations in four dimensions. There are three known examples of this nudging:
* CORIE applications on the Columbia River, assimilating NCOM results near the ocean boundary
* The SEMAME project, using nudging to couple ROMS on the California coast and SELFE on the San Francisco Bay-Delta in a common band along the coast
* Salinity initialization of the Bay-Delta project, which uses salt nudging to shorten long spin up times far upstream of the ocean boundary

== Formulation ==
The nudging formula is an analysis nudging model:
$$
\frac{\partial \alpha}{\partial t} = F(\alpha,x,t) + W_{\alpha}(x,t)(\hat{\alpha_0} - \alpha)
$$
where $\alpha$ comprises the state variables to be nudged at every location (node, side) and the $W_\alpha$ are relaxation weights that are decomposed:
$W_{\alpha} = w_{xy} \cdot w_{z}$

The horizontal, vertical and time parameters for the model are described below. Observation quality and the global nudging factor are bundled into $w_{xy}$. Time weighting is constant, though data are linearly interpolated between observations.

== Files and Parameters ==
The following files and parameters are used to include nudging

=== param.in ===
;inu_st: Enables nudging for inu_st = 1.

;step_nu: This is the nudging data time step, the rate at which new data are introduced to the model. It should be a multiple of the model time step. Nudging is performed every time step, through the entire simulation. Between data time steps, data is linearly interpolated.

;vnh1, vnh2, vnf1, vnf2: These are parameters used to compose $w_z$ composing the relaxation weights. For a model location between the surface and depth of vnh1, vnf1 is used. Deeper than vnh1 but less than vnh2, the weight is interpolated between vnf1 and vnf2. At depths greater than vnh2, vnf2 is used.

=== x_nudge.gr3 ===
The gr3 files represent the horizontal relaxation weights associated with each model node. Sides are given a horizontal relaxation interpolated from their nodes. Note that the weights may contain estimates of data availability and quality as well as scaling considerations. Hence, the weights may be related to the analysis methods that are used to prepare data (salt_nu.in and temp_nu.in)

=== salt_nu.in and temp_nu.in ===
These files contain the actual data used for the nudging. Nudging data are given for all nodes, not the locations of observations, and the analysis of data is assumed precalculated. The analysis quality of locations (ie lower far from any good observations) would thus be handled by:
1. a low assignment in the horizontal weight, probably with finite support so there are many zeros in this file
2. an arbitrary value in salt_nu.in.

The fortran format for creating an xxx_nu.in file is illustrated by this code block:
<nowiki>
open(35,file='salt_nu.in',form='unformatted')
do istep=0,nsteps
write(35)istep*dt_nu ! time stamp in sec (starting from 0)
do inode=1,np ! all nodes
write(35)(saltout(jvert,inode),jvert=1,nvrt) ! all vertical layers
enddo
enddo
</nowiki>

Now lets try it.

Salinity and temperature nudging

2013-02-12T18:16:41Z

Eli: /* Formulation */

== Salt and Temperature Nudging in SELFE ==
Salt and temperature nudging is available by means of analysis nudging (Newtonian relaxation). The nudging allows the model state to be reconciled with observations in four dimensions. There are three known examples of this nudging:
- CORIE applications on the Columbia River, assimilating NCOM results near the ocean boundary
- The SEMAME project, using nudging to couple ROMS on the California coast and SELFE on the San Francisco Bay-Delta in a common band along the coast
- Salinity initialization of the Bay-Delta project, which uses salt nudging to shorten long spin up times far upstream of the ocean boundary

== Salt and Temperature Nudging in SELFE ==
Salt and temperature nudging is available by means of analysis nudging (Newtonian relaxation). The nudging allows the model state to be reconciled with observations in four dimensions. There are three known examples of this nudging:
- CORIE applications on the Columbia River, assimilating NCOM results near the ocean boundary
- The SEMAME project, using nudging to couple ROMS on the California coast and SELFE on the San Francisco Bay-Delta in a common band along the coast
- Salinity initialization of the Bay-Delta project, which uses salt nudging to shorten long spin up times far upstream of the ocean boundary

== Formulation ==
The nudging formula is an analysis nudging model:
$$
\frac{\partial \alpha}{\partial t} = F(\alpha,x,t) + W_{\alpha}(x,t)(\hat{\alpha_0} - \alpha)
$$
where $\alpha$ comprises the state variables to be nudged at every location (node, side) and the $W_\alpha$ are relaxation weights that are decomposed:
$W_{\alpha} = w_{xy} \cdot w_{z}$

The horizontal, vertical and time parameters for the model are described below. Observation quality and the global nudging factor are bundled into $w_{xy}$. Time weighting is constant, though data are linearly interpolated between observations.

== Parameters ==
The following files and parameters are used

=== param.in ===

;step_nu: This is the nudging data time step, the rate at which new data are introduced to the model. It should be a multiple of the model time step. Nudging is performed every time step, through the entire simulation. Between data time steps, data is linearly interpolated.

;vnh1, vnh2, vnf1, vnf2: These are parameters used to compose $w_z$ composing the relaxation weights. For a model location between the surface and depth of vnh1, vnf1 is used. Deeper than vnh1 but less than vnh2, the weight is interpolated between vnf1 and vnf2. At depths greater than vnh2, vnf2 is used.

=== x_nudge.gr3 ===
The gr3 files represent the horizontal relaxation weights associated with each model node. Sides are given a horizontal relaxation interpolated from their nodes. Note that the weights may contain estimates of data availability and quality as well as scaling considerations. Hence, the weights may be related to the analysis methods that are used to prepare data (salt_nu.in and temp_nu.in)

=== salt_nu.in and temp_nu.in ===
These files contain the actual data used for the nudging. Nudging data are given for all nodes, not the locations of observations, and the analysis of data is assumed precalculated. The analysis quality of locations (ie lower far from any good observations) would thus be handled by:
1. a low assignment in the horizontal weight, probably with finite support so there are many zeros in this file
2. an arbitrary value in salt_nu.in.

The fortran format for creating an xxx_nu.in file is illustrated by this code block:
<nowiki>
open(35,file='salt_nu.in',form='unformatted')
do istep=0,nsteps
write(35)istep*dt_nu ! time stamp in sec (starting from 0)
do inode=1,np ! all nodes
write(35)(saltout(jvert,inode),jvert=1,nvrt) ! all vertical layers
enddo
enddo
</nowiki

Now lets try it.

Salinity and temperature nudging

2013-02-12T16:56:51Z

Eli: Created page with "== Salt and Temperature Nudging in SELFE == Salt and temperature nudging is available by means of analysis nudging (Newtonian relaxation). The nudging allows the model state t..."

Main Page

2013-02-12T16:24:20Z

Eli:

The map below indicates the location of visitors to this site. Click on the map to see a larger view.
{|
|[http://www.revolvermaps.com/?target=enlarge&i=3r854vj4vdn&color=ff0000&m=0 http://rd.revolvermaps.com/h/m/a/0/ff0000/139/0/3r854vj4vdn.png]
|-
|}
 
 
Notice 
<OL>
<LI> The information on this wiki site are contributed by users and developers alike, and therefore the developers cannot guarantee all info is correct and up to date, although they are committed to patrolling the site regularly. Verify if necessary by sending a message to the SELFE mailing-list
<LI> The information on this wiki site is appropriate for MPI SELFE only; some info may be version sensitive, and so consult the files in your source code bundle for up-to-date info
<LI> Please consider contributing to any topic and suggest new topics of your interest. You first need to have an account created for you (we do not allow people to create accounts themselves to prevent spams). If you would like to contribute to the page please send an e-mail to [mailto:yjzhang@vims.edu Joseph Zhang], with some basic info: your ''real'' name and email address.
<LI> The links below that have content are in blue.
</OL>

----
* [[About SELFE]]
* [[SELFE news and announcements]]
* [[SELFE case studies]]

* [[Getting Started]]
** [[Downloading and compiling SELFE and utilities]]
** [[Navigating the source code bundle]]
** [[How to set up a model]]
** [[Examples]]
** [[SELFE registration and mailing list]]

*[[Beta version testing]]
* [[Online tutorials]]
* [[Test cases and benchmarks]]

* [[Model documentation]]
** [http://ccrm.vims.edu/yinglong/wiki_files/MPI_developers_notes.pdf Developer's notes on the code]
** [[Barotropic module]]
** [http://ccrm.vims.edu/yinglong/wiki_files/transport.pdf Scalar Transport module]
** [[Windwave module]]
** [[Sediment Transport module]]
** [[Ecological modules]]
** [[Oil spill module]]

* [[Special topics]]
** [[ACE tools]]
** [[Mesh generation]]
** [[Updating a simulation after changing an existing mesh]]
** [[Convergence study with SELFE]]
** [[Tides]]
** [[Salinity and temperature nudging]]
** [[Harmonic analysis]]
** [[Spatial and temporal discretization]]
** [[Explicit vs. implicit calculation]]
** [[Hydrostatic vs. non-hydrostatic calculation]]
** [http://ccrm.vims.edu/yinglong/wiki_files/Report-ChezyFlow-Sept2011.pdf Bottom boundary layer formulation in SELFE]
** [[Simulating wetting and drying with SELFE]]
** [[Baroclinic vs. barotropic mode]]
** [[Salt intrusion study with SELFE]]
** [[2D vs. 3D mode]]
** [[Atmospheric forcing]]

* [[User manual]]
** [[Hydrodynamics]]
** [[Scalar Transport]]
** [[Sediment Transport]]
** [[Windwave]]
** [[Ecology]]

* [[Output formats and postprocessing]]
** [[Parallel output: time and processor blocks]]
** [[Visualization]]
** [[Harmonic analysis]]
** [[One way nesting]]

* [[Sharing your tools]]

* [[SELFE FAQ]]

* [http://www.stccmop.org/CORIE/modeling/elcirc/elcircjour.html References]

== Getting started ==
* Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [//www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [//www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Main Page

2012-10-23T17:10:11Z

Eli:

The map below indicates the location of visitors to this site. Click on the map to see a larger view.
{|
|[http://www.revolvermaps.com/?target=enlarge&i=3r854vj4vdn&color=ff0000&m=0 http://rd.revolvermaps.com/h/m/a/0/ff0000/139/0/3r854vj4vdn.png]
|-
|}
 

Notice 
<OL>
<LI> The information on this wiki site are contributed by users and developers alike, and therefore the developers cannot guarantee all info is correct and up to date, although they are committed to patrolling the site regularly. Verify if necessary by sending a message to the SELFE mailing-list
<LI> The information on this wiki site is appropriate for MPI SELFE only; some info may be version sensitive, and so consult the files in your source code bundle for up-to-date info
<LI> Please consider contribute to any topic and suggest new topics of your interest. You need to register yourself first at this site. For inquiries, email yjzhang@vims.edu
<LI> The links below that have content are in blue.
</OL>

----
* [[About SELFE]]
* [[SELFE news and announcements]]
* [[SELFE case studies]]

* [[Getting Started]]
** [[Downloading and compiling SELFE and utilities]]
** [[Navigating the source code bundle]]
** [[How to set up a model]]
** [[Examples]]
** [[SELFE registration and mailing list]]

*[[Beta version testing]]
* [[Online tutorials]]
* [[Test cases and benchmarks]]

* [[Model documentation]]
** [http://ccrm.vims.edu/yinglong/wiki_files/MPI_developers_notes.pdf Developer's notes on the code]
** [[Barotropic module]]
** [http://ccrm.vims.edu/yinglong/wiki_files/transport.pdf Scalar Transport module]
** [[Windwave module]]
** [[Sediment Transport module]]
** [[Ecological modules]]
** [[Oil spill module]]

* [[Special topics]]
** [[ACE tools]]
** [[Mesh generation]]
** [[Updating a simulation after changing an existing mesh]]
** [[Convergence study with SELFE]]
** [[Tides]]
** [[Salinity initialization and nudging]]
** [[Harmonic analysis]]
** [[Spatial and temporal discretization]]
** [[Explicit vs. implicit calculation]]
** [[Hydrostatic vs. non-hydrostatic calculation]]
** [http://ccrm.vims.edu/yinglong/wiki_files/Report-ChezyFlow-Sept2011.pdf Bottom boundary layer formulation in SELFE]
** [[Baroclinic vs. barotropic mode]]
** [[Salt intrusion study with SELFE]]
** [[2D vs. 3D mode]]
** [[Atmospheric forcing]]

* [[User manual]]
** [[Hydrodynamics]]
** [[Scalar Transport]]
** [[Sediment Transport]]
** [[Windwave]]
** [[Ecology]]

* [[Output formats and postprocessing]]
** [[Parallel output: time and processor blocks]]
** [[Visualization]]
** [[Harmonic analysis]]
** [[One way nesting]]

* [[Sharing your tools]]

* [[SELFE FAQ]]

* [http://www.stccmop.org/CORIE/modeling/elcirc/elcircjour.html References]

== Getting started ==
* Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [//www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [//www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Baroclinic vs. barotropic mode

2012-08-27T17:08:32Z

Eli:

== Mode descriptions ==
Some description of the Baroclinic and Barotropic equations is given in the SELFE paper. A little elaboration will convey how these are implemented and used in practice.

The baroclinic and barotropic modes are toggled in the model by means of the parameter ***. They differ in that in Baroclinic mode, the contribution of salinity-induced density differences is included in the momentum equations. In contrast, in Barotropic mode salt and temperature are (at most) considered passive tracers.

In barotropic mode:
* You can choose whether to calculate salt and temperature transport by toggling the ''itracer'' parameter in the ''param.in'' file.
* This choice affects performance (see below) and also data requirements for salt and temperature. The model (****is/isn't smart) about ...
* The contribution of density to horizontal pressure gradients is dropped.
* The turbulence closure is still calculated in 3D, but the supression of turbulence due to stratification is not included.

== Performance considerations ==
Barotropic mode calculation can be a lot faster than baroclinic. A key speedup is achieved by setting ''itracer=0'' and neglecting salt and temperature entirely, which is particularly common in the case that subcycling of transport is a performance limiter.

== Boundary and well-posedness issues ==

== Sequential barotropic-baroclinic analysis ==
One common usage pattern is to use a sequence of barotropic-baroclinic model runs. The barotropic simulation is used in a preliminary sweep in order to calculate 3D boundary conditions for the subsequent baroclinic analysis. Typically this is done with transport off, maximizing speed for the barotropic step.

Baroclinic vs. barotropic mode

2012-08-27T17:07:29Z

Eli: Created page with " == Mode descriptions == Some description of the Baroclinic and Barotropic equations is given in the SELFE paper. A little elaboration will convey how these are implemented an..."

== Mode descriptions ==
Some description of the Baroclinic and Barotropic equations is given in the SELFE paper. A little elaboration will convey how these are implemented and used in practice.

The Baroclinic and Barotropic modes are toggled in the model by means of the parameter ***. They differ in that in Baroclinic mode, the contribution of salinity-induced density differences is included in the momentum equations. In contrast, in Barotropic mode salt and temperature are (at most) considered passive tracers.

In barotropic mode:
* You can choose whether to calculate salt and temperature transport by toggling the ''itracer'' parameter in the ''param.in'' file.
* This choice affects performance (see below) and also data requirements for salt and temperature. The model (****is/isn't smart) about ...
* The contribution of density to horizontal pressure gradients is dropped.
* The turbulence closure is still calculated in 3D, but the supression of turbulence due to stratification is not included.

== Performance considerations ==
Barotropic mode calculation can be a lot faster than Baroclinic. A key speedup is achieved by setting ''itracer=0'' and neglecting salt and temperature entirely, which is particularly common in the case that subcycling of transport is a performance limiter.

== Boundary and well-posedness issues ==

== Sequential barotropic-baroclinic analysis ==
One common usage pattern is to use a sequence of barotropic-baroclinic model runs. The barotropic simulation is used in a preliminary sweep in order to calculate 3D boundary conditions for the subsequent baroclinic analysis. Typically this is done with transport off, maximizing speed for the barotropic step.

Parallel output: time and processor blocks

2012-08-27T17:05:54Z

Eli: Created page with "SELFE binary state output is emitted in a directory called /outputs. This directory must exist or you will get an immediate warning from the model. Depending on your MPI confi..."

SELFE binary state output is emitted in a directory called /outputs. This directory must exist or you will get an immediate warning from the model. Depending on your MPI configuration, the /outputs directory may exist in a central location (this is more common) or each processor may have an instance in which case you need to collect together the contents into a central location.

An example file name is 9_0000_elev.61. More generally, the file name is:
[time_block]_[processor_no]_[variable_name].[fortran_unit]

; Variable name
The variable name is transparent and covered in the documentation.

; Time block
The time blocks start from 1 and are sequential. The model buffers and writes data occasionally. Every ihfskip time steps it opens a new time block. For instance, if the time step is 120 seconds and ihfskip = 10080 each block will be 14 days long.
# "Neat" time lengths that will make meaningful analysis (e.g. 14 days) are usually easiest later when you postprocess.
# Some of the output post-processing scripts will run a lot better if the length of your simulation is an even multiple of ihfskip. This can be done by altering ihfskip or the simulation length -- at the risk of lengthening the simulation a bit, the latter often produces a neater result.
# If your simulation length is not an even multiple of the time block length, the last time block will be truncated on the last block. This will cause some minor errors and warnings in the post-processing tools. In addition, if you then restart the run it is best to repeat and overwrite the truncated block -- the post-processing tools do not work well with blocks that grow and shrink in the middle of the run.
# Even if the output blocks match the end of the simulation very neatly, the model (at the time of writing) will open a new block that will be unused. This is odd but harmless.

; Processor number
The mpi_processor number starts at 0 and represents the mpi processor id from the task that wrote the output. If your processor writes to a shared directory, the files for different processors will be collocated, but since clusters are not always set up the same way and each process is writing locally this isn't always the case. The per-processor outputs are usually gathered into a global binary. The scripts that do this are called combine_output*. Once you are done, you will have a binary file called something like 9_elev.61. The time block and the variable name remain. There is no utility for gathering the outputs in time, instead most post-processing tools are able to work with multiple files.

CMake Build System

2012-08-27T17:02:43Z

Eli: Created page with " == Introduction == CMake is one option currently available for building SELFE. This documentation covers the SELFE cmake build system under Linux. While CMake is highly ..."

== Introduction ==
CMake is one option currently available for building SELFE. This documentation covers the SELFE cmake build system under Linux. While CMake is highly portable and probably could be made to work under Windows and Mac, no one has tested it under those operating systems. For more information on cmake and documentation, see the [http://www.cmake.org cmake] web site.

== User Documentation ==

=== Basic CMake Usage ===
On Linux, Cmake is just a preprocessor for Make much like a typical ''configure'' script. There are also generators for Eclipse and some other native build systems including Windows and Mac. When you reconfigure the project a lot by swapping modules, compiler options, build type (debug/release) or changing compilers, you re-run cmake ... but most of the time you just use ''make'' or some other build tool. You can create an out-of-source build from the /selfe directory by doing the following:
> mkdir build
> cd build
> setenv FC ifort # Might be shell-dependent. The default (no action needed) is gfortran
> cmake ../src
> make -j8

If you have the prerequisites in typical places or set up your environment as recommended below this sequence will produce a Hydro-only build with default options including the selfe executable and all utilities. More realistically, you will probably have to set some library locations. Configuration is considered in more detail below.

In this case CMake is really just building a Makefile. The Makefile that gets produced has the following targets:
* all (default)
* individual libraries: sediment, ecosim, wwm (assuming you configured CMAKE with USE_XXX)
* pelfe (with whatever features you toggled on)
* utility (all utility scripts)
* pyutil (all python utilities)
* install (installs the system to the "usual" spots /usr/bin etc. The install location is configurable and respects DESTDIR. See cmake docs.

The Makefile is robust if you make source file changes, and can manage complex Fortran module dependencies. If you add a file or alter the project you will have to re-run Cmake so that the new addition gets included. CMake does this well and you can run it with the very simple 'cmake ../src' command. The Makefile scales very well to 8 threads.

There are cases where you should make clean and rebuild all the source. If you toggle compiler define options (-D), you are effectively changing the source code that reaches the compiler net of the preprocessor, yet not actually touching the text of the source file. The GNU Makefile system does not recognize such a change. There is a best practice for making sure that configuration changes are source changes -- configuration "include files" -- but we are not there yet. '''If you change #definitions, make clean'''.

If you change the library or compiler options -- or run into problems -- you should consider blowing away the whole /build directory and starting over:
selfe$ rm -rf build/*
selfe$ cd build
selfe$ cmake ../src

=== SELFE Prerequisites ===
To build the model, you will need the following libraries:
;CMake: The build system is tested against version 2.6 and 2.8
;Parmetis: Domain decomposition and sparse matrix ordering library
* Required for Hydro.
* Included in distro.
* If you build the included one, linking is automatic.
* You can also set the environment PARMETIS_DIR to locate another build.
* Location can also be given by a full path in configuration. See below.
;GOTM: Optional turbulence closure for Hydro.
* Included in distro.
* If you build the included one, linking is automatic.
* You can also set the environment GOTM_DIR to locate another build
* Location can also be hard coded in configuration. See below.
;NetCDF: File format library for Hydro.
* Assumed to be installed separately
* If you set the environment variable NETCDF_DIR (all caps) or put it in /usr/lib /usr/include detection is automatic.
* Location can also be hard coded in configuration. See below.
;HDF5: Parallel backend for some NetCDF 4 (parallel) builds. CMake will tell you if it is needed.
* If you set HDF5_DIR environment variable or put it in usr/lib usr/include, detection automatic.
* Location can also be hard coded in configuration. See below.
;PETSc: Numerical algorithm library required for the Wind-wave module.
* If you set PETSC_DIR environment variable or put it in usr/lib usr/include, detection automatic.
* Location can also be hard coded in configuration. See below.
;MPI: Message passing library used for parallel processing
* MPI wrappers (mpif90) are needed to locate the MPI tools and dependencies (but are not used for the build)

If you use a Linux "environment module" system, the XXX_DIR etc may be automatically set (just watch out for case). Alternatively, the libraries should be found if they are in system lib and include directories as well (e.g. /usr/lib). Finally, XXX_DIR is not the only environment variable that can be used as a hint to cmake. You can also set up pointers to the libraries and includes individually. See the file FindNetCDF.cmake for examples ... but the easiest way is just NetCDF_DIR.

=== Configuration ===
==== Examples of things you will want to configure====
* custom compiler flags (but see below!!!!)
* the name of the compiler
* custom library locations,
* choosing selfe modules to include in the driver
* performance/build parameters (BUILD_TYPE=Debug, MPIVERSION=2, USE_TIMING)

'''Custom compiler flags''': Flag choices are often re-usable across similar systems. If you are setting up flags that should be the standard for your architecture, I would urge you to contribute to selfe/cmake/SELFECompile.cmake so that others can make use of your work and so that your personal configuration is not mixed up with stuff that is just standard for your architecture. If you are tweaking the flags for real then you should follow the directions below.

One class of flags that seems to be a bit of a special case are the flags that force static linking such as '''-Bstatic''' or '''-static'''. I am pretty open to fixing the cmake files so that they will do what you want, but rather than instinctively adding these flags you should investigate first whether maybe CMake already will do what you want ... it generally favors static linking, although MPI can be an exception.

The '''compiler''' can be identified with the '''FC''' environmental variable or the CMAKE_Fortran_COMPILER variable -- case sensitive. Almost everyone seems to do it using the environent, and if you are using the linux [http://linux.die.net/man/1/module module system].

==== Options for configuring CMake ====
Please do not edit the CMakeLists.txt file to add your own directories and configuration info. User-specific data does not belong in CMakeLists.txt. There are two ways to get user selections and variables into CMake, which are not mutually exclusive:

===== METHOD #1: Use the -D option and a shell/batch file =====

The CMake -D option forcibly defines a variable. It might be more immediately intuitive for GNU make users who set a variable
and expect their orders to be followed. To use the -D method, create a shell script in /selfe that looks like this:
mkdir build
cd build
cmake -DUSE_ECO=1 \
-DMPIVERSION=1 \
...
make
cd ..

The only unintuitive part is that you need an argument for all the variables (ON/TRUE/1 all work for turning something on).

===== METHOD #2 Use -C <cache-init-file> to populate the cmake cache. =====
The notion of the CMake cache takes some getting used to. The first time you run cmake, a number of compiler and build options will be placed in a file called CMakeCache.txt. The -C option allows you to specify an input cmake script that has nothing but SET statements that the user can use to populate options ... an example of such a file is /selfe/cmake/SELFE.local.cmake

After the first run, the cache can be manipulated with text, cursor or graphical tools (ccmake or QT based) or by repeating the cmake invocation with new -D options. I don't use the graphical tools much, but ccmake in non-advanced view is nice because it shows you an all-encompassing view of user-configurable variables.

Now here is the funny thing about SET (whether in your <init-cache> file or in the build system): once the cache is initialized, any variable that SETs the value of a cached variable will no longer be evaluated unless the FORCE tag is used. As a consequence the -C <init-file> will not be influential ever again unless
# you use FORCE in your SET statements or
# you blow away the cache and rebuild it.

My experience is that if you are making a single well-managed change like turning on Sediment, then this persistence is actually nice because you can set one change (perhaps -DUSE_SEDIMENT=1) and not worry about the rest of your setup falling apart. When you toggle multiple options it is often safer to blow away the whole build directory and start again with CMake and a <cache-init> file:
$ rm -rf build
$ cd build
$ cmake -C ../cmake/SELFE.local.cmake ../src

== Developer Documentation ==
In contrast to users, developers will use the CMakeLists.txt in /src and its subdirectories. I'll keep this short, because most folks will learn by mimicking examples anyway and there is documentation at [http://www.cmake.org|cmake].

Here are common use cases:
=== Modifying SELFE modules ===
Here are some common cases:
==== Adding a file to an existing module ====
Just add the name of the file to the pre-existing list in CMakeLists.txt.
==== Adding an algorithmic option to an existing module. ====
Please do this at the module directory (not /src) level CMakeLists.txt. You may need the following components to create your addition:
# either the OPTION cmake command or the SET command. OPTION is an easy way to set up boolean options, SET is used for boolean, strings, paths. If your option is to be user configurable, the SET call has include the CACHE keyword.
# to pass the option to the compiler using the cmake add_definitions. Good examples to follow include MPIVERSION, USE_TIMER
# you may want code it so that an environment variable is passed on to the system. See MPI_VERSION.

==== Adding a utility module or file ====
If you are creating a new directory, you will need to add_directory() in the /utility level CMakeLists.txt. The rest happens at the directory level of the script. Make sure to create a dependency of "utility" on your new script so that "make utility" works correctly.

==== Adding a new selfe module ====
Again, learning by example is a good way to tackle this. There is a macro for CMakeLists.txt in the /src level CMakeLists.txt. It will help you bind together:
# a directory name (usually capitalized)
# a USE_XXX variable and
# a (lower case) library name.
# creation of a dependency of the main driver on your module
# cause cmake to recurse into your directory and configure it IF the USE_XXX option is enabled

That should be all you need at the /src CMakeLists.txt level. After that, you just add a subdirectory for the module under /src, add the source files and a CMakeLists.txt and copy the style of CMakeLists.txt from an existing module such as /EcoSim or /Sediment. This will create a library and estabish dependencies. In general, you want to depend on the /Core library but not on any of the other modules.

=== Library dependencies ===
First one obvious caveat -- extra libraries should be avoided if possible.

Dependencies should also be introduced to cmake at the lowest level they are needed. You can introduce the dependency in the /src level CMakeLists.txt if it is going to be used by several modules including Hydro (e.g. NetCDF). However, if it is only going to be used by one module for the moment, (as PETSc is needed by WWM) try to keep it in the module directory. Among other things, you then do not have to put an IF block around it to check if the selfe module is being used because the whole directory will be skipped if the module is toggled off. Someone who isn't using your module can skip the dependency entirely.

The first step with dependent libraries is to get a FindXXX.cmake script for the library if one is not already included in CMake 2.6 and put it in selfe/cmake/modules. You may be tempted to avoid this and try to figure another way, but a suitable script is almost always available on the web and I have found that subverting this feature of CMake makes it fragile. There are some slight tricks making it compatible with cmake 2.6 (specifically the way you include other scripts). The names of the scripts that are included are usually always about the same, so you can probably just look at a script that is already in selfe/cmake/modules. If you have any issues feel free to email me (eli@water.ca.gov).

Downloading and compiling SELFE and utilities

2012-08-27T17:01:06Z

Eli: Created page with "You can download SELFE from the CORIE [http://www.stccmop.org/CORIE/modeling/selfe/ home page] There are currently several build systems being used to build SELFE, including ..."

You can download SELFE from the CORIE [http://www.stccmop.org/CORIE/modeling/selfe/ home page]

There are currently several build systems being used to build SELFE, including GNU Make and CMake. The traditional GNU Makefiles are documented internally, but are not particularly powerful.

[[CMake Build System]]

Main Page

2012-08-27T17:00:24Z

Eli:

== SELFE ==
... please change this organization where ever it does not fit your needs!!

* [[Getting Started]]
** [[Downloading and compiling SELFE and utilities]]
** [[How to set up a model]]
** [[Examples]]

* [[Model documentation]]
** [[Hydrodynamics module]]
** [[Scalar Transport module]]
** [[Windwave module]]
** [[Sediment Transport module]]

* [[Special topics]]
** [[Tidal boundary]]
** [[Mesh creation]]
** [[Salinity initialization and nudging]]
** [[Harmonic analysis]]
** [[Spatial and temporal discretization]]
** [[Explicit vs. implicit calculation]]
** [[Hydrostatic vs. non-hydrostatic calculation]]
** [[Baroclinic vs. barotropic mode]]
** [[2D vs. 3D mode]]

* [[User manual]]
** [[Hydrodynamics]]
** [[Scalar Transport]]
** [[Sediment Transport]]
** [[Windwave]]

* [[Case studies and links]]

* [[Output formats and postprocessing]]
** [[Parallel output: time and processor blocks]]
** [[Visualization]]
** [[Harmonic analysis]]
** [[One way nesting]]

* [[References]]

== Getting started ==
* Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [//www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [//www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]