eenn — Enlightened Equation Neural Network

A hybrid neural-symbolic constraint solver with cognitive reasoning capabilities.

⚠️ Status: Experimental / Research Prototype
This project is not yet ready for production use. It's a research platform exploring hybrid neural-symbolic constraint solving.

Overview

eenn is an experimental constraint solver that combines neural network guidance with symbolic reasoning to solve mathematical constraint problems. It features:

• 🧠 Hybrid Architecture: Neural hints guide symbolic SMT solving
• ⚡ Lightning Strike: Cognitive reasoning engine with dynamic strategy selection
• 🔢 Advanced Constraint Solving: Handles linear systems, non-linear equations, and inequality ranges
• 🎯 Smart Features: Parentheses support, inequality ranges, multi-variable systems

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
eenn = "0.1"

Or install the CLI tool:

cargo install eenn

Basic Usage

# Solve a simple equation
eenn-solve solve -p "x + y = 10 and x - y = 4"
# Output: x = 7, y = 3

# Non-linear systems
eenn-solve solve -p "x * y = 12 and x + y = 7"
# Output: x = 3, y = 4

# Parentheses support
eenn-solve solve -p "3 * (2 + 5) = 21"
# Output: (solution found)

# Inequality ranges
eenn-solve solve -p "x > 5 and x < 10"
# Output: 5 < x < 10

Features

1. Parentheses-Aware Expression Parsing

Handles nested expressions with proper operator precedence:

// Correctly parses: 3 * (2 + 5) = 21
// Evaluates inner expression first

2. Non-Linear System Solving

Uses intelligent brute-force search for small integer domains:

eenn-solve solve -p "x * y = 12 and x + y = 7"
# Finds: x = 3, y = 4 (or x = 4, y = 3)

3. Inequality Range Solutions

Shows solution ranges instead of arbitrary single values:

eenn-solve solve -p "x >= 0 and x <= 100"
# Output: 0 <= x <= 100

eenn-solve solve -p "x > 5 and x <= 15"
# Output: 5 < x <= 15

4. Lightning Strike Cognitive Engine

Dynamic reasoning strategy selection based on problem characteristics:

• Linear Algebra for systems of linear equations
• Symbolic SMT for complex constraints
• Neural Guidance for pattern recognition
• Brute Force for small non-linear systems

Architecture

Hybrid Reasoning Pipeline

┌─────────────────┐
│  User Constraint│
│     Parser      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Lightning      │
│    Strike       │◄─── Cognitive branch selection
│   Reasoning     │
└────────┬────────┘
         │
         ├─► Neural Surrogate (pattern hints)
         │
         ├─► SMT Backend (symbolic solving)
         │       ├─► Linear System Solver
         │       ├─► Non-Linear Brute Force
         │       └─► Inequality Range Detector
         │
         └─► Hybrid Verification

Key Components

• theory_core: Core constraint solving logic, SMT backend, Lightning Strike engine
• constraint_parser: Expression parsing with parentheses support
• smt_stub: Linear, non-linear, and inequality solvers
• lightning_strike: Cognitive reasoning and strategy selection
• surrogate: Neural network guidance (demo implementation)

Library Usage

As a Constraint Solver

use eenn::constraint_parser::parse_constraints;
use theory_core::{SmtBackend, ConstraintSolver};

// Parse constraints
let (constraints, var_map) = parse_constraints("x + y = 10 and x > 5")?;

// Solve
let backend = SmtBackend::new();
let solution = backend.solve(&constraints)?;

// Access results
if solution.satisfiable {
    for (var, value) in &solution.assignment {
        println!("{} = {}", var, value);
    }
    
    // Check for ranges (inequalities)
    if let Some(ranges) = &solution.variable_ranges {
        for (var, range) in ranges {
            println!("{}", range); // e.g., "5 < x"
        }
    }
}

As a Neural Network Library

eenn also provides basic neural network building blocks:

use eenn::{FunctionRegistry, Neuron, Stage, relu, scale};

// Create a function registry
let mut registry = FunctionRegistry::empty();
registry.register_fn("relu", relu, "ReLU activation");

// Build a simple neuron
let neuron = Neuron::new(
    vec![Stage::new(scale(2.0))],
    Stage::new(relu)
);

// Evaluate
let output = neuron.eval(3.0); // = relu(6.0) = 6.0

Command-Line Interface

eenn-solve

