org.bytedeco.pytorch

Class TensorOptions

java.lang.Object

org.bytedeco.javacpp.Pointer

org.bytedeco.pytorch.TensorOptions

All Implemented Interfaces:

AutoCloseable

@Namespace(value="c10")
 @NoOffset
 @Properties(inherit=torch.class)
public class TensorOptions
extends Pointer

A class to encapsulate construction axes of an Tensor. TensorOptions was designed to support the Python style API for specifying construction options on factory functions, e.g., torch.zeros(2, 3, dtype=torch.int32) Because C++ doesn't natively support keyword arguments, there must be another way of specifying keyword-like arguments. TensorOptions is a builder class which can be used to construct this "dictionary" of keyword arguments: functions which support TensorOptions conventionally take this argument optionally as their last argument. WARNING: In PyTorch, there are torch:: variants of factory functions, e.g., torch::zeros for at::zeros. These return Variables (while the stock ATen functions return plain Tensors). If you mix these functions up, you WILL BE SAD. Rather than use the constructor of this class directly, you should prefer to use the constructor functions, and then chain setter methods on top of them. at::device(at::kCUDA).dtype(kInt) at::dtype(at::kInt) Additionally, anywhere a TensorOptions is expected, you can directly pass at::kCUDA / at::kInt, and it will implicitly convert to a TensorOptions. Here are some recommended ways to create a 2x2 tensor of zeros with certain properties. These all *implicitly* make use of TensorOptions, even if they don't mention the class explicitly: at::zeros({2,2}, at::kCUDA); at::zeros({2,2}, at::kLong); at::zeros({2,2}, at::device(at::kCUDA).dtype(at::kLong())); at::zeros({2,2}, at::device({at::kCUDA, 1})); // place on device 1 at::zeros({2,2}, at::requires_grad());

