# Tensor Operations

Core tensor creation, manipulation, and mathematical operations that form the foundation of PyTorch's computational capabilities. These operations support automatic differentiation and GPU acceleration.

## Capabilities

### Tensor Creation

Create tensors from data, with specific values, or using random initialization patterns.

```python { .api }
def tensor(data, *, dtype=None, device=None, requires_grad=False, pin_memory=False) -> Tensor:
    """
    Construct a tensor with data.
    
    Parameters:
    - data: Initial data (list, tuple, ndarray, scalar, tensor)
    - dtype: Data type (torch.float32, torch.int64, etc.)
    - device: Device placement (torch.device or string)
    - requires_grad: Enable automatic differentiation
    - pin_memory: Use pinned memory for faster GPU transfer
    
    Returns:
    Tensor with specified data and properties
    """

def zeros(*size, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Create tensor filled with zeros."""
    
def ones(*size, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Create tensor filled with ones."""
    
def empty(*size, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Create uninitialized tensor."""
    
def full(size, fill_value, *, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Create tensor filled with specific value."""
    
def eye(n, m=None, *, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Create identity matrix."""
```

### Random Tensor Creation

Generate tensors with random values from various distributions.

```python { .api }
def rand(*size, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Random values from uniform distribution [0, 1)."""
    
def randn(*size, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Random values from standard normal distribution."""
    
def randint(low=0, high, size, *, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Random integers from [low, high)."""
    
def randperm(n, *, dtype=torch.int64, device=None, requires_grad=False) -> Tensor:
    """Random permutation of integers 0 to n-1."""
    
def multinomial(input, num_samples, replacement=False, *, generator=None) -> Tensor:
    """Sample from multinomial distribution."""
```

### Range and Sequence Creation

Create tensors with sequential or linearly spaced values.

```python { .api }
def arange(start=0, end, step=1, *, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Values from start to end with step."""
    
def linspace(start, end, steps, *, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Linearly spaced values from start to end."""
    
def logspace(start, end, steps, base=10.0, *, dtype=None, device=None, requires_grad=False) -> Tensor:
    """Logarithmically spaced values."""
```

### Tensor Conversion and Creation from Existing Data

Convert between PyTorch tensors and other data structures.

```python { .api }
def from_numpy(ndarray) -> Tensor:
    """Create tensor from NumPy array (shares memory)."""
    
def as_tensor(data, dtype=None, device=None) -> Tensor:
    """Convert data to tensor, avoiding copy if possible."""
    
def stack(tensors, dim=0) -> Tensor:
    """Stack tensors along new dimension."""
    
def cat(tensors, dim=0) -> Tensor:
    """Concatenate tensors along existing dimension."""
    
def hstack(tensors) -> Tensor:
    """Stack tensors horizontally (column-wise)."""
    
def vstack(tensors) -> Tensor:
    """Stack tensors vertically (row-wise)."""
    
def dstack(tensors) -> Tensor:
    """Stack tensors depth-wise (along third dimension)."""
```

### Shape Manipulation

Reshape, transpose, and manipulate tensor dimensions.

```python { .api }
def reshape(input, shape) -> Tensor:
    """Return tensor with new shape."""
    
def view(input, *shape) -> Tensor:
    """Return tensor with new shape (shares memory)."""
    
def squeeze(input, dim=None) -> Tensor:
    """Remove dimensions of size 1."""
    
def unsqueeze(input, dim) -> Tensor:
    """Add dimension of size 1."""
    
def transpose(input, dim0, dim1) -> Tensor:
    """Swap two dimensions."""
    
def permute(input, dims) -> Tensor:
    """Permute dimensions."""
    
def flatten(input, start_dim=0, end_dim=-1) -> Tensor:
    """Flatten dimensions."""
    
def flip(input, dims) -> Tensor:
    """Reverse tensor along specified dimensions."""
```

### Tensor Splitting and Joining

Split tensors into chunks or join multiple tensors.

```python { .api }
def split(tensor, split_size_or_sections, dim=0) -> List[Tensor]:
    """Split tensor into chunks."""
    
def chunk(input, chunks, dim=0) -> List[Tensor]:
    """Split tensor into specific number of chunks."""
    
def unbind(input, dim=0) -> List[Tensor]:
    """Remove dimension and return sequence of tensors."""
    
def meshgrid(*tensors, indexing='ij') -> List[Tensor]:
    """Create coordinate grids."""
```

