symforce.codegen.codegen module

class LinearizationMode(value)[source]

Bases: Enum

Mode for with_linearization

STACKED_JACOBIAN = 'stacked_jacobian'
FULL_LINEARIZATION = 'full_linearization'
class GeneratedPaths(output_dir, lcm_type_dir, function_dir, python_types_dir, cpp_types_dir, generated_files)[source]

Bases: object

Parameters:

  • output_dir (Path) –

  • lcm_type_dir (Path) –

  • function_dir (Path) –

  • python_types_dir (Path) –

  • cpp_types_dir (Path) –

  • generated_files (List[Path]) –

output_dir: Path
lcm_type_dir: Path
function_dir: Path
python_types_dir: Path
cpp_types_dir: Path
generated_files: List[Path]
__init__(output_dir, lcm_type_dir, function_dir, python_types_dir, cpp_types_dir, generated_files)
Parameters:

  • output_dir (Path) –

  • lcm_type_dir (Path) –

  • function_dir (Path) –

  • python_types_dir (Path) –

  • cpp_types_dir (Path) –

  • generated_files (List[Path]) –

exception InvalidNamespaceError[source]

Bases: ValueError

Exception class for attempting codegen with an invalid namespace

exception InvalidNameError[source]

Bases: ValueError

Exception class for attempting codegen with an invalid function name

exception CodeGenerationException[source]

Bases: Exception

Exception class for errors raised from templates during code generation

class Codegen(inputs, outputs, config, name=None, return_key=None, sparse_matrices=None, docstring=None)[source]

Bases: object

Class used for generating code from symbolic expressions or functions.

Codegen objects can either be used to generate standalone functions, or as specifications in a larger code generation pipeline. Each codegen object defines an input/output relationship between a set of symbolic inputs and a set of symbolic output expressions written in terms of the inputs.

Parameters:

  • inputs (Values) –

  • outputs (Values) –

  • config (CodegenConfig) –

  • name (Optional[str]) –

  • return_key (Optional[str]) –

  • sparse_matrices (Optional[Sequence[str]]) –

  • docstring (Optional[str]) –

__init__(inputs, outputs, config, name=None, return_key=None, sparse_matrices=None, docstring=None)[source]

Creates the Codegen specification.

Parameters:

  • inputs (Values) – Values object specifying names and symbolic inputs to the function

  • outputs (Values) – Values object specifying names and output expressions (written in terms of the symbolic inputs) of the function

  • config (CodegenConfig) – Programming language and configuration in which the function is to be generated

  • name (Optional[str]) – Name of the function to be generated; must be set before the function is generated, but need not be set here if it’s going to be set by with_linearization or with_jacobians. Should be snake_case, will be converted to the language-specific function name style at generation time

  • return_key (Optional[str]) – If specified, the output with this key is returned rather than filled in as a named output argument.

  • sparse_matrices (Optional[Sequence[str]]) – Outputs with this key will be returned as sparse matrices

  • docstring (Optional[str]) – The docstring to be used with the generated function

property output_symbols: Set[Symbol]

The set of free symbols in the output

Cached, because this is somewhat expensive to compute for large outputs

classmethod function(func, config, name=None, input_types=None, output_names=None, return_key=None, sparse_matrices=None, docstring=None)[source]

Creates a Codegen object from a symbolic python function.

Parameters:

  • func (Callable) – Python function. Note, variable position and keyword arguments will be ignored. Additionally, keyword only arguments will be set to their default values and not included in the signature of the generated function.

  • input_types (Optional[Sequence[Union[Any, Type]]]) – List of types of the inputs to the given function. This is optional; if func has type annotations, input_types can be deduced from those. Note that if the type annotation doesn’t match what you want the arguments to be, you need to specify manually, for instance a function add(x: T.Any, y: T.Any) -> T.Any that you want to use to generate add(x: sf.Matrix33, y: sf.Matrix33) -> sf.Matrix33

  • config (CodegenConfig) – Programming language and configuration in which the function is to be generated

  • name (Optional[str]) – Name of the function to be generated; if not provided, will be deduced from the function name. Must be provided if func is a lambda

  • output_names (Optional[Sequence[str]]) – Names to give to outputs returned from func. If None (the default), names will be chosen as f"res{i}" for functions that return multiple results, or "res" for functions that return a single result

  • sparse_matrices (Optional[Sequence[str]]) – Outputs with this key will be returned as sparse matrices

  • return_key (Optional[str]) – If multiple objects are returned, the generated function will return the object with this name (must be in output_names)

  • docstring (Optional[str]) – The docstring to be used with the generated function. Default is to use the existing docstring

Return type:

Codegen

static common_data()[source]

Return common template data for code generation.

Return type:

Dict[str, Any]

property print_code_results: PrintCodeResult
property unused_arguments: List[str]

The names of any inputs that do not appear in any outputs