NOTE [ TensorOptions Constructors ] TensorOptions is like a dictionary with entries from the set: {requires_grad, device, dtype, layout}, where each entry may be unspecified (i.e., is optional). It is used to specify the properties of tensors in many places both in C++ internal and API, e.g., tensor factory methods like at::empty({10}, options), tensor conversions like tensor.to(...), etc. To provide a simple API that is consistent with Python, where one can do torch.empty(sizes, X) with X being a torch.device, torch.dtype, or a torch.layout, we want TensorOptions to be implicitly convertible from ScalarType dtype, Layout layout and Device device. Therefore, we have three implicit constructors from each of these three types. This is sufficient for ScalarType and Layout as they are simple Enum classes. However, Device is an ordinary class with implicit constructors Device(DeviceType, DeviceIndex = -1) and Device(std::string) to be consistent with Python API, where strings are treated as equivalent with a torch.device object (e.g., "cuda:1" can be passed to everywhere a torch.device("cuda:1") is accepted). To support the syntax at::empty({10}, {kCUDA, 1}) and tensor.to(kCUDA), we need to make sure that TensorOptions is implicitly constructible with any arguments that a Device can constructed from. So we have, /* implicit * / TensorOptions(T&& device) : TensorOptions() { this->set_device(device); } template ::value>> /* implicit * / TensorOptions(Args&&... args) : TensorOptions(Device(std::forward(args)...)) {} But this will be problematic. Consider this: TensorOptions({kCUDA, 1}). Compiler will complain about ambiguity between the copy constructor and the Device constructor because {kCUDA, 1} can be converted to both a TensorOption and a Device. To get around this, we templatize the Device constructor. Since overload resolution is done before template resolution, our problem is solved.

Nested Class Summary

Nested classes/interfaces inherited from class org.bytedeco.javacpp.Pointer

Pointer.CustomDeallocator, Pointer.Deallocator, Pointer.NativeDeallocator, Pointer.ReferenceCounter

Field Summary

Fields inherited from class org.bytedeco.javacpp.Pointer

address, capacity, limit, position

Constructor Summary

Constructors

Constructor and Description
TensorOptions()
TensorOptions(byte layout)
TensorOptions(Device device) Constructs a TensorOptions object with the given device.
TensorOptions(long size) Native array allocator.
TensorOptions(Pointer p) Pointer cast constructor.
TensorOptions(torch.Layout layout) Constructs a TensorOptions object with the given layout.
TensorOptions(torch.MemoryFormat memory_format) Constructs a TensorOptions object with the given memory format.
TensorOptions(torch.ScalarType dtype) legacy constructor to support ScalarType
TensorOptions(TypeMeta dtype) Constructs a TensorOptions object with the given dtype.

Method Summary

Modifier and Type	Method and Description
torch.Backend	backend()
torch.DispatchKey	computeDispatchKey()
byte	device_index() Returns the device index of the TensorOptions.
TensorOptions	device_index(byte device_index) Return a copy of TensorOptions, but with device set to CUDA, and the device index set to the given one.
DeviceOptional	device_opt() Returns the device of the TensorOptions, or std::nullopt if device is not specified.
Device	device() Returns the device of the TensorOptions.
TensorOptions	device(DeviceOptional device) Return a copy of TensorOptions with device set to the given one, or cleared if device is nullopt.
TypeMetaOptional	dtype_opt() Returns the dtype of the TensorOptions, or std::nullopt if device is not specified.
TypeMeta	dtype() Returns the dtype of the TensorOptions.
TensorOptions	dtype(ScalarTypeOptional dtype)
TensorOptions	dtype(TypeMetaOptional dtype) Return a copy of TensorOptions with dtype set to the given one.
TensorOptions	getPointer(long i)
boolean	has_device() Returns whether the device is specified.
boolean	has_dtype() Returns whether the dtype is specified.
boolean	has_layout() Returns whether the layout is specified.
boolean	has_memory_format() Returns whether the memory_layout is specified
boolean	has_pinned_memory() Returns whether the pinned_memory is specified.
boolean	has_requires_grad() Returns whether the requires_grad is specified.
boolean	is_sparse_compressed()
boolean	is_sparse_csr() Returns if the layout is sparse CSR, deprecated, use is_sparse_compressed() instead
boolean	is_sparse() Returns if the layout is sparse
LayoutOptional	layout_opt() Returns the layout of the TensorOptions, or std::nullopt if layout is not specified.
torch.Layout	layout() Returns the layout of the TensorOptions.
TensorOptions	layout(LayoutOptional layout) Sets the layout of the TensorOptions.
MemoryFormatOptional	memory_format_opt() Returns the memory_layout property of TensorOptions, or std::nulloptif memory_format{@code is not specified.
TensorOptions	memory_format(MemoryFormatOptional memory_format) Sets the memory_format property on TensorOptions.
TensorOptions	merge_in(TensorOptions options) Return the right-biased merge of two TensorOptions.
TensorOptions	merge_memory_format(MemoryFormatOptional optional_memory_format)
BoolOptional	pinned_memory_opt() Returns the pinned_memory property of the TensorOptions, or std::nullopt if pinned_memory is not specified.
boolean	pinned_memory() Returns the pinned_memory property of the TensorOptions.
TensorOptions	pinned_memory(BoolOptional pinned_memory) Sets the pinned_memory property on the TensorOptions.
TensorOptions	position(long position)
BoolOptional	requires_grad_opt() Returns the requires_grad property of the TensorOptions, or std::nullopt if requires_grad is not specified.
boolean	requires_grad() Returns the requires_grad property of the TensorOptions.
TensorOptions	requires_grad(BoolOptional requires_grad) Sets the requires_grad property of the TensorOptions.
boolean	type_equal(TensorOptions other)

Methods inherited from class org.bytedeco.javacpp.Pointer

address, asBuffer, asByteBuffer, availablePhysicalBytes, calloc, capacity, capacity, close, deallocate, deallocate, deallocateReferences, deallocator, deallocator, equals, fill, formatBytes, free, getDirectBufferAddress, getPointer, getPointer, getPointer, hashCode, interruptDeallocatorThread, isNull, isNull, limit, limit, malloc, maxBytes, maxPhysicalBytes, memchr, memcmp, memcpy, memmove, memset, offsetAddress, offsetof, offsetof, parseBytes, physicalBytes, physicalBytesInaccurate, position, put, realloc, referenceCount, releaseReference, retainReference, setNull, sizeof, sizeof, toString, totalBytes, totalCount, totalPhysicalBytes, withDeallocator, zero

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TensorOptions

public TensorOptions(Pointer p)

Pointer cast constructor. Invokes Pointer(Pointer).

TensorOptions

public TensorOptions(long size)

Native array allocator. Access with Pointer.position(long).

TensorOptions

public TensorOptions()

TensorOptions

public TensorOptions(torch.Layout layout)

Constructs a TensorOptions object with the given layout.

TensorOptions

public TensorOptions(@Cast(value="c10::Layout")
                     byte layout)

TensorOptions

public TensorOptions(@ByRef(value=true)
                     Device device)

Constructs a TensorOptions object with the given device. See NOTE [ TensorOptions Constructors ] on why this is templatized.

TensorOptions

public TensorOptions(@ByVal
                     TypeMeta dtype)

Constructs a TensorOptions object with the given dtype.

TensorOptions

public TensorOptions(torch.ScalarType dtype)

legacy constructor to support ScalarType

TensorOptions

public TensorOptions(torch.MemoryFormat memory_format)

Constructs a TensorOptions object with the given memory format.

Method Detail

position

public TensorOptions position(long position)

Overrides:

position in class Pointer

getPointer

public TensorOptions getPointer(long i)

Overrides:

getPointer in class Pointer

device

@ByVal
 @NoException(value=true)
public TensorOptions device(@ByVal
                                                             DeviceOptional device)

Return a copy of TensorOptions with device set to the given one, or cleared if device is nullopt.

device_index

@ByVal
 @NoException(value=true)
public TensorOptions device_index(@Cast(value="c10::DeviceIndex")
                                                                   byte device_index)

Return a copy of TensorOptions, but with device set to CUDA, and the device index set to the given one. TODO: This function encourages bad behavior (assuming CUDA is the only device that matters). Get rid of it / rename it.

dtype

@ByVal
 @NoException(value=true)
public TensorOptions dtype(@ByVal
                                                            TypeMetaOptional dtype)

Return a copy of TensorOptions with dtype set to the given one.

dtype

@ByVal
 @NoException(value=true)
public TensorOptions dtype(@ByVal
                                                            ScalarTypeOptional dtype)

layout

@ByVal
 @NoException(value=true)
public TensorOptions layout(@ByVal
                                                             LayoutOptional layout)

Sets the layout of the TensorOptions.

requires_grad

@ByVal
 @NoException(value=true)
public TensorOptions requires_grad(@ByVal
                                                                    BoolOptional requires_grad)

Sets the requires_grad property of the TensorOptions.

pinned_memory

@ByVal
 @NoException(value=true)
public TensorOptions pinned_memory(@ByVal
                                                                    BoolOptional pinned_memory)

Sets the pinned_memory property on the TensorOptions.

memory_format

@ByVal
 @NoException(value=true)
public TensorOptions memory_format(@ByVal
                                                                    MemoryFormatOptional memory_format)

Sets the memory_format property on TensorOptions.

device

@ByVal
 @NoException(value=true)
public Device device()

Returns the device of the TensorOptions.

has_device

@Cast(value="bool")
 @NoException(value=true)
public boolean has_device()

Returns whether the device is specified.

device_opt

@ByVal
 @NoException(value=true)
public DeviceOptional device_opt()

Returns the device of the TensorOptions, or std::nullopt if device is not specified.

device_index

@Cast(value="c10::DeviceIndex")
 @NoException(value=true)
public byte device_index()

Returns the device index of the TensorOptions.

dtype

@ByVal
 @NoException(value=true)
public TypeMeta dtype()

Returns the dtype of the TensorOptions.

has_dtype

@Cast(value="bool")
 @NoException(value=true)
public boolean has_dtype()

Returns whether the dtype is specified.

dtype_opt

@ByVal
 @NoException(value=true)
public TypeMetaOptional dtype_opt()

Returns the dtype of the TensorOptions, or std::nullopt if device is not specified.

layout

@NoException(value=true)
public torch.Layout layout()

Returns the layout of the TensorOptions.

has_layout

@Cast(value="bool")
 @NoException(value=true)
public boolean has_layout()

Returns whether the layout is specified.

layout_opt

@ByVal
 @NoException(value=true)
public LayoutOptional layout_opt()

Returns the layout of the TensorOptions, or std::nullopt if layout is not specified.

requires_grad

@Cast(value="bool")
 @NoException(value=true)
public boolean requires_grad()

Returns the requires_grad property of the TensorOptions.

has_requires_grad

@Cast(value="bool")
 @NoException(value=true)
public boolean has_requires_grad()

Returns whether the requires_grad is specified.

requires_grad_opt

@ByVal
 @NoException(value=true)
public BoolOptional requires_grad_opt()

Returns the requires_grad property of the TensorOptions, or std::nullopt if requires_grad is not specified.

pinned_memory

@Cast(value="bool")
 @NoException(value=true)
public boolean pinned_memory()

Returns the pinned_memory property of the TensorOptions.

has_pinned_memory

@Cast(value="bool")
 @NoException(value=true)
public boolean has_pinned_memory()

Returns whether the pinned_memory is specified.

is_sparse

@Cast(value="bool")
public boolean is_sparse()

Returns if the layout is sparse

is_sparse_csr

@Cast(value="bool")
public boolean is_sparse_csr()

Returns if the layout is sparse CSR, deprecated, use is_sparse_compressed() instead

is_sparse_compressed

@Cast(value="bool")
public boolean is_sparse_compressed()

type_equal

@Cast(value="bool")
public boolean type_equal(@Const @ByRef
                                              TensorOptions other)

pinned_memory_opt

@ByVal
 @NoException(value=true)
public BoolOptional pinned_memory_opt()

Returns the pinned_memory property of the TensorOptions, or std::nullopt if pinned_memory is not specified.

has_memory_format

@Cast(value="bool")
 @NoException(value=true)
public boolean has_memory_format()

Returns whether the memory_layout is specified

memory_format_opt

@ByVal
 @NoException(value=true)
public MemoryFormatOptional memory_format_opt()

Returns the memory_layout property of TensorOptions, or std::nulloptif memory_format{@code is not specified.

backend

public torch.Backend backend()

merge_in

@ByVal
 @NoException(value=true)
public TensorOptions merge_in(@ByVal
                                                               TensorOptions options)

Return the right-biased merge of two TensorOptions. This has the effect of overwriting settings from self with specified options of options. NB: This merging operation does NOT respect device merges. For example, if you device({kCUDA, 1}).merge_in(kCUDA) you will get kCUDA in the end! Functions like Tensor.new_empty ensure the right device is selected anyway by way of a device guard.

merge_memory_format

@ByVal
 @NoException(value=true)
public TensorOptions merge_memory_format(@ByVal
                                                                          MemoryFormatOptional optional_memory_format)

computeDispatchKey

public torch.DispatchKey computeDispatchKey()