[Dart-dev] [6354] DART/trunk/doc/html: New docs for the upcoming release.
nancy at ucar.edu
nancy at ucar.edu
Thu Aug 1 10:20:07 MDT 2013
Revision: 6354
Author: nancy
Date: 2013-08-01 10:20:07 -0600 (Thu, 01 Aug 2013)
Log Message:
-----------
New docs for the upcoming release. Reformatted information from
the wiki pages into html for the release differences file.
The release notes file has only minor updates so far, e.g. changing names
from Jamaica/Kodiak to Kodiak/Lanai. It needs more work but i want
a version in the repository first.
Added Paths:
-----------
DART/trunk/doc/html/Lanai_diffs_from_Kodiak.html
DART/trunk/doc/html/Lanai_release.html
-------------- next part --------------
Added: DART/trunk/doc/html/Lanai_diffs_from_Kodiak.html
===================================================================
--- DART/trunk/doc/html/Lanai_diffs_from_Kodiak.html (rev 0)
+++ DART/trunk/doc/html/Lanai_diffs_from_Kodiak.html 2013-08-01 16:20:07 UTC (rev 6354)
@@ -0,0 +1,297 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>DART Lanai Differences from Kodiak Release Notes</title>
+<link rel="stylesheet" type="text/css" href="doc.css" />
+<link href="../images/dart.ico" rel="shortcut icon" />
+</head>
+<body>
+<a name="TOP"></a>
+
+<h1>DART Lanai Differences from Kodiak Release Notes</h1>
+
+<table border=0 summary="" cellpadding=5>
+<tr>
+ <td valign=middle>
+ <img src="../images/Dartboard7.png" alt="DART project logo" height=70 />
+ </td>
+ <td>
+ <p>Jump to DART Documentation Main Index
+ <a href="https://proxy.subversion.ucar.edu/DAReS/DART/releases/Kodiak/index.html">Website</a>
+ or <a href="../../index.html">local file</a><br />
+ <small><small>version information for this file: <br />
+ <!-- version tag follows, do not edit -->
+ $Id$</small></small>
+ </p></td>
+</tr>
+</table>
+
+<a href="#NewModels">New Models or Changes to Existing Models</a> /
+<a href="#Changes">Changes to Core DART routines</a> /
+<a href="#ForwardOps">New or Changed Forward Operators</a> /
+<a href="#ObsConvert">Observation Converters</a> /
+<a href="#Diagnostics">New or Updated DART Diagnostics</a> /
+<a href="#Misc">Tutorial, Scripting, Setup, Builds</a> /
+<a href="#Legalese">Terms of Use</a>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<A NAME="NewModels"></A>
+<H2>New Models or Changes to Existing Models</H2>
+<P>
+Several new models have been incorporated into DART. This section details
+both changes to existing models and descriptions of new models that have
+been added since the Kodiak release.
+</P>
+
+<UL>
+<LI>Changes to the WRF model_mod:
+<UL>
+<LI>allow advanced microphysics schemes (needed interpolation for 7 new kinds)</LI>
+<LI>option to interpolate in the vertical in log(p) instead of linear in p (log(p) is the default now)</LI>
+<LI>added support in the namelist to avoid writing updated fields back into the wrf netcdf files. The fields are still updated during the assimilation but the updated data is not written back to the wrfinput file during the dart_to_wrf step.</LI>
+<LI>fixed an obscure bug in the vertical convert routine of the wrf model_mod that would occasionally fail to convert an obs. This would make tiny differences in the output as the number of mpi tasks change. No quantitative differences in the output but not bitwise compatible before and is again now.</LI>
+</UL>
+</LI>
+<LI>Added support for the MPAS_ATM and MPAS_OCN models.
+<UL>
+<LI>added code to the mpas_atm model to interpolate specific humidity and pressure, so we can assimilate GPS obs now.</LI>
+</UL>
+</LI>
+<LI>Added support for the CLM land model.</LI>
+<LI>Added support for the CESM 1.1.1 release for CAM, POP, CLM: includes experiment setup scripts and assimilation scripts.</LI>
+<LI>Added support for the 'SQG' uniform PV two-surface QC+1 spectral model.</LI>
+<LI>Added support for a flux-transport solar dynamo model.</LI>
+<LI>Added support for the NOAH land model.</LI>
+<LI>Added support for the NAAPS model.</LI>
+<LI>Added model_mod interface code for the NOGAPS model to the SVN repository.</LI>
+<LI>Fix temperature vs potential temp bug in POP model_mod.
+<UL>
+<LI>state vector has all along contained potential temperature and not in-situ (sensible) temperature. The observations from the World Ocean Database are of sensible temperature. Changed the specific kind in the model_mod to be <pre>KIND_POTENTIAL_TEMPERATURE</pre> and added new code to convert from potential to in-situ temperature. Differences for even the deeper obs (4-5km) is still small ( ~ 0.2 degree). (in-situ or sensible temperature is what you measure with a regular thermometer.)</LI>
+</UL>
+</LI>
+<LI>Simple advection model:
+<UL>
+<LI>Fix where the random number seed is set in the models/simple_advection model_mod - it needed to be sooner than it was being called.</LI>
+</UL>
+</LI>
+</UL>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<A NAME="Changes"></A>
+<H2>Changes to Core DART routines</H2>
+<P>
+This section describes changes in the basic DART library routines
+since the Kodiak release.
+</P>
+
+<UL>
+<LI>Added a completely new random number generator based on the Mersenne Twister algorithm from the GNU scientific library. It seems to have better behavior if reseeded frequently, which is a possible usage pattern if perfect_model_obs is run for only single steps and the model is advanced in an external script. As part of this code update all random number code was moved into the random_seq_mod and random_nr_mod is deprecated.</LI>
+<LI>perfect_model_obs calls a seed routine in the time manager now that generates a consistent seed based on the current time of the state. This makes subsequent runs give consistent results and yet separate runs don't get identical error values.</LI>
+<LI>Added random number generator seeds in several routines to try to get consistent results no matter how many MPI tasks the code was run with. This includes:
+<UL>
+<LI>cam model_mod.f90, pert_model_state()</LI>
+<LI>assim_tools_mod.f90, filter_assim(), filter kinds 2, 3, and 5</LI>
+<LI>wrf model_mod.f90, pert_model_state()</LI>
+<LI>adaptive_inflate_mod.f90, adaptive_inflate_init(), non-deterministic inf</LI>
+</UL>
+</LI>
+<LI>Added a time sort routine in the time_manager_mod.</LI>
+<LI>Avoid a pair of all-to-all transposes when setting the inflation mean and sd from the namelist. The new code finds the task which has the two copies and sets them directly without a transpose. The log messages were also moved to the end of the routine - if you read in the mean/sd values from a restart file the log messages that printed out the min/max values needed to be after the read from the file.</LI>
+<LI>Reordered the send/receive loops in the all-to-all transposes to scale better on yellowstone.</LI>
+<LI>Remove a state-vector size array from the stack in read_ensemble_restart(). The array is allocated only if needed and then deallocated. The ensemble write routine was changed before the Kodiak release but the same code in read was apparently not changed simply as an oversight.</LI>
+<LI>If the ensemble mean is selected to be written out in dart restart file format, the date might not have been updated correctly. The code was fixed to ensure the ensemble mean date in the file was correct.</LI>
+<LI>filter writes the ensemble size into the log file.</LI>
+<LI>Reorganized the code in the section of obs_model_mod that prints out the time windows, with and without verbose details. Should be clearer if the next observation is in or out of the current assimilation window, and if the model needs to advance or not.</LI>
+<LI>Added a fill_inflation_restart utility which can write a file with a fixed mean and sd, so the first step of a long assimilation run can use the same 'start_from_restart_file' as subsequent steps.</LI>
+<LI>Added new location module options:
+<UL>
+<LI>Channel coordinate system</LI>
+<LI>[0-1] periodic 3D coordinate system</LI>
+<LI>X,Y,Z 3D Cartesian coordinate system</LI>
+<LI>2D annulus coordinate system</LI>
+</UL>
+</LI>
+</UL>
+
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<A NAME="ForwardOps"></A>
+<H2>New or changed Forward Operators</H2>
+<P>
+This section describes changes to the Foward Operators and
+new Generic Kinds or Specific Types that have been added
+since the Kodiak release.
+</P>
+
+
+<UL>
+<LI>Many new kinds added to the DEFAULT_obs_kind_mod.f90:
+<UL>
+<LI>KIND_CANOPY_WATER</LI>
+<LI>KIND_CARBON</LI>
+<LI>KIND_CLW_PATH</LI>
+<LI>KIND_DIFFERENTIAL_REFLECTIVITY</LI>
+<LI>KIND_DUST</LI>
+<LI>KIND_EDGE_NORMAL_SPEED</LI>
+<LI>KIND_FLASH_RATE_2D</LI>
+<LI>KIND_GRAUPEL_VOLUME</LI>
+<LI>KIND_GROUND_HEAT_FLUX KIND_HAIL_MIXING_RATIO</LI>
+<LI>KIND_HAIL_NUMBER_CONCENTR</LI>
+<LI>KIND_HAIL_VOLUME KIND_ICE KIND_INTEGRATED_AOD</LI>
+<LI>KIND_INTEGRATED_DUST</LI>
+<LI>KIND_INTEGRATED_SEASALT KIND_INTEGRATED_SMOKE</LI>
+<LI>KIND_INTEGRATED_SULFATE</LI>
+<LI>KIND_LATENT_HEAT_FLUX</LI>
+<LI>KIND_LEAF_AREA_INDEX</LI>
+<LI>KIND_LEAF_CARBON</LI>
+<LI>KIND_LEAF_NITROGEN KIND_LIQUID_WATER</LI>
+<LI>KIND_MICROWAVE_BRIGHT_TEMP</LI>
+<LI>KIND_NET_CARBON_FLUX</LI>
+<LI>KIND_NET_CARBON_PRODUCTION</LI>
+<LI>KIND_NEUTRON_INTENSITY</LI>
+<LI>KIND_NITROGEN KIND_RADIATION</LI>
+<LI>KIND_ROOT_CARBON</LI>
+<LI>KIND_ROOT_NITROGEN</LI>
+<LI>KIND_SEASALT</LI>
+<LI>KIND_SENSIBLE_HEAT_FLUX</LI>
+<LI>KIND_SMOKE</LI>
+<LI>KIND_SNOWCOVER_FRAC</LI>
+<LI>KIND_SNOW_THICKNESS</LI>
+<LI>KIND_SNOW_WATER</LI>
+<LI>KIND_SO2</LI>
+<LI>KIND_SOIL_CARBON</LI>
+<LI>KIND_SOIL_NITROGEN</LI>
+<LI>KIND_SPECIFIC_DIFFERENTIAL_PHASE</LI>
+<LI>KIND_STEM_CARBON</LI>
+<LI>KIND_STEM_NITROGEN</LI>
+<LI>KIND_SULFATE</LI>
+<LI>KIND_VORTEX_WMAX</LI>
+<LI>KIND_WATER_TABLE_DEPTH</LI>
+<LI>KIND_WIND_TURBINE_POWER</LI>
+<LI>plus slots 151-250 reserved for Chemistry (specifically WRF-Chem) kinds</LI>
+</UL>
+</LI>
+<LI>Added a forward operator for total precipitable water. It loops over model levels so it can be used as an example of how to handle this without having to hardcode the number of levels into the operator.</LI>
+<LI>Added a forward operator (and obs_seq file converter) for COSMOS ground moisture observations.</LI>
+<LI>Added a forward operator (and obs_seq file converter) for MIDAS observations of Total Electron Count.</LI>
+<LI>Added a 'set_1d_integral()' routine to the obs_def_1d_state_mod.f90 forward operator for the low order models. This subroutine isn't used by filter but it would be needed if someone wanted to write a standalone program to generate obs of this type. We use this file as an example of how to write an obs type that has metadata, but we need to give an example of how to set the metadata if you aren't using create_obs_sequence interactively (e.g. your data is in netcdf and you have a separate converter program.)</LI>
+</UL>
+
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<A NAME="ObsConvert"></A>
+<H2>Observation Converters</H2>
+<P>
+This section describes
+support for new observation types or sources
+that have been added since the Kodiak release.
+</P>
+
+
+<UL>
+<LI>Added an obs_sequence converter for wind profiler data from MADIS.</LI>
+<LI>Added an obs_sequence converter for Ameriflux land observations(latent heat flux, sensible heat flux, net ecosystem production).</LI>
+<LI>Added an obs_sequence converter for MODIS snow coverage measurements.</LI>
+<LI>Added an obs_sequence converter for COSMOS ground moisture observations.</LI>
+<LI>Added an obs_sequence converter for MIDAS observations of Total Electron Count.</LI>
+<LI>Updated scripts for the GPS converter; added options to convert data from multiple satellites.</LI>
+<LI>More scripting support in the MADIS obs converters; more error checks added to the rawin converter.</LI>
+<LI>Added processing for wind profiler observation to the wrf_dart_obs_preprocess program.</LI>
+<LI>Fix BUG in airs converter - the humidity obs are accumulated acrossthe layers and so the best location for them is the layer midpoint and not on the edges (levels) as the temperature obs are. Also fixed off-by-one error where the converter would make one more obs above the requested top level.</LI>
+<LI>Made gts_to_dart converter create separate obs types for surface dewpoint vs obs aloft because they have different vertical coordinates.</LI>
+<LI>Converted mss commands to hpss commands for a couple observation converter shell scripts (inc AIRS).</LI>
+<LI>New matlab code to generate evenly spaced observations on the surface of a sphere (e.g. the globe).</LI>
+<LI>Added obs_loop.f90 example file in obs_sequence directory; example template for how to construct special purpose obs_sequence tools.</LI>
+<LI>Change the default in the script for the prepbufr converter so it will swap bytes, since all machines except ibms will need this now.</LI>
+</UL>
+
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<A NAME="Diagnostics"></A>
+<H2>New or updated DART Diagnostics</H2>
+<P>
+This section describes new or updated diagnostic
+routines that have been added since the Kodiak release.
+</P>
+
+<UL>
+<LI>Handle empty epochs in the obs_seq_to_netcdf converter.</LI>
+<LI>Added a matlab utility to show the output of a 'hop' test (running a model for a continuous period vs. stopping and restarting a run).</LI>
+<LI>The obs_common_subset program can select common observations from up to 4 observation sequence files at a time.</LI>
+<LI>Add code in obs_seq_verify to ensure that the ensemble members are in the same order in all netcdf files.</LI>
+<LI>Added support for the unstructured grids of mpas to our matlab diagnostics.</LI>
+<LI>Fix to writing of ReportTime in obs_seq_coverage.</LI>
+<LI>Fixed logic in obs_seq_verify when determining the forecast lat.</LI>
+<LI>Fixed loops inside obs_seq_coverage which were using the wrong limits on the loops. Fixed writing of 'ntimes' in output netcdf variable.</LI>
+<LI>Rewrote the algorithm in the obs_selection tool so it had better scaling with large numbers of obs.</LI>
+<LI>Added preliminary support for a list of 'trusted obs' in the obs_diag program. Can disable the rank histogram generation with a namelist item. can define height_edges or heights in the namelist, but not both.</LI>
+<LI>Extend obs_seq_verify so it can be used for forecasts from a single member. minor changes to obs_selection, obs_seq_coverage and obs_seq_verify to support a single member.</LI>
+<LI>Added Matlab script to read/print timestamps from binary dart restart/ic files.</LI>
+<LI>Default for obs_seq_to_netcdf in all the namelists is now 'one big time bin' so you don't have to know the exact timespan of an obs_seq.final file before converting to netCDF.</LI>
+</UL>
+
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<A NAME="Misc"></A>
+<H2>Tutorial, Scripting, Setup, Builds</H2>
+<P>
+This section describes
+updates and changes to the tutorial materials,
+scripting, setup, and build information
+since the Kodiak release.
+</P>
+
+
+<UL>
+<LI>Make the default input.nml for the Lorenz 96 and Lorenz 63 model gives good assimilation results. Rename the original input.nml to input.workshop.nml. The workshop_setup script renames it back before doing anything else so this won't break the workshop instructions. Simplify all the workshop_setup.csh scripts to do the minimal work needed by the DART tutorial.</LI>
+<LI>Updates to the models/template directory with the start of a full 3d geophysical model template. Still under construction.</LI>
+<LI>Move the pdf files in the tutorial directory up a level. routines that generate diagrams/figures are moved to the DAReS/group/DART_tutorial dir. framemaker files removed because we don't have a working version to update or read them with.</LI>
+<LI>Enable netCDF large file support in the work/input.nml for models which are likely to have large state vectors.</LI>
+<LI>Minor updates to the doc.css file, make pages look identical in the safari and firefox browsers.</LI>
+<LI>Added a utility that sorts and reformats namelists, culls all comments to the bottom of the file. Useful for doing diffs and finding duplicated namelists in a file.</LI>
+<LI>Cleaned up mkmf files - removed files for obsolete platforms and compilers, updated suggested default flags for intel.</LI>
+<LI>Update the mkmf template for gfortran to allow fortran source lines longer than 132 characters.</LI>
+</UL>
+
+
+<!--==================================================================-->
+<!-- Legalese & Metadata -->
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<a name="Legalese"></a>
+<h2>Terms of Use</h2>
+
+<p>
+DART software - Copyright 2004 - 2013 UCAR.<br />
+This open source software is provided by UCAR, "as is",<br />
+without charge, subject to all terms of use at<br />
+<a href="http://www.image.ucar.edu/DAReS/DART/DART_download">
+http://www.image.ucar.edu/DAReS/DART/DART_download</a>
+</p>
+
+<table border=0 cellpadding=0 width=100% summary="">
+<tr><td valign=top>Contact:</td><td> DART core group </td></tr>
+<tr><td>Revision: </td><td> $Revision$ </td></tr>
+<tr><td>Source: </td><td> $URL$ </td></tr>
+<tr><td>Change Date: </td><td> $Date$ </td></tr>
+<tr><td valign=top>Change history: </td><td> try "svn log" or "svn diff" </td></tr>
+</table>
+
+<!--==================================================================-->
+
+</body>
+</html>
Property changes on: DART/trunk/doc/html/Lanai_diffs_from_Kodiak.html
___________________________________________________________________
Added: svn:mime-type
+ text/html
Added: svn:keywords
+ Date Rev Author HeadURL Id
Added: svn:eol-style
+ native
Added: DART/trunk/doc/html/Lanai_release.html
===================================================================
--- DART/trunk/doc/html/Lanai_release.html (rev 0)
+++ DART/trunk/doc/html/Lanai_release.html 2013-08-01 16:20:07 UTC (rev 6354)
@@ -0,0 +1,3189 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>DART Lanai Release Notes</title>
+<link rel="stylesheet" type="text/css" href="doc.css" />
+<link href="../images/dart.ico" rel="shortcut icon" />
+</head>
+<body>
+<a name="TOP"></a>
+
+<h1>DART Lanai Release Notes</h1>
+
+<table border=0 summary="" cellpadding=5>
+<tr>
+ <td valign=middle>
+ <img src="../images/Dartboard7.png" alt="DART project logo" height=70 />
+ </td>
+ <td>
+ <p>Jump to DART Documentation Main Index
+ <a href="https://proxy.subversion.ucar.edu/DAReS/DART/releases/Kodiak/index.html">Website</a>
+ or <a href="../../index.html">local file</a><br />
+ <small><small>version information for this file: <br />
+ <!-- version tag follows, do not edit -->
+ $Id$</small></small>
+ </p></td>
+</tr>
+</table>
+
+<a href="#Overview">Dart Overview</a> /
+<a href="#GettingStarted">Getting Started</a> /
+<a href="#Installation">Installation</a> /
+<a href="#CurrentUsers">Notes for Current Users</a> /
+<a href="#Nonbackward">Non-backwards Compatible Changes</a> /
+<a href="#NewFeatures">New Features</a> /
+<a href="#NewModels">New Models</a> /
+<a href="#ChangedModels">Changed Models</a> /
+<a href="#NewObs">New Observations</a> /
+<a href="#NewDiagnostics">New Diagnostics and Documentation</a> /
+<a href="#NewUtilities">New Utilities</a> /
+<a href="#KnownProblems">Known Problems</a> /
+<a href="#Legalese">Terms of Use</a>
+
+<!--==================================================================-->
+
+<a name="Overview"></a>
+<h2>Dart Overview</h2>
+
+<p>The Data Assimilation Research Testbed (DART) is designed to
+facilitate the combination of assimilation algorithms, models,
+and real (or synthetic) observations to allow
+increased understanding of all three.
+The DART programs are highly portable, having been
+compiled with many Fortran 90 compilers
+and run on linux compute-servers, linux clusters, OSX laptops/desktops,
+SGI Altix clusters, supercomputers running AIX, and more.
+Read the
+<a href="#customizations">Customizations</a> section
+for help in building on new platforms.</p>
+
+<p>
+DART employs a modular programming approach to apply an Ensemble Kalman Filter
+which adjusts model values toward a state that is more consistent with information
+from a set of observations. Models may be swapped in and out, as can
+different algorithms in the Ensemble Kalman Filter. The method
+requires running multiple instances of a model to generate an ensemble of
+states. A forward operator appropriate for the type of observation being assimilated
+is applied to each of the states to generate the model's estimate of the observation.
+Comparing these estimates and their uncertainty to the observation and
+its uncertainty ultimately results in the adjustments to the model states.
+See the DARTLAB demos or read more in the tutorials included with the
+DART distribution. They are described below.<p>
+
+<p>
+DART diagnostic output includes two netCDF files containing
+the model states just before
+the adjustment (<em class=file>Prior_Diag.nc</em>) and just after the adjustment
+(<em class=file>Posterior_Diag.nc</em>) as well as a file
+<em class=file>obs_seq.final</em> with the model estimates of the observations.
+There is a suite of Matlab® functions that facilitate exploration of the
+results, but the netCDF files are inherently portable and contain all the
+necessary metadata to interpret the contents with other analysis programs
+such as NCL, R, etc.
+</p>
+
+<p>In this document links are available which point to Web-based documentation
+files and also to the same information in html files distributed with DART.
+If you have used subversion to check out a local copy of the DART files you
+can open this file in a browser by loading
+<em class=file>DART/doc/html/Lanai_release.html</em>
+and then use the <em class=file>local file</em> links to see
+other documentation pages without requiring a connection to
+the internet.
+If you are looking at this documentation from
+the <em class=file>www.image.ucar.edu</em> web server or you are
+connected to the internet you can use the
+<em class=file>Website</em> links to view other documentation pages.
+</p>
+
+<!--==================================================================-->
+
+<a name="GettingStarted"></a>
+<h2>Getting Started</h2>
+
+<h3>What's Required</h3>
+<ol><li>a Fortran 90 compiler</li>
+ <li>a netCDF library including the F90 interfaces</li>
+ <li>the C shell</li>
+ <li>(optional, to run in parallel) an MPI library</li>
+</ol>
+<p>
+DART has been tested on many Fortran compilers and platforms.
+We don't have any platform-dependent code sections and we use
+only the parts of the language that are portable across all
+the compilers we have access to.
+We explicitly set the Fortran 'kind' for all real values and do
+not rely on autopromotion or other compile-time flags to set the
+default byte size for numbers.
+It is possible that some model-specific interface code from
+outside sources may have specific compiler flag requirements;
+see the documentation for each model.
+The low-order models and all common portions of the DART code
+compile cleanly.
+<br />
+<br />
+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.
+<br />
+<br />
+Since most of the models being used with DART are
+written in Fortran and run on various UNIX or *nix platforms, the
+development environment for DART is highly skewed to these machines.
+We do most of our development on a small linux workstation and a mac laptop
+running OSX 10.x, and we have an extensive test network.
+(I've never built nor run DART on a Windows machine - so I don't even
+know if it's possible. If you have run it (under Cygwin?) please let me
+know how it went -- I'm curious. Tim - thoar 'at' ucar 'dot ' edu)
+</p>
+
+<h3>What's nice to have</h3>
+
+<strong>ncview</strong>: DART users have used
+<a href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html">ncview</a>
+to create graphical displays of output data fields. The 2D rendering is
+good for 'quick-look' type uses, but I wouldn't want to publish with it.
+<br /><br />
+
+<strong>NCO</strong>: The <a href="http://nco.sourceforge.net">NCO</a> tools
+are able to perform operations on netCDF files like concatenating, slicing,
+and dicing.<br /><br />
+
+<strong>Matlab</strong>®: A set of
+<a href="http://www.mathworks.com/">Matlab®</a> scripts designed to
+produce graphical diagnostics from DART netCDF output files are also part
+of the DART project.<br /><br />
+
+<strong>MPI</strong>: The DART system includes an MPI
+option. MPI stands for 'Message Passing Interface', and is both a library and
+run-time system that enables multiple copies of a single program to run in
+parallel, exchange data, and combine to solve a problem more quickly.
+DART does <b>NOT</b> require MPI to run; the default build
+scripts do not need nor use MPI in any way. However, for larger models with
+large state vectors and large numbers of observations, the data assimilation
+step will run much faster in parallel, which requires MPI to be installed and
+used. However, if multiple ensembles of your model fit comfortably (in time
+and memory space) on a single processor, you need read no further about MPI.
+<br /><br />
+
+<h3>Types of input</h3>
+
+<p>DART programs can require three different types of input.
+First, some of the DART programs, like 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>, which 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 in a custom format in either
+human-readable ascii or more compact machine-specific binary.
+Third, many DART modules (including main programs) make use of
+the Fortran90 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.
+</p>
+
+<!--==================================================================-->
+
+<h2>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>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<a name="Installation"></a>
+<h2>Installation</h2>
+
+<p>
+This document outlines the installation of the DART software
+and the system requirements. 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="#download">Download the DART software
+ 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>
+
+<p>You should <i>absolutely</i> run the DARTLAB
+interactive tutorial (if you have Matlab available) and look at the
+DARTLAB presentation slides
+<a href="https://proxy.subversion.ucar.edu/DAReS/DART/releases/Kodiak/DART_LAB/DART_LAB.html">
+Website</a> or <a href="../../DART_LAB/DART_LAB.html">local file</a>
+in the
+<em class="file">DART_LAB</em> directory, and then take the tutorial
+in the <em class="file">DART/tutorial</em> directory.</p>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<a name="compilers"></a>
+<h3>Requirements: an F90 Compiler</h3>
+
+<p>
+The DART software has been successfully built on several Linux/x86
+platforms with several versions of the
+<a href="http://www.intel.com/software/products/compilers/flin">Intel Fortran
+Compiler for Linux</a>, which (at one point) is/was free for individual
+scientific use. Also Intel Fortran for Mac OSX.
+It has also been built and successfully run with several
+versions of each of the following:
+<a href="http://www.pgroup.com">Portland Group Fortran Compiler</a>,
+<a href="http://www.lahey.com">Lahey Fortran Compiler</a>,
+<a href="http://www.pathscale.com">Pathscale Fortran Compiler</a>,
+<a href="http://gcc.gnu.org/fortran">GNU Fortran 95 Compiler ("gfortran")</a>,
+<a href="http://www.absoft.com">Absoft Fortran 90/95 Compiler (Mac OSX)</a>.
+Since recompiling the code is a necessity to experiment
+with different models, there are no binaries to distribute.
+</p>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<a name="netCDFlib"></a>
+<h3>Requirements: the <em class=file>netCDF</em> library</h3>
+
+<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 is 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. Depending on the netCDF build options, the Fortran 90
+interfaces may be built in a separate library named
+<em class=file>netcdff.a</em> and you may need to add
+<em class=code>-lnetcdff</em> to the library flags.
+</p>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<a name="download"></a>
+<h2>Downloading the distribution.</h2>
+
+<p>
+<strong>HURRAY</strong>! The DART source code is now distributed through
+an anonymous Subversion server! The <strong>big</strong> advantage is
+the ability to patch or update existing code trees at your discretion.
+Subversion (the client-side app
+is '<strong>svn</strong>') allows you to compare your code tree with
+one on a remote server and selectively update individual files or groups of
+files. Furthermore, now everyone has access to any version of any file in
+the project, which is a huge help for developers. I have a brief summary of
+the svn commands I use most posted at:
+<a href="http://www.image.ucar.edu/~thoar/svn_primer.html">
+http://www.image.ucar.edu/~thoar/svn_primer.html</a>
+</p>
+<p>
+The resources to develop and support DART come from our ability to
+demonstrate our growing user base. We ask that you register at our
+download site <a href="http://www.image.ucar.edu/DAReS/DART/DART_download">
+http://www.image.ucar.edu/DAReS/DART/DART_download</a>
+and promise that the information will only be used to notify you
+of new DART releases and shown to our sponsers in an aggregated form:
+"Look - we have three users from Tonawanda, NY". After filling in the form,
+you will be directed to a website that has instructions on how to download
+the code.
+</p>
+<p>
+svn has adopted the strategy that "disk is cheap". In addition to downloading
+the code, it downloads an additional copy of the code to store locally (in
+hidden .svn directories) as well as some administration files. This allows
+svn to perform some commands even when the repository is not available.
+It does double the size of the code tree for the initial download, but then
+future updates download just the changes, so they usually happen very quickly.
+</p>
+<p>
+If you follow the instructions on the download site, you should wind up with
+a directory named <em class=file>DART</em>. Compiling the code in this tree
+(as is usually the case) will necessitate much more space.
+</p>
+<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>
+
+<!--==================================================================-->
+
+<div><hr /><p align=right><a href="#"><small>[top]</small></a></p></div>
+<a name="customizations"></a>
+<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 very 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.<em class=program><i>program</i>_default</em></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.<em class=program><i>program</i>_default</em></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 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.gfortran</em>) is needed.
+Note that only the LAST lines are shown here,
+the head of the file is just a big comment (worth reading, btw).
+</p>
+
+<div class=routine>
+...<br />
+MPIFC = mpif90 <br />
+MPILD = mpif90 <br />
+FC = gfortran <br />
+LD = gfortran <br />
+NETCDF = /usr/local <br />
+INCS = ${NETCDF}/include <br />
+FFLAGS = -O2 -I$(INCS) <br />
+LIBS = -L${NETCDF}/lib -lnetcdf <br />
+LDFLAGS = -I$(INCS) $(LIBS) <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 = gfortran</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>NETCDF</em>, which
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list