TensorLogic

Logic-as-Tensor Planning Layer for Neural-Symbolic AI

TensorLogic compiles logical rules (predicates, quantifiers, implications) into tensor equations (einsum graphs) with a minimal DSL + IR, enabling neural/symbolic/probabilistic models within a unified tensor computation framework.

✨ Key Features

• 🧠 Logic-to-Tensor Compilation: Compile complex logical rules into optimized tensor operations
• ⚡ High Performance: SciRS2 backend with SIMD acceleration (2-4x speedup)
• 🐍 Python Bindings: Production-ready PyO3 bindings with NumPy integration
• 🔧 Multiple Backends: CPU, SIMD-accelerated CPU, GPU (OxiCUDA, driver-only)
• 📊 Comprehensive Benchmarks: 24 benchmark groups across 5 suites
• 🧪 Extensively Tested: 7,178 tests with 100% pass rate
• 📚 Rich Documentation: Tutorials, examples, API docs
• 🔗 Ecosystem Integration: OxiRS (RDF*/SHACL), SkleaRS, QuantrS2, TrustformeRS, ToRSh
• 🤖 Neurosymbolic AI: Bidirectional tensor conversion with ToRSh (pure Rust PyTorch alternative)

🎉 Stable Release

Version: 0.1.1 | Status: Stable Release | Date: 2026-06-09

TensorLogic has reached stable release status with comprehensive testing, benchmarking, and documentation:

• ✅ SciRS2 ecosystem upgraded to 0.3.4 — Latest scientific computing backend
• ✅ OxiRS ecosystem upgraded to 0.2.2 — Major RDF/knowledge graph API upgrade
• ✅ SkleaRS upgraded to 0.1.0 stable — Production-ready kernel integration
• ✅ ToRSh upgraded to 0.1.1 — Enhanced neurosymbolic tensor interop
• ✅ oxicode upgraded to 0.2 — Improved serialization/codec
• ✅ Pure Rust compression — flate2 replaced with oxiarc-deflate (OxiARC policy)
• ✅ RNG unified via scirs2core — All rand09/randdistr05 aliases removed; no direct rand deps
• ✅ No unwrap() in production/example/bench code — clippy::unwrap_used = 0
• ✅ 7,178/7,178 tests passing (100% pass rate)
• ✅ Zero compiler/clippy warnings — Clean build with latest dependencies
• ✅ Exact LTL operators — Release/WeakUntil/StrongRelease with backward-scan recurrences in scirs-backend
• ✅ OxiCUDA enhancements — f64 variants, PCG preconditioned solver, generic SparseCsr, f64/streaming RNG
• ✅ Probabilistic Execution — Monte Carlo integration, variational inference, epistemic uncertainty in scirs-backend
• ✅ SPARQL tensor evaluation — Conjunctive BGP queries via EinsumGraph contraction in oxirs-bridge
• ✅ Neural Architecture Search — Regularized Evolution + ask/tell API in tensorlogic-train
• ✅ SVM via SMO — C-SVM + ε-SVR with Platt SMO in tensorlogic-sklears-kernels

Ready for real-world use in research, production systems, and educational contexts!

🚀 Quick Start

Rust

use tensorlogiccompiler::compileto_einsum;
use tensorlogic_ir::{TLExpr, Term};
use tensorlogicscirsbackend::Scirs2Exec;
use tensorlogic_infer::TlAutodiff;
// Define a logical rule: knows(x, y) ∧ knows(y, z) → knows(x, z) let x = Term::var("x"); let y = Term::var("y"); let z = Term::var("z");
let knows_xy = TLExpr::pred("knows", vec![x.clone(), y.clone()]); let knows_yz = TLExpr::pred("knows", vec![y.clone(), z.clone()]); let premise = TLExpr::and(knowsxy, knowsyz);
// Compile to tensor graph let graph = compiletoeinsum(&premise)?;
// Execute with SciRS2 backend let mut executor = Scirs2Exec::new(); // Add tensor data... let result = executor.forward(&graph)?;

Python

