r2l_core/
lib.rs

1//! Core traits and data types shared by the `r2l` workspace.
2//!
3//! `r2l-core` is the contracts crate. It defines the small set of interfaces
4//! that environments, samplers, policies, agents, learners, and tensor
5//! backends agree on. Backend-specific implementations live in crates such as
6//! `r2l-burn` and `r2l-candle`; concrete algorithms and builders live outside
7//! this crate as well.
8//!
9//! Most downstream code should start with the prelude:
10//!
11//! ```
12//! use r2l_core::prelude::*;
13//! ```
14//!
15//! The main extension points are:
16//!
17//! - [`Env`] and [`EnvBuilder`] for environment integrations.
18//! - [`R2lTensor`] for tensor types used by environments
19//!   and learning code.
20//! - [`Actor`], [`Policy`], [`ValueFunction`], and [`Learner`] for model
21//!   and optimizer components.
22//! - [`TrajectoryBuffer`] and [`TrajectoryView`] for rollout storage.
23//! - [`Agent`], [`Sampler`], and [`OnPolicyAlgorithm`] for on-policy training
24//!   loops.
25//!
26//! [`Actor`]: crate::models::Actor
27//! [`Agent`]: crate::on_policy::algorithm::Agent
28//! [`Env`]: crate::env::Env
29//! [`EnvBuilder`]: crate::env::EnvBuilder
30//! [`Learner`]: crate::models::Learner
31//! [`OnPolicyAlgorithm`]: crate::on_policy::algorithm::OnPolicyAlgorithm
32//! [`Policy`]: crate::models::Policy
33//! [`R2lTensor`]: crate::tensor::R2lTensor
34//! [`Sampler`]: crate::on_policy::algorithm::Sampler
35//! [`TrajectoryBuffer`]: crate::buffers::buffer::TrajectoryBuffer
36//! [`TrajectoryView`]: crate::buffers::buffer::TrajectoryView
37//! [`ValueFunction`]: crate::models::ValueFunction
38
39/// Rollout transition and trajectory storage.
40pub mod buffers;
41/// Environment traits and space descriptions.
42pub mod env;
43/// Error types
44pub mod error;
45/// Actor, policy, value-function, and learner traits.
46pub mod models;
47/// Shared interfaces for on-policy training loops.
48pub mod on_policy;
49/// Reproducible random-number utilities.
50pub mod rng;
51/// Online mean and variance estimators.
52pub mod running_mean;
53/// Backend-neutral tensor interfaces and adapters.
54pub mod tensor;
55mod utils;
56
57pub use utils::actor_wrapper::ActorWrapper;
58
59/// Control-flow result returned by training hooks.
60///
61/// Hook implementations use this to signal whether the surrounding training
62/// loop should continue or stop at the current hook boundary.
63pub enum HookResult {
64    /// Continue the current training loop.
65    Continue,
66    /// Stop the current training loop at the current hook boundary.
67    Break,
68}
69
70#[macro_export]
71/// Breaks out of the surrounding loop when a hook requests [`HookResult::Break`].
72macro_rules! break_on_hook_result {
73    ($hook_res:expr) => {
74        match $hook_res {
75            $crate::HookResult::Continue => {}
76            $crate::HookResult::Break => break,
77        }
78    };
79}
80
81#[macro_export]
82/// Returns `Ok(())` from the surrounding function when a hook requests
83/// [`HookResult::Break`].
84macro_rules! return_on_hook_result {
85    ($hook_res:expr) => {
86        match $hook_res {
87            $crate::HookResult::Continue => {}
88            $crate::HookResult::Break => return Ok(()),
89        }
90    };
91}
92
93/// Common imports for implementing environments, policies, agents, samplers,
94/// and learners.
95pub mod prelude {
96    pub use crate::HookResult;
97    pub use crate::buffers::Memory;
98    pub use crate::env::{Env, EnvBuilder, EnvBuilderType, EnvDescription, Space};
99    pub use crate::models::{
100        ActivationFunction, Actor, Learner, Policy, ToSafetensors, ValueFunction,
101    };
102    pub use crate::on_policy::learning_module::OnPolicyLearner;
103    pub use crate::on_policy::losses::FromPolicyValueLosses;
104    pub use crate::tensor::{R2lTensor, VecTensor};
105}
r2l_core/lib.rs

r2l_core/
lib.rs
