#include <lorenzo_stage.h>

Inheritance diagram for fz::LorenzoStage< T >:

Public Member Functions
	LorenzoStage (uint32_t block_size, bool centering=false, uint8_t order=1)

void	setInverse (bool inv) override

void	setDims (const std::array< size_t, 3 > &dims) override

void	setBlockSize (uint32_t n)

void	setCentering (bool enable)

void	setOrder (uint8_t k)

void	execute (fz::stream_t stream, MemoryPool pool, const std::vector< void > &inputs, const std::vector< void * > &outputs, const std::vector< size_t > &sizes) override

std::string	getName () const override

size_t	getNumInputs () const override
	Centering adds a `"means"` port: a second output forward, a second input inverse.

std::vector< std::string >	getOutputNames () const override

std::vector< size_t >	estimateOutputSizes (const std::vector< size_t > &input_sizes) const override

std::unordered_map< std::string, size_t >	getActualOutputSizesByName () const override

size_t	getActualOutputSize (int index) const override

uint16_t	getStageTypeId () const override

uint8_t	getOutputDataType (size_t) const override

uint8_t	getInputDataType (size_t) const override

size_t	serializeHeader (size_t, uint8_t *buf, size_t max_size) const override

void	deserializeHeader (const uint8_t *buf, size_t size) override

size_t	getMaxHeaderSize (size_t) const override

Public Member Functions inherited from fz::Stage
virtual size_t	getRequiredInputAlignment () const

int	getOutputIndex (const std::string &name) const

virtual void	saveState ()

virtual std::vector< std::string >	getRunNotes () const

virtual void	onFinalize (size_t, MemoryPool *)

virtual size_t	estimateDeviceFootprintBytes (size_t) const

virtual size_t	estimatePinnedFootprintBytes (size_t) const

virtual void	postStreamSync (fz::stream_t stream)

virtual bool	isGraphCompatible () const

virtual size_t	estimateScratchBytes (const std::vector< size_t > &input_sizes) const

Additional Inherited Members
Static Public Member Functions inherited from fz::Stage
static constexpr bool	isSupportedOnBackend ()

Detailed Description

template<typename T>
class fz::LorenzoStage< T >

Plain integer Lorenzo predictor (1-D, 2-D, 3-D). Lossless.

Forward (compression): compute per-element delta from its neighbor(s). Inverse (decompression): prefix sum to reconstruct original values.

Template Parameters

T	Signed integer element type: int8_t, int16_t, int32_t, int64_t.

Constructor & Destructor Documentation

◆ LorenzoStage()

template<typename T >

fz::LorenzoStage< T >::LorenzoStage	(	uint32_t	block_size,
		bool	centering = `false`,
		uint8_t	order = `1`
	)

inlineexplicit

Construct with the block-mode parameters already set.

Prefer this over setBlockSize/setCentering when enabling centering: Pipeline::addStage() captures the stage's port count at add-time, and centering adds a "means" port, so it must be known before the stage joins the DAG. (Same reason setDims() must precede addStage().)

Member Function Documentation

◆ setInverse()

template<typename T >

void fz::LorenzoStage< T >::setInverse ( bool inverse )

inlineoverridevirtual

Switch between forward (compression) and inverse (decompression) mode. Affects getNumInputs()/getNumOutputs() for stages with asymmetric port counts.

Reimplemented from fz::Stage.

◆ setDims()

template<typename T >

void fz::LorenzoStage< T >::setDims ( const std::array< size_t, 3 > & dims )

inlineoverridevirtual

Called once by Pipeline::finalize() so stages can react to the dataset dimensions set via Pipeline::setDims() after construction.

Parameters

dims	{x, y, z} extents (z==1 → 2-D; y==z==1 → 1-D)

Reimplemented from fz::Stage.

◆ setBlockSize()

template<typename T >

void fz::LorenzoStage< T >::setBlockSize ( uint32_t n )

inline

Set an explicit 1-D block-local reset period (cuSZp-style).

n == 0 (default): keep the current behavior — 1-D delta resets every launch block (256), 2-D/3-D use the N-D inclusion-exclusion delta. n > 0: force the 1-D path over the flattened array, restarting the prediction chain (prev = 0) every n elements, independent of the launch configuration and of dims_. cuSZp uses n = 32.

Must be in [1, 1024] (CUDA block limit; the inverse scans one segment per CUDA block of n threads).

◆ setCentering()

template<typename T >

void fz::LorenzoStage< T >::setCentering ( bool enable )

inline

Enable per-block mean centering (FSZ-style adaptive centering).

Subtracts the block's integer mean mu from the values before predicting. Because the k-th order difference of a constant is zero (delta(q - mu) == delta(q)), this changes only the first residual of each block — the one element with no predecessor, which would otherwise be a raw value. On data with a large constant offset (pressure near 1000 hPa, temperature in Kelvin) that raw value dominates the block's magnitude and inflates a downstream fixed-rate coder's bit width for the whole block; centering drops it to q_0 - mu.

Requires block mode (setBlockSize(n) with n > 0) — there is no per-block mean without blocks. Adds a second output port, "means" (one T per block), which the inverse consumes as its second input.

Note: The sizeof(T) bytes per block of mu are only worth paying when the block is long: at block_size = 32 the overhead is 8/32 = 0.25 bits per element to fix 1 residual in 32, which generally loses. Pair with the large block sizes that cross-block prediction wants (256+), where the overhead is under 0.03 bits per element.

Warning: Must be set before Pipeline::addStage() captures the port count — pass it to the LorenzoStage(block_size, centering) constructor rather than calling this on an already-added stage.

◆ setOrder()

template<typename T >

void fz::LorenzoStage< T >::setOrder ( uint8_t k )

