Metadata-Version: 2.4
Name: lazysym
Version: 1.0.1
Summary: Add your description here
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: hatchling>=1.29.0
Requires-Dist: sympy>=1.14.0

# lazysym

A lazy-evaluation symbolic calculator, geometric primitive engine, and constraint solver built on SymPy.

`lazysym` overloads standard Python operators on wrapped symbols, vectors, matrices, physical quantities, and geometric entities to defer evaluation, enabling fluent definition of complex math systems that are solved dynamically.

## Installation

```bash
pip install lazysym
```

## Quick Start

### 1. Symbolic Calculations & Equation Solving
Define symbolic variables in a context, register constraints (using native Python operators), and solve for target variables.

```python
from lazysym import Context

ctx = Context()
x = ctx.Symbol('x')
y = ctx.Symbol('y')

# Register equations
ctx.given(
    2 * x + y == 10,
    x - y == 2
)

# Solve dynamically
print("x =", ctx.find(x))  # x = 4
print("y =", ctx.find(y))  # y = 2
```

### 2. Physical Quantities with Units
Perform arithmetic across different units with automatic base conversion.

```python
from lazysym import Quantity

# Quantities auto-convert to a base representation during operations
distance1 = Quantity(5, 'km')
distance2 = Quantity(500, 'm')

total = distance1 + distance2
print(total)                # 5.5 km
print(total.convert_to('m')) # 5500.0
```

### 3. Constraint Satisfaction (Digit/Alphametic Solvers)
Solve discrete constraint-satisfaction problems or cryptarithms using digit domains and numerical constraints.

```python
from lazysym import Context

ctx = Context()

# Define digits with ranges
A = ctx.Digit('A', domain=(1, 9))
B = ctx.Digit('B', domain=(0, 9))

# Add constraints (e.g. A + B must equal 10, and A must be a prime number)
ctx.given(
    A + B == 10,
    A.isPrime()
)

# Find all valid combinations
solutions = ctx.findAll(A, B)
print(solutions)  # [(2, 8), (3, 7), (5, 5), (7, 3)]
```

### 4. Geometry and Selection Transformations (2D & 3D)
Construct points, lines, circles, spheres, and other geometric primitives in a canvas environment. Group entities into a selection to perform bulk spatial transformations (translation, rotation, scaling, dilation, reflection).

```python
from lazysym import Context, Plot

ctx = Context()
plot = Plot(ctx, dim=2)

p1 = plot.Point('p1', 0, 0)
p2 = plot.Point('p2', 3, 4)

# Calculate dynamic distances
distance = p1.distance(p2)
print("Distance:", distance)  # Distance: 5 m

# Create a circle at p1
circle = plot.Circle('c1', center=p1, radius=5)

# Selection-based bulk transformation
selection = plot.selection(p1, circle)
selection.translate(dx=10, dy=5)

# Original points are modified in-place
print(p1.x, p1.y)          # 10, 5
print(circle.center.coords()) # (10, 5)
```

### 5. Custom Matrix & Vector Wrappers
Construct vectors and matrices with custom support for dot products, cross products, and matrix multiplication under symbolic contexts.

```python
from lazysym import Context

ctx = Context()

# Access namespace matrices and vectors
v1 = ctx.Vector.Vector([1, 2, 3])
v2 = ctx.Vector.Vector([4, 5, 6])

print("Dot product:", v1.dot(v2))    # 32
print("Cross product:", v1.cross(v2))  # Vector([-3, 6, -3])
```

## Features

- **Deferred Symbolic Operations**: Overloaded magic methods map arithmetic and comparison operators directly into SymPy expressions.
- **Physical Quantities System**: Pre-configured factors for metric units (`m`, `cm`, `mm`, `km`), imperial units (`inch`, `ft`, `yd`, `mi`), and angles (`radians`, `degrees`, `gradians`, `turns`).
- **Geometric Primitives**: 2D/3D support for points, lines, rays, segments, circles, spheres, triangles, ellipses, parabolas, cylinders, cones, and planes.
- **Dynamic Solver Contexts**: Behind the scenes, the context uses SymPy solver utilities to resolve systems of equations, with automatic coordinate gauge-fixing for under-constrained geometric layouts.
- **Sequence Patterns**: Built-in support for evaluating arithmetic or custom recurrence relations based on pattern configuration.

## License

MIT
