tensor4all_tensorbackend/

explicit.rs

//! Opt-in explicit/concrete execution frontend.
//!
//! This is the second, opt-in frontend of
//! [tensor4all-rs#859](https://github.com/tensor4all/tensor4all-rs/issues/859): a
//! caller-supplied [`CpuExecutionContext`] plus one concrete session that a whole
//! stage or batch reuses, instead of the process-global convenience surface in
//! the compatibility entry point. The compatibility frontend keeps its own signatures,
//! defaults and behaviour; nothing here reroutes it.
//!
//! Properties of this frontend, from the coexistence record
//! (`docs/design/859-dual-frontend-coexistence.md`):
//!
//! - **One explicit entry.** [`CpuExecutionContext::with_concrete_session`] lends the
//!   context's engine for the whole closure, so a stage borrows it once rather than once
//!   per operation, and the engine's prepared plans and buffer pool stay warm.
//! - **No process-global selector.** No route here selects an execution context or
//!   backend from a default context, a thread-local override or an environment
//!   variable. (Upstream profiling hooks may still read their own environment flags;
//!   those do not choose where the work runs.)
//! - **No eager, trace or AD records.** These routes reach only concrete
//!   `Tensor`/engine operations; they never construct `EagerTensor`,
//!   semantic nodes or gradient slots, and they take no eager owner lock. Tracked
//!   values are not accepted at all, so no detach can happen implicitly.
//! - **No implicit fallback.** An unsupported dtype or shape returns the
//!   backend's typed error. Nothing here retries on the global or CPU-eager route.
//! - **Explicit conversion at the boundary.** Crossing between this frontend and
//!   the compatibility frontend is [`LogicalTensor`](crate::LogicalTensor), which
//!   carries dtype, shape and column-major data and no backend identity.
//!
//! The session is a borrow of one [`tenferro_cpu::CpuEngine`], not a value
//! representation: the concrete values stay the ordinary tenferro tensors.
//!
//! # Examples
//!
//! ```
//! use tensor4all_tensorbackend::{CpuExecutionContext, explicit::Session};
//! use tenferro::Tensor;
//! use tensor4all_tensorbackend::CpuBackend;
//!
//! let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
//! let x = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
//!
//! let product = context.with_concrete_session(|session: &mut Session<'_>| {
//!     session.qr(&x).map(|(q, _r)| q)
//! })?;
//! assert_eq!(product.expect("QR succeeds").shape(), &[2, 2]);
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```

use tenferro::Tensor as NativeTensor;
use tenferro::TensorSessionOpsExt;
use tenferro_einsum::{ConcreteEinsumPlan, EinsumSubscripts, TensorEinsumExt};
use tenferro_linalg::TensorLinalgExt;

use tenferro_tensor::Engine;

use crate::context::{CpuExecutionContext, CpuExecutionContextError};
use crate::einsum_ids::{
    build_binary_einsum_ids, checked_native_einsum_labels, common_dtype, convert_native_tensor_in,
};

/// One explicit concrete session over a caller-held CPU engine.
///
/// The session borrows an engine for the whole of its life. Inside
/// [`CpuExecutionContext::with_concrete_session`] that is the context's engine,
/// borrowed for the closure; a caller that owns an engine ([`crate::CpuBackend`])
/// builds the same session with [`Session::new`] and keeps it across as many
/// operations as it wants. Every route on it runs through that one engine, so a
/// stage does not pay an entry per operation.
///
/// # Examples
///
/// ```
/// use tensor4all_tensorbackend::CpuExecutionContext;
/// use tenferro::Tensor;
/// use tensor4all_tensorbackend::CpuBackend;
///
/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
/// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
/// let b = Tensor::from_vec_col_major(vec![2, 2], vec![0.0_f64, 1.0, 1.0, 0.0])?;
/// let (ab, a_again) = context.with_concrete_session(
///     |session| -> Result<_, Box<dyn std::error::Error + Send + Sync>> {
///         let ab = session.contraction(&a, &[1], &b, &[0])?;
///         // One session, two operations.
///         let a_again = session.permute(&a, &[1, 0])?;
///         Ok((ab, a_again))
///     },
/// )??;
/// // `a` is `[[1, 3], [2, 4]]` column-major and `b` swaps the axes, so `a * b`
/// // is `[[3, 1], [4, 2]]`.
/// assert_eq!(ab.as_slice::<f64>()?, &[3.0, 4.0, 1.0, 2.0]);
/// assert_eq!(a_again.as_slice::<f64>()?, &[1.0, 3.0, 2.0, 4.0]);
/// # Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
/// ```
pub struct Session<'session> {
    engine: &'session mut dyn Engine,
}

impl std::fmt::Debug for Session<'_> {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("explicit::Session")
            .finish_non_exhaustive()
    }
}

/// Failure reported by this frontend's compatibility bridges.
///
/// The original tenferro or tenferro-ad diagnostic is retained as the source.
#[derive(Debug, thiserror::Error)]
pub enum ConversionError {
    /// Materializing a tracked value into a plain concrete value failed.
    #[error("materializing a tracked value failed: {source}")]
    Detach {
        /// Original tenferro diagnostic.
        #[source]
        source: Box<dyn std::error::Error + Send + Sync + 'static>,
    },
    /// Adopting a plain concrete value into an eager runtime failed.
    #[error("adopting a concrete value failed: {source}")]
    Lift {
        /// Original tenferro or tenferro-ad diagnostic.
        #[source]
        source: Box<dyn std::error::Error + Send + Sync + 'static>,
    },
}

