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;