/[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.1 by edhill, Mon Aug 4 21:09:05 2003 UTC revision 1.2 by edhill, Wed Aug 20 19:47:14 2003 UTC
# Line 4  Line 4 
4    
5  <!--  <!--
6  Build commands:  Build commands:
7      db2ps -d ldp.dsl devel_HOWTO.sgml
8    db2pdf -d ldp.dsl devel_HOWTO.sgml    db2pdf -d ldp.dsl devel_HOWTO.sgml
9    db2html -d ./ldp.dsl devel_HOWTO.sgml    db2html -d ./ldp.dsl devel_HOWTO.sgml
10      db2html -u -d ./ldp.dsl devel_HOWTO.sgml
11  -->  -->
12    
13    <articleinfo>    <articleinfo>
# Line 22  Build commands: Line 24  Build commands:
24      <revhistory>      <revhistory>
25        <revision>        <revision>
26          <revnumber>0.01</revnumber>          <revnumber>0.01</revnumber>
27          <date>2003-0-07</date>          <date>2003-08-07</date>
28          <authorinitials>eh3</authorinitials>          <authorinitials>eh3</authorinitials>
29          <revremark>          <revremark>
30            Initial version.            Initial version.
# Line 395  $ mv scratch/dev_docs /u/u0/httpd/html Line 397  $ mv scratch/dev_docs /u/u0/httpd/html
397    
398    </sect1>    </sect1>
399    
400      <sect1 id="coding">
401        <title>Coding</title>
402    
403        <sect2 id="packages">
404          <title>Coding Packages</title>
405    
406          <para>Optional parts of code have been separated from the MITgcmUV
407          core driver code and organised into packages. The packaging
408          structure provides a mechanism for maintaining suites of code,
409          specific to particular classes of problems, in a way that is
410          cleanly separated from the generic fluid dynamical
411          engine.</para>
412    
413          <para>The MITgcmUV packaging structure is described below using
414          generic package names ${pkg}.  A concrete examples of a package
415          is the code for implementing GM/Redi mixing. This code uses the
416          package name</para>
417    
418        </sect2>
419    
420      </sect1>
421    
422      <sect1>
423        <title>Chris's Notes...</title>
424    
425    <programlisting>
426               MITgcmUV Packages
427               =================
428    
429      Optional parts of code are separated from
430    the MITgcmUV core driver code and organised into
431    packages. The packaging structure provides a mechanism for
432    maintaining suites of code, specific to particular
433    classes of problem, in a way that is cleanly
434    separated from the generic fluid dynamical engine.
435    
436     The MITgcmUV packaging structure is describe
437    below using generic package names ${pkg}.
438    A concrete examples of a package is the code
439    for implementing GM/Redi mixing. This code uses
440    the package name
441    *   ${PKG} = GMREDI
442    *   ${pkg} = gmredi
443    *   ${Pkg} = gmRedi
444    
445    Package states
446    ==============
447    
448     Packages can be any one of four states, included,
449     excluded, enabled, disabled as follows:
450    
451     included(excluded) compile time state which
452                        includes(excludes) package
453                        code and routine calls from
454                        compilation/linking etc...
455    
456     enabled(disabled)  run-time state which
457                        enables(disables) package code
458                        execution.
459    
460     Every call to a ${pkg}_... routine from outside the package
461     should be placed within both a
462     #ifdef ALLOW_${PKG} ... block and a
463     if ( use${Pkg} ) ... then block.
464     Package states are generally not expected to change during
465     a model run.
466    
467    Package structure
468    =================
469    
470    o  Each package gets its runtime configuration
471       parameters from a file named "data.${pkg}"
472       Package runtime config. options are imported
473       into a common block held in a header file
474       called "${PKG}.h".
475    
476    o  The core driver part of the model can check
477       for runtime enabling or disabling of individual packages
478       through logical flags use${Pkg}.
479       The information is loaded from a
480       global package setup file called "data.pkg".
481       The use${Pkg} flags are not used within
482       individual packages.
483    
484    o  Included in "${PKG}.h" is a logical flag
485       called ${Pkg}IsOn. The "${PKG}.h" header file can be imported
486       by other packages to check dependencies and requirements
487       from other packages ( see "Package Boot Sequence" section).
488       NOTE: This procedure is not presently implemented,
489       ----- neither for kpp nor for gmRedi.
490    
491    CPP Flags
492    =========
493    
494        1. Within the core driver code flags of the form
495           ALLOW_${PKG} are used to include or exclude
496           whole packages. The ALLOW_${PKG} flags are included
497           from a PKG_CPP_OPTIONS block which is currently
498           held in-line in the CPP_OPTIONS.h header file.
499           e.g.
500    
501           Core model code .....
502    
503           #include "CPP_OPTIONS.h"
504             :
505             :
506             :
507    
508           #ifdef ALLOW_${PKG}
509             if ( use${Pkg} ) CALL ${PKG}_DO_SOMETHING(...)
510           #endif
511    
512        2. Within an individual package a header file,
513           "${PKG}_OPTIONS.h", is used to set CPP flags
514           specific to that package. It is not recommended
515           to include this file in "CPP_OPTIONS.h".
516    
517    
518    Package Boot Sequence
519    =====================
520    
521        Calls to package routines within the core code timestepping
522        loop can vary. However, all packages follow a required
523        "boot" sequence outlined here:
524    
525        1. S/R PACKAGES_BOOT()
526                :
527            CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
528    
529    
530        2. S/R PACKAGES_READPARMS()
531                :
532            #ifdef ALLOW_${PKG}
533              if ( use${Pkg} )
534         &       CALL ${PKG}_READPARMS( retCode )
535            #endif
536    
537        2. S/R PACKAGES_CHECK()
538                :
539            #ifdef ALLOW_${PKG}
540              if ( use${Pkg} )
541         &       CALL ${PKG}_CHECK( retCode )
542            #else
543              if ( use${Pkg} )
544         &       CALL PACKAGES_CHECK_ERROR('${PKG}')
545            #endif
546    
547        3. S/R PACKAGES_INIT()
548                :
549            #ifdef ALLOW_${PKG}
550              if ( use${Pkg} )
551         &       CALL ${PKG}_INIT( retCode )
552            #endif
553    
554    
555    Description
556    ===========
557    
558          - ${PKG}_READPARMS()
559        is responsible for reading
560        in the package parameters file data.${pkg}, and storing
561        the package parameters in "${PKG}.h".
562        -> called in INITIALISE_FIXED
563    
564         - ${PKG}_CHECK()
565        is responsible for validating
566        basic package setup and inter-package dependencies.
567        ${PKG}_CHECK can import other package parameters it may
568        need to check. This is done through header files "${PKG}.h".
569        It is assumed that parameters owned by other packages
570        will not be reset during ${PKG}_CHECK().
571        -> called in INITIALISE_FIXED
572    
573         - ${PKG}_INIT()
574        is responsible for completing the
575        internal setup of a package. This routine is called after
576        the core model state has been completely initialised
577        but before the core model timestepping starts.
578        -> called in INITIALISE_VARIA
579    
580    Summary
581    =======
582    
583    - CPP options:
584      -----------------------
585      * ALLOW_${PKG}         include/exclude package for compilation
586    
587    - FORTRAN logical:
588      -----------------------
589      * use${Pkg}            enable package for execution at runtime
590                             -> declared in PARAMS.h
591      * ${Pkg}IsOn           for package cross-dependency check
592                             -> declared in ${PKG}.h
593                             N.B.: Not presently used!
594    
595    - header files
596      -----------------------
597      * ${PKG}_OPTIONS.h     has further package-specific CPP options
598      * ${PKG}.h             package-specific common block variables, fields
599    
600    - FORTRAN source files
601      -----------------------
602      * ${pkg}_readparms.F   reads parameters from file data.${pkg}
603      * ${pkg}_check.F       checks package dependencies and consistencies
604      * ${pkg}_init.F        initialises package-related fields
605      * ${pkg}_... .F        package source code
606    
607    - parameter file
608      -----------------------
609      * data.${pkg}          parameter file
610    </programlisting>
611    
612      </sect1>
613    
614    
615  </article>  </article>
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2
  ViewVC Help
Powered by ViewVC 1.1.22