A Python CLI tool for generating random SPICE (Simulation Program with Integrated Circuits Emphasis) netlists with configurable device types, connectivity guarantees, and ngspice simulation integration.
- Random Circuit Generation: Creates connected circuits with guaranteed connectivity using graph-based algorithms
- Complete Device Support: 8 device types - resistors, capacitors, inductors, voltage/current sources, diodes, BJTs, and MOSFETs
- Ngspice Integration: Built-in ngspice simulation with automatic model definitions and analysis commands
- Realistic Device Parameters: MOSFETs include W/L dimensions and optional area/perimeter parameters (AD/AS/PD/PS)
- Automatic Model Inclusion: Standard SPICE models for diodes, BJTs, and MOSFETs (NMOS/PMOS)
- Flexible Naming Conventions: Numeric (R1, C2), alphabetic (Ra, Cb), mixed (1a, 2b), or random naming
- Comprehensive Line Formats: Single-line, multi-line (+/\ continuation), tabular columns, compact, traditional SPICE style, mixed
- Writing Styles: Compact, standard, or verbose formatting with detailed comments
- Connectivity Guarantee: Advanced graph-based connectivity ensures all circuits are properly connected, with special handling for inductors to prevent singular matrix errors
- Reproducible Generation: Optional random seed for consistent, repeatable results
- CLI Interface: Comprehensive command-line interface with extensive customization options
# Clone the repository
git clone https://github.com/SJTU-YONGFU-RESEARCH-GRP/spice_netlist_generator.git
cd spice_netlist_generator
# Install in development mode
pip install -e .
# For development with all optional dependencies
pip install -e ".[dev]"Requirements:
- Python 3.10+
- ngspice (optional, for simulation features)
Development Requirements:
- pytest (testing)
- ruff (linting and formatting)
- mypy (type checking)
from netlist_generator.generator import RandomNetlistGenerator, NetlistConfig, DeviceType
# Create a configuration
config = NetlistConfig(
device_types=[DeviceType.RESISTOR, DeviceType.CAPACITOR, DeviceType.VOLTAGE_SOURCE],
num_devices=5,
seed=42 # For reproducible results
)
# Create generator
generator = RandomNetlistGenerator(config)
# Generate a random netlist
netlist = generator.generate_netlist()
print(netlist)Command Line Usage:
# Quick random netlist with 3 device types and 10 devices
python src/main.py -t 3 -n 10
# Custom device types with voltage source
python src/main.py -d r,c,v -n 10 -o my_circuit.cir
# Generate and run ngspice simulation (default dc_tran analysis)
python src/main.py -d r,c,l,v,i,d,q,m -n 15 --run-ngspiceThe generator includes built-in ngspice simulation capabilities with automatic analysis execution and result display.
# Generate and simulate with default OP analysis
python src/main.py -t 3 -n 10 --run-ngspice
# Run AC small-signal analysis
python src/main.py -d r,c,l,v -n 15 --run-ngspice --analysis-type ac
# Run transient time-domain analysis
python src/main.py -t 4 -n 20 --run-ngspice --analysis-type tran
# Run DC sweep analysis
python src/main.py -d r,c,v -n 10 --run-ngspice --analysis-type dc- dc_tran (default): Combined DC sweep and transient analysis for comprehensive circuit testing
- op: Operating point analysis - finds DC operating points and displays all node voltages/currents
- ac: AC small-signal analysis - frequency sweep from 1Hz to 1MHz with decade spacing
- tran: Transient analysis - time-domain simulation from 0 to 10ms with 1µs steps
- dc: DC sweep analysis - voltage source V1 sweep from 0V to 10V
To use ngspice simulation features:
Ubuntu/Debian:
sudo apt update
sudo apt install ngspicemacOS:
brew install ngspiceWindows: Download from the ngspice website
After generating a netlist, you can also run ngspice interactively:
# Generate a netlist
python src/main.py -t 3 -n 10 -o my_circuit.cir
# Run ngspice interactively on the generated netlist
ngspice my_circuit.cir
# Inside ngspice, you can run commands like:
# op # Operating point analysis
# ac dec 10 1 1MEG # AC analysis
# tran 1u 10m # Transient analysis
# plot v(out) # Plot results
# quit # ExitThe package includes a comprehensive command-line interface. You can use either the Python script directly or the shell script wrapper.
# Quick random netlist (3 random device types, 10 devices)
python src/main.py -t 3 -n 10
# Specify exact device types
python src/main.py -d r,c,v -n 10 -o circuit.cir
# Use the shell script wrapper (Linux/macOS/Windows WSL)
./netlist_generator.sh -t 4 -n 15 --run-ngspice# Generate with specific formatting and naming
python src/main.py -d r,c,l,v,i,d,q,m -n 20 \
--naming alphabetic \
--format multi_plus \
--style verbose \
--seed 42
# Disable comments and analysis commands
python src/main.py -d r,c,v -n 10 --no-comments --no-analysis
# Randomize comment inclusion
python src/main.py -d r,c,d,q -n 15 --random-commentsThe generator supports three writing styles that control the level of detail and formatting in the generated netlists.
Minimal formatting with essential information only:
* Random SPICE Netlist
Vbrn 0 1 SIN(0
+ 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
.OP
.END
Balanced formatting with basic comments and analysis commands:
* Random SPICE Netlist
* Generated with 5 devices
* Device types: R, C, V
R1 0 1 1k ; R device
C1 1 0 1u ; C device
V1 0 1 DC 5 ; V device
.OP
.AC DEC 10 1 1MEG
.TRAN 1u 10m
.END
Detailed formatting with extensive comments and explanations:
* Random SPICE Netlist
* Generated with 5 devices
* Device types: R, C, V
* Naming: numeric
* Format: multi_plus
R1 0 1 1k ; R device
C1 1 0 1u ; C device
V1 0 1 DC 5 ; V device
* Analysis Commands
* .OP performs a DC operating point analysis
.OP
* .AC performs AC small-signal analysis
.AC DEC 10 1 1MEG
* .TRAN performs transient analysis
.TRAN 1u 10m
.END
The generator supports 7 different line formatting styles that control how SPICE netlist lines are structured:
Vbrn 0 1 SIN(0 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Vbrn 0 1 SIN(0
+ 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Vbrn 0 1 SIN(0 \
9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Vbrn 0 1 SIN(0 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Vbrn 0 1 SIN(0 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Vbrn 0 1 SIN(0 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Vbrn 0 1 SIN(0
+ 9.0 1524) ; V device
Lbfo 1 0 2.1m ; L device
Generate various types of random circuits:
# Simple RC circuit
python src/main.py -d r,c,v -n 5 -o rc_circuit.cir
# Complex analog circuit with all device types
python src/main.py -d r,c,l,v,i,d,q,m -n 15 --style verbose
# Digital circuit with MOSFETs
python src/main.py -d m,v -n 8 --naming alphabetic -o digital.cir
# Reproducible circuit generation
python src/main.py -d r,c,d,q -n 10 --seed 42 -o reproducible.cir
# Generate with different line formats
python src/main.py -d r,c,v -n 8 --format tabular -o tabular.cir
python src/main.py -d r,c,v -n 8 --format compact -o compact.cir
python src/main.py -d r,c,v -n 8 --format traditional -o traditional.cir
# Generate with mixed analysis (DC sweep + transient)
python src/main.py -d r,c,l,v -n 12 --run-ngspiceThe NetlistConfig dataclass supports the following options:
device_types: List of device types to include (required)num_devices: Number of devices to generate (required)naming_convention: Component naming style - NUMERIC, ALPHABETIC, MIXED, or RANDOM (default: NUMERIC)line_format: Line formatting style - SINGLE_LINE, MULTI_LINE_PLUS, MULTI_LINE_BACKSLASH, TABULAR, COMPACT, TRADITIONAL, MIXED (default: SINGLE_LINE)writing_style: Overall formatting style - COMPACT, STANDARD, or VERBOSE (default: STANDARD)include_comments: Whether to include explanatory comments (default: True)include_analysis: Whether to include analysis commands (.OP, .AC, .TRAN) (default: True)analysis_type: Type of analysis commands to include - op, ac, tran, dc, dc_tran (default: dc_tran)seed: Random seed for reproducible generation (optional)
spice_netlist_parser/
├── src/
│ ├── __init__.py
│ ├── main.py # CLI entry point
│ └── netlist_generator/
│ ├── __init__.py
│ └── generator.py # Core generator logic
├── tests/
│ ├── __init__.py
│ ├── conftest.py
│ ├── test_generator.py
│ ├── test_main.py
│ └── test_main.py.backup
├── examples/
│ ├── 100.sp
│ ├── 1k.sp
│ ├── 10k.sp
│ ├── 100k.sp
│ └── 1m.sp
├── dist/
│ ├── spice_netlist_generator-1.0.0-py3-none-any.whl
│ └── spice_netlist_generator-1.0.0.tar.gz
├── htmlcov/ # HTML coverage reports
├── pyproject.toml # Project configuration
├── netlist_generator.sh # Shell script wrapper
├── test.cir # Example generated netlist
├── coverage.xml # Coverage report
├── LICENSE
└── README.md
Generated netlists can be simulated using various SPICE simulators:
- LTspice: Free Windows-based SPICE simulator with schematic capture
- ngspice: Open-source command-line SPICE simulator
- PSpice: Commercial SPICE simulator from Cadence
- HSPICE: High-performance commercial SPICE simulator
# Install in development mode
pip install -e .
# Install development dependencies (if available)
pip install -e ".[dev]"# Run tests (when test suite is available)
pytest
# Run tests with coverage
pytest --cov=src --cov-report=html# Format code with ruff
ruff format src/
# Check code quality and style
ruff check src/
# Type checking
mypy src/
# Run tests with coverage
pytest --cov=src --cov-report=htmlThe project uses GitHub Actions for comprehensive continuous integration:
- Tests (
tests.yml): Multi-version testing (3.10, 3.11, 3.12) with coverage - Code Quality (
code-quality.yml): Linting, formatting, type checking, and pre-commit hooks - Security (
security.yml): Weekly security scanning with Bandit and Safety - Release (
release.yml): Automated PyPI publishing on version tags
- Linting: Ruff for code style and quality
- Formatting: Automated code formatting checks
- Type Checking: MyPy for static type analysis
- Testing: Pytest with 80%+ coverage requirement
- Security: Bandit security linting and dependency vulnerability checks
- Import Checks: Verification that all imports work correctly
# Install development dependencies
pip install -e ".[dev]"
# Run pre-commit hooks locally
pre-commit install
pre-commit run --all-files
# Run the full CI pipeline locally
./netlist_generator.sh test
# Run all quality checks
./netlist_generator.sh quality
# Or run individual components
./netlist_generator.sh lint # Code linting
./netlist_generator.sh format # Code formatting
./netlist_generator.sh typecheck # Type checking
pytest tests/ # Run tests
ruff check src/ # Manual linting
mypy src/ # Manual type checking
bandit -r src/- Dependabot: Weekly dependency updates for pip and GitHub Actions
- Security Scanning: Weekly vulnerability checks
- Code Coverage: Automated reporting to Codecov
# From project root
python src/main.py [options]
# Using the shell script
./netlist_generator.sh [options]- Fork the repository: https://github.com/SJTU-YONGFU-RESEARCH-GRP/spice_netlist_generator
- Create a feature branch (
git checkout -b feature/amazing-feature) - Set up development environment:
pip install -e ".[dev]" pre-commit install - Add tests for new functionality
- Run quality checks:
pre-commit run --all-files pytest tests/
- Ensure all CI checks pass
- Submit a pull request
- All code must pass CI checks (linting, tests, type checking)
- Maintain 80%+ test coverage
- Add type annotations for all new functions
- Include comprehensive docstrings
- Update documentation for API changes
This project is licensed under the Creative Commons Attribution 4.0 International License - see the LICENSE file for details.
- SPICE was originally developed at UC Berkeley
- Thanks to the open-source SPICE community for continued development
- Built with modern Python practices and comprehensive type annotations