Classes
struct	BvpData
	Internal data structure managing buffers and parameters for bit-vector propagation. More...

Enumerations
enum class	SparseANFBlock { Y , J , Z , L }
	Represents the different ANF blocks. More...

Functions
template<ControlFlowMode CFM>
void	checkBVPInput (const double *basepoint)
	Verifies input data consistency for bit-vector propagation.

void	resetInput (std::span< uint * > &compressedRowStorage)
	Resets all entries in the compressed row storage pointer array to nullptr.

template<BitPatternPropagationDirection BPPD>
void	resetOldSeed (BvpData< BPPD > &data, size_t dim2)
	Sets all seed matrix entries to zero for reuse in the next strip-mined batch.

template<BitPatternPropagationDirection BPPD>
void	prepareSeedMatrix (size_t stripIdx, BvpData< BPPD > &data)
	Builds a strip-mined partition of the seed matrix for a given batch.

template<BitPatternPropagationDirection BPPD>
void	setSeed (BvpData< BPPD > &data, size_t idx, size_t currentStripWordIdx)
	Sets a single bit in the seed matrix corresponding to a specific variable index.

template<BitPatternPropagationDirection BPPD>
void	createSeed (BvpData< BPPD > &data, size_t stripIdx, size_t end)
	Creates a seed matrix segment by invoking setSeed() for each variable in the strip.

void	extract (size_t wordIdx, size_t stripIdx, size_t currentStripWordIdx, BvpData< BitPatternPropagationDirection::Forward > &data, std::span< uint * > &compressedRowStorage)
	Extracts the sparsity pattern for one dependent variable (row) in forward bit-vector propagation mode.

void	extract (size_t wordIdx, size_t stripIdx, BvpData< BitPatternPropagationDirection::Reverse > &data, std::span< uint * > &compressedRowStorage)
	Extracts the sparsity pattern for one dependent variable (row) in reverse bit-vector propagation mode.

template<BitPatternPropagationDirection BPPD>
void	extractCompressedRowStorage (int stripIdx, std::span< uint * > &compressedRowStorage, BvpData< BPPD > &data)
	Converts Jacobian bit patterns to compressed row storage (CRS) format for one strip.

template<BitPatternPropagationDirection BPPD, ControlFlowMode CFM>
void	prepareADCalls (short tapeId, const double *basepoint, BvpData< BPPD > &data)
	Prepares reverse call using zos_forward.

template<BitPatternPropagationDirection BPPD, ControlFlowMode CFM>
void	ADCalls (short tapeId, const double *basepoint, BvpData< BPPD > &data)
	Executes the ADOL-C internal bit-vector propagation calls (forward or reverse).

template<ControlFlowMode CFM, BitPatternPropagationDirection BPPD>
int	bitVectorPropagation (short tapeId, int depen, int indep, const double basepoint, std::span< uint > &compressedRowStorage)
	Main internal implementation for bit-vector propagation.

template<SparseMethod SM, CompressionMode CM, ControlFlowMode CFM, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto>
int	buildJacPatternAndSeed (short tag, int depen, int indep, const double *basepoint)
	Allocates and computes pattern of jacobian and computes a seed to compute a sparse Jacobian.

template<PiecewiseLinear >
int	buildJacPatternAndSeed (short tag, int depen, int indep, int numSwitches, const double *basepoint)
	Build pattern and seed data for the piecewise-linear sparse Jacobian.

template<CompressionMode CM, MemoryHandler MH>
void	recover (const ValueTape &tape, SparseMatrix &sparseJac)
	Passes args to jacobian-recover method based on the template-args.

template<MemoryHandler MH>
void	recover (const ValueTape &tape, SparseANF &sparseANF)
	Passes args to ANF recovery methods based on the template args.

template<CompressionMode CM, MemoryHandler MH>
int	computeSparseJac (short tag, int depen, int indep, const double *basepoint, SparseMatrix &sparseJac)
	Compute sparse Jacobian using precomputed seed matrix and recovery information.

template<MemoryHandler MH>
int	computeSparseJac (short tag, int depen, int indep, int numSwitches, const double *basepoint, SparseANF &sparseANF)
	Recover the piecewise-linear sparse Jacobian into ANF blocks.

template<ControlFlowMode CFM, RecoveryMethod RCM>
int	buildHessPatternAndSeed (short tag, int indep, const double basepoint, int nnz)
	Build Hessian sparsity pattern and generate ColPack seed for recovery.

template<RecoveryMethod RCM>
int	computeSparseHess (short tag, int indep, const double basepoint, int nnz, unsigned int rind, unsigned int cind, double **values)
	Compute sparse Hessian using precomputed seed/recovery info.

SparseANFBlock	classifySparseANFBlock (CoordinateFormatTripled::Coordinates coords, int depen, int indep)

Enumeration Type Documentation

◆ SparseANFBlock

enum class ADOLC::Sparse::detail::SparseANFBlock

strong

Represents the different ANF blocks.

Enumerator
Y
J
Z
L

Function Documentation

◆ ADCalls()

template<BitPatternPropagationDirection BPPD, ControlFlowMode CFM>

void ADOLC::Sparse::detail::ADCalls	(	short	tapeId,
		const double *	basepoint,
		BvpData< BPPD > &	data
	)

Executes the ADOL-C internal bit-vector propagation calls (forward or reverse).

Template Parameters

BPPD	Bit pattern propagation direction.
CFM	Control flow mode.

Parameters

tapeId	ADOL-C tape identifier.
basepoint	Pointer to independent variable values (required for forward tight).
data	Bit-vector propagation state container.

◆ bitVectorPropagation()

template<ControlFlowMode CFM, BitPatternPropagationDirection BPPD>

int ADOLC::Sparse::detail::bitVectorPropagation	(	short	tapeId,
		int	depen,
		int	indep,
		const double *	basepoint,
		std::span< uint * > &	compressedRowStorage
	)

Main internal implementation for bit-vector propagation.

Iteratively builds and propagates seed matrices, performs ADOL-C bit-vector propagation calls, and extracts the sparsity pattern into CRS format.

Template Parameters

CFM	Control flow mode.
BPPD	Bit pattern propagation direction.

Parameters

tapeId	ADOL-C tape identifier.
depen	Number of dependent variables.
indep	Number of independent variables.
basepoint	Pointer to basepoint values.
compressedRowStorage	Output CRS sparsity pattern.

Returns: Return code from ADOL-C driver.

◆ buildHessPatternAndSeed()

template<ControlFlowMode CFM, RecoveryMethod RCM>

int ADOLC::Sparse::detail::buildHessPatternAndSeed	(	short	tag,
		int	indep,
		const double *	basepoint,
		int *	nnz
	)

Build Hessian sparsity pattern and generate ColPack seed for recovery.

This routine computes the sparsity pattern of the Hessian and constructs a seed matrix for Hessian recovery using ColPack. It stores pattern and seed/recovery related data inside the tape's sHInfos() structure for reuse by subsequent numerical recovery calls.

Template Parameters

CFM	ControlFlowMode used when computing the Hessian pattern: ControlFlowMode::Safe : conservative control-flow handling ControlFlowMode::Tight : evaluate control-flow at `basepoint`
RCM	RecoveryMethod selecting Hessian recovery strategy: RecoveryMethod::Indirect : indirect (via two-phase recover) RecoveryMethod::Direct : direct recovery (star pattern)

Parameters

	tag	ADOL-C tape identifier.
	indep	Number of independent variables (dimension of Hessian).
	basepoint	Pointer to an array of length `indep` with the point at which control-flow (if any) should be tested. May be nullptr if not required by the chosen CFM (Safe vs Tight).
[out]	nnz	Pointer to an integer where the number of nonzero Hessian entries will be stored.

Returns

>= 0 : Success value forwarded from hess_pat
< 0 : Error code forwarded from hess_pat.

Note

The computed sparsity pattern (HP) is stored in tape.sHInfos().HP_.
The generated seed matrix is stored (via ColPack) and its contents are copied into tape.sHInfos().Xppp_. The ColPack-owned seed memory will be freed when the ColPack graph object (g_) is destroyed.
Additional workspace arrays (Hcomp_, Xppp_, Yppp_, Zppp_, Upp_) are allocated on the tape for use by the numeric recovery routine.

◆ buildJacPatternAndSeed() [1/2]

template<SparseMethod SM, CompressionMode CM, ControlFlowMode CFM, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto>

int ADOLC::Sparse::detail::buildJacPatternAndSeed	(	short	tag,
		int	depen,
		int	indep,
		const double *	basepoint
	)

Allocates and computes pattern of jacobian and computes a seed to compute a sparse Jacobian.

This routine computes the Jacobian sparsity pattern (via jac_pat) and then uses ColPack to generate a seed matrix (graph coloring) suitable for compressed Jacobian recovery. It stores results inside the tape's sJInfos() structure so subsequent compute_sparse_jac/repeat calls can reuse the seed and recovery objects.

Template Parameters

