wrenfold

Documentation

wrenfold is a framework for converting symbolic mathematical expressions (written in Python) into generated numerical code in other languages (C++, Rust, Python). It aims to bridge the gap between prototyping of functions in expressive symbolic form, and performant production code. wrenfold is particularly relevant to domains where numerical optimization is employed to solve differentiable objective functions, such as robotics or computer vision.

Using wrenfold, mathematical functions can be expressed and composed succinctly in python:

```python from wrenfold import codegeneration, sym from wrenfold.typeannotations import Vector3

def angulardistance(a: Vector3, b: Vector3): """ A simple example function: We compute the angle between two vectors. The angle is returned, and the Jacobian with respect to a is passed as an output argument. This might be a cost in an optimization, for instance. """ dot = (a.T * b)[0] costheta = dot / (a.norm() * b.norm()) theta = sym.acos(costheta) thetaD_a = sym.jacobian([theta], a)

# Our generated function will return `theta`, and pass `theta_D_a` as an output arg.
return (
    code_generation.ReturnValue(theta),
    code_generation.OutputArg(theta_D_a, "theta_D_a"),
)

```

And corresponding compilable code can be obtained easily:

```python

CppGenerator can be swapped out for RustGenerator to obtain Rust. You can implement your own

custom generator to target a new language - or override methods on the provided generators in

order to customize the output code to your liking.

cpp = codegeneration.generatefunction(angulardistance, codegeneration.CppGenerator()) print(cpp) cpp template Scalar angulardistance(const T0& a, const T1& b, T2&& thetaDa) { auto _a = wf::makeinputspan<3, 1>(a); auto _b = wf::makeinputspan<3, 1>(b); auto _thetaDa = wf::makeoutputspan<1, 3>(thetaD_a);

const Scalar v007 = _b(2, 0); const Scalar v006 = _a(2, 0); const Scalar v004 = _b(1, 0);

// ... Output code is truncated for brevity.

const Scalar v009 = v000 * v001 + v003 * v004 + v006 * v007; const Scalar v021 = v001 * v001 + v004 * v004 + v007 * v007;

// ...

thetaDa(0, 0) = (v000 * v072 + v001 * v017) * v073; _thetaDa(0, 1) = (v003 * v072 + v004 * v017) * v073; _thetaD_a(0, 2) = (v006 * v072 + v007 * v017) * v073; return std::acos(v009 * v017 * v023); } ```

wrenfold draws inspiration from SymForce, but differs in a few key ways:

• Improved flexibility: Symbolic expressions can include conditional logic. This enables a broader range of functions to be generated.
• Ease of integration: wrenfold aims to make it straightforward to customize the code-generation step to suit your project. For example, you can use existing types in your codebase in generated method signatures.
• Faster code generation: Faster code generation translates to quicker iteration on experiments. The generation cost should ideally be negligible compared to compile time for the code itself.
• Narrower scope: wrenfold does not implement a numerical optimizer. Rather we aim to make it simple to integrate generated code into your project's existing preferred optimizer (see the extended examples). It should be relatively straightforward to use wrenfold functions with GTSAM, Ceres, the SymForce optimizer, or your own custom implementation.

wrenfold is primarily written in C++, and exposes a python API via pybind11. It can presently generate code in C++17, Rust, and Python (NumPy, PyTorch, and JAX are all supported). <!--- intro_end --->

Motivation

Why use symbolic code generation for mathematical functions? The SymForce paper outlines some of the rationale. In our opinion, the two main arguments are:

• Faster iteration:
  • Functions can be written quickly and expressively in python, enabling rapid prototyping. Over time, users acquire a library of composable expressions that can be combined easily to form new symbolic functions.
  • Derivatives are obtained automatically, without spending time debugging manually chain-ruled Jacobians.
• Improved runtime performance:
  • The performance of generated methods is often competitive with handwritten implementations, and can meaningfully exceed results obtained with runtime auto-diff.
  • Generated methods are fast enough to deploy on a production robot, enabling a quicker pipeline from offline prototyping to real-world testing.
  • A prudent caveat for any performance related claim: Your mileage may vary depending on expression complexity and the degree of effort exerted in optimizing different implementations.

Getting started

Install wrenfold from PyPi:

bash pip install wrenfold

wrenfold is also available on conda-forge:

bash conda install -c conda-forge wrenfold

To get started: - Refer to the quick start guide and user guide. - Take a look at some of the examples: - There are some examples of symbolic expressions in this repository. For instance, an implementation of imu integration or the dynamics of a cart-pole/double-pendulum system. - Each example includes a unit test that invokes the generated code. - The wrenfold-extra-examples repository includes examples of integrating generated code into existing optimizers like GTSAM and Ceres.

Building from source

See Building from source.

Project status

wrenfold was originally created by me after determining there were opportunities to push the symbolic code-generation concept further (see motivations section).

The project began as a part-time hobby for fun, and has evolved into a more full-featured framework over time. wrenfold is in the early stages of receiving feedback from a wider audience. There will be rough edges and undoubtedly some bugs. If you find something broken or missing, please consider filing a ticket. I aim to continue developing and expanding the framework. For details of upcoming work, see the planned features list.

If you are interested in collaboration opportunities or have general questions, please reach out.

License

wrenfold uses the MIT License.

Citation

wrenfold is published in the Journal of Open Source Software (JOSS). If you wish to cite this project, please use the following:

bibtex @article{Cross2025, doi = {10.21105/joss.07303}, url = {https://doi.org/10.21105/joss.07303}, year = {2025}, publisher = {The Open Journal}, volume = {10}, number = {105}, pages = {7303}, author = {Gareth Cross}, title = {wrenfold: Symbolic code generation for robotics}, journal = {Journal of Open Source Software} } <!--- citation_end --->