### Indexing and Selection

Advanced indexing operations for selecting and manipulating tensor elements.

```python { .api }
def gather(input, dim, index) -> Tensor:
    """Gather values along axis specified by index."""
    
def scatter(input, dim, index, src) -> Tensor:
    """Scatter values along axis specified by index."""
    
def scatter_add(input, dim, index, src) -> Tensor:
    """Scatter and add values."""
    
def index_select(input, dim, index) -> Tensor:
    """Select elements along dimension."""
    
def masked_select(input, mask) -> Tensor:
    """Select elements where mask is True."""
    
def nonzero(input, *, as_tuple=False) -> Tensor:
    """Return indices of non-zero elements."""
    
def where(condition, x, y) -> Tensor:
    """Select elements from x or y based on condition."""
```

### Element-wise Mathematical Operations

Basic arithmetic and mathematical functions applied element-wise.

```python { .api }
def add(input, other, *, alpha=1) -> Tensor:
    """Add tensors element-wise."""
    
def sub(input, other, *, alpha=1) -> Tensor:
    """Subtract tensors element-wise."""
    
def mul(input, other) -> Tensor:
    """Multiply tensors element-wise."""
    
def div(input, other, *, rounding_mode=None) -> Tensor:
    """Divide tensors element-wise."""
    
def pow(input, exponent) -> Tensor:
    """Raise to power element-wise."""
    
def abs(input) -> Tensor:
    """Absolute value element-wise."""
    
def neg(input) -> Tensor:
    """Negate elements."""
    
def sign(input) -> Tensor:
    """Sign of elements (-1, 0, 1)."""
    
def sqrt(input) -> Tensor:
    """Square root element-wise."""
    
def square(input) -> Tensor:
    """Square element-wise."""
    
def exp(input) -> Tensor:
    """Exponential function element-wise."""
    
def log(input) -> Tensor:
    """Natural logarithm element-wise."""
    
def log10(input) -> Tensor:
    """Base-10 logarithm element-wise."""
    
def log2(input) -> Tensor:
    """Base-2 logarithm element-wise."""
```

### Trigonometric Functions

Trigonometric and hyperbolic functions.

```python { .api }
def sin(input) -> Tensor:
    """Sine element-wise."""
    
def cos(input) -> Tensor:
    """Cosine element-wise."""
    
def tan(input) -> Tensor:
    """Tangent element-wise."""
    
def asin(input) -> Tensor:
    """Arcsine element-wise."""
    
def acos(input) -> Tensor:
    """Arccosine element-wise."""
    
def atan(input) -> Tensor:
    """Arctangent element-wise."""
    
def atan2(input, other) -> Tensor:
    """Two-argument arctangent."""
    
def sinh(input) -> Tensor:
    """Hyperbolic sine element-wise."""
    
def cosh(input) -> Tensor:
    """Hyperbolic cosine element-wise."""
    
def tanh(input) -> Tensor:
    """Hyperbolic tangent element-wise."""
```

### Comparison Operations

Element-wise comparison operations returning boolean tensors.

```python { .api }
def eq(input, other) -> Tensor:
    """Element-wise equality."""
    
def ne(input, other) -> Tensor:
    """Element-wise inequality."""
    
def lt(input, other) -> Tensor:
    """Element-wise less than."""
    
def le(input, other) -> Tensor:
    """Element-wise less than or equal."""
    
def gt(input, other) -> Tensor:
    """Element-wise greater than."""
    
def ge(input, other) -> Tensor:
    """Element-wise greater than or equal."""
    
def equal(input, other) -> bool:
    """True if tensors are element-wise equal."""
    
def allclose(input, other, rtol=1e-05, atol=1e-08, equal_nan=False) -> bool:
    """True if tensors are approximately equal."""
```

### Reduction Operations

Operations that reduce tensor dimensions by aggregating values.

