The What's New page documents bug-fixes, new features, new compiler-support, etc.
Note that a large amount of effort has been expended during the whole of I/O API development to ensure upward compatibility: programs written for the original Version 0.9 pre-release should still work correctly with I/O API Version 3.0, unlike some other software we will refrain from naming here.
NetCDF Version 4.x have lots of additional build options, that will require a complex set of additional libraries in Makefiles and all other model-building systems. It is recommended that you disable these options by adding the command-line flags below to your netCDF configure command:
--disable-netcdf4 --disable-dap
-lnetcdf with
-lnetcdff -lnetcdf. If you don't
build netCDF as indicated above, you will need additional libraries
that may be discovered by running the netCDF command
nc-config --libs
Starting with I/O API Version 3.1 of October 11,
2011, the m3tools/Makefiles are configured to use the
You must also modify the build-systems for CMAQ. MCIP, SMOKE, and
all your other models similarly.
-lnetcdff -lnetcdf netCDF-v4-style libraries. If
using a previous version of netCDF, you must modify them manually.
Back to Contents
INCLUDE
files.
Any changes are likely to result in very obscure,
difficult-to-diagnose bugs caused by an inconsistency
between standard libioapi.a object-libraries
and whatever code is compiled with the resulting modified
INCLUDE-file. Note that the distribution
license specifies that by making any changes to any of
these INCLUDE files, the user explicitly
agrees that in the case any assistance is
required of BAMS or of the I/O API author,
Carlie J. Coats, Jr. as a result of such
changes, the user and/or his project or contract agrees to
reimburse BAMS and/or the I/O API author,
Carlie J. Coats, Jr., at a rate triple the
normal contract rate for the services required.
ioapi for the
I/O API library source code,
HTML for the documentation,
m3tools for the related tool
programs, iotest for various
test-programs, and notcdf for the
NCEP libnotcdf.a library (a dummy library
for installation sites that don't
allow netCDF on-site).
<machinetype> matches
the extension on one of the
ioapi/Makeinclude.*. Then do a
top-level make dirs to build the
object-directories.
The usual pattern for generating BIN is
setenv BIN `uname -s``uname -r | cut -d. -f1`and then modify the result by appending any compiler specifics, e.g., for F90 or debug compiled configurations.
Note, for example,
that for Linux2_x86, there are
distinct (and incompatible) variants for the
GNU g77/gcc, Intel ifc/icc,
Lahey-Fujitsu lf95/GNU gcc,
and Portland Group pgf90/pgcc;
moreover, the latter is not compatible with
Portland Group pgf90/GNU
gcc (when the latter is used to
build libnetcdf.a, as in the vendor
supplied libraries on RedHat (that
incompatibility being the largest single
generator of installation-questions in recent
years!).
INTEL and SGI NOTES:
MAKEINCLUDE.$BIN
accordingly.
*.F files.
Makefile.cpphack is a sample
Makefile for this purpose
(as provided, it assumes OpenMP and
coupling mode).
MAKEINCLUDE.$BIN to replace
-TARG:platform=ip27 -TARG:processor=r12000
by -TARG:platform=ip27,processor=r12000,
(etc.)
If you plan to build a coupling-mode configuration, do the same with PVM's libpvm3.a. See http://www.csm.ornl.gov/pvm/pvm_home.html (Only the C interface to PVM is used; the resulting library tends to be more compiler-independent than for netCDF, where both C and Fortran interfaces are used.)
ioapi/Makeinclude.$BIN for your
system specific compiler options and PVM
installation location, as appropriate.
Makefile to set
variables BASEDIR, etc., for your
system.
If you are doing a multi-configuration
installation, do the same for each
*/Makefile*.
If you are doing a single-configuration installation, do make configure
make all
make cpl
make nocpl
make relink
M3TOOLS object files (e.g.,if
you have changed the libraries).
make clean
.o),
and library (.a) files.
make configure
Makefile and
then run a set of sed commands
on the templates */Makefile*.sed
in order to generate lower level
Makefiles for a particular
configuration.
make bins
make binclean
make fix
INCLUDE-files.
Back to Contents
MXVARS3 in PARMS3.EXT
from 120 to 2048. Consultation with actual modelers
indicate that this should be more than adequate;
suggestions elsewhere that users should change
MXVARS3 to 50000 are extremely irresponsible,
quite ridiculous, and dangerous for all but the most
sophisticated users..
IOAPI_OFFSET_64 (default NO)
MODULE M3UTILIO
should be used for all new codes).
${BIN} choices.
MODULE M3UTILIO.
Makefiles
assume netCDF 4.1 or later (which requires
-lnetcdff as part of the library flags
for linking).
The build procedure is given above..
Version 3.1 can read all files generated by Version 3.0;
Version 3.0 can read all files generated by Version 3.1,
provided that the number if variables in the file
NVARS3D < 121.
Due to the changes in
MXVARS3. Version 3.1 is a
"Jubilee Day" release: it should completely replace
previous versions; object files produced using
Version 3.1 should not be mixed with previous versions.
MODULE M3UTILIO
ensures that the library and user object code use consistent
parameter values (as well as ensuring correctness of most
call interfaces).
Note also that changing MXVARS3 was never
supported, is strongly discouraged, and may lead to invocation
of the triple-time clause (see header of PARMS3.EXT)
if support of such a modified installation is requested.
This release is current as of September 28, 2011 and includes all bug-fixes up through that date.
Back to Contents
This release is current as of June 11, 2007 and includes all bug-fixes up through that date. It should be considered the production release of Version 3.0 for netCDF files and for PVM-based virtual files, but should probably still be considered "beta" for native-binary layer, and for the multi-file file-list layer, since each of these latter has basically a single-user community rather than widespread beta-test usage.
The build procedure also has been considerably enhanced, by the addition
of a top-level Makefile which allows one to build
various configurations of the entire (I/O API +
M3TOOLS) system with one make command.
Depending upon what you want to do, there are two main options for
how you will build the system:
Before you do so, yhou should edit the ioapi/Makefile and m3tools/Makefile commands so that the make bins and make binclean commands properly reflect the configurations you want to build.
ioapi for the
I/O API library source code,
HTML for the documentation,
m3tools for the related tool
programs, iotest for various
test-programs, and notcdf for the
NCEP libnotcdf.a library (a dummy library
for installation sites that don't
allow netCDF on-site).
<machinetype> matches
the extension on one of the
ioapi/Makeinclude.*. Then do a
top-level make dirs to build the
object-directories.
The usual pattern for generating BIN is
setenv BIN `uname -s``uname -r | cut -d. -f1`and then modify the result by appending any compiler specifics, e.g., for F90 or debug compiled configurations.
Note, for example,
that for Linux2_x86, there are
distinct (and incompatible) variants for the
GNU g77/gcc, Intel ifc/icc,
Lahey-Fujitsu lf95/GNU gcc,
and Portland Group pgf90/pgcc;
moreover, the latter is not compatible with
Portland Group pgf90/GNU
gcc (when the latter is used to
build libnetcdf.a, as in the vendor
supplied libraries on RedHat (that
incompatibility being the largest single
generator of installation-questions in recent
years!).
INTEL and SGI NOTES:
MAKEINCLUDE.$BIN
accordingly.
*.F files.
Makefile.cpphack is a sample
Makefile for this purpose
(as provided, it assumes OpenMP and
coupling mode).
MAKEINCLUDE.$BIN to replace
-TARG:platform=ip27 -TARG:processor=r12000
by -TARG:platform=ip27,processor=r12000,
(etc.)
If you plan to build a coupling-mode configuration, do the same with PVM's libpvm3.a. See http://www.csm.ornl.gov/pvm/pvm_home.html (Only the C interface to PVM is used; the resulting library tends to be more compiler-independent than for netCDF, where both C and Fortran interfaces are used.)
ioapi/Makeinclude.$BIN for your
system specific compiler options and PVM
installation location, as appropriate.
Makefile to set
variables BASEDIR, etc., for your
system.
If you are doing a multi-configuration
installation, do the same for each
*/Makefile*.
If you are doing a single-configuration installation, do make configure
Back to Contents
OBJDIR in the
Makefile, either by commenting out the
current value and un-commenting one of the alternatives,
or by setting your own system-dependent value.
Makefile builds the I/O API
with the Coupling Mode
Extensions enabled, and therefore requires
linking executables with PVM library (version 3 or
greater). To disable the Coupling Mode
Extensions, copy the provided
Makefile.nocpl to Makefile and
then build the system.
This download is current as of October 18, 2003 Back to Contents
libioapi_v2.1.a instead of
Version 2.0's libioapi_new.a
Release Version 2.1 of the I/O API and the I/O -related
tool and sample programs is available
here for download in source code form. New features of this
release are documented here.
Makeinclude files are available for the following
platforms (and some debug- and other variants, denoted by
dbg i8, and r8 suffixes):
Makeinclude.Linux2_x86pg assumes
you are using a gcc/g77-compatible
libnetcdf.a (as comes from the vendor on
many Linux systems). For pgf77/pgf90/pgcc
versions of libnetcdf.a, remove
-Msecond_underscore from
ARCHFLAGS in
Makeinclude.Linux2_x86pg.
From these examples and from a knowledge of the compiler user manual,
it should be relatively easy to build Makeinclude files
for most UNIX or UNIX-like platforms and compilers. Instructions
for building the I/O API library libioapi_v2.1.a
and the I/O API tool executable programs are as given below.
NOTE: It is important to ensure that the compile flags used for building the I/O API library are consistent with both the compile flags used for building your program and the compile flags used for building the netCDF, PVM, and other libraries used by your programs. Failure to do so may result in link-failures or (in the case of the Linux Portland Group compilers) run-time program deadlocks (program hangs, doing no work while consuming all available CPU resources).
ioapi_21.tar.gz.
It contains directories ioapi for the
I/O API library source code, ioapi_doc
for the HTML documentation, and ioapi_tools
for the related tool programs.
ioapi_21.tar.gz (with Gnu tar,
tar xvfz ioapi_v2.1.tar.gz
setenv BIN <machinetype><machinetype> matches the
extension on one of the Makeinclude.*
(building your own Makeinclude if yours
is not one of the supported systems).BIN is
setenv BIN `uname -s``uname -r | cut -d.
-f1`
although there are exceptions where more work is needed
for Cray, SGI and Linux systems, and F90 or DEBUG
compiles.
../$BIN relative
to the source code directories for the I/O API and
tools. Edit the Makefile to put OBJDIR wherever you want it
(if you want somewhere other than the default
../$BIN location).
ARCHFLAGS variable in the (compiler-system
dependent) Makeinclude.$BIN files.
OMPFLAGS
variable in Makeinclude.$BIN. The
I/O API does not have parallel sections of its own;
however, enabling OpenMP does allow the activation of
critical sections allowing the I/O API to be
thread-safe for OpenMP-parallel programs (like the
MAQSIP-RT air quality model, the WRF or MCPL-enabled MM5
meteorology models, research versions of SMOKE, and others.
You may set OMPFLAGS and OMPLIBS
to empty-strings in order to disable this
thread-protection, if you wish.
ioapi,
type make to build the object library. The
current build process will generate
$OBJDIR/libioapi_v2.1.a (to distinguish it
from earlier Version 1 $OBJDIR/libioapi.a);
mv it to libioapi.a or
libm3io.a, if desired.
libnetcdf.a; if you're building with Coupling
Mode active, do the same for PVM.
libnetcdf.a
(and libpvm3.a if you built it) to your
OBJDIR.
ioapi_tools, type either make
(if you have a F90-compliant Fortran compiler), or
make f77 (if you don't) to build the
tool-program executables (adjusting the LIB
make-variable if you renamed
$OBJDIR/libioapi_v2.1.a in the preceeding
step). Note that there are a number of these programs
that do require F90: dayagg, ginterp,
m3cple, m3agmax, m3agmask, m3combo, m3merge, mtxblend,
mtxbuild, mtxcalc, mtxcple, presterp, and
selmrg2d.
NOTE: On the Sun and SGI platforms, there are link incompatibilities between f77 and f90, caused by the fact that these vendors' f77 and f90 by default use different system libraries. Compaq, Cray, and IBM compilers do not seem to do this; however, it is probably advisable not to mix f77 and f90 compiles on a not-well-understood new platform.
Back to Contents
I/O API usage requires archive libraries libioapi.a compiled for your modeling platform. It also requires the Unidata netCDF library libnetcdf.a, version 3.x or later (NOTE: certain token-value parameters were changed between netCDF 2.x and 3.x; all that is required to build the I/O API for netCDF 2.x is to use that version's netcdf.inc INCLUDE-file and recompile libioapi.a.). If you are running in coupled-model mode, you also need the model-coupling library, as well as PVM 3.4 or later.
Both the libioapi.a object library and the m3tools.tar.gz set of I/O API-related programs are available for the following list of currently-supported host architectures:
Please go to the EDSS Registration and Download page for more information about availability, software registration, and downloading of multiple EDSS subsystems, including not only the I/O API and its related tools but also the PAVE visualization system, the EDSS Study Planner, and the SMOKE emissions model.
Back to Contents
Back to Contents
On the other hand, its author thinks it is good stuffTM and welcomes comments and suggestions. Back to Contents
Back to Contents
UP: Environmental Modeling Center at MCNC home page
UP: The Environmental Decision Support System Pages
Back to the I/O API User Manual
Send comments to
Carlie J. Coats, Jr.
carlie.coats@baronams.com