GitHub

Inference Engine

The InferenceEngine is the central component in Cortex.jl for performing probabilistic inference. It acts as an abstraction layer over different model backends, providing a consistent API for interacting with models and running inference algorithms.

Concept

The primary role of the InferenceEngine is to:

  1. Manage a Model Backend: It holds an instance of a specific model structure (e.g., a BipartiteFactorGraph).
  2. Provide a Standardized API: It offers a set of functions to access and manipulate model components like variables, factors, and their connections, regardless of the underlying backend's specific implementation.
  3. Orchestrate Inference: It uses the reactive Signal system to manage the flow of messages and marginals. When data or priors change, the engine helps identify which parts of the model need updates.
  4. Execute Computations: It facilitates the application of user-defined computation functions (rules for how messages and marginals are calculated) to update the model's state using the update_marginals! function.

Upon creation, the InferenceEngine can automatically prepare the metadata of the signals within the model (marginals, messages to variables, messages to factors) by calling prepare_signals_metadata!. This step is crucial as it assigns specific types and metadata (like variable or factor IDs) to signals, which are often used by the computation functions during inference.

Core API

Cortex.InferenceEngine — Type
InferenceEngine{M}

Core structure for managing and executing inference tasks on a given model backend.

Fields

  • model_backend::M: The underlying model backend (e.g., a BipartiteFactorGraph) on which inference is performed. It must conform to the Cortex.jl backend interface.

Constructor

InferenceEngine(; model_backend::M, prepare_signals_metadata::Bool = true) where {M}
  • model_backend: An instance of a supported model backend.
  • prepare_signals_metadata::Bool (default: true): If true, calls prepare_signals_metadata! upon construction to initialize signal types and metadata. This is typically required for inference algorithms.

Overview

The InferenceEngine orchestrates message passing and marginal computation within a probabilistic model using the Signal reactivity system. It provides a standardized API for:

  • Accessing model components (variables, factors, connections).
  • Retrieving reactive signals for marginals and messages.
  • Managing inference execution via update_marginals! and request_inference_for.

The engine interacts with the model_backend through a defined interface (e.g., Cortex.get_variable_data(backend, id)), implemented by backend-specific extensions.

See Also

source

Engine and Backend Management

These functions allow you to interact with the engine itself and its underlying model backend.

Cortex.get_model_backend — Function
get_model_backend(engine::InferenceEngine)

Retrieves the underlying model backend from the InferenceEngine.

Arguments

  • engine::InferenceEngine: The inference engine instance.

Returns

The model backend object stored within the engine.

See Also

source
Cortex.is_backend_supported — Function
is_backend_supported(backend::Any) -> Union{SupportedModelBackend, UnsupportedModelBackend}

Checks if a given backend is supported by the InferenceEngine.

This function should be extended by specific backend implementations.

Arguments

  • backend::Any: The model backend instance to check.

Returns

  • SupportedModelBackend() if the backend is supported.
  • UnsupportedModelBackend() otherwise.

See Also

source
Missing docstring.

Missing docstring for Cortex.UnsupportedModelBackendError. Check Documenter's build log for details.

Accessing Model Components

The engine provides a suite of functions to retrieve data and reactive signals associated with variables, factors, and their connections.

Variables

Cortex.get_variable_data — Function
get_variable_data(engine::InferenceEngine, variable_id)

Retrieves the data structure representing a specific variable from the engine's model backend.

This function dispatches to the get_variable_data(backend, variable_id) method of the specific model backend. The returned object must implement get_marginal(variable_data_object) -> Cortex.Signal.

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the variable to retrieve.

Returns

A backend-specific data structure for the variable.

See Also

source
Cortex.get_variable_ids — Function
get_variable_ids(engine::InferenceEngine)

Retrieves an iterator over all variable identifiers in the engine's model backend.

This function dispatches to the get_variable_ids(backend) method of the specific model backend.

Arguments

  • engine::InferenceEngine: The inference engine instance.

Returns

An iterator of variable identifiers.

See Also

source
Cortex.get_marginal — Method
get_marginal(engine::InferenceEngine, variable_id) -> Cortex.Signal

Retrieves the marginal Signal for a given variable_id from the InferenceEngine.

This is a convenience function calling get_marginal(get_variable_data(engine, variable_id)).

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the variable.

Returns

  • Cortex.Signal: The reactive signal representing the variable's marginal.

See Also

source

Factors

Cortex.get_factor_data — Function
get_factor_data(engine::InferenceEngine, factor_id)

Retrieves the data structure representing a specific factor from the engine's model backend.

This function dispatches to the get_factor_data(backend, factor_id) method of the specific model backend.

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • factor_id: The identifier of the factor to retrieve.

Returns

A backend-specific data structure for the factor.

See Also

source
Cortex.get_factor_ids — Function
get_factor_ids(engine::InferenceEngine)

Retrieves an iterator over all factor identifiers in the engine's model backend.

This function dispatches to the get_factor_ids(backend) method of the specific model backend.

Arguments

  • engine::InferenceEngine: The inference engine instance.

