[Dart-dev] [6666] DART/trunk: commit new documentation for the MPAS atmosphere contributed by
nancy at ucar.edu
nancy at ucar.edu
Tue Dec 10 16:40:26 MST 2013
Revision: 6666
Author: nancy
Date: 2013-12-10 16:40:25 -0700 (Tue, 10 Dec 2013)
Log Message:
-----------
commit new documentation for the MPAS atmosphere contributed by
so-young ha. update the nml file to match, and change the
defaults in the code slightly to be more appropriate.
add two figures used in the model documentation, and add
an emphasis type that is in a monospaced font but is red
to the stylesheet.
Modified Paths:
--------------
DART/trunk/doc/html/doc.css
DART/trunk/models/mpas_atm/model_mod.f90
DART/trunk/models/mpas_atm/model_mod.html
DART/trunk/models/mpas_atm/model_mod.nml
Added Paths:
-----------
DART/trunk/doc/images/MPAS_WindDA_options.png
DART/trunk/doc/images/MPAS_grid_structure.png
-------------- next part --------------
Modified: DART/trunk/doc/html/doc.css
===================================================================
--- DART/trunk/doc/html/doc.css 2013-12-10 20:33:45 UTC (rev 6665)
+++ DART/trunk/doc/html/doc.css 2013-12-10 23:40:25 UTC (rev 6666)
@@ -246,6 +246,10 @@
color:cornflowerblue;
font-family:sans-serif;}
+em.redtt{
+ color:crimson;
+ font-family:monospace;}
+
em{
font-family:sans-serif;
color:red;}
Added: DART/trunk/doc/images/MPAS_WindDA_options.png
===================================================================
(Binary files differ)
Property changes on: DART/trunk/doc/images/MPAS_WindDA_options.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Added: DART/trunk/doc/images/MPAS_grid_structure.png
===================================================================
(Binary files differ)
Property changes on: DART/trunk/doc/images/MPAS_grid_structure.png
___________________________________________________________________
Added: svn:mime-type
+ image/png
Modified: DART/trunk/models/mpas_atm/model_mod.f90
===================================================================
--- DART/trunk/models/mpas_atm/model_mod.f90 2013-12-10 20:33:45 UTC (rev 6665)
+++ DART/trunk/models/mpas_atm/model_mod.f90 2013-12-10 23:40:25 UTC (rev 6666)
@@ -161,7 +161,7 @@
! variables which are in the module namelist
integer :: vert_localization_coord = VERTISHEIGHT
integer :: assimilation_period_days = 0
-integer :: assimilation_period_seconds = 60
+integer :: assimilation_period_seconds = 21600
real(r8) :: model_perturbation_amplitude = 0.0001 ! tiny amounts
real(r8) :: highest_obs_pressure_mb = 100.0_r8 ! do not assimilate obs higher than this level.
real(r8) :: sfc_elev_max_diff = -1.0_r8 ! do not assimilate if |model - station| height is larger than this [m].
@@ -170,8 +170,8 @@
integer :: debug = 0 ! turn up for more and more debug messages
integer :: xyzdebug = 0
character(len=32) :: calendar = 'Gregorian'
-character(len=256) :: model_analysis_filename = 'mpas_analysis.nc'
-character(len=256) :: grid_definition_filename = 'mpas_analysis.nc'
+character(len=256) :: model_analysis_filename = 'mpas_init.nc'
+character(len=256) :: grid_definition_filename = 'mpas_init.nc'
! if .false. use U/V reconstructed winds tri interp at centers for wind forward ops
! if .true. use edge normal winds (u) with RBF functs for wind forward ops
@@ -207,7 +207,8 @@
use_rbf_option, &
update_u_from_reconstruct, &
use_increments_for_u_update, &
- highest_obs_pressure_mb
+ highest_obs_pressure_mb, &
+ sfc_elev_max_diff
! DART state vector contents are specified in the input.nml:&mpas_vars_nml namelist.
integer, parameter :: max_state_variables = 80
Modified: DART/trunk/models/mpas_atm/model_mod.html
===================================================================
--- DART/trunk/models/mpas_atm/model_mod.html 2013-12-10 20:33:45 UTC (rev 6665)
+++ DART/trunk/models/mpas_atm/model_mod.html 2013-12-10 23:40:25 UTC (rev 6666)
@@ -37,60 +37,388 @@
<H2>Overview</H2>
-<P>The <strong>MPAS ATM </strong> interface for
- <strong>Data Assimilation Research Testbed (DART)</strong> is under development.
+<P>This document describes the DART interface module for
+the MPAS-Atmosphere (or briefly, MPAS-ATM) global model,
+which uses an unstructured Voronoi grid mesh, formally Spherical Centriodal Voronoi
+Tesselations (SCVTs). This allows for both quasi-uniform discretization of the sphere and
+local refinement. The MPAS/DART interface was built on the SCVT-dual mesh and does not
+regrid to regular lat/lon grids. In the C-grid discretization, the normal component of
+velocity on cell edges is prognosed; zonal and meridional wind components are diagnosed
+on the cell centers. We provide several options to choose from in the assimilation
+of wind observations as shown below.
</P>
- <br />
- <br />
<P>
- Since MPAS ATM uses netcdf files for their restart mechanism,
- a namelist-controlled set of variables is used to build the DART state vector.
- Each variable must also correspond to a DART "KIND"; required for the DART
- interpolate routines. For example:
+The grid terminology used in MPAS is as shown in the figure below:
</P>
-<pre>&mpas_vars_nml
- mpas_state_variables = 'uReconstructZonal', 'KIND_U_WIND_COMPONENT',
- 'uReconstructMeridional', 'KIND_V_WIND_COMPONENT',
- 'w', 'KIND_VERTICAL_VELOCITY',
- 'theta', 'KIND_POTENTIAL_TEMPERATURE',
- 'qv', 'KIND_VAPOR_MIXING_RATIO',
- 'qc', 'KIND_CLOUDWATER_MIXING_RATIO',
- 'qr', 'KIND_RAINWATER_MIXING_RATIO',
- 'qi', 'KIND_ICE_MIXING_RATIO',
- 'qs', 'KIND_SNOW_MIXING_RATIO',
- 'qg', 'KIND_GRAUPEL_MIXING_RATIO',
- 'surface_pressure', 'KIND_SURFACE_PRESSURE'
- /
+<img src="../../doc/images/MPAS_grid_structure.png" alt="MPAS_grid_structure" height=600 />
+<P>
+The wind options during a DART assimilation
+are controlled by combinations of 4 different namelist options.
+The options control how the forward operators compute expected observation values;
+how the horizontal interpolation is computed; and how the assimilation increments
+are applied to update the wind quantities in the state vector. Preliminary
+experimental results indicate that using the zonal and meridional winds
+for the forward operator fields and using Barycentric interpolation leads
+to the smoothest estimates of wind quantities, and using increments to update
+the <i>u</i> field gives the least noisy increments. However there remains
+scientific questions about how best to handle the wind fields under different
+situations. Thus we have kept all implemented options available for use in
+experimental comparisons. See the figure below for a flow-chart representation
+of how the 4 namelist items interact:
+</P>
+<img src="../../doc/images/MPAS_WindDA_options.png" alt="WindDA_options" height=600 />
+<P>
+Cycling of MPAS/DART is run in a <u>restart</u> mode.
+As for all DART experiments, the overall design for an experiment is this:
+the DART program <em class="program">filter</em> will read the initial
+condition file, the observation sequence file, and the DART namelist
+to decide whether or not to advance the MPAS-ATM model. All of the
+control of the execution of the MPAS model is done by DART directly.
+If the model needs to be advanced, <em class="program">filter</em> makes
+a call to the shell to execute the script
+<em class="program">advance_model.csh</em>,
+which is ENTIRELY responsible
+for getting all the input files, data files, namelists, etc. into
+a temporary directory, running the model, and copying the results
+back to the parent directory (which we call CENTRALDIR).
+The whole process hinges on setting the MPAS-ATM model namelist values
+such that it is doing a restart for every model advance.
+Unlike MPAS-ATM free forecast runs, the forecast step in MPAS/DART requires to
+set up one more namelist parameter called "config_do_DAcycling = .true." in &restart section
+of namelist.input to recouple the state vectors (updated by filter) with the mass field for the restart mode.
+For more information, check the <a href="shell_scripts/advance_model.csh">advance_model.csh</a> script. </P>
+<P>
+
+Since DART is an ensemble algorithm, there are multiple analysis files for a single analysis time:
+one for each ensemble member. Because MPAS/DART is run in a restart mode, each member should keep its own
+MPAS restart file from the previous cycle (rather than having a single template file in CENTRALDIR).
+Creating the initial ensemble of states is an area of active research.
+
+<!--==================================================================-->
+<!--=================== DESCRIPTION OF A NAMELIST ===================-->
+<!--==================================================================-->
+
+<A NAME="Namelist"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>NAMELIST</H2>
+<P>
+This namelist is read from the file <em class=file>input.nml</em>.
+Namelists start with an ampersand
+'&' and terminate with a slash '/'.
+Character strings that contain a '/' must be
+enclosed in quotes to prevent them from
+prematurely terminating the namelist.
+</P>
+
+<div class=namelist>
+<pre>
+&model_nml
+ model_analysis_filename = 'mpas_init.nc',
+ grid_definition_filename = 'mpas_init.nc',
+ output_state_vector = .false.,
+ vert_localization_coord = 3,
+ assimilation_period_days = 0,
+ assimilation_period_seconds = 21600,
+ model_perturbation_amplitude = 0.0001,
+ log_p_vert_interp = .true.,
+ calendar = 'Gregorian',
+ use_u_for_wind = .false.,
+ use_rbf_option = 2,
+ update_u_from_reconstruct = .true.,
+ use_increments_for_u_update = .true.,
+ highest_obs_pressure_mb = 100.0,
+ sfc_elev_max_diff = -1.0,
+ debug = 0,
+/
</pre>
+</div>
-<P>These variables are then adjusted to be consistent with observations and
- stuffed back into the same netCDF analysis files. Since DART is an ensemble
- algorithm, there are multiple analysis files for a single analysis time:
- one for each ensemble member. Creating the initial ensemble of states is an
- area of active research.
- <br />
- <br />
- DART reads grid information from the MPAS ATM 'history' file, I have tried to keep
- the variable names the same. Internal to the DART code, the following variables exist:
+<br />
+<br />
+
+<div>
+<TABLE border=0 cellpadding=10 width=100% summary='namelist description'>
+<THEAD align=left>
+<TR><TH> Item </TH>
+ <TH> Type </TH>
+ <TH> Description </TH> </TR>
+</THEAD>
+
+<TBODY valign=top>
+<TR><TD>model_analysis_filename</TD>
+ <TD>character(len=256)<br />
+ <em class=units>[default: 'mpas_init.nc']</em></TD>
+ <TD>The name of the MPAS analysis file to be read and/or written
+ by the DART programs for the state data.</TD>
+</TR>
+
+<TR><TD>grid_definition_filename</TD>
+ <TD>character(len=256)<br />
+ <em class=units>[default: 'mpas_init.nc']</em></TD>
+ <TD>The name of the MPAS file to be read
+ by the DART programs for the grid information. Generally
+ this is the same as the <em class=code>model_analysis_filename</em>.
+ However, the grid information is large and if the grid is static
+ that information could be omitted from the analysis files to
+ save space. A single grid file could be supplied once and
+ not change during the assimilation run. </TD>
+</TR>
+
+<TR><TD>highest_obs_pressure_mb</TD>
+ <TD>real(r8)<br />
+ <em class=units>[default: 100.0]</em></TD>
+ <TD>Observations higher than this pressure are ignored. Set to -1.0
+ to ignore this test. For models with a prescribed top boundary
+ layer, trying to assimilate very high observations results in
+ problems because the model damps out any changes the assimilation
+ tries to make. With adaptive algorithms this results in larger
+ and larger coefficients as the assimilation tries to effect state
+ vector change.
+ </TD>
+</TR>
+
+<TR><TD>output_state_vector</TD>
+ <TD>logical <em class=units>[default: .false.]</em></TD>
+ <TD>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;
+ as 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. [Recommended] </TD>
+</TR>
+
+<TR><TD>assimilation_period_days</TD>
+ <TD>integer <em class=units>[default: 0]</em></TD>
+ <TD>The number of days to advance the model for each assimilation.
+ Even if the model is being advanced outside of the DART filter
+ program, the assimilation period should be set correctly.
+ Only observations with a time within +/- 1/2 this window size
+ will be assimilated.
+ </TD>
+</TR>
+
+<TR><TD>assimilation_period_seconds</TD>
+ <TD>integer <em class=units>[default: 21600]</em></TD>
+ <TD>In addition to <em class=code>assimilation_period_days</em>,
+ the number of seconds to advance the model for each assimilation. </TD>
+</TR>
+
+<TR><TD>vert_localization_coord</TD>
+ <TD>integer <em class=units>[default: 3]</em></TD>
+ <TD>Vertical coordinate for vertical localization.</em>
+ <UL style="list-style: none;">
+ <LI>1 = model level</LI>
+ <LI>2 = pressure (in pascals)</LI>
+ <LI>3 = height (in meters)</LI>
+ <LI>4 = scale height (unitless)</LI>
+ </UL></TD>
+</TR>
+
+<TR><TD>sfc_elev_max_diff</TD>
+ <TD>real(r8)<em class=units>[default: -1.0]</em></TD>
+ <TD>If > 0, the maximum difference, in meters, between an observation marked
+ as a 'surface obs' as the vertical type (with the surface elevation, in
+ meters, as the numerical vertical location), and the surface elevation as
+ defined by the model. Observations further away from the surface than this
+ threshold are rejected and not assimilated. If the value is negative, this
+ test is skipped. </TD>
+</TR>
+
+<TR><TD>log_p_vert_interp</TD>
+ <TD>logical <em class=units>[default: .true.]</em></TD>
+ <TD>If .true., vertical interpolation is done in log-pressure. Otherwise, linear.</TD>
+</TR>
+
+<TR><TD>use_u_for_wind</TD>
+ <TD>logical <em class=units>[default: .false.]</em></TD>
+ <TD>If .false., zonal and meridional winds at cell centers are used for
+ the wind observation operator [default]. In that case, triangular meshes are used for the
+ barycentric (e.g., area-weighted) interpolation. If .true., wind vectors at an arbitrary
+ (e.g., observation) point are reconstructed from the normal component of velocity on cell edges
+ <em class=file>(u)</em> using radial basis functions (RBFs) provided by the MPAS model.</TD>
+</TR>
+
+<TR><TD>use_rbf_option</TD>
+ <TD>integer <em class=units>[default: 2]</em></TD>
+ <TD>If <em class=code>use_u_for_wind</em> is .true., this option controls
+ how many points will be used in the RBF interpolation. Options are available as 1, 2, and 3.
+ All the edges available in N (= 1,2, or 3) cells go into the RBF reconstruction. </TD>
+</TR>
+
+<TR><TD>update_u_from_reconstruct</TD>
+ <TD>logical <em class=units>[default: .true.]</em></TD>
+ <TD>When zonal and meridional winds at cell centers are used for
+ the wind observation operator (<em class=code>use_u_for_wind</em> = .false.),
+ this option decides if the normal component of velocity on cell edges (which is
+ the only wind prognostic variable in MPAS-ATM) should be updated from the winds at cell centers.
+ If .true., <em class=code>use_increments_for_u_update</em> should be also decided.
+ If <em class=code>use_u_for_wind</em> = .true. and the normal component of velocity on cell
+ edges is defined as a state vector, this option should be .false. so the edge winds can be
+ directly updated by filter. </TD>
+</TR>
+
+<TR><TD>use_increments_for_u_update</TD>
+ <TD>logical <em class=units>[default: .true.]</em></TD>
+ <TD>Only if <em class=code>update_u_from_reconstruct</em> is .true., this option is
+ used to decide if the edge winds are replaced by averaging from the analysis
+ winds at cell centers (.false.), or just updated by the analysis increments
+ at cell centers (.true.). If .true., all the wind components (e.g., both at
+ cell centers and edges) are read from prior and used to compute the
+ increments [Recommended]. </TD>
+</TR>
+
+<TR><TD>model_perturbation_amplitude</TD>
+ <TD>real(r8) <em class=units>[default: 0.0001]</em></TD>
+ <TD>The amplitude of random 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. -->
+ Multiplied by the state vector, it produces standard deviation
+ of a gaussian distribution with the mean at the value of the state vector element. </TD>
+</TR>
+
+<TR><TD>calendar</TD>
+ <TD>character(len=32) <br />
+ <em class=units>[default: 'Gregorian']</em></TD>
+ <TD> Character string specifying the calendar being used by MPAS.</TD>
+</TR>
+
+<TR><TD>debug</TD>
+ <TD>integer <em class=units>[default: 0]</em></TD>
+ <TD>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.
+ </TD>
+</TR>
+
+</TBODY>
+</TABLE>
+</div>
+
+<br />
+<br />
+
+<!--==================================================================-->
+
+<A NAME="mpas_vars_nml"></A>
+<P>
+This namelist contains the list of MPAS variables that make up the DART state vector.
+The order the items are specified controls the order of the data in the
+state vector, so it should not be changed without regenerating any
+DART initial condition or restart files.
+These variables are directly updated by the assimilation in filter.
+Any variables whose values cannot exceed a given
+minimum or maximum can be listed in <em class=code>mpas_state_bounds</em>,
+and when the data is converted back into the MPAS NetCDF files, values
+outside the allowed range will be detected. Data inside the DART
+state vector and data written to the diagnostic files
+may exceed the allowed limits.
</P>
+<div class=namelist>
+<pre>
+&mpas_vars_nml
+ mpas_state_variables = 'theta', 'KIND_POTENTIAL_TEMPERATURE',
+ 'uReconstructZonal', 'KIND_U_WIND_COMPONENT',
+ 'uReconstructMeridional','KIND_V_WIND_COMPONENT',
+ 'qv', 'KIND_VAPOR_MIXING_RATIO',
+ 'qc', 'KIND_CLOUDWATER_MIXING_RATIO',
+ 'surface_pressure', 'KIND_SURFACE_PRESSURE'
+ mpas_state_bounds = 'qv','0.0','NULL','CLAMP',
+ 'qc','0.0','NULL','CLAMP',
+/
+</pre>
+</div>
+
+<br />
+<br />
+
+<div>
+<TABLE border=0 cellpadding=10 width=100% summary='namelist description'>
+<THEAD align=left>
+<TR><TH> Item </TH>
+ <TH> Type </TH>
+ <TH> Description </TH> </TR>
+</THEAD>
+
+<TBODY valign=top>
+
+<TR><TD>mpas_vars_nml</TD>
+ <TD>character(len=NF90_MAX_NAME)::<br />
+ dimension(160)
+ <TD>The table that relates the MPAS-ATM variables
+ to use to build the DART state vector, and the corresponding
+ DART kinds for those variables. The first column in each pair must
+ be the NetCDF name of a field in the MPAS file. The second column
+ in each pair must be a KIND known to the DART system. See the
+ <em class=file>obs_kind/obs_kind_mod.f90</em> file for known names.
+ These must be generic kinds, not specific types.
+ </TD>
+</TR>
+
+<TR><TD>mpas_state_bounds</TD>
+ <TD>character(len=NF90_MAX_NAME)::<br />
+ dimension(160)
+ <TD> MPAS-ATM variables that need to set up lower and upper bound values.
+ Columns are a variable name, min, max values, and 'CLAMP' or 'FAIL' in case
+ the field goes beyond the bounds. If the bound values have 'NULL',
+ the actual data range is used.</TD>
+</TR>
+
+</TBODY>
+</TABLE>
+</div>
+
+<br />
+<br />
+</TABLE>
+
+<!--==================================================================-->
+<A NAME="Grid information"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>Grid information</H2>
+<P>As the forward operators use the unstructured grid meshes in MPAS-ATM, the DART/MPAS interface needs to read static
+ variables related to the grid structure from the MPAS ATM 'history' file (specified in
+ <em class=code>model_analysis_filename</em>).
+ These variables are used to find the closest cell to an observation
+ point in the cartesian coordinate (to avoid the polar issues).
+</P>
+
<table width="100%" cellpadding="3">
-<tr><td valign="top">integer :: nCells </td><td>the number of Cell Centers</td></tr>
-<tr><td valign="top">integer :: nEdges </td><td>the number of Cell Edges </td></tr>
-<tr><td valign="top">integer :: nVertices </td><td>the number of Cell Vertices</td></tr>
-<tr><td valign="top">integer :: nVertLevels </td><td>the number of vertical level midpoints</td></tr>
-<tr><td valign="top">integer :: nVertLevelsP1 </td><td>the number of vertical level edges</td></tr>
-<tr><td valign="top">integer :: nSoilLevels </td><td>the number of soil level ?midpoints?</td></tr>
-<tr><td valign="top">real(r8) :: latCell(:) </td><td>the latitudes of the Cell Centers (-90,90) </td></tr>
-<tr><td valign="top">real(r8) :: lonCell(:) </td><td>the longitudes of the Cell Centers [0, 360) </td></tr>
-<tr><td valign="top">real(r8) :: zgrid(:,:) </td><td>cell center geometric height at cell centers (ncells,nvert) </td></tr>
+<tr><td valign="top">integer :: nCells </td><td>the number of cell centers</td></tr>
+<tr><td valign="top">integer :: nEdges </td><td>the number of cell edges </td></tr>
+<tr><td valign="top">integer :: nVertices </td><td>the number of cell vertices</td></tr>
+<tr><td valign="top">integer :: nVertLevels </td><td>the number of vertical levels for mass fields</td></tr>
+<tr><td valign="top">integer :: nVertLevelsP1 </td><td>the number of vertical levels for vertical velocity</td></tr>
+<tr><td valign="top">integer :: nSoilLevels </td><td>the number of soil levels</td></tr>
+<tr><td valign="top">real(r8) :: latCell(:) </td><td>the latitudes of the cell centers [-90,90] </td></tr>
+<tr><td valign="top">real(r8) :: lonCell(:) </td><td>the longitudes of the cell centers [0, 360] </td></tr>
+<tr><td valign="top">real(r8) :: latEdge(:) </td><td>the latitudes of the edges [-90,90], if edge winds are used. </td></tr>
+<tr><td valign="top">real(r8) :: lonEdge(:) </td><td>the longitudes of the edges [0, 360], if edge winds are used. </td></tr>
+<tr><td valign="top">real(r8) :: xVertex(:) </td><td>The cartesian location in x-axis of the vertex </td></tr>
+<tr><td valign="top">real(r8) :: yVertex(:) </td><td>The cartesian location in y-axis of the vertex </td></tr>
+<tr><td valign="top">real(r8) :: zVertex(:) </td><td>The cartesian location in z-axis of the vertex </td></tr>
+<tr><td valign="top">real(r8) :: xEdge(:) </td><td>The cartesian location in x-axis of the edge, if edge winds are used. </td></tr>
+<tr><td valign="top">real(r8) :: yEdge(:) </td><td>The cartesian location in y-axis of the edge, if edge winds are used. </td></tr>
+<tr><td valign="top">real(r8) :: zEdge(:) </td><td>The cartesian location in z-axis of the edge, if edge winds are used. </td></tr>
+<tr><td valign="top">real(r8) :: zgrid(:,:) </td><td>geometric height at cell centers (nCells, nVertLevelsP1)</td></tr>
<tr><td valign="top">integer :: CellsOnVertex(:,:) </td><td>list of cell centers defining a triangle </td></tr>
+<tr><td valign="top">integer :: edgesOnCell(:,:) </td><td>list of edges on each cell </td></tr>
+<tr><td valign="top">integer :: verticesOnCell(:,:) </td><td>list of vertices on each cell </td></tr>
+<tr><td valign="top">integer :: edgeNormalVectors(:,:) </td><td>unit direction vectors on the edges (only used if <em class=code>use_u_for_wind</em> = .true.)</td></tr>
</table>
+<br />
- <h2>model_mod variable storage</h2>
+<!--==================================================================-->
+<A NAME="model_mod"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>model_mod variable storage</H2>
<P>
- <em class=file>input.nml</em><em class=code>&mpas_vars_nml</em>
+ <em class=file>input.nml</em> :: <em class=code>&mpas_vars_nml</em>
defines the list of MPAS variables used to build the DART state vector.
Combined with an MPAS analysis file, the information is used to
determine the size of the DART state vector and derive the metadata.
@@ -109,17 +437,19 @@
character(len=NF90_MAX_NAME), dimension(NF90_MAX_VAR_DIMS) :: dimname
integer, dimension(NF90_MAX_VAR_DIMS) :: dimlens
integer :: xtype ! netCDF variable type (NF90_double, etc.)
- integer :: numdims ! number of dims - excluding TIME
+ integer :: numdims ! number of dimensions - excluding TIME
integer :: numvertical ! number of vertical levels in variable
- integer :: numcells ! number of horizontal locations (typically cell centers)
- logical :: ZonHalf ! vertical coordinate has dimension nVertLevels
- integer :: varsize ! prod(dimlens(1:numdims))
+ integer :: numcells ! number of cell locations (typically cell centers)
+ integer :: numedges ! number of edge locations (edges for normal velocity)
+ logical :: ZonHalf ! vertical coordinate for mass fields (nVertLevels)
+ integer :: varsize ! variable size (dimlens(1:numdims))
integer :: index1 ! location in dart state vector of first occurrence
integer :: indexN ! location in dart state vector of last occurrence
integer :: dart_kind
character(len=paramname_length) :: kind_string
logical :: clamping ! does variable need to be range-restricted before
- real(r8) :: range(2) ! being stuffed back into MPAS analysis file.
+ real(r8) :: range(2) ! lower and upper bounds for the data range.
+ logical :: out_of_range_fail ! is out of range fatal if range-checking?
end type progvartype
type(progvartype), dimension(max_state_variables) :: progvar
@@ -134,28 +464,36 @@
x(nVertical,nHorizontal,nVariables). The fastest-varying dimension is vertical,
then horizontal, then variable ... naturally, the DART state vector is 1D.
Each variable is also stored this way in the MPAS analysis file.
+ <br />
</P>
-<div class=indent1>
- <h2>The DART interface for MPAS (atm)</h2>
- <P>
- was compiled with the gfortran 4.2.3 compilers and run on a Mac.
- <br />
- <br />
- The DART components were built with the following <em class=file>mkmf.template</em> settings:
- </P>
- <pre>
- FC = gfortran
- LD = gfortran
- NETCDF = /Users/thoar/GNU
- INCS = -I${NETCDF}/include
- LIBS = -L${NETCDF}/lib -lnetcdf -lcurl -lhdf5_hl -lhdf5 -lz -lm
- FFLAGS = -O0 -fbounds-check -frecord-marker=4 -ffpe-trap=invalid $(INCS)
- LDFLAGS = $(FFLAGS) $(LIBS)
- </pre>
-</div>
+<br />
+<!--==================================================================-->
+<A NAME="Compilation"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>Compilation</H2>
+<P>
+The DART interface for MPAS-ATM can be compiled with various fortran compilers such as (but not limited to)
+gfortran, pgf90, and intel. It has been tested on a Mac and NCAR IBM supercomputer (yellowstone).
+</P>
+
+<P>
+NOTE: While MPAS requires the PIO (Parallel IO) and pNetCDF
+(Parallel NetCDF) libraries, DART uses only the plain NetCDF libraries.
+If an altered NetCDF library is required by the parallel versions, there may
+be incompatibilities between the run-time requirements of DART and MPAS.
+Static linking of one or the other executable, or swapping of modules
+between executions may be necessary.
+</P>
+
+<br />
+
+<!--==================================================================-->
<a name="conversions"></a>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>Conversions</H2>
+
<div class=indent1>
<h3>Converting between DART files and MPAS analysis files</h3>
<P>is relatively straightforward. Given the namelist mechanism for
@@ -173,7 +511,7 @@
</P>
<table width="100%" cellpadding="10">
<tr><td valign="top"><a href="model_to_dart.html">model_to_dart.f90</a></td>
- <td>converts an MPAS analysis file (nominally named <em class=file>mpas_analysis.nc</em>) into a
+ <td>converts an MPAS analysis file (nominally named <em class=file>mpas_init.nc</em>) into a
DART-compatible file normally called <em class=file>dart_ics</em> .
We usually wind up linking the actual analysis file to a static name that is used by DART.
</td>
@@ -188,7 +526,7 @@
<em class=program>dart_to_model</em> updates the MPAS analysis file
specified in <em class=file>input.nml</em><em class=code>model_nml:model_analysis_filename</em>.
If the DART file contains an 'advance_to' time, separate control information is written
- to an auxiliary file that is used by the <em class=file>advance_model.csh</em> script.
+ to an auxiliary file (named 'mpas_time') that is used by the <em class=file>advance_model.csh</em> script.
</td>
</tr>
</table>
@@ -212,53 +550,59 @@
</div>
<div class="unix">
-<pre>366 mirage2:thoar% ncdump -h mpas_analysis.nc
+<pre>366 mirage2:thoar% ncdump -h mpas_init.nc
netcdf mpas_analysis {
dimensions:
StrLen = 64 ;
Time = UNLIMITED ; // (1 currently)
- <em>nCells</em> = 10242 ; <em>available in DART</em>
- <em>nEdges</em> = 30720 ; <em>available in DART</em>
+ <em class=redtt>nCells</em> = 10242 ; <em class=redtt>available in DART</em>
+ <em class=redtt>nEdges</em> = 30720 ; <em class=redtt>available in DART</em>
maxEdges = 10 ;
maxEdges2 = 20 ;
- <em>nVertices</em> = 20480 ; <em>available in DART</em>
+ <em class=redtt>nVertices</em> = 20480 ; <em class=redtt>available in DART</em>
TWO = 2 ;
THREE = 3 ;
- <em>vertexDegree</em> = 3 ; <em>available in DART</em>
+ vertexDegree = 3 ;
FIFTEEN = 15 ;
TWENTYONE = 21 ;
R3 = 3 ;
- <em>nVertLevels</em> = 41 ; <em>available in DART</em>
- <em>nVertLevelsP1</em> = 42 ; <em>available in DART</em>
+ <em class=redtt>nVertLevels</em> = 41 ; <em class=redtt>available in DART</em>
+ <em class=redtt>nVertLevelsP1</em> = 42 ; <em class=redtt>available in DART</em>
nMonths = 12 ;
nVertLevelsP2 = 43 ;
- <em>nSoilLevels</em> = 4 ; <em>available in DART</em>
+ <em class=redtt>nSoilLevels</em> = 4 ; <em class=redtt>available in DART</em>
variables:
- char <em>xtime(Time, StrLen)</em> ; <em>available in DART</em>
- double <em>latCell(nCells)</em> ; <em>available in DART</em>
- double <em>lonCell(nCells)</em> ; <em>available in DART</em>
- double latEdge(nEdges) ;
- double lonEdge(nEdges) ;
+ char <em class=redtt>xtime(Time, StrLen)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>latCell(nCells)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>lonCell(nCells)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>latEdge(nEdges)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>lonEdge(nEdges)</em> ; <em class=redtt>available in DART</em>
int indexToEdgeID(nEdges) ;
double latVertex(nVertices) ;
double lonVertex(nVertices) ;
+ double <em class=redtt>xVertex(nVertices)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>yVertex(nVertices)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>zVertex(nVertices)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>xEdge(nVertices)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>yEdge(nVertices)</em> ; <em class=redtt>available in DART</em>
+ double <em class=redtt>zEdge(nVertices)</em> ; <em class=redtt>available in DART</em>
int indexToVertexID(nVertices) ;
int cellsOnEdge(nEdges, TWO) ;
int nEdgesOnCell(nCells) ;
int nEdgesOnEdge(nEdges) ;
- int edgesOnCell(nCells, maxEdges) ;
+ int <em class=redtt>edgesOnCell(nCells, maxEdges)</em> ; <em class=redtt>available in DART</em>
int edgesOnEdge(nEdges, maxEdges2) ;
double weightsOnEdge(nEdges, maxEdges2) ;
double dvEdge(nEdges) ;
double dcEdge(nEdges) ;
double angleEdge(nEdges) ;
- double edgeNormalVectors(nEdges, R3) ;
+ double <em class=redtt>edgeNormalVectors(nEdges, R3)</em> ; <em class=redtt>available in DART</em>
double cellTangentPlane(nEdges, TWO, R3) ;
int cellsOnCell(nCells, maxEdges) ;
- int verticesOnCell(nCells, maxEdges) ;
+ int <em class=redtt>verticesOnCell(nCells, maxEdges)</em> ; <em class=redtt>available in DART</em>
int verticesOnEdge(nEdges, TWO) ;
int edgesOnVertex(nVertices, vertexDegree) ;
- int <em>cellsOnVertex(nVertices, vertexDegree)</em> ; <em>available in DART</em>
+ int <em class=redtt>cellsOnVertex(nVertices, vertexDegree)</em> ; <em class=redtt>available in DART</em>
double kiteAreasOnVertex(nVertices, vertexDegree) ;
double rainc(Time, nCells) ;
double cuprec(Time, nCells) ;
@@ -327,182 +671,7 @@
</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> model_analysis_filename, &
- assimilation_period_days, assimilation_period_seconds, &
- model_perturbation_amplitude, output_state_vector, calendar, 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 model dynamical timestep. This also specifies the MPAS analysis file that will
- be read and/or written by the different program units.
-</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>model_analysis_filename</TD>
- <!-- type --><TD valign=top>character(len=256)<br />
- <em class=units>[default: 'mpas_analysis.nc']</em></TD>
- <!--descript--><TD valign=top>Character string specifying the name of the MPAS analysis
- file to be read and/or written by the different program units.</TD></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>calendar</TD>
- <!-- type --><TD valign=top>character(len=32) <br />
- <em class=units>[default: 'Gregorian']</em></TD>
- <!--descript--><TD valign=top>
- Character string specifying the calendar being used by MPAS.</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.
- </TD></TR>
-
-</TABLE>
-
-<H3 class=indent1>Example</H3>
-
-<pre>
-&model_nml
- model_analysis_filename = 'mpas_restart.nc';
- assimilation_period_days = 0,
- assimilation_period_seconds = 60,
- model_perturbation_amplitude = 0.2,
- output_state_vector = .true.,
- calendar = 'Gregorian',
- debug = 0
- /
-</pre>
-
-</div>
-<br />
-
-<!--==================================================================-->
-
-<A NAME="mpas_vars_nml"></A>
-<br />
-<div class=namelist><pre>
-<em class=call>namelist /mpas_vars_nml/</em> mpas_state_variables
-</pre>
-</div>
-
-<div class=indent1>
-<!-- Description -->
-
-<P>
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list