A wrapper around C++ torch::jit::Module. ScriptModules contain methods, attributes, parameters, and constants. These can be accessed the same as on a normal nn.Module.
Adds a child module to the current module.
The module can be accessed as an attribute using the given name.
Applies fn recursively to every submodule (as returned by .children()) as well as self. Typical use includes initializing the parameters of a model (see also torch.nn.init).
fn (Module -> None) – function to be applied to each submodule
self
Module
Example:
Casts all floating point parameters and buffers to bfloat16 datatype.
self
Module
Returns an iterator over module buffers.
recurse (bool) – if True, then yields buffers of this module and all submodules. Otherwise, yields only buffers that are direct members of this module.
torch.Tensor – module buffer
Example:
Returns an iterator over immediate children modules.
Module – a child module
Returns a pretty-printed representation (as valid Python syntax) of the internal graph for the forward method. See Inspecting Code for details.
Returns a tuple of:
[0] a pretty-printed representation (as valid Python syntax) of the internal graph for the forward method. See code. [1] a ConstMap following the CONSTANT.cN format of the output in [0]. The indices in the [0] output are keys to the underlying constant’s values.
See Inspecting Code for details.
Moves all model parameters and buffers to the CPU.
self
Module
Moves all model parameters and buffers to the GPU.
This also makes associated parameters and buffers different objects. So it should be called before constructing optimizer if the module will live on GPU while being optimized.
device (int, optional) – if specified, all parameters will be copied to that device
self
Module
Casts all floating point parameters and buffers to double datatype.
self
Module
Sets the module in evaluation mode.
This has any effect only on certain modules. See documentations of particular modules for details of their behaviors in training/evaluation mode, if they are affected, e.g. Dropout, BatchNorm, etc.
This is equivalent with self.train(False).
self
Module
Set the extra representation of the module
To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.
Casts all floating point parameters and buffers to float datatype.
self
Module
Returns a string representation of the internal graph for the forward method. See Interpreting Graphs for details.
Casts all floating point parameters and buffers to half datatype.
self
Module
Returns a string representation of the internal graph for the forward method. This graph will be preprocessed to inline all function and method calls. See Interpreting Graphs for details.
Copies parameters and buffers from state_dict into this module and its descendants. If strict is True, then the keys of state_dict must exactly match the keys returned by this module’s state_dict() function.
NamedTuple with missing_keys and unexpected_keys fields
Returns an iterator over all modules in the network.
Module – a module in the network
Note
Duplicate modules are returned only once. In the following example, l will be returned only once.
Example:
Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
(string, torch.Tensor) – Tuple containing the name and buffer
Example:
Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
(string, Module) – Tuple containing a name and child module
Example:
Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
(string, Module) – Tuple of name and module
Note
Duplicate modules are returned only once. In the following example, l will be returned only once.
Example:
Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
(string, Parameter) – Tuple containing the name and parameter
Example:
Returns an iterator over module parameters.
This is typically passed to an optimizer.
recurse (bool) – if True, then yields parameters of this module and all submodules. Otherwise, yields only parameters that are direct members of this module.
Parameter – module parameter
Example:
Registers a backward hook on the module.
This function is deprecated in favor of nn.Module.register_full_backward_hook() and the behavior of this function will change in future versions.
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle
Adds a buffer to the module.
This is typically used to register a buffer that should not to be considered a model parameter. For example, BatchNorm’s running_mean is not a parameter, but is part of the module’s state. Buffers, by default, are persistent and will be saved alongside parameters. This behavior can be changed by setting persistent to False. The only difference between a persistent buffer and a non-persistent buffer is that the latter will not be a part of this module’s state_dict.
Buffers can be accessed as attributes using given names.
Example:
Registers a forward hook on the module.
The hook will be called every time after forward() has computed an output. It should have the following signature:
The input contains only the positional arguments given to the module. Keyword arguments won’t be passed to the hooks and only to the forward. The hook can modify the output. It can modify the input inplace but it will not have effect on forward since this is called after forward() is called.
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle
Registers a forward pre-hook on the module.
The hook will be called every time before forward() is invoked. It should have the following signature:
The input contains only the positional arguments given to the module. Keyword arguments won’t be passed to the hooks and only to the forward. The hook can modify the input. User can either return a tuple or a single modified value in the hook. We will wrap the value into a tuple if a single value is returned(unless that value is already a tuple).
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle
Registers a backward hook on the module.
The hook will be called every time the gradients with respect to module inputs are computed. The hook should have the following signature:
The grad_input and grad_output are tuples that contain the gradients with respect to the inputs and outputs respectively. The hook should not modify its arguments, but it can optionally return a new gradient with respect to the input that will be used in place of grad_input in subsequent computations. grad_input will only correspond to the inputs given as positional arguments and all kwarg arguments are ignored. Entries in grad_input and grad_output will be None for all non-Tensor arguments.
Warning
Modifying inputs or outputs inplace is not allowed when using backward hooks and will raise an error.
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle
Adds a parameter to the module.
The parameter can be accessed as an attribute using given name.
Change if autograd should record operations on parameters in this module.
This method sets the parameters’ requires_grad attributes in-place.
This method is helpful for freezing part of the module for finetuning or training parts of a model individually (e.g., GAN training).
requires_grad (bool) – whether autograd should record operations on parameters in this module. Default: True.
self
Module
See torch.jit.save for details.
Returns a dictionary containing a whole state of the module.
Both parameters and persistent buffers (e.g. running averages) are included. Keys are corresponding parameter and buffer names.
a dictionary containing a whole state of the module
dict
Example:
Moves and/or casts the parameters and buffers.
This can be called as
Its signature is similar to torch.Tensor.to(), but only accepts floating point or complex dtype`s. In addition, this method will
only cast the floating point or complex parameters and buffers to :attr:`dtype (if given). The integral parameters and buffers will be moved device, if that is given, but with dtypes unchanged. When non_blocking is set, it tries to convert/move asynchronously with respect to the host if possible, e.g., moving CPU Tensors with pinned memory to CUDA devices.
See below for examples.
Note
This method modifies the module in-place.
self
Module
Examples:
Sets the module in training mode.
This has any effect only on certain modules. See documentations of particular modules for details of their behaviors in training/evaluation mode, if they are affected, e.g. Dropout, BatchNorm, etc.
mode (bool) – whether to set training mode (True) or evaluation mode (False). Default: True.
self
Module
Casts all parameters and buffers to dst_type.
dst_type (type or string) – the desired type
self
Module
Moves all model parameters and buffers to the XPU.
This also makes associated parameters and buffers different objects. So it should be called before constructing optimizer if the module will live on XPU while being optimized.
device (int, optional) – if specified, all parameters will be copied to that device
self
Module
Sets gradients of all model parameters to zero. See similar function under torch.optim.Optimizer for more context.
set_to_none (bool) – instead of setting to zero, set the grads to None. See torch.optim.Optimizer.zero_grad() for details.


Adds a child module to the current module.
The module can be accessed as an attribute using the given name.


Applies fn recursively to every submodule (as returned by .children()) as well as self. Typical use includes initializing the parameters of a model (see also torch.nn.init).
fn (Module -> None) – function to be applied to each submodule
self
Module
Example:


Casts all floating point parameters and buffers to bfloat16 datatype.
self
Module


Returns an iterator over module buffers.
recurse (bool) – if True, then yields buffers of this module and all submodules. Otherwise, yields only buffers that are direct members of this module.
torch.Tensor – module buffer
Example:


Returns an iterator over immediate children modules.
Module – a child module


Returns a pretty-printed representation (as valid Python syntax) of the internal graph for the forward method. See Inspecting Code for details.


Returns a tuple of:
[0] a pretty-printed representation (as valid Python syntax) of the internal graph for the forward method. See code. [1] a ConstMap following the CONSTANT.cN format of the output in [0]. The indices in the [0] output are keys to the underlying constant’s values.
See Inspecting Code for details.


Moves all model parameters and buffers to the CPU.
self
Module


Moves all model parameters and buffers to the GPU.
This also makes associated parameters and buffers different objects. So it should be called before constructing optimizer if the module will live on GPU while being optimized.
device (int, optional) – if specified, all parameters will be copied to that device
self
Module


Casts all floating point parameters and buffers to double datatype.
self
Module


Sets the module in evaluation mode.
This has any effect only on certain modules. See documentations of particular modules for details of their behaviors in training/evaluation mode, if they are affected, e.g. Dropout, BatchNorm, etc.
This is equivalent with self.train(False).
self
Module


Set the extra representation of the module
To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.


Casts all floating point parameters and buffers to float datatype.
self
Module


Returns a string representation of the internal graph for the forward method. See Interpreting Graphs for details.


Casts all floating point parameters and buffers to half datatype.
self
Module


Returns a string representation of the internal graph for the forward method. This graph will be preprocessed to inline all function and method calls. See Interpreting Graphs for details.


Copies parameters and buffers from state_dict into this module and its descendants. If strict is True, then the keys of state_dict must exactly match the keys returned by this module’s state_dict() function.
NamedTuple with missing_keys and unexpected_keys fields


Returns an iterator over all modules in the network.
Module – a module in the network
Note
Duplicate modules are returned only once. In the following example, l will be returned only once.
Example:


Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
(string, torch.Tensor) – Tuple containing the name and buffer
Example:


Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
(string, Module) – Tuple containing a name and child module
Example:


Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
(string, Module) – Tuple of name and module
Note
Duplicate modules are returned only once. In the following example, l will be returned only once.
Example:


Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
(string, Parameter) – Tuple containing the name and parameter
Example:


Returns an iterator over module parameters.
This is typically passed to an optimizer.
recurse (bool) – if True, then yields parameters of this module and all submodules. Otherwise, yields only parameters that are direct members of this module.
Parameter – module parameter
Example:


Registers a backward hook on the module.
This function is deprecated in favor of nn.Module.register_full_backward_hook() and the behavior of this function will change in future versions.
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle


Adds a buffer to the module.
This is typically used to register a buffer that should not to be considered a model parameter. For example, BatchNorm’s running_mean is not a parameter, but is part of the module’s state. Buffers, by default, are persistent and will be saved alongside parameters. This behavior can be changed by setting persistent to False. The only difference between a persistent buffer and a non-persistent buffer is that the latter will not be a part of this module’s state_dict.
Buffers can be accessed as attributes using given names.
Example:


