[Dart-dev] [4422] DART/trunk/models/POP: First (and last?) effort for the documentation for the converter
nancy at ucar.edu
nancy at ucar.edu
Mon Jul 12 17:14:37 MDT 2010
Revision: 4422
Author: thoar
Date: 2010-07-12 17:14:36 -0600 (Mon, 12 Jul 2010)
Log Message:
-----------
First (and last?) effort for the documentation for the converter
routines for POP. only dart_pop_mod.html remains.
Modified Paths:
--------------
DART/trunk/models/POP/dart_to_pop.f90
DART/trunk/models/POP/dart_to_pop.nml
DART/trunk/models/POP/model_mod.html
DART/trunk/models/POP/pop_to_dart.f90
Added Paths:
-----------
DART/trunk/models/POP/dart_to_pop.html
DART/trunk/models/POP/pop_to_dart.html
-------------- next part --------------
Modified: DART/trunk/models/POP/dart_to_pop.f90
===================================================================
--- DART/trunk/models/POP/dart_to_pop.f90 2010-07-12 22:46:42 UTC (rev 4421)
+++ DART/trunk/models/POP/dart_to_pop.f90 2010-07-12 23:14:36 UTC (rev 4422)
@@ -13,24 +13,27 @@
!----------------------------------------------------------------------
! purpose: interface between DART and the POP model
!
-! method: Read DART state vector (in file 'assim_model_state_ic') and
-! overwrite values in a POP 'restart' file.
-! Must do something with the advance-to time.
+! method: Read DART state vector and overwrite values in a POP restart file.
+! If the DART state vector has an 'advance_to_time' present, a
+! file called pop_in.DART is created with a time_manager_nml namelist
+! appropriate to advance POP to the requested time.
!
-! author: Tim Hoar 25 Jun 09
+! The dart_to_pop_nml namelist setting for advance_time_present
+! determines whether or not the input file has an 'advance_to_time'.
+! Typically, only temporary files like 'assim_model_state_ic' have
+! an 'advance_to_time'.
+!
+! author: Tim Hoar 25 Jun 09, revised 12 July 2010
!----------------------------------------------------------------------
-use types_mod, only : r4, r8, SECPERDAY
-use utilities_mod, only : E_ERR, E_WARN, E_MSG, error_handler, open_file, &
- initialize_utilities, timestamp, &
+use types_mod, only : r8
+use utilities_mod, only : initialize_utilities, timestamp, &
find_namelist_in_file, check_namelist_read, &
logfileunit
use assim_model_mod, only : open_restart_read, aread_state_restart, close_restart
-use time_manager_mod, only : time_type, get_time, print_time, print_date, &
- operator(-), set_time
+use time_manager_mod, only : time_type, print_time, print_date, operator(-)
use model_mod, only : static_init_model, sv_to_restart_file, &
- get_model_size, get_model_time_step, &
- get_pop_restart_filename
+ get_model_size, get_pop_restart_filename
use dart_pop_mod, only : write_pop_namelist
implicit none
@@ -46,7 +49,7 @@
!------------------------------------------------------------------
character (len = 128) :: dart_to_pop_input_file = 'dart.ic'
-logical :: advance_time_present = .TRUE.
+logical :: advance_time_present = .false.
namelist /dart_to_pop_nml/ dart_to_pop_input_file, &
advance_time_present
Added: DART/trunk/models/POP/dart_to_pop.html
===================================================================
--- DART/trunk/models/POP/dart_to_pop.html (rev 0)
+++ DART/trunk/models/POP/dart_to_pop.html 2010-07-12 23:14:36 UTC (rev 4422)
@@ -0,0 +1,266 @@
+<!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_pop</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_pop</em></H1>
+
+<P>
+ <em class=program>dart_to_pop</em> is the program that updates a POP
+ netCDF-format restart file (usually <em class=file>pop.r.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 POP restart file will be updated:
+ specifically -
+ <em class=code>SALT_CUR</em>,
+ <em class=code>TEMP_CUR</em>,
+ <em class=code>UVEL_CUR</em>,
+ <em class=code>VVEL_CUR</em>, and
+ <em class=code>PSURF_CUR</em>. It is <strong>necessary</strong> to
+ perform a forward euler timestep since the '<em class=code>_OLD</em>'
+ variables are untouched by DART. The DART model time is compared to the
+ time in the POP restart file. If they are not identical, the program
+ issues an error message and aborts.
+ <br />
+ <br />
+ From the user perspective, most of the time
+ <em class=program>dart_to_pop</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_pop_nml</a> namelist allows
+ <em class=program>dart_to_pop</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 POP (called
+ <em class=file>pop_in.DART</em>) is written that contains the
+ <em class=code>&time_manager_nml</em> settings appropriate to
+ advance POP 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_pop</em>:
+</P>
+
+<UL>
+ <LI>a valid <em class=file>input.nml</em> namelist file for DART</LI>
+ <LI>a DART file (typically <em class=file>filter_restart.xxxx</em> or
+ <em class=file>filter_ics.xxxx</em>)</LI>
+ <LI>a valid <em class=file>pop_in</em> namelist file for POP</LI>
+ <LI>the POP geometry files mentioned in the <em class=file>pop_in</em> namelist file</LI>
+ <LI>a POP restart file (typically <em class=file>pop.r.nc</em>).
+ Keep in mind that the DART/POP interface requires the existence of
+ a <em class=file>pop.r.nc</em> to harvest the geometry dimensions.</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 POP output filename <em class=file>pop.r.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.
+The namelist declaration is:
+</P>
+<div class=namelist>
+<pre>
+<em class=call>namelist / dart_to_pop_nml / </em> dart_to_pop_input_file, advance_time_present
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+This namelist is always read from a file called <em class=file>input.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>
+
+<TR><!--contents--><TD valign=top>dart_to_pop_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 POP 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 POP (called <em class=file>pop_in.DART</em>)
+ is created that contains the
+ <em class=code>&time_manager_nml</em> settings
+ appropriate to advance POP to the time
+ requested by DART.
+ <em class=units>[default: .false.]</em></TD></TR>
+</TABLE>
+
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="Modules"></A>
+<hr />
+<H2>MODULES USED</H2>
+<PRE>
+assim_model_mod
+dart_pop_mod
+location_mod
+model_mod
+null_mpi_utilities_mod
+obs_kind_mod
+random_nr_mod
+random_seq_mod
+time_manager_mod
+types_mod
+utilities_mod
+</PRE>
+
+<!--==================================================================-->
+<!-- Describe the Files Used by this module. -->
+<!--==================================================================-->
+
+<A NAME="FilesUsed"></A>
+<hr />
+<H2>FILES Read</H2>
+<UL><LI>DART initial conditions/restart file; e.g. <em class=file>filter_ic</em></LI>
+ <LI>DART namelist file; <em class=file>input.nml</em></LI>
+ <LI>POP namelist file; <em class=file>pop_in</em></LI>
+ <LI>POP geometry files specified in <em class=file>pop_in</em></LI>
+ <LI>POP restart file <em class=file>pop.r.nc</em> (to get grid values)</LI>
+</UL>
+
+<H2>FILES Written</H2>
+<UL><LI>POP restart file; <em class=file>pop.r.nc</em></LI>
+ <LI>POP namelist file; <em class=file>pop_in.DART</em></LI>
+</UL>
+
+
+<!--==================================================================-->
+<!-- Cite references, if need be. -->
+<!--==================================================================-->
+
+<A NAME="References"></A>
+<hr />
+<H2>REFERENCES</H2>
+<ul>
+<li>Anderson, J., T. Hoar, K. Raeder,
+ H. Liu, N. Collins, R. Torn,
+ and A. Arellano, 2009:<br />
+ The Data Assimilation Research Testbed: A Community Facility.
+ <span style="font-style: italic;">Bull. Amer. Meteor. Soc.</span>,
+ <span style="font-weight: bold;">90</span>, 1283-1296.<br />
+ <a href="http://ams.allenpress.com/perlserv/?doi=10.1175%2F2009BAMS2618.1&request=get-abstract">DOI: 10.1175/2009BAMS2618.1</a></li>
+</ul>
+<br />
+
+<!--==================================================================-->
+<!-- Describe all the error conditions and codes. -->
+<!--==================================================================-->
+
+<A NAME="Errors"></A>
+<hr />
+<H2>ERROR CODES and CONDITIONS</H2>
+<P>
+none - all error messages come from modules that have their own documentation.
+</P>
+
+<H2>KNOWN BUGS</H2>
+<P>
+none
+</P>
+
+<!--==================================================================-->
+<!-- Describe Future Plans. -->
+<!--==================================================================-->
+
+<A NAME="FuturePlans"></A>
+<hr />
+<H2>FUTURE PLANS</H2>
+<P>
+None.
+</P>
+
+<!--==================================================================-->
+<!-- Legalese & Metadata -->
+<!--==================================================================-->
+
+<A NAME="Legalese"></A>
+<hr />
+<H2>Terms of Use</H2>
+
+<P>
+DART software - Copyright © 2004 - 2010 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/POP/dart_to_pop.html
___________________________________________________________________
Added: svn:mime-type
+ text/html
Added: svn:keywords
+ Date Rev Author HeadURL Id
Added: svn:eol-style
+ native
Modified: DART/trunk/models/POP/dart_to_pop.nml
===================================================================
--- DART/trunk/models/POP/dart_to_pop.nml 2010-07-12 22:46:42 UTC (rev 4421)
+++ DART/trunk/models/POP/dart_to_pop.nml 2010-07-12 23:14:36 UTC (rev 4422)
@@ -1,4 +1,4 @@
&dart_to_pop_nml
dart_to_pop_input_file = 'dart.ic',
- advance_time_present = .FALSE. /
+ advance_time_present = .false. /
Modified: DART/trunk/models/POP/model_mod.html
===================================================================
--- DART/trunk/models/POP/model_mod.html 2010-07-12 22:46:42 UTC (rev 4421)
+++ DART/trunk/models/POP/model_mod.html 2010-07-12 23:14:36 UTC (rev 4422)
@@ -397,6 +397,7 @@
'&' 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.
+</P>
<div class=namelist><pre>
<em class=call>namelist /model_nml/ </em> output_state_vector, &
assimilation_period_days, assimilation_period_seconds, &
Modified: DART/trunk/models/POP/pop_to_dart.f90
===================================================================
--- DART/trunk/models/POP/pop_to_dart.f90 2010-07-12 22:46:42 UTC (rev 4421)
+++ DART/trunk/models/POP/pop_to_dart.f90 2010-07-12 23:14:36 UTC (rev 4422)
@@ -25,9 +25,8 @@
! author: Tim Hoar 6/24/09
!----------------------------------------------------------------------
-use types_mod, only : r4, r8
-use utilities_mod, only : E_ERR, E_WARN, E_MSG, error_handler, logfileunit, &
- initialize_utilities, timestamp, &
+use types_mod, only : r8
+use utilities_mod, only : initialize_utilities, timestamp, &
find_namelist_in_file, check_namelist_read
use model_mod, only : restart_file_to_sv, static_init_model, &
get_model_size, get_pop_restart_filename
Added: DART/trunk/models/POP/pop_to_dart.html
===================================================================
--- DART/trunk/models/POP/pop_to_dart.html (rev 0)
+++ DART/trunk/models/POP/pop_to_dart.html 2010-07-12 23:14:36 UTC (rev 4422)
@@ -0,0 +1,213 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<HTML>
+<HEAD>
+<TITLE>program pop_to_dart</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>pop_to_dart</em></H1>
+
+<P>
+ <em class=program>pop_to_dart</em> is the program that reads a POP
+ restart file (usually <em class=file>pop.r.nc</em>) and creates
+ a DART output/restart file
+ (e.g. <em class=file>perfect_ics, filter_ics, ... </em>).
+ <br />
+ <br />
+ The following variables are extracted from the POP netCDF restart
+ files and are conveyed to DART:
+ <em class=code>SALT_CUR</em>,
+ <em class=code>TEMP_CUR</em>,
+ <em class=code>UVEL_CUR</em>,
+ <em class=code>VVEL_CUR</em>, and
+ <em class=code>PSURF_CUR</em>.
+ <br />
+ <br />
+ Conditions required for successful execution of <em class=program>pop_to_dart</em>:
+</P>
+
+<UL>
+ <LI>a valid <em class=file>input.nml</em> namelist file for DART</LI>
+ <LI>a valid <em class=file>pop_in</em> namelist file for POP</LI>
+ <LI>the POP geometry files mentioned in the <em class=file>pop_in</em> namelist file</LI>
+ <LI>a POP restart file (<em class=file>pop.r.nc</em>).</LI>
+</UL>
+
+<P>
+Since this program is called repeatedly for every ensemble member,
+we have found it convenient to link the POP restart files
+to the default input filename (<em class=file>pop.r.nc</em>).
+The default DART output filename is <em class=file>dart.ud</em> -
+this may be moved or linked as necessary.
+</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.
+The namelist declaration is:
+</P>
+<div class=namelist>
+<pre>
+<em class=call>namelist / pop_to_dart_nml / </em> pop_to_dart_output_file
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+This namelist is always read from a file called <em class=file>input.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>
+
+<TR><!--contents--><TD valign=top>pop_to_dart_output_file </TD>
+ <!-- type --><TD valign=top>character(len=128) </TD>
+ <!--descript--><TD>The name of the DART file containing the model state
+ derived from the POP restart file.
+ <em class=units>[default: 'dart.ud']</em></TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--==================================================================-->
+
+<A NAME="Modules"></A>
+<hr />
+<H2>MODULES USED</H2>
+<PRE>
+assim_model_mod
+dart_pop_mod
+location_mod
+model_mod
+null_mpi_utilities_mod
+obs_kind_mod
+random_nr_mod
+random_seq_mod
+time_manager_mod
+types_mod
+utilities_mod
+</PRE>
+
+<!--==================================================================-->
+<!-- Describe the Files Used by this module. -->
+<!--==================================================================-->
+
+<A NAME="FilesUsed"></A>
+<hr />
+<H2>FILES Read</H2>
+<UL><LI>POP restart file; <em class=file>pop.r.nc</em></LI>
+ <LI>POP namelist file; <em class=file>pop_in</em></LI>
+ <LI>POP geometry files specified in <em class=file>pop_in</em></LI>
+ <LI>DART namelist file; <em class=file>input.nml</em></LI>
+</UL>
+
+<H2>FILES Written</H2>
+<UL><LI>DART initial conditions/restart file; e.g. <em class=file>filter_ic</em></LI>
+</UL>
+
+<!--==================================================================-->
+<!-- Cite references, if need be. -->
+<!--==================================================================-->
+
+<A NAME="References"></A>
+<hr />
+<H2>REFERENCES</H2>
+<P>
+none
+</P>
+
+<!--==================================================================-->
+<!-- Describe all the error conditions and codes. -->
+<!--==================================================================-->
+
+<A NAME="Errors"></A>
+<hr />
+<H2>ERROR CODES and CONDITIONS</H2>
+<P>
+none - all error messages come from modules that have their own documentation.
+</P>
+
+<H2>KNOWN BUGS</H2>
+<P>
+none
+</P>
+
+<!--==================================================================-->
+<!-- Describe Future Plans. -->
+<!--==================================================================-->
+
+<A NAME="FuturePlans"></A>
+<hr />
+<H2>FUTURE PLANS</H2>
+<P>
+None.
+</P>
+
+<!--==================================================================-->
+<!-- Legalese & Metadata -->
+<!--==================================================================-->
+
+<A NAME="Legalese"></A>
+<hr />
+<H2>Terms of Use</H2>
+
+<P>
+DART software - Copyright © 2004 - 2010 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/POP/pop_to_dart.html
___________________________________________________________________
Added: svn:mime-type
+ text/html
Added: svn:keywords
+ Date Rev Author HeadURL Id
Added: svn:eol-style
+ native
More information about the Dart-dev
mailing list