SM	Sparsity-detection method used by `jac_pat`: `SparseMethod::IndexDomains` : index domain propagation `SparseMethod::BitPattern` : bit-vector propagation
CM	Compression orientation for ColPack seed generation: `CompressionMode::Row` : row-compression (recover by rows) `CompressionMode::Column` : column-compression (recover by columns)
CFM	Control-flow mode used when computing the sparsity pattern.
BPPD	Bit pattern propagation direction when `SM == BitPattern`. When `BitPatternPropagationDirection::Auto` a runtime heuristic is used.

Parameters

tag	ADOL-C tape identifier.
depen	Number of dependent (output) variables (rows of Jacobian).
indep	Number of independent (input) variables (columns of Jacobian).
basepoint	Pointer to an array of length `indep` with the basepoint values. May be `nullptr` if control-flow mode does not require a basepoint.

Returns

>= 0 : Number of seed columns (when CM==Row) or seed rows (when CM==Column) produced by ColPack (i.e., the compressed dimension).
< 0 : Error code forwarded from jac_pat or other internal failures.

Note

The function allocates and stores the Compressed Row Storage (CRS) pattern inside tape.sJInfos().JP_. Ownership of those row buffers is transferred to the tape (they will be freed/managed by the tape lifecycle).
After success, tape.sJInfos().g_ and tape.sJInfos().jr1d_ are created and kept in the tape for later use by compute_sparse_jac.

◆ buildJacPatternAndSeed() [2/2]

template<PiecewiseLinear >

int ADOLC::Sparse::detail::buildJacPatternAndSeed	(	short	tag,
		int	depen,
		int	indep,
		int	numSwitches,
		const double *	basepoint
	)

Build pattern and seed data for the piecewise-linear sparse Jacobian.

This specializes the generic sparse Jacobian setup for abs-smooth functions. It computes the sparsity pattern of the extended Jacobian via indopro_forward_absnormal(), then generates a row-compression seed for the [y ; z] by [x ; |z|] matrix. This driver currently supports only row-compression because the compressed Jacobian is computed with fov_pl_reverse().

◆ checkBVPInput()

template<ControlFlowMode CFM>

void ADOLC::Sparse::detail::checkBVPInput ( const double * basepoint )

Verifies input data consistency for bit-vector propagation.

Template Parameters

CFM	Control flow mode (Safe, Tight, etc.).

Parameters

basepoint Pointer to the independent variable values (may be null in Safe mode).

◆ classifySparseANFBlock()

SparseANFBlock ADOLC::Sparse::detail::classifySparseANFBlock	(	CoordinateFormatTripled::Coordinates	coords,
		int	depen,
		int	indep
	)

inline

◆ computeSparseHess()

template<RecoveryMethod RCM>

int ADOLC::Sparse::detail::computeSparseHess	(	short	tag,
		int	indep,
		const double *	basepoint,
		int *	nnz,
		unsigned int **	rind,
		unsigned int **	cind,
		double **	values
	)

Compute sparse Hessian using precomputed seed/recovery info.

Executes compressed forward/reverse evaluations followed by ColPack recovery to produce the Hessian in coordinate (rind, cind, values) form. Supports both indirect and direct recovery methods (template parameter RCM).

Template Parameters

RCM	RecoveryMethod controlling the chosen ColPack recovery routine.

Parameters

	tag	ADOL-C tape identifier.
	indep	Number of independent variables (dimension of Hessian).
	basepoint	Pointer to an array of length `indep` with evaluation point.
	nnz	Expected number of nonzeros (must equal the value computed and stored by `buildHessPatternAndSeed`). If not, the function returns error `-3`.
[out]	rind	Pointer-to-pointer that will receive the row indices of the coordinate-format Hessian (allocated or user-provided).
[out]	cind	Pointer-to-pointer that will receive the column indices.
[out]	values	Pointer-to-pointer that will receive the numerical values.

Returns

>= 0 : Success (driver-specific non-negative codes).
< 0 : Error code from internal ADOL-C calls.

Precondition

buildHessPatternAndSeed<...> must have been called previously to populate tape.sHInfos() (seed, graph g_, hr_, workspace arrays).

Note

The routine uses hov_wk_forward + hos_ov_reverse to compute compressed Hessian blocks and then invokes ColPack's recover routines. Both usermem (if rind/cind/values are non-null) and unmanaged variants are supported.
On success, caller is responsible for freeing memory returned by the unmanaged recovery functions (if used).

◆ computeSparseJac() [1/2]

template<CompressionMode CM, MemoryHandler MH>