import pytensorlogic as tl
import numpy as np
Create logical expressions
x, y = tl.var("x"), tl.var("y")
knows = tl.pred("knows", [x, y])
knows_someone = tl.exists("y", "Person", knows)
Create compiler context and register domain (required for quantifiers)
ctx = tl.compiler_context()
ctx.add_domain("Person", 100)
Compile to tensor graph with context
graph = tl.compilewithcontext(knows_someone, ctx)
Execute with data
knows_matrix = np.random.rand(100, 100)
result = tl.execute(graph, {"knows": knows_matrix})
print(f"Result shape: {result['output'].shape}")  # (100,)

📦 Installation

Rust

Add to your Cargo.toml:

[dependencies]
tensorlogic-ir = "0.1"
tensorlogic-compiler = "0.1"
tensorlogic-scirs-backend = { version = "0.1", features = ["simd"] }

Python

# From PyPI (when published)
pip install pytensorlogic
From source
cd crates/tensorlogic-py
pip install maturin
maturin develop --release

For detailed installation instructions, see crates/tensorlogic-py/PACKAGING.md.

📖 Documentation

Guides

• Project Guide: Complete project overview and development guide
• Python Packaging: Building and distributing Python wheels
• SciRS2 Integration Policy: Using SciRS2 as the tensor backend
• Security Policy: Reporting vulnerabilities
• Contributing: How to contribute

Tutorials

• Getting Started: Beginner-friendly introduction (Jupyter)
• Advanced Topics: Multi-arity predicates, optimization (Jupyter)

Examples

Rust Examples (in examples/):

• 00minimalrule - Basic predicate and compilation
• 01existsreduce - Existential quantifier with reduction
• 02scirs2execution - Full execution with SciRS2 backend
• 03rdfintegration - OxiRS bridge with RDF* data
• 04compilationstrategies - Comparing 6 strategy presets

Python Examples (in crates/tensorlogic-py/python_examples/):

• 10+ examples covering all features
• Backend selection and capabilities
• Compilation strategies
• Integration patterns

🏗️ Architecture

TensorLogic follows a modular architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                    Python Bindings                      │
│              (tensorlogic-py via PyO3)                  │
├─────────────────────────────────────────────────────────┤
│                   Planning Layer                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ IR & AST     │  │  Compiler    │  │  Adapters    │ │
│  │ (types)      │→ │  (logic→IR)  │→ │ (metadata)   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────┤
│                  Execution Layer                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Traits       │  │ SciRS2       │  │  Training    │ │
│  │ (interfaces) │  │ (CPU/SIMD)   │  │  (loops)     │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────┤
│                 Integration Layer                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  OxiRS       │  │  SkleaRS     │  │ TrustformeRS │ │
│  │  (RDF*/SHACL)│  │  (kernels)   │  │ (attention)  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│  ┌──────────────┐  ┌──────────────┐                   │
│  │  QuantrS2    │  │   ToRSh      │                   │
│  │  (PGM/BP)    │  │ (PyTorch Alt)│                   │
│  └──────────────┘  └──────────────┘                   │
└─────────────────────────────────────────────────────────┘

📚 Workspace Structure

The project is organized as a Cargo workspace with 13 specialized crates:

Core

| Crate | Purpose | Status | |-------|---------|--------| | tensorlogic | Root crate re-exporting the public API | ✅ Stable | | tensorlogic-cli | REPL and command-line interface | ✅ Stable |

Planning Layer (Engine-Agnostic)

| Crate | Purpose | Status | |-------|---------|--------| | tensorlogic-ir | AST and IR types (Term, TLExpr, EinsumGraph) | ✅ Complete | | tensorlogic-compiler | Logic → tensor mapping with static analysis | ✅ Complete | | tensorlogic-infer | Execution/autodiff traits (TlExecutor, TlAutodiff) | ✅ Complete | | tensorlogic-adapters | Symbol tables, axis metadata, domain masks | ✅ Complete |

Execution Layer (SciRS2-Powered)

| Crate | Purpose | Status | |-------|---------|--------| | tensorlogic-scirs-backend | Runtime executor (CPU/SIMD/GPU via features) | ✅ Production Ready | | tensorlogic-train | Training loops, loss wiring, schedules, callbacks | ✅ Complete |

Integration Layer

