[Dart-dev] [4417] DART/trunk: The POP documentation for model_mod. html is as good as it gets.
nancy at ucar.edu
nancy at ucar.edu
Fri Jul 9 16:13:25 MDT 2010
Revision: 4417
Author: thoar
Date: 2010-07-09 16:13:25 -0600 (Fri, 09 Jul 2010)
Log Message:
-----------
The POP documentation for model_mod.html is as good as it gets.
I still have to document dart_to_pop.f90 and pop_to_dart.f90.
Modified Paths:
--------------
DART/trunk/doc/html/doc.css
DART/trunk/models/POP/model_mod.html
-------------- next part --------------
Modified: DART/trunk/doc/html/doc.css
===================================================================
--- DART/trunk/doc/html/doc.css 2010-07-09 17:08:38 UTC (rev 4416)
+++ DART/trunk/doc/html/doc.css 2010-07-09 22:13:25 UTC (rev 4417)
@@ -205,6 +205,23 @@
color:green;
font-style:typewriter}
+em.nav{
+ font-style:normal;
+ color:white;}
+
+em.sub{
+ color:peru;
+ font-style:normal;
+ font-size:1.2em;}
+
+em.head{
+ color:white;
+ font-style:normal;
+ font-size:1.2em;}
+
+em.italic{
+ font-style:italic}
+
em.red{
color:crimson;
font-style:normal}
@@ -221,26 +238,16 @@
color:cornflowerblue;
font-style:normal}
-em.sub{
- color:peru;
- font-style:normal;
- font-size:1.2em;}
-
-em.head{
- color:white;
- font-style:normal;
- font-size:1.2em;}
-
-em.italic{
- font-style:italic;
- color:red;}
-
em{
font-style:normal;
color:red;}
-em.nav{
- font-style:normal;
- color:white;}
+.top {
+ font-size: 8pt;
+ clear: both;
+ float: right;
+ margin-top: -10px;
+ margin-left: 5px;
+}
# RGB(204,204,204) == "#CCCCCC"
Modified: DART/trunk/models/POP/model_mod.html
===================================================================
--- DART/trunk/models/POP/model_mod.html 2010-07-09 17:08:38 UTC (rev 4416)
+++ DART/trunk/models/POP/model_mod.html 2010-07-09 22:13:25 UTC (rev 4417)
@@ -1,9 +1,10 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
<HTML>
<HEAD>
<TITLE>module model_mod (POP)</TITLE>
-<link rel="stylesheet" type="text/css" href="../../doc/html/doc.css">
+<link rel="stylesheet" type="text/css" href="../../doc/html/doc.css" />
</HEAD>
<BODY>
<A NAME="TOP"></A>
@@ -11,7 +12,7 @@
<table border=0 summary="" cellpadding=5>
<tr>
<td valign=middle>
- <img src="../../doc/html/Dartboard9.png" alt="DART project logo" height=70 >
+ <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 />
@@ -22,8 +23,8 @@
</tr>
</table>
-<A HREF="#Interface">INTERFACES</A> /
<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> /
@@ -39,7 +40,7 @@
<a href="http://www.cesm.ucar.edu/models/cesm1.0/pop2/">CESM1.0 POP2</a> have been
tested. At present (July 2010), we are assimilating salinity and temperature
observations from the World Ocean Database (2005) with the intention of switching
- to the World Ocean Database (2010) as needed.
+ to the World Ocean Database (2009) as needed.
<br />
<br />
The following POP variables are extracted from the POP netCDF restart files and
@@ -245,7 +246,7 @@
from a hindcast experiment.
<br />
<br />
- There is a <em class="program">shell_scripts/MakeInitialEnsemble.csh</em>
+ There is a <em class=program>shell_scripts/MakeInitialEnsemble.csh</em>
script that is intended to demonstrate how to convert a set of POP netCDF
restart files into a set of DART files that have a consistent timestamp.
If you simply convert each POP file to a DART file using
@@ -293,7 +294,7 @@
<ol>
<li>assimilate data for the first assimilation period and stop. Do not advance
the model at all. The filter namelist can control all of this and you do
- not need to have a working <em class="program">advance_model.csh</em>
+ not need to have a working <em class=program>advance_model.csh</em>
script, or even a working ocean model (as long as you have input data files).</li>
<li>advance the model first and then assimilate data for the first assimilation
period and stop.</li>
@@ -309,7 +310,7 @@
<li>Create a set of initial conditions for DART by running one instance of POP
for a very long time and saving restart files 'every so often'.
Use one of these as the initial condition
- for <em class="program">perfect_model_obs</em> and the rest as the
+ for <em class=program>perfect_model_obs</em> and the rest as the
ensemble for the assimilation experiment. Since no one in their right
mind would use a high-resolution model for a proof-of-concept case
(hint, hint), running a low-resolution model for a 'very long time' should
@@ -321,21 +322,21 @@
and then
<a href="../../../obs_sequence/create_fixed_network_seq.html">create_fixed_network_seq</a>
to create an empty observation sequence file
- (usually called <em class="file">obs_seq.in</em>).
+ (usually called <em class=file>obs_seq.in</em>).
The programs will prompt you for all the information they require.
Read their documentation if necessary.
</li>
- <li>break the <em class="file">pop_in</em> namelist that comes with POP into
- two pieces - one called <em class="file">pop_in.part1</em>,
+ <li>break the <em class=file>pop_in</em> namelist that comes with POP into
+ two pieces - one called <em class=file>pop_in.part1</em>,
that contains the <em class=code>&time_manager_nml</em> and
- put the rest in <em class="file">pop_in.part2</em>. The
+ put the rest in <em class=file>pop_in.part2</em>. The
<em class=code>&time_manager_nml</em> will be repeatedly updated
as the POP model is repeatedly called by
<em class=program>advance_model.csh</em>.
</li>
- <li>modify <em class="file">POP/work/input.nml</em> as needed.
+ <li>modify <em class=file>POP/work/input.nml</em> as needed.
</li>
<li>modify
@@ -368,16 +369,16 @@
Is pretty much like any other model. The netCDF files have the model
prognostic variables before and after the assimilation.
There are Matlab® scripts for perusing the netCDF files in the
- <em class="file">DART/matlab</em> directory.
+ <em class=file>DART/matlab</em> directory.
There are Matlab® scripts for exploring the performance of the
assimilation in observation-space (after running
<a href="../../diagnostics/threed_sphere/obs_diag.html">obs_diag</a>
- to explore the <em class="file">obs_seq.final</em> file) - use the
+ to explore the <em class=file>obs_seq.final</em> file) - use the
scripts starting with 'plot_', i.e.
- <em class="file">DART/diagnostics/matlab/plot_*.m</em>.
+ <em class=file>DART/diagnostics/matlab/plot_*.m</em>.
As always, there are some model-specific item you should know about in
- <em class="file">DART/models/POP/matlab</em>, and
- <em class="file">DART/models/POP/shell_scripts</em>.
+ <em class=file>DART/models/POP/matlab</em>, and
+ <em class=file>DART/models/POP/shell_scripts</em>.
<br />
<br />
It is also worthwhile to convert your obs_seq.final file to a netCDF format
@@ -386,9 +387,201 @@
</div>
<!--==================================================================-->
+<!--=================== DESCRIPTION OF A NAMELIST ===================-->
+<!--==================================================================-->
+<A NAME="Namelist"></A>
+<div class="top">[<a href="#">top</a>]</div><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.
+Consider yourself forewarned that character strings that contain a '/' must be
+enclosed in quotes to prevent them from prematurely terminating the namelist.
+<div class=namelist><pre>
+<em class=call>namelist /model_nml/ </em> output_state_vector, &
+ assimilation_period_days, assimilation_period_seconds, &
+ model_perturbation_amplitude, debug
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>This namelist is read in a file called <em class=file>input.nml</em>.
+ This namelist provides control over the assimilation period for the model.
+ All observations within (+/-) half of the assimilation period are assimilated.
+ The assimilation period is the minimum amount of time the model can be advanced,
+ and checks are performed to ensure that the assimilation window is a multiple of
+ the ocean model dynamical timestep.
+</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>output_state_vector</TD>
+ <!-- type --><TD valign=top>logical <em class=units>[default: .true.]</em></TD>
+ <!--descript--><TD valign=top>The switch to determine the form of the state vector in the
+ output netCDF files. If <em class=code>.true.</em>
+ the state vector will be output exactly as DART uses it
+ ... one long array. If <em class=code>.false.</em>,
+ the state vector is parsed into prognostic variables and
+ output that way -- much easier to use with 'ncview', for
+ example.</TD></TR>
+
+<TR><!--contents--><TD valign=top>assimilation_period_days</TD>
+ <!-- type --><TD valign=top>integer <em class=units>[default: 1]</em></TD>
+ <!--descript--><TD valign=top>The number of days to advance the model for each assimilation.
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>assimilation_period_seconds</TD>
+ <!-- type --><TD valign=top>integer <em class=units>[default: 0]</em></TD>
+ <!--descript--><TD valign=top>In addition to <em class=code>assimilation_period_days</em>,
+ the number of seconds to advance the model for each assimilation.
+ </TD></TR>
+
+<TR><!--contents--><TD valign=top>model_perturbation_amplitude</TD>
+ <!-- type --><TD valign=top>real(r8) <em class=units>[default: 0.2]</em></TD>
+ <!--descript--><TD valign=top> Reserved for future use.
+ <!-- The amount of noise to add when trying to perturb a single
+ state vector to create an ensemble. Only used when
+<em class=file>input.nml</em><em class=code>&filter_nml:start_from_restart = .false.</em>
+ See also
+ <a href="#InitialEnsemble">Generating the initial ensemble</a>
+ at the start of this document. units: standard deviation
+ of a gaussian distribution with the mean at the value of
+ the state vector element. --> </TD></TR>
+
+<TR><!--contents--><TD valign=top>debug</TD>
+ <!-- type --><TD valign=top>integer <em class=units>[default: 0]</em></TD>
+ <!--descript--><TD valign=top>The switch to specify the run-time verbosity.
+ <em class=code>0</em> is as quiet as it gets.
+ <em class=code>> 1</em> provides more run-time messages.
+ <em class=code>> 5</em> provides ALL run-time messages.
+ All values above 0 will also write a netCDF file of the grid
+ information and perform a grid interpolation test.</TD></TR>
+
+</TABLE>
+
+<H3 class=indent1>Example</H3>
+
+<pre>
+&model_nml
+ assimilation_period_days = 1,
+ assimilation_period_seconds = 0,
+ model_perturbation_amplitude = 0.2,
+ output_state_vector = .false.,
+ debug = 0 /
+</pre>
+
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="time_manager_nml"></A>
+<br />
+<div class=namelist><pre>
+<em class=call>namelist /time_manager_nml/ </em> runid, stop_option, stop_count, &
+ time_mix_opt, fit_freq, time_mix_freq, dt_option, dt_count, impcor, laccel, &
+ accel_file, dtuxcel, allow_leapyear, date_separator, &
+ iyear0, imonth0, iday0, ihour0, iminute0, isecond0
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+ This namelist is read in a file called <em class=file>pop_in</em> .
+ This namelist is the same one that is used by the ocean model and is used
+ to control the integration length of POP. It is unimportant for the CESM/POP
+ experiments but is critically important for the LANL/POP experiments.
+ The values are explained in full in the POP documentation. The DART code
+ reads the namelist and simply overwrites several values with the new time
+ integration information. All the other values are unchanged.
+ <br />
+ <br />
+ <em class=program>dart_to_pop</em> writes out a new
+ <em class=code>&time_manager_nml</em> in <em class=file>pop_in.DART</em>
+ if the DART state being converted has the 'advance_to_time' record in it.
+ This is the case during the middle of a DART experiment, but is not
+ typically encountered if one is working with DART 'initial conditions'
+ or 'restart' files. The <em class=file>pop_in.DART</em> must be concatenated
+ with the other namelists needed by POP into a file called
+ <em class=file>pop_in</em> . We have chosen to store the other
+ namelists (which contain static information) in a file called
+ <em class=file>pop_in.part2</em>. Initially, the
+ <em class=code>time_manager_nml</em> is stored in a companion file called
+ <em class=file>pop_in.part1</em> and the two files are concatenated into
+ the expected <em class=file>pop_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>pop_in.part2</em>
+ <br />
+ <br />
+ If you are running the support programs in a standalone fashion
+ (as you might if you are converting restart files into an intial ensemble),
+ the 'valid time' of the model state comes from the restart file
+ - NOT - the namelist. You can always patch the times in the
+ headers with <em class=program>restart_file_utility</em>.
+ <br />
+ <br />
+ Only the namelist variables of interest to DART are discussed. All
+ other namelist variables are ignored by DART - but mean something to POP.
+</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>stop_option</TD>
+ <!-- type --><TD valign=top>character <em class=units>[default: 'nday']</em></TD>
+ <!--descript--><TD valign=top>The units for <em class=code>stop_count</em>.</TD></TR>
+
+<TR><!--contents--><TD valign=top>stop_count</TD>
+ <!-- type --><TD valign=top>integer <em class=units>[default: 1]</em></TD>
+ <!--descript--><TD valign=top>The duration of the model integration. The units
+ come from <em class=code>stop_option</em>.</TD></TR>
+</TABLE>
+
+<H3 class=indent1>Example</H3>
+
+<pre>
+&time_manager_nml
+ runid = 'gx3v5'
+ stop_option = <em class=input>'nday'</em>
+ stop_count = <em class=input>1</em>
+ time_mix_opt = 'avgfit'
+ fit_freq = 1
+ time_mix_freq = 17
+ dt_option = 'auto_dt'
+ dt_count = 1
+ impcor = .true.
+ laccel = .false.
+ accel_file = 'unknown_accel_file'
+ dtuxcel = 1.0
+ allow_leapyear = .true.
+ iyear0 = 2000
+ imonth0 = 1
+ iday0 = 1
+ ihour0 = 0
+ iminute0 = 0
+ isecond0 = 0
+ date_separator = '-'
+ /
+</pre>
+</div>
+<br />
+
+<!--==================================================================-->
+
<A NAME="OtherModulesUsed"></A>
-<HR>
+<div class="top">[<a href="#">top</a>]</div><hr />
<H2>OTHER MODULES USED</H2>
<PRE>
@@ -399,6 +592,7 @@
obs_kind_mod
mpi_utilities_mod
random_seq_mod
+dart_pop_mod
</PRE>
<!--==================================================================-->
@@ -410,33 +604,17 @@
<!--==================================================================-->
<A NAME="Interface"></A>
-<HR>
+<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>
-<TABLE>
-<TR><TD><em class="call">use location_mod, only : </em></TD>
- <TD><A HREF="../../location/threed_sphere/location_mod.html#location_type">location_type</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="../../location/threed_sphere/location_mod.html#get_location">get_location</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="../../location/threed_sphere/location_mod.html#set_location">set_location</A></TD></TR>
-</TABLE>
-
-<P>
-The ocean model namelists <em class="file">data</em>, and
-<em class="file">data.cal</em> <em class=strong>MUST</em> be
-present. These namelists are needed to reconstruct the valid time of the
-snapshot files created by the ocean model. Be aware that as DART advances
-the model, the <em class="file">data</em> namelist gets modified to reflect
-the current time of the model output.
-</P>
-
-
-<TABLE>
-<TR><TD colspan="2">Required Interface Routines</TD></TR>
-<TR><TD><em class=call>use model_mod, only : </em></TD>
+<h3 class=indent1>Required Interface Routines</h3>
+<TABLE width=50%>
+<TR><TD><em class=call>use model_mod, only :</em></TD>
<TD><A HREF="#get_model_size">get_model_size</A></TD></TR>
<TR><TD> </TD><TD><A HREF="#adv_1step">adv_1step</A></TD></TR>
<TR><TD> </TD><TD><A HREF="#get_state_meta_data">get_state_meta_data</A></TD></TR>
@@ -453,44 +631,67 @@
<TR><TD> </TD><TD><A HREF="#get_close_obs_init">get_close_obs_init</A></TD></TR>
<TR><TD> </TD><TD><A HREF="#get_close_obs">get_close_obs</A></TD></TR>
<TR><TD> </TD><TD><A HREF="#ens_mean_for_model">ens_mean_for_model</A></TD></TR>
+</TABLE>
-<TR><TD colspan="2">Unique Interface Routines</TD></TR>
+<h3 class=indent1>Unique Interface Routines</h3>
+<TABLE width=50%>
<TR><TD><em class=call>use model_mod, only : </em></TD>
- <TD><A HREF="#POP_meta_type">POP_meta_type</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#read_meta">read_meta</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#write_meta">write_meta</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#prog_var_to_vector">prog_var_to_vector</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#vector_to_prog_var">vector_to_prog_var</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#read_snapshot">read_snapshot</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#write_snapshot">write_snapshot</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#get_gridsize">get_gridsize</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#snapshot_files_to_sv">snapshot_files_to_sv</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#sv_to_snapshot_files">sv_to_snapshot_files</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#timestep_to_DARTtime">timestep_to_DARTtime</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#DARTtime_to_POPtime">DARTtime_to_POPtime</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#DARTtime_to_timestepindex">DARTtime_to_timestepindex</A></TD></TR>
-<TR><TD> </TD><TD><A HREF="#write_data_namelistfile">write_data_namelistfile</A></TD></TR>
+ <TD><A HREF="#get_gridsize">get_gridsize</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#restart_file_to_sv">restart_file_to_sv</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#sv_to_restart_file">sv_to_restart_file</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_pop_restart_filename">get_pop_restart_filename</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#test_interpolation">test_interpolation</A></TD></TR>
</TABLE>
<P>
-Ocean model namelist interfaces <em class="code">&PARM03</em>,
-<em class="code">&PARM04</em>, and
-<em class="code">&PARM04</em> are read from
-file <em class="file">data</em>.
-Ocean model namelist interface <em class="code">&CAL_NML</em>,
-is read from file <em class="file">data.cal</em>.
+Ocean model namelist interfaces <em class=code>&PARM03</em>,
+<em class=code>&PARM04</em>, and
+<em class=code>&PARM04</em> are read from
+file <em class=file>data</em>.
+Ocean model namelist interface <em class=code>&CAL_NML</em>,
+is read from file <em class=file>data.cal</em>.
</P>
+<TABLE>
+<TR><TD><em class=call>use location_mod, only : </em></TD>
+ <TD><A HREF="../../location/threed_sphere/location_mod.html#get_close_obs">get_close_obs</A></TD></TR>
+</TABLE>
+
+<P>The presence of 'dry' gridpoints causes a little extra work for the
+ <em class=program>get_close_obs()</em> routine. The routine normally
+ comes from the <em class=program>location_mod</em> which has no notion
+ of wet/dry grid cell attributes. As such, the POP
+ <em class=program>model_mod</em> will be augmenting the work done by
+ <em class=program>location_mod/get_close_obs()</em> .
+ <br />
+ <br />
+ Fundamentally, the <em class=program>location_mod</em> calculates and returns
+ all the 'close' observations. DART is designed such that the routine that
+ uses the list of close observations is in <em class=file>model_mod.f90</em>.
+ Consequently, the POP <em class=program>model_mod</em> can take that
+ information and adjust as necessary. This creates some logistical issues
+ in that the POP model_mod needs to intercept all calls to
+ <em class=program>location_mod:get_close_obs()</em> - which can be achieved
+ with the following syntax:
+</P>
+<pre>
+ use location_mod, only : loc_get_close_obs => get_close_obs
+</pre>
+
<P>
A note about documentation style.
Optional arguments are enclosed in brackets
<em class=optionalcode>[like this]</em>.
</P>
+<!--==================================================================-->
+<H3 class=indent1>Required Interface Routines</H3>
+<!--==================================================================-->
+
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="get_model_size"></A>
-<br>
+<br />
<div class=routine>
<em class=call>model_size = get_model_size( )</em>
<pre>
@@ -514,12 +715,12 @@
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="adv_1step"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call adv_1step(x, time)</em>
<pre>
@@ -532,9 +733,9 @@
<!-- Description -->
<P>
-<em class="code">adv_1step</em>
+<em class=code>adv_1step</em>
is not used for the POP model.
-Advancing the model is done through the <em class="program">advance_model</em> script.
+Advancing the model is done through the <em class=program>advance_model</em> script.
This is a NULL_INTERFACE, provided only for compatibility with the DART requirements.
</P>
@@ -549,12 +750,12 @@
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="get_state_meta_data"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call get_state_meta_data (index_in, location,
<em class=optionalcode>[, var_type]</em> )</em>
@@ -569,15 +770,15 @@
<!-- Description -->
<P>
-<em class="code">get_state_meta_data</em>
+<em class=code>get_state_meta_data</em>
returns metadata about a given element of the DART representation of the
model state vector. Since the DART model state vector is a 1D array and the
-native model grid is multidimensional, <em class="code">get_state_meta_data</em>
+native model grid is multidimensional, <em class=code>get_state_meta_data</em>
returns information about the native model state vector representation. Things
-like the <em class="code">location</em>, or the type of the variable
+like the <em class=code>location</em>, or the type of the variable
(for instance: salinity, temperature, u current component, ...).
The integer values used to indicate different variable types in
-<em class="code">var_type</em> are themselves defined as public interfaces
+<em class=code>var_type</em> are themselves defined as public interfaces
to model_mod if required.
</P>
@@ -588,8 +789,8 @@
<TR><TD valign=top><em class=code>location</em></TD>
<TD>Returns the 3D location of the indexed state variable.
- The <em class="code">location_ type</em> comes from
- <em class="file">DART/location/threed_sphere/location_mod.f90</em>.
+ The <em class=code>location_ type</em> comes from
+ <em class=file>DART/location/threed_sphere/location_mod.f90</em>.
Note that the lat/lon are specified in degrees by the user but are converted
to radians internally.</TD></TR>
@@ -597,27 +798,27 @@
<TD>Returns the type of the indexed state variable as an optional argument.
The type is one of the list of supported observation types, found in
the block of code starting
- <em class="code">! Integer definitions for DART TYPES</em>
- in <em class="file">DART/obs_kind/obs_kind_mod.f90</em>
+ <em class=code>! Integer definitions for DART TYPES</em>
+ in <em class=file>DART/obs_kind/obs_kind_mod.f90</em>
</TD></TR>
</TABLE>
<P>
-The list of supported variables in <em class="file">DART/obs_kind/obs_kind_mod.f90</em>
-is created by <em class="program">preprocess</em> using the entries in
-<em class="file">input.nml</em>[<em class="code">&preprocess_nml, &obs_kind_nml</em>],
-<em class="file">DEFAULT_obs_kin_mod.F90</em> and
-<em class="file">obs_def_ocean_mod.f90</em>.
+The list of supported variables in <em class=file>DART/obs_kind/obs_kind_mod.f90</em>
+is created by <em class=program>preprocess</em> using the entries in
+<em class=file>input.nml</em>[<em class=code>&preprocess_nml, &obs_kind_nml</em>],
+<em class=file>DEFAULT_obs_kin_mod.F90</em> and
+<em class=file>obs_def_ocean_mod.f90</em>.
</P>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="model_interpolate"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call model_interpolate(x, location, itype, obs_val, istatus)</em>
<pre>
@@ -633,17 +834,17 @@
<!-- Description -->
<P>
-Given a model state, <em class="code">model_interpolate</em> returns the value of
+Given a model state, <em class=code>model_interpolate</em> returns the value of
the desired observation type (which could be a state variable) that would be
observed at the desired location. The interpolation method is either
completely specified by the model, or uses some standard 2D or 3D scalar
interpolation routines.
-Put another way, <em class="code">model_interpolate</em> will apply the forward
+Put another way, <em class=code>model_interpolate</em> will apply the forward
operator <strong>H</strong> to the model state to create an observation at the desired
location.
-<BR>
-<BR>
-If the interpolation is valid, <em class="code">istatus = 0</em>.
+<br />
+<br />
+If the interpolation is valid, <em class=code>istatus = 0</em>.
In the case where the observation operator is not defined at the given
location (e.g. the observation is below the lowest model level, above the top
level, or 'dry'), interp_val is returned as 0.0 and istatus = 1.
@@ -665,17 +866,17 @@
<TR><TD valign=top><em class=code>istatus</em></TD>
<TD>Integer flag indicating the success of the interpolation.
- <BR>success == 0, failure == anything else</TD></TR>
+ <br />success == 0, failure == anything else</TD></TR>
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="get_model_time_step"></A>
-<br>
+<br />
<div class=routine>
<em class=call>var = get_model_time_step()</em>
<pre>
@@ -687,18 +888,16 @@
<!-- Description -->
<P>
-<em class="code">get_model_time_step</em>
+<em class=code>get_model_time_step</em>
returns the forecast length to be used as the "model base time step" in the filter.
This is the minimum amount of time the model can be advanced by
-<em class="program">filter</em>.
+<em class=program>filter</em>.
<em class="strong">This is also the assimilation window</em>.
All observations within (+/-) one half of the forecast
length are used for the assimilation.
-In the <em class="program">POP</em> case, this is set from
-the namelist values for <em class="file">input.nml</em><em
-class="code">&model_nml:assimilation_period_days, assimilation_period_seconds</em>,
-after ensuring the forecast length is a multiple of the ocean model dynamical timestep
-declared by <em class="file">data</em><em class="code">&PARM03:deltaTClock</em>.
+In the <em class=program>POP</em> case, this is set from
+the namelist values for <em class=file>input.nml</em><em
+class=code>&model_nml:assimilation_period_days, assimilation_period_seconds</em>.
</P>
<TABLE width=100% border=0 summary="" cellpadding=3>
@@ -708,18 +907,13 @@
</TABLE>
-<P>
-Please read the note concerning
-<a href="#ModelTimestepping">Controlling the model advances</a>
-</P>
-
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="static_init_model"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call static_init_model()</em>
</div>
@@ -728,31 +922,40 @@
<!-- Description -->
<P>
-<em class="code">static_init_model</em>
+<em class=code>static_init_model</em>
is called for runtime initialization of the model.
-The namelists are read to determine runtime configuration of the model, the calendar
-information, the grid coordinates, etc. There are no input arguments and no return values.
+The namelists are read to determine runtime configuration of the model,
+the grid coordinates, etc. There are no input arguments and no return values.
The routine sets module-local private attributes that can then be queried by the
public interface routines.
-<BR><BR>
-The namelists (all mandatory) are:<BR>
-<em class="file">input.nml</em><em class="code">&model_mod_nml</em>,<BR>
-<em class="file">data.cal</em><em class="code">&CAL_NML</em>,<BR>
-<em class="file">data</em><em class="code">&PARM03</em>,<BR>
-<em class="file">data</em><em class="code">&PARM04</em>, and <BR>
-<em class="file">data</em><em class="code">&PARM05</em>.
+<br />
+<br />
+See the POP documentation for all namelists in <em class=file>pop_in</em> .
+Be aware that DART reads the POP <em class=code>&grid_nml</em> namelist
+to get the filenames for the horizontal and vertical grid information as well
+as the topography information.
+<br />
+<br />
+The namelists (all mandatory) are:<br />
+<em class=file>input.nml</em><em class=code>&model_mod_nml</em>,<br />
+<em class=file>pop_in</em><em class=code>&time_manager_nml</em>,<br />
+<em class=file>pop_in</em><em class=code>&io_nml</em>,<br />
+<em class=file>pop_in</em><em class=code>&init_ts_nml</em>,<br />
+<em class=file>pop_in</em><em class=code>&restart_nml</em>,<br />
+<em class=file>pop_in</em><em class=code>&domain_nml</em>, and<br />
+<em class=file>pop_in</em><em class=code>&grid_nml</em>.
</P>
<TABLE width=100% border=0 summary="" cellpadding=3>
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="end_model"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call end_model()</em>
</div>
@@ -761,22 +964,22 @@
<!-- Description -->
<P>
-<em class="code">end_model</em>
+<em class=code>end_model</em>
is used to clean up storage for the model, etc.
when the model is no longer needed. There are no arguments and no return values.
-This is required by DART but nothing needs to be done for the POP model.
+The grid variables are deallocated.
</P>
<TABLE width=100% border=0 summary="" cellpadding=3>
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="init_time"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call init_time(time)</em>
<pre>
@@ -788,12 +991,12 @@
<!-- Description -->
<P>
-<em class="code">init_time</em>
+<em class=code>init_time</em>
returns the time at which the model will start if no input initial conditions are
to be used. This is frequently used to spin-up models from rest, but is not
meaningfully supported for the POP model.
The only time this routine would get called is if the
-<em class="file">input.nml</em><em class="code">&perfect_model_obs_nml:start_from_restart</em> is .false., which is
+<em class=file>input.nml</em><em class=code>&perfect_model_obs_nml:start_from_restart</em> is .false., which is
not supported in the POP model.
</P>
@@ -801,17 +1004,17 @@
<TR><TD valign=top><em class=code>time </em></TD>
<TD>the starting time for the model if no initial conditions are to be supplied.
- As of Oct 2008, this is hardwired to 0.0</TD></TR>
+ This is hardwired to 0.0</TD></TR>
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="init_conditions"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call init_conditions(x)</em>
<pre>
@@ -823,7 +1026,7 @@
<!-- Description -->
<P>
-<em class="code">init_conditions</em>
+<em class=code>init_conditions</em>
returns default initial conditions for model; generally used for spinning up
initial model states. For the POP model it is just a stub because
the initial state is always provided by the input files.
@@ -832,17 +1035,18 @@
<TABLE width=100% border=0 summary="" cellpadding=3>
<TR><TD valign=top><em class=code>x </em></TD>
- <TD>Initial conditions for state vector.</TD></TR>
+ <TD>Initial conditions for state vector.
+ This is hardwired to 0.0</TD></TR>
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="nc_write_model_atts"></A>
-<br>
+<br />
<div class=routine>
<em class=call>ierr = nc_write_model_atts(ncFileID)</em>
<pre>
@@ -855,14 +1059,17 @@
<!-- Description -->
<P>
-<em class="code">nc_write_model_atts</em>
+<em class=code>nc_write_model_atts</em>
writes model-specific attributes to an opened netCDF file:
In the POP case, this includes information like the
-coordinate variables (the grid arrays: XG, XC, YG, YC, ZG, ZC, ...),
+coordinate variables (the grid arrays: ULON, ULAT, TLON, TLAT, ZG, ZC, KMT, KMU),
information from some of the namelists, and either the 1D state
-vector or the prognostic variables (S,T,U,V,Eta). All the required
-information (except for the netCDF file identifier) is obtained
-from the scope of the <em class="unix">model_mod</em> module.
+vector or the prognostic variables (SALT,TEMP,UVEL,VVEL,PSURF).
+All the required information (except for the netCDF file identifier)
+is obtained from the scope of the <em class=program>model_mod</em> module.
+Both the <em class=file>input.nml</em> and <em class=file>pop_in</em> files
+are preserved in the netCDF file as variables <em class=code>inputnml</em> and
+<em class=code>pop_in</em>, respectively.
</P>
<TABLE width=100% border=0 summary="" cellpadding=3>
@@ -876,28 +1083,28 @@
</TABLE>
<P>
-<em class="code">nc_write_model_atts</em>
+<em class=code>nc_write_model_atts</em>
is responsible for the model-specific attributes in the following DART-output netCDF files:
-<em class="file">True_State.nc</em>,
-<em class="file">Prior_Diag.nc</em>, and
-<em class="file">Posterior_Diag.nc</em>.
+<em class=file>True_State.nc</em>,
+<em class=file>Prior_Diag.nc</em>, and
+<em class=file>Posterior_Diag.nc</em>.
</P>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="nc_write_model_vars"></A>
-<br>
+<br />
<div class=routine>
<em class=call>ierr = nc_write_model_vars(ncFileID, statevec, copyindex, timeindex)</em>
<pre>
-integer :: <em class=code>nc_write_model_vars</em>
integer, intent(in) :: <em class=code>ncFileID</em>
real(r8), dimension(:), intent(in) :: <em class=code>statevec</em>
integer, intent(in) :: <em class=code>copyindex</em>
integer, intent(in) :: <em class=code>timeindex</em>
+integer :: <em class=code>ierr</em>
</pre>
</div>
@@ -905,16 +1112,16 @@
<!-- Description -->
<P>
-<em class="code">nc_write_model_vars</em>
+<em class=code>nc_write_model_vars</em>
writes a copy of the state variables to a NetCDF file. Multiple copies of the
state for a given time are supported, allowing, for instance, a single file to
include multiple ensemble estimates of the state. Whether the state vector is
-parsed into prognostic variables (S,T,U,V,Eta) or simply written as a 1D array is
-controlled by
-<em class="file">input.nml</em><em class="code">&model_mod_nml:output_state_vector</em>.
-If <em class="code">output_state_vector = .true.</em> the state vector is
+parsed into prognostic variables (SALT, TEMP, UVEL, VVEL, PSURF) or simply written
+as a 1D array is controlled by
+<em class=file>input.nml</em><em class=code>&model_mod_nml:output_state_vector</em>.
+If <em class=code>output_state_vector = .true.</em> the state vector is
written as a 1D array (the simplest case, but hard to explore with the diagnostics).
-If <em class="code">output_state_vector = .false.</em> the state vector is
+If <em class=code>output_state_vector = .false.</em> the state vector is
parsed into prognostic variables before being written.
</P>
@@ -927,7 +1134,7 @@
<TD>A model state vector.</TD></TR>
<TR><TD valign=top><em class=code>copyindex </em></TD>
- <TD> Integer index of copy to be written.</TD></TR>
+ <TD>Integer index of copy to be written.</TD></TR>
<TR><TD valign=top><em class=code>timeindex</em></TD>
<TD>The timestep counter for the given state.</TD></TR>
@@ -938,12 +1145,12 @@
</TABLE>
</div>
-<br>
+<br />
<!--===================== DESCRIPTION OF A ROUTINE =====================-->
<A NAME="pert_model_state"></A>
-<br>
+<br />
<div class=routine>
<em class=call>call pert_model_state(state, pert_state, interf_provided)</em>
<pre>
@@ -953,36 +1160,27 @@
</pre>
</div>
-<div class=indent1>
-<!-- Description -->
-
+<div class=indent1> <!-- Description -->
<P>
-Given a model state, <em class="code">pert_model_state</em> produces a
+Given a model state, <em class=code>pert_model_state</em> produces a
perturbed model state. This is used to generate ensemble initial conditions
perturbed around some control trajectory state when one is preparing to
spin-up ensembles. Since the DART state vector for the POP model
-contains both 'wet' and 'dry' cells, (the 'dry' cells having a value of a
-perfect 0.0 - not my choice) it is imperative to provide an interface to
-perturb <strong>just</strong> the wet cells
-(<em class="code">interf_provided == .true.</em>).
-<BR><BR>
-At present (Oct 2008) the magnitude of the perturbation is wholly determined by
-<em class="file">input.nml</em><em class="code">&model_mod_nml:model_perturbation_amplitude</em>
-and <strong>utterly, completely fails</strong>. The resulting model states
-cause a fatal error when being read in by the ocean model - something like
+contains both 'wet' and 'dry' cells, it is imperative to provide an
+interface to perturb <strong>just</strong> the wet cells
+(<em class=code>interf_provided == .true.</em>).
+<br />
+<br />
+The magnitude of the perturbation is wholly determined by
+<em class=file>input.nml</em><em class=code>&model_mod_nml:model_perturbation_amplitude</em>
+and <strong>utterly, completely fails</strong>.
+<br />
+<br />
+A more robust perturbation mechanism is needed.
+Until then, avoid using this routine by using your own ensemble of initial conditions.
+This is determined by setting
+<em class=file>input.nml</em><em class=code>&filter_nml:start_from_restart = .false.</em>
</P>
-<pre>
-*** ERROR *** S/R INI_THETA: theta = 0 identically.
-If this is intentional you will need to edit ini_theta.F to avoid this safety check
-</pre>
-<P>
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list