/// Materialize a tracked eager value into a plain concrete value on `engine`.
///
/// This is the explicit AD to plain boundary of the coexistence contract: the caller names
/// the conversion, so tracking never disappears silently, and `no_grad` on an eager value is
/// not this operation and does not select the concrete representation. The value keeps its
/// dtype, logical shape and column-major layout; the result is an ordinary concrete tensor
/// that this frontend's routes accept. Materializing a lazy or prepared value needs an
/// engine to evaluate it, so the caller passes the one it wants the copy to run on.
///
/// # Errors
///
/// Returns [`ConversionError::Detach`] when the tracked value cannot be materialized, for
/// example because it is a lazy or prepared value that has not been evaluated.
///
/// # Examples
///
/// ```
/// use tensor4all_tensorbackend::{explicit, CpuExecutionContext};
/// use tenferro::Tensor;
/// use tenferro_ad::EagerTensor;
/// use tensor4all_tensorbackend::CpuBackend;
///
/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
/// let plain = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
/// let tracked = explicit::lift(&context, plain)?;
/// let back = context.with_backend(|backend| explicit::detach(&tracked, backend.engine_mut()))?;
/// assert_eq!(back.as_slice::<f64>()?, &[1.0, 2.0]);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn detach(
    eager: &tenferro_ad::EagerTensor,
    engine: &mut dyn Engine,
) -> Result<NativeTensor, ConversionError> {
    eager
        .to_tensor(engine)
        .map_err(|source| ConversionError::Detach {
            source: Box::new(source),
        })
}

/// Adopt a plain concrete value into `context`'s eager runtime.
///
/// This is the explicit plain to AD boundary: the result is a tracked value in a graph owned
/// by `context`'s own eager runtime, and nothing about it is inferred from the caller's
/// ambient `no_grad` or capture state. The value is moved into the runtime, because a
/// concrete tensor has one owner. Use [`detach`] for the opposite direction.
///
/// # Errors
///
/// Returns [`ConversionError::Lift`] when the context's eager runtime cannot be initialized
/// or when the value cannot be adopted, for example because it is not a concrete host value.
///
/// # Examples
///
/// ```
/// use tensor4all_tensorbackend::{explicit, CpuExecutionContext};
/// use tenferro::Tensor;
/// use tensor4all_tensorbackend::CpuBackend;
///
/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
/// let plain = Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0])?;
/// let tracked = explicit::lift(&context, plain)?;
/// // The adopted value is tracked, and its runtime is the context's own.
/// let back = context.with_backend(|backend| explicit::detach(&tracked, backend.engine_mut()))?;
/// assert_eq!(back.as_slice::<f64>()?, &[3.0, 4.0]);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn lift(
    context: &CpuExecutionContext,
    tensor: NativeTensor,
) -> Result<tenferro_ad::EagerTensor, ConversionError> {
    let runtime = context
        .eager_runtime()
        .map_err(|source| ConversionError::Lift {
            source: Box::new(source),
        })?;
    tenferro_ad::EagerTensor::from_tensor_in(tensor, runtime).map_err(|source| {
        ConversionError::Lift {
            source: Box::new(source),
        }
    })
}

/// One prepared N-ary einsum, reusable across operations of a session.
///
/// Preparing validates the labels and plans the contraction once; every
/// [`PreparedEinsum::execute`] and [`PreparedEinsum::execute_into`] reuses that plan, so
/// a stage keeps one plan across as many evaluations as it needs instead of preparing
/// per call. The plan borrows its operands, so it cannot outlive them, and it holds no
/// execution state: the session stays the caller's.
///
/// # Examples
///
/// ```
/// use tensor4all_tensorbackend::{explicit::PreparedEinsum, CpuExecutionContext};
/// use tenferro::Tensor;
/// use tensor4all_tensorbackend::CpuBackend;
/// use tenferro_tensor::{TensorRead, TensorWrite};
///
/// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
/// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
/// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
/// let reads = [TensorRead::from_tensor(&a), TensorRead::from_tensor(&b)];
/// let plan = PreparedEinsum::prepare(&reads, &[&[0, 1], &[1, 2]], &[0, 2])?;
///
/// // Reused across a stage, including into a caller-provided destination.
/// let mut out = Tensor::from_vec_col_major(vec![2, 1], vec![0.0_f64, 0.0])?;
/// context.with_concrete_session(|session| -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
///     let product = plan.execute(session)?;
///     assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
///     plan.execute_into(session, TensorWrite::Tensor(&mut out))?;
///     Ok(())
/// })??;
/// assert_eq!(out.as_slice::<f64>()?, &[23.0, 34.0]);
/// # Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
/// ```
pub struct PreparedEinsum<'operands> {
    plan: ConcreteEinsumPlan,
    operands: Vec<tenferro_tensor::TensorRead<'operands>>,
}

impl std::fmt::Debug for PreparedEinsum<'_> {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("explicit::PreparedEinsum")
            .field("operands", &self.operands.len())
            .finish_non_exhaustive()
    }
}

