### Install Tensor Frame

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/getting-started.md

Add Tensor Frame to your Cargo.toml file to include it as a dependency in your Rust project.

```toml
[dependencies]
tensor_frame = "0.0.2-alpha"
```

--------------------------------

### Create and Inspect Tensors

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/getting-started.md

Demonstrates how to create tensors using various initialization methods like zeros, ones, and from_vec, and how to inspect their properties such as shape, number of elements, and dimensions.

```rust
use tensor_frame::{Tensor, Result};

fn main() -> Result<()> {
    // Create tensors with different initialization
    let zeros = Tensor::zeros(vec![2, 3])?;
    let ones = Tensor::ones(vec![2, 3])?;
    let from_data = Tensor::from_vec(
        vec![1.0, 2.0, 3.0, 4.0], 
        vec![2, 2]
    )?;
    
    // Inspect tensor properties
    println!("Shape: {:?}", zeros.shape().dims());
    println!("Number of elements: {}", zeros.numel());
    println!("Number of dimensions: {}", zeros.ndim());
    
    Ok(())
}
```

--------------------------------

### Bash: Running Tensor Frame Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Provides commands for executing Tensor Frame examples using Cargo, including options for specifying features like WGPU or CUDA backends. Assumes a standard Cargo project structure.

```bash
# Run basic operations example
cargo run --example basic_operations

# Run with specific backend
cargo run --example basic_operations --features wgpu
cargo run --example basic_operations --features cuda

# Run with all features
cargo run --example basic_operations --features "wgpu,cuda"
```

--------------------------------

### Bash: Interactive and Parameterized Example Execution

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Shows how to run Tensor Frame examples interactively or with specific parameters like tensor size and backend using Cargo command-line arguments. Assumes examples support these arguments.

```bash
# Interactive tensor exploration
cargo run --example interactive

# Performance testing with different sizes
cargo run --example benchmark -- --size 1000
cargo run --example benchmark -- --size 2000 --backend cuda
```

--------------------------------

### Tensor Frame with Feature Flags

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/getting-started.md

Configure Tensor Frame with optional feature flags for different backend support, such as WGPU for GPU acceleration or CUDA for NVIDIA GPU support.

```toml
# CPU only (default)
tensor_frame = "0.0.2-alpha"

# With WGPU support
tensor_frame = { version = "0.0.2-alpha", features = ["wgpu"] }

# With CUDA support  
tensor_frame = { version = "0.0.2-alpha", features = ["cuda"] }

# All backends
tensor_frame = { version = "0.0.2-alpha", features = ["wgpu", "cuda"] }
```

--------------------------------

### Tensor Manipulation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/getting-started.md

Shows how to perform common tensor manipulation tasks, including reshaping, transposing (for 2D tensors), squeezing, and unsqueezing dimensions.

```rust
use tensor_frame::{Tensor, Result, TensorOps};

fn main() -> Result<()> {
    let tensor = Tensor::from_vec(
        vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
        vec![2, 3]
    )?;
    
    // Reshape
    let reshaped = tensor.reshape(vec![3, 2])?;
    
    // Transpose (2D only for now)
    let transposed = reshaped.transpose()?;
    
    // Squeeze and unsqueeze
    let squeezed = tensor.squeeze(None)?;
    let unsqueezed = squeezed.unsqueeze(0)?;
    
    Ok(())
}
```

--------------------------------

### Basic Tensor Operations

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/getting-started.md

Illustrates fundamental element-wise operations (addition, subtraction, multiplication, division) and reduction operations (sum, mean) on tensors.

```rust
use tensor_frame::{Tensor, Result};

fn main() -> Result<()> {
    let a = Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0], vec![2, 2])?;
    let b = Tensor::from_vec(vec![5.0, 6.0, 7.0, 8.0], vec![2, 2])?;
    
    // Element-wise operations
    let sum = (a.clone() + b.clone())?;
    let diff = (a.clone() - b.clone())?;
    let product = (a.clone() * b.clone())?;
    let quotient = (a / b)?;
    
    // Reduction operations
    let total = sum.sum(None)?;
    let average = product.mean(None)?;
    
    println!("Sum result: {:?}", total.to_vec()?);
    
    Ok(())
}
```

--------------------------------

### Install Rust and Development Dependencies

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Instructions for installing Rust using rustup and essential development tools like mdbook, criterion, rustfmt, and clippy.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

cargo install mdbook
cargo install criterion

rustup component add rustfmt
rustup component add clippy
```

--------------------------------

### Broadcasting Tensors

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/getting-started.md

Demonstrates Tensor Frame's automatic broadcasting capabilities, allowing operations between tensors with compatible shapes, similar to NumPy and PyTorch.

```rust
use tensor_frame::{Tensor, Result};

