Runs junction tree inference for a batch of evidence rows. More...

#include <engine.hpp>

Collaboration diagram for bncore::BatchExecutionEngine:

Public Member Functions
	BatchExecutionEngine (const JunctionTree &jt, std::size_t num_threads, std::size_t chunk_size)

void	evaluate (const int evidence_data, std::size_t batch_size, std::size_t num_vars, double output_data, std::size_t query_var)
	Posterior marginal of one variable for every batch row. More...

void	evaluate_multi (const int evidence_data, std::size_t batch_size, std::size_t num_vars, const std::size_t query_vars, std::size_t num_queries, const std::size_t output_offsets, double output_data)
	Posterior marginals of several variables for every batch row, from one sum-product calibration per chunk. More...

void	evaluate_map (const int evidence_data, std::size_t batch_size, std::size_t num_vars, int output_states)
	Most probable state of every variable for every batch row, from max-product propagation. More...

void	set_soft_evidence (bncore::NodeId var, const double *likelihoods, std::size_t n_states)
	Sets one likelihood vector for a variable, used for every batch row. More...

void	set_soft_evidence_matrix (bncore::NodeId var, const double *likelihoods_matrix, std::size_t total_n_states)
	Sets a separate likelihood vector per batch row for a variable. More...

void	clear_soft_evidence ()
	Removes all stored soft evidence, scalar and matrix. More...

void	invalidate_workspace_cache ()
	Discards the workspace kept for single-chunk evaluations. More...

const JunctionTree &	junction_tree () const
	The junction tree given at construction. More...

Private Member Functions
void	apply_soft_evidence_to_workspace (BatchWorkspace &workspace, std::size_t current_batch_start, std::size_t current_chunk_size) const

Private Attributes
const JunctionTree &	jt_

std::size_t	num_threads_

std::size_t	chunk_size_

std::unique_ptr< BatchWorkspace >	single_workspace_cache_
	reused when a batch is a single chunk More...

std::size_t	single_workspace_batch_size_ = 0
	batch size the cache was built for More...

std::unordered_map< bncore::NodeId, std::vector< double > >	soft_evidence_scalar_

std::unordered_map< bncore::NodeId, std::vector< double > >	soft_evidence_matrix_

Detailed Description

Runs junction tree inference for a batch of evidence rows.

A batch is a matrix of hard evidence with one row per independent query case. The engine cuts the batch into chunks of chunk_size rows. A batch that fits in one chunk runs on the calling thread in a BatchWorkspace that the engine keeps between calls. A larger batch is split between up to num_threads workers, each with its own workspace created for that call. One worker runs on the calling thread; several run as std::async tasks and the call waits for all of them.

Soft evidence is stored in the engine and applied to every evaluation until it is replaced or cleared.

The evaluate functions modify the cached workspace without locking, so one engine must not run evaluations from several threads at the same time. The engine keeps a reference to the junction tree, which must outlive it.

Definition at line 41 of file engine.hpp.

Constructor & Destructor Documentation

◆ BatchExecutionEngine()

bncore::BatchExecutionEngine::BatchExecutionEngine	(	const JunctionTree &	jt,
		std::size_t	num_threads,
		std::size_t	chunk_size
	)

Parameters

jt	Compiled junction tree. Held by reference.
num_threads	Largest number of worker tasks for a batch of several chunks. 0 selects std::thread::hardware_concurrency(), or 1 if that reports 0.
chunk_size	Rows per chunk. 0 is treated as 1.

Definition at line 13 of file engine.cpp.

References num_threads_.

Member Function Documentation

◆ apply_soft_evidence_to_workspace()

void bncore::BatchExecutionEngine::apply_soft_evidence_to_workspace	(	BatchWorkspace &	workspace,
		std::size_t	current_batch_start,
		std::size_t	current_chunk_size
	)		const

private

Replaces the workspace's soft evidence with the engine's, passing each matrix from row current_batch_start on.

Definition at line 262 of file engine.cpp.

References bncore::BatchWorkspace::clear_soft_evidence(), bncore::Graph::get_variable(), bncore::JunctionTree::graph(), jt_, bncore::BatchWorkspace::set_soft_evidence(), bncore::BatchWorkspace::set_soft_evidence_matrix(), soft_evidence_matrix_, soft_evidence_scalar_, and bncore::VariableMetadata::states.

Referenced by evaluate_map(), and evaluate_multi().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clear_soft_evidence()

void bncore::BatchExecutionEngine::clear_soft_evidence ( )

Removes all stored soft evidence, scalar and matrix.

Definition at line 257 of file engine.cpp.

References soft_evidence_matrix_, and soft_evidence_scalar_.

◆ evaluate()

void bncore::BatchExecutionEngine::evaluate	(	const int *	evidence_data,
		std::size_t	batch_size,
		std::size_t	num_vars,
		double *	output_data,
		std::size_t	query_var
	)

Posterior marginal of one variable for every batch row.

Equivalent to evaluate_multi() with a single query variable.