impl<'operands> PreparedEinsum<'operands> {
    /// Plan an N-ary einsum over borrowed operands.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] for malformed labels, a
    /// label list whose length does not match the operand's rank, or a label-list count
    /// that does not match the operand count, and [`tenferro_einsum::Error`] from the
    /// contraction planner when the expression cannot be planned.
    pub fn prepare(
        operands: &[tenferro_tensor::TensorRead<'operands>],
        input_ids: &[&[usize]],
        output_ids: &[usize],
    ) -> tenferro_einsum::Result<Self> {
        if operands.len() != input_ids.len() {
            return Err(tenferro_einsum::Error::InvalidSubscripts {
                message: format!(
                    "einsum needs one label list per operand: {} operands, {} label lists",
                    operands.len(),
                    input_ids.len()
                ),
            });
        }
        let invalid = |error: anyhow::Error| tenferro_einsum::Error::InvalidSubscripts {
            message: format!("{error}"),
        };
        let inputs = input_ids
            .iter()
            .map(|ids| checked_native_einsum_labels(ids))
            .collect::<anyhow::Result<Vec<_>>>()
            .map_err(invalid)?;
        let output = checked_native_einsum_labels(output_ids).map_err(invalid)?;
        let subscripts = EinsumSubscripts { inputs, output };
        let plan = ConcreteEinsumPlan::prepare_read_subscripts(operands, &subscripts)?;
        Ok(Self {
            plan,
            operands: operands.to_vec(),
        })
    }

    /// Evaluate the prepared plan on `session`, allocating the result.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::Tensor`] when the session rejects the operands
    /// or the contraction itself fails, and
    /// [`tenferro_einsum::Error::Validation`] when the operands no longer match the
    /// planned expression.
    pub fn execute(&self, session: &mut Session<'_>) -> tenferro_einsum::Result<NativeTensor> {
        self.plan
            .execute_read(self.operands.as_slice(), session.engine())
    }

    /// Evaluate the prepared plan into a caller-provided destination.
    ///
    /// The destination is fully written and is never zero-filled first. Operands and
    /// destination must already share one dtype; this route does not convert into a
    /// caller-owned output.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::Tensor`] when the session rejects the operands,
    /// the destination or the contraction, and
    /// [`tenferro_einsum::Error::Validation`] when the operands no longer match the
    /// planned expression.
    pub fn execute_into(
        &self,
        session: &mut Session<'_>,
        out: tenferro_tensor::TensorWrite<'_>,
    ) -> tenferro_einsum::Result<()> {
        self.plan
            .execute_read_into(self.operands.as_slice(), session.engine(), out)
    }
}

/// Promote a heterogeneous operand set to the dtype both frontends contract in.
///
/// Returns an empty vector when every operand already has the common dtype, so the
/// common case allocates nothing.
///
/// # Errors
///
/// Returns [`tenferro_einsum::Error::Tensor`] when an operand cannot be converted.
fn promote_operands(
    engine: &mut dyn Engine,
    operands: &[&NativeTensor],
) -> tenferro_einsum::Result<Vec<NativeTensor>> {
    let dtypes = operands
        .iter()
        .map(|tensor| tensor.dtype())
        .collect::<Vec<_>>();
    let target = common_dtype(&dtypes);
    if operands.iter().all(|tensor| tensor.dtype() == target) {
        return Ok(Vec::new());
    }
    operands
        .iter()
        .map(|tensor| {
            convert_native_tensor_in(engine, tensor, target).map_err(tenferro_einsum::Error::Tensor)
        })
        .collect()
}

impl<'session> Session<'session> {
    /// Wrap a borrowed engine as this frontend's session.
    ///
    /// A caller that owns an engine - a [`crate::CpuBackend`], an engine it built
    /// itself, or one borrowed for a stage - builds the same [`Session`] the
    /// callback-scoped [`CpuExecutionContext::with_concrete_session`] hands out, so a
    /// long stage can keep one session across many operations without entering a
    /// context. The engine stays borrowed for the whole life of the returned session:
    /// this constructor never enters, replaces or reroutes an engine.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::{explicit::Session, CpuBackend};
    /// use tenferro::Tensor;
    ///
    /// let mut backend = CpuBackend::with_threads(1)?;
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    ///
    /// let mut session = Session::new(backend.engine_mut());
    /// // One session, two operations.
    /// let transposed = session.permute(&a, &[1, 0])?;
    /// let total = session.sum(&transposed)?;
    /// assert_eq!(total.as_slice::<f64>()?, &[10.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn new(engine: &'session mut dyn Engine) -> Self {
        Self { engine }
    }

    /// The engine behind this explicit session.
    ///
    /// Exposed so a prepared plan can evaluate itself on the caller's engine; it is
    /// not a second entry point, and it never consults another backend.
    pub fn engine(&mut self) -> &mut dyn Engine {
        self.engine
    }