| Crate | Purpose | Status | |-------|---------|--------| | tensorlogic-oxirs-bridge | RDF*/GraphQL/SHACL → TL rules; provenance binding | ✅ Complete | | tensorlogic-sklears-kernels | Logic-derived similarity kernels for SkleaRS | ✅ Core Features | | tensorlogic-quantrs-hooks | PGM/message-passing interop for QuantrS2 | ✅ Core Features | | tensorlogic-trustformers | Transformer-as-rules (attention/FFN as einsum) | ✅ Complete | | tensorlogic-py | PyO3 bindings with abi3-py39 support | ✅ Production Ready |

GPU Utilities (OxiCUDA)

| Crate | Purpose | Status | |-------|---------|--------| | tensorlogic-oxicuda-rng | GPU-accelerated RNG (PCG/Box-Muller) with CPU fallback — 60 tests | ✅ Complete | | tensorlogic-oxicuda-solver | GPU-accelerated linear solvers (LU/Cholesky/QR/CG) with CPU fallback — 47 tests | ✅ Complete | | tensorlogic-oxicuda-sparse | GPU-accelerated sparse matrix ops (SpMV/SpMM/CSR) with CPU fallback — 27 tests | ✅ Complete |

🔬 Logic-to-Tensor Mapping

TensorLogic uses these default mappings (configurable per use case):

| Logic Operation | Tensor Equivalent | Configurable Via | |-----------------|-------------------|------------------| | AND(a, b) | a * b (Hadamard product) | CompilationStrategy | | OR(a, b) | max(a, b) or soft variant | CompilationStrategy | | NOT(a) | 1 - a | CompilationStrategy | | ∃x. P(x) | sum(P, axis=x) or max | Quantifier config | | ∀x. P(x) | NOT(∃x. NOT(P(x))) (dual) | Quantifier config | | a → b | max(1-a, b) or ReLU(b-a) | ImplicationStrategy |

Compilation Strategies

Six preset strategies for different use cases:

• soft_differentiable - Neural network training (smooth gradients)
• hard_boolean - Discrete Boolean logic (exact semantics)
• fuzzy_godel - Gödel fuzzy logic (min/max operations)
• fuzzy_product - Product fuzzy logic (probabilistic)
• fuzzy_lukasiewicz - Łukasiewicz fuzzy logic (bounded)
• probabilistic - Probabilistic interpretation

⚡ Performance

Benchmark Suite

TensorLogic includes comprehensive benchmarks across 5 suites (24 benchmark groups):

# Run all benchmarks
cargo bench -p tensorlogic-scirs-backend
Individual suites
cargo bench --bench forward_pass
cargo bench --bench simd_comparison --features simd
cargo bench --bench memory_footprint
cargo bench --bench gradient_stability
cargo bench --bench throughput

SIMD Acceleration

Enable SIMD for 2-4x performance improvement:

[dependencies]
tensorlogic-scirs-backend = { version = "0.1", features = ["simd"] }

Or build with target-specific optimizations:

RUSTFLAGS="-C target-cpu=native" cargo build --release --features simd

Benchmark Results

Typical speedups with SIMD acceleration:

| Operation Type | Size | CPU | SIMD | Speedup | |---------------|------|-----|------|---------| | Element-wise (add) | 100K | 50 µs | 15 µs | 3.3x | | Element-wise (mul) | 100K | 48 µs | 14 µs | 3.4x | | Matrix (hadamard) | 100×100 | 120 µs | 35 µs | 3.4x | | Reduction (sum) | 100K | 45 µs | 18 µs | 2.5x |

Results on Intel Core i7 with AVX2. Your results may vary.

🤖 Neurosymbolic AI with ToRSh

TensorLogic integrates seamlessly with ToRSh (pure Rust PyTorch alternative) for neurosymbolic AI applications:

use tensorlogicscirsbackend::torsh_interop::*;
use torsh_tensor::Tensor;
use torsh_core::device::DeviceType;
// Logic execution results → Neural network input let logicresults = compileandexecuterules()?; let torshtensor = tltotorshf32(&logic_results, DeviceType::Cpu)?;
// Neural network processing let nnoutput = neuralnetwork.forward(torsh_tensor)?;
// Neural output → Logic constraints let logicconstraints = torshtotl(&nnoutput)?; verifyconstraints(&logicconstraints)?;

