Skip to main content

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;