    /// Reshape a concrete tensor without changing its column-major linearization.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] when the element counts
    /// differ or the requested layout is invalid,
    /// [`tenferro_tensor::Error::UnsupportedDType`] for a dtype the backend cannot
    /// reshape, and [`tenferro_tensor::Error::BackendSource`] when the operation
    /// itself fails. It never retries on another route.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let x = Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let reshaped = context.with_concrete_session(|session| session.reshape(&x, &[2, 2]))??;
    /// assert_eq!(reshaped.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn reshape(
        &mut self,
        tensor: &NativeTensor,
        shape: &[usize],
    ) -> tenferro_tensor::Result<NativeTensor> {
        tensor.reshape(shape, self.engine)
    }

    /// Permute the axes of a concrete tensor.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] when `perm` is not a
    /// permutation of the tensor's axes, and
    /// [`tenferro_tensor::Error::BackendSource`] when the operation itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let x = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let transposed = context.with_concrete_session(|session| session.permute(&x, &[1, 0]))??;
    /// assert_eq!(transposed.as_slice::<f64>()?, &[1.0, 3.0, 2.0, 4.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn permute(
        &mut self,
        tensor: &NativeTensor,
        perm: &[usize],
    ) -> tenferro_tensor::Result<NativeTensor> {
        tensor.transpose(perm, self.engine)
    }

    /// Binary contraction along the given axes, preserving the remaining axes in
    /// order.
    ///
    /// The operand identity and axis building is the same code path the
    /// compatibility frontend uses, so both frontends contract identically; only
    /// the session differs.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] when the axis lists are
    /// malformed or of different length, and [`tenferro_einsum::Error::Tensor`] when the
    /// backend rejects the operands, when an operand cannot be promoted, or when the
    /// contraction itself fails.
    ///
    /// Operands are promoted to a common dtype exactly as the compatibility frontend
    /// promotes them: a heterogeneous set contracts in the promoted dtype, and a set
    /// that already shares one dtype is used as is.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
    /// let product =
    ///     context.with_concrete_session(|session| session.contraction(&a, &[1], &b, &[0]))??;
    /// assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn contraction(
        &mut self,
        lhs: &NativeTensor,
        lhs_axes: &[usize],
        rhs: &NativeTensor,
        rhs_axes: &[usize],
    ) -> tenferro_einsum::Result<NativeTensor> {
        let (lhs_ids, rhs_ids, output_ids) =
            build_binary_einsum_ids(lhs.shape().len(), lhs_axes, rhs.shape().len(), rhs_axes)
                .map_err(|error| tenferro_einsum::Error::InvalidSubscripts {
                    message: format!("{error}"),
                })?;
        let subscripts = EinsumSubscripts {
            inputs: vec![lhs_ids, rhs_ids],
            output: output_ids,
        };
        let operands = [lhs, rhs];
        let promoted = promote_operands(self.engine, &operands)?;
        let operands = if promoted.is_empty() {
            operands.to_vec()
        } else {
            promoted.iter().collect::<Vec<_>>()
        };
        operands.einsum_subscripts(&subscripts, self.engine)
    }

    /// N-ary einsum from integer labels, evaluated on this session.
    ///
    /// The labels are validated by the same helper the compatibility frontend
    /// uses; the evaluation is tenferro-einsum's session-direct einsum, so it does
    /// not compile a semantic graph or start a runtime worker.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] for malformed labels, a
    /// label list whose length does not match the operand's rank, or a label-list
    /// count that does not match the operand count, and
    /// [`tenferro_einsum::Error::Tensor`] when the backend rejects the operands, when an
    /// operand cannot be promoted, or when the contraction itself fails.
    ///
    /// Operands are promoted to a common dtype exactly as the compatibility frontend
    /// promotes them: a heterogeneous set contracts in the promoted dtype, and a set
    /// that already shares one dtype is used as is.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let b = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 0.0, 0.0, 1.0])?;
    /// let product = context.with_concrete_session(|session| {
    ///     session.einsum(&[&a, &b], &[&[0, 1], &[1, 2]], &[0, 2])
    /// })??;
    /// assert_eq!(product.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn einsum(
        &mut self,
        operands: &[&NativeTensor],
        input_ids: &[&[usize]],
        output_ids: &[usize],
    ) -> tenferro_einsum::Result<NativeTensor> {
        if operands.len() != input_ids.len() {
            return Err(tenferro_einsum::Error::InvalidSubscripts {
                message: format!(
                    "einsum needs one label list per operand: {} operands, {} label lists",
                    operands.len(),
                    input_ids.len()
                ),
            });
        }
        let inputs = input_ids
            .iter()
            .map(|ids| checked_native_einsum_labels(ids))
            .collect::<anyhow::Result<Vec<_>>>()
            .map_err(|error| tenferro_einsum::Error::InvalidSubscripts {
                message: format!("{error}"),
            })?;
        let subscripts = EinsumSubscripts {
            inputs,
            output: checked_native_einsum_labels(output_ids).map_err(|error| {
                tenferro_einsum::Error::InvalidSubscripts {
                    message: format!("{error}"),
                }
            })?,
        };
        let promoted = promote_operands(self.engine, operands)?;
        let operands: Vec<&NativeTensor> = if promoted.is_empty() {
            operands.to_vec()
        } else {
            promoted.iter().collect()
        };
        operands.einsum_subscripts(&subscripts, self.engine)
    }

    /// Sum every element of a concrete tensor, returning the rank-0 result.
    ///
    /// The compatibility frontend wraps the same rank-0 tensor in a
    /// `BackendScalar`; this route stays on the concrete value so it works without
    /// the compatibility feature.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] for an unsupported reduction
    /// shape and [`tenferro_tensor::Error::BackendSource`] when the reduction itself
    /// fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let x = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let total = context.with_concrete_session(|session| session.sum(&x))??;
    /// assert_eq!(total.shape(), &[] as &[usize]);
    /// assert_eq!(total.as_slice::<f64>()?, &[10.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn sum(&mut self, tensor: &NativeTensor) -> tenferro_tensor::Result<NativeTensor> {
        if tensor.shape().is_empty() {
            return tensor.duplicate();
        }
        let axes = (0..tensor.shape().len()).collect::<Vec<_>>();
        tensor.reduce_sum(Some(&axes), self.engine)
    }

    /// Conjugate a concrete tensor.
    ///
    /// A real tensor is returned unchanged; a complex tensor is conjugated
    /// elementwise.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Unsupported`] for a dtype the backend cannot
    /// conjugate and [`tenferro_tensor::Error::BackendSource`] when the operation
    /// itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    /// use num_complex::Complex64;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let x = Tensor::from_vec_col_major(
    ///     vec![2],
    ///     vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, -4.0)],
    /// )?;
    /// let conjugated = context.with_concrete_session(|session| session.conj(&x))??;
    /// assert_eq!(
    ///     conjugated.as_slice::<Complex64>()?,
    ///     &[Complex64::new(1.0, -2.0), Complex64::new(3.0, 4.0)]
    /// );
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn conj(&mut self, tensor: &NativeTensor) -> tenferro_tensor::Result<NativeTensor> {
        tensor.conj(self.engine)
    }

    /// N-ary einsum over borrowed read inputs, without materializing them.
    ///
    /// Same contract as [`Session::einsum`], except that the operands are
    /// [`TensorRead`](tenferro_tensor::TensorRead) views: a non-contiguous or lazily
    /// represented operand stays borrowed until the contract evaluates it.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] for malformed labels or a
    /// label list whose length does not match the operand's rank, and
    /// [`tenferro_einsum::Error::Tensor`] when the backend rejects the operands or the
    /// contraction itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    /// use tenferro_tensor::TensorRead;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
    /// let reads = [TensorRead::from_tensor(&a), TensorRead::from_tensor(&b)];
    /// let product = context
    ///     .with_concrete_session(|session| session.einsum_reads(&reads, &[&[0, 1], &[1, 2]], &[0, 2]))??;
    /// assert_eq!(product.as_slice::<f64>()?, &[23.0, 34.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn einsum_reads(
        &mut self,
        operands: &[tenferro_tensor::TensorRead<'_>],
        input_ids: &[&[usize]],
        output_ids: &[usize],
    ) -> tenferro_einsum::Result<NativeTensor> {
        if operands.len() != input_ids.len() {
            return Err(tenferro_einsum::Error::InvalidSubscripts {
                message: format!(
                    "einsum needs one label list per operand: {} operands, {} label lists",
                    operands.len(),
                    input_ids.len()
                ),
            });
        }
        let invalid = |error: anyhow::Error| tenferro_einsum::Error::InvalidSubscripts {
            message: format!("{error}"),
        };
        let inputs = input_ids
            .iter()
            .map(|ids| checked_native_einsum_labels(ids))
            .collect::<anyhow::Result<Vec<_>>>()
            .map_err(invalid)?;
        let output = checked_native_einsum_labels(output_ids).map_err(invalid)?;
        let subscripts = EinsumSubscripts { inputs, output };
        let plan = ConcreteEinsumPlan::prepare_read_subscripts(operands, &subscripts)?;
        plan.execute_read(operands, self.engine)
    }

    /// Binary contraction into a caller-provided destination.
    ///
    /// The destination is fully written and is never zero-filled first. The operands
    /// and the destination must already share one dtype: this route does not convert
    /// into a caller-owned output, and a mismatch is rejected typed by the backend.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_einsum::Error::InvalidSubscripts`] when the axis lists are
    /// malformed or of different length, and [`tenferro_einsum::Error::Tensor`] when the
    /// backend rejects the operands, the destination or the contraction.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    /// use tenferro_tensor::TensorWrite;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![5.0_f64, 6.0])?;
    /// let mut out = Tensor::from_vec_col_major(vec![2, 1], vec![0.0_f64, 0.0])?;
    /// context.with_concrete_session(|session| {
    ///     session.contraction_into(&a, &[1], &b, &[0], TensorWrite::Tensor(&mut out))
    /// })??;
    /// assert_eq!(out.as_slice::<f64>()?, &[23.0, 34.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn contraction_into(
        &mut self,
        lhs: &NativeTensor,
        lhs_axes: &[usize],
        rhs: &NativeTensor,
        rhs_axes: &[usize],
        out: tenferro_tensor::TensorWrite<'_>,
    ) -> tenferro_einsum::Result<()> {
        let (lhs_ids, rhs_ids, output_ids) =
            build_binary_einsum_ids(lhs.shape().len(), lhs_axes, rhs.shape().len(), rhs_axes)
                .map_err(|error| tenferro_einsum::Error::InvalidSubscripts {
                    message: format!("{error}"),
                })?;
        let subscripts = EinsumSubscripts {
            inputs: vec![lhs_ids, rhs_ids],
            output: output_ids,
        };
        let inputs = [
            tenferro_tensor::TensorRead::from_tensor(lhs),
            tenferro_tensor::TensorRead::from_tensor(rhs),
        ];
        let plan = ConcreteEinsumPlan::prepare_read_subscripts(&inputs[..], &subscripts)?;
        plan.execute_read_into(&inputs[..], self.engine, out)
    }

    /// Solve `A X = B` for column-major matrices on this session.
    ///
    /// Same kernel, conversion and validation as
    /// [`solve_matrix`](crate::solve_matrix), entered through this session instead of
    /// the process-global one.
    ///
    /// # Errors
    ///
    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
    /// conditions as [`solve_matrix`](crate::solve_matrix).
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Matrix::from_col_major_vec(2, 2, vec![2.0_f64, 0.0, 0.0, 4.0]);
    /// let b = Matrix::from_col_major_vec(2, 1, vec![6.0_f64, 8.0]);
    /// let x = context.with_concrete_session(|session| session.solve_matrix(&a, &b))??;
    /// assert_eq!(x.as_col_major_slice(), &[3.0, 2.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg(feature = "global-defaults")]
    pub fn solve_matrix<T>(
        &mut self,
        a: &crate::matrix::Matrix<T>,
        b: &crate::matrix::Matrix<T>,
    ) -> Result<crate::matrix::Matrix<T>, crate::backend::BackendLinalgError>
    where
        T: crate::backend::BackendLinalgScalar + Copy,
        NativeTensor: From<tenferro::TypedTensor<T>>,
    {
        crate::solve_matrix_in(self.engine, a, b)
    }

    /// Solve a triangular system for column-major matrices on this session.
    ///
    /// Same kernel, conversion and validation as
    /// [`triangular_solve_matrix`](crate::triangular_solve_matrix), entered through this
    /// session instead of the process-global one. `left_side`, `lower`, `transpose_a`
    /// and `unit_diagonal` have the same meaning as on that entry.
    ///
    /// # Errors
    ///
    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
    /// conditions as [`triangular_solve_matrix`](crate::triangular_solve_matrix).
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Matrix::from_col_major_vec(2, 2, vec![2.0_f64, 1.0, 0.0, 4.0]);
    /// let b = Matrix::from_col_major_vec(2, 1, vec![4.0_f64, 4.0]);
    /// let x = context.with_concrete_session(|session| {
    ///     session.triangular_solve_matrix(&a, &b, true, true, false, false)
    /// })??;
    /// assert_eq!(x.as_col_major_slice(), &[2.0, 0.5]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg(feature = "global-defaults")]
    #[allow(clippy::too_many_arguments)]
    pub fn triangular_solve_matrix<T>(
        &mut self,
        a: &crate::matrix::Matrix<T>,
        b: &crate::matrix::Matrix<T>,
        left_side: bool,
        lower: bool,
        transpose_a: bool,
        unit_diagonal: bool,
    ) -> Result<crate::matrix::Matrix<T>, crate::backend::BackendLinalgError>
    where
        T: crate::backend::BackendLinalgScalar + Copy,
        NativeTensor: From<tenferro::TypedTensor<T>>,
    {
        crate::triangular_solve_matrix_in(
            self.engine,
            a,
            b,
            left_side,
            lower,
            transpose_a,
            unit_diagonal,
        )
    }

    /// Complete-pivoting LU decomposition of a column-major matrix on this session.
    ///
    /// Same kernel and conversion as
    /// [`full_piv_lu_matrix`](crate::full_piv_lu_matrix), entered through this session
    /// instead of the process-global one.
    ///
    /// # Errors
    ///
    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
    /// conditions as [`full_piv_lu_matrix`](crate::full_piv_lu_matrix).
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Matrix::from_col_major_vec(2, 2, vec![0.0_f64, 1.0, 2.0, 3.0]);
    /// let factors = context.with_concrete_session(|session| session.full_piv_lu_matrix(&a))??;
    /// assert_eq!(factors.p.nrows(), 2);
    /// assert_eq!(factors.q.ncols(), 2);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg(feature = "global-defaults")]
    pub fn full_piv_lu_matrix<T>(
        &mut self,
        a: &crate::matrix::Matrix<T>,
    ) -> Result<crate::backend::FullPivLuMatrixResult<T>, crate::backend::BackendLinalgError>
    where
        T: crate::backend::BackendLinalgScalar + Copy,
    {
        crate::full_piv_lu_matrix_in(self.engine, a)
    }

    /// Thin/economy QR of a typed tensor on this session.
    ///
    /// Same kernel and conversion as [`qr_backend`](crate::qr_backend), entered through
    /// this session instead of the process-global one.
    ///
    /// # Errors
    ///
    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
    /// conditions as [`qr_backend`](crate::qr_backend).
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::TypedTensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])?;
    /// let (q, r) = context.with_concrete_session(|session| session.qr_backend(a))??;
    /// assert_eq!(q.shape(), &[2, 2]);
    /// assert_eq!(r.shape(), &[2, 2]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg(feature = "global-defaults")]
    pub fn qr_backend<T>(
        &mut self,
        a: tenferro::TypedTensor<T>,
    ) -> Result<
        (tenferro::TypedTensor<T>, tenferro::TypedTensor<T>),
        crate::backend::BackendLinalgError,
    >
    where
        T: crate::backend::BackendLinalgScalar,
    {
        use tenferro::TensorScalar;

        let (shape, data) = a.into_vec_col_major().map_err(|error| {
            crate::backend::BackendLinalgError::from(anyhow::anyhow!(
                "QR input host access failed: {error}"
            ))
        })?;
        let tensor: NativeTensor =
            <T as TensorScalar>::into_tensor(shape, data).map_err(|error| {
                crate::backend::BackendLinalgError::from(anyhow::anyhow!(
                    "QR input tensor construction failed: {error}"
                ))
            })?;
        crate::qr_backend_in(self.engine, tensor)
    }

    /// Thin/economy SVD of a typed tensor on this session.
    ///
    /// Same kernel and conversion as [`svd_backend`](crate::svd_backend), entered through
    /// this session instead of the process-global one.
    ///
    /// # Errors
    ///
    /// Returns [`BackendLinalgError`](crate::BackendLinalgError) under the same
    /// conditions as [`svd_backend`](crate::svd_backend).
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::TypedTensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![3.0, 0.0, 0.0, 2.0])?;
    /// let factors = context.with_concrete_session(|session| session.svd_backend(&a))??;
    /// assert_eq!(factors.s().as_slice()?, &[3.0, 2.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg(feature = "global-defaults")]
    pub fn svd_backend<T>(
        &mut self,
        a: &tenferro::TypedTensor<T>,
    ) -> Result<crate::backend::SvdResult<T>, crate::backend::BackendLinalgError>
    where
        T: crate::backend::BackendLinalgScalar,
    {
        use tenferro::TensorScalar;

        let tensor: NativeTensor = <T as TensorScalar>::into_tensor(
            a.shape().to_vec(),
            a.host_data()
                .map_err(|error| {
                    crate::backend::BackendLinalgError::from(anyhow::anyhow!(
                        "SVD input host access failed: {error}"
                    ))
                })?
                .to_vec(),
        )
        .map_err(|error| {
            crate::backend::BackendLinalgError::from(anyhow::anyhow!(
                "SVD input tensor construction failed: {error}"
            ))
        })?;
        crate::svd_backend_in(self.engine, tensor)
    }

    /// Matrix multiplication `A * B` on this session.
    ///
    /// The same kernel and shape validation as
    /// [`mat_mul`](crate::mat_mul), entered through this session instead of the
    /// process-global one, and returning the shared
    /// [`Matrix`](crate::Matrix) container.
    ///
    /// # Errors
    ///
    /// Returns [`MatrixMulError`](crate::MatrixMulError) when the shapes disagree or
    /// the session operation fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::{CpuExecutionContext, Matrix};
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Matrix::from_col_major_vec(2, 2, vec![1.0_f64, 2.0, 3.0, 4.0]);
    /// let b = Matrix::from_col_major_vec(2, 2, vec![1.0_f64, 0.0, 0.0, 1.0]);
    /// let c = context.with_concrete_session(|session| session.mat_mul(&a, &b))??;
    /// assert_eq!(c.as_col_major_slice(), &[1.0, 2.0, 3.0, 4.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[cfg(feature = "global-defaults")]
    pub fn mat_mul<T: crate::matrix::BlasMul>(
        &mut self,
        a: &crate::matrix::Matrix<T>,
        b: &crate::matrix::Matrix<T>,
    ) -> Result<crate::matrix::Matrix<T>, crate::matrix::MatrixMulError> {
        crate::mat_mul_in(self.engine, a, b)
    }

    /// Thin/economy QR decomposition.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] for an unsupported dtype or
    /// rank, and [`tenferro_tensor::Error::BackendSource`] when the factorization
    /// itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let (q, r) = context.with_concrete_session(|session| session.qr(&a))??;
    /// // `A = Q R` is reproduced to rounding, which is the correctness property
    /// // of a factorization.
    /// let reconstructed =
    ///     context.with_concrete_session(|session| session.contraction(&q, &[1], &r, &[0]))??;
    /// for (got, want) in reconstructed.as_slice::<f64>()?.iter().zip([1.0, 2.0, 3.0, 4.0]) {
    ///     assert!((got - want).abs() < 1e-12, "got {got}, want {want}");
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn qr(
        &mut self,
        tensor: &NativeTensor,
    ) -> tenferro_tensor::Result<(NativeTensor, NativeTensor)> {
        tensor.qr(self.engine)
    }

    /// Thin/economy SVD.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] for an unsupported dtype or
    /// rank, and [`tenferro_tensor::Error::BackendSource`] when the factorization
    /// itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![3.0_f64, 0.0, 0.0, 2.0])?;
    /// let (u, s, vt) = context.with_concrete_session(|session| session.svd(&a))??;
    /// // The singular values of diag(3, 2) are 3 and 2.
    /// assert_eq!(s.as_slice::<f64>()?, &[3.0, 2.0]);
    /// assert_eq!(u.shape(), &[2, 2]);
    /// assert_eq!(vt.shape(), &[2, 2]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn svd(
        &mut self,
        tensor: &NativeTensor,
    ) -> tenferro_tensor::Result<(NativeTensor, NativeTensor, NativeTensor)> {
        tensor.svd(self.engine)
    }

    /// Solve `A X = B` for a square `A`.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] when `lhs` is not square, when
    /// the operands have mismatched shapes, or for an unsupported dtype, and
    /// [`tenferro_tensor::Error::BackendSource`] when the solve itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![2.0_f64, 0.0, 0.0, 4.0])?;
    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![6.0_f64, 8.0])?;
    /// let x = context.with_concrete_session(|session| session.solve(&a, &b))??;
    /// assert_eq!(x.as_slice::<f64>()?, &[3.0, 2.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn solve(
        &mut self,
        lhs: &NativeTensor,
        rhs: &NativeTensor,
    ) -> tenferro_tensor::Result<NativeTensor> {
        lhs.solve(rhs, self.engine)
    }

    /// Solve `A X = B` where `A` is triangular.
    ///
    /// - `left_side`: solve `A X = B` when true, `X A = B` when false;
    /// - `lower`: `A` is lower triangular;
    /// - `transpose_a`: solve with `A` transposed;
    /// - `unit_diagonal`: treat the diagonal of `A` as one, ignoring the stored
    ///   values.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] for a shape mismatch or an
    /// unsupported dtype, and [`tenferro_tensor::Error::BackendSource`] when the solve
    /// itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// // Lower triangular, column-major.
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![2.0_f64, 1.0, 0.0, 4.0])?;
    /// let b = Tensor::from_vec_col_major(vec![2, 1], vec![4.0_f64, 4.0])?;
    /// let x = context.with_concrete_session(|session| {
    ///     session.triangular_solve(&a, &b, true, true, false, false)
    /// })??;
    /// assert_eq!(x.as_slice::<f64>()?, &[2.0, 0.5]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn triangular_solve(
        &mut self,
        lhs: &NativeTensor,
        rhs: &NativeTensor,
        left_side: bool,
        lower: bool,
        transpose_a: bool,
        unit_diagonal: bool,
    ) -> tenferro_tensor::Result<NativeTensor> {
        lhs.triangular_solve(
            rhs,
            left_side,
            lower,
            transpose_a,
            unit_diagonal,
            self.engine,
        )
    }

    /// Full-pivoting LU decomposition `P A Q = L U`, returning
    /// `(P, L, U, Q, parity)`.
    ///
    /// # Errors
    ///
    /// Returns [`tenferro_tensor::Error::Validation`] for a non-square `A` or an
    /// unsupported dtype, and [`tenferro_tensor::Error::BackendSource`] when the
    /// factorization itself fails.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
    /// let (p, l, u, q, _parity) = context
    ///     .with_concrete_session(|session| session.full_piv_lu(&a))?
    ///     .expect("full-pivoting LU");
    /// for factor in [&p, &l, &u, &q] {
    ///     assert_eq!(factor.shape(), &[2, 2]);
    /// }
    /// // Column-major, so index 0 is (0, 0), index 1 is (1, 0) and index 2 is (0, 1).
    /// let l = l.as_slice::<f64>()?;
    /// let u = u.as_slice::<f64>()?;
    /// assert_eq!(l[2], 0.0, "L is lower triangular");
    /// assert_eq!(u[1], 0.0, "U is upper triangular");
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn full_piv_lu(
        &mut self,
        tensor: &NativeTensor,
    ) -> tenferro_tensor::Result<(
        NativeTensor,
        NativeTensor,
        NativeTensor,
        NativeTensor,
        NativeTensor,
    )> {
        tensor.full_piv_lu(self.engine)
    }
}

