Now that the DART code has been downloaded and the prerequisites have been verified, you can now begin building and verifying the DART installation.
Customizing the build scripts — overview¶
DART executable programs are constructed using two tools: mkmf, and
make. The make utility is a very commonly used tool that requires a
user-defined input file (a
Makefile) that records dependencies
between different source files. make then performs actions to the
source hierarchy, in order of dependence, when one or more of the source
files is modified. mkmf is a perl script that generates a make
input file (named Makefile) and an example namelist
input.nml.<program>_default with default values.
mkmf (think “make makefile”) requires two separate input files. The first is a template file which specifies the commands required for a specific Fortran90 compiler and may also contain pointers to directories containing pre- compiled utilities required by the DART system. This template file will need to be modified to reflect your system as detailed in the next section.
The second input file is a
path_names file which is supplied by DART
and can be used without modification. An mkmf command is executed
which uses the
path_names file and the mkmf template file to produce
Makefile which is subsequently used by the standard make
Shell scripts that execute the mkmf command for all standard DART executables are provided with the standard DART distribution. For more information on the mkmf tool please see the mkmf documentation.
Building and Customizing the ‘mkmf.template’ file¶
A series of templates for different compilers/architectures can be found
DART/build_templates directory and have names with
extensions that identify the compiler, the architecture, or both. This
is how you inform the build process of the specifics of your system.
Our intent is that you copy one that is similar to your system into
DART/build_templates/mkmf.template and customize it.
For the discussion that follows, knowledge of the contents of one of these
is needed. Note that only the LAST lines of the file are shown here. The
first portion of the file is a large comment block that provides
valuable advice on how to customize the mkmf template file if needed.
MPIFC = mpif90 MPILD = mpif90 FC = ifort LD = ifort NETCDF = /usr/local INCS = -I$(NETCDF)/include LIBS = -L$(NETCDF)/lib -lnetcdf -lnetcdff FFLAGS = -O2 $(INCS) LDFLAGS = $(FFLAGS) $(LIBS)
the Fortran compiler
the name of the loader; typically, the same as the Fortran compiler
the MPI Fortran compiler; see the DART MPI introduction for more info
the MPI loader; see the DART MPI introduction for more info
the location of your root netCDF installation, which is assumed to contain netcdf.mod and typesizes.mod in the include subdirectory. Note that the value of the NETCDF variable will be used by the “INCS” and “LIBS” variables.
the includes passed to the compiler during compilation. Note you may need to change this if your netCDF includes netcdf.mod and typesizes.mod are not in the standard location under the include subdirectory of NETCDF.
the libraries passed to “FC” (or “MPIFC”) during compilation. Note you may need to change this if the netCDF libraries libnetcdf and libnetcdff are not in the standard location under the “lib” subdirectory of NETCDF.
the Fortran flags passed to “FC” (or “MPIFC”) during compilation. There are often flags used for optimized code versus debugging code. See your particular compiler’s documentation for more information.
the linker flags passed to LD during compilation. See your particular linker’s documentation for more information.
Customizing the path names files¶
path_names_* files are provided in the “work” directory for
each specific model. In this case, the directory of interest is
DART/models/lorenz_63/work (see the next section). Since each
model comes with its own set of files, the
typically need no customization. However, modifying these files will be
required if you wish to add your model to DART. See How do I run DART
with my model? for more information.
Building the Lorenz_63 DART project¶
In order to get started with DART, here we use the Lorenz 63 model, which is a simple ODE model with only three variables. DART supports models with many orders of magnitude more variables than three, but if you can compile and run the DART code for any ONE of the models, you should be able to compile and run DART for ANY of the models. For time-dependent filtering known as cycling, where observations are iteratively assimilated at multiple time steps, DART requires the ability to move the model state forward in time. For low-order models, this may be possible with a Fortran function call, but for higher-order models, this is typically done outside of DART’s execution control. However, the assimilation itself is conducted the same way for all models. For this reason, here we focus solely on the Lorenz 63 model. If so desired, see The Lorenz 63 model: what is it and why should we care? for more information on this simple yet surprisingly relevant model. See A high-level workflow of DA in DART for further information regarding the DART workflow if you prefer to do so before building the code.
There are seven separate, stand-alone programs that are typically
necessary for the end-to-end execution of a DART experiment; see below
or the What is DART? section for more information on
these programs and their interactions. All DART programs are compiled
the same way, and each model directory has a directory called
that has the components necessary to build the executables.
some higher-order models have many more than seven programs; for example, the Weather Research and Forecasting (WRF) model, which is run operationally around the world to predict regional weather, has 28 separate programs. Nonetheless, each of these programs are built the same way.
quickbuild.csh in each directory builds all seven programs
necessary for Lorenz 63. Describing what the
does is useful for understanding how to get started with DART.
The following shell commands show how to build two of these seven
programs for the lorenz_63 model: preprocess and obs_diag.
preprocess is a special program that needs to be built and run to
automatically generate Fortran code that is used by DART to support a
subset of observations - which are (potentially) different for every
model. Once preprocess has been run and the required Fortran code has
been generated, any of the other DART programs may be built in the same
way as obs_diag in this example. Thus, the following runs mkmf to
Makefile for preprocess, makes the preprocess program,
runs preprocess to generate the Fortran observation code, runs mkmf
to make a
Makefile for obs_diag, then makes the obs_diag
$ cd DART/models/lorenz_63/work $ ./mkmf_preprocess $ make $ ./preprocess $ ./mkmf_obs_diag $ make
The remaining executables are built in the same fashion as obs_diag: run the particular mkmf script to generate a Makefile, then execute make to build the corresponding program.
Currently, DART executables are built in a
work subdirectory under
the directory containing code for the given model. The Lorenz_63 model
mkmf_xxxxxx files for the following programs:
creates custom source code for just the observations of interest
specify a (set) of observation characteristics taken by a particular (set of) instruments
specify the temporal attributes of the observation sets
spinup and generate “true state” for synthetic observation experiments
perform data assimilation analysis
creates observation-space diagnostic files in netCDF format to support visualization and quantification.
manipulates observation sequence files. This tool is not generally required (particularly for low-order models) but can be used to combine observation sequences or convert from ASCII to binary or vice-versa. Since this is a rather specialized routine, we will not cover its use further in this document.
As mentioned above,
quickbuild.csh is a script that will build every
executable in the directory. There is an optional argument that will
additionally build the MPI-enabled versions which will not be covered in
this set of instructions. See The DART MPI introduction page for more
information on using DART with MPI.
quickbuild.csh will compile all the executables mentioned
above for the lorenz_63 model:
$ cd DART/models/lorenz_63/work $ ./quickbuild.csh
The result (hopefully) is that seven executables now reside in your work directory.
The most common problem is that the netCDF libraries and/or include
files were not found in the specified location(s). The second most
common problem is that the netCDF libraries were built with a
different compiler than the one used for DART. Find (or compile) a
compatible netCDF library, edit the
to point to the correct locations of the includes and library files,
Makefiles, and try again.