Skip to main content

tensor4all_tensorbackend/
explicit.rs

1//! Opt-in explicit/concrete execution frontend.
2//!
3//! This is the second, opt-in frontend of
4//! [tensor4all-rs#859](https://github.com/tensor4all/tensor4all-rs/issues/859): a
5//! caller-supplied [`CpuExecutionContext`] plus one concrete session that a whole
6//! stage or batch reuses, instead of the process-global convenience surface in
7//! the compatibility entry point. The compatibility frontend keeps its own signatures,
8//! defaults and behaviour; nothing here reroutes it.
9//!
10//! Properties of this frontend, from the coexistence record
11//! (`docs/design/859-dual-frontend-coexistence.md`):
12//!
13//! - **One explicit entry.** [`CpuExecutionContext::with_concrete_session`] lends the
14//!   context's engine for the whole closure, so a stage borrows it once rather than once
15//!   per operation, and the engine's prepared plans and buffer pool stay warm.
16//! - **No process-global selector.** No route here selects an execution context or
17//!   backend from a default context, a thread-local override or an environment
18//!   variable. (Upstream profiling hooks may still read their own environment flags;
19//!   those do not choose where the work runs.)
20//! - **No eager, trace or AD records.** These routes reach only concrete
21//!   `Tensor`/engine operations; they never construct `EagerTensor`,
22//!   semantic nodes or gradient slots, and they take no eager owner lock. Tracked
23//!   values are not accepted at all, so no detach can happen implicitly.
24//! - **No implicit fallback.** An unsupported dtype or shape returns the
25//!   backend's typed error. Nothing here retries on the global or CPU-eager route.
26//! - **Explicit conversion at the boundary.** Crossing between this frontend and
27//!   the compatibility frontend is [`LogicalTensor`](crate::LogicalTensor), which
28//!   carries dtype, shape and column-major data and no backend identity.
29//!
30//! The session is a borrow of one [`tenferro_cpu::CpuEngine`], not a value
31//! representation: the concrete values stay the ordinary tenferro tensors.
32//!
33//! # Examples
34//!
35//! ```
36//! use tensor4all_tensorbackend::{CpuExecutionContext, explicit::Session};
37//! use tenferro::Tensor;
38//! use tensor4all_tensorbackend::CpuBackend;
39//!
40//! let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
41//! let x = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
42//!
43//! let product = context.with_concrete_session(|session: &mut Session<'_>| {
44//!     session.qr(&x).map(|(q, _r)| q)
45//! })?;
46//! assert_eq!(product.expect("QR succeeds").shape(), &[2, 2]);
47//! # Ok::<(), Box<dyn std::error::Error>>(())
48//! ```
49
50use tenferro::Tensor as NativeTensor;
51use tenferro::TensorSessionOpsExt;
52use tenferro_einsum::{ConcreteEinsumPlan, EinsumSubscripts, TensorEinsumExt};
53use tenferro_linalg::TensorLinalgExt;
54
55use tenferro_tensor::{DotGeneralConfig, Engine, TensorRead};
56
57use crate::context::{CpuExecutionContext, CpuExecutionContextError};
58use crate::einsum_ids::{
59    build_binary_einsum_ids, checked_native_einsum_labels, common_dtype, convert_native_tensor_in,
60};
61
62/// One explicit concrete session over a caller-held CPU engine.
63///
64/// The session borrows an engine for the whole of its life. Inside
65/// [`CpuExecutionContext::with_concrete_session`] that is the context's engine,
66/// borrowed for the closure; a caller that owns an engine ([`crate::CpuBackend`])
67/// builds the same session with [`Session::new`] and keeps it across as many
68/// operations as it wants. Every route on it runs through that one engine, so a
69/// stage does not pay an entry per operation.
70///
71/// # Examples
72///
73/// ```
74/// use tensor4all_tensorbackend::CpuExecutionContext;
75/// use tenferro::Tensor;
76/// use tensor4all_tensorbackend::CpuBackend;
77///
78/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
79/// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
80/// let b = Tensor::from_vec_col_major(vec![2, 2], vec![0.0_f64, 1.0, 1.0, 0.0])?;
81/// let (ab, a_again) = context.with_concrete_session(
82///     |session| -> Result<_, Box<dyn std::error::Error + Send + Sync>> {
83///         let ab = session.contraction(&a, &[1], &b, &[0])?;
84///         // One session, two operations.
85///         let a_again = session.permute(&a, &[1, 0])?;
86///         Ok((ab, a_again))
87///     },
88/// )??;
89/// // `a` is `[[1, 3], [2, 4]]` column-major and `b` swaps the axes, so `a * b`
90/// // is `[[3, 1], [4, 2]]`.
91/// assert_eq!(ab.as_slice::<f64>()?, &[3.0, 4.0, 1.0, 2.0]);
92/// assert_eq!(a_again.as_slice::<f64>()?, &[1.0, 3.0, 2.0, 4.0]);
93/// # Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
94/// ```
95pub struct Session<'session> {
96    engine: &'session mut dyn Engine,
97}
98
99impl std::fmt::Debug for Session<'_> {
100    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
101        formatter
102            .debug_struct("explicit::Session")
103            .finish_non_exhaustive()
104    }
105}
106
107/// Failure reported by this frontend's compatibility bridges.
108///
109/// The original tenferro or tenferro-ad diagnostic is retained as the source.
110#[derive(Debug, thiserror::Error)]
111pub enum ConversionError {
112    /// Materializing a tracked value into a plain concrete value failed.
113    #[error("materializing a tracked value failed: {source}")]
114    Detach {
115        /// Original tenferro diagnostic.
116        #[source]
117        source: Box<dyn std::error::Error + Send + Sync + 'static>,
118    },
119    /// Adopting a plain concrete value into an eager runtime failed.
120    #[error("adopting a concrete value failed: {source}")]
121    Lift {
122        /// Original tenferro or tenferro-ad diagnostic.
123        #[source]
124        source: Box<dyn std::error::Error + Send + Sync + 'static>,
125    },
126}
127
128/// Materialize a tracked eager value into a plain concrete value on `engine`.
129///
130/// This is the explicit AD to plain boundary of the coexistence contract: the caller names
131/// the conversion, so tracking never disappears silently, and `no_grad` on an eager value is
132/// not this operation and does not select the concrete representation. The value keeps its
133/// dtype, logical shape and column-major layout; the result is an ordinary concrete tensor
134/// that this frontend's routes accept. Materializing a lazy or prepared value needs an
135/// engine to evaluate it, so the caller passes the one it wants the copy to run on.
136///
137/// # Errors
138///
139/// Returns [`ConversionError::Detach`] when the tracked value cannot be materialized, for
140/// example because it is a lazy or prepared value that has not been evaluated.
141///
142/// # Examples
143///
144/// ```
145/// use tensor4all_tensorbackend::{explicit, CpuExecutionContext};
146/// use tenferro::Tensor;
147/// use tenferro_ad::EagerTensor;
148/// use tensor4all_tensorbackend::CpuBackend;
149///
150/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
151/// let plain = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
152/// let tracked = explicit::lift(&context, plain)?;
153/// let back = context.with_backend(|backend| explicit::detach(&tracked, backend.engine_mut()))?;
154/// assert_eq!(back.as_slice::<f64>()?, &[1.0, 2.0]);
155/// # Ok::<(), Box<dyn std::error::Error>>(())
156/// ```
157pub fn detach(
158    eager: &tenferro_ad::EagerTensor,
159    engine: &mut dyn Engine,
160) -> Result<NativeTensor, ConversionError> {
161    eager
162        .to_tensor(engine)
163        .map_err(|source| ConversionError::Detach {
164            source: Box::new(source),
165        })
166}
167
168/// Adopt a plain concrete value into `context`'s eager runtime.
169///
170/// This is the explicit plain to AD boundary: the result is a tracked value in a graph owned
171/// by `context`'s own eager runtime, and nothing about it is inferred from the caller's
172/// ambient `no_grad` or capture state. The value is moved into the runtime, because a
173/// concrete tensor has one owner. Use [`detach`] for the opposite direction.
174///
175/// # Errors
176///
177/// Returns [`ConversionError::Lift`] when the context's eager runtime cannot be initialized
178/// or when the value cannot be adopted, for example because it is not a concrete host value.
179///
180/// # Examples
181///
182/// ```
183/// use tensor4all_tensorbackend::{explicit, CpuExecutionContext};
184/// use tenferro::Tensor;
185/// use tensor4all_tensorbackend::CpuBackend;
186///
187/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
188/// let plain = Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0])?;
189/// let tracked = explicit::lift(&context, plain)?;
190/// // The adopted value is tracked, and its runtime is the context's own.
191/// let back = context.with_backend(|backend| explicit::detach(&tracked, backend.engine_mut()))?;
192/// assert_eq!(back.as_slice::<f64>()?, &[3.0, 4.0]);
193/// # Ok::<(), Box<dyn std::error::Error>>(())
194/// ```
195pub fn lift(
196    context: &CpuExecutionContext,
197    tensor: NativeTensor,
198) -> Result<tenferro_ad::EagerTensor, ConversionError> {
199    let runtime = context
200        .eager_runtime()
201        .map_err(|source| ConversionError::Lift {
202            source: Box::new(source),
203        })?;
204    tenferro_ad::EagerTensor::from_tensor_in(tensor, runtime).map_err(|source| {
205        ConversionError::Lift {
206            source: Box::new(source),
207        }
208    })
209}
210
211/// One prepared N-ary einsum, reusable across operations of a session.
212///
213/// Preparing validates the labels and plans the contraction once; every
214/// [`PreparedEinsum::execute`] and [`PreparedEinsum::execute_into`] reuses that plan, so
215/// a stage keeps one plan across as many evaluations as it needs instead of preparing
216/// per call. The plan borrows its operands, so it cannot outlive them, and it holds no
217/// execution state: the session stays the caller's.
218///
219/// # Examples
220///
221/// ```
222/// use tensor4all_tensorbackend::{explicit::PreparedEinsum, CpuExecutionContext};
223/// use tenferro::Tensor;
224/// use tensor4all_tensorbackend::CpuBackend;
225/// use tenferro_tensor::{TensorRead, TensorWrite};
226///
227/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
228/// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
229/// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
230/// let reads = [TensorRead::from_tensor(&a), TensorRead::from_tensor(&b)];
231/// let plan = PreparedEinsum::prepare(&reads, &[&[0, 1], &[1, 2]], &[0, 2])?;
232///
233/// // Reused across a stage, including into a caller-provided destination.
234/// let mut out = Tensor::from_vec_col_major(vec![2, 1], vec![0.0_f64, 0.0])?;
235/// context.with_concrete_session(|session| -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
236///     let product = plan.execute(session)?;
237///     assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
238///     plan.execute_into(session, TensorWrite::Tensor(&mut out))?;
239///     Ok(())
240/// })??;
241/// assert_eq!(out.as_slice::<f64>()?, &[23.0, 34.0]);
242/// # Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
243/// ```
244pub struct PreparedEinsum<'operands> {
245    plan: ConcreteEinsumPlan,
246    operands: Vec<tenferro_tensor::TensorRead<'operands>>,
247}
248
249impl std::fmt::Debug for PreparedEinsum<'_> {
250    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
251        formatter
252            .debug_struct("explicit::PreparedEinsum")
253            .field("operands", &self.operands.len())
254            .finish_non_exhaustive()
255    }
256}
257
258impl<'operands> PreparedEinsum<'operands> {
259    /// Plan an N-ary einsum over borrowed operands.
260    ///
261    /// # Errors
262    ///
263    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] for malformed labels, a
264    /// label list whose length does not match the operand's rank, or a label-list count
265    /// that does not match the operand count, and [`tenferro_einsum::Error`] from the
266    /// contraction planner when the expression cannot be planned.
267    pub fn prepare(
268        operands: &[tenferro_tensor::TensorRead<'operands>],
269        input_ids: &[&[usize]],
270        output_ids: &[usize],
271    ) -> tenferro_einsum::Result<Self> {
272        if operands.len() != input_ids.len() {
273            return Err(tenferro_einsum::Error::InvalidSubscripts {
274                message: format!(
275                    "einsum needs one label list per operand: {} operands, {} label lists",
276                    operands.len(),
277                    input_ids.len()
278                ),
279            });
280        }
281        let invalid = |error: anyhow::Error| tenferro_einsum::Error::InvalidSubscripts {
282            message: format!("{error}"),
283        };
284        let inputs = input_ids
285            .iter()
286            .map(|ids| checked_native_einsum_labels(ids))
287            .collect::<anyhow::Result<Vec<_>>>()
288            .map_err(invalid)?;
289        let output = checked_native_einsum_labels(output_ids).map_err(invalid)?;
290        let subscripts = EinsumSubscripts { inputs, output };
291        let plan = ConcreteEinsumPlan::prepare_read_subscripts(operands, &subscripts)?;
292        Ok(Self {
293            plan,
294            operands: operands.to_vec(),
295        })
296    }
297
298    /// Evaluate the prepared plan on `session`, allocating the result.
299    ///
300    /// # Errors
301    ///
302    /// Returns [`tenferro_einsum::Error::Tensor`] when the session rejects the operands
303    /// or the contraction itself fails, and
304    /// [`tenferro_einsum::Error::Validation`] when the operands no longer match the
305    /// planned expression.
306    pub fn execute(&self, session: &mut Session<'_>) -> tenferro_einsum::Result<NativeTensor> {
307        self.plan
308            .execute_read(self.operands.as_slice(), session.engine())
309    }
310
311    /// Evaluate the prepared plan into a caller-provided destination.
312    ///
313    /// The destination is fully written and is never zero-filled first. Operands and
314    /// destination must already share one dtype; this route does not convert into a
315    /// caller-owned output.
316    ///
317    /// # Errors
318    ///
319    /// Returns [`tenferro_einsum::Error::Tensor`] when the session rejects the operands,
320    /// the destination or the contraction, and
321    /// [`tenferro_einsum::Error::Validation`] when the operands no longer match the
322    /// planned expression.
323    pub fn execute_into(
324        &self,
325        session: &mut Session<'_>,
326        out: tenferro_tensor::TensorWrite<'_>,
327    ) -> tenferro_einsum::Result<()> {
328        self.plan
329            .execute_read_into(self.operands.as_slice(), session.engine(), out)
330    }
331}
332
333/// Promote a heterogeneous operand set to the dtype both frontends contract in.
334///
335/// Returns an empty vector when every operand already has the common dtype, so the
336/// common case allocates nothing.
337///
338/// # Errors
339///
340/// Returns [`tenferro_einsum::Error::Tensor`] when an operand cannot be converted.
341fn promote_operands(
342    engine: &mut dyn Engine,
343    operands: &[&NativeTensor],
344) -> tenferro_einsum::Result<Vec<NativeTensor>> {
345    let dtypes = operands
346        .iter()
347        .map(|tensor| tensor.dtype())
348        .collect::<Vec<_>>();
349    let target = common_dtype(&dtypes);
350    if operands.iter().all(|tensor| tensor.dtype() == target) {
351        return Ok(Vec::new());
352    }
353    operands
354        .iter()
355        .map(|tensor| {
356            convert_native_tensor_in(engine, tensor, target).map_err(tenferro_einsum::Error::Tensor)
357        })
358        .collect()
359}
360
361impl<'session> Session<'session> {
362    /// Wrap a borrowed engine as this frontend's session.
363    ///
364    /// A caller that owns an engine - a [`crate::CpuBackend`], an engine it built
365    /// itself, or one borrowed for a stage - builds the same [`Session`] the
366    /// callback-scoped [`CpuExecutionContext::with_concrete_session`] hands out, so a
367    /// long stage can keep one session across many operations without entering a
368    /// context. The engine stays borrowed for the whole life of the returned session:
369    /// this constructor never enters, replaces or reroutes an engine.
370    ///
371    /// # Examples
372    ///
373    /// ```
374    /// use tensor4all_tensorbackend::{explicit::Session, CpuBackend};
375    /// use tenferro::Tensor;
376    ///
377    /// let mut backend = CpuBackend::with_threads(1)?;
378    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
379    ///
380    /// let mut session = Session::new(backend.engine_mut());
381    /// // One session, two operations.
382    /// let transposed = session.permute(&a, &[1, 0])?;
383    /// let total = session.sum(&transposed)?;
384    /// assert_eq!(total.as_slice::<f64>()?, &[10.0]);
385    /// # Ok::<(), Box<dyn std::error::Error>>(())
386    /// ```
387    pub fn new(engine: &'session mut dyn Engine) -> Self {
388        Self { engine }
389    }
390
391    /// The engine behind this explicit session.
392    ///
393    /// Exposed so a prepared plan can evaluate itself on the caller's engine; it is
394    /// not a second entry point, and it never consults another backend.
395    pub fn engine(&mut self) -> &mut dyn Engine {
396        self.engine
397    }
398
399    /// Reshape a concrete tensor without changing its column-major linearization.
400    ///
401    /// # Errors
402    ///
403    /// Returns [`tenferro_tensor::Error::Validation`] when the element counts
404    /// differ or the requested layout is invalid,
405    /// [`tenferro_tensor::Error::UnsupportedDType`] for a dtype the backend cannot
406    /// reshape, and [`tenferro_tensor::Error::BackendSource`] when the operation
407    /// itself fails. It never retries on another route.
408    ///
409    /// # Examples
410    ///
411    /// ```
412    /// use tensor4all_tensorbackend::CpuExecutionContext;
413    /// use tenferro::Tensor;
414    /// use tensor4all_tensorbackend::CpuBackend;
415    ///
416    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
417    /// let x = Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?;
418    /// let reshaped = context.with_concrete_session(|session| session.reshape(&x, &[2, 2]))??;
419    /// assert_eq!(reshaped.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);
420    /// # Ok::<(), Box<dyn std::error::Error>>(())
421    /// ```
422    pub fn reshape(
423        &mut self,
424        tensor: &NativeTensor,
425        shape: &[usize],
426    ) -> tenferro_tensor::Result<NativeTensor> {
427        tensor.reshape(shape, self.engine)
428    }
429
430    /// Permute the axes of a concrete tensor.
431    ///
432    /// # Errors
433    ///
434    /// Returns [`tenferro_tensor::Error::Validation`] when `perm` is not a
435    /// permutation of the tensor's axes, and
436    /// [`tenferro_tensor::Error::BackendSource`] when the operation itself fails.
437    ///
438    /// # Examples
439    ///
440    /// ```
441    /// use tensor4all_tensorbackend::CpuExecutionContext;
442    /// use tenferro::Tensor;
443    /// use tensor4all_tensorbackend::CpuBackend;
444    ///
445    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
446    /// let x = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
447    /// let transposed = context.with_concrete_session(|session| session.permute(&x, &[1, 0]))??;
448    /// assert_eq!(transposed.as_slice::<f64>()?, &[1.0, 3.0, 2.0, 4.0]);
449    /// # Ok::<(), Box<dyn std::error::Error>>(())
450    /// ```
451    pub fn permute(
452        &mut self,
453        tensor: &NativeTensor,
454        perm: &[usize],
455    ) -> tenferro_tensor::Result<NativeTensor> {
456        tensor.transpose(perm, self.engine)
457    }
458
459    /// Binary contraction along the given axes, preserving the remaining axes in
460    /// order.
461    ///
462    /// The operand identity and axis building is the same code path the
463    /// compatibility frontend uses, so both frontends contract identically; only
464    /// the session differs.
465    ///
466    /// # Errors
467    ///
468    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] when the axis lists are
469    /// malformed or of different length, and [`tenferro_einsum::Error::Tensor`] when the
470    /// backend rejects the operands, when an operand cannot be promoted, or when the
471    /// contraction itself fails.
472    ///
473    /// Operands are promoted to a common dtype exactly as the compatibility frontend
474    /// promotes them: a heterogeneous set contracts in the promoted dtype, and a set
475    /// that already shares one dtype is used as is.
476    ///
477    /// Operands that share a dtype (the common case) are contracted by a single
478    /// `dot_general` call on the engine, the same kernel and plan cache the global
479    /// route uses, without planning an einsum; only a dtype mismatch, which needs
480    /// promotion first, goes through the einsum route. Neither route conjugates.
481    ///
482    /// # Examples
483    ///
484    /// ```
485    /// use tensor4all_tensorbackend::CpuExecutionContext;
486    /// use tenferro::Tensor;
487    /// use tensor4all_tensorbackend::CpuBackend;
488    ///
489    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
490    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
491    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
492    /// let product =
493    ///     context.with_concrete_session(|session| session.contraction(&a, &[1], &b, &[0]))??;
494    /// assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
495    /// # Ok::<(), Box<dyn std::error::Error>>(())
496    /// ```
497    pub fn contraction(
498        &mut self,
499        lhs: &NativeTensor,
500        lhs_axes: &[usize],
501        rhs: &NativeTensor,
502        rhs_axes: &[usize],
503    ) -> tenferro_einsum::Result<NativeTensor> {
504        if lhs.dtype() == rhs.dtype() {
505            return self.contraction_reads(
506                TensorRead::from_tensor(lhs),
507                lhs_axes,
508                TensorRead::from_tensor(rhs),
509                rhs_axes,
510            );
511        }
512        let (lhs_ids, rhs_ids, output_ids) =
513            build_binary_einsum_ids(lhs.shape().len(), lhs_axes, rhs.shape().len(), rhs_axes)
514                .map_err(|error| tenferro_einsum::Error::InvalidSubscripts {
515                    message: format!("{error}"),
516                })?;
517        let subscripts = EinsumSubscripts {
518            inputs: vec![lhs_ids, rhs_ids],
519            output: output_ids,
520        };
521        let operands = [lhs, rhs];
522        let promoted = promote_operands(self.engine, &operands)?;
523        let operands = if promoted.is_empty() {
524            operands.to_vec()
525        } else {
526            promoted.iter().collect::<Vec<_>>()
527        };
528        operands.einsum_subscripts(&subscripts, self.engine)
529    }
530
531    /// Binary contraction of two borrowed reads that share a dtype, as one `dot_general`.
532    ///
533    /// Same axis semantics and output order as [`Session::contraction`] (the left
534    /// operand's free axes, then the right operand's), but the operands stay
535    /// borrowed, so a caller holding a non-owned read does not copy it first. Nothing
536    /// is conjugated.
537    ///
538    /// # Errors
539    ///
540    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] when the axis lists are
541    /// malformed or of different length, and [`tenferro_einsum::Error::Tensor`] when the
542    /// operands' dtypes differ (this route does not promote; use
543    /// [`Session::contraction`]) or the backend rejects the contraction.
544    ///
545    /// # Examples
546    ///
547    /// ```
548    /// use tensor4all_tensorbackend::CpuExecutionContext;
549    /// use tenferro::Tensor;
550    /// use tensor4all_tensorbackend::CpuBackend;
551    /// use tenferro_tensor::TensorRead;
552    ///
553    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
554    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
555    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
556    /// let product = context.with_concrete_session(|session| {
557    ///     session.contraction_reads(
558    ///         TensorRead::from_tensor(&a),
559    ///         &[1],
560    ///         TensorRead::from_tensor(&b),
561    ///         &[0],
562    ///     )
563    /// })??;
564    /// assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
565    /// # Ok::<(), Box<dyn std::error::Error>>(())
566    /// ```
567    pub fn contraction_reads(
568        &mut self,
569        lhs: TensorRead<'_>,
570        lhs_axes: &[usize],
571        rhs: TensorRead<'_>,
572        rhs_axes: &[usize],
573    ) -> tenferro_einsum::Result<NativeTensor> {
574        // The axis validation is the einsum route's own, so both routes refuse the
575        // same malformed input.
576        build_binary_einsum_ids(lhs.shape().len(), lhs_axes, rhs.shape().len(), rhs_axes).map_err(
577            |error| tenferro_einsum::Error::InvalidSubscripts {
578                message: format!("{error}"),
579            },
580        )?;
581        let config = DotGeneralConfig {
582            lhs_contracting_dims: lhs_axes.into(),
583            rhs_contracting_dims: rhs_axes.into(),
584            lhs_batch_dims: Default::default(),
585            rhs_batch_dims: Default::default(),
586        };
587        self.engine
588            .dot_general_read(lhs, rhs, &config)
589            .map_err(tenferro_einsum::Error::from)
590    }
591
592    /// N-ary einsum from integer labels, evaluated on this session.
593    ///
594    /// The labels are validated by the same helper the compatibility frontend
595    /// uses; the evaluation is tenferro-einsum's session-direct einsum, so it does
596    /// not compile a semantic graph or start a runtime worker.
597    ///
598    /// # Errors
599    ///
600    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] for malformed labels, a
601    /// label list whose length does not match the operand's rank, or a label-list
602    /// count that does not match the operand count, and
603    /// [`tenferro_einsum::Error::Tensor`] when the backend rejects the operands, when an
604    /// operand cannot be promoted, or when the contraction itself fails.
605    ///
606    /// Operands are promoted to a common dtype exactly as the compatibility frontend
607    /// promotes them: a heterogeneous set contracts in the promoted dtype, and a set
608    /// that already shares one dtype is used as is.
609    ///
610    /// # Examples
611    ///
612    /// ```
613    /// use tensor4all_tensorbackend::CpuExecutionContext;
614    /// use tenferro::Tensor;
615    /// use tensor4all_tensorbackend::CpuBackend;
616    ///
617    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
618    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
619    /// let b = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 0.0, 0.0, 1.0])?;
620    /// let product = context.with_concrete_session(|session| {
621    ///     session.einsum(&[&a, &b], &[&[0, 1], &[1, 2]], &[0, 2])
622    /// })??;
623    /// assert_eq!(product.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);
624    /// # Ok::<(), Box<dyn std::error::Error>>(())
625    /// ```
626    pub fn einsum(
627        &mut self,
628        operands: &[&NativeTensor],
629        input_ids: &[&[usize]],
630        output_ids: &[usize],
631    ) -> tenferro_einsum::Result<NativeTensor> {
632        if operands.len() != input_ids.len() {
633            return Err(tenferro_einsum::Error::InvalidSubscripts {
634                message: format!(
635                    "einsum needs one label list per operand: {} operands, {} label lists",
636                    operands.len(),
637                    input_ids.len()
638                ),
639            });
640        }
641        let inputs = input_ids
642            .iter()
643            .map(|ids| checked_native_einsum_labels(ids))
644            .collect::<anyhow::Result<Vec<_>>>()
645            .map_err(|error| tenferro_einsum::Error::InvalidSubscripts {
646                message: format!("{error}"),
647            })?;
648        let subscripts = EinsumSubscripts {
649            inputs,
650            output: checked_native_einsum_labels(output_ids).map_err(|error| {
651                tenferro_einsum::Error::InvalidSubscripts {
652                    message: format!("{error}"),
653                }
654            })?,
655        };
656        let promoted = promote_operands(self.engine, operands)?;
657        let operands: Vec<&NativeTensor> = if promoted.is_empty() {
658            operands.to_vec()
659        } else {
660            promoted.iter().collect()
661        };
662        operands.einsum_subscripts(&subscripts, self.engine)
663    }
664
665    /// Sum every element of a concrete tensor, returning the rank-0 result.
666    ///
667    /// The compatibility frontend wraps the same rank-0 tensor in a
668    /// `BackendScalar`; this route stays on the concrete value so it works without
669    /// the compatibility feature.
670    ///
671    /// # Errors
672    ///
673    /// Returns [`tenferro_tensor::Error::Validation`] for an unsupported reduction
674    /// shape and [`tenferro_tensor::Error::BackendSource`] when the reduction itself
675    /// fails.
676    ///
677    /// # Examples
678    ///
679    /// ```
680    /// use tensor4all_tensorbackend::CpuExecutionContext;
681    /// use tenferro::Tensor;
682    /// use tensor4all_tensorbackend::CpuBackend;
683    ///
684    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
685    /// let x = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
686    /// let total = context.with_concrete_session(|session| session.sum(&x))??;
687    /// assert_eq!(total.shape(), &[] as &[usize]);
688    /// assert_eq!(total.as_slice::<f64>()?, &[10.0]);
689    /// # Ok::<(), Box<dyn std::error::Error>>(())
690    /// ```
691    pub fn sum(&mut self, tensor: &NativeTensor) -> tenferro_tensor::Result<NativeTensor> {
692        if tensor.shape().is_empty() {
693            return tensor.duplicate();
694        }
695        let axes = (0..tensor.shape().len()).collect::<Vec<_>>();
696        tensor.reduce_sum(Some(&axes), self.engine)
697    }
698
699    /// Conjugate a concrete tensor.
700    ///
701    /// A real tensor is returned unchanged; a complex tensor is conjugated
702    /// elementwise.
703    ///
704    /// # Errors
705    ///
706    /// Returns [`tenferro_tensor::Error::Unsupported`] for a dtype the backend cannot
707    /// conjugate and [`tenferro_tensor::Error::BackendSource`] when the operation
708    /// itself fails.
709    ///
710    /// # Examples
711    ///
712    /// ```
713    /// use tensor4all_tensorbackend::CpuExecutionContext;
714    /// use tenferro::Tensor;
715    /// use tensor4all_tensorbackend::CpuBackend;
716    /// use num_complex::Complex64;
717    ///
718    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
719    /// let x = Tensor::from_vec_col_major(
720    ///     vec![2],
721    ///     vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, -4.0)],
722    /// )?;
723    /// let conjugated = context.with_concrete_session(|session| session.conj(&x))??;
724    /// assert_eq!(
725    ///     conjugated.as_slice::<Complex64>()?,
726    ///     &[Complex64::new(1.0, -2.0), Complex64::new(3.0, 4.0)]
727    /// );
728    /// # Ok::<(), Box<dyn std::error::Error>>(())
729    /// ```
730    pub fn conj(&mut self, tensor: &NativeTensor) -> tenferro_tensor::Result<NativeTensor> {
731        tensor.conj(self.engine)
732    }
733
734    /// N-ary einsum over borrowed read inputs, without materializing them.
735    ///
736    /// Same contract as [`Session::einsum`], except that the operands are
737    /// [`TensorRead`](tenferro_tensor::TensorRead) views: a non-contiguous or lazily
738    /// represented operand stays borrowed until the contract evaluates it.
739    ///
740    /// # Errors
741    ///
742    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] for malformed labels or a
743    /// label list whose length does not match the operand's rank, and
744    /// [`tenferro_einsum::Error::Tensor`] when the backend rejects the operands or the
745    /// contraction itself fails.
746    ///
747    /// # Examples
748    ///
749    /// ```
750    /// use tensor4all_tensorbackend::CpuExecutionContext;
751    /// use tenferro::Tensor;
752    /// use tensor4all_tensorbackend::CpuBackend;
753    /// use tenferro_tensor::TensorRead;
754    ///
755    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
756    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
757    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
758    /// let reads = [TensorRead::from_tensor(&a), TensorRead::from_tensor(&b)];
759    /// let product = context
760    ///     .with_concrete_session(|session| session.einsum_reads(&reads, &[&[0, 1], &[1, 2]], &[0, 2]))??;
761    /// assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
762    /// # Ok::<(), Box<dyn std::error::Error>>(())
763    /// ```
764    pub fn einsum_reads(
765        &mut self,
766        operands: &[tenferro_tensor::TensorRead<'_>],
767        input_ids: &[&[usize]],
768        output_ids: &[usize],
769    ) -> tenferro_einsum::Result<NativeTensor> {
770        if operands.len() != input_ids.len() {
771            return Err(tenferro_einsum::Error::InvalidSubscripts {
772                message: format!(
773                    "einsum needs one label list per operand: {} operands, {} label lists",
774                    operands.len(),
775                    input_ids.len()
776                ),
777            });
778        }
779        let invalid = |error: anyhow::Error| tenferro_einsum::Error::InvalidSubscripts {
780            message: format!("{error}"),
781        };
782        let inputs = input_ids
783            .iter()
784            .map(|ids| checked_native_einsum_labels(ids))
785            .collect::<anyhow::Result<Vec<_>>>()
786            .map_err(invalid)?;
787        let output = checked_native_einsum_labels(output_ids).map_err(invalid)?;
788        let subscripts = EinsumSubscripts { inputs, output };
789        let plan = ConcreteEinsumPlan::prepare_read_subscripts(operands, &subscripts)?;
790        plan.execute_read(operands, self.engine)
791    }
792
793    /// Binary contraction into a caller-provided destination.
794    ///
795    /// The destination is fully written and is never zero-filled first. The operands
796    /// and the destination must already share one dtype: this route does not convert
797    /// into a caller-owned output, and a mismatch is rejected typed by the backend.
798    ///
799    /// # Errors
800    ///
801    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] when the axis lists are
802    /// malformed or of different length, and [`tenferro_einsum::Error::Tensor`] when the
803    /// backend rejects the operands, the destination or the contraction.
804    ///
805    /// # Examples
806    ///
807    /// ```
808    /// use tensor4all_tensorbackend::CpuExecutionContext;
809    /// use tenferro::Tensor;
810    /// use tensor4all_tensorbackend::CpuBackend;
811    /// use tenferro_tensor::TensorWrite;
812    ///
813    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
814    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
815    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
816    /// let mut out = Tensor::from_vec_col_major(vec![2, 1], vec![0.0_f64, 0.0])?;
817    /// context.with_concrete_session(|session| {
818    ///     session.contraction_into(&a, &[1], &b, &[0], TensorWrite::Tensor(&mut out))
819    /// })??;
820    /// assert_eq!(out.as_slice::<f64>()?, &[23.0, 34.0]);
821    /// # Ok::<(), Box<dyn std::error::Error>>(())
822    /// ```
823    pub fn contraction_into(
824        &mut self,
825        lhs: &NativeTensor,
826        lhs_axes: &[usize],
827        rhs: &NativeTensor,
828        rhs_axes: &[usize],
829        out: tenferro_tensor::TensorWrite<'_>,
830    ) -> tenferro_einsum::Result<()> {
831        let (lhs_ids, rhs_ids, output_ids) =
832            build_binary_einsum_ids(lhs.shape().len(), lhs_axes, rhs.shape().len(), rhs_axes)
833                .map_err(|error| tenferro_einsum::Error::InvalidSubscripts {
834                    message: format!("{error}"),
835                })?;
836        let subscripts = EinsumSubscripts {
837            inputs: vec![lhs_ids, rhs_ids],
838            output: output_ids,
839        };
840        let inputs = [
841            tenferro_tensor::TensorRead::from_tensor(lhs),
842            tenferro_tensor::TensorRead::from_tensor(rhs),
843        ];
844        let plan = ConcreteEinsumPlan::prepare_read_subscripts(&inputs[..], &subscripts)?;
845        plan.execute_read_into(&inputs[..], self.engine, out)
846    }
847
848    /// Solve `A X = B` for column-major matrices on this session.
849    ///
850    /// Same kernel and validation as [`solve_matrix`](crate::solve_matrix), entered
851    /// through this session instead of the process-global one. `f64` and `Complex64`
852    /// agree with that entry bit for bit; `f32` and `Complex32` are solved in their own
853    /// precision here, while [`solve_matrix`](crate::solve_matrix) promotes them to
854    /// `f64` / `Complex64` and narrows the result, so the narrow types can differ in
855    /// the last bits (see [`solve_matrix_in`](crate::solve_matrix_in)).
856    ///
857    /// # Errors
858    ///
859    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
860    /// conditions as [`solve_matrix`](crate::solve_matrix).
861    ///
862    /// # Examples
863    ///
864    /// ```
865    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
866    /// use tensor4all_tensorbackend::CpuBackend;
867    ///
868    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
869    /// let a = Matrix::from_col_major_vec(2, 2, vec![2.0_f64, 0.0, 0.0, 4.0]);
870    /// let b = Matrix::from_col_major_vec(2, 1, vec![6.0_f64, 8.0]);
871    /// let x = context.with_concrete_session(|session| session.solve_matrix(&a, &b))??;
872    /// assert_eq!(x.as_col_major_slice(), &[3.0, 2.0]);
873    /// # Ok::<(), Box<dyn std::error::Error>>(())
874    /// ```
875    #[cfg(feature = "global-defaults")]
876    pub fn solve_matrix<T>(
877        &mut self,
878        a: &crate::matrix::Matrix<T>,
879        b: &crate::matrix::Matrix<T>,
880    ) -> Result<crate::matrix::Matrix<T>, crate::backend::BackendLinalgError>
881    where
882        T: crate::backend::BackendLinalgScalar + Copy,
883        NativeTensor: From<tenferro::TypedTensor<T>>,
884    {
885        crate::solve_matrix_in(self.engine, a, b)
886    }
887
888    /// Solve a triangular system for column-major matrices on this session.
889    ///
890    /// Same kernel, conversion and validation as
891    /// [`triangular_solve_matrix`](crate::triangular_solve_matrix), entered through this
892    /// session instead of the process-global one: `f64` and `Complex64` are solved
893    /// directly, `f32` and `Complex32` are promoted to `f64` / `Complex64` and the
894    /// result narrowed, so both routes return bitwise identical results. `left_side`,
895    /// `lower`, `transpose_a` and `unit_diagonal` have the same meaning as on that entry.
896    ///
897    /// # Errors
898    ///
899    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
900    /// conditions as [`triangular_solve_matrix`](crate::triangular_solve_matrix).
901    ///
902    /// # Examples
903    ///
904    /// ```
905    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
906    /// use tensor4all_tensorbackend::CpuBackend;
907    ///
908    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
909    /// let a = Matrix::from_col_major_vec(2, 2, vec![2.0_f64, 1.0, 0.0, 4.0]);
910    /// let b = Matrix::from_col_major_vec(2, 1, vec![4.0_f64, 4.0]);
911    /// let x = context.with_concrete_session(|session| {
912    ///     session.triangular_solve_matrix(&a, &b, true, true, false, false)
913    /// })??;
914    /// assert_eq!(x.as_col_major_slice(), &[2.0, 0.5]);
915    /// # Ok::<(), Box<dyn std::error::Error>>(())
916    /// ```
917    #[cfg(feature = "global-defaults")]
918    #[allow(clippy::too_many_arguments)]
919    pub fn triangular_solve_matrix<T>(
920        &mut self,
921        a: &crate::matrix::Matrix<T>,
922        b: &crate::matrix::Matrix<T>,
923        left_side: bool,
924        lower: bool,
925        transpose_a: bool,
926        unit_diagonal: bool,
927    ) -> Result<crate::matrix::Matrix<T>, crate::backend::BackendLinalgError>
928    where
929        T: crate::backend::MatrixTriangularSolveScalar,
930    {
931        crate::triangular_solve_matrix_in(
932            self.engine,
933            a,
934            b,
935            left_side,
936            lower,
937            transpose_a,
938            unit_diagonal,
939        )
940    }
941
942    /// Complete-pivoting LU decomposition of a column-major matrix on this session.
943    ///
944    /// Same kernel and conversion as
945    /// [`full_piv_lu_matrix`](crate::full_piv_lu_matrix), entered through this session
946    /// instead of the process-global one.
947    ///
948    /// # Errors
949    ///
950    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
951    /// conditions as [`full_piv_lu_matrix`](crate::full_piv_lu_matrix).
952    ///
953    /// # Examples
954    ///
955    /// ```
956    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
957    /// use tensor4all_tensorbackend::CpuBackend;
958    ///
959    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
960    /// let a = Matrix::from_col_major_vec(2, 2, vec![0.0_f64, 1.0, 2.0, 3.0]);
961    /// let factors = context.with_concrete_session(|session| session.full_piv_lu_matrix(&a))??;
962    /// assert_eq!(factors.p.nrows(), 2);
963    /// assert_eq!(factors.q.ncols(), 2);
964    /// # Ok::<(), Box<dyn std::error::Error>>(())
965    /// ```
966    #[cfg(feature = "global-defaults")]
967    pub fn full_piv_lu_matrix<T>(
968        &mut self,
969        a: &crate::matrix::Matrix<T>,
970    ) -> Result<crate::backend::FullPivLuMatrixResult<T>, crate::backend::BackendLinalgError>
971    where
972        T: crate::backend::BackendLinalgScalar + Copy,
973    {
974        crate::full_piv_lu_matrix_in(self.engine, a)
975    }
976
977    /// Thin/economy QR of a typed tensor on this session.
978    ///
979    /// Same kernel and conversion as [`qr_backend`](crate::qr_backend), entered through
980    /// this session instead of the process-global one.
981    ///
982    /// # Errors
983    ///
984    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
985    /// conditions as [`qr_backend`](crate::qr_backend).
986    ///
987    /// # Examples
988    ///
989    /// ```
990    /// use tensor4all_tensorbackend::CpuExecutionContext;
991    /// use tenferro::TypedTensor;
992    /// use tensor4all_tensorbackend::CpuBackend;
993    ///
994    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
995    /// let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])?;
996    /// let (q, r) = context.with_concrete_session(|session| session.qr_backend(a))??;
997    /// assert_eq!(q.shape(), &[2, 2]);
998    /// assert_eq!(r.shape(), &[2, 2]);
999    /// # Ok::<(), Box<dyn std::error::Error>>(())
1000    /// ```
1001    #[cfg(feature = "global-defaults")]
1002    pub fn qr_backend<T>(
1003        &mut self,
1004        a: tenferro::TypedTensor<T>,
1005    ) -> Result<
1006        (tenferro::TypedTensor<T>, tenferro::TypedTensor<T>),
1007        crate::backend::BackendLinalgError,
1008    >
1009    where
1010        T: crate::backend::BackendLinalgScalar,
1011    {
1012        use tenferro::TensorScalar;
1013
1014        let (shape, data) = a.into_vec_col_major().map_err(|error| {
1015            crate::backend::BackendLinalgError::from(anyhow::anyhow!(
1016                "QR input host access failed: {error}"
1017            ))
1018        })?;
1019        let tensor: NativeTensor =
1020            <T as TensorScalar>::into_tensor(shape, data).map_err(|error| {
1021                crate::backend::BackendLinalgError::from(anyhow::anyhow!(
1022                    "QR input tensor construction failed: {error}"
1023                ))
1024            })?;
1025        crate::qr_backend_in(self.engine, tensor)
1026    }
1027
1028    /// Thin/economy SVD of a typed tensor on this session.
1029    ///
1030    /// Same kernel and conversion as [`svd_backend`](crate::svd_backend), entered through
1031    /// this session instead of the process-global one.
1032    ///
1033    /// # Errors
1034    ///
1035    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
1036    /// conditions as [`svd_backend`](crate::svd_backend).
1037    ///
1038    /// # Examples
1039    ///
1040    /// ```
1041    /// use tensor4all_tensorbackend::CpuExecutionContext;
1042    /// use tenferro::TypedTensor;
1043    /// use tensor4all_tensorbackend::CpuBackend;
1044    ///
1045    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1046    /// let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![3.0, 0.0, 0.0, 2.0])?;
1047    /// let factors = context.with_concrete_session(|session| session.svd_backend(&a))??;
1048    /// assert_eq!(factors.s().as_slice()?, &[3.0, 2.0]);
1049    /// # Ok::<(), Box<dyn std::error::Error>>(())
1050    /// ```
1051    #[cfg(feature = "global-defaults")]
1052    pub fn svd_backend<T>(
1053        &mut self,
1054        a: &tenferro::TypedTensor<T>,
1055    ) -> Result<crate::backend::SvdResult<T>, crate::backend::BackendLinalgError>
1056    where
1057        T: crate::backend::BackendLinalgScalar,
1058    {
1059        use tenferro::TensorScalar;
1060
1061        let tensor: NativeTensor = <T as TensorScalar>::into_tensor(
1062            a.shape().to_vec(),
1063            a.host_data()
1064                .map_err(|error| {
1065                    crate::backend::BackendLinalgError::from(anyhow::anyhow!(
1066                        "SVD input host access failed: {error}"
1067                    ))
1068                })?
1069                .to_vec(),
1070        )
1071        .map_err(|error| {
1072            crate::backend::BackendLinalgError::from(anyhow::anyhow!(
1073                "SVD input tensor construction failed: {error}"
1074            ))
1075        })?;
1076        crate::svd_backend_in(self.engine, tensor)
1077    }
1078
1079    /// Matrix multiplication `A * B` on this session.
1080    ///
1081    /// The same kernel and shape validation as
1082    /// [`mat_mul`](crate::mat_mul), entered through this session instead of the
1083    /// process-global one, and returning the shared
1084    /// [`Matrix`](crate::Matrix) container.
1085    ///
1086    /// # Errors
1087    ///
1088    /// Returns [`MatrixMulError`](crate::MatrixMulError) when the shapes disagree or
1089    /// the session operation fails.
1090    ///
1091    /// # Examples
1092    ///
1093    /// ```
1094    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
1095    /// use tensor4all_tensorbackend::CpuBackend;
1096    ///
1097    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1098    /// let a = Matrix::from_col_major_vec(2, 2, vec![1.0_f64, 2.0, 3.0, 4.0]);
1099    /// let b = Matrix::from_col_major_vec(2, 2, vec![1.0_f64, 0.0, 0.0, 1.0]);
1100    /// let c = context.with_concrete_session(|session| session.mat_mul(&a, &b))??;
1101    /// assert_eq!(c.as_col_major_slice(), &[1.0, 2.0, 3.0, 4.0]);
1102    /// # Ok::<(), Box<dyn std::error::Error>>(())
1103    /// ```
1104    #[cfg(feature = "global-defaults")]
1105    pub fn mat_mul<T: crate::matrix::BlasMul>(
1106        &mut self,
1107        a: &crate::matrix::Matrix<T>,
1108        b: &crate::matrix::Matrix<T>,
1109    ) -> Result<crate::matrix::Matrix<T>, crate::matrix::MatrixMulError> {
1110        crate::mat_mul_in(self.engine, a, b)
1111    }
1112
1113    /// Thin/economy QR decomposition.
1114    ///
1115    /// # Errors
1116    ///
1117    /// Returns [`tenferro_tensor::Error::Validation`] for an unsupported dtype or
1118    /// rank, and [`tenferro_tensor::Error::BackendSource`] when the factorization
1119    /// itself fails.
1120    ///
1121    /// # Examples
1122    ///
1123    /// ```
1124    /// use tensor4all_tensorbackend::CpuExecutionContext;
1125    /// use tenferro::Tensor;
1126    /// use tensor4all_tensorbackend::CpuBackend;
1127    ///
1128    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1129    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
1130    /// let (q, r) = context.with_concrete_session(|session| session.qr(&a))??;
1131    /// // `A = Q R` is reproduced to rounding, which is the correctness property
1132    /// // of a factorization.
1133    /// let reconstructed =
1134    ///     context.with_concrete_session(|session| session.contraction(&q, &[1], &r, &[0]))??;
1135    /// for (got, want) in reconstructed.as_slice::<f64>()?.iter().zip([1.0, 2.0, 3.0, 4.0]) {
1136    ///     assert!((got - want).abs() < 1e-12, "got {got}, want {want}");
1137    /// }
1138    /// # Ok::<(), Box<dyn std::error::Error>>(())
1139    /// ```
1140    pub fn qr(
1141        &mut self,
1142        tensor: &NativeTensor,
1143    ) -> tenferro_tensor::Result<(NativeTensor, NativeTensor)> {
1144        tensor.qr(self.engine)
1145    }
1146
1147    /// Thin/economy SVD.
1148    ///
1149    /// # Errors
1150    ///
1151    /// Returns [`tenferro_tensor::Error::Validation`] for an unsupported dtype or
1152    /// rank, and [`tenferro_tensor::Error::BackendSource`] when the factorization
1153    /// itself fails.
1154    ///
1155    /// # Examples
1156    ///
1157    /// ```
1158    /// use tensor4all_tensorbackend::CpuExecutionContext;
1159    /// use tenferro::Tensor;
1160    /// use tensor4all_tensorbackend::CpuBackend;
1161    ///
1162    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1163    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![3.0_f64, 0.0, 0.0, 2.0])?;
1164    /// let (u, s, vt) = context.with_concrete_session(|session| session.svd(&a))??;
1165    /// // The singular values of diag(3, 2) are 3 and 2.
1166    /// assert_eq!(s.as_slice::<f64>()?, &[3.0, 2.0]);
1167    /// assert_eq!(u.shape(), &[2, 2]);
1168    /// assert_eq!(vt.shape(), &[2, 2]);
1169    /// # Ok::<(), Box<dyn std::error::Error>>(())
1170    /// ```
1171    pub fn svd(
1172        &mut self,
1173        tensor: &NativeTensor,
1174    ) -> tenferro_tensor::Result<(NativeTensor, NativeTensor, NativeTensor)> {
1175        tensor.svd(self.engine)
1176    }
1177
1178    /// Solve `A X = B` for a square `A`.
1179    ///
1180    /// # Errors
1181    ///
1182    /// Returns [`tenferro_tensor::Error::Validation`] when `lhs` is not square, when
1183    /// the operands have mismatched shapes, or for an unsupported dtype, and
1184    /// [`tenferro_tensor::Error::BackendSource`] when the solve itself fails.
1185    ///
1186    /// # Examples
1187    ///
1188    /// ```
1189    /// use tensor4all_tensorbackend::CpuExecutionContext;
1190    /// use tenferro::Tensor;
1191    /// use tensor4all_tensorbackend::CpuBackend;
1192    ///
1193    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1194    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![2.0_f64, 0.0, 0.0, 4.0])?;
1195    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![6.0_f64, 8.0])?;
1196    /// let x = context.with_concrete_session(|session| session.solve(&a, &b))??;
1197    /// assert_eq!(x.as_slice::<f64>()?, &[3.0, 2.0]);
1198    /// # Ok::<(), Box<dyn std::error::Error>>(())
1199    /// ```
1200    pub fn solve(
1201        &mut self,
1202        lhs: &NativeTensor,
1203        rhs: &NativeTensor,
1204    ) -> tenferro_tensor::Result<NativeTensor> {
1205        lhs.solve(rhs, self.engine)
1206    }
1207
1208    /// Solve `A X = B` where `A` is triangular.
1209    ///
1210    /// - `left_side`: solve `A X = B` when true, `X A = B` when false;
1211    /// - `lower`: `A` is lower triangular;
1212    /// - `transpose_a`: solve with `A` transposed;
1213    /// - `unit_diagonal`: treat the diagonal of `A` as one, ignoring the stored
1214    ///   values.
1215    ///
1216    /// # Errors
1217    ///
1218    /// Returns [`tenferro_tensor::Error::Validation`] for a shape mismatch or an
1219    /// unsupported dtype, and [`tenferro_tensor::Error::BackendSource`] when the solve
1220    /// itself fails.
1221    ///
1222    /// # Examples
1223    ///
1224    /// ```
1225    /// use tensor4all_tensorbackend::CpuExecutionContext;
1226    /// use tenferro::Tensor;
1227    /// use tensor4all_tensorbackend::CpuBackend;
1228    ///
1229    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1230    /// // Lower triangular, column-major.
1231    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![2.0_f64, 1.0, 0.0, 4.0])?;
1232    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![4.0_f64, 4.0])?;
1233    /// let x = context.with_concrete_session(|session| {
1234    ///     session.triangular_solve(&a, &b, true, true, false, false)
1235    /// })??;
1236    /// assert_eq!(x.as_slice::<f64>()?, &[2.0, 0.5]);
1237    /// # Ok::<(), Box<dyn std::error::Error>>(())
1238    /// ```
1239    pub fn triangular_solve(
1240        &mut self,
1241        lhs: &NativeTensor,
1242        rhs: &NativeTensor,
1243        left_side: bool,
1244        lower: bool,
1245        transpose_a: bool,
1246        unit_diagonal: bool,
1247    ) -> tenferro_tensor::Result<NativeTensor> {
1248        lhs.triangular_solve(
1249            rhs,
1250            left_side,
1251            lower,
1252            transpose_a,
1253            unit_diagonal,
1254            self.engine,
1255        )
1256    }
1257
1258    /// Full-pivoting LU decomposition `P A Q = L U`, returning
1259    /// `(P, L, U, Q, parity)`.
1260    ///
1261    /// # Errors
1262    ///
1263    /// Returns [`tenferro_tensor::Error::Validation`] for a non-square `A` or an
1264    /// unsupported dtype, and [`tenferro_tensor::Error::BackendSource`] when the
1265    /// factorization itself fails.
1266    ///
1267    /// # Examples
1268    ///
1269    /// ```
1270    /// use tensor4all_tensorbackend::CpuExecutionContext;
1271    /// use tenferro::Tensor;
1272    /// use tensor4all_tensorbackend::CpuBackend;
1273    ///
1274    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1275    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
1276    /// let (p, l, u, q, _parity) = context
1277    ///     .with_concrete_session(|session| session.full_piv_lu(&a))?
1278    ///     .expect("full-pivoting LU");
1279    /// for factor in [&p, &l, &u, &q] {
1280    ///     assert_eq!(factor.shape(), &[2, 2]);
1281    /// }
1282    /// // Column-major, so index 0 is (0, 0), index 1 is (1, 0) and index 2 is (0, 1).
1283    /// let l = l.as_slice::<f64>()?;
1284    /// let u = u.as_slice::<f64>()?;
1285    /// assert_eq!(l[2], 0.0, "L is lower triangular");
1286    /// assert_eq!(u[1], 0.0, "U is upper triangular");
1287    /// # Ok::<(), Box<dyn std::error::Error>>(())
1288    /// ```
1289    pub fn full_piv_lu(
1290        &mut self,
1291        tensor: &NativeTensor,
1292    ) -> tenferro_tensor::Result<(
1293        NativeTensor,
1294        NativeTensor,
1295        NativeTensor,
1296        NativeTensor,
1297        NativeTensor,
1298    )> {
1299        tensor.full_piv_lu(self.engine)
1300    }
1301}
1302
1303impl CpuExecutionContext {
1304    /// Run `f` inside one explicit concrete session of this context.
1305    ///
1306    /// The context's engine is borrowed once for the whole closure, so a stage
1307    /// borrows it once and reuses its prepared plans and buffer pool. All routes on
1308    /// the [`Session`] run on that engine only: nothing here consults the
1309    /// process-global default context, and nothing falls back to it.
1310    ///
1311    /// # Examples
1312    ///
1313    /// ```
1314    /// use tensor4all_tensorbackend::CpuExecutionContext;
1315    /// use tenferro::Tensor;
1316    /// use tensor4all_tensorbackend::CpuBackend;
1317    ///
1318    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
1319    /// let x = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 3.0])?;
1320    /// let doubled = context.with_concrete_session(|session| session.reshape(&x, &[2]))??;
1321    /// assert_eq!(doubled.as_slice::<f64>()?, &[1.0, 3.0]);
1322    /// # Ok::<(), Box<dyn std::error::Error>>(())
1323    /// ```
1324    ///
1325    /// # Errors
1326    ///
1327    /// Returns [`CpuExecutionContextError::Reentered`] when the calling thread is
1328    /// already inside a session of this context. A session entered from a Rayon
1329    /// worker runs inline on a serial engine that shares the context engine's
1330    /// prepared-plan cache, so a worker entry completes instead of waiting for a
1331    /// pool it belongs to (tensor4all-rs#830).
1332    ///
1333    /// # Panics
1334    ///
1335    /// Never. A panic in `f` propagates after the engine borrow is released.
1336    pub fn with_concrete_session<R>(
1337        &self,
1338        f: impl FnOnce(&mut Session<'_>) -> R,
1339    ) -> Result<R, CpuExecutionContextError> {
1340        self.with_session(|engine| f(&mut Session::new(engine)))
1341    }
1342}
1343
1344#[cfg(test)]
1345mod tests;