Home

OASIS3 User Guide prism 2-5

1. 4 6 Sending and receiving actions 4 6 1 Sending a coupling field 4 6 2 Receiving a coupling field 46 3 Auxiliary routines p os a ee sure a Mon pen ee et es tot oe We ee AT SVerimimawons o 6 05 ee ete he see a cg ah ee DL alertes he ad 4 8 Coupling algorithms SEQ and LAG concepts 4 8 1 Fhelas concept 2 12 Gosek dh adn Ag ete de gk ok eet Ad tb D 2 Le 4 8 2 The seguente concept aaa 8 2 ec ar ea be ee ae Bae ae LE 4 8 3 A mix of lag and sequence the sequential coupled model 4 8 4 Mixing sequential and parallel runs using prism put restart proto The OASIS3 configuration file namcouple 5 1 An example of a simple namcouple 2 a 5 2 First section of namcouple file 5 3 Second section of namcouple file 5 3 1 Second section of namcouple for EXPORTED AUXILARY and EXPOUT fields 5 3 2 Second section of namcouple for IGNORED IGNOUT and OUTPUT fields 5 3 3 Second section of namcouple for INPUT fields The transformations and interpolations in OASIS3 6 1 Using OASIS3 in the interpolator only mode 6 2 The time transformations 6 3 The pre processing transformations 6 4 The nterpolation seai
2. var id INTEGER IN field ID from corresponding prism_def_var_proto 14 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY date INTEGER IN number of seconds in the run at the beginning of the timestep info INTEGER OUT returned info code This routine may be called at any time to inquire what would happen to the corresponding field i e with same var id and at same date below the corresponding prism put proto The possible value of the returned info code are as for prism put proto e PRISM_Sent 4 if the field would be sent to another model directly or via OASIS3 main process e PRISM_LocTrans 5 if the field would be only used in a time transformation not sent not output e PRISM _ToRest 6 if the field would be written to a restart file only e PRISM_Output 7 if the field would be written to an output file only e PRISM SentOut 8 if the field would be both written to an output file and sent to another model directly or via OASIS3 main process e PRISM_ToRestOut 9 if the field would be written both to a restart file and to an output file e PRISM_Ok 0 otherwise and no error occurred This is useful when the calculation of the corresponding field array is CPU consuming and should be avoided if the field is not effectively used below the prism put proto e CALL prism but restart proto var id date lerror var id INTEGER IN field ID from corresponding prism_def_var_
3. was changed for include lt netcdf inc gt B 2 Changes between oasis3 prism _2_4 andoasis3 prism 2 3 The changes between versions tagged oasis3 prism 2 4 and oasis3 prism 23 delivered in July 2004 are the following e Update of compiling and running environments with version prism 2 4 of PRISM Standard Com piling Environment SCE and PRISM Standard Running Environment SRE which among other improvements include the environments to compile and run on the CRAY X1 see the directories with lt node gt balticl thanks to Charles Henriet from CRAY France and on a Linux station from Recherche en Pr vision Num rique Environnement Canada Dorval Canada see the direc tories with lt node gt armc28 e prism src mod o as is3 s rc ini iof F the opening of the coupling restart files is done only if the corresponding field has a lag greater than 0 note that this implies that all fields in mode NONE must now have a lag greater than 0 e g LAG 1 thanks to Veronika Gayler from M amp D B 3 APPENDIX B CHANGES BETWEEN VERSIONS prism src lib p smile s rc p ri sm def var proto F contrary to what was previously described in the documentation PRISM Double is not supported as 7 argument to describe the field type PRISM Real must be given for single or double precision real arrays prism src mod o as is3 s rc i ni par F 90 For upward compatibility of SCRIPR inter polation VECTOR is still accepted i
4. For IGNORED fields the name used in the coupling restart file if any must be the target symbolic name The third line is LOCTRANS if this transformation is chosen for the field Note that LOCTRANS is the only transformation supported for IGNORED IGNOUT and OUTPUT fields as it is performed directly in the PSMILe below the prism put proto call If LOCTRANS is chosen a fourth line giving the name of the time transformation is required For more detail on LOCTRANS see section 6 2 CHAPTER 5 THE OASIS3 CONFIGURATION FILE NAMCOUPLE 5 3 3 Second section of namcouple for INPUT fields The first and only line for fields with status INPUT is SOALBEDO SOALBEDO 17 86400 0 SOALBEDO nc INPUT e SOALBEDO symbolic name for the field in the target model CHARACTER 8 repeated twice e 17 index in auxiliary file cf_name_table txt see above for EXPORTED fields e 86400 input period in seconds e 0 number of transformations always 0 for INPUT fields e SOALBEDO nc CHARACTER 32 giving the input file name for more detail on its format see section 7 4 e INPUT field status Chapter 6 The transformations and interpolations in OASIS3 Different transformations and 2D interpolations are available in OASIS3 to adapt the coupling fields from a source model grid to a target model grid They are divided into five general classes that have precedence one over the other in the following order time transformation with CLIM MPI1 MPI2 and PSMILe
5. 2 cos 16 F represents a global dipole reaching its maximum and minimum values at the equator respectively at the date line and at the Greenwich meridian F2 represents two dipoles reaching respectively their maximum and minimum values at the equator respectively at the date line and at 90 W and at the Greenwich meridian and at 90 E it is similar to a spherical harmonic with 2 and m 2 where is the sherical 8 3 RUNNING OASIS3 IN INTERPOLATOR ONLY MODE harmonic order and m is the azimuthal wave number F3 represents a series of dipoles centered at 45 N and 45 S it is similar to a spherical harmonic with 32 and m 16 and is useful for testing interpolation of fields with relatively high spatial frequency and rapidly changing gradients The exchange of Field2 from toyoce to toyatm and Fields Fieldg Field7 Fieldg and Fieldg from toyatm to toyoce follow exactly the same logic as for Fieldi Fields as a status INPUT in the namcouple Field3 will therefore not be exchanged between two models but will be read from a file automatically below the target model toyoce prism_get calls at the user defined frequency in the input file also specified in the namcouple SOALBEDO nc Fields as a status of OUTPUT in the namcouple It will therefore be only automatically written to a file at the user defined frequency below the source model toyatm prism_put calls The name of the file will be automatically composed of the field symb
6. an auxiliary field on the fine coarse grid e g the albedo The whole operation is interpolated from the coarse grid with a grid mapping type of interpolation the dataset of weights and addresses has to be given by the user For non solar type of field SSUBTYPE NONSOLAR _ a first order Taylor expansion of the field on the fine grid relatively to a state variable is performed for instance an expansion of the total heat flux relatively to the SST OF F oh T where F is the heat flux on the fine coarse grid T T an auxiliary field on the fine coarse grid e g the SST and a the derivative of the flux versus the auxiliary field on the coarse grid This operation is interpolated from the coarse grid with a grid mapping type of interpolation the dataset of weights and addresses has to be given by the user This analysis requires one input line with 7 or 8 arguments depending on the type of subgrid inter polation 1 If the the SUBGRID operation is performed on a solar flux the 7 argument input line is SUBGRID operation with SSUBTYPE SOLAR SCFILE SNUMLU SNID SNV SSUBIYPE SCCOARSE SCFINE SCFILE and SNUMLU are the subgrid mapping file name and associated logical unit see sec tion 7 5 for the structure of this file SNID the identificator for this subgrid mapping dataset within the file build by OASIS based on all the different SUBGRID analyses in the present coupling SNV is the maximum number of target gr
7. pling software is refered to as the TOYCLIM coupled model the TOYCLIM coupling is realistic as the coupling algorithm linking the toy component models the size and the grid of the 2D coupling fields and the operations performed by OASIS3 on the coupling fields are realistic The current version of OASIS3 and its TOYCLIM example coupled model was successfully compiled and run on NEC SX6 IBM Power4 and Linux PC DELL and previous versions were compiled and run on many other platforms Compiling OASIS3 and TOYCLIM was described in section 8 1 In the following section the TOYCLIM example coupled model is first described in more detail see section 8 2 1 then instructions on how to run TOYCLIM are given in section 8 2 2 8 2 1 TOYCLIM description The toyoce model The toyoce model which sources can be found in prism src mod t oy oce s rc has a 2D logically rectangular streched and rotated grid of 182x152 points which corresponds to a real ocean model grid the pole of convergence is shifted over Asia Toyoce timestep is 14400 seconds it performs therefore 36 timesteps per 6 day run OASIS3 PRISM System Model Interface PSMILe routines are detailed in section 4 At the beginning of a run toyoce performs appropriate PSMILe calls to initialize the coupling define its grids and declare its T O or coupling fields As toyoce is not parallel it calls the PSMILe prism def_partition routine to define only one Serial partition containing th
8. ACCUMUL the field accumulated over the previous coupling period is transferred AVERAGE _ the field averaged over the previous coupling period is transferred T_MIN the minimum value of the field for each source grid point over the previous coupling period is transferred T_MAX the maximum value of the field for each source grid point over the previous coupling period is transferred ONCE only one prism put proto orprism get proto will be performed this is equivalent to giving the length of the run as coupling or I O period The pre processing transformations The following transformations are available in the pre processing part of OASIS3 controlled by preproc f REDGLO This transformation is obsolete in the current OASIS version as interpolations for Gaussian Reduced grid now exist this transformation should not be used anymore REDGLO routine redglo f performs the interpolation from a Reduced grid to a Gaussian one The interpolation is linear and performed latitude circle per latitude circle When present REDGLO must be the first pre processing transformation performed The configuring line is as follows REDGLO operation SNNBRLAT SCDMSK where xxx is half the number of latitude circles of the Gaussian grid For example for a T42 with 64 latitude circles SNNBRLAT is NO32 In the current version it can be either NO16 NO24 NO32 NO48 NO80 NO160 SCDMSK is a flag indicating if non masked values have to b
9. INTEGER DIMENSION 2 IN varnodims 1 is the rank of field ar ray 1 or 2 var_nodims 2 is the number of bundles always 1 for OASIS3 12 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY kinout INTEGER IN PRISM In for fields received by the model or PRISM Out for fields sent by the model var _actual shape INTEGER DIMENSION 2 var nodims 1 IN vector of integers giving the minimum and maximum index for each dimension of the coupling field ar ray for OASIS3 the minimum index has to be 1 and the maximum index has to be the extent of the dimension var type INTEGER IN type of coupling field array put PRISM Real for single or double precision real arrays No automatic conversion is implemented therefore all coupling fields exchanged through OASIS3 main process must be of same type ierror INTEGER OUT returned error code 4 5 End of definition phase Each process implied in the coupling closes the definition phase e CALL prism enddef proto ierror ierror INTEGER OUT returned error code 4 6 Sending and receiving actions 4 6 1 Sending a coupling fi eld In the model time stepping loop each process implied in the coupling sends its part of the I O or coupling field e USE mod prism put proto Module to be used by the component model to call prism put proto e CALL prism put proto var id date field array info var _id INTEGER IN field ID from corr
10. def var proto in section 4 4 1 index in auxiliary file cf_name _table txt used by OASIS3 and PSMILe to identify corre sponding CF standard name and units see 7 1 86400 coupling and or I O period for the field in seconds If SCHANNEL is NONE put 1 5 number of transformations to be performed on this field 5 3 SECOND SECTION OF NAMCOUPLE FILE sstoc nc name of the coupling restart file for the field CHARACTER 8 it may be a binary of netCDF file for more detail see section 7 3 sstat nc name of the field output file may be indicated for NONE and PIPE communication techniques only It may be a binary of netCDF file see section 7 3 EXPORTED field status e Field second line 182 number of points for the source grid first dimension optional if a netCDF coupling restart file is used 149 number of points for the source grid second dimension optional if a netCDF coupling restart file is used 128 number of points for the target grid first dimension optional if a netCDF coupling restart file is used 64 number of points for the target grid second dimension optional if a netCDF coupling restart file is used toce prefix of the source grid name in grid data files see section 7 2 CHARACTER 4 atmo prefix of the target grid name in grid data files CHARACTER 4 LAG 14400 optional lag index for the field expressed in se
11. it is important to indicate a sequence index In fact at each OASIS3 main process coupling timestep Fy is necessarily treated after F2 There fore SEQ F 2 and SEQ F2 1 4 8 4 Mixing sequential and parallel runs using prism put restart proto In the example illustrated on figure 4 8 the models run sequentially for the first run only and then run simultaneously For the first run the LAG and SEQ indices must be defined as in section 4 8 3 After the first run the situation is similar to the one of section 4 8 1 and positive LAG must be defined for F and F gt As their lag is positive their corresponding first prism get proto will automatically lead to reading F and F gt from coupling restart files In this case model A has to write F to its restart file explicitly by calling prism put restart proto illustrated on the figure by an orange arrow at the end of the first run in fact F lag being then negative such writing is not automatically done below the last prism put proto of the first run Chapter 5 The OASIS3 confi guration fi le namcouple The OASIS3 configuration file namcouple contains below pre defined keywords all user s defined infor mation necessary to configure a particular coupled run The namcouple is a text file with the following characteristics e the keywords used to separate the information can appear in any order e the number of blanks between two character strings is non significant e all lin
12. only pre processing interpolation cooking and post processing This order of precedence is concep tually logical but is also constrained by the OASIS3 software internal structure In the following paragraphs it is first described how to use OASIS3 in an interpolator only mode Then a description of each transformation with its corresponding configuring lines is given 6 1 Using OASIS3 in the interpolator only mode OASIS3 can be used in an interpolator only mode in which case it transforms fields without running any model It is recommended to use first OASIS3 in this mode to test different transformations and interpola tions without having to run the whole coupled system In the interpolator only mode all transformations except the time transformations are available To run OASIS3 in an interpolator only mode the user has to prepare the namcouple as indicated in sections 5 2 and 5 3 In particular NONE has to be chosen below the keyword SCHANNEL 0 without any model name and Fortran unit number must be given below the keyword SNBMODEL S RUNTIME has to be the number of time occurrences of the field to interpolate from the NetCDF input file finally the coupling period of the field 4th entry on the field first line must be always 1 Note that if SRUNTIME is smaller than the total number of time ocurrences in the input file the first SRUNTIME occurrences will be interpolated The name of the input file
13. 4 is the number of corners in the counterclockwize sense The names of the arrays must be composed of the grid prefix and the suffix clo or cla for respectively the grid corner longitudes or lati tudes As for the other grid information the corners can be provided in grids nc before the run by the user or directly by the model through PSMILe specific calls see section 4 2 furthermore for Logically Rectangular LR source grids only the grid corners will be automatically calculated if they 41 CHAPTER 7 OASIS3 AUXILIARY DATA FILES are not available in grids nc if needed the corresponding reverse remapping can be done in which the current target grid become the source grid Longitudes must be given in degrees East in the interval 360 0 to 720 0 Latitudes must be given in degrees North in the interval 90 0 to 90 0 Note that if some grid points overlap it is recommended to define those points with the same number e g 360 0 for both not 450 0 for one and 90 0 for the other to ensure automatic detection of overlap by OASIS Note also that cells larger than 180 0 degrees in longitude are not supported If vector fields are defined on a grid which has a local coordinate system not oriented in the usual zonal and meridional directions the local angle of the grid coordinate system must be given in grids nc file in an array which name must be composed of the grid prefix and the suffix ang The angle is defined as the
14. AUX ILARY or EXPOUT see section 5 in a given order at each coupling timestep a sequence index SEQ must be defined for each of them This is not required for I O fields or for coupling fields exchanged directly between the component models i e with status IGNOUT INPUT or OUTPUT SEQ gives the position of the coupling field in the sequence A coupling algorithm showing the SEQ concept is illustrated on figure 4 6 All coupling field produced by the source model at the coupling timestep can be consumed by the target model at the same timestep without causing any deadlock situation therefore LAG 0 for all coupling fields However at each coupling timestep a particular order of exchange must be respected F must be received by model A before it can send F2 which in turn must be received by model B before it can send F3 Therefore SEQ 1 2 3 must be defined respectively for F1 F2 and F3 As all fields can be consumed at the time they are produced LAG 0 for all fields there no reading writing from to coupling restart files 4 8 3 A mix of lag and sequence the sequential coupled model One can run the same component models simultaneously or sequentially by defining the appropriate LAG and SEQ indices In the example illustrated on figure 4 7 the models perform their prism put proto and prism get proto calls exactly as in the first lag example above model A receives Fa and then sends F its timestep length is 4 During a coupl
15. With 0 there is practically no output written to the cplout with 1 only some general information on the run the header of the main routines and the names of the fields when treated appear in the cplout Finally with 2 the full output is generated e SCALTYPE This new keyword gives the type of calendar used For now the calendar type is im portant only if FILLING analysis is used for a coupling field in the run and for printing information in OASIS3 log file cplout Below this keyword a number 0 1 or n must be indicated by the user 0 a 365 day calendar no leap year 1 a 365 or 366 leap years day calendar A year is a leap year if it can be divided by 4 however if it can be divided by 4 and 100 it is not a leap year furthermore if it can be divided by 4 100 and 400 it is a leap year n n gt 1 day month calendar from the MPI buffer in this routine See the example in the toyatm model in prism src mod toyatm sre 2With MPI1 models have to be started by the user in a pseudo MPMD mode in the order they are introduced in the nam couple The way to do this depends on the computing platform With MPI1 OASIS3 main process and the component models automatically share the same MPI_COMM_WORLD communicator in this communicator OASIS3 main process is assumed to have rank 0 and the other component models are assumed to have ranks in the order of which they are introduced in namcouple If this is not the case a deadlock ma
16. grid on which FILLING is performed e NLU _fil is the logical unit associated to the global data file and is defined in the input file nam couple Note that the first month needs not to be a january This is the only file within OASIS in which the fields are not read using a locator 7 5 3 Auxiliary data files for SCRIPR The NetCDF files containing the weights and addresses for the SCRIPR remappings see section 6 4 are automatically generated at runtime by OASIS3 Their structure is described in detail in section 2 2 3 of the SCRIP documentation available in prism src mod oa sis3 doc SCRIPusers pdf Chapter 8 Compiling and running OASIS3 8 1 Compiling OASIS3 and TOYCLIM Compiling OASIS3 and TOYCLIM see section 8 2 1 can be done using the top makefile TopMakefileOasi s3 and platform dependent header files as described in section 8 1 1 Note OASIS3 is temporarily released without the corresponding PRISM Standard Compile Environment and Running Environment SCE SRE they will be included when the migration from CVS to Subversion will be realized in CERFACS During compilation a new directory branch is created prism arch where arch is the name of the com piling platform architecture e g Linux After successful compilation resulting executables are found in prism arch bin libraries in prism arch lib and object and module files in prism arch build The different pre compiling flags used for OASIS3 and its associated PSMILe lib
17. if routine prism src lib s cr ip sr c re ma p gauswgt f is compiled with 11 nnei true the non masked nearest neighbour is used for target point if all original neighbours are masked see section 6 4 For SCRIPR BICUBIC routine prism src lib s cri p sr c remap bicubic f the convergence criteria was modified so to ensure convergence even in single precision For SCRIPR CONSERV routine prism src lib s cri p sr c remap conserv f a test was added for non convex cell so that integration does not stall The routine prism src lib sc ri p sr c c or ners F was modified so to abort if it is called for the target grid as the automatic calculation of corners works only for Logically 56 B 2 CHANGES BETWEEN OASIS3 PRISM 2 4 AND OASIS3 PRISM 2 3 Rectangular LR grids and as the target grid type is unknown If needed the reverse remap ping in which the current target grid become the source grid can be done e Other important modifications Anew PSMILe routine prism src lib ps mil e sr c pr ism get freq F was added this routine can be used to retrieve the coupling period of field see section 4 6 3 The routines of the mpp io library in prism src lib m pp io changed name and were merged with the OASIS4 mpp io library Routine prism src mod oa si s3 s rc e xtr ap F was modified to ensure that the ex trapolation works even if the MASK value is very big thanks to J M Epitalon In the namco
18. local offset 10 local size 4 local size 6 local size 5 Figure 4 1 Apple partition 10 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY HE TT goba x extent 5 Proc 1 Proc 2 Proc 3 local offset 0 local offset 2 local offset 10 local x extent 2 local x extent 3 local x extent 5 local y extent 2 local y extent 2 local y extent 1 Figure 4 2 Box partition e ig paral l 2 indicates a Box partition e ig paral 2 the upper left corner global offset e ig paral 3 the local extent in X e ig paral 4 the local extent in Y e ig paral 5 the global extent in X Figure 4 2 illustrates a Box partition over 3 processes 4 3 4 Orange partition Each partition is an ensemble of segments of the global domain Each segment is described by its global offset and its local extent In this case we have ig paral 1 N where N 2 2 number of segments e ig paral l 3 indicates a Orange partition e ig paral 2 the total number of segments for the partition limited to 200 presently see note for ig_paral 4 for Box partition above e ig paral 3 the first segment global offset The maximum value of the local extent in Y is presently 338 it can be increased by mod ifying the valu
19. messages to cplout file and by the PSMILe to produce CF compliant NetCDF files 72 Grid data files The grids of the models being coupled must be given by the user or directly by the model through PSMILe specific calls see section 4 2 in grid data files These files can be all binary or all NetCDF In prism data toy clim input toyclim standard standard prism 2 2 tar gz Net CDF examples can be found The arrays containing the grid information are dimensioned nx ny where nx and ny are the grid first and second dimension except for Unstructured U and Reduced D grid for which the arrays are dimensioned nbr pts 1 where nbr pts is the total number of grid points 1 grids or grids nc contains the model grid longitudes latitudes and local angles if any in single or double precision REAL arrays depending on OASIS3 compilation options The array names must be composed of a prefix 4 characters given by the user in the namcouple on the second line of each field see section 5 3 and of a suffix 4 characters this suffix is lon or lat for respectively the grid point longitudes or latitudes see prism src mod oa sis3 sre mod _label F90 For SCRIPR interpolations the grid data files must be NetCDF files If the SCRIPR CONSERV remapping is used longitudes and latitudes for the source and target grid corners must also be available in the grids nc file as arrays dimensioned nx ny 4 or nbr pts 1 4 where
20. note that those modifications should not bring any difference in the interpolation results except for SCRIPR DISTWGT see below e Bug corrections In prism src lib s cr ip s rc sc ri pr mp F initialisation of dst array bug fix announced to the mailing list diff oasis cerfacs fr on 02 02 2006 Inprism src lib p smile s rc p ri sm enddef proto F andprism src lib clim src CLIM Start MPI F the call to MPI barrier that created a deadlock when not all processes of a component model were exchanging data with the coupler was changed for a call to MPI_wait on the previous MPI_Isend bug fix announced to the mailing list diff oasis cerfacs fr on 02 23 2006 For SCRIPR DISTWGT in prism src lib sc ri p s rc remap distwgt f line 190 was repeated without epsilon modification bug fix announced to the mailing list diff oasis cerfacs fr on 03 21 2006 In prism src lib p smile src mod prism put proto F90 for prism put proto r28 and prism put proto r24 the reshape of the 2d field was moved after the test checking if the field is defined in the namcouple thanks to Arnaud Caubel from LSCE e Modification in SCRIP interpolations For SCRIPR interpolations see section 6 4 the value 1 0E 20 is assigned to target grid points for which no value has been calculated if prism src lib scrip sre scriprmp f or vector F90 for vector interpolation are compiled with 11 weightot true For SCRIPR GAUSWGT
21. pseudo MPMD mode the way to do this depends on the computing platform For more details see section 4 2 Grid data file defi nition The grid data files grids nc masks nc and areas nc must be created by the user before the run or can be written directly at run time by the master process of each component model If written by the component models the writing of those grid files is driven by OASIS3 main process It first checks whether the binary file grids or the netCDF file grids nc exists in that case it is assumed that areas or areas nc and masks or masks nc files exist too or if writing is needed If grids or grids nc exists it must contain all grid information from all models if it does not exist each model must write its grid definition in the grid data files The coupler sends the information on whether or not writing is needed to the models following an OA SIS internal order below prism start_grids_writing If no writing is needed nothing happens when calling the following prism_write_xxxx routines If writing is needed the first model creates the files writes the data arrays with prism write grid prism write corner prism write mask prism write area calls and then sends a termination flag to the coupler below gt The model may call MPI_Init explicitly but if so has to call it before calling prism init comp proto in this case the model also has to call MPI_Finalize explicitly but only after calling prism t
22. which contains the fields to interpolate is given by the 6th entry on the field first line see 5 3 After their transformation OASIS3 writes them to their output file which name is the 7th entry on the first line Note that all fields have to be present in the same restart file The time variable in the input file if any is recognized by the its attribute units The acceptable units for time are listed in the udunits dat file 3 This follows the CF convention To compile OASIS3 in interpolator only mode see section 8 1 1 Practical examples on how to use OA SIS3 in a interpolator only mode are given in prism util runn in g to ymo de 1 te st int erp see also section 8 3 1 and prism util runn ing t oy mo de 1 t es tN ONE see also section 8 3 2 The configuring parameters that have to be defined in the namcouple for each transformation in the interpolator only mode or in the coupling mode are described here after lFor binary input file only one time occurence may be interpolated 29 6 2 CHAPTER 6 THE TRANSFORMATIONS AND INTERPOLATIONS IN OASIS3 The time transformations LOCTRANS can be chosen as first transformation if CLIM MPI1 MPI2 communication and the PSMILe interface are used LOCTRANS requires one configuring line on which a time transformation automati cally performed below the call to PSMILe prism put proto should be indicated 6 3 INSTANT no time transformation the instantaneous field is transferred
23. 1 1 Field9 Field2 1 Finally at the end of the run toyatm performs the PSMILe finalization call The toyche model Toyche which sources can be found in prism src mod to yc he s rc is integrated on the same atmospheric model grid than toyatm Its timestep is 7200 seconds it therefore performs 72 timesteps per 6 day run As the other toymodels toyche performs at the beginning of a run appropriate PSMILe calls to initialize the coupling define its grids and declare its I O or coupling variables it also retrieves a local commu nicator if needed As toyche has the same grid than toyatm a direct exchange of coupling fields can occur between those two models without going through OASIS3 interpolation process To insure this the coupling field must have a field status IGNORED or IGNOUT in the OASIS3 configuration file namcouple see section 5 3 and the two models must have also the same parallel decomposition Toyche decomposition is hardcoded the same way than toyatm and if the user modifies the toyatm decomposition he has to modify the toyche decomposition the same way by changing toyche values for il nbcplproc and cdec see above for toyatm At the beginning of its timestep toyche calls the PSMILe prism_get routine to request Field10 see table 8 1 At the end of its timestep toyche calls PSMILe prism_put routine to send Field11 As toyche contains no real physics or dynamics it defines a simple feed back between Fi
24. 3 main process e direct communication between two parallel component models when no transformations and no repartitioning are required e automatic sending and receiving actions at appropriate times following user s choice indicated in the namcouple e time integration or accumulation of the coupling fields e I O actions from to files To adapt a component model to PSMILe specific calls of the following classes have to be implemented in the code 1 Initialisation section 4 1 Grid data file definition section 4 2 Partition definition section 4 3 I O coupling field declaration section 4 4 End of definition phase section 4 5 NM BW WN I O coupling field sending and receiving section 4 6 7 Termination section 4 7 Finally in section 4 8 different coupling algorithms are illustrated and explanations are given on how to reproduce them with PSMILe by defining the appropriate indices of lag and sequence for each coupling field The SIPC PIPE and GMEM communication techniques available in previous versions should still work but are not main tained anymore and were not tested 6 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY 4 1 Initialisation All processes of the component model initialise the coupling and if required retrieve a local communica tor for the component model internal parallelisation e USE mod prism proto Module to be used by the component models e CALL prism init comp proto comp
25. 61 61 61 62 Chapter 1 Acknowledgements We would like to thank the main past or present developers of OASIS are in alphabetical order with the name of their institution at the time Arnaud Caubel FECIT Fujitsu Damien Declat CERFACS Veronika Gayler MPI M amp D Josefine Ghattas CERFACS Jean Latour Fujitsu Fecit Eric Maisonnave CERFACS Elodie Rapaport CERFACS Hubert Ritzdorf CCRLE NEC Sami Saarinen ECM WF Eric Sevault M t o France Laurent Terray CERFACS Olivier Thual CERFACS Sophie Valcke CERFACS Reiner Vogelsang SGI Germany We also would like to thank the following people for their help and suggestions in the design of the OASIS software in alphabetical order with the name of their institution at the time Dominique Astruc IMFT Sophie Belamari M t o France Dominique Bielli M t o France Gilles Bourhis IDRIS Pascale Braconnot IPSL LSCE Christophe Cassou CERFACS Yves Chartier RPN Jalel Chergui IDRIS Philippe Courtier M t o France Philippe Dandin M t o France Michel D qu M t o France Ralph Doescher SMHI Jean Louis Dufresne LMD Jean Marie Epitalon CERFACS Laurent Fairhead LMD Marie Alice Foujols IPSL Gilles Garric CERFACS Eric Guilyardi CERFACS Charles Henriet CRAY France Pierre Herchuelz ACCRI Maurice Imbard M t o France Luis Kornblueh MPI M Stephanie Legutke MPI M amp D Claire L vy LODYC Olivier Marti PSL LSCE Claude Me
26. A and model B receiving actions which means that a lag of 6 must be defined for both F1 and Fy For both coupling fields the prism put proto performed at times 6 and 18 by the source model then lead to sending actions as 6 6 12 and 18 6 24 which are coupling periods that match the receiving action performed at time 12 and 24 below the prism get proto called by the target model For F3 sent by model A and received by model B no lag needs to be defined the coupling field produced by model A at the coupling timestep can be consumed by model B without causing a deadlock situation As in the first example the prism get proto performed at the beginning of the run for Fi and F gt automatically read them from their coupling restart files and the last prism put proto performed at the end of the run automatically write them to their coupling restart file For F3 no coupling restart file is needed nor used as at each coupling period the coupling field produced by model A can be directly consumed by model B We see here how the introduction of appropriate LAG indices results in receiving below the prism get proto inthe target model coupling fields produced below the prism put proto by the source model the timestep before this is in some coupling configurations essential to avoid deadlock situations 4 8 2 The sequence concept To exchange the coupling fields going through OASIS3 main process i e with status EXPORTED
27. ATA FILES e clweight is the locator of the weight dataset e iadress i j is the address on the source grid of the 7 neighbor used for the mapping of the j target grid point The address is the index of a grid point within the total number of grid points e weight i j is the weight affected to the neighbor used for the transformation of the 7 target grid point For file nweights there is an additional brick composed of a CHARACTER 8 variable formed by the characters INCREME and by the data set identificator and of an INTEGER array N which is the iteration number within EXTRAP NINENN at which the extrapolation of the n grid point is effectively performed 7 5 2 Auxiliary data files for FILLING For the FILLING analysis the global data set used can be either interannual monthly climatological monthly or yearly see 6 4 The name of the global data file can be chosen by the user and has to be indicated in the namcouple have to be given to OASIS through the input file namcouple In case of monthly data the file must be written in the following way REAL field_january_y ear_01 jpi jpj WRITE NLU_fil field_january_ye ar_01 WRITE NLU_fil field_february_y ear_01 WRITE NLU_fil field_march_year _01 etc WRITE NLU_fil field_december_y ear_0l C if climatology one stops here WRITE NLU_fil field_january_ye ar 02 etc where e field _ is the global dataset e jpi and jpj are the dimensions of the
28. D 1 1 argl 22 5 1 AN EXAMPLE OF A SIMPLE NAMCOUPLE 3 1 arg2 3 1 arg3 SNFIELDS 4 SJOBNAME JOB SNBMODEL 3 ocemod atmmod chemod 55 70 99 SRUNTIME 432000 SINIDATE 00010101 SMODINFO NOT SNLOGPRT 2 SCALTYPE 1 HEREHERE EEH tt tt tt tH ttt TH PE HH E EEE FE FH PE TE EEE PE PE PE PEPEE FE OPE PE EEH Second section SSTRINGS Field 1 SOSSTSST SISUTESU 1 86400 5 sstoc ne EXPORTED 182 149 128 64 toce atmo LAG 14400 SEQ 1 P 2 P 0 LOCTRANS CHECKIN MOZAIC BLASNEW CHECKOUT AVERAGE INT 1 at3ltopa 91 2 48 CONSTANT 213515 INT 1 Field 2 CONSFTOT SOHEFLDO 6 86400 ft flxat nc EXPORTED atmo toce LAG 14400 SEQ 1 P 0 P 2 LOCTRANS CHECKIN SCRIPR CHECKOUT CHAPTER 5 THE OASIS3 CONFIGURATION FILE NAMCOUPLE ACCUMUL INT 1 CONSERV LR SCALAR LATLON 10 FRACAREA FIRST INT 1 Field COSENHFL SOSENHFL 31 86400 1 flda3 nc IGNOUT atmo atmo LAG 7200 SEQ 1 LOCTRANS AVERAGE j Field 4 SOALBEDO SOALBEDO 17 86400 0 SOALBEDO nc INPUT j HEHEHEHEHE SRE HEE EE EE HEE E E E E EE PE EE EE EE PEE PE PE PE E PEE PE EE EHEH 5 2 First section of namcouple fi le The first section of namcouple uses some predefined keywords prefixed by the sign to locate the related information The sign must be in the second column The first ten keywords are described hereafter e SSEQMODE On the line below this keyword is the maximum number of fields that have to be at one particular coupling t
29. ENDING AND RECEIVING ACTIONS 13 This routine may be called by the model at each timestep The sending is actually performed only if the time obtained by adding the field lag see 4 8 to the argument date corresponds to a time at which it should be activated given the coupling or I O period indicated by the user in the namcouple see section 5 A field will not be sent at all if its coupling or I O period indicated in the namcouple is greater than the total run time If a local time transformation is indicated for the field by the user in the namcouple INSTANT AVER AGE ACCUMUL TMIN or T_MAX see section 6 it is automatically performed and the resulting field is finally sent at the coupling or I O frequency For a coupling field with a positive lag see 4 8 the OASIS3 restart file see section 7 3 is automatically written by the last prism put proto call of the run if its argument date the field lag corresponds to a coupling or I O period To force the writing of the field in its coupling restart file one can use prism put restart proto see below This routine can use the buffered MPI_BSend by default or the standard blocking send MPI Send if NOBSEND is specified in the namcouple see SCHANNEL section 5 2 to send the coupling fields 4 6 2 Receiving a coupling field In the model time stepping loop each process implied in the coupling receives its part of the I O coupling field e USE mod prism get proto Module to be u
30. H interpolation gweights weights and addresses for INTERP GAUSSIAN interpolation any name weights and addresses for MOZAIC interpolation any name weights and addresses for SUBGRID interpolation Table 7 1 Analysis auxiliary data files The files nweights mweights and gweights can be created by OASIS3 if their corresponding NIO 1 see EXTRAP NINENN INTERP SURFMESH INTERP GAUSSIAN in sections 6 3 and 6 4 The name of the sub grid mapping files for MOZAIC EXTRAP WEIGHT and SUBGRID analyses can be chosen by the user and have to be indicated in the namcouple see respectively sections 6 3 and 6 4 and 6 5 These files have to be generated by the user before starting the coupled run The structure of these files is as follows CHARACTER 8 cladress clwei ght INTEGER iadress jpnb jJ po REAL weight jpnb jpo OPEN unit 90 file at3ltopa form unformatt ed WRITE clweight WEIGHTS I1 knumb WRITE cladress RDRES SE I1 knumb WRITE 90 clweight WRITE 90 weight WRITE 90 cladress WRITE 90 iadress where e jpnb is the maximum number of neighbors used in the transformation SNVOISIN in the nam couple e jpo is the total dimension of the target grid e at3ltopa is the name of the grid mapping data file SCFILE in namcouple e knumb is the identificator of the data set SNID in namcouple e cladress is the locator of the address dataset 7 5 TRANSFORMATION AUXILIARY D
31. M Log and error messages from compilation are saved in the files COMP log and COMP err in make dir 8 1 2 CPP keys The following CPP keys are coded in OASIS3 and associated PSMILe library and can be specified in CPPDEF inmake your platform file To indicate which communication technique will be used see sections 4 1 and 5 2 use comm MPI2 by default CLIM MPI2 use comm MPI1 CLIM MPII use comm NONE no communication technique for Oasis interpolator only mode NONE The SIPC PIPE and GMEM communication techniques available in previous versions should still work but are not maintained anymore and were not tested To indicate the precision for REAL variables use _realtype double by default to exchange double precision coupling fields de clared as REAL kind SELECT ED REAL KIND 12 307 use _realtype single to exchange single precision coupling fields declared as REAL kind SELEC TE D REAL KIND 6 37 Note that if use realtype single is activated the compiling option promoting reals should be removed from F90FLAGS When linking OASIS3 and PSMILe with a netCDF library which is highly recommended the opposite case should work but was not fully tested use _netCDF Mandatory for compiling the mpp_io and psmile libraries use _LibMPI Mandatory for compiling the mpp io library if LAM implementation of MPI is used use _LAM MT For more information in log files prt during the psmile librar
32. N SCRIPR supports 2D vector interpolation Please note however that this functionality is relatively new and has been tested and validated only in a reduced number of test cases The two vector components have to be identified by replacing SCFTYP by VECTOR I or VECTOR J and have to be associated by replacing ASSCMP for each component field by the source symbolic name of the associated vector component in see above The grids of the two vector components can be different but have to have the same number of points the same overlap the same mask the same in terpolation must be used for the two components A proper example of vector interpolation is given in the interpolator only mode example see details in prism util runni ng testinte rp README testinterp _ The details of the vector treatment performed by the routines scriprmp _vector F90 and rotations F90 in prism src lib sc rip src are the following If the angles of the source grid local coordinate system are defined in the grids nc data file see section 7 2 an automatic rotation from the local to the geographic spherical coordinate system is performed If the two source vector components are not defined on the same source grid one component is automatically interpolated on the grid of the other component Ifthe user put the PROJCART keyword at the end of the SCRIPR configuring line see above projection of the two vector components in a Cartesian coordinate sys
33. NFCOAST areas for the SST filling without smoothing In this case SCMETH 1 3 SMO SCMETH 4 6 SST and the last two characters define the time characteristics of the global data file as for the SIE filling CNAME is the symbolic name for the correction term that is calculated by OASIS3 and SNUNIT the logical unit on which it is going to be written 6 5 The cooking stage The following analyses are available in the cooking part of OASIS3 controlled by cookart f e CONSERV CONSERV routine prism src mod oa si s3 s re co ns er v f performs global flux con servation The flux is integrated on both source and target grids without considering values of masked points and the residual target source is calculated Then all flux values on the target grid are uniformly modified according to their corresponding surface This analysis requires one input line with one argument 6 5 THE COOKING STAGE CONSERV operation CMETH version only global flux conservation can be performed Therefore CMETH must be GLOBAL e SUBGRID SUBGRID can be used to interpolate a field from a coarse grid to a finer target grid the target grid must be finer over the whole domain Two types of subgrid interpolation can be performed depending on the type of the field For solar type of flux field SSUBTYPE SOLAR the operation performed is z 1 Qi l a where F is the flux on the fine coarse grid a a
34. PRISM An Infrastructure Project for Climate Research in Europe OASIS3 User Guide prism_2 5 Edited by S Valcke CERFACS PRISM Support Initiative Report No 3 CERFACS TR CMGC 06 73 September 2006 Copyright Notice Copyright 2006 by CERFACS All rights reserved No parts of this document should be either reproduced or commercially used without prior agreement by CERFACS representatives How to get assistance Assistence can be obtained as listed below PRISM documentations can be downloaded from the WWW PRISM web site under the URL lt http prism enes org gt Phone Numbers and Electronic Mail Adresses Name Phone At emi Sophie Valcke 33 5 61 19 30 76 CERFACS oasishelp at cerfacs fr Contents Acknowledgements Introduction 2 1 Step by step use of OASIS3 The OASIS3 sources Interfacing a model with the PSMILe library 4 1 Initialisation 44 4 4 4 a a ee 4 2 Grid data file definition 43 Partition definitions siiu So cn Sy ee eb re ee eee dE Se eed 43 1 Serial no partition 3 see Oe ee eA ea A re a ee eS RL 432 Apple partition 55 nase anis a ao bP eae Rg a GA abs ae Sud ah a 43 3 BOX partition 45 p way en mire gest es arn deena ew Auth Bik eH 4 3 4 Orange partition 4 4 O coupling field declaration 4 5 End of definition phase
35. Ps JW ad 0 4 8 12 Model A timestep 4 Cpl_period F1 12 Cpl_period F2 12 LAG F1 8 LAG F2 6 SEQ F1 2 SEQ F2 1 Figure 4 7 Mix of LAF and SEQ concepts 108 114 116 120 prism_put_proto prism_get_proto leading to writing reading to from coupling restart file prism_put_proto prism_get_proto leading to sending receiving actions prism_put_proto prism_get_proto not leading to sending receiving actions 4 8 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS First run LAG F1 8 1 114 120 Model B 08 H4 LAG F2 6 af fp SEQ F1 2 Restart SEQ F2 1 file F2 Restart file F1 120 Model A Next runs Restart LAG F1 4 file F1 LAG F2 6 SEQ F1 1 Restart i F SEQ F2 1 file F2 1 r ra Model A A 77 120 0 8 gt prism_put_proto prism_get_proto leading p prism_put_proto prism_get_proto not to writing reading to from restart file leading to sending receiving actions prism_put_proto prism_get_proto leading gt prism_put_restart leading to writing to to sending receiving actions coupling restart file Figure 4 8 An example using prism_put_restart_proto B Fo prism put proto of the run at time 114 a writing of F to its restart file is performed as 114 LAG 6 120 is a coupling period and as the LAG is positive If the coupling fields are transformed through OASIS3 main process
36. angle between the first component and the zonal direction which is also the angle between the second component and the meridional direction In the grid file in prism data toy cl im inputtoyclim standard standard prism 2 2 tar gz the angles of the torc grid are given in array torc ang Ifoneofthe SCRIPR interpolations is requested for a vector field OASIS3 automatically performs the rotation from the local coordinate system to the geographic spherical coordinate system for a source grid or vice versa for a target grid File grids or grids nc must be present with at least the grid point longitudes and latitudes for all component model 2 masks or masks nc contains the masks for all component model grids in INTEGER arrays 0 not masked or 1 masked for each grid point The array names must be composed of the grid prefix and the suffix msk This file masks or masks nc is mandatory 3 areas or areas nc this file contains mesh surfaces for the component model grids in single or double precision REAL arrays depending on OASIS3 compilation options The array names must be composed of the grid prefix and the suffix srf The surfaces may be given in any units but they must be all the same in INTERP GAUSSIA N it is assumed that the units are m but they are used for statistics calculations only This file areas or areas nc is mandatory for CHECKIN CHECKOUT or CONSERV and used for statistic calculations in INTERP GAUSSIA N
37. aset is going to be read SNID the identificator for this grid mapping dataset in all MOZAIC grid mapping datasets in the present coupling SNV is the maximum number of target grid points use in the mapping e NOINTERP NOINTERP is the analysis that has to be chosen when no other transformation from the interpolation class is chosen There is no configuring line e FILLING FILLING routine prism src mod oas is 3 sr c fil ling f performs the blending of a regional data set with a climatological global one for a Sea Surface Temperature SST or a Sea Ice Extent field This occurs when coupling a non global ocean model with a global atmospheric model FILLING can only handle fields on Logically Rectangular grid LR but also A B G L Y and Z grids see section A The global data set has to be a set of SST given in Celsius degrees for the filling of a Sea Ice Extent field the presence or absence of ice is deduced from the value of the SST The frequency of the global set can be interannual monthly climatological monthly or yearly The blending can be smooth or abrupt If the blending is abrupt only model values are used within the model domain and only the global data set values are used outside If the blending is smooth a linear interpolation is performed between the two fields within the model domain over narrow bands along the boundaries The linear interpolation can also be performed giving a different weight to
38. b scr ip src scriprmp f or vector F90 for vector interpolation are compiled with 1l weightot true The configuring line is SCRIPR GAUSWGT SCMETH SCGRS SCFTYP SREST SNBIN SNV SVAR SASSCMP SPROJCART SCMETH GAUSWGT SVAR which must be given as a REAL value e g 2 0 and not 2 defines the weight given to a neighbour source grid point as inversely proportional to exp 1 2 d o where d is the distance between the source and target grid points and o V AR d where T is the average distance between two source grid points calculated automatically by OASIS3 BILINEAR performs bilinear interpolation BICUBIC performs a bicubic interpolation For BILINEAR and BICUBIC Logically Rectangular LR and Reduced D source grid types are supported Masked target grid points no values are calculated for masked target grid points Non masked target grid points if the some of the source grid points normally used in the bilinear or bicubic interpolation are masked another algorithm is applied at least the nearest non masked source neighbour is used The configuring line is SCRIPR BILINEA R or SCRIPR BICUBIC CHAPTER 6 THE TRANSFORMATIONS AND INTERPOLATIONS IN OASIS3 SCMETH SCGRS SCFTYP SREST SNBIN SASSCMP SPROJCART SCMETH BILINEAR or BICUBIC SCGRS is the source grid type LR or D SCFTYP SNBIN SASSCMP PROJCART are as for DISTWGT SREST is as for DISTWGT except that only LATITUDE is possible for a Reduc
39. calculation To avoid the contamination by masked source grid points transformations MASK and EXTRAP should be used Values are calculated for all target grid points masked or not The configuring line is as follows BILINEAR or BICUBIC or NNEIBOR interpolation SCMETH CGRS CFTYP SCMETH BILINEAR BICUBIC or NNEIBOR SCGRS is the source grid type A B G L Y or Z see appendix A SCFTYP the field type SCALAR or VECTOR VECTOR has an effect for target grid points located near the pole the sign of a source value located on the other side of the pole will be reversed SURFMESH routines in prism src lib an ais m is a first order conservative remap ping from a fine to a coarse grid the source grid must be finer over the whole domain and sup ports only Lat Lon grids see appendix A For a target grid cell all the underlying not masked source grid cells are found and the target grid field value is the sum of the source grid field val ues weighted by the overlapped surfaces No value is assigned to masked cells Note that it is not recommended to use this interpolation anymore as the more general SCRIPR CONSERV remapping is now available The configuring line is as follows SURFMESH remapping SCMETH SCGRS SCFTYP SNID S NV SNIO SCMETH SURFMESH SCGRS and SCFTYP areas for BILINEAR SNID is the identificator for the weight address dataset in all the different INTERP SURFMESH datasets in the present coup
40. codes il nbcplproc 1 toyatm runs on only one process and defines only one Serial 8 2 RUNNING OASIS3 IN COUPLED MODE WITH TOYCLIM partition containing the 96X48 grid points If il nbcplproc 3 toyatm runs on 3 processes and its decomposition depends on the cdec parameter hardcoded to APPLE In this case each of the 3 toyatm processes calls the PSMILe prism_def_partition routine to define 1 segment of an APPLE decomposition 1536 grid points per segment If the user changes the hardcoded value of cdec to BOX each process will define 1 box of a BOX decomposition the first two processes treat a box of 64X24 points while the third process treats a box of 128X12 points If the user hardcodes cdec ORANGE each process will define a partition of two segments of 768 points distant of 1536 points Then toyatm starts its timestep loop At the beginning of its timestep toyatm calls the PSMILe prism get routine 3 times to request the fields named Field1 Field2 and Field11 on table 8 1 At the end of its timestep toyatm calls PSMILe prism_put routine to send fields named Field4 to Field10 on table 8 1 The fields will be effectively received or sent only at the coupling frequency defined by the user see section 5 3 As toyatm contains no real physics or dynamics it defines a simple feed back between the different fields as Field5 Field1 1 Field Field2 1 Field10 Field11 1 Field4 Field1 1 Field8 Field2 1 Field6 Field
41. conds CLIM MPI1 or CLIM MPI2 communication technique only see section 4 8 Note that in mode NONE a LAG has to be defined so that the input file is opened initially SEQ 1 optional sequence index for the field CLIM MPI1 orCLIM MPI2 communication technique only see section 4 8 e Field third line P source grid first dimension characteristic P periodical R regional 2 source grid first dimension number of overlapping grid points P target grid first dimension characteristic P periodical R regional 0 target grid first dimension number of overlapping grid points The fourth line gives the list of transformations to be performed for this field There is then one or more additional configuring lines describing some parameters for each transformation These additional lines are described in more details in the section 6 5 3 2 Second section of namcouple for IGNORED IGNOUT and OUTPUT fields The first 2 lines for fields with status IGNORED or IGNOUT or OUTPUT are as follows COSENHFL SOSENEFL 37 86400 1 flda3 nc IGNOUT atmo toce LAG 7200 SEQ 1 entries are as for EXPORTED fields except that there is no output file name on the first line For OUTPUT fields there is no target model and therefore no target symbolic name the source symbolic name must be repeated twice on the field first line Also there is no coupling restart file name f1da3 nc here no LAG index and no SEQ index
42. cou pling restart file see section 4 8 If needed these files are also automatically updated by the last prism put proto call of the run see section 4 6 1 To force the writing of the field in its coupling restart file one can use the routine prism put restart proto see section 4 6 3 Warning the date is not written or read to from the restart file therefore the user has to make sure that the appropriate restart file is present in the working directory The name of the coupling restart file is given by the 6th character string on the first configuring line for each field in the namcouple see section 5 3 Coupling fields coming from different models cannot be in the same coupling restart files but for each model there can be an arbitrary number of fields written in one coupling restart file Note that in the NONE techniques output files with the same format are also created for writing the resulting field after transformation In the coupling restart files the fields must be single or double precision REAL arrays depending on PSMILe and OASIS3 compilation options and as the grid data files must be dimensioned nx ny where nx and ny are the grid first and second dimension except for fields given on Unstructured U and Reduced D grid for which the arrays are dimensioned nbr pts 1 wherenbr pts is the total number of grid points The shape and orientation of each restart field and of the corresponding coupling fields e
43. d O Thual Oasis le couplage oc an atmosph re La M t orologie 10 50 61 1995 M Pontaud L Terray E Guilyardi E Sevault D B Stephenson and O Thual Coupled ocean atmosphere modelling computing and scientific aspects In 2nd UNAM CRAY supercomputing conference Numerical simulations in the environmental and earth sciences Mexico city Mexico 1995 L Terray E Sevault E Guilyardi and O Thual OASIS 2 0 Ocean Atmosphere Seai Ice Soil User s Guide and Reference Manual Technical Report TR CGMC 95 46 CERFACS 1995 E Sevault P Noyret and L Terray Clim 1 2 user guide and reference manual Technical Report TR CGMC 95 47 CERFACS 1995 P Noyret E Sevault L Terray and O Thual Ocean atmosphere coupling Proceedings of the Fall Cray User Group CUG meeting 1994 L Terray and O Thual Coupled ocean atmosphere simulations In High Performance Computing in the Geosciences proceedings of the Les Houches Workshop F X Le Dimet Ed Kluwer Academic Publishers B V 1993 64
44. d that this Notice and any statement of authorship are reproduced on all copies Neither the Government nor the University makes any warranty express or implied or assumes any liability or responsibility for the use of this SOFTWARE If SOFTWARE is modified to produce derivative works such modified SOFTWARE should be clearly marked so as not to confuse it with the version available from Los Alamos National Laboratory 61 Appendix D The coupled models realized with OASIS Here is a list of some of the coupled models realized with OASIS within the past 5 years or so in Europe and in other institutions in the world Tab IRI USA 2 4 ECHAM4 MOM3 SGI Origin I a Ec LOPART ess U of Aus 3 0 Data atm model MOM4 SGI 03400 O lee jun BMRC AUS 3 0 BAM4 MOM4 CE A me CAS IIT India 3 0 0 MMS si IAP CAS reine Reo st SS Table D 1 List of couplings realized with OASIS within the past 5 years in institutions outside Europe The columns list the institution the country the OASIS version used the atmospheric model the ocean model and the computing platform used for the coupled model run 62 3 0 LMDz 96x71x19 ORCH INCA LMDz 96x71x19 LMDz 72x45x19 2 4 LMDZ 120X90X1 2 4 LMDZ 120X90X1 ORCA2 182x149x31 LIM ORCA2 182x149x31 ORCA4 92x76x31 OPA ATL3 1 3 deg OPA ATLI 1 deg SX6 VPP5000 VPP5000 Lodyc ISAO ECHAM4 T30 T42 L14 ORCA2 182x149x31 SX4 SX5 ORCA2 OPA med 1 8e OPA 8 1 Gela
45. documentation util Utilities to compile OASIS3 toyatm TOYCLIM component odel 1 toyoce TOYCLIM component odel 2 toyche TOYCLIM component odel 3 prism util run ni ng t est in te rp environment to test OASIS3 interpolation testNONE interpolator o nly mode NONE toyclim environment to run the TOYCLIM toymodel Chapter 4 Interfacing a model with the PSMILe library At run time OASIS3 acts as a separate mono process executable which drives the coupled run interpolates and transforms the coupling fields To communicate with OASIS3 or directly between the component models different communication techniques have been historically developed The technique used for one particular run is defined by the user in the configuration file namcouple see section 5 In OASIS3 the CLIM communication technique based on MPI1 or MPI2 message passing and the associated model interface library PSMILe should be used For a practical toy model using the PSMILe library see the sources in prism src mod toyatm toyche toyoce and more details in chapter 8 To communicate with OASIS3 or directly with another component model using the CLIM MPI1 2 com munication technique or to perform I O actions a component model needs to be interfaced with the PRISM System Model Interface library PSMILe which sources can be found in prism src lib p smile directory PSMILe supports e parallel communication between a parallel component model and OASIS
46. e cplout is now defined in an additional auxiliary file cf_name _table txt not in inipar F anymore This auxiliary file must be copied to the working directory at the beginning of the run The user may edit and modify this file at her own risk In cf_name_table txt an index is given for each field standard name and associated units The appropriate index has to be indicated for each field in the namcouple third entry on the field first line see section 5 3 APPENDIX B CHANGES BETWEEN VERSIONS This standard name and the associated units are also used to define the field attributes long name and units in the NetCDF output files written by the PSMILe for fields with status EXPOUT IGNOUT and OUTPUT For more details on this auxiliary file see section 7 1 Many timesteps for mode NONE In mode NONE OASIS3 can now interpolate at once all time occurrences of a field contained in an input NetCDF file The time variable in the input file is recognized by its attribute units The acceptable units for time are listed in the udunits dat file 3 This follows the CF convention The keyword SRUNTIME in the namcouple has to be the number of time occurrences of the field to interpolate from the input file The coupling period of the field 4th entry on the field first line must be always 1 Note that if SRUNTIME is smaller than the total number of time ocurrences in the input file the first SRUNTIME occurrences will be interp
47. e 182X152 grid points Then toyoce starts its timestep loop At the beginning of its timestep toyoce calls the PSMILe prism get routine 7 times to request the fields named Field3 to Field9 on table 8 1 At the end of its timestep toyoce calls PSMILe prism_put routine to send fields named Field1 and Field2 on table 8 1 The fields will be effectively received or sent only at the coupling frequency defined by the user see section 5 3 As toyoce contains no real physics or dynamics it defines a simple feed back between Field1 and Field3 and between Field2 and Field7 such as Fieldi Field3 1 Field2 Field7 1 Finally at the end of the run toyoce performs the PSMILe finalization call The toyatm model The toyatm model which sources can be found in prism src mod t oy at m sr c has a realistic atmospheric T31 Gaussian grid 96x48 points Its timestep is 3600 seconds it therefore performs 144 timesteps per 6 day run As toyoce toyatm performs at the beginning of a run appropriate PSMILe calls to initialize the coupling define its grids and declare its I O or coupling variables Then toyatm retrieves a local communicator for its internal parallelization with a call to PSMILe prism_get_localcomm routine useful if the MPI1 communication technique is chosen by the user see section 4 1 Toyatm can run on 1 or 3 processes depending on the variable il nbcplproc hardcoded to 3 by default If the user modifies this vari able and hard
48. e Gok Be ne RAR Le der MR AE MO de pi Ra 22 22 24 26 26 27 28 6 5 6 6 The cooking stage The post processing OASIS3 auxiliary data files 7 1 7 2 7 3 74 7 5 Field names and units Grid data files Coupling restart files CONTENTS Input data flesse a Gyles a wee ee tes fae Ty DA ead Ce NA NT ae ot a Transformation auxiliary data files 7 5 1 Auxiliary data files for EXTRAP NINENN INTERP GAUSSIAN 7 5 2 Auxiliary data files for FILLING 7 5 3 Auxiliary data files for SCRIPR MOZAIC Compiling and running OASIS3 8 1 8 2 8 3 The grid types for the transformations Compiling OASIS3 and TOYCLIM 8 1 1 8 1 2 CPP keys Compilation with TopMakefileOasis3 EXTRAP WEIGHT and SUBGRID Running OASIS3 in coupled mode with TOYCLIM 8 2 1 TOYCLIM description 8 2 2 Running TOYCLIM using the script run toyclim Running OASIS3 in interpolator only mode The testinterp test case 8 3 2 The testNONE test case 8 3 1 Changes between versions B 1 B 2 B 3 B 4 B 5 Changes between oasis3 Changes between oasis3 Changes between oasis3 Changes between oasis3 Changes between oasis3 Copyright statements C 1 OASIS3 copyright statement C 2 The SCRIP 1 4 copyright statement prism prism prism prism prism 2 _5 and oasis3 2 4 and oasis3 2 3 and oasis3 2 2 and oasis3 2 1 and oasis3 prism prism prism prism prism The coupled models realized with OASIS
49. e example into which OASIS3 interpolates many time occurrences from one input file put TIME MANY insc run testinterp The configuration file prism data test in te rp in put namcouple MANY and the input file fldin nc in prism data tes tin te rp r es tar t is then used The results obtained after running the testinterp test case should match the ones in prism data testinterp outd ata 8 3 2 The testNONE test case All files to run the testNONE test case can be found in prism util runn in g te stN ON E This test case provides a flexible environnement to test the interpolation specified in the INPUT namcoup1 e configuration file from a source grid to a target grid both grids being defined in regular OASIS3 grid data files grids nc masks nc areas nc see section 7 2 To run test NONE the user has to adapt the User specifications part of the running script sc run NONE In particular he has to specify the directory for the grid data files the directory for the namcouple and cf name table txt files the source and target grid prefixes in the namcouple and in the grid data files see section 5 3 1 an analytic function and whether or not the error on the target grid will be calcu lated on all points MASKERROR NOT or only on non masked points MASKERROR YES When launched the running script sc run NONE e creates a working directory e compiles and runs the program PROG create inputfield f90 that creates an i
50. e extended to masked areas before interpolation SCDMSK SEALAND using the Reduced grid mask see section 7 2 or if the opposite has to be performed SCDMSK LANDSEA If SCDMSK NOEXTRAP then no extrapolation is performed INVERT This transformation is obsolete in the current OASIS version and should be used anymore INVERT routine invert f reorders a field so that it goes from south to north and from west to east the first point will be the southern and western most one then it goes parallel by parallel going from south to north Note that INVERT does not transform the associated grid or mask INVERT should be used only for fields associated to A B G L Z or Y grids see annexe A but produced by the source model from North to South and or from East to West INVERT does not work for Reduced D or unstructured U grids see annexe A The generic input line is as follows INVERT operation SCORLAT SCORLON SCORLAT NORSUD or SUDNOR and SCORLON ESTWST or WSTEST describes the orien tation of the source field in longitude and latitude respectively MASK 6 3 THE PRE PROCESSING TRANSFORMATIONS MASK routine masq f is used before the analysis EXTRAP A given REAL value VALMASK is assigned to all masked points following the source grid mask see section 7 2 so they can be detected by EXTRAP The generic input line is as follows MASK operation SVALMASK approaches the maximum value that your compu
51. e following B 5 CHANGES BETWEEN 0AS153 PRISM 2 1 AND OASIS3 PRISM 12 B 5 Bug corrections INTERP GAUSSIAN and SCRIPR GAUSWGT transformations work for U grids The grid and data information contained in I O files output by the PSMILe library have now a coherent ordering even if INVERT or REVERSE transformations are used OASIS3 and the TOYCLIM coupled model are ported to IBM Power4 and Linux Opteron which are now included in the Standard Compiling and Running Environments SCE and SRE SIPC technique communication is re validated Clim MaxSegments 338 inprism src lib clim sr c modclim F90 andinprism src 1lib ps 338 is presently the largest value needed by a PRISM model MPI _BSend below the call to prism enddef proto the PSMILe tests whether or not the model has already attached to an MPI buffer If it is the case the PSMILe detaches from the buffer adds the size of the pre attached buffer to the size needed for the coupling exchanges and reattaches to an MPI buffer The model own call to MPI Buffer Attach must therefore be done before the call to prism _enddef proto Furthermore the model is not allowed to call MPI BSend after the call to prism terminate proto as the PSMILe definitively detaches from the MPI buffer in this routine See the example in the toyatm model in prism src mod to yatm src Changes between oasis3 _prism _2_1 and oasis3 prism 12 The changes between versions tagged oasis3 prism 12 d
52. e of Clim MaxSegments in prism src lib clim src mod clim F90 and in prism src lib psmile src mod prism proto F90 and by recompiling Oasis3 and the PSMILe library As for the Box partition the maximum number of segments is presently 338 it can be increased by modifying the value of Clim MaxSegments 4 4 I O COUPLING FIELD DECLARATION 11 Proc 1 1st segment offset 0 nbr of segments 3 1st segment size 4 2nd segment offset 7 2nd segment size 2 3rd segment offset 10 3rd segment size 3 Figure 4 3 Orange partition for one process e ig paral 4 the first segment local extent e ig paral 5 the second segment global offset e ig paral 6 the second segment local extent e ig paral N 1 the last segment global offset e ig paral N the last segment local extent Figure 4 3 illustrates an Orange partition with 3 segments for one process The other process partitions are not illustrated 4 4 T O coupling fi eld declaration Each process implied in the coupling declares each field it will send or receive during the simulation e CALL prism def var proto var id name il part id var nodims kinout var _actual shape var type terror var id INTEGER OUT coupling field ID name CHARACTER 8 IN field symbolic name as in the namcouple il part _id INTEGER IN partition ID returned by prism def partition proto var _nodims
53. echniques offered by Los Alamos National Laboratory SCRIP 1 4 library 1 SCRIPR routines are in prism src lib scr ip See the SCRIP 1 4 documen tation in prism src mod oa si s3 do c SC RI Pus er s pd f for more details on the interpo lation algorithms Linking with NetCDF library is mandatory when using SCRIPR interpolations The following types of interpolations are available DISTWGT performs a distance weighted nearest neighbour interpolation N neighbours All grid types are supported Masked target grid points no values are calculated for masked target grid points Non masked target grid points if the N nearest neighbours of a non masked target grid point are masked no value is calculated for that target point note that transformations MASK and EXTRAP can be used to avoid this situation the value 1 0E 20 is assigned to that non masked target grid point if prism src lib s crip src sc riprmp f orvector F90 for vector interpolation are compiled with 11 weightot true The configuring line is See the copyright statement in appendix C 2 6 4 THE INTERPOLATION SCRIPR DISWGT SCMETH CGRS CFTYP S REST SNBIN NV S ASSCMP PROJCART SCMETH DISTWGT SCGRS is the source grid type LR D or U see annexe A SCFTYP isthe field type SCALAR ifthe field is a scalar one or VECTOR I orVECTOR J whether the field represents respectively the first or the second component of a vector field see paragraph Support of vecto
54. ed D source grid CONSERV performs Ist or 2nd order conservative remapping which means that the weight of a source cell is proportional to area intersected by target cell Note that the SCRIP library supposes that the borders of the cells are linear in the longitude latitude space between the corners defined by the users or calculated automatically by OASIS3 see CGRS In this space the border of a cell has to be coincident with the border of its neighbour cell to give proper results The target grid mask is never considered in CONSERV except with normalisation option FRACNNEI see below To have a value calculated a target grid cell must intersect at least one source cell However the NORMlisation option that takes into account the source grid mask see below may result in a null value calculated for those target grid cells In that case i e at least one intersecting source cell but a null value finally calculated be cause of the normalisation option the value 1 0E 20 is assigned to those target grid points if prism src lib s cr ip src scriprmp f orvector F90 for vector interpola tion are compiled with 11 weightot true The configuring line is SCRIPR CONSERV SCMETH SCGRS SCFTYP SREST SNBIN SNORM SORDER SASSCMP SPROJCART SCMETH CONSERV SCGRS is the source grid type LR D and U are supported for 1st order remapping if the grid comers are given by the user in the grid data file which is in this ca
55. eld11 and Field10 such as Field11 Field10 1 Finally at the end of the run toyche performs the PSMILe finalisation call CHAPTER 8 COMPILING AND RUNNING OASIS3 TOYCLIM coupling algorithm The coupling algorithm between the TOYCLIM component models toyoce toyatm and toyche is de scribed here Table 8 1 lists the coupling fields exchanged between those 3 model components giving the symbolic name used in each component and indicating whether the model produces the field src or receives it tgt RC EE ET Fid SOSSTSST Ge SISUTESU g ren A Field SOICECOV sre SIICECOV g him A Field3 SOALBEDO g __ SOAIBEOm Relat SONSHLDO g0 CONSETOT Gey fui En Field SOSHFLDO__ COSHPTOTse 7 Fielde SOWAFLDO ai COWATFLU Ge Mare Fs Fiela SORUNOFF Qe CORUNOFE re snes Field SOZOTAUX igi COZOTAUX sre ___ ds dane A Field SOMETAUY e9 COMETAUY we fm a et CON re SONT sne Ft ad COTHSHSU D SOTHSHSU sre lune A Table 8 1 Coupling and I O fields of the TOYCLIM coupled model The symbolic name used in each toy model is given and it is indicated whether the model produces the field src or receives it tgt The function used to create the field in the initial restart file is also given Figure 8 1 illustrates the coupling algorithm between the 3 TOYCLIM toy models for Fueld Fields Fields Fieldio and Field11 Field is sent from to
56. elds Fieldi0 and Field 8 3 RUNNING OASIS3 IN INTERPOLATOR ONLY MODE 8 3 1 The testinterp test case The testinterp test case can be run to test the interpolation of different source fields corresponding to analytical functions and to evaluate the error between the interpolated fields and the same analytical functions calculated on the different target grids All files needed to run this test case can be found in prism data tes tint erp i np ut and prism data testinterp restart To run testinterp OASIS3 first has to be compiled in interpolator only mode NONE see section 8 1 Then the programs that will calculate the interpolation error i e gen error f90 and gen error vector f90 for vector fields in directory prism util runn ing t es ti nt erp e rr or have to be compiled see script sc comp error Then one has to adapt and execute the running script prism util runni ng testinte rp script sc run testinterp WithTIME ONE _ the configuration file prism data test inter p input namcouple ONE the input files fldal nc flda2 nc flda3 nc fldbl nc fldol nc andfldzl nc fromprism data tes tinte rp res ta rt and the input files aalin nc and caJin nc from prism data testi nt er p re sta rt v ec to r are used This example also shows one vector interpolation field components at42 1 andc at42 J The test case automatically writes the error fields in error _ nc files and error statistics in log files To run th
57. elivered in September 2003 and oasis3 prism 21 delivered to PRISM in April 2004 are the following Bug corrections Thanks to Eric Maisonnave a bug was found and corrected in prism src lib scrip sre scriprmp f sou_mask and tet_mask were not properly initialised if weights and addresses were not calculated but read from file 39 Ges Some deallocation were missing in prism_terminate_proto F ig def_part ig _length_part cg_ignout_field Thanks to Arnaud Caubel a bug was found and correctedin prism src lib psmile src write_file F90 In case of parallel communication between a model and OASIS3 main process the binary cou pling restart files were not written properly NetCDF coupling restart files are OK Routines renamed The routines preproc f extrap f iniiof f inprism src mod o as is 3 s rc were renamed to preproc F extrap F iniiof F as a CPP key key_openmp was added Please note that this key allowing openMP parallelisation is not fully tested yet Modifications in the namcouple The third entry on the field first line now corresponds to an index in the new auxiliary file cf_name_table txt see sections 5 3 and 7 1 For IGNORED IGNOUT and OUTPUT fields the source and target grid locator prefixes must now be given on the field second line see section 5 3 2 A new auxiliary file cf name_table txt For each field the CF standard name used in the OASIS3 log fil
58. erminate proto 4 2 GRID DATA FILE DEFINITION 7 prism terminate grids writing call The coupler will send the starting flag to the next model this ensures that only one model accesses the files at a time This section describes the PSMILe routines that may be called by the master process of each component model to write at run time the whole grid information to the grid data files These routines have to be called just after prism init comp proto The TOYCLIM coupled model uses those routines to write its grid data files if gridswr 1 in the running script run toyclim see section e USE mod prism grids writing Module to be used by the component model to call grid writing routines e CALL prism start grids writing flag flag INTEGER OUT returns 1 0 if grids writing is needed not needed Initialisation of grids writing e CALL prism write grid cgrid nx ny lon lat cgrid CHARACTER 4 IN grid name prefix see 5 3 nx INTEGER IN grid dimension in x direction ny INTEGER IN grid dimension in y direction lon REAL DIMENSION nx ny IN array of longitudes degrees East lat REAL DIMENSION nx ny IN array of latitudes degrees North Writing of the model grid longitudes and latitudes Longitudes must be given in degrees East in the interval 360 0 to 720 0 Latitudes must be given in degrees North in the interval 90 0 to 90 0 Note that if some grid points overla
59. es beginning with are ignored and considered as comments e blank lines are not allowed The first part of namcouple is devoted to configuration of general parameters such as the number of mod els involved in the simulation the number of fields the communication technique etc The second part gathers specific information on each coupling or I O field e g their coupling period the list of transfor mations or interpolations to be performed by OASIS3 and their associated configuring lines described in more details in section 6 etc In the next sections a simple namcouple example is given and all configuring parameters are described The additional lines containing the different parameters required for each transformation are described in section 6 An example of a realistic namcouple can be found in directory prism util runn ing toyclim input na mc ou ple 5 1 An example of a simple namcouple The following simple namcouple configures a run in which an ocean an atmosphere and an atmospheric chemistry models are coupled The ocean provides only the SOSSTSST field to the atmosphere which in return provides the field CONSFTOT to the ocean One field COSENHEL is exchanged directly from the atmosphere to the atmospheric chemistry and one field SOALBEDO is read from a file by the ocean He HH HERE HEH tt tt tH FH HE FH TH HE HE PTE TE TE EE HE FE FE PE PE PRE FH FH THE EE PEE First section SSEQMODE 1 SCHANNEL MP12 NOBSEN
60. ese can be other coupling fields or constant fields This analysis requires the same input line as BLASOLD e MASKP A new analysis MASKP can be used to mask the fields after interpolation MASKP has the same generic input line as MASK 6 6 The post processing The following analyses are available in the post processing part of OASIS3 controlled by prism src mod oasis3 src po st pro f e REVERSE This transformation is obsolete in the current OASIS version REVERSE routine prism src mod oas is 3 sr c rev er se f reorders a field This analysis requires the same input line as INVERT with SCORLON and SCORLAT being now the resulting orientation REVERSE does not work for U and D grids see appendix A Note that INVERT does not transform the associated grid or mask e CHECKOUT CHECKOUT routine prism src mod o as is3 s rc chk fld f calculates the mean and extremum values of an output field and prints them to the coupler output cplout The generic input line is as for CHECKIN see above e GLORED This transformation is obsolete in the current OASIS version as coupling fields can be directly interpolated to a target Reduced grid if needed this transformation should not be used anymore GLORED performs a linear interpolation of field from a full Gaussian grid to a Reduced grid When present GLORED must be the last analysis performed Before doing the interpolation non masked values are automatically extrapolated to masked
61. esponding prism_def_var_proto date INTEGER IN number of seconds in the run at the beginning of the timestep field array REAL IN I O or coupling field array info INTEGER OUT returned info code i e PRISM_Sent 4 if the field was sent to another model directly or via OASIS3 main process PRISM LocTrans 5 if the field was only used in a time transformation not sent not output PRISM_ToRest 6 if the field was written to a restart file only x PRISM_Output 7 if the field was written to an output file only x PRISM_SentOut 8 if the field was both written to an output file and sent to another model directly or via OASIS3 main process x PRISM _ToRestOut 9 if the field was written both to a restart file and to an output file PRISM_Ok 0 otherwise and no error occurred SPRISM standard is to exchange coupling fields declared REAL kind SELECTED REAL KIND 12 307 By default all real variables are declared as such in OASIS3 To exchange single precision coupling fields OA SIS3 has to be compiled with the pre compiling key use_realtype_single the coupling fields must be declared REAL kind SELECTED REAL KIND 6 37 in the component models see also chapter 8 Coupling fields exchanged directly between two component models can have a type different from the ones exchanged through OASIS3 main process as long as they are single or double precision real arrays in both models 4 6 S
62. fter the receiving action in the target model below the prism get proto call The grid and partitioning of the source and target models have to be identical e INPUT simply read in from the input file by the target model PSMILe below the prism get proto call at appropriate times corresponding to the input period indicated by the user in the namcouple See section 7 4 for the format of the input file e OUTPUT simply written out to an output file by the source model PSMILe below the prism put proto call at appropriate times corresponding to the output period indicated by the user in the namcouple The name of the output file one per field is automatically built based on the field name and initial date of the run SINIDATE 5 3 1 Second section of namcouple for EXPORTED AUXILARY and EXPOUT fields The first 3 lines for fields with status EXPORTED AUXILARY and EXPOUT are as follows SOSSTSST SISUTESU 1 86400 5 sstoc nc sstat nc EXPORTED 182 149 128 64 toce atmo LAG 14400 SEQ 1 P 2 P 0 where the different entries are e Field first line SOSSTSST symbolic name for the field in the source model CHARACTER 8 It has to match the argument name of the corresponding field declaration in the source model see prism def var proto in section 4 4 SISUTESU symbolic name for the field in the target model CHARACTER 8 It has to match the argument name of the corresponding field declaration in the target model see prism
63. fying anything in the component model codes themselves The lag and sequence concepts and indices are explained in more details here below These mechanisms are valid for fields exchanged through OASIS3 main process and for fields exchanged directly between the component models 4 8 1 The lag concept If no lag index or if a lag index equal to 0 is given by the user in the namcouple for a particular coupling field the sending or receiving actions will actually be performed below the prism put proto called in the source model or below the prism get proto called in the target model respectively each time the date arguments on both sides match an integer number of coupling periods Tomatchaprism put proto called by the source model at a particular date withaprism get proto called by the target model at a different date the user has to define in the namcouple an appropriate lag in dex LAG for the coupling field see section 5 The value of the LAG index must be expressed in number of seconds its value is automatically added to the prism put proto date value and the sending action is effectively performed when the sum of the date and the lag matches an integer number of coupling peri ods This sending action is automatically matched on the target side with the receiving action performed when the prism get proto date argument equals the same integer number of coupling periods 1 LAG concept first example A first coupling algorithm explo
64. he interpolation type i e DISTWGT GAUSWGT BILINEA BICUBIC orCONSERV and NORMAOPT is the normalization option i e DESTAREA or FRACAREA for CONSERV only The problem comes from the fact that the weights and addresses will also differ whether or not the MASK and EXTRAP transformations are first acti vated during the pre processing phase see section 6 3 and this option is not stored in the remap ping file name Therefore the remapping file used will be the one created for the first field having the same source grid target grid and interpolation type and the same normalization option for CONSERV even if the MASK and EXTRAP transformations are used or not for that field This in consistency is however usually not a problem as the MASK andEXTRAP transformations are usually used for all fields having the same source grid target grid and interpolation type or not at all e INTERP CHAPTER 6 THE TRANSFORMATIONS AND INTERPOLATIONS IN OASIS3 INTERP gathers different techniques of interpolation controlled by routine fiasco f The fol lowing interpolations are available BILINEAR performs a bilinear interpolation using 4 neighbours BICUBIC performs a bicubic interpolation NNEIBOR performs a nearest neighbour interpolation These three interpolations are performed by routines in prism src lib fs cint and support only A B G L Y or Z grids see appendix A All sources grid points masked or not are used in the
65. id model name ierror compid INTEGER OUT component model ID model name CHARACTER 6 IN name of calling model as in namcouple ierror INTEGER OUT returned error code Routine called by all component model processes which initialises the coupling e CALL prism get _localcomm proto local comm ierror local _com INTEGER OUT value of local communicator ierror INTEGER OUT returned error code For CLIM MPI1 communication technique routine called by all model processes to get the value of a local communicator to be used by the model for its internal parallelisation In fact with CLIM MPI1 all component models started in a pseudo MPMD mode share automati cally the same MPI COMM_WORLD communicator Another communicator has to be used for the internal parallelisation of each model OASIS3 creates this model local communicator following a coloring scheme its value is returned as the first argument of prism_get_localcomm proto routine With CLIM MPI2 the communicator MPI LCOMM WORLD will be returned as local communica tor Besides that the differences between using PSMILe with MPI1 or MPI2 message passing are The CHANNEL in the namcouple see section 5 2 The way the models are started With MPI2 only OASIS3 needs to be started at the command line it will then spawn the component models at the beginning of the run With MPI1 models have to be started by the user in a
66. id points use in the subgrid mapping SSUBTYPE SOLAR is the type of subgrid interpolation SCCOARSE is the auxiliary field name on the coarse grid corresponding to a and SCFINE is the auxiliary field name on fine grid corresponding to a These two fields needs to be exchanged between their original model and OASIS3 main process at least as AUXILARY fields This analysis is performed from the coarse grid with a grid mapping type of interpolation based on the SCFILE file 2 If the the SUBGRID operation is performed on a nonsolar flux the 8 argument input line is SUBGRID operation with SUBTYPE NONSO LAR SCFILE SNUMLU SNID SNV SSUBTYPE SCCOARSE SCFINE S SCDQDT SNV are as for a solar subgrid interpolation SSUBTYPE NONSOLAR SCCOARSE is the auxiliary field name on the coarse grid corresponding to J and CFINE is the auxiliary field name on fine grid corresponding to T the additional argument SCDQDT is the coupling ratio on the coarse grid corresponding to 22 These three fields need to be exchanged between their original model and OASIS3 main process as AUXILARY fields This operation is performed from the coarse grid with a grid mapping type of interpolation based on the CFILE file CHAPTER 6 THE TRANSFORMATIONS AND INTERPOLATIONS IN OASIS3 e BLASNEW BLASNEW routine prism src mod oas is 3 sr c bla sn ew f performs a linear combi nation of the current coupling field with any other fields after the interpolation Th
67. imestep necessarily exchanged sequentially in a given order For SEQMODE gt 1 the position of each coupling field in the sequence has to be given by its SEQ index see below and also section 4 8 e SCHANNEL On the line below this keyword is the communication technique chosen Choices are MPI1 orMPI2 for the CLIM communication technique and related PSMILe library using MPI1 or MPI2 message passing To run OASIS3 as an interpolator only put NONE see also section 6 1 The communication techniques available in previous OASIS version i e SIPC PIPE or GMEM should still work but are not officially supported anymore and were not tested To use the CLIM MPI2 communication technique the lines below SCHANNEL are e g for 3 models SCHANNEL MPI2 NOBSEND 1 1 argi 3 1 arg2 3 1 arg3 where MPI2 is the message passing used in CLIM and PSMILe and NOBSEND indicates that standard blocking send MPI Send should be used in place of the buffered MPI BSend to send the coupling fields Use the standard blocking send MPI Send if the coupling fields are necessarily sent and received in the same order or on platforms for which MPI _Send is implemented with a mailbox e g VPPs in this case make sure that the size of the mailbox is sufficient Use the less efficient buffered send MPI BSend on platforms for which MPI Send is not implemented with a mailbox if the coupling fields are not sent and received in the same order Note that below the call
68. ing of grid and data information contained in T O files when INVERT orREVERSE transformations are used the re ordering now occurs only for source field if INVERT is used and only for target field if REVERSE is used LGPL license OASIS3 is now officially released under a Lesser GNU General Public License LGPL as published by the Free Software Foundation see prism src mod oa sis 3 CO PY RI GHT and prism src mod o as is3 src couple f Upgrade of compiling and running environments The compiling and running environments have been upgraded to the PRISM Standard Compiling and Running Environment version dated August Sth 2004 that should be very close to prism_2 3 Treament of vector fields The interpolation algorithms using the SCRIP library now support vector fields including automatic rotation from local to geographic coordinate system projection in Carte sian coordinate system and interpolation of 3 Cartesian components and support of vector compo nents given on different grids New routines have been added in prism src lib s crip src scriprmp _vector F90 and rotations F90 For more detail see SCRIPR in section 6 4 All include of mpif h are now written include lt mpif h gt The output format of CHECKIN and CHECKOUT results is now E22 7 Changes between oasis3 prism 22 andoasis3 prism 21 The changes between versions tagged oasis3 prism 22 delivered in June 2004 andoasis3 prism 21 delivered to PRISM in April 2004 are th
69. ing timestep model B receives F and then sends F5 its timestep length is 6 Ff and F2 coupling periods are both 12 By defining a LAG index of 8 for F3 the models will now run sequentially As the LAG for Fh is positive 6 a reading of F2 in its coupling restart file is automatically performed below the initial prism get proto As the LAG for F is negative 8 no reading from file is per formed initially and model B waits at time 8 a sending action is effectively performed below model A Fi prism put proto as 8 LAG 8 0 which is the first coupling timestep and matches the initial model B F1 prism get proto Below the last model A Fi prism put proto of the run at time 116 a sending action is effectively performed as 116 LAG 8 108 is a coupling pe riod as the LAG is negative the field is not written to its coupling restart file Below the last model 4 8 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS 19 ee B Eai a 18 24 30 120 OASIS3 main process Hand a 120 prism_put_proto prism_get_proto leading to sending receiving actions gt prism_put_proto prism_get_proto NOT leading to sending receiving actions Model A timestep 6 Cpl_period F1 12 LAG F1 0 SEQ F1 1 Cpl_period F2 12 LAG F2 0 SEQ F2 Cpl_period F3 12 LAG F3 0 SEQ P3 Figure 4 6 The SEQ concept CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY Model B timestep 6 F2 rif e Fl
70. input line is Sea Ice Extent FILLING operation SCFILE SNUMLU CMETH the file name for the global data set SNUMLU the associated logical unit SCMETH the FILLING technique is a CHARACTER 8 variable the first 3 characters are either SMO smooth filling or RAW no smoothing the next three characters must be SIE for a Sea Ice Extent filling operation the last two define the time characteristics of the global data file re spectively MO SE and AN for interannual monthly climatological monthly and yearly Note that in all cases the global data file has to be a Sea Surface Temperature field in Celsius degrees 2 If FILLING performs the blending of a regional data set with a global one for the Sea Surface Temperature without any smoothing the 4 argument input line is Sea Surface Temperature FILLING operation without smoothing SCFILE SNUMLU SCMETH SNFCOAST SCFILE SNUMLU are as for the SIE filling In this case however CMETH 1 3 RAW SCMETH 4 6 SST and the last two characters define the time characteristics of the global data file as for the SIE filling SNFCOAST is the flag for the calculation of the coastal correction 0 no 1 yes 3 If FILLING performs the blending of a regional data set with a global one for the Sea Surface Temperature with smoothing the 6 argument input line is Sea Surface Temperature FILLING operation with smoothing SCFILE SNUMLU SCMETH SNFCOAST SCNAME SNUNIT where SCFILE S NUMLU andS
71. ion smoothing bands will be calculated as for the second dimension The user must provide the climatological data file with a specific format described in 7 5 When one uses FILLING for SST with smooth blending thermodynamics consistency requires to modify the heat fluxes over the blending regions The correction term is proportional to the difference between the blended SST and the original SST interpolated on the atmospheric grid and can be written out CHAPTER 6 THE TRANSFORMATIONS AND INTERPOLATIONS IN OASIS3 on a file to be read later for analysis CORRECT for example In that case the symbolic name of the flux correction term read through the input file namcouple must correspond in FILLING and CORRECT analyses In case the regional ocean model includes a coastal part or islands a sea land mask mismatch may occur and a coastal point correction can be performed if the field has been previously interpolated with INTER SURFMESH In fact the mismatch could result in the atmosphere undesirably seeing climatological SST s directly adjacent to ocean model SST s Where this situation arises the coastal correction consists in identifying the suitable ocean model grid points that can be used to extrapolate the field excluding climatological grid points This analysis requires one configuring line with 3 4 or 6 arguments 1 If FILLING performs the blending of a regional data set with a global one for the Sea Ice Extent the 3 argument
72. it is not required otherwise 4 maskr or maskrnc this file contains Reduced D grid mask in INTEGER arrays dimensioned array nbr pts wherenbr pts is the total number of the Reduced grid points 0 not masked or 1 masked for each grid point This file is required only for grids to which the REDGLO or GLORED transformation is applied As mentionned above these transformations should not be used anymore as interpolations are now available for Reduced grids directly If used the mask array name must be MSKRDxxx where xxx is half the number of latitude circles of the reduced grid 032 for a T42 for example If the binary format is used grids masks areas and maskr must have the following structure The array name is first written to the file to locate a data set corresponding to a given grid The data set is then written sequentially after its name Let us call brick the name and its associated data set The order in which the bricks are written doesn t matter All the bricks are written in the grid data file in the following way WRITE LU array_name WRITE LU auxildata e LU is the associated unit e array name is the name of the array CHARACTER 3 e auxildata is the REAL or INTEGER array dimensioned nx ny or nbr pts l con taining the grid data 7 3 COUPLING RESTART FILES 7 3 Coupling restart fi les At the beginning of a coupled run some coupling fields may have to be initially read from their
73. iting the LAG concept is illustrated on figure 4 4 On the 4 figures in this section short black arrows correspond to prism put proto or prism get proto called in the component model that do not lead to any sending or receiv ing action long black arrows correspond to prism put proto or prism get proto called in the component models that do effectively lead to a sending or receiving action long red arrows correspond to prism put proto or prism get proto called in the component models that lead to a reading or writing of the coupling field from or to a coupling restart file either directly or through OASIS3 main process During a coupling timestep model A receives F2 and then sends F its timestep length is 4 During a coupling timestep model B receives F and then sends F gt its timestep length is 6 F1 and F gt coupling periods are respectively 12 and 24 If F F sending action by model A B was used at a coupling timestep to match the model B A receiving action a deadlock would occur as both models would be initially waiting on a receiving action To prevent this F and F produced at the timestep before have to be used to match respectively the model B and model A receiving actions 16 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY Model B timestep 6 a etant Model A timestep 4 prism_put_proto prism_get_proto leading to writing reading to from coupling restart file prism_put_proto prism_get_pro
74. ive coefficient of the current field and SNBFIELDS the number of addi tional fields to be combined with the current field For each additional field an additional configur ing line is required nbfields lines SCLOC SAMULT SCFILE SNUMLU SCLOC and SAMULT SCFILE and SNUMLU are respectively the symbolic name the multiplicative coefficient the file name and the associated logical unit on which the additional field is going to be read The structure of the file has to follow the structure of OASIS3 binary coupling restart files see section 7 3 The interpolation The following interpolations controlled by interp f are available in OASIS3 BLASOLD BLASOLD routine blasold f performs a linear combination of the current coupling field with other coupling fields or with a constant before the interpolation per se This transformation requires at least one configuring line with two parameters BLASOLD operation SXMULT SNBFIELDS SXMULT is the multiplicative coefficient of the current field and NBFIELDS the number of addi tional fields to be combined with the current field For each additional field an additional input line is required nbfields lines SCNAME SAMULT where SCNAME and SAMULT are the symbolic name and the multiplicative coefficient for the ad ditional field To add a constant value to the original field put SXMULT 1 SNBFIELDS 1 SCNAME CONSTANT SAMULT value to add SCRIPR SCRIPR gathers the interpolation t
75. le and at the equator if the grid is hemispheric or global with NJ odd The first longitude is 0 the Greenwhich meridian and is repeated at the end of the grid SCPER P and NPER 1 The latitudinal grid length is 180 NJ 1 for a global grid 90 NJ 1 otherwise The longitudinal grid length is 360 NI 1 G grid this is a irregular Lat Lon Gaussian grid covering either an hemisphere or the whole globe going from South to North and from West to East This grid is used in spectral models It is very much alike the A grid except that the latitudes are not equidistant There is no grid point at the pole and at the equator The first longitude is 0 the Greenwhich meridian and is not repeated at the end of the grid SCPER P and SNPER 0 The longitudinal grid length is 360 NI L grid this type covers regular Lat Lon grids in general going from South to North and from West to East The grid can be described by the latitude and the longitude of the southwest corner of the grid and by the latitudinal and longitudinal grid mesh sizes in degrees z grid this is a Lat Lon grid with non constant latitudinal and longitudinal grid mesh sizes going from South to North and from West to East The deformation of the mesh can be described with the help of 1 dimensional positional records in each direction This grid is periodical SCPER P with NPER overlapping grid points y grid this grid is like Z grid excep
76. ling This dataset will be calculated by OASIS3 if SNIO 1 or only read if SNIO 0 SNV is the maximum number of source grid meshes used in the remapping GAUSSIAN routines in prism src lib ana is g is a gaussian weighted nearest neighbour interpolation technique The user can choose the variance of the function and the number of neighbours considered The masked source grid points are not used and no value are calculated for masked target grid points The configuring line is GAUSSIAN interpolation SCMETH SCGRS SCFTYP SNID SNV SVAR SNIO SCMETH GAUSSIAN SCGRS is the source grid type LR D orU and CFTYP is as for the DISTWGT SNID is the identificator for the weight address dataset in all the different INTERP GAUSSIAN datasets in the present coupling This weight address dataset will be calculated by OA SIS3 if SNIO 1 or only read if NIO 0 SNV is the number of neighbours used in the interpolation x SVAR is as for SCRIPR GAUSWGT see above 6 4 THE INTERPOLATION e MOZAIC MOZAIC performs the mapping of a field from a source to a target grid The grid mapping dataset i e the weights and addresses of the source grid points used to calculate the value of each target grid point are defined by the user in a file see section 7 5 The configuring line is MOZAIC operation SCFILE SNUMLU SNID SNV SCFILE and SNUMLU are the grid mapping file name and associated logical unit on which the grid mapping dat
77. n the namcouple as the field type and leads to the same behaviour as before i e each vector component is treated as an independent scalar field To have a real vector treatment one has to indicate VECTOR T or VECTOR J see section 6 4 Bug corrections in prism src lib s cr ip src scriprmpvector F90 In some cases some local variables were not deallocated and variable dimid was declared twice prism src lib p smile s rc mod psmile io F90 correct allocation of array host ing the longitudes thanks to Reiner Vogelsang from SGI Germany prism src lib p smile src write file F90 to remove a deadlock on some ar chitecture thanks to Luis Kornblueh from MPI prism src lib p smile s rc p ri sm enddef proto F the error handler is now explicitely set to MPI ERRORS RETURN before the call to MPI Buffer Detach to avoid abort on some architecture when the component model is not previously attached to any buffer thanks to Luis Kornblueh from MPI prism src lib s cr ip sr c remap conserv f thanks to Veronika Gayler from M amp D prism src mod o as is3 s rc i ni cmc F prism src lib s cr ip sr c re ma p distwgt f Changes between oasis3 prism _2_3 andoasis3 prism 22 The changes between versions tagged oasis3 prism 2 3 delivered in July 2004 and oasis3 prism 2 2 delivered in June 2004 are the following B 4 Bug correction of the previous bug fix regarding order
78. nput field using the chosen analytical function on the specified source grid in file fldin nc e copy all required input and data file to the working directory e run oasis3 that interpolates the analytical field from fldin nc with the interpolation specified in the namcouple e compile and run the program PROG create errorfield f90 that calculates the error be tween the resulting interpolated field and the field defined by the chosen analytical function on the specified target grid and writes it to the file error nc Appendix A The grid types for the transformations As described in section 6 the different transformations in OASIS3 support different types of grids The characteristics of these grids are detailed here 1 Grids supported for the INTERP interpolations see section 6 4 A grid this is a regular Lat Lon grid covering either the whole globe or an hemisphere going from South to North and from West to East There is no grid point at the pole and at the equator and the first latitude has an offset of 0 5 grid interval The first longitude is 0 the Greenwhich meridian and is not repeated at the end of the grid SCPER P and SNPER 0 The latitudinal grid length is 180 NJ for a global grid 90 NJ otherwise The longitudinal grid length is 360 NI B grid this is a regular Lat Lon grid covering either an hemisphere or the whole globe going from South to North and from West to East There is a grid point at the po
79. o html http www unidata ucar edu packages udunits udunits dat S Valcke A Caubel R Vogelsang and D Declat OASIS3 User s Guide oasis3 prism 2 4 PRISM Report No 2 5th Ed CERFACS Toulouse France 2004 S Valcke A Caubel D Declat and L Terray OASIS3 Ocean Atmosphere Sea Ice Soil User s Guide Technical Report TR CMGC 03 69 CERFACS Toulouse France 2003 S Valcke L Terray and A Piacentini OASIS 2 4 Ocean Atmosphere Sea Ice Soil User s Guide and Reference Manual Technical Report TR CMGC 00 10 CERFACS Toulouse France 2000 L Terray S Valcke and A Piacentini OASIS 2 3 Ocean Atmosphere Sea Ice Soil User s Guide and Reference Manual Technical Report TR CMGC 99 37 CERFACS Toulouse France 1999 C Cassou P Noyret E Sevault O Thual L Terray D Beaucourt and M Imbard Dis tributed Ocean Atmosphere Modelling and Sensitivity to the Coupling Flux Precision the CATH ODe Project Monthly Weather Review 126 No 4 1035 1053 1998 L Terray O Thual S Belamari M D qu P Dandin C L vy and P Delecluse Climatology and interannual variability simulated by the arpege opa model Climate Dynamics 11 487 505 1995 E Guilyardi G Madec L Terray M D qu M Pontaud M Imbard D Stephenson M A Filib erti D Cariolle P Delecluse and O Thual Simulation coupl e oc an atmosph re de la variabilit du climat C R Acad Sci Paris t 320 s rie Ila 683 690 1995 L Terray an
80. olated For more details see section 6 1 Model grid data file writing The grid data files grids nc masks nc and areas nc can now be written directly at run time by the component models if they call the new routines prism_start_grids_writing prism_write_grid prism_write_comer prism_write_mask prism_write_area prism_terminate _grids_writing The writing of those grid files by the models is driven by the coupler It first checks whether the binary file grids or the netCDF file grids nc exists in that case it is assumed that areas or areas nc and masks or masks nc files exist too or if writing is needed If grids or grids nc exists it must contain all grid information from all models if it does not exist each model must write its grid informations in the grid data files See section 4 2 for more details Output of CF compliant files The NetCDF output files written by the PSMILe for fields with status EXPOUT IGNOUT and OUTPUT are now fully CF compliant In the NetCDF file the field attributes long_name and units are the ones corresponding to the field index in cf name _table fxt see above and section 7 1 The field index must be given by the user as the third entry on the field first line in the namcouple Also the latitudes and the longitudes of the fields are now automatically read from the grid aux iliary data file grids nc and written to the output files If the latitudes and the longitudes of the mesh corners are p
81. olic name here COSHFTOT _ and of the begin and end dates of the run The prism_get calls in the toyoce model will not be activated at all Fieldio and Field are exchanged respectively from toyatm to toyche and from toyche to toyatm fol lowing Field logic described here above except that the exchanges take place directly between the component models without going to OASIS3 interpolation process as toyatm and toyche have the same grid and the same parallel partition The fields status chosen by the user for those fields in the namcouple should therefore be IGNORED or IGNOUT if the user wants the fields also automatically be written to files below the prism_put and after the prism_get At the beginning of the run i e at time 0 the toyoce prism_get called to receive those fields will automatically read the fields in their corresponding coupling restart files flda3 nc and flda4 nc 8 2 2 Running TOYCLIM using the script run toyclim Data for running TOYCLIM are contained in tar file input toyclim standard standard prism _2 2 tar gz or input toyclim standard standard prism 2 2 single tar gz in di rectory prism data toy cl im Input files and script are located in directory prism util runn in g toyclim To run TOYCLLIM one has to compile OASIS3 and the 3 TOYCLIM component models see section 8 1 to adapt the User s section of the running script prism util runn ing t oyclim scri pt run toyclim for his her platform and to la
82. p it is recommended to define those points with the same number e g 90 0 for both not 450 0 for one and 90 0 for the other to ensure automatic detection of overlap by OASIS which is essential to have a correct conservative remapping SCRIPR CONSERV see section 6 4 e CALL prism write corner cgrid nx ny nc clon clat cgrid CHARACTER 4 IN grid name prefix nx INTEGER IN grid dimension in x direction ny INTEGER IN grid dimension in y direction nc INTEGER IN number of corners per grid cell 4 lon REAL DIMENSION nx ny nc IN array of corner longitudes in degrees East lat REAL DIMENSION nx ny nc IN array of corner latitudes in degrees North Writing of the grid cell corner longitudes and latitudes counterclockwise sense Longitudes must be given in degrees East in the interval 360 0 to 720 0 Latitudes must be given in degrees North in the interval 90 0 to 90 0 Note also that cells larger than 180 0 degrees in longitude are not sup ported Writing of corners is optional as corner information is needed only for some transformations see section 7 2 If called prism_write_corners needs to be called after prism write grids e CALL prism write mask cgrid nx ny mask cgrid CHARACTER 4 IN grid name prefix nx INTEGER IN grid dimension in x direction ny INTEGER IN grid dimension in y direction mask INTEGER DIMENSION nx ny IN mask a
83. part of the namcouple e SJOBNAME Onthe line below this keyword isa CHARACTER x3 or CHARACTER x4 variable giving an acronym for the given simulation e SNBMODEL On the line below this keyword is the number of models running in the given ex periment followed by CHARACTER x6 variables giving their names Then the user may indicate the maximum Fortran unit number used by the models In the example Fortran units above 55 70 and 99 are free for respectively the ocean atmosphere and atmospheric chemistry models If no maximum unit numbers are indicated OASIS3 will suppose that units above 1024 are free If SCHANNEL is NONE SNBMODEL has to be O and there should be no model name and no unit number e SRUNTIME On the line below this keyword is the total simulated time of the run expressed in seconds If SCHANNEL is NONE SRUNTIME has to be the number of time occurrences of the field to interpolate from the restart file e SINIDATE On the line below this keyword is the initial date of the run The format is YYYYMMDD This date is important only for the FILLING transformation and for printing information in OASIS3 log file cplout e SMODINFO If coupling restart files are binary files see section 7 3 the line below this keyword indicates if a header is encapsulated or not it can be YES or NOT e SNLOGPRT The line below this keyword refers to the amount of information that will be written to the OASIS3 log file cplout during the run
84. partition in the global index space ierror INTEGER OUT returned error code The vector of integers describing the process local partition ig paral has a different expression de pending on the type of the partition In OASIS3 4 types of partition are supported Serial no partition Apple Box and Orange 4 3 1 Serial no partition This is the choice for a monoprocess model In this case we have ig paral 1 3 e ig paral l O indicates a Serial partition e ig paral 2 0 e ig paral 3 the total grid size 4 3 2 Apple partition Each partition is a segment of the global domain described by its global offset and its local size In this case we have ig paral 1 3 e ig paral i 1 indicates an Apple partition e ig paral 2 the segment global offset e ig paral 3 the segment local size Figure 4 1 illustrates an Apple partition over 3 processes 4 3 3 Box partition Each partition is a rectangular region of the global domain described by the global offset of its upper left corner and its local extents in the X and Y dimensions The global extent in the X dimension must also be given In this case we have ig paral 1 5 4 3 PARTITION DEFINITION 9 Proc 1 Proc 2 Proc 3 local offset 0 local offset 4
85. points with EXTRAP NINENN method see above to do so the masked grid points are first replaced with a predefined value The required global grid mask must be present in data file masks ormasks nc see section 7 2 The generic input line is as follows GLORED operation SNNBRLAT SNV SNIO SNID is as for REDGLO see REDGLO description above The next 3 parameters refer to the EXTRAP NINENN extrapolation see EXTRAP NINENN description above The value assigned to all land points be fore interpolation is given by amskred in prism src mod o as is 3 sr c b lk data f as for the SVALMASK in MASK analysis it has to be chosen well outside the range of your field values but not too large to avoid any representation problem Chapter 7 OASIS3 auxiliary data fi les OASIS3 needs auxiliary data files describing coupling and I O field names and units defining the grids of the models being coupled containing the field coupling restart values or input data values as well as a number of other auxiliary data files used in specific transformations 7 1 Field names and units The text file cf name table txt that can be found in directory prism util runn ing toyclim input directory contains a list of CF standard names and associated units identified with an index The appropriate index has to be given by the user for each coupling or I O field as the third entry on the field first line see 5 3 This information will be used by OASIS3 for its log
86. proto date INTEGER IN number of seconds in the run at the beginning of the timestep info INTEGER OUT returned error code should be PRISM _ToRest 6 if the restart writing was successful This routine forces the writing of the field with corresponding var id in its coupling restart file see section 7 3 If a time operation is specified for this field the value of the field as calculated below the last prism put proto is written If no time operation is specified the value of the field transferred to the last prism put proto is written e CALL prism get freq var id period ierror var id INTEGER IN field ID from corresponding prism_def_var_proto period INTEGER OUT period of coupling in number of seconds ierror INTEGER OUT returned error code This routine can be used to retrieve the coupling period of field with corresponding var id as defined in the namcouple see also section 5 3 1 4 7 Termination e CALL prism terminate proto ierror ierror INTEGER OUT returned error code All processes must terminate the coupling by calling prism terminate proto 7 normal ter mination Oasis will terminate after all processes called prism_terminate_proto With MPI2 the run may be considered finished when Oasis terminates to avoid problem place the call to prism_terminate_proto at the very end in the component model code e CALL prism abort _proto compid routine name abo
87. r fields below Note that VECTOR which is fact leads to a scalar treatment of the field as in the previous versions is still supported SREST is the search restriction type LATLON or LATITUDE see SCRIP 1 4 documen tation Note that for D or U grid the restriction may influence sligthly the result near the borders of the restriction bins SNBIN the number of restriction bins see SCRIP 1 4 documentation SNV is the number of neighbours used SASSCMP optional for VECTOR I or VECTOR J vector fields only the source symbolic name of the associated vector component SPROJCART optional for vector fields only should be PROJCART if the user wants the vector components to be projected in a Cartesian coordinate system before interpolation see paragraph Support of vector fields below GAUSWGT performs a N nearest neighbour interpolation weighted by their distance and a gaussian function All grid types are supported Masked target grid points no values are calculated for masked target grid points Non masked target grid points if the N nearest neighbours of a non masked target grid point are masked no value is calculated for that target point except that if prism src 1lib scrip src remap gauswgt f is compiled with 11 nnei true in which case the non masked nearest neighbour is used As for DISTWGT the value 1 0E 20 is assigned to non masked target grid points for which no value is calculated if prism src li
88. rary are described in section 8 1 2 8 1 1 Compilation with TopMakefi leOasis3 Compiling OASIS3 and TOYCLIM using the top makefile TopMakefileOas is3 can be done in di rectory prism src mod oas is 3 ut il ma ke dir TopMakefileOas is 3 must be completed with a header file make your_platform specific to the compiling platform used and specified in prism src mod o as is 3 ut il make dir make inc One of the files make pgi cerfacs make sx frontend ormake aix can by used as a template The root of the prism tree can be any were and must be set in the variable PRISMHOME in the make your platform file The choice of MPI1 MPI2 or NONE interpolator only mode see section 6 1 is also done in the make your_platform file see SCHAN therein The following commands are available e make f TopMakefileOas is 3 compiles OASIS3 libraries clim anaisg anaism fscint scrip and creates OASIS3 main executable oasis3 CHAN x where SCHAN is MPII MPI2 or NONE e make f TopMakefileOas is 3 toyclim compiles OASIS3 libraries as above compiles mpp io and psmile librairies and creates OASIS3 and TOYCLIM executables oasis3 MPI 1 2 x toyatm MPI 1 2 x toyoce MPI 1 2 x and toylan MPI 1 2 x emake clean f TopMakefileOas LS3 4 cleans OASIS3 and TOYCLIM compiled files but not the libraries e make realclean f TopMakefileOasi s3 cleans OASIS3 and TOYCLIM compiled files including libraries 46 8 1 COMPILING OASIS3 AND TOYCLI
89. rcier IDRIS Pascale Noyret EDF Andrea Piacentini CERFACS Marc Pontaud M t o France Ren Redler NEC CCRLE Tim Stockdale ECMWF Rowan Sutton UGAMP V ronique Taverne CERFACS Jean Christophe Thil UKMO Nils Wedi ECMWF CHAPTER 1 ACKNOWLEDGEMENTS Chapter 2 Introduction OASIS3 is the direct evolution of the OASIS coupler developed since more than 10 years at CERFACS Toulouse France OASIS3 is a portable set of Fortran 77 Fortran 90 and C routines At run time OA SIS3 acts as a separate mono process executable which main function is to interpolate the coupling fields exchanged between the component models and as a library linked to the component models the OA SIS3 PRISM Model Interface Library OASIS3 PSMILe OASIS3 supports 2D coupling fields only To communicate with OASIS3 directly with another model or to perform I O actions a component model needs to include few specific PSMILe calls OASIS3 PSMILe supports in particular parallel communica tion between a parallel component model and OASIS3 main process based on Message Passing Interface MPI and file I O using the mpp io library from GFDL Portability and flexibility are OASIS3 key design concepts OASIS3 has been extensively used in the PRISM demonstration runs and is currently used by approximately 15 climate modelling groups in Europe USA Canada Australia India and Brasil The current OASIS3 version and its toy coupled model TOYCLIM were compiled and
90. resent in grids nc they are also written to the ouput files as associated bounds variable This works whether the grids nc is given initially by the user or written at run time by the component models see above However this does not work if the user gives the grid definition in a binary file grids Removal of pre compiling key key_BSend The pre_compiling key key_BSend has been removed The default has changed by default the buffered MPI_BSend is used unless NOBSEND is specified in the namcouple after MPI1 or MPI2 in which case the standard blocking send MPI Send is used to send the coupling fields Appendix C Copyright statements C 1 OASIS3 copyright statement Copyright 2006 Centre Europeen de Recherche et Formation Avancee en Calcul Scientifique CERFACS This software and ancillary information called OASIS3 is free software CERFACS has rights to use reproduce and distribute OASIS3 The public may copy distribute use prepare derivative works and publicly display OASIS3 under the terms of the Lesser GNU General Public License LGPL as published by the Free Software Foundation provided that this notice and any statement of authorship are reproduced on all copies If OASIS3 is modified to produce derivative works such modified software should be clearly marked so as not to confuse it with the OASIS3 version available from CERFACS The developers of the OASIS3 software are researchers attempting to build a mod
91. rray 0 not masked 1 masked Writing of the model grid mask e CALL prism write _area cgrid nx ny area cgrid CHARACTER 4 IN grid name prefix 8 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY nx INTEGER IN grid dimension in x direction ny INTEGER IN grid dimension in y direction area REAL DIMENSION nx n y IN array of grid cell areas Writing of the model grid cell areas Writing of areas is optional as area information is needed only for some transformations see section 7 2 e CALL prism terminate grids writing Termination of grids writing A flag stating that all needed grid information was written will be sent to OASIS3 main process 4 3 Partition defi nition When a component of the coupled system is a parallel code each coupling field is usually scattered among the different processes With the PSMILe library each process sends directly its partition to OASIS3 main process or directly to the other component model if no transformation nor repartition is required To do so each process implied in the coupling has to define its local partition in the global index space e USE mod prism def partition proto Module to be used by the component model to call prism def partition proto e CALL prism def partition proto il part id ig paral ierror il part _id INTEGER OUT partition ID ig paral INTEGER DIMENSION IN vector of integers describing the local
92. rt message compid INTEGER IN component model ID from prism _init comp_proto routine name IN name of calling routine If the process called MPI _Init before calling prism init comp proto it must also call MPI Finalize explicitly but only after calling prism terminate proto 4 8 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS 15 abort message IN message to be written out If a process needs to abort abnormal termination it must do so by calling prism abort proto This will ensure a proper termination of all processes in the coupled model communicator This routine writes the name of the calling model the name of the calling routine and the message to the job standard output stdout 4 8 Coupling algorithms SEQ and LAG concepts Using PSMILe library the user has full flexibility to reproduce different coupling algorithms In the com ponent codes the sending and receiving routines respectively prism put proto andprism get proto can be called at each model timestep with the appropriate date argument giving the actual time at the be ginning of the timestep expressed in number of seconds since the start of the run This date argument is automatically analysed by the PSMILe and depending on the coupling period the lag and sequencing indices LAG and SEQ chosen by the user for each coupling field in the configuration file namcouple different coupling algorithms can be reproduced without modi
93. run on NEC SX6 IBM Power4 and Linux PC cluster and previous OASIS3 versions were run on many other platforms 2 1 Step by step use of OASIS3 To use OASIS3 for coupling models and or perform I O actions one has to follow these steps 1 Obtain OASIS3 sources See chapter 3 2 Identify the coupling or I O fields and adapt the component models to allow their exchange with the PSMILe library based on MPI1 or MPI2 message passing The PSMILe library is interfaced with the mpp io library from GFDL 2 and therefore can be used to perform I O actions from to disk files For more detail on how to interface a model with the PSMILe see chapter 4 The TOYCLIM coupled model gives a practical example of a coupled model the sources are given in directories prism src mod to yat m toyoce toyche more detail on TOYCLIM and how to compile and run it can be found in chapter 8 3 Define all coupling and I O parameters and the transformations required to adapt each coupling field from its source model grid to its target model grid prepare OASIS3 configuring file namcouple See chapter 5 OASIS3 supports different interpolation algorithms as is described in chapter 6 4 Generate required auxiliary data files See chapter 7 5 Compile OASIS3 the component models and start the coupled experiment Chapter 8 describes how to compile and run OASIS3 and the TOYCLIM coupled model The appendix D lists some of the coupled models realized with OASIS wi
94. se necessarily a netCDF file grids nc see section 7 2 only LR is supported if the grid corners are not available in the grid data file and therefore have to be calculated automatically by OASIS3 For second order remapping only LR is supported because the gradient of the coupling field used in the transformation has to be calculated automatically by OASIS3 SCFTYP SREST SNBIN SASSCMP andSPROJCART areasforDISTWGT Note that for CONSERV the restriction does not influence the result SNORM is the NORMlization option FRACAREA The sum of the non masked source cell intersected areas is used to NORMlise each target cell field value the flux is not locally conserved but the flux value itself is reasonable DESTAREA The total target cell area is used to NORMlise each target cell field value even if it only partly intersects non masked source grid cells local flux conservation is ensured but unreasonable flux values may result FRACNNEI as FRACAREA except that at least the source nearest unmasked neigh bour is used for unmasked target cells that intersect only masked source cells Note that no value will be calculated for a target cell not intersecting any source cells masked or unmasked even with FRACNNEI option SORDER FIRST or SECOND for first or second order remapping respectively see SCRIP 1 4 documentation Support of vector fields SCONSERV SECOND has not been tested in detail 6 4 THE INTERPOLATIO
95. sed by the component model to call prism get proto e CALL prism get proto var id date field array ierror var id INTEGER IN field ID from corresponding prism_def_var_proto date INTEGER IN number of seconds in the run at the beginning of the timestep field array REAL OUT I O or coupling field array info INTEGER OUT returned info code PRISM_Recvd 3 if the field was received from another model directly or via OASIS3 main process PRISM_FromRest 10 if the field was read from a restart file only directly or via OA SIS3 main process PRISM_Input 11 if the field was read from an input file only PRISM_RecvOut 12 if the field was both received from another model directly or via OASIS3 main process and written to an output file PRISM_FromRestOut 13 if the field was both read from a restart file directly or via OASIS3 main process and written to an output file PRISM_Ok 0 otherwise and no error occurred This routine may be called by the model at each timestep The date argument is automatically analysed and the receiving action is actually performed only if date corresponds to a time for which it should be activated given the period indicated by the user in the namcouple A field will not be received at all if its coupling or I O period indicated in the namcouple is greater than the total run time 4 6 3 Auxiliary routines e CALL prism put inquire var id date info
96. t that it is regional SCPER R and NPER 0 2 Grids supported for the SCRIPR interpolations LR grid The longitudes and the latitudes of 2D Logically Rectangular LR grid points can be described by two arrays longitude i j and latitude i j where i and j are respectively the first and second index dimensions Streched or and rotated grids are LR grids Note that A B G L Y or Z grids are all particular cases of LR grids 54 e U grid Unstructured U grids do have any particular structure The longitudes and the latitudes of 2D Unstructured grid points must be described by two arrays longitude nbr pts 1 and latitude nbr pts 1 where nbr_pts is the total grid size e D grid The Reduced D grid is composed of a certain number of latitude circles each one being divided into a varying number of longitudinal segments In OASIS3 the grid data longitudes latitudes etc must be described by arrays dimensioned nbr pts 1 where nbr _pts is the total number of grid points There is no overlap of the grid and no grid point at the equator nor at the poles There are grid points on the Greenwich meridian Appendix B Changes between versions Here is a list of changes between the different official OASIS3 versions B 1 Changes between oasis3 prism 2 5 and oasis3 prism 24 The changes between version oasis3 prism 2 5 and version oasis3 prism 2 4 delivered in De cember 2004 are listed here after Please
97. tem interpolation of the resulting 3 Cartesian components and projection back in the spherical coordinate system are performed In debug mode compilation with _DEBUG pre compiling key the resulting vertical component in the spherical coordinate system after interpolation is written to a file projection nc as the source vector is horizontal this component should be very close to 0 Ifthe user did not put the PROJCART keyword at the end of the SCRIPR configuring line the two spherical coordinate system components are interpolated If the angles of the target grid local coordinate system are defined in the grids nc data file see section 7 2 an automatic rotation from the geographic spherical to the local coordinate system is performed The first and second components of the interpolated vector field are then present in the target fields associated respectively to the first and second source vector component The target grids for the two vector components can be different Known problems with SCRIPR When the SCRIP library performs a remapping it first checks if the file containing the corres ponding remapping weights and addresses exists If it exists it reads them from the file if not it calculates them and store them in a file The file is created in the working directory and is called rmp usrcg_to tgtg XXXXXXX_NORMAOPT nc where srcg and tgtg are the acronyms of respetively the source and the target grids XXXXXXX is t
98. the regional or and global fields The smoothing is defined by parameters in prism src mod oa si s3 src mod _smooth F90 The lower smoothing band in the global model second dimension is defined by nsltb outermost point and nslte innermost point the upper smoothing band in the global model second dimension is defined by nnltb outermost point and nnlte innermost point The parameter galfa controls the weights given to the regional and to the global fields in the linear interpolation galfa has to be 1 nslte nsltb or 1 nnitb nnlte For the outermost points ns tb or nnltb in the smoothing band the weight given to the regional and global fields will respectively be O and 1 for the inner most points ns te or nnlte in the smoothing band the weight given to the regional and global fields will respectively be 1 and 0 within the smoothing band the weights will be a linear interpolation of the outermost and innermost weights The smoothing band in the global model first dimension will be a band of nliss points following the coastline To calculate this band OASIS3 needs nwlgmx the greater first dimension index of the lower coastline and nelgmx the smaller first dimension index on the upper coastline The parameter qbeta controls the weights given to the regional and to the global fields in the linear interpolation qbeta has to be 1 nliss 1 The weights given to the regional and global fields in the global model first dimens
99. thin the past 5 years or so If you need extra help do not hesitate to contact us see contact details on the back of the cover page The SIPC PIPE and GMEM communication techniques available in previous versions should still work but are not main tained anymore and were not tested Chapter 3 The OASIS3 sources The sources and data of OASIS3 all related libraries and TOYCLIM coupled model are available from CERFACS CVS server alter and from CERFACS anonymous ftp The CVS repository is home oasis PRI SMC VS To obtain the CVS login and password as well as the most recent OASIS3 tag please contact us see contact details on the back of the cover page Note that OASIS3 is temporarily released without the corresponding PRISM Standard Compile Envi ronment and Running Environment SCE SRE they will be included when the migration from CVS to Subversion will be realized at CERFACS OASIS3 directory structure follows the PRISM standard one prism data tes tinterp data and results for OASIS3 in mode NONE toyclim data and results for TOYCLIM coupled model prism src lib an ai sg GAUSSIAN interpolation library anaism SURFMESH interpolation library clim CLIM MPI1 MPI2 communication library fscint INTERP interpolation library mpp_io I O library NAG_dummies Dummy library for NAG compiler psmile PRISM System Model Interface Library scrip SCRIPR interpolation library prism src mod oa si s3 sr c OASIS3 main code doc OASIS3
100. time The time variable as to be an array time time expressed in seconds since beginning of run The time INote that even if the grid auxiliary data files are in NetCDF format the restart coupling files may be in binary format or vice versa If REDGLO is the first transformation applied on a Reduced grid field the Reduced field must be given is an array restartdata nx ny where nx and ny are the global Gaussian grid dimensions and the Reduced field is completed by trailing zeros CHAPTER 7 OASIS3 AUXILIARY DATA FILES dimension has to be the unlimited dimension For a practical example see the file SOALBEDO nc in prism data toy clim input toyclim standard standard prism 2 2 tar gz 7 5 Transformation auxiliary data fi les Many transformation need auxiliary data files such as the grid mapping files used for an interpolation Some of them are created automatically by OASIS3 others have to be generated by the user before starting the coupled run 7 5 1 Auxiliary data files for EXTRAP NINENN EXTRAP WEIGHT INTERP SURFMESH INTERP GAUSSIAN MOZAIC and SUBGRID The auxiliary data files containing the weights and addresses used in these transformations have a similar structure their names are given in Table 7 1 nweights weights addresses and iteration number for EXTRAP NINENN interpolation any name weights and addresses for EXTRAP WEIGHT extrapolation mweights weights and addresses for INTERP SURFMES
101. ting platform can represent choose a value well outside the range of your field values but not too large e EXTRAP EXTRAP routine extrap f performs the extrapolation of a field over its masked points The analysis MASK must be used just before so that EXTRAP can identify masked points Note that EXTRAP does not work for Reduced D or unstructured U grids see appendix A Two methods of extrapolation are available With NINENN a N nearest neighbour method is used The procedure is iterative and the set of remaining masked points evolves at each iteration The configuring line is EXTRAP operation for SCMETH NINENN SCMETH SNV SNIO SNID SCMETH NINENN SNV is the minimum number of neighbours required to perform the extrap olation with a maximum of 4 NIO is the flag that indicates if the weight address and iteration number dataset will be calculated and written by OASIS3 SNIO 1 or only read SNIO 0 in file nweights see section 7 5 SNID is the identificator for the weight address iteration number dataset in all the different EXTRAP NINENN datasets in the present coupling With SCMETH WEIGHT an N weighted neighbour extrapolation is performed In that case the user has to build the grid mapping file giving for each target grid point the weights and addresses of the source grid points used in the extrapolation the structure of this file has to follow the OASIS3 generic structure for transformation auxiliar
102. to M t o Fr Fr 3 0 ARPEGE 4 2 4 ARPEGE medias 2 2 ARPEGE 3 Fr Fr 3 CERFACS 3 0 ARPEGE 4 2 4 ARPEGE 3 2 2 ARPEGE 3 ECMWF U 2 2 IFS T63 T255 2 2 2 2 K IFS Cy23r4 T159L40 MPI Ger 3 0 ECHAMS ma 2 4 ECHAMS T42 L19 PUMAT42 L19 2 4 ECHAMS T42 L19 w w OPA9 NEMO ORCA2 LIM OPA 8 1 E HOPE 2deg 1deg E HOPE 256L29 E HOPE 256L29 MPI OM C HOPE T42 L20 C HOPE 2deg GIN E HOPE T42 L20 E HOPE T42 L20 NEMO ORCA2 182x149x31 ORCA 182x149x31 IFS Cy23r4 T95L40 IFM GEOMAR 0 ECHAMS CGAM 3 0 HadAM3 2 5x3 75 L20 HadAM3 2 5x3 75 L20 INGV I KNMI NERSC y 3 K 2 4 3 30 30 30 Nw 50 LE n D U N D N N ECHAM RCA teg 3o ECHAMS mom Go ECRANS MP 3 0 30 ROMS ARPEGE MICOM VPP5000 VPP5000 VPP5000 PAM OPA VPP5000 CRAY XD1 PC Linux VPP5000 VPP700 IBM Power 4 VPP700 VPP700 IBM Power4 NEC SX NEC SX CRAY C 90 NEC SX NEC SX6 T3E SGI 03800 NEC SX6 SGI IRIX64 NEC SX6 Table D 2 List of couplings realized with OASIS within the past 5 years in Europe The columns list the institution the country the OASIS version used the atmospheric model the ocean model and the computing platform used for the coupled model run Bibliography 1 2 3 4 5 6 7 8 9 10 11 12 14 14 15 16 http gcmd nasa gov records LANL SCRIP html http www gfdl noaa gov vb mpp_i
103. to leading to Cpl_p eriod F1 rie sending receiving actions Cpl_period F2 prism_put_proto prism_get_proto not leading to LAG F1 4 sending receiving actions LAG F2 6 Figure 4 4 LAG concept first example 4 8 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS 17 B P 30 120 ee ene ee 6 ere pte es 18 a perte 24 ne fe ne ns FI tal riff rol rife rol frf F2 F1 F3 F2 Fi F3 F2 F3 nf e rf Fl F2 F3 rif fe rf Fl F2 F3 ra F fF fa RS E ef 225 15 n T8 ES EEE N UE SEES E 1 1 Le 18 24 120 Model timestep 6 prism_put_proto prism_get_proto leading to writing reading to from coupling restart file Cpl_period F1 12 prism_put_proto prism_get_proto leading to Cpl_period F2 12 sending receiving actions Cpl_period F3 12 prism_put_proto prism_get_proto NOT leading to L AG F 1 6 sending receiving actions LAG F2 6 LAG F3 0 Figure 4 5 LAG concept second example This implies that a lag of respectively 4 and 6 seconds must be defined for F and Fy For F the prism put proto performed at time 8 and 20 by model A will then lead to sending ac tions as 8 4 12 and 20 4 24 which are coupling periods that match the receiving ac tions performed at times 12 and 24 below the prism get proto called by model B For F5 the prism put proto performed at time 18 by model B then leads to a sending action as 18 6 24 which is a coupling period that matches the recei
104. to prism enddef proto the PSMILe tests whether or not the model has already attached to an MPI buffer If it is the case the PSMILe detaches from the buffer adds the size of the pre attached buffer to the size needed for the coupling exchanges and reattaches to an MPI buffer The model own call to MPI Buffer Attach must therefore be done before the call to prism enddef proto Furthermore the model is not allowed to call MPI _BSend after the call to prism terminate proto as the PSMILe definitively detaches FIRST SECTION OF NAMCOUPLE FILE If NOBSEND is not specified the buffered send MPI BSend will be used The following lines one line per model listed on the SNBMODEL line indicate for each model the total number of processes the number of processes implied in the coupling and possibly launching arguments Here the first model runs on one process which is of course implied in the coupling and the argument passed to the model is arg1 the second and third models run on 3 processes but only one process is implied in the coupling i e exchanging information with OASIS3 main process and the argument passed to the models are respectively arg and arg3 To use the CLIM MPI1 communication technique the SCHANNEL lines are are as for MPI2 except that MPI2 is replaced by MI1 and there is no launching arguments e SNFIELDS On the line below this keyword is the total number of fields exchanged and described in the second
105. ular and user friendly coupler accessible to the climate modelling community Although we use the tool ourselves and have made every effort to ensure its accuracy we can not make any guarantees We provide the software to you for free In return you the user assume full responsibility for use of the software The OASIS3 software comes without any warranties implied or expressed and is not guaranteed to work for you or on your computer Specifically CERFACS and the various individuals involved in development and maintenance of the OASIS3 software are not responsible for any damage that may result from correct or incorrect use of this software C 2 The SCRIP 1 4 copyright statement The SCRIP 1 4 copyright statement reads as follows Copyright 1997 1998 the Regents of the University of California This software and ancillary infor mation herein called SOFTWARE called SCRIP is made available under the terms described here The SOFTWARE has been approved for release with associated LA CC Number 98 45 Unless otherwise in dicated this SOFTWARE has been authored by an employee or employees of the University of California operator of Los Alamos National Laboratory under Contract No W 7405 ENG 36 with the United States Department of Energy The United States Government has rights to use reproduce and distribute this SOFTWARE The public may copy distribute prepare derivative works and publicly display this SOFT WARE without charge provide
106. unch it The script run toyclim was tested on Linux PC NEC SX 6 and IBM Power4 To run the single precision case OASIS3 and the 3 component models have to be compiled in sin gle precision see section 8 1 2 the configuration file prism util run ning toyclim inp ut namcouple single has to be renamed namcouple in the same directory so to be used automati cally and comp precision single has to be specified in run toyclim The configuration file namcouple single has to be used because the original namcouple specifies some MOZAIC transfor mations using binary auxiliary files that were not converted the results obtained with namcouple single into which the MOZAIC transformations are replaced by SCRIPR DISTWGT interpolations will be slightly different 8 3 Running OASIS3 in interpolator only mode OASIS3 can be used in an interpolator only mode in which case it transforms fields without running any model see section 6 1 Two test cases are provided with OASIS3 to illustrate its uses in this mode the testinterp test case see section 8 3 1 and the testNONE test case see section 8 3 2 CHAPTER 8 COMPILING AND RUNNING OASIS3 F10 F11 F10 Fil F10 Fil F10 F11 ATM FI F4 F1 F4 F1 F4 Fi 1 2 3 4 Gas 1 OASIS Gon 0 OCE lt lt lt SOALBEDO nc SOALBEDO nc Figure 8 1 Exchange algorithm between the 3 TOYCLIM component models for fields Field Fields Fi
107. uple there is no need anymore to define a lag greater than 0 e g LAG 1 for fields in mode NONE Diverse modifications were included for successful compilation with NAGW compiler non portable use of kind etc thanks to Luis Kornblueh from MPI In prism src lib ps mi le mo dprism get proto F90 a potential deadlock was removed the master process was sending a message to itself thanks to Luis Kornblueh from MPI Routine prism src lib sc ri p sr c scr iprmpvector F90 was completely rewrit ten for more clarity Obsolete transformations INVERT and REVERSE were removed from the toy coupled model TOYCLIM in file prism util runn in g toy cl im i np ut na mc ou pl e This change does not affect the statistics printed in the cplout but changes the orientation of some fields in the NetCDF ouput files see the results in prism data toy cli m ou td at a e Other minor modifications In prism src lib ps mi le s rc prism enddef proto F allocation is done only for rg_field_trans or dg_field_trans depending on precision for REAL but not for both to save memory In few routines in prism src lib c li m and in prism src mod oa si s3 parenthe ses were added to make sure that amp amp has priority over in CPP instructions thanks to A Caubel from LSCE Routines scrip src corne rs f netcdf f andscriprmp f were renamed corners F netcdf F scriprmp F and the line INCLUDE netcdf inc
108. ving action performed at time 24 below the prism get proto called by model A At the beginning of the run as their LAG index is greater than 0 the first prism get proto will automatically lead to reading Fi and F from their coupling restart files The user therefore have to create those coupling restart files for the first run in the experiment At the end of the run Fi having a lag greater than 0 is automatically written to its coupling restart file below the last Fi prism put proto if the date F lag equals a coupling time The analogue is true for F2 These values will automatically be read in at the beginning of the next run below the respective prism get proto 2 LAG concept second example A second coupling algorithm exploiting the LAG concept is illustrated on figure 4 5 During its timestep model A receives fF sends F3 and then F3 its timestep length is 6 During its timestep model B receives F receives F3 and then sends F gt its timestep length is also 6 Fi F gt and F3 coupling periods are both supposed to be equal to 12 For F and F gt the situation is similar to the first example If F F sending action by model A B was used at a coupling timestep to match the model B A receiving action a deadlock would occur 18 CHAPTER 4 INTERFACING A MODEL WITH THE PSMILE LIBRARY as both models would be waiting on a receiving action To prevent this F and F gt produced at the timestep before have to be used to match the model
109. xchanged during the simulation must be coherent with the shape of its grid data arrays Both binary and NetCDF formats are supported for NetCDF file the suffix nc is not mandatory If the coupling restart file for the first field is in NetCDF format OASIS3 will assume that all coupling restart files and output files for NONE communication techniques are NetCDF In the NetCDF restart files the field arrays must have the source symbolic name indicated in the namcouple see section 5 3 In binary restart file each field is written in the following way WRITE LU array_name WRITE LU restartdata e LU is the associated unit e array name is the source symbolic name of the field CHARACTER S8 e restartdata is the restart field REAL array dimensioned nx ny or nbr pts l 2 7 4 Input data files Fields with status INPUT in the namcouple will at runtime simply be read in from a NetCDF input file by the target model PSMILe below the prism get proto call at appropriate times corresponding to the input period indicated by the user in the namcouple The name of the file must be the one given on the field first configuring line in the namcouple see section 5 3 3 There must be one input file per INPUT field containing a time sequence of the field in a single or double precision REAL array depending on PSMILe compilation options named with the field sym bolic name in the namcouple and dimensioned nx ny time or nbr _pts 1
110. y data files see section 7 5 The configuring line is EXTRAP operation for SCMETH WEIGHT SCMETH SNV SCFILE SNUMLU SNID SCMETH WEIGHT SNV is the maximum number of neighbours required by the extrapolation operation SCFILE and SNUMLU are the grid mapping file name and associated logical unit NID is the identificator for the relevant grid mapping dataset in all different EXTRAP WEIGHT transfor mations in the present coupling e CHECKIN CHECKIN routine chkfld f calculates the mean and extremum values of the source field and prints them to the coupler log file cplout The generic input line is as follows CHECKIN operation SNINT SNINT 1 or 0 depending on whether or not the source field integral is also calculated and printed e CORRECT CORRECT routine correct f reads external fields from binary files and uses them to modify the coupling field This transformation can be used for example to perform flux correction on the field gt For some grids the extrapolation may not converge if NV is too large 3 An EXTRAP NINENN analysis is automatically performed within GLORED analysis but the corresponding datasets have to be distinct this is automatically checked by OASIS3 at the beginning of the run 6 4 CHAPTER 6 THE TRANSFORMATIONS AND INTERPOLATIONS IN OASIS3 This transformation requires at least one configuration line with two parameters CORRECT operation SXMULT SNBFIELDS SXMULT is the multiplicat
111. y exchanges VERBOSE For more debugging information to the standard output from the mpp io library DEBUG The CPP key _DEBUG can also be activated for deadlock detection in clim and psmile librairies more debugging information in log files prt during the psmile library I Os in SCRIPR vector transformation for writing the resulting vertical component in the spherical coordinate system after interpolation to a file projection nc see section 6 4 To compile the PSMILe communication library without the I O functionality see section 5 3 i e to compile only empty routines in prism src lib mp pio key nol0 For compiling without linking the SCRIP library key noSCRIP Other platform dependent CPP keys that should be automatically activated on the corresponding platforms are defined and used in prism src lib m pp io include Linking with netCDF is mandatory when using SCRIPR transformations see section 6 4 CHAPTER 8 COMPILING AND RUNNING OASIS3 8 2 Running OASIS3 in coupled mode with TOYCLIM In order to test the OASIS3 coupler in a light coupled configuration CERFACS has written 3 toy com ponent models mimicking an atmosphere model toyatm an ocean model toyoce and a chemistry model toyche These toy component models are empty in the sense that they do not model any real physics or dynamics The coupled combination of these 3 toy component models through OASIS3 cou
112. y occur CHAPTER 5 THE OASIS3 CONFIGURATION FILE NAMCOUPLE 5 3 Second section of namcouple fi le The second part of the namcouple starting after the keyword SSTRINGS contains coupling information for each coupling or I O field Its format depends on the field status given by the last entry on the field first line EXPORTED IGNOUT or INPUT in the example above The field status may be the follow ing AUXILARY and EXPORTED are supported by all communication techniques while the others are supported only by the PSMILe i e the CLIM MPI1 orCLIM MPI2 communication technique e AUXILARY sent by the source model received and used by OASIS3 main process for the transfor mation of other fields e EXPORTED exchanged between component models and transformed by OASIS3 main process e EXPOUT exchanged transformed and also written to two output files one before the sending action in the source model below the prism put proto call and one after the receiving action in the target model below the prism get proto call e IGNORED exchanged directly between the component models without being transformed by OA SIS3 main process The grid and partitioning of the source and target models have to be identical e IGNOUT exchanged directly between the component models without being transformed by OA SIS3 main process and written to two output files one before the sending action in the source model below the prism put proto call and one a
113. yoce component to toyatm component at the coupling frequency dtF defined by the user in the configuring file namcouple As interpolation is needed between toyoce and toyatm grids this exchange must go through OASIS3 interpolation process In the namcouple Field field status must therefore be EX PORTED and the interpolation must be defined If the user wants the field to be also automatically written to files before being sent below the prism put and after being received below the prism_get he can choose the field status E X POUT In toyoce and toyatm codes the prism_put and prism_get routines are respectively called every timestep with an argument corresponding to the time at the beginning of the timestep The lag of Field defined as 4 hours 14400 seconds in the namcouple is automatically added to the prism_put time argument the prism put called at the toyoce timestep preceeding the coupling period therefore matches the prism_get called in toyatm at the coupling period At the beginning of the run i e at time 0 the toyoce prism put for Feld is not activated as a positive lag is defined for Field and OASIS3 automatically read Feld in its coupling restart file fldol nc and sends it to toyatm component after interpolation The different functions used to create the fields in the initial restart file are also indicated in table 8 1 They are defined as follows F 2 cos r x acos cos cos Fy 2 cos 0 cos 2 F3 2 sin

OASIS3 User Guide prism 2-5

Contents

Download Pdf Manuals

Related Search

Related Contents