ADOLC::Sparse Namespace Reference

Namespaces
namespace	adtl_indo
namespace	detail

Classes
class	CoordinateFormatTripled
	One nonzero entry of a sparse matrix in coordinate format. More...
struct	PiecewiseLinear
	Tag type selecting sparse drivers for piecewise-linear abs-normal forms. More...
struct	SparseANF
	Stores the abs-normal form in sparse format. More...
struct	SparseHessInfos
	Cached sparse Hessian recovery data stored on a tape. More...
struct	SparseJacInfos
	Cached sparse Jacobian recovery data stored on a tape. More...
class	SparseMatrix
	Owning sparse matrix container in coordinate-format. More...
struct	SparseShape
	Nonzero counts for the four blocks of a sparse abs-normal form. More...

Enumerations
enum class	SparseMethod { IndexDomains , BitPattern }
	Method used to determine the sparsity pattern. More...
enum class	ControlFlowMode { Safe , Tight , OldSafe , OldTight }
	Control-flow handling mode for sparsity and dependence analysis. More...
enum class	BitPatternPropagationDirection { Auto , Forward , Reverse }
	Direction used for bit-pattern propagation. More...
enum class	CompressionMode { Column , Row }
	Compression orientation for sparse Jacobian recovery. More...
enum class	RecoveryMethod { Indirect , Direct }
	Recovery strategy for sparse Hessians. More...
enum class	MemoryHandler { Auto , Manual }
	Selects how sparse coordinate buffers are provided. More...

Functions
template<ControlFlowMode CFM>
ADOLC_API int	forward (short tag, int m, int n, int p, double *x, std::vector< bitword_t * > &X, double *y, std::vector< bitword_t * > &Y)
	Forward-mode bit-pattern propagation (safe or tight control-flow).
template<ControlFlowMode CFM>
ADOLC_API int	forward (short tag, int m, int n, int p, std::vector< bitword_t * > &X, std::vector< bitword_t * > &Y)
	Forward-mode bit-pattern propagation (safe control-flow only).
template<ControlFlowMode CFM>
ADOLC_API int	reverse (short tag, int m, int n, int q, std::vector< bitword_t * > &U, std::vector< bitword_t * > &Z)
	Reverse-mode bit-pattern propagation (safe or tight control-flow).
ADOLC_API int	forward (short tag, int m, int n, int p, double *x, bitword_t **X, double *y, bitword_t **Y, char mode)
	Legacy forward-mode bit-pattern propagation (mode-selected).
ADOLC_API int	forward (short tag, int m, int n, int p, bitword_t **X, bitword_t **Y, char mode)
	Legacy forward-mode bit-pattern propagation, safe mode only.
ADOLC_API int	reverse (short tag, int m, int n, int q, bitword_t **U, bitword_t **Z, char mode)
	Legacy reverse-mode bit-pattern propagation (mode-selected).
template<ControlFlowMode CFM, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto>
ADOLC_API int	bit_vector_propagation (short tapeId, int depen, int indep, const double *basepoint, std::span< uint * > &compressedRowStorage)
	Computes the sparsity pattern of a Jacobian using bit-vector propagation.
template<SparseMethod SM, ControlFlowMode CFM, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto>
ADOLC_API int	jac_pat (short tag, int depen, int indep, const double *basepoint, std::span< uint * > &compressedRowStorage)
	Compute Jacobian sparsity pattern using the selected sparse method.
template<PiecewiseLinear >
ADOLC_API int	jac_pat (short tag, int depen, int indep, int numsw, const double *basepoint, std::span< uint * > &compressedRowStorage)
	Computes the Jacobian sparsity pattern for an abs-smooth function.
template<CompressionMode CM>
ADOLC_API void	generate_seed_jac (int m, int n, const std::span< uint * > JP, double ***Seed, int *p)
	Generate a seed matrix (coloring) for compressed Jacobian recovery.
