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

Diff of /MITgcm/doc/devel_HOWTO.sgml

Parent Directory Parent Directory | Revision Log 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.6 by jmc, Tue Dec 23 22:42:20 2003 UTC
# Line 2  Line 2 
2    
3  <article id="MITgcm-Development-HOWTO">  <article id="MITgcm-Development-HOWTO">
4    
 <!--  
 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  
 -->  
   
5    <articleinfo>    <articleinfo>
6      <title>MITgcm Development HOWTO</title>      <title>MITgcm Development HOWTO</title>
7    
# Line 63  Build commands: Line 55  Build commands:
55      <sect2>      <sect2>
56        <title>User Manual</title>        <title>User Manual</title>
57    
58        <para>Before jumping into        <para>Before jumping into development, please familiarize yourself with
59        development, please familiarize yourself with the MITgcm user          the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual
60        manual which is available <ulink          </ulink>.  This document contains volumes of useful information and is
61        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>  
62    
63        <para>Also, a "snapshot" or<ulink        <!--
64          <para>Also, a "snapshot" or <ulink
65        url="http://mitgcm.org/dev_docs/">development version</ulink> of        url="http://mitgcm.org/dev_docs/">development version</ulink> of
66        the user manual may be available, though this is only put on the        the user manual may be available, though this is only put on the
67        web for testing purposes.</para>        web for testing purposes.</para>
68          -->
69      </sect2>      </sect2>
70    
71      <sect2>      <sect2>
# Line 300  checkpoint50d_pre Line 292  checkpoint50d_pre
292        server using:</para>        server using:</para>
293    
294  <screen>  <screen>
295  $ export CVS_RSH=ssh    $ export CVS_RSH=ssh
296  $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'    $ export CVSROOT=':ext:auden.lcs.mit.edu:/u/u3/gcmpack'
297  $ mkdir scratch    $ mkdir scratch
298  $ cvs co MITgcm manual mitgcm.org    $ cvs co MITgcm manual mitgcm.org
299  </screen>  </screen>
300    
301        <para>These commands extract the necessary information from the        <para>These commands extract the necessary information from the
# Line 371  $ cvs co MITgcm manual mitgcm.org Line 363  $ cvs co MITgcm manual mitgcm.org
363        site can be built using:</para>        site can be built using:</para>
364    
365  <screen>  <screen>
366  $ cd mitgcm.org/devel/buildweb    $ cd mitgcm.org/devel/buildweb
367  $ make All    $ make All
368  </screen>  </screen>
369    
370        <para>Which builds the PDF from the LaTeX source, creates the        <para>Which builds the PDF from the LaTeX source, creates the
# Line 390  $ make All Line 382  $ make All
382        area:</para>        area:</para>
383    
384  <screen>  <screen>
385  $ mv scratch/dev_docs /u/u0/httpd/html    $ mv scratch/dev_docs /u/u0/httpd/html
386  </screen>  </screen>
387    
388        <para>and the update is complete.</para>        <para>and the update is complete.</para>
# Line 412  $ mv scratch/dev_docs /u/u0/httpd/html Line 404  $ mv scratch/dev_docs /u/u0/httpd/html
404          For MITgcm, the process is similar.  Typical commands are:</para>          For MITgcm, the process is similar.  Typical commands are:</para>
405    
406  <screen>  <screen>
407  $ genmake -mods=../code    $ genmake -mods=../code
408  $ make depend    $ make depend
409  $ make    $ make
410  </screen>  </screen>
411    
412        <para>The following sections describe the individual steps in the build        <para>The following sections describe the individual steps in the build
# Line 448  $ make Line 440  $ make
440          simple as:</para>          simple as:</para>
441    
442  <screen>  <screen>
443  $ genmake2 -mods=../code    $ genmake2 -mods=../code
444  </screen>  </screen>
445    
446          <para>However, some systems (particularly commercial Unixes that lack a          <para>However, some systems (particularly commercial Unixes that lack a
# Line 457  $ genmake2 -mods=../code Line 449  $ genmake2 -mods=../code
449            the following: </para>            the following: </para>
450    
451  <screen>  <screen>
452  $ /usr/bin/sh genmake2 -make=gmake  -mods=../code    $ /usr/bin/sh genmake2 -make=gmake  -mods=../code
453  $ /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
454  </screen>  </screen>
455    
456          <para>The genmake2 code has been written in a Bourne and BASH (v1)          <para>The genmake2 code has been written in a Bourne and BASH (v1)
# Line 471  $ /opt/gnu/bin/bash genmake2 -ieee -make Line 463  $ /opt/gnu/bin/bash genmake2 -ieee -make
463    
464          <orderedlist>          <orderedlist>
465            <listitem>            <listitem>
466              <para>a <filename>gm_local</filename> file in the current              <para>a <filename>gemake_local</filename> file in the current
467                directory</para>                directory</para>
468            </listitem>            </listitem>
469            <listitem>            <listitem>
# Line 491  $ /opt/gnu/bin/bash genmake2 -ieee -make Line 483  $ /opt/gnu/bin/bash genmake2 -ieee -make
483            from:</para>            from:</para>
484    
485  <screen>  <screen>
486  $ genmake2 -help    $ genmake2 -help
487  </screen>  </screen>
488    
489          <para>The most important options for <filename>genmake2</> are:</para>          <para>The most important options for <filename>genmake2</> are:</para>
# Line 547  $ genmake2 -help Line 539  $ genmake2 -help
539                specified, then it is assumed that the two packages are compatible                specified, then it is assumed that the two packages are compatible
540                and will function either with or without each other.</para>                and will function either with or without each other.</para>
541              </listitem>              </listitem>
   
542            </varlistentry>            </varlistentry>
543    
544            <varlistentry>            <varlistentry>
# Line 562  $ genmake2 -help Line 553  $ genmake2 -help
553            </varlistentry>            </varlistentry>
554    
555            <varlistentry>            <varlistentry>
556                <term><filename>-adof=/path/to/file</></term>
557                <term><filename>-adoptfile=/path/to/file</></term>
558                <listitem>
559                  <para>This option specifies the "adjoint" or automatic
560                    differentiation options file to be used.  The file is analogous
561                    to the "optfile" defined above but it specifies information for
562                    the AD build process.  The default file is located in <filename>
563                    $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
564                    defines the "TAF" and "TAMC" compilers.  An alternate version is
565                    also available at <filename>
566                    $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
567                    newer "STAF" compiler.  As with any compilers, it is helpful to
568                    have their directories listed in your $PATH environment
569                    variable.</para>
570                </listitem>
571              </varlistentry>
572    
573              <varlistentry>
574              <term><filename>-mods=DIR</></term>              <term><filename>-mods=DIR</></term>
575              <term><filename>-mods='DIR1 [DIR2 ...]'</></term>              <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
576              <listitem>              <listitem>
# Line 615  $ genmake2 -help Line 624  $ genmake2 -help
624        </sect3>        </sect3>
625    
626        <sect3 id="makefile_use">        <sect3 id="makefile_use">
627          <title>Using <filename>Makefile</></title>          <title>Using the <filename>Makefile</></title>
628    
629          <para>Once a <filename>Makefile</> has been created, one can          <para>Once a <filename>Makefile</> has been created using
630          build an executable using:</para>            <filename>genmake2</>, one can build a "standard" (forward
631              simulator) executable using:</para>
632    
633  <screen>  <screen>
634  $ make CLEAN    $ make CLEAN
635  $ make depend    $ make depend
636  $ make    $ make
637  </screen>  </screen>
638    
639          <para>The "make CLEAN" step will remove any stale source files, include          <para>The "make CLEAN" step will remove any stale source files, include
# Line 647  $ make Line 657  $ make
657            substitutions) custom definitions such as variable types within the            substitutions) custom definitions such as variable types within the
658            source files.  This additional stage is necessary in order to overcome            source files.  This additional stage is necessary in order to overcome
659            some of the inconsistencies in the sizes of objects (bytes) between            some of the inconsistencies in the sizes of objects (bytes) between
660            different compilers.</para>            different compilers. The result of the build process is an executable
661              with the name <filename>mitgcmuv</>.</para>
662    
663            <para>In addition to the forward simulator described above, the
664              <filename>Makefile</> also has a number of targets that can be used to
665              produce various adjoint and tangent-linear builds for optimization and
666              other parameter-sensitivity problems.  The additional targets within
667              the <filename>Makefile</> are:</para>
668    
669            <variablelist>
670    
671              <varlistentry>
672                <term><filename>make adall</></term>
673                <listitem>
674                  <para>This target produces an <filename>mitgcmuv_ad</> executable
675                    using the <filename>taf</> or <filename>staf</> adjoint
676                    compiler.  See the <filename>genmake2</> "-adof" option for
677                    compiler selection.</para>
678                </listitem>
679              </varlistentry>
680    
681          <para>Please report compilation failures or other problems to            <varlistentry>
682            <email>MITgcm-support@mitgcm.org</email>.</para>              <term><filename>make ftlall</></term>
683                <listitem>
684                  <para>Similar to <filename>make adall</> above, this
685                    produces...</para>
686                </listitem>
687              </varlistentry>
688    
689            </variablelist>
690    
691            <para>Please report any compilation failures or other build problems to
692              the <email>MITgcm-support@mitgcm.org</email> list.</para>
693    
694        </sect3>        </sect3>
695    
# Line 683  $ make Line 722  $ make
722          line as simple as:</para>          line as simple as:</para>
723    
724  <screen>  <screen>
725  $ cd verification    $ cd verification
726  $ ./testreport -ieee    $ ./testreport -ieee
727  </screen>  </screen>
728    
729          <para>However, some systems (those lacking or wiht a broken "/bin/sh")          <para>However, some systems (those lacking or wiht a broken "/bin/sh")
730            may require an explicit shell invocation such as:</para>            may require an explicit shell invocation such as:</para>
731    
732  <screen>  <screen>
733  $ sh ./testreport -ieee -t 'exp0 exp4'    $ sh ./testreport -ieee -t 'exp0 exp4'
734  $ /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'
735  </screen>  </screen>
736    
737          <para>The <filename>testreport</> script accepts a number of          <para>The <filename>testreport</> script accepts a number of
# Line 921  Package Boot Sequence Line 960  Package Boot Sequence
960       &       CALL ${PKG}_READPARMS( retCode )       &       CALL ${PKG}_READPARMS( retCode )
961          #endif          #endif
962    
963      2. S/R PACKAGES_CHECK()      3. S/R PACKAGES_INIT_FIXED()
964                :
965            #ifdef ALLOW_${PKG}
966              if ( use${Pkg} )
967         &       CALL ${PKG}_INIT_FIXED( retCode )
968            #endif
969    
970        4. S/R PACKAGES_CHECK()
971              :              :
972          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
973            if ( use${Pkg} )            if ( use${Pkg} )
# Line 931  Package Boot Sequence Line 977  Package Boot Sequence
977       &       CALL PACKAGES_CHECK_ERROR('${PKG}')       &       CALL PACKAGES_CHECK_ERROR('${PKG}')
978          #endif          #endif
979    
980      3. S/R PACKAGES_INIT()      5. S/R PACKAGES_INIT_VARIABLES()
981              :              :
982          #ifdef ALLOW_${PKG}          #ifdef ALLOW_${PKG}
983            if ( use${Pkg} )            if ( use${Pkg} )
984       &       CALL ${PKG}_INIT( retCode )       &       CALL ${PKG}_INIT_VARIA( )
985          #endif          #endif
986    
987    Package Output
988    ==============
989         6. S/R DO_THE_MODEL_IO
990    
991            #ifdef ALLOW_${PKG}
992              if ( use${Pkg} )
993         &       CALL ${PKG}_DIAGS( )
994            #endif
995    
996         7. S/R PACKAGES_WRITE_PICKUP()
997    
998            #ifdef ALLOW_${PKG}
999              if ( use${Pkg} )
1000         &       CALL ${PKG}_WRITE_PICKUP( )
1001            #endif
1002    
1003  Description  Description
1004  ===========  ===========
# Line 946  Description Line 1007  Description
1007      is responsible for reading      is responsible for reading
1008      in the package parameters file data.${pkg}, and storing      in the package parameters file data.${pkg}, and storing
1009      the package parameters in "${PKG}.h".      the package parameters in "${PKG}.h".
1010      -> called in INITIALISE_FIXED      -> called from INITIALISE_FIXED in PACKAGES_READPARMS
1011    
1012         - ${PKG}_INIT_FIXED()
1013        is responsible for completing the internal setup of a package.
1014        -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
1015        note: 1) some pkg use instead:
1016                 CALL ${PKG}_INITIALISE  ( or the old form CALL ${PKG}_INIT )
1017              2) for simple pkg setup, this part is done inside ${PKG}_READPARMS
1018    
1019       - ${PKG}_CHECK()       - ${PKG}_CHECK()
1020      is responsible for validating      is responsible for validating
# Line 955  Description Line 1023  Description
1023      need to check. This is done through header files "${PKG}.h".      need to check. This is done through header files "${PKG}.h".
1024      It is assumed that parameters owned by other packages      It is assumed that parameters owned by other packages
1025      will not be reset during ${PKG}_CHECK().      will not be reset during ${PKG}_CHECK().
1026      -> called in INITIALISE_FIXED      -> called from INITIALISE_FIXED in PACKAGES_CHECK
1027    
1028       - ${PKG}_INIT()       - ${PKG}_INIT_VARIA()
1029      is responsible for completing the      is responsible for fill-in all package variables with an initial value.
1030      internal setup of a package. This routine is called after      Contains eventually a call to ${PKG}_READ_PICKUP that will read
1031      the core model state has been completely initialised      from a pickup file the package variables required to restart the model.
1032      but before the core model timestepping starts.      This routine is called after the core model state has been completely
1033      -> called in INITIALISE_VARIA      initialised but before the core model timestepping starts.
1034        -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
1035        note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
1036         use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
1037         form ${PKG}_INIT
1038    
1039         - ${PKG}_DIAGS()
1040         is responsible for writing time-average diagnostics to output
1041         files (but the cumulating step is done within the package main S/R).
1042         Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1043         and write snap-shot fields that are hold in common blocks. Other
1044         temporary fields are directly dump to file where they are available.
1045         NOTE: this part does not yet have a standard form and should be called
1046           from a package dedicated S/R such as PACKAGE_WRITE_DIAGS
1047        -> called within DO_THE_MODEL_IO
1048    
1049         - ${PKG}_WRITE_PICKUP()
1050         is responsible for writing a package pickup file when necessary for
1051         a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1052        -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1053    
1054  Summary  Summary
1055  =======  =======
# Line 986  Summary Line 1073  Summary
1073    
1074  - FORTRAN source files  - FORTRAN source files
1075    -----------------------    -----------------------
1076    * ${pkg}_readparms.F   reads parameters from file data.${pkg}    * ${pkg}_readparms.F    reads parameters from file data.${pkg}
1077    * ${pkg}_check.F       checks package dependencies and consistencies    * ${pkg}_init_fixed.F   complete the package setup
1078    * ${pkg}_init.F        initialises package-related fields    * ${pkg}_check.F        checks package dependencies and consistencies
1079    * ${pkg}_... .F        package source code    * ${pkg}_init_varia.F   initialises package-related fields
1080      * ${pkg}_... .F         package source code
1081      * ${pkg}_diags.F        write diagnostics to file.
1082      * ${pkg}_write_pickup.F write a package pickup file to restart the model
1083    
1084  - parameter file  - parameter file
1085    -----------------------    -----------------------
Legend:
Removed from v.1.4  
changed lines
  Added in v.1.6
  ViewVC Help
Powered by ViewVC 1.1.22