Home

OASIS3 Ocean Atmosphere Sea Ice Soil User's Guide

Contents

1. 1 Note that if RUNTIME is smaller than the total number of time ocurrences in the input file the first RUNTIME occurrences will be interpolated For more details see section 5 1 e Model grid data file writing The grid data files grids ne masks nc and areas nc can now be written di rectly at run time by the component models if they call the new routines prism start grids writing prism write grid prism write corner prism write mask prism write area prism terminate grids writing The writing of those grid files by the models is driven by the coupler It first checks whether the binary file grids or the netCDF file gr ds nc exists in that case it is assumed that areas or areas nc and masks or masks nc files exist too or if writing 1s needed If grids or grids nc exists it must contain all grid information from all models if it does not exist each model must write its grid informations in the grid data files See section 3 2 for more details e Output of CF compliant files The NetCDF output files written by the PSMILe for fields with status EXPOUT IGNOUT and OUTPUT are now fully CF compliant In the NetCDF file the field attributes long_name and units are the ones corresponding to the field index in cf_name_table txt see above and section 6 1 The field index must be given by the user as the third entry on the field first line in the namcouple Also the latitudes and the longitudes of the
2. 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 PSMILe with the MPI1 or MPI2 communication technique 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 PSMILe with the MPI1 or MPI2 communication technique 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 33 grid and pa
3. rif F2 rif rif j gg 8 12 e quens 2 6 116 120 Model A timestep 2 4 p 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 C ie iod F2 12 sending receiving actions pl_period F2 prism put proto prism get proto not leading to LAG F1 8 sending receiving actions LAG F2 6 SEQ F 2 SEQ F2 1 Figure 7 Mix of LAF and SEQ concepts first lag example above model A receives F and then sends Fi its timestep length is 4 During a coupling timestep model B receives Fy and then sends F its timestep length is 6 Fi 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 P 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 prism put proto as 8 LAG 8 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 resta
4. 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 correction 0 no 1 yes 3 If FILLING performs the blending of a regional data set with a global one for the Sea Surface Temperature with smoothing the 6 argument input line is 5ea Surface Temperature FILLING operation with smoothing CFILE NUMLU CMETHOD NFCOAST CNAME NUNIT 46 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 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 it CONSERV operation CMETHOD where CMETHO
5. In the following paragraphs it is first described how to use OASIS3 in an interpolator only mode Then a description of each transformation with its corresponding 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 first OASIS3 in this mode 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 namcouple as indicated in sections 4 2 and 4 3 In particular NONE has to be chosen below the keyword CHANNEL 0 without any model name and Fortran unit number must be given below the keyword NBMODEL RUNTIME has to be the number of time occurrences of the field to interpolate from the NetCDF input file finally the coupling period of the field 4th entry on the field first line must be always 1 Note that if RUNTIME is smaller than the total number of time ocurrences in the input file the first RUNTIME occurrences will be interpolated The name of the input file which contains the fields to interpolate is given by the 6th entry on the field first line see 4 3 After their transformation OASIS3 writes them to their output file which name is the 7th entr
6. 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 x PRISM_FromRest 10 if the field was read from a restart file only directly or via OASIS3 main process PRISM Input 11 if the field was read from an input file only 19 PRISM RecvOut 12 if the field was both received from another model directly or via OASIS3 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 is actually performed only if date corresponds to a time for which it should be activated given the period indicated by the user in the namcouple A field will not be received at all if its coupling or I O period indicated in the namcouple is greater than the total run time 3 6 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 ru
7. and described in the second part of the namcouple JOBNAME On the line below this keyword is a CHARACTER 3 or CHARACTER 4 variable giving an acronym for the given simulation 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 may indicate the maximum Fortran unit number used by the models In the example Fortran units above 55 70 and 99 are free for respectively the ocean atmosphere and atmospheric chemistry models If no maximum unit numbers are indicated OASIS3 will suppose that units above 1024 are free If CHANNEL is NONE NBMODEL has to be 0 and there should be no model name and no unit number RUNTIME On the line below this keyword is the total simulated time of the run expressed in seconds If CHANNEL is NONE RUNTIME has to be the number of time occurrences of the field to interpolate from the restart file 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 Use the standard blocking send MPI Send if the coupling fields are necessarily sent and received in the same order or on architectures on which MPI Send is implemented with a mailbox e g VPPs in this case make sure that the size of the mailbox is sufficient Use the less efficient buffered s
8. 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 4 1 index in auxiliary file cf name table txt used by OASIS3 and PSMILe to identify corresponding CF standard name and units see 6 1 86400 coupling and or I O period for the field in seconds If CHANNEL is NONE put 1 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 3 sstat nc name of the field output file may be indicated for NONE and PIPE communication techniques only It may be a binary of netCDF file see section 6 3 EXPORTED field status e Field second line 34 182 number of points for the source grid first dimension optional if a netCDF coupling restart file is used 149 number of points for the source grid second dimension optional if a netCDF coupling restart file is used 128 number of points for the target grid first dimension optional if a netCDF coupling restart file is used 64 number of points for the target grid second dimension optional if a netCDF coupling restart file is used toce prefix of the source grid name in grid data files see section 6 2 CHARACTER 4 atmo pref
9. Db e reed e AE sos o Neh to Oe Sa St tek 56 The grid types for the transformations 57 The SCRIP 1 4 copyright statement 59 The coupled models realized with OASIS 60 The list of changes since last OASIS3 version 62 Acknowledgements We would like to thank the main past or present developers of OASIS are in alphabetical order with the name of their institution at the time Arnaud Caubel FECIT Fujitsu Damien Declat CERFACS Veronika Gayler MPLM amp D Jean Latour Fujitsu Fecit Hubert Ritzdorf CCRLE NEC Sami Saarinen ECMWE Eric Sevault M t o France Laurent Terray CERFACS Olivier Thual CERFACS Sophie Valcke CERFACS Reiner Vogelsang SGI Germany We also would like to thank the following people for their help and suggestions in the design of the OASIS software in alphabetical order with the name of their institution at the time Dominique Astruc IMFT Sophie Belamari M t o France Dominique Bielli M t o France Gilles Bourhis IDRIS Pascale Braconnot IPSL LSCE Christophe Cassou CERFACS Yves Chartier RPN Jalel Chergui IDRIS Philippe Courtier M t o France Philippe Dandin M t o France Michel D qu M t o France Ralph Doescher SMHI Jean Louis Dufresne LMD Laurent Fairhead LMD Marie Alice Foujols IPSL Gilles Garric CERFACS Eric Guilyardi CERFACS Pierre Herchuelz ACCRI Maurice Imbard M t o France Stephanie Legutke MPI M amp D Claire L vy LODYC Olivier
10. In fact with MPII all component models started in a pseudo MPMD mode share automatically the same MPI COMM WORLD communicator Another commu nicator has to be used for the internal parallelisation of each model OASIS3 creates this model local communicator following a coloring scheme its value is returned as the first argument of prism get localcomm proto routine With MPI2 the communicator MPIL COMM WORLD will be returned as local communicator Besides that the only differences between using PSMILe with MPII or MPI2 message passing are The SCHANNEL in the namcouple see section 4 2 The way the models are started With MPI2 only OASIS3 needs to be started at the command line it will then spawn the component models at the beginning of the run With MPII models have to be started by the user in a pseudo MPMD mode the way to do this depends on the computing platform 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 10 3 2 Grid data file definition The grid data files grids nc masks nc and areas nc must be created by the user before the run or can now be written directly at run time by the component models If written by the component models the writing of those grid files is driven by OASIS3 main process It first checks whether the binary file
11. LINTEGER IN grid dimension in y direction mask INTEGER DIMENSION nx ny IN mask array 0 not masked 1 masked Writing of the model grid mask e CALL prism write area cgrid nx ny area cgrid CHARACTER 4 IN grid name prefix nx INTEGER IN grid dimension in x direction ny LINTEGER IN grid dimension in y direction area REAL DIMENSION nx ny IN array of grid cell areas Writing of the model grid cell areas Writing of areas is optional as area infor mation is needed only for some transformations see section 6 2 e CALL prism terminate grids writing Termination of grids writing A flag stating that all needed grid information was written will be sent to OASIS3 main process 3 3 Partition definition When a component of the coupled system is a parallel code each coupling field is usually scattered among the different processes With the PSMILe library each process sends directly its partition to OASIS3 main process or directly to the other component model if no transformation nor repartition is required To do so each process implied in the coupling has to define its local partition in the global index space e USE mod prism def partition proto Module to be used by the component model to call prism def partition proto 12 e CALL prism def partition proto il_part_id ig paral ierror il_part_id INTEGER OUT partition ID ig paral INTEGER DIMENSION IN vect
12. 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 NOBSEND 1 1 argi 3 1 arg2 3 1 arg3 where MPI2 is the message passing used in CLIM and PSMILe and NOBSEND indicates that standard blocking send MPI Send should be used in place of the 31 buffered MPI BSend to send the coupling fields If NOBSEND is not specified the buffered send MPI BSend will be used The following 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 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 NFIELDS On the line below this keyword is the total number of fields exchanged
13. a Box partition over 3 processes The maximum value of the local extent in Y is presently 200 it can be increased by modifying the value of Clim MaxSegments in prism src lib clim src mod clim F90 and in prism src lib psmile src mod prism proto F90 and by recompiling Oasis3 and the PSMILe li brary 13 Proc 1 local offset 0 local size 4 Proc 2 local offset 4 local size 6 Figure 1 Apple partition 14 Proc 3 local offset 10 local size 5 local offset 2 local x extent 3 local y extent 2 local offset 0 local x extent 2 local y extent 2 Figure 2 Box partition Proc 3 local offset 10 local x extent 5 local y extent 1 3 3 4 Orange partition Each partition is an ensemble of segments of the global domain Each segment is described by its global offset and its local extent In this case we have ig paral 1 N where N 2 2 number of segments ig paral 1 3 indicates a Orange partition ig paral 2 the total number of segments for the partition limited to 200 presently see note for i
14. and then run simultaneously For the first run the LAG and SEQ indices must be defined as in section 3 8 3 After the first run the situation is similar to the one of section 3 8 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 illustrated on the figure by an orange arrow at the end of the first run in fact F lag being then negative such writing is not automatically done below the last prism put proto of the first run 28 4 The OASISS3 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 is 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
15. e PRISM Sent 4 if the field was sent to another model directly or via OASIS3 main process PRISM LocTrans 5 if the field was only used in a time 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 5PRISM 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 PRISMReal or PRISM Double are valid for var type To ex change 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 5Coupling fields exchanged directly between two component models still 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 18 x PRISM_ToRestOut 9 if the field was written both to a restart file and 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 sending is actually performed only if the time obt
16. grids or the netCDF file grids nc exists in that case it is assumed that areas or areas nc and masks or masks nc files exist too or if writing is needed If grids or grids nc exists it must contain all grid information from all models if it does not exist each model must write its grid informations in the grid data files The coupler sends the information on whether or not writing is needed to the models following an OASIS internal order below prism start grids writing If no writing is needed nothing happens when calling the following prism_write_xxxx rou tines If writing is needed the first model creates the files writes the data arrays be low prism write grid prism write corner prism write mask prism write area calls and then sends a termination flag to the coupler below prism terminate grids writing call The coupler will send the starting flag to the next model this ensures that only one model accesses the files at a time This section describes the PSMILe routines that may be called by the master process of each component model to write at run time the whole grid information to the grid data files These routines have to be called just after prism init comp proto The new toy coupled model toyclim see the sources of the toy component models in prism src mod toyatm toyoce and toyche uses those grid data file writing routines e USE mod prism grids writing Module to be used by the component model to call grid
17. standard names and associated units identified with an index The appropriate index has to be given by the user for each coupling or I O field as the third entry on the field first line see 4 3 This information will be used by OASIS3 for its log messages to cploul file and by the PSMILe to produce CF compliant NetCDF files 6 2 Grid data files The grids of the models being coupled must be given by the user or directly by the model through PSMILe specific calls see 3 2 in grid data files These files can be all binary or all NetCDF files The arrays containing the grid information are dimensioned nx ny where nx and ny are the grid first and second dimension except for Unstructured U and Reduced D grid for which the arrays are dimensioned nbr pts 1 where nbr pts is the total number of grid points 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 dimension
18. 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 F5 Therefore SEQ 1 2 3 must be defined respectively for Fi Fy and F As all fields can be consumed at the time they are produced LAG 0 for all fields there no reading writing from to coupling restart files 3 8 3 A mix of lag and sequence the sequential coupled model One can run the same component models simultaneously or sequentially by defining the appropriate LAG and SEQ indices In the example illustrated on figure 7 the models perform their prism put proto and prism get proto calls exactly as in the 25 Model B ia pup oom Vh 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 26 Model B timestep 6 0 12 108 11 e LE NN Fi el rif Fi el rif
19. type SCALAR or VECTOR RESTRICis the search restriction type LATLON or LATITUDE see SCRIP 1 4 documentation 13See the copyright statement in annexe B 1 No particular treatment for vector interpolation is performed presently 4 NBRBINS the number of restriction bins see SCRIP 1 4 documenta tion NVOISIN is the number of neighbours used GAUSWGT performs N nearest neighbour interpolation weighted by a gaussian function All grid types are supported The configuring line is SCRIPR GAUSWGT CMETHOD CGRDSRC CFLDTYP RESTRIC NBRBINS NVOISIN VAR where all entries are as for DISTWGT except that x CMETHOD GAUSWGT 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 ezp 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 DIS
20. values weighted by the overlapped surfaces 15cONSERV SECOND has not been tested in detail 43 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 CGRDSRC CFLDTYP NID NVOISIN NIO where x CMETHOD SURFMESH CGRDSRC and CFLDTYP are as for BILINEAR 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 CMETHOD GAUSSIAN x CGRDSRC and CFLDTYP are as for the BILINEAR interpolation and LR D and U grids NID is the identificator for the weight address dataset in all the different INTERP GAUSSIAN datasets in the present coupling This weight address dataset will be calculated by OASIS3 if NIO 1 or only read if NIO 0 NVOISIN is the number of neighbours used in the interpolation VA
21. which is the iteration number within EXTRAP NINENN at which the extrapolation of the n grid point is effectively performed 6 5 2 Auxiliary data files for FILLING For the FILLING analysis the global data set used can be either interannual monthly climatological monthly or yearly see 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 C REAL field january year O1 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 if climatology one stops here C WRITE NLU fil field january year 02 etc where e field is the global dataset e jpiand jpj are the dimensions of the grid on which FILLING is performed 54 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 6 5 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 a
22. D is the conservation method required In this version only global flux conservation can be performed Therefore CMETHOD must be GLOBAL e SUBGRID SUBGRID can be used to interpolate a field from a coarse grid to a finer target grid the target grid must be finer over the whole domain Two types of subgrid interpolation can be performed depending on the type of the field For solar type of flux field SUBTYPE SOLAR the operation performed is l a l a where 9 F is the flux on the fine coarse grid a o 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 T T EA 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 the derivative of the flux versus the auxiliary field on the coarse grid This operation 1s interpolated from the AT 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 depen
23. ILe specific calls of the following classes have to be implemented in the code 1 Initialisation section 3 1 2 Grid data file definition section 3 2 3 Partition definition section 3 3 4 I O coupling field declaration section 3 4 5 End of definition phase section 3 5 6 I O coupling field sending and receiving section 3 6 7 Termination section 3 7 Finally in section 3 8 different coupling algorithms are illustrated and explanations are given on how to reproduce them with PSMILe by defining the appropriate indices of lag and sequence for each coupling field 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 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 For MPII routine called by all model processes to get the value of a local com municator to be used by the model for its internal parallelisation
24. LOCTRANS if this transformation is chosen for the field Note that LOCTRANS is the only transformation supported for IGNORED IGNOUT and OUTPUT fields as it is performed directly in the PSMILe below the prism_put_proto call If LOCTRANS is chosen a fourth line giving the name of the time transformation is required 35 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 index in auxiliary file cf name table txt see above for EXPORTED fields e 86400 input period in seconds e 0 number of transformations always 0 for INPUT fields e SOALBEDO nc CHARACTER 32 giving the input file name for more detail on its format see section 6 4 e INPUT field status 36 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
25. Marti IPSL LSCE Claude Mercier IDRIS Pascale Noyret EDF Andrea Piacentini CERFACS Marc Pontaud M t o France Ren Redler NEC CCRLE Tim Stockdale ECMWF Rowan Sutton UGAMP V ronique Taverne CERFACS Jean Christophe Thil UKMO The OASIS3 working team leading the software maintenance and development is composed of Sophie Valcke Damien Declat and Laurent Terray at CERFACS For any question bug report or further information you should contact us at oa sishelp cerfacs fr 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 1 2 Obtain OASIS3 sources See section 2 Identify the coupling or I O fields and adapt the component models to allow their exchange with the PSMILe library based on MPII or MPI2 message passing The PSMILe library is also interfaced with the mpp io library from GFDL 2 and therefore can be used to perform I O actions from to disk files A practical exam ple of toy component models are given in directories prism src mod toyatm toyoce toyche these toy models are included im PRISM standard compiling and running environment See 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 OASIS3 supports more interpolation algo rithms and more gr
26. 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 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 TEE IERERERETERERERERERERETERE RETE ERE RE TERRE TEREREREHERERERERETE EIER ERE RE TERRE TERE RENE HERETEIERETE EIER ERERETERERE ERE RENE ERETERE First section SEQMODE 1 CHANNEL MPI2 NOBSEND 1 1 argi 3 1 arg2 3 1 arg3 NFIELDS 4 29 JOBNAME JOB NBMODEL 3 ocemod atmmod chemod 55 70 99 RUNTIME 432000 INIDATE 00010101 MODINFO NOT NLOGPRT 2 CALTYPE 1 DEIIIPPIPPIDIRPRPIEPPRPIPPPPIPEPPIIDERPIIDIIIIIIIIIIIIPEIIIIEIIIIIIIIIIIIX Second section STRINGS Field 1 SOSSTSST SISUTESU 1 86400 5 sstoc nc EXPORTED 182 149 128 64 toce atm
27. OASIS3 Ocean Atmosphere Sea Ice Soil User s Guide oasis3 prism 2 1 April 2004 Sophie Valcke Arnaud Caubel Reiner Vogelsang Damien Declat PRISM Project WP3a 1C E R F A C S FECIT Fujitsu GI Germany 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 coupling independent general circulation models of the atmosphere and the ocean A O GCMs as well as other climate component models sea ice land atmospheric chemistry ocean biogeochemistry and regional models The resulting cou pled models are necessary tools to tackle current climatic paradigms such as the natural variability El Nino 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 fields produced by the source model on its grid Modularity and flexibility have been particularly em phasized in OASIS3 design Contents Acknowledgements 1 Overview of step by step use of OASIS3 2 Obtaining OASIS3 sources 24 rhe OAS Sa package i ues ete ut CE SURE wo eh ee tup S Ox Interfacing a model with the PSMILe library sab Mfrulralsaticibieu cae aay ind eum nex CONO EI EU EROR DEAD eet N 32 Grid
28. R 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 are defined by the user in a file see section 6 5 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 44 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 e NOINTERP NOINTERP is the analysis that has to be chosen when no other transformation from the interpolation class is chosen There is no configuring line e FILLING FILLING routine prism src mod 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 d
29. TWARE 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 59 C The coupled models realized with OASIS Here is a list of some of the coupled models realized with OASIS within the past 5 years or so in Europe and in other institutions in the world USA 2 4 ECHAMA MOM3 SGI Origin Li hl 4 nue Ops ESSX5 U of Aus 3 0 Data atm model MoM a 03400 Tasmania tral Compaq BMRC Aus 3 0 BAM4 MOM4 tral 2 4 BAM3 T47L34 ACOM2 a CASTIT Table 2 List of couplings realized with OASIS within the past 5 years in institutions outside Europe The columns list the institution the country the OASIS version used the atmospheric model the ocean model and t
30. TWGT 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 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 2 only LR is supported if the grid corners are not available in the grid data file and therefore have to be calculated automatically 42 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 local flux conservation is ensured but unreasonable flux values may result FRACNNEI
31. ained by adding the field lag see 3 8 to the argument date corresponds to a time at which it should be activated given the coupling or I O period indicated by the user in the namcouple see section 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 8 the OASIS3 restart file see section 6 3 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 buffered MPI_BSend by default or the standard blocking send MPI Send if NOBSEND is specified in the namcouple see CHANNEL section 4 2 to send the coupling fields 3 6 2 Receiving a coupling field In the model time stepping loop each process implied in the coupling receives its part of the I O coupling field e USE mod prism get proto Module to be 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
32. aism SURFMESH interpolation library clim CLIM MPI1 MPI2 communication library fscint INTERP interpolation library psmile PRISM System Model Interface Library scrip SCRIPR interpolation library 3 Interfacing a model with the PSMILe library At run time OASIS3 acts as a separate mono process executable which drives the coupled run interpolates and transforms the coupling fields To communicate with OASIS3 or directly between the component models different communication techniques have been historically developed The technique used for one particular run is defined by the user in the configuration file namcouple see section 4 In OASIS3 the CLIM communication technique based on MPII or MPI2 message passing is used To communicate with OASIS3 or directly with another component model or to per form I O actions a component model needs to be interfaced with the PRISM System Model Interface library PSMILe which sources can be found in prism src lib psmile directory PSMILe supports e parallel communication between a parallel component model and OASIS3 main process e direct communication between two parallel component models when no transfor mations and no repartitioning are required e automatic sending and receiving actions at appropriate times following user s choice indicated in the namcouple e time integration or accumulation of the coupling fields e I O actions from to files To adapt a component model to PSM
33. alyses 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 INTEGER 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 53 jpnb is the maximum number of neighbors used in the transformation NVOISIN in the namcouple jpo is the total dimension of the target grid at31topa is the name of the grid mapping data file CFILE in namcouple knumb is the identificator of the data set NID in namcouple cladress is the locator of the address dataset clweight is the locator of the weight dataset iadress i j is the address on the source grid of the 2 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 weight i j is the weight affected to the neighbor used for the transformation of the 7 target grid point For file nweighis 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
34. art files for the first run in the experiment At the end of the run Fi having a lag greater than 0 is automatically written to its coupling restart file below the last F prism put proto if the date Fjlag equals a coupling time The analogue is true for F5 These values will automatically be read in at the beginning of the next run below the respective prism get proto 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 Fy its timestep length is also 6 F1 Fy and F coupling periods are both supposed to be equal to 12 24 For Fj and F the situation is similar to the first example If F F sending action by model A B was used at a coupling timestep to match the model B A receiving action a deadlock would occur as both models would be waiting on a receiving action To prevent this Ff and F5 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 Fj and F5 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
35. as FRACAREA except that the source nearest neighbour is used for target cells that do not intersect any unmasked source cells ORDER FIRST or SECOND for first or second order remapping respec tively see SCRIP 1 4 documentation e INTERP INTERP gathers different techniques 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 x 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
36. ations 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 5T 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 58 B The SCRIP 1 4 copyright statement The SCRIP 1 4 copyright statement reads as follows Copyright 1997 1998 the Regents of the University of California This software and ancillary 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 SOF
37. ays dimensioned array nbr pts where nbr pts is the total number of the Reduced 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 MSKRDxxx where xxx is half the number of latitude circles of the reduced grid 032 for a T42 for example If the binary format is used grids masks areas and maskr must have the following structure The array name is first written to the file to locate a data set corresponding to a given grid The data set is then written sequentially after its name Let us call brick the name and its associated data set The order in which the bricks are written doesn t matter All the bricks are written in the grid data file in the following way WRITE LU array name WRITE LU auxildata where e LU is the associated unit e array name is the name of the array CHARACTER S e auxildatais the REAL or INTEGER array dimensioned nx ny or nbr_pts 1 containing the grid data 6 3 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 8 The name of the coupling restart file is given by the 6th character string on the first con
38. bal Gaussian grid dimensions and the Reduced field is completed by trailing zeros 52 array time time expressed in seconds since beginning of run The time dimension has to be the unlimited dimension 6 5 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 6 5 1 Auxiliary data files for EXTRAP NINENN EXTRAP WEIGHT INTERP SURFMESH INTERP GAUSSIAN MOZAIC and SUBGRID The auxiliary data files containing the weights and addresses used in these transfor mations have a similar structure their names are given in Table 1 nweighls 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 gweights weights and addresses for INTERP GAUSSIAN interpolation any name weights and addresses for MOZAIC interpolation any name weights and addresses for SUBGRID interpolation Table 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 an
39. by the target model For F3 sent by model A and received by model B no lag needs to be defined the coupling field produced by model 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 Fp 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 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 8 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
40. can be directly interpolated to a target Reduced grid if needed 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 2 The generic input line is as follows 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 AQ 6 OASIS3 auxiliary data files OASIS3 needs auxiliary data files describing coupling and I O field names and units defining the grids of the models being coupled containing the field coupling restart values or input data values as well as a number of other auxiliary data files used in specific transformations 6 1 Field names and units The text file cf name table txt contains a list of CF
41. cessing transformations The following transformations are available in the pre processing part of OASIS3 con trolled by preproc f 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 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 NO80 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 2 or if the opposite has to be performed CDMSK LANDSEA If CDMSK NOEXTRAP then no extrapolation is performed 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
42. 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 it BLASOLD 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 input line is required i 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
43. cond section of namcouple for IGNORED IGNOUT and OUTPUT Keld cuo ue estera ed irate divino or aoa NODI elo Pe e die ange heer ae do at 4 3 3 Second section of namcouple for INPUT fields The transformations and interpolations in OASIS3 5 1 Using OASIS3 in the interpolator only mode 5 2 The time transformations ioca x ete Ro dA Do DRA 214d 5 8 The pre processing transformations a a a bu Checmnterpolation 2 2 2 dem Spem ed ub e mte ow GR eR 5 9 The cooking Stage a oreet Bs e qe ae at act ok tace e A a 5 6 The post processing suche de Ro oC eir Rum Ro Cae BRS 10 11 12 13 13 13 16 16 18 18 18 19 20 21 21 22 25 25 28 29 29 31 33 34 35 36 6 OASISS3 auxiliary data files 50 7 a B 6 1 Field names and units 12 6 esc cti aee ut el De te se Ret A Rest t 50 0 2 Grid data Wesce uou se uto e dr RU A AG Ue dc A det 50 6 3 Coupling restart Mes sto ctus qe wt dee arte e he didi en 51 6A duaput data files iu de e a4 das etm p e e ute ee RS ea 52 6 5 Transformation auxiliary data files llle 53 6 5 1 Auxiliary data files for EXTRAP NINENN EXTRAP WEIGHT INTERP SURFMESH INTERP GAUSSIAN MOZAIC and SUBGRID 53 6 5 2 Auxiliary data files for FILLING 54 6 5 3 Auxiliary data files for SCRIBE sa xo be 55 Compiling and running with OASIS3 56 7 1 Compiling OASIS3 and the toyclim coupled model 56 Tar otis CU Ses ele
44. data le stefiilion s 22 dr uto ous g ah cord Eus ice e rut Sid s 3 3 Parution Cel RON 4 gs a Se e eo GOS pg qvx SIE EU oe Ng 3 3 1 Serial no partition d a arde eeu e aides dy RE E Rei E Re OU 3 3 2 Apple partiti n su ssa ses ea sea eas aided HS er S Gidea Box partitio de exuti biat e idk Gerd amp aani Sta Sa a a oie t 3 3 4 Orange partition cng onc ee tea RE EU Spidey NS ERN S EN 3 4 I O coupling field declaration 43 9 3 939 30 4 384 4 8 Reds d 3 5 End of definition phase 42 539 ew were box ew Ix Od 3 6 Sending and receiving actions i e ox coe e 9oxodo oS xim cw A le 3 3 6 1 Sending a coupling held 939929993 3 6 2 Receiving a coupling field oaaae 3 6 3 Auxiliary routines aoaaa Poe Posteado Uoc Termination zenti dace a E ho ec ep Ea E SEHR KAS E ok 3 8 Coupling algorithms SEQ and LAG concepts sel 3Dhelaeonc pb lue RA eo a G4 Sus N 3 8 2 The sequence concept oaoa a pe we Ape eae aoa See d 3 8 3 A mix of lag and sequence the sequential coupled model 3 8 4 An experiment mixing sequential and parallel coupled model runs the use of prism_put_restart_proto The OASIS3 configuration file namcouple 4 1 An example of a simple namcouple es 4 2 First section of namcouple file aoo Rao fe Re BES She s 4 3 Second section of namcouple file 4 3 1 Second section of namcouple for EXPORTED AUXILARY and EXPOUT i pu xc Lc EPI TEES 4 3 2 Se
45. ding on the type of subgrid interpolation 1 If the the SUBGRID operation is performed on a solar flux the 7 argument input line is 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 5 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 nam
46. e on fine grid corresponding to 7 the additional argument CDQDT is the cou pling ratio on the coarse 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 48 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 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 cplout The generic input line is as for CHECKIN e GLORED not recommended as coupling fields
47. ed nx ny 4 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 calculated approximately 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 least the grid point longitudes and latitudes for all component model 2 masks or masks nc contains the masks for all component model grids in INTEGER arrays 0 not masked or 1 masked for each grid point The array names must be composed of the grid prefix and the suffix msk This file masks or masks nc is mandatory 3 areas or areas nc this file contains mesh surfaces for the component model grids in single or double precision REAL arrays depending on OASIS3 compilation 50 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 arr
48. educed from the value of the SST The frequency of the global set can be interannual monthly climatological monthly or yearly The blending can be smooth or abrupt If the blending is abrupt only model values are used within the model domain and only the global data set values are used outside If the blending is smooth a linear interpolation is performed between the two fields within the model domain over narrow bands along the boundaries The linear interpolation can also be performed giving a different weight to 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 di mension 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 nnlte 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 nslib 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 nslte or nnlte in the smoothing band the weight given to the regional and global fields will respectively be 1 and 0 within the smoothing band the weights will be a linear interpolation of the outermost and innermos
49. els 3 8 1 The lag concept If no lag index or if a lag index equal to 0 is given by the user in the namcouple for a particular coupling field the sending or receiving actions will actually be performed below the prism put proto called in the source model or below the prism get proto called in the target model respectively each time the date arguments on both sides match an integer number of coupling periods 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 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 sending or receiving action long black arrows correspond to pr
50. end MPI BSend on architectures on which MPI Send is not implemented with a mailbox e g NEC SX5 if the coupling fields are not sent and received in the same order 32 4 3 MODINFO If coupling restart files are binary files see section 6 3 the line below this keyword indicates if a header is encapsulated or not it can be YES or NOT 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 CALTYPE This new keyword gives the type of calendar used For now the calendar type is important only if FILLING analysis is used for a coupling field in the run and for printing information in OASIS3 log file cplout Below this keyword a number 0 1 or n must be indicated by the user 0 a 365 day calendar no leap year 1 a 365 or 366 leap years day calendar A year is a leap year if it can be divided by 4 however if it can be divided by 4 and 100 it 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
51. fields are now automatically read from the grid auxiliary data file grids nc and written to the output files If the latitudes and the longitudes of the mesh corners are present in grids nc they are also written to the ouput files as associated bounds variable This works whether the grids ne is given initially by the user or written at run time by the component models see above However this does not work if the user gives the grid definition in a binary file grids e Removal of pre compiling key key_BSend The pre compiling key key_BSend has been removed The default has changed by default the buffered MPI_BSend is used unless NOBSEND is specified in the namcouple after MPI1 or MPI2 in which case the standard blocking send MPI Send is used to send the coupling fields 63 References 1 http climate lanl gov Software SCRIP index htm 2 http www gfdl gov vb mpp io html 3 http www unidata ucar edu packages udunits udunits dat 4 http prism dkrz de Workpackages WP3i 64
52. figuring 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 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 51 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 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 exceptions are 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 t
53. g paral 4 for Box partition above ig paral 3 the first segment global offset ig paral 4 the first segment local extent ig paral 5 the second segment global offset ig paral 6 the second segment local extent ig paral N 1 the last segment global offset ig paral N the last segment local extent Figure 3 illustrates an Orange partition with 3 segments for one process The other process partitions are not illustrated 3 4 I O coupling field declaration Each process implied in the coupling declares each field it will send or receive during the simulation 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 varmodims 2 is the number of bundles always 1 for OASIS3 kinout INTEGER IN PRISM Inm for fields received by the model or PRISM Out for fields sent by the model var_actual_shape INTEGER DIMENSION 2 var nodims 1 IN vector of integers giving the minimum and maximum index for each dimension of the coupling field array for OASIS3 the minimum index has to be 1 and the maximum index has to be the extent of the dimension As for the Box pa
54. he 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 positional 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 interpol
55. he computing platform used for the coupled model run 60 IPSL 3 0 LMDz 96x71x19 ORCH INCA 2 4 LMDz 96x71x19 2 4 LMDz 72x45x19 2 4 LMDZ 120X90X1 ORCA2 182x149x31 SX6 LIM ORCA2 182x149x31 ORCA4 92x76x31 OPA ATL3 1 3 deg VPP5000 VPP5000 2 4 LMDZ 120X90X1 OPA ATLI 1 deg IFS TI95 L31 OPA amp 1 pur Lodyc ISAO ECHAM4 T30 T42 L14 ORCA2 182x149x31 SX4 8X5 sack Mercator CERFACS ECMWF 3 0 ARPEGE 4 2 4 ARPEGE medias 2 2 ARPEGE 3 ORCA2 OPA med 1 8e OPA 8 1 Gelato OPA8 TDH interp mode PAM OPA AG cuESHN OPA 8 1 OPAICE E HOPE 2deg 1deg E HOPE 256L29 E HOPE 256L29 E HOPE 128L20 MPI OM C HOPE T424 L20 IFS T63 T255 IFS Cy23r4 T159L40 IFS Cy23r4 T95L40 IFS Cy15r8 T63L31 VPP5000 VPP5000 VPP5000 CRAY J90 VPP5000 VPP700 CRAY C90 IBM Power 4 VPP700 VPP700 VPP300 IBM Power4 NEC SX C HOPE 2deg GIN E HOPE T424 L20 E HOPE T424 L20 E HOPE T42 L20 CRAY T90 E HOPE T424L20 CRAY C90 HadAMS3 2 5x3 75 L20 ORCA2 182x149x31 NEC SX6 ECHAM RCAC reg SGI 03800 Rco oceam tog RCA HIRLAM reg ECHAM5 MPIOM NEC X6 EOT MPIOM SGI IRIX64 NEC SX CRAY C 90 NEC SX E E ROMS cs Interm Atm GCM OCCAM Lite ns Table 3 List of couplings realized with OASIS within the past 5 years in Europe The columns list the institution the country the OASIS version used the atmospheric model the ocean model and the computing platform used for the c
56. id types than before as it is now interfaced with the SCRIP 1 4 library 1 see appendix B See sections 4 and 5 Generate required auxiliary data files See section 6 Compile OASIS3 the component models and start the coupled experiment See section 7 The toy coupled model has successfully run on Fujitsu VPP5000 NEC X5 SGI Octane and 03000 COMPAQ Alpha cluster and Linux PC cluster The appendix C lists some of the coupled models realized with OASIS within the past 5 years or so If you need extra help do not hesitate to contact us oasishelp cerfacs fr In OASIS3 the PIPE SIPC and GMEM communication techniques should still work but are not maintained anymore and were not tested 2 Obtaining OASIS3 sources 2 1 The OASIS3 package OASIS3 and all related libraries are available on PRISM CVS server bedano and on CERFACS CVS server elnino cerfacs fr To obtain the sources from bedano please ask Veronika Gayler gayler dkrz de or Reiner Vogelsang reiner sgi com On CER FACS CVS server the repository is home valcke PRISMCVS To obtain the CVS login and password as well as the most recent OASIS3 tag please contact us oa sishelp 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 an
57. ile _ prism put proto prism get proto leading to e e neri sending receiving actions pl period F2 LAG F1 24 LAG F2 6 prism put proto prism get proto not leading to sending receiving actions Figure 4 LAG concept first example 23 o B Pd e 30 120 18 N 24 ee L J PESEE EIER 6 EM h FI T ZEN el ZI el zi F2 Fi F3 F2 Fl F3 F2 F3 if e f Fi F2 F3 al nlf Fi F2 F3 Pa FI Lb 6 ef 1 E eee eres EN ek SERE ee LY l 24 0 1 p prism put proto prism get proto leading to writing reading to from coupling restart file Model A timestep 6 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 prism get proto called by model B For 75 the prism_put_proto performed at time 18 by model B then leads to a sending action as 18 6 24 which is a coupling period that matches the 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 F5 from their coupling restart files The user therefore have to create those coupling rest
58. ism put proto or prism get proto called in the component models that do effectively lead to a sending or receiving action long red arrows correspond to prism put proto or prism get proto called in the component models that lead to a reading or writing of the coupling field from or to a coupling restart file either directly or through OASIS3 main process During a coupling timestep model A receives F and then sends F its timestep length is 4 During a coupling timestep model B receives F and then sends F3 its timestep length is 6 F and F 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 22 Model B timestep 6 0 6 12 18 24 30 N 120 pup px od tbtebenietpebesa a I 120 Model A timestep 2 4 p prism put proto prism get proto leading to writing reading to from coupling restart f
59. ix of the target grid name in grid data files CHARACTER 4 LAG 14400 optional lag index for the field expressed in seconds see section 3 8 SEQ 1 optional sequence index for the field expressed in seconds see section 3 8 e Field third line P source grid first dimension characteristic P periodical R regional 2 source grid first dimension number of overlapping grid points P target grid first dimension characteristic P periodical R regional 0 target grid first dimension number of overlapping grid points The fourth line gives the list of transformations to be performed for this field There is then one or more additional configuring lines describing some parameters for each transformation These additional lines are described in more details in the section 5 4 3 2 Second section of namcouple for IGNORED IGNOUT and OUTPUT fields The first 2 lines for fields with status IGNORED or IGNOUT or OUTPUT are as follows COSENHFL SOSENHFL 37 86400 1 flda3 nc IGNOUT atmo toce 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 For OUTPUT fields there is no target model and therefore no target symbolic name the source symbolic name must be repeated twice on the field first line Also there is no coupling restart file name flda3 nc here no LAG index and no SEQ index The third line is
60. ixes must now be given on the field second line see section 4 3 2 e A new auxiliary file cf name table lxl For each field the CF standard name used in the OASIS3 log file cplout is now defined in an additional auxiliary file cf name table irt not in inipar F anymore This auxiliary file must be copied to the working directory at the beginning of the run The user may edit and modify this file at her own risk In cf_name_table tat an index is given for each field standard name and associated units The appropriate index has to be indicated for each field in the namcouple third entry on the field first line see section 4 3 This standard name and the associated units are also used to define the field attributes long_name and units in the NetCDF output files written by the PSMILe for fields with status EXPOUT IGNOUT and OUTPUT For more details on this auxiliary file see section 6 1 62 e Many timesteps for mode NONE In mode NONE OASIS3 can now interpolate at once all time occurrences of a field contained in an input NetCDF file The time variable in the input file is recognized by its attribute units The acceptable units for time are listed in the udunits dat file 3 This follows the CF convention The keyword RUNTIME in the namcouple has to be the number of time occur rences of the field to interpolate from the input file The coupling period of the field 4th entry on the field first line must be always
61. n 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 e PRISM_Sent 4 if the field would be sent to another model directly or via OASIS3 main process e PRISM_LocTrans 5 if the field would be only used in a time transformation not sent not output e PRISM ToRest 6 if the field would be written to a restart file only e PRISM Output 7 if the field would be written to an output file only e PRISM SentOut 8 if the field would be both written to an output file and sent to another model directly or via OASIS3 main process e PRISM ToRestOut 9 if the field would be written both to a restart file and to an output file e PRISM_Ok 0 otherwise and no error occurred This is useful when the calculation of the corresponding field array is CPU 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 20 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 resta
62. o 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 30 ACCUMUL INT 1 CONSERV LR SCALAR LATLON 10 FRACAREA FIRST INT 1 Field COSENHFL SOSENHFL 37 86400 1 flda3 nc IGNOUT atmo atmo LAG 7200 SEQ 1 LOCTRANS AVERAGE Field 4 SOALBEDO SOALBEDO 17 86400 0 SOALBEDO nc INPUT ERERERETETERETERERETERETERERERERERERERERETERETERERERERERERERERE ERE EIER RENE RE TERRENI REIR RE ERE ERE EIER EE IE 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 8 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
63. o 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 In binary restart file each field is written 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 Dr 6 4 Input data files Fields with status INPUT in the namcouple will at runtime simply be read in from a NetCDF input file by the target model PSMILe below the prism get proto call at appropriate times corresponding to the input period indicated by the user in the namcouple The name of the file must be the one given on the field first configuring line in the namcouple see section 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 16Note that even if the grid auxiliary data files are in NetCDF format the restart coupling files may be in binary format or vice versa If REDGLO is the first transformation applied on a Reduced grid field the Reduced field must be given is an array restartdata nx ny where nx and ny are the glo
64. 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 38 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 e MASK MASK routine masq f is used before the analysis EXTRAP A given REAL value VALMASK is assigned to all masked points following the source grid mask see section 6 2 so they can be detected by EXTRAP The generic input line is as follows 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 neighbou
65. or 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 ig paral has a differ ent expression depending on the type of the partition In OASIS3 4 types of partition are supported Serial no partition Apple Box and Orange 3 3 1 Serial no partition This is the choice for a monoprocess model In this case we have ig paral 1 3 e ig paral 1 0 indicates a Serial partition e ig paral 2 0 e ig paral 3 the total grid size 3 3 2 Apple partition Each partition is a segment of the global domain described by its global offset and its local size In this case we have ig paral 1 3 e ig paral 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 3 3 3 Box partition Each partition is a rectangular 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 ye e ig paral 5 the global extent in X Figure 2 illustrates
66. oupled model run 61 D The list of changes since last OASIS3 version Here is a list of changes since the last official OASIS3 version i e the differences between the versions tagged oasis3 prism 1 2 delivered in September 2003 and oa sis3_prism_2_1 the current one e Bug corrections Thanks to Eric Maisonnave a bug was found and corrected in prism src lib scrip src scriprmp f sou mask and tgt mask were not properly initialised if weights and addresses were not calculated but read from file Some deallocation were missing in prism terminate proto F ig def part ig length part cg ignout field Thanks to Arnaud Caubel a bug was found and corrected in prism src lib psmile src write file F90 In case of parallel communication between a model and OASIS3 main process the binary coupling restart files were not written properly NetCDF coupling restart files are OK e Routines renamed The routines preproc f extrap f iniiof f in prism src mod oasis3 src were renamed to preproc F extrap F iniiof F as a CPP key key_openmp was added Please note that this key allowing openMP parallelisation is not fully tested yet e Modifications in the namcouple The third entry on the field first line now corresponds to an index in the new auxiliary file cf name table tzt see sections 4 3 and 6 1 For IGNORED IGNOUT and OUTPUT fields the source and target grid locator pref
67. re undesirably seeing climatological SST s directly adjacent to ocean model SST s Where this situation arises the coastal correction consists in identifying the suitable ocean model grid points that can be used to extrapolate the field excluding climatological grid points This analysis requires one configuring line with 3 4 or 6 arguments 1 If FILLING performs the blending of a regional data set with a global one for the Sea Ice Extent the 3 argument 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
68. rs 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 nweights see section 6 5 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 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 5 The configuring line is 1For some grids the extrapolation may not converge if NVOISIN is too large 12An 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 39 EXTRAP operation for CMETHOD WEIGHT CMETHOD NVOISIN CFILE NUMLU NID 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 tran
69. rt file Below the last model B Fy 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 27 First run LAG F1 8 Q A2 8 B 120 Model B LAG F2 6 uoce on E M SEQ F1 22 Restart SEQ F2 1 Restart file F2 file F1 F2 F2 js i F2 1 al el Fi 0 78 12 12 16 116 120 PARS 0 6 12 18 120 LAG F1 24 file F1 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 prism put proto prism get proto not to writing reading to from restart file d Next runs Restart FI 2 I P J leading to sending receiving actions prism put proto prism get protoleading 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 8 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
70. rt writing was successful This routine forces the writing of the field with corresponding var id in its coupling restart file see section 6 3 If a time operation is specified for this field the value of the field as calculated below the last prism put proto is written If no time operation is specified the value of the field transferred to the last prism put proto is written 3 7 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 termination Oasis will terminate after all processes implied in the cou pling call prism terminate proto With MPI2 the run may be considered finished when Oasis terminates to avoid problem place the call to prism terminate proto at the very end in the component model code e CALL prism abort proto compid routine name 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 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 8 Coupling algorithms SEQ and LAG concepts U
71. rtition the maximum number of segments is presently 200 it can be increased by modifying the value of Clim MaxSegments 16 Proc 1 1st segment offset 0 nbr of segments 3 1 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 17 var type INTEGER IN type of coupling field array i e PRISM Real or PRISM Double No automatic conversion is implemented therefore all cou pling fields exchanged through OASIS3 main process must share the same kind ierror INTEGER OUT returned error code 3 5 End of definition phase Each process implied in the coupling closes the definition phase e CALL prism enddef proto ierror ierror INTEGER OUT returned error code 3 6 Sending and receiving actions 3 6 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 REAL IN I O or coupling field array info INTEGER OUT returned info code i
72. rtitioning of the source and target models have to be identical This is supported only by the PSMILe with the MPI1 or MPI2 communication technique e INPUT simply read in from the input file by the target model PSMILe below the prism get proto call at appropriate times corresponding to the input period indicated by the user in the namcouple This is supported only by the PSMILe with the MPI1 or MPI2 communication technique See section 6 4 for the format of the input file e OUTPUT simply written out to an output file by the source model PSMILe be low the prism_put_proto call at appropriate times corresponding to the output period indicated by the user in the namcouple The name of the output file one per field is automatically built based on the field name and initial date of the run INIDATE This is supported only by the PSMILe with MPI1 or 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 SOSSTSST SISUTESU 1 86400 5 sstoc nc sstat nc EXPORTED 182 149 128 64 toce atmo LAG 14400 SEQ 1 P2P0 where the different entries are e Field first line SOSSTSST symbolic name for the field in the source model CHARACTER 8 It has to match the argument name of the corresponding field declaration in the source model see prism def var proto in section 3 4 SISUTESU
73. sformations in the present coupling 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 CORRECT CORRECT routine correct f reads external fields from binary files and uses them to modify the coupling field This transformation can be used for example to perform flux correction on the field 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 i 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 3 40 5 4 The interpolation The following interpolations controlled by interp f are available in OASIS3 e BLASOLD BLASOLD routine blasold f performs a linear
74. sing 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 coupling field in the configuration If the process called MPI_Init before calling prism_init_comp_proto it must also call MPI_Finalize explicitly but only after calling prismterminate_proto With 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 21 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 mod
75. t 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 the smaller first dimension index on the upper coastline The parameter qbeta controls the weights given to the regional and to the global fields in the linear interpolation qbeta has to be 1 nliss 1 The weights given to the regional and global fields in the global model first dimension smoothing bands will be calculated as for the second dimension 45 The user must provide the climatological data file with a specific format described in 6 5 When one uses FILLING for SST with smooth blending thermodynamics consistency requires to modify the heat fluxes over the blending regions The correction term is proportional to the difference between the blended SST and the original SST interpolated on the atmospheric grid and can be written out on a file to be read later for analysis CORRECT for example In that case the symbolic name of the flux correction term read through the input file namcouple must correspond in FILLING and CORRECT analyses In case the regional ocean model includes a coastal part or islands a sea land mask mismatch may occur and a coastal point correction can be performed if the field has been previously interpolated with INTER SURFMESH In fact the mis match could result in the atmosphe
76. vailable in prism src mod oasis3 doc SCRIPusers pdf 55 7 Compiling and running with OASIS3 7 1 Compiling OASIS3 and the toyclim coupled model OASIS3 and the toyclim coupled model use the PRISM standard directory structure and compiling environment For more detail please refer to 4 7 2 Running OASIS3 The toyclim coupled model uses PRISM standard running environment For more detail please refer to 4 56 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 regular Lat Lon grid covering either an hemisphere or the whole globe going from South to North and from West to East There is a grid point at the pole and at the equator if the grid is hemispheric or global with NJ odd The first longitude is 0 t
77. writing routines e CALL prism start grids writing flag flag INTEGER OUT returns 1 0 if grids writing is needed not needed Initialisation of grids writing e CALL prism write grid cgrid nx ny lon lat cgrid CHARACTER 4 IN grid name prefix see 4 3 nx INTEGER IN grid dimension in x direction ny LINTEGER IN grid dimension in y direction lon REAL DIMENSION nx ny IN array of longitudes degrees East lat REAL DIMENSION nx ny IN array of latitudes degrees North Writing of the model grid longitudes and latitudes e CALL prism write corner cgrid nx ny nc clon clat cgrid CHARACTER 4 IN grid name prefix nx INTEGER IN grid dimension in x direction 11 ny LINTEGER IN grid dimension in y direction nc INTEGER IN number of corners per grid cell 4 lon REAL DIMENSION nx ny nc IN array of corner longitudes in degrees Fast lat REAL DIMENSION nx ny nc IN array of corner latitudes in de grees North Writing of the grid cell corner longitudes and latitudes counterclockwise sense Writing of corners is optional as corner information is needed only for some transformations see section 6 2 If called prism write corners needs to be called after prism write grids e CALL prism write mask cgrid nx ny mask cgrid CHARACTER 4 IN grid name prefix nx INTEGER IN grid dimension in x direction ny
78. y on the first line Note that all fields have to be present in the same restart file The time variable in the input file if any is recognized by the its attribute units The acceptable units for time are listed in the udunits dat file 3 This follows the CF convention 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 LOCTRANS can be chosen as first transformation if CLIM MPII MPI2 communica tion and the PSMILe interface are used LOCTRANS requires one configuring line 10For binary input file only one time occurence may be interpolated 3T on which a time transformation automatically performed below the call to PSMILe prism put proto should be indicated 9 3 INSTANT no time transformation the instantaneous field is transferred ACCUMUL the field accumulated over the previous coupling period is transferred AVERAGE the field averaged over the previous coupling period is transferred T MIN the minimum value of the field for each source grid point over the previous coupling period is transferred T MAX the maximum value of the field for each source grid point over the previous coupling period is transferred ONCE only one prism put proto or prism get proto will be performed this is equivalent to giving the length of the run as coupling or I O period The pre pro

Download Pdf Manuals

Related Search

Related Contents

GEMINI EXPRESS MULTIPLEXER User's Guide  Samsung CE2618N manual de utilizador    SHAMPOO DE ALFOMBRAS - Distribuidora DITAGO      

Copyright © All rights reserved. Failed to retrieve file