Metadata-Version: 2.4
Name: wave_view
Version: 1.0.1
Summary: A Python package for visualizing SPICE simulation waveforms in Jupyter notebooks
Author-email: Jianxun Zhu <jianxun.zhu@example.com>
Maintainer-email: Jianxun Zhu <jianxun.zhu@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Jianxun/wave_view
Project-URL: Bug Reports, https://github.com/Jianxun/wave_view/issues
Project-URL: Source, https://github.com/Jianxun/wave_view
Project-URL: Documentation, https://github.com/Jianxun/wave_view/tree/main/docs
Keywords: spice,simulation,waveform,visualization,jupyter,eda
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Jupyter
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: plotly>=5.0.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: spicelib>=1.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Provides-Extra: jupyter
Requires-Dist: ipywidgets>=8.0.0; extra == "jupyter"
Requires-Dist: jupyter>=1.0.0; extra == "jupyter"
Requires-Dist: jupyterlab>=3.0.0; extra == "jupyter"
Dynamic: license-file

# Wave View: A Python Toolkit for SPICE Simulation Waveform Visualization


[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](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.

![Demo](https://raw.githubusercontent.com/Jianxun/wave_view/main/examples/screenshots/wave_view_demo.png)

## 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! 🌊📈 