Parameters

evidence_data	Hard evidence matrix as described at evaluate_multi(), or nullptr for no hard evidence.
batch_size	Number of rows.
num_vars	Number of columns of the evidence matrix.
output_data	Receives [batch_size x S] values, row-major, where S is the state count of `query_var`. Each row is a normalized distribution over the variable's states.
query_var	NodeId of the queried variable.

Exceptions

std::out_of_range	if `query_var` is not a variable of the graph.
std::invalid_argument	for the reasons listed at evaluate_multi().

Definition at line 24 of file engine.cpp.

References evaluate_multi(), bncore::Graph::get_variable(), bncore::JunctionTree::graph(), jt_, and bncore::VariableMetadata::states.

Here is the call graph for this function:

◆ evaluate_map()

void bncore::BatchExecutionEngine::evaluate_map	(	const int *	evidence_data,
		std::size_t	batch_size,
		std::size_t	num_vars,
		int *	output_states
	)

Most probable state of every variable for every batch row, from max-product propagation.

Each row is processed on its own with a workspace of batch size 1 (see BatchWorkspace::max_calibrate() and BatchWorkspace::query_map()). Rows are grouped into chunks and spread over tasks in the same way as in evaluate_multi(), and the workspace kept between calls is used only when batch_size is 1. Stored soft evidence applies here as well.

Parameters

evidence_data	Evidence matrix as described at evaluate_multi(), or nullptr for no hard evidence.
batch_size	Number of rows. 0 returns without writing anything.
num_vars	Number of columns of the evidence matrix. When `evidence_data` is given it must be at least the graph's variable count.
output_states	Receives [batch_size x V] state indices, row-major, where V is the graph's variable count. Column v is the state of the variable with NodeId v.

Exceptions

std::invalid_argument if output_states is null, the evidence matrix is narrower than the variable count, or evidence is rejected as described at evaluate_multi().

Definition at line 147 of file engine.cpp.

References apply_soft_evidence_to_workspace(), chunk_size_, bncore::BatchWorkspace::clear_evidence(), bncore::JunctionTree::graph(), jt_, bncore::BatchWorkspace::max_calibrate(), num_threads_, bncore::Graph::num_variables(), bncore::BatchWorkspace::query_map(), bncore::BatchWorkspace::reset(), bncore::BatchWorkspace::set_evidence_matrix(), single_workspace_batch_size_, and single_workspace_cache_.

Here is the call graph for this function:

◆ evaluate_multi()

void bncore::BatchExecutionEngine::evaluate_multi	(	const int *	evidence_data,
		std::size_t	batch_size,
		std::size_t	num_vars,
		const std::size_t *	query_vars,
		std::size_t	num_queries,
		const std::size_t *	output_offsets,
		double *	output_data
	)

Posterior marginals of several variables for every batch row, from one sum-product calibration per chunk.

Hard evidence is a row-major [batch_size x num_vars] matrix of ints. Column v belongs to the variable with NodeId v. A negative entry means "not observed"; otherwise the entry is the observed state index. Variables with an id of num_vars or more have no hard evidence. If soft evidence is set for a variable, it is used in place of that variable's hard evidence.

The output is row-major [batch_size x T], where T is output_offsets[num_queries]. Within a row, the marginal of query q occupies positions [output_offsets[q], output_offsets[q] + S_q), where S_q is the state count of that variable. Each marginal is normalized to sum to 1. A marginal whose unnormalized sum is zero is written as zeros.

The call returns without writing anything if num_queries, batch_size or T is 0.

Parameters

evidence_data	Evidence matrix, or nullptr for no hard evidence.
batch_size	Number of rows.
num_vars	Number of columns of the evidence matrix.
query_vars	NodeIds of the queried variables, `num_queries` of them.
num_queries	Number of queried variables.
output_offsets	Prefix offsets into an output row. The array has `num_queries + 1` entries and the last one is the row width T.
output_data	Receives batch_size * T values.

Exceptions

std::invalid_argument if query_vars, output_offsets or output_data is null, a queried variable is not in the junction tree, a hard evidence state index is not below the variable's state count, stored soft evidence has the wrong number of states or a negative entry, a soft evidence matrix has fewer rows than the batch, or the evidence of a chunk that holds exactly one row is inconsistent (it leaves a clique potential that sums to zero).

std::out_of_range if stored soft evidence names a variable that is not in the graph.

Definition at line 36 of file engine.cpp.

References apply_soft_evidence_to_workspace(), bncore::BatchWorkspace::calibrate(), chunk_size_, bncore::BatchWorkspace::clear_evidence(), jt_, num_threads_, bncore::BatchWorkspace::query_marginals_multi(), bncore::BatchWorkspace::reset(), bncore::BatchWorkspace::set_evidence_matrix(), single_workspace_batch_size_, and single_workspace_cache_.

Referenced by evaluate().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ invalidate_workspace_cache()

void bncore::BatchExecutionEngine::invalidate_workspace_cache ( )