template<SparseMethod SM = SparseMethod::IndexDomains, CompressionMode CM = CompressionMode::Column, ControlFlowMode CFM = ControlFlowMode::Safe, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto, MemoryHandler MH = MemoryHandler::Auto>
ADOLC_API int	sparse_jac (short tag, int depen, int indep, int repeat, const double *basepoint, SparseMatrix &sparseJac)
	High-level API to compute a sparse Jacobian (single call or repeat).
template<PiecewiseLinear PL = PiecewiseLinear{}, MemoryHandler MH = MemoryHandler::Auto>
ADOLC_API int	sparse_jac (short tag, int depen, int indep, int numSwitches, int repeat, const double *basepoint, SparseANF &sparseANF)
	Compute the sparse extended Jacobian of a piecewise-linear abs-normal form in block form.
template<ControlFlowMode CFM>
ADOLC_API int	hess_pat (short tag, int indep, const double *basepoint, std::span< uint * > &compressedRowStorage)
	Compute Hessian sparsity pattern (dispatch by control-flow mode).
template<RecoveryMethod RCM>
ADOLC_API void	generate_seed_hess (int n, std::span< uint * > HP, double ***Seed, int *p)
	Generate a seed matrix for compressed Hessian recovery.
template<ControlFlowMode CFM, RecoveryMethod RCM>
ADOLC_API int	sparse_hess (short tag, int indep, int repeat, const double *basepoint, int *nnz, unsigned int **rind, unsigned int **cind, double **values)
	High-level API to compute a sparse Hessian.
template<CompressionMode CM>
void	generateSeedJac (int, int, const std::span< uint * >, double ***, int *)
void	generateSeedHess (int dimIn, const std::span< uint * > HP, double ***Seed, int *p, const std::string &coloringVariant)
	Generate a Hessian seed matrix using ColPack.

Enumeration Type Documentation

BitPatternPropagationDirection

enum class ADOLC::Sparse::BitPatternPropagationDirection

strong

Direction used for bit-pattern propagation.

Specifies whether sparsity propagation is performed in forward mode, reverse mode, or selected automatically based on problem dimensions.

Enumerator
Auto	Automatic selection of propagation direction. A heuristic chooses forward or reverse propagation at runtime, based on the relative sizes of the numbers of dependent and independent variables.
Forward	Forward-mode bit-pattern propagation. Efficient when the number of independent variables is significantly smaller than the number of dependent variables.
Reverse	Reverse-mode bit-pattern propagation. Efficient when the number of dependent variables is significantly smaller than the number of independent variables.

CompressionMode

enum class ADOLC::Sparse::CompressionMode

strong

Compression orientation for sparse Jacobian recovery.

Determines whether compressed derivative evaluations and recovery are performed row-wise or column-wise.

Enumerator
Column	Column compression. Compresses columns of the Jacobian and recovers entries column-wise. This is the default mode in ADOL-C.
Row	Row compression. Compresses rows of the Jacobian and recovers entries row-wise.

ControlFlowMode

enum class ADOLC::Sparse::ControlFlowMode

strong

Control-flow handling mode for sparsity and dependence analysis.

Determines how conditional branches in the taped computational graph are treated during sparsity propagation.

Enumerator
Safe	Safe (conservative) control-flow handling. All potential dependencies that may occur for any value of the independent variables are included. No reevaluation at a basepoint is required. Example: For c = max(a, b), the dependence pattern of c is taken as the union of the patterns of a and b.
Tight	Tight (basepoint-dependent) control-flow handling. Control-flow branches are resolved using the provided basepoint values. The resulting sparsity pattern may contain fewer nonzeros but is only valid locally around the basepoint where the function is analytic. Example: For c = max(a, b), the dependence pattern of c is taken from either a or b, depending on which branch is active at the basepoint.
OldSafe	Legacy safe control-flow handling. Historical implementation of safe control-flow propagation retained for backward compatibility.
OldTight	Legacy tight control-flow handling. Historical implementation of tight control-flow propagation retained for backward compatibility.

MemoryHandler

enum class ADOLC::Sparse::MemoryHandler

strong

Selects how sparse coordinate buffers are provided.

