/[MITgcm]/MITgcm/doc/devel_HOWTO.sgml

Diff of /MITgcm/doc/devel_HOWTO.sgml

Parent Directory | Revision Log | View Revision Graph Revision Graph | View Patch Patch

-revision 1.3 by edhill,
Thu Aug 28 22:44:00 2003 UTC
+revision 1.6 by jmc,
Tue Dec 23 22:42:20 2003 UTC
 Line 2
  <article id="MITgcm-Development-HOWTO">
- <!--
- Build commands:
-   db2ps -d ldp.dsl devel_HOWTO.sgml
-   db2pdf -d ldp.dsl devel_HOWTO.sgml
-   db2html -d ./ldp.dsl devel_HOWTO.sgml
-   db2html -u -d ./ldp.dsl devel_HOWTO.sgml
- -->
    <articleinfo>
      <title>MITgcm Development HOWTO</title>
-Line 63 
 Build commands:
+Line 55 
 Build commands:
      <sect2>
        <title>User Manual</title>
-       <para>Before jumping into
+       <para>Before jumping into development, please familiarize yourself with
-       development, please familiarize yourself with the MITgcm user
+         the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual
-       manual which is available <ulink
+         </ulink>.  This document contains volumes of useful information and is
-       url="http://mitgcm.org/">on the main web page</ulink>.  This
+         included here by reference.</para>
-       document contains volumes of useful information and is included
-       here by reference.</para>
-       <para>Also, a "snapshot" or<ulink
+       <!--
+       <para>Also, a "snapshot" or <ulink
        url="http://mitgcm.org/dev_docs/">development version</ulink> of
        the user manual may be available, though this is only put on the
        web for testing purposes.</para>
+       -->
      </sect2>
      <sect2>
-Line 128 
 Build commands:
+Line 120 
 Build commands:
         doc                      tags -- connect to real docs?
         eesupp                   cnh?
         exe                      ecco user build
-     *- jobs                     runtime shell scripts for
+     ,- jobs                     runtime shell scripts for
      |                             various platforms
      |  lsopt                    line search
     m|  model                    main dynamics (core)
     e|    optimization_drivers   ?
     r|  optim                    line search interface
     g|  pkg                      alternate and optional numerics, etc.
-    e*- tools
+    e|- tools
     ?|  tutorial_examples        documented tests
      |                             only populated on release1 branch
      |                             and not validated during "testscript"
-     *- utils
+     '- utils
         verification             std tests
-Line 300 
 checkpoint50d_pre
+Line 292 
 checkpoint50d_pre
        server using:</para>
  <screen>
- $ export CVS_RSH=ssh
+   $ export CVS_RSH=ssh
- $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'
+   $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'
- $ mkdir scratch
+   $ mkdir scratch
- $ cvs co MITgcm manual mitgcm.org
+   $ cvs co MITgcm manual mitgcm.org
  </screen>
        <para>These commands extract the necessary information from the
-Line 316 
 $ cvs co MITgcm manual mitgcm.org
+Line 308 
 $ cvs co MITgcm manual mitgcm.org
      </sect2>
      <sect2>
-       <title>Editing</title>
+       <title>Editing the Documentation</title>
        <para>The documentation is contained in the
        <filename>manual</filename> directory in a raw LaTeX format.
-Line 364 
 $ cvs co MITgcm manual mitgcm.org
+Line 356 
 $ cvs co MITgcm manual mitgcm.org
      </sect2>
      <sect2>
-       <title>Building</title> <para>Given the directory structure of
+       <title>Building the Documentation</title>
-       <xref linkend="documentation_getting">, the entire documentation
-       for the web site can be built using:</para>
+       <para>Given the directory structure of <xref
+       linkend="documentation_getting">, the entire documentation for the web
+       site can be built using:</para>
  <screen>
- $ cd mitgcm.org/devel/buildweb
+   $ cd mitgcm.org/devel/buildweb
- $ make All
+   $ make All
  </screen>
        <para>Which builds the PDF from the LaTeX source, creates the
-Line 388 
 $ make All
+Line 382 
 $ make All
        area:</para>
  <screen>
