rust_lstm/
lib.rs

1#![allow(clippy::type_complexity)]
2
3//! # Rust LSTM Library
4//!
5//! A complete LSTM implementation with training capabilities, multiple optimizers,
6//! dropout regularization, and support for various architectures including peephole
7//! connections and bidirectional processing.
8//!
9//! ## Core Components
10//!
11//! - **LSTM Cells**: Standard and peephole LSTM implementations with full backpropagation
12//! - **Bidirectional LSTM**: Process sequences in both directions with flexible output combination
13//! - **Networks**: Multi-layer LSTM networks for sequence modeling
14//! - **Training**: Complete training system with BPTT, gradient clipping, and validation
15//! - **Optimizers**: SGD, Adam, and RMSprop optimizers with adaptive learning rates
16//! - **Loss Functions**: MSE, MAE, and Cross-Entropy with numerically stable implementations
17//! - **Dropout**: Input, recurrent, output dropout and zoneout regularization
18//!
19//! ## Quick Start
20//!
21//! ```rust
22//! use rust_lstm::models::lstm_network::LSTMNetwork;
23//! use rust_lstm::training::create_basic_trainer;
24//!
25//! // Create a 2-layer LSTM with 10 input features and 20 hidden units
26//! let mut network = LSTMNetwork::new(10, 20, 2)
27//!     .with_input_dropout(0.2, true)     // Variational input dropout
28//!     .with_recurrent_dropout(0.3, true) // Variational recurrent dropout
29//!     .with_output_dropout(0.1);         // Standard output dropout
30//!
31//! let mut trainer = create_basic_trainer(network, 0.001);
32//!
33//! // Train on your data
34//! // trainer.train(&train_data, Some(&validation_data));
35//! ```
36
37pub mod layers;
38pub mod loss;
39pub mod models;
40pub mod optimizers;
41pub mod persistence;
42pub mod random;
43pub mod schedulers;
44pub mod text;
45pub mod training;
46/// Main library module.
47pub mod utils;
48
49// Re-export commonly used items
50pub use layers::bilstm_network::{BiLSTMNetwork, BiLSTMNetworkCache, CombineMode};
51pub use layers::dropout::{Dropout, Zoneout};
52pub use layers::gru_cell::{GRUCell, GRUCellCache, GRUCellGradients};
53pub use layers::linear::{LinearGradients, LinearLayer};
54pub use layers::lstm_cell::{LSTMCell, LSTMCellCache, LSTMCellGradients};
55pub use layers::peephole_lstm_cell::{
56    PeepholeLSTMCell, PeepholeLSTMCellCache, PeepholeLSTMCellGradients,
57};
58pub use loss::{CrossEntropyLoss, LossFunction, MAELoss, MSELoss};
59pub use models::gru_network::{
60    GRUNetwork, GRUNetworkCache, LayerDropoutConfig as GRULayerDropoutConfig,
61};
62pub use models::lstm_network::{LSTMNetwork, LSTMNetworkCache, LSTMState, LayerDropoutConfig};
63pub use optimizers::{Adam, RMSprop, ScheduledOptimizer, SGD};
64pub use persistence::{ModelMetadata, ModelPersistence, PersistenceError, PersistentModel};
65pub use random::seed;
66pub use schedulers::{
67    AnnealStrategy, ConstantLR, CosineAnnealingLR, CosineAnnealingWarmRestarts, CyclicalLR,
68    CyclicalMode, ExponentialLR, LRScheduleVisualizer, LearningRateScheduler, LinearLR,
69    MultiStepLR, OneCycleLR, PolynomialLR, ReduceLROnPlateau, ScaleMode, StepLR, WarmupScheduler,
70};
71pub use text::{
72    argmax, sample_nucleus, sample_top_k, sample_with_temperature, softmax, CharacterEmbedding,
73    EmbeddingGradients, TextVocabulary,
74};
75pub use training::{
76    create_adam_batch_trainer, create_basic_batch_trainer, create_basic_trainer,
77    create_cosine_annealing_trainer, create_one_cycle_trainer, create_step_lr_trainer,
78    EarlyStopper, EarlyStoppingConfig, EarlyStoppingMetric, LSTMBatchTrainer, LSTMTrainer,
79    ScheduledLSTMTrainer, TrainingConfig, TrainingMetrics,
80};
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85    use ndarray::arr2;
86
87    #[test]
88    fn test_library_integration() {
89        let mut network = models::lstm_network::LSTMNetwork::new(2, 3, 1);
90        let input = arr2(&[[1.0], [0.5]]);
91        let state = network.zero_state(1);
92
93        let (hy, next) = network.forward(&input, &state);
94        let cy = &next.c[0];
95
96        assert_eq!(hy.shape(), &[3, 1]);
97        assert_eq!(cy.shape(), &[3, 1]);
98    }
99
100    #[test]
101    fn test_library_with_dropout() {
102        let mut network = models::lstm_network::LSTMNetwork::new(2, 3, 1)
103            .with_input_dropout(0.2, false)
104            .with_recurrent_dropout(0.3, true)
105            .with_output_dropout(0.1);
106
107        let input = arr2(&[[1.0], [0.5]]);
108        let state = network.zero_state(1);
109
110        // Test training mode
111        network.train();
112        let (hy_train, next_train) = network.forward(&input, &state);
113        let cy_train = &next_train.c[0];
114
115        // Test evaluation mode
116        network.eval();
117        let (hy_eval, next_eval) = network.forward(&input, &state);
118        let cy_eval = &next_eval.c[0];
119
120        assert_eq!(hy_train.shape(), &[3, 1]);
121        assert_eq!(cy_train.shape(), &[3, 1]);
122        assert_eq!(hy_eval.shape(), &[3, 1]);
123        assert_eq!(cy_eval.shape(), &[3, 1]);
124    }
125}
rust_lstm/lib.rs

rust_lstm/
lib.rs
