3 OASIS3-MCT C API

OASIS3-MCT is distributed with C bindings and can be called from models written in C and in C++. These bindings leverage the Fortran ISO_C_BINDING standard. The C bindings can be compiled into static or shared libraries by the OASIS3-MCT TopMakefileOasis3 as documented in 6.1.

The C interfaces largely match up with equivalent interfaces in Fortran. An interface named oasis_interface in Fortran can be expected to be named oasis_c_interface in C.

All of the C interfaces return an integer error code which can be tested against the OASIS_Ok (or the equivalent OASIS_Success) constant. The OASIS_CHECK_ERR macro aborts OASIS3-MCT with a meaningful message in the debug files in case of failure. For most of the functions, the return code is consistent with the kinfo argument in the Fortran interfaces (see section 2.2). However, for the put and get communication functions, the return error code only indicates success or failure, while the detailed status is returned by the kinfo argument (equivalent to the returned value of info argument for the Fortran oasis_put and oasis_get routines, see section 2.2.7).

For example, the following constructs are equivalent in the two languages:

call oasis_get_localcomm(localcomm, kinfo)
if (kinfo .ne. OASIS_Ok)  &
   &  call OASIS_Abort(comp_id, "oasis_get_localcomm", &
   &  "Runtime error", __FILE__, __LINE__)

and

OASIS_CHECK_ERR(oasis_get_localcomm(localcomm))

For convenience a similar macro OASIS_CHECK_MPI_ERR has been defined for testing the return code of any MPI function against MPI_SUCCESS and cleanly aborting OASIS3-MCT in case of failure.

Use of these C bindings are illustrated in practical examples in directories /C in the different subdirectories in pyoasis/examples/. Notes and deviations from the Fortran standard are noted below.

• To use the OASIS3-MCT C bindings, the statement

  #include "oasis_c.h"
  

  needs to be added to the C model source code. All available parameters macros and interfaces are defined there.

• int oasis_c_init_comp(int* compid, const char* comp_name, const bool coupled)
  • This oasis_c_init_comp interface includes the coupled flag but NO communicator argument; use oasis_c_init_comp_with_comm below to indicate a communicator argument.
  • The coupled argument can receive the predefined mnemonic boolean constants OASIS_Coupled and OASIS_Not_Coupled

  
  

• int oasis_c_init_comp_with_comm(int* compid, const char* comp_name, const bool coupled, const MPI_Comm commworld)
  • This alternative init_comp interface has the coupled flag and a C MPI_Comm communicator

  
  

• int oasis_c_get_localcomm(MPI_Comm* local_comm)
  • Returns the local communicator by reference in a C MPI_Comm* type argument

  
  

• int oasis_c_create_couplcomm(const int icpl, const MPI_Comm local_comm, MPI_Comm* coupl_comm)
  • icpl is a C int type input argument (see oasis_create_couplcomm in section 2.2.2)
  • loca_comm is a C MPI_Comm type input argument (by value)

  • coupl_comm is a C MPI_Comm* type output argument (by reference)

  
  

• int oasis_c_set_couplcomm(const MPI_Comm coupl_comm)
  • Takes a C MPI_Comm type as an input argument (by value)

  
  

• int oasis_c_def_partition(int* il_part_id, const int ig_paral_size, const int* ig_paral, const int ig_size, const char* name)
  • ig_paral_size is the size of the array ig_paral: the oasis_c.h header provides a set of constants and macros for the size of every partition strategy, namely OASIS_Serial_Params, OASIS_Apple_Params, OASIS_Box_Params, OASIS_Orange_Params(n_segments), OASIS_Points_Params(n_points)
  • the oasis_c.h header also provides a set of predefined constants for the storages positions in ig_paral, namely OASIS_Strategy, OASIS_Segments, OASIS_Npoints, OASIS_Offset, OASIS_Length, OASIS_SizeX, OASIS_SizeY, OASIS_LdX
  • the partition strategy, to be stored in the OASIS_Strategy position of ig_paral, can take one of the following predefined constants values: OASIS_Serial, OASIS_Apple, OASIS_Box, OASIS_Orange, OASIS_Points
  • for the cases in which the ig_size and name arguments are not relevant for the partition definition, the placeholders OASIS_No_Gsize and OASIS_No_Name can be used instead
  Here an example for the OASIS_Part_Apple strategy

    int part_params[OASIS_Apple_Params];
    part_params[OASIS_Strategy] = OASIS_Apple;
    part_params[OASIS_Offset] = offset;
    part_params[OASIS_Length] = local_size;
    int part_id;
    OASIS_CHECK_ERR(oasis_c_def_partition(&part_id, OASIS_Apple_Params,
                                          part_params, OASIS_No_Gsize,
                                          OASIS_No_Name));
  

  
  

