Tensor Creation APIs

Tensor Creation APIs#

APIs on Iris that create and initialize tensors on the Iris symmetric heap.

Iris.zeros(*size, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)[source]#

Returns a tensor filled with the scalar value 0, with the shape defined by the variable argument size. The tensor is allocated on the Iris symmetric heap.

Parameters:

*size (int...) – a sequence of integers defining the shape of the output tensor. Can be a variable number of arguments or a collection like a list or tuple.

Keyword Arguments:

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_dtype()).

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided. Note: Iris tensors always use torch.strided regardless of this parameter.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.zeros(2, 3)
>>> print(tensor.shape)  # torch.Size([2, 3])
>>> print(tensor[0])  # tensor([0., 0., 0.], device='cuda:0')
Iris.zeros_like(input, *, dtype=None, layout=None, device=None, requires_grad=False, memory_format=torch.preserve_format)[source]#

Returns a tensor filled with the scalar value 0, with the same size as input, allocated on the Iris symmetric heap.

Parameters:

input (Tensor) – the size of input will determine size of the output tensor.

Keyword Arguments:

  • dtype (torch.dtype, optional) – the desired data type of returned Tensor. Default: if None, defaults to the dtype of input.

  • layout (torch.layout, optional) – the desired layout of returned tensor. Default: if None, defaults to the layout of input. Note: Iris tensors are always contiguous (strided).

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, defaults to the device of input. Must be compatible with this Iris instance.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

  • memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.preserve_format.

Example

>>> ctx = iris.iris(1 << 20)
>>> input_tensor = ctx.ones(2, 3)
>>> zeros_tensor = ctx.zeros_like(input_tensor)
>>> print(zeros_tensor.shape)  # torch.Size([2, 3])
Iris.ones(*size, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)[source]#

Returns a tensor filled with the scalar value 1, with the shape defined by the variable argument size. The tensor is allocated on the Iris symmetric heap.

Parameters:

*size (int...) – a sequence of integers defining the shape of the output tensor. Can be a variable number of arguments or a collection like a list or tuple.

Keyword Arguments:

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_dtype()).

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided. Note: Iris tensors always use torch.strided regardless of this parameter.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.ones(2, 3)
>>> print(tensor.shape)  # torch.Size([2, 3])
>>> print(tensor[0])  # tensor([1., 1., 1.], device='cuda:0')
Iris.full(size, fill_value, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)[source]#

Creates a tensor of size size filled with fill_value. The tensor’s dtype is inferred from fill_value. The tensor is allocated on the Iris symmetric heap.

Parameters:

  • size (int...) – a list, tuple, or torch.Size of integers defining the shape of the output tensor.

  • fill_value (Scalar) – the value to fill the output tensor with.

Keyword Arguments:

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_dtype()).

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided. Note: Iris tensors always use torch.strided regardless of this parameter.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.full((2, 3), 3.14)
>>> print(tensor.shape)  # torch.Size([2, 3])
>>> print(tensor[0])  # tensor([3.1400, 3.1400, 3.1400], device='cuda:0')
Iris.empty(*size, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False, pin_memory=False, memory_format=torch.contiguous_format)[source]#

Returns a tensor filled with uninitialized data. The shape of the tensor is defined by the variable argument size. The tensor is allocated on the Iris symmetric heap.

Note

If torch.use_deterministic_algorithms() and torch.utils.deterministic.fill_uninitialized_memory are both set to True, the output tensor is initialized to prevent any possible nondeterministic behavior from using the data as an input to an operation. Floating point and complex tensors are filled with NaN, and integer tensors are filled with the maximum value.

Parameters:

*size (int...) – a sequence of integers defining the shape of the output tensor. Can be a variable number of arguments or a collection like a list or tuple.

Keyword Arguments:

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_dtype()).

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided. Note: Iris tensors always use torch.strided regardless of this parameter.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

  • pin_memory (bool, optional) – If set, returned tensor would be allocated in the pinned memory. Works only for CPU tensors. Default: False. Note: Iris tensors are always on GPU.

  • memory_format (torch.memory_format, optional) – the desired memory format of returned Tensor. Default: torch.contiguous_format.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.empty(2, 3)
>>> print(tensor.shape)  # torch.Size([2, 3])
Iris.randn(*size, generator=None, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False, pin_memory=False)[source]#

Returns a tensor filled with random numbers from a normal distribution with mean 0 and variance 1 (also called the standard normal distribution). The tensor is allocated on the Iris symmetric heap.

\[\text{out}_i \sim \mathcal{N}(0, 1)\]

For complex dtypes, the tensor is i.i.d. sampled from a complex normal distribution with zero mean and unit variance as

\[\text{out}_i \sim \mathcal{CN}(0, 1)\]

This is equivalent to separately sampling the real \((\text{Re})\) and imaginary \((\text{Im})\) part of \(\text{out}_i\) as

\[\text{Re}(\text{out}_i) \sim \mathcal{N}(0, \frac{1}{2}), \quad \text{Im}(\text{out}_i) \sim \mathcal{N}(0, \frac{1}{2})\]

The shape of the tensor is defined by the variable argument size.

Parameters:

*size (int...) – a sequence of integers defining the shape of the output tensor. Can be a variable number of arguments or a collection like a list or tuple.

Keyword Arguments:

  • generator (torch.Generator, optional) – a pseudorandom number generator for sampling

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.set_default_dtype()).

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided. Note: Iris tensors always use torch.strided regardless of this parameter.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type (see torch.set_default_device()). device will be the CPU for CPU tensor types and the current CUDA device for CUDA tensor types.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

  • pin_memory (bool, optional) – If set, returned tensor would be allocated in the pinned memory. Works only for CPU tensors. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.randn(2, 3)
>>> print(tensor.shape)  # torch.Size([2, 3])
>>> print(tensor[0])  # tensor([ 0.3982, -0.0059, -0.4365], device='cuda:0')
Iris.uniform(size, low=0.0, high=1.0, dtype=torch.float)[source]#

Returns a tensor filled with random numbers from a uniform distribution, allocated on the Iris symmetric heap.

Parameters:

  • size (int or tuple of ints) – the size of the output tensor.

  • low (float, optional) – the lower bound of the uniform distribution. Default: 0.0.

  • high (float, optional) – the upper bound of the uniform distribution. Default: 1.0.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: torch.float.

Returns:

A tensor filled with random numbers from a uniform distribution.

Return type:

Tensor

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.uniform((2, 3), low=0.0, high=1.0)
>>> print(tensor.shape)  # torch.Size([2, 3])
>>> print(tensor[0])  # tensor([0.1234, 0.5678, 0.9012], device='cuda:0')
Iris.randint(*args, generator=None, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)[source]#

Returns a tensor filled with random integers generated uniformly between low (inclusive) and high (exclusive). The shape of the tensor is defined by the variable argument size. The tensor is allocated on the Iris symmetric heap.

Note

With the global dtype default (torch.float32), this function returns a tensor with dtype torch.int64.

Parameters:

  • low (int, optional) – Lowest integer to be drawn from the distribution. Default: 0.

  • high (int) – One above the highest integer to be drawn from the distribution.

  • size (tuple) – a tuple defining the shape of the output tensor.

Keyword Arguments:

  • generator (torch.Generator, optional) – a pseudorandom number generator for sampling.

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – if None, this function returns a tensor with dtype torch.int64.

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.randint(0, 10, (2, 3))  # Random integers [0, 10)
>>> print(tensor.shape)  # torch.Size([2, 3])
>>> print(tensor[0])  # tensor([7, 2, 9], device='cuda:0')
Iris.linspace(start, end, steps, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)[source]#

Creates a one-dimensional tensor of size steps whose values are evenly spaced from start to end, inclusive. The tensor is allocated on the Iris symmetric heap.

The values are: (start, start + (end-start)/(steps-1), …, start + (steps-2)*(end-start)/(steps-1), end)

Parameters:

  • start (float or Tensor) – the starting value for the set of points. If Tensor, it must be 0-dimensional.

  • end (float or Tensor) – the ending value for the set of points. If Tensor, it must be 0-dimensional.

  • steps (int) – size of the constructed tensor.

Keyword Arguments:

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the data type to perform the computation in. Default: if None, uses the global default dtype when both start and end are real, and corresponding complex dtype when either is complex.

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.linspace(0, 10, 5)  # [0, 2.5, 5, 7.5, 10]
>>> print(tensor) # tensor([ 0.0000,  2.5000,  5.0000,  7.5000, 10.0000], device='cuda:0')
Iris.arange(start=0, end=None, step=1, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)[source]#

Returns a 1-D tensor of size ⌈(end - start) / step⌉ with values from the interval [start, end) taken with common difference step beginning from start. The tensor is allocated on the symmetric heap.

Note: When using floating-point dtypes (especially reduced precision types like bfloat16), the results may be affected by floating-point rounding behavior. Some values in the sequence might not be exactly representable in certain floating-point formats, which can lead to repeated values or unexpected rounding. For precise sequences, it is recommended to use integer dtypes instead of floating-point dtypes.

Note that non-integer step is subject to floating point rounding errors when comparing against end; to avoid inconsistency, we advise subtracting a small epsilon from end in such cases.

Parameters:

  • start (Number, optional) – the starting value for the set of points. Default: 0.

  • end (Number) – the ending value for the set of points

  • step (Number, optional) – the gap between each pair of adjacent points. Default: 1.

  • out (Tensor, optional) – the output tensor.

  • dtype (torch.dtype, optional) – the desired data type of returned tensor. Default: if None, uses a global default (see torch.get_default_dtype()). If dtype is not given, infer the data type from the other input arguments. If any of start, end, or step are floating-point, the dtype is inferred be the default dtype, see get_default_dtype(). Otherwise, the dtype is inferred to be torch.int64.

  • layout (torch.layout, optional) – the desired layout of returned Tensor. Default: torch.strided. Note: Iris tensors always use torch.strided regardless of this parameter.

  • device (torch.device, optional) – the desired device of returned tensor. Default: if None, uses the current device for the default tensor type.

  • requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default: False.

Example

>>> ctx = iris.iris(1 << 20)
>>> tensor = ctx.arange(0, 10, 2)  # [0, 2, 4, 6, 8]
>>> print(tensor.shape)  # torch.Size([5])