Metadata-Version: 2.4
Name: matpy-linalg
Version: 0.1.0
Summary: A comprehensive Python library for vector and matrix operations with a clean, Pythonic API
Author-email: Noah Ryan <njryan2005@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/matpy
Project-URL: Documentation, https://github.com/yourusername/matpy#readme
Project-URL: Repository, https://github.com/yourusername/matpy
Project-URL: Issues, https://github.com/yourusername/matpy/issues
Keywords: matrix,vector,linear-algebra,mathematics,numpy-alternative
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Dynamic: license-file

# MatPy

A comprehensive Python library for vector and matrix operations with a clean, Pythonic API. MatPy provides an intuitive interface for linear algebra operations without external dependencies, making it perfect for educational purposes and lightweight mathematical applications.

## Features

### 🎯 Core Components

- **Vector Class**: 3D vectors with full operator support
- **Matrix Class**: Dynamic-size matrices with comprehensive operations
- **Custom Error Handling**: Descriptive exceptions for better debugging
- **Pure Python**: No external dependencies required

### ⚡ Vector Operations

- Arithmetic operations (`+`, `-`, `*`, `/`)
- Dot product and cross product
- Magnitude and normalization
- Vector projection and rejection
- Angle calculation between vectors
- Linear interpolation (lerp)
- Reflection across surfaces
- Full Python protocol support (iteration, indexing, etc.)

### 🔢 Matrix Operations

- Element-wise operations
- Matrix multiplication (`*` or `@` operator)
- Matrix power (`**` operator)
- Transpose
- Determinant calculation
- Matrix inverse
- Adjugate (adjoint) matrix
- Rank calculation
- Trace
- Eigenvalues (for 1x1 and 2x2 matrices)
- Matrix properties (symmetric, orthogonal, singular, etc.)

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/matpy.git
cd matpy

# Install in development mode
pip install -e .

# Or install from source
pip install .
```

## Quick Start

### Vector Examples

```python
from matpy import Vector
from matpy.vector import ops

# Create vectors
v1 = Vector(3, 4, 5)
v2 = Vector(1, 2, 3)

# Arithmetic operations
v3 = v1 + v2          # Vector addition
v4 = v1 - v2          # Vector subtraction
v5 = v1 * 2           # Scalar multiplication
v6 = v1 / 2           # Scalar division

# Vector operations
dot_product = v1.dot(v2)           # Dot product
cross_product = v1.cross(v2)       # Cross product
magnitude = v1.magnitude()         # Magnitude/length
normalized = v1.normalize()        # Unit vector

# Advanced operations
angle = ops.angle_between(v1, v2)  # Angle in radians
projection = ops.projection(v1, v2)
interpolated = ops.lerp(v1, v2, 0.5)

# Python protocols
print(v1)              # (3, 4, 5)
print(repr(v1))        # <3, 4, 5>
print(len(v1))         # 3
print(v1[0])           # 3
for component in v1:   # Iteration
    print(component)
```

### Matrix Examples

```python
from matpy.matrix.core import Matrix

# Create matrices
m1 = Matrix(2, 2, [[1, 2], [3, 4]])
m2 = Matrix(2, 2, [[5, 6], [7, 8]])

# Arithmetic operations
m3 = m1 + m2          # Matrix addition
m4 = m1 - m2          # Matrix subtraction
m5 = m1 * 3           # Scalar multiplication
m6 = m1 @ m2          # Matrix multiplication (@ operator)
m7 = m1 ** 3          # Matrix power

# Matrix operations
transposed = m1.transpose()
determinant = m1.determinant()
inverted = m1.inverse()
trace = m1.trace()
rank = m1.rank()

# Matrix properties
is_square = m1.is_square()
is_symmetric = m1.is_symmetric()
is_singular = m1.is_singular()
is_invertible = m1.is_invertible()

# Advanced operations
adjugate = m1.adjugate()
cofactor = m1.cofactor(0, 1)

# Python protocols
print(m1)              # Formatted matrix output
print(f"{m1:.2f}")     # Formatted to 2 decimal places
for value in m1:       # Iterate over all elements
    print(value)
