Home

OASIS3-MCT User Guide OASIS3-MCT 2.0

1. DISTWGT performs a distance weighted nearest neighbour interpolation N neighbours All types of grids are supported x Masked target grid points the zero value is associated to masked target grid points x Non masked target grid points having some of the N source nearest neighbours masked a nearest neighbour algorithm using the remaining non masked source nearest neighbours is applied x Non masked target grid points having all of the N source nearest neighbours masked by default the nearest non masked source neighbour is used logical 11_nnei hard coded to true in oasis3 mct lib scrip src remap_distwgt F same default behaviour as OASIS3 3 The configuring line is SCRIPR for DISWGT SCMETH CGRS SCFTYP REST SNBIN SNV SASSCMP SPROJCART where SCMETH DISTWGT SCGRS is the source grid type LR D or U see appendix A SCFTYP is the field type SCALAR The option VECTOR which in fact leads to a scalar treatment of the field as in the previous versions is still accepted WECTOR_I or See also http climate lanl gov Software SCRIP and the copyright statement in appendix 1 3 3 4 3 THE REMAPPING INTERPOLATION 31 VECTOR_J i e vector fields are not supported anymore in OASIS3 MCT See Support of vector fields with the SCRIPR remappings below SREST is the search restriction type LATLON or LATITUDE see SCRIP 1 4 documen tation SCRIPusers pdf SNBIN the number of res
2. e 29 4 3 The remapping interpolation 2 2 0 0 0 2 0 0000000000005 29 4 4 The post processing stages s ma Boeke ane eon be ann Boe ee 33 5 OASIS3 MCT auxiliary data files 35 51 Grid data files ge ei oe Se BO we 35 32 Coupling restart files recan 4 ar Bos ae bs ed eo as at go ea a a 36 3 35 Input data flesh irra ii sh eg Sa a bl eae Ba ae bee be WASH Daw Sake BX 36 5 4 Transformation auxiliary data files 2 2 2 ee ee 36 6 Compiling running and debugging 38 6 1 Compiling OASIS3 MCT 38 6 2 EBPIKOYS seis ae hc ke ate he A A E ce eae ase E 38 6 3 Running OASIS3 MCT zu serant rai ee 39 6 3 1 Thetutorialtoymodel o e 39 6 3 2 The test interpolation environment e 39 6 4 DEDUSSMES s raras a A sa E 39 6 4 1 Debus files to peli mee a a ta eels 39 6 4 2 Time statistics files o o o e R E a 40 A The grid types for the transformations 41 B Changes between the different versions of OASIS3 MCT 42 B 1 Changes between OASIS3 MCT_1 0 and OASIS3 MCT 2 0 o ooo 42 B 2 Changes between OASIS3 3 and OASIS3 MCT_1 0 o ooo 43 B 2 1 General architecture e 43 B 2 2 Changes in the coupling interface in the component models 43 B 2 3 Functionality not offered anymore o o e 44 B 2 4 New functionality offered o o e e 45 B 2 5 Changes in the configuratio
3. e ig_paral 3 the segment local size Figure 2 1 illustrates an Apple partition over 3 processes 2 4 3 Box partition Each partition is a rectangular region of the global domain described by the global offset of its upper left corner and its local extents in the X and Y dimensions The global extent in the X dimension must also be given In this case we have ig_paral 1 5 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 12 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT T an al extent 5 Proc 1 Proc 2 Proc 3 local offset 0 local offset 2 local offset 10 local x extent 2 local x extent 3 local x extent 5 local y extent 2 local y extent 2 local y extent 1 Figure 2 2 Box partition It is assumed here that the index start at O in the upper left corner e ig paral e ig_paral 4 the local extent in y 5 the global extent in x Figure 2 2 illustrates a Box partition over 3 processes 2 4 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 wher
4. Obsolete in OASIS3 MCT exists however for upward compatibility e CALL oasis write grid cgrid nx ny lon lat or e CALL prism_write_grid cgrid nx ny lon lat cgrid CHARACTERx4 IN grid name prefix see 3 3 nx INTEGER IN first grid dimension x ny INTEGER IN second grid dimension y lon REAL DIMENSION nx ny IN single or double real array of longitudes de grees East lat REAL DIMENSION nx ny IN single or double real array of latitudes de grees North Writes the model grid longitudes and latitudes Longitudes must be given in degrees East in the interval 360 0 to 720 0 Latitudes must be given in degrees North in the interval 90 0 to 90 0 Note that if some grid points overlap it is recommended to define those points with the same number e g 90 0 for both not 450 0 for one and 90 0 for the other to ensure automatic detection of overlap by OASIS3 MCT which is essential to have a correct conservative remapping SCRIPR CONSERV see section 4 3 e CALL oasis_write_corner cgrid nx ny nc clon clat or e CALL prism_write_corner cgrid nx ny nc clon clat cgrid CHARACTER 4 IN grid name prefix nx INTEGER IN first grid dimension x ny INTEGER IN second grid dimension y nc INTEGER IN number of corners per grid cell always 4 in th
5. ically share the same MP1_COMM_WORLD communicator and an internal communicator created by OASIS3 MCT needs to be used for internal parallelization see section 2 2 2 B 2 2 Changes in the coupling interface in the component models e Use statement The different OASIS3 3 USE statements were gathered into one USE mod_oasis or one USE mod_pri sm therefore much simpler to use e Support of previous prism_xxx and new oasis_xxx interfaces OASIS3 MCT retains prior interface names of OASIS3 3 e g prism_put_proto to ensure full backward compatibility However new interface names such as oasis_put are also available and should be prefered Both routine names are listed in chapter 2 e Auxiliary routines not supported yet Auxiliary routines prism_put_inquire prism_put_restart_proto prism_get_freq are not supported yet lAs with OASIS3 3 the put calls are non blocking but the get calls are blocking As before the user has to take care of implementing a coupling algorithm that will result in matching put and get calls to avoid deadlocks see section 2 7 The lag LAG index works as before in OASIS3 3 see section 2 10 44 APPENDIX B CHANGES BETWEEN THE DIFFERENT VERSIONS OF OASIS3 MCT e Support of components for which only a subset of processes participate in the coupling New routines oasis_create_couplcomm and oasis_set_couplcomm are now available to create or set a coupling communicato
6. fid2 depends on fid1 If this dependency is known then there is a benefit in using SEQ 1 for fidl and SEQ 2 for fld2 At runtime if the sequencings of both modell and model2 do not match the above diagram the model will abort gracefully For instance if model2 has the dependency shown above but modell does not have consistent ordering of the put and get as required by model2 then if SEQ is unused the model will deadlock and hang If SEQ is set properly the coupling layer will detect that the required sequence has not been followed and will exit gracefully with an error message Again the SEQ namecouple setting is only diagnostic and is not required Chapter 3 The configuration file namcouple The OASIS3 MCT configuration file namcouple contains below pre defined keywords all user s defined information necessary to configure a particular coupled run The namcouple is a text file with the following characteristics e the keywords used to separate the information can appear in any order e the number of blanks between two character strings is non significant e all lines beginning with are ignored and considered as comments e blank lines are not allowed The first part of namcouple is devoted to configuration of general parameters such as the number of models involved in the simulation or the number of fields The second part gathers specific information on each coupling or I O field e g their coupling period the list of tra
7. If you need extra help do not hesitate to contact us see contact details on the back of the cover page 1 2 OASIS3 MCT sources OASIS3 MCT sources are available from CERFACS SVN server To obtain more detail on downloading the sources please fill in the registration form at https verc enes org oasis download oasis registration form OASIS3 MCT directory structure is the following one oasis3 mct lib psmile OASIS3 MCT coupling library scrip SCRIP interpolation library met Model Coupling Toolkit Coupling Software oasis3 mct doc OASIS3 MCT User Guide oasis3 mct util make_dir Utilities to compile OASIS3 MCT oasis3 mct examples Environment to run the tutorial and test_interpolation toy coupled models 4 CHAPTER 1 INTRODUCTION 1 3 Licenses and Copyrights 1 3 1 OASIS3 MCT license and copyright statement Copyright 2013 Centre Europ en de Recherche et Formation Avanc e en Calcul Scientifique CERFACS This software and ancillary information called OASIS3 MCT is free software CERFACS has rights to use reproduce and distribute OASIS3 MCT The public may copy distribute use prepare derivative works and publicly display OASIS3 MCT under the terms of the Lesser GNU General Public License LGPL as published by the Free Software Foundation provided that this notice and any statement of authorship are reproduced on all copies If OASIS3 MCT is modified to produce derivative works such modified software sh
8. OASIS Real or PRISM Real i e 4 for single or double precision real arrays All coupling data is treated as double pre cision in the coupling layer but conversion to or from single precision data is supported in the interface INTEGER OUT returned error code 2 6 End of definition phase All component processes close the definition phase e CALL e CALL oasis_enddef ierror prism_enddef_proto ierror error INTEGER OUT returned error code 2 7 Sending put and receiving get actions 2 7 1 Sending a coupling or VO field In the model time step loop each process sends its part of the coupling or I O field e CALL e CALL var_id 2 5 date oasis_put prism_put var_id date fldl f1d2 f1d3 1d4 f1d5 info t_proto var_id date fldl fld2 fld3 f1d4 fld5 info INTEGER IN field ID from corresponding oasis_def_var see section INT EGER IN number of seconds or any other time units as long as the same are used in all models and in the namcouple at the time of the call by convention at the beginning of the timestep 1dl REA 1d2 REA 17 1d3 REAL 17 1d4 REA U h h h hh A 1d5 REA 17 info 17 IN coupling or I O field array can be 1D or 2D IN OPTIONAL IN OPTIONAL IN OPTIONAL IN OPTIONAL optional 2 coupling field
9. Toolkit MCT OASIS3 MCT is a coupling library to be linked to the component models and that carries out the coupling field transformations e g remappings interpolations in parallel on either the source or target processes and that performs all communication in parallel directly between the component models there is no central coupler executable anymore e MAPPING transformation to use a pre defined mapping file With MAPPING OASIS3 MCT has the ability to read a predefined set of weights and addresses mapping file specified in the namcouple to perform the interpolation remapping The user also has the flexibility to choose the location and the parallelization strategy of the remapping with specific MAPP ING options see section 4 3 e Mono process mapping file generation with the SCRIP library But as before OASIS3 MCT_1 0 can also generate the mapping file using the SCRIP library Jones 1999 When this is the case the mapping file generation is done on one process of the model compo nents all previous SCRIPR remapping schemes available in OASIS3 3 are still supported besides BICUBIC and CONSERV SECOND Note these remapping schemes not available in OASIS3 MCT_1 0 were reactivated in OASIS3 MCT 2 0 see B 1 e MPI2 job launching is NOT supported Only MPI1 start mode is allowed As before with the MPI1 mode all component models must be started by the user in the job script in a pseudo MPMD mode in this case they will automat
10. Toulouse France 2000 50 BIBLIOGRAPHY
11. are allowed for different coupling exchanges of the same field If coupling restart files are required either if a LAG or if a LOCTRANS transformation is specified it is mandatory to specify different files for the different fields 2 7 2 Receiving a coupling or I O field In the model time stepping loop each process receives its part of the coupling field e CALL oasis_get var_id date fld info 16 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT e CALL prism_get_proto var_id date fld info var id INTEGER IN field ID from the corresponding oasis_def_var date INTEGER IN number of seconds or any other time units as long as the same are used in all models and in the namcouple at the time of the call by convention at the beginning of the timestep fld REAL OUT I O or coupling field array info INTEGER OUT returned info code x x x x OASIS_Recvd 3 if the field was received from another model OASIS_FromRest 10 if the field was read from a restart file only OASIS Input 11 if the field was read from an input file only OASIS _RecvOut 12 if the field was both received from another model and written to an output file OASIS_FromRestOut 13 if the field was both read from a restart file and written to an output file OASIS_Ok 0 otherwise and no error occurred This routine may be called by the model at each timestep The date argument is automat
12. array can be 1D or 2D optional 3 coupling field array can be 1D or 2D optional 4 coupling field array can be 1D or 2D 5th optional 5 coupling field array can be 1D or 2D INTEGER OUT returned info code x OASIS Sent 4 if the field was sent to another model OASIS _LocTrans 5 if the field was only used in a time transformation not sent not output OASIS _ToRest 6 if the field was written to a restart file only x OASIS Output 7 if the field was written to an output file only OASIS _SentOut 8 if the field was both written to an output file and sent to another model directly or via OASIS3 main process 3 Parameters OASIS In PRISM In OASIS Out PRISM Out are defined in oasis3 mct lib psmile src mod_oasis_parameters F90 2 7 SENDING PUT AND RECEIVING GET ACTIONS 15 OASIS _ToRestOut 9 if the field was written both to a restart file and to an output file OASIS Ok 0 otherwise and no error occurred To ensure a proper use of the oasis_put one has to take care of the following aspects e A 274 gra 4th and 5 source field can be passed as optional arguments If so the gnd 3rd qth and 5 set of weights present in the remapping file will be applied respectively see section 5 4 for the weight file format This will be used for example for the SCRIPR BICUBIC remapping for which a 1 27d 37d 4h set of weights should be respectively applied to the f
13. cpl setup time spent in oasis_coupler_setup which sets up additional coupling aspects related to oasis method _enddef e cpl_smatrd time spent in oasis_coupler_smatreaddnc in mod_oasis_coupler rou tine oasis_coupler_setup this routine performs a distributed read of a NetCDF SCRIP file and returns weights in a distributed SparseMatrix and calls mct_sMatP_Init which initialises the sparse matrix vector multiplication e oasis advance init time spent in oasis_advance_init which handles reading of initial coupling restart and communication of data for fields with positive lags e grcv_00x time spent in the reception of field x in mct_recv including communication and possible waiting time linked to unbalance of components e wout_00x time spent in the I O for field x in routine oasis_advance_run e gcpy_00x time spent in routine oasis_advance_run in copying the field x just received in a local array e pcpy_00x time spent in routine oasis_advance_run in copying the local field x in the array to send i e with local transformation besides division for averaging e pavg 00x time spent in routine oasis_advance_run to calculate the average of field x if done e pmap_00x gmap_00x time spent in routine oasis_advance_run for the matrix vector mul tiplication for field x on the source target processes e pand OUS time spent in routine oasis_advance_run for sending field x i e incl
14. followed in real time by registering on the Redmine project management site at https inle cerfacs fr see Register at the right top of the page On this site registered users can browse the sources and consult tickets describing bug fixes and developments To follow day to day evolution of the OASIS3 MCT sources it is also possible to have your e mail added to the list of addresses to which the log files of the SVN checkins are automatically sent please contact oasishelp cerfacs fr if you wish to be added to that list B 1 Changes between OASIS3 MCT_1 0 and OASIS3 MCT 2 0 The main changes and bug fixes new in OASIS3 MCT_2 0 are the following Support of BICUBIC interpolation see paragraph BICUBIB in section 4 3 Support of CONSERV SECOND regridding see paragraph CONSERV SECOND in section 4 3 Support of components exchanging data on only a subdomain of the global grid a new optional argument ig_size was added to oasis_def partition that provides the user with the ability to define the total number of grid cells on the grid see section 2 4 The CPP key balance in mod_oasis_advance was added this option can be used to produce times tamps in OASIS debug file see section 6 2 The variable TIMER_Debug controlling the amount of time statistics written out is now an optional argument read in the namcouple see the NLOGPRT line in 3 2 and all details about time statistics in section 6 4 2 Specific prob
15. for each model and processor The first number that can be changed at runtime with the oasis_set_debug routine see section 2 9 may be 0 one file debug root xx is open by the master proces of each model and one file de bug_notroot xx is open for all the other processes of each model to write only error infor mation 1 one file debug root xx is open by the master proces of each model to write information equivalent to level 10 see below one file debug _notroot xx is open for all the other processes of each model to write error information 2 one file debug xx xxxxxx is open by each process of each model to write normal production diagnostics 5 as for 2 with in addition some initial debug info 10 as for 5 with in addition the routine calling tree 12 as for 10 with in addition some routine calling notes 15 as for 12 with even more debug diagnostics 3 3 SECOND SECTION OF NAMCOUPLE FILE 25 3 3 20 as for 15 with in addition some extra runtime analysis 30 full debug information The second number defines how time statistics are written out to file timers_xxxx it can be 0 nothing is calculated nothing is written 1 some time statistics are calculated and written in a single file by the processor 0 as well as the min and the max times over all the proce Sssors 2 some time statistics are calculated and each processor writes its own file proces
16. given as a REAL value e g 2 0 and not 2 defines the weight given to a neighbour source grid point as proportional to exp 1 2 d 0 where d is the distance between the source and target grid points and o V AR d where 2 l l Z d is the average distance between two source grid points calculated automatically by OASIS3 MCT BILINEAR performs an interpolation based on a local bilinear approximation see details in chapter 4 of SCRIP 1 4 documentation SCRIPusers pdf Logically Rectangular LR and Reduced D source grid types are supported BICUBIC performs an interpolation based on a local bicubic approximation for Logically Rectangular LR grids see details in chapter 5 of SCRIP 1 4 documentation SCRIPusers pdf and on a 16 point stencil for Gaussian Reduced D grids Note that for Logically Rectangular grids 4 weights for each of the 4 enclosing source neighbours are required corresponding to the field value at the point the gradient of the field with respect to i the gradient of the field with respect to j and the cross gradient with respect to 7 and j in that order OASIS3 MCT will calculate the remapping weights and addresses if they are not already provided but will not at run time calculate the two gradients and the cross gradient of the source field as was the case with OASIS3 3 These 3 extra fields need to be calculated by the source code and transfered as extra arguments of the oasis_put
17. interval between these calls AVERAGE the field averaged over the previous coupling period is transferred the average is simply done over the arrays field array provided as third argument to the oasis put calls not weighted by the time interval between these calls 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 UNUSED not supported in OASIS3 MCT With OASIS3 MCT time transformations are supported more generally with use of the coupling restart file The coupling restart file allows the partial time transformation to be saved at the end of a run for exact restart at the start of the next run For that reason coupling restart filenames are now required for all namcouple entries that use LOCTRANS with non INSTANT values This is the reason an optional restart file is now provided on the OUTPUT namcouple input line 4 2 THE PRE PROCESSING TRANSFORMATIONS 29 4 2 4 3 The pre processing transformations REDGLO UNUSED INVERT UNUSED MASK UNUSED EXTRAP UNUSED CHECKIN CHECKIN calculates the global minimum the maximum and the sum of the source field values not weighted by the grid cell area and prints them to the OASIS3 MCT debug file for the master process of the source component model only This oper
18. line gives the list of transformations to be performed for this field In addition there is one or more configuring lines describing some parameters for each transformation These additional lines are described in more details in the chapter 4 3 3 2 Second section of namcouple for OUTPUT fields The first 2 lines for fields with status OUTPUT are as follows COSHFTOT COSHFTOT 7 86400 0 fldhftot nc OUTPUT atmo atmo where the different entries are as for EXPOUT fields except that e the source symbolic name must be repeated twice on the field first line e the restart file name here 1dhftot nc is needed only if a LOCTRANS transformation is present e there is no output file name on the first line e there is no grid dimension and no LAG or SEQ index on the second line The name of the output file is automatically defined based on the field and component model names The third line is LOCTRANS if this transformation is chosen for the field Note that LOCTRANS is the only transformation supported for OUTPUT fields For 1D field put 1 as the second dimension gt This means that all output fields will be written out in the output files as 1D arrays this should be fixed in the next OASIS3 MCT version 3 3 SECOND SECTION OF NAMCOUPLE FILE 27 3 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 d
19. part of the namcouple If more than one field are described on the same line new in OASIS3 MCT 1 0 see appendix B 2 4 this counts as only one entry JOBNAME UNUSED SNBMODEL On the line below this keyword is the number of models running in the given experi ment followed by CHARACTERA6 variables giving their names which must correspond to the name announced by each model when calling oasis_init_comp second argument see section 2 2 Then the user may indicate on the same line 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 In all cases OASIS3 MCT library assumes during the initialization phase that units 1025 and 1026 are free and temporarily uses these units to read the namcouple and to write corresponding log messages to file nout 000000 After the initialization phase OASIS3 MCT will still suppose that units above 1024 are free unless maximum unit numbers are indicated here in the namcouple SRUNTIME On the line below this keyword is the total simulated time of the run expressed in seconds or any other time units as long as the same are used in all models and in the namcouple see 2 7 SINIDATE UNUSED S MODINFO UNUSED SNLOGPRT The first and second numbers on the line below this keyword refer to the amount of debug and time statistic information written by OASIS3 MCT
20. side The prior feature that supported linear combinations of the current coupling field with any other fields after the interpolation has been deprecated This analysis requires the same input line s as BLASOLD MASKP UNUSED REVERSE UNUSED CHECKOUT CHECKOUT calculates the global minimum the maximum and the sum of the target field values not weighted by the grid cell area and prints them to the OASIS3 MCT debug file for the master process of the target component model only This operation does not transform the field The generic input line is as for CHECKIN see above GLORED UNUSED Chapter 5 OASIS3 MCT auxiliary data files In some cases OASIS3 MCT uses auxiliary data files e g defining the grids of the models being coupled containing the field coupling restart values or input data values or the remapping weights and addresses 5 1 Grid data files With OASIS3 MCT the grid data files grids nc masks nc and areas nc are required only for certain oper ations i e grids nc and masks nc for SCRIPR see section 4 3 and masks nc and areas nc for CONSERV see section 4 4 These NetCDF files can be created by the user before the run or can be written directly at run time by the master process of each component model using the grid data definition routines see section 2 3 These routines can be used by the component models to add grid fields to the grid files but grid fields are never overwritten in the grid file
21. than 0 is automatically written to its coupling restart file below the last F oasis_put as the date lag equals the total run time The analogue is true for F gt These values will automatically be read in at the beginning of the next run below the respective oasis_get 2 LAG concept second example A second coupling algorithm exploiting the LAG concept is illustrated on figure 2 5 During its timestep model A receives F5 sends F and then F its timestep length is 6 During its timestep 2 10 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS 19 0 6 di 4 8 Model A timestep 4 Model B timestep 6 ee eee S ee FT F2 rif rf rife Hp rife Fl rf FIP F2 Fi rf rf Fl APA PRA sl LS E NI e AE O eee Soe O A SRP 0 1 Cpl_period F1 12 Cpl_period F2 24 LAG F1 4 LAG F2 6 18 24 30 120 rol F T r F T F2 Fi F2 6 20 24 28 120 prism put proto prism_get_proto leading to writing reading to from coupling restart file gt prism put _proto prism_get_proto leading to sending receiving actions gt prism_put_proto prism_get_proto not leading to sending receiving actions Figure 2 4 LAG concept first example 20 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT a B Kia a 30 120 Lis 18 EEEE 24 Solo re 6 AAA xs Lor O 2 T efes L e efet F2 19 F3 F2 Fi F3 F2 F3 rf e SI Fi F2 F3 if pa rf Fi F2 F3 Pa F Te ENE 5 ef 17 A 4
22. the process called MPI_Init before calling oasis_init_comp or prism init comp_proto it must also call MPI_Finalize explicitly but only after calling oasis_terminate_proto or prism_terminate_proto 2 10 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS 17 name of the calling model the name of the calling routine and the message to the process debug file see SNLOGPRT in section 3 2 This routine cannot be called before oasis_init_comp e CALL oasis get debug debug_value e CALL prism_get_debug debug_value debug_value INTEGER OUT debug value This routine may be called at any time to retrieve the current OASIS3 MCT internal debug level see SNLOGPRT in section 3 2 This is useful if the user wants to return the original debug value after changing it e CALL oasis set debug debug_value e CALL prism_set debug debug value debug_value INTEGER IN debug value This routine may be called at any time to change the debug level in OASIS3 MCT This method allows users to vary the debug level at different points in the model integration e CALL oasis_get_intercomm new_comm cdnam kinfo e CALL prism_get_intercomm new_comm cdnam kinfo new_comm INTEGER OUT mpi intercomm communicator cdnam CHARACTERx IN other model name kinfo INTEGER OUT OPTIONAL returned error code This routine sets up an MPI intercomm commu
23. yet When the lag is positive a restart file must be available to initiate the coupling and in those cases the restart file is then updated at the end of the run A positive lag acts like a send occurred before the model started In fact for a field with positive lag the source component model automatically reads the field in the restart file during the coupling initialization phase below the oasis_enddef and send the data to match the oasis_get performed at time 0 in the target component model The final coupling data on the source side will then be automatically written to the restart file for use in the next run When there is a lag the first and last instance of the source field in the debug netCDF file EXPOUT fields see section 3 3 always correspond respectively to the field read from and written to the restart file 1 LAG concept first example A first coupling algorithm exploiting the LAG concept is illustrated on figure 2 4 On the 4 figures in this section short black arrows correspond to oasis_put or oasis_get called in the component model that do not lead to any put or receiving action long black arrows correspond to oasis_put or oasis_get called in the component models that do actually lead to a put or get action long red arrows correspond to oasis_put or oasis_get called in the component models that lead to a reading or writing of the coupling field from or to a coupling restart file During a coupling
24. 0 assigned to these target grid cell intersecting only masked source cells for easier identification is not yet availble in OASIS3 MCT Support of vector fields with the SCRIPR remappings Vector mapping is NOT supported and will not be supported by OASIS3 MCT For proper treatment of vector fields the component model has to send the 3 components of the vector projected in a Cartesian coordinate system INTERP UNUSED MOZAIC UNUSED note that MAPPING see above is the NetCDF equivalent to MOZAIC NOINTERP UNUSED FILLING UNUSED The post processing stage CONSERV CONSERV ensures a global modification of the coupling field This analysis requires the source and target grid mesh areas to be transfered to the coupler with oasis_write_area see section 2 3 For a correct CONSERV operation overlapping grid cells on the source grid or on the target 34 CHAPTER 4 TRANSFORMATIONS AND INTERPOLATIONS grid must be masked In the namcouple CONSERV requires one input line with one argument and one optional argument CONSERV operation SCMETH S CONSOPT where SCMETH is the method desired with the following choices with SCMETH GLOBAL the field is integrated on both source and target grids with out considering values of masked points and the residual target source is uniformly distributed on the target grid this option ensures global conservation of the field with SCMETH GLBPOS the same o
25. 3 MCT CALL oasis_set_couplcomm couplComm ierror The call to MPI_COMM Split and oasis_set_couplcomm could be replaced by CALL oasis_create_couplcomm icpl localComm couplComm ierror CALL oasis_def partition CALL oasis_def_ var CALL oasis_enddef do loop U if couplingpe CALL oasis_put l if couplingpe CALL oasis_get l enddo CALL oasis_terminate Bibliography Cassou et al 1998 Cassou C P Noyret E Sevault O Thual L Terray D Beaucourt and M Im bard Distributed Ocean Atmosphere Modelling and Sensitivity to the Coupling Flux Precision the CATHODe Project Monthly Weather Review 126 No 4 1035 1053 1998 Guilyardi et al 1995 Guilyardi E G Madec L Terray M D qu M Pontaud M Imbard D Stephenson M A Filiberti D Cariolle P Delecluse and O Thual Simulation coupl e oc an atmosphere de la variabilit du climat C R Acad Sci Paris t 320 s rie Ila 683 690 1995 Jacob et al 2005 Jacob R J Larson and E Ong MxN Communication and Parallel Interpolation in CCSM3 Using the Model Coupling Toolkit Int J High Perf Comp App 193 293 307 2005 Jones 1999 Jones P Conservative remapping First and second order conservative remapping Mon Weather Rev 127 2204 2210 1999 Larson et al 2005 Larson J R Jacob and E Ong The Model Coupling Toolkit A New Fort
26. 9 SRUNTIME 432000 SINIDATI it SMODINFO SNLOGPRT 2 1 E SCALTYP Ht Ht HH AHHH RRHH AAA Second section SSTRINGS E Field 1 SOSSTSST SISUTESU 1 86400 5 sstoc nc EXPORTED 182 149 128 64 toce atmo LAG 14400 SEQ 1 P2P 0 LOCTRANS CHECKIN MAPPING BLASNEW CHECKOUT AVERAGE INT 1 map_toce_atmo_120315 nc src opt CONSTANT 273 15 INT 1 Field 2 CONSFTOT SOHEFLDO 6 86400 4 flxat nc EXPORTED atmo toce LAG 14400 SEQ 2 POP 2 LOCTRANS CHECKIN SCRIPR CHECKOUT ACCUMUL INT 1 BILINEAR LR SCALAR LATLON 1 INT 1 Field 3 COSENHFL SOSENHFL 37 86400 1 flda3 nc IGNOUT atmo atmo LAG 7200 LOCTRANS 24 CHAPTER 3 THE CONFIGURATION FILE NAMCOUPLE AV ERAGE T Field 4 SOALBEDO SOALBEDO 7 86400 0 SOALBEDO nc INPUT FE TE aE aE aE AE aE a aE aE aE aE ae aE HE aE aE aE AE FE E HEE aaa aaa aaah AE HE FE AE FE AE TE AE TE AE FE TE AE TE AE E E EAE EE E 3 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 SEQMODE UNUSED CHANNEL UNUSED NFIELDS On the line below this keyword is the total number of field entries in the second
27. ASIS3 on this field sstoc nc name of the coupling restart file for the field CHARACTER 8 mandatory even if no coupling restart file is effectively used for more detail see section 5 2 EXPORTED field status e Field second line 182 number of points for the source grid first dimension optional 149 number of points for the source grid second dimension optional 128 number of points for the target grid first dimension optional 64 number of points for the target grid second dimension optional These source and target grid dimensions are optional but note that in order to have 2D fields written as 2D arrays in the debug files these dimensions must be provided in the namcouple otherwise the fields will be written out as 1D arrays toce prefix of the source grid name in grid data files see section 5 1 CHARACTER 4 atmo prefix of the target grid name in grid data files CHARACTER 4 LAG 14400 optional lag index for the field see section 2 10 1 SEQ 1 optional sequence index for the field see section 2 10 2 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
28. Climate Dynamics 11 487 505 1995 Terray et al 1999 Terray L S Valcke and A Piacentini OASIS 2 3 Ocean Atmosphere Sea Ice Soil User s Guide and Reference Manual Technical Report TR CMGC 99 37 CERFACS Toulouse France 1999 Valcke 2013 Valcke S The OASIS3 coupler a European climate modelling community software Geosci Model Dev 6 373 388 Valcke et al 2012 Valcke S T Craig L Coquart OASIS3 MCT User Guide OASIS3 MCT 1 0 Technical Report WN CMGC 12 49 CERFACS Toulouse France 2012 BIBLIOGRAPHY 49 Valcke et al 2011 Valcke S M Hanke L Coquart OASIS4_1 User Guide Technical Report TR CMGC 11 50 CERFACS Toulouse France 2011 Valcke 2006b Valcke S OASIS3 User Guide prism_2 5 Technical Report TR CMGC 06 73 CER FACS Toulouse France 2006 Valcke 2006a Valcke S OASIS4 User Guide OASIS4 02 Technical Report TR CMGC 06 74 CERFACS Toulouse France 2006 Valcke et al 2004 Valcke S A Caubel R Vogelsang and D Declat OASIS3 User s Guide oa sis3_prism_2 4 PRISM Report No 2 5th Ed CERFACS Toulouse France 2004 Valcke et al 2003 Valcke S A Caubel D Declat and L Terray OASIS3 Ocean Atmosphere Sea Ice Soil User s Guide Technical Report TR CMGC 03 69 CERFACS Toulouse France 2003 Valcke et al 2000 Valcke S L Terray and A Piacentini OASIS 2 4 Ocean Atmosphere Sea Ice Soil User s Guide and Reference Manual Technical Report TR CMGC 00 10 CERFACS
29. RSE GLORED e To get 2D fields in the debug output NetCDF files the 2D dimensions of the grids must be provided in the namcouple except if the field has the status OUTPUT otherwise the fields in the debug output files will be 1D B 2 6 Other differences e IGNORED and IGNOUT fields are converted to EXPORTED and EXPOUT respectively e The file areas nc is not needed anymore to calculate some statistics with options CHECKIN and or CHECKOUT see section 4 2 e SEQ index is no longer needed to ensure correct coupling sequencing within the coupler Use of SEQ allows the coupling layer to detect potential deadlocks before they happen and to exit grace fully see section 2 10 2 e The UO library mpp_io is no longer used to write the restart and output files Appendix C API for processes not involved in the coupling Here is a coding sample of how to use the API routines for the processes not involved in the coupling while other processes of the same executable are involved in the coupling CALL oasis_init_comp comp_id comp_name ierror CALL oasis_get_localcomm localComm ierror create communicator gathering coupling processes every other CALL MPI_Comm_Rank localComm mype ierror couplingpe false if mod mype 2 0 couplingpe true icpl MPI_UNDEFINED if couplingpe icpl 1 CALL MP1_COMM_Split localComm icpl 1 couplComm ierror provide this communicator to OASIS
30. TION OF LIABILITY IN NO EVENT WILL THE COPYRIGHT HOLDER THE UNITED STATES THE UNITED STATES DEPARTMENT OF ENERGY OR THEIR EMPLOYEES BE LIABLE FOR ANY INDIRECT INCIDENTAL CONSEQUENTIAL SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA FOR ANY REASON WHATSOEVER WHETHER SUCH LIA BILITY IS ASSERTED ON THE BASIS OF CONTRACT TORT INCLUDING NEGLIGENCE OR STRICT LIABILITY OR OTHERWISE EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES 1 3 3 The SCRIP 1 4 license copyright statement The SCRIP 1 4 copyright statement reads as follows Copyright 1997 1998 the Regents of the University of California This software and ancillary infor mation herein called SOFTWARE called SCRIP is made available under the terms described here The SOFTWARE has been approved for release with associated LA CC Number 98 45 Unless otherwise in dicated this SOFTWARE has been authored by an employee or employees of the University of California operator of Los Alamos National Laboratory under Contract No W 7405 ENG 36 with the United States Department of Energy The United States Government has rights to use reproduce and distribute this SOFTWARE The public may copy distribute prepare derivative works and publicly display this SOFT WARE without charge provided that this Notice and any statement of authorship are reproduced on all copies Neither the Governmen
31. V For SCRIPR CONSERV remapping grid mesh corners will not be compute automatically if they are needed but not provided e Other transformations not supported The following transformations are not available in OASIS3 3 and will most probably not be implemented as it should be not too difficult to implement the equivalent operations in the component models themselves CORRECT FILLING SUBGRID MASKP LOCTRANS ONCE is not explicitely offered as it is equivalent to defining a coupling period equal to the total runtime The following transformations are not available as they were already deprecated in OASIS3 3 see OASIS3 3 User Guide REDGLO INVERT REVERSE GLORED MASK and EXTRAP are not available but the corresponding linear extrapolation can be re placed by the more efficient option using the nearest non masked source neighbour for tar get points having their original neighbours all masked This is now the default option for SCRIPR DISTWGT GAUSWGT and BILINEAR interpolations It is also included in SCRIPR CONSERV if FRACNNEI normalization option is chosen see section 4 3 INTERP interpolations are not available SCRIPR should be used instead MOZAIC is not available as MAPPING should be used instead NOINTERP does not need to be specified anymore if no interpolation is required Field combination with BLASOLD and BLASNEW these transformations only support multi
32. ace has a different expression depending on the type of the partition in OASIS3 MCT 4 types of partition are supported Serial no partition Apple Box and Orange see below ierror INTEGER OUT returned error code isize INTEGER OPTIONAL IN Optional argument needed if the coupling data is exchanged for only a subdomain of the global grid in this case isize must give the total dimension of the grid total number of points 2 4 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 2 4 PARTITION DEFINITION 11 Proc 1 Proc 2 local offset 0 local offset 4 local size 4 local size 6 Proc 3 local offset 10 local size 5 Figure 2 1 Apple partition It is assumed here that the index start at 0 in the upper left corner e ig_paral 2 0 e ig paral 3 the total grid size 2 4 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
33. apping file MAPPING can still be listed in the namcouple to specify a name for the remapping file generated by SCRIPR different from the default and or to specify a SMAPLOC or SMAPSTRATEGY option SCRIPR SCRIPR gathers the interpolation techniques offered by Los Alamos National Laboratory SCRIP 1 4 library Jones 1999 SCRIPR routines are in oasis3 mct lib scrip See the SCRIP 1 4 documentation in oasis3 doc SCRIPusers pdf for more details on the interpolation algorithms When the SCRIP library performs a remapping it first checks if the file containing the corre sponding remapping weights and addresses exists if it exists it reads them from the file if not it calculates them and store them in a file The file is created in the working directory and is called rmp_srcg_t o_tgtg_ INTTYPE_NORMAOPT nc where srcg and tgtg are the acronyms of respetively the source and the target grids INTTYPE is the interpolation type i e DISTWGT GAUSWGT BILINEAR not BILINEA as in OASIS3 3 or CONSERV see below and NOR MAOPT is the normalization option i e DESTAREA FRACAREA or FRACNNET for CONSERV only see below One has to take care that the remapping file will have the same name even if other details like the grid masks are changed When reusing a remapping file one has to be sure that it was generated in exactly the same conditions than the ones it is used for The following types of interpolations are available
34. art_id below can then be anything e CALL oasis def var var_id name il_part_id var_nodims kinout var_actual shape var type ierror or e CALL prismdef 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 CHARACTERx8 IN field symbolic name as in the namcouple il_part_id INTEGER IN partition ID see section 2 4 var_nodims INTEGER DIMENSION 2 IN var_nodims 1 is the rank of field ar ray 1 or 2 var_nodims 2 is the number of bundles always 1 in the current OASIS3 MCT version If the field does not appear in the namcouple the returned field ID will be equal to 1 and corresponding oasis_put and oasis_get cannot be called in the code 14 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT kinout ierror var type INTEGER IN OASIS_In or PRISM_In i e 15 for fields received by the model OASTS_Out PRISM_Out i e 14 for fields sent by the model S var_actual_shape INTEGER DIMENSION 2x var_nodims 1 IN vector of integers giving the minimum and maximum index for each dimension of the coupling field ar ray for the current OASIS3 MCT version the minimum index has to be 1 and the maximum index has to be the extent of the dimension INTEGER IN type of coupling field array put
35. ast active oasis_put or prism_put_proto call of the run see section 2 7 1 Warning the date is not written or read to from the restart file therefore the user has to make sure that the appropriate coupling restart file is present in the working directory The coupling restart files must follow the NetCDF format The name of the coupling restart file is given by the 6th character string on the first configuring line for each field in the namcouple see section 3 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 The only exception is when a coupling field sent by a source component model is associated with more than one target field and model in that case if coupling restart files are required it is mandatory to specify different files for the different fields In the coupling restart files the fields must be provided on the source grid in single or double precision REAL arrays and as the grid data files must be dimensioned nx ny where nx and ny are the grid first and second dimension see section 5 1 above 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 coupling restart files are also used automatically by OASIS3 MCT to allow partial LOCTRANS time transformatio
36. ation does not transform the field The generic input line is as follows CHECKIN operation INT 1 CORRECT UNUSED BLASOLD BLASOLD allows the source field to be scaled and allows a scalar to be added to the field The prior ability to perform a linear combination of the current coupling field with other coupling fields has been deprecated in OASIS3 MCT This transformation occurs before the interpolation per se This transformation requires at least one configuring line with two parameters BLASOLD operation SXMULT SNBFIELDS where XMULT is the multiplicative coefficient of the source field which must be given as a REAL value e g 2 0 and not 2 SNBF TE LDS must be 0 if no scalar needs to be added or 1 if a scalar needs to be added In this last case an additional input line is required where SAVALUE is the scalar to be added to the field which must also be given as a REAL value CONSTANT SAVALUE The remapping interpolation MAPPING The MAPPING keyword is used to specify an input file to be read and used for mapping ie regrid ding or interpolation the MAPPING file must follow the SCRIPR format This is an alternative method to SCRIPR for setting the mapping file Since OASIS3 MCT 2 0 MAPPING can be used for higher order remapping Up to 5 different sets of weights see section 5 4 for the weight file format can be applied to up to 5 different fields transfered as oasis put arguments see se
37. ction 2 7 1 This transformation requires at least one configuring line with one filename and two optional string values SMAPNAME SMAPLOC SMAPSTRATEGY SMAPNAME is the name of the mapping file to read This is a NetCDF file consistent with the SCRIPR map file format see section 5 3 SMAPLOC is optional and can be either src or dst With src the mapping will be done in parallel on the source processors before communication to the destination model processes this is the default With dst the mapping is done on the destination processes after the source grid data is sent from the source model 30 CHAPTER 4 TRANSFORMATIONS AND INTERPOLATIONS SMAPSTRATEGY is optional and can be either bfb sum or opt In bfb mode the map ping is done using a strategy that produces bit for bit identical results regardless of the grid decompositions without leveraging a partial sum computation this is the default With sum the transform is done using the partial sum approach which generally introduces roundoff level changes in the results on different processor counts Option opt allows the coupling layer to choose either approach based on an analysis of which strategy is likely to run faster Usually partial sums will be used if the source grid has a higher resolution than the target grid as this should reduce the overall communication e g for conservative remapping Note that if SCRIPR see below is used to calculate the rem
38. culating the error of interpolation on the target grid For more details see also the document test_interpolation_oasis3 mct pdf there in 6 4 Debugging 6 4 1 Debug files If you experience problems while running your coupled model with OASIS3 MCT you can obtain more information on what is happening by increasing the SNLOGPRT value in your namcouple see also section 3 2 Different outputs are written depending on SNLOGPRT value e 0 one file debug root xx is open by the master process of each model and one file debug _notroot xx is open for all the other processes of each model to write only error information if an error occurs e 1 one file debug root xx is open by the master process of each model to write information equiv alent to level 10 see below one file debug_notroot xx is open for all the other processes of each model to write only error information if an error occurs e 2 one file debug xx xxxxxx is open by each process of each model to write normal production diagnostics e 5 as for 2 with in addition some initial debug info e 10 as for 5 with in addition the routine calling tree e 12 as for 10 with in addition some routine calling notes e 15 as for 12 with even more debug diagnostics e 20 as for 15 with in addition some extra runtime analysis e 30 full debug information 40 CHAPTER 6 COMPILING RUNNING AND DEBUGGING 6 4 2 Time statistics files The variable TIMER Debug defined in the namcou
39. d LY EL LY q a 18 24 12 Model A timestep 6 gt prism_put_proto prism_get_proto leading to writing reading to from coupling restart file Cpl_period F1 12 gt prism_put_proto prism_get_proto leading to Cpl_period F2 12 sending receiving actions Cpl_period F3 12 gt prism_put_proto prism_get_proto NOT leading to LAG F1 6 sending receiving actions LAG F2 6 LAG F3 0 Figure 2 5 LAG concept second example model B receives F receives F3 and then sends Fo its timestep length is also 6 F3 Fh and F3 coupling periods are both supposed to be equal to 12 For F and F gt the situation is similar to the first example If F F put action by model A B was used at a coupling timestep to match the model B A get action a deadlock would occur as both models would be waiting on a get action To prevent this F and F produced at the timestep before have to be used to match the model A and model B get actions which means that a lag of 6 must be defined for both F and Fy For both coupling fields the oasis put performed at times 6 and 18 by the source model then lead to put actions as 6 6 12 and 18 6 24 which are coupling periods that match the get action performed at time 12 and 24 below the casis_get called by the target model For F3 sent by model A and received by model B no lag needs to be defined the coupling field produced by
40. d routine names that will continue to evolve in the future always ensuring backward compatibility In the following sections both the mod _prism and mod_oasis interface names are defined and a single description of the interface ar guments is provided 2 2 Initialisation 2 2 1 Coupling initialisation e CAI L oasis_init_comp compid model_name ierror e CALL prism_init_comp_proto compid model_name ierror compid INTEGER OUT component model ID model_name CHARACTERx6 IN component model name as in namcouple under SNBMODEL ierror INTEGER OUT returned error code This routine must called by all component processes to initialise the coupling 2 2 2 Communicator for internal parallelisation e CALL oasis get localcomm local_comm ierror e CALL prism_get_localcomm_proto local_comm ierror local_comm INTEGER OUT value of local communicator error INTEGER OUT returned error code If needed this routine may be called by the component processes to get the value of a local com municator to be used by the component for its internal parallelisation This may be needed as all component models started in a pseudo MPMD mode with MPI1 share au tomatically the same MPLCOMM_WORLD communicator Another communicator has to be used for the internal parallelisation of each component OASIS3 MCT creates this local communica
41. e N 2 2x number of segments e ig_paral e ig paral for ig_para e ig_paral e ig paral e ig_paral e ig_paral e ig paral 1 3 indicates a Orange partition 2 the total number of segments for the partition limited to 200 presently see note 1 4 for Box partition above L 3 the first segment global offset L 4 the first segment local extent L 5 the second segment global offset L 6 the second segment local extent N 1 the last segment global offset e ig_ paral N the last segment local extent 2 5 COUPLING FIELD DECLARATION 13 Proc 1 1 segment offset 0 E A a G nbr of segments 3 1 segment size 5 2nd segment offset 7 2nd segment size 2 a a 3rd segment offset 10 E E E 3rd segment size 3 Figure 2 3 Orange partition for one process It is assumed here that the index start at O in the upper left corner Figure 2 3 illustrates an Orange partition with 3 segments for one process The other process partitions are not illustrated 2 5 Coupling field declaration All component processes declares the fields sent or received by the component during the simulation If some processes of a model are not involved in the coupling they still have to call the same number of oasis _def_var than the ones participating to the coupling even if the associated field symbolic names and partition ID see name and 11 _p
42. e grid line with i 6 3 RUNNING OASIS3 MCT 39 overlaps the grid line with i imax it is the latter that must be masked when this is not the case with the mask defined in masks nc this CPP key forces these rules to be respected e balance Add a MPI_Wtime function before and after mct_isend MPI put and mct_recv MPI get to calculate the time of the send and receive of a coupling field This option can be used to produce timestamps in OASIS3 MCT debug files During a post processing phase this information can be used to perform an analysis of the coupled components load un balance specific tools have been developed to do this and will be released with a further version of OASIS3 MCT 6 3 Running OASIS3 MCT Examples of running environement are provided with the sources For more details see the instructions on OASIS web site athttps verc enes org oasis oasis dedicated user support 1 user toys tutorial and test_interpolation of oasis3 mct 1 6 3 1 The tutorial toy model A practical example on how to run OASIS3 MCT and running it in a coupled system is provided in oasis3 mct examples tutorial See also the document tutorial_oasis3 mct pdf there in for more details 6 3 2 The test interpolation environment This environment available with the sources in vasis3 mct examples test_interpolation allows the user to test the quality of the interpolations and transformations between his source and target grids by cal
43. e it happens and exit It does this by tracking the order of get and put calls in models compared to the SEQ specified in the namcouple If there are any inconsistencies the model will abort gracefully with a useable error message before the system deadlocks If there are any coupling dependencies in the system use of the SEQ index is recommended for diagnosis but has no impact on the ultimate solution and is NOT required Take the following two examples In both examples there are two models each put a field to the other at every coupling period without any lags In the first case there is no dependency and each model sends puts the data first and then receives the data second at each timestep modell model2 put f1d1 put f1d2 get f1d2 get f1d1 The put from model for fld1 is received by the get in model2 and the put from model2 for fld2 is received by the get in modell In this case there is no sequencing dependency and the value of SEQ must be identical or unset in the namcouple description of the fld1 and fld2 coupling If SEQ is set to 1 for fld1 and 2 for fld2 in this case then the model will abort because at runtime the coupling will detect in model 2 that fld2 was sent before fld1 was received which is out of sequence as defined by the SEQ settings In the next example there is a dependency in the sequencing modell model2 put f1d1 get fldl f1d2 g fld1 get f1d2 put f1d2 In model2
44. e version lon REAL DIMENSION nx ny nc IN single or double real array of corner longitudes in degrees_East lat REAL DIMENSION nx ny nc IN single or double real array of corner lat itudes in degrees_North Writes the grid cell corner longitudes and latitudes counterclockwise sense Longitudes must be given in degrees East in the interval 360 0 to 720 0 Latitudes must be given in degrees North in the interval 90 0 to 90 0 Note also that cells larger than 180 0 degrees in longitude are not supported Writing of corners is optional as corner information is needed only for SCRIPR CONSERV see section 4 3 If called needs to be called after oasis prism_write_grid e CALL oasis write mask cgrid nx ny mask or e CALL prism_write_mask cgrid nx ny mask 10 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT cgrid CHARACTERx4 IN grid name prefix nx INTEGER IN first grid dimension x ny INTEGER IN second grid dimension y mask INTEGER DIMENSION nx ny IN mask array be careful about the OA SIS historical convention 0 not masked 1 masked Writes the model grid mask e CALL oasis_write_area cgrid nx ny area or e CALL prism_write_area cgrid nx ny area cgrid CHARACTERx4 IN grid name prefix nx INTEGER IN first grid dimension x ny INTEGER IN second grid dime
45. ements fully parallel regridding as a parallel matrix vector multiplication and parallel distributed exchanges of the coupling fields based on pre computed regridding weights and addresses Its design philosophy based on flexibility and minimal invasiveness is close to the OASIS approach MCT has proven parallel perfor mance and is most notably the underlying coupling software used in National Center for Atmospheric Research Community Earth System Model 1 NCAR CESM1 OASIS3 MCT is a portable set of Fortran 77 Fortran 90 and C routines Low intrusiveness portability and flexibility are OASIS3 MCT key design concepts After compilation OASIS3 MCT is a coupling library that needs to be linked to the component models and which main function is to interpolate and exchange the coupling fields between them to form a coupled system OASIS3 MCT supports coupling of 2D logically rectangular fields but 3D fields and 1D fields expressed on unstructured grids are also supported using a one dimension degeneration of the structures Thanks to MCT all transformations including regridding are executed in parallel on the set of source or target component processes and all couplings are now executed in parallel directly between the components via Message Passing Interface MPI OASIS3 MCT also supports file I O using netcdf In spite of the significant changes in underlying implementation usage of OASIS3 MCT in the codes has largely remained unchanged with
46. equencies and transformations are allowed for different coupling exchanges of the same field If coupling restart files are required eitherifa LAG orifa LOCTRANS transformation 1s specified 1t is mandatory to specify different files for the different fields The inverse feature is not allowed i e a single target get field CANNOT be associated with multiple source put fields e The debug files The debug mode was greatly improved as compared to OASIS3 3 The level of debug information written out to the OASIS3 MCT debug files for each model process is defined by the NLOGPRT value in the namcouple All details are provided in section 3 2 B 2 5 Changes in the configuration file namcouple e The namcouple configuration file of OASIS3 MCT is fully backward compatible with OASIS3 3 However several namcouple keywords have been deprecated even if they are still allowed These 46 APPENDIX B CHANGES BETWEEN THE DIFFERENT VERSIONS OF OASIS3 MCT keywords are noted UNUSED in sections 3 2 and 3 3 and are not fully described Information below these keywords will not be read and will not be used SEQMODE CHANNEL JOB NAME INIDATE MODINFO CALTYPE e Also the following inputs should not appear in the namcouple anymore as the related functionality are not supported anymore in OASIS3 MCT see above field status AUXILARY time transforma tion ONCE REDGLO INVERT MASK EXTRAP CORRECT INTERP MOZAIC FILLING SUBGRID MASKP REVE
47. erials provided with the distribution 3 The end user documentation included with the redistribution if any must include the following acknowledgment This product includes software developed by the UChicago Argonne LLC as Operator of Argonne National Laboratory Alternately this acknowledgment may appear in the software itself if and wherever such third party acknowledgments normally appear This software was authored by e Argonne National Laboratory Climate Modeling Group Mathematics and Computer Science Division Argonne National Laboratory Argonne IL 60439 e Robert Jacob tel 630 252 2983 E mail jacob mcs anl gov e Jay Larson E mail larson mcs anl gov e Everest Ong e Ray Loy 4 WARRANTY DISCLAIMER THE SOFTWARE IS SUPPLIED AS IS WITHOUT WARRANTY OF ANY KIND THE COPYRIGHT HOLDER THE UNITED STATES THE UNITED STATES DEPARTMENT OF ENERGY AND THEIR EMPLOYEES 1 DISCLAIM ANY WARRANTIES EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE TITLE OR NON IN FRINGEMENT 2 DO NOT ASSUME ANY LEGAL LIABILITY OR RESPONSIBILITY FOR 1 3 LICENSES AND COPYRIGHTS 5 THE ACCURACY COMPLETENESS OR USEFULNESS OF THE SOFTWARE 3 DO NOT REPRESENT THAT USE OF THE SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS 4 DO NOT WARRANT THAT THE SOFTWARE WILL FUNCTION UNINTER RUPTED THAT IT IS ERROR FREE OR THAT ANY ERRORS WILL BE CORRECTED 5 LIMITA
48. etween two border segments using a Lambert equivalent azimuthal projection Problems were observed in some cases for the grid cell located around this north _thresh or south thresh latitude Another limitation of the SCRIP 1st order conservative remapping algorithm is that is also supposes for line integral calculation that sin latitude is linear in longitude on the cell borders which again is in general not valid close to the pole For a proper consevative remapping the corners of a cell have to coincide with the corners of 1ts neighbour cell with no holes between the cells If two cells of one same grid overlay at least the one with the greater numerical index must be masked for a proper conservative remapping For example if the grid cells with i overlays the grid cells with i imax the latter must be masked If this is not the case given the mask defined in masks nc OASIS3 MCT must be compiled with the CPP key TREAT_OVERLAY which will ensure that these rules are respected This CPP key was introduced in OASIS3 3 A target grid cell intersecting no source cell either masked or non masked at all i e falling in a hole of the source grid will in all cases get a zero value If a target grid cell intersects only masked source cells it will still get a zero value unless the FRACNNEI normalisation option is used in which case it will get the nearest non masked neighbour value Note that the option of having the value 1 0E 2
49. familiar with OASIS3 MCT by going through the tutorial steps The tutorial sources are given in directory examples tutorial and all explanations are provided in the document tutorial_oasis3 mct pdf therein 3 Identify the coupling or I O fields and adapt the component models to allow their exchange with the OASIS3 MCT coupling library based on MPI message passing The OASIS3 MCT coupling library uses NetCDF and therefore can be used to perform I O actions from to disk files For more detail on how to interface a model with OASIS3 MCT see chapter 2 4 Define all coupling and I O parameters and the transformations required to adapt each coupling field from the source model grid to the target model grid on this basis prepare OASIS3 MCT config uring file namcouple see chapter 3 OASIS3 MCT supports different interpolation algorithms as described in chapter 4 Regridding files can be computed online using the SCRIP options or offline and read using the MAPPING transformation We strongly recommend to tests off line the quality of the chosen transformations and regrid dings using the environment available in examples test_interpolation and explanations provided in the document test _interpolation_oasis3 mct pdf therein 5 Generate required auxiliary data files see chapter 5 6 Compile OASIS3 MCT the component models and start the coupled experiment Details on how to compile and run a coupled model with OASIS3 MCT can be found in section 6
50. first coupling of a run should occur at time 0 and the final coupling should occur at time runtime cpl_period where runtime is the total time of the run and cpl_period is the coupling period e The total run time should match an integer number of coupling periods e Ifa coupling field has a positive lag the coupling field that matches the oasis_get at time 0 will come from a coupling restart file written by the last active oasis_put of the previous run see section 2 10 For a coupling field with a positive lag the coupling restart file see section 5 2 is automatically overwritten by the oasis_put when the time i e date LAG equals to the total runtime e Ifa local time transformation is indicated for the field by the user in the namcouple INSTANT AVERAGE ACCUMUL T_MIN or T_MAX see section 4 it is automatically performed and the resulting field is finally sent at the coupling or I O frequency For non instant transformations partially transformed fields will be written to the restart file at the end of the run for use on the next model startup e A coupling field sent by a source component model can be associated with more than one target field and model if specified as so with different entries in the namcouple configuration file In that case the source model needs to send the field only once and the corresponding data will arrive at multiple targets as specified in the namcouple Different coupling frequencies and transformations
51. for backward compatibility compiles all OASIS3 MCT libraries mct scrip and psmile e make realclean f TopMakefileOasis3 removes all OASIS3 MCT compiled sources and librairies Log and error messages from compilation are saved in util make dir in the files COMP log and COMP err During compilation a new compiling directory defined by variable ARCHDTR is created After successful compilation resulting libraries are found in the compiling directory in 1ib and object and module files in build If module mod_oasis is used in the models it is enough to include the path of the psmile objects and modules SARCHDIR build lib psmile MPI1 for the compilation and to use the psmile library SARCHDIR 1lib libpsmile MPI1 a when linking If module mod_pri smis used in the models it is necessary to include the path of the psmile and of the mct objects and modules for the compilation i e SARCHDIR build lib psmile MPI1 and mct and to use both the psmile and mct libraries SARCHDIR 1ib libpsmile MPI1 aand libmct a and libmpeu a when linking 6 2 CPP keys The following CPP keys are coded in OASIS3 MCT and can be specified in CPPDEF in make your platform file e TREAT_OVERLAY To ensure in SCRIPR CONSERV remapping see section 4 3 that if two cells of the source grid overlay at least the one with the greater numerical index is masked they also can be both masked this is mandatory for this remapping For example if th
52. g 3 E g 5 ES 3 OASIS3 MCT User Guide OASIS3 MCT_2 0 Edited by S Valcke T Craig L Coquart CERFACS CNRS SUC URA No1875 CERFACS TR CMGC 13 17 May 2013 Copyright Notice Copyright 2013 by CERFACS All rights reserved No parts of this document should be either reproduced or commercially used without prior agreement by CERFACS representatives How to get assistance Assistance can be obtained as listed below Phone Numbers and Electronic Mail Adresses Name Phone Affiliation e mail Laure Coquart CNRS oasishelp at cerfacs fr Sophie Valcke CERFACS How to get documentation The documentation can be downloaded from the OASIS web site under the URL http oasis enes org Contents 1 Introduction 1 1 Step by step use of OASIS3 MCT 2 ee 1 2 OASIS3 MCT sources 2 ee 1 33 Licenses and Copyrights aoaaa ee 1 3 1 OASIS3 MCT license and copyright statement oo 1 3 2 MCT copyright statement 0 0 2 000000 00004 1 3 3 The SCRIP 1 4 license copyright statement o o 2 Interfacing a component model with OASIS3 MCT 2 1 UseofOASIS3 MCT library e 2 2 LOIS SaO aa AA a dee eth en on A Rs 2 2 1 Coupling initialisation e 2 2 2 Communicator for internal parallelisation o o o 2 2 3 Coupling through a subset of the component model processes 2 2 4 Separate executable not coupling at a
53. ically 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 An exchange at the beginning of the run at time 0 is expected Trying to receive with oasis_get a field declared with a oasis_def_var but not defined in the con figuration file namcouple will lead to an abort In this case the field ID returned by the oasis def var is equal to 1 and the corresponding oasis_get should not be called 2 8 Termination e CALL oasis_terminate ierror e CALL prism_terminate_proto ierror error INTEGER OUT returned error code All processes of the component model must terminate the coupling by calling this routinet normal termination 2 9 Auxiliary routines Not all auxiliary routines that were in OASIS3 3 are currently available e CALL oasis_abort compid routine_name abort message e CALL prism abort proto compid routine_name abort_ message compid INTEGER IN component model ID from oasis_init_comp or prism_init_comp proto routine_name CHARACTERx IN name of calling routine abort_message CHARACTERx IN message to be written out If a process needs to abort voluntarily it should do so by calling oasis_abort This will ensure a proper termination of all processes in the coupled model communicator This routine writes the Tf
54. ield value its gradient in the first dimension its gradient in the second dimension and its cross gradient With OASIS3 MCT 2 0 and following versions bicubic and higher order remapping are therefore supported given that the higher order fields are provided at each time step as oasis_put arguments Note that if 1d3 is passed 1d2 must also be passed if 1d4 is passed 1d3 and 1d2 must also be passed and if 1d5 is passed 1d4 1d3 and f1d2 must also be passed However having a gra 374 4 and 5 set of weights in the remapping file but not passing a 274 374 4t and 5 source field as argument will not lead to an error the appropriate set of weights will simply be applied to the fields provided as arguments e Trying to send with oasis_put a field declared with a oasis def_var but not defined in the configuration file namcouple will lead to an abort In this case the field ID returned by the oasis_def_var is equal to 1 and the corresponding oasis_put should not be called e This routine may be called by the model at each timestep The convention for the date argument is to indicate the time at the beginning of the timestep The sending is actually performed only if the time obtained by adding the field lag LAG in the namcouple to the 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 3 e If the convention for date is followed the
55. ifferent 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 O for INPUT fields e SOALBEDO nc CHARACTER 32 giving the input file name for more detail on its format see section 5 3 e INPUT field status Chapter 4 Transformations and interpolations Different transformations and 2D interpolations are available in OASIS3 MCT to adapt the coupling fields from a source model grid to a target model grid In the following paragraphs a description of each transformation with its corresponding configuration lines that the user has to write in the namcouple file is given Features that are now deprecated non functional compared to prior versions will be noted with the string UNUSED but not described 4 1 Time transformations e LOCTRANS LOCTRANS requires one configuring line on which a time transformation automatically performed below the call to oasis_put should be indicated LOCTRANS operation STRANSFORM where TRANSFORM can be INSTANT no time transformation the instantaneous field is transferred ACCUMUL the field accumulated over the previous coupling period is exchanged the accu mulation is simply done over the arrays field array provided as third argument to the oasis_put calls not weighted by the time
56. led by all component processes with icp1 1 for processes participating in the coupling and with icpl MP I_UNDEFINED for the others Argument local_comm is the MPI communicator associated with all processes of the component The new coupling communicator is returned in coup1_comm If this communicator already exist in the code the component should simply provide it to OASIS3 MCT with e CALL oasis_set_couplcomm coupl_comm kinfo e CALL prism_set_couplcomm coupl_comm kinfo coupl_comm INTEGER IN MPI communicator gathering only component processes participating in the coupling kinfo INTEGER OUT OPTIONAL returned error code This routine allows to provide a local coupling communicator to OASIS3 MCT given that it already exists in the code The value of coup1_comm must be the value of this local coupling communicator for the processes participating to the coupling and it must be MP I_COMM_NULL for processes not involved in the coupling All OASIS3 MCT interface routines besides the grid definition see section 2 3 and the oasis_put and oasis_get per se see section 2 7 are collective and must be called by all processes of an executable In particular the oasis_def_partition see section 2 4 must be called by all processes but with ig_paral 0 for the processes not involved in the coupling also these processes must call the same number of oasis_def_var than the ones participating to the coup
57. lems in writing out the time statistics when all the processors are not coupling were solved see Redmine issue 497 The problem with restart files when one coupling field is sent to 2 target components was solved see Redmine ticket 522 A memory leak in mod_oasis_getput_interface F90 was fixed thanks to R Hill from the MetOffice see Redmine ticket 437 A bug fix was provided to ensure that the nearest neighbour option is activated when the option FRACNNE is defined in the namcouple for the conservative interpolation The behaviour of OASIS3 MCT was changed in the case a component model tries to send with oasis_put a field declared with aoasis_def_var but not defined in the configuration file nam couple this will now lead to an abort In this case the field ID returned by the oasis_def_var is equal to 1 and the corresponding oasis_put should not be called B 2 CHANGES BETWEEN OASIS3 3 AND OASIS3 MCT_1 0 43 e OASIS3 MCT developments are now continuously tested and validated on different computers with a test suite under Buildbot which is a software written in Python to automate compile and test cycles required in software project see https inle cerfacs fr projects oasis3 mct wiki Buildbot on the Redmine site B 2 Changes between OASIS3 3 and OASIS3 MCT_1 0 B 2 1 General architecture e OASIS3 MCT is only a coupling library Much of the underlying implementation of OASIS3 was refactored to leverage the Model Coupling
58. ling even if the associated field symbolic names and partition ID see name and il_part_id arguments in section 2 5 can then be anything Appendix C shows a coding sample of how to use these routines 2 2 4 Separate executable not coupling at all For a separate executable part of a coupled system managed by OASIS3 MCT but for which all processes are not involved in the coupling such as a separate I O server the only calls that should be made are CALL oasis_init_comp comp_id comp_name ierror CALL oasis_get_localcomm localComm ierror optional CALL oasis_enddef CALL oasis_terminate 2 3 GRID DATA FILE DEFINITION 9 2 3 Grid data file definition With OASIS3 MCT the grid data files grids nc masks nc and areas nc are required only for certain oper ations see also section 5 1 i e grids nc and masks nc for SCRIPR see section 4 3 and masks nc and areas nc for CONSERV see section 4 4 These grid data files can be created by the user before the run or can be written directly at run time by the master process of each component model with the following routines These routines can be used by the component models to add grid fields to the grid files but not to overwrite them These routines have to be called just after oasis_init_comp e CALL oasis_start_grids_writing flag or e CALL prism_start_grids_writing flag flag INTEGER OUT not used
59. ll o 2 3 Grid data filed finition gt ae E R R ds rd tt ete oe ada 24 Partition definition 3 3 42 ht a AA a es AA 2 4 1 Serial no partition ee 2 4 2 gt Apple Partition o Ra EOS a Se ee es 24 3 Box partition A ti Boe ats aa a 24 4 Orange partition nda a A Be we ee 2 5 Coupling field declaration 2 ee 2 6 End of definition phase ee ee 2 7 Sending put and receiving get actions 2 2 2 2 ee ee eee 2 7 1 Sending a coupling or I O field 2 2 ee ee ee 2 7 2 Receiving a coupling or I O field 2 2 ee ee 2 8 Termination SRTR doy Se ee yas eS ee OA ee a ee ee ad 29 Auxiliary TOUUNGS A ee a ss he Bo Ge as de 2 10 Coupling algorithms SEQ and LAG concepts o o e 2100F The lag concept wo ss A a e a 2 10 2 The Sequence Concept Ane E ara E R EE E A ee 3 The configuration file namcouple 3 1 3 2 3 3 An example of a simple namcouple First section of namcouple file Second section of namcouple file 3 3 1 Second section of namcouple for EXPORTED and EXPOUT fields 3 3 2 Second section of namcouple for OUTPUT fields 3 3 3 Second section of namcouple for INPUT fields 4 Transformations and interpolations 22 22 24 25 25 26 27 28 ii CONTENTS 4 1 Timetransformations 2 R R e e T e d e L a RR ee ee 28 4 2 The pre processing transformations
60. model A at the coupling timestep can be consumed by model B without causing a deadlock situation As in the first example the oasis_get performed at the beginning of the run for F and Fy will automatically receive data read from their coupling restart files and the last oasis_put performed at the end of the run automatically write them to their coupling restart file For F3 no coupling restart file is needed nor used as at each coupling period the coupling field produced by model A can be directly consumed by model B We see here how the introduction of appropriate LAG indices results in receiving in the target model the coupling fields produced by the source model the timestep before this is in some coupling configurations essential to avoid deadlock situations 2 10 COUPLING ALGORITHMS SEQ AND LAG CONCEPTS 21 2 10 2 The sequence concept The order of coupling operations in the system is determined solely by the order of calls to send put and receive get data in the models in conjunction with the setting of the lag in the namcouple Data that is received get is always blocking while data that is sent put is non blocking with respect to the model making that call It is possible to deadlock the system if the relative orders of puts and gets in different models are not compatible With OASIS3 MCT the sequence SEQ index in the namcouple file now provides the coupling layer with an ability to detect a deadlock befor
61. n between grids T O actions from to files To adapt a component model to OASIS3 MCT specific calls of the following classes have to be imple mented in the code CoN DN FW NY a Initialisation section 2 2 Grid data file definition section 2 3 Partition definition section 2 4 Coupling I O field declaration section 2 5 End of definition phase section 2 6 Coupling I O field sending and receiving section 2 7 Termination section 2 8 Optional auxiliary routines section 2 9 Finally in section 2 10 different coupling algorithms are illustrated and details on how to reproduce them with OASIS3 MCT are provided More information on the LAG and SEQ indices are also given in that section 2 1 USE OF OASIS3 MCT LIBRARY 7 2 1 Use of OASIS3 MCT library To use OASIS3 MCT library a user needs to add in his code e USE mod_oasis e USE mod_prism Both use statements are valid and use of just one or the other is recommended in a particular component model A single use statement now provides all the methods that required multiple use statements in pre vious OASIS3 versions The methods datatypes and capabilities are identical for both the mod_prism or mod_oasis interfaces The only difference is the name of the interface The interface in module mod_prism is provided for backwards compatability with prior versions of OASIS3 Use of module mod_oasis is now recommended provides access to a set of update
62. n file namcouple 0 00004 45 B 2 6 Other differences san e E o a Rae a daa e de a E A 46 C API for processes not involved in the coupling 47 Index 50 CONTENTS 1 ACKNOWLEDGMENTS 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 of their contribution to OASIS Arnaud Caubel LSCE IPSL FECIT Fujitsu Damien Declat CERFACS Italo Epicoco CMCC Veronika Gayler MPI M amp D Josefine Ghattas CERFACS Jean Latour CERFACS amp Fujitsu Fecit Eric Maisonnave CERFACS Silvia Mocavero CMCC Elodie Rapaport CERFACS Hubert Ritzdorf CCRLE NEC Sami Saarinen ECMWF Eric Sevault M t o France Laurent Terray CERFACS Olivier Thual CERFACS Reiner Vogelsang SGI Germany Li Yan CERFACS 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 of their contribution to OASIS Dominique Astruc IMFT Chandan Basu NSC Sweden Sophie Belamari M t o France Dominique Bielli M t o France Gilles Bourhis IDRIS Pascale Braconnot IPSL LSCE Sandro Calmanti M t o France 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 D
63. n to be saved at the end of a run for exact restart at the start of the next run For that reason coupling restart filenames are now required for all namcouple transformations that use LOCTRANS with non INSTANT values 5 3 Input data files Fields with status INPUT in the namcouple will at runtime simply be read in from a NetCDF input file by the target model below the oasis_get 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 sec tion 3 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 named with the field symbolic name in the namcouple and dimen sioned nx ny time The time variable has to be an array time time expressed in seconds since beginning of run The time dimension has to be the unlimited dimension 5 4 Transformation auxiliary data files The mapping files to be used for the MAPPING option must be consistent with the files generated by the SCRIP library to be used for the SCRIPR transformations see also section 4 3 The files are NetCDF containing the following fields 5 4 TRANSFORMATION AUXILIARY DATA FILES 37 where int src_address num_links int dst_address num_links double remap_matrix num_links num_wgts num_links is a scalar integer indicating the to
64. nicator between the root processors of two compo nents the local component and the component associated with cdnam This call is collective across the tasks of the two components but other components are not involved e CALL oasis_get_intracomm new_comm cdnam kinfo e CALL prism_get_intracomm new_comm cdnam kinfo new_comm INTEGER OUT mpi intracomm communicator cdnam CHARACTERx IN other model name kinfo INTEGER OUT OPTIONAL returned error code This routine sets up an MPI intracomm communicator between the root processors of two compo nents the local component and the component associated with cdnam This call is collective across the tasks of the two components but other components are not involved 2 10 Coupling algorithms SEQ and LAG concepts Using the OASIS3 MCT coupling library the user has full flexibility to reproduce different coupling algo rithms In the components the sending and receiving routines respectively oasis_put and oasis get can be called at each model timestep with the appropriate date argument giving the actual time at the beginning of the timestep expressed in number of seconds since the start of the run or in any other time units as long as the same are used in all models and in the namcouple see section 2 7 1 This date argument is automatically analysed by the coupling library and depending on the coupling period and the lag LAG cho
65. nsformations or interpolations to be performed by OASIS3 MCT and associated configuring lines described in more details in chapter 4 etc In OASIS3 MCT several namcouple inputs have been deprecated but for backwards compatibility they are still allowed These inputs will be noted in the following text using the notation UNUSED and not fully described Information below these keywords is obsolete in OASIS3 MCT it will not be read and will not be used In the next sections a simple namcouple example is given and all configuring parameters are described The additional lines containing the different parameters required for each transformation are described in section 4 A realistic namcouple can be found in oasis3 mct examples tutorial data_oasis3 directory 3 1 An example of a simple namcouple The following simple namcouple configures a run into 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 from the atmosphere to the atmospheric chemistry and one field SOALBEDO is read from a file by the ocean HH HH OOOO AA First section SSEQMODE T SCHANNEL 3 1 AN EXAMPLE OF A SIMPLE NAMCOUPLE 23 SNFIELDS 4 JOBNAME T SNBMODEL 3 ocemod atmmod chemod 55 70 9
66. nsion y area REAL DIMENSION nx ny IN single or double real array of grid cell ar eas Writes of the model grid cell areas Needed only for CONSERV operation see section 4 4 e CALL prism_terminate_grids_writing e CALL oasis terminate grids writing Terminates grids writing required if some of the above grid writing routines are called The creation of the different files is effective in the routine oasis_enddef 2 4 Partition definition The coupling fields sent or received by a component model are usually scattered among the different component processes With OASIS3 MCT all processes exchanging coupling data have to define their local partition in the global index space If only a subset of the processes actually exchange coupling data the processes not implied in the coupling have to call this routine to describe a null partition i e with ig_paral 0 If the sum of the partitions defined over all the processes do not cover the global grid the total dimension of the grid total number of points must be given as an optional argument see isize below e CALL oasis def partition il part_id ig_paral ierror isize or e CALL prism def partition proto il part id ig_paral lerror isize il_part_id INTEGER OUT partition ID ig paral INTEGER DIMENSION IN vector of integers describing the local partition in the global index sp
67. nts with the same number e g 360 0 for both not 450 0 for one and 90 0 for the other to ensure automatic detection of overlap by OASIS3 MCT The corners of a cell cannot be defined modulo 360 degrees For example a cell located over Greenwich will have to be defined with corners at 1 0 deg and 1 0 deg but not with corners at 359 0 deg and 1 0 deg Cells larger than 180 0 degrees in longitude are not supported 2 masks nc contains the masks for all component model grids in INTEGER arrays Be careful to note the historical OASIS convention 0 not masked i e active or 1 masked i e not active 36 CHAPTER 5 OASIS3 MCT AUXILIARY DATA FILES 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 nc this file contains mesh surfaces for the component model grids in double precision REAL arrays The array names must be composed of the grid prefix and the suffix srf The sur faces may be given in any units but they must be all the same This file areas nc is mandatory for CONSERV GLOBAL GLBPOS BASBAL and BASPOS it is not required otherwise 5 2 Coupling restart files At the beginning of a coupled run some coupling fields may have to be initially read from their coupling restart file on their source grid see the LAG concept in section 2 10 When needed these files are also automatically updated by the l
68. ould be clearly marked so as not to confuse it with the OASIS3 MCT version available from CERFACS The developers of the OASIS3 MCT software are researchers attempting to build a modular and user friendly coupler accessible to the climate modelling community Although we use the tool ourselves and have made every effort to ensure its accuracy we can not make any guarantees We provide the software to you for free In return you the user assume full responsibility for use of the software The OASIS3 MCT software comes without any warranties implied or expressed and is not guaranteed to work for you or on your computer Specifically CERFACS and the various individuals involved in development and maintenance of the OASIS3 MCT software are not responsible for any damage that may result from correct or incorrect use of this software 1 3 2 MCT copyright statement Modeling Coupling Toolkit MCT Software Copyright 2011 UChicago Argonne LLC as Operator of Argonne National Laboratory All rights re served Redistribution and use in source and binary forms with or without modification are permitted provided that the following conditions are met 1 Redistributions of source code must retain the above copyright notice this list of conditions and the following disclaimer 2 Redistributions in binary form must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other mat
69. peration is performed except that the residual is distributed proportionally to the value of the original field this option ensures the global conservation of the field and does not change the sign of the field with SCMETH BASBAL the operation is analogous to GLOBAL except that the non masked surface of the source and the target grids are taken into account in the calculation of the residual this option does not ensure global conservation of the field but ensures that the energy received is proportional to the non masked surface of the target grid with SCMETH BASPOS the non masked surface of the source and the target grids are taken into account and the residual is distributed proportionally to the value of the original field therefore this option does not ensure global conservation of the field but ensures that the energy received is proportional to the non masked surface of the target grid and it does not change the sign of the field SCONSOPT is an optional argument specifying the algorithm CONSOPT can be bfb or opt The bfb option enforces a bit for bit transformation regardless of the grid decomposition or process count The opt option carries out the conservation using an optimal algorithm using less memory and a faster approach Option bfb is the default setting SUBGRID UNUSED BLASNEW BLASNEW performs a scalar multiply or scalar add to any destination field This is the equivalent of BLASOLD on the destination
70. ple second number on the line below NLOGPRT keyword is used to obtain time statistics over all the processors for each routine Different output are written in files named timers_xxxx depending on TIMER Debug value e TIMER Debug 0 nothing is calculated nothing is written e TIMER Debug 1 the times are calculated and written in a single file by the process O as well as the min and the max times over all the processes e TIMER Debug 2 the times are calculated and each process writes its own file process O also writes the min and the max times over all the processes in its file e TIMER_Debug 3 the times are calculated and each process writes its own file process O also writes in its file the min and the max times over all processes and also writes in its file all the results for each process The time given for each timer is calculated by the difference between calls to oasis timer_start and oasis_timer_stop and is the accumulated time over the entire run Here is an overview of the meaning of the different timers as implemented by default e total after init total time of the simulation implemented in mod_oasis_method i e between the end of oasis_init_comp and the call to mpi_barrier and mpi_finalize in routine oasis_terminate e map definition time spent in mct_gsmap_init in routine oasis_def_partition this routine defines the patterns of communication between the source and target processes e
71. plication and addition terms to the fields see section 4 2 e Using the coupler in interpolator only mode This is not possible anymore as OASIS3 MCT is now only a coupling library However it is planned in a further release to provide a toy coupled model that could be use to check the quality B 2 CHANGES BETWEEN OASIS3 3 AND OASIS3 MCT_1 0 45 of the remapping for any specific couple of grids e Coupling field CF standard names The file cf_name_table txt is not needed or used anymore The CF standard names of the coupling fields are not written to the debug files e Binary auxiliay files All auxiliary files besides the namcouple must be NetCDF binary files are not supported anymore B 2 4 New functionality offered e Better support of components for which only a subset of processes participate in the coupling In OASIS3 3 components for which only a subset of processes participated in the coupling were supported in a very restricted way In fact this subset had to be composed of the N first processes and N had to be specified in the namcouple Now the subset of processes can be composed of any of the component processes and does not have to be pre defined in the namcouple New routines oasis_create_couplcomm and oasis_set_couplcomm are now available to create or set a coupling communicator gathering only these processes see section 2 2 3 e Exact restart for LOCTRANS transformations If needed LOCTRANS transformations
72. r in the case only a subset of the component processes partici pate in the coupling see section 2 2 3 But even in this case all OASIS3 MCT interface routines besides the grid definition see section 2 3 and the put and get call per se see section 2 7 are collective and must be called by all processes New routines oasis_get_debug and oasis_set_debug New routines oasis_get_debug and oasis_set_debug are now available to respectively re trieve the current OASIS3 MCT internal debug level set by SNLOGPRT in the namcouple or to change it see section 2 9 B 2 3 Functionality not offered anymore e SCRIPR BICUBIC and SCRIPR CONSERV SECOND remappings As in OASIS3 3 the SCRIP library can be used to generate the remapping interpolation weights and addresses and write them to a mapping file All previous SCRIPR remapping schemes available in OASIS3 3 are still supported in OASIS3 MCT_1 0 besides BICUBIC and CONSERV SECOND because these remapping involve at each source grid point the value of the field but also the value of the gradients of the field which are not known or calculated Note these remapping schemes not available in OASIS3 MCT_1 0 were reactivated in OASIS3 MCT_2 0 see B 1 Vector field remapping Vector field remapping is not and will not be supported see Support of vector fields with the SCRIPR remappings in section 4 3 Automatic calculation of grid mesh corners in SCRIPR CONSER
73. ran90 Toolkit for Building Multiphysics Parallel Coupled Models Int J High Perf Comp App 19 3 277 292 2005 Noyret et al 1994 Noyret P E Sevault L Terray and O Thual Ocean atmosphere coupling Pro ceedings of the Fall Cray User Group CUG meeting 1994 Pontaud et al 1995 Pontaud M L Terray E Guilyardi E Sevault D B Stephenson and O Thual Coupled ocean atmosphere modelling computing and scientific aspects In 2nd UNAM CRAY su percomputing conference Numerical simulations in the environmental and earth sciences Mexico city Mexico 1995 Sevault et al 1995 Sevault E P Noyret and L Terray Clim 1 2 user guide and reference manual Technical Report TR CGMC 95 47 CERFACS 1995 Terray and Thual 1995b Terray L and O Thual Oasis le couplage oc an atmosph re La M t orologie 10 50 61 1995 Terray and Thual 1993 Terray L and O Thual Coupled ocean atmosphere simulations In High Per formance Computing in the Geosciences proceedings of the Les Houches Workshop F X Le Dimet Ed Kluwer Academic Publishers B V 1993 Terray et al 1995 Terray L E Sevault E Guilyardi and O Thual OASIS 2 0 Ocean Atmosphere Sea Ice Soil User s Guide and Reference Manual Technical Report TR CGMC 95 46 CERFACS 1995 Terray et al 1995b Terray L O Thual S Belamari M D qu P Dandin C L vy and P Delecluse Climatology and interannual variability simulated by the arpege opa model
74. respect to OASIS3 3 To communicate with another model or to perform I O actions a component model needs to include few specific calls to the OASIS3 MCT coupling library which Application Programmig Interface APD used in component models is unchanged The use statement has been updated and now requires a single use mod_prism or use mod_oasis statement instead of the various use statements required in prior OASIS3 versions The namcouple configuration file is also largely unchanged relative to OASIS3 although several options are either not used or not supported There is a new transformation in namcouple i e MAPPING which allows a user to specify a mapping file generated externally The changes between OASIS3 3 and OASIS3 MCT are lilsted in appendix B First tests done with up to 8000 cores on the Bullx Curie machine at the TGCC are very encouraging and it is therefore very likely that OASIS3 MCT will provide an efficient and easy to use coupling solution for many climate modelling groups in the few years to come The list of coupled models realized with OASIS can be found at https verc enes org oasis oasis dedicated user support 1 some current users gt www mces anl gov research projects mct 1 1 STEP BY STEP USE OF OASIS3 MCT 3 1 1 Step by step use of OASIS3 MCT To use OASIS3 MCT for coupling models and or perform I O actions one has to follow these steps 1 Obtain OASIS3 MCT source code see chapter 1 2 2 Get
75. s The arrays containing the grid information are dimensioned nx ny where nx and ny are the grid first and second dimension Unstructured grids or other grids expressed with 1D vectors are supported by setting nx to the total number of grid points and ny to 1 1 grids nc contains the model grid longitudes and latitudes in double precision REAL arrays 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 3 3 and of a suffix 4 characters this suffix is lon or lat for respectively the grid point longitudes or latitudes If the SCRIPR CONSERV remapping is used longitudes and latitudes for the source and target grid corners must also be available in the grids nc file as double precision REAL arrays dimensioned nx ny 4 or nbr_pts 1 4 where 4 is the number of corners in the counterclockwize sense The names of the arrays must be composed of the grid prefix and the suffix clo or cla for respectively the grid corner longitudes or latitudes As for the other grid information the corners can be provided in grids nc before the run by the user or directly by the model through specific calls see section 2 3 Longitudes must be given in degrees East in the interval 360 0 to 720 0 Latitudes must be given in degrees North in the interval 90 0 to 90 0 Note that if some grid points overlap it is recommended to define those poi
76. see 1d2 f1d3 f1d4 in section 2 7 1 For both BILINEAR and BICUBIC x Masked target grid points the zero value is associated to masked target grid points 32 CHAPTER 4 TRANSFORMATIONS AND INTERPOLATIONS x Non masked target grid points having some of the source points normally used in the bilinear or bicubic interpolation masked a N nearest neighbour algorithm using the re maining non masked source points is applied x Non masked target grid points having all bilinear or bicubic neighbours masked by de fault the nearest non masked source neighbour is used 11_nnei hard coded to t rue inoasis3 mct lib scrip src remap_bilinear f remap_bicubic f and remap_bicubic_reduced f this is not the same default behaviour as OASIS3 3 to have the same default behaviour as in OASIS3 3 put 1l_nnei false in the ap propriate routine For both BILINEAR and BICUBIC the configuring line is SCRIPR for BILINEAR or BICUBIC SCMETH CGRS SCFTYP SREST SNBIN where SCMETH BILINEAR or BICUBIC SCGRS is the source grid type LR or D SCFTYP SNBIN are as for DISTWGT SREST is as for DISTWGT except that only LATITUDE is possible for a Reduced D source grid CONSERV performs Ist or 2nd order conservative remapping which means that the weight of a source cell is proportional to area intersected by the target cell plus some other terms proportional to the gradien
77. sen by the user for each coupling field in the configuration file namcouple different coupling algorithms can be reproduced without modifying the component model codes themselves With OASIS3 MCT the SEQ index is no longer needed in the namcouple input to specify the sequencing order of different coupling fields The sequence SEQ index in the namcouple file now provides the coupling layer with an ability to detect a deadlock before it happens and exit The lag concept and indices are explained in more detail below and some examples are provided 18 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT 2 10 1 The lag concept The lag LAG value tells the coupler to modify the time at which that data is sent put by the amount of the lag The lag must be expressed in the time unit used that must be the same in the models and in the namcouple see section 2 7 1 and can be positive or negative but should never be larger in absolute magnitude than the coupling period of any field due to problems with restartability and dead locking When a component model calls a oasis_put the value of the lag is automatically added to the value of the date argument and the put is actually performed when the sum date lag is a coupling time in the target component this put will match a oasis_get for which the date argument is the same coupling time The lag only shifts the time data is sent It cannot be used to shift the time data is received
78. setting is equivalent to and converted to EXPORTED IGNOUT with OASIS3 MCT this setting is equivalent to and converted to EXPOUT INPUT read in from the input file by the target model below the oasis_get call at appropriate by the user in the namcouple See section 5 3 for OUTPUT written out to an output debug NetCDF file by the source model below the oasis_put call after local transformations LOCTRANS and 1 BLASOLD at appropriate times corresponding to the output period indicated by the user in the namcouple 3 3 1 Second section of namcouple for EXPORTED and EXPOUT fields The first 3 lines for fields with status EXPORTED and EXPOUT are as follows SOSSTSST SISUTESU 1 86400 5 sstoc nc EXPORTED 182 149 128 64 toce atmo LAG 14400 SEO 1 P2P0 where the different entries are 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 oasis_def_var in section 2 5 26 CHAPTER 3 THE CONFIGURATION FILE NAMCOUPLE SISUTESU symbolic name for the field in the target model CHARACTER 8 It has to match the argument name of the corresponding field declaration in the target model see oasis_def_var in section 2 5 1 UNUSED but still required for parsing 86400 coupling and or I O period for the field in seconds 5 number of transformations to be performed by O
79. sor 0 also writes the min and the max times over all the processors in its file 3 some time statistics are calculated and each processor writes its own file processor 0 also writes in its file the min and the max times over all processors and also writes in its file all the results for each processor For more information on the time statistics written out see section 6 4 2 SCALTYPE UNUSED Second section of namcouple file The second part of the namcouple starting after the keyword STRINGS contains coupling information for each coupling or I O field Its format depends on the field status given by the last entry on the field first line EXPORTED IGNOUT or INPUT in the example above The field may be AUXILARY UNUSED EXPORTED exchanged between component models and transformed by OASIS3 MCT EXPOUT exchanged transformed and also written to two debug NetCDF files one before the send ing action in the source model below the oasis_put call after local transformations LOCTRANS and BLASOLD if present and one after the receiving action in the target model below the oasis_get call after all transformations EXPOUT should be used when debugging the coupled model only The name of the debug NetCDF file one per field is automatically defined based on the field and component model names times corresponding to the input period indicated the format of the input file IGNORED with OASIS3 MCT this
80. t 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 Chapter 2 Interfacing a component model with OASIS3 MCT At run time OASIS3 MCT allows exchanging coupling data between two components as well as in terpolation and transformation of these coupling fields Different communication techniques have been historically developed in OASIS With OASIS3 MCT communication is performed by MCT based on Message Passing Interface 1 MPI1 protocol For a practical example using the OASIS3 MCT library see the sources in examples tutorial and explanations in the test_interpolation_oasis3 mct pdf document therein To communicate with another component model or to perform I O actions a component model needs to be interfaced with the OASIS3 MCT library which sources can be found in oasis3 mct lib psmile directory The OASIS3 MCT library supports parallel communication between parallel component models coupling a component on a subset of it s processeses only automatic sending and receiving actions at appropriate times following user s choice indicated in the namcouple time integration or accumulation of the coupling fields some transformations such as mapping interpolatio
81. t of the field in the longitudinal and latitudinal directions for the second order The configuring line is SCRIPR for CONSERV where SCMETH SCGRS SCFTYP SREST SNBIN SNORM SORDER SCMETH CONSERV SCGRS is the source grid type LR D and U Note that the grid corners have to given by the user in the grid data file grids nc or by the code itself in the initialisation phase by calling routine oasis_write_corner see section 2 3 OASIS3 MCT will not attempt to automatically calculate them as OASIS3 3 SCFTYP SREST SNBIN are as for DISTWGT SNORM is the NORMalization option FRACAREA The sum of the non masked source cell intersected areas is used to NORMalise each target cell field value the flux is not locally conserved but the flux value itself is reasonable DESTAREA The total target cell area is used to NORMalise each target cell field value even if it only partly intersects non masked source grid cells local flux conser vation is ensured but unreasonable flux values may result FRACNNEI as FRACAREA except that at least the source nearest unmasked neigh bour is used for unmasked target cells that intersect only masked source cells Note that a zero value will be assigned to a target cell that does not intersect any source cells masked or unmasked even with FRACNNEI option SORDER FIRST or SECOND for first or second order conservative remapping respec tively see SCRIP 1 4 documenta
82. tal number of associated grid point pairs in the file This is typically a large number This field is a netCDF dimension num_wgt s is a scalar integer indicating the number of weights per associated grid point pair up to 5 are supported see section 2 7 1 This field is a netCDF dimension src_address is a one dimensional array of size num_links It contains the integer source address associated with each weight This field is a netCDF variable dst_address is a one dimensional array of size num_links It contains the integer destination address associated with each weight This field is a netCDF variable remap _mat rix is a two dimensional array of size num_links num_wgts It contains the real weight value s associated with the source and destination address This field is a netCDF variable Chapter 6 Compiling running and debugging 6 1 Compiling OASIS3 MCT Compiling OASIS3 MCT libraries can be done in directory oasis3 MCT util make_dir with Make file TopMakefileOasis3 which must be completed with a header file make your_platform specific to the compiling platform used and specified in oasis3 MCT util make_dir make inc One of the header files distributed with the release can by used as a template The root of the OASIS3 MCT tree can be anywhere and must be set in the variable COUPLE in the make your_platform file The following commands are available e make f TopMakefileOasis3 or make oasis3_psmile f TopMakefileOasis3
83. timestep model A receives b and then sends F3 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 gt coupling periods are respectively 12 and 24 If F1 F3 put action by model A B was used at a coupling timestep to match the model B A get action a deadlock would occur as both models would be initially waiting on a get action To prevent this Fy and F gt produced at the timestep before have to be used to match respectively the model B and model A get actions This implies that a lag of respectively 4 and 6 seconds must be defined for Ff and Fy For F the oasis put performed at time 8 and 20 by model A will then lead to put actions as 8 4 12 and 20 4 24 which are coupling periods that match the get actions performed at times 12 and 24 below the oasis_get called by model B For Fo the oasis_put performed at time 18 by model B then leads to a put action as 18 6 24 which is a coupling period that matches the get action performed at time 24 below the oasis_get called by model A At the beginning of the run as their LAG index is greater than 0 the first oasis_get of E and F will automatically be fulfilled with fields read from their respective coupling restart files The user therefore has to create those coupling restart files before the first run in the experiment At the end of the run F having a lag greater
84. tion For CONSERV SECOND 3 weigths are needed OASIS3 MCT will calculate these weights and corresponding addresses if they are not already provided but will not at run time calculate the two extra terms to which the second and third weights should be applied these terms respectively the gradient of the field with respect to the longitude 0 of and 4 4 THE POST PROCESSING STAGE 33 4 4 the gradient of the field with respect to the latitude ay i need to be calculated by the source code and transfered as extra arguments of the oasis put see 1d2 f1d3 in section 2 7 1 Note that CONSERV SECOND is not positive definite and has not been fully validated yet Precautions related to the use of the SCRIPR CONSERV remapping For the 1st order conservative remapping the weight of a source cell is proportional to area of the source cell intersected by target cell Using the divergence theorem the SCRIP library evaluates this area with the line integral along the cell borders enclosing the area As the real shape of the borders is not known only the location of the 4 corners of each cell is known the library assumes that the borders are linear in latitude and longitude between two corners This assumption becomes less valid closer to the pole and for latitudes above the north thresh or below the south_thresh values see oasis3 mct lib scrip remap_conserv F the library evaluates the intersection b
85. tor based on the name given to oasis_init_comp routine its value is returned as the first argument of the routine Local_comm The model may call MPI_Init explicitly but if so has to call it before calling oasis_init_comp in this case the model also has to call MPI_Finalize explicitly but only after calling oasis_terminate 8 CHAPTER 2 INTERFACING A COMPONENT MODEL WITH OASIS3 MCT 2 2 3 Coupling through a subset of the component model processes If only a subset of the component processes participate in the coupling a communicator gathering only these processes must be defined with oasis prism_create_couplcomm or oasis prism_set_couplcomm These routines should be called after the oasis_init_comp but before the grid partition or coupling field declaration If such communicator does not exist in the code the component processes have to create it with e CALL oasis_create_couplcomm icpl local_comm coupl_comm kinfo e CALL prism_create_couplcomm icpl local comm coupl comm kinfo icpl INTEGER IN coupling process flag local_comm INTEGER IN MPI communicator with all processes of the component coupl_comm INTEGER OUT returned MPI communicator gathering only component processes participating in the coupling kinfo INTEGER OUT OPTIONAL returned error code This routine creates a coupling communicator for a subset of processes It must be cal
86. triction bins see SCRIP 1 4 documentation SCRIPusers pdf Note that for D or U grid the restriction may influence sligthly the result near the borders of the restriction bins SNV is the number of neighbours used SASSCMP UNUSED vector fields are not supported anymore in OASIS3 MCT See Support of vector fields with the SCRIPR remappings below SPROJCART UNUSED vector fields are not supported anymore in OASIS3 MCT See Support of vector fields with the SCRIPR remappings below GAUSWGT performs a N nearest neighbour interpolation weighted by their distance and a gaussian function All grid types are supported x Masked target grid points the zero value is associated to masked target grid points Non masked target grid points having some of the N source nearest neighbours masked a nearest neighbour algorithm using the remaining non masked source nearest neighbours is applied x Non masked target grid points having all of the N source nearest neighbours masked by default the nearest non masked source neighbour is used logical 11_nnei hard coded to true inoasis3 mct lib scrip src remap_gauswgt F this is NOT the same default behaviour as OASIS3 3 to have the same default behaviour as in OASIS3 3 put 1l nnei false The configuring line is SCRIPR for GAUSWGT SCMETH SCGRS SCFTYP SREST S NBIN SNV SVAR where all entries are as for DISTWGT except that SCMETH GAUSWGT SVAR which must be
87. uding call to mct_waitsend and mct_isend Appendix A The grid types for the transformations As described in section 4 for the different SCRIP remappings OASIS3 MCT support different types of grids The characteristics of these grids are detailed here 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 previous OASIS3 A B G L Y or Z grids are all particular cases of LR grids U grid Unstructured U grids do have any particular structure The longitudes and the lati tudes of 2D Unstructured grid points must be described by two arrays longitude nbr_pts 1 and latitude nbr_pts 1 where nbr_pts is the total grid size D grid The Reduced D grid is composed of a certain number of latitude circles each one being divided into a varying number of longitudinal segments In OASIS3 MCT the grid data lon gitudes latitudes etc must be described by arrays dimensioned nbr_pts 1 where nbr_pts is the total number of grid points There is no overlap of the grid and no grid point at the equator nor at the poles There are grid points on the Greenwich meridian Appendix B Changes between the different versions of OASIS3 MCT The evolution between the different versions of OASIS3 MCT can be
88. ufresne LMD Jean Marie Epitalon CERFACS Laurent Fairhead LMD Uwe Fladrich SMHI Marie Alice Foujols IPSL Gilles Garric CERFACS Eric Guilyardi CERFACS Charles Henriet CRAY France Pierre Herchuelz ACCRD Maurice Imbard M t o France Luis Kornblueh MPI M Stephanie Legutke MPI M amp D Claire L vy LODYC Olivier Marti IPSL LSCE S bastien Masson IPSL LOCEAN Claude Mercier IDRIS Pascale Noyret EDF Andrea Piacentini CER FACS Marc Pontaud M t o France Adam Ralph ICHEC Ren Redler MPI M Tim Stockdale ECMWF Rowan Sutton UGAMP V ronique Taverne CERFACS Jean Christophe Thil UKMO Nils Wedi ECMWF Chapter 1 Introduction In 1991 CERFACS started the development of a software interface to couple existing ocean and atmo sphere numerical General Circulation Models Today different versions of the OASIS coupler are used by about 35 modelling groups in Europe Australia Asia and North America on the different computing plat forms Valcke 2013 OASIS sustained development is ensured by a collaboration between CERFACS and the Centre National de la Recherche Scientifique CNRS and its maintainance and user support is presently reinforced with additional resources coming from the IS ENES2 project funded by the EU The current OASIS3 MCT is interfaced with MCT the Model Coupling Toolkit Larson et al 2005 Jacob et al 2005 developed by the Argonne National Laboratory in the USA MCT impl
89. write partially transformed fields in the coupling restart file at the end of a run to ensure an exact restart of the next run see section 4 1 For that reason coupling restart filenames are now required for all namcouple entries that use LOCTRANS with non INSTANT values This is the reason an optional restart file is now provided on the OUTPUT namcouple input line e Support to couple multiple fields via a single communication This is supported through colon delimited field lists in the namcouple for example ATMTAUX ATMTAUY ATMHFLUX TAUX TAUY HEATFLUX 1 3600 3 rstrt nc EXPORTED in a single namcouple entry All fields will use the namcouple settings for that entry In the com ponent model codes these fields are still sent put or received get one at a time Inside OASIS3 MCT the fields are stored and a single mapping and send or receive instruction is executed for all fields This is useful in cases where multiple fields have the same coupling transformations and to reduce communication costs by aggregating multiple fields into a single communication e Matching one source filed with multiple targets A coupling field sent by a source component model can be associated with more than one target field and model get In that case the source model needs to send put the field only once and the corresponding data will arrive at multiple targets as specified in the namcouple configuration file Different coupling fr

OASIS3-MCT User Guide OASIS3-MCT 2.0

Contents

Download Pdf Manuals

Related Search

Related Contents