Skip to content

Latest commit

 

History

History
264 lines (190 loc) · 4.74 KB

cli_reference.md

File metadata and controls

264 lines (190 loc) · 4.74 KB

VAJAX CLI Reference

The vajax command-line interface provides ngspice-style access to circuit simulation.

Installation

After installing vajax, the CLI is available:

# Install with uv
uv sync

# Verify installation
vajax --version
vajax --help

Basic Usage

# Run simulation on a circuit file
vajax circuit.sim

# Specify output file
vajax circuit.sim -o results.raw

# Run with specific output format
vajax circuit.sim -o results.csv --format csv

Commands

run (default)

Run circuit simulation. This is the default command when a circuit file is provided.

# These are equivalent:
vajax circuit.sim
vajax run circuit.sim

Options:

Option Description
-o, --output FILE Output file path (default: circuit.raw)
-f, --format FMT Output format: raw, csv, json (default: raw)
--tran DT TSTOP Override transient analysis parameters
--ac TYPE PTS FSTART FSTOP AC analysis (dec/lin/oct, points, freq range)
--sparse Force sparse solver (for large circuits)
--no-scan Disable lax.scan (use Python loop)
--gpu Force GPU backend
--cpu Force CPU backend
--x64 Force float64 precision
--x32 Force float32 precision
--profile Enable profiling

Examples:

# Transient analysis with custom parameters
vajax circuit.sim --tran 1n 100u

# AC analysis
vajax circuit.sim --ac dec 100 1k 1G

# Large circuit with sparse solver on GPU
vajax large_circuit.sim --sparse --gpu

# Force float64 precision on CPU
vajax circuit.sim --cpu --x64

benchmark

Run benchmark circuits from the VACASK test suite.

# List available benchmarks
vajax benchmark --list

# Run a specific benchmark
vajax benchmark ring

# Run with profiling
vajax benchmark ring --profile

Options:

Option Description
-l, --list List available benchmarks
--sparse Force sparse solver
--x64 Force float64 precision
--x32 Force float32 precision
--profile Enable timing profiling

convert

Convert SPICE netlists to VACASK format.

vajax convert input.sp output.sim

info

Display system information.

vajax info

Shows:

  • JAX backend (CPU, CUDA, Metal)
  • Float64 support status
  • Available devices

Output Formats

Raw (ngspice-compatible)

Binary format compatible with ngspice tools and gwave waveform viewer.

vajax circuit.sim -o results.raw --format raw

Read with ngspice:

ngspice> load results.raw
ngspice> plot v(out)

Read with gwave:

gwave results.raw

CSV

Comma-separated values, compatible with spreadsheets and data analysis tools.

vajax circuit.sim -o results.csv --format csv

Format:

time,node1,node2,...
0.0,0.0,1.2,...
1e-9,0.1,1.1,...

JSON

JSON format for programmatic processing.

vajax circuit.sim -o results.json --format json

Format:

{
  "times": [0.0, 1e-9, ...],
  "voltages": {
    "node1": [0.0, 0.1, ...],
    "node2": [1.2, 1.1, ...]
  }
}

Environment Variables

Variable Description
JAX_PLATFORMS Force JAX platform: cpu, cuda, gpu
JAX_ENABLE_X64 Enable float64: 1 or 0
NGSPICE_BIN Path to ngspice binary (for convert)

Examples

Transient Analysis

# Basic transient simulation
vajax ring_oscillator.sim --tran 1n 10u

# Large circuit with sparse solver
vajax c6288.sim --tran 1n 100n --sparse

# GPU acceleration
vajax ring_oscillator.sim --gpu --tran 1n 10u

AC Analysis

# Decade sweep, 100 points per decade
vajax amplifier.sim --ac dec 100 1k 1G

# Linear sweep
vajax filter.sim --ac lin 1000 1k 10k

Benchmarking

# Run ring oscillator benchmark with profiling
vajax benchmark ring --profile

# Compare sparse vs dense solver
vajax benchmark mul --profile
vajax benchmark mul --profile --sparse

Batch Processing

# Process multiple circuits
for f in circuits/*.sim; do
    vajax "$f" -o "results/$(basename "$f" .sim).raw"
done

Troubleshooting

GPU Not Detected

# Check system info
vajax info

# Force CPU fallback
vajax circuit.sim --cpu

Convergence Issues

For difficult circuits, try:

# Use sparse solver for better conditioning
vajax circuit.sim --sparse

# Force double precision
vajax circuit.sim --x64

Out of Memory

For large circuits:

# Use sparse solver (required for >1000 nodes)
vajax large_circuit.sim --sparse

See Also