- $ mv scratch/dev_docs /u/u0/httpd/html
+   $ mv scratch/dev_docs /u/u0/httpd/html
  </screen>
        <para>and the update is complete.</para>
-Line 403 
 $ mv scratch/dev_docs /u/u0/httpd/html
+Line 397 
 $ mv scratch/dev_docs /u/u0/httpd/html
      <sect2 id="build_tools">
        <title>Build Tools</title>
-       <para>Many Open Source projects use the "GNU Autotools" to help
+       <para>Many Open Source projects use the "GNU Autotools" to help streamline
-       streamline the build process for various Unix and Unix-like
+         the build process for various Unix and Unix-like architectures.  For a
-       architectures.  For a user, the result is the common "configure"
+         user, the result is the common "configure" (that is,
-       (that is, "<filename>./configure && make && make
+         "<filename>./configure && make && make install</filename>") commands.
-       install</filename>") commands.  For MITgcm, the process is
+         For MITgcm, the process is similar.  Typical commands are:</para>
-       similar.  Typical commands are:</para>
  <screen>
- $ genmake -mods=../code
+   $ genmake -mods=../code
- $ make depend
+   $ make depend
- $ make
+   $ make
  </screen>
-       <para>The following sections describe the individual steps in
+       <para>The following sections describe the individual steps in the build
-       the build process.</para>
+         process.</para>
        <sect3 id="genmake">
          <title>The <filename>genmake2</> Utility</title>
-         <para><emphasis>Please note that the older
+         <para><emphasis>Please note that the older <filename>genmake</> is
-         <filename>genmake</> is deprecated and will eventually
+             deprecated and will eventually be replaced by <filename>genmake2</>.
-         be replaced by <filename>genmake2</>.  This HOWTO only
+             This HOWTO only describes the newer tool.</emphasis></para>
-         describes the newer tool.</emphasis></para>
+         <para>The first step in any MITgcm build is to create a Unix-style
-         <para>The first step in any MITgcm build is to create a
+           <filename>Makefile</filename> which will be parsed by
-         Unix-style <filename>Makefile</filename> which will be parsed
+           <filename>make</filename> to specify how to compile the MITgcm source
-         by <filename>make</filename> to specify how to compile the
+           files.  For more detailed descriptions of what the make tools are and
-         MITgcm source files.  For more detailed descriptions of what
+           how they are used, please see:</para>
-         the make tools are and how they are used, please see:</para>
          <itemizedlist>
            <listitem>
-             <para><ulink url="http://www.gnu.org/software/make/make.html">http://www.gnu.org/software/make/make.html</></para>
+             <para><ulink url="http://www.gnu.org/software/make/make.html">
+                 http://www.gnu.org/software/make/make.html</></para>
            </listitem>
            <listitem>
-             <para><ulink url="http://www.oreilly.com/catalog/make2/">http://www.oreilly.com/catalog/make2/</></para>
+             <para><ulink url="http://www.oreilly.com/catalog/make2/">
+                 http://www.oreilly.com/catalog/make2/</></para>
            </listitem>
          </itemizedlist>
-         <para>Due to the poor handling of soft-links and other bugs
+         <para>Genmake can often be invoked successfully with a command line as
-         common with the <filename>make</filename> versions provided by
+         simple as:</para>
-         commercial Unix vendors, GNU <filename>make</filename>
-         (sometimes called <filename>gmake</filename>) should be
+ <screen>
-         preferred.</para>
+   $ genmake2 -mods=../code
+ </screen>
-         <para>As the name implies, <filename>genmake2</filename>
-         generates a <filename>Makefile</filename>.  It does so by
+         <para>However, some systems (particularly commercial Unixes that lack a
-         first parsing the information supplied from the following
+           more modern "/bin/sh" implementation or that have shells installed in
-         sources</para>
+           odd locations) may require an explicit shell invocation such as one of
+           the following: </para>
+ <screen>
+   $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
+   $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
+ </screen>
+         <para>The genmake2 code has been written in a Bourne and BASH (v1)
+         compatible syntax so it should work with most "sh" and all recent "bash"
+         implementations.</para>
+         <para>As the name implies, <filename>genmake2</filename> generates a
+           <filename>Makefile</filename>.  It does so by first parsing the
+           information supplied from the following sources</para>
          <orderedlist>
            <listitem>
-             <para>a <filename>gm_local</filename> file in the current
+             <para>a <filename>gemake_local</filename> file in the current
-             directory</para>
+               directory</para>
            </listitem>
            <listitem>
              <para>directly from command-line options</para>
            </listitem>
            <listitem>
-             <para>an "options file" as specified by the command-line
+             <para>an "options file" as specified by the command-line option
-             option <filename>-optfile='FILENAME'</filename></para>
+               <filename>-optfile='FILENAME'</filename></para>
            </listitem>
          </orderedlist>
-         <para>then checking certain dependency rules (the package
+         <para>then checking certain dependency rules (the package dependencies),
-         dependencies), and then writing a
+           and finally writing a <filename>Makefile</filename> based upon the
-         <filename>Makefile</filename> based upon the source code that
+           source code that it finds.  For convenience within various Unix
-         it finds.  For convenience with the various Unix shells,
+           shells, <filename>genmake2</> supports both "long"- and "short"-style
-         <filename>genmake2</> supports both "long"- and "shor"-style
+           options.  A complete list of the available options can be obtained
-         options.  A complete list of the available options can be
+           from:</para>
-         obtained from:</para>
  <screen>
- $ genmake2 -help
+   $ genmake2 -help
  </screen>
-         <para>The most important options for <filename>genmake2</>
+         <para>The most important options for <filename>genmake2</> are:</para>
-         are:</para>
          <variablelist>
            <varlistentry>
              <term><filename>--optfile=/PATH/FILENAME</></term>
              <listitem>
-               <para>This specifies the "options file" that should be
+               <para>This specifies the "options file" that should be used for a
-               used for a particular build.  The options file is a
+                 particular build.  The options file is a convenient and
-               convenient and machine-indepenent way of specifying
+                 machine-indepenent way of specifying parameters such as the
-               parameters such as the FORTRAN compiler
+                 FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
-               (<filename>FC=</>), FORTRAN compiler optimization flags
+                 optimization flags (<filename>FFLAGS=</>), and the locations of
-               (<filename>FFLAGS=</>), and the locations of various
+                 various platform- and/or machine-specific tools
-               platform- and/or machine-specific tools
+                 (eg. <filename>MAKEDEPEND=</>).  As with <filename>genmake2</>,
-               (eg. <filename>MAKEDEPEND=</>).  As with
+                 all options files should be written to be compatible with
-               <filename>genmake2</>, all options files should be
+                 Bourne--shell ("sh" or "BASH v1") syntax.  Examples of various
-               written a BASH v1-compatible syntax.  Examples of
+                 options files can be found in
-               various options files can be found in
+                 <filename>$ROOTDIR/tools/build_options</>.</para>
-               <filename>$ROOTDIR/tools/build_options</>.  Everyone is
-               encouraged to submit their options files to the MITgcm
+               <para>If no "optfile" is specified (either through the command lin
-               project for inclusion (please send to
+                 or the environment variable), genmake2 will try to make a
-               <email>MITgcm-support@mitgcm.org</email>).  We are
+                 reasonable guess from the list provided in
-               particularly grateful for options files tested on new or
+                 <filename>$ROOTDIR/tools/build_options</>.  The method used for
-               unique platforms!</para>
+                 making this guess is to first determine the combination of
+                 operating system and hardware (eg. "linux_ia32") and then find a
+                 working Fortran compiler within the user's path.  When these
+                 three items have been identified, genmake2 will try to find an
+                 optfile that has a matching name. </para>
+               <para>Everyone is encouraged to submit their options files to the
+                 MITgcm project for inclusion (please send to
+                 <email>MITgcm-support@mitgcm.org</email>).  We are particularly
+                 grateful for options files tested on new or unique
+                 platforms!</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>-pdepend=/PATH/FILENAME</></term>
              <listitem>
-               <para>This specifies the dependency file used for
+               <para>This specifies the dependency file used for packages.  If
-               packages.  If not specified, the default dependency file
+               not specified, the default dependency file is
-               is <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for
+               <filename>$ROOTDIR/pkg/pkg_depend</>.  The syntax for this file is
-               this file is parsed on a line-by-line basis where each
+               parsed on a line-by-line basis where each line containes either a
-               line containes either a comment ("#") or a simple
+               comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
-               "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or
+               where the "+" or "-" symbol specifies a "must be used with" or a
-               "-" symbol specifies a "must be used with" or a "must
+               "must not be used with" relationship, respectively.  If no rule is
-               not be used with" relationship, respectively.  If no
+               specified, then it is assumed that the two packages are compatible
-               rule is specified, then it is assumed that the two
+               and will function either with or without each other.</para>
-               packages are compatible and will function either with or
-               without each other.</para>
              </listitem>
            </varlistentry>
-Line 536 
 $ genmake2 -help
+Line 553 
 $ genmake2 -help
            </varlistentry>
            <varlistentry>
-             <term><filename></>-mods=DIR</term>
+             <term><filename>-adof=/path/to/file</></term>
-             <term><filename></>-mods='DIR1 [DIR2 ...]'</term>
+             <term><filename>-adoptfile=/path/to/file</></term>
              <listitem>
-               <para>This option specifies a list of directories
+               <para>This option specifies the "adjoint" or automatic
-               containing "modifications".  These are files that may
+                 differentiation options file to be used.  The file is analogous
-               (or may not) exist in the main MITgcm source tree but
+                 to the "optfile" defined above but it specifies information for
-               will be overridden by any identically-named sources
+                 the AD build process.  The default file is located in <filename>
-               within the "MODS" directories.</para>
+                 $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
+                 defines the "TAF" and "TAMC" compilers.  An alternate version is
+                 also available at <filename>
+                 $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
+                 newer "STAF" compiler.  As with any compilers, it is helpful to
+                 have their directories listed in your $PATH environment
+                 variable.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-mods=DIR</></term>
+             <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
+             <listitem>
+               <para>This option specifies a list of directories containing
+                 "modifications".  These directories contain files with names
+                 that may (or may not) exist in the main MITgcm source tree but
+                 will be overridden by any identically-named sources within the
+                 "MODS" directories.  The order of precedence for this
+                 "name-hiding" is as follows:</para>
+               <itemizedlist>
+                 <listitem><para>"MODS" directories (in the order given)
+                   </para></listitem>
+                 <listitem><para>Packages either explicitly specified or
+                     provided by default (in the order given)</para></listitem>
+                 <listitem><para>Packages included due to package dependencies
+                     (in the order that that package dependencies are
+                     parsed)</para></listitem>
+                 <listitem><para>The "standard dirs" (which may have been
+                     specified by the "-standarddirs" option)</para></listitem>
+               </itemizedlist>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-make=/path/to/gmake</></term>
+             <listitem>
+               <para>Due to the poor handling of soft-links and other bugs common
+                 with the <filename>make</> versions provided by commercial Unix
+                 vendors, GNU <filename>make</filename> (sometimes called
+                 <filename>gmake</filename>) should be preferred.  This option
+                 provides a means for specifying the make program to be
+                 used.</para>
              </listitem>
            </varlistentry>
          </variablelist>
-         <para>A successful run of <filename>genmake2</> will produce
+         <para>A successful run of <filename>genmake2</> will produce a
-         both a <filename>Makefile</> and a locally modified copy of
+           <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
-         the specified <filename>CPP_OPTIONS.h</> file.  The local copy
+           various convenience files used for the automatic differentiation
-         of <filename>CPP_OPTIONS.h</> will contain a list of
+           process.</para>
-         <filename>genmake2</>-created #DEFINE and #UNDEF statements
-         that reflect the list of packages that will be compiled into
+         <para>In general, it is best to use <filename>genmake2</> on a "clean"
-         the code (either directly through enable/disable/defaults
+           directory that is free of all source (*.[F,f],*.[F,f]90) and header
-         options or indirectly through dependencies).</para>
+           (*.h,*.inc) files.  Generally, this can be accomplished in an
+           "un-clean" directory by running "make CLEAN" followed by "make
-         <para>In general, it is best to use <filename>genmake2</> on a
+           makefile".</para>
-         "clean" directory that is free of all source
-         (*.[F,f],*.[F,f]90) and header (*.h,*.inc) files.  Generally,
-         this can be accomplished in an "un-clean" directory by running
-         "make CLEAN" followed by "make makefile".</para>
        </sect3>
        <sect3 id="makefile_use">
-         <title>Using <filename>Makefile</></title>
+         <title>Using the <filename>Makefile</></title>
-         <para>Once a <filename>Makefile</> has been created, one can
+         <para>Once a <filename>Makefile</> has been created using
-         build the executable using:</para>
+           <filename>genmake2</>, one can build a "standard" (forward
+           simulator) executable using:</para>
  <screen>
- $ make CLEAN
+   $ make CLEAN
- $ make depend
+   $ make depend
- $ make
+   $ make
  </screen>
-         <para>The "make CLEAN" step will remove any local source
+         <para>The "make CLEAN" step will remove any stale source files, include
-         files, include files, and links.  It is strongly recommended
+           files, and links.  It is strongly recommended for "un-clean"
-         for "un-clean" directories which may contain the (partial?)
+           directories which may contain the (perhaps partial) results of
-         results of previous builds.  Such "debris" can interfere with
+           previous builds.  Such "debris" can interfere with the next stage of
-         the next stage of the build.</para>
+           the build.</para>
-         <para>The "make depend" step will create a large number of
+         <para>The "make depend" step will create a large number of symbolic
-         symbolic links from the local directory to the source file
+           links from the local directory to the source file locations.  It also
-         locations.  It also parses these files and creates an
+           parses these files and creates an extensive list of dependencies
-         extensive list of dependencies within the
+           within the <filename>Makefile</> itself.  The links that exist at this
-         <filename>Makefile</> itself.  The links that exist at this
+           stage are mostly "large F" files (*.F and *.F90) that need to be
-         stage are mostly "large F" files (*.F and *.F90) that need to
+           processed by a C preprocessor ("CPP").  Since "make depend" edits the
-         be processed by a C preprocessor ("CPP").
+           <filename>Makefile</>, it is important not to skip this step!</para>
-         </para>
+         <para>The final "make" invokes the C preprocessor to produce the "little
-         <para>The final "make" invokes the C preprocessor to produce
+           f" files (*.f and *.f90) and then compiles them to object code using
-         the "little f" files (*.f and *.f90) and then compiles them to
+           the specified FORTRAN compiler and options.  An intermediate script is
-         object code using the specified FORTRAN compiler and options.
+           often used during this stage to further process (usually, make simple
-         An intermediate script is often used during this stage to
+           substitutions) custom definitions such as variable types within the
-         further process (usually, make simple substitutions) custom
+           source files.  This additional stage is necessary in order to overcome
-         definitions such as variable types within the source files.
+           some of the inconsistencies in the sizes of objects (bytes) between
-         This additional stage is necessary in order to overcome some
+           different compilers. The result of the build process is an executable
-         of the inconsistencies in the sizes of objects (bytes) between
+           with the name <filename>mitgcmuv</>.</para>
-         different compilers.</para>
+         <para>In addition to the forward simulator described above, the
+           <filename>Makefile</> also has a number of targets that can be used to
+           produce various adjoint and tangent-linear builds for optimization and
+           other parameter-sensitivity problems.  The additional targets within
+           the <filename>Makefile</> are:</para>
+         <variablelist>
+           <varlistentry>
+             <term><filename>make adall</></term>
+             <listitem>
+               <para>This target produces an <filename>mitgcmuv_ad</> executable
+                 using the <filename>taf</> or <filename>staf</> adjoint
+                 compiler.  See the <filename>genmake2</> "-adof" option for
+                 compiler selection.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>make ftlall</></term>
+             <listitem>
+               <para>Similar to <filename>make adall</> above, this
+                 produces...</para>
+             </listitem>
+           </varlistentry>
+         </variablelist>
-         <para>Please report compilation failures or other problems to
+         <para>Please report any compilation failures or other build problems to
-         <email>MITgcm-support@mitgcm.org</email>.</para>
+           the <email>MITgcm-support@mitgcm.org</email> list.</para>
        </sect3>
-Line 613 
 $ make
+Line 698 
 $ make
      <sect2 id="verification">
        <title>The Verification Suite</title>
-       <para>The MITgcm CVS tree (within the
+       <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
-       <filename>$ROOTDIR/verification/</> directory) includes more
+         directory) includes more than a dozen examples intended for regression
-       than a dozen examples intended for regression testing.  Each one
+         testing.  Each one of these example directories contains "known-good"
-       of these example directories contains "known-good" output files
+         output files along with all the input (including both code and data
-       along with all the input (including both code and data files)
+         files) required for their re-calculation.  These example directories are
-       required for their re-calculation.  These example directories
+         further broken down into sets of subdirectories
-       are further broken down into sets of subdirectories
+         (eg. <filename>/input</>, <filename>/code</>) intended to expedite the
-       (eg. <filename>/input</>, <filename>/code</>) intended to
+         testing process.</para>
-       expedite the testing process.</para>
        <sect3 id="testreport">
          <title>The <filename>testreport</> Utility</title>
