page `index`¶

OverviewAMIO (Asynchronous Multidimensional I/O) is a high-performance I/O engine designed for NOAA NWS Earth system models. It provides a unified C99 API surface with Fortran 2003 bindings for writing and reading multidimensional scientific data through pluggable backend drivers.

Key Features

Asynchronous I/O: Non-blocking write operations with staging pool and worker threads for overlapping computation with I/O.
Multiple Backends: Pluggable drivers for NetCDF-4 (parallel HDF5), Zarr v3 (TensorStore or NCZarr fallback), and GRIB2 (nceplibs-g2c).
Unified API: Single C99 API surface consumed by both C/C++ and Fortran applications through iso_c_binding wrappers.
MPI-Aware: Communicator splitting and parallel I/O support for distributed-memory HPC applications.
Type-Safe Handles: Opaque handle system with generation-counter validation prevents use-after-free and handle misuse.

Architecture

┌─────────────────────────────────────────────────────────┐
│                   Host Application                       │
│              (C / C++ / Fortran)                         │
├─────────────────────────────────────────────────────────┤
│              AMIO Public API (C99 FFI)                   │
│         amio.h / amio_mod (Fortran)                     │
├─────────────────────────────────────────────────────────┤
│                  C-Boundary Layer                        │
│    Handle Table │ Exception Bridge │ Config Loader       │
├─────────────────────────────────────────────────────────┤
│   Staging Pool  │  Worker Pool  │  Prefetch Queue       │
├─────────────────────────────────────────────────────────┤
│              Backend Factory (Plugin Registry)           │
├──────────────┬──────────────┬───────────────────────────┤
│  NetCDF-4    │   Zarr v3    │       GRIB2               │
│  Driver      │   Driver     │       Driver              │
│ (HDF5/pnetcdf)│(TensorStore/ │  (nceplibs-g2c)          │
│              │  NCZarr)     │                           │
└──────────────┴──────────────┴───────────────────────────┘

Quick StartC API

#include <[amio/amio.h](site/api/api-amio.h.md#amio_8h)>

[amio_core_handle](site/api/api-amio_core_handle.md#amio__types_8h_1a40ca069f7efb7765f5f87d118f2d2456) core = NULL;
[amio_status_t](site/api/api-amio_status_t.md#amio__errors_8h_1ac629b1349893ce6659582f2140f854e1) rc = [amio_init](site/api/api-amio_init.md#amio_8h_1a9e0151f2a4efd94de22842c657b188fd)("manifest.yaml", &core);
if (rc != [AMIO_OK](site/api/api-AMIO_OK.md#amio__errors_8h_1a36457c86faa30c50b5eff175f3422ab1a4ca528f9fdc067a7fd53448b08f6330d)) {
    fprintf(stderr, "Init failed: %s\n", [amio_strerror](site/api/api-amio_strerror.md#amio__errors_8h_1a8f6d724b36dcca5d66487ace3b47a559)(rc));
    return 1;
}

[amio_dataset_handle](site/api/api-amio_dataset_handle.md#amio__types_8h_1a9687e377cd4a7e1c3582f22a9aa30d37) ds = NULL;
rc = [amio_open_dataset](site/api/api-amio_open_dataset.md#amio_8h_1acc0d48b38ac4681b35a4e4996c8efe74)(core, "dataset.yaml", [AMIO_MODE_WRITE](site/api/api-AMIO_MODE_WRITE.md#amio__types_8h_1a5ca753fc600875548fd99563d5e24713), &ds);

// Write data...
[amio_flush](site/api/api-amio_flush.md#amio_8h_1af1c229b161d14e76e3db4f27b504f1d8)(ds, 0);
[amio_close_dataset](site/api/api-amio_close_dataset.md#amio_8h_1ab1b5a9579243b1221a9f9f0adc8543c7)(ds);
[amio_finalize](site/api/api-amio_finalize.md#amio_8h_1a32bded0945b6a7097cc8c5e4047929ef)(core);

Fortran API

use [amio_mod](site/api/api-amio_mod.md#namespaceamio__mod)
type(c_ptr) :: core, dataset, io_handle
integer(c_int32_t) :: rc

rc = [amio_init](site/api/api-amio_mod::amio_init.md#interfaceamio__mod_1_1amio__init)("manifest.yaml" // c_null_char, core)
rc = [amio_open_dataset](site/api/api-amio_mod::amio_open_dataset.md#interfaceamio__mod_1_1amio__open__dataset)(core, "dataset.yaml" // c_null_char, &
                       [amio_mode_write](site/api/api-amio_mode_write.md#namespaceamio__mod_1a4885ed40c10bc44cc2dd7f976087832e), dataset)

! Use convenience subroutines for type-safe writes
call [amio_write_array](site/api/api-amio_mod::amio_write_array.md#interfaceamio__mod_1_1amio__write__array)(dataset, "temperature" // c_null_char, &
                      temp_field, io_handle, rc)

rc = [amio_flush](site/api/api-amio_mod::amio_flush.md#interfaceamio__mod_1_1amio__flush)(dataset, 0_c_int64_t)
rc = [amio_close_dataset](site/api/api-amio_mod::amio_close_dataset.md#interfaceamio__mod_1_1amio__close__dataset)(dataset)
rc = [amio_finalize](site/api/api-amio_mod::amio_finalize.md#interfaceamio__mod_1_1amio__finalize)(core)

API Reference

C API Reference — All public C entry points
Error Codes — AMIO_ERR_* enumeration and amio_strerror
Type Definitions — Data types, shapes, and handles
Export Macro — AMIO_API visibility control
Fortran Module — iso_c_binding wrapper with convenience routines

ExamplesComplete, compilable examples are provided in the examples/ directory:

C Examples (examples/c/):
example_netcdf4_write.c — Write a 3D temperature field to NetCDF-4
example_zarr_write.c — Write SST data to Zarr v3 (NCZarr mode)
example_grib2_write.c — Write geopotential height to GRIB2
Fortran Examples (examples/fortran/):
example_netcdf4_write.f90 — Write a 3D temperature field to NetCDF-4
example_zarr_write.f90 — Write SST data to Zarr v3
example_grib2_write.f90 — Write geopotential height to GRIB2
Manifest Files (examples/manifests/):
netcdf4_manifest.yaml — Configuration for NetCDF-4 backend
zarr3_manifest.yaml — Configuration for Zarr v3 backend
grib2_manifest.yaml — Configuration for GRIB2 backend

Building

mkdir build && cd build
cmake .. -DAMIO_BUILD_DOCS=ON -DAMIO_BUILD_EXAMPLES=ON
make
make docs    # Generate Doxygen HTML documentation

LicenseSee the LICENSE file in the project root.

page index¶

page `index`¶