Availability/Download of the EDSS/Models-3 I/O API

Please read the copyright, licensing, and acknowledgements page: The I/O API library is available under the Lesser Gnu Public License, version 2.1; the "tool" and example programs are available under the Gnu Public License, version 2.

Contents

Release notes are available here.

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.


NOTE on File Types

Files with extension ".gz" or ".tgz" are compressed with the GNU gzip utility. Source for gzip is available from a number of FTP sites; executables for a variety of platforms are available from several sources, including ftp://ftp.netscape.com/pub/unsupported/gnu/. On windows platforms, either winzip or the Cygnus windows port of gzip can deal with ".gz" and ".tgz" files.

Back to Contents


DISCLAIMER

This source code and these object libraries are available in unsupported form only, and neither MCNC nor Baron Advanced Meteorological Systems LLC accepts any liability for its usability or correctness for any purpose. See the "Notices" document for acknowledgements, copyright and licensing information.

On the other hand, its author thinks it is good stuffTM and welcomes comments and suggestions. Back to Contents


I/O API Documents

The EDSS Documentation for the EDSS/Models-3 I/O API is available only as HTML -- it was designed from the start as a heavily cross-linked hyperdocument, and is not available in linear dead-tree document-forms such as PDF. The EDSS Documentation for the EDSS/Models-3 I/O API is copyright (C) 1992-2002 MCNC and Carlie J. Coats Jr, and copyright (C) 2003-2004 Baron Advanced Meteorological Systems. A gzipped tar-file snapshot for I/O API Version 2.1 is available here.;

Back to Contents


I/O API Version 3.0 Availability

Version 3.0 of the I/O API library code is available here for download in source code form. New features of this release are documented here, and include additional support for WRF, a new native-binary-format lower layer, a file-set lower layer, some new routines, and enhancements for portability and OpenMP thread-safety.

This release is current as of January 18 29, 2005 and includes all bug-fixes up through that date. It should be considered the first prduction release of Version 3.0 for netCDF files, but should probably still be considered "beta" for PVM-based virtual files, 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:

To build multiple configurations from one installation directory (e.g., multiple compilers, etc.)
The procedure is much as before, except that one can use just a single make command to build all the libraries and all the executables for a configuration.

To build a single configuration from one installation directory
The new procedure allows one to do a make configure command during setup to make a complete set of customized Makefiles for the configuration, and then a top-level make command to build all the libraries and all the executables for that configuration.

To set up the installation:
  1. Download the gzipped tar-file. It contains directories 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).

  2. cd to the directory under which you wish to build the I/O API. gunzip and untar (gtar xvfz ioapi-3.0.tar.gz does this in one operation).

  3. For each desired configuration, setenv BIN <machinetype>, where <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:

    • At some point in its 8.0.x sequence of compiler versions, Intel has changed the names of its compilers: ecc becomes icc for the Itanium (IA64) platform, and both efc and ifc become ifort; you may need to edit the MAKEINCLUDE.$BIN accordingly.
    • There are problems with SGI f90 Version 7.4. Use Version 7.4.1 or later instead.
    • There are command line incompatibilities between SGI f90 Version 7.3.x and 7.4.1; for 7.3.x, you need to edit the MAKEINCLUDE.$BIN to replace -TARG:platform=ip27 -TARG:processor=r12000 by -TARG:platform=ip27,processor=r12000, (etc.)

  4. Acquire and build the netCDF library, libnetcdf.a, for each configuration. The netCDF home page is http://www.unidata.ucar.edu/packages/netcdf/ For each configuration,copy or link the resulting libnetcdf.a to the appropriate object directory.

    If you plan to build a coupling-mode configuration, do the same with PVM. See http://www.csm.ornl.gov/pvm/pvm_home.html

  5. Edit the relevant files ioapi/Makeinclude.$BIN for your system specific compiler options and PVM installation location, as appropriate.

  6. Edit the top-level 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

  7. setenv BIN ..., followed by one of the make <target> commands below, as appropriate for your configuration(s),

