Metadata-Version: 2.4
Name: pyvelora
Version: 0.3.3
Summary: Lightweight mathematical backend for physics libraries.
Author: Noah Ryan
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/pyvelora/
Project-URL: Repository, https://github.com/njryan-boou/pyvelora
Project-URL: Issues, https://github.com/njryan-boou/pyvelora/issues
Keywords: linear-algebra,vector,matrix,tensor,scientific-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: build>=1.3; extra == "dev"
Requires-Dist: twine>=6.2; extra == "dev"

# pyvelora

pyvelora is a lightweight math backend for scientific and simulation workflows.
It provides structured `Vector`, `Matrix`, and `Tensor` classes, linear algebra helpers,
and an ODE module for differential equation workflows.

## What You Get

- Clear, typed array wrappers for vectors, matrices, and tensors
- Loop-based arithmetic with predictable behavior
- Linear algebra helpers for matrix operations, solvers, and decompositions
- Utility helpers for precision control, validation, mesh generation, and plotting
- ODE solving helpers with first-order and second-order system support

## Philosophy

- Lightweight abstractions over Python-native containers
- Predictable data containers with explicit operations
- Reusable core infrastructure for physics/simulation libraries

## Installation

```bash
pip install pyvelora
```

Optional dependencies:

- SciPy for ODE solving
- Matplotlib for plotting utilities and ODE visualization

Install them with:

```bash
pip install scipy matplotlib
```

## Core Quick Start

```python
from pyvelora import Vector, Matrix, Tensor

v = Vector([3, 4])
print(v.magnitude())  # 5.0

m = Matrix([[1, 2], [3, 4]])
print(m.transpose())

t = Tensor([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
print(t.shape)  # (2, 2, 2)
```

## Coordinate Vector Input

`Vector` supports polar, spherical, and cylindrical coordinate input.

```python
from pyvelora import Vector

# Polar input: [r, theta]
v_polar = Vector([2, 45], type="polar", degrees=True)

# Spherical input: [r, theta, phi]
v_spherical = Vector([1, 90, 30], type="spherical", degrees=True)

# Cylindrical input: [rho, phi, z]
v_cyl = Vector([2, 90, 3], type="cylindrical", degrees=True)
```

Angles are interpreted as radians unless `degrees=True` is passed.

## Linear Algebra Utilities

```python
from pyvelora import Matrix
from pyvelora import Vector
from pyvelora.linalg import solve

A = Matrix([[2, 1], [5, 3]])
b = Vector([4, 11])

print(A.determinant())
print(A.inverse())
print(solve(A, b, method="lu"))
```

## Utilities and Plotting

`pyvelora.utils` includes numerical cleanup, tolerance management, mesh generation,
and lightweight plotting helpers.

```python
from pyvelora import Matrix
from pyvelora.utils import clean, set_precision, get_precision, heatmap, linspace

set_precision(atol=1e-10, rtol=1e-8)
print(get_precision())

A = Matrix([[1.0, 0.99999999999], [-0.2, 0.3]])
print(clean(A.data))

fig, ax = heatmap(A, annotate=True, show=False)
```

## ODE Module

The ODE API is available under `pyvelora.diffeq.ode`.

```python
from pyvelora.constants import pi
from pyvelora.diffeq.ode import solve, second_order
from pyvelora.utils import linspace

# First-order system: y' = -y
sol = solve(lambda t, y: -y, (0, 2), [1.0], t_eval=linspace(0, 2, 11))
print(sol.final())

# Convert second-order equation y'' = -y to first-order system
sho = second_order(lambda t, y, v: -y)
sho_sol = solve(sho, (0, 2 * pi), [1.0, 0.0])
print(sho_sol.final())
```

## Error Types

The package provides reusable exception types:

- `PyveloraError`
- `ShapeError`
- `DimensionError`

```python
from pyvelora import Vector, ShapeError

try:
    _ = Vector([1, 2, 3]) + Vector([1, 2])
except ShapeError as exc:
    print(exc)
```

## Development

Run the test suite:

```bash
python -m pytest src/pyvelora/tests -q
```

Build source and wheel distributions:

```bash
python -m build --no-isolation
```

## AI Use Disclaimer

AI-assisted tooling was used during development for parts of the test suite, docstrings,
and project documentation. Library design, implementation decisions, review, and release
validation were still performed manually.

## Project Status

pyvelora is currently alpha-stage and actively evolving.
Core APIs are usable, but minor interface changes may still happen between releases.
