Mantle

2.0.21 verified Mon Apr 27 auth: no python

The standard library for the Magma hardware DSL, providing core primitives (gates, muxes, registers, memories) for building digital circuits in Python. Current version: 2.0.21, release cadence: irregular.

pip install mantle

Common errors

error ModuleNotFoundError: No module named 'mantle.coreir' ↓

cause Importing from old submodule path that no longer exists in mantle 2.x.

fix

Use 'from mantle import ...' directly instead of 'from mantle.coreir import ...'.

error NameError: name 'DefineAdd' is not defined ↓

cause DefineAdd is not imported; it's in the mantle namespace but not auto-imported.

fix

Add 'from mantle import DefineAdd' or use 'mantle.DefineAdd' after importing mantle.

Warnings

breaking Mantle 1.x APIs changed significantly in 2.0. Many modules (e.g., mantle.coreir, mantle.backend) moved or removed. Always use 'from mantle import ...'. ↓

fix Update imports to match version 2.x patterns: use 'from mantle import Register' instead of 'from mantle.coreir import Register'.

deprecated Mantle 2.0.21 notes that some functions (e.g., DefineAdd, DefineCounter) are considered legacy; consider using magma.ir directly for new designs. ↓

fix Check if mantle provides a direct replacement or use Magma's built-in IR primitives.

gotcha Mantle registers require explicit width parameter (e.g., Register(4)). Forgetting the width will cause errors. ↓

fix Always pass width as first argument: Register(width) or Register(width, init=0).

Imports

mantle
```
import mantle
```
Standard import; used to access mantle primitives like mantle.Register, mantle.DefineCounter, etc.
Register
wrong
```
from mantle.coreir import Register
```
correct
```
from mantle import Register
```
In earlier versions (pre-2.0), mantle was structured differently; direct import from mantle is the current pattern.
DefineCounter
```
from mantle import DefineCounter
```
Commonly used for counter circuits.

Quickstart

Basic circuit using mantle primitives.

import magma
import mantle

# Define a simple circuit: incrementer using a register and adder
class Incrementer(magma.Circuit):
    name = "Incrementer"
    io = magma.IO(I=magma.In(magma.Bits[4]), O=magma.Out(magma.Bits[4]))
    
    reg = mantle.Register(4, init=0)
    adder = mantle.DefineAdd(4)
    
    # Connect: reg_out -> adder b, I -> adder a, adder out -> reg in
    magma.wire(reg.O, adder.b)
    magma.wire(io.I, adder.a)
    magma.wire(adder.out, reg.I)
    magma.wire(reg.O, io.O)

# Compile and simulate (requires fault or other backend)
# magma.compile("build/Incrementer", Incrementer)
print("Circuit defined successfully.")