Metadata-Version: 2.4
Name: Vectorian-arjungangwar
Version: 0.0.3
Summary: Complete Vector Analysis Library for Mathematics and Physics
Author-email: Arjun Singh Gangwar <arjungangwariitpkd@email.com>
License-Expression: MIT
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Dynamic: license-file

# Vectorian - Complete Vector Analysis Library

[![PyPI version](https://badge.fury.io/py/vectorian.svg)](https://badge.fury.io/py/vectorian)
[![Python Version](https://img.shields.io/pypi/pyversions/vectorian.svg)](https://pypi.org/project/vectorian/)
[![License](https://img.shields.io/github/license/ArjunGangwar/vectorian.svg)](https://github.com/007arjungangwar/vectorian/blob/main/LICENSE)
[![Downloads](https://pepy.tech/badge/vectorian)](https://pepy.tech/project/vectorian)

**Author:** Arjun Singh Gangwar  
**Email:** ArjunGangwarIitPkd@.com  
**GitHub:** [github.com/007arjungangwar/vectorian](https://github.com/007arjungangwar/vectorian)

A comprehensive Python library for vector analysis covering everything from basic vector operations to advanced vector calculus and field theory. Perfect for students, educators, researchers, and professionals in mathematics, physics, engineering, and computer science.

## 📋 Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Detailed Examples](#detailed-examples)
- [API Reference](#api-reference)
- [Use Cases](#use-cases)
- [Contributing](#contributing)
- [License](#license)

## ✨ Features

### 📐 Basic Vector Operations
- Vector addition, subtraction, scalar multiplication
- Dot product, cross product, triple product
- Magnitude, normalization, direction cosines
- Projection and rejection
- N-dimensional vector support

### 🔄 Advanced Vector Calculus
- **Gradient** - for scalar fields
- **Divergence** - for vector fields
- **Curl** - for vector fields
- **Laplacian** - scalar and vector Laplacian
- **Directional derivatives** - along any direction
- **Jacobian matrix** - for vector fields
- **Hessian matrix** - for scalar fields

### 📊 Field Theory
- Scalar fields (temperature, pressure, potential)
- Vector fields (velocity, force, electromagnetic)
- Field line computation using Runge-Kutta 4
- Conservative field detection
- Scalar potential calculation

### 🧮 Integral Theorems
- Line integrals (work, circulation)
- Surface integrals (flux)
- Volume integrals
- Green's theorem verification
- Stokes' theorem verification
- Divergence theorem verification

### 🔄 Transformations & Coordinates
- **Rotations** - around X, Y, Z axes
- **Reflections** - across any plane
- **Scaling** - non-uniform scaling
- **Coordinate conversions:**
  - Cartesian ↔ Spherical (r, θ, φ)
  - Cartesian ↔ Cylindrical (ρ, φ, z)

### 🎯 Additional Capabilities
- Gram-Schmidt orthogonalization
- Parallel transport
- Orthonormal basis verification
- Numerical integration for field lines
- Finite difference approximations

## 🚀 Installation

### Basic Installation
```bash
pip install vectorian-arjungangwar
```

```python
# With Extra Features
# For plotting and visualization
pip install vectorian[plot]

# For symbolic mathematics
pip install vectorian[symbolic]

# For development (testing, linting)
pip install vectorian[dev]

# Install everything
pip install vectorian[plot,symbolic,dev]


# From Source
git clone https://github.com/007arjungangwar/vectorian.git
cd vectorian
pip install -e .

# 🏃‍♂️ Quick Start
from vectorian import Vector, Vector3D, dot, cross, angle_between

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

# Basic operations
print(f"v1 + v2 = {v1 + v2}")
print(f"v1 · v2 = {dot(v1, v2)}")
print(f"v1 × v2 = {cross(v1, v2)}")
print(f"|v1| = {v1.magnitude():.2f}")
print(f"Angle between: {angle_between(v1, v2, radians=False):.1f}°")

# Normalization
v1_normalized = v1.normalize()
print(f"Normalized: {v1_normalized}")
print(f"Magnitude after normalization: {v1_normalized.magnitude()}")

# Projections
projection = v1.projection(v2)
rejection = v1.rejection(v2)
print(f"Projection onto v2: {projection}")
print(f"Rejection from v2: {rejection}")


# Vector Fields
from vectorian import VectorField, ScalarField, gradient

# Define a vector field F(x,y,z) = (x², y², z²)
def P(x, y, z): return x**2
def Q(x, y, z): return y**2
def R(x, y, z): return z**2

field = VectorField(P, Q, R)

# Evaluate at a point
point = (1, 1, 1)
print(f"Field at {point}: {field.evaluate(*point)}")

# Calculate divergence and curl
print(f"Divergence: {field.divergence(*point):.2f}")
print(f"Curl: {field.curl(*point)}")

# Check if field is conservative
print(f"Is conservative? {field.is_conservative(*point)}")

# Define a scalar field
def scalar_func(x, y, z):
    return x**2 + y**2 + z**2

scalar_field = ScalarField(scalar_func)
print(f"Gradient: {scalar_field.gradient(*point)}")
print(f"Laplacian: {scalar_field.laplacian(*point):.2f}")


# Advanced Calculus

from vectorian import gradient, divergence, curl, laplacian, jacobian

# Define a function
def f(x, y, z):
    return x*y*z + x**2 + y**2 + z**2

# Compute gradient at point (1, 1, 1)
grad = gradient(f, 1, 1, 1)
print(f"Gradient: {grad}")

# Compute Laplacian
lap = laplacian(f, 1, 1, 1)
print(f"Laplacian: {lap:.2f}")

# Define vector field components
def P(x, y, z): return x*y
def Q(x, y, z): return y*z
def R(x, y, z): return z*x

# Compute Jacobian matrix
J = jacobian(P, Q, R, 1, 1, 1)
print(f"Jacobian matrix:")
for row in J:
    print(f"  {row}")


# Coordinate Transformations

from vectorian import Vector3D
from vectorian.transformations import (
    cartesian_to_spherical, spherical_to_cartesian,
    cartesian_to_cylindrical, cylindrical_to_cartesian
)

# Cartesian to Spherical
cartesian = Vector3D(1, 1, 1)
r, theta, phi = cartesian.to_spherical()
print(f"Cartesian: {cartesian}")
print(f"Spherical: (r={r:.2f}, θ={theta:.2f} rad, φ={phi:.2f} rad)")

# Convert back
reconstructed = Vector3D.from_spherical(r, theta, phi)
print(f"Reconstructed: {reconstructed}")

# Cartesian to Cylindrical
rho, phi, z = cartesian.to_cylindrical()
print(f"Cylindrical: (ρ={rho:.2f}, φ={phi:.2f} rad, z={z:.2f})")

# Rotations and Transformations
from vectorian import Vector3D

v = Vector3D(1, 0, 0)

# Rotate around different axes
print(f"Original: {v}")
print(f"Rotated 90° around X: {v.rotate_x(90)}")
print(f"Rotated 90° around Y: {v.rotate_y(90)}")
print(f"Rotated 90° around Z: {v.rotate_z(90)}")

# Rotate around arbitrary axis
axis = Vector3D(1, 1, 0).normalize()
v_rotated = v.rotate_around_axis(axis, 45)
print(f"Rotated 45° around (1,1,0): {v_rotated}")

# Reflection across a plane
normal = Vector3D(0, 1, 0)  # Reflect across XZ-plane
v_reflected = v.reflect(normal)
print(f"Reflected across XZ-plane: {v_reflected}")


# 📚 Detailed Examples
#Example 1: Electromagnetic Field Analysis
from vectorian import VectorField, curl, divergence

# Define electric field of a point charge
def E_field(x, y, z):
    r = (x**2 + y**2 + z**2)**0.5
    if r < 1e-10:
        return Vector3D(0, 0, 0)
    factor = 1 / (r**3)  # Coulomb's law constant omitted
    return Vector3D(x * factor, y * factor, z * factor)

# Create vector field
E = VectorField.from_vector_function(E_field)

# Check Maxwell's equations
point = (1, 2, 3)
print(f"Divergence of E (should be proportional to charge density): {E.divergence(*point):.4f}")
print(f"Curl of E (should be zero for electrostatic): {E.curl(*point)}")


# Example 2: Fluid Flow Analysis
from vectorian import VectorField, Vector3D

# 2D vortex flow field
def vortex_field(x, y, z):
    r2 = x**2 + y**2
    if r2 < 1e-10:
        return Vector3D(0, 0, 0)
    return Vector3D(-y / r2, x / r2, 0)

vortex = VectorField.from_vector_function(vortex_field)

# Compute field lines from a starting point
start = Vector3D(1, 0, 0)
field_lines = vortex.field_lines(start, t_max=2*np.pi, steps=200)
print(f"Computed {len(field_lines)} points along field line")

# Check divergence (should be zero for incompressible flow)
point = (1, 1, 0)
print(f"Divergence: {vortex.divergence(*point):.6f} (should be ~0)")

# Example 3: Conservative Force Field

from vectorian import VectorField, gradient, ScalarField

# Define potential energy function
def potential_energy(x, y, z):
    return x**2 + y**2 + z**2  # Harmonic oscillator potential

# Create force field from potential (F = -∇V)
force_field = VectorField.from_vector_function(
    lambda x, y, z: -gradient(potential_energy, x, y, z)
)

# Verify it's conservative
point = (1, 1, 1)
print(f"Is force field conservative? {force_field.is_conservative(*point)}")
print(f"Curl: {force_field.curl(*point)}")

# Compute work done moving from origin to point
def path_func(t):
    return Vector3D(t, t, t)

work = force_field.line_integral(Vector3D(0,0,0), Vector3D(1,1,1))
print(f"Work done: {work:.4f}")


# Example 4: N-Dimensional Vectors
from vectorian import Vector

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

print(f"v1 = {v1}")
print(f"v2 = {v2}")
print(f"v1 + v2 = {v1 + v2}")
print(f"Dot product: {v1.dot(v2)}")
print(f"Magnitude of v1: {v1.magnitude():.2f}")

# Create zero and basis vectors
zero = Vector.zeros(5)
basis_2 = Vector.basis(5, 2)  # Vector along 3rd axis (0-indexed)
print(f"Zero vector: {zero}")
print(f"Basis vector e2: {basis_2}")

# Gram-Schmidt orthogonalization
vectors = [Vector(1, 1, 0), Vector(1, 0, 1), Vector(0, 1, 1)]
from vectorian.operations import gram_schmidt
orthogonal_basis = gram_schmidt(vectors)
print(f"Original vectors: {vectors}")
print(f"Orthogonal basis: {orthogonal_basis}")
```

## 📖 API Reference
### Core Classes
Class	Description	Key Methods
Vector	N-dimensional vector	dot(), magnitude(), normalize(), projection()
Vector3D	3D vector with cross product	cross(), rotate_*(), reflect(), to_spherical()
VectorField	Vector field F(x,y,z)	divergence(), curl(), field_lines(), is_conservative()
ScalarField	Scalar field f(x,y,z)	gradient(), laplacian(), directional_derivative()
### Key Functions
Category	Functions
Basic	dot(), cross(), angle_between(), projection(), rejection()
Calculus	gradient(), divergence(), curl(), laplacian(), jacobian(), hessian()
Transformations	rotate_vector(), reflect_vector(), scale_vector()
Coordinates	cartesian_to_spherical(), spherical_to_cartesian(), cartesian_to_cylindrical(), cylindrical_to_cartesian()


# 💡 Use Cases
### Academic
Teaching vector calculus - Visualize gradients, curls, and divergences
Student assignments - Verify theoretical results numerically
Research - Quick prototyping of mathematical models

### Engineering
Electromagnetics - Field analysis, Maxwell's equations
Fluid dynamics - Velocity fields, vorticity, flow lines
Structural mechanics - Stress and strain tensors
Robotics - Kinematics, transformations, rotations

### Physics
Classical mechanics - Force fields, potentials, work integrals
Quantum mechanics - Wave functions, probability currents
Astrophysics - Gravitational fields, orbital mechanics

Computer Graphics & Game Development
3D transformations - Rotations, reflections, scaling

Physics engines - Force calculations, collisions
Animation - Vector interpolation, path following
Data Science & Machine Learning
Feature vector operations - Distance metrics, normalization
Gradient descent - Gradient computations
Dimensionality reduction - Projections, orthogonalization

### 🔧 Requirements
Python 3.8 or higher

NumPy (for numerical operations)
SciPy (for advanced numerical methods)

Optional:
Matplotlib (for visualization)
SymPy (for symbolic mathematics)

### 🤝 Contributing
Contributions are welcome! Here's how you can help:
Report bugs - Open an issue on GitHub
Suggest features - Share your ideas
Improve documentation - Fix typos, add examples

Submit pull requests - Add new features or fix bugs
Development Setup
bash
git clone https://github.com/007arjungangwar/vectorian.git
cd vectorian
pip install -e .[dev]
pytest tests/
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.

# 🙏 Acknowledgments
Inspired by classical vector analysis textbooks

Built with scientific Python ecosystem
Thanks to all contributors and users

## 📧 Contact
Author: Arjun Singh Gangwar
Email: arjungangwariitpkd@.com
GitHub: github.com/007arjungangwar
Project Link: github.com/007arjungangwar/vectorian

## ⭐ Star the Project
If you find this library useful, please star the repository on GitHub!