total_ops()[source]

The number of symbolic ops in the expression.

Return type:

int

generate_function(output_dir=None, lcm_bindings_output_dir=None, shared_types=None, namespace='sym', generated_file_name=None, skip_directory_nesting=False)[source]

Generates a function that computes the given outputs from the given inputs.

Usage for generating multiple functions with a shared type:

codegen_obj_1.generate_function(namespace="my_namespace")
shared_types = {"my_type": "my_namespace.my_type_t"}
codegen_obj_2.generate_function(shared_types=shared_types, namespace="my_namespace")

In the example above, both codegen_obj_1 and codegen_obj_2 use the type "my_type". During the first call to generate_function() we generate the type "my_type", and it then becomes a shared type for the second call to generate_function(). This signals that "my_type" does not need to be generated during the second call to generate_function() as it already exists.

Parameters:

  • output_dir (Union[str, PathLike, None]) – Directory in which to output the generated function. Any generated types will be located in a subdirectory with name equal to the namespace argument.

  • lcm_bindings_output_dir (Union[str, PathLike, None]) – Directory in which to output language-specific LCM bindings

  • shared_types (Optional[Mapping[str, str]]) – Mapping between types defined as part of this codegen object (e.g. keys in self.inputs that map to Values objects) and previously generated external types.

  • namespace (str) – Namespace for the generated function and any generated types. Must be a valid identifier, nested namespaces are not supported.

  • generated_file_name (Optional[str]) – Stem for the filename into which the function is generated, with no file extension

  • skip_directory_nesting (bool) – Generate the output file directly into output_dir instead of adding the usual directory structure inside output_dir

Return type:

GeneratedPaths

static default_docstring(inputs, outputs, original_function=None)[source]

Create a default docstring if no other is available from the function or caller.

Parameters:

  • inputs (Values) –

  • outputs (Values) –

  • original_function (Optional[Callable]) –

Return type:

str

static wrap_docstring_arg_description(preamble, description, config)[source]
Parameters:

  • preamble (str) –

  • description (str) –

  • config (CodegenConfig) –

Return type:

List[str]

with_linearization(which_args=None, include_result=True, name=None, linearization_mode=LinearizationMode.FULL_LINEARIZATION, sparse_linearization=False, custom_jacobian=None)[source]

Given a codegen object that takes some number of inputs and computes a single result, create a new codegen object that additionally computes the jacobian (or the full Gauss-Newton linearization) with respect to the given input arguments.

The jacobians are in the tangent spaces of the inputs and outputs, see jacobian_helpers.py for more information.

The previous codegen object (the self argument to this function) is unmodified by this function and still valid after this function returns.

Parameters:

  • self – Existing codegen object that returns a single value

  • which_args (Optional[Sequence[str]]) – Names of args for which to compute jacobians. If not given, uses all.

  • include_result (bool) – For the STACKED_JACOBIAN mode, whether we should still include the result or only return the jacobian. For the FULL_LINEARIZATION mode, we always include the result (which is the residual).

  • name (Optional[str]) – Generated function name. If not given, picks a reasonable name based on the one given at construction.

  • linearization_mode (LinearizationMode) – Whether to generate a single jacobian matrix (STACKED_JACOBIANS), or generate a full linearization with a hessian and rhs (FULL_LINEARIZATION).

  • sparse_linearization (bool) – Whether to output matrices (jacobian and/or hessian) as sparse matrices, as opposed to dense

  • custom_jacobian (Optional[Matrix]) – This is generally 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, should have shape (result_dim, input_tangent_dim), where input_tangent_dim is the sum of the tangent dimensions of arguments corresponding to which_args

Return type:

Codegen

with_jacobians(which_args=None, which_results=(0,), include_results=True, name=None, sparse_jacobians=False)[source]

Given a codegen object that takes some number of inputs and computes some number of results, create a new codegen object that additionally computes jacobians of the given results with respect to the given input arguments. By default, computes the jacobians of the first result with respect to all arguments. Flexible to produce the values and all jacobians, just the jacobians, or any combination of one or more jacobians.

The jacobians are in the tangent spaces of the inputs and outputs, see jacobian_helpers.py for more information.

The previous codegen object (the self argument to this function) is unmodified by this function and still valid after this function returns.

Parameters:

  • self – Existing codegen object that return a single value

  • which_args (Optional[Sequence[str]]) – Names of args for which to compute jacobians. If not given, uses all.

  • which_results (Sequence[int]) – Indices of results for which to compute jacobians. If not given, uses the first result.

  • include_results (bool) – Whether we should still return the values in addition to the jacobian(s), for the results in which_results. Values not in which_results are always still returned.

  • name (Optional[str]) – Generated function name. If not given, picks a reasonable name based on the one given at construction.

  • sparse_jacobians (bool) – Whether to output jacobians as sparse matrices, as opposed to dense

Return type:

Codegen