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:	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