Skip to content

Getting Started

Documentation Home | 中文

This guide gets the repository running without requiring any external PDK.

Requirements

  • Python 3.10 or newer.
  • uv is recommended for environment management; standard venv and pip remain supported.
  • The sole compute engine, circuitopt_core, is a compiled Rust extension (package circuitopt-core, pinned exactly by version). Building it from this repository checkout needs a Rust toolchain (rustup) and a C compiler for the vendored BSIM4.5 sources — see "Build the Compiled Core" below. Installing a released wheel instead (from the project's GitHub Releases page) needs neither.
  • Optional PDK files and external tools only for the corresponding silicon process. See the PDK Support Matrix.

Build the Compiled Core

From a repository checkout, circuitopt-core is not on PyPI yet (see the project's GitHub Releases page for prebuilt wheels), so install rustup first, then build and install the extension into the active virtual environment before installing the Python package below:

python -m pip install "maturin>=1.14,<2.0"
maturin develop --release -m rust/crates/co-py/Cargo.toml

This compiles the vendored Berkeley BSIM4.5 C sources once (via the cc crate) and installs circuitopt_core as an editable package. Re-run it after pulling Rust changes.

Install With uv

From the repository root, after the compiled core above is installed into the active environment:

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

circuit-optimization pins circuitopt-core to an exact version; pip/uv resolve that pin against the extension already installed above rather than fetching it from an index.

Install the development and test dependencies when modifying the project:

uv pip install -e ".[dev]"

Useful optional groups:

uv pip install -e ".[ml]"       # scikit-learn surrogate
uv pip install -e ".[torch]"    # differentiable PyTorch surrogate
uv pip install -e ".[plot]"     # matplotlib plotting
uv pip install -e ".[serve]"    # FastAPI and uvicorn
uv pip install -e ".[mcp]"      # Model Context Protocol server
uv pip install -e ".[parquet]"  # Parquet dataset export

Install With Standard venv

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "maturin>=1.14,<2.0"
maturin develop --release -m rust/crates/co-py/Cargo.toml
python -m pip install -e .

Verify the Core Installation

The passive RC example needs no transistor model or PDK:

circuit-opt run examples/periodic_rc.json --analysis ac,noise

Run all analyses configured in that JSON:

circuit-opt run examples/periodic_rc.json

The package module entry is equivalent:

python -m circuitopt run examples/periodic_rc.json --analysis ac,noise

For a test-level check:

pytest -q tests/test_cli_subcommands.py tests/test_periodic_solvers.py

Run a Transistor Example

The default transistor process is the built-in AT4000TG PMOS model. examples/single_stage.json has no analyses block of its own (it is set up for the explore/dataset workflows below), so circuit-opt run does not apply to it; a process-corner sweep does, and prints gain/bandwidth/noise directly:

circuit-opt corners examples/single_stage.json

Other processes are selected per device through the JSON models field. They are not global simulator switches. See the Circuit JSON Format and PDK Support Matrix.

Typical Workflows

# Design-space exploration
circuit-opt explore examples/afe_explore.json -n 200 --seed 1

# Process corners for the circuit's configured process
circuit-opt corners examples/afe_explore.json

# AT4000TG mismatch Monte Carlo
circuit-opt mc examples/afe_explore.json -n 100 --seed 1

# Build a surrogate dataset
circuit-opt dataset examples/single_stage.json -n 500 --out results/datasets/single

# Start the optional local API
circuit-opt serve

# Start the optional stdio MCP server for an LLM client
circuit-opt mcp --workspace .

See the CLI Reference before applying a workflow to a silicon PDK: corner and mismatch support differs by backend.

Paths and Portability

The project does not require machine-specific absolute paths in circuit JSON. Resolution follows explicit environment variables, the active virtual environment, the project .venv, and documented project-local conventions.

Common variables:

Variable Purpose
PDK_ROOT Root for FreePDK45, or SKY130 used for explicit card extraction
SKY130_CARD_DIR Additional resolved SKY130 BSIM4 cards
TSMC28_MODEL_DIR Directory containing the supported TSMC HSPICE model file
TSMC28_PDK_ROOT Outer TSMC iPDK or delivery root
NGSPICE_BIN Explicit ngspice executable for oracle comparisons/card extraction

Do not commit licensed model files, generated model cards, local virtual environments, or simulator caches.

Where to Go Next