Registers a forward hook on the module.
The hook will be called every time after forward() has computed an output. It should have the following signature:
The input contains only the positional arguments given to the module. Keyword arguments won’t be passed to the hooks and only to the forward. The hook can modify the output. It can modify the input inplace but it will not have effect on forward since this is called after forward() is called.
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle


Registers a forward pre-hook on the module.
The hook will be called every time before forward() is invoked. It should have the following signature:
The input contains only the positional arguments given to the module. Keyword arguments won’t be passed to the hooks and only to the forward. The hook can modify the input. User can either return a tuple or a single modified value in the hook. We will wrap the value into a tuple if a single value is returned(unless that value is already a tuple).
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle


Registers a backward hook on the module.
The hook will be called every time the gradients with respect to module inputs are computed. The hook should have the following signature:
The grad_input and grad_output are tuples that contain the gradients with respect to the inputs and outputs respectively. The hook should not modify its arguments, but it can optionally return a new gradient with respect to the input that will be used in place of grad_input in subsequent computations. grad_input will only correspond to the inputs given as positional arguments and all kwarg arguments are ignored. Entries in grad_input and grad_output will be None for all non-Tensor arguments.
Warning
Modifying inputs or outputs inplace is not allowed when using backward hooks and will raise an error.
a handle that can be used to remove the added hook by calling handle.remove()
torch.utils.hooks.RemovableHandle


Adds a parameter to the module.
The parameter can be accessed as an attribute using given name.


Change if autograd should record operations on parameters in this module.
This method sets the parameters’ requires_grad attributes in-place.
This method is helpful for freezing part of the module for finetuning or training parts of a model individually (e.g., GAN training).
requires_grad (bool) – whether autograd should record operations on parameters in this module. Default: True.
self
Module


Returns a dictionary containing a whole state of the module.
Both parameters and persistent buffers (e.g. running averages) are included. Keys are corresponding parameter and buffer names.
a dictionary containing a whole state of the module
dict
Example:


Moves and/or casts the parameters and buffers.
This can be called as
Its signature is similar to torch.Tensor.to(), but only accepts floating point or complex dtype`s. In addition, this method will
only cast the floating point or complex parameters and buffers to :attr:`dtype (if given). The integral parameters and buffers will be moved device, if that is given, but with dtypes unchanged. When non_blocking is set, it tries to convert/move asynchronously with respect to the host if possible, e.g., moving CPU Tensors with pinned memory to CUDA devices.
See below for examples.
Note
This method modifies the module in-place.
self
Module
Examples:


Sets the module in training mode.
This has any effect only on certain modules. See documentations of particular modules for details of their behaviors in training/evaluation mode, if they are affected, e.g. Dropout, BatchNorm, etc.
mode (bool) – whether to set training mode (True) or evaluation mode (False). Default: True.
self
Module


Casts all parameters and buffers to dst_type.
dst_type (type or string) – the desired type
self
Module


Moves all model parameters and buffers to the XPU.
This also makes associated parameters and buffers different objects. So it should be called before constructing optimizer if the module will live on XPU while being optimized.
device (int, optional) – if specified, all parameters will be copied to that device
self
Module


Sets gradients of all model parameters to zero. See similar function under torch.optim.Optimizer for more context.
set_to_none (bool) – instead of setting to zero, set the grads to None. See torch.optim.Optimizer.zero_grad() for details.


Compiles fn when it is first called during tracing. torch.jit.script has a non-negligible start up time when it is first called due to lazy-initializations of many compiler builtins. Therefore you should not use it in library code. However, you may want to have parts of your library work in tracing even if they use control flow. In these cases, you should use @torch.jit.script_if_tracing to substitute for torch.jit.script.
fn – A function to compile.
If called during tracing, a ScriptFunction created by torch.jit.script is returned. Otherwise, the original function fn is returned.


Trace a function and return an executable or ScriptFunction that will be optimized using just-in-time compilation. Tracing is ideal for code that operates only on Tensors and lists, dictionaries, and tuples of Tensors.
Using torch.jit.trace and torch.jit.trace_module, you can turn an existing module or Python function into a TorchScript ScriptFunction or ScriptModule. You must provide example inputs, and we run the function, recording the operations performed on all the tensors.
This module also contains any parameters that the original module had as well.
Warning
Tracing only correctly records functions and modules which are not data dependent (e.g., do not have conditionals on data in tensors) and do not have any untracked external dependencies (e.g., perform input/output or access global variables). Tracing only records operations done when the given function is run on the given tensors. Therefore, the returned ScriptModule will always run the same traced graph on any input. This has some important implications when your module is expected to run different sets of operations, depending on the input and/or the module state. For example,
In cases like these, tracing would not be appropriate and scripting is a better choice. If you trace such models, you may silently get incorrect results on subsequent invocations of the model. The tracer will try to emit warnings when doing something that may cause an incorrect trace to be produced.
If func is nn.Module or forward of nn.Module, trace returns a ScriptModule object with a single forward method containing the traced code. The returned ScriptModule will have the same set of sub-modules and parameters as the original nn.Module. If func is a standalone function, trace returns ScriptFunction.
Example (tracing a function):
Example (tracing an existing module):


Trace a module and return an executable ScriptModule that will be optimized using just-in-time compilation. When a module is passed to torch.jit.trace, only the forward method is run and traced. With trace_module, you can specify a dictionary of method names to example inputs to trace (see the inputs) argument below.
See torch.jit.trace for more information on tracing.
A ScriptModule object with a single forward method containing the traced code. When func is a torch.nn.Module, the returned ScriptModule will have the same set of sub-modules and parameters as func.
Example (tracing a module with multiple methods):


This decorator indicates to the compiler that a function or method should be ignored and replaced with the raising of an exception. This allows you to leave code in your model that is not yet TorchScript compatible and still export your model.
Example (using @torch.jit.unused on a method):


Forces completion of a torch.jit.Future[T] asynchronous task, returning the result of the task. See fork() for docs and examples. :param func: an asynchronous task reference, created through torch.jit.fork :type func: torch.jit.Future[T]
the return value of the the completed task
T


Computes the Kaiser window with window length window_length and shape parameter beta.
Let I_0 be the zeroth order modified Bessel function of the first kind (see torch.i0()) and N = L - 1 if periodic is False and L if periodic is True, where L is the window_length. This function computes:
Calling torch.kaiser_window(L, B, periodic=True) is equivalent to calling torch.kaiser_window(L + 1, B, periodic=False)[:-1]). The periodic argument is intended as a helpful shorthand to produce a periodic window as input to functions like torch.stft().
Note
If window_length is one, then the returned window is a single element tensor containing a one.


Computes the Kronecker product, denoted by ⊗\otimes , of input and other.
If input is a (a0×a1×⋯×an)(a_0 \times a_1 \times \dots \times a_n)  tensor and other is a (b0×b1×⋯×bn)(b_0 \times b_1 \times \dots \times b_n)  tensor, the result will be a (a0∗b0×a1∗b1×⋯×an∗bn)(a_0*b_0 \times a_1*b_1 \times \dots \times a_n*b_n)  tensor with the following entries:
where kt=it∗bt+jtk_t = i_t * b_t + j_t  for 0≤t≤n0 \leq t \leq n . If one tensor has fewer dimensions than the other it is unsqueezed until it has the same number of dimensions.
Supports real-valued and complex-valued inputs.
Note
This function generalizes the typical definition of the Kronecker product for two matrices to two tensors, as described above. When input is a (m×n)(m \times n)  matrix and other is a (p×q)(p \times q)  matrix, the result will be a (p∗m×q∗n)(p*m \times q*n)  block matrix:
where input is A\mathbf{A}  and other is B\mathbf{B} .
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:


Returns a namedtuple (values, indices) where values is the k th smallest element of each row of the input tensor in the given dimension dim. And indices is the index location of each element found.
If dim is not given, the last dimension of the input is chosen.
If keepdim is True, both the values and indices tensors are the same size as input, except in the dimension dim where they are of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in both the values and indices tensors having 1 fewer dimension than the input tensor.
Note
When input is a CUDA tensor and there are multiple valid k th values, this function may nondeterministically return indices for any of them.
out (tuple, optional) – the output tuple of (Tensor, LongTensor) can be optionally given to be used as output buffers
Example:


Computes the element-wise least common multiple (LCM) of input and other.
Both input and other must have integer types.
Note
This defines lcm(0,0)=0lcm(0, 0) = 0  and lcm(0,a)=0lcm(0, a) = 0 .
out (Tensor, optional) – the output tensor.
Example:


Multiplies input by 2**:attr:other.
Typically this function is used to construct floating point numbers by multiplying mantissas in input with integral powers of two created from the exponents in :attr:’other’.
out (Tensor, optional) – the output tensor.


Computes input≤other\text{input} \leq \text{other}  element-wise.
The second argument can be a number or a tensor whose shape is broadcastable with the first argument.
out (Tensor, optional) – the output tensor.
A boolean tensor that is True where input is less than or equal to other and False elsewhere
Example:


Does a linear interpolation of two tensors start (given by input) and end based on a scalar or tensor weight and returns the resulting out tensor.
The shapes of start and end must be broadcastable. If weight is a tensor, then the shapes of weight, start, and end must be broadcastable.
out (Tensor, optional) – the output tensor.
Example:


Computes the logarithm of the gamma function on input.
Example:


Common linear algebra operations.
This module is in BETA. New functions are still being added, and some functions may change in future PyTorch releases. See the documentation of each function for details.
Computes the Cholesky decomposition of a Hermitian (or symmetric for real-valued matrices) positive-definite matrix or the Cholesky decompositions for a batch of such matrices. Each decomposition has the form:
where LL  is a lower-triangular matrix and LHL^H  is the conjugate transpose of LL , which is just a transpose for the case of real-valued input matrices. In code it translates to input = L @ L.t() if input is real-valued and input = L @ L.conj().t() if input is complex-valued. The batch of LL  matrices is returned.
Supports real-valued and complex-valued inputs.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
LAPACK’s potrf is used for CPU inputs, and MAGMA’s potrf is used for CUDA inputs.
Note
If input is not a Hermitian positive-definite matrix, or if it’s a batch of matrices and one or more of them is not a Hermitian positive-definite matrix, then a RuntimeError will be thrown. If input is a batch of matrices, then the error message will include the batch index of the first matrix that is not Hermitian positive-definite.
input (Tensor) – the input tensor of size (∗,n,n)(*, n, n)  consisting of Hermitian positive-definite n×nn \times n  matrices, where ∗*  is zero or more batch dimensions.
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:
Computes the condition number of a matrix input, or of each matrix in a batched input, using the matrix norm defined by p.
For norms {‘fro’, ‘nuc’, inf, -inf, 1, -1} this is defined as the matrix norm of input times the matrix norm of the inverse of input computed using torch.linalg.norm(). While for norms {None, 2, -2} this is defined as the ratio between the largest and smallest singular values computed using torch.linalg.svd().
This function supports float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function may synchronize that device with the CPU depending on which norm p is used.
Note
For norms {None, 2, -2}, input may be a non-square matrix or batch of non-square matrices. For other norms, however, input must be a square matrix or a batch of square matrices, and if this requirement is not satisfied a RuntimeError will be thrown.
Note
For norms {‘fro’, ‘nuc’, inf, -inf, 1, -1} if input is a non-invertible matrix then a tensor containing infinity will be returned. If input is a batch of matrices and one or more of them is not invertible then a RuntimeError will be thrown.
p (int, float, inf, -inf, 'fro', 'nuc', optional) –
the type of the matrix norm to use in the computations. inf refers to float('inf'), numpy’s inf object, or any equivalent object. The following norms can be used:
p
norm for matrices
None
ratio of the largest singular value to the smallest singular value
’fro’
Frobenius norm
’nuc’
nuclear norm
inf
max(sum(abs(x), dim=1))
-inf
min(sum(abs(x), dim=1))
1
max(sum(abs(x), dim=0))
-1
min(sum(abs(x), dim=0))
2
ratio of the largest singular value to the smallest singular value
-2
ratio of the smallest singular value to the largest singular value
Default: None
out (Tensor, optional) – tensor to write the output to. Default is None.
The condition number of input. The output dtype is always real valued even for complex inputs (e.g. float if input is cfloat).
Examples:
Computes the determinant of a square matrix input, or of each square matrix in a batched input.
This function supports float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The determinant is computed using LU factorization. LAPACK’s getrf is used for CPU inputs, and MAGMA’s getrf is used for CUDA inputs.
Note
Backward through det internally uses torch.linalg.svd() when input is not invertible. In this case, double backward through det will be unstable when input doesn’t have distinct singular values. See torch.linalg.svd() for more details.
input (Tensor) – the input matrix of size (n, n) or the batch of matrices of size (*, n, n) where * is one or more batch dimensions.
Example:
Calculates the sign and natural logarithm of the absolute value of a square matrix’s determinant, or of the absolute values of the determinants of a batch of square matrices input. The determinant can be computed with sign * exp(logabsdet).
Supports input of float, double, cfloat and cdouble datatypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The determinant is computed using LU factorization. LAPACK’s getrf is used for CPU inputs, and MAGMA’s getrf is used for CUDA inputs.
Note
For matrices that have zero determinant, this returns (0, -inf). If input is batched then the entries in the result tensors corresponding to matrices with the zero determinant have sign 0 and the natural logarithm of the absolute value of the determinant -inf.
input (Tensor) – the input matrix of size (n,n)(n, n)  or the batch of matrices of size (∗,n,n)(*, n, n)  where ∗*  is one or more batch dimensions.
out (tuple, optional) – tuple of two tensors to write the output to.
A namedtuple (sign, logabsdet) containing the sign of the determinant and the natural logarithm of the absolute value of determinant, respectively.
Example:
Computes the eigenvalues and eigenvectors of a complex Hermitian (or real symmetric) matrix input, or of each such matrix in a batched input.
For a single matrix input, the tensor of eigenvalues w and the tensor of eigenvectors V decompose the input such that input = V diag(w) Vᴴ, where Vᴴ is the transpose of V for real-valued input, or the conjugate transpose of V for complex-valued input.
Since the matrix or matrices in input are assumed to be Hermitian, the imaginary part of their diagonals is always treated as zero. When UPLO is “L”, its default value, only the lower triangular part of each matrix is used in the computation. When UPLO is “U” only the upper triangular part of each matrix is used.
Supports input of float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The eigenvalues/eigenvectors are computed using LAPACK’s syevd and heevd routines for CPU inputs, and MAGMA’s syevd and heevd routines for CUDA inputs.
Note
The eigenvalues of real symmetric or complex Hermitian matrices are always real.
Note
The eigenvectors of matrices are not unique, so any eigenvector multiplied by a constant remains a valid eigenvector. This function may compute different eigenvector representations on different device types. Usually the difference is only in the sign of the eigenvector.
Note
See torch.linalg.eigvalsh() for a related function that computes only eigenvalues. However, that function is not differentiable.
out (tuple, optional) – tuple of two tensors to write the output to. Default is None.
A namedtuple (eigenvalues, eigenvectors) containing
The eigenvalues in ascending order.
The orthonormal eigenvectors of the input.
(Tensor, Tensor)
Examples:
Computes the eigenvalues of a complex Hermitian (or real symmetric) matrix input, or of each such matrix in a batched input. The eigenvalues are returned in ascending order.
Since the matrix or matrices in input are assumed to be Hermitian, the imaginary part of their diagonals is always treated as zero. When UPLO is “L”, its default value, only the lower triangular part of each matrix is used in the computation. When UPLO is “U” only the upper triangular part of each matrix is used.
Supports input of float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The eigenvalues are computed using LAPACK’s syevd and heevd routines for CPU inputs, and MAGMA’s syevd and heevd routines for CUDA inputs.
Note
The eigenvalues of real symmetric or complex Hermitian matrices are always real.
Note
This function doesn’t support backpropagation, please use torch.linalg.eigh() instead, which also computes the eigenvectors.
Note
See torch.linalg.eigh() for a related function that computes both eigenvalues and eigenvectors.
out (Tensor, optional) – tensor to write the output to. Default is None.
Examples:
Computes the numerical rank of a matrix input, or of each matrix in a batched input.
The matrix rank is computed as the number of singular values (or absolute eigenvalues when hermitian is True) that are greater than the specified tol threshold.
If tol is not specified, tol is set to S.max(dim=-1)*max(input.shape[-2:])*eps, where S is the singular values (or absolute eigenvalues when hermitian is True), and eps is the epsilon value for the datatype of input. The epsilon value can be obtained using the eps attribute of torch.finfo.
Supports input of float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The matrix rank is computed using singular value decomposition (see torch.linalg.svd()) by default. If hermitian is True, then input is assumed to be Hermitian (symmetric if real-valued), and the computation is done by obtaining the eigenvalues (see torch.linalg.eigvalsh()).
out (Tensor, optional) – tensor to write the output to. Default is None.
Examples:
Returns the matrix norm or vector norm of a given tensor.
This function can calculate one of eight different types of matrix norms, or one of an infinite number of vector norms, depending on both the number of reduction dimensions and the value of the ord parameter.
ord (int, float, inf, -inf, 'fro', 'nuc', optional) –
The order of norm. inf refers to float('inf'), numpy’s inf object, or any equivalent object. The following norms can be calculated:
ord
norm for matrices
norm for vectors
None
Frobenius norm
2-norm
’fro’
Frobenius norm
– not supported –
‘nuc’
nuclear norm
– not supported –
inf
max(sum(abs(x), dim=1))
max(abs(x))
-inf
min(sum(abs(x), dim=1))
min(abs(x))
0
– not supported –
sum(x != 0)
1
max(sum(abs(x), dim=0))
as below
-1
min(sum(abs(x), dim=0))
as below
2
2-norm (largest sing. value)
as below
-2
smallest singular value
as below
other
– not supported –
sum(abs(x)**ord)**(1./ord)
Default: None
Examples:
Using the dim argument to compute vector norms:
Using the dim argument to compute matrix norms:
Computes the pseudo-inverse (also known as the Moore-Penrose inverse) of a matrix input, or of each matrix in a batched input.
The singular values (or the absolute values of the eigenvalues when hermitian is True) that are below the specified rcond threshold are treated as zero and discarded in the computation.
Supports input of float, double, cfloat and cdouble datatypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The pseudo-inverse is computed using singular value decomposition (see torch.linalg.svd()) by default. If hermitian is True, then input is assumed to be Hermitian (symmetric if real-valued), and the computation of the pseudo-inverse is done by obtaining the eigenvalues and eigenvectors (see torch.linalg.eigh()).
Note
If singular value decomposition or eigenvalue decomposition algorithms do not converge then a RuntimeError will be thrown.
out (Tensor, optional) – The output tensor. Ignored if None. Default is None.
Examples:
Computes the singular value decomposition of either a matrix or batch of matrices input.” The singular value decomposition is represented as a namedtuple (U, S, Vh), such that input=U@diag(S)×Vhinput = U \mathbin{@} diag(S) \times Vh . If input is a batch of tensors, then U, S, and Vh are also batched with the same batch dimensions as input.
If full_matrices is False (default), the method returns the reduced singular value decomposition i.e., if the last two dimensions of input are m and n, then the returned U and V matrices will contain only min(n,m)min(n, m)  orthonormal columns.
If compute_uv is False, the returned U and Vh will be empy tensors with no elements and the same device as input. The full_matrices argument has no effect when compute_uv is False.
The dtypes of U and V are the same as input’s. S will always be real-valued, even if input is complex.
Note
Unlike NumPy’s linalg.svd, this always returns a namedtuple of three tensors, even when compute_uv=False. This behavior may change in a future PyTorch release.
Note
The singular values are returned in descending order. If input is a batch of matrices, then the singular values of each matrix in the batch is returned in descending order.
Note
The implementation of SVD on CPU uses the LAPACK routine ?gesdd (a divide-and-conquer algorithm) instead of ?gesvd for speed. Analogously, the SVD on GPU uses the cuSOLVER routines gesvdj and gesvdjBatched on CUDA 10.1.243 and later, and uses the MAGMA routine gesdd on earlier versions of CUDA.
Note
The returned matrix U will be transposed, i.e. with strides U.contiguous().transpose(-2, -1).stride().
Note
Gradients computed using U and Vh may be unstable if input is not full rank or has non-unique singular values.
Note
When full_matrices = True, the gradients on U[..., :, min(m, n):] and V[..., :, min(m, n):] will be ignored in backward as those vectors can be arbitrary bases of the subspaces.
Note
The S tensor can only be used to compute gradients if compute_uv is True.
Note
Since U and V of an SVD is not unique, each vector can be multiplied by an arbitrary phase factor eiϕe^{i \phi}  while the SVD result is still correct. Different platforms, like Numpy, or inputs on different device types, may produce different U and V tensors.
Example:
Computes the solution x to the matrix equation matmul(input, x) = other with a square matrix, or batches of such matrices, input and one or more right-hand side vectors other. If input is batched and other is not, then other is broadcast to have the same batch dimensions as input. The resulting tensor has the same shape as the (possibly broadcast) other.
Supports input of float, double, cfloat and cdouble dtypes.
Note
If input is a non-square or non-invertible matrix, or a batch containing non-square matrices or one or more non-invertible matrices, then a RuntimeError will be thrown.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:
Batched input:
Computes a tensor input_inv such that tensordot(input_inv, input, ind) == I_n (inverse tensor equation), where I_n is the n-dimensional identity tensor and n is equal to input.ndim. The resulting tensor input_inv has shape equal to input.shape[ind:] + input.shape[:ind].
Supports input of float, double, cfloat and cdouble data types.
Note
If input is not invertible or does not satisfy the requirement prod(input.shape[ind:]) == prod(input.shape[:ind]), then a RuntimeError will be thrown.
Note
When input is a 2-dimensional tensor and ind=1, this function computes the (multiplicative) inverse of input, equivalent to calling torch.inverse().
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:
Computes a tensor x such that tensordot(input, x, dims=x.ndim) = other. The resulting tensor x has the same shape as input[other.ndim:].
Supports real-valued and complex-valued inputs.
Note
If input does not satisfy the requirement prod(input.shape[other.ndim:]) == prod(input.shape[:other.ndim]) after (optionally) moving the dimensions using dims, then a RuntimeError will be thrown.
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:
Computes the multiplicative inverse matrix of a square matrix input, or of each square matrix in a batched input. The result satisfies the relation:
matmul(inv(input),input) = matmul(input,inv(input)) = eye(input.shape[0]).expand_as(input).
Supports input of float, double, cfloat and cdouble data types.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The inverse matrix is computed using LAPACK’s getrf and getri routines for CPU inputs. For CUDA inputs, cuSOLVER’s getrf and getrs routines as well as cuBLAS’ getrf and getri routines are used if CUDA version >= 10.1.243, otherwise MAGMA’s getrf and getri routines are used instead.
Note
If input is a non-invertible matrix or non-square matrix, or batch with at least one such matrix, then a RuntimeError will be thrown.
input (Tensor) – the square (n, n) matrix or the batch of such matrices of size (*, n, n) where * is one or more batch dimensions.
out (Tensor, optional) – The output tensor. Ignored if None. Default is None.
Examples:
Computes the QR decomposition of a matrix or a batch of matrices input, and returns a namedtuple (Q, R) of tensors such that input=QR\text{input} = Q R  with QQ  being an orthogonal matrix or batch of orthogonal matrices and RR  being an upper triangular matrix or batch of upper triangular matrices.
Depending on the value of mode this function returns the reduced or complete QR factorization. See below for a list of valid modes.
Note
Differences with numpy.linalg.qr:
Note
Backpropagation is not supported for mode='r'. Use mode='reduced' instead.
Backpropagation is also not supported if the first min(input.size(−1),input.size(−2))\min(input.size(-1), input.size(-2))  columns of any matrix in input are not linearly independent. While no error will be thrown when this occurs the values of the “gradient” produced may be anything. This behavior may change in the future.
Note
This function uses LAPACK for CPU inputs and MAGMA for CUDA inputs, and may produce different (valid) decompositions on different device types or different platforms.
mode (str, optional) –
if k = min(m, n) then:
out (tuple, optional) – tuple of Q and R tensors. The dimensions of Q and R are detailed in the description of mode above.
Example:


Computes the Cholesky decomposition of a Hermitian (or symmetric for real-valued matrices) positive-definite matrix or the Cholesky decompositions for a batch of such matrices. Each decomposition has the form:
where LL  is a lower-triangular matrix and LHL^H  is the conjugate transpose of LL , which is just a transpose for the case of real-valued input matrices. In code it translates to input = L @ L.t() if input is real-valued and input = L @ L.conj().t() if input is complex-valued. The batch of LL  matrices is returned.
Supports real-valued and complex-valued inputs.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
LAPACK’s potrf is used for CPU inputs, and MAGMA’s potrf is used for CUDA inputs.
Note
If input is not a Hermitian positive-definite matrix, or if it’s a batch of matrices and one or more of them is not a Hermitian positive-definite matrix, then a RuntimeError will be thrown. If input is a batch of matrices, then the error message will include the batch index of the first matrix that is not Hermitian positive-definite.
input (Tensor) – the input tensor of size (∗,n,n)(*, n, n)  consisting of Hermitian positive-definite n×nn \times n  matrices, where ∗*  is zero or more batch dimensions.
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:


Computes the condition number of a matrix input, or of each matrix in a batched input, using the matrix norm defined by p.
For norms {‘fro’, ‘nuc’, inf, -inf, 1, -1} this is defined as the matrix norm of input times the matrix norm of the inverse of input computed using torch.linalg.norm(). While for norms {None, 2, -2} this is defined as the ratio between the largest and smallest singular values computed using torch.linalg.svd().
This function supports float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function may synchronize that device with the CPU depending on which norm p is used.
Note
For norms {None, 2, -2}, input may be a non-square matrix or batch of non-square matrices. For other norms, however, input must be a square matrix or a batch of square matrices, and if this requirement is not satisfied a RuntimeError will be thrown.
Note
For norms {‘fro’, ‘nuc’, inf, -inf, 1, -1} if input is a non-invertible matrix then a tensor containing infinity will be returned. If input is a batch of matrices and one or more of them is not invertible then a RuntimeError will be thrown.
p (int, float, inf, -inf, 'fro', 'nuc', optional) –
the type of the matrix norm to use in the computations. inf refers to float('inf'), numpy’s inf object, or any equivalent object. The following norms can be used:
p
norm for matrices
None
ratio of the largest singular value to the smallest singular value
’fro’
Frobenius norm
’nuc’
nuclear norm
inf
max(sum(abs(x), dim=1))
-inf
min(sum(abs(x), dim=1))
1
max(sum(abs(x), dim=0))
-1
min(sum(abs(x), dim=0))
2
ratio of the largest singular value to the smallest singular value
-2
ratio of the smallest singular value to the largest singular value
Default: None
out (Tensor, optional) – tensor to write the output to. Default is None.
The condition number of input. The output dtype is always real valued even for complex inputs (e.g. float if input is cfloat).
Examples:


Computes the determinant of a square matrix input, or of each square matrix in a batched input.
This function supports float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The determinant is computed using LU factorization. LAPACK’s getrf is used for CPU inputs, and MAGMA’s getrf is used for CUDA inputs.
Note
Backward through det internally uses torch.linalg.svd() when input is not invertible. In this case, double backward through det will be unstable when input doesn’t have distinct singular values. See torch.linalg.svd() for more details.
input (Tensor) – the input matrix of size (n, n) or the batch of matrices of size (*, n, n) where * is one or more batch dimensions.
Example:


Computes the eigenvalues and eigenvectors of a complex Hermitian (or real symmetric) matrix input, or of each such matrix in a batched input.
For a single matrix input, the tensor of eigenvalues w and the tensor of eigenvectors V decompose the input such that input = V diag(w) Vᴴ, where Vᴴ is the transpose of V for real-valued input, or the conjugate transpose of V for complex-valued input.
Since the matrix or matrices in input are assumed to be Hermitian, the imaginary part of their diagonals is always treated as zero. When UPLO is “L”, its default value, only the lower triangular part of each matrix is used in the computation. When UPLO is “U” only the upper triangular part of each matrix is used.
Supports input of float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The eigenvalues/eigenvectors are computed using LAPACK’s syevd and heevd routines for CPU inputs, and MAGMA’s syevd and heevd routines for CUDA inputs.
Note
The eigenvalues of real symmetric or complex Hermitian matrices are always real.
Note
The eigenvectors of matrices are not unique, so any eigenvector multiplied by a constant remains a valid eigenvector. This function may compute different eigenvector representations on different device types. Usually the difference is only in the sign of the eigenvector.
Note
See torch.linalg.eigvalsh() for a related function that computes only eigenvalues. However, that function is not differentiable.
out (tuple, optional) – tuple of two tensors to write the output to. Default is None.
A namedtuple (eigenvalues, eigenvectors) containing
The eigenvalues in ascending order.
The orthonormal eigenvectors of the input.
(Tensor, Tensor)
Examples:


Computes the eigenvalues of a complex Hermitian (or real symmetric) matrix input, or of each such matrix in a batched input. The eigenvalues are returned in ascending order.
Since the matrix or matrices in input are assumed to be Hermitian, the imaginary part of their diagonals is always treated as zero. When UPLO is “L”, its default value, only the lower triangular part of each matrix is used in the computation. When UPLO is “U” only the upper triangular part of each matrix is used.
Supports input of float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The eigenvalues are computed using LAPACK’s syevd and heevd routines for CPU inputs, and MAGMA’s syevd and heevd routines for CUDA inputs.
Note
The eigenvalues of real symmetric or complex Hermitian matrices are always real.
Note
This function doesn’t support backpropagation, please use torch.linalg.eigh() instead, which also computes the eigenvectors.
Note
See torch.linalg.eigh() for a related function that computes both eigenvalues and eigenvectors.
out (Tensor, optional) – tensor to write the output to. Default is None.
Examples:


Computes the multiplicative inverse matrix of a square matrix input, or of each square matrix in a batched input. The result satisfies the relation:
matmul(inv(input),input) = matmul(input,inv(input)) = eye(input.shape[0]).expand_as(input).
Supports input of float, double, cfloat and cdouble data types.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The inverse matrix is computed using LAPACK’s getrf and getri routines for CPU inputs. For CUDA inputs, cuSOLVER’s getrf and getrs routines as well as cuBLAS’ getrf and getri routines are used if CUDA version >= 10.1.243, otherwise MAGMA’s getrf and getri routines are used instead.
Note
If input is a non-invertible matrix or non-square matrix, or batch with at least one such matrix, then a RuntimeError will be thrown.
input (Tensor) – the square (n, n) matrix or the batch of such matrices of size (*, n, n) where * is one or more batch dimensions.
out (Tensor, optional) – The output tensor. Ignored if None. Default is None.
Examples:


Computes the numerical rank of a matrix input, or of each matrix in a batched input.
The matrix rank is computed as the number of singular values (or absolute eigenvalues when hermitian is True) that are greater than the specified tol threshold.
If tol is not specified, tol is set to S.max(dim=-1)*max(input.shape[-2:])*eps, where S is the singular values (or absolute eigenvalues when hermitian is True), and eps is the epsilon value for the datatype of input. The epsilon value can be obtained using the eps attribute of torch.finfo.
Supports input of float, double, cfloat and cdouble dtypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The matrix rank is computed using singular value decomposition (see torch.linalg.svd()) by default. If hermitian is True, then input is assumed to be Hermitian (symmetric if real-valued), and the computation is done by obtaining the eigenvalues (see torch.linalg.eigvalsh()).
out (Tensor, optional) – tensor to write the output to. Default is None.
Examples:


Returns the matrix norm or vector norm of a given tensor.
This function can calculate one of eight different types of matrix norms, or one of an infinite number of vector norms, depending on both the number of reduction dimensions and the value of the ord parameter.
ord (int, float, inf, -inf, 'fro', 'nuc', optional) –
The order of norm. inf refers to float('inf'), numpy’s inf object, or any equivalent object. The following norms can be calculated:
ord
norm for matrices
norm for vectors
None
Frobenius norm
2-norm
’fro’
Frobenius norm
– not supported –
‘nuc’
nuclear norm
– not supported –
inf
max(sum(abs(x), dim=1))
max(abs(x))
-inf
min(sum(abs(x), dim=1))
min(abs(x))
0
– not supported –
sum(x != 0)
1
max(sum(abs(x), dim=0))
as below
-1
min(sum(abs(x), dim=0))
as below
2
2-norm (largest sing. value)
as below
-2
smallest singular value
as below
other
– not supported –
sum(abs(x)**ord)**(1./ord)
Default: None
Examples:
Using the dim argument to compute vector norms:
Using the dim argument to compute matrix norms:


Computes the pseudo-inverse (also known as the Moore-Penrose inverse) of a matrix input, or of each matrix in a batched input.
The singular values (or the absolute values of the eigenvalues when hermitian is True) that are below the specified rcond threshold are treated as zero and discarded in the computation.
Supports input of float, double, cfloat and cdouble datatypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The pseudo-inverse is computed using singular value decomposition (see torch.linalg.svd()) by default. If hermitian is True, then input is assumed to be Hermitian (symmetric if real-valued), and the computation of the pseudo-inverse is done by obtaining the eigenvalues and eigenvectors (see torch.linalg.eigh()).
Note
If singular value decomposition or eigenvalue decomposition algorithms do not converge then a RuntimeError will be thrown.
out (Tensor, optional) – The output tensor. Ignored if None. Default is None.
Examples:


Computes the QR decomposition of a matrix or a batch of matrices input, and returns a namedtuple (Q, R) of tensors such that input=QR\text{input} = Q R  with QQ  being an orthogonal matrix or batch of orthogonal matrices and RR  being an upper triangular matrix or batch of upper triangular matrices.
Depending on the value of mode this function returns the reduced or complete QR factorization. See below for a list of valid modes.
Note
Differences with numpy.linalg.qr:
Note
Backpropagation is not supported for mode='r'. Use mode='reduced' instead.
Backpropagation is also not supported if the first min(input.size(−1),input.size(−2))\min(input.size(-1), input.size(-2))  columns of any matrix in input are not linearly independent. While no error will be thrown when this occurs the values of the “gradient” produced may be anything. This behavior may change in the future.
Note
This function uses LAPACK for CPU inputs and MAGMA for CUDA inputs, and may produce different (valid) decompositions on different device types or different platforms.
mode (str, optional) –
if k = min(m, n) then:
out (tuple, optional) – tuple of Q and R tensors. The dimensions of Q and R are detailed in the description of mode above.
Example:


Calculates the sign and natural logarithm of the absolute value of a square matrix’s determinant, or of the absolute values of the determinants of a batch of square matrices input. The determinant can be computed with sign * exp(logabsdet).
Supports input of float, double, cfloat and cdouble datatypes.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
Note
The determinant is computed using LU factorization. LAPACK’s getrf is used for CPU inputs, and MAGMA’s getrf is used for CUDA inputs.
Note
For matrices that have zero determinant, this returns (0, -inf). If input is batched then the entries in the result tensors corresponding to matrices with the zero determinant have sign 0 and the natural logarithm of the absolute value of the determinant -inf.
input (Tensor) – the input matrix of size (n,n)(n, n)  or the batch of matrices of size (∗,n,n)(*, n, n)  where ∗*  is one or more batch dimensions.
out (tuple, optional) – tuple of two tensors to write the output to.
A namedtuple (sign, logabsdet) containing the sign of the determinant and the natural logarithm of the absolute value of determinant, respectively.
Example:


Computes the solution x to the matrix equation matmul(input, x) = other with a square matrix, or batches of such matrices, input and one or more right-hand side vectors other. If input is batched and other is not, then other is broadcast to have the same batch dimensions as input. The resulting tensor has the same shape as the (possibly broadcast) other.
Supports input of float, double, cfloat and cdouble dtypes.
Note
If input is a non-square or non-invertible matrix, or a batch containing non-square matrices or one or more non-invertible matrices, then a RuntimeError will be thrown.
Note
When given inputs on a CUDA device, this function synchronizes that device with the CPU.
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:
Batched input:


Computes the singular value decomposition of either a matrix or batch of matrices input.” The singular value decomposition is represented as a namedtuple (U, S, Vh), such that input=U@diag(S)×Vhinput = U \mathbin{@} diag(S) \times Vh . If input is a batch of tensors, then U, S, and Vh are also batched with the same batch dimensions as input.
If full_matrices is False (default), the method returns the reduced singular value decomposition i.e., if the last two dimensions of input are m and n, then the returned U and V matrices will contain only min(n,m)min(n, m)  orthonormal columns.
If compute_uv is False, the returned U and Vh will be empy tensors with no elements and the same device as input. The full_matrices argument has no effect when compute_uv is False.
The dtypes of U and V are the same as input’s. S will always be real-valued, even if input is complex.
Note
Unlike NumPy’s linalg.svd, this always returns a namedtuple of three tensors, even when compute_uv=False. This behavior may change in a future PyTorch release.
Note
The singular values are returned in descending order. If input is a batch of matrices, then the singular values of each matrix in the batch is returned in descending order.
Note
The implementation of SVD on CPU uses the LAPACK routine ?gesdd (a divide-and-conquer algorithm) instead of ?gesvd for speed. Analogously, the SVD on GPU uses the cuSOLVER routines gesvdj and gesvdjBatched on CUDA 10.1.243 and later, and uses the MAGMA routine gesdd on earlier versions of CUDA.
Note
The returned matrix U will be transposed, i.e. with strides U.contiguous().transpose(-2, -1).stride().
Note
Gradients computed using U and Vh may be unstable if input is not full rank or has non-unique singular values.
Note
When full_matrices = True, the gradients on U[..., :, min(m, n):] and V[..., :, min(m, n):] will be ignored in backward as those vectors can be arbitrary bases of the subspaces.
Note
The S tensor can only be used to compute gradients if compute_uv is True.
Note
Since U and V of an SVD is not unique, each vector can be multiplied by an arbitrary phase factor eiϕe^{i \phi}  while the SVD result is still correct. Different platforms, like Numpy, or inputs on different device types, may produce different U and V tensors.
Example:


Computes a tensor input_inv such that tensordot(input_inv, input, ind) == I_n (inverse tensor equation), where I_n is the n-dimensional identity tensor and n is equal to input.ndim. The resulting tensor input_inv has shape equal to input.shape[ind:] + input.shape[:ind].
Supports input of float, double, cfloat and cdouble data types.
Note
If input is not invertible or does not satisfy the requirement prod(input.shape[ind:]) == prod(input.shape[:ind]), then a RuntimeError will be thrown.
Note
When input is a 2-dimensional tensor and ind=1, this function computes the (multiplicative) inverse of input, equivalent to calling torch.inverse().
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:


Computes a tensor x such that tensordot(input, x, dims=x.ndim) = other. The resulting tensor x has the same shape as input[other.ndim:].
Supports real-valued and complex-valued inputs.
Note
If input does not satisfy the requirement prod(input.shape[other.ndim:]) == prod(input.shape[:other.ndim]) after (optionally) moving the dimensions using dims, then a RuntimeError will be thrown.
out (Tensor, optional) – The output tensor. Ignored if None. Default: None
Examples:


Creates a one-dimensional tensor of size steps whose values are evenly spaced from start to end, inclusive. That is, the value are:
Warning
Not providing a value for steps is deprecated. For backwards compatibility, not providing a value for steps will create a tensor with 100 elements. Note that this behavior is not reflected in the documented function signature and should not be relied on. In a future PyTorch release, failing to provide a value for steps will throw a runtime error.
Example:


