symforce.opt.residual_block module

class ResidualBlock(residual, extra_values=None, metadata=None)

Bases: object

A single residual vector, with associated extra values. The extra values are not used in the optimization, but are intended to be additional outputs used for debugging or other purposes.

Parameters:

• residual (Matrix) –

• extra_values (Dataclass | None) –

• metadata (Dict[str, Any] | None) –

residual: Matrix

extra_values: Dataclass | None = None

metadata: Dict[str, Any] | None = None

compute_jacobians(inputs, residual_name=None, key_names=None)

Compute the jacobians of this residual block with respect to a sequence of inputs

Parameters:

• inputs (Sequence[Any]) – Sequence of inputs to differentiate with respect to

• residual_name (str | None) – Optional human-readable name of the residual to be used for debug messages

• key_names (Sequence[str] | None) – Optional sequence of human-readable names for the inputs to be used for debug messages

Returns:

Sequence of jacobians of the residual with respect to each entry in inputs

Return type:

Sequence[Matrix]

set_metadata(key, value)

Sets a metadata field of the residual block and returns the residual block.

Parameters:

• key (str) –

• value (Any) –

Return type:

ResidualBlock

class ResidualBlockWithCustomJacobian(residual, extra_values=None, metadata=None, custom_jacobians=<factory>)

Bases: ResidualBlock

A residual block, with a custom jacobian for the residual

This should generally only be used if you want to override the jacobian computed by SymForce, e.g. to stop derivatives with respect to certain variables or directions, or because the jacobian can be analytically simplified in a way that SymForce won’t do automatically. The custom_jacobians field should then be filled out with a mapping from all inputs to the residual which may be differentiated with respect to, to the desired jacobian of the residual with respect to each of those inputs.

Parameters:

• residual (Matrix) –

• extra_values (Dataclass | None) –

• metadata (Dict[str, Any] | None) –

• custom_jacobians (Dict[Any, Matrix]) –

custom_jacobians: Dict[Any, Matrix]

compute_jacobians(inputs, residual_name=None, key_names=None)

Compute the jacobians of this residual block with respect to a sequence of inputs

Parameters:

• inputs (Sequence[Any]) – Sequence of inputs to differentiate with respect to

• residual_name (str | None) – Optional human-readable name of the residual to be used for debug messages

• key_names (Sequence[str] | None) – Optional sequence of human-readable names for the inputs to be used for debug messages

Returns:

Sequence of jacobians of the residual with respect to each entry in inputs

Return type:

Sequence[Matrix]