• int oasis_c_start_grids_writing()

  
  

• int oasis_c_write_grid(const char* cgrid, const int nx_global, const int ny_global, const int nx_loc, const int ny_loc, const double* lon, const double* lat, const int il_partid) /local
  • nx_global and ny_global are the first and second dimensions of the global grid
  • nx_loc and ny_loc are the two dimensions of the local arrays lon and lat
  • lon and lat are stored with a Fortran compatible (column major) ordering. For example, if they are declared as double pointers, they have to be lon[ny_loc][nx_loc]
  • il_partid is relevant only for parallel writing; in case of single proc invocations, the constant OASIS_No_Part can be passed as a placeholder

  
  

• int oasis_c_write_corner(const char* cgrid, const int nx_global, const int ny_global, const int nc, const int nx_loc, const int ny_loc, const double* clon, const double* clat, const int il_partid)
  • nx_global and ny_global are the first and second dimensions of the global grid
  • nc is the maximum number of corners per cell
  • nx_loc and ny_loc are the two dimensions of the local arrays clon and clat
  • clon and clat are stored with a Fortran compatible (column major) ordering. If they are declared as triple pointers, they have to be clon[nc][ny_loc][nx_loc]
  • il_partid is relevant only for parallel writing. In case of single proc invocations, the constant OASIS_No_Part can be passed as a placeholder

  
  

• int oasis_c_write_mask(const char* cgrid, const int nx_global, const int ny_global, const int nx_loc, const int ny_loc, const int* mask, const int il_partid, const char* companion)
  • nx_global and ny_global are the first and second dimensions of the global grid
  • nx_loc and ny_loc are the two dimensions of the local array mask
  • mask is stored with a Fortran compatible (column major) ordering. If it is declared as a double pointer, it has to be mask[ny_loc][nx_loc]
  • il_partid is relevant only for parallel writing. In case of single proc invocations, the constant OASIS_No_Part can be passed as a placeholder
  • if no companion grid attribute is needed, the constant OASIS_No_Companion can be passed as a placeholder

  
  

• int oasis_c_write_frac(const char* cgrid, const int nx_global, const int ny_global, const int nx_loc, const int ny_loc, const double* frac, const int il_partid, const char* companion)
  • nx_global and ny_global are the first and second dimensions of the global grid
  • nx_loc and ny_loc are the two dimensions of the local array frac
  • frac is stored with a Fortran compatible (column major) ordering. If it is declared as a double pointer, it has to be frac[ny_loc][nx_loc]
  • il_partid is relevant only for parallel writing. In case of single proc invocations, the constant OASIS_No_Part can be passed as a placeholder
  • if no companion grid attribute is needed, the constant OASIS_No_Companion can be passed as a placeholder

  
  

• int oasis_c_write_area(const char* cgrid, const int nx_global, const int ny_global, const int nx_loc, const int ny_loc, const double* area, const int il_partid)
  • nx_global and ny_global are the first and second dimensions of the global grid
  • nx_loc and ny_loc are the two dimensions of the local array area
  • area is stored with a Fortran compatible (column major) ordering. If it is declared as a double pointer, it has to be area[ny_loc][nx_loc]
  • il_partid is relevant only for parallel writing. In case of single proc invocations, the constant OASIS_No_Part can be passed as a placeholder

  
  

