# Wave View: A Python Toolkit for SPICE Simulation Waveform Visualization
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
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
```bash
pip install wave_view
```
#### Option 2: Install from GitHub (Latest)
```bash
# 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
```bash
# 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.
```python
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.
```bash
# 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.
```python
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
```bash
# 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
```bash
# 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](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
```bash
# 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](https://github.com/Jianxun/wave_view/issues)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
## Version
Current version: **0.1.0** (Alpha)
---
**Wave View** - Making SPICE waveform visualization simple and interactive! 🌊📈
Raw data
{
"_id": null,
"home_page": null,
"name": "wave-view",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jianxun Zhu <jianxun.zhu@example.com>",
"keywords": "spice, simulation, waveform, visualization, jupyter, eda",
"author": null,
"author_email": "Jianxun Zhu <jianxun.zhu@example.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/bb/e718b840ebfc9c64c5a488b461eea4e84dbd4a304bd030b7b7a9c8d746f9/wave_view-1.0.1.tar.gz",
"platform": null,
"description": "# Wave View: A Python Toolkit for SPICE Simulation Waveform Visualization\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nWave 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.\n\n\n\n## Features\n\n- **Interactive Plotly Visualization**: Modern, web-based plots with zoom, pan, and hover\n- **YAML Configuration**: Flexible, reusable plotting configurations\n- **Simple API**: Plot waveforms with a single function call\n- **Command Line Interface**: Quick plotting from terminal with `wave_view plot`\n- **Automatic Environment Detection**: Auto-detection and inline plotting for Jupyter Notebooks, render in browser when running in standalone Python scripts.\n\n## Quick Start\n\n### Installation\n\n#### Option 1: Install from PyPI\n```bash\npip install wave_view\n```\n\n#### Option 2: Install from GitHub (Latest)\n```bash\n# Install latest version directly from GitHub\npip install git+https://github.com/Jianxun/wave_view.git\n\n# Or install a specific branch/tag\npip install git+https://github.com/Jianxun/wave_view.git@main\npip install git+https://github.com/Jianxun/wave_view.git@v1.0.0\n```\n\n#### Option 3: Development Installation\n```bash\n# Clone the repository\ngit clone https://github.com/Jianxun/wave_view.git\ncd wave_view\n\n# Create and activate virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode (editable install)\npip install -e .\n\n# Install development dependencies (optional)\npip install -r requirements-dev.txt\n```\n\n### Basic Usage\nThis quick example demonstrates the three-step workflow:\n- Load the simulation data.\n- Build a declarative `PlotSpec`.\n- Call `wave_view.plot` to render the figure. \n\nNote 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.\n\n```python\nimport wave_view as wv\n\ndata, metadata = wv.load_spice_raw('')\nspec = wv.PlotSpec.from_yaml(\"\"\"\ntitle: \"Transient Analysis\"\nx: \n label: \"Time (s)\"\n signal: \"time\"\ny:\n - label: \"Voltage (V)\"\n signals:\n OUT: \"v(out)\"\n IN: \"v(in)\"\n\"\"\")\n\nfig = wv.plot(data, spec)\nfig.show()\n```\n\n### Command Line Interface\n\nWave 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\u2014perfect for quick checks in CI pipelines or when you don't want to open a notebook.\n\nKey subcommands:\n\n- `wave_view plot` \u2013 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`.\n- `wave_view signals` \u2013 List the available signal names inside a raw file with an optional `--limit` for quick inspection.\n\nEach subcommand accepts `--help` to show all options, and the root command (`wave_view --help`) prints version information and global flags.\n\n```bash\n# Plot with specification file\nwave_view plot simulation.raw --spec config.yaml\n\n# Plot with custom options\nwave_view plot simulation.raw --spec config.yaml --title \"My Analysis\" --theme plotly_dark\n\n# Save to file\nwave_view plot simulation.raw --spec config.yaml --output plot.html\n\n# List available signals\nwave_view signals simulation.raw\nwave_view signals simulation.raw --limit 20\n\n# Get help\nwave_view --help\nwave_view plot --help\n```\n\n### Advanced Usage\n\nFor 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.\n\nBecause the dictionary preserves insertion order (Python \u2265 3.7) and Wave View ignores letter-case when looking up keys, your additions flow straight into the plotting pipeline with zero friction.\n\n> **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.\n\n```python\nimport numpy as np, wave_view as wv\n\n# Pre-load data for inspection or heavy processing\ndata, _ = wv.load_spice_raw(\"simulation.raw\")\nprint(f\"Signals \u2192 {list(data)[:10]}\")\n\n# Create a derived signal\ndata[\"power\"] = data[\"v(out)\"] * data[\"i(out)\"]\n\nspec = wv.PlotSpec.from_yaml(\"\"\"\nx:\n label: \"Time (s)\"\n signal: \"time\"\ny:\n - label: \"Voltage (V)\"\n signals:\n OUT: \"v(out)\"\n - label: \"Power (W)\"\n signals:\n Power: \"power\"\n\"\"\")\n\nfig = wv.plot(data, spec)\nfig.show()\n```\n\n### Configuration Validation\n\nPlotSpec uses Pydantic, so validation happens automatically when you call ``PlotSpec.from_yaml`` or ``PlotSpec.model_validate``. Invalid specs raise ``ValidationError`` with helpful messages.\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/Jianxun/wave_view.git\ncd wave_view\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode with all dependencies\npip install -e .\npip install -r requirements-dev.txt\n\n# Verify development setup\npython -c \"import wave_view as wv; print('Development setup complete!')\"\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npytest\n\n# With coverage\npytest --cov=wave_view --cov-report=html\n\n# Run specific test file\npytest tests/workflows/test_cli_plot.py -v\n```\n\n\n## Project Structure\n\n```\nwave_view/\n\u251c\u2500\u2500 src/wave_view/\n\u2502 \u251c\u2500\u2500 core/\n\u2502 \u2502 \u251c\u2500\u2500 plotspec.py # PlotSpec model\n\u2502 \u2502 \u251c\u2500\u2500 plotting.py # Plotting helpers + plot()\n\u2502 \u2502 \u2514\u2500\u2500 wavedataset.py # WaveDataset + low-level loaders\n\u2502 \u251c\u2500\u2500 loader.py # load_spice_raw convenience wrapper\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 __init__.py # Public symbols (plot, PlotSpec, load_spice_raw,...)\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 examples/ # Usage examples\n\u251c\u2500\u2500 docs/ # Documentation\n\u2514\u2500\u2500 pyproject.toml # Packaging\n```\n\n## Requirements\n\n- **Python**: 3.8+\n- **Core Dependencies**:\n - `plotly` >= 5.0.0 (Interactive plotting)\n - `numpy` >= 1.20.0 (Numerical operations)\n - `PyYAML` >= 6.0 (Configuration files)\n - `spicelib` >= 1.0.0 (SPICE file reading)\n - `click` >= 8.0.0 (Command line interface)\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Documentation\n\nComprehensive documentation is available with:\n\n- **User Guides**: Installation, quickstart, and configuration\n- **API Reference**: Complete function documentation\n- **Examples**: Practical use cases and tutorials\n- **Development**: Contributing guidelines and setup\n\n### Build Documentation Locally\n\n```bash\n# Install documentation dependencies\npip install -e \".[docs]\"\n\n# Build documentation\nmake docs\n\n# Serve documentation locally\nmake docs-serve # Opens at http://localhost:8000\n```\n\n## Links\n\n- **Documentation**: [Local Build Available]\n- **PyPI Package**: [Coming Soon] \n- **Issue Tracker**: [GitHub Issues](https://github.com/Jianxun/wave_view/issues)\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n\n## Version\n\nCurrent version: **0.1.0** (Alpha)\n\n---\n\n**Wave View** - Making SPICE waveform visualization simple and interactive! \ud83c\udf0a\ud83d\udcc8 \n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for visualizing SPICE simulation waveforms in Jupyter notebooks",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/Jianxun/wave_view/issues",
"Documentation": "https://github.com/Jianxun/wave_view/tree/main/docs",
"Homepage": "https://github.com/Jianxun/wave_view",
"Source": "https://github.com/Jianxun/wave_view"
},
"split_keywords": [
"spice",
" simulation",
" waveform",
" visualization",
" jupyter",
" eda"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6b7d72c1d32ab5e4eeb71bc8fc7b86d79dc0d5be81c3affd86fd975abb7218e4",
"md5": "acb333bff44fb2723becb75933ea1c50",
"sha256": "1bd71d253eb47cedce82933c22575bb04b52144b05a180955f22381d3b9b4a76"
},
"downloads": -1,
"filename": "wave_view-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acb333bff44fb2723becb75933ea1c50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22915,
"upload_time": "2025-07-11T07:14:54",
"upload_time_iso_8601": "2025-07-11T07:14:54.318742Z",
"url": "https://files.pythonhosted.org/packages/6b/7d/72c1d32ab5e4eeb71bc8fc7b86d79dc0d5be81c3affd86fd975abb7218e4/wave_view-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2fbbe718b840ebfc9c64c5a488b461eea4e84dbd4a304bd030b7b7a9c8d746f9",
"md5": "6a9cd725f3ed0c6a33edfcfbf86fd103",
"sha256": "a3f790394ff1f1e2b8ef27cb0d71d894bb432e5a4d48fe1564c8a25cfcecdbb2"
},
"downloads": -1,
"filename": "wave_view-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6a9cd725f3ed0c6a33edfcfbf86fd103",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23568,
"upload_time": "2025-07-11T07:14:55",
"upload_time_iso_8601": "2025-07-11T07:14:55.425033Z",
"url": "https://files.pythonhosted.org/packages/2f/bb/e718b840ebfc9c64c5a488b461eea4e84dbd4a304bd030b7b7a9c8d746f9/wave_view-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 07:14:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jianxun",
"github_project": "wave_view",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "ipywidgets",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "jupyter",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"22.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "wave-view"
}
JSON
