Fortran Bindings

zfp 0.5.5 adds zFORp: a Fortran API providing wrappers around the high-level C API. Wrappers for compressed arrays will arrive in a future release. The zFORp implementation is based on the standard iso_c_binding module available since Fortran 2003.

Every high-level C API function can be called from a Fortran wrapper function. C structs are wrapped as Fortran derived types, each containing a single C pointer to the C struct in memory. The wrapper functions accept and return these Fortran types, so users should never need to touch the C pointers. In addition to the high-level C API, two essential functions from the bit stream API for opening and closing bit streams are available.

See example code tests/fortran/testFortran.f (on the GitHub develop branch) for how the Fortran API is used to compress and decompress data.

Types

type zFORp_bitstream
Type fields:
  • % object [c_ptr] :: A C pointer to the instance of bitstream
type zFORp_stream
Type fields:
  • % object [c_ptr] :: A C pointer to the instance of zfp_stream
type zFORp_field
Type fields:
  • % object [c_ptr] :: A C pointer to the instance of zfp_field

Constants

Enumerations

integer zFORp_type_none
integer zFORp_type_int32
integer zFORp_type_int64
integer zFORp_type_float
integer zFORp_type_double

Enums wrapping zfp_type

integer zFORp_mode_null
integer zFORp_mode_expert
integer zFORp_mode_fixed_rate
integer zFORp_mode_fixed_precision
integer zFORp_mode_fixed_accuracy
integer zFORp_mode_reversible

Enums wrapping zfp_mode

integer zFORp_exec_serial
integer zFORp_exec_omp
integer zFORp_exec_cuda

Enums wrapping zfp_exec_policy

Non-Enum Constants

integer zFORp_version_major

Wraps ZFP_VERSION_MAJOR

integer zFORp_version_minor

Wraps ZFP_VERSION_MINOR

integer zFORp_version_patch

Wraps ZFP_VERSION_PATCH

integer zFORp_codec_version

Wraps zfp_codec_version

integer zFORp_library_version

Wraps zfp_library_version

character(len=36) zFORp_version_string

Wraps zfp_version_string

integer zFORp_min_bits

Wraps ZFP_MIN_BITS

integer zFORp_max_bits

Wraps ZFP_MAX_BITS

integer zFORp_max_prec

Wraps ZFP_MAX_PREC

integer zFORp_min_exp

Wraps ZFP_MIN_EXP

integer zFORp_header_magic

Wraps ZFP_HEADER_MAGIC

integer zFORp_header_meta

Wraps ZFP_HEADER_META

integer zFORp_header_mode

Wraps ZFP_HEADER_MODE

integer zFORp_header_full

Wraps ZFP_HEADER_FULL

integer zFORp_meta_null

Wraps ZFP_META_NULL

integer zFORp_magic_bits

Wraps ZFP_MAGIC_BITS

integer zFORp_meta_bits

Wraps ZFP_META_BITS

integer zFORp_mode_short_bits

Wraps ZFP_MODE_SHORT_BITS

integer zFORp_mode_long_bits

Wraps ZFP_MODE_LONG_BITS

integer zFORp_header_max_bits

Wraps ZFP_HEADER_MAX_BITS

integer zFORp_mode_short_max

Wraps ZFP_MODE_SHORT_MAX

Functions and Subroutines

Each of the functions included here wraps a corresponding C function. Please consult the C documentation for detailed descriptions of the functions, their parameters, and their return values.

Bit Stream

function zFORp_bitstream_stream_open(buffer, bytes)

Wrapper for stream_open()

Parameters:
  • buffer [c_ptr,in] :: Memory buffer
  • bytes [integer (kind=8),in] :: Buffer size in bytes
Return:

bs [zFORp_bitstream] :: Bit stream

subroutine zFORp_bitstream_stream_close(bs)

Wrapper for stream_close()

Parameters:bs [zFORp_bitstream,inout] :: Bit stream

Utility Functions

function zFORp_type_size(scalar_type)

Wrapper for zfp_type_size()

Parameters:scalar_type [integer,in] :: zFORp_type enum
Return:type_size [integer (kind=8)] :: Size of described zfp_type, in bytes, from C-language perspective

Compressed Stream

function zFORp_stream_open(bs)

Wrapper for zfp_stream_open()