fn main() -> Result<()> {
    let a = Tensor::ones(vec![2, 1])?;
    let b = Tensor::ones(vec![1, 3])?;
    
    // Broadcasting: [2, 1] + [1, 3] -> [2, 3]
    let c = (a + b)?;
    println!("Result shape: {:?}", c.shape().dims());
    
    Ok(())
}
```

--------------------------------

### Clone and Setup Tensor Frame Repository

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Steps to clone the Tensor Frame repository and navigate into the project directory.

```bash
git clone https://github.com/TrainPioneers/Tensor-Frame.git
cd Tensor-Frame
```

--------------------------------

### Install Rust and Dependencies

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Installs Rust using rustup and essential development tools like Criterion, rustfmt, and clippy.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

cargo install criterion

rustup component add rustfmt

rustup component add clippy
```

--------------------------------

### CPU Backend Usage Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/README.md

Provides examples of when the CPU backend is suitable, including small tensors, development, and scalar operations. Also notes when to avoid it.

```rust
// Good for:
let small_tensor = Tensor::ones(vec![10, 10])?;
let dev_tensor = Tensor::zeros(vec![100])?;
let scalar_ops = tensor.sum(None)?;

// Avoid for:
// - Large matrix multiplications (> 1000x1000)
// - Batch operations on many tensors
// - Compute-intensive element-wise operations
```

--------------------------------

### Install mdBook

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/README.md

Installs the mdBook tool, which is used for building and serving the documentation. This command requires Cargo, the Rust package manager.

```bash
cargo install mdbook
```

--------------------------------

### Clone and Setup Repository

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Clones the Tensor Frame repository and navigates into the project directory.

```bash
git clone https://github.com/TrainPioneers/Tensor-Frame.git
cd Tensor-Frame
```

--------------------------------

### Changelog Entry Example

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

An example of how to format a changelog entry, detailing added features and fixed bugs with references to issue numbers.

```markdown
## [Unreleased]
### Added
- New tensor operation `my_operation` (#123)
### Fixed  
- Fixed broadcasting bug in GPU backend (#124)
```

--------------------------------

### Performance Comparison Examples in Rust

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/basic.md

Provides a basic setup for comparing the performance of tensor operations, starting with small tensors where CPU operations are expected to be faster.

```rust
/// Demonstrates performance characteristics
fn performance_comparison() -> Result<()> {
    println!("=== Performance Comparison ===");
    
    // Small tensor operations (CPU should be faster)
    let small_a = Tensor::ones(vec![100, 100])?;
    let small_b = Tensor::ones(vec![100, 100])?;
    
    let start = Instant::now();
    let result = &small_a + &small_b;
    // Note: The rest of the performance comparison logic would follow here.
```

--------------------------------

### Nsight Compute Kernel Analysis

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/performance.md

Example command to launch Nsight Compute for analyzing kernel performance. It targets the 'sm__throughput.avg.pct_of_peak_sustained_elapsed' metric for a given application executable.

```bash
ncu --metrics sm__throughput.avg.pct_of_peak_sustained_elapsed ./your_app
```

--------------------------------

### Tensor Frame WGPU Backend Installation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/wgpu.md

Instructions on how to enable the WGPU backend for the tensor_frame crate using Cargo feature flags.

```toml
[dependencies]
tensor_frame = { version = "0.0.2-alpha", features = ["wgpu"] }
```

--------------------------------

### CPU Profiling with `Instant` and `flamegraph`

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/performance.md

Shows how to profile CPU-bound operations in Rust using `std::time::Instant` for basic timing and the `flamegraph` tool for more detailed performance analysis. Instructions for installing and using `flamegraph` are included.

```rust
// Use built-in timing
use std::time::Instant;

let start = Instant::now();
let result = expensive_operation()?;
println!("Operation took: {:?}", start.elapsed());

// Use external profilers
// cargo install flamegraph
// cargo flamegraph --bin your_app
```

--------------------------------

### Rust Documentation Example for Tensor Creation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Illustrates Rust documentation comments for a `zeros` function, including arguments, return values, examples, and error conditions.

```rust
/// Creates a new tensor filled with zeros.
///
/// # Arguments
/// * `shape` - The dimensions of the tensor
///
/// # Returns
/// A new tensor filled with zeros, or an error if the shape is invalid.
///
/// # Examples
/// ```
/// use tensor_frame::Tensor;
/// 
/// let tensor = Tensor::zeros(vec![2, 3])?;
/// assert_eq!(tensor.numel(), 6);
/// # Ok::<(), tensor_frame::TensorError>(())
/// ```
///
/// # Errors
/// Returns `TensorError::InvalidShape` if any dimension is zero.
pub fn zeros(shape: Vec<usize>) -> Result<Self> {
    // Implementation
}
```

--------------------------------

### Handling Backend Compatibility for Operations

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Provides a solution for cases where a specific operation is not supported on a particular backend (e.g., WGPU). It shows how to fall back to a compatible backend like CPU.

```rust
// Problem: Operation not supported on backend
let result = match tensor.backend_type() {
    BackendType::Wgpu => {
        // Some operations not yet implemented on WGPU
        tensor.to_backend(BackendType::Cpu)?.complex_operation()? // Assuming complex_operation exists
    }
    _ => tensor.complex_operation()?,
};
result
```

--------------------------------

### Rust: Demonstrating Tensor Broadcasting

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Explains and demonstrates tensor broadcasting with examples of scalar, vector, and matrix broadcasting. Shows how operations between tensors of different shapes are handled. Requires `Tensor`.

```rust
use tensor_frame::Tensor;

