Flux

1. Design Philosophy

Flux is built on a simple principle: if the math can't be written on paper and look the same way, it isn't correct Flux. This philosophy shapes every design decision.

Flux serves as the high-performance numerical engine of the Axiom Stack—a collection of tools designed for mathematical computing, formal verification, and AI-assisted reasoning.

2. Getting Started

2.1 Installation (Windows)

Quick Install

Flux is distributed as a standalone package. No compilation required.

1. Download `flux-1.0.0-windows.zip` from the Releases Page.
2. Extract the folder.
3. Right-click `install.ps1` and select "Run with PowerShell" (or run in terminal as Admin).

powershell -ExecutionPolicy Bypass -File install.ps1

2.2 Installation (Linux / macOS)

Download the latest tarball for your architecture.

# Extract and install
tar -xzf flux-1.0.0-linux.tar.gz
cd flux-1.0.0
sudo ./install.sh

2.3 Running Flux

Launch the REPL to see the new scientific banner:

flux

   +-------------------------------------------------------------+
   |    ______  __    __  __  __   __                            |
   |   /\  ___\/\ \  /\\ /\ \/\_\_\_\                            |
   |   \ \  __ \ \ \_\ \ \_\ \/_/\_\/_                           |
   |    \ \_\   \ \_____\ \_____\/\_\/\_\                        |
   |     \/_/    \/_____/\/_____/\/_/\/_/                        |
   |                                                             |
   |   Flux - Scientific Computational Engine                    |
   |   v1.0.0                                                    |
   +-------------------------------------------------------------+

2.3 Your First Flux Program

Create a file hello.flux:

-- A taste of paper-like math
x = 3
y = x² + 2·x + 1   -- (x + 1)² = 16

if y > 10:
    print "Math works!"
    print y

3. Paper-Like Syntax

Flux uses significant whitespace (indentation) instead of braces, and Unicode operators.

3.1 Multiplication Operators

Flux supports three equivalent multiplication operators:

-- All three are equivalent for scalar multiplication
a = 3 · 4     -- Middle dot: 12
b = 2 × 5     -- Times sign: 10  
c = 5 * 6     -- ASCII asterisk: 30

3.2 Superscript Exponents

Use Unicode superscript digits for exponents—just like on paper! Supported superscripts: ⁰¹²³⁴⁵⁶⁷⁸⁹

x = 2
quadratic = x² + 3·x + 2       -- x² is x^2
cubic = x³ - 1                 -- x³ is x^3
polynomial = x⁴ + 2·x² + 1     -- Higher powers work too!

3.3 Comments

Flux uses -- for comments, following mathematical and Haskell conventions rather than C-style //.

-- This is a single-line comment
gravity = 9.8  -- Acceleration due to gravity (m/s²)

4. Type System

Flux is dynamically typed but uses optimized native C structures for mathematical types.

4.1 Primitive Types

4.2 Mathematical Types

z = complex(3, 4)   -- 3 + 4i
print abs(z)        -- 5 (magnitude)
print conj(z)       -- 3 - 4i (conjugate)

v = vec(1, 2, 3)    -- 3D vector
w = vec(4, 5, 6)
print v · w         -- Dot product: 32

A = mat([[1, 2], [3, 4]])
I = mat([[1, 0], [0, 1]])   -- Identity
print A × A              -- Matrix multiplication
print det(A)             -- Determinant: -2

5. Operators

5.1 Arithmetic Operators

5.2 Comparison Operators

5.3 Logical Operators

6. Linear Algebra

Flux treats linear algebra as a first-class concern. Vectors and matrices have dedicated types with natural syntax for common operations.

6.1 Vectors

-- Define force and displacement vectors
F = vec(10, 0, 0)   -- 10N in x-direction
d = vec(5, 5, 0)    -- 5m in x, 5m in y

-- Calculate work using dot product
W = F · d
print W             -- Output: 50 (Joules)

Vector operations:

a = vec(1, 2, 3)
b = vec(4, 5, 6)

print a + b             -- Vector addition: vec(5, 7, 9)
print a - b             -- Vector subtraction: vec(-3, -3, -3)
print a · b             -- Dot product: 32
print cross(a, b)       -- Cross product: vec(-3, 6, -3)
print len(a)            -- Length (dimension): 3

6.2 Matrices

-- 2x2 rotation matrix (90 degrees)
R = mat([[0, -1], [1, 0]])

-- Identity matrix
I = mat([[1, 0], [0, 1]])

-- Matrix operations
print R × R              -- R² = 180° rotation
print det(R)             -- Determinant: 1
print transpose(R)       -- Transpose

Matrix operations:

A = mat([[1, 2], [3, 4]])
B = mat([[5, 6], [7, 8]])

print A + B             -- Element-wise addition
print A × B             -- Matrix multiplication
print det(A)            -- Determinant: -2
print transpose(A)      -- Transpose

7. Complex Numbers

Native complex number support enables clean implementation of signal processing, control systems, and quantum mechanics algorithms.

7.1 Basic Operations

z1 = complex(3, 4)   -- 3 + 4i
z2 = complex(1, 2)   -- 1 + 2i

print z1 + z2        -- 4 + 6i
print z1 × z2        -- -5 + 10i
print z1 / z2        -- 2.2 - 0.4i

7.2 Complex Functions

z = complex(3, 4)

print abs(z)             -- 5 (magnitude: √(3² + 4²))
print conj(z)            -- 3 - 4i (conjugate)
print real(z)            -- 3 (real part)
print imag(z)            -- 4 (imaginary part)

8. Numerical Calculus

Flux includes built-in numerical methods for differentiation and integration via the Prelude library.

8.1 Differentiation

The deriv(f, x) function computes the numerical derivative of function f at point x using central differences.

f(x) = x² + 2·x + 1  -- Math-style definition

print deriv(f, 3)    -- d/dx at x=3 → ~8.0
                      -- (Analytical: 2x + 2 = 8)

8.2 Integration

The integrate(f, a, b) function computes the definite integral \(\int_a^b f(x)\,dx\) using Simpson's rule.

g(x) = x²

print integrate(g, 0, 1)    -- ∫₀¹ x² dx → ~0.333
                             -- (Analytical: 1/3)

-- Constant acceleration
a(t) = 9.8

-- Velocity: ∫a·dt from 0 to t
print integrate(a, 0, 5)    -- v(5) ≈ 49 m/s

-- For more complex scenarios, use numerical ODE solvers (planned)

9. Functions

9.1 Function Declaration

-- Math-style (Recommended)
square(x) = x²

-- Block-style (also valid with indentation)
fun add(a, b):
    return a + b

print square(5)      -- 25
print add(3, 4)      -- 7

9.2 First-Class Functions

Functions are values and can be passed as arguments:

apply_twice(f, x) = f(f(x))
increment(n) = n + 1

print apply_twice(increment, 5)  -- 7

9.3 Closures

Functions capture their enclosing environment:

fun make_adder(n):
    f(x) = x + n
    return f

add5 = make_adder(5)
print add5(10)    -- 15

9.4 Planned: Pattern Matching (Future)

-- Math-style function definition (planned)
factorial(0) = 1
factorial(n) = n · factorial(n - 1)

-- Fibonacci (planned)
fib(0) = 0
fib(1) = 1
fib(n) = fib(n - 1) + fib(n - 2)

10. Control Flow

10.1 Conditionals

x = 10

if x > 5:
    print "x is greater than 5"
else:
    print "x is 5 or less"

10.2 While Loops

i = 0
while i < 5:
    print i
    i = i + 1

10.3 For Loops

-- "for" loop desugars to while
i = 0
while i < 10:
    print i²
    i = i + 1

10.4 Expression-Oriented If

-- If-then-else is an expression!
max = if a > b then a else b

-- Nested if expressions
sign = if x > 0 then 1 else if x < 0 then -1 else 0

11. Standard Library (Prelude)

Flux's standard library is split into two layers: native functions (implemented in C for performance) and the Prelude (implemented in Flux itself for flexibility).

11.1 Native Functions

Mathematical Functions

Linear Algebra Functions

Utility Functions

11.2 Prelude Functions

High-level functions implemented in Flux:

12. Real-World Modeling

-- Disease Logic
if state[i] == INFECTED:
    -- Check for susceptible neighbors
    j = 0;
    while j < NUM_PARTICLES:
        if state[j] == SUSCEPTIBLE:
            delta = pos[j] - pos[i];
            
            -- Vector distance check
            dist_sq = dot(delta, delta);
            
            if dist_sq < INFECTION_RADIUS^2:
                -- Probabilistic infection
                if random() < INFECTION_PROB:
                    state[j] = INFECTED;
        j = j + 1;

