Design Considerations
In order to define an API it is necessary to first identify the issues that the API needs to address. In the case of the Star/CD file format, the relevant issues are:
-
Adherence to the defined specification. Considerable work went into defining the Star/CD file format, so the API should be able to read and write precisely to the specs.
-
Flexibility of the API. The API should be flexible enough to allow some changes to the specification to be made without requiring modification of the API.
-
Relocatability of data. Nodes for mesh and solution data should be relocatable so the API can be used for purposes other than passing data from pre-processor to solver and solver to post-processor.
-
Usability of the API. The API needs to strike a balance between ultimate flexibility, which results in a low-level API, and ultimate usability, which is not easily extensible.
The design decisions that have been made in light of these issues are detailed below.
Adherence
The specification developed by Wayne, Samir, Luke, and Milovan outlines a format to replace the vast number of different files and formats we currently use with a single format and possibly a single file. This specification was written to meet all the needs of our next generation face-based CCM solvers and should be used to drive all design decisions for the API which writes to and reads from it. At a bare minimum, then, the API must be able to write and read files precisely to the specification.
Flexibility
It is inevitable that the changes to the specification will be made in the future. Wherever possible, the API should be written such that minor changes to the specification can be made without any modification to the API. Fundamental portions of the specification such as the face vertices and face cells should be accessed through fixed, high level methods in the API since these items will not change and are stored in a complex way that should not be exposed by the API. Other data, such as the recently added cell topology type, should be accessed through the API simply as a named attribute (i.e. using a character string, not a fixed enumeration or subroutine). In this way, other pieces of similar information can be added to the specification without requiring any modification to the API.
In addition, this design allows us to deal flexibly with the question of whether the specification is simply sufficient or both necessary and sufficient. For example, if a writing application does not have cell topology type stored, is it required to compute this information before it can write the file (necessary and sufficient) or can it write the file without this information (just sufficient). The reading application, then, would read the data if it is in the file or either compute it or assume a sensible default if it is not.
Relocatability
Passing mesh data from pre-processor to solver and post data from solver to post-processor are just two possible uses for this API. Since the file format is supposed to be a genuine replacement for the existing .ngeom, .pst, and .npost formats, we must consider its use in passing data between other applications, such as between two meshing components. To facilitate this, it should be possible to write mesh and post data to any location in the file, not just that defined in the specification. In the simplest case, it should be possible for a meshing application to use the API to write just the mesh to a file (a true replacement for the .ngeom file).
Usability
The API makes certain assumptions about the nature of usability; these are:
-
Conciseness: the API will attempt to keep the number of functions to the bare minimum. This means that structures will be employed to return multiple pieces of data and tasks that have similar functions (e.g. opening and closing data sets) will use the same entry points. However, where conciseness prevents compile-time checking, different entry points will be used.
-
No dynamic data: the API will not create arrays for the caller; the caller is responsible for determining the size of any array passed to the API. (The API will, of course, provide access to the necessary sizes.) There is one exception: the Core API, which should really only be used within the library itself.
-
Error handling: error handling will only require one check, at the end of all the function calls to the API. This will be accomplished by means of passing the error to each function (or NULL, if the check is to be avoided); if an error has already occurred, the function will do nothing, and if an error does occur, the value of the error parameter will be updated. Return values of all functions will be the value of the error parameter, for convenience of the caller. Of course, error handling may be performed as often as desired, however it need not be done after every call.
Caveats
The CCMIO library currently uses ADF as the underlying file format. Unfortunately, deleting ADF nodes, as is necessary when rewriting mesh and post results, leads to fragmentation and loss of usable file space. This means that the ADF file will usually grow each time data is changed. A function,
CCMIOCompress(), has been provided to compress the file to its minimum size, and should be called judiciously.
Generated on Mon Dec 13 16:20:26 2004 for libccmio by
1.3.6