fn demonstrate_broadcasting() -> Result<()> {
    // Scalar broadcast
    let tensor = Tensor::ones(vec![3, 4])?;
    let scaled = tensor * 2.0;  // Scalar broadcasts to all elements
    
    // Vector broadcast
    let matrix = Tensor::ones(vec![3, 4])?;
    let vector = Tensor::ones(vec![4])?;
    let result = matrix + vector;             // Broadcasts to [3, 4]
    
    // Matrix broadcast
    let a = Tensor::ones(vec![3, 1])?;
    let b = Tensor::ones(vec![1, 4])?;
    let result = a + b;                       // Result: [3, 4]
    
    Ok(())
}
```

--------------------------------

### Tensor Frame Example Usage

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/README.md

A basic example demonstrating the creation of a Tensor with zeros using the Tensor Frame library. It shows how to instantiate a Tensor and print its representation.

```rust
use tensor_frame::Tensor;

fn example() -> Result<()> {
    let tensor = Tensor::zeros(vec![2, 3])?;
    println!("Created: {}", tensor);
    Ok(())
}
```

--------------------------------

### Profiling CPU Backend with Flamegraph

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/cpu.md

Provides instructions on installing and using `flamegraph` to profile Rust applications utilizing the CPU backend.

```bash
# Install flamegraph
cargo install flamegraph

# Profile your application  
cargo flamegraph --bin your_app
```

--------------------------------

### WGPU Backend Usage Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/README.md

Shows use cases for the WGPU backend, such as large tensors, batch operations, and complex element-wise computations. Also suggests when to consider it.

```rust
// Good for:
let large_tensor = Tensor::zeros(vec![2048, 2048])?;
let batch_ops = tensors.iter().map(|t| t * 2.0);
let element_wise = (a * b) + c;

// Consider for:
// - Cross-platform deployment
// - When CUDA is not available
// - Mixed CPU/GPU workloads
```

--------------------------------

### Efficient Batched Tensor Processing

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Processes a batch of tensors efficiently by converting them to a common backend (WGPU in this example) before applying an expensive operation. Includes error handling for backend conversion and processing.

```rust
fn process_batch_efficiently(inputs: Vec<Tensor>) -> Result<Vec<Tensor>> {
    // Convert all inputs to same backend
    let backend = BackendType::Wgpu;
    let gpu_inputs: Result<Vec<_>> = inputs
        .into_iter()
        .map(|t| t.to_backend(backend))
        .collect();
    
    // Process on GPU
    let gpu_outputs: Result<Vec<_>> = gpu_inputs?
        .into_iter()
        .map(|input| expensive_operation(input)) // Assuming expensive_operation exists
        .collect();
    
    gpu_outputs
}
```

--------------------------------

### CPU Tensor Memory Allocation Example

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/cpu.md

Demonstrates the allocation of a CPU tensor, illustrating the direct memory allocation from the system heap.

```rust
let tensor = Tensor::zeros(vec![1000, 1000])?;  // Allocates 4MB
```

--------------------------------

### Tensor Frame Zero Initialization Documentation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Rust documentation example for a `zeros` function that creates a tensor filled with zeros, including arguments, return values, examples, and error conditions.

```rust
/// Creates a new tensor filled with zeros.
///
/// # Arguments
/// * `shape` - The dimensions of the tensor
///
/// # Returns
/// A new tensor filled with zeros, or an error if the shape is invalid.
///
/// # Examples
/// ```
/// use tensor_frame::Tensor;
/// 
/// let tensor = Tensor::zeros(vec![2, 3])?;
/// assert_eq!(tensor.numel(), 6);
/// # Ok::<(), tensor_frame::TensorError>(())
/// ```
///
/// # Errors
/// Returns `TensorError::InvalidShape` if any dimension is zero.
pub fn zeros(shape: Vec<usize>) -> Result<Self> {
    // Implementation
}
```

--------------------------------

### Optimal Use Cases for CPU Backend

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/cpu.md

Provides examples of scenarios where the CPU backend is performant, including small to medium tensors, scalar reductions, and development.

```rust
// Small to medium tensors (< 10K elements)
let small = Tensor::ones(vec![100, 100])?;
```

```rust
// Scalar reductions
let sum = large_tensor.sum(None)?;
```

```rust
// Development and prototyping
let test_tensor = Tensor::from_vec(test_data, shape)?;
```

--------------------------------

### WGPU Backend for Large Element-wise Operations

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/performance.md

Illustrates using the WGPU backend for large element-wise operations, emphasizing its massive parallelism and cross-platform deployment capabilities.

```rust
use tensor_frame::Tensor;
// WGPU optimal: Large parallel operations
let large = Tensor::ones(vec![2048, 2048])?\
    .to_backend(BackendType::Wgpu)?;