impl CpuExecutionContext {
    /// Run `f` inside one explicit concrete session of this context.
    ///
    /// The context's engine is borrowed once for the whole closure, so a stage
    /// borrows it once and reuses its prepared plans and buffer pool. All routes on
    /// the [`Session`] run on that engine only: nothing here consults the
    /// process-global default context, and nothing falls back to it.
    ///
    /// # Examples
    ///
    /// ```
    /// use tensor4all_tensorbackend::CpuExecutionContext;
    /// use tenferro::Tensor;
    /// use tensor4all_tensorbackend::CpuBackend;
    ///
    /// let context = CpuExecutionContext::from_backend(CpuBackend::with_threads(1)?);
    /// let x = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 3.0])?;
    /// let doubled = context.with_concrete_session(|session| session.reshape(&x, &[2]))??;
    /// assert_eq!(doubled.as_slice::<f64>()?, &[1.0, 3.0]);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`CpuExecutionContextError::Reentered`] when the calling thread is
    /// already inside a session of this context. A session entered from a Rayon
    /// worker runs inline on a serial engine that shares the context engine's
    /// prepared-plan cache, so a worker entry completes instead of waiting for a
    /// pool it belongs to (tensor4all-rs#830).
    ///
    /// # Panics
    ///
    /// Never. A panic in `f` propagates after the engine borrow is released.
    pub fn with_concrete_session<R>(
        &self,
        f: impl FnOnce(&mut Session<'_>) -> R,
    ) -> Result<R, CpuExecutionContextError> {
        self.with_session(|engine| f(&mut Session::new(engine)))
    }
}

#[cfg(test)]
mod tests;