-         <para>Also included in <filename>$ROOTDIR/verification/</> are
+         <para>Also included in <filename>$ROOTDIR/verification/</> are shell
-         shell scripts for automated testing.  The newest script (which
+           scripts for automated testing.  The newest script (which was written
-         was written to work with <filename>genmake2</>) is called
+           to work with <filename>genmake2</>) is called <filename>testreport</>.
-         <filename>testreport</>.  Ths script can be used to build the
+           This script can be used to build different versions of the MITgcm
-         different versions of the MITgcm code, run the various
+           code, run the various examples, compare the output, and (if specified)
-         examples, compare the output, and (if specified) email the
+           email the results of each one of these tests to a central
-         results of each one of these tests to a central
+           repository.</para>
-         repository.</para>
+         <para>On some systems, the testreport script can be run with a command
+         line as simple as:</para>
+ <screen>
+   $ cd verification
+   $ ./testreport -ieee
+ </screen>
+         <para>However, some systems (those lacking or wiht a broken "/bin/sh")
+           may require an explicit shell invocation such as:</para>
+ <screen>
+   $ sh ./testreport -ieee -t 'exp0 exp4'
+   $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
+ </screen>
          <para>The <filename>testreport</> script accepts a number of
-         command-line options which can be listed using the
+           command-line options which can be listed using the <filename>-help</>
-         <filename>-help</> option.  The most important ones are:</para>
+           option.  The most important ones are:</para>
          <variablelist>
            <varlistentry>
