[Dart-dev] [6824] DART/trunk/models/CESM/model_mod.html: updated to give more help to users trying to run
nancy at ucar.edu
nancy at ucar.edu
Mon Feb 24 17:05:51 MST 2014
Revision: 6824
Author: nancy
Date: 2014-02-24 17:05:50 -0700 (Mon, 24 Feb 2014)
Log Message:
-----------
updated to give more help to users trying to run
a fully coupled CESM/DART assimilation. could still
use more work, but better than what was there before.
will now try to do similar updates to the CAM page.
the POP and CLM pages at least explain how to run
under the CESM framework. the CAM page still talks
about running CAM as a separate executable.
Modified Paths:
--------------
DART/trunk/models/CESM/model_mod.html
-------------- next part --------------
Modified: DART/trunk/models/CESM/model_mod.html
===================================================================
--- DART/trunk/models/CESM/model_mod.html 2014-02-20 20:59:01 UTC (rev 6823)
+++ DART/trunk/models/CESM/model_mod.html 2014-02-25 00:05:50 UTC (rev 6824)
@@ -25,74 +25,117 @@
</tr>
</table>
-<A HREF="#Namelist">NAMELIST</A> /
+<A HREF="#Quickstart">QUICKSTART</A> /
+<A HREF="#Namelist">NAMELISTS</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 current interface to the CESM climate modeling system does assimilation
-into CAM, POP, and CLM separately. Therefore at this point there is NOT
-a single CESM model_mod that is compiled into a single filter. However, there
-exists a beta version of a unified model_mod that redirects forward operator
-calls to the proper component-specific model_mod, and works around the
-conflicts between the naming of the model_mod at the module level. It would
-require a single state vector to fit into the memory space of one process,
-which means it would be limited in resolution. cesm_to_dart and dart_to_cesm
-converter prototypes also exist, which pack the data from each model
-end-to-end in the state vector.
+The Lanai release of DART works within the CESM framework. The release
+includes a setup script that will build the required DART executables,
+build the CESM case, and copy the required initial files and
+executables to the correct locations.
+The CESM run script is modified during the build process so it first
+runs CESM, then it runs the DART executable 'filter'.
</P>
<P>
-For now, see each of the component specific model_mod documentation for information
+The instructions on this page describe how to set up a coupled
+CESM run when you want to assimilate observations into more than
+one active component (e.g. assimilate atmospheric obs into the
+atmosphere model, ocean obs into the ocean model, and land obs into
+the land model). If you are interested in assimilating observations
+into only a single component there are more appropriate setup scripts
+in each of the model-specific pages that set up a CESM run for that component.
+</P>
+
+<P>
+See these component specific model_mod documentation for information
on the namelists and requirements:
</P>
<UL>
-<LI><a href="../cam/model_mod.html">CAM</a>
-<LI><a href="../POP/model_mod.html">POP</a>
-<LI><a href="../clm/model_mod.html">CLM</a>
+<LI><a href="../cam/model_mod.html">CAM (atmosphere)</a>
+<LI><a href="../POP/model_mod.html">POP (ocean)</a>
+<LI><a href="../clm/model_mod.html">CLM (land)</a>
</UL>
<P>
-There are scripts in the CESM/shell_scripts directory which are intended to
-build the 3 filter programs for each of the components, copy the right files
-into the CESM caseroot directory, build CESM, and stage files to run an experiment.
+There are scripts in the each of the component shell_scripts directory which will
+build the filter program for that single component, copy the right files
+into the CESM caseroot directory, build CESM, and stage files to run an experiment
+where observations are only assimilated into that component.
</P>
-<H2>Quickstart for CESM/DART</H2>
+<P>
+The rest of this page describes setting up a coupled CESM run
+where you are assimilating into multiple active components.
+</P>
+<br /><br />
+<P> </P>
+<A NAME="Quickstart"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H2>Quickstart for CESM/DART on the NCAR 'yellowstone' machine</H2>
+
<P>
-If you are going to run CESM/DART on the NCAR "yellowstone" machine,
-here are some canned instructions to get you started:
+Both CESM and DART are large, complex software systems with a lot
+of power and capability, but they will require an investment of time and effort
+in learning how to set them up and run them correctly. The following
+list includes the tasks that need to be accomplished in order to
+run a CESM Data Assimilation (DA) experiment.
+
+<ul>
+<li><a href="GetCESM">Get CESM</a></li>
+<li><a href="GetPatches">Get required patches to CESM1.1.1</a></li>
+<li><a href="GetDART">Get DART</a></li>
+<li><a href="ICSandObs">Initial conditions and observations</a></li>
+<li><a href="Running">Running</a></li>
+<li><a href="Archiving">Archiving files</a></li>
+<li><a href="ResetCESM">Reset CESM files</a></li>
+<li><a href="UpdateDART">Update DART files</a></li>
+<li><a href="Diagnostics">Diagnostics</a></li>
+</ul>
+
</P>
-<H3> Get CESM </H3>
+<P>
+The following sections have some information that is specific
+to running CESM/DART on the NCAR 'yellowstone' machine.
+If you are running on another platform please contact us
+at <a href="mailto:dart at ucar.edu">dart at ucar.edu</a> for help.
+The basics of the information below should still apply, but things like where
+the <em class=mono>SourceMods</em> are stored or where to find initial
+condition files will certainly differ.
+</P>
+<br /><br />
+<P> </P>
+<A NAME="GetCESM"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H3>Get CESM</H3>
+
<P>
-Check out CESM1.1.1 which is one release back
-from the very most current version (they updated versions
-right before the Breckenridge User's meeting).
-We will soon have a chance to test the code with
-the latest release, but for now we know this setup
-works with 1.1.1.
+Check out CESM version 1.1.1 (which we know is not the
+most recent release - but it is the latest version we
+have tested the DART code with). We are working on
+validating CESM 1.2 with DART and will update the
+code and documentation when it is ready.
</P>
<P>
-Here's the user's guide for CESM version 1.1.1:<br />
+Here's the user's guide for CESM version 1.1.1:<br /><br />
<a href="http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/usersguide/book1.html">
-<pre>http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/usersguide/book1.html</pre>
-</a>
+http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/usersguide/book1.html </a>
</P>
<P>
-Here's the page that explains how to download the release code:<br />
+Here's the page that explains how to download the release code:<br /><br />
<a href="http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/usersguide/x388.html">
-<pre>http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/usersguide/x388.html</pre>
-</a>
+http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/usersguide/x388.html </a>
</P>
<P>
You will want "cesm1_1_1" as the model version. You will have
@@ -101,16 +144,14 @@
</P>
<P>
This web page shows the names of the 'compsets' which are the
-configurations of the various models:<br />
+configurations of the various models:<br /><br />
<a href="http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/modelnl/compsets.html">
-<pre>http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/modelnl/compsets.html</pre>
-</a>
+http://www.cesm.ucar.edu/models/cesm1.1/cesm/doc/modelnl/compsets.html </a>
</P>
<P>
-This page has pointers to the recent CESM versions:<br />
+This page has pointers to the recent CESM versions:<br /><br />
<a href="http://www2.cesm.ucar.edu/models/current">
-<pre>http://www2.cesm.ucar.edu/models/current</pre>
-</a>
+http://www2.cesm.ucar.edu/models/current </a>
</P>
<P>
If you want to try to build CESM separately from DART
@@ -119,7 +160,8 @@
wait on building it if you want.
</P>
-<H3>Required patches to CESM1.1.1</H3>
+<A NAME="GetPatches"></A>
+<H3>Get required patches to CESM1.1.1</H3>
<P>
There are a few CESM files that we still need to modify to make
@@ -131,19 +173,29 @@
for this subdirectory in your home directory and incorporate these
patches when it builds CESM.
</P>
+This file is also on the IMAGe web server, at this address:
+<a href="http://www.image.ucar.edu/pub/DART/CESM">
+http://www.image.ucar.edu/pub/DART/CESM</a>
+</P>
-<H3>DART</H3>
+<br /><br />
+<P> </P>
+<A NAME="GetDART"></A>
+<div class="top">[<a href="#">top</a>]</div><hr />
+<H3>Get DART</H3>
<P>
-Go to the DART web pages: <a href="http://www.image.ucar.edu/DARES/">
-http://www.image.ucar.edu/DARES/</a>
-and register as a DART user. It's important for us to be able
-to show as large a user base as possible and everyone who
-registers helps us out.
+Go to the DART web pages:
+<a href="http://www.image.ucar.edu/DAReS">
+http://www.image.ucar.edu/DAReS</a>
+and register as a DART user. (See the 'Download DART'
+item under the 'Getting Started' menu.)
+It's important for us to be able to document the size of
+our user base and everyone who registers helps us out.
</P>
<P>
-Check out the "trunk" version. The following instructions
+Check out the "Lanai" release. The following instructions
assume you've checked it out into a subdirectory "DART".
</P>
<P>
@@ -151,14 +203,15 @@
<em class=file>mkmf.template.intel.linux</em> to
<em class=file>mkmf.template</em> . That should work
for yellowstone with the default set of modules that are loaded
-on that machine. <strong>**IMPORTANT**</strong> if you
-are ever thinking of running with an active ocean, you must add:<br />
+on that machine. <strong>**IMPORTANT**</strong> If you
+are running with an active ocean, or you might ever
+sometime in the future run with an active ocean, you must add:<br />
<pre>
-convert big_endian
</pre>
to the list of FFLAGS in the mkmf.template file. POP uses some binary
restart files that are still in the byte order for bluefire. If all
-your restart files for CAM, CAM-CHEM, CLM, etc are netcdf files,
+your restart files for CAM, CAM-CHEM, CLM, etc are NetCDF files,
then you can leave that flag off so yellowstone writes data in
the normal little-endian byte order.
</P>
@@ -178,1483 +231,336 @@
<pre>
DART/models/CESM/shell_scripts
</pre>
-Look at CESM1_1_1_initial.csh.
+Look at <em class=mono>CESM1_1_1_setup_hybrid.csh</em>.
</P>
<P>
-There are some things you can customize at the top, including the compset,
-your project number for running, how many ensemble members, etc. make
+There are some things you should customize at the top, including the compset,
+your project number for running, how many ensemble members, etc. Make
any changes you want there.
</P>
<P>
-Run the script. It will build the CAM, POP, and CLM filters first, and then
+Run the script. It will build the CAM, POP, and CLM filters first (the main
+DART executable is called <em class=mono>filter</em>), and then
build and configure CESM. When the script is done you should have
-files in several directories:<br />
+files in several directories. Unless you have changed these values
+in the setup script, the default locations are:<br />
<UL>
<LI>
The 'cases' dir has the scripts that start and configure runtime vars
-for CESM. It also has the <em class=file>input.nml</em>s for the various components.
-Typically we set this to /glade/p/work/${USER}/cases
+for CESM. It also has the DART namelist files, <em class=file>input.nml</em>s,
+for the various components. Usually we set this to <br />
+<pre>/glade/p/work/${USER}/cases</pre>
</LI>
<LI>
-The actual execution directory is usually<br />
+The actual execution directory is usually <br />
<pre>/glade/scratch/${USER}/$casename/run</pre>
-and the executable files themselves are<br />
+and the executable files themselves are <br />
<pre>/glade/scratch/${USER}/$casename/bld</pre>
</LI>
<LI>
-When you've successfully run a model advance, the output files are saved in<br />
+When you've successfully run a model advance, the output files are saved in <br />
<pre>/glade/scratch/${USER}/archive/$casename</pre>
-with a subdir for each component. Our output files will be in the
-'dart' subdir, and under that directory will be
-'hist', 'logs', and 'rest'. You'll find your diag files and
-obs_seq.final files in the 'hist' subdir.
+with a subdirectory for each component. Our output files will be in the
+'dart' subdirectory, and under that directory will be
+'hist', 'logs', and 'rest'. You'll find the DART diagnostic files and
+obs_seq.final files in the 'hist' subdirectory.
</LI>
</UL>
-
-<H3>EVERYTHING BELOW HERE PERTAINS ONLY TO POP AND NEEDS UPDATING</H3>
-<H3>EVERYTHING BELOW HERE PERTAINS ONLY TO POP AND NEEDS UPDATING</H3>
-<H3>EVERYTHING BELOW HERE PERTAINS ONLY TO POP AND NEEDS UPDATING</H3>
-
-<div class=indent1>
- <h2><a href="http://www.cesm.ucar.edu/models/cesm1.0/pop2/">CESM1.0 POP2</a></h2>
- <P>
- was tested and run in production on NCAR's bluefire computer from IBM.
- This implementation is a significant departure from the DART 'business as usual'
- model in that DART is not responsible for advancing the model - in this case,
- ALL of CESM! Instead, the CESM Interactive Ensemble facility is used to manage
- the ensemble and the Flux Coupler is responsible for stopping POP at the times
- required to perform an assimilation. DART simply runs 'end-to-end' at every
- assimilation time, while CESM runs continuously. This is a complete role-reversal
- from the normal DART operation but was relatively simple to implement because
- CESM had infrastructure to exploit.
- <br />
- <br />
- Several modifications to CESM CASEROOT scripts will be required and will be
- documented more later in this document. The
- <em class=file>DART/models/POP/shell_scripts/</em><em class=program>assimilate.csh</em>
- script is inserted into the CESM run script. The Flux Coupler stops POP every
- midnight and all the observations within +/- 12 hours are assimilated.
- The observation sequence files have been parsed into 'daylong' chunks and
- have names derived from the date to facilitate manipulation in the UNIX shell.
- <br />
- <br />
- The DART components were built with the following settings:
- </P>
- <pre>
- MPIFC = mpxlf95_r
- MPILD = mpxlf95_r
- FC = xlf90_r
- LD = xlf90_r
- INCS = -I/usr/local/lib64/r4i4 -I/usr/local/include
- LIBS = -L/usr/local/lib64/r4i4 -lnetcdf
- FFLAGS = -qsuffix=f=f90:cpp=F90 -q64 -b64 -qarch=auto -qmaxmem=-1 -O2 $(INCS)
- LDFLAGS = $(FFLAGS) $(LIBS)
- </pre>
-</div>
-
-<div class=indent1>
- <h2><a href="http://climate.lanl.gov/Models/POP/">LANL POP</a></h2>
- <P>
- is invoked the same way as any other high-order model.
- <b>Important</b>: This interface was tested with the LANL/POP 2_0_1 version
- of POP ... but STILL CANNOT BE USED for assimilation until the POP code is
- modified to do a forward euler timestep for an 'assimilation' restart.
- <br />
- <br />
- DART is invoked and POP is started/stopped multiple times.
- It was checked in the gx3v5 geometry and POP was built in the 'default'
- configuration: one which requires no forcing files, no boundary conditions,
- etc., so I have no idea what to expect when confronting this with real
- observations ...
- </P>
- <pre>
- setenv ARCHDIR linux
- gmake OPTIMIZE=no COUPLED=no
- </pre>
- <P>
- Given the wide range of input files and modes for running POP -
- the DART scripts will surely have to be modified to accomodate moving
- the boundary/forcing files required for different usage patterns.
- <br />
- <br />
- There are several scripts in the <em class=file>DART/models/POP/shell_scripts</em>
- directory that are employed when using DART to assimilate with a LANL/POP
- model: <em class=program>advance_model.csh</em>,
- <em class=program>run_perfect_model_obs.batch</em>, and
- <em class=program>run_filter.batch</em> .
- <br />
- <br />
- The DART components compile and run on our Intel-based cluster running SLES10
- with the ifort 10.1 20090203 compiler with the following flags
- (the value of NETCDF was appropriate for our system):
- </P>
- <pre>
- MPIFC = mpif90
- MPILD = mpif90
- FC = ifort
- LD = ifort
- INCS = -I$(NETCDF)/include
- LIBS = -L$(NETCDF)/lib -lnetcdf -lmkl -lmkl_lapack -lguide -lpthread
- FFLAGS = -O0 -fpe0 -vec-report0 -assume byterecl $(INCS)
- LDFLAGS = $(FFLAGS) $(LIBS)
- </pre>
- <P>
- Intel-based machines are natively little-endian, so I like to append
- a ".le" suffix on all binary files.
- <br />
- <br />
- On our machine, with the openmpi framework, it is necessary to specify
- <em class=file>input.nml</em><em class=code>:&mpi_utilities_nml:reverse_task_layout = .true.,</em >
- to be able to simultaneously run (2) MPI programs on the same set of nodes.
- </P>
-</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 POP restart files.</h3>
- <P>Only POP netCDF format restart files are supported. Yes, really.
- It gets better.
- Since the POP restart files do not have the actual grid information
- in them, that information must be read from binary files (for the horizontal)
- and an ascii file (for the vertical). Since I'm always working on both
- big- and little-endian machines, I have a devil of a time keeping my
- binary files straight.
- All of DART/POP is predicated on using pointer files to contain the
- names of the POP restart netCDF files. It turns out to be really
- useful to dereference the pointer file and link the result to a presumed
- name for use by the program unit. Otherwise, we were endlessly mucking about
- with trying to dynamically change namelists, etc. in our scripts. Ugly.
- <br />
- <br />
- There are two programs and one module:
- </P>
- <table width="100%" cellpadding="10">
- <tr><td valign="top"><a href="pop_to_dart.html">pop_to_dart.f90</a></td>
- <td>converts the POP restart file <em class=file>pop.r.nc</em> into a
- DART-compatible file normally called <em class=file>dart_ics</em> .
- There must also be a <em class=file>pop_in</em> namelist for POP
- (since this specifies the names of the grid files).
- We usually wind up linking the dereferenced
- pointer file name to a static name that is used by DART.
- To that end, <em class=file>rpointer.ocn.restart</em> points to
- <em class=file>pop.r.nc</em> for this program.
- </td>
- </tr>
- <tr><td valign="top"><a href="dart_to_pop.html">dart_to_pop.f90</a></td>
- <td>inserts the DART output into an existing POP restart netCDF file by
- overwriting the
- <em class=code>SALT_CUR</em>,
- <em class=code>TEMP_CUR</em>,
- <em class=code>UVEL_CUR</em>,
- <em class=code>VVEL_CUR</em>, and
- <em class=code>PSURF_CUR</em> variables in the POP restart netCDF 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_pop</em>
- requires the POP restart file have a name of <em class=file>pop.r.nc</em>,
- the POP input namelist <em class=file>pop_in</em> must exist, as do the
- geometry files specified by <em class=file>pop_in</em>.
- If the DART file contains an 'advance_to' time,
- <em class=program>dart_to_pop</em> creates a new
- <em class=code>&time_manager_nml</em> for POP in a file called
- <em class=file>pop_in.DART</em> which can be used to control the
- length of the POP integration.
- </td>
- </tr>
- <tr><td valign="top"><A href="dart_pop_mod.html">dart_pop_mod.f90</a></td>
- <td>is the module containing many support routines that are used by
- both <em class=program>pop_to_dart</em>, <em class=program>dart_to_pop</em>,
- and the POP <em class=program>model_mod</em>.
- </td></tr>
- </table>
-</div>
-
-<a name="InitialEnsemble"></a>
-<div class=indent1>
- <h3>Generating the initial ensemble.</h3>
- <P> Under development ...
- </P>
-</div>
-
-<a name="POP_OSSE"></a>
-<div class=indent1>
- <h3>Generating a set of observations for a 'perfect model' experiment using the LANL/POP 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 POP
- for a very long time and saving restart files 'every so often'.
- Use one of these as the initial condition
- for <em class=program>perfect_model_obs</em> and the rest as the
- 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 POP into
- two pieces - one called <em class=file>pop_in.part1</em>,
- that contains the <em class=code>&time_manager_nml</em> and
- put the rest in <em class=file>pop_in.part2</em>. The
- <em class=code>&time_manager_nml</em> will be repeatedly updated
- as the POP model is repeatedly called by
- <em class=program>advance_model.csh</em>.
- </li>
-
- <li>modify <em class=file>POP/work/input.nml</em> as needed.
- </li>
-
- <li>modify
- <em class=file>DART/models/POP/shell_scripts</em><em class=program>run_perfect_model_obs.batch</em>
- to reflect the location of your DART directory, the POP 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/POP/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/POP/matlab</em>, and
- <em class=file>DART/models/POP/shell_scripts</em>.
- <br />
- <br />
- It is also worthwhile to convert your obs_seq.final file to a netCDF format
- 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 POP. It is unimportant for the CESM/POP
- experiments but is critically important for the LANL/POP experiments.
- The values are explained in full in the POP documentation. The DART code
- reads the namelist and simply overwrites several values with the new time
- integration information. All the other values are unchanged.
- <br />
- <br />
- <em class=program>dart_to_pop</em> writes out a new
- <em class=code>&time_manager_nml</em> in <em class=file>pop_in.DART</em>
- if the DART state being converted has the 'advance_to_time' record in it.
- This is the case during the middle of a DART experiment, but is not
- typically encountered if one is working with DART 'initial conditions'
- or 'restart' files. The <em class=file>pop_in.DART</em> must be concatenated
- with the other namelists needed by POP into a file called
- <em class=file>pop_in</em> . We have chosen to store the other
- namelists (which contain static information) in a file called
- <em class=file>pop_in.part2</em>. Initially, the
- <em class=code>time_manager_nml</em> is stored in a companion file called
- <em class=file>pop_in.part1</em> and the two files are concatenated into
- the expected <em class=file>pop_in</em> - then, during the course of an
- assimilation experiment, DART keeps writing out a new
- <em class=code>time_manager_nml</em> with new integration information -
- which gets appended with the static information in
- <em class=file>pop_in.part2</em>
- <br />
- <br />
- If you are running the support programs in a standalone fashion
- (as you might if you are converting restart files into an intial ensemble),
- the 'valid time' of the model state comes from the restart file
- - NOT - the namelist. You can always patch the times in the
- headers with <em class=program>restart_file_utility</em>.
- <br />
- <br />
- Only the namelist variables of interest to DART are discussed. All
- other namelist variables are ignored by DART - but mean something to POP.
+The CESM/DART system uses the CESM multi-instance capability to run
+multiple copies of components concurrently. The coupler
+routes data between the corresponding instances of each component.
+Each component can have N instances or 1 instance which is shared
+amongst all the multi-instances of other components.
+DART expects the CESM naming convension of adding instance numbers
+of the form <em class=mono>_NNNN</em> following the component name,
+e.g. <em class=mono>my_case.cam_0001.r.2009-01-01-21600.nc</em>
+is the first instance in a multi-instance case. For components
+without multiple instances the names follow the usual naming
+conventions, e.g. <em class=mono>my_case.cam.r.2009-01-01-21600.nc</em>.
</P>
-<TABLE border=0 cellpadding=3 width=100%>
-<TR><TH align=left>Contents </TH>
- <TH align=left>Type </TH>
- <TH align=left>Description </TH></TR>
-
-<TR><!--contents--><TD valign=top>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>
+<br /><br />
+<P> </P>
+<A NAME="ICSandObs"></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>
-
+<H3>Initial Conditions and Observations</H3>
+<H4>ICs</H4>
<P>
-Only a select number of interfaces used are discussed here.
-Each module has its own discussion of their routines.
+DART requires an <em class=file>ensemble</em> of initial conditions.
+This is the same as <em class=file>multiple instances</em> in CESM terminology.
+If you have a multiple-instance run available to you for initial condition
+files, great. If you do not, one suggested option is to make N copies of a single
+initial condition file, each with the same data but with a different
+filename that includes the instance number.
+(See the paragraph immediately above discussing filename conventions.)
+When you run CESM for the first step it will be advancing N identical
+copies of the model. However, when you run DART with the following
+changes to the <em class=file>input.nml</em> namelist, each instance
+will be perturbed differently and as the system runs these differences
+will evolve into distinct instances that will remain different.
</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 POP
- <em class=program>model_mod</em> will be augmenting the work done by
- <em class=program>location_mod/get_close_obs()</em> .
- <br />
- <br />
- Fundamentally, the <em class=program>location_mod</em> calculates and returns
- all the 'close' observations. DART is designed such that the routine that
- uses the list of close observations is in <em class=file>model_mod.f90</em>.
- Consequently, the POP <em class=program>model_mod</em> can take that
- information and adjust as necessary. This creates some logistical issues
- in that the POP model_mod needs to intercept all calls to
- <em class=program>location_mod:get_close_obs()</em> - which can be achieved
- with the following syntax:
-</P>
@@ Diff output truncated at 40000 characters. @@
More information about the Dart-dev
mailing list