Features:

• ✅ Bidirectional conversion (TensorLogic ↔ ToRSh)
• ✅ Type support (f32/f64 with automatic conversion)
• ✅ Lossless roundtrip for f64 precision
• ✅ Feature-gated: --features torsh (optional)
• ✅ Pure Rust (no C++ PyTorch dependencies)

Use Cases:

• Differentiable logic programming: Gradient descent on logic rules
• Hybrid systems: Combine symbolic reasoning with neural learning
• Explainable AI: Logic constraints on neural network outputs
• Knowledge-guided learning: Inject symbolic knowledge into neural models

Basic Example:

cargo run --example torsh_integration --features torsh

Advanced Neurosymbolic Examples

Knowledge Graph Reasoning (knowledgegraph_reasoning.rs):

cargo run --example knowledgegraphreasoning --features torsh

Demonstrates hybrid logic-neural reasoning for knowledge completion:

• Symbolic rules: transitivity, symmetry (friendOf relations)
• Neural embeddings: entity similarity via learned representations
• Hybrid scoring: α·logic + (1-α)·neural with configurable weights
• Constraint validation: bidirectional conversion for verification

Constrained Neural Optimization (constrainedneural_optimization.rs):

cargo run --example constrainedneuraloptimization --features torsh

Shows how to enforce logical constraints on neural network outputs:

• Logical constraints: mutual exclusivity, hierarchical rules
• Violation detection: automatic constraint checking
• Guided correction: constraint-aware prediction adjustments
• Training integration: constraint loss for gradient descent

See also: torsh_integration.rs for basic ToRSh interop usage.

🧪 Testing

TensorLogic has extensive test coverage:

# Run all tests
cargo test --workspace --no-fail-fast
Or use nextest (faster)
cargo nextest run --workspace
Python tests
cd crates/tensorlogic-py
pytest tests/ -v

Test Statistics:

• 7,178 tests across all crates (lib + integration + doc)
• 100% pass rate (37 tests intentionally skipped)
• Zero compiler warnings, zero clippy warnings, zero rustdoc warnings
• ~325K lines of Rust code (1,108 source files — tokei)
• Coverage includes:

- Unit tests (logic operations, type checking, optimization) - Integration tests (end-to-end workflows) - Property tests (algebraic properties) - Documentation tests (examples in code documentation) - Python tests (comprehensive pytest suite)

🛠️ Development

Prerequisites

• Rust 1.70+ (rustup recommended)
• Python 3.9+ (for Python bindings)
• Cargo nextest (optional, faster testing)

Building

# Clone repository
git clone https://github.com/cool-japan/tensorlogic.git
cd tensorlogic
Build all crates
cargo build
Build with SIMD
cargo build --features simd
Run example
cargo run --example 00minimalrule

Code Quality

# Format code
cargo fmt --all
Run linter
cargo clippy --workspace --all-targets -- -D warnings
Run tests
cargo nextest run --workspace

Python Development

cd crates/tensorlogic-py
Install in development mode
make dev
Run tests
make test
Build wheels
make wheels

See crates/tensorlogic-py/PACKAGING.md for detailed instructions.

🌟 Advanced Features

Type System

use tensorlogic_ir::{Term, PredicateSignature};
// Define typed predicates let sig = PredicateSignature::new("parent", 2)     .withargumenttype(0, "Person")     .withargumenttype(1, "Person")     .withreturntype("Bool");

Graph Optimization

use tensorlogic_ir::optimization::OptimizationPipeline;
let mut graph = compiletoeinsum(&expr)?;
// Apply optimizations let pipeline = OptimizationPipeline::default(); let stats = pipeline.optimize(&mut graph)?;
println!("Eliminated {} dead nodes", stats.nodes_eliminated);

Provenance Tracking

use tensorlogicoxirsbridge::ProvenanceTracker;
let mut tracker = ProvenanceTracker::new(); tracker.addrule("rule1", &expr);
// Track tensor computations back to source rules let provenance = tracker.getprovenance(tensorid);

Batch Execution