```python { .api }
def sum(input, dim=None, keepdim=False, *, dtype=None) -> Tensor:
    """Sum of tensor elements."""
    
def mean(input, dim=None, keepdim=False, *, dtype=None) -> Tensor:
    """Mean of tensor elements."""
    
def median(input, dim=None, keepdim=False) -> Tensor:
    """Median of tensor elements."""
    
def mode(input, dim=None, keepdim=False) -> Tensor:
    """Mode of tensor elements."""
    
def std(input, dim=None, keepdim=False, *, dtype=None) -> Tensor:
    """Standard deviation."""
    
def var(input, dim=None, keepdim=False, *, dtype=None) -> Tensor:
    """Variance."""
    
def max(input, dim=None, keepdim=False) -> Tensor:
    """Maximum values."""
    
def min(input, dim=None, keepdim=False) -> Tensor:
    """Minimum values."""
    
def argmax(input, dim=None, keepdim=False) -> Tensor:
    """Indices of maximum values."""
    
def argmin(input, dim=None, keepdim=False) -> Tensor:
    """Indices of minimum values."""
    
def prod(input, dim=None, keepdim=False, *, dtype=None) -> Tensor:
    """Product of tensor elements."""
    
def all(input, dim=None, keepdim=False) -> Tensor:
    """True if all elements are True."""
    
def any(input, dim=None, keepdim=False) -> Tensor:
    """True if any elements are True."""
```

### Linear Algebra Operations

Core linear algebra operations for matrices and vectors.

```python { .api }
def matmul(input, other) -> Tensor:
    """Matrix multiplication."""
    
def mm(input, mat2) -> Tensor:
    """Matrix multiplication (2D tensors only)."""
    
def bmm(input, mat2) -> Tensor:
    """Batch matrix multiplication."""
    
def dot(input, other) -> Tensor:
    """Dot product of vectors."""
    
def mv(input, vec) -> Tensor:
    """Matrix-vector multiplication."""
    
def outer(input, vec2) -> Tensor:
    """Outer product of vectors."""
    
def cross(input, other, dim=None) -> Tensor:
    """Cross product."""
    
def norm(input, p='fro', dim=None, keepdim=False, *, dtype=None) -> Tensor:
    """Matrix or vector norm."""
```

### Tensor Properties and Utilities

Functions for inspecting and manipulating tensor properties.

```python { .api }
def is_tensor(obj) -> bool:
    """Check if object is a tensor."""
    
def numel(input) -> int:
    """Number of elements in tensor."""
    
def typename(o) -> str:
    """Type name of tensor."""
    
def is_floating_point(input) -> bool:
    """Check if tensor has floating point data type."""
    
def is_complex(input) -> bool:
    """Check if tensor has complex data type."""
    
def is_signed(input) -> bool:
    """Check if tensor has signed data type."""
    
def clone(input) -> Tensor:
    """Create copy of tensor."""
    
def detach(input) -> Tensor:
    """Detach tensor from computation graph."""
```

## Usage Examples

### Basic Tensor Operations

```python
import torch

# Create tensors
x = torch.tensor([[1, 2], [3, 4]], dtype=torch.float32)
y = torch.rand(2, 2)

# Basic operations
z = torch.add(x, y)
product = torch.matmul(x, y)
mean_val = torch.mean(x)

# Shape manipulation
reshaped = torch.reshape(x, (4,))
transposed = torch.transpose(x, 0, 1)

# Indexing
selected = torch.index_select(x, 0, torch.tensor([0]))
mask = x > 2
masked = torch.masked_select(x, mask)

print(f"Original: {x}")
print(f"Sum: {z}")
print(f"Mean: {mean_val}")
print(f"Reshaped: {reshaped}")
print(f"Masked: {masked}")
```

### GPU Operations

```python
import torch

# Check CUDA availability
if torch.cuda.is_available():
    device = torch.device('cuda')
    
    # Create tensors on GPU
    x = torch.tensor([[1, 2], [3, 4]], device=device, dtype=torch.float32)
    y = torch.rand(2, 2, device=device)
    
    # Operations are performed on GPU
    z = torch.matmul(x, y)
    
    # Move back to CPU if needed
    z_cpu = z.cpu()
    
    print(f"GPU result: {z}")
    print(f"CPU result: {z_cpu}")
```