fault

library4.0.1pypypiunverified

Fault is a Python package for testing hardware designs, forming a core part of the magma ecosystem. It provides a unified, high-level interface to simulate and verify digital circuits directly from Python, supporting various hardware description languages and simulation targets like Verilator and Icarus. Currently at version 4.0.1, Fault is actively maintained with major versions typically introducing significant API improvements and architectural refactorings.

testing devops

pip install fault

github ↗package ↗

INSTALL

IMPORT

SIG · FAULT

fault

testingpythonv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

2/4 runs

py 3.11

✕ build_error

2/4 runs

py 3.12

✕ build_error

2/4 runs

py 3.13

✕ build_error

2/4 runs

py 3.9

✕ build_error

2/4 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Tester

✓ from fault import Tester

MagmaTarget

✓ from fault.magma_target import MagmaTarget

VerilatorTarget

✓ from fault.verilator_target import VerilatorTarget

This quickstart demonstrates how to define a simple Magma circuit, create a `fault.Tester` for it, apply inputs (`poke`), verify outputs (`expect`), and run the simulation using a Verilator target. Note that external simulators like Verilator often require system-level installation in addition to Python packages.

import magma as m import fault # Define a simple circuit using Magma class MyCircuit(m.Circuit): io = m.IO(I=m.In(m.Bit), O=m.Out(m.Bit)) io.O @= io.I # Create a Tester instance for the circuit tester = fault.Tester(MyCircuit) # Poke inputs and expect outputs tester.poke(MyCircuit.I, 1) tester.expect(MyCircuit.O, 1) tester.poke(MyCircuit.I, 0) tester.expect(MyCircuit.O, 0) # Compile and run the test using a target (e.g., Verilator) # Ensure 'verilator' is installed on your system and 'fault-verilator' is installed via pip try: tester.compile_and_run("verilator", magma_output="mlir") print("Test passed successfully with Verilator!") except Exception as e: print(f"Test failed: {e}") print("Make sure 'verilator' is installed and in your PATH, and 'pip install fault-verilator' has been run.")

Debug

Known issues

breakingFault 4.0.0 and higher require Magma 3.0.0 or higher. Older versions of Magma are incompatible and will lead to import errors or unexpected behavior.

fix

Upgrade Magma to the latest 3.x version: `pip install --upgrade magma`.

affects: >=4.0.0

breakingThe package structure underwent a significant refactoring in Fault 3.0.0. Direct imports from internal or deprecated submodules like `fault.core` (which became `fault-core`) may no longer work. Users should rely on top-level imports from `fault`.

fix

Update import statements to use top-level `from fault import ...` or directly import from `fault-core` if low-level components are explicitly needed.

affects: >=3.0.0

breakingThe `Target` API was substantially revised in Fault 2.0.0, affecting how simulation targets are configured and used. Custom targets or direct interaction with `SimulatorTarget` will require updates, and `compile_and_run` method signatures changed.

fix

Consult the `fault` documentation for the 2.x API to adapt custom targets and `compile_and_run` calls.

affects: >=2.0.0

gotchaSimulation targets (e.g., Verilator, Icarus, Eldo) often require both a Python wrapper package (e.g., `fault-verilator`) AND the external simulator executable to be installed on your system and discoverable via your system's PATH.

fix

Ensure the specific `fault-` Python package for your target is installed (e.g., `pip install fault-verilator`), and that the corresponding external simulator executable (e.g., `verilator`) is installed and available in your system's PATH.

affects: All

Upgrade

Version history

4.0.1latest on PyPI · released Dec 7, 2023

Audit

Dependencies

magmarequiredFault is built on the Magma hardware construction language and requires it for circuit definition and compilation.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/leonardt/fault ↗

packagehttps://pypi.org/project/fault/ ↗