use tensorlogic_infer::TlBatchExecutor;
let inputs = vec![tensor1, tensor2, tensor3]; let batchresult = executor.executebatch(&graph, inputs)?;

🔗 Ecosystem Integration

OxiRS Integration (RDF*/SHACL)

use tensorlogicoxirsbridge::schema::SchemaAnalyzer;
let analyzer = SchemaAnalyzer::fromturtle(&rdfdata)?; let symbols = analyzer.extractsymboltable()?; let rules = shacltotensorlogic(&shacl_constraints)?;

SkleaRS Kernels

use tensorlogicsklearskernels::{RuleSimilarityKernel, TensorKernel};
let kernel = RuleSimilarityKernel::new(rule1, rule2); let similarity = kernel.compute(&data1, &data2)?;

TrustformeRS (Transformers)

use tensorlogic_trustformers::{SelfAttention, MultiHeadAttention};
let attention = MultiHeadAttention::new(512, 8); let output = attention.forward(&query, &key, &value)?;

📊 Project Status

| Phase | Component | Status | Completion | |-------|-----------|--------|------------| | 0 | Repo Hygiene | ✅ Complete | 100% | | 1 | IR & Compiler | ✅ Complete | 100% | | 2 | Engine Traits | ✅ Complete | 100% | | 3 | SciRS2 Backend | ✅ Production Ready | 100% | | 4 | OxiRS Bridge | ✅ Complete | 100% | | 4.5 | Core Enhancements | ✅ Production Ready | 100% | | 5 | Interop Crates | ✅ Core Features | 50-100% | | 6 | Training Scaffolds | ✅ Complete | 100% | | 7 | Python Bindings | ✅ Production Ready | 98% | | 8 | Validation & Scale | ✅ Complete | 100% |

Overall Project Status: 🎉 Stable Release (0.1.1)

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• 🐛 Bug reports and fixes
• 📚 Documentation improvements
• ✨ New features and optimizations
• 🧪 Additional tests and benchmarks
• 🌍 Multi-language support
• 📦 Packaging and distribution

Development Workflow

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Make your changes
• Run tests (cargo nextest run)
• Format code (cargo fmt)
• Run linter (cargo clippy)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to branch (git push origin feature/amazing-feature)
• Open a Pull Request

Sponsorship

TensorLogic is developed and maintained by COOLJAPAN OU (Team Kitasan).

If you find TensorLogic useful, please consider sponsoring the project to support continued development of the Pure Rust ecosystem.

https://github.com/sponsors/cool-japan

Your sponsorship helps us:

• Maintain and improve the COOLJAPAN ecosystem
• Keep the entire ecosystem (OxiBLAS, OxiFFT, SciRS2, etc.) 100% Pure Rust
• Provide long-term support and security updates

📄 License

Licensed under Apache 2.0 License. See LICENSE for details.

🙏 Acknowledgments

• Tensor Logic Paper: arXiv:2510.12269
• SciRS2: Scientific computing in Rust
• PyO3: Rust bindings for Python
• Maturin: Building Python packages from Rust

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

Short-term (Next Release)

• [x] GPU backend support - ✅ COMPLETE (OxiCUDA driver-only, no CUDA SDK needed — tensorlogic-oxicuda-{rng,solver,sparse,backend})
• [ ] Additional fuzzy logic variants
• [x] ToRSh tensor interoperability - ✅ COMPLETE (pure Rust alternative to PyTorch)
• [x] Provenance API in Python bindings - ✅ COMPLETE (get_provenance)
• [x] SciRS2 ecosystem upgrade - ✅ COMPLETE (upgraded to 0.3.4)
• [x] OxiRS ecosystem upgrade - ✅ COMPLETE (upgraded to 0.2.2)
• [x] rand 0.10 full alignment - ✅ COMPLETE

Medium-term

• [ ] Distributed execution support
• [ ] JIT compilation
• [ ] Additional interop crates
• [ ] Performance profiling tools

Long-term

• [ ] Visual graph editor
• [ ] Cloud deployment templates
• [ ] Auto-tuning and optimization
• [ ] Multi-language support (Julia, R)

---

Built with ❤️ by the COOLJAPAN team

For detailed project information, see CLAUDE.md and TODO.md.