Use Auto when the recovery routine should resize and overwrite the supplied SparseMatrix or SparseANF. Use Manual when the caller already provides container storage whose entry counts exactly match the sparse pattern expected for the requested recovery. This choice is orthogonal to repeat, which only controls whether sparse metadata is rebuilt or reused.

Enumerator
Auto
Manual

RecoveryMethod

enum class ADOLC::Sparse::RecoveryMethod

strong

Recovery strategy for sparse Hessians.

Selects the algorithm used by ColPack to recover the Hessian from its compressed representation.

Enumerator
Indirect	Indirect (acyclic) recovery. Uses an acyclic coloring and recovers Hessian entries indirectly, typically via successive substitutions.
Direct	Direct (star) recovery. Uses star coloring and recovers Hessian entries directly without additional arithmetic.

SparseMethod

enum class ADOLC::Sparse::SparseMethod

strong

Method used to determine the sparsity pattern.

Selects the algorithm used to compute sparsity patterns of Jacobians and Hessians.

Enumerator
IndexDomains	Index-domain propagation. Uses index-domain propagation as described in the ADOL-C documentation. It is the default for sparsity detection.
BitPattern	Bit-pattern propagation. Uses packed Boolean (bit-pattern) propagation through the computational graph. This method enables strip-mining for large problems, at the cost of additional memory.

Function Documentation

bit_vector_propagation()

template<ControlFlowMode CFM, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto>

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

Computes the sparsity pattern of a Jacobian using bit-vector propagation.

This routine determines the sparsity pattern of the Jacobian of a taped function by propagating bit patterns through the recorded computational graph. It supports both forward and reverse propagation strategies, with optional control-flow sensitivity.

Parameters

tapeId	Tape identification number for the recorded function.
depen	Number of dependent (output) variables.
indep	Number of independent (input) variables.
basepoint	Pointer to an array of length indep specifying the values of the independent variables at which the sparsity pattern is evaluated. Required when CFM == ControlFlowMode::Tight; otherwise may be null.
compressedRowStorage	Output: Compressed Row Storage (compressedRowStorage) representation of the Jacobian sparsity pattern. compressedRowStorage[i][0] → number of nonzero entries in row i compressedRowStorage[i][1..] → column indices (0-based) of nonzero entries in row i. Memory for compressedRowStorage[i] is (re)allocated within this routine.

Returns

Return code from the underlying forward/reverse driver: Nonnegative status on success; negative on failure. Lower nonnegative values indicate reduced differentiability or changed control flow.

Note

• Uses "strip-mining" to split the bit pattern matrix into manageable blocks if the number of bits per size_t is insufficient to store the full pattern.
• In forward mode, seeds are built per independent variable block; in reverse mode, seeds are built per dependent variable block.
• Memory allocated for compressedRowStorage[i] must be freed by the caller when no longer needed.

See also

jac_pat

hess_pat

forward() [1/4]

ADOLC_API int ADOLC::Sparse::forward	(	short	tag,
		int	m,
		int	n,
		int	p,
		bitword_t **	X,
		bitword_t **	Y,
		char	mode
	)

Legacy forward-mode bit-pattern propagation, safe mode only.

Backward-compatible overload corresponding to the “safe” bit-pattern forward routine in the ADOL-C manual. This variant does not require a basepoint and does not compute function values.

Dispatch behavior:

• mode == 0 → forward<ControlFlowMode::Safe>(tag, m, n, p, X, Y)

Parameters

	tag	Tape identifier.
	m	Number of dependent variables (outputs).
	n	Number of independent variables (inputs).
	p	Number of packed bit-vectors per row/column block.
[in]	X	Seed dependence structure in packed form (n pointers, each p words).
[out]	Y	Output dependence structure in packed form (m pointers, each p words).
	mode	Must be 0 (safe). Any other value is an error.

Returns

Return code from the underlying ADOL-C driver.

Exceptions

(via	ADOLCError::fail) If mode != 0.

Note

This function is retained for backward compatibility. New code should prefer forward<ControlFlowMode::Safe>(tag, m, n, p, X, Y).

forward() [2/4]

