Expand description
IPFRS TensorLogic - Integration with TensorLogic IR
This crate provides comprehensive integration between IPFRS and TensorLogic including:
§Core Features
- IR (Intermediate Representation): Serialization and storage of logic terms
- Term and Predicate Storage: Content-addressed storage for logical statements
- Distributed Reasoning: Query caching, goal decomposition, and proof assembly
- Zero-Copy Tensor Transport: Apache Arrow integration for efficient data sharing
- Safetensors Support: Read/write Safetensors format for ML models
- PyTorch Checkpoint Support: Load/save PyTorch .pt/.pth model checkpoints
- Shared Memory: Cross-process memory mapping for large tensors
- Gradient Management: Compression, aggregation, and differential privacy
- Model Version Control: Git-like versioning for ML models
- Provenance Tracking: Complete lineage tracking for datasets and models
- Computation Graphs: IPLD-based graph storage with optimization
- Device Management: Heterogeneous device support with adaptive batch sizing
- FFI Profiling: Overhead measurement and bottleneck identification
- Allocation Optimization: Buffer pooling and zero-copy conversions
- GPU Support: Stub implementation for future CUDA/OpenCL/Vulkan integration
§Performance Targets
- FFI call overhead: < 1μs
- Zero-copy tensor access: < 100ns
- Query cache lookup: < 1μs
- Term serialization: < 10μs for small terms
§Examples
§Basic Term and Predicate Creation
use ipfrs_tensorlogic::{Term, Predicate, Constant};
// Create terms
let alice = Term::Const(Constant::String("Alice".to_string()));
let bob = Term::Const(Constant::String("Bob".to_string()));
let x = Term::Var("X".to_string());
// Create a predicate: parent(Alice, Bob)
let pred = Predicate::new("parent".to_string(), vec![alice, bob]);
assert!(pred.is_ground());§Zero-Copy Tensor Operations
use ipfrs_tensorlogic::{ArrowTensor, ArrowTensorStore};
// Create a tensor from f32 data
let data: Vec<f32> = vec![1.0, 2.0, 3.0, 4.0];
let tensor = ArrowTensor::from_slice_f32("my_tensor", vec![4], &data);
// Zero-copy access to the data
let slice = tensor.as_slice_f32().unwrap();
assert_eq!(slice[0], 1.0);
// Create a tensor store
let mut store = ArrowTensorStore::new();
store.insert(tensor);
assert_eq!(store.len(), 1);§Query Caching
use ipfrs_tensorlogic::{QueryCache, QueryKey};
// Create a cache with capacity 100
let cache = QueryCache::new(100);
// Insert a query result
let key = QueryKey {
predicate_name: "parent".to_string(),
ground_args: vec![],
};
cache.insert(key.clone(), vec![]);
// Retrieve from cache
let result = cache.get(&key);
assert!(result.is_some());§Gradient Compression
use ipfrs_tensorlogic::GradientCompressor;
let gradient = vec![0.1, 0.5, 0.01, 0.8, 0.02];
// Top-k compression (keep largest 2 values)
let sparse = GradientCompressor::top_k(&gradient, vec![5], 2).unwrap();
assert_eq!(sparse.nnz(), 2); // Only 2 non-zero elements
// Quantization to int8
let quantized = GradientCompressor::quantize(&gradient, vec![5]);
assert!(quantized.compression_ratio() > 1.0);§Device-Aware Batch Sizing
use ipfrs_tensorlogic::{DeviceCapabilities, AdaptiveBatchSizer};
use std::sync::Arc;
// Detect device capabilities
let caps = DeviceCapabilities::detect().unwrap();
println!("Device: {:?}, Memory: {} GB",
caps.device_type,
caps.memory.total_bytes / 1024 / 1024 / 1024);
// Create adaptive batch sizer
let sizer = AdaptiveBatchSizer::new(Arc::new(caps))
.with_min_batch_size(1)
.with_max_batch_size(256);
// Calculate optimal batch size
let model_size = 500 * 1024 * 1024; // 500MB model
let item_size = 256 * 1024; // 256KB per item
let batch_size = sizer.calculate(item_size, model_size);
println!("Optimal batch size: {}", batch_size);§FFI Profiling
use ipfrs_tensorlogic::{FfiProfiler, global_profiler};
let profiler = FfiProfiler::new();
// Profile a function call
{
let _guard = profiler.start("my_ffi_function");
// Your FFI code here
}
// Get statistics
let stats = profiler.get_stats("my_ffi_function").unwrap();
println!("Calls: {}, Avg: {:?}", stats.call_count, stats.avg_duration);
// Use global profiler
let global = global_profiler();
let _guard = global.start("global_operation");§Buffer Pooling
use ipfrs_tensorlogic::BufferPool;
let pool = BufferPool::new(4096, 10); // 4KB buffers, max 10 pooled
// Acquire buffer from pool
let mut buffer = pool.acquire();
buffer.as_mut().extend_from_slice(&[1, 2, 3, 4]);
// Buffer automatically returned to pool when dropped
drop(buffer);
assert!(pool.size() > 0); // Buffer available for reuse§Zero-Copy Conversions
use ipfrs_tensorlogic::ZeroCopyConverter;
let floats: Vec<f32> = vec![1.0, 2.0, 3.0, 4.0];
// Zero-copy conversion to bytes
let bytes = ZeroCopyConverter::slice_to_bytes(&floats);
assert_eq!(bytes.len(), 16); // 4 floats * 4 bytes
// Zero-copy conversion back
let floats_back: &[f32] = ZeroCopyConverter::bytes_to_slice(bytes);
assert_eq!(floats, floats_back);§Safetensors Multi-Dtype Support
use ipfrs_tensorlogic::{SafetensorsWriter, SafetensorsReader, ArrowTensor};
use bytes::Bytes;
// Create a model with multiple data types
let mut writer = SafetensorsWriter::new();
// Add float32 weights
writer.add_f32("layer1.weights", vec![128, 64], &vec![0.1; 8192]);
// Add float64 biases for high precision
writer.add_f64("layer1.bias", vec![64], &vec![0.01; 64]);
// Add int32 indices
writer.add_i32("vocab_indices", vec![1000], &vec![42; 1000]);
// Add int64 large IDs
writer.add_i64("entity_ids", vec![100], &vec![1000000; 100]);
// Serialize and read back
let bytes = writer.serialize().unwrap();
let reader = SafetensorsReader::from_bytes(Bytes::from(bytes)).unwrap();
// Load as Arrow tensors for zero-copy access
let weights = reader.load_as_arrow("layer1.weights").unwrap();
let bias = reader.load_as_arrow("layer1.bias").unwrap();
let indices = reader.load_as_arrow("vocab_indices").unwrap();
let ids = reader.load_as_arrow("entity_ids").unwrap();
assert!(weights.as_slice_f32().is_some());
assert!(bias.as_slice_f64().is_some());
assert!(indices.as_slice_i32().is_some());
assert!(ids.as_slice_i64().is_some());§Memory Profiling
use ipfrs_tensorlogic::MemoryProfiler;
use std::time::Duration;
let profiler = MemoryProfiler::new();
{
let _guard = profiler.start_tracking("tensor_allocation");
let data: Vec<f32> = vec![1.0; 1000000]; // ~4 MB
std::thread::sleep(Duration::from_millis(10));
drop(data);
}
let stats = profiler.get_stats("tensor_allocation").unwrap();
assert_eq!(stats.track_count, 1);
assert!(stats.total_duration >= Duration::from_millis(10));
// Generate and print a report
let report = profiler.generate_report();
println!("Total operations tracked: {}", report.total_operations);§Model Quantization
use ipfrs_tensorlogic::{QuantizedTensor, QuantizationConfig};
// Per-tensor INT8 symmetric quantization
let weights = vec![0.5, -0.3, 0.8, -0.1];
let config = QuantizationConfig::int8_symmetric();
let quantized = QuantizedTensor::quantize_per_tensor(&weights, vec![4], config).unwrap();
// Dequantize back to f32
let dequantized = quantized.dequantize();
assert_eq!(dequantized.len(), 4);
// Check compression ratio
println!("Compression: {:.2}x", quantized.compression_ratio());§More Examples
For complete examples, see the examples/ directory:
basic_reasoning.rs- TensorLogic inference and backward chainingquery_optimization.rs- Materialized views and query cachingproof_storage.rs- Proof fragment management and compressionproof_explanation_demo.rs- Automatic proof explanation in natural language (multiple styles)model_versioning.rs- Git-like version control for ML modelsmodel_quantization.rs- Model quantization for edge deployment (INT4/INT8, per-channel, dynamic)tensor_storage.rs- Safetensors and Arrow integrationdevice_aware_training.rs- Device detection and adaptive batchingfederated_learning.rs- Gradient compression and differential privacyallocation_optimization.rs- Buffer pooling and zero-copy techniquesffi_profiling.rs- FFI overhead measurementdistributed_graph_execution.rs- Graph partitioning across multiple workersmemory_profiling.rs- Memory usage tracking and profilingvisualization_demo.rs- Graph and proof visualization with DOT format
Re-exports§
pub use allocation_optimizer::AdaptiveBuffer;pub use allocation_optimizer::AllocationError;pub use allocation_optimizer::BufferPool;pub use allocation_optimizer::PooledBuffer;pub use allocation_optimizer::StackBuffer;pub use allocation_optimizer::TypedBufferPool;pub use allocation_optimizer::TypedPooledBuffer;pub use allocation_optimizer::ZeroCopyConverter;pub use arrow::ArrowTensor;pub use arrow::ArrowTensorStore;pub use arrow::TensorDtype;pub use arrow::TensorMetadata;pub use arrow::ZeroCopyAccessor;pub use cache::CacheManager;pub use cache::CacheStats;pub use cache::CacheStatsSnapshot;pub use cache::CombinedCacheStats;pub use cache::QueryCache;pub use cache::QueryKey;pub use cache::RemoteFactCache;pub use computation_graph::BatchScheduler;pub use computation_graph::ComputationGraph;pub use computation_graph::DistributedExecutor;pub use computation_graph::ExecutionBatch;pub use computation_graph::GraphError;pub use computation_graph::GraphNode;pub use computation_graph::GraphOptimizer;pub use computation_graph::GraphPartition;pub use computation_graph::LazyCache;pub use computation_graph::NodeAssignment;pub use computation_graph::ParallelExecutor;pub use computation_graph::StreamChunk;pub use computation_graph::StreamingExecutor;pub use computation_graph::TensorOp;pub use datalog::parse_fact;pub use datalog::parse_query;pub use datalog::parse_rule;pub use datalog::DatalogParser;pub use datalog::ParseError;pub use datalog::Statement;pub use device::AdaptiveBatchSizer;pub use device::CpuInfo;pub use device::DeviceArch;pub use device::DeviceCapabilities;pub use device::DeviceError;pub use device::DevicePerformanceTier;pub use device::DeviceProfiler;pub use device::DeviceType;pub use device::MemoryInfo;pub use ffi_profiler::global_profiler;pub use ffi_profiler::FfiCallGuard;pub use ffi_profiler::FfiCallStats;pub use ffi_profiler::FfiProfiler;pub use ffi_profiler::OverheadSummary;pub use ffi_profiler::ProfilingReport;pub use gpu::GpuBackend;pub use gpu::GpuBuffer;pub use gpu::GpuDevice;pub use gpu::GpuError;pub use gpu::GpuExecutor;pub use gpu::GpuKernel;pub use gpu::GpuMemoryManager;pub use gradient::ClientInfo;pub use gradient::ClientState;pub use gradient::ConvergenceDetector;pub use gradient::DPMechanism;pub use gradient::DifferentialPrivacy;pub use gradient::FederatedRound;pub use gradient::GradientAggregator;pub use gradient::GradientCompressor;pub use gradient::GradientDelta;pub use gradient::GradientError;pub use gradient::GradientVerifier;pub use gradient::LayerGradient;pub use gradient::ModelSyncProtocol;pub use gradient::PrivacyBudget;pub use gradient::QuantizedGradient;pub use gradient::SecureAggregation;pub use gradient::SparseGradient;pub use ir::Constant;pub use ir::KnowledgeBase;pub use ir::KnowledgeBaseStats;pub use ir::Predicate;pub use ir::Rule;pub use ir::Term;pub use ir::TermRef;pub use memory_profiler::MemoryProfiler;pub use memory_profiler::MemoryProfilingReport;pub use memory_profiler::MemoryStats;pub use memory_profiler::MemoryTrackingGuard;pub use optimizer::OptimizationRecommendation;pub use optimizer::PlanNode;pub use optimizer::PredicateStats;pub use optimizer::QueryOptimizer;pub use optimizer::QueryPlan;pub use reasoning::CycleDetector;pub use reasoning::DistributedReasoner;pub use reasoning::GoalDecomposition;pub use reasoning::InferenceEngine;pub use reasoning::MemoizedInferenceEngine;pub use reasoning::Proof;pub use reasoning::ProofRule;pub use reasoning::Substitution;pub use recursive_reasoning::FixpointEngine;pub use recursive_reasoning::StratificationAnalyzer;pub use recursive_reasoning::StratificationResult;pub use recursive_reasoning::TableStats;pub use recursive_reasoning::TabledInferenceEngine;pub use remote_reasoning::DistributedGoalResolver;pub use remote_reasoning::DistributedProofAssembler;pub use remote_reasoning::FactDiscoveryRequest;pub use remote_reasoning::FactDiscoveryResponse;pub use remote_reasoning::GoalResolutionRequest;pub use remote_reasoning::GoalResolutionResponse;pub use remote_reasoning::IncrementalLoadRequest;pub use remote_reasoning::IncrementalLoadResponse;pub use remote_reasoning::MockRemoteKnowledgeProvider;pub use remote_reasoning::QueryRequest;pub use remote_reasoning::QueryResponse;pub use remote_reasoning::RemoteKnowledgeProvider;pub use remote_reasoning::RemoteReasoningError;pub use proof_storage::ProofAssembler;pub use proof_storage::ProofFragment;pub use proof_storage::ProofFragmentRef;pub use proof_storage::ProofFragmentStore;pub use proof_storage::ProofMetadata;pub use proof_storage::RuleRef;pub use proof_explanation::ExplanationConfig;pub use proof_explanation::ExplanationStyle;pub use proof_explanation::FragmentProofExplainer;pub use proof_explanation::ProofExplainer;pub use proof_explanation::ProofExplanationBuilder;pub use provenance::Attribution;pub use provenance::DatasetProvenance;pub use provenance::Hyperparameters;pub use provenance::License;pub use provenance::LineageTrace;pub use provenance::ProvenanceError;pub use provenance::ProvenanceGraph;pub use provenance::TrainingProvenance;pub use pytorch_checkpoint::CheckpointMetadata;pub use pytorch_checkpoint::OptimizerState;pub use pytorch_checkpoint::ParamState;pub use pytorch_checkpoint::PyTorchCheckpoint;pub use pytorch_checkpoint::StateDict;pub use pytorch_checkpoint::TensorData;pub use quantization::CalibrationMethod;pub use quantization::DynamicQuantizer;pub use quantization::QuantizationConfig;pub use quantization::QuantizationError;pub use quantization::QuantizationGranularity;pub use quantization::QuantizationParams;pub use quantization::QuantizationScheme;pub use quantization::QuantizedTensor;pub use safetensors_support::ChunkedModelStorage;pub use safetensors_support::ModelSummary;pub use safetensors_support::SafetensorError;pub use safetensors_support::SafetensorsReader;pub use safetensors_support::SafetensorsWriter;pub use safetensors_support::TensorInfo;pub use storage::TensorLogicStore;pub use utils::KnowledgeBaseUtils;pub use utils::PredicateBuilder;pub use utils::QueryUtils;pub use utils::RuleBuilder;pub use utils::TermUtils;pub use version_control::Branch;pub use version_control::LayerDiff;pub use version_control::ModelCommit;pub use version_control::ModelDiff;pub use version_control::ModelDiffer;pub use version_control::ModelRepository;pub use version_control::VersionControlError;pub use visualization::GraphVisualizer;pub use visualization::ProofVisualizer;
Modules§
- allocation_
optimizer - Allocation Optimization Utilities
- arrow
- Apache Arrow integration for zero-copy tensor transport
- cache
- Caching support for query results and remote facts
- computation_
graph - Computation graph storage and execution
- datalog
- Datalog syntax parser for TensorLogic
- device
- Heterogeneous Device Support
- ffi_
profiler - FFI Overhead Profiling
- gpu
- GPU Execution Backend (Stub for Future Integration)
- gradient
- Gradient storage and management for federated learning
- ir
- TensorLogic IR types
- memory_
profiler - Memory profiling utilities for tracking allocations and memory usage.
- optimizer
- Query optimization for TensorLogic
- proof_
explanation - Automatic Proof Explanation
- proof_
storage - Proof fragment storage as IPLD
- provenance
- Provenance tracking for ML models
- pytorch_
checkpoint - PyTorch model checkpoint support for ipfrs-tensorlogic.
- quantization
- Model Quantization Support
- reasoning
- Distributed reasoning and inference engine
- recursive_
reasoning - Recursive Query Support with Tabling
- remote_
reasoning - Remote Knowledge Retrieval and Distributed Reasoning
- safetensors_
support - Safetensors file format support
- shared_
memory - Shared memory support for zero-copy IPC
- storage
- Storage for TensorLogic IR
- utils
- Utility functions for common TensorLogic operations
- version_
control - Model version control system for ML models
- visualization
- Visualization utilities for computation graphs and proofs.
Macros§
- profile_
ffi - Profile an FFI function call