Compilation¶

Archimedes can “compile” a Python function into a C++ computational graph, meaning that when you call the compiled function, the entire numerical code gets executed in C++ rather than interpreted Python.
For complicated functions this can achieve dramatic speedups over pure Python (5-10x even on simple benchmarks).

import numpy as np
import archimedes as arc

@arc.compile
def rotate(x, theta):
    R = np.array([
        [np.cos(theta), -np.sin(theta)],
        [np.sin(theta), np.cos(theta)],
    ], like=x)
    return R @ x

rotate(np.array([1.0, 0.0]), 0.1)

You can embed complex functionality like ODE solves, constrained nonlinear optimization, and more directly in these computational graphs.

When you first call your function, Archimedes feeds it symbolic arrays (using CasADi’s symbolic types under the hood) that match the shape and type of your numerical inputs.
As your code executes, it builds up a C++ representation of the calculation.
Then, instead of operating on the numerical arrays, your code operates on these symbolic replacements, using NumPy’s array dispatch mechanism to redirect to CasADi whenever you call NumPy functions.
By the end of this “tracing” step, CasADi has a full view of what the function does and can reproduce it in efficient C++.
Then, any time you call that function again, the C++ equivalent is what actually gets executed.

This approach is not “Just-In-Time” (JIT) compilation in the sense used by Julia/JAX/Numba, where the Python code is literally compiled down to highly optimized platform-specific machine code.
We’ll show some benchmarking in a separate post, but generally what you can expect is that these JIT-compiled frameworks will be somewhat faster than pre-compiled CasADi (and hence, Archimedes).
However, by avoiding the overhead and “unrolling” of true JIT compilation, we get a massive reduction in compilation time for the kind of complex functions typical of advanced controls applications.

For more on how this works (and when it doesn’t), see the Under the Hood documentation page.

Simulation, Optimization, & Root-finding¶

Archimedes provides a SciPy-like interface to the powerful and robust CVODES solver from SUNDIALS, which is a highly efficient and time-tested implementation of a stiff/non-stiff implicit solver that even supports gradient-based sensitivity analysis:

def simulate(x0):
    xs = arc.odeint(dynamics, (t0, tf), x0, t_eval=ts)
    return xs[:, -1]

arc.jac(simulate)(x0)  # dxf/dx0

We also have a SciPy-like optimization interface that can solve constrained nonlinear problems with IPOPT:

# Rosenbrock problem
def f(x):
    return 100 * (x[1] - x[0] ** 2) ** 2 + (1 - x[0]) ** 2

result = arc.minimize(f, x0=[-1.0, 1.0])

and a root-finding interface for iteratively solving nonlinear algebraic systems using Newton iterations and similar methods:

def f(x):
    return np.array([
        x[0] + 0.5 * (x[0] - x[1])**3 - 1.0,
        0.5 * (x[1] - x[0])**3 + x[1]
    ], like=x)

x = arc.root(f, x0=np.array([0.0, 0.0]))

These solves can also be embedded in compiled computational graphs for accelerated simulation and optimization.

Automatic Differentiation¶

Compilation into a CasADi computational graph unlocks two critical capabilities: execution speed and automatic differentiation.
This means that you can easily and accurately calculate derivatives of your functions:

def lotka_volterra(t, x):
    a, b, c, d = 1.5, 1.0, 1.0, 3.0
    return np.hstack([
        a * x[0] - b * x[0] * x[1],
        c * x[0] * x[1] - d * x[1],
    ])

# Linearize the system
J = arc.jac(dynamics, argnums=1)
print(J(0.0, [1.0, 1.0]))

Besides linearizing models for stability analysis and controller design, this is a feature you may not directly use very often.
But gradients and Jacobians are used pervasively in numerical methods:

• Optimization solvers use gradients of the objective, Jacobians of the constraints, and sometimes even Hessian information

• Simulation algorithms use Jacobians of the dynamics model for implicit solvers, especially for “stiff” ODE/DAE problems

• Root-finding solvers like Newton’s method use Jacobians at every iteration to find an improved guess at the solution point

So when you do parameter estimation, trajectory optimization, trim point identification, or even just call odeint, you don’t think about “autodiff”, but it’s happening behind the scenes to solve your problem.

Traditional scientific computing packages like SciPy and MATLAB usually fall back to slow and inaccurate finite differencing unless you provide manually implemented gradients, Jacobians, etc. – but for anything but the simplest problems this is prohibitively complicated to calculate and implement.

Newer frameworks like Julia, JAX, and PyTorch rely much more heavily on autodiff, but none of these are tailored towards hardware and controls engineering applications.
My personal experience has been that CasADi (the autodiff framework used under the hood by Archimedes) has far and away the best autodiff system for the kinds of large, sparse problems that commonly arise in engineering (like parameter estimation, trajectory optimization, model-predictive control, etc.).

All that is to say, the derivatives are there if you need them.

Structured Data Types¶

