scirs2_core/
lib.rs

1#![recursion_limit = "512"]
2// TODO: Address deprecated code usage and remove this allow
3#![allow(deprecated)]
4// TODO: Remove dead code or justify why it's kept
5#![allow(dead_code)]
6
7//! # ``SciRS2`` Core (Beta 1)
8//!
9//! Core utilities and common functionality for the ``SciRS2`` library.
10//!
11//! This crate provides shared utilities, error types, and common traits
12//! used across the ``SciRS2`` ecosystem of crates.
13//!
14//! ## Beta 1 Features
15//!
16//! - **Stable APIs**: Core functionality with API stability guarantees for production use
17//! - **Advanced Error Diagnostics**: ML-inspired error pattern recognition and domain-specific recovery strategies
18//! - **Performance Optimizations**: Enhanced SIMD operations, adaptive chunking, and intelligent load balancing
19//! - **GPU Acceleration**: CUDA, Metal MPS, and other backend support for accelerated computing
20//! - **Memory Management**: Efficient memory-mapped arrays and adaptive chunking for large datasets
21//!
22//! ## Overview
23//!
24//! * Common error types and traits
25//! * High-performance numerical operations
26//!   * SIMD-accelerated computations
27//!   * Parallel processing for multi-core systems
28//!   * Memory-efficient algorithms
29//!   * GPU acceleration abstractions
30//! * Caching and memoization for optimized performance
31//! * Type definitions and conversions
32//! * Physical and mathematical constants
33//! * Configuration system
34//! * Input/output utilities
35//! * Validation utilities
36//! * Numeric traits and conversions
37//! * Memory management utilities
38//! * Logging and diagnostics
39//! * Profiling tools
40//! * Random number generation
41//!
42//! ## Performance Optimizations
43//!
44//! The library provides several performance optimization features:
45//!
46//! * **SIMD Operations**: Uses CPU vector instructions for faster array operations
47//! * **Parallel Processing**: Leverages multi-core systems for improved performance
48//! * **GPU Acceleration**: Provides abstractions for GPU computation (CUDA, WebGPU, Metal)
49//! * **Memory-Efficient Algorithms**: Optimizes memory usage for large-scale computations
50//! * **Caching and Memoization**: Avoids redundant computations
51//! * **Profiling and Instrumentation**: Identifies performance bottlenecks
52//! * **Memory Management**: Efficient memory utilization and pooling
53//!
54//! ## Additional Utilities
55//!
56//! * **Logging**: Structured logging for scientific applications
57//! * **Random Number Generation**: Consistent interface for random sampling
58//! * **Type Conversions**: Safe numeric and complex number conversions
59//!
60//! ## Feature Flags
61//!
62//! These features can be controlled via feature flags:
63//!
64//! * `simd`: Enable SIMD acceleration
65//! * `parallel`: Enable parallel processing
66//! * `cache`: Enable caching and memoization functionality
67//! * `validation`: Enable validation utilities
68//! * `logging`: Enable structured logging and diagnostics
69//! * `gpu`: Enable GPU acceleration abstractions
70//! * `memory_management`: Enable advanced memory management
71//! * `memory_efficient`: Enable memory-efficient array operations and views
72//! * `array`: Enable scientific array types (``MaskedArray``, ``RecordArray``)
73//! * `profiling`: Enable performance profiling tools
74//! * `random`: Enable random number generation utilities
75//! * `types`: Enable type conversion utilities
76//! * `linalg`: Enable linear algebra with BLAS/LAPACK bindings
77//! * `cloud`: Enable cloud storage integration (S3, GCS, Azure)
78//! * `jit`: Enable just-in-time compilation with LLVM
79//! * `ml_pipeline`: Enable ML pipeline integration and real-time processing
80//! * `all`: Enable all features except backend-specific ones
81
82// Re-export modules
83pub mod api_freeze;
84pub mod apiversioning;
85#[cfg(feature = "array")]
86pub mod array;
87pub mod array_protocol;
88#[cfg(feature = "types")]
89pub mod batch_conversions;
90#[cfg(feature = "cache")]
91pub mod cache;
92pub mod chunking;
93#[cfg(feature = "cloud")]
94pub mod cloud;
95pub mod config;
96pub mod constants;
97pub mod distributed;
98pub mod ecosystem;
99pub mod error;
100#[cfg(feature = "gpu")]
101pub mod gpu;
102#[cfg(feature = "gpu")]
103pub mod gpu_registry;
104pub mod io;
105#[cfg(feature = "jit")]
106pub mod jit;
107#[cfg(feature = "logging")]
108pub mod logging;
109#[cfg(feature = "memory_management")]
110pub mod memory;
111#[cfg(feature = "memory_efficient")]
112pub mod memory_efficient;
113pub mod metrics;
114#[cfg(feature = "ml_pipeline")]
115pub mod ml_pipeline;
116pub mod ndarray;
117pub mod ndarray_ext;
118pub mod numeric;
119#[cfg(feature = "parallel")]
120pub mod parallel;
121#[cfg(feature = "parallel")]
122pub mod parallel_ops;
123pub mod performance;
124pub mod performance_optimization;
125#[cfg(feature = "profiling")]
126pub mod profiling;
127#[cfg(feature = "random")]
128pub mod random;
129pub mod resource;
130#[cfg(feature = "simd")]
131pub mod simd;
132pub mod simd_aligned;
133pub mod simd_ops;
134#[cfg(feature = "testing")]
135pub mod testing;
136// Universal Functions (ufuncs) module
137pub mod error_templates;
138pub mod safe_ops;
139#[cfg(feature = "types")]
140pub mod types;
141#[cfg(feature = "ufuncs")]
142pub mod ufuncs;
143pub mod units;
144pub mod utils;
145pub mod validation;
146
147// Production-level features for enterprise deployments
148pub mod observability;
149pub mod stability;
150pub mod versioning;
151
152// Advanced optimization and AI features
153pub mod neural_architecture_search;
154pub mod quantum_optimization;
155
156// Advanced Mode Ecosystem Integration
157pub mod advanced_ecosystem_integration;
158
159// Advanced JIT Compilation Framework
160pub mod advanced_jit_compilation;
161
162// Advanced Distributed Computing Framework
163pub mod advanced_distributed_computing;
164
165// Advanced Cloud Storage Framework
166// pub mod distributed_storage; // Module not implemented yet
167
168// Advanced Tensor Cores and Automatic Kernel Tuning Framework
169pub mod advanced_tensor_cores;
170
171// Tensor cores optimization modules
172#[cfg(feature = "gpu")]
173pub mod tensor_cores;
174
175// Benchmarking module
176#[cfg(feature = "benchmarking")]
177pub mod benchmarking;
178
179// Re-exports
180#[cfg(feature = "cache")]
181pub use crate::cache::*;
182#[cfg(feature = "cloud")]
183pub use crate::cloud::{
184    CloudConfig, CloudCredentials, CloudError, CloudObjectMetadata, CloudProvider,
185    CloudStorageClient, EncryptionConfig, EncryptionMethod, HttpMethod, ListResult,
186    TransferOptions,
187};
188pub use crate::config::production as config_production;
189pub use crate::config::{
190    get_config, get_config_value, set_config_value, set_global_config, Config, ConfigValue,
191};
192pub use crate::constants::{math, physical, prefixes};
193#[allow(ambiguous_glob_reexports)]
194pub use crate::error::*;
195
196// Re-export the array! macro for convenient array creation
197// This addresses the common pain point where users expect array! to be available
198// directly from scirs2_core instead of requiring import from scirs2_autograd
199//
200// # Example
201//
202// ```rust
203// use scirs2_core::array;
204//
205// let matrix = array![[1, 2, 3], [4, 5, 6]];
206// assert_eq!(matrix.shape(), &[2, 3]);
207// ```
208#[cfg(feature = "gpu")]
209pub use crate::gpu::*;
210pub use crate::io::*;
211#[cfg(feature = "jit")]
212pub use crate::jit::DataType as JitDataType;
213#[cfg(feature = "jit")]
214pub use crate::jit::{
215    CompiledKernel, ExecutionProfile, JitBackend, JitCompiler, JitConfig, JitError, KernelLanguage,
216    KernelSource, OptimizationLevel, TargetArchitecture,
217};
218#[cfg(feature = "logging")]
219pub use crate::logging::*;
220#[cfg(feature = "memory_management")]
221pub use crate::memory::{
222    format_memory_report, generate_memory_report, global_buffer_pool, track_allocation,
223    track_deallocation, track_resize, BufferPool, ChunkProcessor, ChunkProcessor2D,
224    GlobalBufferPool, ZeroCopyView,
225};
226// Legacy re-export from ndarray_ext (kept for backward compatibility)
227pub use crate::ndarray_ext::array as array_legacy;
228
229// Complete ndarray functionality through the unified module
230pub use crate::ndarray::{
231    arr1,
232    arr2,
233    // Essential macros - now available at crate root
234    array,
235    s,
236    // Common types for convenience
237    Array,
238    Array1,
239    Array2,
240    ArrayD,
241    ArrayView,
242    ArrayView1,
243    ArrayView2,
244    ArrayViewMut,
245    Axis,
246    Ix1,
247    Ix2,
248    IxDyn,
249};
250
251#[cfg(feature = "leak_detection")]
252pub use crate::memory::{
253    LeakCheckGuard, LeakDetectionConfig, LeakDetector, LeakReport, LeakType, MemoryCheckpoint,
254    MemoryLeak, ProfilerTool,
255};
256
257#[cfg(feature = "memory_efficient")]
258pub use crate::memory_efficient::{
259    chunk_wise_binary_op, chunk_wise_op, chunk_wise_reduce, create_disk_array, create_mmap,
260    create_temp_mmap, diagonal_view, evaluate, load_chunks, open_mmap, register_fusion,
261    transpose_view, view_as, view_mut_as, AccessMode, AdaptiveChunking, AdaptiveChunkingBuilder,
262    AdaptiveChunkingParams, AdaptiveChunkingResult, ArithmeticOps, BroadcastOps, ChunkIter,
263    ChunkedArray, ChunkingStrategy, DiskBackedArray, FusedOp, LazyArray, LazyOp, LazyOpKind,
264    MemoryMappedArray, MemoryMappedChunkIter, MemoryMappedChunks, MemoryMappedSlice,
265    MemoryMappedSlicing, OpFusion, OutOfCoreArray, ViewMut, ZeroCopyOps,
266};
267
268// Compression-related types are only available with the memory_compression feature
269#[cfg(feature = "memory_compression")]
270pub use crate::memory_efficient::{
271    CompressedMemMapBuilder, CompressedMemMappedArray, CompressionAlgorithm,
272};
273
274// Re-export the parallel memory-mapped array capabilities
275#[cfg(all(feature = "memory_efficient", feature = "parallel"))]
276pub use crate::memory_efficient::MemoryMappedChunksParallel;
277
278#[cfg(feature = "array")]
279pub use crate::array::{
280    is_masked, mask_array, masked_equal, masked_greater, masked_inside, masked_invalid,
281    masked_less, masked_outside, masked_where, record_array_from_typed_arrays,
282    record_array_fromrecords, ArrayError, FieldValue, MaskedArray, Record, RecordArray, NOMASK,
283};
284
285#[cfg(feature = "memory_metrics")]
286pub use crate::memory::metrics::{
287    clear_snapshots,
288    compare_snapshots,
289    // Utility functions
290    format_bytes,
291    format_duration,
292    take_snapshot,
293    MemoryEvent,
294    MemoryEventType,
295    // Core metrics types
296    MemoryMetricsCollector,
297    MemoryMetricsConfig,
298    // Memory snapshots and leak detection
299    MemorySnapshot,
300    SnapshotDiff,
301    // Tracked memory components
302    TrackedBufferPool,
303    TrackedChunkProcessor,
304    TrackedChunkProcessor2D,
305};
306
307#[cfg(feature = "types")]
308pub use crate::batch_conversions::{
309    utils as batch_utils, BatchConversionConfig, BatchConversionResult, BatchConverter,
310    ElementConversionError,
311};
312#[cfg(all(feature = "memory_metrics", feature = "gpu"))]
313pub use crate::memory::metrics::{setup_gpu_memory_tracking, TrackedGpuBuffer, TrackedGpuContext};
314pub use crate::metrics::{
315    global_healthmonitor, global_metrics_registry, Counter, Gauge, HealthCheck, HealthMonitor,
316    HealthStatus, Histogram, MetricPoint, MetricType, MetricValue, Timer,
317};
318#[cfg(feature = "ml_pipeline")]
319pub use crate::ml_pipeline::DataType as MLDataType;
320#[cfg(feature = "ml_pipeline")]
321pub use crate::ml_pipeline::{
322    DataBatch, DataSample, FeatureConstraint, FeatureSchema, FeatureTransformer, FeatureValue,
323    MLPipeline, MLPipelineError, ModelPredictor, ModelType, PipelineConfig, PipelineMetrics,
324    PipelineNode, TransformType,
325};
326pub use crate::numeric::*;
327#[cfg(feature = "parallel")]
328pub use crate::parallel::*;
329#[cfg(feature = "parallel")]
330pub use crate::parallel_ops::{
331    is_parallel_enabled, num_threads, par_chunks, par_chunks_mut, par_join, par_scope,
332};
333// Re-export all parallel traits and types
334#[cfg(feature = "parallel")]
335pub use crate::parallel_ops::*;
336#[cfg(feature = "profiling")]
337pub use crate::profiling::{profiling_memory_tracker, Profiler};
338#[cfg(feature = "random")]
339#[allow(ambiguous_glob_reexports)]
340pub use crate::random::*;
341pub use crate::resource::{
342    get_available_memory, get_performance_tier, get_recommended_chunk_size,
343    get_recommended_thread_count, get_system_resources, get_total_memory, is_gpu_available,
344    is_simd_supported, DiscoveryConfig, PerformanceTier, ResourceDiscovery, SystemResources,
345};
346#[cfg(feature = "simd")]
347pub use crate::simd::*;
348#[cfg(feature = "testing")]
349pub use crate::testing::{TestConfig, TestResult, TestRunner, TestSuite};
350#[cfg(feature = "types")]
351pub use crate::types::{convert, ComplexConversionError, ComplexExt, ComplexOps};
352
353// Re-export complex number types for SCIRS2 POLICY compliance
354pub use num_complex::{Complex, Complex32, Complex64};
355
356// Re-export RNG types for SCIRS2 POLICY compliance
357pub use crate::units::{
358    convert, global_unit_registry, unit_value, Dimension, UnitDefinition, UnitRegistry, UnitSystem,
359    UnitValue,
360};
361pub use crate::utils::*;
362pub use crate::validation::production as validation_production;
363pub use crate::validation::{
364    check_finite, check_in_bounds, check_positive, checkarray_finite, checkshape,
365};
366pub use rand_chacha::{ChaCha12Rng, ChaCha20Rng, ChaCha8Rng};
367
368#[cfg(feature = "data_validation")]
369pub use crate::validation::data::DataType as ValidationDataType;
370#[cfg(feature = "data_validation")]
371pub use crate::validation::data::{
372    Constraint, FieldDefinition, ValidationConfig, ValidationError, ValidationResult,
373    ValidationRule, ValidationSchema, Validator,
374};
375
376// Production-level feature re-exports
377pub use crate::observability::{audit, tracing};
378pub use crate::stability::{
379    global_stability_manager, ApiContract, BreakingChange, BreakingChangeType, ConcurrencyContract,
380    MemoryContract, NumericalContract, PerformanceContract, StabilityGuaranteeManager,
381    StabilityLevel, UsageContext,
382};
383pub use crate::versioning::{
384    compatibility, deprecation, migration, negotiation, semantic, ApiVersion, CompatibilityLevel,
385    SupportStatus, Version, VersionManager,
386};
387
388// Advanced optimization and AI feature re-exports
389pub use crate::neural_architecture_search::{
390    ActivationType, Architecture, ArchitecturePerformance, ConnectionType, HardwareConstraints,
391    LayerType, NASStrategy, NeuralArchitectureSearch, OptimizationObjectives, OptimizerType,
392    SearchResults, SearchSpace,
393};
394pub use crate::quantum_optimization::{
395    OptimizationResult, QuantumOptimizer, QuantumParameters, QuantumState, QuantumStrategy,
396};
397
398// Advanced JIT Compilation re-exports
399// pub use crate::advanced_jit_compilation::{
400//     AdaptiveCodeGenerator, CompilationStatistics, JitAnalytics, JitCompilerConfig, JitProfiler,
401//     KernelCache, KernelMetadata, KernelPerformance, LlvmCompilationEngine, OptimizationResults,
402//     PerformanceImprovement, RuntimeOptimizer, advancedJitCompiler,
403// }; // Missing module
404
405// Advanced Cloud Storage re-exports
406// pub use crate::distributed_storage::{
407//     AdaptiveStreamingEngine, CloudPerformanceAnalytics, CloudProviderConfig, CloudProviderId,
408//     CloudProviderType, CloudSecurityManager, CloudStorageMonitoring, CloudStorageProvider,
409//     DataOptimizationEngine, DownloadRequest, DownloadResponse, IntelligentCacheSystem,
410//     ParallelTransferManager, StreamRequest, advancedCloudConfig,
411//     advancedCloudStorageCoordinator, UploadRequest, UploadResponse,
412// };
413
414// Benchmarking re-exports
415#[cfg(feature = "benchmarking")]
416pub use crate::benchmarking::{
417    BenchmarkConfig, BenchmarkMeasurement, BenchmarkResult, BenchmarkRunner, BenchmarkStatistics,
418    BenchmarkSuite,
419};
420
421/// ``SciRS2`` core version information
422pub const fn _version() -> &'static str {
423    env!("CARGO_PKG_VERSION")
424}
425
426/// Initialize the library (called automatically)
427#[doc(hidden)]
428#[allow(dead_code)]
429pub fn __init() {
430    use std::sync::Once;
431    static INIT: Once = Once::new();
432
433    INIT.call_once(|| {
434        // Initialize API freeze registry
435        crate::api_freeze::initialize_api_freeze();
436    });
437}
438
439// Ensure initialization happens
440#[doc(hidden)]
441#[used]
442#[cfg_attr(target_os = "linux", link_section = ".init_array")]
443#[cfg_attr(target_os = "macos", link_section = "__DATA,__mod_init_func")]
444#[cfg_attr(target_os = "windows", link_section = ".CRT$XCU")]
445static INIT: extern "C" fn() = {
446    extern "C" fn __init_wrapper() {
447        __init();
448    }
449    __init_wrapper
450};
scirs2_core/lib.rs

scirs2_core/
lib.rs
