Home

Report no 2 “OASIS3 User's Guide” 1 st ed

1. Proc 1 Proc 2 Proc 3 local offset 0 local offset 4 local offset 10 local size 4 local size 6 local size 5 Figure 1 Apple partition 3 2 1 Serial no partition This is the choice for a monoprocess model In this case we have ig paral 1 3 e ig paral 1 0 indicates a Serial partition e ig paral 2 0 e ig paral 3 the total grid size 3 2 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 1 1 indicates an Apple partition e ig paral 2 the segment global offset e ig paral 3 the segment local size Figure 1 illustrates an Apple partition over 3 processes PRISM Project Report 2 11 CERFACS TR CMGC 03 69 T EEN TT 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 2 Box partition 3 2 3 Box partition Each partition is a rectangu
2. Figure 7 Mix of LAF and SEQ concepts is 4 During a coupling timestep model B receives Fy and then sends FF its timestep length is 6 F and F coupling periods are both 12 By defining a LAG index of 8 for Fi the models will now run sequentially As the LAG for F is positive 6 a reading of F 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 performed initially and model B waits at time 8 a sending action is effectively performed below model A F prism put proto as 8 LAG 8 2 0 which is the first coupling timestep and matches the initial model B F 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 4 LAG 8 108 is a coupling period as the LAG is negative the field is not written to its coupling restart file Below the last model B F 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 it is important to indicate a sequence index In fact at each OASIS3 main process coupling timestep F is necessarily treated after F5 Therefore SEQ F1 2 and S EQ F 1 PRISM Project Report 2 23 CERFACS TR CMGC 03 69 First run
3. 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 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 or masks nc see section 6 1 The generic input line is as follows it GLORED operation NNBRLAT NVOISIN NIO NID where NNBRLAT is as for REDGLO see REDGLO description above The next 3 pa rameters refer to the EXTRAP NINENN extrapolation see EXTRAP NINENN descrip tion above The value assigned to all land points before interpolation is given by amskred in prism src mod oasis3 src blkdata f as for the VALMASK 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 PRISM Project Report 2 45 CERFACS TR CMGC 03 69 6 OASIS3 auxiliary data files OASIS3 needs auxiliary data files describing the grids of the models being coupled containing the fields coupling restart values or input data values as well as a number of other auxiliary data files used in specific transformations 6 1 Grid data files The grid of the models being coupled must be given by the user in grid data files These files can be all binary or all NetCDF
4. PRISM Report no 2 OASIS3 User s Guide ist ed Edited by Sophie Valcke Arnaud Caubel Damien Declat Laurent Terray OASIS3 Ocean Atmosphere Sea Ice Soil User s Guide August 2003 Sophie Valcke Arnaud Caubel Damien Declat Laurent Terray PRISM Project WP3a Leading partner C E R F A C S 42 avenue Coriolis 31057 TOULOUSE cedex 1 Abstract This User s Guide contains a detailed step by step description on how to realize a coupled simulation with OASIS3 The aim of OASIS3 is to provide a flexible and user friendly tool for cou pling independent general circulation models of the atmosphere and the ocean A O GCMs as well as models of the other climate components sea ice land atmospheric chemistry ocean biogeochemistry and regional models The re sulting coupled models are necessary tools to tackle current climatic paradigms such as the natural variability El Ni o Southern Oscillation ENSO or the greenhouse gas global warming effect OASIS3 synchronizes the exchanges of coupling fields between the models being coupled and performs 2D interpolations and transformations needed to express on the grid of the target model the coupling field produced by the source model on its grid Modularity and flexibility have been particularly emphasized in the OASIS3 design PRISM Project Report 2 3 CERFACS TR CMGC 03 69 PRISM Project Report 2 4 CERFACS TR CMGC 03 69 Contents 1 Overview of step by step u
5. 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 SUBTYPE SOLAR the operation performed is l ai l a where 9 F is the flux on the fine coarse grid a a 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 SUBTYPE 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 ar T where 9 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 2 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 interpolation 1 If the the SUBGRID operation is performed on a solar flux the 7 argument input line is PRISM Project Report
6. CGRDSRC CFLDTYP RESTRIC NBRBINS NORMA 0RDER where CMETHOD CONSERV CGRDSRC is the source grid type LR D and U are supported for 1st order remapping if the grid corners are given by the user in the grid data file which is in this case necessarily a netCDF file grids nc see section 6 1 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 CFLDTYP RESTRIC and NBRBINS are as for DISTWGT NORMA is the normalization option FRACAREA The sum of the source cell intersected areas is used to normalise each target cell field value the flux 1s not locally con served but the flux value itself is reasonable DESTAREA The total target cell area is used to normalise each target cell field value even if it only partly intersects the source grid cells PRISM Project Report 2 38 CERFACS TR CMGC 03 69 local flux conservation is ensured but unreasonable flux values may result FRACNNEI as FRACAREA except that the source nearest neighbour is used for target cells that do not intersect any unmasked source cells O0RDER FIRST or SECOND for first or second order remapping respec tively see SCRIP 1 4 documentation e INTERP INTERP gathers different techn
7. reading writing from to coupling restart files 3 7 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 7 the models perform their prism put proto and prism get proto calls exactly as in the first lag example above model A receives F and then sends Fi its timestep length PRISM Project Report 2 21 CERFACS TR CMGC 03 69 Model B ia pup oom del ueteri ddl nef Model A timestep 6 prism put proto prism get proto leading to sending receiving actions prism put proto prism get proto NOT leading to sending receiving actions Cpl period F1 12 LAG F1 0 SEQ F 1 Cpl period F2 12 LAG F2 0 SEQ F2 Cpl period F3 12 LAG F3 0 SEQ F3 Figure 6 The SEQ concept PRISM Project Report 2 22 CERFACS TR CMGC 03 69 Model B timestep 6 0 12 108 11 e LE ND Fi el rif Fi el rif q rif F2 rif rif j gg 8 p Js q g L 0 2 T67 116 120 Model A timestep 2 4 1 prism put proto prism get proto leading to writing reading to from coupling restart file Cpl period Fi 12 P prism put proto prism get proto leading to sending receiving actions Cpl_period F2 12 prism put proto prism get proto not leading to LAG F1 8 sending receiving actions LAG F2 6 SEQ F 2 SEQ F2 1
8. 2 43 CERFACS TR CMGC 03 69 it SUBGRID operation with SUBTYPE SOLAR CFILE NUMLU NID NVOISIN SUBTYPE CCOARSE CFINE where CFILE and NUMLU are the subgrid mapping file name and associated logical unit see section 6 4 for the structure of this file NID the identifi cator for this subgrid mapping dataset within the file build by OASIS based on all the different SUBGRID analyses in the present coupling NVOISIN is the maximum number of target grid points use in the subgrid mapping SUBTYPE SOLAR is the type of subgrid interpolation CCOARSE is the auxiliary field name on the coarse grid corresponding to a and CFINE 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 pro cess at least as AUXILARY fields This analysis is performed from the coarse grid with a grid mapping type of interpolation based on the CFILE file 2 If the the SUBGRID operation is performed on a nonsolar flux the 8 argument input line is SUBGRID operation with SUBTYPE NONSOLAR CFILE NUMLU NID NVOISIN SUBTYPE CCOARSE CFINE CDQDT where CFILE NUMLU NID NVOISIN are as for a solar subgrid interpo lation SUBTYPE NONSOLAR CCOARSE is the auxiliary field name on the coarse grid corresponding to T and CFINE is the auxiliary field name on fine grid corresponding to 7 the additional argument CDQDT is the cou pling ratio on the coarse
9. 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 tech niques have been historically developed The technique used for one particular run is defined by the user in the configuration file namcouple see section 4 In OASIS3 the CLIM communication technique based on MPI1 or MPI2 message passing is used To communicate with OASIS3 or directly between them or to perform I O actions the component models need to be interfaced with the PRISM System Model Interface library PSMILe which sources can be found in prism src lib psmile directory PSMILe supports e parallel communication between a parallel component model and OASIS3 main process e direct communication between parallel component models when no transforma tions are required e automatic sending and receiving actions at appropriate time 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 i Thitiahestion section 3 1 2 Partition definition section 3 2 3 I O coupling field declaration section 3 3 4 End of definition phase section 3 4 5 I O coupling field sending and receiving sec
10. 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 PRISM Project Report 2 30 CERFACS TR CMGC 03 69 toce locator prefix CHARACTER 4 for the source grid parameters in the grid data files see section 6 1 atmo locator prefix CHARACTER 4 for the target grid parameters in the grid data files see section 6 1 LAG 14400 optional lag index for the field expressed in seconds see section 3 7 SEQ 1 optional sequence index for the field expressed in seconds see section 3 7 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 transformati
11. also 6 F1 F3 and F5 coupling periods are both supposed to be equal to 12 For Fj and F the situation is similar to the first example If F F sending PRISM Project Report 2 20 CERFACS TR CMGC 03 69 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 waiting on a receiving action To prevent this F and F produced at the timestep before have to be used to match the model A and model B receiving actions which means that a lag of 6 must be defined for both F and F3 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 F sent by model A and received by model B no lag needs to be defined the coupling field produced by model 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 F5 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 F5 no coupling restart file is needed nor used as at each coupling period the coupling field produced by model can be
12. as follows REDGLO operation NNBRLAT CDMSK where NNBRLAT is NOxxx where xxx is half the number of latitude circles of the Gaussian grid For example for a T42 with 64 latitude circles NNBRLAT is NO32 In the current version it can be either NO16 NO24 NO32 NO48 NOS80 NO160 CDMSK is a flag indicating if non masked values have to be ex tended to masked areas before interpolation CDMSK SEALAND using the Re duced grid mask see section 6 1 or if the opposite has to be performed CDMSK LANDSEA If CDMSK NOEXTRAP then no extrapolation is performed e INVERT 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 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 CORLAT CORLON where CORLAT NORSUD or SUDNOR and CORLON ESTWST or WSTEST describes the orientation of the source field in longitude and latitude respectively PRISM Project Report 2 34 CERFACS TR CMGC 03 69 e MASK MASK routine masq f is used before the analysis EXTRAP A given REAL value VALMASK is assigne
13. configuring line is SCRIPR GAUSWGT CMETHOD CGRDSRC CFLDTYP RESTRIC NBRBINS NVOISIN VAR where all entries are as for DISTWGT except that CMETHOD GAUSWGT See the copyright statement in annexe B 19No particular treatment for vector interpolation is performed presently PRISM Project Report 2 37 CERFACS TR CMGC 03 69 VAR 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 propor tional to exp 1 2 d o where d is the distance between the source and target grid points and o V AR d where d 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 and the configuring line is SCRIPR BILINEAR or SCRIPR BICUBIC CMETHOD CGRDSRC CFLDTYP RESTRIC NBRBINS where CMETHOD BILINEAR or BICUBIC CGRDSRC is the source grid type LR or D CFLDTYP and NBRBINS are as for DISTWGT RESTRIC is as for DISTWGT except that only LATITUDE is possible for a Reduced D source grid CONSERV performs 1st or 2nd order conservative remapping which means that the weight of a source cell is proportional to area intersected by target cell The configuring line is SCRIPR CONSERV CMETHOD
14. equals the same integer number of coupling periods 1 LAG concept first example A first coupling algorithm exploiting the LAG concept is illustrated on figure 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 8With the PIPE SIPC GMEM and previously with the CLIM communication techniques no such analysis was performed For PIPE SIPC and GMEM the sending actions on the source side would automatically match the receiving actions on the target side on a FIFO First In First Out basis PRISM Project Report 2 18 CERFACS TR CMGC 03 69 Model B timestep 6 0 6 12 18 24 30 120 mU aio da Ll Mm ios n J F2 Fl F2 F2 Fl F2 Fl EN j ls F2 Fi f F2 FRETI CR e oh ar um i pp Model A timestep 4 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 i sending receiving actions Cpl_period F2 prism put proto prism get proto not leading to LAG F1 4 sending receiving actions LAG P2 Figure 4 LAG concept first example sending or receiving 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 ge
15. field name and initial date of the 1NIDATE This is supported only by the CLIM MPI1 MPI2 communication technique and its associated PSMILe 4 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 SOSST 182 P2P where the SST SISUTESU 1 86400 5 sstoc nc sstat nc EXPORTED 149 128 64 toce atmo LAG 14400 SEQ 1 0 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 3 3 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 def var proto in section 3 3 1 internal label used by OASIS3 for corresponding CF standard name see prism src mod oasis3 src inipar F 86400 coupling and or I O period for the field in seconds 5 number of transformations to be performed on this field 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 6 2 sstat nc name of the field output file required for NONE and PIPE com munication techniques only It may be a binary of netCDF file see section 6 2 EXPORTED field status e
16. files NetCDF examples can be found in prism util mod toyclim Cpl Grids 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 dimen sioned nbr_pts 1 where nbr pts is the total number of grid points l grids or grids nc contains the component model grid point longitudes and lati tudes 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 4 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 oasis3 src mod label F90 If the SCRIPR CONSERV interpolation is used for a grid the grid data file may contain longitudes and latitudes for model mesh corners as arrays dimensioned nx ny nc or nbr pts 1 4 where 4 is the number of corners in this case it must necessarily be a NetCDF file grids nc For Logically Rectangular LR grids the grid corners will be automatically approximately calculated if they are not given in grids nc 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 latitudes File grids or grids nc must be present with at lea
17. 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 input line is Sea Ice Extent FILLING operation CFILE NUMLU CMETHOD where CFILE is the file name for the global data set NUMLU the associated logical unit CMETHOD 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 respectively 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 5ea Surface Temperature FILLING operation without smoothing CFILE NUMLU CMETHOD NFCOAST where CFILE NUMLU are as for the SIE filling In this case however CMETHOD 1 3 RAW CMETHOD 4 6 SST and the last two characters define the time characteristics of the global data file as for the SIE filling NFCOAST is the flag for the calculation of the coastal correc
18. psmile 7 2 Running OASIS3 To run the toy coupled model which set up is in prism util mod toyclim first com pile OASIS3 and the toyclim component models toyatm toyoce toyche with MPI1 or MPI2 communication technique see above To start the run adapt the User In terface part of sc run toyclim and execute it For more details please read carefully the README toyclim therein To run OASIS3 in an interpolator only mode first compile OASIS3 with NONE as message passing and then execute prism util mod testinterp sc run testinterp For more details please read carefully the README testinterp therein PRISM Project Report 2 53 CERFACS TR CMGC 03 69 A The grid types for the transformations As described in section 5 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 5 4 e 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 CPER P and NPER 0 The latitudinal grid length is 180 NJ for a global grid 90 NJ otherwise The longitudinal grid length is 360 NI e B grid this is a regu
19. 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 the regional or and global fields The smoothing is defined by parameters in prism src mod oasis3 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 nnitb outermost point and nnite innermost point The parameter qalfa controls the weights given to the regional and to the global fields in the linear interpolation qalfa has to be 1 nslte nsltb or 1 nnltb nnlte For the outermost points nsltb or nnltb in the smoothing band the weight given to the regional and global fields will respectively be 0 and 1 for the innermost points nsite or nnite 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 nwlgmz the greater first dimension index of the lower coastline and nelgmz
20. the smaller first dimension index on the upper coastline The parameter gbeta 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 dimension smoothing bands will be calculated as for the second dimension The user must provide the climatological data file with a specific format described in 6 4 When one uses FILLING for 5ST 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 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 PRISM Project Report 2 A CERFACS TR CMGC 03 69 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 mis match 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
21. 3 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 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 12Note that even if the grid auxiliary data files are in NetCDF format the restart coupling files may be in binary format or vice versa PRISM Project Report 2 AT CERFACS TR CMGC 03 69 dimension except for fields given on 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 The shape and orientation of each restart field and of the corresponding coupling fields exchanged during the simulation must be coherent with the shape of its grid data arrays The only exception is for A B G L Z or Y grids for which the field may be oriented from North to South and or from East to West in which case INVERT transformation will have to be used see section 5 3 In the NetCDF restart files the field arrays must have the source symbolic name indicated in the namcouple see section 4 3 1 In binary restart file each field is wri
22. AL IN I O or coupling field array info INTEGER OUT returned info code i e x 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 transforma tion not sent not output PRISM_ToRest 6 if the field was written to a restart file only PRISM Output 7 if the field was written to an output file only PRISM SentOut 8 if the field was both written to an output file and sent to another model directly or via OASIS3 main process 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 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 3 7 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 4 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 nam couple INSTANT AVERAGE ACCUMUL T MIN or T MAX see section 5 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 3 7 the OASIS3 restart file see
23. GRDSRC CFLDTYP NID NVOISIN NIO where CMETHOD SURFMESH CGRDSRC and CFLDTYP are as for BILINEAR HI CONSERV SECOND has not been tested in detail PRISM Project Report 2 39 CERFACS TR CMGC 03 69 NID is the identificator for the weight address dataset in all the different INTERP SURFMESH datasets in the present coupling This dataset will be calculated by OASIS3 if NIO 1 or only read if NIO 0 NVOISIN is the maximum number of source grid meshes used in the remapping GAUSSIAN routines in prism src lib anaisg is a gaussian weighted nearest neighbour interpolation technique The user can choose the variance of the function and the number of neighbours considered The configuring line is GAUSSIAN interpolation CMETHOD CGRDSRC CFLDTYP NID NVOISIN VAR NIO where x CMETHOD GAUSSIAN CGRDSRC and CFLDTYP are as for the BILINEAR interpolation NIDis 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 OASIS3 if NTO 1 or only read if NIO 0 NVOISIN is the number of neighbours used in the interpolation VAR is as for SCRIPR GAUSWGT see above 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 ar
24. IS3 main process and written to an out put 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 x 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 1s 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 3 5 3 Auxiliary routines e CALL prism_put_inquire var_id date info 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 info INTEGER OUT returned info code This routine may be called at any time to inquire what would happen to the cor responding 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 PRISM Project Report 2 16 CERFACS TR CMGC 03 69 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 t
25. LAG F1 8 Q A2 8 B 120 Model B LAG F2 6 uoce on E M SEQ F1 2 Restart SEQ F2 1 Recan file F2 E E file F1 is Ja mf el Fi 0 78 o 12 12 16 116 120 cid 0 6 12 18 120 YA TA Tl q v Model B Next runs Restart 4 E al fr gl Fl p LAG F1 4 file Fl LAG F2 6 SEQ F1 1 Restart i F SEQ F2 1 file F2 Vi gl Jel A p Model A 8 1246 prism put proto prism get proto leading gt prism put proto prism get proto not to writing reading to from restart file leading to sending receiving actions prism put proto prism get protoleading gt gt prism put restart leading to writing to to sending receiving actions coupling restart file Figure 8 An example using prism put restart proto 3 7 4 An experiment mixing sequential and parallel coupled model runs the use of prism put restart proto In the example illustrated on figure 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 3 7 3 After the first run the situation is similar to the one of section 3 7 1 and positive LAG must be defined for F and F5 As their lag is positive their corresponding first prism get proto will automatically lead to reading F and F from coupling restart files In this case model A has to write F to its restart file explicitly by calling prism put restart proto illu
26. Reiner Vogelsang from Silicon Graphics GmbH With MPII this call is mandatory for parallel models with MPI2 the communicator MPLCOMM_WORLD will be returned as local communicator 3 2 Partition definition When a component of the coupled system is a parallel code each coupling field is usu ally scattered among the different processes With the PSMILe library each process sends directly its partition to the OASIS3 main process or directly to the other com ponent model if no transformation nor repartition 1s required To do so each process implied in the coupling has to define its local partition in the global index space 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 partition in the global index space ierror INTEGER OUT returned error code The vector of integers describing the process local partition argument ig paral of prism def partition proto has a different expression depending on the type of the partition In OASIS3 4 types of partition are supported Serial no partition Apple Box and Orange The model may call MPLInit 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 terminate proto PRISM Project Report 2 10 CERFACS TR CMGC 03 69
27. T INT 1 Field COSENHFL SOSENHFL 37 86400 1 flda3 nc IGNOUT LAG 7200 SEQ 1 LOCTRANS AVERAGE Field 4 SOALBEDO SOALBEDO 17 86400 0 SOALBEDO nc INPUT TERERERETERERETERETETERE RETE RETERERERETERERERETERERERETERERETERERERETERERERETETRERETERERETEREIERETETERERETERERETEERE EHI GE IE E UE 4 2 First section of namcouple file 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 SEQMODE On the line below this keyword is the maximum number of fields that have to be at one particular coupling timestep necessarily exchanged sequen tially 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 3 7 e CHANNEL On the line below this keyword is the communication technique chosen Choices are MPI1 or MPI2 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 5 1 PIPE SIPC 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 CHANNEL are e g for 3 models CHANNEL MPI2 1 1 argi 3 1 arg2 3 1 arg3 where MPI2 is the message passing used in CLIM and PSMILe and the follo
28. TEGER iadress jpnb jpo REAL weight jpnb jpo OPEN unit 90 file at31topa form unformatted WRITE clweight WEIGHTS 1I1 knumb WRITE cladress ADRESSE I1 knumb WRITE 90 cladress WRITE 90 iadress WRITE 90 clweight WRITE 90 weight where e jpnb is the maximum number of neighbors used in the transformation NVOISIN in the namcouple e jpo is the total dimension of the target grid e at31topa is the name of the grid mapping data file CFILE in namcouple e knumb is the identificator of the data set NID in namcouple PRISM Project Report 2 49 CERFACS TR CMGC 03 69 e cladress is the locator of the address dataset e clweight is the locator of the weight dataset e iadress i j is the address on the source grid of the neighbor used for the mapping of the 7 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 2 neighbor used for the transformation of the 7 target grid point For file nweights there is an additional brick composed of a CHARACTER 8 vari able 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 6 4 2 Auxiliary data files for FILLING For the FILLING analysis the global data set used ca
29. TRANS can be chosen as first transformation if CLIM MPII MPI2 communica tion and the PSMILe interface are used LOCTRANS requires one configuring line on which a time transformation automatically performed below the call to PSMILe prism_put_proto should be indicated e INSTANT no time transformation the instantaneous field is transferred e ACCUMUL the field accumulated over the previous coupling period is transferred e AVERAGE the field averaged over the previous coupling period is transferred PRISM Project Report 2 33 CERFACS TR CMGC 03 69 e T MIN the minimum value of the field for each source grid point over the previous coupling period is transferred e T MAX the maximum value of the field for each source grid point over the previous coupling period is transferred e ONCE only one prism put proto or prism get proto will be performed this is equivalent to giving the length of the run as coupling or I O period 5 3 The pre processing transformations The following transformations are available in the pre processing part of OASIS3 con trolled by preproc f e REDGLO not recommended anymore as interpolations now exist directly for Reduced grids 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 trans formation performed The configuring line is
30. _Double are valid for var_type No automatic conversion is implemented therefore all coupling fields exchanged through OASIS3 main process must share the same kind ierror INTEGER OUT returned error code 3 4 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 3To exchange single precision coupling fields OASIS3 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 and var type must be PRISM Real 4Coupling fields exchanged directly between two component models stil have to be either PRISM Real or PRISM Double but can have a kind different from the ones exchanged through OASIS3 main process as long as 1t 1s the same in both models PRISM Project Report 2 14 CERFACS TR CMGC 03 69 3 5 Sending and receiving actions 3 5 1 Sending a coupling field 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 corresponding prism def var proto date INTEGER IN number of seconds in the run at the beginning of the timestep field_array RE
31. ading 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 LAG F1 6 sending receiving actions LAG F2 6 LAG F3 0 Figure 5 LAG concept second example time 18 by model B then leads to a sending action as 18 6 24 which is a coupling period that matches the receiving 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 F 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 F having a lag greater than 0 is automatically written to its coupling restart file below the last F prism put proto if the date F lag equals a coupling time The analogue is true for Fy 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 5 During its timestep model A receives F5 sends F3 and then F3 its timestep length is 6 During its timestep model B receives F receives F3 and then sends F its timestep length is
32. ads 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 This transformation requires at least one configuration line with two parameters it CORRECT operation XMULT NBFIELDS where XMULT is the multiplicative coefficient of the current field and NBFIELDS the number of additional fields to be combined with the current field For each additional field an additional configuring line is required nbfields lines CLOC AMULT CFILE NUMLU where CLOC and AMULT CFILE and NUMLU 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 6 2 5 4 The interpolation The following interpolations controlled by interp f are available in OASIS3 e BLASOLD BLASOLD routine blasold f performs a linear combination of the current cou pling 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 PRISM Project Report 2 36 CERFACS TR CMGC 03 69 it BLASOLD operation XMULT NBFIELDS where XMULT is the multiplicative coefficient of the current field and NBFIELDS the number of additional fields to be com
33. al extent Figure 3 illustrates an Orange partition with 3 segments for one process The other process partitions are not illustrated PRISM Project Report 2 13 CERFACS TR CMGC 03 69 3 3 I O coupling field 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 ierror 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 INTEGER DIMENSION 2 IN var nodims 1 is the rank of field array 1 or 2 var nodims 2 is the number of bundles always 1 for OASIS3 kinout INTEGER IN PRISM In for fields received by the model or PRISM_0ut 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 array 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 i e PRISM_Real or PRISMDouble PRISM 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 In this case both PRISM_Real or PRISM
34. atement reads as follows Copyright 1997 1998 the Regents of the University of California This software and ancillary information 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 indicated 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 SOFTWARE without charge provided 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 PRISM Project Report 2 56 CERFACS TR CMGC 03 69 References 1 http www acl lanl gov climate software SCRIP scrip frames htm 2 http www gfdl gov vb mpp io html PRISM Project Report 2 oT CERFACS TR CMGC 03 69
35. bined with the current field For each additional field an additional input line is required nbfields lines CNAME AMULT where CNAME and AMULT are the symbolic name and the multiplicative coeffi cient for the additional field To add a constant value to the original field put XMULT 1 NBFIELDS 1 CNAME CONSTANT AMULT value to add e SCRIPR SCRIPR is new in OASIS3 and gathers the interpolation techniques offered by Los Alamos National Laboratory SCRIP 1 4 library 1 SCRIPR routines are in prism src lib scrip For more details see also the SCRIP 1 4 documentation in prism src mod oasis3 doc SCRIPusers pdf Linking with NetCDF library is mandatory when using SCRIPR interpolations The following types of interpolations are available DISTWGT performs N nearest neighbour interpolation N neighbours All grid types are supported The configuring line is SCRIPR DISWGT CMETHOD CGRDSRC CFLDTYP RESTRIC NBRBINS NVOISIN where CMETHOD DISTWGT CGRDSRC is the source grid type LR D or U see annexe A CFLDTYP is the field type SCALAR or VECTOR RESTRIC is the search restriction type LATLON or LATITUDE see SCRIP 1 4 documentation NBRBINS the number of restriction bins see SCRIP 1 4 documentation B NVOISIN is the number of neighbours used GAUSWGT performs N nearest neighbour interpolation weighted by a gaussian function All grid types are supported The
36. c namcouple can be found in directory prism util mod toyclim Cp1l Nam 4 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 COSENHFL is exchanged directly from the atmosphere to the atmospheric chemistry and one field SOALBEDO is read from a file by the ocean HERRERA RARO RR ROA RR RRA RARA ARRE RRA RARO RR ERE RR RARA RARO RAR RRA ERE ERE EREIEREIEREIE EIE UE First section SEQMODE 1 CHANNEL MPI2 1 1 argi 3 1 arg2 3 1 arg3 NFIELDS PRISM Project Report 2 25 CERFACS TR CMGC 03 69 4 JOBNAME JOB NBMODEL 3 ocemod atmmod chemod 55 70 99 RUNTIME 432000 INIDATE 00010101 MODINFO NOT NLOGPRT 2 CALTYPE 1 PERERA ARAHAL RARA RAR RAR RARA RARA RRA RARA RARA RARA RARA Second section STRINGS Field 1 SOSSTSST SISUTESU 1 86400 5 sstoc nc EXPORTED 182 149 128 64 toce atmo LAG 14400 SEQ 1 P2P0 LOCTRANS CHECKIN MOZAIC BLASNEW CHECKOUT AVERAGE INT 1 at3itopa 91 2 48 CONSTANT 273 15 INT 1 Field 2 CONSFTOT SOHEFLDO 6 86400 7 flxat nc EXPORTED atmo toce LAG 14400 SEQ 1 POP2 LOCTRANS CHECKIN SCRIPR CHECKOUT PRISM Project Report 2 26 CERFACS TR CMGC 03 69 ACCUMUL INT 1 CONSERV LR SCALAR LATLON 10 FRACAREA FIRS
37. cond section of namcouple for EXPORTED AUXILARY and EXPOUT Held aco BO we ae DIM etc an ap e toto dios SB toan de 30 4 3 2 Second section of namcouple for IGNORED and IGNOUT fields 31 4 3 3 Second section of namcouple for INPUT fields 31 4 3 4 Second section of namcouple for OUTPUT fields 32 5 The transformations and interpolations in OASIS3 33 5 1 Using OASIS3 in the interpolator only mode 33 5 2 The time transformations 2 Gus o as ida 33 5 3 The pre processing transformations a 34 5 4 The interpolation aaa tee ete ar key ar Ret RR OR ARRA A 36 5 5 The cooking stage iud ceto dou dos uot et dee the un 43 5 6 The post processing ns 4 4 6 5 eR a Soa edd Sw ee AC RR 44 PRISM Project Report 2 5 CERFACS TR CMGC 03 69 6 OASISS3 auxiliary data files 46 Gal Xd data Mes chr tt DA tL a I ce D ts sb RA A 46 6 2 Coupline restart Tes uno hah oen ARR oA Ue e dnce ow SO AT 6 3 Input daba files 4 uuo TS AS AA dE 48 6 4 Transformation auxiliary data files 48 6 4 1 Auxiliary data files for EXTRAP NINENN EXTRAP WEIGHT INTERP SURFMESH INTERP GAUSSIAN MOZAIC and SUBGRID 49 6 4 2 Auxiliary data Mes dor FILLING uh oum UE 50 6 4 3 Auxiliary data files for SCRIPR 2 o noo Rus 51 7 Compiling and running with OASIS3 52 7 1 Compiling OASIS3 and the toy coupled model 52 T2 a QI ioe a Bedi bs E ur amp Beer a he Sr as 53 A The grid type
38. coupling field in the configuration file namcouple different coupling algorithms can be reproduced without modifying anything in the component model codes themselves The lag and sequence con cepts 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 3 7 1 The lag concept If no lag index or if a lag index equal to 0 1s 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 To match a prism put proto called by the source model at a particular date with a prism get proto called by the target model at a different date the user has to define in the namcouple an appropriate lag index LAG for the coupling field see section 4 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 periods This sending action is automatically matched on the target side with the receiving action performed when the prism get proto date argument
39. d PSMILe IGNORED exchanged directly between the component models without being trans formed by OASIS3 main process The grid and partitioning of the source and target models have to be identical This is supported only by the CLIM MPI1 MPI2 communication technique and its associated PSMILe IGNOUT exchanged directly between the component models without being trans formed by OASIS3 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 after 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 This is supported only by the CLIM MPI1 MPI2 communication technique and its associated PSMILe 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 pe riod indicated by the user in the namcouple This is supported only by the CLIM MPI1 MPI2 communication technique and its associated PSMILe 5ee sec tion 6 3 for the format of the input file PRISM Project Report 2 29 CERFACS TR CMGC 03 69 e OUTPUT simply written out to an output file by the source model PSMILe below the riod per run prism put proto call at appropriate times corresponding to the output pe indicated by the user in the namcouple The name of the output file one field is automatically built based on the
40. d to all masked points following the source grid mask see section 6 1 so they can be detected by EXTRAP The generic input line is as follows it MASK operation VALMASK Problems may arise if the value chosen approaches the maximum value that your computing 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 unstruc tured U grids see section 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 CMETHOD NINENN CMETHOD NVOISIN NIO NID where CMETHOD NINENN NVOISIN is the minimum number of neighbours re quired to perform the extrapolation with a maximum of 4 NIO is the flag that indicates if the weight address and iteration number dataset will be calcu lated and written by OASIS3 NIO 1 or only read NIO 0 in file nwezghts see section 6 4 NID is the identificator for the weight address iteration number dataset in all the different EXTRAP NINENN datasets in the present coupling With CMETHOD WEIGHT an N weighted neighbour
41. directly consumed by model B We see here how the introduction of appropriate LAG indices results in receiving below the prism get proto in the 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 3 7 2 The sequence concept To exchange the coupling fields going through OASIS3 main process i e with status EXPORTED AUXILARY or EXPOUT see section 4 in a given order at each cou pling 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 6 All cou pling 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 PF must be received by model A be fore it can send 75 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 Fz and F As all fields can be consumed at the time they are produced LAG 0 for all fields there no
42. e Then a description of each transformation with its corresponding config uring lines is given 5 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 OASIS3 in this mode before hand to test different transformations and interpolations 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 namcou ple as indicated in sections 4 2 and 4 3 In particular NONE has to be chosen below the keyword CHANNEL and 0 without any model name and Fortran unit number below the keyword NBMODEL Finally the fields to transform and interpolate have to be present in their coupling restart file 6th entry on the first line After their trans formation OASIS3 writes them to their output file which name is the 7th entry on the first line Note that in the interpolator only mode OASIS3 may treat different fields but only one temporal instance for each A practical example on how to use OASIS3 in a interpolator only mode is given in prism util mod toymodel testscrip 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 5 2 The time transformations LOC
43. e defined by the user in a file see section 6 4 The configuring line is it MOZAIC operation CFILE NUMLU NID NVOISIN where CFILE and NUMLU are the grid mapping file name and associated logical unit on which the grid mapping dataset is going to be read NID the identificator for this grid mapping dataset in all MOZAIC grid mapping datasets in the present coupling NVOISIN is the maximum number of target grid points use in the mapping 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 PRISM Project Report 2 40 CERFACS TR CMGC 03 69 e FILLING FILLING routine prism src mod oasis3 src filling f performs the blend ing of a regional data set with a climatological global one for a Sea Surface Tem perature 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
44. eed extra help do not hesitate to contact us oa sishelp cerfacs fr In OASIS3 the PIPE SIPC and GMEM communication techniques should still work but are not maintained anymore and were not tested PRISM Project Report 2 7 CERFACS TR CMGC 03 69 2 Obtaining OASIS3 sources 2 1 The OASIS3 package OASIS3 and all related libraries are available on CERFACS CVS server elnino cerfacs fr The repository is home valcke PRISMCVS To obtain the CVS login and password as well as the most recent OASIS3 tag please contact us oasishelp cerfacs fr OASIS3 directory structure follows the PRISM standard one prism src mod oasis3 src OASIS3 main code doc OASIS3 documentation toyatm toy model code 1 toyoce toy model code 2 toyche toy model code 3 prism src lib anaisg GAUSSIAN interpolation library anaism SURFMESH interpolation library clim CLIM MPI1 MPI2 communication library fscint INTERP interpolation library pipe CRAY PIPE communication library not maintained anymore psmile PRISM System Model Interface Library scrip SCRIPR interpolation library sipc svipc SIPC communication library not maintained anymore sxgmem GMEM communication library not maintained anymore prism util mod toyclim a toy coupled model environment testinterp an environment to test OASIS3 in the interpolator only mode PRISM Project Report 2 8 CERFACS TR CMGC 03 69 3 Interfacing a model with the PSMILe library
45. 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 extrap olation the structure of this file has to follow the OASIS3 generic structure for transformation auxiliary data files see section 6 4 The configuring line is EXTRAP operation for CMETHOD WEIGHT CMETHOD NVOISIN CFILE NUMLU NID For some grids the extrapolation may not converge if NVOISIN is too large An EXTRAP NINENN analysis is automatically performed within GLORED analysis but the corre sponding datasets have to be distinct this is automatically checked by OASIS3 at the beginning of the run PRISM Project Report 2 35 CERFACS TR CMGC 03 69 where CMETHOD WEIGHT NVOISIN is the maximum number of neighbours required by the extrapolation operation CFILE and NUMLU 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 transformations 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 it CHECKIN operation NINT where NINT 1 or 0 depending on whether or not the source field integral is also calculated and printed e CORRECT CORRECT routine correct f re
46. grid corresponding to oF 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 e BLASNEW BLASNEW routine prism src mod oasis3 src blasnew f performs a linear combination of the current coupling field with any other fields after the interpo lation These 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 5 6 The post processing The following analyses are available in the post processing part of OASIS3 controlled by prism src mod oasis3 src postpro f e REVERSE REVERSE routine prism src mod oasis3 src reverse f reorders a field PRISM Project Report 2 44 CERFACS TR CMGC 03 69 This analysis requires the same input line as INVERT with CORLON and CORLAT being now the resulting orientation REVERSE does not work for U and D grids see annexe A e CHECKOUT CHECKOUT routine prism src mod oasis3 src chkfld f calculates the mean and extremum values of an output field and prints them to the coupler output cploul The generic input line is as for CHECKIN e GLORED not recommended as coupling fields can be directly interpolated to a target Reduced grid if needed
47. he 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 consum ing and should be avoided if the field is not effectively used below the prism put proto e CALL prism put restart var id date 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 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 6 2 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 3 6 Termination e CALL prism terminate proto ierror ierror INTEGER OUT returned error code Each process must terminate the coupling by calling prism terminate proto normal ter
48. ield must be given is an array restartdata nx ny where nx and ny are the global Gaussian grid dimensions and the Reduced field 1s completed by trailing zeros PRISM Project Report 2 48 CERFACS TR CMGC 03 69 6 4 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 transfor mations have a similar structure their names are given in Table 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 SURFMESH interpolation gweighls weights and addresses for INTERP GAUSSIAN interpolation any name weights and addresses for MOZAIC interpolation any name weights and addresses for SUBGRID interpolation Table 1 Analysis auxiliary data files The files nweighls mweighls and gweighls can be created by OASIS3 if their cor responding NIO 1 see EXTRAP NINENN INTERP SURFMESH INTERP GAUSSIAN in sections 5 3 and 5 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 5 3 and 5 4 and 5 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 clweight IN
49. iques of interpolation controlled by routine fiasco f The following 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 fscint and support only A B G L Y or Z grids see annexe A The configuring line is as follows BILINEAR or BICUBIC or NNEIBOR interpolation CMETHOD CGRDSRC CFLDTYP where CMETHOD BILINEAR BICUBIC or NNEIBOR CGRDSRC is the source grid type A B G L Y or Z see annexe A CFLDTYP 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 anaism is a first order conservative remapping from a fine to a coarse grid the source grid must be finer over the whole domain and supports only Lat Lon grids For a target grid cell all the underlying source grid cells are found and the target grid field value is the sum of the source grid field values 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 CMETHOD C
50. l records in each direction This grid is periodical CPER P with NPER overlapping grid points e Y grid this grid is like Z grid except that it is regional CPER R and NPER 0 2 Grids supported for the SCRIPR interpolations e 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 PRISM Project Report 2 54 CERFACS TR CMGC 03 69 e U grid Unstructured U grids do have any particular structure The longitudes and the latitudes of 2D Unstructured grid points must be de scribed by two arrays longitude nbr_pts and latitude nbr pts where nbr pts is the total grid size e D grid The Reduced D grid is composed of a certain number of lati tude 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 PRISM Project Report 2 55 CERFACS TR CMGC 03 69 B The SCRIP 1 4 copyright statement The SCRIP 1 4 copyright st
51. lar 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 pole 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 CPER 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 e G grid this is a irregular Lat Lon Gaussian grid covering either an hemi sphere 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 CPER P and NPER 0 The longitudinal grid length is 360 NI e 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 e Z grid this is a Lat Lon grid with non constant latitudinal and longi tudinal 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 positiona
52. lar region of the global domain described by the global off set 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 e ig paral 1 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 2 illustrates a Box partition over 3 processes 3 2 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 PRISM Project Report 2 12 CERFACS TR CMGC 03 69 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 3 Orange partition for one process e ig paral 1 3 indicates a Orange partition e ig paral 2 the total number of segments for the partition e ig paral 3 the first segment global offset 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 loc
53. le for OUTPUT fields The first two lines for fields with status OUTPUT is SYMBNAME SYMBNAME 99 86400 0 OUTPUT LAG 0 where the different entries are e SYMBNAME symbolic name for the field in the source model CHARACTER 8 repeated twice e 99 OASIS3 internal label e 86400 output period in seconds e 1 number of transformations 0 or 1 for LOCTRANS e OUTPUT field status Note that a second line is mandatory put at least LAG 0 The third line is LOCTRANS if this transformation is chosen for the field Note that LOCTRANS is the only transformation supported for 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 PRISM Project Report 2 32 CERFACS TR CMGC 03 69 5 The transformations and interpolations in OA SIS3 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 only pre processing interpola tion cooking and post processing This order of precedence is conceptually 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 mod
54. mination e CALL prism abort proto compid routine name abort message compid INTEGER IN component model ID from prism init comp proto routine name IN name of calling routine abort message IN message to be written out 5If the process called MPI_Init before calling prism init comp proto it must also call MPI_Finalize explicitly but only after calling prismterminate_proto PRISM Project Report 2 17 CERFACS TR CMGC 03 69 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 3 7 Coupling algorithms SEQ and LAG concepts Using PSMILe library the user has full flexibility to reproduce different coupling al gorithms without modifying the component model codes themselves In the com ponent codes the sending and receiving routines respectively prism put proto and prism get proto can be called at each model timestep with the appropriate date ar gument giving the actual time at the beginning 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 in dices LAG and SEQ chosen by the user for each
55. munication technique will be used CLIM MPI2 by default use comm MPI CLIM MPI2 for OASIS3 and PSMILe or use comm MPII CLIM MPII for OASIS3 and PSMILe or use comm NONE no communication technique for OASIS3 interpolator only mode e Other pre compiling keys for the PSMILe I O library routines in prism lib mpp io use netCDF mandatory use libMPI mandatory use LAM MPI if LAM MPI version is used The following keys are also available but not activated in those compiling scripts 14Use the standard blocking send MPI Send if the coupling fields are necessarily sent and re ceived in the same order or on architectures on which MPI Send is implemented with a mail box e g VPPs in this second case make sure that the size of the mailbox is sufficient Use the less efficient buffered send MPI BSend on architectures on which MPI Send is not im plemented with a mailbox e g NEC SX5 if the coupling fields are not sent and received in the same order This pre compiling option affects prism src lib clim src CLIM Export F and prism src lib psmile src mod prism put proto F90 PRISM Project Report 2 52 CERFACS TR CMGC 03 69 e use realtype single to exchange single precision REAL variables as coupling fields see section 3 3 e key noIOfor compiling PSMILe without compiling the I O library i e routines in prism src lib mpp io and mod psmile io F90 and mod psmile io interfaces F90 in prism src lib
56. n be either interannual monthly climatological monthly or yearly see 5 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_year_01 jpi jpj WRITE NLU fil field_january_year_01 WRITE NLU fil field february year 01 WRITE NLU fil field march year 01 etc WRITE NLU fil field december year 01 C C if climatology one stops here C WRITE NLU fil field january year 02 etc where e field is the global dataset e jpi and jpj are the dimensions of the 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 namcouple 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 PRISM Project Report 2 50 CERFACS TR CMGC 03 69 6 4 3 Auxiliary data files for SCRIPR The NetCDF files containing the weights and addresses for the SCRIPR remappings see section 5 4 are automatically generated at runtime by OASIS3 Their struc ture is described in detail in section 2 2 3 of the SCRIP documentation available in prism src mod oasis3 doc SCRIPusers pdf PRISM Project Report 2 51 CERFACS TR CMGC 03 69 7 Compiling and running with OASIS3 7 1 Compiling OASIS3 and the toy coupled m
57. ndicate 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 CHANNEL is NONE NBMODEL has to be 0 and there should be no model name and no unit number e RUNTIME On the line below this keyword is the total simulated time of the run expressed in seconds e INIDATE 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 MODINFO For SIPC and GMEM techniques only the line below this keyword indicates if a header is encapsulated in the binary coupling restart file see section 6 2 it can be YES or NOT e NLOGPRT The line below this keyword refers to the amount of information that will be written to the OASIS3 log file cplout during the run 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 PRISM Project Report 2 28 CERFACS TR CMGC 03 69 4 3 CALTYPE This new keyword gives the type of calendar used For now the calendar type is important only if FILLING analy
58. odel OASIS3 uses the PRISM standard directory structure and compiling environment To compile OASIS3 execute the script COMP_oasis3 in prism src mod oasis3 This script automatically executes COMP_libs_oasis3 in prism util which compiles ap propriate libraries in prism src lib A practical example of a toy coupled model using OASIS3 and PSMILe with the CLIM MPI1 or MPI communication technique is given in prism util mod toyclin To compile its different components execute the scripts COMP_toyatm COMP_toyoce COMP_toyche in prism src mod toyatm toyoce or toyche respectively To compile OASIS3 and the toyclim components on another platform than those already included adapt the parts user specifications and configurable specification of those scripts OASIS3 and the toy coupled model have been compiled and success fully run on Fujitsu VPP5000 NEC X5 SGI Octane and 03000 COMPAQ Alpha cluster and Linux PC cluster In the user specifications part of those scripts the user has to indicate in par ticular his choice of message passing MPI1 MPI2 or NONE For MPI1 and MPI2 one also as to indicate whether or not the buffered MPI_BSend should be used to send the coupling fields instead of a standard blocking send MPI_Send use_key_BSend BSend or NoBSend This will activate or not the pre compiling key key_BSend Other pre compiling keys are automatically activated by those compiling scripts e To indicate which com
59. on These additional lines are described in more details in the section 5 4 3 2 Second section of namcouple for IGNORED and IGNOUT fields The first 2 lines for fields with status IGNORED and IGNOUT fields are as follows COSENHFL SOSENHFL 37 86400 1 flda3 nc IGNOUT LAG 7200 SEQ 1 where the different entries are as for EXPORTED fields except that there is no output file name on the first line and that there are no locator prefix on the second line Note that a second line is mandatory put at least LAG 0 The third line is LOCTRANS if this transformation is chosen for the field Note that LOCTRANS is the only transformation supported for IGNORED and IGNOUT 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 4 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 where the different entries are e SOALBEDO symbolic name for the field in the target model CHARACTER 8 repeated twice e 17 OASIS3 internal label PRISM Project Report 2 31 CERFACS TR CMGC 03 69 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 6 3 e INPUT field status 4 3 4 Second section of namcoup
60. s for the transformations 54 B The SCRIP 1 4 copyright statement 56 PRISM Project Report 2 6 CERFACS TR CMGC 03 69 1 Overview of step by step use of OASIS3 To use OASIS3 for coupling models and or perform I O actions one has to follow these steps ike 2 Obtain OASIS3 sources section 2 Identify the coupling or I O fields and adapt the component models to allow their exchange with the CLIM communication technique and its associated PSMILe library based on MPI or MPI2 message passing The PSMILe library is in terfaced with the mpp io library from GFDL 2 and therefore can also be used to perform I O actions from to disk files A practical example of a toy coupled model is given in the prism util mod toyclim directory Section 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 sections 4 and 5 OASIS3 supports more interpolation algorithms for more different grids than before as it is now interfaced with the SCRIP 1 4 library 1 see appendix B Generate required auxiliary data files section 6 Compile OASIS3 the component models and start the coupled experiment sec tion 7 The toy coupled model in prism util mod toyclim has been successfully run on on Fujitsu VPP5000 NEC X5 SGI Octane and 03000 COMPAQ Alpha cluster and Linux PC cluster If you n
61. se of OASIS3 7 2 Obtaining OASIS3 sources 8 2l The OASISS package usas 3409 03 3e RES eS a eS ey 8 3 Interfacing a model with the PSMILe library 9 Jd intra lisas loro bl Bate a ds we meg EU A v X109 404 10 al Partition demon Lusso Pese docete CK dre ac ge ee NGPA Re 10 3 2 1 Serial no partition 5 quete E 11 lee Apple partos Para eb Geet dee ee E EROR SE ER E 11 du Box partitions saya s a iere a So i s Rex e amp Gide 2 12 J24 Orange partition 4g i ede oon E dete UE Gy EE iN 12 3 3 I O coupling field declaration ddr abra CHE os et rr 14 3 4 End of definition phase eii A 14 3 5 Sending and receiving actions 44 2 wok ee we a 15 3 5 1 Sending a coupling field 52 s oss s 15 3 5 2 Receiving a coupling field ngo Ree EROS S 16 3 5 3 Auxiliary routines Goel a Bt ae AE A AE 16 9 0 Terminaline tele Dato ak Dag a a ae a Lag ae eh E a es 17 3 7 Coupling algorithms SEQ and LAG concepts 18 S Thelag concept cu a sadra but a e eeu ge A ty dee Ingo s 18 3 4 4 The sequence concept 2 22 21 3 1 3 A mix of lag and sequence the sequential coupled model 21 3 7 4 An experiment mixing sequential and parallel coupled model runs the use of prism_put_restart_proto 24 4 The OASIS3 configuration file namcouple 25 4 1 An example of a simple namcouple ee 25 4 2 First section of namcouple file o a aa aa 27 4 3 Second section of namcouple fle corr 29 4 3 1 Se
62. section 6 2 is now 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 standard blocking send MPI Send by default as before or the buffered MPI BSend if pre processed with CPP flag key BSend to send the coupling fields see section 7 PRISM Project Report 2 15 CERFACS TR CMGC 03 69 3 5 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 used 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 OASIS3 main process x 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 OAS
63. sis 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 1s not a leap year furthermore if it can be divided by 4 100 and 400 it 1s a leap year n n gt 1 day month calendar Second section of namcouple file The second part of the namcouple starting after the keyword STRINGS contains cou pling 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 AUXILARY sent by the source model received and used by OASIS3 main process for the transformation of other fields this choice is supported for all communi cation techniques EXPORTED exchanged between component models and transformed by OASIS3 main process this choice is supported for all communication techniques 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 this is supported only by the CLIM MPI1 MPI2 communication technique and its associate
64. st 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 GAUSSIAN 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 GAUSSIAN it is not required otherwise 4 maskr or maskr nc this file contains Reduced D grid mask in INTEGER arrays dimensioned array nbr pts where nbr pts is the total number of the Reduced PRISM Project Report 2 46 CERFACS TR CMGC 03 69 grid points 0 not masked or 1 masked for each grid point This file is re quired only for grids to which the REDGLO or GLORED transformation is applied As mentionned above these transformations should not be used anymore as in terpolations are now available for Reduced grids directly If used the mask array name must be MSKRDx
65. strated 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 PRISM Project Report 2 24 CERFACS TR CMGC 03 69 4 The OASIS3 configuration file namcouple The OASIS3 configuration file namcouple contains below pre defined keywords all user s defined information necessary to configure a particular coupled run The nam couple 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 lines beginning with are ignored and considered as comments Note that blank lines are not allowed The first part of namcouple 1s devoted to configuration of general parameters such as the number of models involved in the simulation the number of fields the commu nication technique etc The second part gathers specific information on each coupling or I O field e g their coupling period the list of transformations or interpolations to be performed by OASIS3 and their associated configuring lines described in more details in section 5 etc In the next sections a simple namcouple example is given and all configuring param eters are described The additional lines containing the different parameters required for each transformation are described in section 5 Examples of realisti
66. t 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 Fy and then sends F its timestep length is 4 During a coupling timestep model B receives F and then sends F its timestep length is 6 F and F3 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 fF and F produced at the timestep before have to be used to match respectively the model B and model receiving actions This implies that a lag of respectively 4 and 6 seconds must be defined for F and Fy For Fi the prism put proto performed at time 8 and 20 by model A will then lead to sending actions as 8 4 12 and 20 4 24 which are coupling periods that match the receiving actions performed at times 12 and 24 below the prism get proto called by model B For 75 the prism put proto performed at PRISM Project Report 2 19 CERFACS TR CMGC 03 69 o B Pd e 30 120 6 18 Sii 24 li L I d E fel allel pepe a ft El F3 if e al Fl F2 F3 tejet Fl F2 F3 Pa Fi FE b E e s 15 M EN EN Aber E A A A T ONT S i 18 24 I Model A timestep 6 prism put proto prism get proto le
67. tion 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 5ea Surface Temperature FILLING operation with smoothing CFILE NUMLU CMETHOD NFCOAST CNAME NUNIT where CFILE NUMLU and NFCOAST are as for the SST filling without smoothing In this case CMETHOD 1 3 SMO CMETHOD 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 NUNIT the logical unit on which it is going to be written PRISM Project Report 2 42 CERFACS TR CMGC 03 69 5 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 oasis3 src conserv f performs global flux conservation The flux is integrated on both source and target grids without con sidering 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 CONSERV operation CMETHOD where CMETHOD is the conservation method required In this version only global flux conservation can be performed Therefore CMETHOD must be GLOBAL e SUBGRID
68. tion 3 5 6 Termination section 3 6 Finally in section 3 7 different coupling algorithms are illustrated and explanations are given on how to reproduce them with PSMILe defining the appropriate indices of lag and sequence for each coupling field A practical example of a toy coupled model based on OASIS3 and PSMILe is given in prism util mod toyclim see the README toyclim therein PRISM Project Report 2 9 CERFACS TR CMGC 03 69 3 1 Initialisation All processes initialise the coupling and if required retrieve a local communicator for the component model internal parallelisation e USE mod prism proto Module to be used by the component models The MPI include file mpif h also needs to be included in the component models INCLUDE mpif h e CALL prism init comp proto compid model name ierror compid INTEGER OUT component model ID model name CHARACTER 6 IN name of the calling model as in the nam couple 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 comm INTEGER OUT value of local communicator ierror INTEGER OUT returned error code Routine called by all model processes to get the value of a local communicator to be used by the model for its internal parallelisation This is done follow ing a colouring scheme developed by
69. tten in the following way WRITE LU array name WRITE LU restartdata where e LU is the associated unit e array name is the source symbolic name of the field CHARACTER 8 e restartdataistherestart field REAL array dimensioned nx ny or nbr_pts 1 5 6 3 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 4 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 symbolic name in the namcouple and dimensioned nx ny time or nbr_pts 1 time The time variable as to be an array time time expressed in sec since beginning of run For a practical example see the file prism util mod toyclim Cp1 Restart SOALBEDO nc 6 4 Transformation auxiliary data files 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 131f REDGLO is the first transformation applied on a Reduced grid field the Reduced f
70. wing lines one line per model listed on the NBMODEL line indicate for each model the total number of processes the number of processes implied in the coupling and PRISM Project Report 2 27 CERFACS TR CMGC 03 69 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 argl 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 arg2 and arg3 To use the CLIM MPII communication technique the CHANNEL lines are e g CHANNEL MPI1 where MPI1 is the message passing used in CLIM and PSMILe and the following lines one line per model listed on the NBMODEL line are as for MPI2 except that there is no launching argument To use the PIPE SIPC or GMEM communication technique the user has to write only PIPE SIPC or GMEM below the CHANNEL keyword e NFIELDS On the line below this keyword is the total number of fields exchanged and described in the second part of the namcouple e JOBNAME On the line below this keyword is a CHARACTERx3 or CHARACTERx4 variable giving an acronym for the given simulation e NBMODEL On the line below this keyword is the number of models running in the given experiment followed by CHARACTERx6 variables giving their names Then the user should i
71. xx 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 where e LU is the associated unit e array name is the name of the array CHARACTER 8 e auxildatais the REAL or INTEGER array dimensioned nx ny or nbr_pts 1 containing the grid data 6 2 Coupling restart files At the beginning of a coupled run some coupling fields may have to be initially read in from their coupling restart file see section 3 7 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 4 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 see sstac nc in section 4

Report no 2 “OASIS3 User's Guide” 1 st ed

Contents

Download Pdf Manuals

Related Search

Related Contents

Report no 2 &ldquo;OASIS3 User's Guide&rdquo; 1 st ed

Contents

Download Pdf Manuals

Related Search

Related Contents

Report no 2 “OASIS3 User's Guide” 1 st ed