The eenn-solve binary provides an interactive constraint solving interface:

# Basic solving
eenn-solve solve -p "equation"

# Verbose mode (shows strategy and timing)
eenn-solve solve -p "equation" -v

# Interactive mode
eenn-solve solve

Examples

# Linear systems
eenn-solve solve -p "2*x + 3*y = 13 and x - y = 1"

# Non-linear
eenn-solve solve -p "x^2 = 16"

# Inequalities
eenn-solve solve -p "x >= 10 and x <= 20"

# Complex expressions with parentheses
eenn-solve solve -p "2 * (x + 3) = 10"

Advanced Features

Zero-Copy Serialization (Optional)

eenn uses rkyv for optional zero-copy serialization of neural network architectures:

[dependencies]
eenn = { version = "0.1", features = ["rkyv"] }

# Run tests with rkyv
cargo test --features rkyv

# Unsafe fast path (trusted inputs only)
cargo test --features "rkyv rkyv_unchecked"

Note: The rkyv feature provides zero-copy deserialization for optimal performance. Neural network weights use standard serde serialization.

GPU Acceleration (Experimental)

[dependencies]
eenn = { version = "0.1", features = ["gpu"] }

GPU support is experimental and requires WGPU-compatible hardware.

Known Limitations

1. Reversed Comparisons: 5 < x must be written as x > 5

   • Parser currently expects variable on the left side
   • Workaround: Rewrite constraints in standard form

2. Non-Linear Complexity: Brute-force search limited to small domains

   • Default range: -20 to 20
   • Maximum combinations: 1,000,000
   • Use for small integer problems only

3. Inequality Mixing: Mixed equality/inequality constraints may not optimize ranges

   • Pure inequality constraints → range output
   • Mixed constraints → single value from equality solver

Benchmarking

The repository includes benchmarks comparing different solving strategies and serialization performance.

Running Benchmarks

# Run all benchmarks
cargo bench --all-features

# Run specific benchmark
cargo bench --bench simple_bench

# Compare rehydration performance
cargo bench --bench rehydration_bench

The benchmarks compare:

• Solving Strategies: Linear vs. brute-force vs. symbolic SMT
• Serialization: Standard serde vs. rkyv zero-copy
• Rehydration: Validated vs. unchecked deserialization paths

Note: For reproducible results, pin dependencies and use consistent CPU frequency/power settings.

Development

Building from Source

# Clone the repository
git clone https://github.com/ciresnave/eenn.git
cd eenn

# Build
cargo build --release

# Run tests
cargo test

# Run with specific features
cargo test --features rkyv

Project Structure

eenn/
├── src/
│   ├── lib.rs                    # Main library
│   ├── constraint_parser.rs      # Expression parsing
│   ├── models.rs                 # Neural network serialization
│   ├── nn.rs                     # Neural network training
│   └── bin/
│       └── eenn-solve.rs         # CLI application
├── crates/
│   ├── theory_core/              # Core constraint solving
│   │   ├── src/
│   │   │   ├── smt_stub.rs       # SMT backend
│   │   │   ├── lightning_strike.rs # Cognitive reasoning
│   │   │   ├── surrogate.rs      # Neural guidance
│   │   │   └── ir.rs             # Constraint IR
│   │   └── Cargo.toml
│   └── lightning_strike/         # Standalone reasoning crate
├── tests/                        # Integration tests
├── examples/                     # Example programs
└── benches/                      # Benchmarks

Running Benchmarks

cargo bench

Future Directions

eenn v2 is planned as a complete rewrite built on:

• Candle: Modern Rust tensor library
• llama.cpp: Efficient LLM inference
• vLLM: Production-grade serving

This will enable true neural constraint solving with real language models.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE-2.0 or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Citation

If you use eenn in your research, please cite:

@software{eenn2025,
  author = {Evans, Eric},
  title = {eenn: Enlightened Equation Neural Network},
  year = {2025},
  url = {https://github.com/ciresnave/eenn}
}

Acknowledgments

eenn builds on research in:

• Hybrid neural-symbolic reasoning
• SMT solving and constraint satisfaction
• Cognitive architectures for AI

Contact

• GitHub: https://github.com/ciresnave/eenn
• Issues: https://github.com/ciresnave/eenn/issues

Status: Experimental / Research Prototype

This is a research project exploring hybrid neural-symbolic constraint solving. While functional, it is not recommended for production use without thorough testing for your specific use case.