[Dart-dev] [6334] DART/trunk: move the DART/doc/mpi directory to mpi_utilities/test
nancy at ucar.edu
nancy at ucar.edu
Tue Jul 30 14:21:13 MDT 2013
Revision: 6334
Author: nancy
Date: 2013-07-30 14:21:13 -0600 (Tue, 30 Jul 2013)
Log Message:
-----------
move the DART/doc/mpi directory to mpi_utilities/test
because it only contains test programs for common
problems with mpi installations.
remove a lot of obsolete files from the doc directory.
move some of the original design documents into a 'design'
directory which will probably be removed after review.
move the files which help generate html pages from the
source code into a 'boilerplate' directory.
remove framemaker source because we no longer have
framemaker available on any platform. the pdf files
remain and it may be possible to extract content from them.
copy over a few of the image files from the html dir
to the images dir; the rest should follow after the html
pages that reference them have been updated.
Added Paths:
-----------
DART/trunk/doc/html/README
DART/trunk/doc/html/boilerplate/
DART/trunk/doc/html/boilerplate/boilerplate.html
DART/trunk/doc/html/boilerplate/html_function.f90
DART/trunk/doc/html/boilerplate/html_namelist.f90
DART/trunk/doc/html/boilerplate/html_subroutine.f90
DART/trunk/doc/html/boilerplate/template.html
DART/trunk/doc/html/design/
DART/trunk/doc/html/design/calling_sequence.pdf
DART/trunk/doc/html/design/obs_set_specification.pdf
DART/trunk/doc/html/design/task_schedule.pdf
DART/trunk/doc/html/design/userViews1to6.png
DART/trunk/doc/html/design/users_guide_overview.pdf
DART/trunk/doc/images/Dartboard7.png
DART/trunk/doc/images/dart.ico
DART/trunk/mpi_utilities/tests/
Removed Paths:
-------------
DART/trunk/doc/html/Fiji_release.html
DART/trunk/doc/html/Guam_release.html
DART/trunk/doc/html/I_diffs_from_workshop.html
DART/trunk/doc/html/Iceland_release.html
DART/trunk/doc/html/Jamaica_diffs_from_I.html
DART/trunk/doc/html/Jamaica_release.html
DART/trunk/doc/html/PostI_diffs_from_I.html
DART/trunk/doc/html/Post_Iceland_release.html
DART/trunk/doc/html/boilerplate.html
DART/trunk/doc/html/calling_sequence.pdf
DART/trunk/doc/html/gui_notes.fm
DART/trunk/doc/html/hawaii_release.html
DART/trunk/doc/html/html_function.f90
DART/trunk/doc/html/html_namelist.f90
DART/trunk/doc/html/html_subroutine.f90
DART/trunk/doc/html/obs_set_specification.fm
DART/trunk/doc/html/obs_set_specification.pdf
DART/trunk/doc/html/pre_guam_release.html
DART/trunk/doc/html/pre_hawaii_release.html
DART/trunk/doc/html/pre_j_release.html
DART/trunk/doc/html/task_schedule.fm
DART/trunk/doc/html/task_schedule.pdf
DART/trunk/doc/html/template.html
DART/trunk/doc/html/userViews1to6.png
DART/trunk/doc/html/users_guide_overview.fm
DART/trunk/doc/html/users_guide_overview.pdf
DART/trunk/doc/mpi/
DART/trunk/doc/pre_h_diffs_from_guam
DART/trunk/doc/preh_to_h_diffs
-------------- next part --------------
Deleted: DART/trunk/doc/html/Fiji_release.html
===================================================================
--- DART/trunk/doc/html/Fiji_release.html 2013-07-30 20:17:26 UTC (rev 6333)
+++ DART/trunk/doc/html/Fiji_release.html 2013-07-30 20:21:13 UTC (rev 6334)
@@ -1,1470 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
-<HTML>
-<HEAD>
-<TITLE>DART "fiji release" Documentation</TITLE>
-<link rel="stylesheet" type="text/css" href="doc.css">
-</HEAD>
-<BODY>
-<A NAME="TOP"></A>
-
-<center>
-<A HREF="#Legalese">TERMS OF USE</A>
-<br>
-<br>
-<img src = "Dartboard7.png" alt="cool DART logo">
-</center>
-
-<!--==================================================================-->
-
-<H1>DART "fiji release" Documentation</H1>
-<!-- version tag follows, do not edit --><P>$Id$</P>
-
-<!--==================================================================-->
-
-<A NAME="OVERVIEW"></A>
-<H1>Overview of DART</H1>
-
-<P>The Data Assimilation Research Testbed (DART) is designed to
-facilitate the combination of assimilation algorithms, models,
-and observation sets to allow increased understanding of all three.
-The DART programs have been compiled with the Intel 7.1 Fortran compiler
-and run on a linux compute-server. If your system is different, you will
-definitely need to read the
-<A HREF="#customizations">Customizations</A> section.
-</P>
-
-<P>DART programs can require three different types of input.
-First, some of the DART programs, those for creating synthetic
-observational datasets, require interactive input from the keyboard.
-For simple cases, this interactive input can be made directly
-from the keyboard. In more complicated cases, a file containing
-the appropriate keyboard input can be created and this file
-can be directed to the standard input of the DART program.
-Second, many DART programs expect one or more input files in
-DART specific formats to be available. For instance,
-<em class=program>perfect_model_obs</em> creates a synthetic
-observation set given a particular model and a description
-of a sequence of observations requires an input file that
-describes this observation sequence.
-At present, the observation files for DART are inefficient but
-human-readable ascii files in a custom format. Third, many DART
-modules (including main programs) make use of the Fortan90
-namelist facility to obtain values of certain parameters
-at run-time. All programs look for a namelist input file
-called <em class=file>input.nml</em> in the directory in which
-the program is executed. The <em class=file>input.nml</em>
-file can contain a sequence of individual Fortran90 namelists
-which specify values of particular parameters for modules that
-compose the executable program.
-Unfortunately, the Fortran90 namelist interface
-is poorly defined in the language standard, leaving
-considerable leeway to compiler developers in implementing the
-facility. The Intel 7.1 compiler has some particularly unpleasant
-behavior when a namelist file contains an entry that is NOT defined
-in the program reading the namelist.
-Error behavior is unpredictable, but often results in read
-errors for other input files opened by DART programs.
-If you encounter run-time read errors, the first course of action
-should be to ensure the components of the namelist are actual components.
-Changing the names of the namelist components <strong>will</strong>
-create unpleasantries. DART provides a mechanism that automatically
-generates namelists with the default values for each program to be run.
-</P>
-
-<P>
-DART uses the
-<A HREF="http://www.unidata.ucar.edu/packages/netcdf/">netCDF</A>
-self-describing data format with a particular metadata convention to
-describe output that is used to analyze the results of assimilation
-experiments. These files have the extension <em class=file>.nc</em>
-and can be read by a number of standard data analysis tools.
-A set of <A HREF="http://www.mathworks.com/">Matlab</A>
-scripts, designed to produce graphical diagnostics from DART netCDF
-output files are available.
-DART users have also used <A HREF="http://meteora.ucsd.edu/~pierce/ncview_home_page.html">ncview</A>
-to create rudimentary graphical displays of output data fields.
-The <A HREF="http://nco.sourceforge.net">NCO</A> tools, produced by
-UCAR's Unidata group, are available to do operations like
-concatenating, slicing, and dicing of netCDF files.
-</P>
-
-<!--==================================================================-->
-
-<H2 class=indent1>Document conventions</H2>
-<P>
-Anything underlined is a URL.
-<br>
-<br>
-<em class=file>All filenames look like this -- (typewriter font, green)</em>.<BR>
-<em class=program>Program names look like this -- (italicized font, green)</em>.<BR>
-<em class=input>user input looks like this -- (bold, magenta)</em>.
-</P>
-<div class=unix>
-commands to be typed at the command line are contained in an
-indented gray box.
-</div>
-<P>
-And the contents of a file are enclosed in a box with a border:
-</P>
-<div class=routine>
-&hypothetical_nml<BR>
- obs_seq_in_file_name = "obs_seq.in",<BR>
- obs_seq_out_file_name = "obs_seq.out",<BR>
- init_time_days = 0,<BR>
- init_time_seconds = 0,<BR>
- output_interval = 1<BR>
-&end</div>
-
-<!--==================================================================-->
-
-<A NAME="Installation"></A>
-<HR>
-<H1>Installation</H1>
-
-<P>
-This document outlines the installation of the DART software
-and the system requirements. For convenience, some of the original
-colloquium exercises are repeated here, mostly just to check the
-installation. A few of the
-<A HREF="dart_exercise_doc.pdf">exercises from the ASP summer 2003 Colloquium</A>
-are repeated here, primarily to serve as the verification of the installation.
-The entire installation process is summarized in
-the following steps:
-</P>
-
-<OL><LI><A HREF="#compilers">Determine which F90 compiler is available</A>.</LI>
- <LI><A HREF="#netCDFlib">Determine the location of the
- <em class=code>netCDF</em> library</A>.</LI>
- <LI><A HREF="#udunits">Determine the location of the
- <em class=code>udunits</em> library</A>.</LI>
- <LI><A HREF="#download">Download the DART software bundle and untar it
- into the expected source tree</A>.</LI>
- <LI><A HREF="#customizations">Modify certain DART files to reflect
- the available F90 compiler and location of the
- appropriate libraries</A>.</LI>
- <LI><A HREF="#building">Build the executables</A>.</LI>
-</OL>
-
-<P>
-We have tried to make the code as portable as possible, but we
-do not have access to all compilers on all platforms, so there are no
-guarantees. We are interested in your experience building the system,
-so please email me (Tim Hoar) thoar 'at' ucar 'dot' edu
-(trying to cut down on the spam).
-</P>
-
-<P>
-After the installation, you might want to peruse the following.
-</P>
-
-<UL><LI><A HREF="#Running">Running the Lorenz_63 Model</A>.</LI>
- <LI><A HREF="#matlab">Using the Matlab diagnostic scripts</A>.</LI>
- <LI>A short discussion on
- <A HREF="#discussion">bias, filter divergence and covariance inflation.</A></LI>
- <LI>And another one on
- <A HREF="#syntheticobservations">synthetic observations</A>.</LI>
-</UL>
-
-<!--==================================================================-->
-
-<A NAME="compilers"></A>
-<HR>
-<H2>Requirements: an F90 Compiler</H2>
-
-<P>
-The DART software has been successfully built on several Linux/x86
-platforms with the
-<A HREF="http://www.intel.com/software/products/compilers/flin">Intel Fortran
-Compiler 7.1 for Linux</A>, which is free for individual scientific use.
-It has also been built and successfully run with the
-<A HREF="http://www.pgroup.com">Portland Group Fortran Compiler</A> (5.02), and again with
-the Intel 8.0.034 compiler.
-Since recompiling the code is a necessity to experiment
-with different models, there are no binaries to distribute.
-</P>
-
-<!--==================================================================-->
-
-<A NAME="netCDFlib"></A>
-<HR>
-<H2>Requirements: the <em class=file>netCDF</em> library</H2>
-
-<P>
-DART uses the
-<A HREF="http://www.unidata.ucar.edu/packages/netcdf/">netCDF</A>
-self-describing data format for the results of assimilation
-experiments. These files have the extension <em class=file>.nc</em>
-and can be read by a number of standard data analysis tools.
-In particular, DART also makes use of the F90 interface to the library
-which are available through the <em class=file>netcdf.mod</em> and
-<em class=file>typesizes.mod</em> modules.
-<em class=bold>IMPORTANT</em>: different compilers create these modules with
-different "case" filenames, and sometimes they are not <strong>both</strong>
-installed into the expected directory. It is required that both modules
-be present. The normal place would be in the <TT>netcdf/include</TT>
-directory, as opposed to the <TT>netcdf/lib</TT> directory.
-</P>
-
-<P>
-If the netCDF library does not exist on your system, you must build
-it (as well as the F90 interface modules). The library and instructions
-for building the library or installing from an RPM may be found at
-the netCDF home page:
-<A HREF="http://www.unidata.ucar.edu/packages/netcdf/">
-http://www.unidata.ucar.edu/packages/netcdf/</A>
-Pay particular attention to the compiler-specific patches that must
-be applied for the Intel Fortran Compiler. (Or the PG compiler, for
-that matter.)
-</P>
-
-<P>
-The location of the netCDF library, <em class=file>libnetcdf.a</em>,
-and the locations of both <em class=file>netcdf.mod</em> and
-<em class=file>typesizes.mod</em> will be needed by the makefile
-template, as described in the <A HREF="#compiling">compiling</A>
-section.
-</P>
-
-<!--==================================================================-->
-
-<A NAME="udunits"></A>
-<HR>
-<H2>Requirements: the <em class=file>udunits</em> library</H2>
-
-<P>DART also uses the <strong>very</strong> common
-<A HREF="http://my.unidata.ucar.edu/content/software/udunits/index.html">
-udunits</A> library for manipulating units of physical quantities. If,
-somehow, it is not installed on your system, you will need to install
-it (instructions are available from
-<A HREF="http://www.unidata.ucar.edu">Unidata's Downloads</A> page).
-</P>
-
-<P>
-The location of the udunits library, <em class=file>libudunits.a</em>,
-will be needed by the makefile template, as described in the
-<A HREF="#compiling">compiling</A> section.
-</P>
-
-<!--==================================================================-->
-
-<A NAME="download"></A>
-<HR>
-<H2>Unpacking the distribution.</H2>
-
-<P>
-The DART source code is distributed as a compressed tar file.
-<A HREF="/pub/DART/DART_fiji.tar.gz">DART_fiji.tar.gz</A>
-[22347692 bytes]. When untarred, the source tree will begin with a
-directory named <em class=file>DART</em> and will be approximately
-105 Mb. Compiling the code in this tree (as is usually the case) will
-necessitate much more space.
-</P>
-
-<div class=unix>
- gunzip <em class=file>DART_fiji.tar.gz</em><BR>
- tar -xvf <em class=file>DART_fiji.tar</em><BR>
-</div>
-
-<P>
-The code tree is very "bushy"; there are many directories of support
-routines, etc. but only a few directories involved with the
-customization and installation of the DART software. If you can
-compile and run ONE of the low-order models, you should be able to
-compile and run ANY of the low-order models. For this reason,
-we can focus on the Lorenz `63 model. Subsequently, the only
-directories with files to be modified to check the installation
-are:
- <em class=file>DART/mkmf</em>,
- <em class=file>DART/models/lorenz_63/work</em>, and
- <em class=file>DART/matlab</em> (but only for analysis).
-</P>
-
-<!--==================================================================-->
-
-<A NAME="customizations"></A>
-<HR>
-<H2>Customizing the build scripts -- Overview.</H2>
-
-<P>
-DART executable programs are constructed using two tools:
-<em class=program>make</em> and
-<em class=program>mkmf</em>.
-The <em class=program>make</em> utility is a relatively common
-piece of software that requires a user-defined input file that records
-dependencies between different source files. <em class=program>make</em>
-then performs a hierarchy of actions when one or more of the
-source files is modified. The <em class=program>mkmf</em> utility is
-a custom preprocessor that generates a <em class=program>make</em> input file
-(named <em class=file>Makefile</em>) and an example namelist <em class=file>input.nml.mkmf</em>
-with the default values. The <em class=file>Makefile</em> is designed specifically to work
-with object-oriented Fortran90 (and other languages) for systems like DART.
-</P>
-
-<P>
-<em class=program>mkmf</em> requires two separate input files.
-The first is a `template' file which specifies details of the commands
-required for a specific Fortran90 compiler and may also contain
-pointers to directories containing pre-compiled utilities required by
-the DART system. <strong>This template file will need to
-be modified to reflect your system</strong>. The second input file is a
-`path_names' file which includes a complete list of the locations
-(either relative or absolute) of all Fortran90 source files that are
-required to produce a particular DART program.
-Each 'path_names' file must contain a path for
-exactly one Fortran90 file containing a main program,
-but may contain any number of additional paths pointing to files
-containing Fortran90 modules.
-An <em class=program>mkmf</em> command is executed which
-uses the 'path_names' file and the mkmf template file to produce a
-<em class=file>Makefile</em> which is subsequently used by the
-standard <em class=program>make</em> utility.
-</P>
-
-<P>
-Shell scripts that execute the mkmf command for all standard
-DART executables are provided as part of the standard DART software.
-For more information on <em class=program>mkmf</em> see
-<A HREF="http://www.gfdl.gov/fms/pubrel/j/atm_dycores/doc/dycore_public_manual.html#mkmf">the FMS mkmf description</A>.
-<BR>
-One of the benefits of using <em class=program>mkmf</em> is that it also
-creates an example namelist file for each program. The example namelist is
-called <em class=file>input.nml.mkmf</em>, so as not to clash with any
-exising <em class=file>input.nml</em> that may exist in that directory.
-</P>
-
-<A NAME="template"></A>
-<H3 class=indent1>Building and Customizing the 'mkmf.template' file</H3>
-
-<P>
-A series of templates for different compilers/architectures exists
-in the <em class=file>DART/mkmf/</em> directory and have names with
-extensions that identify either 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
-<em class=file>mkmf.template</em> and customize it.
-For the discussion that follows, knowledge of the contents of one of these
-templates (i.e. <em class=file>mkmf.template.pgi</em>) is needed:
-(note that only the first few lines are shown here)
-</P>
-
-<div class=routine>
-# Makefile template for PGI f90<BR>
-FC = pgf90<BR>
-CPPFLAGS =<BR>
-FFLAGS = -r8 -Ktrap=fp -pc 64 -I/usr/local/netcdf/include<BR>
-LD = pgf90<BR>
-LDFLAGS = $(LIBS)<BR>
-LIBS = -L/usr/local/netcdf/lib -lnetcdf -L/usr/local/udunits-1.11.7/lib -ludunits<BR>
-LIST = -Mlist<BR>
-<BR>
-# you should never need to change any lines below.<BR>
-...<BR>
-</div>
-
-<P>
-Essentially, each of the lines defines some part of the resulting
-<em class=file>Makefile</em>. Since <em class=program>make</em>
-is particularly good at sorting out dependencies, the order of these
-lines really doesn't make any difference.
-The <em class=code>FC = pgf90</em> line ultimately defines the
-Fortran90 compiler to use, etc.
-The lines which are most likely to need site-specific changes
-start with <em class=code>FFLAGS</em> and <em class=code>LIBS</em>, which
-indicate where to look for the netCDF F90 modules and the
-location of the netCDF and udunits libraries.
-</P>
-
-<A HREF="fflags"></A>
-<H4 class=indent2>FFLAGS</H4>
-
-<P class=indent1>
-Each compiler has different compile flags, so there is really no way
-to exhaustively cover this other than to say the templates as we supply
-them should work -- depending on the location of the netCDF modules
-<em class=file>netcdf.mod</em> and
-<em class=file>typesizes.mod</em>.
-Change the <em class=code>/usr/local/netcdf/include</em> string to
-reflect the location of your modules.
-The low-order models can be compiled without the <em class=code>-r8</em>
-switch, but the <em class=file>bgrid_solo</em> model cannot.
-</P>
-
-<A HREF="libs"></A>
-<H4 class=indent2>LIBS</H4>
-
-<P class=indent1>
-Modifying the <em class=code>LIBS</em> value should be relatively
-straightforward.<BR>
-Change the <em class=code>/usr/local/netcdf/lib</em> string to
-reflect the location of your <em class=file>libnetcdf.a</em>.<BR>
-Change the <em class=code>/usr/local/udunits-1.11.7/lib</em> string to
-reflect the location of your <em class=file>libudunits.a</em>.
-</P>
-
-<A NAME="path_names"></A>
-<H3 class=indent1>Customizing the 'path_names_*' file</H3>
-
-<P>
-Several <em class=file>path_names_*</em> files are provided in
-the <em class=file>work</em> directory for each specific model,
-in this case: <em class=file>DART/models/lorenz_63/work</em>.
-</P>
-<OL>
- <LI><em class=file>path_names_create_obs_set_def</em></LI>
- <LI><em class=file>path_names_create_obs_sequence</em></LI>
- <LI><em class=file>path_names_perfect_model_obs</em></LI>
- <LI><em class=file>path_names_filter</em></LI>
-</OL>
-<P>
-Since each model comes with its own set of files, no further
-customization is needed.
-</P>
-
-<!--==================================================================-->
-
-<A NAME="building"></A>
-<HR>
-<H2>Building the Lorenz_63 DART project.</H2>
-
-<P>Currently, DART executables are constructed in a <em class=file>work</em>
-subdirectory under the directory containing code for the given model.
-In the top-level DART directory, change to the L63 work
-directory and list the contents:
-</P>
-
-<div class=unix>
-cd DART/models/lorenz_63/work<BR>
-ls -1
-</div>
-
-<P>
-With the result:
-<PRE>filter_ics
-mkmf_create_obs_sequence
-mkmf_create_obs_set_def
-mkmf_filter
-mkmf_perfect_model_obs
-path_names_create_obs_sequence
-path_names_create_obs_set_def
-path_names_filter
-path_names_perfect_model_obs
-perfect_ics</PRE>
-
-<P>
-There are four <em class=file>mkmf_</em><em class=italic>xxxxxx</em>
-files for the programs
-<em class=program>create_obs_set_def</em>,
-<em class=program>create_obs_sequence</em>,
-<em class=program>perfect_model_obs</em>, and
-<em class=program>filter</em> along with the
-corresponding <em class=file>path_names_</em><em class=italic>xxxxxx</em> files.
-You can examine the contents of one of the
-<em class=file>path_names_</em><em class=italic>xxxxxx</em> files,
-for instance <em class=file>path_names_filter</em>, to see a list of
-the relative paths of all files that contain Fortran90 modules
-required for the program <em class=program>filter</em> for
-the L63 model. All of these paths are relative to your
-<em class=file>DART</em> directory.
-The first path is the main program
-(<em class=file>filter.f90</em>) and is followed by all
-the Fortran90 modules used by this program.
-</P>
-
-<P>
-The <em class=program>mkmf_</em><em class=italic>xxxxxx</em> scripts
-are cryptic but should not need to be modified -- as long as you do not
-restructure the code tree (by moving directories, for example).
-
-The only function of the <em class=program>mkmf_</em><em class=italic>xxxxxx</em> script
-is to generate a <em class=file>Makefile</em> and an <em class=file>input.nml.mkmf</em> file.
-It is not supposed to compile anything:
-</P>
-
-<div class=unix>
-csh mkmf_create_obs_set_def<BR>
-mv input.nml.mkmf input.nml.create_obs_set_def<BR>
-make
-</div>
-
-<P>
-The first command generates an appropriate <em class=file>Makefile</em> and
-the <em class=file>input.nml.mkmf</em> file. The second saves the example namelist to a
-unique name (the next DART release will do this automatically -- no harm is done by
-omitting this step) and the last command results in the compilation of a series of
-Fortran90 modules which ultimately produces an executable file:
-<em class=program>create_obs_set_def</em>.
-Should you need to make any changes to the
-<em class=file>DART/mkmf/mkmf.template</em>,
-you will need to regenerate the <em class=file>Makefile</em>.
-A series of object files for each module compiled will also be
-left in the work directory, as some of these are undoubtedly needed by the build
-of the other DART components.
-You can proceed to create the other three programs needed to work with
-L63 in DART as follows:
-</P>
-
-<div class=unix>
-csh mkmf_create_obs_sequence<BR>
-mv input.nml.mkmf input.nml.create_obs_sequence<BR>
-make<BR>
-csh mkmf_perfect_model_obs<BR>
-mv input.nml.mkmf input.nml.perfect_model_obs<BR>
-make<BR>
-csh mkmf_filter<BR>
-mv input.nml.mkmf input.nml.filter<BR>
-make
-</div><BR>
-
-The result (hopefully) is that four executables now
-reside in your work directory. The most common problem is that the netCDF libraries
-and include files (particularly <em class=file>typesizes.mod</em>) are not found.
-Edit the <em class=file>DART/mkmf/mkmf.template</em>,
-recreate the <em class=file>Makefile</em>, and try again.<BR><BR>
-
-<TABLE border=0 cellpadding=1 width=100%>
-<TR><TH>program</TH><TH>purpose</TH></TR>
-<TR><TD><em class=program>create_obs_set_def</em></TD>
- <TD>specify a (set) of observation characteristics taken
- by a particular (set of) instruments
- </TD></TR>
-<TR><TD><em class=program>create_obs_sequence</em></TD>
- <TD>specify the temporal attributes of the observation sets
- </TD></TR>
-<TR><TD><em class=program>perfect_model_obs</em></TD>
- <TD>spinup, generate "true state" for synthetic observation experiments, ...
- </TD></TR>
-<TR><TD><em class=program>filter</em></TD>
- <TD>perform experiments
- </TD></TR>
-</TABLE>
-
-<!--==================================================================-->
-<!--==================================================================-->
-
-<A NAME="Running"></A>
-<HR>
-<H2>Running Lorenz_63.</H2>
-
-<P>
-This initial sequence of exercises includes detailed instructions
-on how to work with the DART code and allows investigation of the
-basic features of one of the most famous dynamical systems, the
-3-variable Lorenz-63 model.
-The remarkable complexity of this simple model will also be used as
-a case study to introduce a number of features of a simple ensemble
-filter data assimilation system.
-To perform a synthetic observation assimilation experiment
-for the L63 model, the following steps must be performed
-(an overview of the process is given first,
-followed by detailed procedures for each step):
-</P>
-
-<H2 class=indent1>Experiment Overview</H2>
-<OL>
- <LI><A HREF="#integrate">Integrate the L63 model for a long time</A><br>
- starting from arbitrary initial conditions to generate a model state
- that lies on the attractor. The ergodic nature of the L63 system
- means a 'lengthy' integration always converges to some point on
- the computer's finite precision representation of the model's
- attractor.<br><br></LI>
-
- <LI><A HREF="#ensemblate">Generate a set of ensemble initial conditions</A><br>
- from which to start an assimilation. Since L63 is ergodic, the
- ensemble members can be designed to look like random samples from
- the model's 'climatological distribution'. To generate an ensemble
- member, very small perturbations can be introduced to the state on
- the attractor generated by step 1. This perturbed state can then be
- integrated for a very long time until all memory of its initial
- condition can be viewed as forgotten. Any number of ensemble
- initial conditions can be generated by repeating this procedure.<br><br></LI>
-
- <LI><A HREF="#simulate">Simulate a particular observing system</A><br>
- by first creating an 'observation set definition' and then creating
- an 'observation sequence'. The 'observation set definition' describes the
- instrumental characteristics of the observations and the 'observation sequence'
- defines the temporal sequence of the observations.<br><br></LI>
-
- <LI><A HREF="#generate">Populate the 'observation sequence' with 'perfect' observations</A><br>
- by integrating the model and using the information in the
- 'observation sequence' file to create simulated observations.
- This entails operating on the model state at the
- time of the observation with an appropriate forward operator
- (a function that operates on the model state vector to produce
- the expected value of the particular observation) and then adding
- a random sample from the observation error distribution specified
- in the observation set definition. At the same time, diagnostic
- output about the 'true' state trajectory can be created.<br><br></LI>
-
- <LI><A HREF="#assimilate">Assimilate the synthetic observations</A><br>
- by running the filter; diagnostic output is generated.</LI>
-</OL>
-
-<A NAME="integrate"></A>
-<H3 class=indent1>1. Integrate the L63 model for a 'long' time.</H3>
-<em class=program>perfect_model_obs</em> integrates the model
-for all the times specified in the 'observation sequence definition' file.
-To this end, begin by creating an 'observation sequence definition'
-file that spans a long time. Creating an 'observation sequence definition'
-file is a two-step procedure involving
-<em class=program>create_obs_set_def</em> followed by
-<em class=program>create_obs_sequence</em>. After they are both run, it
-is necessary to integrate the model with <em class=program>perfect_model_obs</em>.
-
-<H4 class=indent1>1.1 Create an observation set definition.</H4>
-<P>
-<em class=program>create_obs_set_def</em> creates an observation
-set definition, the time-independent part of an observation sequence.
-An observation set definition file only contains the
-<em class=code>location, type,</em>
-and <em class=code>observational error characteristics</em>
-(normally just the diagonal observational error variance)
-for a related set of observations. There are no actual observations,
-nor are there any times associated with the definition.
-For spin-up, we are only interested in integrating the L63 model,
-not in generating any particular synthetic observations.
-Begin by creating a minimal observation set definition.<BR>
-<BR>
-In general, for the low-order models, only a single observation set need
-be defined. Next, the number of individual scalar observations
-(like a single surface pressure observation) in the set is needed.
-To spin-up an initial condition for the L63 model, only a
-single observation is needed.
-Next, the error variance for this observation must be entered.
-Since we do not need (nor want) this observation to have any impact
-on an assimilation (it will only be used for spinning up the model
-and the ensemble), enter a very large value for the error variance.
-An observation with a very large error variance has essentially no
-impact on deterministic filter assimilations like the default variety
-implemented in DART. Finally, the location and type of the
-observation need to be defined. For all types of models,
-the most elementary form of synthetic observations are called
-'identity' observations. These observations are generated simply
-by adding a random sample from a specified observational error
-distribution directly to the value of one of the state variables.
-This defines the observation as being an identity observation of the
-first state variable in the L63 model.
-The program will respond by terminating after generating a file
-(generally named <em class=file>set_def.out</em>)
-that defines the single identity observation of the first
-state variable of the L63 model. The following is a screenshot
-(much of the verbose logging has been left off for clarity),
-the user input looks <em class=input>like this</em>.
-</P>
-
-<div class=unix>
-<PRE>
-[unixprompt]$ <em class=input>./create_obs_set_def</em>
- Initializing the utilities module.
- Registering module :
- $Source$
- $Revision$
- $Date$
- Registration complete.
-
- &UTILITIES_NML
- TERMLEVEL = 2,
- LOGFILENAME = dart_log.out
- /
-
- Registering module :
- $Source$
- $Revision$
- $Date$
- Registration complete.
-
- Input the filename for output of observation set_def_list? [set_def.out]
-<em class=input>set_def.out</em>
-
-{ ... }
-
- Input the number of unique observation sets you might define
-<em class=input>1</em>
- How many observations in set 1
-<em class=input>1</em>
- Defining observation 1
- Input error variance for this observation definition
-<em class=input>1000000</em>
- Input an integer index if this is identity observation, else -1
-<em class=input>1</em>
-
- Registering module :
- $Source$
- $Revision$
- $Date$
- Registration complete.
-
- set_def.out successfully created.
- Terminating normally.
-</PRE>
-</div>
-
-<H4 class=indent1>1.2 Create an observation sequence definition.</H4>
-<P>
-<em class=program>create_obs_sequence</em> creates an 'observation
-sequence definition' by extending the 'observation set definition'
-with the temporal attributes of the observations.<BR>
-<BR>
-The first input is the name of the file created in the previous step,
-i.e. the name of the observation set definition that you've just created.
-It is possible to create sequences in which the observation sets
-are observed at regular intervals or irregularly in time.
-Here, all we need is a sequence that takes observations over a
-long period of time - indicated by entering a 1.
-Although the L63 system normally is defined as having a non-dimensional
-time step, the DART system arbitrarily defines the model
-timestep as being 3600 seconds. By declaring we have 1000 observations
-taken once per day, we create an observation sequence definition
-spanning 24000 'model' timesteps; sufficient to spin-up the model
-onto the attractor. Finally, enter a name for the
-'observation sequence definition' file. Note again: there are no observation
-values present in this file. Just an observation type, location, time and the
-error characteristics. We are going to populate the observation sequence
-with the <em class=program>perfect_model_obs</em> program.
-</P>
-
-<div class=unix>
-<PRE>
-[thoar at ghotiol work]$ <em class=input>./create_obs_sequence</em>
- Registering module :
- $Source$
- $Revision$
- $Date$
- Registration complete.
-
- &UTILITIES_NML
- TERMLEVEL = 2,
- LOGFILENAME = dart_log.out
- /
-
- Registering module :
- $Source$
- $Revision$
- $Date$
- Registration complete.
-
- What is name of set_def_list? [set_def.out]
-<em class=input>set_def.out</em>
-
- { ... }
-
- Setting times for obs_def 1
- To input a regularly repeating time sequence enter 1
- To enter an irregular list of times enter 2
-<em class=input>1</em>
- Input number of observations in sequence
-<em class=input>1000</em>
- Input time of initial ob in sequence in days and seconds
-<em class=input>1, 0</em>
- Input period of obs in days and seconds
-<em class=input>1, 0</em>
- time 1 is 0 1
- time 2 is 0 2
- time 3 is 0 3
-...
- time 998 is 0 998
- time 999 is 0 999
- time 1000 is 0 1000
- Input file name for output of obs_sequence? [obs_seq.in]
-<em class=input>obs_seq.in</em>
-</PRE>
-</div>
-
-
-<H4>1.3 Initialize the model onto the attractor.</H4>
-<P>
- <em class=program>perfect_model_obs</em> can now advance the
- arbitrary initial state for 24,000 timesteps to move it onto the
- attractor.</BR>
- <em class=program>perfect_model_obs</em> uses the Fortran90 namelist
- input mechanism instead of (admittedly gory, but temporary) interactive input.
- All of the DART software expects the namelists to found in a file called
- <em class=file>input.nml</em>. When you built the executable, an example namelist
- was created <em class=file>input.nml.mkmf</em> that contains all of the namelist
- input for the executable. If you followed the example, each namelist was saved
- to a unique name. We must now rename and edit the namelist file for
- <em class=program>perfect_model_obs</em>.
- Copy <em class=file>input.nml.perfect_model_obs</em>
- to <em class=file>input.nml</em> and edit it to look like the following:
-</P>
-
-<div class=routineIndent1>
-&perfect_model_obs_nml <BR>
- async = 0, <BR>
- obs_seq_in_file_name = "obs_seq.in", <BR>
- obs_seq_out_file_name = "obs_seq.out", <BR>
- start_from_restart = .false., <BR>
- output_restart = <em class=changed>.true.</em>, <BR>
- restart_in_file_name = "perfect_ics", <BR>
- restart_out_file_name = "perfect_restart", <BR>
- init_time_days = 0, <BR>
- init_time_seconds = 0, <BR>
- output_interval = 1 <BR>
-&end </BR>
-&assim_tools_nml</BR>
- prior_spread_correction = .false.,</BR>
- filter_kind = 1,</BR>
- slope_threshold = 1.0</BR>
-&end</BR>
-&cov_cutoff_nml</BR>
- select_localization = 1</BR>
-&end</BR>
-&assim_model_nml</BR>
- binary_restart_files = .true.</BR>
-&end</BR>
-&model_nml</BR>
- sigma = 10.0, </BR>
- r = 28.0, </BR>
- b = 2.6666666666667,</BR>
- deltat = 0.01</BR>
-&end</BR>
-&utilities_nml</BR>
- TERMLEVEL = 1</BR>
- logfilename = 'dart_log.out'</BR>
-&end</BR>
-</div><BR>
-
-For the moment, only two namelists warrant explanation. Each namelists is covered in detail
-in the html files accompanying the source code for the module.
-
-<h3 class=indent1>perfect_model_obs_nml</h3>
-<TABLE border=1 class=indent1>
-<TR><TH>namelist variable</TH><TH>description</TH></TR>
-<TR><TD><em class=code>async</em></TD>
- <TD>For the lorenz_63, simply ignore this. Leave it set to '0'</TD></TR>
-
-<TR><TD><em class=code>obs_seq_in_file_name</em></TD>
- <TD>specifies the file name that results from running
- <em class=program>create_obs_sequence</em>, i.e. the
- 'observation sequence definition' file.</TD></TR>
-
-<TR><TD><em class=code>obs_seq_out_file_name</em></TD>
- <TD>specifies the output file name containing the
- 'observation sequence', finally populated with
- (perfect?) 'observations'.</TD></TR>
-
-<TR><TD><em class=code>start_from_restart</em></TD>
- <TD>When set to 'false',
- <em class=program>perfect_model_obs</em> generates an
- arbitrary initial condition (which cannot be guaranteed
- to be on the L63 attractor).</TD></TR>
-
-<TR><TD><em class=code>output_restart</em></TD>
- <TD>When set to 'true',
- <em class=program>perfect_model_obs</em> will record
- the model state at the end of this integration in the file
- named by <em class=code>restart_out_file_name</em>.</TD></TR>
-
-<TR><TD><em class=code>restart_in_file_name</em></TD>
- <TD>is ignored when 'start_from_restart' is 'false'.</TD></TR>
-
-<TR><TD><em class=code>restart_out_file_name</em></TD>
- <TD>if <em class=code>output_restart</em> is 'true',
- this specifies the name of the file containing the model
- state at the end of the integration.</TD></TR>
-
-<TR><TD><em class=code>init_time_</em><em class=italic>xxxx</em></TD>
- <TD>the start time of the integration.</TD></TR>
-
-<TR><TD><em class=code>output_interval</em></TD>
- <TD>interval at which to save the model state.</TD></TR>
-</TABLE>
-
-
-<h3 class=indent1>utilities_nml</h3>
-<TABLE class=indent1 border=1>
-<TR><TH>namelist variable</TH><TH>description</TH></TR>
-<TR><TD><em class=code>TERMLEVEL</em></TD>
- <TD>When set to '1' the programs terminate when a 'warning' is generated.
- When set to '2' the programs terminate only with 'fatal' errors.</TD></TR>
-
-<TR><TD><em class=code>logfilename</em></TD>
- <TD>Run-time diagnostics are saved to this file. This namelist is used
- by all programs, so the file is opened in APPEND mode. Subsequent
- executions cause this file to grow.</TD></TR>
-</TABLE>
-
-
-<P>
-Executing <em class=program>perfect_model_obs</em> will integrate the
-model 24,000 steps and output the resulting state in the file
-<em class=file>perfect_restart</em>. Interested parties can check the
-spinup in the <em class=file>True_State.nc</em> file.
-</P>
-
-<div class=unix>
-perfect_model_obs
-</div>
-
-<A NAME="ensemblate"></A>
-<H3 class=indent1>2. Generate a set of ensemble initial conditions.</H3>
-<P class=indent1>
- The set of initial conditions for a 'perfect model' experiment is
- created by taking the spun-up state of the model
- (available in <em class=file>perfect_restart</em>),
- running <em class=program>perfect_model_obs</em> to generate
- the 'true state' of the experiment and a corresponding set of
- observations, and then feeding the same initial spun-up state
- and resulting observations into <em class=program>filter</em>.
- <BR><BR>
- Generating ensemble initial conditions
- is achieved by changing a perfect_model_obs namelist parameter,
- copying <em class=file>perfect_restart</em> to
- <em class=file>perfect_ics</em>, and
- rerunning <em class=program>perfect_model_obs</em>.
- This execution of <em class=program>perfect_model_obs</em>
- will advance the model state from
- the end of the first 24,000 steps to the end of an additional 24,000
- steps and place the final state in <em class=file>perfect_restart</em>.
- The rest of the namelists in <em class=file>input.nml</em> should remain
- unchanged.
-</P>
-
- <div class=routineIndent1>
- &perfect_model_obs_nml <BR>
- async = 0, <BR>
- obs_seq_in_file_name = "obs_seq.in", <BR>
- obs_seq_out_file_name = "obs_seq.out", <BR>
- start_from_restart = <em class=changed>.true.</em>, <BR>
- output_restart = .true., <BR>
- restart_in_file_name = "perfect_ics", <BR>
- restart_out_file_name = "perfect_restart", <BR>
- init_time_days = 0, <BR>
- init_time_seconds = 0, <BR>
- output_interval = 1 /
- </div>
-
- <div class=unix>
- cp perfect_restart perfect_ics<BR>
- perfect_model_obs
- </div>
-
-<P class=indent1>
- A <em class=file>True_State.nc</em>
- file is also created. It contains the 'true' state of the integration.
-</P>
-
-<H4 class=indent1>Generating the ensemble</H4>
-<P class=indent1>
- is done with the program <em class=program>filter</em>, which also uses the
- Fortran90 namelist mechanism for input. It is now necessary to copy the
- <em class=file>input.nml.filter</em> namelist to <em class=file>input.nml</em>
- or you may simply insert the <em class=code>filter_nml</em> namelist into the
- existing <em class=file>input.nml</em>. Having the <em class=code>perfect_model_obs</em>
- namelist in the input.nml does not hurt anything. In fact, I generally create a single
- <em class=file>input.nml</em> that has all the namelist blocks in it.
-</P>
-
-<div class=routineIndent1>
-&perfect_model_obs_nml<BR>
- async = 0,<BR>
- obs_seq_in_file_name = "obs_seq.in",<BR>
- obs_seq_out_file_name = "obs_seq.out",<BR>
- start_from_restart = .true.,<BR>
- output_restart = .true.,<BR>
- restart_in_file_name = "perfect_ics",<BR>
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list