ADOLC_API int ADOLC::Sparse::forward	(	short	tag,
		int	m,
		int	n,
		int	p,
		double *	x,
		bitword_t **	X,
		double *	y,
		bitword_t **	Y,
		char	mode
	)

Legacy forward-mode bit-pattern propagation (mode-selected).

Backward-compatible entry point corresponding to the “bit pattern forward” routine documented in the ADOL-C manual (Dependence Analysis section).

This overload selects the control-flow handling at runtime via mode and dispatches to the typed C++ API:

• mode == 0 → forward<ControlFlowMode::Safe>(...)
• mode == 1 → forward<ControlFlowMode::Tight>(...)

Parameters

	tag	Tape identifier.
	m	Number of dependent variables (outputs).
	n	Number of independent variables (inputs).
	p	Number of packed bit-vectors per row/column block.
	x	Basepoint array of length n. Required when mode == 1 (tight). May be nullptr when mode == 0 (safe).
[in]	X	Seed dependence structure in packed form. Must contain exactly n pointers; each X[i] points to an array of length p of bitword_t.
[out]	y	Output values array of length m. Only required/used for mode == 1 (tight).
[out]	Y	Output dependence structure in packed form. Must contain exactly m pointers; each Y[j] points to an array of length p of bitword_t.
	mode	Control-flow mode selector: 0 : safe mode (default / conservative) 1 : tight mode (evaluated at x)

Returns

Return code from the underlying ADOL-C driver.

Exceptions

(via	ADOLCError::fail) If mode is not in {0,1}. If mode == 1 and x == nullptr (missing basepoint).

Note

This function is retained for backward compatibility. New code should prefer the typed overload forward<ControlFlowMode::Safe/Tight>(...).

No memory is allocated or freed by this routine; all buffers are managed by the caller.

forward() [3/4]

template<ControlFlowMode CFM>

ADOLC_API int ADOLC::Sparse::forward	(	short	tag,
		int	m,
		int	n,
		int	p,
		double *	x,
		std::vector< bitword_t * > &	X,
		double *	y,
		std::vector< bitword_t * > &	Y
	)

Forward-mode bit-pattern propagation (safe or tight control-flow).

Computes bit-pattern propagation through a taped function in forward mode using packed boolean vectors (bitword_t).

This is a C++ wrapper around the internal ADOL-C drivers:

• int_forward_safe(...) (CFM == ControlFlowMode::Safe)
• int_forward_tight(...) (CFM == ControlFlowMode::Tight)

Template Parameters

CFM	Control-flow handling mode

Parameters

	tag	Tape identifier.
	m	Number of dependent variables (outputs).
	n	Number of independent variables (inputs).
	p	Number of packed bit-vectors per row/column block. For the full Jacobian pattern in forward mode use nBV = n.
	x	Basepoint array of length n. Required when CFM == ControlFlowMode::Tight, ignored in Safe mode.
[in]	X	Seed matrix in packed form. Must contain exactly n pointers; each X[i] points to an array of length p of bitword_t. The caller owns and manages the memory behind these pointers.
[out]	y	Output values array of length m. Only written in Tight mode (because tight propagation actually evaluates at x). May be nullptr in Safe mode.
[out]	Y	Output bit-pattern matrix in packed form. Must contain exactly m pointers; each Y[j] points to an array of length p of bitword_t. On return, Y contains the propagated dependency pattern.

Returns

Return code from the underlying ADOL-C driver.

Exceptions

(via	ADOLCError::fail) In Tight mode if x == nullptr (missing basepoint).

Note

This function does not allocate or free any memory. It only reads/writes through the provided pointers.

A legacy interface using a "mode" argument is provided below.

forward() [4/4]

template<ControlFlowMode CFM>

ADOLC_API int ADOLC::Sparse::forward	(	short	tag,
		int	m,
		int	n,
		int	p,
		std::vector< bitword_t * > &	X,
		std::vector< bitword_t * > &	Y
	)

Forward-mode bit-pattern propagation (safe control-flow only).

Safe-mode-only overload of forward bit-pattern propagation that does not require a basepoint x and does not produce function values y.

This is a convenience wrapper around int_forward_safe(...).

Template Parameters

