ieeLabTools

ieeLabTools is a Python library for automating uncertainty propagation and weighted linear regression in physics and engineering lab work. It eliminates manual symbolic differentiation and repetitive numeric error calculation.

Features

• Handles an arbitrary number of variables and measurements
• Returns symbolic SymPy expressions for use in lab reports
• Vectorised numeric evaluation over full measurement series (NumPy)
• Lightweight — only sympy and numpy required

Installation

pip install ieeLabTools

Quick start

Uncertainty propagation (Yvel)

import sympy as sp
import numpy as np
from ieeLabTools import Yvel

# Define the function symbolically
U, I = sp.symbols("U I")
R = U / I

# Instantiate – pass vars explicitly to guarantee column order
calc = Yvel(R, vars=[U, I])

# Inspect the symbolic error formula
print(calc.symbolic())
# sqrt(σI**2*U**2/I**4 + σU**2/I**2)

# Real lab data: voltage divider measurements
U_values = np.array([0.131, 0.505, 1.370, 2.944, 6.74])
I_values = np.full(5, 10e-3)          # 10 mA constant current
U_errors = np.array([6.56e-4, 2.526e-3, 6.851e-3, 1.4721e-2, 3.3701e-2])
I_errors = np.zeros(5)                # current source assumed perfect

# Stack into m×k matrices (m measurements, k variables)
values = np.column_stack([U_values, I_values])
sigmas = np.column_stack([U_errors, I_errors])

sigma_R = calc.numeric(values, sigmas)
print(sigma_R)
# [0.0656  0.2526  0.6851  1.4721  3.3701]

Column order matters. The order of columns in values and sigmas must match the order of variables in vars. Always pass vars explicitly.

Weighted linear regression (WeightedLinregress)

import numpy as np
from ieeLabTools import WeightedLinregress

x     = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
y     = np.array([2.1, 3.9, 6.2, 7.8, 10.1])
y_err = np.array([0.1, 0.2, 0.1, 0.3, 0.2])   # individual y uncertainties

reg = WeightedLinregress(y_err, x, y)
slope, intercept, slope_err, intercept_err = reg.fit()

print(f"slope     = {slope:.4f} ± {slope_err:.4f}")
print(f"intercept = {intercept:.4f} ± {intercept_err:.4f}")

The fit minimises $\chi^2 = \sum_i \frac{(y_i - a - b x_i)^2}{\sigma_i^2}$ using the closed-form weighted least-squares solution:

$$ b = \frac{W \sum w_i x_i y_i - \sum w_i x_i \sum w_i y_i}{D}, \quad a = \frac{\sum w_i x_i^2 \sum w_i y_i - \sum w_i x_i \sum w_i x_i y_i}{D} $$

where $w_i = 1/\sigma_i^2$ and $D = W \sum w_i x_i^2 - \left(\sum w_i x_i\right)^2$.

API reference

Yvel(f, vars=None)

values and sigmas are both m × k array-likes where m is the number of measurements and k is the number of variables.

WeightedLinregress(y_sigma, x, y)

Mathematical background

Non-covariant error propagation:

$$ \sigma_f = \sqrt{\sum_{i} \left(\frac{\partial f}{\partial x_i}\right)^2 \sigma_i^2} $$

This assumes uncorrelated measurement variables. A covariance-aware version is planned for a future release.

Development

git clone https://github.com/ieepirzy/ieeLabTools
cd ieeLabTools
pip install -e ".[dev]"
pytest tests/ -v

Documentation

Full documentation with derivations and worked examples: Docs/Documentation.md

License

MIT — see LICENSE.