int ADOLC::Sparse::detail::computeSparseJac	(	short	tag,
		int	depen,
		int	indep,
		const double *	basepoint,
		SparseMatrix &	sparseJac
	)

Compute sparse Jacobian using precomputed seed matrix and recovery information.

This routine performs the actual compressed Jacobian computation using the seed matrix and graph/recovery structures stored in the tape's sJInfos(). It supports both row- and column-oriented compression strategies and writes the recovered coordinate-format entries into a SparseMatrix.

Template Parameters

CM	Compression orientation (Row or Column) chosen when the seed was generated.
MH	Selects whether `sparseJac` may be resized automatically or must already contain exactly `nnzIn_` entry slots.

Parameters

	tag	ADOL-C tape identifier.
	depen	Number of dependent variables (rows).
	indep	Number of independent variables (columns).
	basepoint	Pointer to basepoint values (length `indep`) used for evaluation in tight control-flow or other drivers.
[in,out]	sparseJac	Sparse matrix receiving recovered coordinate-format entries.

Returns

0 on success (or driver-specific non-negative codes),
negative error code on failure (propagated from internal ADOL-C calls).

Precondition: t already equal the number of nonzeros stored in tape.sJInfos().nnzIn_; otherwise the function returns -3.

Postcondition

On success, sparseJac contains one entry per recovered Jacobian nonzero.

Note

repeat and MemoryHandler are orthogonal: repeat controls whether pattern/seed metadata is rebuilt or reused, while MemoryHandler controls only whether sparseJac is resized automatically.
The function allocates intermediate storage B_ and y_ inside the tape; these are freed with the tape lifecycle or overwritten on subsequent calls.
For CompressionMode::Row, a forward evaluation zos_forward is used to compute y_ followed by fov_reverse to obtain B_. For CompressionMode::Column, fov_forward is used to obtain B_.

◆ computeSparseJac() [2/2]

template<MemoryHandler MH>

int ADOLC::Sparse::detail::computeSparseJac	(	short	tag,
		int	depen,
		int	indep,
		int	numSwitches,
		const double *	basepoint,
		SparseANF &	sparseANF
	)

Recover the piecewise-linear sparse Jacobian into ANF blocks.

This variant partitions the recovered extended Jacobian into the four abs-normal blocks Y, J, Z, and L. Entries inside each block use block-local coordinates, while cy and cz are filled with the dense constants derived from the same primal y and z evaluation used for recovery.

◆ createSeed()

template<BitPatternPropagationDirection BPPD>

void ADOLC::Sparse::detail::createSeed	(	BvpData< BPPD > &	data,
		size_t	stripIdx,
		size_t	end
	)

Creates a seed matrix segment by invoking setSeed() for each variable in the strip.

Template Parameters

BPPD	Bit pattern propagation direction.

Parameters

data	Bit-vector propagation data container.
stripIdx	Index of the strip-mined batch.
end	End index (exclusive) of the variable range for this batch.

◆ extract() [1/2]

void ADOLC::Sparse::detail::extract	(	size_t	wordIdx,
		size_t	stripIdx,
		BvpData< BitPatternPropagationDirection::Reverse > &	data,
		std::span< uint * > &	compressedRowStorage
	)

Extracts the sparsity pattern for one dependent variable (row) in reverse bit-vector propagation mode.

This function builds the corresponding CRS row for each output, using the flags stored in indepWordHasNonzero_.

Each bit set in the propagated Jacobian pattern indicates a dependency of the current dependent variable on an independent variable.

Parameters

	wordIdx	Index of the dependent variable (row in the Jacobian).
	stripIdx	Index of the current strip-mined batch.
	data	Bit-vector propagation data container (Reverse mode).
[in,out]	compressedRowStorage	Span of pointers to CRS rows (updated in-place).

Note

Memory for each row is reallocated every time the strip is processed.
The caller is responsible for freeing the allocated CRS memory.

◆ extract() [2/2]

void ADOLC::Sparse::detail::extract	(	size_t	wordIdx,
		size_t	stripIdx,
		size_t	currentStripWordIdx,
		BvpData< BitPatternPropagationDirection::Forward > &	data,
		std::span< uint * > &	compressedRowStorage
	)

Extracts the sparsity pattern for one dependent variable (row) in forward bit-vector propagation mode.

This routine constructs or extends a row in compressed row storage format based on the current bit pattern flags in indepWordHasNonzero_.

Each bit set in the propagated Jacobian pattern indicates a dependency of the current dependent variable on an independent variable.