-- State Transitions
if recovery_timer[i] > RECOVERY_TIME:
    state[i] = RECOVERED;

13. Novel Use Cases

Flux isn't just another scripting language—it's a computational kernel designed to bridge the gap between human mathematical thinking and machine execution. Here's how it's being used in ways no other language can match.

13.1 The Alexitha Bridge — Teaching AI to Actually Do Math

# The FluxBridge — Where AI Meets Mathematics
from core.flux_bridge import FluxBridge

bridge = FluxBridge()
result = bridge.execute("""
    f(x) = x²
    answer = integrate(f, 0, 1)
    print answer
""")

# Output: {"stdout": "0.333333", "success": true, "duration": 0.002}
# The answer is COMPUTED, not guessed.

Why this matters: This is the first step toward AI systems that can prove their answers are correct. Flux serves as the "ground truth" engine—a mathematical oracle that the AI must satisfy.

13.2 First-Principles Simulation — Physics From Scratch

-- Projectile Motion: From F = ma to Trajectory
-- Not a library call. The actual physics.

g = 9.8              -- Gravitational acceleration
v0 = 50              -- Initial velocity (m/s)  
θ = 45 * π / 180     -- Launch angle (radians)

-- Initial conditions
vx = v0 · cos(θ)     -- Horizontal velocity (constant)
vy = v0 · sin(θ)     -- Vertical velocity (changes)
x = 0
y = 0
t = 0
dt = 0.001           -- Time step (1 millisecond)

-- Euler Integration: The fundamental algorithm
while y >= 0:
    -- Update position (s = s₀ + v·Δt)
    x = x + vx · dt
    y = y + vy · dt
    
    -- Update velocity (v = v₀ + a·Δt, and a = -g)
    vy = vy - g · dt
    
    t = t + dt

print "Range: " + x + " meters"
print "Max height reached at t = " + (v0 · sin(θ) / g) + "s"

Educational Power: When Alexitha learns physics, it doesn't memorize formulas—it derives simulations. Every line of code maps to a physical principle. The AI understands why projectiles follow parabolas, not just that they do.

13.3 Game Theory Integration — Where Math Meets Strategy

-- Utility function for economic modeling
-- Risk-adjusted return with diminishing marginal utility

utility(wealth, risk) = sqrt(wealth) · exp(-0.1 · risk²)

-- Payoff calculations for a market entry game
entry_payoff(market_size, competitors) = 
    market_size / (competitors + 1) - 50000  -- Fixed entry cost

-- Tenet can import these for Nash equilibrium analysis:
-- payoff Firm1 { (Enter, Stay): entry_payoff(1000000, 2) }

-- Compute and verify
print "Utility(100, 2): " + utility(100, 2)       -- ~6.7
print "Entry payoff: " + entry_payoff(1000000, 2) -- ~283,333

This separation is powerful: Tenet handles the strategy, Flux handles the math. Economists can model complex real-world scenarios where payoffs depend on non-linear utility functions, risk preferences, and multi-variable optimization.

13.4 Operating System Executor — The Axiom Scheduler's Engine

-- Auto-generated by Tenet Scheduler
-- This script ENFORCES the Nash equilibrium allocation

print "=== Axiom Game-Theoretic Scheduler ==="

-- HIGH priority: octave_sim (Nash allocation: 4 cores, 8GB)
print "[EXEC] octave_sim (HIGH priority)"
cgroup_create("octave_sim")
cgroup_set_cpu("octave_sim", 4096)          -- CPU shares
cgroup_set_memory("octave_sim", 8589934592) -- 8GB hard limit
exit_code = cgroup_exec("octave_sim", "octave simulation.m")
print "  → Completed with exit code " + exit_code
cgroup_delete("octave_sim")

-- MED priority: r_analysis (Nash allocation: 2 cores, 16GB)
print "[EXEC] r_analysis (MEDIUM priority)"  
cgroup_create("r_analysis")
cgroup_set_cpu("r_analysis", 2048)
cgroup_set_memory("r_analysis", 17179869184) -- 16GB
exit_code = cgroup_exec("r_analysis", "Rscript analysis.R")
print "  → Completed with exit code " + exit_code
cgroup_delete("r_analysis")

print "=== All Tasks Complete ==="

This is not a normal scheduler. Traditional schedulers use heuristics that can lead to starvation, unfairness, or thrashing. The Axiom scheduler uses game theory—where fairness and efficiency emerge mathematically from the equilibrium, not from hand-tuned rules.