CFM	Must be ControlFlowMode::Safe.

Parameters

	tag	Tape identifier.
	m	Number of dependent variables (outputs).
	n	Number of independent variables (inputs).
	p	Number of packed bit-vectors per row/column block.
[in]	X	Seed matrix in packed form. Must contain exactly n pointers; each X[i] points to an array of length p of bitword_t. The caller owns and manages the memory behind these pointers.
[out]	Y	Output bit-pattern matrix in packed form. Must contain exactly m pointers; each Y[j] points to an array of length p of bitword_t. On return, Y contains the propagated dependency pattern.

Returns

Return code from the underlying ADOL-C driver.

Note

Use the 7-argument overload (with x and y) if you need tight control-flow handling at a basepoint.

generate_seed_hess()

template<RecoveryMethod RCM>

ADOLC_API void ADOLC::Sparse::generate_seed_hess	(	int	n,
		std::span< uint * >	HP,
		double ***	Seed,
		int *	p
	)

Generate a seed matrix for compressed Hessian recovery.

Produces a seed matrix for Hessian recovery using ColPack and returns the seed via Seed and the compressed dimension via p. The caller owns this unmanaged allocation; the graph does not free it.

Template Parameters

RCM	RecoveryMethod selecting the recovery strategy: RecoveryMethod::Indirect : indirect recovery (acyclic strategy) RecoveryMethod::Direct : direct recovery (star strategy)

Parameters

	n	Number of variables (dimension of Hessian).
	HP	Span over CRS row pointers representing Hessian sparsity (HP).
[out]	Seed	Seed matrix with n rows and p columns.
[out]	p	Compressed dimension (number of seed columns/rows depending on layout).

Note

Delete each seed row with delete[], then delete the row-pointer array with delete[].

generate_seed_jac()

template<CompressionMode CM>

ADOLC_API void ADOLC::Sparse::generate_seed_jac	(	int	m,
		int	n,
		const std::span< uint * >	JP,
		double ***	Seed,
		int *	p
	)

Generate a seed matrix (coloring) for compressed Jacobian recovery.

Uses ColPack's Bipartite graph coloring to produce the seed matrix suitable for recovering the full Jacobian from compressed directional evaluations. This function uses ColPack's unmanaged API and returns pointers via Seed and the compressed dimension via p.

Template Parameters

CM	CompressionMode selecting orientation of compression: CompressionMode::Row : seeds correspond to row-compression CompressionMode::Column : seeds correspond to column-compression

Parameters

	m	Number of dependent variables (rows of JP).
	n	Number of independent variables (columns of JP).
	JP	Compressed Row Storage, storing the dependencies on independents.
[out]	Seed	Output pointer to a 2D array representing the seed matrix. Memory is provided by ColPack (unmanaged) and returned to caller.
[out]	p	On return: compressed dimension (number of seed columns when Row compression, or seed rows when Column compression).

Note

Delete each seed row with delete[], then delete the row-pointer array with delete[]. Column compression has n rows; row compression has p.

generateSeedHess()

void ADOLC::Sparse::generateSeedHess	(	int	dimIn,
		const std::span< uint * >	HP,
		double ***	Seed,
		int *	p,
		const std::string &	coloringVariant
	)

Generate a Hessian seed matrix using ColPack.

Parameters

	dimIn	Hessian dimension.
	HP	Hessian sparsity pattern in CRS form.
[out]	Seed	Seed matrix returned by ColPack.
[out]	p	Compressed dimension of the seed matrix.
	coloringVariant	ColPack coloring strategy.

generateSeedJac()

template<CompressionMode CM>

void ADOLC::Sparse::generateSeedJac	(	int	,
		int	,
		const std::span< uint * >	,
		double ***	,
		int *
	)

hess_pat()

template<ControlFlowMode CFM>

ADOLC_API int ADOLC::Sparse::hess_pat	(	short	tag,
		int	indep,
		const double *	basepoint,
		std::span< uint * > &	compressedRowStorage
	)

Compute Hessian sparsity pattern (dispatch by control-flow mode).

