Skip to main content

rusting_brain/
lib.rs

1//! A deep-learning library in Rust, from a two-layer XOR network up to a
2//! 300M-parameter transformer language model.
3//!
4//! There are two model types, and they share the matrix, optimizer, and
5//! serialization code underneath:
6//!
7//! - [`Network`] — a dense feed-forward network for tabular regression and
8//!   classification. Built with [`Network::builder`], trained with
9//!   [`Network::fit`].
10//! - [`TransformerLm`] — a decoder-only language model with grouped-query
11//!   attention, rotary positions, RMSNorm, SwiGLU feed-forwards, and optional
12//!   sparse mixture-of-experts layers. Built with [`TransformerLm::builder`],
13//!   trained one batch at a time with [`TransformerLm::train_step`].
14//!
15//! # A language model in twenty lines
16//!
17//! ```no_run
18//! use rusting_brain::{Optimizer, TransformerLm};
19//!
20//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
21//! let mut model = TransformerLm::builder()
22//!     .vocab_size(32_000)
23//!     .d_model(512)
24//!     .n_layers(8)
25//!     .heads(8, 2, 64)          // 8 query heads, 2 key/value heads (GQA)
26//!     .d_ff(1408)
27//!     .experts(8, 2)            // 8 experts, 2 active per token
28//!     .moe_layers(2..8)         // layers 0-1 stay dense
29//!     .max_seq_len(1024)
30//!     .optimizer(Optimizer::adam(3e-4))
31//!     .seed(42)
32//!     .build()?;
33//!
34//! println!("{}", model.parameter_counts());   // total vs. active
35//!
36//! let batch: Vec<Vec<u32>> = vec![vec![1, 2, 3, 4], vec![5, 6, 7, 8]];
37//! let loss = model.train_step(&batch)?;
38//! println!("loss {:.4}", loss.lm_loss);
39//! # Ok(())
40//! # }
41//! ```
42//!
43//! # Generating text
44//!
45//! [`TransformerLm::generate`] prefills a per-layer [`KvCache`] with the prompt
46//! and then decodes one token at a time, so the *n*-th token costs one row of
47//! attention instead of *n*. [`Sampler`] decides which token that is.
48//!
49//! ```no_run
50//! # use rusting_brain::{Sampler, TransformerLm};
51//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
52//! # let model = TransformerLm::builder().build()?;
53//! # let prompt = [1u32, 2, 3];
54//! let mut sampler = Sampler::temperature(0.8, Some(42)).top_k(40).top_p(0.95);
55//! let generated = model.generate(&prompt, 50, &mut sampler)?;
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! [`TransformerLm::forward_cached`] is the cache underneath, for driving
61//! decoding by hand.
62//!
63//! # Running on a GPU
64//!
65//! CUDA is an optional feature and is off by default; the crate builds and the
66//! tests pass without a driver, a toolkit, or a device.
67//!
68//! ```bash
69//! cargo add rusting_brain --features cuda
70//! ```
71//!
72//! [`TransformerLm::to_cuda`] moves the parameters onto a device and every
73//! later `train_step`, `forward_batch`, and `backward` runs there. The device
74//! path is fail-closed: if the driver, cuBLAS, a kernel, an allocation, or a
75//! numerical check fails, the call returns [`NetworkError`] rather than
76//! silently falling back to the CPU.
77//!
78//! ```no_run
79//! # use rusting_brain::TransformerLm;
80//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
81//! # let mut model = TransformerLm::builder().build()?;
82//! # #[cfg(feature = "cuda")] {
83//! model.set_mixed_precision(true);      // BF16 GEMMs, FP32 master weights
84//! model.to_cuda(0, 9_000)?;             // device 0, 9000 MiB budget
85//! # }
86//! # Ok(())
87//! # }
88//! ```
89//!
90//! Dense [`Network`]s use a separate device path,
91//! [`TrainingBackend::Cuda`], or `metal_training` on Apple Silicon.
92//!
93//! # Where to read next
94//!
95//! - `tutorials/` — a sixteen-chapter course, from what a neural network is to
96//!   training a language model end to end.
97//! - `docs/baseline.md` — measured throughput per architecture on an RTX 3060.
98//! - `IMPORT_MODELS.md` — running ONNX models exported from TensorFlow or
99//!   PyTorch.
100
101pub mod accelerator;
102pub mod activations;
103pub mod adaln;
104pub mod attention;
105pub mod batch;
106pub mod causal_lm_loss;
107pub mod checkpoint;
108pub mod clip;
109pub mod conv;
110pub mod dataset;
111pub mod detection;
112pub mod diffusion;
113pub mod dit_lora;
114pub mod ema;
115pub mod embedding;
116pub mod ffn;
117pub mod flow_transformer;
118#[cfg(test)]
119mod fuzz;
120pub mod gguf;
121pub mod gltf;
122pub mod hf;
123pub mod interoceptive;
124pub mod losses;
125pub mod masked_lm;
126pub mod matrix;
127pub mod mesh;
128pub mod mmdit;
129pub mod moe;
130pub mod network;
131pub mod norm;
132pub mod optimizers;
133pub mod param;
134pub mod pipeline;
135pub mod quantized;
136pub mod recurrent;
137pub mod rng;
138pub mod rope;
139pub mod safetensors;
140pub mod sampling;
141pub mod serialization;
142pub mod shape_vae;
143pub mod shards;
144pub mod t5;
145pub mod text_encoder;
146pub mod token_file;
147pub mod tokenizer;
148pub mod transformer;
149pub mod transformer_block;
150pub mod unet;
151pub mod unet_lora;
152pub mod vae;
153pub mod vision;
154pub mod vit_encoder;
155pub mod webdataset;
156pub mod yolo;
157
158#[cfg(feature = "cuda")]
159pub(crate) mod cuda_flash;
160#[cfg(feature = "cuda")]
161pub mod cuda_image;
162#[cfg(feature = "cuda")]
163pub mod cuda_mmdit;
164#[cfg(feature = "cuda")]
165pub mod cuda_t5;
166#[cfg(feature = "cuda")]
167pub mod cuda_training;
168#[cfg(feature = "cuda")]
169pub(crate) mod gpu_cross;
170#[cfg(feature = "cuda")]
171pub(crate) mod gpu_flow;
172#[cfg(feature = "cuda")]
173pub(crate) mod gpu_matrix;
174#[cfg(feature = "cuda")]
175pub(crate) mod gpu_model;
176#[cfg(feature = "cuda")]
177pub(crate) mod gpu_shape;
178#[cfg(feature = "cuda")]
179pub mod gpu_test;
180#[cfg(feature = "cuda")]
181pub mod gpu_transformer;
182#[cfg(all(feature = "metal", target_os = "macos"))]
183pub mod metal_training;
184
185pub mod onnx;
186pub(crate) mod onnx_export;
187
188/// The library version and the commit it was built from, such as
189/// `3.0.0 (b46a6b4)`. Print it at startup: a binary built from an older
190/// checkout then shows a hash that does not match `git rev-parse --short HEAD`.
191/// The hash is `unknown` outside a git checkout.
192pub const BUILD: &str = concat!(
193    env!("CARGO_PKG_VERSION"),
194    " (",
195    env!("RUSTING_BRAIN_GIT_HASH"),
196    ")"
197);
198
199#[cfg(test)]
200#[test]
201fn build_names_the_checkout() {
202    let head = std::process::Command::new("git")
203        .args(["rev-parse", "--short", "HEAD"])
204        .output()
205        .unwrap();
206    let head = String::from_utf8(head.stdout).unwrap();
207    assert_eq!(
208        BUILD,
209        format!("{} ({})", env!("CARGO_PKG_VERSION"), head.trim())
210    );
211}
212
213pub use accelerator::{
214    AcceleratorDoctorReport, AcceleratorStats, TrainingSession, accelerator_doctor,
215    estimate_tensor_memory_mib,
216};
217pub use activations::Activation;
218pub use adaln::{
219    AdaLayerNorm, AdaLnCache, Modulation, ModulationCache, TimestepCache, TimestepEmbedding,
220    gate_residual, gate_residual_backward,
221};
222pub use attention::{CrossAttentionCache, KvCache, MultiHeadAttention};
223pub use batch::{Layout, TokenBatch};
224pub use causal_lm_loss::{CausalLmLoss, TotalLoss, causal_lm_loss, causal_lm_loss_batch};
225pub use checkpoint::{load as load_checkpoint, save as save_checkpoint};
226pub use clip::{ClipTextConfig, ClipTextEncoder};
227pub use conv::{
228    Conv2d, ConvCache, ConvGeometry, FeatureMap, GroupNorm, GroupNormCache, ImageBatch,
229    TrainableConv2d, TrainableGroupNorm, pixel_shuffle, pixel_unshuffle, upsample_nearest,
230};
231#[cfg(feature = "cuda")]
232pub use conv::{
233    DeviceGroupNormCache, DeviceImageBatch, DeviceSpatialSoftmaxCache,
234    global_avg_pool_backward_device, global_avg_pool_device, silu_backward_device, silu_device,
235    spatial_softmax_backward_device, spatial_softmax_device,
236};
237#[cfg(feature = "cuda")]
238pub use cuda_training::{CudaDoctorReport, CudaTrainingSession, CudaTrainingStats, cuda_doctor};
239pub use dataset::{
240    Augment, BatchCursor, BatchSource, Dataset, DatasetBatch, DatasetStream, JsonlStream,
241    Standardizer,
242};
243pub use diffusion::{
244    Denoiser, Inpaint, SamplingConfig, Scheduler, Solver, noise, sample, sample_consistency,
245    sample_from, sample_unipc, sample_with_sigmas,
246};
247pub use ema::Ema;
248pub use embedding::Embedding;
249pub use ffn::{GeluMlp, SwiGlu};
250pub use flow_transformer::{
251    FlowConfig, FlowDenoiser, FlowTransformer, flow_match_target, sample_timesteps,
252};
253pub use gltf::Glb;
254#[cfg(feature = "cuda")]
255pub use gpu_transformer::GpuContext;
256pub use losses::Loss;
257pub use masked_lm::{MaskedBatch, masked_lm_loss};
258pub use matrix::Matrix;
259pub use mesh::{
260    Bvh, Mesh, QuerySampling, Transform, marching_tetrahedra, marching_tetrahedra_sparse,
261};
262#[cfg(all(feature = "metal", target_os = "macos"))]
263pub use metal_training::{MetalTrainingSession, metal_doctor};
264pub use mmdit::{Conditioning, Dit, DitConfig};
265pub use moe::{Expert, MoeConfig, MoeLayer, Router};
266pub use network::{
267    CudaTrainingCheckpoint, Dense, DenseLayer, Network, NetworkBuilder, NetworkError, TrainConfig,
268    TrainingBackend, TrainingHistory,
269};
270pub use norm::RmsNorm;
271pub use optimizers::{Optimizer, Schedule, SpikeGuard};
272pub use param::{CudaDevice, Linear, Lora, Param};
273pub use pipeline::{
274    DynamicShift, ImageDenoiser, ImagePipeline, PipelineConfig, PooledEncoder, PromptEncoder,
275};
276pub use rng::RunRng;
277pub use rope::Rope;
278pub use safetensors::{Dtype, SafeTensors, ShardedSafeTensors, TensorInfo};
279pub use sampling::Sampler;
280pub use shape_vae::{ShapeVae, ShapeVaeConfig, fourier_features};
281pub use shards::{Batch, BatchConfig, BatchStream, Corpus, Example, Shards};
282pub use t5::{T5Config, T5Encoder};
283pub use text_encoder::{TextEncoder, TextEncoderConfig};
284pub use token_file::{TokenFile, TokenMix, TokenStream};
285pub use tokenizer::{Bpe, Unigram};
286pub use transformer::{
287    BatchDecoder, Decoder, LoraConfig, ParameterCounts, Precision, TransformerBuilder,
288    TransformerConfig, TransformerLm,
289};
290pub use transformer_block::{FeedForward, TransformerBlock};
291pub use unet::{Control, ControlNet, Unet, UnetConfig};
292pub use vae::{VaeConfig, VaeDecoder, VaeEncoder, to_rgb8};
293pub use vision::{VisionTransformer, VitConfig};
294#[cfg(feature = "images")]
295pub use vit_encoder::read_image;
296pub use vit_encoder::{CLIP_MEAN, CLIP_STD, VitEncoder, VitEncoderConfig, composite_rgba};