pyCircuit 6

Python-first hardware construction and architecture modeling, backed by MLIR, deterministic C++ simulation, and Verilog generation.

pyCircuit provides two complementary Python frontends in one versioned toolchain:

• pycircuit constructs cycle-aware, synthesizable hardware from signals, state, hierarchy, memories, and explicit logical cycles.
• agentic_circuit models architecture-level processes, queues, resources, scheduling, and committed state through ACPy and ACIR.

Both paths converge on verified PYC MLIR when generating hardware. C++ and Verilog therefore share one semantic contract rather than separate handwritten implementations.

Highlights

• Cycle-aware signals with automatic pipeline balancing
• Structural and cycle-aware authoring on one verified PYC representation
• Preserved module hierarchy and deterministic generated artifacts
• Exact-width values, typed structures, queues, tables, and memories
• C++ cycle simulation, gfsim architecture simulation, and Verilog generation
• Focused pull-request gates plus reproducible release closure

Choose a frontend

You want to describe	Install	Import	Primary flow
Ports, signals, registers, memories, pipelines, and synthesizable hardware	pycircuit-hisi	pycircuit	Python → PYC → pycc → C++ / Verilog
Processes, queues, resources, scheduling, and architecture state	agentic-circuit	agentic_circuit	Python → ACPy 0.5 → ACIR → ACSim/gfsim or PYC

Read Choose a Frontend for the supported authoring boundaries and examples.

Quick start

The integrated development setup requires Python 3.11 or later, CMake, Ninja, and LLVM/MLIR 22.1.8. pyCircuit-only frontend use supports Python 3.10 or later.

git clone https://github.com/PTO-ISA/pyCircuit.git
cd pyCircuit

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e "python/semantic-core"
python -m pip install -e ".[dev,docs]"

bash flows/scripts/pyc build
export PYC_TOOLCHAIN_ROOT="$PWD/.pycircuit_out/toolchain/install"

Build the counter example with the C++ and Verilog backends:

PYTHONPATH=python/pycircuit/src \
python -m pycircuit.cli build \
  examples/pycircuit/basics/counter/tb_counter.py \
  --out-dir .pycircuit_out/quickstart/counter \
  --target both \
  --jobs 8

Add the architecture-modeling frontend when needed:

python -m pip install -e "python/agentic-circuit[test]"
agentic-circuit --help

Continue with the Quickstart or the complete installation guide.

How the toolchain fits together

agentic_circuit frontend -> ACPy 0.5 -> ACIR
                                         |-> ACSim -> gfsim
                                         `-> PYC -> pycc -> pyc6 C++ / Verilog

pycircuit frontend -> Cycle-Aware Signal -> PYC -> pycc -> pyc6 C++ / Verilog

ACIR remains an architecture-level dialect; PYC remains the shared hardware contract. The pycircuit and agentic_circuit Python namespaces are separate and are not compatibility aliases.

Documentation

Start here	Purpose
Getting Started	Install the toolchain and run the first design
pyCircuit 6 Tutorial	Learn cycle-aware authoring and testbenches
Language and API Reference	Look up syntax, APIs, diagnostics, primitives, and PYC IR
Architecture	Understand frontends, compiler stages, runtimes, and backends
Agentic Circuit and ACIR	Learn ACPy, ACIR/ACSim, QueueGraph, and gfsim
Development Guide	Build, test, contribute, and prepare pull requests
Agent Frontend Guide	Choose and apply a Pythonic authoring model for complex circuits

Repository layout

The tree is organized by responsibility:

python/       Python distributions and shared semantics
compiler/     PYC and ACIR/ACSim dialects, passes, and generators
library/      Stable pyCircuit C++ runtime and Verilog implementations
simulator/    gfsim architecture-modeling runtime
docs/         User, architecture, reference, and contributor documentation
examples/     Small supported examples
benchmarks/   Performance-only workloads and harnesses
tests/        Unit, system, integration, MLIR, C++, Verilog, and golden tests
tools/        User-facing and product-maintenance utilities
flows/        Build, CI, gate, and release orchestration
schemas/      Machine-readable contracts, inventories, and registries
packaging/    SDK, archive, and wheel assembly
toolchains/   Pinned compiler and dependency identities

See Repository Layout for the complete ownership map, including .github/, cmake/, and third_party/. Complete CPU, NPU, accelerator, SoC, board, ISA, and product-specific testbench sources live in their owning consumer repositories.

Validate a change

Run the lightweight repository checks first:

pre-commit run --all-files
pytest tests/unit -m unit
python tools/agentic-circuit/check-contracts.py
mkdocs build --strict

Native compiler or runtime changes also require the narrowest affected MLIR, C++, simulation, or backend test. The full release matrix runs through the release workflow rather than every pull request.

See Testing and Gates for the exact change-to-gate mapping.

Project status

PTO-ISA/pyCircuit is the canonical source, issue tracker, and release authority. The latest published release is available from GitHub Releases. The distribution name is pycircuit-hisi; the Python import remains pycircuit.

The former standalone Agentic Circuit repository is archived provenance. Its consolidation record is preserved in the historical repository record, not as an active development or compatibility path.

Contributing and security

• Contributing guide
• Development workflow
• Review and merge requirements
• Security policy
• Code of conduct

License

pyCircuit and the integrated Agentic Circuit sources are licensed under the BSD 3-Clause License.