VLA Documentation

pip install simgen-vla

import torch
from simgen import vla

# Create GPU-native extended precision tensors
x = vla.Decimal(torch.randn(1000, device='cuda'))
y = vla.Decimal(torch.randn(1000, device='cuda'))

# All operations stay on GPU with full precision
result = (x + y * 2).sum()

# Display exact value (converts to Python Decimal only for display)
print(result)  # VLADecimal(-12.34567890123456789...)

# Explicit conversion when you need Python Decimal
exact_value = result.to_decimal()  # decimal.Decimal object

# Convert back to torch.Tensor when done
tensor = result.to_torch()  # float64 tensor

# Create from exact fractions (TRUE zero representation error)
x = vla.Decimal_frac(1, 3)  # Exact 1/3

# Create zeros/ones/random
zeros = vla.Decimal_zeros((100, 100))
ones = vla.Decimal_ones((100, 100))
randn = vla.Decimal_randn((100, 100))

# Concatenate/stack VLADecimal tensors
combined = vla.Decimal_cat([x, y], dim=0)
stacked = vla.Decimal_stack([x, y], dim=0)

from simgen import vla

# GPU exact arithmetic - TRUE ZERO error
a = vla.ModularTensor.from_fraction(1, 3, shape=(10000,), device='cuda')
b = vla.ModularTensor.from_fraction(1, 6, shape=(10000,), device='cuda')
c = a + b  # Exactly 1/2 for all 10,000 elements

# Exact equality check
expected = vla.ModularTensor.from_fraction(1, 2, shape=(10000,), device='cuda')
print((c == expected).all())  # True - TRUE ZERO!

# 100K iterations - still TRUE ZERO
acc = vla.ModularTensor.from_int(0, shape=(1,), device='cuda')
delta = vla.ModularTensor.from_fraction(1, 100000, shape=(1,), device='cuda')
for _ in range(100000):
    acc = acc + delta
print((acc == vla.ModularTensor.from_int(1, shape=(1,), device='cuda')).all())  # True!

from simgen import vla

# CPU exact arithmetic
a = vla.ModularRational.from_fraction(1, 3)  # Exactly 1/3
b = vla.ModularRational.from_fraction(1, 6)  # Exactly 1/6
c = a + b  # Exactly 1/2

print(c == vla.ModularRational.from_fraction(1, 2))  # True - EXACT!

# Exact vector operations
vec_a = vla.ModularVector.from_fractions([(1,2), (1,3), (1,4)])
vec_b = vla.ModularVector.from_fractions([(2,1), (3,1), (4,1)])
dot = vec_a.dot(vec_b)  # Exactly 3

# Exact matrix operations
A = vla.ModularMatrix.from_ints([[1,1],[1,0]])  # Fibonacci matrix
F10 = A.power(10)  # F10[0,0] = 89 - EXACT!

# Matrix multiply
I = vla.ModularMatrix.identity(2)
B = A * I  # A @ I = A exactly

# Lorenz attractor with EXACT time reversibility
from simgen import vla

def lorenz_derivs(x, y, z):
    sigma = vla.ModularRational.from_int(10)
    rho = vla.ModularRational.from_int(28)
    beta = vla.ModularRational.from_fraction(8, 3)
    return sigma*(y-x), x*(rho-z)-y, x*y - beta*z

dt = vla.ModularRational.from_fraction(1, 1000)
x, y, z = [vla.ModularRational.from_int(1)]*3
stored = []

# Forward 5000 steps
for _ in range(5000):
    dx, dy, dz = lorenz_derivs(x, y, z)
    stored.append((dx, dy, dz))
    x, y, z = x + dt*dx, y + dt*dy, z + dt*dz

# Backward 5000 steps (using stored derivatives)
for dx, dy, dz in reversed(stored):
    x, y, z = x - dt*dx, y - dt*dy, z - dt*dz

# TRUE ZERO - back to start!
print(x == vla.ModularRational.from_int(1))  # True

import torch
from simgen import vla

# Create test data
x = torch.randn(10000, device='cuda')

# Exact sum with zero accumulation error
result = vla.sum(x)

# Get cross-GPU checksum (SAME on any GPU!)
checksum = vla.checksum(result)
print(f"Checksum: {checksum}")  # e.g., "6ece6956f187064f"

import torch
from simgen import vla

# Instead of 0.001 (NOT exact), use vla.frac():
dt = vla.frac(1, 1024)  # Exact 0.0009765625

# Check if a value is exact
vla.is_exact(0.125)  # True (1/8 = 2^-3)
vla.is_exact(0.001)  # False (infinite binary expansion)

# See exact stored value with VLADecimal
x = vla.Decimal(torch.tensor([0.001], device='cuda'))
print(x.to_decimal())  # Shows exact stored representation

# Find the best dyadic approximation
num, denom, exact, error = vla.dyadic(0.001)
# (1, 1024, 0.0009765625, 0.0000234375)

import torch
from simgen import vla

vla.enable()  # Now ALL torch ops use VLA!

# These now use exact arithmetic automatically:
torch.sum(x)       # Uses VLA internally
torch.matmul(A, B) # Uses VLA internally
model(input)       # Entire model uses VLA!

vla.disable()  # Restore standard PyTorch ops

with vla.mode():
    # All operations in this block use VLA
    result = torch.sum(x)
    output = model(input)
# Back to standard PyTorch outside the block

# Standard: precision lost at each step
r = vla.sqrt(vla.add(vla.mul(x, x), vla.mul(y, y)))

# Chained: full precision preserved through entire computation
x2 = vla.mul(x, x, return_vla=True)
y2 = vla.mul(y, y, return_vla=True)
r2 = vla.add(x2, y2, return_vla=True)
r = vla.sqrt(r2)  # Final collapse to tensor

# Compute deterministic checksum
result = vla.matmul(A, B)
cs = vla.checksum(result)  # "6ece6956f187064f"

# Full 64-char SHA256
full_cs = vla.checksum_hex(result)

# Verify result matches expected checksum
vla.verify(result, "6ece6956f187064f")  # Raises ValueError if mismatch

# Non-raising version
is_valid = vla.verify(result, "6ece6956f187064f", raise_on_mismatch=False)