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_stream
¶ Type fields: %
object
[c_ptr] :: A C pointer to the instance ofzfp_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_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: - 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_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
-
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: - 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