Returns

An iterator of factor identifiers.

See Also

source

Connections and Messages

Cortex.get_connection — Function
get_connection(engine::InferenceEngine, variable_id, factor_id)

Retrieves the data structure representing the connection between a specified variable_id and factor_id.

This function dispatches to the get_connection(backend, variable_id, factor_id) method of the specific model backend. The returned object must implement:

  • get_connection_label(connection_object) -> Symbol
  • get_connection_index(connection_object) -> Int
  • get_message_to_variable(connection_object) -> Cortex.Signal
  • get_message_to_factor(connection_object) -> Cortex.Signal

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the variable in the connection.
  • factor_id: The identifier of the factor in the connection.

Returns

A backend-specific data structure for the connection.

See Also

source
Cortex.get_connection_label — Method
get_connection_label(engine::InferenceEngine, variable_id, factor_id) -> Symbol

Retrieves the label of the connection between variable_id and factor_id.

This is a convenience function calling get_connection_label(get_connection(engine, variable_id, factor_id)).

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the variable.
  • factor_id: The identifier of the factor.

Returns

  • Symbol: The label of the connection.

See Also

source
Cortex.get_connection_index — Method
get_connection_index(engine::InferenceEngine, variable_id, factor_id) -> Int

Retrieves the index of the connection between variable_id and factor_id.

This is a convenience function calling get_connection_index(get_connection(engine, variable_id, factor_id)).

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the variable.
  • factor_id: The identifier of the factor.

Returns

  • Int: The index of the connection.

See Also

source
Cortex.get_message_to_variable — Method
get_message_to_variable(engine::InferenceEngine, variable_id, factor_id) -> Cortex.Signal

Retrieves the message Signal from factor_id to variable_id.

This is a convenience function calling get_message_to_variable(get_connection(engine, variable_id, factor_id)).

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the target variable.
  • factor_id: The identifier of the source factor.

Returns

  • Cortex.Signal: The reactive signal for the message.

See Also

source
Cortex.get_message_to_factor — Method
get_message_to_factor(engine::InferenceEngine, variable_id, factor_id) -> Cortex.Signal

Retrieves the message Signal from variable_id to factor_id.

This is a convenience function calling get_message_to_factor(get_connection(engine, variable_id, factor_id)).

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the source variable.
  • factor_id: The identifier of the target factor.

Returns

  • Cortex.Signal: The reactive signal for the message.

See Also

source
Cortex.get_connected_variable_ids — Function
get_connected_variable_ids(engine::InferenceEngine, factor_id)

Retrieves an iterator over the identifiers of variables connected to a given factor_id.

This function dispatches to the get_connected_variable_ids(backend, factor_id) method of the specific model backend.

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • factor_id: The identifier of the factor.

Returns

An iterator of connected variable identifiers.

See Also

source
Cortex.get_connected_factor_ids — Function
get_connected_factor_ids(engine::InferenceEngine, variable_id)

Retrieves an iterator over the identifiers of factors connected to a given variable_id.

This function dispatches to the get_connected_factor_ids(backend, variable_id) method of the specific model backend.

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id: The identifier of the variable.

Returns

An iterator of connected factor identifiers.

See Also

source

Signal Metadata and Types

Understanding and managing signal metadata is key for many inference algorithms.

Cortex.InferenceSignalTypes — Module
InferenceSignalTypes

Module defining constants for different types of signals used within the inference engine. These types help in dispatching computation rules and managing signal metadata.

Constants

  • MessageToVariable: Signal representing a message from a factor to a variable.
  • MessageToFactor: Signal representing a message from a variable to a factor.
  • ProductOfMessages: Signal representing an intermediate product of messages, often a dependency for an IndividualMarginal.
  • IndividualMarginal: Signal representing the marginal distribution of a single variable.
  • JointMarginal: Signal representing the joint marginal distribution of a set of variables.

See Also

source
Cortex.prepare_signals_metadata! — Function
prepare_signals_metadata!(engine::InferenceEngine)

Initializes the type and metadata fields for relevant signals within the InferenceEngine.

This function iterates through variables and factors in the model backend, setting:

This setup is typically done once upon engine creation and is crucial for dispatching appropriate computation rules during inference.

Arguments

  • engine::InferenceEngine: The inference engine instance whose signals are to be prepared.

See Also

source

Running Inference

These functions are used to initiate and execute the inference process.

Cortex.request_inference_for — Function
request_inference_for(engine::InferenceEngine, variable_id_or_ids)

Creates an InferenceRequest to compute the marginals for the specified variable_id_or_ids.

This function prepares the necessary signals by marking their dependencies as potentially pending. It supports requesting inference for a single variable ID or a collection (Tuple or AbstractVector) of variable IDs.

Arguments

  • engine::InferenceEngine: The inference engine instance.
  • variable_id_or_ids: A single variable identifier or a collection of variable identifiers.

Returns

  • InferenceRequest: An internal structure representing the inference request.

See Also

source
Missing docstring.

Missing docstring for Cortex.update_marginals!. Check Documenter's build log for details.