Discards the workspace kept for single-chunk evaluations.

A workspace builds its clique potentials from the graph's CPTs once and reuses them. Call this after Graph::set_cpt() so that the next evaluation builds a new workspace from the current tables. Stored soft evidence is not affected.

Definition at line 242 of file engine.cpp.

References single_workspace_batch_size_, and single_workspace_cache_.

◆ junction_tree()

const JunctionTree & bncore::BatchExecutionEngine::junction_tree ( ) const

inline

The junction tree given at construction.

Definition at line 175 of file engine.hpp.

References jt_.

◆ set_soft_evidence()

void bncore::BatchExecutionEngine::set_soft_evidence	(	bncore::NodeId	var,
		const double *	likelihoods,
		std::size_t	n_states
	)

Sets one likelihood vector for a variable, used for every batch row.

likelihoods[s] is the weight of state s, P(observation | variable = s). The values are copied. They need not sum to 1. Any matrix soft evidence stored for the same variable is removed. The vector is checked when the next evaluation applies it, not here.

Parameters

var	Variable the evidence applies to.
likelihoods	Array of `n_states` non-negative weights.
n_states	Length of the array. It must equal the variable's state count, otherwise the next evaluation throws std::invalid_argument.

Definition at line 247 of file engine.cpp.

References soft_evidence_matrix_, and soft_evidence_scalar_.

◆ set_soft_evidence_matrix()

void bncore::BatchExecutionEngine::set_soft_evidence_matrix	(	bncore::NodeId	var,
		const double *	likelihoods_matrix,
		std::size_t	total_n_states
	)

Sets a separate likelihood vector per batch row for a variable.

The matrix is row-major [rows x S], where S is the variable's state count: the weight of state s for batch row b is at b * S + s. Rows are indexed by position in the whole batch, not within a chunk. The values are copied, and any scalar soft evidence stored for the same variable is removed. An evaluation whose batch has more rows than the matrix throws std::invalid_argument.

Parameters

var	Variable the evidence applies to.
likelihoods_matrix	Array of `total_n_states` non-negative weights.
total_n_states	Total number of values, rows * S.

Definition at line 252 of file engine.cpp.

References soft_evidence_matrix_, and soft_evidence_scalar_.

Member Data Documentation

◆ chunk_size_

std::size_t bncore::BatchExecutionEngine::chunk_size_

private

Definition at line 186 of file engine.hpp.

Referenced by evaluate_map(), and evaluate_multi().

◆ jt_

const JunctionTree& bncore::BatchExecutionEngine::jt_

private

Definition at line 184 of file engine.hpp.

Referenced by apply_soft_evidence_to_workspace(), evaluate(), evaluate_map(), evaluate_multi(), and junction_tree().

◆ num_threads_

std::size_t bncore::BatchExecutionEngine::num_threads_

private

Definition at line 185 of file engine.hpp.

Referenced by BatchExecutionEngine(), evaluate_map(), and evaluate_multi().

◆ single_workspace_batch_size_

std::size_t bncore::BatchExecutionEngine::single_workspace_batch_size_ = 0

private

batch size the cache was built for

Definition at line 188 of file engine.hpp.

Referenced by evaluate_map(), evaluate_multi(), and invalidate_workspace_cache().

◆ single_workspace_cache_

std::unique_ptr<BatchWorkspace> bncore::BatchExecutionEngine::single_workspace_cache_

private

reused when a batch is a single chunk

Definition at line 187 of file engine.hpp.

Referenced by evaluate_map(), evaluate_multi(), and invalidate_workspace_cache().

◆ soft_evidence_matrix_

std::unordered_map<bncore::NodeId, std::vector<double> > bncore::BatchExecutionEngine::soft_evidence_matrix_

private

Definition at line 192 of file engine.hpp.

Referenced by apply_soft_evidence_to_workspace(), clear_soft_evidence(), set_soft_evidence(), and set_soft_evidence_matrix().

◆ soft_evidence_scalar_

std::unordered_map<bncore::NodeId, std::vector<double> > bncore::BatchExecutionEngine::soft_evidence_scalar_

private

Definition at line 190 of file engine.hpp.

Referenced by apply_soft_evidence_to_workspace(), clear_soft_evidence(), set_soft_evidence(), and set_soft_evidence_matrix().

The documentation for this class was generated from the following files:

src/BNCore/include/bncore/inference/engine.hpp
src/BNCore/src/engine.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BatchExecutionEngine()

Member Function Documentation

◆ apply_soft_evidence_to_workspace()

◆ clear_soft_evidence()

◆ evaluate()

◆ evaluate_map()

◆ evaluate_multi()

◆ invalidate_workspace_cache()

◆ junction_tree()

◆ set_soft_evidence()

◆ set_soft_evidence_matrix()

Member Data Documentation

◆ chunk_size_

◆ jt_

◆ num_threads_

◆ single_workspace_batch_size_

◆ single_workspace_cache_

◆ soft_evidence_matrix_

◆ soft_evidence_scalar_