incin-core 0.1.0

Core tensor operations and static shape checking for incin
Documentation
//! Tensor axis permutation and transposition operations.

use crate::backend_authoring::{Backend, Execute};
use crate::dist::placement::Local;
use crate::err::Result;
use crate::exec::Capabilities;
use crate::exec::catalog::{TransposeAttributes, op};
use crate::exec::dispatch;
use crate::exec::request::TensorHandle;
use crate::shapes::idx::StaticCursor;
use crate::shapes::{DynShape, Shape, ShapeBuf, ShapeValue, SwapAxes};
use crate::tensor::base::Tensor;
use crate::tensor::grad::RequiresGrad;
use crate::tensor::ops::manipulation::selectors::AxisPairSelector;

impl<S: Shape + DynShape, B: Backend, K: crate::tensor::dtype::DType, G: RequiresGrad>
    Tensor<S, B, K, G>
{
    /// Transposes two axis selectors while preserving the strongest available
    /// output shape proof.
    #[allow(clippy::type_complexity)]
    pub fn transpose<L, R>(
        &self,
        left: L,
        right: R,
    ) -> Result<Tensor<<() as AxisPairSelector<S, L, R>>::Output, B, K, G>>
    where
        (): AxisPairSelector<S, L, R>,
        B: Execute<op::TransposeExact> + Capabilities,
        <B as Execute<op::TransposeExact>>::Output: Into<B::Storage<K>>,
    {
        let (first, second) =
            <() as AxisPairSelector<S, L, R>>::resolve(&(left, right), self.shape_buf().rank())?;
        let mut out_dims = self.shape_buf().as_ref().to_vec();
        out_dims.swap(first, second);
        let output_shape = ShapeValue::<<() as AxisPairSelector<S, L, R>>::Output>::try_new(
            ShapeBuf::from_slice(&out_dims),
        )
        .map_err(crate::err::Error::Shape)?;
        let input = TensorHandle::from_storage::<B, K, Local>(&self.inner);
        let context = crate::tensor::grad::execution_context::<B, G>(&self._grad);
        let inner = G::grad_mode(&self._grad).restrict(|| {
            dispatch::execute_shaped::<
                op::TransposeExact,
                B,
                <() as AxisPairSelector<S, L, R>>::Output,
            >(
                &context,
                TransposeAttributes { first, second },
                &[input],
                &output_shape,
            )
        })?;
        Tensor::from_shape_value(
            inner.into(),
            output_shape,
            self._dtype.clone(),
            self._device.clone(),
            self._grad.clone(),
        )
    }

    /// Advanced structural transpose retained for shape-proof internals.
    #[allow(clippy::type_complexity)]
    pub fn transpose_structural<L, R>(
        &self,
    ) -> Result<Tensor<<S as SwapAxes<L, R>>::Output, B, K, G>>
    where
        L: StaticCursor,
        R: StaticCursor,
        S: SwapAxes<L, R>,
        <S as SwapAxes<L, R>>::Output: Shape + DynShape,
        B: Execute<op::TransposeExact> + Capabilities,
        <B as Execute<op::TransposeExact>>::Output: Into<B::Storage<K>>,
    {
        let axes = crate::shapes::idx::AxisSelector::new(&[L::INDEX, R::INDEX])
            .normalize(self.shape_buf().rank())?;
        let mut out_dims = self.shape_buf().as_ref().to_vec();
        out_dims.swap(axes[0], axes[1]);
        let output_shape =
            ShapeValue::<<S as SwapAxes<L, R>>::Output>::try_new(ShapeBuf::from_slice(&out_dims))
                .map_err(crate::err::Error::Shape)?;
        let input = TensorHandle::from_storage::<B, K, Local>(&self.inner);
        let context = crate::tensor::grad::execution_context::<B, G>(&self._grad);
        let inner = G::grad_mode(&self._grad)
            .restrict(|| {
                dispatch::execute_shaped::<op::TransposeExact, B, <S as SwapAxes<L, R>>::Output>(
                    &context,
                    TransposeAttributes {
                        first: axes[0],
                        second: axes[1],
                    },
                    &[input],
                    &output_shape,
                )
            })?
            .into();
        Tensor::<<S as SwapAxes<L, R>>::Output, B, K, G>::from_shape_value(
            inner,
            output_shape,
            self._dtype.clone(),
            self._device.clone(),
            self._grad.clone(),
        )
    }

    /// Runtime-selector transpose. Known input rank is preserved in the
    /// result; a fully dynamic input remains fully dynamic.
    #[doc(hidden)]
    pub fn transpose_runtime(&self, left: isize, right: isize) -> Result<Tensor<S::Keep, B, K, G>>
    where
        S: crate::shapes::RuntimeRankProjection,
        S::Keep: Shape + DynShape,
        B: Execute<op::TransposeExact> + Capabilities,
        <B as Execute<op::TransposeExact>>::Output: Into<B::Storage<K>>,
    {
        let (first, second) = <() as AxisPairSelector<S, isize, isize>>::resolve(
            &(left, right),
            self.shape_buf().rank(),
        )?;
        let mut out_dims = self.shape_buf().as_ref().to_vec();
        out_dims.swap(first, second);
        let output_shape = ShapeValue::<S::Keep>::try_new(ShapeBuf::from_slice(&out_dims))
            .map_err(crate::err::Error::Shape)?;
        let input = TensorHandle::from_storage::<B, K, Local>(&self.inner);
        let context = crate::tensor::grad::execution_context::<B, G>(&self._grad);
        let inner = G::grad_mode(&self._grad)
            .restrict(|| {
                dispatch::execute_shaped::<op::TransposeExact, B, S::Keep>(
                    &context,
                    TransposeAttributes { first, second },
                    &[input],
                    &output_shape,
                )
            })?
            .into();
        Tensor::from_shape_value(
            inner,
            output_shape,
            self._dtype.clone(),
            self._device.clone(),
            self._grad.clone(),
        )
    }
}