rusttorch_core/lib.rs
1//! Tensors, automatic differentiation, device selection, and errors for RustTorch.
2//!
3//! Use this crate when you need tensor calculations without the higher-level
4//! model and data-loading APIs. Applications that train neural networks can
5//! instead use [`rusttorch`](https://docs.rs/rusttorch), which re-exports these
6//! types alongside its layers and optimizers.
7//!
8//! [`Tensor`] is backed by LibTorch and supports numerical operations, views,
9//! reductions, and gradient recording. Fallible methods use the `f_` prefix;
10//! their errors convert into the crate's [`Result`] type.
11//!
12//! # Calculate a gradient
13//!
14//! Mark leaf tensors as requiring gradients before constructing a calculation.
15//! Backpropagating a scalar result fills each leaf tensor's gradient.
16//!
17//! ```
18//! use rusttorch_core::{Kind, Result, Tensor};
19//!
20//! # fn main() -> Result<()> {
21//! let values = Tensor::f_from_slice(&[2_f32, 3.])?.set_requires_grad(true);
22//! let squared_sum = values.f_mul(&values)?.f_sum(Kind::Float)?;
23//! squared_sum.f_backward()?;
24//!
25//! let gradient = values.grad();
26//! assert_eq!(gradient.double_value(&[0]), 4.0);
27//! assert_eq!(gradient.double_value(&[1]), 6.0);
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! Use [`no_grad`] or [`no_grad_guard`] for calculations that do not need a
33//! gradient graph, such as prediction and manual parameter updates.
34//!
35//! # Select a compute device
36//!
37//! Keep tensors participating in an operation on the same device.
38//! [`DeviceSpec::Auto`] selects CUDA, then MPS, then CPU according to runtime
39//! availability. An explicit request returns an error if the device is not
40//! available; [`available_devices`] reports the usable backends.
41//!
42//! ```
43//! use rusttorch_core::{DeviceSpec, Kind, Result, Tensor, resolve_device};
44//!
45//! # fn main() -> Result<()> {
46//! let device = resolve_device(DeviceSpec::Cpu)?;
47//! let features = Tensor::f_zeros([8, 4], (Kind::Float, device))?;
48//! assert_eq!(features.device(), device);
49//! # Ok(())
50//! # }
51//! ```
52
53#![deny(missing_docs)]
54
55pub mod device;
56pub mod error;
57
58pub use device::{DeviceCapabilities, DeviceSpec, available_devices, resolve_device};
59pub use error::{Result, RustTorchError};
60pub use tch::{Device, Kind, Reduction, Tensor, no_grad, no_grad_guard};
61
62/// Seeds LibTorch's shared random generator before drawing tensors.
63///
64/// Use this to reproduce the order of draws on one runtime/device. Other threads
65/// share the generator, and matching seeds do not guarantee identical streams on
66/// different backends. Dataset samplers have their own explicit seed controls.
67///
68/// ```
69/// use rusttorch_core::{Device, Kind, Tensor, manual_seed};
70/// manual_seed(42);
71/// let first = Tensor::randn([3], (Kind::Float, Device::Cpu));
72/// manual_seed(42);
73/// let repeated = Tensor::randn([3], (Kind::Float, Device::Cpu));
74/// assert!(first.equal(&repeated));
75/// ```
76pub fn manual_seed(seed: i64) {
77 tch::manual_seed(seed);
78}