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> |
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. |
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> |