Parameters:bs [zFORp_bitstream,in] :: Bit stream
Return:stream [zFORp_stream] :: Newly allocated compressed stream
subroutine zFORp_stream_close(stream)

Wrapper for zfp_stream_close()

Parameters:stream [zFORp_stream,inout] :: Compressed stream
function zFORp_stream_bit_stream(stream)

Wrapper for zfp_stream_bit_stream()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:bs [zFORp_bitstream] :: Bit stream
function zFORp_stream_compression_mode(stream)

Wrapper for zfp_stream_compression_mode()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:mode [integer] :: zFORp_mode enum
function zFORp_stream_mode(stream)

Wrapper for zfp_stream_mode()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:mode [integer (kind=8)] :: 64-bit encoded mode
subroutine zFORp_stream_params(stream, minbits, maxbits, maxprec, minexp)

Wrapper for zfp_stream_params()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • minbits [integer,inout] :: Minimum number of bits per block
  • maxbits [integer,inout] :: Maximum number of bits per block
  • maxprec [integer,inout] :: Maximum precision
  • minexp [integer,inout] :: Minimum bit plane number encoded
function zFORp_stream_compressed_size(stream)

Wrapper for zfp_stream_compressed_size()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:compressed_size [integer (kind=8)] :: Compressed size in bytes
function zFORp_stream_maximum_size(stream, field)

Wrapper for zfp_stream_maximum_size()

Parameters:
Return:

max_size [integer (kind=8)] :: Maximum possible compressed size in bytes

subroutine zFORp_stream_set_bit_stream(stream, bs)

Wrapper for zfp_stream_set_bit_stream()

Parameters:
subroutine zFORp_stream_rewind(stream)

Wrapper for zfp_stream_rewind()

Parameters:stream [zFORp_stream,in] :: Compressed stream

Compression Parameters

subroutine zFORp_stream_set_reversible(stream)

Wrapper for zfp_stream_set_reversible()

Parameters:stream [zFORp_stream,in] :: Compressed stream
function zFORp_stream_set_rate(stream, rate, scalar_type, dims, wra)

Wrapper for zfp_stream_set_rate()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • rate [real,in] :: Desired rate
  • scalar_type [integer,in] :: zFORp_type enum
  • dims [integer,in] :: Number of dimensions
  • wra [integer,in] :: Use write random access?
Return:

rate_result [real] :: Actual set rate in bits/scalar

function zFORp_stream_set_precision(stream, prec)

Wrapper for zfp_stream_set_precision()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • prec [integer,in] :: Desired precision
Return:

prec_result [integer] :: Actual set precision

function zFORp_stream_set_accuracy(stream, tolerance)

Wrapper for zfp_stream_set_accuracy()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • tolerance [real (kind=8),in] :: Desired error tolerance
Return:

tol_result [real (kind=8)] :: Actual set tolerance

function zFORp_stream_set_mode(stream, mode)

Wrapper for zfp_stream_set_mode()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • mode [integer (kind=8),in] :: Compact encoding of compression parameters
Return:

mode_result [integer] :: Newly set zFORp_mode enum

function zFORp_stream_set_params(stream, minbits, maxbits, maxprec, minexp)

Wrapper for zfp_stream_set_params()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • minbits [integer,in] :: Minimum number of bits per block
  • maxbits [integer,in] :: Maximum number of bits per block
  • maxprec [integer,in] :: Maximum precision
  • minexp [integer,in] :: Minimum bit plane number encoded
Return:

is_success [integer] :: Indicate whether parameters were successfully set (1) or not (0)

Execution Policy

function zFORp_stream_execution(stream)

Wrapper for zfp_stream_execution()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:execution_policy [integer] :: zFORp_exec enum indicating active execution policy
function zFORp_stream_omp_threads(stream)

Wrapper for zfp_stream_omp_threads()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:thread_count [integer] :: Number of OpenMP threads to use upon execution
function zFORp_stream_omp_chunk_size(stream)

Wrapper for zfp_stream_omp_chunk_size()

Parameters:stream [zFORp_stream,in] :: Compressed stream
Return:chunk_size_blocks [integer (kind=8)] :: Specified chunk size, in blocks
function zFORp_stream_set_execution(stream, execution_policy)

Wrapper for zfp_stream_set_execution()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • execution_policy [integer,in] :: zFORp_exec enum indicating desired execution policy
Return:

is_success [integer] :: Indicate whether execution policy was successfully set (1) or not (0)

function zFORp_stream_set_omp_threads(stream, thread_count)

Wrapper for zfp_stream_set_omp_threads()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • thread_count [integer,in] :: Desired number of OpenMP threads
Return:

is_success [integer] :: Indicate whether number of threads was successfully set (1) or not (0)

function zFORp_stream_set_omp_chunk_size(stream, chunk_size)

Wrapper for zfp_stream_set_omp_chunk_size()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • chunk_size [integer,in] :: Desired chunk size, in blocks
Return:

is_success [integer] :: Indicate whether chunk size was successfully set (1) or not (0)

Array Metadata

function zFORp_field_alloc()

Wrapper for zfp_field_alloc()

Return:field [zFORp_field] :: Newly allocated field
function zFORp_field_1d(uncompressed_ptr, scalar_type, nx)

Wrapper for zfp_field_1d()

Parameters:
  • uncompressed_ptr [c_ptr,in] :: Pointer to uncompressed data
  • scalar_type [integer,in] :: zFORp_type enum describing uncompressed scalar type
  • nx [integer,in] :: Number of array elements
Return:

field [zFORp_field] :: Newly allocated field

function zFORp_field_2d(uncompressed_ptr, scalar_type, nx, ny)

Wrapper for zfp_field_2d()

Parameters:
  • uncompressed_ptr [c_ptr,in] :: Pointer to uncompressed data
  • scalar_type [integer,in] :: zFORp_type enum describing uncompressed scalar type
  • nx [integer,in] :: Number of array elements in x dimension
  • ny [integer,in] :: Number of array elements in y dimension
Return:

field [zFORp_field] :: Newly allocated field

function zFORp_field_3d(uncompressed_ptr, scalar_type, nx, ny, nz)

Wrapper for zfp_field_3d()

Parameters:
  • uncompressed_ptr [c_ptr,in] :: Pointer to uncompressed data
  • scalar_type [integer,in] :: zFORp_type enum describing uncompressed scalar type
  • nx [integer,in] :: Number of array elements in x dimension
  • ny [integer,in] :: Number of array elements in y dimension
  • nz [integer,in] :: Number of array elements in z dimension
Return:

field [zFORp_field] :: Newly allocated field

function zFORp_field_4d(uncompressed_ptr, scalar_type, nx, ny, nz, nw)

Wrapper for zfp_field_4d()

Parameters:
  • uncompressed_ptr [c_ptr,in] :: Pointer to uncompressed data
  • scalar_type [integer,in] :: zFORp_type enum describing uncompressed scalar type
  • nx [integer,in] :: Number of array elements in x dimension
  • ny [integer,in] :: Number of array elements in y dimension
  • nz [integer,in] :: Number of array elements in z dimension
  • nw [integer,in] :: Number of array elements in w dimension
Return:

field [zFORp_field] :: Newly allocated field

subroutine zFORp_field_free(field)

Wrapper for zfp_field_free()

Parameters:field [zFORp_field,inout] :: Field metadata
function zFORp_field_pointer(field)

Wrapper for zfp_field_pointer()

Parameters:field [zFORp_field,in] :: Field metadata
Return:arr_ptr [c_ptr] :: Pointer to raw (uncompressed/decompressed) array
function zFORp_field_scalar_type(field)

Wrapper for zfp_field_type()

Parameters:field [zFORp_field,in] :: Field metadata
Return:scalar_type [integer] :: zFORp_type enum describing uncompressed scalar type
function zFORp_field_precision(field)

Wrapper for zfp_field_precision()

Parameters:field [zFORp_field,in] :: Field metadata
Return:prec [integer] :: Scalar type precision in number of bits
function zFORp_field_dimensionality(field)

Wrapper for zfp_field_dimensionality()

Parameters:field [zFORp_field,in] :: Field metadata
Return:dims [integer] :: Dimensionality of array
function zFORp_field_size(field, size_arr)

Wrapper for zfp_field_size()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • size_arr [integer,dimension(4),target,inout] :: Integer array to write field dimensions into
Return:

total_size [integer (kind=8)] :: Total number of array elements

function zFORp_field_stride(field, stride_arr)

Wrapper for zfp_field_stride()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • stride_arr [integer,dimension(4),target,inout] :: Integer array to write strides into
Return:

is_strided [integer] :: Indicate whether field is strided (1) or not (0)

function zFORp_field_metadata(field)

Wrapper for zfp_field_metadata()

Parameters:field [zFORp_field,in] :: Field metadata
Return:encoded_metadata [integer (kind=8)] :: Compact encoding of metadata
subroutine zFORp_field_set_pointer(field, arr_ptr)

Wrapper for zfp_field_set_pointer()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • arr_ptr [c_ptr,in] :: Pointer to beginning of uncompressed array
function zFORp_field_set_type(field, scalar_type)

Wrapper for zfp_field_set_type()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • scalar_type [integer] :: zFORp_type enum indicating desired scalar type
Return:

type_result [integer] :: zFORp_type enum indicating actual scalar type

subroutine zFORp_field_set_size_1d(field, nx)

Wrapper for zfp_field_set_size_1d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • nx [integer,in] :: Number of array elements
subroutine zFORp_field_set_size_2d(field, nx, ny)

Wrapper for zfp_field_set_size_2d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • nx [integer,in] :: Number of array elements in x dimension
  • ny [integer,in] :: Number of array elements in y dimension
subroutine zFORp_field_set_size_3d(field, nx, ny, nz)

Wrapper for zfp_field_set_size_3d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • nx [integer,in] :: Number of array elements in x dimension
  • ny [integer,in] :: Number of array elements in y dimension
  • nz [integer,in] :: Number of array elements in z dimension
subroutine zFORp_field_set_size_4d(field, nx, ny, nz, nw)

Wrapper for zfp_field_set_size_4d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • nx [integer,in] :: Number of array elements in x dimension
  • ny [integer,in] :: Number of array elements in y dimension
  • nz [integer,in] :: Number of array elements in z dimension
  • nw [integer,in] :: Number of array elements in w dimension
subroutine zFORp_field_set_stride_1d(field, sx)

Wrapper for zfp_field_set_stride_1d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • sx [integer,in] :: Stride in number of scalars
subroutine zFORp_field_set_stride_2d(field, sx, sy)

Wrapper for zfp_field_set_stride_2d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • sx [integer,in] :: Stride in x dimension
  • sy [integer,in] :: Stride in y dimension
subroutine zFORp_field_set_stride_3d(field, sx, sy, sz)

Wrapper for zfp_field_set_stride_3d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • sx [integer,in] :: Stride in x dimension
  • sy [integer,in] :: Stride in y dimension
  • sz [integer,in] :: Stride in z dimension
subroutine zFORp_field_set_stride_4d(field, sx, sy, sz, sw)

Wrapper for zfp_field_set_stride_4d()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • sx [integer,in] :: Stride in x dimension
  • sy [integer,in] :: Stride in y dimension
  • sz [integer,in] :: Stride in z dimension
  • sw [integer,in] :: Stride in w dimension
function zFORp_field_set_metadata(field, encoded_metadata)

Wrapper for zfp_field_set_metadata()

Parameters:
  • field [zFORp_field,in] :: Field metadata
  • encoded_metadata [integer (kind=8),in] :: Compact encoding of metadata
Return:

is_success [integer] :: Indicate whether metadata was successfully set (1) or not (0)

Compression and Decompression

function zFORp_compress(stream, field)

Wrapper for zfp_compress()

Parameters:
Return:

bitstream_offset_bytes [integer (kind=8)] :: Bit stream offset after compression, in bytes, or zero on failure

function zFORp_decompress(stream, field)

Wrapper for zfp_decompress()

Parameters:
Return:

bitstream_offset_bytes [integer (kind=8)] :: Bit stream offset after decompression, in bytes, or zero on failure

function zFORp_write_header(stream, field, mask)

Wrapper for zfp_write_header()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • field [zFORp_field,in] :: Field metadata
  • mask [integer,in] :: Bit mask indicating which parts of header to write
Return:

num_bits_written [integer (kind=8)] :: Number of header bits written or zero on failure

function zFORp_read_header(stream, field, mask)

Wrapper for zfp_read_header()

Parameters:
  • stream [zFORp_stream,in] :: Compressed stream
  • field [zFORp_field,in] :: Field metadata
  • mask [integer,in] :: Bit mask indicating which parts of header to read
Return:

num_bits_read [integer (kind=8)] :: Number of header bits read or zero on failure