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

Reversed Comparisons: 5 < x must be written as x > 5
- Parser currently expects variable on the left side
- Workaround: Rewrite constraints in standard form
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
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:

Fork the repository
Create a feature branch
Add tests for new functionality
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.

eenn 0.1.0

eenn — Enlightened Equation Neural Network

Overview

Quick Start

Installation

Basic Usage

Features

1. Parentheses-Aware Expression Parsing

2. Non-Linear System Solving

3. Inequality Range Solutions

4. Lightning Strike Cognitive Engine

Architecture

Hybrid Reasoning Pipeline

Key Components

Library Usage

As a Constraint Solver

As a Neural Network Library

Command-Line Interface

eenn-solve

Examples

Advanced Features

Zero-Copy Serialization (Optional)

GPU Acceleration (Experimental)

Known Limitations

Benchmarking

Running Benchmarks

Development

Building from Source

Project Structure

Running Benchmarks

Future Directions

Contributing

License

Citation

Acknowledgments

Contact