Most numerical codes are naturally written to operate on flat vectors.
This makes sense for the implementation of an optimization algorithm or ODE solver, but physical systems are usually more naturally conceived of as hierarchical.
For instance, a satellite has position, velocity, attitude, angular velocity, battery state, thermal state, etc.
To work with typical numerical codes, you have to either keep track of what entries in your array are which physical state or manually flatten/unflatten every time you call a routine that expects a flat vector.

That might be fine the first time, but what if you want to try a higher-fidelity battery model that has twice as many dynamic states?
It quickly becomes a nightmare to maintain these kinds of codes, and the result is that you waste cycles on keeping all of this straight, and you lose the practical capability to explore multi-fidelity modeling.

This also comes up frequently in deep learning: models are naturally organized as hierarchical modules with trainable parameters.
This is the root of the nn.Module in PyTorch and the “PyTree” concept in JAX.
Modern ML frameworks (specifically JAX and PyTorch) have developed a nice set of solutions around working with this kind of hierarchically structured data.

But this hierarchical data and logic might even be more common in engineering.
Physical systems are naturally organized into subsystems and components that have well-defined interfaces, and each of these might have its own dynamic state and configurable parameters.
Hierarchical data structures can mirror this physical system decomposition.

Archimedes takes inspiration from these frameworks and supports “tree operations” (functions applied to hierarchical data) and a @struct decorator to create tree-compatible data classes:

@arc.struct
class PointMass:
    pos: np.ndarray
    vel: np.ndarray

state = PointMass(np.zeros(3), np.ones(3))  # state.pos, state.vel
flat_state, unravel = arc.tree.ravel(state)  # flat_state is a vector
state = unravel(flat_state)  # Back to a PointMass instance

These @struct-decorated classes can be nested inside one another, flattened to/from a 1D vector, and used to auto-generate nested struct types in deployable C code.
If a PointMass is used as an argument to a codegen function, it will become:

typedef struct {
    float pos[3];
    float vel[3];
} point_mass_t;

This gives you a predictable and intuitive way to switch back and forth between Python and auto-generated C.

For much more on structured data types, see Structured Data Types, Hierarchical Systems Modeling, and the C Code Generation tutorial series.

On-ramp Projects¶

Once you learn the basics, I bet in an hour or two you could:

• Deploy a PI temperature controller to an Arduino

• Write an integrator for the IMU strapdown equations

• Run parameter estimation on some step response data you have lying around

• Design an energy-shaping controller for a pendulum

• Benchmark some old hand-written C code against the auto-generated equivalent (and share the results)

If you have a cool first project that you’re willing to share, feel free to post about it on the Discussions page – if it’s interesting it could become its own tutorial or blog post.

“Public Beta” Status¶

This post marks the release of Archimedes in “public beta” (v0.X.X).
This means that the core functionality is there and has already been tested in practical applications.
The API is also well-tested and stable; while it is likely to evolve in time, it will change with semantic versioning conventions, meaning smooth upgrade paths and deprecation notices.
The library will remain in beta for 6-12 months to allow for community feedback and API maturation across ongoing real-world applications.

For symbolic/numeric reliability in particular, Archimedes gets a big leg up by using CasADi as its backend, which has an excellent track record and is widely and actively used and tested in a variety of applications.

All that is to say, between now and the “v1.0” release you can expect things to be largely stable, but this additional time builds in a cushion to work out any kinks.

Ongoing development priorities are outlined in detail in the roadmap, but key focus areas include:

• Hybrid Simulations: Support for DAEs, zero-crossing events, multirate control logic

• Hardware Deployment: Improved support for HIL testing, static analysis, and profiling/telemetry

• Physics Modeling: Built-in functionality like reference frames, kinematic trees, polynomial/spline primitives, and templates for domain-specific components.

• Algorithm Development: State machines, trajectory optimization, MPC, sensor fusion, uncertainty quantification, etc.

Stay Updated¶

For updates on Archimedes, including release announcements, new features, blog posts, application examples, and case studies, subscribe to the free newsletter:

You can expect infrequent posts (maybe monthly) with a strong technical focus – no ads, spam, or paywalls.

Supporting Archimedes¶

This post might read a bit like ad copy, but Archimedes is a free, open-source project.
The codebase, ongoing status, and discussions all live on the GitHub repository.

If you want to support it, the best thing you can do right now is try it out and give feedback.
What worked well? What didn’t work? What did you like? What was confusing? What was confusing at first but you liked once you got used to it? What would you like to try with Archimedes? What would you like to try but there’s a functionality gap?

The Discussions page is a great place to share general feedback, and bug reports or feature requests are welcome on the Issues tab.

Besides feedback, other easy ways to support the project include:

• ⭐ Star the Repository: This shows support and interest and helps others discover the project

• 📢 Spread the Word: Think anyone you know might be interested?

• 🐛 Report Issues: Detailed bug reports, documentation gaps, and feature requests are invaluable

• 🗞️ Stay in the Loop: Subscribe to the newsletter for updates and announcements

Thanks for checking out the project!