Enhance documentation with usage examples for crate::compute::models

src/compute/models/activations.rs

@@ -1,3 +1,15 @@
+//! Common activation functions used in neural networks.
+//!
+//! Functions operate element-wise on [`Matrix`] values.
+//!
+//! ```
+//! use rustframe::compute::models::activations::sigmoid;
+//! use rustframe::matrix::Matrix;
+//!
+//! let x = Matrix::from_vec(vec![0.0], 1, 1);
+//! let y = sigmoid(&x);
+//! assert!((y.get(0,0) - 0.5).abs() < 1e-6);
+//! ```
 use crate::matrix::{Matrix, SeriesOps};
 
 pub fn sigmoid(x: &Matrix<f64>) -> Matrix<f64> {

src/compute/models/dense_nn.rs

@@ -1,3 +1,30 @@
+//! A minimal dense neural network implementation for educational purposes.
+//!
+//! Layers operate on [`Matrix`] values and support ReLU and Sigmoid
+//! activations. This is not meant to be a performant deep‑learning framework
+//! but rather a small example of how the surrounding matrix utilities can be
+//! composed.
+//!
+//! ```
+//! use rustframe::compute::models::dense_nn::{ActivationKind, DenseNN, DenseNNConfig, InitializerKind, LossKind};
+//! use rustframe::matrix::Matrix;
+//!
+//! // Tiny network with one input and one output neuron.
+//! let config = DenseNNConfig {
+//!     input_size: 1,
+//!     hidden_layers: vec![],
+//!     output_size: 1,
+//!     activations: vec![ActivationKind::Relu],
+//!     initializer: InitializerKind::Uniform(0.5),
+//!     loss: LossKind::MSE,
+//!     learning_rate: 0.1,
+//!     epochs: 1,
+//! };
+//! let mut nn = DenseNN::new(config);
+//! let x = Matrix::from_vec(vec![1.0, 2.0], 2, 1);
+//! let y = Matrix::from_vec(vec![2.0, 3.0], 2, 1);
+//! nn.train(&x, &y);
+//! ```
 use crate::compute::models::activations::{drelu, relu, sigmoid};
 use crate::matrix::{Matrix, SeriesOps};
 use crate::random::prelude::*;

src/compute/models/gaussian_nb.rs

@@ -1,3 +1,16 @@
+//! Gaussian Naive Bayes classifier for dense matrices.
+//!
+//! ```
+//! use rustframe::compute::models::gaussian_nb::GaussianNB;
+//! use rustframe::matrix::Matrix;
+//!
+//! let x = Matrix::from_vec(vec![1.0, 2.0, 1.0, 2.0], 2, 2); // two samples
+//! let y = Matrix::from_vec(vec![0.0, 1.0], 2, 1);
+//! let mut model = GaussianNB::new(1e-9, false);
+//! model.fit(&x, &y);
+//! let preds = model.predict(&x);
+//! assert_eq!(preds.rows(), 2);
+//! ```
 use crate::matrix::Matrix;
 use std::collections::HashMap;
 

src/compute/models/k_means.rs

@@ -1,3 +1,14 @@
+//! Simple k-means clustering working on [`Matrix`] data.
+//!
+//! ```
+//! use rustframe::compute::models::k_means::KMeans;
+//! use rustframe::matrix::Matrix;
+//!
+//! let data = Matrix::from_vec(vec![1.0, 1.0, 5.0, 5.0], 2, 2);
+//! let (model, labels) = KMeans::fit(&data, 2, 10, 1e-4);
+//! assert_eq!(model.centroids.rows(), 2);
+//! assert_eq!(labels.len(), 2);
+//! ```
 use crate::compute::stats::mean_vertical;
 use crate::matrix::Matrix;
 use crate::random::prelude::*;

src/compute/models/linreg.rs

@@ -1,3 +1,16 @@
+//! Ordinary least squares linear regression.
+//!
+//! ```
+//! use rustframe::compute::models::linreg::LinReg;
+//! use rustframe::matrix::Matrix;
+//!
+//! let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 4, 1);
+//! let y = Matrix::from_vec(vec![2.0, 3.0, 4.0, 5.0], 4, 1);
+//! let mut model = LinReg::new(1);
+//! model.fit(&x, &y, 0.01, 100);
+//! let preds = model.predict(&x);
+//! assert_eq!(preds.rows(), 4);
+//! ```
 use crate::matrix::{Matrix, SeriesOps};
 
 pub struct LinReg {

src/compute/models/logreg.rs

@@ -1,3 +1,16 @@
+//! Binary logistic regression classifier.
+//!
+//! ```
+//! use rustframe::compute::models::logreg::LogReg;
+//! use rustframe::matrix::Matrix;
+//!
+//! let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 4, 1);
+//! let y = Matrix::from_vec(vec![0.0, 0.0, 1.0, 1.0], 4, 1);
+//! let mut model = LogReg::new(1);
+//! model.fit(&x, &y, 0.1, 100);
+//! let preds = model.predict(&x);
+//! assert_eq!(preds[(0,0)], 0.0);
+//! ```
 use crate::compute::models::activations::sigmoid;
 use crate::matrix::{Matrix, SeriesOps};
 

src/compute/models/mod.rs

@@ -1,3 +1,19 @@
+//! Lightweight machine‑learning models built on matrices.
+//!
+//! Models are intentionally minimal and operate on the [`Matrix`](crate::matrix::Matrix) type for
+//! inputs and parameters.
+//!
+//! ```
+//! use rustframe::compute::models::linreg::LinReg;
+//! use rustframe::matrix::Matrix;
+//!
+//! let x = Matrix::from_vec(vec![1.0, 2.0, 3.0, 4.0], 4, 1);
+//! let y = Matrix::from_vec(vec![2.0, 3.0, 4.0, 5.0], 4, 1);
+//! let mut model = LinReg::new(1);
+//! model.fit(&x, &y, 0.01, 1000);
+//! let preds = model.predict(&x);
+//! assert_eq!(preds.rows(), 4);
+//! ```
 pub mod activations;
 pub mod dense_nn;
 pub mod gaussian_nb;

src/compute/models/pca.rs

@@ -1,3 +1,14 @@
+//! Principal Component Analysis using covariance matrices.
+//!
+//! ```
+//! use rustframe::compute::models::pca::PCA;
+//! use rustframe::matrix::Matrix;
+//!
+//! let data = Matrix::from_rows_vec(vec![1.0, 1.0, 2.0, 2.0], 2, 2);
+//! let pca = PCA::fit(&data, 1, 0);
+//! let projected = pca.transform(&data);
+//! assert_eq!(projected.cols(), 1);
+//! ```
 use crate::compute::stats::correlation::covariance_matrix;
 use crate::compute::stats::descriptive::mean_vertical;
 use crate::matrix::{Axis, Matrix, SeriesOps};