Top-Level make targets include the following:
make all
Build all libraries and executables (assumes the Fortran compiler is Fortran-90 compliant) for the default mode.
make cpl
Build all libraries and executables for PVM-enabled coupling mode.
make nocpl
... for no-PVM no-coupling mode. This is probably the best target for regulatory users who need multiple configurations.
make f77
... for Fortran-77 only compiler systems
make f77cpl
... for Fortran-77 only, PVM-enabled
make f77nocpl
... for Fortran-77 only, no-PVM
make relink
Rebuild all the executables, using the existing M3TOOLS object files (e.g.,if you have changed the libraries).
make clean
removes all executable, object (.o), and library (.a) files.
make configure
allows you to set up make-parameters in the top-level 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 SGI
builds everything for architectures IRIX6n32, IRIX6n32f90, IRIX64, and IRIX64f90make Sun
builds everything for architectures SunOS5 and SunOS5f90
make fix
builds CMAQ "fixed-132" Fortran source form INCLUDE-files.

Back to Contents


I/O API Version 2.2 Availability

Version 2.2 of the I/O API library code is available here for download in source code form. New features of this release are documented here. The build procedure is the same as that for Version 2.1, documented below, except for the following:

This download is current as of October 18, 2003 Back to Contents


I/O API Version 2.0 and 2.1 Availability

Updated May 7,2002 for SMOKE release: now produces a library named 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):

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).

  1. Download the gzipped tar-file 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.

  2. cd to the directory under which you wish to build the I/O API. gunzip and untar the ioapi_21.tar.gz (with Gnu tar,
    tar xvfz ioapi_v2.1.tar.gz
    does unzip-untar all in one step).

  3. setenv BIN <machinetype>
    where <machinetype> matches the extension on one of the Makeinclude.* (building your own Makeinclude if yours is not one of the supported systems).
    The usual pattern for generating 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.

  4. The default directory for both executables and object libraries is in directory ../$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).
    NOTE 1: Different compilers generate linker-visible object names in different ways (some with multiple options...). It is important that all of the compiles for an entire executable program (including the compiles for netCDF, PVM, and other libraries) use the same scheme; this is controlled by various parts of the ARCHFLAGS variable in the (compiler-system dependent) Makeinclude.$BIN files.
    NOTE 2: By default on most systems, OpenMP parallelism is enabled; see the 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.

  5. In the I/O API library source directory 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.

  6. If necessary, get netCDF and build libnetcdf.a; if you're building with Coupling Mode active, do the same for PVM.
  7. Copy or link (ln -s ...) libnetcdf.a (and libpvm3.a if you built it) to your OBJDIR.

  8. In the I/O API tool source directory 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.

Binary executables and object libraries are available for the following platforms; note that they were compiled on specific systems here at MCNC EMC, and may well suffer from shared-library and compiler compatibility problems on other platforms (particularly for Suns); the recommended procedure is to make the libraries and tools from source, but these are provided as a convenience to the users:

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 Version 1 Availability

I/O API library source code and related tool and example program source code (copyright MCNC 1992-1999) are available in tarred, gzipped (.tar.gz) form. Note to Internet Explorer users: IE seems to be brain-damaged in some fashion, and refuses to accept an FTP-URL to the current working directory. Try either using Netscape for the download or going to the EDSS download page, instead.

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:

Additionally, libioapi.a has in the past been compiled for Cray Y-MP/UNICOS, Cray C-90/UNICOS, SGI IRIX 4.x, SGI IRIX 6.x (n64 mode), Digital ULTRIX (both VAX and MIPS) and VAX/VMS, but the machines used for building these no longer are available to compile and build the latest versions of the libraries. Work is in progress on Cray T-3E and Win32; it should be a simple task to build versions of the libioapi.a and libnetcdf.a archive libraries and the I/O API-related programs on most UNIX workstations--at least, those with Feldman-descended f77's or those with g77 from the Free Software Foundation or the EGCS Project.

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


UP: I/O API home page

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