[Dart-dev] [5005] DART/trunk/models/NCOMMAS: This is long-overdue documentation for NCOMMAS.
nancy at ucar.edu
nancy at ucar.edu
Mon Jun 13 17:21:06 MDT 2011
Revision: 5005
Author: thoar
Date: 2011-06-13 17:21:06 -0600 (Mon, 13 Jun 2011)
Log Message:
-----------
This is long-overdue documentation for NCOMMAS.
The model_mod.html still needs quite a bit of work in the Description
section, but all the interfaces are believed to be accurate.
Modified Paths:
--------------
DART/trunk/models/NCOMMAS/model_mod.f90
DART/trunk/models/NCOMMAS/model_mod.nml
Added Paths:
-----------
DART/trunk/models/NCOMMAS/dart_ncommas_mod.html
DART/trunk/models/NCOMMAS/dart_to_ncommas.html
DART/trunk/models/NCOMMAS/model_mod.html
DART/trunk/models/NCOMMAS/ncommas_to_dart.html
-------------- next part --------------
Added: DART/trunk/models/NCOMMAS/dart_ncommas_mod.html
===================================================================
--- DART/trunk/models/NCOMMAS/dart_ncommas_mod.html (rev 0)
+++ DART/trunk/models/NCOMMAS/dart_ncommas_mod.html 2011-06-13 23:21:06 UTC (rev 5005)
@@ -0,0 +1,907 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<HTML>
+<HEAD>
+<TITLE>module dart_ncommas_mod</TITLE>
+<link rel="stylesheet" type="text/css" href="../../doc/html/doc.css" />
+</HEAD>
+<BODY>
+<A NAME="TOP"></A>
+
+<table border=0 summary="" cellpadding=5>
+<tr>
+ <td valign=middle>
+ <img src="../../doc/html/Dartboard9.png" alt="DART project logo" height=70 />
+ </td>
+ <td>
+ <P><a href="../../index.html">DART Documentation Main Index</a><br />
+ <small>version information for this file: <br />
+ <!-- version tag follows, do not edit -->
+ $Id$</small>
+ </P></td>
+</tr>
+</table>
+
+<A HREF="#Namelist">NAMELIST</A> /
+<A HREF="#Interface">INTERFACES</A> /
+<A HREF="#FilesUsed">FILES</A> /
+<A HREF="#References">REFERENCES</A> /
+<A HREF="#Errors">ERRORS</A> /
+<A HREF="#FuturePlans">PLANS</A> /
+<A HREF="#PrivateComponents">PRIVATE COMPONENTS</A> /
+<A HREF="#Legalese">TERMS OF USE</A>
+
+<H1>MODULE dart_ncommas_mod (ncommas)</H1>
+
+<P>
+ <em class=program>dart_ncommas_mod</em> provides a consistent collection
+ of routines that are useful for multiple programs e.g.
+ <em class=program>dart_to_ncommas</em>,
+ <em class=program>ncommas_to_dart</em>, etc.
+</P>
+
+<!--==================================================================-->
+<!--=================== DESCRIPTION OF A NAMELIST ===================-->
+<!--==================================================================-->
+
+<A NAME="Namelist"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>NAMELIST</H2>
+<P>There are no namelists unique to this module.
+It is necessary for this module to read some of the ncommas namelists,
+and so they are declared in this module. In one instance, DART
+will read the <em class=code>time_manager_nml</em> namelist and <b>write</b>
+an updated version to control the length of the integration of ncommas.
+All other information is simply read from the namelists and is used
+in the same context as ncommas itself. The ncommas documentation should be
+consulted. <strong>Only the variables of interest to DART are described in
+this document.</strong>
+<br />
+<br />
+All namelists are read from a file named <em class=file>ncommas_in</em>.
+</P>
+
+<!--==================================================================-->
+
+<A NAME="time_manager_nml"></A>
+<div class=namelist><pre>
+<em class=call>namelist /time_manager_nml/ </em> allow_leapyear, stop_count, stop_option
+</pre></div>
+<div class=indent1><!-- Description -->
+<P>
+ <em class=program>dart_to_ncommas</em> controls the model advance of LANL/ncommas
+ by creating a <em class=code>&time_manager_nml</em> in
+ <em class=file>ncommas_in.DART</em> <strong>IFF</strong> the DART state being
+ converted has the 'advance_to_time' record.
+ The <em class=file>ncommas_in.DART</em> must be concatenated
+ with the other namelists needed by ncommas into a file called
+ <em class=file>ncommas_in</em> . We have chosen to store the other
+ namelists (which contain static information) in a file called
+ <em class=file>ncommas_in.part2</em>. Initially, the
+ <em class=code>time_manager_nml</em> is stored in a companion file called
+ <em class=file>ncommas_in.part1</em> and the two files are concatenated into
+ the expected <em class=file>ncommas_in</em> - then, during the course of an
+ assimilation experiment, DART keeps writing out a new
+ <em class=code>time_manager_nml</em> with new integration information -
+ which gets appended with the static information in
+ <em class=file>ncommas_in.part2</em>
+</P>
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>allow_leapyear </TD>
+ <!-- type --><TD valign=top>logical</TD>
+ <!--descript--><TD valign=top>DART ignores the setting of this parameter.
+ All observations must use a Gregorian calendar.
+ There are pathological cases, but if you are doing data assimilation,
+ just use the Gregorian calendar.
+ <em class=units>[default: .true.]</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>stop_count</TD>
+ <!-- type --><TD valign=top>integer</TD>
+ <!--descript--><TD valign=top>the number of model advance steps to take.
+ <em class=units>[default: 1]</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>stop_option</TD>
+ <!-- type --><TD valign=top>character(len=64) </TD>
+ <!--descript--><TD valign=top>The units for the number of model advance
+ steps (<em class=code>stop_count</em>) to take.
+ <em class=units>[default: 'ndays']</em>
+ </TD></TR>
+
+</TABLE>
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="io_nml"></A>
+<div class=namelist><pre>
+<em class=call>namelist /io_nml/ </em> luse_pointer_files, pointer_filename
+</pre></div>
+
+<div class=indent1><!-- Description -->
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>luse_pointer_files</TD>
+ <!-- type --><TD valign=top>logical</TD>
+ <!--descript--><TD valign=top>switch to indicate the use of pointer files
+ or not. If <em class=code>.true.</em>, a pointer file is used to contain
+ the name of the restart file to be used.
+ DART requires this to be <em class=code>.true</em>.
+ <em class=units>[default: .true.]</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>pointer_filename</TD>
+ <!-- type --><TD valign=top>character(len=100)</TD>
+ <!--descript--><TD valign=top>The name of the pointer file. All of
+ the DART scripts presume and require the use of the default.
+ Each ensmeble member gets its own pointer file.
+ <em class=units>[default: rpointer.ocn.[1-N].restart]</em>
+ </TD></TR>
+</TABLE>
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="restart_nml"></A>
+<br />
+<div class=namelist><pre>
+<em class=call>namelist /restart_nml/ </em> restart_freq_opt, restart_freq
+</pre></div>
+
+<div class=indent1><!-- Description -->
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>luse_pointer_files </TD>
+ <!-- type --><TD valign=top>logical</TD>
+ <!--descript--><TD valign=top>switch to indicate the use of pointer files
+ or not. If <em class=code>.true.</em>, a pointer file is used to contain
+ the name of the restart file to be used.
+ DART requires this to be <em class=code>.true</em>.
+ <em class=units>[default: .true.]</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>pointer_filename</TD>
+ <!-- type --><TD valign=top>character(len=100) </TD>
+ <!--descript--><TD valign=top>The name of the pointer file. All of
+ the DART scripts presume and require the use of the default.
+ Each ensmeble member gets its own pointer file.
+ <em class=units>[default: rpointer.ocn.[1-N].restart]</em>
+ </TD></TR>
+</TABLE>
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="init_ts_nml"></A>
+<br />
+<div class=namelist><pre>
+<em class=call>namelist /init_ts_nml/ </em> init_ts_option, init_ts_file, init_ts_file_fmt
+</pre></div>
+
+<div class=indent1><!-- Description -->
+<P>
+ The <em class=program>dart_ncommas_mod:initialize_module()</em> routine reads
+ <em class=file>ncommas_in</em> . There are several code stubs for future
+ use that may allow for a more fully-supported ncommas namelist implementation.
+ This namelist is one of them. Until further notice,
+ the <em class=code>init_ts_nml</em> is completely ignored by DART.
+</P>
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>init_ts_option</TD>
+ <!-- type --><TD valign=top>character(len=64)</TD>
+ <!--descript--><TD valign=top>NOT USED by DART. All T,S information
+ comes from a netCDF restart file named <em class=file>ncommas.r.nc</em>
+ <em class=units>[default: 'restart']</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>init_ts_file</TD>
+ <!-- type --><TD valign=top>character(len=100) </TD>
+ <!--descript--><TD valign=top>NOT USED by DART. All T,S information
+ comes from <em class=file>ncommas.r.nc</em>
+ <em class=units>[default: 'ncommas.r']</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>init_ts_file_fmt </TD>
+ <!-- type --><TD valign=top>character(len=64)</TD>
+ <!--descript--><TD valign=top>NOT USED by DART.
+ The file format is <em class=code>'nc'</em>
+ <em class=units>[default: 'nc']</em>
+ </TD></TR>
+</TABLE>
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="domain_nml"></A>
+<br />
+<div class=namelist><pre>
+<em class=call>namelist /domain_nml/ </em> ew_boundary_type
+</pre></div>
+
+<div class=indent1><!-- Description -->
+<P>DART needs to know if the East-West domain is cyclic for spatial interpolations.
+Presently, DART has only been tested for the dipole grid, which is cyclic E-W and
+closed N-S.
+</P>
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>ew_boundary_type </TD>
+ <!-- type --><TD valign=top>character(len=64) </TD>
+ <!--descript--><TD valign=top>switch to indicate whether the East-West
+ domain is cyclic or not. DART/ncommas has not been tested in a regional
+ configuration, so DART requires this to be <em class=code>'cyclic'</em>.
+ <em class=units>[default: 'cyclic']</em>
+ </TD></TR>
+
+</TABLE>
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="grid_nml"></A>
+<br />
+<div class=namelist><pre>
+<em class=call>namelist /grid_nml/ </em> horiz_grid_opt, vert_grid_opt, topography_opt, &
+ horiz_grid_file, vert_grid_file, topography_file
+</pre></div>
+
+<div class=indent1><!-- Description -->
+<P>
+The ncommas grid information comes in several files:
+horizontal grid lat/lons in one,
+the vertical grid spacing in another, and the
+topography (lowest valid vertical level) in a third.
+<br />
+<br />
+Here is what we can get from the (binary) horizontal grid file:
+</P>
+<pre>
+real(r8), dimension(:,:) :: ULAT, &! latitude (radians) of U points
+real(r8), dimension(:,:) :: ULON, &! longitude (radians) of U points
+real(r8), dimension(:,:) :: HTN , &! length (cm) of north edge of T box
+real(r8), dimension(:,:) :: HTE , &! length (cm) of east edge of T box
+real(r8), dimension(:,:) :: HUS , &! length (cm) of south edge of U box
+real(r8), dimension(:,:) :: HUW , &! length (cm) of west edge of U box
+real(r8), dimension(:,:) :: ANGLE &! angle
+</pre>
+<P>
+The vertical grid file is ascii, with 3 columns/line:
+</P>
+<pre>cell thickness(in cm) cell center(in m) cell bottom(in m)</pre>
+<P>
+Here is what we can get from the topography file:
+</P>
+<pre>
+integer, dimension(:,:), :: KMT &! k index of deepest grid cell on T grid
+</pre>
+<P>
+These must be derived or come from someplace else ...
+</P>
+<pre>
+KMU k index of deepest grid cell on U grid
+HT real(r8) value of deepest valid T depth (in cm)
+HU real(r8) value of deepest valid U depth (in cm)
+</pre>
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>horiz_grid_opt, vert_grid_opt, topography_opt</TD>
+ <!-- type --><TD valign=top>character(len=64)</TD>
+ <!--descript--><TD valign=top>switch to indicate whether or not the grids
+ will come from an external file or not. DART requires ALL of these to be
+ <em class=code>'file'</em>.
+ <em class=units>[default: 'file']</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>horiz_grid_file</TD>
+ <!-- type --><TD valign=top>character(len=100)</TD>
+ <!--descript--><TD valign=top>The name of the binary file containing the
+ values for the horizontal grid. The <strong>dimensions</strong> of the
+ grid are read from <em class=file>ncommas.r.nc</em>. It would have been nice
+ to include the actual grid information in the netCDF files.
+ <em class=units>[default: 'horiz_grid.gx3v5.r8ieee.le']</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>vert_grid_file</TD>
+ <!-- type --><TD valign=top>character(len=100)</TD>
+ <!--descript--><TD valign=top>The name of the ASCII file containing the
+ values for the vertical grid. The file must contain three columns of data
+ pertaining to the cell thickness (in cm), the cell center (in meters), and the
+ cell bottom (in meters). Again, it would have been nice
+ to include the vertical grid information in the netCDF files.
+ <em class=units>[default: 'vert_grid.gx3v5']</em>
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>topography_grid_file</TD>
+ <!-- type --><TD valign=top>character(len=100)</TD>
+ <!--descript--><TD valign=top>The name of the binary file containing the
+ values for the topography information. The <strong>dimensions</strong> of the
+ grid are read from <em class=file>ncommas.r.nc</em>.
+ <em class=units>[default: 'topography.gx3v5.r8ieee.le']</em>
+ </TD></TR>
+</TABLE>
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="OtherModulesUsed"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>OTHER MODULES USED</H2>
+
+<PRE>
+types_mod
+time_manager_mod
+utilities_mod
+typesizes
+netcdf
+</PRE>
+
+<!--==================================================================-->
+<!-- Note to authors. The first row of the table is different. -->
+<!--==================================================================-->
+<!-- Declare all public entities ... -->
+<!-- duplicate public routines template as many times as necessary -->
+<!-- make sure you replace all yyyroutine?? strings -->
+<!--==================================================================-->
+
+<A NAME="Interface"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>PUBLIC INTERFACES</H2>
+
+<P>
+Only a select number of interfaces used are discussed here.
+Each module has its own discussion of their routines.
+</P>
+
+<h3 class=indent1>Interface Routines</h3>
+<TABLE width=80%>
+<TR><TD><em class=call>use dart_ncommas_mod, only : </em></TD>
+ <TD><A HREF="#get_ncommas_calendar">get_ncommas_calendar</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#set_model_time_step">set_model_time_step</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_horiz_grid_dims">get_horiz_grid_dims</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_vert_grid_dim">get_vert_grid_dim</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#read_horiz_grid">read_horiz_grid</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#read_topography">read_topography</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#read_vert_grid">read_vert_grid</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#write_ncommas_namelist">write_ncommas_namelist</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_ncommas_restart_filename">get_ncommas_restart_filename</A></TD></TR>
+</TABLE>
+
+<!--==================================================================-->
+<H3 class=indent1>Required Interface Routines</H3>
+<!--==================================================================-->
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="get_ncommas_calendar"></A>
+<br />
+<div class=routine>
+<em class=call>call get_ncommas_calendar(calstring)</em>
+<pre>
+character(len=*), intent(out) :: <em class=code>calstring</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+Returns a string containing the type of calendar in use.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>calstring</em></TD>
+ <TD>DART/ncommas uses a 'gregorian' calendar.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="set_model_time_step"></A>
+<br />
+<div class=routine>
+<em class=call>ncommastimestep = set_model_time_step()</em>
+<pre>
+type(time_type), intent(out) :: <em class=code>ncommastimestep</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>set_model_time_step</em>
+returns the model time step that was set in the
+<a href="#restart_nml">restart_nml</a><em class=code>restart_freq</em>.
+This is the minimum amount of time DART thinks the ncommas model can advance.
+Indirectly, this specifies the minimum assimilation interval.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>ncommastimestep</em></TD>
+ <TD>the minimum assimilation interval</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="get_horiz_grid_dims"></A>
+<br />
+<div class=routine>
+<em class=call>call get_horiz_grid_dims(Nx, Ny)</em>
+<pre>
+integer, intent(out) :: <em class=code>Nx, Ny</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>get_horiz_grid_dims</em>
+reads <em class=file>ncommas.r.nc</em> to determine the number of longitudes and
+latitudes.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>Nx </em></TD>
+ <TD>the length of the 'i' dimension in the ncommas restart file.
+ The number of longitudes in use.</TD></TR>
+
+<TR><TD valign=top><em class=code>Ny </em></TD>
+ <TD>the length of the 'j' dimension in the ncommas restart file.
+ The number of latitudes in use.</TD></TR>
+
+</TABLE>
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="get_vert_grid_dim"></A>
+<br />
+<div class="routine">
+<em class=call>call get_vert_grid_dim( Nz )</em>
+<pre>
+integer, intent(out) :: <em class=code>Nz</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>get_vert_grid_dim</em>
+reads <em class=file>ncommas.r.nc</em> to determine the number of vertical levels
+in use.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>Nz </em></TD>
+ <TD>the length of the 'k' dimension in the ncommas restart file.
+ The number of vertical levels in use.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="read_horiz_grid"></A>
+<br />
+<div class="routine">
+<em class=call>call read_horiz_grid(nx, ny, ULAT, ULON, TLAT, TLON)</em>
+<pre>
+integer, intent(in) :: <em class=code>nx, ny</em>
+real(r8), dimension(nx,ny), intent(out) :: <em class=code>ULAT, ULON, TLAT, TLON</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>read_horiz_grid</em> reads the direct access binary files
+containing the ncommas grid information.
+<strong>The first record is REQUIRED to be 'ULAT',
+the second record is REQUIRED to be 'ULON'.</strong>
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>nx </em></TD>
+ <TD>The number of longitudes in the grid.</TD></TR>
+
+<TR><TD valign=top><em class=code>ny </em></TD>
+ <TD>The number of latitudes in the grid.</TD></TR>
+
+<TR><TD valign=top><em class=code>ULAT </em></TD>
+ <TD>The matrix of latitudes for the UVEL and VVEL variables.
+ Units are degrees [-90,90].</TD></TR>
+
+<TR><TD valign=top><em class=code>ULON </em></TD>
+ <TD>The matrix of longitudes for the UVEL and VVEL variables.
+ Units are degrees. [0,360] </TD></TR>
+
+<TR><TD valign=top><em class=code>TLAT </em></TD>
+ <TD>The matrix of latitudes for the SALT and TEMP variables.
+ Units are degrees [-90,90].</TD></TR>
+
+<TR><TD valign=top><em class=code>TLON </em></TD>
+ <TD>The matrix of longitudes for the SALT and TEMP variables.
+ Units are degrees. [0,360] </TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="read_topography"></A>
+<br />
+<div class="routine">
+<em class=call>call read_topography(nx, ny, KMT, KMU)</em>
+<pre>
+integer, intent(in) :: <em class=code>nx, ny</em>
+integer, dimension(nx,ny), intent(out) :: <em class=code>KMT, KMU</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>read_topography</em> reads the direct access binary files
+containing the ncommas topography information.
+<strong>The first record is REQUIRED to be 'KMT'.</strong>
+'KMU' is calculated from 'KMT'.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>nx </em></TD>
+ <TD>The number of longitudes in the grid.</TD></TR>
+
+<TR><TD valign=top><em class=code>ny </em></TD>
+ <TD>The number of latitudes in the grid.</TD></TR>
+
+<TR><TD valign=top><em class=code>KMT </em></TD>
+ <TD>The matrix containing the lowest valid depth index
+ at grid centroids.</TD></TR>
+
+<TR><TD valign=top><em class=code>KMU </em></TD>
+ <TD>The matrix containing the lowest valid depth index
+ at grid corners.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="read_vert_grid"></A>
+<br />
+<div class="routine">
+<em class=call>call read_vert_grid(nz, ZC, ZG)</em>
+<pre>
+integer, intent(in) :: <em class=code>nz</em>
+real(r8), dimension(nz), intent(out) :: <em class=code>ZC, ZG</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>read_vert_grid</em> reads the ASCII file
+containing the information about the vertical levels.
+The file must contain three columns of data pertaining to;
+1) the cell thickness (in cm),<br />
+2) the cell center (in meters),<br /> and
+3) the cell bottom (in meters).
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>nz </em></TD>
+ <TD>The number of vertical levels.</TD></TR>
+
+<TR><TD valign=top><em class=code>ZC </em></TD>
+ <TD>The depth (in meters) at the grid centers.</TD></TR>
+
+<TR><TD valign=top><em class=code>ZG </em></TD>
+ <TD>The depth (in meters) at the grid edges.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="write_ncommas_namelist"></A>
+<br />
+<div class="routine">
+<em class=call>call write_ncommas_namelist(model_time, adv_to_time)</em>
+<pre>
+type(time_type), intent(in) :: <em class=code>model_time</em>
+type(time_type), intent(in) :: <em class=code>adv_to_time</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>write_ncommas_namelist</em> writes the ncommas namelist
+<em class=code>time_manager_nml</em> with the information necessary
+to advance ncommas to the next assimilation time. The namelist is written
+to a file called <em class=code>ncommas_in.DART</em>. Presently, DART is
+configured to minimally advance ncommas for 86400 seconds - i.e. 1 day.
+The forecast length (the difference between 'model_time' and 'adv_to_time')
+must be an integer number of days with the current setup. An error will
+result if it is not.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>model_time </em></TD>
+ <TD>The 'valid' time of the current model state.</TD></TR>
+
+<TR><TD valign=top><em class=code>adv_to_time </em></TD>
+ <TD>The time of the next assimilation.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="get_ncommas_restart_filename"></A>
+<br />
+<div class="routine">
+<em class=call>call get_ncommas_restart_filename( filename )</em>
+<pre>
+character(len=*), intent(out) :: <em class=code>filename</em>
+</pre>
+</div>
+
+<div class=indent1><!-- Description -->
+
+<P>
+<em class=code>get_ncommas_restart_filename</em> returns the filename
+containing the ncommas restart information. At this point the filename
+is <strong>hardwired</strong> to <em class=file>ncommas.r.nc</em>,
+but may become more flexible in future versions.
+The filename may be derived from the <em class=code>restart_nml</em>
+but is currently ignored.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>filename </em></TD>
+ <TD>The name of the ncommas restart file.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--==================================================================-->
+<!-- Describe the Files Used by this module. -->
+<!--==================================================================-->
+
+<A NAME="FilesUsed"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>FILES</H2>
+
+<TABLE border=0 width=100%>
+<TR><TH align=left>filename</TH>
+ <TH align=left>purpose</TH></TR>
+<TR><TD>ncommas_in</TD>
+ <TD>to read the ncommas namelists</TD></TR>
+<TR><TD>ncommas.r.nc</TD>
+ <TD>provides grid dimensions and 'valid_time' of the model state</TD></TR>
+<TR><TD><em class=code>&grid_nml</em> "horiz_grid_file"</TD>
+ <TD>contains the values of the horizontal grid</TD></TR>
+<TR><TD><em class=code>&grid_nml</em> "vert_grid_file"</TD>
+ <TD>contains the number and values of the vertical levels</TD></TR>
+<TR><TD><em class=code>&grid_nml</em> "topography_grid_file"</TD>
+ <TD>contains the indices of the wet/dry cells</TD></TR>
+<TR><TD>ncommas_in.DART</TD>
+ <TD>to control the integration of the ncommas model advance</TD></TR>
+</TABLE>
+<br />
+
+<!--==================================================================-->
+<!-- Cite references, if need be. -->
+<!--==================================================================-->
+
+<A NAME="References"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>REFERENCES</H2>
+<ul>
+<li> none </li>
+</ul>
+
+<!--==================================================================-->
+<!-- Describe all the error conditions and codes. -->
+<!--==================================================================-->
+
+<A NAME="Errors"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>ERROR CODES and CONDITIONS</H2>
+<div class=errors>
+<TABLE border=1 cellspacing=1 cellpadding=10 width=100%>
+<TR><TH>Routine</TH><TH width="50%">Message</TH><TH>Comment</TH></TR>
+
+<TR><!-- routine --><TD VALIGN=top>initialize_module</TD>
+ <!-- message --><TD VALIGN=top>ncommas_in:init_ts_file ncommas.r.nc not found'
+</TD>
+ <!-- comment --><TD VALIGN=top>The ncommas restart file MUST be called
+ 'ncommas.r.nc'. Make a soft link if necessary.</TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>get_horiz_grid_dims</TD>
+ <!-- message --><TD VALIGN=top>unable to find either 'i' or 'nlon' in file ncommas.r.nc</TD>
+ <!-- comment --><TD VALIGN=top>The ncommas restart file must contain dimensions named either 'i' or 'nlon'.</TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>get_horiz_grid_dims</TD>
+ <!-- message --><TD VALIGN=top>unable to find either 'j' or 'nlat' in file ncommas.r.nc</TD>
+ <!-- comment --><TD VALIGN=top>The ncommas restart file must contain dimensions named either 'j' or 'nlat'.</TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>set_model_time_step</TD>
+ <!-- message --><TD VALIGN=top>restart_freq_opt must be nday</TD>
+ <!-- comment --><TD VALIGN=top>Pretty self-explanatory.
+ The ncommas namelist must specify the forecast length as a multiple of 'days'.
+ </TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>write_ncommas_namelist</TD>
+ <!-- message --><TD VALIGN=top>adv_to_time has seconds == xxx must be zero'</TD>
+ <!-- comment --><TD VALIGN=top>DART is asking ncommas to advance to a time that is
+ a fraction of a day away. This should not be possible.
+ Contact the DART developers.</TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>write_ncommas_namelist</TD>
+ <!-- message --><TD VALIGN=top>stop_option must be "nday"</TD>
+ <!-- comment --><TD VALIGN=top>the ncommas <em class=code>time_manager_nml:stop_option</em>
+ is not set to 'nday'. This is required by DART.</TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>read_horiz_grid</TD>
+ <!-- message --><TD VALIGN=top>ncommas_in:horiz_grid_file 'XYZ' not found</TD>
+ <!-- comment --><TD VALIGN=top>The horizontal grid filename specified in
+ <em class=file>ncommas_in</em><em class=code>grid_nml</em> cannot be found.
+ </TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>calc_tpoints</TD>
+ <!-- message --><TD VALIGN=top>ncommas_in&domain_nml:ew_boundary_type 'X' unknown</TD>
+ <!-- comment --><TD VALIGN=top>The <em class=code>ew_boundary_type</em>
+ must be 'cyclic' - until DART/ncommas gets tested with non-cyclic domains.
+ </TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>read_topography</TD>
+ <!-- message --><TD VALIGN=top>ncommas_in:topography_file 'XYZ' not found</TD>
+ <!-- comment --><TD VALIGN=top>The topography file specified in
+ <em class=file>ncommas_in</em><em class=code>grid_nml</em> cannot be found.
+ </TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>read_vert_grid</TD>
+ <!-- message --><TD VALIGN=top>ncommas_in:vert_grid_file 'XYZ' not found</TD>
+ <!-- comment --><TD VALIGN=top>The vertical grid file specified in
+ <em class=file>ncommas_in</em><em class=code>grid_nml</em> cannot be found.
+ </TD>
+</TR>
+
+<TR><!-- routine --><TD VALIGN=top>read_vert_grid</TD>
+ <!-- message --><TD VALIGN=top>error reading depths, line 'X'</TD>
+ <!-- comment --><TD VALIGN=top>The vertical grid file is corrupt or
+ does not have the expected three pieces of information per line.
+ </TD>
+</TR>
+
+</TABLE>
+</div>
+
+<H2>KNOWN BUGS</H2>
+<P>
+There are no known bugs, but there sure is a lot of dependence on
+assimilating on daily boundaries - and the ncommas.r.nc file.
+</P>
+
+<!--==================================================================-->
+<!-- Describe Future Plans. -->
+<!--==================================================================-->
+
+<A NAME="FuturePlans"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>FUTURE PLANS</H2>
+<P>
+none at this time
+</P>
+
+<!--==================================================================-->
+<!-- PrivateComponents -->
+<!--==================================================================-->
+
+<A NAME="PrivateComponents"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>PRIVATE COMPONENTS</H2>
+<P>
+N/A
+</P>
+
+<!--==================================================================-->
+<!-- Legalese & Metadata -->
+<!--==================================================================-->
+
+<A NAME="Legalese"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>Terms of Use</H2>
+
+<P>
+DART software - Copyright 2004 - 2011 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 valign=top>Revision: </TD><TD> $Revision$ </TD></TR>
+<TR><TD valign=top>Source: </TD><TD> $URL$ </TD></TR>
+<TR><TD valign=top>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/models/NCOMMAS/dart_ncommas_mod.html
___________________________________________________________________
Added: svn:mime-type
+ text/html
Added: svn:keywords
+ Date Rev Author HeadURL Id
Added: svn:eol-style
+ native
Added: DART/trunk/models/NCOMMAS/dart_to_ncommas.html
===================================================================
--- DART/trunk/models/NCOMMAS/dart_to_ncommas.html (rev 0)
+++ DART/trunk/models/NCOMMAS/dart_to_ncommas.html 2011-06-13 23:21:06 UTC (rev 5005)
@@ -0,0 +1,295 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<HTML>
+<HEAD>
+<TITLE>program dart_to_ncommas</TITLE>
+<link rel="stylesheet" type="text/css" href="../../doc/html/doc.css" />
+</HEAD>
+<BODY>
+<A NAME="TOP"></A>
+
+<table border=0 summary="" cellpadding=5>
+<tr>
+ <td valign=middle>
+ <img src="../../doc/html/Dartboard9.png" alt="DART project logo" height=70 />
+ </td>
+ <td>
+ <P><a href="../../index.html">DART Documentation Main Index</a><br />
+ <small>version information for this file: <br />
+ <!-- version tag follows, do not edit -->
+ $Id$</small>
+ </P></td>
+</tr>
+</table>
+
+<A HREF="#Namelist">NAMELIST</A> /
+<A HREF="#Modules">MODULES</A> /
+<A HREF="#FilesUsed">FILES</A> /
+<A HREF="#References">REFERENCES</A> /
+<A HREF="#Errors">ERRORS</A> /
+<A HREF="#FuturePlans">PLANS</A> /
+<A HREF="#Legalese">TERMS OF USE</A>
+
+<H1>PROGRAM <em class=program>dart_to_ncommas</em></H1>
+
+<P>
+ <em class=program>dart_to_ncommas</em> is the program that <strong>updates</strong>
+ a ncommas netCDF-format restart file (usually <em class=file>ncommas_restart.nc</em>)
+ with the state information contained in a DART output/restart file
+ (e.g. <em class=file>perfect_ics, filter_ics, ... </em>).
+ Only the CURRENT values in the ncommas restart file will be updated.
+ The DART model time is compared to the time in the ncommas restart file.
+ If the last time in the restart file does not match the DART model time,
+ the program issues an error message and aborts.
+ <br />
+ <br />
+ From the user perspective, most of the time
+ <em class=program>dart_to_ncommas</em> will be used on DART files that
+ have a header containing one time stamp followed by the model state.
+ <br />
+ <br />
+ The <a href=#Namelist>dart_to_ncommas_nml</a> namelist allows
+ <em class=program>dart_to_ncommas</em> to read the
+ <em class=file>assim_model_state_ic</em> files that have
+ <em class=italic>two</em> timestamps in the header. These files are
+ temporarily generated when DART is used to advance the model.
+ One timestamp is the 'advance_to' time, the other is the 'valid_time'
+ of the model state. In this case, a namelist for ncommas (called
+ <em class=file>ncommas_in.DART</em>) is written that contains the
+ <em class=code>&time_manager_nml</em> settings appropriate to
+ advance ncommas to the time requested by DART. The repository version
+ of the <em class=program>advance_model.csh</em> script has a section
+ to ensure the proper DART namelist settings for this case.
+ <br />
+ <br />
+ Conditions required for successful execution of <em class=program>dart_to_ncommas</em>:
+</P>
+
+<UL>
+ <LI>a valid <em class=file>input.nml</em> namelist file for DART</LI>
+ <LI>a valid <em class=file>ncommas_vars.nml</em> namelist file for ncommas -
+ the same one used to create the DART state vector, naturally,</LI>
+ <LI>a DART file (typically <em class=file>filter_restart.xxxx</em> or
+ <em class=file>filter_ics.xxxx</em>)</LI>
+ <LI>a ncommas restart file (typically <em class=file>ncommas_restart.nc</em>).</LI>
+</UL>
+
+<P>
+Since this program is called repeatedly for every ensemble member,
+we have found it convenient to link the DART input file
+to the default input filename (<em class=file>dart.ic</em>). The same
+thing goes true for the ncommas output filename <em class=file>ncommas_restart.nc</em>.
+</P>
+
+<!--==================================================================-->
+<!--=================== DESCRIPTION OF A NAMELIST ====================-->
+<!--==================================================================-->
+
+<A NAME="Namelist"></A>
+<hr />
+<H2>NAMELIST</H2>
+<P>We adhere to the F90 standard of starting a namelist with an ampersand
+'&' and terminating with a slash '/' for all our namelist input.
+Character strings that contain a '/' must be
+enclosed in quotes to prevent them from prematurely terminating the namelist.
+</P>
+<div class=namelist>
+<pre>
+<em class=call>namelist / dart_to_ncommas_nml / </em> dart_to_ncommas_input_file, advance_time_present
+
+<em class=call>namelist / model_nml / </em> ncommas_restart_filename, calendar
+
+<em class=call>namelist / ncommas_vars_nml / </em> ncommas_state_variables
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<em class=code>dart_to_ncommas_nml</em> and <em class=code>model_nml</em>
+are always read from a file called <em class=file>input.nml</em>.
+The full description of the <em class=code>model_nml</em> namelist is documented
+in the <a href="model_mod.html#Namelist">NCOMMAS model_mod</a>.
+</P>
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
+<TR><!--contents--><TD valign=top>dart_to_ncommas_input_file </TD>
+ <!-- type --><TD valign=top>character(len=128) </TD>
+ <!--descript--><TD>The name of the DART file containing the model state
+ to insert into the ncommas restart file.
+ <em class=units>[default: 'dart.ic']</em></TD></TR>
+
+<TR><!--contents--><TD valign=top>advance_time_present</TD>
+ <!-- type --><TD valign=top>logical</TD>
+ <!--descript--><TD>switch to control the ability to read a DART file
+ containing TWO timestamps in the file header.
+ If you are converting a DART initial conditions or
+ restart file - this should be
+ <em class=code>.false.</em> - these files have a
+ single timestamp describing the valid time of the
+ model state.
+ <br />
+ <br />
+ If <em class=code>.true.</em>, TWO timestamps are
+ expected to be the DART file header. In this case, a
+ namelist for ncommas (called <em class=file>ncommas_in.DART</em>)
+ is created that contains the
+ <em class=code>&time_manager_nml</em> settings
+ appropriate to advance ncommas to the time
+ requested by DART.
+ <em class=units>[default: .false.]</em></TD></TR>
+</TABLE>
+
+</div>
+<br />
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<em class=code>ncommas_vars_nml</em> is always read from a file
+called <em class=file>ncommas_vars.nml</em>.
+</P>
+
+<TABLE border=0 cellpadding=3 width=100%>
+<TR><TH align=left>Contents </TH>
+ <TH align=left>Type </TH>
+ <TH align=left>Description </TH></TR>
+
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list