Parameters

	wordIdx	Index of the dependent variable (row in the Jacobian).
	stripIdx	Index of the current strip-mined batch.
	currentStripWordIdx	Starting global index of the strip.
	data	Bit-vector propagation data container (Forward mode).
[in,out]	compressedRowStorage	Span of pointers to CRS rows (updated in-place).

Note

The function merges new nonzeros with previously existing entries when processing subsequent strips.
Memory for each row is reallocated as needed and must be freed by the caller.

◆ extractCompressedRowStorage()

template<BitPatternPropagationDirection BPPD>

void ADOLC::Sparse::detail::extractCompressedRowStorage	(	int	stripIdx,
		std::span< uint * > &	compressedRowStorage,
		BvpData< BPPD > &	data
	)

Converts Jacobian bit patterns to compressed row storage (CRS) format for one strip.

Template Parameters

BPPD	Bit pattern propagation direction.

Parameters

stripIdx	Index of the strip-mined batch.
compressedRowStorage	Output CRS array (span over row pointers).
data	Bit-vector propagation data container.

◆ prepareADCalls()

template<BitPatternPropagationDirection BPPD, ControlFlowMode CFM>

void ADOLC::Sparse::detail::prepareADCalls	(	short	tapeId,
		const double *	basepoint,
		BvpData< BPPD > &	data
	)

Prepares reverse call using zos_forward.

Template Parameters

BPPD	Bit pattern propagation direction.
CFM	Control flow mode.

Parameters

tapeId	ADOL-C tape identifier.
basepoint	Pointer to basepoint values (used in tight control-flow mode).
data	Bit-vector propagation data container.

◆ prepareSeedMatrix()

template<BitPatternPropagationDirection BPPD>

void ADOLC::Sparse::detail::prepareSeedMatrix	(	size_t	stripIdx,
		BvpData< BPPD > &	data
	)

Builds a strip-mined partition of the seed matrix for a given batch.

Template Parameters

BPPD	Bit pattern propagation direction.

Parameters

stripIdx	Current strip-mined batch index.
data	Bit-vector propagation state data.

◆ recover() [1/2]

template<MemoryHandler MH>

void ADOLC::Sparse::detail::recover	(	const ValueTape &	tape,
		SparseANF &	sparseANF
	)

Passes args to ANF recovery methods based on the template args.

◆ recover() [2/2]

template<CompressionMode CM, MemoryHandler MH>

void ADOLC::Sparse::detail::recover	(	const ValueTape &	tape,
		SparseMatrix &	sparseJac
	)

Passes args to jacobian-recover method based on the template-args.

◆ resetInput()

void ADOLC::Sparse::detail::resetInput ( std::span< uint * > & compressedRowStorage )

inline

Resets all entries in the compressed row storage pointer array to nullptr.

Parameters

compressedRowStorage Span over the row storage pointer array to be reset.

◆ resetOldSeed()

template<BitPatternPropagationDirection BPPD>

void ADOLC::Sparse::detail::resetOldSeed	(	BvpData< BPPD > &	data,
		size_t	dim2
	)

Sets all seed matrix entries to zero for reuse in the next strip-mined batch.

Template Parameters

BPPD	Bit pattern propagation direction.

Parameters

data	Bit-vector propagation state data.
dim2	Inner dimension to clear (depends on direction).

◆ setSeed()

template<BitPatternPropagationDirection BPPD>

void ADOLC::Sparse::detail::setSeed	(	BvpData< BPPD > &	data,
		size_t	idx,
		size_t	currentStripWordIdx
	)

Sets a single bit in the seed matrix corresponding to a specific variable index.

Template Parameters

BPPD	Bit pattern propagation direction.

Parameters

data	Bit-vector propagation state data.
idx	Global variable index.
currentStripWordIdx	Starting index of the current strip.

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ SparseANFBlock

Function Documentation

◆ ADCalls()

◆ bitVectorPropagation()

◆ buildHessPatternAndSeed()

◆ buildJacPatternAndSeed() [1/2]

◆ buildJacPatternAndSeed() [2/2]

◆ checkBVPInput()

◆ classifySparseANFBlock()

◆ computeSparseHess()

◆ computeSparseJac() [1/2]

◆ computeSparseJac() [2/2]

◆ createSeed()

◆ extract() [1/2]

◆ extract() [2/2]

◆ extractCompressedRowStorage()

◆ prepareADCalls()

◆ prepareSeedMatrix()

◆ recover() [1/2]

◆ recover() [2/2]

◆ resetInput()

◆ resetOldSeed()

◆ setSeed()