archimedes 0.4.5

Python framework for modeling, simulation, and controls development

Archimedes

Archimedes is an open-source Python framework designed for deployment of control systems to hardware. To make this possible, it provides a comprehensive toolkit for modeling, simulation, optimization, and C code generation.

For more details, see the documentation site

Key features

By combining the powerful symbolic capabilities of CasADi with the intuitive interface designs of NumPy, PyTorch, and JAX, Archimedes provides a number of key features:

• NumPy-compatible array API with automatic dispatch
• Efficient execution of computational graphs in compiled C++
• Automatic differentiation with forward- and reverse-mode sparse autodiff
• Interface to "plugin" solvers for ODE/DAEs, root-finding, and nonlinear programming
• Automated C code generation for embedded applications
• JAX-style function transformations
• PyTorch-style hierarchical data structures for parameters and dynamics modeling

⚠️ API Stability Notice ⚠️: Archimedes is currently pre-1.0 software. The API is still evolving and may change between minor versions. We'll document breaking changes in the changelog and will follow semantic versioning for 0.X releases, but expect to see some instability until version 1.0 is released.

Examples

Automatic differentiation

import numpy as np
import archimedes as arc

def f(x):
    return np.sin(x**2)

df = arc.grad(f)
np.allclose(df(1.0), 2.0 * np.cos(1.0))

ODE solving with SUNDIALS

import numpy as np
import archimedes as arc


# Lotka-Volterra model
def f(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],
    ])


x0 = np.array([1.0, 1.0])
t_span = (0.0, 10.0)
t_eval = np.linspace(*t_span, 100)

xs = arc.odeint(f, t_span=t_span, x0=x0, t_eval=t_eval)

Constrained optimization

The constrained Rosenbrock problem has a local minimum at (0, 0) and a global minimum at (1, 1)

import numpy as np
import archimedes as arc

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

def g(x):
    g1 = (x[0] - 1) ** 3 - x[1] + 1
    g2 = x[0] + x[1] - 2
    return np.hstack([g1, g2])

x_opt = arc.minimize(f, constr=g, x0=[2.0, 0.0], constr_bounds=(-np.inf, 0))
print(np.allclose(x_opt, [1.0, 1.0], atol=1e-3))

C code generation

Archimedes can convert plain NumPy functions to standalone C code for use in embedded applications:

import numpy as np
import archimedes as arc

def f(x, y):
    return x + np.sin(y)

# Create templates with appropriate shapes and dtypes
x_type = np.zeros((), dtype=float)
y_type = np.zeros((2,), dtype=float)

arc.codegen(f, (x_type, y_type), return_names=("z", ))

For more details, see the tutorial on C code generation

Tutorials

• Hierarchical systems modeling
• C code generation
• Nonlinear system identification
• Hardware development workflow

Examples

The examples folder includes some examples that are not as well-documented as those on the website, but showcase some additional functionality in different application domains. These include:

• Multirotor vehicle dynamics
• CartPole system ID + control
• Subsonic F-16 benchmark
• Trajectory optimization

Installation

Basic setup

The easiest way to install is from PyPI:

pip install archimedes

Test with any of the examples shown above.

Recommended setup

For development (or just a more robust environment configuration), we recommend using UV for faster dependency resolution and virtual environment management:

# Create and activate a virtual environment 
uv venv
source .venv/bin/activate

# Install with minimal dependencies
uv pip install archimedes

# OR install with extras (control, jupyter, matplotlib, etc.)
uv pip install archimedes[all]

To install a Jupyter notebook kernel, if you have installed the additional dependencies with [all] you can run:

uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=archimedes

This will create a kernel named archimedes - you can change the name to whatever you'd like.

Legacy environments

The default package configuration restricts to Python 3.11+, which in turn requires NumPy 2.0+ and cascades to other dependencies. This is primarily for supporting Sphinx 8.2+ for documentation, but isn't a hard constraint on the library itself.

Archimedes itself is compatible back to at least Python 3.9 and NumPy 1.20 and can be force-installed with:

pip install --ignore-requires-python --no-deps archimedes

The other dependencies can then be installed manually with specific versions as needed (you should be able to base these on the specific constraints in pyproject.toml).

This is considered a "legacy" configuration since it is not within the constraints of the actual pyproject.toml configuration, but 3.9/1.20 is tested as a special case in CI.

Source installation

To install from source locally (e.g. for development or building the docs), the recommended procedure is to create a UV virtual environment as described above and then run:

git clone https://github.com/pinetreelabs/archimedes.git
cd archimedes

# Install the package with development dependencies
uv pip install -e ".[all]"
uv sync --all-extras

Testing and development

Development standards outlined in the testing guide include:

• 100% code coverage
• Ruff formatting
• MyPy static type checking
• Vulnerability scanning with pip-audit
• Static analysis for security issues using Bandit
• Licensing compliance with REUSE

Licensing

Archimedes is available under a dual-licensing model:

The open-source code is licensed under the GNU General Public License v3.0. For organizations that would like more flexible licensing contact [e-mail] for details.

Third-Party Components

Archimedes incorporates code from several open source projects, including JAX (Apache 2.0), Flax (Apache 2.0), SciPy (BSD-3), and NumPy (NumPy license). See NOTICE.md for a complete list of attributions, including licenses for key dependencies (CasADi and NumPy).

Citing Archimedes

At this time Archimedes does not have a DOI-linked publication, though a draft is in progress. Feel free to link to the repository in the meantime.

If you use Archimedes in published work, please also consider citing CasADi, the symbolic-numeric backend for Archimedes:

@Article{Andersson2018,
  Author = {Joel A E Andersson and Joris Gillis and Greg Horn
            and James B Rawlings and Moritz Diehl},
  Title = {{CasADi} -- {A} software framework for nonlinear optimization
           and optimal control},
  Journal = {Mathematical Programming Computation},
  Year = {2018},
}

Getting involved

We're excited to build a community around Archimedes - here's how you can get involved at this stage:

• ⭐ Star the Repository: The simplest way to show support and help others discover the project
• 🐛 Report Issues: Detailed bug reports, documentation gaps, and feature requests are invaluable
• 💬 Join Discussions: Share your use cases, ask questions, or provide feedback in our GitHub Discussions
• 🗞️ Stay In the Loop: Subscribe to the newsletter for updates and announcements
• 📢 Spread the Word: Tell colleagues, mention us in relevant forums, or share on social media
• 📝 Document Use Cases: Share how you're using (or planning to use) Archimedes

Contributing

At this early stage of development:

• 👍 We welcome issue reports with specific bugs, documentation improvements, and feature requests
• ⏳ We are not currently accepting pull requests as we establish the project's foundation and architecture
• ❓ We encourage discussions about potential applications, implementation questions, and project direction

If you've built something with Archimedes or are planning to, we definitely want to hear about it! Your real-world use cases directly inform our development priorities.

We appreciate your interest and support!