Metadata-Version: 2.4
Name: linear-algebra-toolkit
Version: 0.1.0
Summary: Educational pure-Python vector and matrix objects for linear algebra experiments.
Author: Max B.
License-Expression: MIT
Project-URL: Homepage, https://github.com/maxboro/linear-algebra-toolkit
Project-URL: Repository, https://github.com/maxboro/linear-algebra-toolkit
Project-URL: Issues, https://github.com/maxboro/linear-algebra-toolkit/issues
Keywords: linear algebra,matrix,vector,education,math
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Linear Algebra Toolkit

`linear-algebra-toolkit` is a small pure-Python package for experimenting with
core linear algebra operations without NumPy or other numerical libraries.

The codebase is intentionally simple and explicit. It is best suited for
learning, reading through the implementation, and running small examples rather
than for high-performance scientific computing.

## Installation

Install the published package from PyPI with:

```bash
python -m pip install linear-algebra-toolkit
```

If you are working from a local checkout, install the project in editable mode
with:

```bash
python -m pip install -e .
```

## What the project provides

- A `Vector` type for one-dimensional numeric data.
- A `Matrix` type for two-dimensional numeric data.
- Operator overloads for addition, subtraction, element-wise multiplication and
  division, and linear algebra products through `@`.
- A couple of small utility helpers used by the core objects.
- No runtime dependencies outside the Python standard library.

## Design goals

- Keep the implementation readable and easy to inspect.
- Avoid hidden abstractions so the math stays visible in plain Python.
- Provide a compact codebase that is easy to test and extend.

## Quick start

Import the public objects directly from the package:

```python
from linear_algebra_toolkit import Matrix, Vector

vector = Vector([3, 4])
other = Vector([1, 2])
matrix = Matrix([[1, 2], [3, 4]])

print(vector + other)       # Vector([4, 6], n elements=2)
print(vector @ other)       # 11
print(matrix @ vector)      # Vector([11, 25], n elements=2)
print(vector.normalized)    # Vector([0.6, 0.8], n elements=2)
print(vector.as_row_matrix())
```

## Supported operations

### Vector

- Construction from a non-empty list of `int` and `float` values.
- `+` and `-` with vectors of the same shape.
- `+` and `-` with compatible row matrices (`1 x n`) and column matrices (`n x 1`).
- `*` and `/` with scalars.
- Element-wise `*` and `/` with another vector of the same shape.
- `@` with another vector for the dot product.
- `@` with a compatible matrix.
- Norms through `norm(mode="euclidean" | "manhattan" | "max")`.
- `normalized`, `abs(vector)`, `round(vector, ndigits)`,
  `as_row_matrix()`, and `as_col_matrix()`.

### Matrix

- Construction from a non-empty rectangular list of rows.
- `+` and `-` with matrices of the same shape.
- `+` and `-` with compatible vectors represented as a row or column.
- `*` and `/` with scalars.
- Element-wise `*` and `/` with another matrix of the same shape.
- `@` with another compatible matrix.
- `@` with a compatible vector.
- `T` for transpose, `norm()` for the Frobenius norm,
  `get_row_elements()`, `get_col_elements()`, and `get_flatten_elements()`.

## Behavior notes

- Only plain Python `int` and `float` values are accepted.
- Division goes through `zero_aware_division()`. With the current default
  configuration, dividing by zero returns `0` instead of raising an exception.
- The project is educational in scope and prioritizes clarity over performance.

## Running tests

From a repository checkout:

```bash
python -m unittest discover -s tests
```

## Repository examples

The repository includes a few small scripts in `examples/` that demonstrate the
API. From the repository root you can run them like this:

```bash
python -m examples.vector_plus_vector
python -m examples.vector_dot_product
python -m examples.matrix_dot_vector
python -m examples.vector_as_matrix
```

## Repository layout

- `linear_algebra_toolkit/objects.py` contains the `Vector` and `Matrix` implementations.
- `linear_algebra_toolkit/utils.py` contains small shared helpers.
- `tests/` contains the unit tests for the public behavior.
- `examples/` contains runnable usage examples.
