Crate scirs2_core 

SciRS2 Core - Foundation for Scientific Computing in Rust

scirs2-core is the foundational crate for the SciRS2 scientific computing ecosystem, providing essential utilities, abstractions, and optimizations used by all SciRS2 modules.

🎯 Design Philosophy

• Zero-Cost Abstractions: Performance without compromising safety
• Layered Architecture: Clear separation between interface and implementation
• Policy Compliance: Enforce SciRS2 POLICY - only scirs2-core uses external dependencies directly
• Production Ready: Enterprise-grade error handling, diagnostics, and stability guarantees

🚀 Key Features

Performance Acceleration

• SIMD Operations: CPU vector instructions (SSE, AVX, NEON) for array operations
• Parallel Processing: Multi-threaded execution with intelligent load balancing
• GPU Acceleration: Unified interface for CUDA, Metal, OpenCL, and WebGPU
• Memory Efficiency: Zero-copy views, memory-mapped arrays, adaptive chunking

Core Utilities

• Error Handling: ML-inspired diagnostics with recovery strategies
• Validation: Input checking with informative error messages
• Caching: Memoization and result caching for expensive computations
• Profiling: Performance monitoring and bottleneck detection

Scientific Infrastructure

• Constants: Physical and mathematical constants (via constants module)
• Random Number Generation: Consistent RNG interface across the ecosystem
• Complex Numbers: Type-safe complex arithmetic
• Array Protocol: Unified array interface for interoperability

📦 Module Overview

Performance & Optimization

Module	Description
simd_ops	SIMD-accelerated operations with platform detection
parallel_ops	Parallel processing primitives
gpu	GPU acceleration abstractions
memory	Memory management (buffer pools, zero-copy views)
memory_efficient	Memory-mapped arrays and lazy evaluation

Error Handling & Diagnostics

Module	Description
error	Error types and traits
validation	Input validation utilities
logging	Structured logging for diagnostics
profiling	Performance profiling tools

Scientific Computing Basics

Module	Description
ndarray	Unified ndarray interface (re-exports with SciRS2 extensions)
numeric	Generic numerical operations
random	Random number generation
constants	Mathematical and physical constants

Infrastructure

Module	Description
config	Configuration management
cache	Result caching and memoization
io	I/O utilities
cloud	Cloud storage integration (S3, GCS, Azure)

🚀 Quick Start

Installation

[dependencies]
scirs2-core = { version = "0.1.0-rc.3", features = ["simd", "parallel"] }

SIMD Operations

use scirs2_core::simd_ops::SimdUnifiedOps;
use ::ndarray::array;

