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: 6,982 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.0 | Status: Stable Release | Date: 2026-04-27

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 scirs2_core — All rand_09/rand_distr_05 aliases removed; no direct rand deps
• ✅ No unwrap() in production/example/bench code — clippy::unwrap_used = 0
• ✅ 6,982/6,982 tests passing (100% pass rate)
• ✅ Zero compiler/clippy warnings — Clean build with latest dependencies

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

🚀 Quick Start

Rust

use tensorlogic_compiler::compile_to_einsum;
use tensorlogic_ir::{TLExpr, Term};
use tensorlogic_scirs_backend::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(knows_xy, knows_yz);

// Compile to tensor graph
let graph = compile_to_einsum(&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.compile_with_context(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/):

• 00_minimal_rule - Basic predicate and compilation
• 01_exists_reduce - Existential quantifier with reduction
• 02_scirs2_execution - Full execution with SciRS2 backend
• 03_rdf_integration - OxiRS bridge with RDF* data
• 04_compilation_strategies - 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 — 47 tests	✅ Complete
tensorlogic-oxicuda-solver	GPU-accelerated linear solvers (LU/Cholesky/QR/CG) with CPU fallback — 35 tests	✅ Complete
tensorlogic-oxicuda-sparse	GPU-accelerated sparse matrix ops (SpMV/SpMM/CSR) with CPU fallback — 13 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:

1. soft_differentiable - Neural network training (smooth gradients)
2. hard_boolean - Discrete Boolean logic (exact semantics)
3. fuzzy_godel - Gödel fuzzy logic (min/max operations)
4. fuzzy_product - Product fuzzy logic (probabilistic)
5. fuzzy_lukasiewicz - Łukasiewicz fuzzy logic (bounded)
6. 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 tensorlogic_scirs_backend::torsh_interop::*;
use torsh_tensor::Tensor;
use torsh_core::device::DeviceType;

// Logic execution results → Neural network input
let logic_results = compile_and_execute_rules()?;
let torsh_tensor = tl_to_torsh_f32(&logic_results, DeviceType::Cpu)?;

// Neural network processing
let nn_output = neural_network.forward(torsh_tensor)?;

// Neural output → Logic constraints
let logic_constraints = torsh_to_tl(&nn_output)?;
verify_constraints(&logic_constraints)?;

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 (knowledge_graph_reasoning.rs):

cargo run --example knowledge_graph_reasoning --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 (constrained_neural_optimization.rs):

cargo run --example constrained_neural_optimization --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:

• 6,982 tests across all crates (lib + integration + doc)
• 100% pass rate (12 tests intentionally skipped)
• Zero compiler warnings, zero clippy warnings, zero rustdoc warnings
• ~294K lines of Rust code (843 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 00_minimal_rule

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)
    .with_argument_type(0, "Person")
    .with_argument_type(1, "Person")
    .with_return_type("Bool");

Graph Optimization

use tensorlogic_ir::optimization::OptimizationPipeline;

let mut graph = compile_to_einsum(&expr)?;

// Apply optimizations
let pipeline = OptimizationPipeline::default();
let stats = pipeline.optimize(&mut graph)?;

println!("Eliminated {} dead nodes", stats.nodes_eliminated);

Provenance Tracking

use tensorlogic_oxirs_bridge::ProvenanceTracker;

let mut tracker = ProvenanceTracker::new();
tracker.add_rule("rule_1", &expr);

// Track tensor computations back to source rules
let provenance = tracker.get_provenance(tensor_id);

Batch Execution

use tensorlogic_infer::TlBatchExecutor;

let inputs = vec![tensor1, tensor2, tensor3];
let batch_result = executor.execute_batch(&graph, inputs)?;

🔗 Ecosystem Integration

OxiRS Integration (RDF*/SHACL)

use tensorlogic_oxirs_bridge::schema::SchemaAnalyzer;

let analyzer = SchemaAnalyzer::from_turtle(&rdf_data)?;
let symbols = analyzer.extract_symbol_table()?;
let rules = shacl_to_tensorlogic(&shacl_constraints)?;

SkleaRS Kernels

use tensorlogic_sklears_kernels::{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.0)

🤝 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (cargo nextest run)
5. Format code (cargo fmt)
6. Run linter (cargo clippy)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to branch (git push origin feature/amazing-feature)
9. 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)

• GPU backend support - ✅ COMPLETE (OxiCUDA driver-only, no CUDA SDK needed — tensorlogic-oxicuda-{rng,solver,sparse,backend})
• Additional fuzzy logic variants
• ToRSh tensor interoperability - ✅ COMPLETE (pure Rust alternative to PyTorch)
• Provenance API in Python bindings - ✅ COMPLETE (get_provenance)
• SciRS2 ecosystem upgrade - ✅ COMPLETE (upgraded to 0.3.4)
• OxiRS ecosystem upgrade - ✅ COMPLETE (upgraded to 0.2.2)
• 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.