wave-view 1.0.0

A Python package for visualizing SPICE simulation waveforms in Jupyter notebooks

Wave View: A Python Toolkit for SPICE Simulation Waveform Visualization

Wave View is a lightweight yet powerful Python toolkit that transforms raw SPICE .raw files into beautiful, interactive Plotly figures with minimal code. It reads simulation traces straight into a plain {signal_name: np.ndarray} dictionary, lets you define multi-axis plots declaratively via YAML (or override them on the command line), and automatically selects the best renderer whether you are in a Jupyter notebook, VS Code, or a headless CI job. Case-insensitive signal lookup, engineering-notation tick labels, and first-class multi-strip support help you focus on circuit analysis rather than plotting boilerplate.

Features

• Interactive Plotly Visualization: Modern, web-based plots with zoom, pan, and hover
• YAML Configuration: Flexible, reusable plotting configurations
• Simple API: Plot waveforms with a single function call
• Command Line Interface: Quick plotting from terminal with wave_view plot
• Automatic Environment Detection: Auto-detection and inline plotting for Jupyter Notebooks, render in browser when running in standalone Python scripts.

Quick Start

Installation

Option 1: Install from PyPI

pip install wave_view

Option 2: Install from GitHub (Latest)

# Install latest version directly from GitHub
pip install git+https://github.com/Jianxun/wave_view.git

# Or install a specific branch/tag
pip install git+https://github.com/Jianxun/wave_view.git@main
pip install git+https://github.com/Jianxun/wave_view.git@v1.0.0

Option 3: Development Installation

# Clone the repository
git clone https://github.com/Jianxun/wave_view.git
cd wave_view

# Create and activate virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode (editable install)
pip install -e .

# Install development dependencies (optional)
pip install -r requirements-dev.txt

Basic Usage

This quick example demonstrates the three-step workflow:

• Load the simulation data.
• Build a declarative PlotSpec.
• Call wave_view.plot to render the figure.

Note that the y section is always provided as a list ("-"); even if you only have a single Y-axis group you must wrap it in a list so the same schema works seamlessly for multi-strip plots.

import wave_view as wv

data, metadata = wv.load_spice_raw('')
spec = wv.PlotSpec.from_yaml("""
title: "Transient Analysis"
x: 
  label: "Time (s)"
  signal: "time"
y:
  - label: "Voltage (V)"
    signals:
      OUT: "v(out)"
      IN:  "v(in)"
""")

fig = wv.plot(data, spec)
fig.show()

Command Line Interface

Wave View ships with a convenient wave_view executable that mirrors the high-level Python API so you can explore data and generate plots straight from the terminal—perfect for quick checks in CI pipelines or when you don't want to open a notebook.

Key subcommands:

• wave_view plot – Render a figure from a SPICE .raw file plus a YAML spec. Supports on-the-fly overrides such as --title, --theme, --width, --height, and can save to HTML/PNG/PDF/SVG via --output.
• wave_view signals – List the available signal names inside a raw file with an optional --limit for quick inspection.

Each subcommand accepts --help to show all options, and the root command (wave_view --help) prints version information and global flags.

# Plot with specification file
wave_view plot simulation.raw --spec config.yaml

# Plot with custom options
wave_view plot simulation.raw --spec config.yaml --title "My Analysis" --theme plotly_dark

# Save to file
wave_view plot simulation.raw --spec config.yaml --output plot.html

# List available signals
wave_view signals simulation.raw
wave_view signals simulation.raw --limit 20

# Get help
wave_view --help
wave_view plot --help

Advanced Usage

For heavier workflows you can work directly with the returned dictionary of NumPy arrays: slice signals, run vectorised math, or attach completely new keys generated by any Python code.

Because the dictionary preserves insertion order (Python ≥ 3.7) and Wave View ignores letter-case when looking up keys, your additions flow straight into the plotting pipeline with zero friction.

Heads-up: if you intend to plot against an independent variable that isn't the default one stored in the raw file (e.g. sweep index instead of time, or a custom frequency array), you must inject that array into data and reference it in x.signal so Wave View knows what to use on the X-axis.

import numpy as np, wave_view as wv

# Pre-load data for inspection or heavy processing
data, _ = wv.load_spice_raw("simulation.raw")
print(f"Signals → {list(data)[:10]}")

# Create a derived signal
data["power"] = data["v(out)"] * data["i(out)"]

spec = wv.PlotSpec.from_yaml("""
x:
  label: "Time (s)"
  signal: "time"
y:
  - label: "Voltage (V)"
    signals:
      OUT:   "v(out)"
  - label: "Power (W)"
    signals:
      Power: "power"
""")

fig = wv.plot(data, spec)
fig.show()

Configuration Validation

PlotSpec uses Pydantic, so validation happens automatically when you call PlotSpec.from_yaml or PlotSpec.model_validate. Invalid specs raise ValidationError with helpful messages.

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/Jianxun/wave_view.git
cd wave_view

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e .
pip install -r requirements-dev.txt

# Verify development setup
python -c "import wave_view as wv; print('Development setup complete!')"

Run Tests

# Run all tests
pytest

# With coverage
pytest --cov=wave_view --cov-report=html

# Run specific test file
pytest tests/workflows/test_cli_plot.py -v

Project Structure

wave_view/
├── src/wave_view/
│   ├── core/
│   │   ├── plotspec.py      # PlotSpec model
│   │   ├── plotting.py      # Plotting helpers + plot()
│   │   └── wavedataset.py   # WaveDataset + low-level loaders
│   ├── loader.py            # load_spice_raw convenience wrapper
│   ├── cli.py               # Command-line interface
│   └── __init__.py          # Public symbols (plot, PlotSpec, load_spice_raw,...)
├── tests/                   # Test suite
├── examples/                # Usage examples
├── docs/                    # Documentation
└── pyproject.toml           # Packaging

Requirements

• Python: 3.8+
• Core Dependencies:
  • plotly >= 5.0.0 (Interactive plotting)
  • numpy >= 1.20.0 (Numerical operations)
  • PyYAML >= 6.0 (Configuration files)
  • spicelib >= 1.0.0 (SPICE file reading)
  • click >= 8.0.0 (Command line interface)

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Comprehensive documentation is available with:

• User Guides: Installation, quickstart, and configuration
• API Reference: Complete function documentation
• Examples: Practical use cases and tutorials
• Development: Contributing guidelines and setup

Build Documentation Locally

# Install documentation dependencies
pip install -e ".[docs]"

# Build documentation
make docs

# Serve documentation locally
make docs-serve  # Opens at http://localhost:8000

Links

• Documentation: [Local Build Available]
• PyPI Package: [Coming Soon]
• Issue Tracker: GitHub Issues
• Changelog: CHANGELOG.md

Version

Current version: 0.1.0 (Alpha)

---

Wave View - Making SPICE waveform visualization simple and interactive! 🌊📈