tenferro_scalar_consumer_algorithm/lib.rs
1//! The algorithm role of the external-scalar consumer.
2//!
3//! The algorithm states the capabilities it needs and never names a scalar, a provider,
4//! or a dtype-specific entry point. The application supplies the bindings, so the same
5//! source runs with canonical standard support and with an application-added scalar
6//! contribution.
7
8use tenferro_ad::AdContext;
9use tenferro_runtime::{Error, ErrorPhase, TracedTensor};
10
11/// The scalar and operation capabilities the algorithm requires from its binding.
12///
13/// A binding supplies a factorization of the supported scalar and a way to present a
14/// value of that scalar as an ordinary `f64` tensor, which is what the loss and its
15/// derivative are written against.
16///
17/// # Examples
18///
19/// ```rust
20/// # use tenferro_runtime::{TraceContext, Error, ErrorPhase, TracedTensor};
21/// # use tenferro_scalar_consumer_algorithm::{squared_factor_norm, ScalarSupport};
22/// struct Refusing;
23///
24/// impl ScalarSupport for Refusing {
25/// fn qr(&self, _input: &TracedTensor) -> Result<(TracedTensor, TracedTensor), Error> {
26/// Err(Error::runtime_state("Refusing::qr", ErrorPhase::GraphBuild, "unsupported"))
27/// }
28/// fn to_f64(&self, _input: &TracedTensor) -> Result<TracedTensor, Error> {
29/// Err(Error::runtime_state("Refusing::to_f64", ErrorPhase::GraphBuild, "unsupported"))
30/// }
31/// }
32///
33/// let trace = TraceContext::new();
34/// let input = trace.input_concrete_shape(tenferro_tensor::DType::F64, &[2, 1])?;
35/// // The factorization is the first capability the algorithm needs.
36/// assert!(squared_factor_norm(&input, &Refusing).is_err());
37/// # Ok::<(), Box<dyn std::error::Error>>(())
38/// ```
39pub trait ScalarSupport {
40 /// Factor a matrix into `(Q, R)`, where `R` has a positive diagonal.
41 ///
42 /// # Errors
43 ///
44 /// Returns the binding's error when the input's rank or shape is invalid, when the
45 /// input's dtype is unsupported, or when the matrix is not full column rank.
46 ///
47 /// # Examples
48 ///
49 /// ```rust
50 /// # use tenferro_runtime::{Error, ErrorPhase, TracedTensor};
51 /// # use tenferro_scalar_consumer_algorithm::ScalarSupport;
52 /// struct Identity;
53 ///
54 /// impl ScalarSupport for Identity {
55 /// fn qr(&self, input: &TracedTensor) -> Result<(TracedTensor, TracedTensor), Error> {
56 /// // A binding decides what a factorization means for its scalar.
57 /// Ok((input.clone(), input.clone()))
58 /// }
59 /// fn to_f64(&self, input: &TracedTensor) -> Result<TracedTensor, Error> {
60 /// Ok(input.clone())
61 /// }
62 /// }
63 ///
64 /// use tenferro_runtime::TraceContext;
65 /// let trace = TraceContext::new();
66 /// let input = trace.input_concrete_shape(tenferro_tensor::DType::F64, &[2, 1])?;
67 /// let (_q, r) = Identity.qr(&input)?;
68 /// assert_eq!(r.rank(), 2);
69 /// # Ok::<(), Box<dyn std::error::Error>>(())
70 /// ```
71 fn qr(&self, input: &TracedTensor) -> Result<(TracedTensor, TracedTensor), Error>;
72
73 /// Present a supported value as an ordinary `f64` tensor.
74 ///
75 /// # Errors
76 ///
77 /// Returns the binding's error when the value's dtype is unsupported or its shape is
78 /// invalid for the presentation the binding defines.
79 ///
80 /// # Examples
81 ///
82 /// ```rust
83 /// # use tenferro_runtime::{Error, TracedTensor};
84 /// # use tenferro_scalar_consumer_algorithm::ScalarSupport;
85 /// struct AlreadyF64;
86 ///
87 /// impl ScalarSupport for AlreadyF64 {
88 /// fn qr(&self, input: &TracedTensor) -> Result<(TracedTensor, TracedTensor), Error> {
89 /// Ok((input.clone(), input.clone()))
90 /// }
91 /// fn to_f64(&self, input: &TracedTensor) -> Result<TracedTensor, Error> {
92 /// // The supported scalar is already ordinary `f64`, so no conversion is needed.
93 /// Ok(input.clone())
94 /// }
95 /// }
96 ///
97 /// use tenferro_runtime::TraceContext;
98 /// let trace = TraceContext::new();
99 /// let input = trace.input_concrete_shape(tenferro_tensor::DType::F64, &[1])?;
100 /// assert_eq!(AlreadyF64.to_f64(&input)?.dtype(), tenferro_tensor::DType::F64);
101 /// # Ok::<(), Box<dyn std::error::Error>>(())
102 /// ```
103 fn to_f64(&self, input: &TracedTensor) -> Result<TracedTensor, Error>;
104}
105
106/// The loss the connected program minimizes: the squared norm of the triangular factor.
107///
108/// The loss is ordinary `f64` work, so only [`ScalarSupport::to_f64`] stands between the
109/// factorization's scalar and the objective.
110///
111/// # Examples
112///
113/// ```rust
114/// # use tenferro_runtime::{Error, TracedTensor};
115/// # use tenferro_scalar_consumer_algorithm::{squared_factor_norm, ScalarSupport};
116/// struct PassThrough;
117///
118/// impl ScalarSupport for PassThrough {
119/// fn qr(&self, input: &TracedTensor) -> Result<(TracedTensor, TracedTensor), Error> {
120/// Ok((input.clone(), input.clone()))
121/// }
122/// fn to_f64(&self, input: &TracedTensor) -> Result<TracedTensor, Error> {
123/// Ok(input.clone())
124/// }
125/// }
126///
127/// use tenferro_runtime::TraceContext;
128/// let trace = TraceContext::new();
129/// let input = trace.input_concrete_shape(tenferro_tensor::DType::F64, &[2, 2])?;
130/// // The loss is the squared norm of the factor the binding returned, as ordinary f64.
131/// let loss = squared_factor_norm(&input, &PassThrough)?;
132/// assert_eq!(loss.rank(), 0);
133/// # Ok::<(), Box<dyn std::error::Error>>(())
134/// ```
135///
136/// # Errors
137///
138/// Returns the binding's error when the factorisation or the presentation fails: an
139/// unsupported dtype, an invalid shape, or a matrix that is not full column rank.
140pub fn squared_factor_norm<S: ScalarSupport + ?Sized>(
141 input: &TracedTensor,
142 support: &S,
143) -> Result<TracedTensor, Error> {
144 let (_q, r) = support.qr(input)?;
145 let narrowed = support.to_f64(&r)?;
146 let squared = narrowed.mul(&narrowed)?;
147 squared.reduce_sum(None)
148}
149
150/// The objective's gradient with respect to the program input.
151///
152/// # Examples
153///
154/// ```rust
155/// # use tenferro_runtime::{Error, ErrorPhase, TracedTensor};
156/// # use tenferro_scalar_consumer_algorithm::{factor_norm_gradient, ScalarSupport};
157/// struct Refusing;
158///
159/// impl ScalarSupport for Refusing {
160/// fn qr(&self, _input: &TracedTensor) -> Result<(TracedTensor, TracedTensor), Error> {
161/// Err(Error::runtime_state("Refusing::qr", ErrorPhase::GraphBuild, "unsupported"))
162/// }
163/// fn to_f64(&self, _input: &TracedTensor) -> Result<TracedTensor, Error> {
164/// Err(Error::runtime_state("Refusing::to_f64", ErrorPhase::GraphBuild, "unsupported"))
165/// }
166/// }
167///
168/// let ad = tenferro_ad::AdContext::builder().build()?;
169/// use tenferro_runtime::TraceContext;
170/// let trace = TraceContext::new();
171/// let input = trace.input_concrete_shape(tenferro_tensor::DType::F64, &[2, 1])?;
172/// let seed = trace.input_concrete_shape(tenferro_tensor::DType::F64, &[])?;
173/// // A binding that cannot factor stops the program before the reverse pass.
174/// assert!(factor_norm_gradient(&ad, &input, &seed, &Refusing).is_err());
175/// # Ok::<(), Box<dyn std::error::Error>>(())
176/// ```
177///
178/// # Errors
179///
180/// Returns the binding's error when the factorisation or the presentation fails with an
181/// unsupported dtype or an invalid shape, [`Error::RuntimeStateSource`] when the input does
182/// not reach the loss, or the reverse pass error when the program cannot be built.
183pub fn factor_norm_gradient<S: ScalarSupport + ?Sized>(
184 ad: &AdContext,
185 input: &TracedTensor,
186 seed: &TracedTensor,
187 support: &S,
188) -> Result<TracedTensor, Error> {
189 let loss = squared_factor_norm(input, support)?;
190 let gradients = ad.vjp_many(&loss, &[input], seed)?;
191 gradients.into_iter().next().flatten().ok_or_else(|| {
192 Error::runtime_state(
193 "factor_norm_gradient",
194 ErrorPhase::GraphBuild,
195 "the input is inactive",
196 )
197 })
198}
199
200#[cfg(test)]
201mod tests;