eesupp/src/main.F

C $Header: /u/gcmpack/MITgcm/eesupp/src/main.F,v 1.14 2004/08/29 17:13:24 edhill 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: 
C     Wrapper synopsis and code Routines in the subdirectories under
C     eesupp/ ( src/ and inc/ ) provide the core framework within which
C     numerical and ancilliary software of MITgcm operates.  The eesupp/
C     directories provide a collection of software we call {\bf WRAPPER}
C     ( ({\bf W}rappable {\bf A}pplication {\bf P}aralell {\bf
C     P}rogramming {\bf E}nvironment {\bf R}esource).  The {bf WRAPPER}
C     provides a generic bootstrapping capability to start applications
C     in a manner that allows them to exploit single and
C     multi-processing environments on all present day hardware
C     platforms (spanning vector SMP systems to distributed memory and
C     processing cluster systems). Numerical applications must be coded
C     to fit within the {\bf WRAPPER}. This entails applications
C     adopting a particular style for declaring data structures
C     representing grids and values on grids. The {\bf WRAPPER}
C     currently provides support for grid point models using a single
C     global indexing system. This is sufficient for latitude-logitude,
C     cylindrical, and cartesian coordinate configurations. There is
C     also limited support for composing grids in which no single,
C     sructured global index can be defined. At present, this support is
C     limited to specific configurations of projections of a cube onto
C     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
C       creation/management of multiple threads and/or processes
C     \item communication and synchronisatioin operations between
C       multiple processes and/or threads
C     \item multi-process input and output operations to disk and to
C       other applications
C     \end{itemize}
C
C     Multi-process execution assumes the existence of MPI for process
C     startup and termination. However, MPI does not have to be used for
C     performance critical operations. Instead, {\bf WRAPPER}
C     performance critical parallel primitives are implemented to allow
C     them to bind to different low-level system software
C     layers. Bindings exist for using {\bf WRAPPER} with portable
C     systems such as MPI and UNIX System V IPC memory mapping, as well
C     bindings for high-performance propreitary systems such as Myrinet
C     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"

C---+----1----+----2----+----3----+----4----+----5----+----6----+----7-|--+----|
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

#ifdef HAVE_PTHREADS
C      IF (usePTHREADS) THEN
        CALL PTINIT(nThreads)
C      ELSE
#else

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
         CALL ADMTLM_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"

#endif  /*  HAVE_PTHREADS  */

  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


C---+----1----+----2----+----3----+----4----+----5----+----6----+----7-|--+----|

CBOP 0
C     !ROUTINE: PTREENTRY
      
C     !INTERFACE:
      SUBROUTINE PTREENTRY( 
     I     myThid )

C     !DESCRIPTION:
C     Re-entry point for a pthreads-based threading mechanism.  The
C     intent is to produce a threading hack that will work with gcc/g77.
      
C     !USES:
      implicit none
#include "SIZE.h"
#include "EEPARAMS.h"
#include "EESUPPORT.h"
#include "THE_MODEL_COMMON_BLOCKS.h"

C     !INPUT PARAMETERS:
      integer myThid
CEOP

      write(*,*) 'myThid = ', myThid
      CALL CHECK_THREADS( myThid )

C     CALL THE_MODEL_MAIN(myThid)

      threadIsComplete(myThid) = .TRUE.

      RETURN
      END

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