# sklears-linear

[![Crates.io](https://img.shields.io/crates/v/sklears-linear.svg)](https://crates.io/crates/sklears-linear)
[![Documentation](https://docs.rs/sklears-linear/badge.svg)](https://docs.rs/sklears-linear)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
[![Minimum Rust Version](https://img.shields.io/badge/rustc-1.70+-blue.svg)](https://www.rust-lang.org)

High-performance linear models for Rust with pure Rust implementation and ongoing performance optimization, featuring advanced solvers, numerical stability, and GPU acceleration.

> **Latest release:** `0.1.2` (June 30, 2026). See the [workspace release notes](../../docs/releases/0.1.2.md) for highlights and upgrade guidance.

## Overview

`sklears-linear` provides comprehensive linear modeling capabilities:

- **Core Models**: LinearRegression, Ridge, Lasso, ElasticNet, LogisticRegression
- **Advanced Solvers**: ADMM, coordinate descent, proximal gradient, L-BFGS
- **Numerical Stability**: Condition checking, iterative refinement, rank-deficient handling
- **Performance**: SIMD optimization, sparse matrix support, parallel training
- **Production Ready**: Cross-validation, early stopping, warm start

## Quick Start

```rust
use sklears_linear::{LinearRegression, Ridge, Lasso, ElasticNet};
use ndarray::array;

// Basic linear regression
let model = LinearRegression::default();
let X = array![[1.0, 2.0], [2.0, 4.0], [3.0, 6.0]];
let y = array![2.0, 4.0, 6.0];
let fitted = model.fit(&X, &y)?;
let predictions = fitted.predict(&X)?;

// Ridge regression with regularization
let ridge = Ridge::builder()
    .alpha(1.0)
    .solver(RidgeSolver::Cholesky)
    .build();

// Lasso with coordinate descent
let lasso = Lasso::builder()
    .alpha(0.1)
    .max_iter(1000)
    .tol(1e-4)
    .build();

// ElasticNet combining L1 and L2
let elastic = ElasticNet::builder()
    .alpha(0.5)
    .l1_ratio(0.5)
    .build();
```

## Advanced Features

### Solvers

```rust
use sklears_linear::{ADMMSolver, CoordinateDescentSolver, ProximalGradientSolver};

// ADMM for distributed optimization
let admm = ADMMSolver::builder()
    .rho(1.0)
    .max_iter(500)
    .abstol(1e-4)
    .reltol(1e-3)
    .build();

// Coordinate descent for L1 regularization
let cd = CoordinateDescentSolver::builder()
    .selection_rule(SelectionRule::Cyclic)
    .build();
```

### Numerical Stability

```rust
use sklears_linear::{LinearRegression, Solver};

// Automatic method selection based on condition number
let stable_model = LinearRegression::builder()
    .solver(Solver::Auto)  // Chooses based on matrix condition
    .check_condition(true)
    .build();

// Iterative refinement for ill-conditioned problems
let refined = LinearRegression::builder()
    .solver(Solver::QR)
    .iterative_refinement(true)
    .build();
```

### Sparse Data Support

```rust
use sklears_linear::sparse::{SparseLinearRegression};
use sprs::CsMat;

// Efficient sparse matrix operations
let sparse_X = CsMat::from_dense(...);
let model = SparseLinearRegression::default();
let fitted = model.fit(&sparse_X, &y)?;
```

### Bayesian Linear Models

```rust
use sklears_linear::{BayesianRidge, VariationalBayesRegression};

// Bayesian ridge with automatic relevance determination
let bayesian = BayesianRidge::builder()
    .n_iter(300)
    .compute_score(true)
    .build();

// Variational Bayes for uncertainty quantification
let vb = VariationalBayesRegression::builder()
    .credible_interval(0.95)
    .build();

let fitted = vb.fit(&X, &y)?;
let (predictions, lower, upper) = fitted.predict_with_uncertainty(&X)?;
```

## Performance Features

### Parallel Training

```rust
let model = Ridge::builder()
    .alpha(1.0)
    .n_jobs(4)  // Use 4 threads
    .build();
```

### Cross-Validation

```rust
use sklears_linear::{RidgeCV, LassoCV};

// Ridge with built-in cross-validation
let ridge_cv = RidgeCV::builder()
    .alphas(vec![0.1, 1.0, 10.0])
    .cv(5)
    .build();

// Lasso with efficient path computation
let lasso_cv = LassoCV::builder()
    .n_alphas(100)
    .cv(10)
    .build();
```

### Early Stopping

```rust
let model = Lasso::builder()
    .alpha(0.1)
    .early_stopping(true)
    .validation_fraction(0.2)
    .n_iter_no_change(5)
    .build();
```

## Specialized Regression

### Robust Regression

```rust
use sklears_linear::{HuberRegressor, RANSACRegressor};

// Huber regression for outliers
let huber = HuberRegressor::builder()
    .epsilon(1.35)
    .alpha(0.0001)
    .build();

// RANSAC for severe outliers
let ransac = RANSACRegressor::builder()
    .min_samples(0.5)
    .residual_threshold(5.0)
    .build();
```

### Quantile Regression

```rust
use sklears_linear::QuantileRegressor;

// Median regression (50th percentile)
let median = QuantileRegressor::builder()
    .quantile(0.5)
    .solver(QuantileSolver::InteriorPoint)
    .build();

// Multiple quantiles
let quantiles = vec![0.1, 0.5, 0.9];
for q in quantiles {
    let model = QuantileRegressor::new(q);
    // Fit and predict...
}
```

## Benchmarks

Performance comparisons on standard datasets:

| Model | scikit-learn | sklears-linear | Speedup |
|-------|--------------|----------------|---------|
| Linear Regression | 2.3ms | 0.3ms | 7.7x |
| Ridge (Cholesky) | 1.8ms | 0.2ms | 9.0x |
| Lasso (CD) | 15ms | 1.2ms | 12.5x |
| ElasticNet | 18ms | 1.5ms | 12.0x |

With GPU acceleration (coming soon):
- Expected 50-100x speedup for large problems
- Linear scaling with problem size

## Architecture

```
sklears-linear/
├── models/         # Core linear models
├── solvers/        # Optimization algorithms
├── regularization/ # L1, L2, ElasticNet
├── robust/         # Robust regression methods
├── bayesian/       # Bayesian linear models
├── sparse/         # Sparse matrix support
└── gpu/           # GPU acceleration (WIP)
```

## Status

**Stable** (`0.1.2`)

- **Core Models**: 100% complete
- **Advanced Solvers**: 100% complete
- **Tests**: 429 passing, 3 skipped
- **GPU Support**: In development

## Contributing

We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md).

## License

Licensed under the Apache License, Version 2.0.

## Citation

```bibtex
@software{sklears_linear,
  title = {sklears-linear: High-Performance Linear Models for Rust},
  author = {COOLJAPAN OU (Team KitaSan)},
  year = {2026},
  url = {https://github.com/cool-japan/sklears}
}
```