let result = (large_a * large_b) + large_c;
```

--------------------------------

### CPU Backend for Small Tensors

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/performance.md

Demonstrates using the CPU backend for small tensors and scalar operations, highlighting its low latency and suitability for development.

```rust
use tensor_frame::Tensor;
// CPU optimal: Small tensors and scalar operations
let small = Tensor::ones(vec![100, 100])?;
let result = small.sum(None)?;
```

--------------------------------

### WGPU GPU Memory Allocation Example

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/wgpu.md

Shows how WGPU manages GPU memory allocation for tensors, illustrating the creation of a tensor and the approximate memory usage on the GPU.

```rust
let tensor = Tensor::zeros(vec![2048, 2048])?  // Allocates ~16MB GPU memory
```

--------------------------------

### Test Tensor Frame Documentation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/README.md

Tests the Tensor Frame documentation, including checking for broken links and validating code examples within the documentation files.

```bash
# Test documentation links and code examples
make docs-test

# Or manually:
cd docs
mdbook test
```

--------------------------------

### Rust Tensor Broadcasting Visualization

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Provides a textual visualization of how tensor broadcasting works with different shape combinations, illustrating implicit dimension expansion and compatibility checks.

```rust
fn visualize_broadcasting() -> Result<()> {
    println!("Broadcasting visualization:");
    println!();
    
    // Example 1: [2, 3] + [3]
    println!("Example 1: [2, 3] + [3]");
    println!("  A: [2, 3]");  
    println!("  B:    [3]  ->  [1, 3]  (implicit leading 1)");
    println!("  Result: [2, 3]");
    println!();
    
    // Example 2: [4, 1, 5] + [3, 5]
    println!("Example 2: [4, 1, 5] + [3, 5]");
    println!("  A: [4, 1, 5]");
    println!("  B:    [3, 5]  ->  [1, 3, 5]  (implicit leading 1)");
    println!("  Result: [4, 3, 5]  (1 broadcasts to 3, 4)");
    println!();
    
    // Example 3: Incompatible
    println!("Example 3: [3, 4] + [2, 4] - INCOMPATIBLE");
    println!("  A: [3, 4]");
    println!("  B: [2, 4]");
    println!("  Error: 3 and 2 cannot broadcast (neither is 1)");
    println!();
    
    Ok(())
}
```

--------------------------------

### CUDA Backend Usage Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/README.md

Highlights optimal use cases for the CUDA backend, including very large tensors, matrix operations, and machine learning workloads on NVIDIA GPUs.

```rust
// Excellent for:
let huge_tensor = Tensor::zeros(vec![4096, 4096])?;
let matrix_mul = a.matmul(&b)?;
let ml_workload = model.forward(input)?;

// Best when:
// - NVIDIA GPU available
// - Performance is critical
// - Using alongside other CUDA libraries
```

--------------------------------

### Tensor Method Chaining Example

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/basic.md

Demonstrates the conciseness achieved through method chaining in Tensor Frame. Multiple operations like reshape, transpose, and squeeze can be chained together in a single expression.

```rust
let result = tensor
    .reshape(vec![4, 2])?
    .transpose()?;
    .squeeze(None)?;
```

--------------------------------

### Build and Test Tensor Frame

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Demonstrates how to build the project with various features and run tests, including backend-specific tests.

```bash
# Build with all features
cargo build --all-features

# Run tests using make
make test

# Run with specific backend
cargo test --features wgpu
cargo test --features cuda
```

--------------------------------

### Memory Layout Optimization Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/performance.md

Demonstrates efficient and less efficient memory access patterns for tensor operations. It highlights the impact of contiguous memory access, layout preservation, and reshaping on performance.

```rust
// Efficient: Contiguous memory access
let matrix = Tensor::from_vec(data, vec![rows, cols])?;
let transposed = matrix.transpose()?;

// Efficient: Operations that preserve layout
let result = (&matrix_a + &matrix_b) * 2.0;

// Less efficient: Operations that break layout
let reshaped = matrix.reshape(vec![cols, rows])?;
```

--------------------------------

### Operation Fusion Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/performance.md

Illustrates the performance benefits of operation fusion by comparing a single fused expression with multiple separate operations. Fused operations can reduce intermediate allocations and improve execution efficiency.

```rust
// Efficient: Fused operations
let result = ((a * b) + c) / d;

// Less efficient: Separate operations  
let temp1 = a * b;
let temp2 = temp1 + c;
let result = temp2 / d;
```

--------------------------------

### Documentation Generation and Serving

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Commands to generate API documentation using `cargo doc --open` and to build and serve the project's book documentation locally using `mdbook`.

```bash
# Generate API documentation
cargo doc --open

# Build the book
cd docs
mdbook build

