rusting_brain 1.0.0

A Rust neural-network library for learning, training, and inference from small models to small size LLM.
Documentation

RustingBrain

RustingBrain is a small neural-network library for learning how inference and training work under the hood.

The crate keeps the core pieces visible: matrices, dense layers, activations, loss functions, optimizers, batches, and model weights. It is not trying to replace PyTorch or TensorFlow. It is for experiments, study, and small models where readable Rust code matters more than having every deep-learning feature.

Features

  • Dense feedforward networks
  • Regression, binary classification, multiclass classification, and XOR examples
  • ReLU, sigmoid, tanh, softmax, and linear activations
  • Mean squared error, binary cross entropy, and cross entropy losses
  • SGD and Adam optimizers
  • Mini-batch training with reproducible shuffling
  • JSON save/load for RustingBrain models
  • ONNX inference for models trained elsewhere
  • Optional fail-closed FP32 CUDA training (MSE; linear/ReLU/tanh/sigmoid; SGD/Adam)

Install

Add the crate from crates.io:

cargo add rusting_brain

Or clone and run the examples:

git clone https://github.com/Vasyl-Trefilov/RustingBrain.git
cd RustingBrain
cargo test
cargo run --example xor

Quick Example

use rusting_brain::{Activation, Dataset, Loss, Network, Optimizer, TrainConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let data = Dataset::new(
        vec![
            vec![0.0, 0.0],
            vec![0.0, 1.0],
            vec![1.0, 0.0],
            vec![1.0, 1.0],
        ],
        vec![vec![0.0], vec![1.0], vec![1.0], vec![0.0]],
    );

    let mut model = Network::builder()
        .input_size(2)
        .dense(8, Activation::Tanh)
        .dense(1, Activation::Sigmoid)
        .loss(Loss::BinaryCrossEntropy)
        .optimizer(Optimizer::adam(0.05))
        .build();

    model.fit(
        &data,
        TrainConfig {
            epochs: 2_000,
            batch_size: 4,
            shuffle: true,
            seed: Some(42),
        },
    )?;

    println!("{:?}", model.predict(&[1.0, 0.0])?);
    Ok(())
}

Examples

cargo run --example xor
cargo run --example regression
cargo run --example classification
cargo run --example save_load

Save And Load

model.save_json("model.json")?;
let loaded = rusting_brain::Network::load_json("model.json")?;

The saved JSON contains the network shape, activations, loss, weights, biases, and file format version. Optimizer state is not stored yet, so saved models are mainly for inference and reproducible examples.

Import Models

RustingBrain can run ONNX models for inference:

cargo run --example onnx_inference --features onnx -- model.onnx

Some TensorFlow exports leave the input shape dynamic. In that case, pass the shape and input values explicitly:

cargo run --example onnx_inference --features onnx -- xor.onnx 1,2 0,1

See IMPORT_MODELS.md for the TensorFlow/Keras to ONNX flow.

CUDA Benchmark

CUDA is optional. The normal crate build does not require CUDA, nvcc, or an NVIDIA GPU.

CUDA Training

CUDA fitting is explicit and fail-closed: TrainingBackend::Cuda returns an error if the driver, cuBLAS, kernels, allocation, or numerical checks fail. It never switches to CPU training. JSON model artifacts remain unchanged, so a model trained on CUDA can be saved and loaded for ordinary CPU inference.

For epoch-level checkpointing, keep the CUDA resources alive with CudaTrainingSession: call train_epoch() repeatedly and call checkpoint() only when a host snapshot is needed. stats() reports allocated tensor bytes, transfer counts, and setup/training/checkpoint timing. The complete dataset is kept on the device when it fits the configured memory budget; otherwise the session reuses staged batch buffers.

cargo test --features cuda
cargo run --example cuda_training_smoke --features cuda
cargo run --release --example cuda_persistent_training --features cuda

For a 12 GiB RTX 3060, RustingTrade should request an application budget of 8192 MiB, leaving capacity for the desktop, driver, and other processes.

To compile the CUDA benchmark support:

cargo check --features cuda

To run the benchmark on a CUDA machine:

cargo run --release --example cuda_benchmark --features cuda

See INSTALL_CUDA.md for driver, toolkit, and cuBLAS setup.

Scope

The current focus is dense neural networks and inference interop. Convolution layers, transformer experiments, mixed precision, and full GPU training are future work.

License

RustingBrain is released under the RustingBrain License 1.0. You can use, modify, and distribute it, including in commercial projects, but redistributed copies must keep the license and credit Vasyl Trefilov as the original author.

See LICENSE.md for the full terms.