Release 0.2.0 with physics-aware quantities

Author: madhurthareja

.gitignore

@@ -0,0 +1,16 @@
+# macOS
+.DS_Store
+build/.DS_Store
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Build artifacts
+/build/
+/dist/
+/*.egg-info/
+
+# Virtual environments
+.venv/
+venv/

README.md

@@ -1,6 +1,6 @@
 # Voltops
 
-**Voltops** is a Python library built for electronics and signal processing enthusiasts. Whether you're an engineer, student, or hobbyist, this package offers intuitive functions for working with electrical formulas and analyzing signals with ease.
+**Voltops** is a Python library built for electronics and signal processing enthusiasts. Whether you're an engineer, student, or hobbyist, this package offers intuitive functions for working with electrical formulas and analyzing signals with ease. Every function is **physics-aware**—values carry metadata (DC/AC, RMS/peak, phase, frequency) so you catch mistakes before they propagate.
 
 ---
 
@@ -21,11 +21,11 @@ from voltops.formulas.basic import BasicFormulas
 
 # Calculate voltage using Ohm's Law: V = I * R
 voltage = BasicFormulas.ohms_law(current=2, resistance=5)
-print(f"Voltage: {voltage} V")  # Output: Voltage: 10 V
+print(f"Voltage: {voltage.value} V (kind={voltage.metadata.kind})")
 
 # Calculate power: P = V * I
-power = BasicFormulas.power(voltage=10, current=2)
-print(f"Power: {power} W")  # Output: Power: 20 W
+power = BasicFormulas.power(voltage=voltage, current=2)
+print(f"Power: {power.value} W")
 ```
 
 ### Frequency Spectrum Analysis
@@ -58,10 +58,13 @@ filtered_signal = Filters.low_pass_filter(signal, cutoff=15, sampling_rate=1000)
 
 ## Features
 
-- **Electronic Formulas**: Ohm's Law, power, and more.
+- **Physics-aware quantities**: Voltage, Current, Resistance/Impedance, Power, Frequency, and Phase objects with waveform metadata.
+- **Electronic Formulas**: Ohm's Law, power, and more—now returning safe quantity objects.
 - **Signal Processing**: FFT, DFT, filtering, and spectral analysis.
 - **Extensible API**: Easy-to-use, modular design for seamless integration.
 
+Learn more about the design direction in [`docs/philosophy.md`](docs/philosophy.md).
+
 
 ## Contributing
 
@@ -74,7 +77,7 @@ If you'd like to report a bug, request a feature, or contribute code, feel free
 This library is actively developed and maintained by **Madhur Thareja**.
 
 
-## 📄 License
+## License
 
 Licensed under the [MIT License](https://opensource.org/licenses/MIT).  
 Feel free to use, modify, and distribute this library.

dist/voltops-0.2.0-py3-none-any.whl

@@ -0,0 +1,58 @@
+# VoltOps Core Philosophy
+
+VoltOps delivers **physics-aware computation for everyday electronics and signal-analysis workflows**. Each public API corresponds to a concept that practicing engineers recognize—Ohm's Law, impedance, FFT-based measurement, and so on. Rather than replicating generic math helpers, VoltOps focuses on wiring realistic metadata, guardrails, and educational context into every computation.
+
+---
+
+## Guiding Assumptions
+
+- **Linear, time-invariant, lumped elements** unless explicitly stated.
+- **Steady-state analysis** is the default; transient behavior must be modeled consciously.
+- **Closed-form expressions first**. Numerical solvers and optimizers stay in delegated libraries (e.g., SciPy) until they can be wrapped with clear physics-aware semantics.
+- **Quantities, not scalars**. VoltOps manipulates `Voltage`, `Current`, `Power`, etc., keeping track of waveform kind (DC, AC RMS, AC peak), phase references, and carrier frequency.
+
+## Non‑Goals (for now)
+
+Reinforcing explicit "no" statements builds trust:
+
+- VoltOps is **not** a SPICE replacement or a general-purpose circuit simulator.
+- **No real-time execution guarantees**—runtime safety belongs to your embedded toolchain.
+- **No nonlinear semiconductor device physics**. Analytical helpers for BJTs/FETs may arrive later, but they will remain closed-form.
+- **No blind duplication of SciPy/NumPy** utilities. We wrap them only when physics-aware metadata adds value.
+
+## Design Principles
+
+1. **Quantities over scalars** – Type-safe values that guard against invalid operations and attach waveform metadata everywhere.
+2. **Physical invariants as tests** – Unit tests assert conservation laws, scaling behavior, and dimensional consistency instead of memorizing golden numbers.
+3. **Layered architecture** – Packages are separated into `core/` (metadata + quantities), `formulas/`, `signal_processing/`, and future `circuits/` or `numeric/` layers. Lower layers never depend on higher ones.
+4. **Context-rich results** – APIs return annotated objects. Even FFT helpers yield spectra with sampling metadata rather than naked arrays.
+5. **Delegation with intent** – Expensive numerical kernels continue to live in SciPy/NumPy; VoltOps focuses on keeping the surrounding context faithful to the underlying physics.
+
+## Roadmap Snapshot
+
+| Theme | Why it matters | Current Status |
+| --- | --- | --- |
+| Quantity primitives | Enforce metadata, catch misuse early | (`voltage`, `current`, `resistance`, etc.) |
+| Circuit abstractions | Series/parallel, dividers, equivalents | planned |
+| Measurement helpers | ADC quantization, SNR, aliasing guards | planned |
+| Signal-aware DSP | FFTs that return annotated spectra | foundational transforms |
+| Symbolic hooks | Bridge SymPy for derivations | future exploration |
+
+## How This Shapes Implementation
+
+- **APIs describe intent**: instead of `voltage = i * r`, users call `BasicFormulas.ohms_law(current=i, resistance=r)` and receive a `Voltage` object tied to the originating metadata.
+- **Docs teach, not just list**: each recipe explains the physical context, common pitfalls, and how VoltOps keeps track of assumptions.
+- **Architecture anticipates acceleration**: should we swap in C++ kernels later, the Python-facing API remains unchanged because all metadata plumbing lives in `core/`.
+
+## Delegations
+
+| Capability | Preferred Library |
+| --- | --- |
+| Large-scale linear algebra | NumPy / SciPy |
+| Nonlinear solvers & optimizers | SciPy |
+| Symbolic manipulation | SymPy (optional future layer) |
+| Plotting / visualization | Matplotlib, Plotly, etc. (kept outside VoltOps) |
+
+---
+
+VoltOps succeeds when it saves engineers from re-deriving the same relationships, documents the assumptions behind every helper, and keeps metadata honest from input to output. Depth over breadth, physics over convenience, meaning over speed.

dist/voltops-0.2.0.tar.gz

@@ -2,7 +2,7 @@
 
 setup(
     name="voltops",
-    version="0.1.1",
+    version="0.2.0",
     author="Madhur Thareja",
     author_email="madhurthareja1105@gmail.com",
     description="A Python library for electronic formulas and signal processing",

docs/philosophy.md

@@ -1,16 +1,42 @@
 import pytest
 import numpy as np
 from voltops.formulas.basic import BasicFormulas
+from voltops.core.quantities import Voltage, Current, Resistance, Power, SignalMetadata, SignalKind
 from voltops.signal_processing.filters import Filters
 from voltops.signal_processing.transforms import Transforms
 
 def test_ohms_law():
-    assert BasicFormulas.ohms_law(current=2, resistance=5) == 10
-    assert BasicFormulas.ohms_law(voltage=10, resistance=5) == 2
-    assert BasicFormulas.ohms_law(voltage=10, current=2) == 5
+    voltage = BasicFormulas.ohms_law(current=2, resistance=5)
+    assert isinstance(voltage, Voltage)
+    assert voltage.value == pytest.approx(10)
+
+    current = BasicFormulas.ohms_law(voltage=10, resistance=5)
+    assert isinstance(current, Current)
+    assert current.value == pytest.approx(2)
+
+    resistance = BasicFormulas.ohms_law(voltage=10, current=2)
+    assert isinstance(resistance, Resistance)
+    assert resistance.value == pytest.approx(5)
 
 def test_power():
-    assert BasicFormulas.power(voltage=10, current=2) == 20
+    power = BasicFormulas.power(voltage=10, current=2)
+    assert isinstance(power, Power)
+    assert power.value == pytest.approx(20)
+
+    ac_metadata = SignalMetadata(kind=SignalKind.AC_RMS, frequency_hz=60, phase_deg=0)
+    voltage = Voltage(120, metadata=ac_metadata)
+    current = Current(10, metadata=ac_metadata)
+    ac_power = BasicFormulas.power(voltage=voltage, current=current)
+    assert ac_power.metadata.kind is SignalKind.AC_RMS
+
+
+def test_power_metadata_mismatch():
+    meta_a = SignalMetadata(kind=SignalKind.AC_RMS, frequency_hz=50, phase_deg=0)
+    meta_b = SignalMetadata(kind=SignalKind.AC_RMS, frequency_hz=60, phase_deg=0)
+    voltage = Voltage(10, metadata=meta_a)
+    current = Current(1, metadata=meta_b)
+    with pytest.raises(ValueError):
+        BasicFormulas.power(voltage=voltage, current=current)
 
 def test_frequency_spectrum():
     t = np.linspace(0, 1, 1000, endpoint=False)

setup.py

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voltops
-Version: 0.1.1
+Version: 0.2.0
 Summary: A Python library for electronic formulas and signal processing
 Home-page: https://github.com/madhurthareja/voltops
 Author: Madhur Thareja
@@ -24,7 +24,7 @@ Dynamic: summary
 
 # Voltops
 
-**Voltops** is a Python library built for electronics and signal processing enthusiasts. Whether you're an engineer, student, or hobbyist, this package offers intuitive functions for working with electrical formulas and analyzing signals with ease.
+**Voltops** is a Python library built for electronics and signal processing enthusiasts. Whether you're an engineer, student, or hobbyist, this package offers intuitive functions for working with electrical formulas and analyzing signals with ease. Every function is **physics-aware**—values carry metadata (DC/AC, RMS/peak, phase, frequency) so you catch mistakes before they propagate.
 
 ---
 
@@ -45,11 +45,11 @@ from voltops.formulas.basic import BasicFormulas
 
 # Calculate voltage using Ohm's Law: V = I * R
 voltage = BasicFormulas.ohms_law(current=2, resistance=5)
-print(f"Voltage: {voltage} V")  # Output: Voltage: 10 V
+print(f"Voltage: {voltage.value} V (kind={voltage.metadata.kind})")
 
 # Calculate power: P = V * I
-power = BasicFormulas.power(voltage=10, current=2)
-print(f"Power: {power} W")  # Output: Power: 20 W
+power = BasicFormulas.power(voltage=voltage, current=2)
+print(f"Power: {power.value} W")
 ```
 
 ### Frequency Spectrum Analysis
@@ -82,10 +82,13 @@ filtered_signal = Filters.low_pass_filter(signal, cutoff=15, sampling_rate=1000)
 
 ## Features
 
-- **Electronic Formulas**: Ohm's Law, power, and more.
+- **Physics-aware quantities**: Voltage, Current, Resistance/Impedance, Power, Frequency, and Phase objects with waveform metadata.
+- **Electronic Formulas**: Ohm's Law, power, and more—now returning safe quantity objects.
 - **Signal Processing**: FFT, DFT, filtering, and spectral analysis.
 - **Extensible API**: Easy-to-use, modular design for seamless integration.
 
+Learn more about the design direction in [`docs/philosophy.md`](docs/philosophy.md).
+
 
 ## Contributing
 
@@ -98,7 +101,7 @@ If you'd like to report a bug, request a feature, or contribute code, feel free
 This library is actively developed and maintained by **Madhur Thareja**.
 
 
-## 📄 License
+## License
 
 Licensed under the [MIT License](https://opensource.org/licenses/MIT).  
 Feel free to use, modify, and distribute this library.