Struct PntosStandardFusionEngine

Defined in File fusion.h

Struct Documentation

struct PntosStandardFusionEngine

An implementation of a fusion engine that supports the standard fusion model.

Assumes the system is described by discrete-time matrices and noise inputs are zero-mean white Gaussian. In addition, all covariance matrices / mean vectors are descriptions of jointly-Gaussian multivariate distributions. All noise sources are jointly-Gaussian distributed.

This object requires a PntosStandardFusionStrategy to work. Some implementations may be able to provide their own. Others will require a strategy to be provided via the PntosStandardFusionEngine.set_strategy method. It is possible to check whether a fusion engine needs to be provided a fusion strategy by calling the PntosStandardFusionEngine.get_strategy method (if the return is NULL then this fusion engine needs to be provided a strategy). While PntosStandardFusionEngine.get_strategy returns NULL, all other methods are unsafe to be called.

UNSTABLE: This feature is unstable and is not yet considered part of the stable pntOS API. Usage of this feature is highly discouraged in non-experimental code, and its definition may change at any time.

Public Members

PntosCommonFusionEngine common

void (*set_time)(struct PntosStandardFusionEngine *self, AspnTypeTimestamp time): Set the current time of the filter to the parameter.

AspnTypeTimestamp (*get_time)(struct PntosStandardFusionEngine *self): Get the current time of the filter

void (*set_strategy)(struct PntosStandardFusionEngine *self, PntosStandardFusionStrategy *strategy): Set the underlying algorithm used for Bayesian inference - the type of filter (EKF, UKF, etc.)

PntosStandardFusionStrategy *(*get_strategy)(struct PntosStandardFusionEngine *self)

Return: The underlying algorithm used for Bayesian inference - the type of filter (EKF, UKF, etc.). Returns NULL if this fusion engine does not have a strategy. If that is the case, the fusion engine must be provided with a strategy via set_strategy.

size_t (*get_num_states)(struct PntosStandardFusionEngine *self): Get the total number of states currently in the fusion engine that are associated with PntosStandardStateBlocks.

PntosStringArray *(*get_state_block_labels)(struct PntosStandardFusionEngine *self): Gets a list of the PntosStandardStateBlocks labels that have been added to this fusion engine. Returns NULL if no state blocks have been added. Guaranteed to not return NULL if get_num_states returns a value other than 0.

bool (*has_block)(struct PntosStandardFusionEngine *self, char *block_label): Returns true if the fusion engine has a PntosStandardStateBlock with a matching label.

void (*add_state_block)(struct PntosStandardFusionEngine *self, PntosStandardStateBlock *block, PntosEstimateWithCovariance *initial_estimate_covariance, PntosCrossCovariances *cross_covariances): Add the given PntosStandardStateBlock to the fusion engine. This will expand the state vector being estimated by the value of block->get_num_states(). The initial_estimate_covariance parameter contains the initial conditions of the states, with initial_estimate_covariance->estimate being an Nx1 matrix and initial_estimate_covariance->covariance being an NxN matrix, where N is block->get_num_states(). The cross_covariances are an optional parameter which, if non-NULL, contains a description of the newly added StateBlock’s cross covariances with respect to a set of StateBlocks which already exist inside the filter (specified by cross_covariances->block_labels). If the cross_covariance parameter is NULL, cross covariance between the existing states and the added states will be set to zeroes.

PntosMatrix *(*get_state_block_estimate)(struct PntosStandardFusionEngine *self, char *block_label): Find a PntosStandardStateBlock or PntosVirtualStateBlock within the fusion engine matching block_label, and return a copy of its current estimate vector. If block_label references a virtual state block (VSB) this will return a converted estimate, converted into the VSBs coordinate frame. Returns NULL if block_label does not correspond to a block that has been added to the fusion engine. Guaranteed to not return NULL when has_block returns true for block_label and get_strategy does not return NULL.

PntosMatrix *(*get_state_block_covariance)(struct PntosStandardFusionEngine *self, char *block_label): Find a PntosStandardStateBlock or PntosVirtualStateBlock within the fusion engine matching block_label, and return a copy of its current covariance matrix. If block_label references a virtual state block (VSB) this will return a converted covariance, converted into the VSBs coordinate frame. Returns NULL if block_label does not correspond to a block that has been added to the fusion engine. Guaranteed to not return NULL when has_block returns true for block_label and get_strategy does not return NULL.

PntosMatrix *(*get_state_block_cross_covariance)(struct PntosStandardFusionEngine *self, char *block_label1, char *block_label2): Find the PntosStandardStateBlocks within the fusion engine matching block_label1 and block_label2, and return the cross-covariance matrix between them. Returns NULL if block_label1 or block_label2 do not correspond to blocks that gave been added to the fusion engine. Guaranteed to not return NULL when has_block returns true for both block_label and block_label2 and get_strategy does not return NULL.

void (*set_state_block_estimate)(struct PntosStandardFusionEngine *self, char *block_label, PntosMatrix *estimate): Find a PntosStandardStateBlock within the fusion engine matching block_label, and change its current estimate vector. Note that this function may lead to performance degradation with some implementations and thus its use is discouraged if other options are available.

void (*set_state_block_covariance)(struct PntosStandardFusionEngine *self, char *block_label, PntosMatrix *covariance): Find a PntosStandardStateBlock within the fusion engine matching block_label, and change its current covariance matrix. Note that this function may lead to performance degradation with some implementations and thus its use is discouraged if other options are available.

