simpyq 1.0.1

CLI tool to query and analyze simulation CSV data with natural language

simpyQ

CLI tool for querying simulation CSV data using natural language.

Analyze and visualize simulation data from CSV files using natural language queries interpreted via spaCy and a rule-enhanced NLP pipeline.

---

Features

• Terminal-based CLI tool with live interactive mode
• Natural language processing of signal queries (e.g., mean of Vout)
• Signal name indexing and pretty terminal display using Rich
• Plotting of signal vs time with auto-saving to file
• Logging of results and errors to timestamped log files
• Lightweight, extensible, and easy to adapt to other domains

---

Installation

# Create environment (recommended)
conda create -n simpyq_env python=3.10
conda activate simpyq_env

# Install dependencies
pip install -r requirements.txt

# Or install manually
pip install pandas numpy matplotlib rich pyfiglet spacy
python -m spacy download en_core_web_trf

---

Usage

# Run in one-shot mode (process query then exit)
python simpyq/cli.py path/to/data.csv "mean of Vout"

# Show available signals
python simpyq/cli.py path/to/data.csv --show

# Plot signal(s)
python simpyq/cli.py path/to/data.csv --plot Vout Iload --start 0.1 --end 0.9

Interactive Mode

# Start interactive REPL
python simpyq/cli.py path/to/data.csv

Then just type queries like:

mean of Vout
rms of Iin
(mean of Vout) + (rms of Iload) / 2
exit()

---

Example Queries

Query	Description
mean of Vout	Computes the average value of Vout
rms of Iload	Root-mean-square of Iload
max of Temp - min of Temp	Temperature swing
integral of Pin	Energy under the Pin curve
rms of Vout + mean of Iin * 2	Composite math query
plot of Vout and Iin	(Use --plot flag instead)

---

Directory Structure

simpyq/
│
├── cli.py                # Main CLI entry point
├── core.py               # Signal processing, math
├── utils.py              # Helpers, plotting, logging
├── out/
│   ├── logs/             # Query logs
│   └── plots/            # Auto-saved plots

---

Supported Operations

OPERATIONS = {
    "mean": np.mean,
    "average": np.mean,
    "rms": lambda x: np.sqrt(np.mean(np.square(x))),
    "std": np.std,
    "variance": np.var,
    "max": np.max,
    "min": np.min,
    "abs max": lambda x: np.max(np.abs(x)),
    "abs min": lambda x: np.min(np.abs(x)),
    "sum": np.sum,
    "peak-to-peak": lambda x: np.ptp(x),
    "median": np.median,
    "integral": lambda x: np.trapz(x),
    "squared mean": lambda x: np.mean(np.square(x)),
    "derivative": lambda x: np.gradient(x),
    "diff": np.diff,
}

---

How It Works

• Loads CSV data and extracts signal names
• Injects them as named entities into the spaCy NLP pipeline
• Parses user query and extracts operations and signals
• Computes the operations and evaluates full expressions
• Plots and saves results as needed

---

NLP Training / Fine-tuning

You can customize the NLP model to better understand domain-specific expressions.

To train or adapt:

1. Edit get_nlp() to support additional patterns
2. Add EntityRuler rules:

patterns = [{"label": "ELECTRONIC_SIGNAL", "pattern": name} for name in signal_names]
ruler.add_patterns(patterns)

3. (Optional) Fine-tune spaCy model with labeled data:

python -m spacy train config.cfg --output ./model --paths.train ./train.spacy --paths.dev ./dev.spacy

---

License

GPL v3 License

---

Acknowledgments

Thanks to the open-source community and tools like:

• spaCy
• NumPy
• Matplotlib
• Rich