/** \page intropage Introduction
<h3>Design Considerations</h3>
<div style="margin-left: 40px;">In order to define an API it is
necessary to first identify the issues that the API needs to
address.&nbsp; In the case of the Star/CD file format, the relevant
issues are:
<ul>
  <li> Adherence to the defined specification.&nbsp;  Considerable work
went into defining the Star/CD file format, so the API should be able to
read and write precisely to the specs. </li>
  <li> Flexibility of the API. &nbsp;The API should be flexible enough
to allow some changes to the specification to be made without requiring
modification of the API.</li>
  <li> Relocatability of data. &nbsp;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.</li>
  <li>Usability of the API.&nbsp; 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.</li>
</ul>
The design decisions that have been made in light of these issues are
detailed below.<br>
<h4>Adherence</h4>
<div style="margin-left: 40px;"> 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. &nbsp;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. &nbsp;At a bare minimum, then, the API must be able to
write and read files precisely to the specification.<br>
</div>
<h4>Flexibility</h4>
<div style="margin-left: 40px;"> 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.&nbsp;   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.<br>
<br>
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. </div>
<h4>Relocatability</h4>

<div style="margin-left: 40px;"> Passing mesh data from pre-processor to
solver and post data from solver to post-processor are just two
possible uses for this API.&nbsp;  Since the file format is supposed to
be a genuine replacement for the existing <span
 style="font-family: monospace;">.ngeom</span>, <span
 style="font-family: monospace;">.pst</span>, and <span
 style="font-family: monospace;">.npost</span> 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 <span style="font-family: monospace;">.ngeom</span>
file).</div>
<h4>Usability</h4>
<div style="margin-left: 40px;">The API makes certain assumptions about
the nature of usability;&nbsp; these are:<br>
<ul>
  <li>Conciseness:&nbsp; the API will attempt to keep the number of
functions to the bare minimum.&nbsp; 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.</li>
  <li>No dynamic data:&nbsp; the API will not create arrays for the
caller;&nbsp; the caller is responsible for determining the size of any
array passed to the API.&nbsp; (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.</li>
  <li>Error handling:&nbsp; error handling will only require one check,
at the end of all the function calls to the API.&nbsp; This will be
accomplished by means of passing the error to each function (or NULL, if
the check is to be avoided);&nbsp; 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.&nbsp; Return values of all functions
will be the value of the error parameter, for convenience of the
caller.&nbsp; Of course, error handling may be performed as often as
desired, however it need not be done after every call.<br>
  </li>
</ul>
</div>
<h3>Caveats</h3>
<div style="margin-left: 40px;">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.
</div>
</div>
*/
