Metadata-Version: 2.4
Name: equser
Version: 0.0.1
Summary: User toolkit for power quality data from EQ Wave sensors
Project-URL: Homepage, https://eq.systems
Project-URL: Documentation, https://equser.eq.systems
Project-URL: Repository, https://github.com/Energy-Quotient/equser
Project-URL: Changelog, https://github.com/Energy-Quotient/equser/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Energy-Quotient/equser/issues
Author-email: Energy Quotient <info@eq.systems>
Maintainer-email: Kevin Davies <kdavies@eq.systems>
License: MIT
License-File: LICENSE
Keywords: continuous-waveform,cpow,data-acquisition,electrical,energy,eq-wave,monitoring,parquet,power-quality,pq,waveform
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: argcomplete>=3.5
Requires-Dist: colorlog>=6.9
Requires-Dist: numpy>=1.24
Requires-Dist: pyarrow!=21.0.0,>=18.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.5; extra == 'analysis'
Requires-Dist: requests>=2.28; extra == 'analysis'
Requires-Dist: websocket-client>=1.6; extra == 'analysis'
Provides-Extra: daq
Requires-Dist: avro>=1.12; extra == 'daq'
Requires-Dist: fastavro>=1.9; extra == 'daq'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: full
Requires-Dist: avro>=1.12; extra == 'full'
Requires-Dist: duckdb>=1.0; extra == 'full'
Requires-Dist: fastavro>=1.9; extra == 'full'
Requires-Dist: ipykernel>=6.29; extra == 'full'
Requires-Dist: ipywidgets>=8.1; extra == 'full'
Requires-Dist: jupyterlab>=4.4; extra == 'full'
Requires-Dist: matplotlib>=3.5; extra == 'full'
Requires-Dist: nbconvert>=7.16; extra == 'full'
Requires-Dist: requests>=2.28; extra == 'full'
Requires-Dist: websocket-client>=1.6; extra == 'full'
Provides-Extra: jupyter
Requires-Dist: duckdb>=1.0; extra == 'jupyter'
Requires-Dist: ipykernel>=6.29; extra == 'jupyter'
Requires-Dist: ipywidgets>=8.1; extra == 'jupyter'
Requires-Dist: jupyterlab>=4.4; extra == 'jupyter'
Requires-Dist: matplotlib>=3.5; extra == 'jupyter'
Requires-Dist: nbconvert>=7.16; extra == 'jupyter'
Requires-Dist: requests>=2.28; extra == 'jupyter'
Requires-Dist: websocket-client>=1.6; extra == 'jupyter'
Description-Content-Type: text/markdown

# equser

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

User toolkit for power quality data from EQ Wave sensors.

## Overview

equser is a Python library for loading, analyzing, and visualizing continuous
waveform (CPOW) and power monitoring (PMon) data from EQ Wave hardware. It
provides:

- **Data loading** (`data`): Load CPOW and PMon Parquet files with automatic scaling
- **Waveform analysis** (`analysis`): Zero-crossing detection, cycle extraction
- **Visualization** (`plotting`): Static plots for power quality data (requires `[analysis]`)
- **API client** (`api`): REST and WebSocket clients for EQ Synapse gateways (requires `[analysis]`)
- **Live acquisition** (`pmon`): Real-time sensor data acquisition (requires `[daq]`)
- **CLI tools**: Command-line interface for monitoring and conversion

## Installation

### Base installation (data loading + analysis)

```bash
pip install equser
```

### With plotting and API support

```bash
pip install equser[analysis]
```

### With JupyterLab notebook environment

```bash
pip install equser[jupyter]
```

### With live sensor acquisition

```bash
pip install equser[daq]
```

### Full installation (all features)

```bash
pip install equser[full]
```

## Quick Start

### Load and explore CPOW data

```python
from equser.data import load_cpow_scaled

result = load_cpow_scaled('20250623_075056.parquet')
print(f"Voltage A peak: {result['VA'].max():.1f} V")
print(f"Start time: {result['start_time']}")
print(f"Sample rate: {result['sample_rate']} Hz")
```

### Load PMon summary data

```python
from equser.data import load_pmon

table = load_pmon('20250623_0750.parquet')
print(table.column_names)
```

### Analyze waveform zero crossings

```python
import numpy as np
from equser.data import load_cpow_scaled, SAMPLE_RATE_HZ
from equser.analysis import find_zero_crossings

result = load_cpow_scaled('cpow_data.parquet')
time = np.arange(len(result['VA'])) / SAMPLE_RATE_HZ
crossings, indices = find_zero_crossings(result['VA'], time)
print(f"Found {len(crossings)} zero crossings")
```

### Plot data (requires `[analysis]`)

```python
from equser.plotting import PowerMonitorPlotter, WaveformPlotter

# Plot power monitor data
plotter = PowerMonitorPlotter()
plotter.plot_file('pmon_data.parquet')

# Plot waveform data
wf_plotter = WaveformPlotter()
wf_plotter.plot_file('cpow_data.parquet')
```

### Query a gateway (requires `[analysis]`)

```python
from equser.api import SynapseClient

client = SynapseClient('http://gateway:8080')
devices = client.list_devices()
table = client.get_pmon_data(devices[0]['id'])
```

### Command Line

```bash
# Start power monitoring (requires EQ Wave sensor + [daq])
equser pmon acquire -c config.yaml

# Convert Avro files to Parquet (requires [daq])
equser pmon convert data/*.avro --remove

# Plot data file (requires [analysis])
equser plot data.parquet
```

## Configuration

equser looks for configuration in the following locations (in order):

1. `EQUSER_CONFIG` environment variable
2. `./equser.yaml` (current directory)
3. `~/.config/equser/config.yaml` (XDG config)
4. `/etc/equser/config.yaml` (system-wide)

Example configuration:

```yaml
sensor:
  address: "192.168.10.10"
  port: 1535

pmon:
  connection:
    retry_delay: 3
  parquet:
    interval: 86400
    compression:
      method: ZSTD
      level: 4
```

## Dependency Tiers

| Extra | Description | Key Packages |
|-------|-------------|--------------|
| *(base)* | Data loading, analysis, CLI | numpy, pyarrow, pyyaml, argcomplete, colorlog |
| `[daq]` | Live sensor acquisition | avro, fastavro |
| `[analysis]` | Plotting + API client | matplotlib, requests, websocket-client |
| `[jupyter]` | Full notebook environment | `[analysis]` + jupyterlab, duckdb, ipywidgets |
| `[dev]` | Development tools | pytest, ruff, mypy |
| `[full]` | All of the above (except dev) | - |

## Requirements

- Python 3.10 or later
- Linux (for hardware integration features)

## Documentation

- [API Documentation](https://equser.eq.systems)
- [Changelog](CHANGELOG.md)

## License

MIT License - Copyright (c) 2026 EQ Systems Inc.

## About

equser is developed by [Energy Quotient](https://eq.systems) as part of the
EQ Synapse platform for continuous waveform intelligence in power systems.
