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.1", 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::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.1 (Released October 03, 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

Re-export essential macros that were missing in some modules 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 macros that were missing in some modules 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

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

Create a one-dimensional index

Ix2

Create a two-dimensional index

IxDyn

Create a dynamic-dimensional index

_version

SciRS2 core version information

arr1

Re-export essential macros that were missing in some modules Create a one-dimensional array with elements from xs.

arr2

Re-export essential macros that were missing in some modules Create a two-dimensional array with elements from xs.

Type Aliases

Array

An array that owns its data uniquely.

Array1

one-dimensional array

Array2

two-dimensional array

ArrayD

dynamic-dimensional array

ArrayView

A read-only array view.

ArrayView1

one-dimensional array view

ArrayView2

two-dimensional array view

ArrayViewMut

A read-write array view.

Complex32

Alias for a Complex<f32>

Complex64

Alias for a Complex<f64>

Ix1

one-dimensional

Ix2

two-dimensional

IxDyn

dynamic-dimensional