This function computes the sparsity pattern of the Hessian by dispatching to the appropriate internal non-linear independent-index propagation driver based on the compile-time ControlFlowMode template parameter.

Template Parameters

CFM

ControlFlowMode controlling how control-flow is handled: ControlFlowMode::OldTight : legacy tight control-flow handling ControlFlowMode::OldSafe : legacy safe control-flow handling ControlFlowMode::Tight : tight control-flow (evaluate branches at basepoint) ControlFlowMode::Safe : safe / conservative control-flow

Parameters

	tag	ADOL-C tape identifier.
	indep	Number of independent variables (Hessian dimension).
	basepoint	Pointer to an array of length indep with the evaluation point used when tight control-flow is required.
[out]	compressedRowStorage	Span of length indep where each element is a pointer to a Compressed Row Storage (CRS) row for the Hessian pattern. For row i: entry [i][0] is the count of indices stored, entry [i][1..] are the independents the output i depend on.

Returns

• >= 0 : Driver-specific non-negative code.
• < 0 : Error code forwarded from the underlying driver.

Note

• The routine resets compressedRowStorage pointers before use.
• Memory allocated for each row will be owned by the caller/tape.

jac_pat() [1/2]

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

ADOLC_API int ADOLC::Sparse::jac_pat	(	short	tag,
		int	depen,
		int	indep,
		const double *	basepoint,
		std::span< uint * > &	compressedRowStorage
	)

Compute Jacobian sparsity pattern using the selected sparse method.

Dispatches to either index-domain propagation or bit-vector propagation depending on the template parameter SM and control-flow mode CFM.

Template Parameters

SM	SparseMethod used to compute pattern: SparseMethod::IndexDomains : index-domain propagation SparseMethod::BitPattern : bit-vector propagation
CFM	ControlFlowMode controlling control-flow sensitivity: ControlFlowMode::Safe : conservative (may ignore branches) ControlFlowMode::Tight : evaluate control-flow at basepoint
BPPD	BitPatternPropagationDirection used when SM==BitPattern. If BitPatternPropagationDirection::Auto a runtime heuristic selects forward/reverse direction.

Parameters

	tag	Tape identifier (as used by ADOL-C tracing).
	depen	Number of dependent (output) variables (rows).
	indep	Number of independent (input) variables (cols).
	basepoint	Pointer to an array of length indep. Required when CFM == ControlFlowMode::Tight; may be nullptr in Safe mode.
[out]	compressedRowStorage	Span of length depen where each element is a pointer to a Compressed Row Storage (CRS) row: entry [i][0] holds the count of nonzeros in row i entry [i][1..] holds the 0-based column indices that represent the influencing independent variables

Returns

Nonnegative sweep status on success; negative on failure.

Note

Ownership: allocated row buffers in compressedRowStorage are transferred to the caller / tape infrastructure and must be freed appropriately.

jac_pat() [2/2]

template<PiecewiseLinear >

ADOLC_API int ADOLC::Sparse::jac_pat	(	short	tag,
		int	depen,
		int	indep,
		int	numsw,
		const double *	basepoint,
		std::span< uint * > &	compressedRowStorage
	)

Computes the Jacobian sparsity pattern for an abs-smooth function.

This function computes the sparsity pattern of the extended Jacobian (aka abs-normal form) of an abs-smooth function. Internally, it performs an index-domain propagation through the recorded function, represented using switching variables.

Parameters

	tag	ADOL-C tape identifier.
	depen	Number of dependent (output) variables.
	indep	Number of independent (input) variables.
	numsw	Number of switching variables.
	basepoint	Pointer to basepoint values (independent variable array).
[out]	compressedRowStorage	Span over an array of row pointers, each representing one row of the extended Jacobian in Compressed Row Storage (CRS) format. Rows are ordered as [y ; z], while columns are ordered as [x ; |z|].

Returns

Return code from indopro_forward_absnormal():

• 0 → success,
• nonzero → warning or error code from ADOL-C.

reverse() [1/2]

ADOLC_API int ADOLC::Sparse::reverse	(	short	tag,
		int	m,
		int	n,
		int	q,
		bitword_t **	U,
		bitword_t **	Z,
		char	mode
	)

