A lightweight, dependency-free vector mathematics library for Python.
Designed for Artificial Intelligence, Machine Learning, Robotics, Computer Graphics, Scientific Computing, Physics Simulations, and Education.
AIVector is an open-source Python library that provides a clean, readable, and well-documented implementation of fundamental vector mathematics.
Unlike large scientific libraries that expose thousands of functions, AIVector focuses on providing a carefully designed collection of essential vector operations with an emphasis on:
- Clean architecture
- Readable source code
- Strong type hints
- Comprehensive documentation
- Educational implementations
- Zero external dependencies
- Overview
- Why AIVector?
- Project Philosophy
- Features
- Installation
- Quick Start
- Examples
- API Overview
- Project Structure
- Performance
- Roadmap
- Contributing
- License
AIVector provides a carefully designed collection of vector operations commonly used in mathematics, artificial intelligence, robotics, scientific computing, computer graphics, and simulation software.
The library currently includes:
- Vector addition
- Vector subtraction
- Element-wise multiplication
- Element-wise division
- Scalar multiplication
- Element-wise maximum
- Element-wise minimum
- Euclidean magnitude
- Squared magnitude
- Unit vector normalization
- Dot product
- Euclidean distance
- Cosine similarity
- Angle between vectors
- Vector projection
- Linear interpolation (Lerp)
- Clamp
- 2D Cross Product
AIVector is designed around reusable internal building blocks.
Instead of duplicating loops across functions, the library internally uses reusable helper utilities for:
- Unary vector operations
- Binary vector operations
- Scalar operations
- Type conversion
- Input validation
This architecture keeps the implementation concise, easy to maintain, and highly extensible.
The project follows several core principles.
Every function should be understandable without reading external papers or advanced mathematics textbooks.
Algorithms should remain mathematically correct while avoiding unnecessary complexity.
Every public function uses modern Python type hints to improve readability and editor support.
The implementation is intentionally written to teach vector mathematics, not merely perform computations.
The library currently relies only on the Python Standard Library.
No third-party packages are required.
Every public function follows the same conventions regarding:
- Naming
- Type hints
- Error handling
- Documentation
- Examples
- Time complexity
- Space complexity
This consistency makes the library predictable and easy to learn.
The project is designed for developers who want to understand vector mathematics rather than simply use it.
Whether you are building an AI model, a physics simulation, a robotics project, a game engine, or simply learning linear algebra, AIVector aims to provide intuitive, production-quality implementations that are easy to read, extend, and maintain.
Modern Python already offers powerful scientific libraries such as NumPy, SciPy, and PyTorch.
Those libraries are incredibly fast and feature-rich.
However, they are intentionally optimized for performance and large-scale numerical computation rather than education.
Their internal implementations are highly optimized, making them difficult to study for developers who want to understand the underlying algorithms.
AIVector follows a different philosophy.
Instead of hiding the mathematics behind optimized C/C++ extensions, every algorithm is implemented in pure Python with readability as its highest priority.
Every function is fully documented.
Every mathematical equation is explained.
Every design decision is intentional.
Every implementation is written to teach.
This makes AIVector an ideal resource for:
- Students learning linear algebra.
- AI engineers building mathematical intuition.
- Robotics developers.
- Game developers.
- Researchers.
- Python programmers interested in numerical computing.
- Anyone who wants to understand how vector mathematics actually works.
AIVector is built around a simple principle:
Readable code is educational code.
The goal of this project is not to compete with NumPy in raw performance.
Instead, the goal is to create a library whose source code can be read from top to bottom while understanding every single line.
Every function is implemented using straightforward Python code, allowing developers to learn both mathematics and software engineering at the same time.
The project also follows modern Python development practices including:
- Type hints
- Modular architecture
- Small reusable helper functions
- Comprehensive docstrings
- Predictable API design
- Extensive testing
- Continuous extensibility
As the project grows, additional modules—including matrices, statistics, geometry, optimization, and AI utilities—will follow the same philosophy.
AIVector is distributed through PyPI and can be installed using
pip.
pip install aivectorVerify the installation:
import aivector as vm
print(vm.__version__)To install the latest development version directly from GitHub:
git clone https://github.com/<your-username>/aivector.git
cd aivector
pip install .Or install directly:
pip install git+https://github.com/<your-username>/aivector.gitAIVector is implemented entirely in pure Python.
Requirements:
- Python 3.11 or newer
- No third-party dependencies
The following examples demonstrate the most common operations provided by the library.
import aivector as vm
a = [1, 2, 3]
b = [4, 5, 6]
result = vm.add(a, b)
print(result)Output
[5.0, 7.0, 9.0]
import aivector as vm
a = [1, 2, 3]
b = [4, 5, 6]
print(vm.dot(a, b))Output
32.0
import aivector as vm
vector = [3, 4]
print(vm.normalize(vector))Output
[0.6, 0.8]
import math
import aivector as vm
a = [1, 0]
b = [0, 1]
angle = vm.angle_between(a, b)
print(math.degrees(angle))Output
90.0
import aivector as vm
a = [1, 2, 3]
b = [2, 4, 6]
print(vm.cosine_similarity(a, b))Output
1.0
import aivector as vm
a = [3, 4]
b = [1, 0]
projection = vm.project(a, b)
print(projection)Output
[3.0, 0.0]
import aivector as vm
start = [0, 0]
end = [10, 0]
print(vm.lerp(start, end, 0.5))Output
[5.0, 0.0]
import aivector as vm
vector = [5, -10, 100]
print(vm.clamp(vector, 0, 10))Output
[5.0, 0.0, 10.0]
import aivector as vm
a = [1, 0]
b = [0, 1]
print(vm.cross2D(a, b))Output
1.0
These examples cover the most frequently used functionality.
More advanced examples can be found in the documentation and future tutorials.
This section provides a high-level overview of the public API currently available in AIVector.
Every function is implemented using pure Python, includes full type hints, comprehensive documentation, and consistent error handling.
| Function | Description | Returns |
|---|---|---|
add() |
Element-wise vector addition | list[float] |
subtract() |
Element-wise vector subtraction | list[float] |
multiply() |
Element-wise vector multiplication | list[float] |
divide() |
Element-wise vector division | list[float] |
maximum() |
Element-wise maximum | list[float] |
minimum() |
Element-wise minimum | list[float] |
| Function | Description | Returns |
|---|---|---|
magnitude() |
Compute the Euclidean length of a vector | float |
magnitude_squared() |
Compute the squared Euclidean length | float |
normalize() |
Normalize a vector to unit length | list[float] |
| Function | Description | Returns |
|---|---|---|
dot() |
Compute the dot product | float |
euclidean_distance() |
Compute the Euclidean distance | float |
cosine_similarity() |
Compute the cosine similarity between two vectors | float |
angle_between() |
Compute the angle between two vectors | float |
project() |
Project one vector onto another | list[float] |
lerp() |
Perform linear interpolation | list[float] |
clamp() |
Clamp every element to a given range | list[float] |
cross2D() |
Compute the 2D cross product | float |
The public API is organized into logical categories.
These functions perform element-wise arithmetic operations between two vectors or between a vector and a scalar.
- add
- subtract
- multiply
- divide
- scale
These functions describe the mathematical properties of a vector.
- magnitude
- magnitude_squared
- normalize
These functions describe geometric relationships between vectors.
- dot
- cosine_similarity
- angle_between
- project
- euclidean_distance
- cross2D
General-purpose helper operations.
- clamp
- lerp
AIVector performs extensive input validation before executing any mathematical operation.
Depending on the situation, the library raises the following exceptions.
| Exception | Description |
|---|---|
TypeError |
One or more supplied values are not numeric. |
ValueError |
Vectors have incompatible dimensions. |
ValueError |
A zero vector was supplied where mathematically invalid. |
ValueError |
Invalid parameter values were provided. |
Every public function uses modern Python type annotations.
Example:
def normalize(
vector: Iterable[SupportsFloat],
) -> list[float]:The project avoids ambiguous parameter types whenever possible and follows modern Python typing conventions to improve readability, maintainability, and editor support.
Every public function includes comprehensive documentation covering:
- Description
- Mathematical definition
- Parameters
- Return value
- Exceptions
- Notes
- Applications
- Complexity analysis
- Related functions
- Examples
This documentation style is inspired by scientific Python libraries and is intended to make the library both educational and practical.
AIVector is released under the MIT License.
You are free to use, modify, distribute, and integrate this project into both open-source and commercial software, provided that the original copyright and license notice are retained.
See the LICENSE file for the complete license text.