# Serve book locally
mdbook serve
```

--------------------------------

### Demonstrate Backend Selection Strategies in Rust

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/custom-backends.md

Shows how to automatically select a backend and manually switch between CPU, WGPU, and CUDA backends for tensors. It includes checks for feature availability for WGPU and CUDA.

```rust
use tensor_frame::{Tensor, BackendType, Result};
use std::time::Instant;

fn backend_selection_demo() -> Result<()> {
    println!("=== Backend Selection Strategies ===\n");
    
    // Automatic selection (recommended for most cases)
    let auto_tensor = Tensor::zeros(vec![1000, 1000])?;
    println!("Automatic backend selected: {:?}", auto_tensor.backend_type());
    
    // Manual backend specification
    let cpu_tensor = auto_tensor.to_backend(BackendType::Cpu)?;
    println!("Forced CPU backend: {:?}", cpu_tensor.backend_type());
    
    #[cfg(feature = "wgpu")]
    {
        match auto_tensor.to_backend(BackendType::Wgpu) {
            Ok(wgpu_tensor) => {
                println!("WGPU backend available: {:?}", wgpu_tensor.backend_type());
            }
            Err(e) => {
                println!("WGPU backend not available: {}", e);
            }
        }
    }
    
    #[cfg(feature = "cuda")]
    {
        match auto_tensor.to_backend(BackendType::Cuda) {
            Ok(cuda_tensor) => {
                println!("CUDA backend available: {:?}", cuda_tensor.backend_type());
            }
            Err(e) => {
                println!("CUDA backend not available: {}", e);
            }
        }
    }
    
    Ok(())
}
```

--------------------------------

### Tensor Broadcasting Examples

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Demonstrates different methods of creating broadcastable tensors for operations like row, column, and scalar broadcasting.

```rust
fn size_one_broadcasting() -> Result<()> {
    // Different ways to create broadcastable tensors
    let base = Tensor::from_vec(
        vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
        vec![2, 3]
    )?;
    
    // Row broadcasting (1 x N)
    let row_broadcast = Tensor::from_vec(vec![10.0, 20.0, 30.0], vec![1, 3])?;
    let row_result = &base + &row_broadcast;
    println!("Row broadcasting [2,3] + [1,3]:\n{}\n", row_result);
    
    // Column broadcasting (N x 1)
    let col_broadcast = Tensor::from_vec(vec![100.0, 200.0], vec![2, 1])?;
    let col_result = &base + &col_broadcast;
    println!("Column broadcasting [2,3] + [2,1]:\n{}\n", col_result);
    
    // Both dimensions broadcast (1 x 1)
    let scalar_as_tensor = Tensor::from_vec(vec![1000.0], vec![1, 1])?;
    let scalar_result = &base + &scalar_as_tensor;
    println!("Scalar broadcasting [2,3] + [1,1]:\n{}\n", scalar_result);
    
    Ok(())
}
```

--------------------------------

### Build and Test Tensor Frame

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Commands to build the project with all features enabled and run tests, including tests for specific backends like wgpu and cuda.

```bash
# Build with all features
cargo build --all-features

# Run tests
cargo test

# Run with specific backend
cargo test --features wgpu
cargo test --features cuda
```

--------------------------------

### Rust Tensor Broadcasting Errors

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Demonstrates runtime errors that occur when attempting to broadcast tensors with incompatible shapes. It shows examples of both failing and succeeding broadcasting operations.

```rust
fn broadcasting_errors() -> Result<()> {
    // These will fail - incompatible shapes
    let a = Tensor::ones(vec![3, 4])?;
    let b = Tensor::ones(vec![2, 4])?;  // Different first dimension, not 1
    
    match &a + &b {
        Ok(_) => println!("Unexpected success"),
        Err(e) => println!("Expected error - incompatible shapes: {}", e),
    }
    
    // These will work - compatible shapes
    let c = Tensor::ones(vec![1, 4])?;
    let success = &a + &c;
    println!("Compatible shapes work: {:?}", success.shape().dims());
    
    Ok(())
}
```

--------------------------------

### Serve Tensor Frame Documentation Locally

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/README.md

Serves the Tensor Frame documentation locally, typically with auto-reloading capabilities for development. This allows previewing changes in real-time.

```bash
# Serve with auto-reload
make docs-serve

# Or manually:
cd docs
mdbook serve

# Or use the convenience script:
./scripts/serve-docs.sh
```

--------------------------------

### Generate and Serve Tensor Frame Documentation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Commands to generate API documentation using `cargo doc` and build/serve the project's book documentation using `mdbook`.

```bash
# Generate API documentation
cargo doc --open

# Build the book
cd docs
mdbook build

# Serve book locally
mdbook serve
```

--------------------------------

### Adaptive Backend Selection for Tensors

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Selects the optimal backend (CPU, WGPU, CUDA) for a tensor based on its size to balance performance and overhead. Small tensors benefit from CPU, medium from WGPU, and large from CUDA.

```rust
fn adaptive_backend_selection(tensor_size: usize) -> BackendType {
    match tensor_size {
        0..=1000 => BackendType::Cpu,           // Small: CPU overhead minimal
        1001..=100000 => BackendType::Wgpu,     // Medium: GPU beneficial
        _ => BackendType::Cuda,                 // Large: Maximum performance
    }
}
```

--------------------------------

### Handling WGPU Device Creation Errors

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/wgpu.md

Demonstrates how to catch and handle errors during WGPU backend initialization, including a fallback mechanism.

```rust
match WgpuBackend::new() {
    Ok(backend) => println!("WGPU backend ready"),
    Err(TensorError::BackendError(msg)) => {
        eprintln!("WGPU initialization failed: {}", msg);
        // Fallback to CPU backend
    }
}
```

--------------------------------

### Project Test Commands

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Lists commands for running all tests via make, testing individual backends (CPU, WGPU, CUDA), running tests with verbose output, and executing specific tests.

```bash
# Run all tests using make
make test

# Test individual backends
make test-cpu
make test-wgpu
make test-cuda

# Test with verbose output
cargo test -- --nocapture

# Run specific test
cargo test test_tensor_creation
```

--------------------------------

### Image Processing Broadcasting Patterns

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Shows how broadcasting is applied in image processing tasks, including channel-wise normalization and pixel-wise adjustments.

```rust
fn image_broadcasting_patterns() -> Result<()> {
    // Image batch processing
    let images = Tensor::ones(vec![4, 3, 224, 224])?;
    
    // Channel-wise normalization
    let channel_mean = Tensor::from_vec(
        vec![0.485, 0.456, 0.406],
        vec![1, 3, 1, 1]
    )?;
    let channel_std = Tensor::from_vec(
        vec![0.229, 0.224, 0.225],
        vec![1, 3, 1, 1]
    )?;
    
    let normalized_images = (&images - &channel_mean) / &channel_std;
    println!("Image normalization result shape: {:?}\n", normalized_images.shape().dims());
    
    // Pixel-wise operations
    let brightness_adjustment = Tensor::from_vec(vec![0.1], vec![1, 1, 1, 1])?;
    let brightened = &images + &brightness_adjustment;
    println!("Brightness adjustment result shape: {:?}\n", brightened.shape().dims());
    
    Ok(())
}
```

--------------------------------

### Generate Documentation and Build Book

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Commands to generate Rust documentation for all features and build the project's documentation using mdbook.

```bash
cargo doc --all-features
cd docs && mdbook build
```

--------------------------------

### Cross-Backend Operation Example

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/README.md

Demonstrates how operations between tensors on different backends automatically handle conversion, defaulting to the lower priority backend.

```rust
let cpu_a = Tensor::ones(vec![1000])?;
let gpu_b = Tensor::zeros(vec![1000])?.to_backend(BackendType::Wgpu)?;

// Automatically converts to common backend
let result = cpu_a + gpu_b;  // Runs on CPU backend
```

--------------------------------

### Build Tensor Frame Project

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/contributing.md

Commands for compiling the Tensor Frame project, including quick checks, building with specific backends, and creating release builds.

```bash
# Quick compilation check
cargo check

# Build with specific backends
cargo build --features wgpu
cargo build --features cuda
cargo build --all-features

# Release build
cargo build --release --all-features
```

--------------------------------

### Update Documentation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Generates or updates the project's documentation, ensuring that API references and usage guides are current with the latest code changes.

```bash
cargo doc --all-features
```

--------------------------------

### Configure Tensor Backend from Environment Variables

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/custom-backends.md

Loads tensor backend configuration from environment variables. It supports specifying a preferred backend ('cpu', 'wgpu', 'cuda') and a threshold for small tensors. If no preferred backend is set, it attempts to auto-select the best available backend.

```rust
use std::env;

#[derive(Debug)]
struct TensorConfig {
    preferred_backend: BackendType,
    fallback_backends: Vec<BackendType>,
    small_tensor_threshold: usize,
}

impl TensorConfig {
    fn from_env() -> Self {
        let preferred = env::var("TENSOR_BACKEND")
            .unwrap_or_else(|_| "auto".to_string());
        
        let preferred_backend = match preferred.as_str() {
            "cpu" => BackendType::Cpu,
            #[cfg(feature = "wgpu")]
            "wgpu" => BackendType::Wgpu,
            #[cfg(feature = "cuda")]
            "cuda" => BackendType::Cuda,
            _ => {
                // Auto-select best available
                #[cfg(feature = "cuda")]
                { BackendType::Cuda }
                #[cfg(all(feature = "wgpu", not(feature = "cuda")))]
                { BackendType::Wgpu }
                #[cfg(all(not(feature = "wgpu"), not(feature = "cuda")))]
                { BackendType::Cpu }
            }
        };
        
        let threshold = env::var("SMALL_TENSOR_THRESHOLD")
            .unwrap_or_else(|_| "10000".to_string())
            .parse()
            .unwrap_or(10000);
        
        TensorConfig {
            preferred_backend,
            fallback_backends: vec![BackendType::Cpu],  // Always fallback to CPU
            small_tensor_threshold: threshold,
        }
    }
    
    fn select_backend(&self, tensor_size: usize) -> BackendType {
        if tensor_size < self.small_tensor_threshold {
            BackendType::Cpu  // Always use CPU for small tensors
        } else {
            self.preferred_backend
        }
    }
}

fn production_backend_usage() -> Result<()> {
    println!("=== Production Backend Usage ===\n");
    
    let config = TensorConfig::from_env();
    println!("Configuration: {:?}", config);
    
    // Use configuration for tensor operations
    let sizes = vec![100, 1000, 10000, 100000];
    
    for size in sizes {
        let tensor = Tensor::ones(vec![size])?;
        let elements = tensor.numel();
        
        let backend = config.select_backend(elements);
        let optimized_tensor = tensor.to_backend(backend)?;
        
        println!("Tensor size {}: using {:?} backend", 
                elements, optimized_tensor.backend_type());
    }
    
    Ok(())
}

```

--------------------------------

### Broadcasting Performance Comparison

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Compares the performance of efficient broadcasting versus manual expansion, highlighting the benefits of avoiding large intermediate tensors.

```rust
use std::time::Instant;

fn broadcasting_performance() -> Result<()> {
    // Efficient: Broadcasting avoids large intermediate tensors
    let large_matrix = Tensor::ones(vec![1000, 1000])?;
    let small_vector = Tensor::ones(vec![1000])?;
    
    let start = Instant::now();
    let efficient_result = &large_matrix + &small_vector;
    let efficient_time = start.elapsed();
    
    println!("Efficient broadcasting: {:?}\n", efficient_time);
    
    // Less efficient: Explicit expansion (don't do this!)
    let start = Instant::now();
    let expanded_vector = small_vector.reshape(vec![1, 1000])?;
    // Note: This would need manual tiling which isn't implemented
    // let manual_result = &large_matrix + &expanded_vector;
    let manual_time = start.elapsed();
    
    println!("Manual expansion overhead: {:?}\n", manual_time);
    
    Ok(())
}
```

--------------------------------

### Rust: Backend Selection for Tensor Operations

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Shows how to leverage different computational backends (like WGPU or CUDA) for tensor operations, including automatic selection and manual control. Requires `Tensor` and `BackendType` definitions.

```rust
use tensor_frame::{Tensor, BackendType};

// Automatic backend selection
let tensor = Tensor::zeros(vec![1000, 1000])?;

// Manual backend control
let gpu_tensor = tensor.to_backend(BackendType::Wgpu)?;
let cuda_tensor = tensor.to_backend(BackendType::Cuda)?;
```

--------------------------------

### Memory-Efficient Broadcasting Patterns

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Demonstrates memory-efficient broadcasting techniques, emphasizing how broadcasting reuses memory compared to creating large intermediate tensors.

```rust
fn memory_efficient_broadcasting() -> Result<()> {
    // Good: Broadcasting reuses memory
    let data = Tensor::ones(vec![1000, 500])?;
    let scale_factor = Tensor::from_vec(vec![2.0], vec![1])?;
    
    let scaled = &data * &scale_factor;
    
    // Avoid: Creating large intermediate tensors
    // let large_scale = scale_factor.broadcast_to(vec![1000, 500])?;
    // let scaled = &data * &large_scale;
    
    println!("Memory-efficient scaling completed\n");
    
    Ok(())
}
```

--------------------------------

### Build Tensor Frame Documentation

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/README.md

Builds the Tensor Frame documentation from its source files using mdBook. This command generates the static HTML output.

```bash
# Build the documentation
make docs-book

# Or manually:
cd docs
mdbook build
```

--------------------------------

### Tensor Creation Examples in Rust

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/basic.md

Illustrates how to create tensors filled with zeros, ones, or from existing vector data. It also shows how to inspect tensor properties like shape, number of elements, data type, and backend.

```rust
use tensor_frame::{Tensor, Result, TensorOps};
use std::time::Instant;

fn main() -> Result<()> {
    println!("=== Tensor Frame Basic Operations ===\n");

    // 1. Tensor Creation
    tensor_creation_examples()?;
    
    // 2. Basic Arithmetic
    arithmetic_examples()?;
    
    // 3. Shape Manipulation  
    shape_manipulation_examples()?;
    
    // 4. Data Access
    data_access_examples()?;
    
    // 5. Performance Comparison
    performance_comparison()?;

    Ok(())
}