+             <term><filename>-ieee</></term>
+             <listitem>
+               <para>If allowed by the compiler (as defined in the "optfile"),
+                 use IEEE arithmetic.  This option, along with the GCC compiler,
+                 is how the standard results were produced.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
              <term><filename>-tdir TESTDIR</></term>
              <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
              <listitem>
-               <para>This option specifies the test directory or list
+               <para>This option specifies the test directory or list of test
-               of test directories that should be used.  Each of these
+                 directories that should be used.  Each of these entries should
-               entries should exactly (note: they're case sensitive!)
+                 exactly (note: they are case sensitive!) match the names of
-               match the names of directries in
+                 directries in <filename>$ROOTDIR/verification/</>.  If this
-               <filename>$ROOTDIR/verification/</>.  If this option is
+                 option is omitted, then all directories that are properly
-               omitted, then all directories that are properly
+                 formatted (that is, containing an <filename>input</>
-               formatted (that is, containing an <filename>input</>
+                 sub-directory and a <filename>results/output.txt</> file) will
-               sub-directory and example output) will be used.</para>
+                 be used.</para>
              </listitem>
            </varlistentry>
-Line 660 
 $ make
+Line 768 
 $ make
              <term><filename>-optfile=/PATH/FILENAME</></term>
              <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
              <listitem>
-               <para>This specifies a list of "options files" that will
+               <para>This specifies a list of "options files" that will be passed
-               be passed to <filename>genmake2</>.  If multiple options
+                 to <filename>genmake2</>.  If multiple options files are used
-               files are used (say, to test different compilers or
+                 (say, to test different compilers or different sets of options
-               different sets of options for the same compiler), then
+                 for the same compiler), then each options file will be used with
-               each options file will be used with each of the test
+                 each of the test directories.</para>
-               directories.</para>
              </listitem>
            </varlistentry>
-Line 674 
 $ make
+Line 781 
 $ make
              <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
              <listitem>
                <para>Send the results (namely, <filename>output.txt</>,
-               <filename>gm_local</>, <filename>gm_state</>, and
+                 <filename>genmake_local</>, <filename>genmake_state</>, and
-               <filename>Makefile</>) to the specified email addresses.
+                 <filename>Makefile</>) to the specified email addresses.  The
-               The results are gzipped, placed in a tar file, MIME
+                 results are gzipped, placed in a tar file, MIME encoded, and
-               encoded, and sent to an @mitgcm.org address.  If no
+                 sent to the specified address.  If no email addresses are
-               email addresses are specified, no mail is sent.</para>
+                 specified, no mail is sent.</para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-mpi</></term>
+             <listitem>
+               <para>If the necessary files
+               (<filename>TESTDIR/code/CPP_EEOPTIONS.h_mpi</> and
+               <filename>TESTDIR/code/SIZE.h_mpi</>) exist, then use them for an
+               MPI--enabled run.  Note that the use of MPI typically requires a
+               special command option (see "-command" below) to invoke the MPI
+               executable.  Examples of PBS scripts using MPI with testreport can be
+               found in the <ulink
+               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
+               MITgcm-contrib area</ulink></para>
+             </listitem>
+           </varlistentry>
+           <varlistentry>
+             <term><filename>-command='some command to run'</></term>
+             <listitem>
+               <para>For some tests, particularly MPI runs, the default "make
+               output.txt" is not sufficient.  This option allows a more general
+               command (or shell script) to be invoked.  Examples of PBS scripts
+               using MPI with testreport can be found in the <ulink
+               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
+               MITgcm-contrib area</ulink></para>
              </listitem>
            </varlistentry>
          </variablelist>
-         <para>The <filename>testreport</> script will write progress
+         <para>The <filename>testreport</> script will write progress to the
-         to the screen (stdout) as it runs.  In addition, it will
+           screen (stdout) as it runs.  In addition, it will create a
-         create a <filename>summary.txt</> file that contains a brief
+           <filename>tr_out.txt</> file that contains a brief comparison of the
-         comparison of the current output with the "known-good"
+           current output with the "known-good" output.</para>
-         output.</para>
        </sect3>
      </sect2>
      <sect2 id="packages">
        <title>Creating MITgcm Packages</title>
-       <para>Optional parts of code have been separated from the MITgcmUV
+       <para>Optional parts of code have been separated from the MITgcmUV core
-       core driver code and organised into packages. The packaging
+         driver code and organised into packages.  The packaging structure
-       structure provides a mechanism for maintaining suites of code,
+         provides a mechanism for maintaining suites of code, specific to
-       specific to particular classes of problems, in a way that is
+         particular classes of problems, in a way that is cleanly separated from
-       cleanly separated from the generic fluid dynamical
+         the generic fluid dynamical engine.</para>
-       engine.</para>
+       <para>The MITgcmUV packaging structure is described below using generic
-       <para>The MITgcmUV packaging structure is described below using
+         package names ${pkg}.  A concrete examples of a package is the code for
-       generic package names ${pkg}.  A concrete examples of a package
+         implementing GM/Redi mixing. This code uses the package name</para>
-       is the code for implementing GM/Redi mixing. This code uses the
-       package name</para>
      </sect2>
-Line 828 
 Package Boot Sequence
+Line 960 
 Package Boot Sequence
       &       CALL ${PKG}_READPARMS( retCode )
          #endif
-. S/R PACKAGES_CHECK()
+. S/R PACKAGES_INIT_FIXED()
+             :
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_INIT_FIXED( retCode )
+         #endif
+. S/R PACKAGES_CHECK()
              :
          #ifdef ALLOW_${PKG}
            if ( use${Pkg} )
-Line 838 
 Package Boot Sequence
+Line 977 
 Package Boot Sequence
       &       CALL PACKAGES_CHECK_ERROR('${PKG}')
          #endif
-. S/R PACKAGES_INIT()
+. S/R PACKAGES_INIT_VARIABLES()
              :
          #ifdef ALLOW_${PKG}
            if ( use${Pkg} )
-      &       CALL ${PKG}_INIT( retCode )
+      &       CALL ${PKG}_INIT_VARIA( )
+         #endif
+ Package Output
+ ==============
+. S/R DO_THE_MODEL_IO
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_DIAGS( )
          #endif
+. S/R PACKAGES_WRITE_PICKUP()
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_WRITE_PICKUP( )
+         #endif
  Description
  ===========
-Line 853 
 Description
+Line 1007 
 Description
      is responsible for reading
      in the package parameters file data.${pkg}, and storing
      the package parameters in "${PKG}.h".
