symforce.opt.factor module#

class Factor(keys, residual, config=None, custom_jacobian_func=None, **kwargs)[source]#

Bases: object

A class used to represent symbolic factors as used in a factor graph. The factor is typically constructed from either a function or from a symbolic expression using from_inputs_and_residual(). A linearization function can be generated from the factor using generate() which can be used in a larger optimization.

Parameters:

  • keys (T.Sequence[str]) – The set of variables that are inputs to the factor. These should be in order of the residual function arguments.

  • residual (T.Callable[..., sf.Matrix]) – The residual function for the factor. When passed symbolic inputs, this should return a symbolic expression for the residual.

  • config (T.Optional[codegen_config.CodegenConfig]) – The language the numeric factor will be generated in. Defaults to Python, which does not require any compilation.

  • custom_jacobian_func (T.Optional[T.Callable[[T.Iterable[str]], sf.Matrix]]) – A functor that computes the jacobian, typically unnecessary unless 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. If not provided, the jacobian will be computed automatically. If provided, this should be a function that takes the set of optimized keys, and returns the jacobian of the residual with respect to those keys.

  • kwargs (T.Any) – Any other arguments to be passed to the codegen object used to generate the numeric factor. See Codegen.function for details.

static default_codegen_config()[source]#

The default codegen config used by the Factor class

This is a PythonConfig with settings appropriate for converting to a numeric_factor.NumericFactor (returns 2d vectors).

Return type:

PythonConfig

classmethod from_inputs_and_residual(keys, inputs, residual, config=None, custom_jacobian_func=None, **kwargs)[source]#

Constructs a Factor from a set of inputs and a residual vector that consists of symbolic expressions composed from the symbolic variables in the inputs.

Parameters:

  • keys (Sequence[str]) – The set of variables that are inputs to the factor. These should be in order of input Values entries (computed using inputs.keys_recursive()), and are the keys used in the overall optimization problem.

  • inputs (Values) – The inputs Values for the factor.

  • residual (Matrix) – An expression representing the residual of the factor.

  • config (CodegenConfig | None) – The language the numeric factor will be generated in. Defaults to Python, which does not require any compilation.

  • custom_jacobian_func (Callable[[Iterable[str]], Matrix] | None) – A functor that computes the jacobian, typically unnecessary unless 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. If not provided, the jacobian will be computed automatically. If provided, this should be a function that takes the set of optimized keys, and returns the jacobian of the residual with respect to those keys.

  • kwargs (Any) – Any other arguments to be passed to the codegen object used to generate the numeric factor. See Codegen for details.

Return type:

Factor

generate(optimized_keys, output_dir=None, namespace=None, sparse_linearization=False)[source]#

Generates the code needed to construct a numeric_factor.NumericFactor from this Factor.

Parameters:

  • optimized_keys (Sequence[str]) – Keys which we compute the linearization of the residual with respect to.

  • output_dir (str | PathLike | None) – Where the generated linearization function will be output.

  • namespace (str | None) – Namespace of the generated linearization function.

  • sparse_linearization (bool) – Whether the generated linearization function should use sparse matrices for the jacobian and hessian approximation

Returns:

  • Dict containing locations where the code was generated (e.g. “output_dir” and

  • “python_function_dir” or “cpp_function_dir”) and the name of the generated function.

Return type:

Dict[str, Any]

to_numeric_factor(optimized_keys, output_dir=None, namespace=None, sparse_linearization=False)[source]#

Constructs a numeric_factor.NumericFactor from this Factor, including generating a linearization function.

Parameters:

  • optimized_keys (Sequence[str]) – Keys which we compute the linearization of the residual with respect to.

  • output_dir (str | PathLike | None) – Where the generated linearization function will be output

  • namespace (str | None) – Namespace of the generated linearization function

  • sparse_linearization (bool) – Whether the generated linearization function should use sparse matrices for the jacobian and hessian approximation

Return type:

NumericFactor

visualize_factors(factors, outfile=None)[source]#

Construct a dot file of the factor graph given by the input set of factors.

Parameters:

  • factors (Sequence[Factor]) – List of factors to visualize, including all mentioned keys

  • outfile (str | PathLike | None) – Output file, if given. Format is parsed from the extension.

Returns:

graph object

Return type:

Graph