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: 'Path', lcm_type_dir: 'Path', function_dir: 'Path', python_types_dir: 'Path', cpp_types_dir: 'Path', generated_files: 'T.List[Path]')[source]¶
Bases:
object
- Parameters:
- 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:
- 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 (Sequence[Any | Type] | None) – 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 functionadd(x: T.Any, y: T.Any) -> T.Any
that you want to use to generateadd(x: sf.Matrix33, y: sf.Matrix33) -> sf.Matrix33
config (CodegenConfig) – Programming language and configuration in which the function is to be generated
name (str | None) – Name of the function to be generated; if not provided, will be deduced from the function name. Must be provided if
func
is a lambdaoutput_names (Sequence[str] | None) – Names to give to outputs returned from
func
. IfNone
(the default), names will be chosen asf"res{i}"
for functions that return multiple results, or"res"
for functions that return a single resultsparse_matrices (Sequence[str] | None) – Outputs with this key will be returned as sparse matrices
return_key (str | None) – If multiple objects are returned, the generated function will return the object with this name (must be in
output_names
)docstring (str | None) – The docstring to be used with the generated function. Default is to use the existing docstring
- Return type:
- property print_code_results: PrintCodeResult¶
- 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
andcodegen_obj_2
use the type"my_type"
. During the first call togenerate_function()
we generate the type"my_type"
, and it then becomes a shared type for the second call togenerate_function()
. This signals that"my_type"
does not need to be generated during the second call togenerate_function()
as it already exists.- Parameters:
output_dir (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 (str | PathLike | None) – Directory in which to output language-specific LCM bindings
shared_types (Mapping[str, str] | None) – 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 (str | None) – 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:
- static default_docstring(inputs, outputs, original_function=None)[source]¶
Create a default docstring if no other is available from the function or caller.
- static wrap_docstring_arg_description(preamble, description, config)[source]¶
- Parameters:
preamble (str) –
description (str) –
config (CodegenConfig) –
- Return type:
- 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 (Sequence[str] | None) – 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 (str | None) – 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 (Matrix | None) – 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:
- 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 (Sequence[str] | None) – 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 (str | None) – 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: