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 functionoutputs (
Values
) – Values object specifying names and output expressions (written in terms of the symbolic inputs) of the functionconfig (
CodegenConfig
) – Programming language and configuration in which the function is to be generatedname (
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 timereturn_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 matricesdocstring (
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; iffunc
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 generatedname (
Optional
[str
]) – Name of the function to be generated; if not provided, will be deduced from the function name. Must be provided iffunc
is a lambdaoutput_names (
Optional
[Sequence
[str
]]) – Names to give to outputs returned fromfunc
. 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 (
Optional
[Sequence
[str
]]) – Outputs with this key will be returned as sparse matricesreturn_key (
Optional
[str
]) – If multiple objects are returned, the generated function will return the object with this name (must be inoutput_names
)docstring (
Optional
[str
]) – The docstring to be used with the generated function. Default is to use the existing docstring
- Return type:
- 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
- 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 (
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 bindingsshared_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 extensionskip_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:
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 densecustom_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:
- 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: