Trait TensorStructural 

pub trait TensorStructural {
    // Required methods
    fn transpose(&mut self, input: &Tensor, perm: &[usize]) -> Result<Tensor>;
    fn reshape(&mut self, input: &Tensor, shape: &[usize]) -> Result<Tensor>;
    fn broadcast_in_dim(
        &mut self,
        input: &Tensor,
        shape: &[usize],
        dims: &[usize],
    ) -> Result<Tensor>;
    fn cast(&mut self, input: &Tensor, to: DType) -> Result<Tensor>;
    fn extract_diagonal(
        &mut self,
        input: &Tensor,
        axis_a: usize,
        axis_b: usize,
    ) -> Result<Tensor>;
    fn embed_diagonal(
        &mut self,
        input: &Tensor,
        axis_a: usize,
        axis_b: usize,
    ) -> Result<Tensor>;
    fn tril(&mut self, input: &Tensor, k: i64) -> Result<Tensor>;
    fn triu(&mut self, input: &Tensor, k: i64) -> Result<Tensor>;

    // Provided methods
    fn to_contiguous_read(&mut self, input: TensorRead<'_>) -> Result<Tensor> { ... }
    fn copy_read_into(
        &mut self,
        _src: TensorRead<'_>,
        _dst: TensorWrite<'_>,
    ) -> Result<()> { ... }
    fn transpose_read(
        &mut self,
        input: TensorRead<'_>,
        perm: &[usize],
    ) -> Result<Tensor> { ... }
    fn reshape_read(
        &mut self,
        input: TensorRead<'_>,
        shape: &[usize],
    ) -> Result<Tensor> { ... }
    fn broadcast_in_dim_read(
        &mut self,
        input: TensorRead<'_>,
        shape: &[usize],
        dims: &[usize],
    ) -> Result<Tensor> { ... }
    fn convert(&mut self, input: &Tensor, to: DType) -> Result<Tensor> { ... }
}

Shape, layout, and dtype transformation operations.

Examples

use tenferro_tensor::TensorStructural;

fn accepts_structural<B: TensorStructural>(_backend: &mut B) {}

Required Methods

fn transpose(&mut self, input: &Tensor, perm: &[usize]) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn reshape(&mut self, input: &Tensor, shape: &[usize]) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn broadcast_in_dim( &mut self, input: &Tensor, shape: &[usize], dims: &[usize], ) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn cast(&mut self, input: &Tensor, to: DType) -> Result<Tensor>

Cast a tensor to another dtype using explicit dtype projection.

Backends may truncate, narrow precision, project complex values, or use boolean truthiness according to their documented cast support.

Examples

use tenferro_tensor::{DType, Tensor, TensorStructural};

fn cast_to_i32<B: TensorStructural>(
    backend: &mut B,
    input: &Tensor,
) -> tenferro_tensor::Result<Tensor> {
    backend.cast(input, DType::I32)
}

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn extract_diagonal( &mut self, input: &Tensor, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn embed_diagonal( &mut self, input: &Tensor, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn tril(&mut self, input: &Tensor, k: i64) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn triu(&mut self, input: &Tensor, k: i64) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

Provided Methods

fn to_contiguous_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Materialize an owned tensor or borrowed view into fresh compact storage.

The result has the input’s shape and dtype, uses compact column-major layout, and remains in the input’s placement. This operation is a same-placement canonicalization boundary, never an implicit host/device transfer. The conservative default accepts only compact host-owned tensors and clones them; it rejects views, backend buffers, and device placement because only an owning backend can materialize those safely.

Backend overrides may accept strided views. CUDA accepts numeric and complex views on its active device, including arbitrary valid strides, but currently reports an explicit unsupported-dtype error for Bool.

Examples

use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural};

struct HostDefaults;
impl TensorStructural for HostDefaults {
    fn transpose(&mut self, _: &Tensor, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn reshape(&mut self, _: &Tensor, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn broadcast_in_dim(&mut self, _: &Tensor, _: &[usize], _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn cast(&mut self, _: &Tensor, _: DType) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn extract_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn embed_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn tril(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn triu(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
}

let input = Tensor::from_vec_col_major(vec![2], vec![1_i32, 2])?;
let mut backend = HostDefaults;
let structural: &mut dyn TensorStructural = &mut backend;
let output = structural.to_contiguous_read(TensorRead::from_tensor(&input))?;
assert_eq!(output.shape(), &[2]);
assert_eq!(output.as_slice::<i32>()?, &[1, 2]);

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn copy_read_into( &mut self, _src: TensorRead<'_>, _dst: TensorWrite<'_>, ) -> Result<()>

Overwrite caller-provided storage from a readable tensor or view.

Source and destination must have identical dtype and shape and belong to the executing backend’s placement. The destination is not resized, and every logical destination element is overwritten without reading its old value. Source and destination allocations must not alias. Implementations must not materialize through host memory or perform an implicit transfer.

CPU accepts arbitrary valid source and destination strides and performs no tensor allocation. CUDA currently accepts only a compact column-major source with offset zero covering its full allocation; CUDA destinations may be arbitrary valid non-overlapping views. CUDA rejects aliased allocations and currently reports an explicit unsupported-dtype error for Bool. The conservative default is explicitly unsupported.

Examples

use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural, TensorWrite};

struct ConservativeDefaults;
impl TensorStructural for ConservativeDefaults {
    fn transpose(&mut self, _: &Tensor, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn reshape(&mut self, _: &Tensor, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn broadcast_in_dim(&mut self, _: &Tensor, _: &[usize], _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn cast(&mut self, _: &Tensor, _: DType) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn extract_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn embed_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn tril(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    fn triu(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
}

let src = Tensor::from_vec_col_major(vec![2], vec![1_i32, 2])?;
let mut dst = Tensor::from_vec_col_major(vec![2], vec![0_i32, 0])?;
let mut backend = ConservativeDefaults;
let structural: &mut dyn TensorStructural = &mut backend;
let error = structural.copy_read_into(
    TensorRead::from_tensor(&src),
    TensorWrite::from_tensor(&mut dst),
).unwrap_err();
assert!(error.to_string().contains("unsupported"));
assert_eq!(dst.as_slice::<i32>()?, &[0, 0]);

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn transpose_read( &mut self, input: TensorRead<'_>, perm: &[usize], ) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn reshape_read( &mut self, input: TensorRead<'_>, shape: &[usize], ) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn broadcast_in_dim_read( &mut self, input: TensorRead<'_>, shape: &[usize], dims: &[usize], ) -> Result<Tensor>

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

fn convert(&mut self, input: &Tensor, to: DType) -> Result<Tensor>

Convert a tensor to another dtype using checked dtype conversion.

convert accepts only conversions allowed by tenferro’s dtype-promotion lattice. Use TensorStructural::cast for explicit lossy projection.

Examples

use tenferro_tensor::{DType, Tensor, TensorStructural};

fn convert_to_f64<B: TensorStructural>(
    backend: &mut B,
    input: &Tensor,
) -> tenferro_tensor::Result<Tensor> {
    backend.convert(input, DType::F64)
}

Errors

Returns crate::Error::Validation with a typed ValidationError source for invalid shapes, ranks, axes, dtypes, or output metadata. It returns crate::Error::BackendFailure or crate::Error::BackendSource when backend execution or storage access cannot provide the requested result.

Implementors