[Dart-dev] [4939] DART/trunk/models/cam/model_mod.html: Extensive revisions by Kevin ( content) and me (formatting).
nancy at ucar.edu
nancy at ucar.edu
Thu Jun 2 10:58:20 MDT 2011
Revision: 4939
Author: nancy
Date: 2011-06-02 10:58:20 -0600 (Thu, 02 Jun 2011)
Log Message:
-----------
Extensive revisions by Kevin (content) and me (formatting).
Modified Paths:
--------------
DART/trunk/models/cam/model_mod.html
-------------- next part --------------
Modified: DART/trunk/models/cam/model_mod.html
===================================================================
--- DART/trunk/models/cam/model_mod.html 2011-06-02 16:27:14 UTC (rev 4938)
+++ DART/trunk/models/cam/model_mod.html 2011-06-02 16:58:20 UTC (rev 4939)
@@ -4,6 +4,7 @@
<HEAD>
<TITLE>module model_mod (CAM)</TITLE>
<link rel="stylesheet" type="text/css" href="../../doc/html/doc.css" />
+<link href="../../doc/html/dart.ico" rel="shortcut icon" />
</HEAD>
<BODY>
<A NAME="TOP"></A>
@@ -24,34 +25,49 @@
</tr>
</table>
-<A HREF="#Namelist">NAMELIST</A> /
-<A HREF="#Interface">INTERFACES</A> /
+<!--
+UPDATE COMMENTS
+ Updated to reflect changes in model_mod:
+ addition of get_close_obs pass-through functionality,
+ conversion of obs on all which_verts to pressure (requires pressure profiles),
+ handling of observations on heights
+ arrangement of subroutines into sections according to functionality
+ Removed description of obsolete routines and added descriptions of new ones.
+ Clarified what are public interfaces versus private subroutines.
+-->
+
+
+<A HREF="#Namelist">NAMELIST</A> /
+<A HREF="#Interface">INTERFACES</A> /
+<A HREF="#PrivateComponents">PRIVATE COMPONENTS</A> /
<A HREF="#FilesUsed">FILES</A> /
<A HREF="#References">REFERENCES</A> /
<A HREF="#Errors">ERRORS</A> /
+<A HREF="#KnownBugs">BUGS</A> /
<A HREF="#FuturePlans">PLANS</A> /
-<A HREF="#PrivateComponents">PRIVATE COMPONENTS</A> /
<A HREF="#Legalese">TERMS OF USE</A>
+
+
+<A NAME="OVERVIEW"></A>
<H2>Overview</H2>
<P>
-The 17 public interfaces in model_mod
-are standardized for all DART compliant models. These interfaces allow
-DART to advance the model, get the model state and metadata describing
-this state, find state variables that are close to a given location,
-and do spatial interpolation for a variety of variables required in
-observational operators.
-</P>
-
-<P>
This is the DART interface module for the stand-alone CAM model,
using the either the Eulerian and Finite Volume dynamical core,
+soon the HOMME core on the cubed sphere,
and possibly the Semi-Lagrangian core.
-It is designed to work for versions of CAM starting with 2.0.1,
+It is designed to work for versions of CAM from 2.0.1
+through the currently released version(s)
by specifying the version number in the model_mod namelist.
-This implementation of DART-CAM uses the CAM (and CLM) initial files for
+This implementation of DART-CAM uses the CAM initial files for
transferring the model state to/from the filter/CAM.
+The intent of this interface design is to facilitate using any CAM
+version with minimal changes to the model_mod code and accompanying scripts.
+Non-state variables, which are updated by the forecasts, are also
+carried forward by the CAM and CLM initial files.
+For CAM 3.6 and later the ICE restart files also carry along non-state variables.
+<!-- (non-NetCDF before cice4_0_20090603 ~? cam3_6_41.). -->
</P>
<P>
@@ -60,10 +76,12 @@
state vector via model_mod namelist entries. This may include quantities
the model considers to be parameters, although ongoing research is
being conducted into the difficulties and meaning of
-assimilating model parameters of various kinds.
-The CLM incorporated in the stand-alone CAM is currently (4/16/2007)
+tuning model parameters of various kinds by this method.
+The CLM incorporated in the stand-alone CAM is currently (2011-4)
treated as a parameterization. That is, none of its variables
are incorporated into the DART state vector.
+For each distinct set of fields comprizing a state vector,
+an ensemble of initial files for the program 'filter' must be created.
</P>
<P>
@@ -71,77 +89,76 @@
from model_interpolate. Surface observations can not yet be interpolated,
due to the difference between the model surface and the earth's surface
where the observations are made. Model_interpolate can be queried for any
-(non-surface) variable in the state vector, which are variables native to
-CAM, plus pressure on height levels. The default state vector is (PS), T,
-U, V, Q, CLDLIQ, CLDICE. Other variables can be added, but minor
-modifications to model_mod.f90 will be necessary. Use the existing code
-for the current state variables as a template. In particular add the
-TYPE_s in the declarations at the beginning of the module, and see
-subroutines <em class=code>order_state_fields and obs_field_location</em>,
-where those TYPE_s are used. Modify CAM to write the new fields to the
-initial files, and modify the <em class=code>model_mod_nml</em>
-(in <em class=file>input.nml</em>) to include the new state vector components.
-In the namelist the vertical coordinate type of the new fields must also be
-specified. See <em class=code>which_vert</em> in
-<A HREF="../../location/threed_sphere/location_mod.html"> location_mod </A>
+(non-surface) variable in the state vector (which are variables native to
+CAM) plus pressure on height levels. The default state vector is PS, T,
+U, V, Q, CLDLIQ, CLDICE.
+Variables which are not on the initial file
+<A HREF="./doc/cam_guidelines.html" >can be added </A> ,
+but minor modifications to model_mod.f90 (and perhaps CAM) may be necessary.
</P>
<P>
-Links to information about
+The 16 public interfaces in model_mod
+are standardized for all DART compliant models. These interfaces allow
+DART to advance the model, get the model state and metadata describing
+this state, find state variables that are close to a given location,
+and do spatial interpolation for a variety of variables required by
+observational operators.
+</P>
+
+<P>
+Help with several aspects of
<A HREF="doc/cam_guidelines.html" > setting up assimilation experiments </A>
-using CAM and parallel architecture computers, including:
-</P>
+using CAM and parallel architecture computers is available:
<UL>
- <LI> script and executable calling tree </LI>
- <LI> file contents and purposes</LI>
- <LI> output directory structure for use by obs_diag</LI>
- <LI> experiment set-up</LI>
- <LI> helpful hints</LI>
- <LI> space requirements of various CAM resolutions</LI>
+ <LI> <A HREF="doc/cam_guidelines.html#SET-UP"> experiment set-up </A> </LI>
+ <LI> <A HREF="doc/cam_guidelines.html#INITIAL FILES">creating initial ensembles </A> </LI>
+ <LI> <A HREF="doc/cam_guidelines.html#CALLING TREE"> script and executable calling tree </A> </LI>
+ <LI> <A HREF="doc/cam_guidelines.html#OUTPUT DIRECTORY"> output directory structure for use by obs_diag </A> </LI>
+ <LI> <A HREF="doc/cam_guidelines.html#FILE CONTENTS"> file contents and purposes </A> </LI>
+ <LI> <A HREF="doc/cam_guidelines.html#HINTS"> helpful hints </A> </LI>
+ <LI> <A HREF="doc/cam_guidelines.html#SPACE"> space requirements of various CAM resolutions </A> </LI>
</UL>
+</P>
<!--==================================================================-->
-<!--=================== DESCRIPTION OF A NAMELIST ====================-->
-<!--==================================================================-->
+<!--=================== 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.
-The declarations have a different syntax, naturally.
-</P>
+<P>We adhere to the F90 standard of starting a namelist with an ampersand
+'&' and terminating with a slash '/'.
<div class=namelist>
<pre>
-<em class=call>namelist / model_nml / </em> &
- output_state_vector, model_version, model_config_file, &
- state_num_0d, state_num_1d, state_num_2d, state_num_3d, &
- state_names_0d, state_names_1d, state_names_2d, state_names_3d, &
- which_vert_1d, which_vert_2d, which_vert_3d, &
- pert_names, pert_sd, pert_base_vals, &
- highest_obs_pressure_mb, highest_state_pressure_mb, &
- max_obs_lat_degree, Time_step_seconds, Time_step_days
+<em class=call>namelist / model_nml / </em> &
+ output_state_vector, model_version, model_config_file, &
+ state_num_0d, state_num_1d, state_num_2d, state_num_3d, &
+ state_names_0d, state_names_1d, state_names_2d, state_names_3d, &
+ which_vert_1d, which_vert_2d, which_vert_3d, &
+ pert_names, pert_sd, pert_base_vals, &
+ highest_obs_pressure_mb, highest_state_pressure_mb ,max_obs_lat_degree, &
+ Time_step_seconds, Time_step_days, impact_only_same_kind, print_details
+
</pre>
</div>
+</P>
-<div class=indent1>
-<!-- Description -->
-
<P>
-This namelist is read in a file called <em class=file>input.nml</em>
+This namelist is read from a file called <em class=file>input.nml</em>
The specification of lists of names and numbers for the various dimensions
enables the very flexible definition of the state vector. It can be
done via the namelist, instead of recompiling DART for each different set.
-One hurdle that still remains is that distinct filter_ics are
-necessary for each separate set of fields which compose the state vector.
+One hurdle that still remains is that distinct filter initial condition files are
+necessary for each distinct set of fields which compose the state vector.
</P>
<P>
The dimension of these lists is currently hardwired to size 100.
-If more variables types need to be assimilated (e.g. many chemical species),
+If more fields need to be assimilated (e.g. many chemical species),
look for the integer parameter MAX_STATE_NAMES in the source code
and change it to a long enough value and recompile DART.
-Longer term we intend to investigate using 2 different nameslists
+Longer term we intend to investigate using 2 different namelists
inside model_mod; one for setting the length of the lists and another
to actually read in the data which fills the lists.
</P>
@@ -234,7 +251,7 @@
<TR><!--contents--><TD valign=top>highest_obs_pressure_mb </TD>
<!-- type --><TD valign=top>real(r8) </TD>
<!--descript--><TD>Observations higher than this pressure are ignored.
- Default 150.0 hPa </TD></TR>
+ Default 150.0 hPa (Use 100. for GPS) </TD></TR>
<TR><!--contents--><TD valign=top>highest_state_pressure_mb </TD>
<!-- type --><TD valign=top>real(r8) </TD>
<!--descript--><TD>Influence of all obs on model points higher than
@@ -242,73 +259,88 @@
Default 150.0 hPa </TD></TR>
<TR><!--contents--><TD valign=top>Time_step_seconds </TD>
<!-- type --><TD valign=top>real(r8) </TD>
- <!--descript--><TD>Forecast duration (the part < 1 day)
+ <!--descript--><TD>Minimum forecast duration (the part < 1 day)
Default 21600 sec </TD></TR>
<TR><!--contents--><TD valign=top>Time_step_days </TD>
<!-- type --><TD valign=top>real(r8) </TD>
- <!--descript--><TD>Forecast duration (the part > 24*3600 sec)
+ <!--descript--><TD>Minimum forecast duration (the part > 24*3600 sec)
Default 0 days </TD></TR>
+<TR><!--contents--><TD valign=top>impact_only_same_kind </TD>
+ <!-- type --><TD valign=top>character(len=32) </TD>
+ <!--descript--><TD>Name of one observation kind which can only affect
+ state variables of the same kind.
+ Default ' ' </TD></TR>
+<TR><!--contents--><TD valign=top>print_details </TD>
+ <!-- type --><TD valign=top>logical </TD>
+ <!--descript--><TD>If true, print out detailed information about
+ the sizes, shapes, offsets, etc of items in the
+ CAM state vector. If false, just print out the
+ names of the fields as they are read into the state
+ vector.
+ Default .FALSE. </TD></TR>
</TABLE>
-
-</div>
<br>
<!--==================================================================-->
-<!--==================================================================-->
-<A NAME="OtherModulesUsed"></A>
+<A NAME="OTHER MODULES USED"></A>
<HR>
<H2>OTHER MODULES USED</H2>
<PRE>
- netcdf
- obs_kind_mod
- random_nr_mod
- random_seq_mod
- threed_sphere/location_mod
- time_manager_mod
- types_mod
- utilities_mod
- mpi_utilities (or null_mpi_utilities, depending on the calling program)
+obs_kind_mod
+random_nr_mod
+random_seq_mod
+threed_sphere/location_mod
+time_manager_mod
+types_mod
+utilities_mod
+mpi_utilities
</PRE>
<!--==================================================================-->
-<!-- Declare all public entities ... -->
-<!-- duplicate public routines template as many times as necessary -->
-<!-- make sure you replace all yyyroutine?? strings -->
-<!--==================================================================-->
-<!--Note to authors. The first row of the table is different. -->
-<!--==================================================================-->
+<A NAME="PublicEntities"></A>
+
<A NAME="Interface"></A>
<HR>
<H2>PUBLIC INTERFACES</H2>
+<H4>FILTER INTERFACE</H4>
+<P>
+Here they are listed alphabetically, except for the last 4 interfaces,
+which are only required for low-order models where advancing
+the model can be done by a call to a subroutine.
+The CAM model only advances by executing the program cam (via script run-pc.csh).
+Thus the last 4 interfaces only appear as stubs in the CAM module.
+Following this list they are listed in
+the order in which they appear in model_mod.f90, which is separated into sections
+corresponding to the main functions of model_mod.f90: static_init_model,
+I/O, model_interpolate, vector<->field translations, get_close_obs, and
+utility routines.
+</P>
+
<TABLE>
<TR><TD><em class=call>use model_mod, only : </em></TD>
- <TD><A HREF="#get_model_size">get_model_size</A></TD></TR>
+ <TD><A HREF="#ens_mean_for_model">ens_mean_for_model</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="#get_model_time_step">get_model_time_step</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#get_model_size">get_model_size</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="#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>
+<TR><TD> </TD><TD><A HREF="#static_init_model">static_init_model</A></TD></TR>
<TR><TD> </TD><TD><A HREF="#adv_1step">adv_1step</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>
</TABLE>
+
<P>
-The last 4 interfaces are only required for low-order models where advancing
-the model can be done by a call to a subroutine. The CAM model only advances by
-executing the program cam (via script run-pc.csh). Thus the last 4 interfaces
-only appear as stubs in the CAM module.
-<br><br>
The interface pert_model_state is provided for CAM, and it allows each
field of the state vector to be randomly perturbed using a separate
standard deviation. Even this may not be flexible enough to handle
@@ -316,57 +348,73 @@
from the surface to the top of the model.
</P>
+<H4>OTHER PUBLIC INTERFACES</H4>
<P>
-Optional namelist interface
-<a href="#Namelist"><em class=code>&model_nml</em></a>
-may be read from file <em class=file>input.nml</em>.
+The list of interfaces above is part of the list of public routines in this module.
+The rest of the public list are used by programs other than filter;
+dart_to_cam, cam_to_dart, etc.
</P>
+<TABLE>
+<TR><TD><em class=call>use model_mod, only : </em></TD>
+ <TD><A HREF="#prog_var_to_vector">prog_var_to_vector</A></TD></TR>
+<TR><TD> </TD><TD><A HREF="#read_cam_init">read_cam_init</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="#write_cam_init">write_cam_init</A></TD></TR>
+</TABLE>
+
<P>
- A note about documentation style.
- Optional arguments are enclosed in brackets
- <em class=optionalcode>[like this]</em>.
+Namelist interface
+<A HREF="#Namelist"> <em class=code>&model_nml</em> </A>
+is read from file <em class=file>input.nml</em>.
</P>
-<!--===================== DESCRIPTION OF FUNCTION ====================-->
+<br><br>
+<!--==================================================================-->
+<!-- Declare all public entities ... -->
+<!-- duplicate public routines template as many times as necessary -->
+<!--==================================================================-->
-<A NAME="get_model_size"></A>
-<br>
+
+<!--================================================================-->
+<!--=================== DESCRIPTION OF SUBROUTINE ====================-->
+
+<A NAME="static_init_model"></A>
<div class=routine>
-<em class=call> model_size = get_model_size( )</em>
+<em class=call>call static_init_model( )</em>
<pre>
-integer :: <em class=code> get_model_size </em>
-</pre>
-</div>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
-Returns the length of the model state vector as an integer. This includes all
-nested domains.
+Used for runtime initialization of the model. This is the first call made
+to the model by any DART compliant assimilation routine. It reads the
+model_mod namelist parameters, sets the calendar type (the GREGORIAN
+calendar is used with the CAM model), and determines the dart vector
+length, among other things. This subroutine requires that caminput.nc
+(or the name in namelist variable model_config_file) be present in the working
+directory to retrieve model information (grid dimensions and spacing
+including the vertical hybrid coordinate coefficients, time step, and
+Gaussian weights, etc).
</P>
-
</div>
-<br>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+<!--================================================================-->
+<!--=================== DESCRIPTION OF SUBROUTINE ====================-->
+
<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>
+ <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>
+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=code> var_type </em>
+</pre></div>
+
<div class=indent1>
-<!-- Description -->
-
<P>
Returns metadata about a given element, indexed by index_in, in the model
state vector. The location defines where the state variable is located
@@ -377,101 +425,70 @@
</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>index_in</em></TD>
+ <TD>Index into the long state vector.</TD></TR>
<TR><TD valign=top><em class=code>location</em></TD>
<TD>Returns location of indexed state variable. The location should
use a location_mod that is appropriate for the model domain. For
realistic atmospheric models, for instance, a three-dimensional
spherical location module that can represent height in a variety
of ways is provided. </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.</TD></TR>
-
</TABLE>
+<br>
+</div>
+<!--=================================================================-->
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+
+ <A NAME="ens_mean_for_model"></A>
+ <div class=routine>
+ <em class=call> call ens_mean_for_model(ens_mean) </em>
+ <pre>
+ real(r8), dimension(:), intent(in) :: <em class=code>ens_mean</em>
+ </pre></div>
+
+<div class=indent1>
+ <P>
+saves a local copy of the ensemble means which can be used for
+computing vertical heights, for example.
+ </P>
+ <TABLE width=100% border=0 summary="" celpadding=3>
+ <TR><TD valign=top><em class=code>ens_mean </em></TD>
+ <TD>Ensemble mean state vector</TD></TR>
+ </TABLE>
+<br>
</div>
-<br>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+<!--================================================================-->
+<!--===================== DESCRIPTION OF FUNCTION ====================-->
-<A NAME="model_interpolate"></A>
-<br>
+<A NAME="get_model_size"></A>
<div class=routine>
-<em class=call>call model_interpolate(x, location, obs_type, interp_val, istatus)</em>
+<em class=call> model_size = get_model_size( )</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>obs_type</em>
-real(r8), intent(out) :: <em class=code>interp_val</em>
-integer, intent(out) :: <em class=code>istatus</em>
-</pre>
-</div>
+integer :: <em class=code> get_model_size </em>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
-Given model state, returns the value of observation type interpolated to a
-given location by a method of the model's choosing. Currently observation
-types: KIND_U_WIND_COMPONENT, KIND_V_WIND_COMPONENT, KIND_SURFACE_PRESSURE,
-KIND_TEMPERATURE, KIND_SPECIFIC_HUMIDITY, KIND_PRESSURE are supported, but
-others can be added. KIND_PRESSURE does not have a corresponding field on
-CAM initial files, but is routinely calculated in CAM using its own
-subroutines. Interpolation of this field has been incorporated in order to
-facilitate assimilations of observations which require it, such as GPS
-radio occultation. If the interpolation is valid, istatus = 0. In the
-case where the observational operator is not defined at the given location
-(e.g. the observation is below the lowest model level or above the top
-level), interp_val is returned as 0.0 and istatus = 1. CAM is highly
-damped in the upper levels of the model, which has required the exclusion
-of otherwise valid observations above a certain level, which can be
-specified in the model_mod namelist variable highest_obs_pressure_mb. Such
-cases return istatus = 2, and also do the interpolation and return the
-value, which is NOT used by filter. Eventually such quality control may be
-moved to another module, but for now is performed in subroutine
-get_val_pressure.
+Returns the length of the model state vector as an integer. This includes all
+nested domains.
</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>obs_type</em></TD>
- <TD>Integer indexing which type of observation is to be interpolated.</TD></TR>
-
-<TR><TD valign=top><em class=code>interp_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.</TD></TR>
-
-</TABLE>
-
</div>
-<br>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+<!--================================================================-->
+<!--==================== DESCRIPTION OF FUNCTION =====================-->
<A NAME="get_model_time_step"></A>
-<br>
<div class=routine>
-<em class=call>var = get_model_time_step()</em>
+<em class=call> var = get_model_time_step( )</em>
<pre>
-type(time_type) :: <em class=code>get_model_time_step</em>
-</pre>
-</div>
+type(time_type) :: <em class=code> get_model_time_step </em>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
Returns the forecast length to be used as the "model base time step" in the filter.
The choice of initial files instead of restart files restricts the
@@ -483,97 +500,235 @@
In the long run, a more general extended interface may be required that specifies
the models range of time stepping possibilities.
</P>
+</div>
+<!--=================================================================-->
+<!--==================== DESCRIPTION OF FUNCTION =====================-->
+
+<A NAME="nc_write_model_atts"></A>
+<div class=routine>
+<em class=call> ierr = nc_write_model_atts(ncFileId) </em>
+<pre>
+integer, :: <em class=code> nc_write_model_atts </em>
+integer, intent(in) :: <em class=code> ncFileId </em>
+</pre></div>
+
+<div class=indent1>
+<P>
+ Function to write model specific attributes to a netCDF file. At present, DART
+is using the NetCDF format to output diagnostic information. This is not a
+requirement, and models could choose to provide output in other formats. This function
+writes the metadata associated with the model to a NetCDF file opened to a file
+identified by ncFileID.
+</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>
+<TR><TD valign=top><em class=code>ncFileId </em></TD>
+ <TD>Integer file descriptor opened to NetCDF file.</TD></TR>
+<TR><TD valign=top><em class=code>ierr</em></TD>
+ <TD>Returned error code.</TD></TR>
+
</TABLE>
-
+<br>
</div>
-<br>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+<!--================================================================-->
+<!--==================== DESCRIPTION OF FUNCTION =====================-->
-<A NAME="static_init_model"></A>
-<br>
+<A NAME="nc_write_model_vars"></A>
<div class=routine>
-<em class=call>call static_init_model()</em>
-</div>
+<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>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
-Used for runtime initialization of the model. This is the first call made
-to the model by any DART compliant assimilation routine. It reads the
-model_mod namelist parameters, sets the calendar type (the GREGORIAN
-calendar is used with the CAM model), and determines the dart vector
-length, among other things. This subroutine requires that caminput.nc
-(or the name in namelist variable model_config_file) be present in the working
-directory to retrieve model information (grid dimensions and spacing
-including the vertical hybrid coordinate coefficients, time step, and
-Gaussian weights, etc).
+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.
</P>
<TABLE width=100% border=0 summary="" cellpadding=3>
-</TABLE>
-</div>
-<br>
+<TR><TD valign=top><em class=code>ncFileID </em></TD>
+ <TD>Integer file descriptor to opened NetCDF file.</TD></TR>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
+<TR><TD valign=top><em class=code>statevec</em></TD>
+ <TD>State vector.</TD></TR>
-<A NAME="get_close_maxdist_init"></A>
+<TR><TD valign=top><em class=code>copyindex</em></TD>
+ <TD> Integer index to which copy is to be written. </TD></TR>
+
+<TR><TD valign=top><em class=code>timeindex</em></TD>
+ <TD>Integer index of which time in the file is being written.</TD></TR>
+
+<TR><TD valign=top><em class=code>ierr</em></TD>
+ <TD>Returned error code. success == 0, failure == -1</TD></TR>
+
+</TABLE>
<br>
+</div>
+
+<!--================================================================-->
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="read_cam_init"></A>
<div class=routine>
-<em class=call> call get_close_maxdist_init(gc, maxdist) </em>
+<em class=call> call read_cam_init(file_name,var) </em>
<pre>
-type(get_close_type), intent(inout) :: <em class=code>gc</em>
-real(r8), intent(in) :: <em class=code>maxdist</em>
-</pre>
-</div>
+character(len, intent(in) :: <em class=code>file_name</em>
+type(model_type), intent(out) :: <em class=code>var</em>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
-Pass-through to the 3-D sphere locations module routine of the same name. See
-<A HREF="../../location/threed_sphere/location_mod.html#get_close_maxdist_init">
-location_mod:get_close_maxdist_init()</A> for the documentation of this subroutine.
+Reads state vector fields from a CAM initial file. Fields are specified in model_mod.nml.
</P>
+<TABLE width=100% border=0 summary="" celpadding=3>
+<TR><TD valign=top><em class=code>file_name </em></TD>
+ <TD>CAM initial file name.</TD></TR>
+<TR><TD valign=top><em class=code>var </em></TD>
+ <TD>Structure to hold the state vector fields read from file_name.</TD></TR>
+</TABLE>
+<br>
+</div>
+
+ <!--================================================================-->
+ <!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+ <A NAME="write_cam_init"></A>
+ <div class=routine>
+ <em class=call> call write_cam_init(file_name,var) </em>
+ <pre>
+ character, intent(in) :: <em class=code>file_name</em>
+ type(model_type), allocatable, intent(in) :: <em class=code>var</em>
+ </pre></div>
+ <div class=indent1>
+ <P>
+ Write fields that have been updated by assimilation to the CAM 'initial' file.
+ </P>
+ <TABLE width=100% border=0 summary="" celpadding=3>
+ <TR><TD valign=top><em class=code>file_name </em></TD>
+ <TD>Name of CAM initial file to which var will be written.</TD></TR>
+ <TR><TD valign=top><em class=code>var </em></TD>
+ <TD>Structure containing all the fields of the state vector.</TD></TR>
+ </TABLE>
+<br>
</div>
-<br>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
-<A NAME="get_close_obs_init"></A>
-<br>
+<!--================================================================-->
+<!--=================== DESCRIPTION OF SUBROUTINE ====================-->
+
+<A NAME="model_interpolate"></A>
<div class=routine>
-<em class=call> call get_close_obs_init(gc, num, obs) </em>
+<em class=call> call model_interpolate(x, location, obs_type, interp_val, istatus)</em>
<pre>
-type(get_close_type), intent(inout) :: <em class=code>gc</em>
-integer, intent(in) :: <em class=code>num</em>
-type(location_type), intent(in) :: <em class=code>obs(num)</em>
-</pre>
-</div>
+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> obs_type </em>
+real(r8), intent(out) :: <em class=code> interp_val </em>
+integer, intent(out) :: <em class=code> istatus </em>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
-Pass-through to the 3-D sphere locations module. See
-<A HREF="../../location/threed_sphere/location_mod.html#get_close_obs_init">
-get_close_obs_init()</A> for the documentation of this subroutine.
+Given model state, returns the value of observation type interpolated to a
+given location by a method of the model's choosing. Currently observation
+types: KIND_U_WIND_COMPONENT, KIND_V_WIND_COMPONENT, KIND_SURFACE_PRESSURE,
+KIND_TEMPERATURE, KIND_SPECIFIC_HUMIDITY, KIND_PRESSURE are supported, but
+others can be added. KIND_PRESSURE does not have a corresponding field on
+CAM initial files, but is routinely calculated in CAM using its own
+subroutines. Interpolation of this field has been incorporated in order to
+facilitate assimilations of observations which require it, such as GPS
+radio occultation. If the interpolation is valid, istatus = 0. In the
+case where the observational operator is not defined at the given location
+(e.g. the observation is below the lowest model level or above the top
+level), interp_val is returned as 0.0 and istatus = 1. CAM is highly
+damped in the upper levels of the model, which has required the exclusion
+of otherwise valid observations above a certain level, which can be
+specified in the model_mod namelist variable highest_obs_pressure_mb. Such
+cases return istatus = 2, and also do the interpolation and return the
+value, which is NOT used by filter. Eventually such quality control may be
+moved to another module, but for now is performed in subroutine
+get_val_pressure.
</P>
+<TABLE width=100% border=0 summary="" cellpadding=3>
+
+<TR><TD valign=top><em class=code>x </em></TD>
+ <TD>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>obs_type</em></TD>
+ <TD>Integer indexing which type of observation is to be interpolated.</TD></TR>
+
+<TR><TD valign=top><em class=code>interp_val</em></TD>
+ <TD>Value interpolated to location.</TD></TR>
+
+<TR><TD valign=top><em class=code>istatus</em></TD>
+ <TD>Integer flag indicating the success of the interpolation.</TD></TR>
+
+</TABLE>
+<br>
</div>
+
+ <!--================================================================-->
+ <!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+ <A NAME="prog_var_to_vector"></A>
+ <div class=routine>
+ <em class=call> call prog_var_to_vector(var,x) </em>
+ <pre>
+ type(model_type), allocatable, intent(in) :: <em class=code>var</em>
+ real(r8), allocatable, dimension(:), intent(out) :: <em class=code>x</em>
+ </pre></div>
+
+ <div class=indent1>
+ <P>
+ Insert CAM fields (N-D) into DART state vector array (1-D)
+ </P>
+ <TABLE width=100% border=0 summary="" celpadding=3>
+ <TR><TD valign=top><em class=code>var </em></TD>
+ <TD>Structure containing all the fields of the state vector.</TD></TR>
+ <TR><TD valign=top><em class=code>x </em></TD>
+ <TD>DART state vector.</TD></TR>
+ </TABLE>
<br>
+</div>
+ <!--================================================================-->
+ <!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+ <A NAME="vector_to_prog_var"></A>
+ <div class=routine>
+ <em class=call> call vector_to_prog_var(x,var) </em>
+ <pre>
+ real(r8), allocatable, dimension(:), intent(in) :: <em class=code>x</em>
+ type(model_type), allocatable, intent(out) :: <em class=code>var</em>
+ </pre></div>
+
+ <div class=indent1>
+ <P>
+ Extract CAM fields (N-D) from state vector (1-D).
+ </P>
+ <TABLE width=100% border=0 summary="" celpadding=3>
+ <TR><TD valign=top><em class=code>x </em></TD>
+ <TD>DART state vector.</TD></TR>
+ <TR><TD valign=top><em class=code>var </em></TD>
+ <TD>Structure containing all the fields of the state vector.</TD></TR>
+ </TABLE>
+<br>
+</div>
+
+<!--=================================================================-->
<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
<A NAME="get_close_obs"></A>
-<br>
<div class=routine>
<em class=call> call get_close_obs(gc, base_obs_loc, base_obs_kind,
obs, obs_kind, num_close, close_ind
@@ -587,19 +742,17 @@
integer, intent(out) :: <em class=code>num_close</em>
integer, intent(out) :: <em class=code>close_ind(:)</em>
real(r8), optional, intent(out) :: <em class=optionalcode>dist(:)</em>
-</pre>
-</div>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
First calls the location module code and then updates
the distances to accomodate damping CAM's highest levels.
Pass-through to the 3-D sphere locations module. See
<A HREF="../../location/threed_sphere/location_mod.html#get_close_obs">
get_close_obs()</A> for the documentation of this subroutine.
-<br><br>
+
+<P>
CAM uses a hybrid vertical coordinate, which requires the surface pressure
beneath a point in order to determine the point's vertical coordinate.
When the model state vector is divided up among several regions during
@@ -616,140 +769,59 @@
ensemble mean for calculations. The influence declines
to 0 above model level 6 for <em class="code">highest_obs_pressure_mb = 150</em>
( ~ model level 12).
-
</P>
-
</div>
-<br>
-
+<!--=================================================================-->
<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
-<A NAME="ens_mean_for_model"></A>
-<br>
+<A NAME="get_close_maxdist_init"></A>
<div class=routine>
-<em class=call> call ens_mean_for_model(ens_mean) </em>
+<em class=call> call get_close_maxdist_init(gc, maxdist) </em>
<pre>
-real(r8), dimension(:), intent(in) :: <em class=code>ens_mean</em>
-</pre>
-</div>
+type(get_close_type), intent(inout) :: <em class=code>gc</em>
+real(r8), intent(in) :: <em class=code>maxdist</em>
+</pre></div>
<div class=indent1>
-<!-- Description -->
-
<P>
-saves a local copy of the ensemble means which can be used for
-computing vertical heights, for example.
+Pass-through to the 3-D sphere locations module routine of the same name. See
+<A HREF="../../location/threed_sphere/location_mod.html#get_close_maxdist_init">
+location_mod:get_close_maxdist_init()</A> for the documentation of this subroutine.
</P>
-
-<TABLE width=100% border=0 summary="" cellpadding=3>
-
-<TR><TD valign=top><em class=code>ens_mean </em></TD>
-
- <TD>State vector containing the ensemble mean.</TD></TR>
-
-</TABLE>
-
</div>
-<br>
-<!--===================== DESCRIPTION OF A ROUTINE =====================-->
-
-<A NAME="nc_write_model_atts"></A>
-<br>
+<!--=================================================================-->
+<!--============= DESCRIPTION OF A SUBROUTINE =======================-->
+<A NAME="get_close_obs_init"></A>
<div class=routine>
-<em class=call>ierr = nc_write_model_atts(ncFileID)</em>
+<em class=call> call get_close_obs_init(gc, num, obs) </em>
<pre>
-integer :: <em class=code>nc_write_model_atts</em>
-integer, intent(in) :: <em class=code>ncFileID</em>
-</pre>
-</div>
+type(get_close_type), intent(inout) :: <em class=code>gc</em>
+integer, intent(in) :: <em class=code>num</em>
+type(location_type), intent(in) :: <em class=code>obs(num)</em>
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list