// Automatic SIMD acceleration based on CPU capabilities
let a = array![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
let b = array![8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0];

// SIMD-accelerated element-wise addition
let result = f64::simd_add(&a.view(), &b.view());

Parallel Processing

use scirs2_core::parallel_ops::*;

// Parallel iteration over chunks
let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
par_chunks(&data, 3).for_each(|chunk| {
    // Process each chunk in parallel
    let sum: i32 = chunk.iter().sum();
    println!("Chunk sum: {}", sum);
});

Input Validation

use scirs2_core::validation::*;
use scirs2_core::error::CoreResult;
use ::ndarray::Array2;

fn process_matrix(data: &Array2<f64>, k: usize) -> CoreResult<()> {
    // Validate inputs
    check_positive(k, "k")?;
    checkarray_finite(data, "data")?;
    checkshape(data, &[2, 3], "data")?;

    // Process data...
    Ok(())
}

Constants

use scirs2_core::constants::{math, physical};

// Mathematical constants
let pi = math::PI;
let e = math::E;

// Physical constants
let c = physical::SPEED_OF_LIGHT;
let h = physical::PLANCK;

Random Number Generation

use scirs2_core::random::*;
use rand::Rng;

// Standard distributions
let mut rng = rand::rng();
let normal = Normal::new(0.0, 1.0)?;
let samples: Vec<f64> = (0..1000).map(|_| normal.sample(&mut rng)).collect();

let uniform = Uniform::new(0.0, 1.0)?;
let samples: Vec<f64> = (0..1000).map(|_| uniform.sample(&mut rng)).collect();

Memory-Efficient Operations

use scirs2_core::memory_efficient::*;
use std::path::Path;
use ::ndarray::Array2;

// Memory-mapped array for large datasets
let data = Array2::<f64>::zeros((1000, 1000));
let path = Path::new("/path/to/large_file.dat");
let mmap = create_mmap(&data, path, AccessMode::ReadWrite, 0)?;

// Chunked operations for out-of-core processing
let result = chunk_wise_op(&data, |chunk| {
    chunk.mapv(|x| x * 2.0)
}, ChunkingStrategy::Fixed(10000))?;

🏗️ Architecture

┌─────────────────────────────────────────┐
│     SciRS2 Ecosystem Modules            │
│  (linalg, stats, neural, vision, etc.)  │
└─────────────────────────────────────────┘
             ▼
┌─────────────────────────────────────────┐
│         scirs2-core (This Crate)        │
│  ┌────────────────────────────────────┐ │
│  │  High-Level Abstractions           │ │
│  │  - SIMD Operations                 │ │
│  │  - Parallel Processing             │ │
│  │  - GPU Acceleration                │ │
│  │  - Error Handling                  │ │
│  └────────────────────────────────────┘ │
│  ┌────────────────────────────────────┐ │
│  │  Core Utilities                    │ │
│  │  - Array Protocol                  │ │
│  │  - Validation                      │ │
│  │  - Memory Management               │ │
│  │  - Configuration                   │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘
             ▼
┌─────────────────────────────────────────┐
│     External Dependencies               │
│  (ndarray, rayon, BLAS, etc.)           │
│  ⚠️  Only scirs2-core depends directly  │
└─────────────────────────────────────────┘

🎨 Feature Flags

Performance Features

• simd - SIMD acceleration (SSE, AVX, NEON)
• parallel - Multi-threaded execution via Rayon
• gpu - GPU acceleration (CUDA, Metal, OpenCL)

Memory Management

• memory_management - Advanced memory management (buffer pools, tracking)
• memory_efficient - Memory-mapped arrays and lazy evaluation
• memory_metrics - Memory usage tracking and profiling

Scientific Computing

• array - Scientific array types (MaskedArray, RecordArray)
• random - Random number generation
• linalg - Linear algebra with BLAS/LAPACK

Development & Debugging

• validation - Input validation (recommended for development)
• logging - Structured logging
• profiling - Performance profiling
• testing - Testing utilities

Advanced Features

• cloud - Cloud storage (S3, GCS, Azure)
• jit - Just-in-time compilation with LLVM
• ml_pipeline - ML pipeline integration

Convenience

• default - Commonly used features (parallel, validation)
• all - All features except backend-specific ones

🔒 SciRS2 Policy Compliance

Important: scirs2-core is the only crate in the SciRS2 ecosystem that directly depends on external crates like ndarray, rand, rayon, etc.

All other SciRS2 crates must use abstractions provided by scirs2-core:

// ✅ CORRECT: Use scirs2-core abstractions
use scirs2_core::crate::ndarray::Array2;
use scirs2_core::random::Normal;
use scirs2_core::parallel_ops::*;

// ❌ WRONG: Don't import external deps directly in other crates
// use ::ndarray::Array2;       // NO!
// use rand_distr::Normal;    // NO!
// use rayon::prelude::*;     // NO!

This policy ensures:

• Consistent APIs across the ecosystem
• Centralized version management
• Easy addition of SciRS2-specific extensions
• Better compile times through reduced duplication

📊 Performance

scirs2-core provides multiple optimization levels:

Feature	Speedup	Use Case
SIMD	2-8x	Array operations, numerical computations
Parallel	2-16x	Large datasets, independent operations
GPU	10-100x	Massive parallelism, deep learning
Memory-mapped	∞	Out-of-core processing, datasets larger than RAM

Platform Detection

Automatic CPU feature detection for optimal SIMD usage:

use scirs2_core::simd_ops::PlatformCapabilities;

let caps = PlatformCapabilities::detect();
println!("SIMD available: {}", caps.simd_available);
println!("AVX2 available: {}", caps.avx2_available);
println!("GPU available: {}", caps.gpu_available);

🔗 Integration

scirs2-core integrates seamlessly with the Rust ecosystem:

• ndarray: Core array operations
• num-traits: Generic numeric operations
• rayon: Parallel processing
• BLAS/LAPACK: Optimized linear algebra

🔒 Version

Current version: 0.1.0-rc.3 (Released December 17, 2025)

📚 Examples

See the examples directory for more detailed usage examples.

Re-exports

pub use crate::config::production as config_production;

pub use crate::config::get_config;

pub use crate::config::get_config_value;

pub use crate::config::set_config_value;

pub use crate::config::set_global_config;

pub use crate::config::Config;

pub use crate::config::ConfigValue;

pub use crate::constants::math;

pub use crate::constants::physical;

pub use crate::constants::prefixes;

pub use crate::array::is_masked;

pub use crate::array::mask_array;

pub use crate::array::masked_equal;

pub use crate::array::masked_greater;

pub use crate::array::masked_inside;

pub use crate::array::masked_invalid;

pub use crate::array::masked_less;

pub use crate::array::masked_outside;

pub use crate::array::masked_where;

pub use crate::array::record_array_from_typed_arrays;

pub use crate::array::record_array_fromrecords;

pub use crate::array::ArrayError;

pub use crate::array::FieldValue;

pub use crate::array::MaskedArray;

pub use crate::array::Record;

pub use crate::array::RecordArray;

pub use crate::array::NOMASK;

pub use crate::metrics::global_healthmonitor;

pub use crate::metrics::global_metrics_registry;

pub use crate::metrics::Counter;

pub use crate::metrics::Gauge;

pub use crate::metrics::HealthCheck;

pub use crate::metrics::HealthMonitor;

pub use crate::metrics::HealthStatus;

pub use crate::metrics::Histogram;

pub use crate::metrics::MetricPoint;

pub use crate::metrics::MetricType;

pub use crate::metrics::MetricValue;

pub use crate::metrics::Timer;

pub use crate::resource::get_available_memory;

pub use crate::resource::get_performance_tier;

pub use crate::resource::get_recommended_chunk_size;

pub use crate::resource::get_recommended_thread_count;

pub use crate::resource::get_system_resources;

pub use crate::resource::get_total_memory;

pub use crate::resource::is_gpu_available;

pub use crate::resource::is_simd_supported;

pub use crate::resource::DiscoveryConfig;

pub use crate::resource::PerformanceTier;

pub use crate::resource::ResourceDiscovery;

pub use crate::resource::SystemResources;

pub use crate::units::convert;

pub use crate::units::global_unit_registry;

pub use crate::units::unit_value;

pub use crate::units::Dimension;

pub use crate::units::UnitDefinition;

pub use crate::units::UnitRegistry;

pub use crate::units::UnitSystem;

pub use crate::units::UnitValue;

pub use crate::validation::production as validation_production;

pub use crate::validation::check_finite;

pub use crate::validation::check_in_bounds;

pub use crate::validation::check_positive;

pub use crate::validation::checkarray_finite;

pub use crate::validation::checkshape;

pub use crate::observability::audit;

pub use crate::observability::tracing;

pub use crate::stability::global_stability_manager;

pub use crate::stability::ApiContract;

pub use crate::stability::BreakingChange;

pub use crate::stability::BreakingChangeType;

pub use crate::stability::ConcurrencyContract;

pub use crate::stability::MemoryContract;

pub use crate::stability::NumericalContract;

pub use crate::stability::PerformanceContract;

pub use crate::stability::StabilityGuaranteeManager;

pub use crate::stability::StabilityLevel;

pub use crate::stability::UsageContext;

pub use crate::versioning::compatibility;

pub use crate::versioning::deprecation;

pub use crate::versioning::migration;

pub use crate::versioning::negotiation;

pub use crate::versioning::semantic;

pub use crate::versioning::ApiVersion;

pub use crate::versioning::CompatibilityLevel;

pub use crate::versioning::SupportStatus;

pub use crate::versioning::Version;

pub use crate::versioning::VersionManager;

pub use crate::neural_architecture_search::ActivationType;

pub use crate::neural_architecture_search::Architecture;

pub use crate::neural_architecture_search::ArchitecturePerformance;

pub use crate::neural_architecture_search::ConnectionType;

pub use crate::neural_architecture_search::HardwareConstraints;

pub use crate::neural_architecture_search::LayerType;

pub use crate::neural_architecture_search::NASStrategy;

pub use crate::neural_architecture_search::NeuralArchitectureSearch;

pub use crate::neural_architecture_search::OptimizationObjectives;

pub use crate::neural_architecture_search::OptimizerType;

pub use crate::neural_architecture_search::SearchResults;

pub use crate::neural_architecture_search::SearchSpace;

pub use crate::quantum_optimization::OptimizationResult;

pub use crate::quantum_optimization::QuantumOptimizer;

pub use crate::quantum_optimization::QuantumParameters;

pub use crate::quantum_optimization::QuantumState;

pub use crate::quantum_optimization::QuantumStrategy;

pub use crate::error::*;

pub use crate::io::*;

pub use crate::numeric::*;

pub use crate::utils::*;

Modules

advanced_distributed_computing

Advanced Distributed Computing Framework

advanced_ecosystem_integration

Advanced Mode Ecosystem Integration (Refactored)

advanced_jit_compilation

Advanced JIT Compilation Framework

advanced_tensor_cores

Advanced Tensor Cores and Automatic Kernel Tuning Framework

api_freeze

API freeze module for scirs2-core 1.0

apiversioning

API versioning system for backward compatibility

array

Array module that provides enhanced array types and utilities

array_protocol

Implementation of Array Protocol (similar to NumPy’s __array_function__ protocol)

chunking

Advanced chunking strategies for optimal parallel performance

config

Configuration system for SciRS2

constants

Physical and Mathematical Constants

distributed

Production-grade distributed computing infrastructure

ecosystem

Ecosystem management and validation for SciRS2

error

Advanced error handling and recovery system for SciRS2

error_templates

Standardized error message templates for consistent error reporting

io

I/O utilities for SciRS2

metrics

Production-Level Metrics Collection and Monitoring

ndarray

Complete ndarray re-export for SciRS2 ecosystem

ndarray_ext

Extended ndarray operations for scientific computing

neural_architecture_search

Self-Optimizing Neural Architecture Search (NAS) System

numeric

Numeric traits and utilities for SciRS2

observability

Observability Infrastructure

performance

Performance optimization and monitoring for SciRS2 Core

performance_optimization

Performance optimization utilities for critical paths

prelude

Convenient re-exports of commonly used items

quantum_optimization

Quantum-Inspired Optimization Algorithms for SciRS2

resource

Resource Discovery and Hardware Detection

safe_ops

Safe mathematical operations that handle edge cases and validate results

simd_aligned

Memory-aligned SIMD operations for optimal performance

simd_ops

Unified SIMD operations abstraction layer

stability

Long-term stability guarantees and API contracts for SciRS2

units

Unit Conversion System

utils

Utility functions for numerical operations

validation

Validation utilities for SciRS2

versioning

API Versioning Infrastructure

Macros

array

Create an Array with one, two, three, four, five, or six dimensions.

array_function_def

Convenience macro for defining array protocol functions.

array_function_dispatch

array_legacy

Create an Array with one, two, three, four, five, or six dimensions.

batch_operation

Macro for batch error handling

computationerror

Macro to create a computation error with location information

config_get

Configuration convenience macros Get a configuration value with type conversion

config_set

Set a configuration value

convert_units

Macro for convenient unit conversions

counter

Convenience macros for metrics Create and register a counter metric

deprecated_in

Macro to mark deprecated APIs

diagnosticerror

Macro to create a diagnostic error with automatic context

dimensionerror

Macro to create a dimension error with location information

domainerror

Macro to create a domain error with location information

enhanced_error

Macro to create an enhanced error with automatic severity detection

error_context

Macro to create a new error context with location information

feature_enabled

Check if a feature is enabled

gauge

Create and register a gauge metric

histogram

Create and register a histogram metric

require_api

Macro to check API availability at compile time

s

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly Slice argument constructor.

since_version

Macro to mark APIs with version information

timer

Create and register a timer metric

trace_fn

Convenience macro for creating traced functions

track_precision

Convenience macros for precision tracking

update_precision

valueerror

Macro to create a value error with location information

with_retry

Macro for error recovery with retry logic

Structs

Axis

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly An axis index.

ChaCha8Rng

A cryptographically secure random number generator that uses the ChaCha algorithm.

ChaCha12Rng

A cryptographically secure random number generator that uses the ChaCha algorithm.

ChaCha20Rng

A cryptographically secure random number generator that uses the ChaCha algorithm.

Complex

A complex number in Cartesian form.

Functions

Ix1

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly Create a one-dimensional index

Ix2

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly Create a two-dimensional index

IxDyn

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly Create a dynamic-dimensional index

_version

SciRS2 core version information

arr1

Create a one-dimensional array with elements from xs.

arr2

Create a two-dimensional array with elements from xs.

Type Aliases

Array

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly An array that owns its data uniquely.

Array1

one-dimensional array

Array2

two-dimensional array

ArrayD

dynamic-dimensional array

ArrayView

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly A read-only array view.

ArrayView1

one-dimensional array view

ArrayView2

two-dimensional array view

ArrayViewMut

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly A read-write array view.

Complex32

Alias for a Complex<f32>

Complex64

Alias for a Complex<f64>

Ix1

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly one-dimensional

Ix2

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly two-dimensional

IxDyn

Re-export essential ndarray types and macros for convenience Use ::ndarray to refer to the external crate directly dynamic-dimensional