Crate rust_mlp 

A small MLP (multi-layer perceptron) crate.

rust-mlp is a small-core, from-scratch implementation of a dense feed-forward network. It is designed to be easy to read while keeping the per-sample hot path allocation-free.

Design goals

• Predictable performance: reuse buffers (Scratch / Gradients) instead of allocating.
• Clear contracts: shapes are explicit and validated at the API boundary.
• Practical training loop: fit supports mini-batches, shuffling, LR schedules, and common optimizers.

Panics vs Result

This crate intentionally exposes two layers of API:

• Low-level hot path (panics on misuse):

  • mlp::Mlp::forward, mlp::Mlp::backward
  • mlp::Mlp::forward_batch, mlp::Mlp::backward_batch Shape mismatches are treated as programmer error and will panic via assert!.

• High-level convenience APIs (shape-checked):

  • crate::Mlp::fit, crate::Mlp::evaluate
  • mlp::Mlp::predict_into These validate inputs and return Result.

Data layout and shapes

• Scalars are f32.
• Dataset and Inputs store samples contiguously in row-major layout.
• Layer weights are row-major with shape (out_dim, in_dim).
• Batched inputs/outputs are passed as flat row-major buffers:
  • inputs: (batch_size, input_dim) as batch_size * input_dim scalars
  • outputs: (batch_size, output_dim) as batch_size * output_dim scalars

MSRV

This crate’s minimum supported Rust version (MSRV) is specified in Cargo.toml.

See ROADMAP.md for the production-readiness plan.

Quick start

use rust_mlp::{Activation, FitConfig, Loss, Metric, MlpBuilder};

let xs = vec![
    vec![0.0, 0.0],
    vec![0.0, 1.0],
    vec![1.0, 0.0],
    vec![1.0, 1.0],
];
let ys = vec![vec![0.0], vec![1.0], vec![1.0], vec![0.0]];
let train = rust_mlp::Dataset::from_rows(&xs, &ys)?;

let mut mlp = MlpBuilder::new(2)?
    .add_layer(8, Activation::ReLU)?
    .add_layer(1, Activation::Sigmoid)?
    .build_with_seed(0)?;

let _report = mlp.fit(
    &train,
    None,
    FitConfig {
        epochs: 200,
        lr: 0.1,
        batch_size: 4,
        shuffle: rust_mlp::Shuffle::Seeded(0),
        lr_schedule: rust_mlp::LrSchedule::Constant,
        optimizer: rust_mlp::Optimizer::Adam {
            beta1: 0.9,
            beta2: 0.999,
            eps: 1e-8,
        },
        weight_decay: 0.0,
        grad_clip_norm: None,
        loss: Loss::Mse,
        metrics: vec![Metric::Accuracy],
    },
)?;
Ok(())

Allocation-free training (advanced)

If you want to drive training yourself (e.g. custom loop), allocate buffers once and reuse them across steps:

use rust_mlp::{Activation, Loss, MlpBuilder};

let mut mlp = MlpBuilder::new(3)?
    .add_layer(8, Activation::Tanh)?
    .add_layer(2, Activation::Identity)?
    .build_with_seed(0)?;

let mut trainer = mlp.trainer();
let x = [0.1_f32, -0.2, 0.3];
let t = [0.0_f32, 1.0];

let y = mlp.forward(&x, &mut trainer.scratch);
let _loss = Loss::Mse.backward(y, &t, trainer.grads.d_output_mut());
mlp.backward(&x, &trainer.scratch, &mut trainer.grads);
mlp.sgd_step(&trainer.grads, 1e-2);
Ok(())

Re-exports

pub use activation::Activation;

pub use builder::MlpBuilder;

pub use data::Dataset;

pub use data::Inputs;

pub use error::Error;

pub use error::Result;

pub use layer::Init;

pub use layer::Layer;

pub use loss::Loss;

pub use metrics::Metric;

pub use mlp::Trainer;

pub use mlp::BatchBackpropScratch;

pub use mlp::BatchScratch;

pub use mlp::Gradients;

pub use mlp::Mlp;

pub use mlp::Scratch;

pub use optim::Optimizer;

pub use optim::OptimizerState;

pub use optim::Sgd;

pub use train::Shuffle;

pub use train::EpochReport;

pub use train::EvalReport;

pub use train::FitConfig;

pub use train::FitReport;

pub use train::LrSchedule;

Modules

activation

Activation functions.

builder

Model builder.

data

Contiguous dataset helpers.

error

Error and Result types.

layer

Dense layer implementation.

loss

Loss functions.

metrics

Metrics.

mlp

Multi-layer perceptron (MLP) core.

optim

Optimizers.

serde_model

Model serialization/deserialization (feature: serde).

train

High-level training and evaluation APIs.

Functions

predict_into

Shape-safe, non-allocating inference.