Loads an object saved with torch.save() from a file.
torch.load() uses Python’s unpickling facilities but treats storages, which underlie tensors, specially. They are first deserialized on the CPU and are then moved to the device they were saved from. If this fails (e.g. because the run time system doesn’t have certain devices), an exception is raised. However, storages can be dynamically remapped to an alternative set of devices using the map_location argument.
If map_location is a callable, it will be called once for each serialized storage with two arguments: storage and location. The storage argument will be the initial deserialization of the storage, residing on the CPU. Each serialized storage has a location tag associated with it which identifies the device it was saved from, and this tag is the second argument passed to map_location. The builtin location tags are 'cpu' for CPU tensors and 'cuda:device_id' (e.g. 'cuda:2') for CUDA tensors. map_location should return either None or a storage. If map_location returns a storage, it will be used as the final deserialized object, already moved to the right device. Otherwise, torch.load() will fall back to the default behavior, as if map_location wasn’t specified.
If map_location is a torch.device object or a string containing a device tag, it indicates the location where all tensors should be loaded.
Otherwise, if map_location is a dict, it will be used to remap location tags appearing in the file (keys), to ones that specify where to put the storages (values).
User extensions can register their own location tags and tagging and deserialization methods using torch.serialization.register_package().
Warning
torch.load() uses pickle module implicitly, which is known to be insecure. It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. Never load data that could have come from an untrusted source, or that could have been tampered with. Only load data you trust.
Note
When you call torch.load() on a file which contains GPU tensors, those tensors will be loaded to GPU by default. You can call torch.load(.., map_location='cpu') and then load_state_dict() to avoid GPU RAM surge when loading a model checkpoint.
Note
By default, we decode byte strings as utf-8. This is to avoid a common error case UnicodeDecodeError: 'ascii' codec can't decode byte 0x... when loading files saved by Python 2 in Python 3. If this default is incorrect, you may use an extra encoding keyword argument to specify how these objects should be loaded, e.g., encoding='latin1' decodes them to strings using latin1 encoding, and encoding='bytes' keeps them as byte arrays which can be decoded later with byte_array.decode(...).


Find the k largest (or smallest) eigenvalues and the corresponding eigenvectors of a symmetric positive defined generalized eigenvalue problem using matrix-free LOBPCG methods.
This function is a front-end to the following LOBPCG algorithms selectable via method argument:
method=”basic” - the LOBPCG method introduced by Andrew Knyazev, see [Knyazev2001]. A less robust method, may fail when Cholesky is applied to singular input.
method=”ortho” - the LOBPCG method with orthogonal basis selection [StathopoulosEtal2002]. A robust method.
Supported inputs are dense, sparse, and batches of dense matrices.
Note
In general, the basic method spends least time per iteration. However, the robust methods converge much faster and are more stable. So, the usage of the basic method is generally not recommended but there exist cases where the usage of the basic method may be preferred.
Warning
The backward method does not support sparse and complex inputs. It works only when B is not provided (i.e. B == None). We are actively working on extensions, and the details of the algorithms are going to be published promptly.
Warning
While it is assumed that A is symmetric, A.grad is not. To make sure that A.grad is symmetric, so that A - t * A.grad is symmetric in first-order optimization routines, prior to running lobpcg we do the following symmetrization map: A -> (A + A.t()) / 2. The map is performed only when the A requires gradients.
tracker (callable, optional) –
a function for tracing the iteration process. When specified, it is called at each iteration step with LOBPCG instance as an argument. The LOBPCG instance holds the full state of the iteration process in the following attributes:
iparams, fparams, bparams - dictionaries of integer, float, and boolean valued input parameters, respectively
ivars, fvars, bvars, tvars - dictionaries of integer, float, boolean, and Tensor valued iteration variables, respectively.
A, B, iK - input Tensor arguments.
E, X, S, R - iteration Tensor variables.
For instance:
ivars[“istep”] - the current iteration step X - the current approximation of eigenvectors E - the current approximation of eigenvalues R - the current residual ivars[“converged_count”] - the current number of converged eigenpairs tvars[“rerr”] - the current state of convergence criteria
Note that when tracker stores Tensor objects from the LOBPCG instance, it must make copies of these.
If tracker sets bvars[“force_stop”] = True, the iteration process will be hard-stopped.
tensor of eigenvalues of size (∗,k)(*, k)
X (Tensor): tensor of eigenvectors of size (∗,m,k)(*, m, k)
E (Tensor)
[Knyazev2001] Andrew V. Knyazev. (2001) Toward the Optimal Preconditioned Eigensolver: Locally Optimal Block Preconditioned Conjugate Gradient Method. SIAM J. Sci. Comput., 23(2), 517-541. (25 pages) https://epubs.siam.org/doi/abs/10.1137/S1064827500366124
[StathopoulosEtal2002] Andreas Stathopoulos and Kesheng Wu. (2002) A Block Orthogonalization Procedure with Constant Synchronization Requirements. SIAM J. Sci. Comput., 23(6), 2165-2182. (18 pages) https://epubs.siam.org/doi/10.1137/S1064827500370883
[DuerschEtal2018] Jed A. Duersch, Meiyue Shao, Chao Yang, Ming Gu. (2018) A Robust and Efficient Implementation of LOBPCG. SIAM J. Sci. Comput., 40(5), C655-C676. (22 pages) https://epubs.siam.org/doi/abs/10.1137/17M1129830


Returns a new tensor with the natural logarithm of the elements of input.
input (Tensor) – the input tensor.
out (Tensor, optional) – the output tensor.
Example:


Returns a new tensor with the logarithm to the base 10 of the elements of input.
input (Tensor) – the input tensor.
out (Tensor, optional) – the output tensor.
Example:


Returns a new tensor with the natural logarithm of (1 + input).
Note
This function is more accurate than torch.log() for small values of input
input (Tensor) – the input tensor.
out (Tensor, optional) – the output tensor.
Example:


Returns a new tensor with the logarithm to the base 2 of the elements of input.
input (Tensor) – the input tensor.
out (Tensor, optional) – the output tensor.
Example:


Logarithm of the sum of exponentiations of the inputs.
Calculates pointwise log(ex+ey)\log\left(e^x + e^y\right) . This function is useful in statistics where the calculated probabilities of events may be so small as to exceed the range of normal floating point numbers. In such cases the logarithm of the calculated probability is stored. This function allows adding probabilities stored in such a fashion.
This op should be disambiguated with torch.logsumexp() which performs a reduction on a single tensor.
out (Tensor, optional) – the output tensor.
Example:


Logarithm of the sum of exponentiations of the inputs in base-2.
Calculates pointwise log2(2x+2y)\log_2\left(2^x + 2^y\right) . See torch.logaddexp() for more details.
out (Tensor, optional) – the output tensor.


Returns the logarithm of the cumulative summation of the exponentiation of elements of input in the dimension dim.
For summation index jj  given by dim and other indices ii , the result is
out (Tensor, optional) – the output tensor.


Calculates log determinant of a square matrix or batches of square matrices.
Note
Result is -inf if input has zero log determinant, and is nan if input has negative determinant.
Note
Backward through logdet() internally uses SVD results when input is not invertible. In this case, double backward through logdet() will be unstable in when input doesn’t have distinct singular values. See svd() for details.
input (Tensor) – the input tensor of size (*, n, n) where * is zero or more batch dimensions.
Example:


Computes the element-wise logical AND of the given input tensors. Zeros are treated as False and nonzeros are treated as True.
out (Tensor, optional) – the output tensor.
Example:


Computes the element-wise logical NOT of the given input tensor. If not specified, the output tensor will have the bool dtype. If the input tensor is not a bool tensor, zeros are treated as False and non-zeros are treated as True.
input (Tensor) – the input tensor.
out (Tensor, optional) – the output tensor.
Example:


Computes the element-wise logical OR of the given input tensors. Zeros are treated as False and nonzeros are treated as True.
out (Tensor, optional) – the output tensor.
Example:


Computes the element-wise logical XOR of the given input tensors. Zeros are treated as False and nonzeros are treated as True.
out (Tensor, optional) – the output tensor.
Example:


Returns a new tensor with the logit of the elements of input. input is clamped to [eps, 1 - eps] when eps is not None. When eps is None and input < 0 or input > 1, the function will yields NaN.
out (Tensor, optional) – the output tensor.
Example:


Creates a one-dimensional tensor of size steps whose values are evenly spaced from basestart{{\text{{base}}}}^{{\text{{start}}}}  to baseend{{\text{{base}}}}^{{\text{{end}}}} , inclusive, on a logarithmic scale with base base. That is, the values are:
Warning
Not providing a value for steps is deprecated. For backwards compatibility, not providing a value for steps will create a tensor with 100 elements. Note that this behavior is not reflected in the documented function signature and should not be relied on. In a future PyTorch release, failing to provide a value for steps will throw a runtime error.
Example:


Returns the log of summed exponentials of each row of the input tensor in the given dimension dim. The computation is numerically stabilized.
For summation index jj  given by dim and other indices ii , the result is
If keepdim is True, the output tensor is of the same size as input except in the dimension(s) dim where it is of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the output tensor having 1 (or len(dim)) fewer dimension(s).
out (Tensor, optional) – the output tensor.


Computes the solution to the least squares and least norm problems for a full rank matrix AA  of size (m×n)(m \times n)  and a matrix BB  of size (m×k)(m \times k) .
If m≥nm \geq n , lstsq() solves the least-squares problem:
If m<nm < n , lstsq() solves the least-norm problem:
Returned tensor XX  has shape (max(m,n)×k)(\max(m, n) \times k) . The first nn  rows of XX  contains the solution. If m≥nm \geq n , the residual sum of squares for the solution in each column is given by the sum of squares of elements in the remaining m−nm - n  rows of that column.
Note
The case when m<nm < n  is not supported on the GPU.
out (tuple, optional) – the optional destination tensor
A namedtuple (solution, QR) containing:
(Tensor, Tensor)
Note
The returned matrices will always be transposed, irrespective of the strides of the input matrices. That is, they will have stride (1, m) instead of (m, 1).
Example:


Computes input<other\text{input} < \text{other}  element-wise.
The second argument can be a number or a tensor whose shape is broadcastable with the first argument.
out (Tensor, optional) – the output tensor.
A boolean tensor that is True where input is less than other and False elsewhere
Example:


Computes the LU factorization of a matrix or batches of matrices A. Returns a tuple containing the LU factorization and pivots of A. Pivoting is done if pivot is set to True.
Note
The pivots returned by the function are 1-indexed. If pivot is False, then the returned pivots is a tensor filled with zeros of the appropriate size.
Note
LU factorization with pivot = False is not available for CPU, and attempting to do so will throw an error. However, LU factorization with pivot = False is available for CUDA.
Note
This function does not check if the factorization was successful or not if get_infos is True since the status of the factorization is present in the third element of the return tuple.
Note
In the case of batches of square matrices with size less or equal to 32 on a CUDA device, the LU factorization is repeated for singular matrices due to the bug in the MAGMA library (see magma issue 13).
Note
L, U, and P can be derived using torch.lu_unpack().
Warning
The LU factorization does have backward support, but only for square inputs of full rank.
A tuple of tensors containing
(Tensor, IntTensor, IntTensor (optional))
Example:


Returns the LU solve of the linear system Ax=bAx = b  using the partially pivoted LU factorization of A from torch.lu().
This function supports float, double, cfloat and cdouble dtypes for input.
out (Tensor, optional) – the output tensor.
Example:


Unpacks the data and pivots from a LU factorization of a tensor.
Returns a tuple of tensors as (the pivots, the L tensor, the U tensor).
Examples:


Sets the seed for generating random numbers. Returns a torch.Generator object.
seed (int) – The desired seed. Value must be within the inclusive range [-0x8000_0000_0000_0000, 0xffff_ffff_ffff_ffff]. Otherwise, a RuntimeError is raised. Negative inputs are remapped to positive values with the formula 0xffff_ffff_ffff_ffff + seed.


Returns a new 1-D tensor which indexes the input tensor according to the boolean mask mask which is a BoolTensor.
The shapes of the mask tensor and the input tensor don’t need to match, but they must be broadcastable.
Note
The returned tensor does not use the same storage as the original tensor
out (Tensor, optional) – the output tensor.
Example:


Matrix product of two tensors.
The behavior depends on the dimensionality of the tensors as follows:
If both arguments are at least 1-dimensional and at least one argument is N-dimensional (where N > 2), then a batched matrix multiply is returned. If the first argument is 1-dimensional, a 1 is prepended to its dimension for the purpose of the batched matrix multiply and removed after. If the second argument is 1-dimensional, a 1 is appended to its dimension for the purpose of the batched matrix multiple and removed after. The non-matrix (i.e. batch) dimensions are broadcasted (and thus must be broadcastable). For example, if input is a (j×1×n×n)(j \times 1 \times n \times n)  tensor and other is a (k×n×n)(k \times n \times n)  tensor, out will be a (j×k×n×n)(j \times k \times n \times n)  tensor.
Note that the broadcasting logic only looks at the batch dimensions when determining if the inputs are broadcastable, and not the matrix dimensions. For example, if input is a (j×1×n×m)(j \times 1 \times n \times m)  tensor and other is a (k×m×p)(k \times m \times p)  tensor, these inputs are valid for broadcasting even though the final two dimensions (i.e. the matrix dimensions) are different. out will be a (j×k×n×p)(j \times k \times n \times p)  tensor.
This operator supports TensorFloat32.
Note
The 1-dimensional dot product version of this function does not support an out parameter.
out (Tensor, optional) – the output tensor.
Example:


Returns the matrix exponential. Supports batched input. For a matrix A, the matrix exponential is defined as
The implementation is based on:
Bader, P.; Blanes, S.; Casas, F. Computing the Matrix Exponential with an Optimized Taylor Polynomial Approximation. Mathematics 2019, 7, 1174.
input (Tensor) – the input tensor.
Example:


Returns the matrix raised to the power n for square matrices. For batch of matrices, each individual matrix is raised to the power n.
If n is negative, then the inverse of the matrix (if invertible) is raised to the power n. For a batch of matrices, the batched inverse (if invertible) is raised to the power n. If n is 0, then an identity matrix is returned.
Example:


Returns the numerical rank of a 2-D tensor. The method to compute the matrix rank is done using SVD by default. If symmetric is True, then input is assumed to be symmetric, and the computation of the rank is done by obtaining the eigenvalues.
tol is the threshold below which the singular values (or the eigenvalues when symmetric is True) are considered to be 0. If tol is not specified, tol is set to S.max() * max(S.size()) * eps where S is the singular values (or the eigenvalues when symmetric is True), and eps is the epsilon value for the datatype of input.
Note
torch.matrix_rank() is deprecated. Please use torch.linalg.matrix_rank() instead. The parameter symmetric was renamed in torch.linalg.matrix_rank() to hermitian.
out (Tensor, optional) – the output tensor.
Example:


Returns the maximum value of all elements in the input tensor.
Warning
This function produces deterministic (sub)gradients unlike max(dim=0)
input (Tensor) – the input tensor.
Example:
Returns a namedtuple (values, indices) where values is the maximum value of each row of the input tensor in the given dimension dim. And indices is the index location of each maximum value found (argmax).
If keepdim is True, the output tensors are of the same size as input except in the dimension dim where they are of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the output tensors having 1 fewer dimension than input.
Note
If there are multiple maximal values in a reduced row then the indices of the first maximal value are returned.
out (tuple, optional) – the result tuple of two output tensors (max, max_indices)
Example:
See torch.maximum().


Computes the element-wise maximum of input and other.
Note
If one of the elements being compared is a NaN, then that element is returned. maximum() is not supported for tensors with complex dtypes.
out (Tensor, optional) – the output tensor.
Example:


Returns the mean value of all elements in the input tensor.
input (Tensor) – the input tensor.
Example:
Returns the mean value of each row of the input tensor in the given dimension dim. If dim is a list of dimensions, reduce over all of them.
If keepdim is True, the output tensor is of the same size as input except in the dimension(s) dim where it is of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the output tensor having 1 (or len(dim)) fewer dimension(s).
out (Tensor, optional) – the output tensor.
Example:


Returns the median of the values in input.
Note
The median is not unique for input tensors with an even number of elements. In this case the lower of the two medians is returned. To compute the mean of both medians, use torch.quantile() with q=0.5 instead.
Warning
This function produces deterministic (sub)gradients unlike median(dim=0)
input (Tensor) – the input tensor.
Example:
Returns a namedtuple (values, indices) where values contains the median of each row of input in the dimension dim, and indices contains the index of the median values found in the dimension dim.
By default, dim is the last dimension of the input tensor.
If keepdim is True, the output tensors are of the same size as input except in the dimension dim where they are of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the outputs tensor having 1 fewer dimension than input.
Note
The median is not unique for input tensors with an even number of elements in the dimension dim. In this case the lower of the two medians is returned. To compute the mean of both medians in input, use torch.quantile() with q=0.5 instead.
Warning
indices does not necessarily contain the first occurrence of each median value found, unless it is unique. The exact implementation details are device-specific. Do not expect the same result when run on CPU and GPU in general. For the same reason do not expect the gradients to be deterministic.
out ((Tensor, Tensor), optional) – The first tensor will be populated with the median values and the second tensor, which must have dtype long, with their indices in the dimension dim of input.
Example:


Take NN  tensors, each of which can be either scalar or 1-dimensional vector, and create NN  N-dimensional grids, where the ii  th grid is defined by expanding the ii  th input over dimensions defined by other inputs.
tensors (list of Tensor) – list of scalars or 1 dimensional tensors. Scalars will be treated as tensors of size (1,)(1,)  automatically
If the input has kk  tensors of size (N1,),(N2,),…,(Nk,)(N_1,), (N_2,), \ldots , (N_k,) , then the output would also have kk  tensors, where all tensors are of size (N1,N2,…,Nk)(N_1, N_2, \ldots , N_k) .
seq (sequence of Tensors)
Example:


Returns the minimum value of all elements in the input tensor.
Warning
This function produces deterministic (sub)gradients unlike min(dim=0)
input (Tensor) – the input tensor.
Example:
Returns a namedtuple (values, indices) where values is the minimum value of each row of the input tensor in the given dimension dim. And indices is the index location of each minimum value found (argmin).
If keepdim is True, the output tensors are of the same size as input except in the dimension dim where they are of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the output tensors having 1 fewer dimension than input.
Note
If there are multiple minimal values in a reduced row then the indices of the first minimal value are returned.
out (tuple, optional) – the tuple of two output tensors (min, min_indices)
Example:
See torch.minimum().


Computes the element-wise minimum of input and other.
Note
If one of the elements being compared is a NaN, then that element is returned. minimum() is not supported for tensors with complex dtypes.
out (Tensor, optional) – the output tensor.
Example:


Performs a matrix multiplication of the matrices input and mat2.
If input is a (n×m)(n \times m)  tensor, mat2 is a (m×p)(m \times p)  tensor, out will be a (n×p)(n \times p)  tensor.
Note
This function does not broadcast. For broadcasting matrix products, see torch.matmul().
Supports strided and sparse 2-D tensors as inputs, autograd with respect to strided inputs.
This operator supports TensorFloat32.
out (Tensor, optional) – the output tensor.
Example:


Returns a namedtuple (values, indices) where values is the mode value of each row of the input tensor in the given dimension dim, i.e. a value which appears most often in that row, and indices is the index location of each mode value found.
By default, dim is the last dimension of the input tensor.
If keepdim is True, the output tensors are of the same size as input except in the dimension dim where they are of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the output tensors having 1 fewer dimension than input.
Note
This function is not defined for torch.cuda.Tensor yet.
out (tuple, optional) – the result tuple of two output tensors (values, indices)
Example:


Alias for torch.movedim().
This function is equivalent to NumPy’s moveaxis function.
Examples:


Moves the dimension(s) of input at the position(s) in source to the position(s) in destination.
Other dimensions of input that are not explicitly moved remain in their original order and appear at the positions not specified in destination.
Examples:


Sorts the elements of the input tensor along its first dimension in ascending order by value.
Note
torch.msort(t) is equivalent to torch.sort(t, dim=0)[0]. See also torch.sort().
input (Tensor) – the input tensor.
out (Tensor, optional) – the output tensor.
Example:


Multiplies each element of the input input with the scalar other and returns a new resulting tensor.
If input is of type FloatTensor or DoubleTensor, other should be a real number, otherwise it should be an integer
{out} –
Example:
Each element of the tensor input is multiplied by the corresponding element of the Tensor other. The resulting tensor is returned.
The shapes of input and other must be broadcastable.
out (Tensor, optional) – the output tensor.
Example:


Returns a tensor where each row contains num_samples indices sampled from the multinomial probability distribution located in the corresponding row of tensor input.
Note
The rows of input do not need to sum to one (in which case we use the values as weights), but must be non-negative, finite and have a non-zero sum.
Indices are ordered from left to right according to when each was sampled (first samples are placed in first column).
If input is a vector, out is a vector of size num_samples.
If input is a matrix with m rows, out is an matrix of shape (m×num_samples)(m \times \text{num\_samples}) .
If replacement is True, samples are drawn with replacement.
If not, they are drawn without replacement, which means that when a sample index is drawn for a row, it cannot be drawn again for that row.
Note
When drawn without replacement, num_samples must be lower than number of non-zero elements in input (or the min number of non-zero elements in each row of input if it is a matrix).
Example:


torch.multiprocessing is a wrapper around the native multiprocessing module. It registers custom reducers, that use shared memory to provide shared views on the same data in different processes. Once the tensor/storage is moved to shared_memory (see share_memory_()), it will be possible to send it to other processes without making any copies.
The API is 100% compatible with the original module - it’s enough to change import multiprocessing to import torch.multiprocessing to have all the tensors sent through the queues or shared via other mechanisms, moved to shared memory.
Because of the similarity of APIs we do not document most of this package contents, and we recommend referring to very good docs of the original module.
Warning
If the main process exits abruptly (e.g. because of an incoming signal), Python’s multiprocessing sometimes fails to clean up its children. It’s a known caveat, so if you’re seeing any resource leaks after interrupting the interpreter, it probably means that this has just happened to you.
Returns a set of sharing strategies supported on a current system.
Returns the current strategy for sharing CPU tensors.
Sets the strategy for sharing CPU tensors.
new_strategy (str) – Name of the selected strategy. Should be one of the values returned by get_all_sharing_strategies().
Sharing CUDA tensors between processes is supported only in Python 3, using a spawn or forkserver start methods.
Unlike CPU tensors, the sending process is required to keep the original tensor as long as the receiving process retains a copy of the tensor. The refcounting is implemented under the hood but requires users to follow the next best practices.
Warning
If the consumer process dies abnormally to a fatal signal, the shared tensor could be forever kept in memory as long as the sending process is running.
2. Keep producer process running until all consumers exits. This will prevent the situation when the producer process releasing memory which is still in use by the consumer.
This section provides a brief overview into how different sharing strategies work. Note that it applies only to CPU tensor - CUDA tensors will always use the CUDA API, as that’s the only way they can be shared.
Note
This is the default strategy (except for macOS and OS X where it’s not supported).
This strategy will use file descriptors as shared memory handles. Whenever a storage is moved to shared memory, a file descriptor obtained from shm_open is cached with the object, and when it’s going to be sent to other processes, the file descriptor will be transferred (e.g. via UNIX sockets) to it. The receiver will also cache the file descriptor and mmap it, to obtain a shared view onto the storage data.
Note that if there will be a lot of tensors shared, this strategy will keep a large number of file descriptors open most of the time. If your system has low limits for the number of open file descriptors, and you can’t raise them, you should use the file_system strategy.
This strategy will use file names given to shm_open to identify the shared memory regions. This has a benefit of not requiring the implementation to cache the file descriptors obtained from it, but at the same time is prone to shared memory leaks. The file can’t be deleted right after its creation, because other processes need to access it to open their views. If the processes fatally crash, or are killed, and don’t call the storage destructors, the files will remain in the system. This is very serious, because they keep using up the memory until the system is restarted, or they’re freed manually.
To counter the problem of shared memory file leaks, torch.multiprocessing will spawn a daemon named torch_shm_manager that will isolate itself from the current process group, and will keep track of all shared memory allocations. Once all processes connected to it exit, it will wait a moment to ensure there will be no new connections, and will iterate over all shared memory files allocated by the group. If it finds that any of them still exist, they will be deallocated. We’ve tested this method and it proved to be robust to various failures. Still, if your system has high enough limits, and file_descriptor is a supported strategy, we do not recommend switching to this one.
Note
Available for Python >= 3.4.
This depends on the spawn start method in Python’s multiprocessing package.
Spawning a number of subprocesses to perform some function can be done by creating Process instances and calling join to wait for their completion. This approach works fine when dealing with a single subprocess but presents potential issues when dealing with multiple processes.
Namely, joining processes sequentially implies they will terminate sequentially. If they don’t, and the first process does not terminate, the process termination will go unnoticed. Also, there are no native facilities for error propagation.
The spawn function below addresses these concerns and takes care of error propagation, out of order termination, and will actively terminate processes upon detecting an error in one of them.
Spawns nprocs processes that run fn with args.
If one of the processes exits with a non-zero exit status, the remaining processes are killed and an exception is raised with the cause of termination. In the case an exception was caught in the child process, it is forwarded and its traceback is included in the exception raised in the parent process.
fn (function) –
Function is called as the entrypoint of the spawned process. This function must be defined at the top level of a module so it can be pickled and spawned. This is a requirement imposed by multiprocessing.
The function is called as fn(i, *args), where i is the process index and args is the passed through tuple of arguments.
None if join is True, ProcessContext if join is False
Returned by spawn() when called with join=False.
Tries to join one or more processes in this spawn context. If one of them exited with a non-zero exit status, this function kills the remaining processes and raises an exception with the cause of the first process exiting.
Returns True if all processes have been joined successfully, False if there are more processes that need to be joined.
timeout (float) – Wait this long before giving up on waiting.


Returns a set of sharing strategies supported on a current system.


Returns the current strategy for sharing CPU tensors.


Sets the strategy for sharing CPU tensors.
new_strategy (str) – Name of the selected strategy. Should be one of the values returned by get_all_sharing_strategies().


Spawns nprocs processes that run fn with args.
If one of the processes exits with a non-zero exit status, the remaining processes are killed and an exception is raised with the cause of termination. In the case an exception was caught in the child process, it is forwarded and its traceback is included in the exception raised in the parent process.
fn (function) –
Function is called as the entrypoint of the spawned process. This function must be defined at the top level of a module so it can be pickled and spawned. This is a requirement imposed by multiprocessing.
The function is called as fn(i, *args), where i is the process index and args is the passed through tuple of arguments.
None if join is True, ProcessContext if join is False


Returned by spawn() when called with join=False.
Tries to join one or more processes in this spawn context. If one of them exited with a non-zero exit status, this function kills the remaining processes and raises an exception with the cause of the first process exiting.
Returns True if all processes have been joined successfully, False if there are more processes that need to be joined.
timeout (float) – Wait this long before giving up on waiting.


Tries to join one or more processes in this spawn context. If one of them exited with a non-zero exit status, this function kills the remaining processes and raises an exception with the cause of the first process exiting.
Returns True if all processes have been joined successfully, False if there are more processes that need to be joined.
timeout (float) – Wait this long before giving up on waiting.


Performs a matrix-vector product of the matrix input and the vector vec.
If input is a (n×m)(n \times m)  tensor, vec is a 1-D tensor of size mm , out will be 1-D of size nn .
Note
This function does not broadcast.
out (Tensor, optional) – the output tensor.
Example:


Computes the multivariate log-gamma function) with dimension pp  element-wise, given by
where C=log(π)×p(p−1)4C = \log(\pi) \times \frac{p (p - 1)}{4}  and Γ(⋅)\Gamma(\cdot)  is the Gamma function.
All elements must be greater than p−12\frac{p - 1}{2} , otherwise an error would be thrown.
Example:


Returns the median of the values in input, ignoring NaN values.
This function is identical to torch.median() when there are no NaN values in input. When input has one or more NaN values, torch.median() will always return NaN, while this function will return the median of the non-NaN elements in input. If all the elements in input are NaN it will also return NaN.
input (Tensor) – the input tensor.
Example:
Returns a namedtuple (values, indices) where values contains the median of each row of input in the dimension dim, ignoring NaN values, and indices contains the index of the median values found in the dimension dim.
This function is identical to torch.median() when there are no NaN values in a reduced row. When a reduced row has one or more NaN values, torch.median() will always reduce it to NaN, while this function will reduce it to the median of the non-NaN elements. If all the elements in a reduced row are NaN then it will be reduced to NaN, too.
out ((Tensor, Tensor), optional) – The first tensor will be populated with the median values and the second tensor, which must have dtype long, with their indices in the dimension dim of input.
Example:


This is a variant of torch.quantile() that “ignores” NaN values, computing the quantiles q as if NaN values in input did not exist. If all values in a reduced row are NaN then the quantiles for that reduction will be NaN. See the documentation for torch.quantile().
out (Tensor, optional) – the output tensor.
Example:


Returns the sum of all elements, treating Not a Numbers (NaNs) as zero.
input (Tensor) – the input tensor.
dtype (torch.dtype, optional) – the desired data type of returned tensor. If specified, the input tensor is casted to dtype before the operation is performed. This is useful for preventing data type overflows. Default: None.
Example:
Returns the sum of each row of the input tensor in the given dimension dim, treating Not a Numbers (NaNs) as zero. If dim is a list of dimensions, reduce over all of them.
If keepdim is True, the output tensor is of the same size as input except in the dimension(s) dim where it is of size 1. Otherwise, dim is squeezed (see torch.squeeze()), resulting in the output tensor having 1 (or len(dim)) fewer dimension(s).
dtype (torch.dtype, optional) – the desired data type of returned tensor. If specified, the input tensor is casted to dtype before the operation is performed. This is useful for preventing data type overflows. Default: None.
Example:


Replaces NaN, positive infinity, and negative infinity values in input with the values specified by nan, posinf, and neginf, respectively. By default, NaN`s are replaced with zero, positive infinity is replaced with the
greatest finite value representable by :attr:`input’s dtype, and negative infinity is replaced with the least finite value representable by input’s dtype.
out (Tensor, optional) – the output tensor.
Example: