/[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.4 by edhill,
Thu Nov 20 00:01:42 2003 UTC
+revision 1.7 by edhill,
Tue Apr  6 04:12:00 2004 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 190 
 Build commands:
+Line 182 
 Build commands:
        <title>Branches</title>
        <para>As shown in the online <ulink
-       url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">ViewCVS-generated
+       url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">
-       tree</ulink>, the MITgcm codebase is split into to two branches
+       ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two
-       or "lines" under which development proceeds.  These two lines
+       branches or "lines" under which development proceeds.  These two lines are
-       are referred to as the "MAIN" and "ecco" versions of the code.
+       referred to as the "MAIN" and "ecco" versions of the code.  While not
-       While not identical, the bulk of the MAIN and ecco lines are
+       identical, the bulk of the MAIN and ecco lines are composed of files from
-       composed of files from the same codebase.
+       the same codebase.
        </para>
        <para>Periodically, a "Release" branch is formed from the "MAIN"
-       development branch.  This is done in order to create a
+       development branch.  This is done in order to create a relatively stable
-       relatively stable reference point for both users and developers.
+       reference point for both users and developers.  The intent is that once a
-       The intent is that once a relese branch has been created, only
+       relese branch has been created, only bug-fixes will be added to it.
-       bug-fixes will be added to it.  Meanwhile, development (which
+       Meanwhile, development (which might "break" or otherwise render invalid
-       might "break" or otherwise render invalid the documentation,
+       the documentation, tutorials, and/or examples contained within a release
-       tutorials, and/or examples contained within a release branch) is
+       branch) is allowed to continue along the MAIN and ecco lines.</para>
-       allowed to continue along the MAIN and ecco lines.</para>
      </sect2>
      <sect2>
        <title>Tagging</title>
-       <para>The intent of tagging is to create "known-good"
+       <para>The intent of tagging is to create "known-good" checkpoints that
-       checkpoints that developers can use as references.
+       developers can use as references.  Traditionally, MITgcm tagging has
-       Traditionally, MITgcm tagging has maintained the following
+       maintained the following conventions:</para>
-       conventions:</para>
        <orderedlist>
          <listitem>
-           <para>Developer checks out code into a local CVS-managed
+           <para>Developer checks out code into a local CVS-managed directory,
-           directory, makes various changes/additions, tests these
+           makes various changes/additions, tests these edits, and eventually
-           edits, and eventually reaches a point where (s)he is
+           reaches a point where (s)he is satisfied that the changes form a new
-           satisfied that the changes form a new "useful" point in the
+           "useful" point in the evolution of the code.</para>
-           evolution of the code.</para>
          </listitem>
          <listitem>
            <para>The developer then runs the <ulink
-           url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">testscript</ulink>
+           url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">
-           shell script to see if any problems are introduced.  While
+           testscript</ulink> shell script to see if any problems are introduced.
-           not intended to be exhaustive, the test cases within the
+           While not intended to be exhaustive, the test cases within the
-           verification directory do provide some indication whether
+           verification directory do provide some indication whether gross errors
-           gross errors have been introduced.
+           have been introduced.
            </para>
          </listitem>
-Line 241 
 Build commands:
+Line 230 
 Build commands:
            then:</para>
            <orderedlist>
              <listitem>
-               <para>adds a "checkpointXY_pre" comment (where X is a
+               <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
-               checkpoint number and Y is a letter) to the <ulink
+               number and Y is a letter) to the <ulink
-               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">tag-index</ulink>
+               url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">
-               file and checks it into the CVS repository</para>
+               tag-index</ulink> file and checks it into the CVS
+               repository</para>
              </listitem>
              <listitem>
-               <para>submits the set of changes to the CVS repository
+               <para>submits the set of changes to the CVS repository and adds
-               and adds comments to <filename>tag-index</filename>
+               comments to <filename>tag-index</filename> describing what the
-               describing what the changes are along with a matching
+               changes are along with a matching "checkpointXY_post" entry</para>
-               "checkpointXY_post" entry</para>
              </listitem>
            </orderedlist>
          </listitem>
        </orderedlist>
-       <para>The result of this tagging procedure is a sequence of
+       <para>The result of this tagging procedure is a sequence of development
-       development checkpoints with comments which resembles:</para>
+       checkpoints with comments which resembles:</para>
  <programlisting>
  checkpoint50e_post
-Line 279 
 o fix small problem with in ptracers_wri
+Line 268 
 o fix small problem with in ptracers_wri
  checkpoint50d_pre
  </programlisting>
-       <para>This information can be used to refer to various stages of
+       <para>This information can be used to refer to various stages of the code
-       the code development.  For example, bugs can be traced to
+       development.  For example, bugs can be traced to individual sets of CVS
-       individual sets of CVS checkins based upon their first
+       checkins based upon their first appearance when comparing the results from
-       appearance when comparing the results from different
+       different checkpoints.</para>
-       checkpoints.</para>
      </sect2>
    </sect1>
-Line 295 
 checkpoint50d_pre
+Line 283 
 checkpoint50d_pre
      <sect2 id="documentation_getting">
        <title>Getting the Docs and Code</title>
-       <para>The first step towards editing the documentation is to
+       <para>The first step towards editing the documentation is to checkout a
-       checkout a copy of code, docs, and build scripts from the CVS
+       copy of code, docs, and build scripts from the CVS server using:</para>
-       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:NAME@mitgcm.org:/u/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
+       <para>These commands extract the necessary information from the CVS server
-       CVS server and create a temporary (called
+       and create a temporary (called <filename>scratch</filename>) directory for
-       <filename>scratch</filename>) directory for the storage of the
+       the storage of the HTML and other files that will be created.  Please note
-       HTML and other files that will be created.  Please note that you
+       that you must either create <filename>scratch</filename> as shown or edit
-       must either create <filename>scratch</filename> as shown or edit
+       the various <filename>Makefile</filename>s and scripts used to create the
-       the various <filename>Makefile</filename>s and scripts used to
+       documentation.</para>
-       create the documentation.</para>
      </sect2>
      <sect2>
        <title>Editing the Documentation</title>
-       <para>The documentation is contained in the
+       <para>The documentation is contained in the <filename>manual</filename>
-       <filename>manual</filename> directory in a raw LaTeX format.
+       directory in a raw LaTeX format.  The main document is
-       The main document is <filename>manual.tex</filename> and it uses
+       <filename>manual.tex</filename> and it uses <command>\input{}</command>s
-       <command>\input{}</command>s to include the chapters and
+       to include the chapters and subsections.</para>
-       subsections.</para>
+       <para>Since the same LaTeX source is used to produce PostScript, PDF, and
-       <para>Since the same LaTeX source is used to produce PostScript,
+       HTML output, care should be taken to follow certain conventions.  Two of
-       PDF, and HTML output, care should be taken to follow certain
+       the most important are the usage of the <command>\filelink{}{}</command>
-       conventions.  Two of the most important are the usage of the
+       and <command>\varlink{}{}</command> commands.  Both of these commands have
-       <command>\filelink{}{}</command> and
+       been defined to simplify the connection between the automatically
-       <command>\varlink{}{}</command> commands.  Both of these
+       generated ("code browser") HTML and the HTML version of the manual
-       commands have been defined to simplify the connection between
+       produced by LaTeX2HTML.  They each take two arguments (corresponding to
-       the automatically generated ("code browser") HTML and the HTML
+       the contents of the two sets of curly braces) which are the text that the
-       version of the manual produced by LaTeX2HTML.  They each take
+       author wishes to be "wrapped" within the link, and a specially formatted
-       two arguments (corresponding to the contents of the two sets of
+       link thats relative to the <filename>MITgcm</filename> directory within
-       curly braces) which are the text that the author wishes to be
+       the CVS tree.</para>
-       "wrapped" within the link, and a specially formatted link thats
-       relative to the <filename>MITgcm</filename> directory within the
-       CVS tree.</para>
        <para>The result is a command that resembles either</para>
-Line 371 
 $ cvs co MITgcm manual mitgcm.org
+Line 354 
 $ cvs co MITgcm manual mitgcm.org
        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
+       <para>Which builds the PDF from the LaTeX source, creates the HTML output
-       HTML output from the LaTeX source, parses the FORTRAN code base
+       from the LaTeX source, parses the FORTRAN code base to produce a
-       to produce a hyperlinked HTML version of the source, and then
+       hyperlinked HTML version of the source, and then determines the
-       determines the cross-linking between the various HTML
+       cross-linking between the various HTML components.</para>
-       components.</para>
+       <para>If there are no errors, the result of the build process (which can
-       <para>If there are no errors, the result of the build process
+       take 30+ minutes on a P4/2.5Ghz) will be contained within a single
-       (which can take 30+ minutes on a P4/2.5Ghz) will be contained
+       directory called <filename>scratch/dev_docs</filename>.  This is a freshly
-       within a single directory called
+       built version of the entire on-line users manual.  If you have the correct
-       <filename>scratch/dev_docs</filename>.  This is a freshly built
+       permissions, it can be directly copied to the web server area:</para>
-       version of the entire on-line users manual.  If you have the
-       correct permissions, it can be directly copied to the web server
-       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 412 
 $ mv scratch/dev_docs /u/u0/httpd/html
+Line 392 
 $ mv scratch/dev_docs /u/u0/httpd/html
          For MITgcm, the process is 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 the build
-Line 448 
 $ make
+Line 428 
 $ make
          simple as:</para>
  <screen>
- $ genmake2 -mods=../code
+   $ genmake2 -mods=../code
  </screen>
          <para>However, some systems (particularly commercial Unixes that lack a
-Line 457 
 $ genmake2 -mods=../code
+Line 437 
 $ genmake2 -mods=../code
            the following: </para>
  <screen>
- $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
+   $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
- $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/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)
-Line 471 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
+Line 451 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
          <orderedlist>
            <listitem>
-             <para>a <filename>gm_local</filename> file in the current
+             <para>a <filename>gemake_local</filename> file in the current
                directory</para>
            </listitem>
            <listitem>
-Line 491 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
+Line 471 
 $ /opt/gnu/bin/bash genmake2 -ieee -make
            from:</para>
  <screen>
- $ genmake2 -help
+   $ genmake2 -help
  </screen>
          <para>The most important options for <filename>genmake2</> are:</para>
-Line 547 
 $ genmake2 -help
+Line 527 
 $ genmake2 -help
                specified, then it is assumed that the two packages are compatible
                and will function either with or without each other.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
-Line 562 
 $ genmake2 -help
+Line 541 
 $ genmake2 -help
            </varlistentry>
            <varlistentry>
+             <term><filename>-adof=/path/to/file</></term>
+             <term><filename>-adoptfile=/path/to/file</></term>
+             <listitem>
+               <para>This option specifies the "adjoint" or automatic
+                 differentiation options file to be used.  The file is analogous
+                 to the "optfile" defined above but it specifies information for
+                 the AD build process.  The default file is located in <filename>
+                 $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>
-Line 615 
 $ genmake2 -help
+Line 612 
 $ genmake2 -help
        </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 an 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 stale source files, include
-Line 647 
 $ make
+Line 645 
 $ make
            substitutions) custom definitions such as variable types within the
            source files.  This additional stage is necessary in order to overcome
            some of the inconsistencies in the sizes of objects (bytes) between
-           different compilers.</para>
+           different compilers. The result of the build process is an executable
+           with the name <filename>mitgcmuv</>.</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>
-         <para>Please report compilation failures or other problems to
+           <varlistentry>
-           <email>MITgcm-support@mitgcm.org</email>.</para>
+             <term><filename>make ftlall</></term>
+             <listitem>
+               <para>Similar to <filename>make adall</> above, this
+                 produces...</para>
+             </listitem>
+           </varlistentry>
+         </variablelist>
+         <para>Please report any compilation failures or other build problems to
+           the <email>MITgcm-support@mitgcm.org</email> list.</para>
        </sect3>
-Line 683 
 $ make
+Line 710 
 $ make
          line as simple as:</para>
  <screen>
- $ cd verification
+   $ cd verification
- $ ./testreport -ieee
+   $ ./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'
+   $ sh ./testreport -ieee -t 'exp0 exp4'
- $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
+   $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
  </screen>
          <para>The <filename>testreport</> script accepts a number of
-Line 921 
 Package Boot Sequence
+Line 948 
 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 931 
 Package Boot Sequence
+Line 965 
 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 946 
 Description
+Line 995 
 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 955 
 Description
+Line 1011 
 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 986 
 Summary
+Line 1061 
 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.4
 


changed lines


 
Added in v.1.7
 Legend:



Removed from v.1.4
 


changed lines


 
Added in v.1.7
-Removed from v.1.4
+Added in v.1.7

	ViewVC Help
Powered by ViewVC 1.1.22