inline

Prediction order: 1 (first difference, the default) or 2 (second difference, FSZ's LZ2).

Second order predicts each element from the trend of the two before it rather than from the previous value alone, so it annihilates a linear ramp exactly where first order leaves a constant non-zero residual. That makes it the right choice on fields with a smooth gradient (geopotential height, temperature profiles, pressure gradients) and the wrong choice on piecewise-constant fields, where it roughly doubles the residual.

Requires block mode (setBlockSize(n) with n > 0): the second difference is taken within a reset segment, and the N-D inclusion-exclusion path has no second-order analogue here. Costs one extra element of raw seed per block (both e_0 and e_1 lack full predecessors), so it pairs with long blocks and with setCentering().

◆ execute()

template<typename T >

void fz::LorenzoStage< T >::execute	(	fz::stream_t	stream,
		MemoryPool *	pool,
		const std::vector< void * > &	inputs,
		const std::vector< void * > &	outputs,
		const std::vector< size_t > &	sizes
	)

overridevirtual

Execute the stage. Inputs, outputs, and sizes are device pointers/bytes.

Stages may call cudaStreamSynchronize(stream) or issue blocking D2H copies when the algorithm requires it (e.g. Huffman histogram readback for codebook construction, ANS renormalization tables). Such stages must return false from isGraphCompatible() and must document the sync points.

Note: the DAG dispatches sibling nodes (same topological level) via a sequential CPU loop, each enqueuing to its own stream. A sync inside execute() blocks the CPU from dispatching subsequent siblings until the synced stream is idle — this delays parallel branches in wide DAGs. In a linear pipeline there are no siblings and no extra cost.

Implements fz::Stage.

◆ getName()

template<typename T >

std::string fz::LorenzoStage< T >::getName ( ) const

inlineoverridevirtual

Human-readable name used in error messages and debug output.

Implements fz::Stage.

◆ getOutputNames()

template<typename T >

std::vector< std::string > fz::LorenzoStage< T >::getOutputNames ( ) const

inlineoverridevirtual

Output port names in order. Default: single port named "output". Multi-output stages (e.g. Lorenzo: "codes", "outliers") override this.

Reimplemented from fz::Stage.

◆ estimateOutputSizes()

template<typename T >

std::vector< size_t > fz::LorenzoStage< T >::estimateOutputSizes ( const std::vector< size_t > & input_sizes ) const

inlineoverridevirtual

Estimate output buffer sizes given input sizes. Used for buffer allocation planning in PREALLOCATE mode — must be a safe upper bound; under-estimation causes buffer overruns.

Implements fz::Stage.

◆ getActualOutputSizesByName()

template<typename T >

std::unordered_map< std::string, size_t > fz::LorenzoStage< T >::getActualOutputSizesByName ( ) const

inlineoverridevirtual

Actual output sizes after execute(), keyed by output port name.

Implements fz::Stage.

◆ getActualOutputSize()

template<typename T >

size_t fz::LorenzoStage< T >::getActualOutputSize ( int index ) const

inlineoverridevirtual

Actual size of a single output by index after execute(). Avoids constructing the map for the common single-output case. Default delegates to getActualOutputSizesByName(); override to return directly from an internal field.

Reimplemented from fz::Stage.

◆ getStageTypeId()

template<typename T >

uint16_t fz::LorenzoStage< T >::getStageTypeId ( ) const

inlineoverridevirtual

Stage type identifier written into the FZM file header.

Implements fz::Stage.

◆ getOutputDataType()

template<typename T >

uint8_t fz::LorenzoStage< T >::getOutputDataType ( size_t output_index ) const

inlineoverridevirtual

DataType enum of the given output port.

Implements fz::Stage.

◆ getInputDataType()

template<typename T >

uint8_t fz::LorenzoStage< T >::getInputDataType ( size_t ) const

inlineoverridevirtual

Expected DataType of the given input port.

Used by Pipeline::finalize() to detect type mismatches between connected stages before any execution. Return DataType::UNKNOWN to opt out of checking — byte-transparent stages (Bitshuffle, RZE, RRE) and mock stages must return UNKNOWN; finalize() skips any connection where either side is UNKNOWN.

Reimplemented from fz::Stage.

◆ serializeHeader()

template<typename T >

size_t fz::LorenzoStage< T >::serializeHeader	(	size_t	output_index,
		uint8_t *	header_buffer,
		size_t	max_size
	)		const

inlineoverridevirtual

Serialize stage config into header_buffer (max 128 bytes) for the FZM file. Return the number of bytes written, or 0 if the stage has no config.

Reimplemented from fz::Stage.

◆ deserializeHeader()

template<typename T >

void fz::LorenzoStage< T >::deserializeHeader	(	const uint8_t *	header_buffer,
		size_t	size
	)

inlineoverridevirtual

Restore stage config from header_buffer during decompression.

Reimplemented from fz::Stage.

◆ getMaxHeaderSize()

template<typename T >

size_t fz::LorenzoStage< T >::getMaxHeaderSize ( size_t output_index ) const

inlineoverridevirtual

Maximum bytes this stage writes into its per-output FZM header slot.

Reimplemented from fz::Stage.

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ LorenzoStage()

Member Function Documentation

◆ setInverse()

◆ setDims()

◆ setBlockSize()

◆ setCentering()

◆ setOrder()

◆ execute()

◆ getName()

◆ getOutputNames()

◆ estimateOutputSizes()

◆ getActualOutputSizesByName()

◆ getActualOutputSize()

◆ getStageTypeId()

◆ getOutputDataType()

◆ getInputDataType()

◆ serializeHeader()

◆ deserializeHeader()

◆ getMaxHeaderSize()