• int oasis_c_write_angle(const char* cgrid, const int nx_global, const int ny_global, const int nx_loc, const int ny_loc, const double* angle, const int il_partid)
  • nx_global and ny_global are the first and second dimensions of the global grid
  • nx_loc and ny_loc are the two dimensions of the local array angle
  • angle is stored with a Fortran compatible (column major) ordering. If it is declared as a double pointer, it has to be angle[ny_loc][nx_loc]
  • il_partid is relevant only for parallel writing. In case of single proc invocations, the constant OASIS_No_Part can be passed as a placeholder

  
  

• int oasis_c_terminate_grids_writing()

  
  

• int oasis_c_def_var(int* var_id, const char* name, const int il_part_id, const bundle_size, const int kinout, const int var_type)
  • bundle_size is a scalar integer, corresponding to the second entry of the Fortran var_nodims array
  • kinout can receive one of the two predefined constants OASIS_In or OASIS_Out (also in the form OASIS_IN or OASIS_OUT)
  • var_type can receive one of the two predefined constants OASIS_Real or OASIS_Double (also in the form OASIS_REAL or OASIS_DOUBLE)

  
  

• int oasis_c_enddef()

  
  

• int oasis_c_put(const int var_id, const int date, const int x_size, const int y_size, const int bundle_size, const int fkind, const int storage, const void* fld1, const bool write_restart, int* kinfo)
  • This interface does not support higher order mapping through optional fields at this time.
  • x_size and y_size are the dimensions of the local portion of the domain (i.e. fld1). The order of these dimensions must be the same than the order of the dimensions of the arrays in the grids.nc file, which corresponds to the storage order in the corresponding internal OASIS3-MCT Fortran work arrays.
    Notice that for unstructured grids y_size=1
  • bundle_size should be coherent with the argument of same name in the corresponding oasis_c_def_var
  • fkind can take one of the two predefined constants OASIS_Real or OASIS_Double (also in the form OASIS_REAL or OASIS_DOUBLE) should be coherent with the argument ktype in oasis_c_def_var
  • storage can take one of the two predefined constants OASIS_COL_MAJOR or
    OASIS_ROW_MAJOR.
    In the first case, the array containing the field has to be declared as
    field[bundle_size][y_size][x_size] (or any equivalent storage of total size
    bundle_size*y_size*x_size stored in column major order.
    In the second case, the field has to be declared as
    field[x_size][y_size][bundle_size] (or any equivalent row major storage).
    Notice that this choice implies an extra memory copy performed internally by OASIS3-MCT before acting on the field and is therefore to be avoided whenever possible.
  • write_restart can take one of the two predefined constants OASIS_Write_Restart or OASIS_No_Restart
  • kinfo contains a return status to be compared against the values of the return_codes enumeration in oasis_c.h (equivalent to the returned value of info argument for the Fortran oasis_put routine, see section 2.2.7)

  
  

• int oasis_c_get(const int var_id, const int date, const int x_size, const int y_size, const int bundle_size, const int fkind, const int storage, void* fld1, int* kinfo)
  • arguments are the same than for oasis_c_put, except that kinfo return status is equivalent to the returned value of info argument for the Fortran oasis_get routine, see section 2.2.7.

  
  

• int oasis_c_terminate()

  
  

• int oasis_c_abort(const int compid, const char* routine_name, const char* abort_message, const char* file, const int line)

  
  

• int oasis_c_get_debug(int* debug)

  
  

• int oasis_c_set_debug(const int debug)

  
  

• int oasis_c_get_intercomm(MPI_Comm* new_comm, char* cdnam)
  • Returns a C MPI_Comm type by reference

  
  

• int oasis_c_get_intracomm(MPI_Comm* new_comm, char* cdnam)
  • Returns a C MPI_Comm type as by reference

  
  

• int oasis_c_get_multi_intracomm(MPI_Comm* new_comm, const int cdnam_size, char** cdnam, int* root_ranks)
  • Returns a C MPI_Comm type as by reference
  • cdnam_size is the size of the array cdnam

  
  

• int oasis_c_put_inquire(int var_id, int date, int* kinfo)
  • kinfo contains a return status to be compared against the values of the return_codes enumeration in oasis_c.h

  
  

• int oasis_c_get_ncpl(const int var_id, int* ncpl)

  
  

• int oasis_c_get_freqs(const int var_id, const int mop, const int ncpl, int* cpl_freqs)