Legacy reverse-mode bit-pattern propagation (mode-selected).

Backward-compatible entry point corresponding to the “bit pattern reverse” routine documented in the ADOL-C manual (Dependence Analysis section).

This overload selects the control-flow handling at runtime via mode and dispatches to the typed C++ API:

• mode == 0 → reverse<ControlFlowMode::Safe>(...)
• mode == 1 → reverse<ControlFlowMode::Tight>(...)

Parameters

	tag	Tape identifier.
	m	Number of dependent variables (outputs).
	n	Number of independent variables (inputs).
	q	Number of packed bit-vectors (rows of packed reverse seeds).
[in]	U	Seed dependence structure in packed form. Must contain exactly q pointers; each U[k] points to an array of length m of bitword_t.
[out]	Z	Output dependence structure in packed form. Must contain exactly q pointers; each Z[k] points to an array of length n of bitword_t.
	mode	Control-flow mode selector: 0 : safe mode (default / conservative) 1 : tight mode

Returns

Return code from the underlying ADOL-C driver.

Exceptions

(via	ADOLCError::fail) If mode is not in {0,1}.

Note

This function is retained for backward compatibility. New code should prefer the typed overload reverse<ControlFlowMode::Safe/Tight>(...).

No memory is allocated or freed by this routine; all buffers are managed by the caller.

reverse() [2/2]

template<ControlFlowMode CFM>

ADOLC_API int ADOLC::Sparse::reverse	(	short	tag,
		int	m,
		int	n,
		int	q,
		std::vector< bitword_t * > &	U,
		std::vector< bitword_t * > &	Z
	)

Reverse-mode bit-pattern propagation (safe or tight control-flow).

Computes bit-pattern propagation through a taped function in reverse mode using packed boolean vectors (bitword_t).

This is a C++ wrapper around the internal ADOL-C drivers:

• int_reverse_safe(...) (CFM == ControlFlowMode::Safe)
• int_reverse_tight(...) (CFM == ControlFlowMode::Tight)

Template Parameters

CFM	Control-flow handling mode

Parameters

	tag	Tape identifier.
	m	Number of dependent variables (outputs).
	n	Number of independent variables (inputs).
	q	Number of packed bit-vectors (rows of the packed adjoint seed). For the full Jacobian pattern in reverse mode use nBV = m.
[in]	U	Reverse seed matrix in packed form. Must contain exactly q pointers; each U[k] points to an array of length m of bitword_t. The caller owns and manages the memory behind these pointers.
[out]	Z	Output packed bit-pattern matrix. Must contain exactly q pointers; each Z[k] points to an array of length n of bitword_t.

Returns

Return code from the underlying ADOL-C driver.

Note

This function does not allocate or free any memory. It only reads/writes through the provided pointers.

A legacy interface using a "mode" argument is provided below.

sparse_hess()

template<ControlFlowMode CFM, RecoveryMethod RCM>

ADOLC_API int ADOLC::Sparse::sparse_hess	(	short	tag,
		int	indep,
		int	repeat,
		const double *	basepoint,
		int *	nnz,
		unsigned int **	rind,
		unsigned int **	cind,
		double **	values
	)

High-level API to compute a sparse Hessian.

Coordinates Hessian sparsity pattern generation (when repeat == 0), seed generation and caching, and the numeric recovery step. For repeat == 0 the function computes and caches pattern/seed info; for subsequent calls it performs the numeric recovery using cached state.

Template Parameters

CFM	ControlFlowMode used when computing the Hessian pattern.
RCM	RecoveryMethod used by ColPack to perform recovery.

Parameters

	tag	ADOL-C tape identifier.
	indep	Number of independent variables (Hessian dimension).
	repeat	If 0: compute pattern and seed (cache them). If >0: perform
	basepoint	Basepoint for tight control-flow (may be nullptr if not required).
[in,out]	nnz	On entry: expected number of nonzeros when repeat != 0. On exit: set to the number of nonzeros when repeat == 0.
[out]	rind	Pointer-to-pointer to receive row indices (coordinate format).
[out]	cind	Pointer-to-pointer to receive column indices.
[out]	values	Pointer-to-pointer to receive numerical values.

Returns

• >= 0 : Success (driver-specific non-negative codes).
• < 0 : Error code (forwarded from pattern/compute routines).

Note

Memory ownership semantics for rind/cind/values match the underlying recovery calls: if user provided non-null pointers, user memory is used (usermem variants), otherwise the unmanaged variant allocates memory and the caller must free it.

sparse_jac() [1/2]

template<PiecewiseLinear PL = PiecewiseLinear{}, MemoryHandler MH = MemoryHandler::Auto>

ADOLC_API int ADOLC::Sparse::sparse_jac	(	short	tag,
		int	depen,
		int	indep,
		int	numSwitches,
		int	repeat,
		const double *	basepoint,
		SparseANF &	sparseANF
	)

Compute the sparse extended Jacobian of a piecewise-linear abs-normal form in block form.

This overload computes the sparse extended Jacobian of the abs-normal form associated with a taped abs-smooth function and partitions it into the four blocks Y, J, Z, and L.

Parameters

	tag	Tape identifier.
	depen	Number of dependent variables y.
	indep	Number of independent variables x.
	numSwitches	Number of switching variables z.
	repeat	If 0: rebuild sparsity/seed metadata and perform numeric recovery. If >0: reuse cached metadata and perform numeric recovery.
	basepoint	Independent basepoint values.
[in,out]	sparseANF	Sparse abs-normal container receiving the recovered Y, J, Z, and L blocks, plus the dense vectors y, z and cyandcz`.

Returns

0 or a positive driver status on success, negative error code on failure.

Note

repeat and MemoryHandler are orthogonal. MemoryHandler::Auto resizes the sparse blocks of sparseANF to the recovered nonzero counts. MemoryHandler::Manual requires that sparseANF.Y, sparseANF.J, sparseANF.Z, and sparseANF.L are already sized correctly. In both modes, cy,cz, y and z are overwritten with internally computed constants.

sparse_jac() [2/2]

template<SparseMethod SM = SparseMethod::IndexDomains, CompressionMode CM = CompressionMode::Column, ControlFlowMode CFM = ControlFlowMode::Safe, BitPatternPropagationDirection BPPD = BitPatternPropagationDirection::Auto, MemoryHandler MH = MemoryHandler::Auto>

ADOLC_API int ADOLC::Sparse::sparse_jac	(	short	tag,
		int	depen,
		int	indep,
		int	repeat,
		const double *	basepoint,
		SparseMatrix &	sparseJac
	)

High-level API to compute a sparse Jacobian (single call or repeat).

This function coordinates sparsity detection, seed generation (via ColPack), compressed AD evaluations, and recovery. When repeat == 0 the function rebuilds and caches the sparsity/seed information stored on the tape, then performs numeric recovery. Subsequent calls (repeat != 0) reuse the cached pattern/seed metadata and perform numeric recovery at the new basepoint.

Template Parameters

SM	Default SparseMethod used for pattern detection (IndexDomains).
CM	Default CompressionMode used for recovery (Column).
CFM	Default ControlFlowMode for propagation (Safe).
BPPD	Default bit-propagation direction (Auto).
MH	Selects whether sparseJac may be resized automatically or must already provide the exact number of output entries.

Parameters

	tag	Tape identifier.
	depen	Number of dependent variables (rows).
	indep	Number of independent variables (columns).
	repeat	If 0: rebuild sparsity/seed metadata and perform numeric recovery. If >0: reuse cached sparsity/seed metadata and perform numeric recovery.
	basepoint	Array of independent values (required if tight control-flow).
[in,out]	sparseJac	Sparse matrix receiving the recovered coordinate-format nonzeros.

Returns

0 or positive status on success, negative error code on failure.

Note

repeat and MemoryHandler are orthogonal. MemoryHandler::Auto resizes sparseJac to the recovered nonzero count, while MemoryHandler::Manual overwrites caller-provided storage and requires that sparseJac.size() already matches that count.