An system coupled by OASIS4 consists of different applications (each
application forming one
executable), each one hosting one or more than one components.
To communicate with the rest of the coupled system, each component
needs to perform appropriate calls to the OASIS4 Model
Interface Library (PSMILe)7 . The PSMILe is the software layer that
manages the coupling data flow between any two (possibly parallel)
components, directly or via additional Transformer processes,
and handles data I/O from/to files.
The PSMILe is layered, and while it is not designed to handle the component internal communication, it completely manages the communication to other components and can also manage the details of the I/O file access. The detailed communication patterns among the possibly parallel components are established by the PSMILe. They are based on the source and target components identified for each coupling exchange by the user in the SMIOC XML files (see section 6.5) and on the local domain covered by each component process. This complexity is hidden from the component codes as well as the exchanges of coupling fields per se built on top of MPI. In order to minimise communication, the PSMILe also includes some local transformations on the coupling fields, like accumulation, averaging, gathering or scattering, and performs the required transformation locally before the exchange with other components of the coupled system.
The interface was designed to keep modifications of the model codes at a minimum when implementing the API. Some complexity arises however in the API from the need to transfer not only the coupling data but also the definition of the grid, mask, etc. as will be explained below. In order to match the data structures of the various component codes (in particular for the geographical information) as closely as possible, Fortran90 overloading is used. All grid description and field arrays provided by the component code through the PSMILe API (e.g. the grid point location through prism_set_points , see 5.3.6) can have one, two or three numerical dimensions and can be of type ``Real'' or ``Double precision''. There is no need to copy the data arrays prior to the PSMILe API call in order to match some predefined internal PSMILe shape. To interpret the received array correctly, a properly defined grid type is required (see section 5.3.1), since the grid type implicitly specifies the shape of the data arrays passed to the PSMILe. Few API routines, i.e. prism_init, prism_enddef and prism_terminate, are collective routines that need to be called by all processes of all applications whether or not they participate in the coupling exchanges, while the other API routine should be called only by the application processes involved in the coupling.
A major principle followed throughout the declaration phase and during the transmission of transient fields is that of using identifiers (ID) to data objects accessible in the user space once they have been declared. Like in MPI, the memory that is used for storing internal representations of various data objects is not directly accessible to the user, and the objects are accessed via their ID. Those IDs are of type INTEGER and represent an index in a table of the respective objects. The object and its associated ID are significant only on the process where it was created.
The PSMILe API routines that are defined and implemented are not subject to modifications between the different versions of the OASIS4 coupler. However new routines may be added in the future to support new functionality. In addition to that the PSMILe is extendable to new types of coupling data and grids.
The next sections describe the functioning of the PSMILe, and explain its different routines in the logical order in which they should be called in a component.