-     -> called in INITIALISE_FIXED
+     -> called from INITIALISE_FIXED in PACKAGES_READPARMS
+      - ${PKG}_INIT_FIXED()
+     is responsible for completing the internal setup of a package.
+     -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
+     note: 1) some pkg use instead:
+              CALL ${PKG}_INITIALISE  ( or the old form CALL ${PKG}_INIT )
+) for simple pkg setup, this part is done inside ${PKG}_READPARMS
       - ${PKG}_CHECK()
      is responsible for validating
-Line 862 
 Description
+Line 1023 
 Description
      need to check. This is done through header files "${PKG}.h".
      It is assumed that parameters owned by other packages
      will not be reset during ${PKG}_CHECK().
-     -> called in INITIALISE_FIXED
+     -> called from INITIALISE_FIXED in PACKAGES_CHECK
-      - ${PKG}_INIT()
+      - ${PKG}_INIT_VARIA()
-     is responsible for completing the
+     is responsible for fill-in all package variables with an initial value.
-     internal setup of a package. This routine is called after
+     Contains eventually a call to ${PKG}_READ_PICKUP that will read
-     the core model state has been completely initialised
+     from a pickup file the package variables required to restart the model.
-     but before the core model timestepping starts.
+     This routine is called after the core model state has been completely
-     -> called in INITIALISE_VARIA
+     initialised but before the core model timestepping starts.
+     -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
+     note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
+      use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
+      form ${PKG}_INIT
+      - ${PKG}_DIAGS()
+      is responsible for writing time-average diagnostics to output
+      files (but the cumulating step is done within the package main S/R).
+      Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
+      and write snap-shot fields that are hold in common blocks. Other
+      temporary fields are directly dump to file where they are available.
+      NOTE: this part does not yet have a standard form and should be called
+        from a package dedicated S/R such as PACKAGE_WRITE_DIAGS
+     -> called within DO_THE_MODEL_IO
+      - ${PKG}_WRITE_PICKUP()
+      is responsible for writing a package pickup file when necessary for
+      a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
+     -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
  Summary
  =======
-Line 893 
 Summary
+Line 1073 
 Summary
  - FORTRAN source files
    -----------------------
-   * ${pkg}_readparms.F   reads parameters from file data.${pkg}
+   * ${pkg}_readparms.F    reads parameters from file data.${pkg}
-   * ${pkg}_check.F       checks package dependencies and consistencies
+   * ${pkg}_init_fixed.F   complete the package setup
-   * ${pkg}_init.F        initialises package-related fields
+   * ${pkg}_check.F        checks package dependencies and consistencies
-   * ${pkg}_... .F        package source code
+   * ${pkg}_init_varia.F   initialises package-related fields
+   * ${pkg}_... .F         package source code
+   * ${pkg}_diags.F        write diagnostics to file.
+   * ${pkg}_write_pickup.F write a package pickup file to restart the model
  - parameter file
    -----------------------

 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.6
 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.6
-Removed from v.1.3
+Added in v.1.6

	ViewVC Help
Powered by ViewVC 1.1.22