eesupp/src/main.F

C $Header: /u/u3/gcmpack/MITgcm/eesupp/src/main.F,v 1.10 2003/10/02 21:30:22 heimbach Exp $
C $Name:  $

CBOI
C
C !TITLE: WRAPPER CODE SYNOPSIS
C !AUTHORS: mitgcm developers ( support@mitgcm.org )
C !AFFILIATION: Massachussetts Institute of Technology
C !DATE:
C !INTRODUCTION: Wrapper synopsis and code
C Routines in the subdirectories under eesupp/ ( src/ and inc/ ) provide the core
C framework within which numerical and ancilliary software of MITgcm operates.
C The eesupp/ directories provide a collection of software we call {\bf WRAPPER} (
C ({\bf W}rappable {\bf A}pplication {\bf P}aralell {\bf P}rogramming {\bf E}nvironment {\bf R}esource).
C The {bf WRAPPER} provides a generic bootstrapping capability to start applications
C in a manner that allows them to exploit single and multi-processing environments on all present 
C day hardware platforms (spanning vector SMP systems to distributed memory and processing cluster
C systems). Numerical applications must be coded to fit within the {\bf WRAPPER}. This entails
C applications adopting a particular style for declaring data structures representing
C grids and values on grids. The {\bf WRAPPER} currently provides support for grid point
C models using a single global indexing system. This is sufficient for latitude-logitude,
C cylindrical, and cartesian coordinate configurations. There is also limited support for
C composing grids in which no single, sructured global index can be defined. At present, this 
C support is limited to specific configurations of projections of a cube onto the sphere.
C
C The main functions supported by the current {\bf WRAPPER} code are
C \begin{itemize}
C  \item program startup and termination including creation/management of multiple 
C        threads and/or processes
C  \item communication and synchronisatioin operations between multiple processes and/or threads 
C  \item multi-process input and output operations to disk and to other 
C  applications
C \end{itemize}
C
C Multi-process execution assumes the existence of MPI for process startup and termination. However,
C MPI does not have to be used for performance critical operations. Instead,
C {\bf WRAPPER} performance critical parallel primitives are implemented to allow them to bind to 
C different low-level system software layers. Bindings exist for using {\bf WRAPPER} with portable
C systems such as MPI and UNIX System V IPC memory mapping, as well bindings for high-performance 
C propreitary systems such as Myrinet GM software and Compaq IMC memory channel technology.
C 
CEOI


C--   Get C preprocessor options
#include "PACKAGES_CONFIG.h"
#include "CPP_OPTIONS.h"
#include "CPP_EEOPTIONS.h"

CBOP
C !ROUTINE: MAIN

C !INTERFACE:
      PROGRAM MAIN
      IMPLICIT NONE

C !DESCRIPTION:
C     *==========================================================*
C     | PROGRAM MAIN                                            
C     | o MAIN wrapper for MITgcm UV implementation.            
C     *==========================================================*
C     | MAIN controls the "execution environment".               
C     | Its main functions are                                   
C     | 1. call procedure EEBOOT to perform execution environment
C     |    initialisation.                                       
C     | 2. call procedure THE_MODEL_MAIN once for each concurrent
C     |    thread. THE_MODEL_MAIN is the user supplied top-level 
C     |    routine.                                              
C     | 3. call procedure EEDIE to perform execution environment 
C     |    shutdown.                                             
C     *==========================================================*

C      !CALLING SEQUENCE:
C
C      main()       
C      |
C      |--eeboot()         :: WRAPPER initilization
C      |
C      |--check_threads()  :: Validate multiple thread start up.
C      |
C      |--the_model_main() :: Numerical code top-level driver routine
C      |
C      |--eedie()          :: WRAPPER termination

C     !USES:
C     == Global variables ==
C     Include all the "shared" data here. That means all common
C     blocks used in the model. On many implementations this is not
C     necessary but doing this is the safest method.
#include "SIZE.h"
#include "EEPARAMS.h"
#include "EESUPPORT.h"
#include "THE_MODEL_COMMON_BLOCKS.h"

C     !LOCAL VARIABLES:
C--   Local variables
      INTEGER myThid
      INTEGER I
CEOP

C--   Set up the execution environment
C     EEBOOT loads a execution environment parameter file 
C     ( called "eedata" by default ) and sets variables 
C     accordingly.
      CALL EEBOOT

C--   Trap errors 
      IF ( eeBootError ) THEN
       fatalError = .TRUE.
       GOTO 999
      ENDIF

C--   Start nThreads concurrent threads.   
C     Note: We do a fiddly check here. The check is performed
C           by CHECK_THREADS. CHECK_THREADS does a count
C           of all the threads. If after ten seconds it has not
C           found nThreads threads are running it flags an
C           error. This traps the case in which the input 
C           parameter nThreads is different from the actual 
C           number of concurrent threads the OS gives us. This
C           case causes a deadlock if we do not trap it here.
#include "MAIN_PDIRECTIVES1.h"
      DO I=1,nThreads
        myThid = I

C--     Do check to see if there are nThreads threads running
        IF ( .NOT. eeBootError ) THEN
         CALL CHECK_THREADS( myThid )
        ENDIF

C--     Invoke nThreads instances of the numerical model
        IF ( .NOT. eeBootError ) THEN
#ifdef ALLOW_ADMTLM_RUN
         CALL DSVD(myThid)
#else
         CALL THE_MODEL_MAIN(myThid)
#endif
        ENDIF

C--     Each threads sets flag indicating it is done
        threadIsComplete(myThid) = .TRUE.
        IF ( .NOT. eeBootError ) THEN
         _BARRIER
        ENDIF
      ENDDO
#include "MAIN_PDIRECTIVES2.h"

  999 CONTINUE
C--   Shut down execution environment
      CALL EEDIE

C--   Write closedown status
      IF ( fatalError ) THEN
       STOP 'ABNORMAL END: PROGRAM MAIN'
      ELSE
       STOP 'NORMAL END'
      ENDIF
C
      END
1	edhill	1.11	C $Header: /u/u3/gcmpack/MITgcm/eesupp/src/main.F,v 1.10 2003/10/02 21:30:22 heimbach Exp $
2	cnh	1.8	C $Name: $
3
4			CBOI
5			C
6			C !TITLE: WRAPPER CODE SYNOPSIS
7			C !AUTHORS: mitgcm developers ( support@mitgcm.org )
8			C !AFFILIATION: Massachussetts Institute of Technology
9			C !DATE:
10	adcroft	1.9	C !INTRODUCTION: Wrapper synopsis and code
11	cnh	1.8	C Routines in the subdirectories under eesupp/ ( src/ and inc/ ) provide the core
12			C framework within which numerical and ancilliary software of MITgcm operates.
13			C The eesupp/ directories provide a collection of software we call {\bf WRAPPER} (
14			C ({\bf W}rappable {\bf A}pplication {\bf P}aralell {\bf P}rogramming {\bf E}nvironment {\bf R}esource).
15			C The {bf WRAPPER} provides a generic bootstrapping capability to start applications
16			C in a manner that allows them to exploit single and multi-processing environments on all present
17			C day hardware platforms (spanning vector SMP systems to distributed memory and processing cluster
18			C systems). Numerical applications must be coded to fit within the {\bf WRAPPER}. This entails
19			C applications adopting a particular style for declaring data structures representing
20			C grids and values on grids. The {\bf WRAPPER} currently provides support for grid point
21			C models using a single global indexing system. This is sufficient for latitude-logitude,
22			C cylindrical, and cartesian coordinate configurations. There is also limited support for
23			C composing grids in which no single, sructured global index can be defined. At present, this
24			C support is limited to specific configurations of projections of a cube onto the sphere.
25			C
26			C The main functions supported by the current {\bf WRAPPER} code are
27			C \begin{itemize}
28			C \item program startup and termination including creation/management of multiple
29			C threads and/or processes
30			C \item communication and synchronisatioin operations between multiple processes and/or threads
31			C \item multi-process input and output operations to disk and to other
32			C applications
33			C \end{itemize}
34			C
35			C Multi-process execution assumes the existence of MPI for process startup and termination. However,
36			C MPI does not have to be used for performance critical operations. Instead,
37			C {\bf WRAPPER} performance critical parallel primitives are implemented to allow them to bind to
38			C different low-level system software layers. Bindings exist for using {\bf WRAPPER} with portable
39			C systems such as MPI and UNIX System V IPC memory mapping, as well bindings for high-performance
40			C propreitary systems such as Myrinet GM software and Compaq IMC memory channel technology.
41			C
42			CEOI
43
44	cnh	1.1
45			C-- Get C preprocessor options
46	edhill	1.11	#include "PACKAGES_CONFIG.h"
47	cnh	1.1	#include "CPP_OPTIONS.h"
48			#include "CPP_EEOPTIONS.h"
49
50	cnh	1.8	CBOP
51			C !ROUTINE: MAIN
52
53			C !INTERFACE:
54	cnh	1.1	PROGRAM MAIN
55	adcroft	1.6	IMPLICIT NONE
56	cnh	1.1
57	cnh	1.8	C !DESCRIPTION:
58			C ==========================================================
59			C \| PROGRAM MAIN
60			C \| o MAIN wrapper for MITgcm UV implementation.
61			C ==========================================================
62			C \| MAIN controls the "execution environment".
63			C \| Its main functions are
64			C \| 1. call procedure EEBOOT to perform execution environment
65			C \| initialisation.
66			C \| 2. call procedure THE_MODEL_MAIN once for each concurrent
67			C \| thread. THE_MODEL_MAIN is the user supplied top-level
68			C \| routine.
69			C \| 3. call procedure EEDIE to perform execution environment
70			C \| shutdown.
71			C ==========================================================
72
73			C !CALLING SEQUENCE:
74			C
75			C main()
76			C \|
77			C \|--eeboot() :: WRAPPER initilization
78			C \|
79			C \|--check_threads() :: Validate multiple thread start up.
80			C \|
81			C \|--the_model_main() :: Numerical code top-level driver routine
82			C \|
83			C \|--eedie() :: WRAPPER termination
84
85			C !USES:
86	cnh	1.1	C == Global variables ==
87			C Include all the "shared" data here. That means all common
88			C blocks used in the model. On many implementations this is not
89			C necessary but doing this is the safest method.
90			#include "SIZE.h"
91			#include "EEPARAMS.h"
92			#include "EESUPPORT.h"
93			#include "THE_MODEL_COMMON_BLOCKS.h"
94
95	cnh	1.8	C !LOCAL VARIABLES:
96	cnh	1.1	C-- Local variables
97			INTEGER myThid
98			INTEGER I
99	cnh	1.8	CEOP
100	cnh	1.1
101			C-- Set up the execution environment
102			C EEBOOT loads a execution environment parameter file
103			C ( called "eedata" by default ) and sets variables
104			C accordingly.
105			CALL EEBOOT
106
107			C-- Trap errors
108			IF ( eeBootError ) THEN
109			fatalError = .TRUE.
110			GOTO 999
111			ENDIF
112
113			C-- Start nThreads concurrent threads.
114			C Note: We do a fiddly check here. The check is performed
115			C by CHECK_THREADS. CHECK_THREADS does a count
116			C of all the threads. If after ten seconds it has not
117			C found nThreads threads are running it flags an
118			C error. This traps the case in which the input
119			C parameter nThreads is different from the actual
120			C number of concurrent threads the OS gives us. This
121	cnh	1.5	C case causes a deadlock if we do not trap it here.
122	cnh	1.1	#include "MAIN_PDIRECTIVES1.h"
123			DO I=1,nThreads
124			myThid = I
125
126			C-- Do check to see if there are nThreads threads running
127			IF ( .NOT. eeBootError ) THEN
128			CALL CHECK_THREADS( myThid )
129			ENDIF
130
131			C-- Invoke nThreads instances of the numerical model
132			IF ( .NOT. eeBootError ) THEN
133	heimbach	1.10	#ifdef ALLOW_ADMTLM_RUN
134			CALL DSVD(myThid)
135			#else
136	cnh	1.1	CALL THE_MODEL_MAIN(myThid)
137	heimbach	1.10	#endif
138	cnh	1.1	ENDIF
139
140			C-- Each threads sets flag indicating it is done
141			threadIsComplete(myThid) = .TRUE.
142			IF ( .NOT. eeBootError ) THEN
143			_BARRIER
144			ENDIF
145			ENDDO
146			#include "MAIN_PDIRECTIVES2.h"
147
148			999 CONTINUE
149			C-- Shut down execution environment
150			CALL EEDIE
151
152			C-- Write closedown status
153			IF ( fatalError ) THEN
154			STOP 'ABNORMAL END: PROGRAM MAIN'
155			ELSE
156			STOP 'NORMAL END'
157			ENDIF
158			C
159			END