/// Demonstrates various ways to create tensors
fn tensor_creation_examples() -> Result<()> {
    println!("=== Tensor Creation ===");
    
    // Create tensor filled with zeros
    let zeros = Tensor::zeros(vec![2, 3])?;
    println!("Zeros tensor (2x3):\n{}\n", zeros);
    
    // Create tensor filled with ones
    let ones = Tensor::ones(vec![3, 2])?;
    println!("Ones tensor (3x2):\n{}\n", ones);
    
    // Create tensor from existing data
    let data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
    let from_data = Tensor::from_vec(data, vec![2, 3])?;
    println!("From data (2x3):\n{}\n", from_data);
    
    // Check tensor properties
    println!("Tensor properties:");
    println!("  Shape: {:?}", from_data.shape().dims());
    println!("  Number of elements: {}", from_data.numel());
    println!("  Data type: {:?}", from_data.dtype());
    println!("  Backend: {:?}\n", from_data.backend_type());
    
    Ok(())
}
```

--------------------------------

### Scalar Broadcasting in Tensor Frame

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Demonstrates how to perform arithmetic operations between a Tensor and a scalar value using broadcasting. All standard arithmetic operations (+, -, *, /) are supported.

```rust
use tensor_frame::{Tensor, Result};

fn scalar_broadcasting() -> Result<()> {
    // Create a base tensor
    let tensor = Tensor::from_vec(vec![2.0, 4.0, 6.0, 8.0], vec![2, 2])?;
    println!("Original tensor:\n{}\n", tensor);
    
    // Scalar tensor for broadcasting
    let scalar = Tensor::from_vec(vec![2.0], vec![])?;
    
    // All operations support broadcasting
    let add_result = (tensor.clone() + scalar.clone())?;
    println!("Tensor + 2.0:\n{}\n", add_result);
    
    let sub_result = (tensor.clone() - scalar.clone())?;
    println!("Tensor - 2.0:\n{}\n", sub_result);
    
    let mul_result = (tensor.clone() * scalar.clone())?;
    println!("Tensor * 2.0:\n{}\n", mul_result);
    
    let div_result = (tensor.clone() / scalar.clone())?;
    println!("Tensor / 2.0:\n{}\n", div_result);
    
    Ok(())
}
```

--------------------------------

### Machine Learning Broadcasting Patterns

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/broadcasting.md

Illustrates common broadcasting patterns used in machine learning, such as batch normalization, bias addition, and attention mechanisms.

```rust
fn ml_broadcasting_patterns() -> Result<()> {
    // Batch normalization pattern
    let batch_data = Tensor::ones(vec![32, 128])?;
    let mean = Tensor::zeros(vec![128])?;
    let std = Tensor::ones(vec![128])?;
    
    let normalized = (&batch_data - &mean) / &std;
    println!("Batch normalization result shape: {:?}\n", normalized.shape().dims());
    
    // Bias addition pattern  
    let linear_output = Tensor::ones(vec![32, 10])?;
    let bias = Tensor::from_vec(
        vec![0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0],
        vec![10]
    )?;
    
    let biased_output = &linear_output + &bias;
    println!("Bias addition result shape: {:?}\n", biased_output.shape().dims());
    
    // Attention score broadcasting
    let queries = Tensor::ones(vec![32, 8, 64])?;
    let attention_weights = Tensor::ones(vec![32, 8, 1])?;
    
    let weighted_queries = &queries * &attention_weights;
    println!("Attention weighting result shape: {:?}\n", weighted_queries.shape().dims());
    
    Ok(())
}
```

--------------------------------

### Custom GPU Operation Timing

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/wgpu.md

Provides an example of timing GPU operations, highlighting the asynchronous nature and the need for synchronization when measuring elapsed time.

```rust
use std::time::Instant;

let start = Instant::now();
let result = gpu_tensor_a + gpu_tensor_b;
// Note: GPU operations are asynchronous!
let _data = result.to_vec()?;  // Synchronization point
println!("GPU operation took: {:?}", start.elapsed());
```

--------------------------------

### Project Build Commands

Source: https://github.com/trainpioneers/tensor-frame/blob/main/CONTRIBUTING.md

Provides commands for checking code compilation, building with specific backends (wgpu, cuda), and creating release builds.

```bash
# Quick compilation check
cargo check

# Build with specific backends
cargo build --features wgpu
cargo build --features cuda
cargo build --all-features

# Release build
cargo build --release --all-features
```

--------------------------------

### Parallel Element-wise Operations with Rayon

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/backends/cpu.md

Shows an example of parallel element-wise addition between two tensors using Rayon's parallel iterators.

```rust
a.par_iter()
    .zip(b.par_iter())
    .map(|(a, b)| a + b)
    .collect()
```

--------------------------------

### Rust: Tensor Creation and Basic Arithmetic

Source: https://github.com/trainpioneers/tensor-frame/blob/main/docs/src/examples/README.md

Demonstrates fundamental tensor operations including creation (zeros, ones, from_vec) and basic arithmetic operations like addition and multiplication. Assumes a `Tensor` struct and associated methods are available.

```rust
use tensor_frame::Tensor;

// Tensor creation
let zeros = Tensor::zeros(vec![3, 4])?;
let ones = Tensor::ones(vec![2, 2])?;
let data = Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0], vec![2, 2])?;

// Basic arithmetic
let sum = a + b;
let product = a * b;
let result = (a * 2.0) + b;
```