void (*set_state_block_cross_covariance)(struct PntosStandardFusionEngine *self, char *block_label1, char *block_label2, PntosMatrix *covariance): Find the PntosStandardStateBlocks within the fusion engine matching block_label1 and block_label2, and change the current covariance matrix between them. Note that this function may lead to performance degradation with some implementations and thus its use is discouraged if other options are available.

void (*remove_state_block)(struct PntosStandardFusionEngine *self, char *block_label): Remove the PntosStandardStateBlock previously added to the fusion engine using add_state_block based on a matching block_label. This will reduce the state vector being estimated by the number of states that the block represents.

PntosStringArray *(*get_virtual_state_block_target_labels)(struct PntosStandardFusionEngine *self)

Gets a list of the target labels of virtual state blocks that have been added to this fusion engine.

A label being returned by this list is not a guarantee that the virtual state block has a valid source. For that, call has_virtual_state_block().

Returns NULL if no virtual state blocks have been added to this fusion engine.

bool (*has_virtual_state_block)(struct PntosStandardFusionEngine *self, char *vsb_target_label): Returns true if the fusion engine has a PntosVirtualStateBlock with a matching target label that is capable of generating an estimate. That is, the VSB’s source exists and is in a continuous chain to a concrete state block which also exists in the fusion engine.

void (*add_virtual_state_block)(struct PntosStandardFusionEngine *self, PntosVirtualStateBlock *virtual_state_block): Add the given PntosVirtualStateBlock to the fusion engine. A virtual state block (VSB) convert from an underlying block coordinate frame into the VSB coordinate frame.

void (*remove_virtual_state_block)(struct PntosStandardFusionEngine *self, char *vsb_target_label): Remove the PntosVirtualStateBlock previously added to the fusion engine using add_virtual_state_block based on a matching vsb_target_label.

PntosStringArray *(*get_measurement_processor_labels)(struct PntosStandardFusionEngine *self): Gets a list of the labels of measurement processors that have been added to this fusion engine. Returns NULL if no measurement processors have been added to this fusion engine.

bool (*has_processor)(struct PntosStandardFusionEngine *self, char *processor_label): Returns true if the fusion engine has a measurement processor with a matching label.

void (*add_measurement_processor)(struct PntosStandardFusionEngine *self, PntosStandardMeasurementProcessor *processor): Add a PntosStandardMeasurementProcessor which can be used to process future measurements that correspond to processor->get_label();

void (*remove_measurement_processor)(struct PntosStandardFusionEngine *self, char *processor_label): Remove the PntosStandardMeasurementProcessor previously added to the fusion engine using add_measurement_processor based on a matching processor_label.

void (*propagate)(struct PntosStandardFusionEngine *self, AspnTypeTimestamp time): Propagate the filter estimate forward in time. May be evaluated lazily (when results are requested).

void (*update)(struct PntosStandardFusionEngine *self, char *processor_label, PntosMessage *message): Update the filter with the given measurement. Will propagate first if needed to reach the time encoded inside the measurement.

PntosEstimateWithCovariance *(*peek_ahead)(struct PntosStandardFusionEngine *self, AspnTypeTimestamp time, char **block_labels, size_t num_block_labels)

Calculates the estimate and covariance at a requested time using the state blocks listed in block_labels, without changing the state of the fusion engine or its underlying filter. Blocks are assembled in the order that the labels are passed in.

block_labels is an array of num_block_labels pointers to \0 terminated C strings.

If all of the following are true:

time is equal to or after the filter time (which can be checked with get_time)
all labels in block_labels correspond to a block that has been added to the fusion engine (which can be checked with has_block)
num_block_labels is greater than zero

Then the result returned is guaranteed to not be NULL. Otherwise, if any of the above are false then the result will be NULL.

PntosEstimateWithCovariance *(*generate_x_and_p)(struct PntosStandardFusionEngine *self, char **block_labels, size_t num_block_labels)

Generates the current estimate and covariance built corresponding to a list of State Block labels. Blocks are assembled in the order that the labels are passed in.

block_labels is an array of num_block_labels pointers to \0 terminated C strings.

If all of the following are true:

all labels in block_labels correspond to a block that has been added to the fusion engine (which can be checked with has_block)
num_block_labels is greater than zero

Then the result returned is guaranteed to not be NULL. Otherwise, if any of the above are false then the result will be NULL.

void (*give_state_block_aux_data)(struct PntosStandardFusionEngine *self, char *block_label, PntosMessageArray *aux): Route a PntosMessageArray of aux data to a PntosStandardStateBlock previously registered using add_state_block based on a matching block_label.

void (*give_measurement_processor_aux_data)(struct PntosStandardFusionEngine *self, char *processor_label, PntosMessageArray *aux): Route a PntosMessageArray of aux data to a PntosStandardMeasurementProcessor previously registered using add_measurement_processor based on a matching processor_label.

void (*give_virtual_state_block_aux_data)(struct PntosStandardFusionEngine *self, char *target_label, PntosMessageArray *aux): Route a PntosMessageArray of aux data to a PntosVirtualStateBlock previously registered using add_virtual_state_block based on a matching target_label.

struct PntosStandardFusionEngine *(*clone)(struct PntosStandardFusionEngine *self): Produce a deep-copy this fusion engine instance. All state blocks and measurement processors held by the fusion engine will also be cloned. The fusion strategy used by the fusion engine will also be cloned.