[Dart-dev] [5848] DART/branches/development/models/noah/model_mod.html: I' m trying to put down documentation before I leave on vacation.
nancy at ucar.edu
nancy at ucar.edu
Thu Aug 16 21:48:05 MDT 2012
Revision: 5848
Author: thoar
Date: 2012-08-16 21:48:04 -0600 (Thu, 16 Aug 2012)
Log Message:
-----------
I'm trying to put down documentation before I leave on vacation.
Only the first few paragraphs actually apply to NOAH. The bones are
from the POP model_mod.html, so there is a BIG non-sequiter.
Added Paths:
-----------
DART/branches/development/models/noah/model_mod.html
-------------- next part --------------
Added: DART/branches/development/models/noah/model_mod.html
===================================================================
--- DART/branches/development/models/noah/model_mod.html (rev 0)
+++ DART/branches/development/models/noah/model_mod.html 2012-08-17 03:48:04 UTC (rev 5848)
@@ -0,0 +1,1663 @@
+<!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 (NOAH)</TITLE>
+<link rel="stylesheet" type="text/css" href="../../doc/html/doc.css" />
+</HEAD>
+<BODY>
+<A NAME="TOP"></A>
+
+<H1>MODULE model_mod (NOAH)</H1>
+
+<table border=0 summary="" cellpadding=5>
+<tr>
+ <td valign=middle>
+ <img src="../../doc/html/Dartboard7.png" alt="DART project logo" height=70 />
+ </td>
+ <td>
+ <P>Jump to <a href="../../index.html">DART Documentation Main Index</a><br />
+ <small><small>version information for this file: <br />
+ <!-- version tag follows, do not edit -->
+ $Id$</small></small>
+ </P></td>
+</tr>
+</table>
+
+<A HREF="#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>
+
+<H2>Overview</H2>
+
+<P>The <strong><a href="http://www.ral.ucar.edu/research/land/technology/lsm.php">NOAH</a>
+ Land Surface Model</strong> may now be tested with the
+ <strong>Data Assimilation Research Testbed (DART)</strong>.
+ This should be considered
+ an 'alpha' release -- the code has only been tested for a single column configuration.
+ The offline 2D driver code: High-Resolution Land Data Assimilation System (HRLDAS)
+ v3.3 -- April 2011 is the version used to develop the interface.
+ <br />
+ <br />
+ The <em>simple_driver-v3.3</em> was deemed suboptimal because of poor restart
+ characteristics. Since the offline 2D driver code can be run at a single gridpoint
+ and has excellent restart characteristics, there are no plans to support the
+ <em>simple-driver-v3.3</em> version of NOAH.
+ <br />
+ <br />
+ <strong>IMPORTANT:</strong> The <em>hrldas-v3.3</em> driver
+ generates NOAH restart files that are a bit unusual in
+ that the <em>Times</em> string in the restart file <strong>does not</strong> denote the
+ time at which the restart is valid. The time at which the state is valid is actually
+ <strong>ONE <em class=code>noah_timestep</em> BEFORE</strong> the time in the restart
+ file - <em>by design</em>. This has a
+ <strong>HUGE</strong> impact on the complexity of the scripting. At some point soon,
+ I will develop a schematic to illustrate this point.
+ <br />
+ <br />
+ Any of the variables in the NOAH restart file are available to be adjusted by the
+ assimilation. The list of variables is set though a simple namelist interface. Since
+ we are testing in a column configuration, there is no practical reason not to include
+ all the variables necessary for a bit-for-bit restart:
+ <em class=code>SOIL_T</em>,
+ <em class=code>SOIL_M</em>,
+ <em class=code>SOIL_W</em>,
+ <em class=code>SKINTEMP</em>,
+ <em class=code>SNODEP</em>,
+ <em class=code>WEASD</em>,
+ <em class=code>CANWAT</em>, and
+ <em class=code>QFX</em>. These variables are then adjusted to be consistent
+ with real observations and stuffed back into the same netCDF restart files.
+ Since DART is an ensemble algorithm, there are multiple restart files for a
+ single restart time: one for each ensemble member. Creating the initial ensemble
+ of land surface states is an area of active research. At present, it may be sufficient
+ to use a climatological ensemble; e.g., using the restarts for '1 January 00Z'
+ from 50 consecutive years.
+ <br />
+ <br />
+ The <em>offline hrldas-v3.3</em> driver is designed to use atmospheric
+ forcing files that cover a VERY short period - about every hour.
+ Consequently, the directories that contain the forcing files get very
+ cluttered for experiments that may cover years, for example.
+ There is reason to believe that the ensemble system will benefit from having
+ unique atmospheric forcing for each ensemble member.
+ A reasonable ensemble size is 50 or 80 or so. You do the math.
+ <br />
+ <br />
+ DART reads the NOAH namelist <em class=code>&NOAHLSM_OFFLINE</em> from a file called
+ <em class=file>namelist.hrldas</em> for several pieces of information.
+ DART is responsible for starting/stopping NOAH, the restart information is
+ conveyed through the NOAH namelist.
+ <br />
+ <br />
+ There are several scripts in the <em class=file>DART/models/noah/shell_scripts</em>
+ directory that assist in configuring and running experiments:
+ <em class=program>setup_pmo.csh</em>,
+ <em class=program>run_pmo.csh</em>,
+ <em class=program>setup_filter.csh</em>, and
+ <em class=program>run_filter.csh</em> .
+</P>
+
+<div class=indent1>
+ <h2>The offline 2D HRLDAS-V3.3</h2>
+ <P>
+ and the development branch of DART was tested and run on a MacBook Pro laptop
+ running OS X 10.7.4 (Lion) with gfortran v 4.5.0.
+ Several trivial modifications to the hrldas makefiles were necessary to compile
+ <em>Noah_hrldas_beta</em> on a case-insensitive filesystem.
+ [TJH include more about this]
+ <br />
+ <br />
+ The DART components were built for debugging with the following settings:
+ </P>
+ <pre>
+ FC = gfortran
+ LD = gfortran
+ INCS = -I${NETCDF}/include
+ LIBS = -L${NETCDF}/lib -lnetcdff -lnetcdf -lcurl -lhdf5_hl -lhdf5 -lz -lm
+ FFLAGS = -g -O0 -ffree-line-length-none -fbounds-check -frecord-marker=4 -ffpe-trap=invalid $(INCS)
+ LDFLAGS = $(FFLAGS) $(LIBS)
+ </pre>
+</div>
+
+<!-- div class=indent1>
+ <h3>Observations.</h3>
+ <P>
+ The observations come from the
+ <a href="http://www.nodc.noaa.gov/OC5/WOD05/pr_wod05.html">World Ocean Database 2005</a>
+ and are processed by DART routines in the
+ <a href="../../observations/WOD/WOD.html">DART/observations/WOD</a> directory.
+ </P>
+</div -->
+
+<a name="conversions"></a>
+<div class=indent1>
+ <h3>Converting between DART files and NOAH restart files.</h3>
+ <P>
+ The information about how the NOAH variables are stored in the DART
+ state vector comes from the order in which the variables are specified in
+ <em class=file>input.nml</em><em class=code>model_nml:noah_variables</em> ,
+ as is the the name of the NOAH restart file.
+ DART also needs to read the
+ <em class=file>namelist.hrldas</em><em class=code>&NOAHLSM_OFFLINE</em> namelist.
+ <br />
+ <br />
+ There are two programs - both use the <em class=program>model_mod</em> module:
+ </P>
+ <table width="100%" cellpadding="10">
+ <tr><td valign="top"><a href="noah_to_dart.html">noah_to_dart.f90</a></td>
+ <td>converts the NOAH restart file <em class=file>restart.nc</em> into a
+ DART-compatible file normally called <em class=file>dart_ics</em> .
+ We usually wind up linking the NOAH restart files to the
+ static name (<em class=file>dart_ics</em>).
+ </td>
+ </tr>
+ <tr><td valign="top"><a href="dart_to_noah.html">dart_to_noah.f90</a></td>
+ <td>inserts the DART output into an existing NOAH restart netCDF file by
+ overwriting the variables. There is the ability to selectively avoid
+ updating the NOAH variables. This allows one to include NOAH variables in
+ the DART state vector to aid in the application of observation operators, etc.,
+ without having to modify those variables in the NOAH restart file.
+ There are two different types of DART output files, so there is a namelist
+ option to specify if the DART file has two time records or just one
+ (if there are two, the first one is the 'advance_to' time, followed
+ by the 'valid_time' of the ensuing state). <em class=program>dart_to_noah</em>
+ requires the DART file to be named <em class=file>dart_restart</em> and the
+ NOAH restart file have a name of <em class=file>restart.nc</em> &npsp;.
+ If the DART file contains an 'advance_to' time,
+ <em class=program>dart_to_noah</em> creates a file
+ <em class=file>noah_advance_information.txt</em> which contains information
+ to control the length of the NOAH integration.
+ </td>
+ </tr>
+ </table>
+</div>
+
+
+<p>left off here</P>
+<p>left off here</P>
+<p>left off here</P>
+<p>left off here</P>
+<p>left off here</P>
+
+cover the staging of the perfect model experiment
+
+<a name="InitialEnsemble"></a>
+<div class=indent1>
+ <h3>Generating the initial ensemble.</h3>
+ <P>
+ Creating the initial ensemble of ocean states is an area of active research.
+ The NOAH model cannot take one single model state and generate its own
+ ensemble (typically done with <a href="#pert_model_state">pert_model_state</a>).
+ <br />
+ <br />
+ The ensemble has to come from 'somewhere else'.
+ At present, it may be sufficient to use a climatological ensemble; e.g.,
+ using the NOAH restarts for '1 January 00Z' from 50 consecutive years
+ from a hindcast experiment.
+ <br />
+ <br />
+ There is a <em class=program>shell_scripts/MakeInitialEnsemble.csh</em>
+ script that is intended to demonstrate how to convert a set of NOAH netCDF
+ restart files into a set of DART files that have a consistent timestamp.
+ If you simply convert each NOAH file to a DART file using
+ <em class=program>dart_to_noah</em>, each DART file will have a 'valid time'
+ that reflects the NOAH time of that state - instead of an ensemble of states
+ reflecting one single time. The
+ <a href="../../../utilities/restart_file_utility.f90">restart_file_utility</a>
+ can be used to overwrite the timestep in the header of each DART initial
+ conditions file. The namelist for this program must look something like:
+ </P>
+ <pre>
+ &restart_file_tool_nml
+ input_file_name = "<em class=changed>dart.ics</em>",
+ output_file_name = "filter_updated_restart",
+ ens_size = 1,
+ single_restart_file_in = .true.,
+ single_restart_file_out = .true.,
+ write_binary_restart_files = .true.,
+ overwrite_data_time = <em class=changed>.true.</em>,
+ new_data_days = <em class=changed>145731</em>,
+ new_data_secs = <em class=changed>0</em>,
+ input_is_model_advance_file = .false.,
+ output_is_model_advance_file = .false.,
+ overwrite_advance_time = .false.,
+ new_advance_days = -1,
+ new_advance_secs = -1,
+ gregorian_cal = .true. /</pre>
+ <P>
+ The time of days = <em class=changed>145731</em>
+ seconds = <em class=changed>0</em> relates to 00Z 1 Jan 2000 in the DART world.
+ <br />
+ <br />
+ BTW - Experience has shown that having a paired (unique) atmospheric forcing
+ maintains the ensemble spread better than simply forcing all the ocean
+ ensemble members with one single atmospheric state.
+ </P>
+</div>
+
+<a name="POP_OSSE"></a>
+<div class=indent1>
+ <h3>Generating a set of observations for a 'perfect model' experiment using the LANL/NOAH executable and scripts.</h3>
+ <P>
+ A perfectly sensible approach to get to know the system would be to try to
+ </P>
+ <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>
+ 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>
+ <li>advance, assimilate and advance again. This tests the whole DART facility.</li>
+ </ol>
+ <P>
+ I always like running something akin to a 'perfect model' experiment to start.
+ Since I have not come up with a good way to perturb a single model state to
+ generate an ensemble, here's the next best thing. The details for running
+ each program are covered in their own documentation.
+ </P>
+ <ol>
+ <li>Create a set of initial conditions for DART by running one instance of NOAH
+ 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
+ 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
+ not be a problem.
+ </li>
+
+ <li>create a TINY (i.e. 1) set of 'perfect' observations in the normal fashion:
+ <a href="../../../obs_sequence/create_obs_sequence.html">create_obs_sequence</a>
+ 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>).
+ 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 NOAH 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
+ <em class=code>&time_manager_nml</em> will be repeatedly updated
+ as the NOAH model is repeatedly called by
+ <em class=program>advance_model.csh</em>.
+ </li>
+
+ <li>modify <em class=file>NOAH/work/input.nml</em> as needed.
+ </li>
+
+ <li>modify
+ <em class=file>DART/models/NOAH/shell_scripts</em><em class=program>run_perfect_model_obs.batch</em>
+ to reflect the location of your DART directory, the NOAH directory,
+ and which POPFILE to use as the initial condition.
+ </li>
+
+ <li>Run the experiment and populate the observation sequence file by
+ executing/submitting the script
+ <em class=file>DART/models/NOAH/shell_scripts/</em><em class=program>run_perfect_model_obs.batch</em>.
+ The script may require some modification, but not much.
+ Please let me know if I can improve the readability or comments.
+ <em class=program>run_perfect_model_obs.batch</em> runs
+ <a href="../../perfect_model_obs/perfect_model_obs.html">perfect_model_obs</a>
+ </li>
+
+ <li><em class=program>run_filter.batch</em> runs
+ <a href="../../filter/filter.html">filter</a> in a similar fashion.
+ I have not finished the documentation for this yet.
+ </li>
+ </ol>
+</div>
+
+
+<a name="ExploringOutput"></a>
+<div class=indent1>
+ <h3>Exploring the Output.</h3>
+ <P>
+ 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.
+ 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
+ scripts starting with 'plot_', i.e.
+ <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/NOAH/matlab</em>, and
+ <em class=file>DART/models/NOAH/shell_scripts</em>.
+ <br />
+ <br />
+ It is also worthwhile to convert your obs_seq.final file to a netCDF format
+ obs_sequence file with <a href="../../obs_sequence/obs_seq_to_netcdf.html">obs_seq_to_netcdf</a>
+</P>
+</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.
+</P>
+<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 NOAH. It is unimportant for the CESM/POP
+ experiments but is critically important for the LANL/NOAH experiments.
+ The values are explained in full in the NOAH 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_noah</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 NOAH 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 NOAH.
+</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>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>OTHER MODULES USED</H2>
+
+<PRE>
+types_mod
+time_manager_mod
+threed_sphere/location_mod
+utilities_mod
+obs_kind_mod
+mpi_utilities_mod
+random_seq_mod
+dart_pop_mod
+</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>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>
+<TR><TD> </TD><TD><A HREF="#model_interpolate">model_interpolate</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_model_time_step">get_model_time_step</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#static_init_model">static_init_model</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#end_model">end_model</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#init_time">init_time</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#init_conditions">init_conditions</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#nc_write_model_atts">nc_write_model_atts</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#nc_write_model_vars">nc_write_model_vars</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#pert_model_state">pert_model_state</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_close_maxdist_init">get_close_maxdist_init</A></TD></TR>
+<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>
+
+<h3 class=indent1>Unique Interface Routines</h3>
+<TABLE width=50%>
+<TR><TD><em class=call>use model_mod, only : </em></TD>
+ <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>.
+</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 NOAH
+ <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 NOAH <em class=program>model_mod</em> can take that
+ information and adjust as necessary. This creates some logistical issues
+ in that the NOAH 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 />
+<div class=routine>
+<em class=call>model_size = get_model_size( )</em>
+<pre>
+integer :: <em class=code>get_model_size</em>
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+Returns the length of the model state vector.
+Required.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>model_size</em></TD>
+ <TD>The length of the model state vector.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="adv_1step"></A>
+<br />
+<div class=routine>
+<em class=call>call adv_1step(x, time)</em>
+<pre>
+real(r8), dimension(:), intent(inout) :: <em class=code>x</em>
+type(time_type), intent(in) :: <em class=code>time</em>
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<em class=code>adv_1step</em>
+is not used for the NOAH model.
+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>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>x</em></TD>
+ <TD>State vector of length model_size.</TD></TR>
+
+<TR><TD valign=top><em class=code>time </em></TD>
+ <TD>Specifies time of the initial model state.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="get_state_meta_data"></A>
+<br />
+<div class=routine>
+<em class=call>call get_state_meta_data (index_in, location,
+ <em class=optionalcode>[, var_type]</em> )</em>
+<pre>
+integer, intent(in) :: <em class=code>index_in</em>
+type(location_type), intent(out) :: <em class=code>location</em>
+integer, optional, intent(out) :: <em class=optionalcode> var_type </em>
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<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>
+returns information about the native model state vector representation. Things
+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
+to model_mod if required.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>index_in </em></TD>
+ <TD>Index of state vector element about which information is requested.</TD></TR>
+
+<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>.
+ Note that the lat/lon are specified in degrees by the user but are converted
+ to radians internally.</TD></TR>
+
+<TR><TD valign=top><em class=optionalcode>var_type</em></TD>
+ <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>
+ </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>.
+</P>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="model_interpolate"></A>
+<br />
+<div class=routine>
+<em class=call>call model_interpolate(x, location, itype, obs_val, istatus)</em>
+<pre>
+real(r8), dimension(:), intent(in) :: <em class=code>x</em>
+type(location_type), intent(in) :: <em class=code>location</em>
+integer, intent(in) :: <em class=code>itype</em>
+real(r8), intent(out) :: <em class=code>obs_val</em>
+integer, intent(out) :: <em class=code>istatus</em>
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+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
+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>.
+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.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>x</em></TD>
+ <TD>A model state vector.</TD></TR>
+
+<TR><TD valign=top><em class=code>location </em></TD>
+ <TD>Location to which to interpolate.</TD></TR>
+
+<TR><TD valign=top><em class=code>itype</em></TD>
+ <TD>Integer indexing which type of observation is desired.</TD></TR>
+
+<TR><TD valign=top><em class=code>obs_val</em></TD>
+ <TD> The interpolated value from the model.</TD></TR>
+
+<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>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="get_model_time_step"></A>
+<br />
+<div class=routine>
+<em class=call>var = get_model_time_step()</em>
+<pre>
+type(time_type) :: <em class=code>get_model_time_step</em>
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<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="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>NOAH</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>
+
+<TR><TD valign=top><em class=code>var </em></TD>
+ <TD>Smallest time step of model.</TD></TR>
+
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="static_init_model"></A>
+<br />
+<div class=routine>
+<em class=call>call static_init_model()</em>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<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 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 />
+See the NOAH documentation for all namelists in <em class=file>pop_in</em> .
+Be aware that DART reads the NOAH <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 />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="end_model"></A>
+<br />
+<div class=routine>
+<em class=call>call end_model()</em>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<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.
+The grid variables are deallocated.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+</TABLE>
+
+</div>
+<br />
+
+<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+
+<A NAME="init_time"></A>
+<br />
+<div class=routine>
+<em class=call>call init_time(time)</em>
+<pre>
+type(time_type), intent(out) :: <em class=code>time</em>
+</pre>
+</div>
+
+<div class=indent1>
+<!-- Description -->
+
+<P>
+<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 NOAH 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
+not supported in the NOAH model.
+</P>
+
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list