Fortran Bindings¶
zfp 0.5.5 adds zFORp: a Fortran API providing wrappers around
the high-level C API. Wrappers for
compressed-array classes will arrive in a future release.
The zFORp implementation is based on the standard iso_c_binding
module available since Fortran 2003. The use of ptrdiff_t
in
the zfp 1.0.0 C API, however, requires the corresponding
c_ptrdiff_t
available only since Fortran 2018.
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.
Note
zfp 1.0.0 simplifies the zFORp module name from
zforp_module
to zfp
. This will likely require changing
associated use statements within existing code when updating
from prior versions of zFORp.
Furthermore, as outlined above, the zfp 1.0.0 API requires a Fortran 2018 compiler.
Types¶
- type zFORp_stream¶
- Type fields:
% object [c_ptr] :: A C pointer to the instance of
zfp_stream
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_version_tweak
Wraps
ZFP_VERSION_TWEAK
- 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_rate(stream, dims)¶
Wrapper for
zfp_stream_rate()
- Parameters:
stream [zFORp_stream,in] :: Compressed stream
dims [integer,in] :: Number of dimensions
- Return:
rate_result [real (kind=8)] :: Rate in compressed bits/scalar
- function zFORp_stream_precision(stream)¶
Wrapper for
zfp_stream_precision()
- Parameters:
stream [zFORp_stream,in] :: Compressed stream
- Return:
prec_result [integer] :: Precision in uncompressed bits/scalar
- function zFORp_stream_accuracy(stream)¶
Wrapper for
zfp_stream_accuracy()
- Parameters:
stream [zFORp_stream,in] :: Compressed stream
- Return:
tol_result [real (kind=8)] :: Absolute error tolerance
- 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:
stream [zFORp_stream,in] :: Compressed stream
field [zFORp_field,in] :: Field metadata
- Return:
max_size [integer (kind=8)] :: Maximum possible compressed size in bytes
- subroutine zFORp_stream_rewind(stream)¶
Wrapper for
zfp_stream_rewind()
- Parameters:
stream [zFORp_stream,in] :: Compressed stream
- subroutine zFORp_stream_set_bit_stream(stream, bs)¶
Wrapper for
zfp_stream_set_bit_stream()
- Parameters:
stream [zFORp_stream,in] :: Compressed stream
bs [zFORp_bitstream,in] :: Bit 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, align)¶
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
align [integer,in] :: Align blocks on words for write random access?
- Return:
rate_result [real (kind=8)] :: 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_begin(field)¶
Wrapper for
zfp_field_begin()
- Parameters:
field [zFORp_field,in] :: Field metadata
- Return:
begin_ptr [c_ptr] :: Pointer to lowest memory address spanned by field
- function zFORp_field_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_size_bytes(field)¶
Wrapper for
zfp_field_size_bytes()
- Parameters:
field [zFORp_field,in] :: Field metadata
- Return:
byte_size [integer (kind=8)] :: Number of bytes spanned by field data including gaps (if any)
- function zFORp_field_blocks(field)¶
Wrapper for
zfp_field_blocks()
- Parameters:
field [zFORp_field,in] :: Field metadata
- Return:
blocks [integer (kind=8)] :: Total number of blocks spanned by field
- 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_is_contiguous(field)¶
Wrapper for
zfp_field_is_contiguous()
- Parameters:
field [zFORp_field,in] :: Field metadata
- Return:
is_contiguous [integer] :: Indicate whether field is contiguous (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:
stream [zFORp_stream,in] :: Compressed stream
field [zFORp_field,in] :: Field metadata
- 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:
stream [zFORp_stream,in] :: Compressed stream
field [zFORp_field,in] :: Field metadata
- 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