```

## Running Tests

```bash
# Run all tests
python tests/run_tests.py

# Run specific test file
python tests/test_vector_core.py
python tests/test_vector_ops.py

# Run with unittest
python -m unittest discover tests

# Run with pytest (if installed)
pytest tests/
```

## Examples

Check out the `examples/` directory for more detailed examples:

- `Vector_example.py` - Comprehensive vector operations showcase
- `vector_arithmatic.py` - Vector arithmetic demonstrations
- `python_methods.py` - Python dunder methods examples

## Project Structure

```
matpy/
├── src/
│   └── matpy/
│       ├── __init__.py
│       ├── version.py
│       ├── error.py          # Custom exceptions
│       ├── core/             # Core utilities
│       │   ├── utils.py
│       │   └── validate.py
│       ├── vector/           # Vector implementation
│       │   ├── core.py       # Vector class
│       │   └── ops.py        # Vector operations
│       ├── matrix/           # Matrix implementation
│       │   └── core.py       # Matrix class
│       └── visualization/    # Visualization tools
├── tests/                    # Test suite
│   ├── test_vector_core.py
│   ├── test_vector_ops.py
│   └── run_tests.py
├── examples/                 # Example scripts
├── pyproject.toml           # Project configuration
└── README.md                # This file
```

## Custom Error Handling

MatPy provides descriptive custom exceptions for better error handling:

```python
from matpy.error import (
    ValidationError,
    ShapeError,
    NotSquareError,
    SingularMatrixError,
    require_square,
    require_compatible_for_multiplication
)

# Errors provide detailed context
try:
    m1 @ m2  # Incompatible dimensions
except ShapeError as e:
    print(e)  # "Incompatible shapes for matrix multiplication: (2, 3) and (4, 5)"

# Convenience functions for validation
require_square(matrix, "determinant")
require_compatible_for_multiplication(m1, m2)
```

## API Reference

### Vector Class

**Constructor:**
- `Vector(x=0, y=0, z=0)` - Create a 3D vector

**Methods:**
- `dot(other)` - Dot product
- `cross(other)` - Cross product
- `magnitude()` - Calculate magnitude
- `normalize()` - Return unit vector

**Operators:**
- `+`, `-`, `*`, `/` - Arithmetic operations
- `==`, `!=` - Equality comparison
- `abs()` - Magnitude
- `len()` - Always returns 3
- `[]` - Index access (0, 1, 2)
- `in` - Membership test
- `iter()` - Iteration support

### Matrix Class

**Constructor:**
- `Matrix(rows, cols, data=None)` - Create a matrix

**Methods:**
- `transpose()` - Matrix transpose
- `determinant()` - Calculate determinant
- `inverse()` - Matrix inverse
- `adjugate()` - Adjugate matrix
- `trace()` - Sum of diagonal elements
- `rank()` - Matrix rank
- `cofactor(row, col)` - Cofactor calculation
- `is_square()` - Check if square
- `is_symmetric()` - Check if symmetric
- `is_singular()` - Check if singular
- `is_invertible()` - Check if invertible

**Operators:**
- `+`, `-`, `*`, `/` - Arithmetic operations
- `@` - Matrix multiplication
- `**` - Matrix power
- `==`, `!=`, `<`, `>`, `<=`, `>=` - Comparisons
- `abs()` - Frobenius norm
- `len()` - Total number of elements
- `[]` - Row access
- `iter()` - Iteration support

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests with coverage
pytest --cov=matpy

# Format code
black src/ tests/

# Type checking
mypy src/
```

## Future Enhancements

- [ ] Matrix decomposition (LU, QR, SVD)
- [ ] Sparse matrix support
- [ ] Higher-dimensional tensors
- [ ] Visualization module with matplotlib
- [ ] Performance optimizations with NumPy backend (optional)
- [ ] Additional matrix operations (Cholesky, Schur, etc.)
- [ ] Complex number support

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- Inspired by NumPy and other linear algebra libraries
- Built with pure Python for educational purposes
- Comprehensive test coverage for reliability

## Contact

Noah Ryan - njryan2005@gmail.com

Project Link: [https://github.com/yourusername/matpy](https://github.com/yourusername/matpy)
