Package 'torch'

Description

Converts to array

Usage

as_array(x)

Arguments

Description

The graph is differentiated using the chain rule. If any of tensors are non-scalar (i.e. their data has more than one element) and require gradient, then the Jacobian-vector product would be computed, in this case the function additionally requires specifying grad_tensors. It should be a sequence of matching length, that contains the “vector” in the Jacobian-vector product, usually the gradient of the differentiated function w.r.t. corresponding tensors (None is an acceptable value for all tensors that don’t need gradient tensors).

Usage

autograd_backward(
  tensors,
  grad_tensors = NULL,
  retain_graph = create_graph,
  create_graph = FALSE
)

Arguments

Details

This function accumulates gradients in the leaves - you might need to zero them before calling it.

Examples

if (torch_is_installed()) {
x <- torch_tensor(1, requires_grad = TRUE)
y <- 2 * x

a <- torch_tensor(1, requires_grad = TRUE)
b <- 3 * a

autograd_backward(list(y, b))
}

Description

Every operation performed on Tensor's creates a new function object, that performs the computation, and records that it happened. The history is retained in the form of a DAG of functions, with edges denoting data dependencies (input <- output). Then, when backward is called, the graph is processed in the topological ordering, by calling backward() methods of each Function object, and passing returned gradients on to next Function's.

Usage

autograd_function(forward, backward)

Arguments

Examples

if (torch_is_installed()) {

exp2 <- autograd_function(
  forward = function(ctx, i) {
    result <- i$exp()
    ctx$save_for_backward(result = result)
    result
  },
  backward = function(ctx, grad_output) {
    list(i = grad_output * ctx$saved_variable$result)
  }
)
}

Description

grad_outputs should be a list of length matching output containing the “vector” in Jacobian-vector product, usually the pre-computed gradients w.r.t. each of the outputs. If an output doesn’t require_grad, then the gradient can be None).

Usage

autograd_grad(
  outputs,
  inputs,
  grad_outputs = NULL,
  retain_graph = create_graph,
  create_graph = FALSE,
  allow_unused = FALSE
)

Arguments

Details

If only_inputs is TRUE, the function will only return a list of gradients w.r.t the specified inputs. If it’s FALSE, then gradient w.r.t. all remaining leaves will still be computed, and will be accumulated into their .grad attribute.

Examples

if (torch_is_installed()) {
w <- torch_tensor(0.5, requires_grad = TRUE)
b <- torch_tensor(0.9, requires_grad = TRUE)
x <- torch_tensor(runif(100))
y <- 2 * x + 1
loss <- (y - (w * x + b))^2
loss <- loss$mean()

o <- autograd_grad(loss, list(w, b))
o
}

Description

Sets or disables gradient history.

Usage

autograd_set_grad_mode(enabled)

Arguments

Description

Class representing the context.

Class representing the context.

Public fields

Active bindings

Methods

Public methods

• AutogradContext$new()

• AutogradContext$save_for_backward()

• AutogradContext$mark_non_differentiable()

• AutogradContext$mark_dirty()

• AutogradContext$clone()

Method new()

(Dev related) Initializes the context. Not user related.

Usage

AutogradContext$new(
  ptr,
  env,
  argument_names = NULL,
  argument_needs_grad = NULL
)

Arguments

Method save_for_backward()

Saves given objects for a future call to backward().

This should be called at most once, and only from inside the forward() method.

Later, saved objects can be accessed through the saved_variables attribute. Before returning them to the user, a check is made to ensure they weren’t used in any in-place operation that modified their content.

Arguments can also be any kind of R object.

Usage

AutogradContext$save_for_backward(...)

Arguments

Method mark_non_differentiable()

Marks outputs as non-differentiable.

This should be called at most once, only from inside the forward() method, and all arguments should be outputs.

This will mark outputs as not requiring gradients, increasing the efficiency of backward computation. You still need to accept a gradient for each output in backward(), but it’s always going to be a zero tensor with the same shape as the shape of a corresponding output.

This is used e.g. for indices returned from a max Function.

Usage

AutogradContext$mark_non_differentiable(...)

Arguments

Method mark_dirty()

Marks given tensors as modified in an in-place operation.

This should be called at most once, only from inside the forward() method, and all arguments should be inputs.

Every tensor that’s been modified in-place in a call to forward() should be given to this function, to ensure correctness of our checks. It doesn’t matter whether the function is called before or after modification.

Usage

AutogradContext$mark_dirty(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

AutogradContext$clone(deep = FALSE)

Arguments

Description

CuDNN is available

Usage

backends_cudnn_is_available()

Description

CuDNN version

Usage

backends_cudnn_version()

Description

MKL is available

Usage

backends_mkl_is_available()

Value

Returns whether LibTorch is built with MKL support.

Description

MKLDNN is available

Usage

backends_mkldnn_is_available()

Value

Returns whether LibTorch is built with MKL-DNN support.

Description

MPS is available

Usage

backends_mps_is_available()

Value

Returns whether LibTorch is built with MPS support.

Description

OpenMP is available

Usage

backends_openmp_is_available()

Value

Returns whether LibTorch is built with OpenMP support.

Description

Raises value_error: if any of the values is not a numeric instance, a torch.*Tensor instance, or an instance implementing torch_function TODO: add has_torch_function((v,)) See: https://github.com/pytorch/pytorch/blob/master/torch/distributions/utils.py

Usage

broadcast_all(values)

Arguments

Description

Clones a module.

Usage

clone_module(module, deep = FALSE, ..., replace_values = TRUE)

Arguments

Examples

if (torch_is_installed()) {
clone_module(nn_linear(1, 1), deep = TRUE)
# is the same as
nn_linear(1, 1)$clone(deep = TRUE)
}

Description

Abstract base class for constraints.

Abstract base class for constraints.

Details

A constraint object represents a region over which a variable is valid, e.g. within which a variable can be optimized.

Methods

Public methods

• Constraint$check()

• Constraint$print()

• Constraint$clone()

Method check()

Returns a byte tensor of sample_shape + batch_shape indicating whether each event in value satisfies this constraint.

Usage

Constraint$check(value)

Arguments

Method print()

Define the print method for constraints,

Usage

Constraint$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

Constraint$clone(deep = FALSE)

Arguments

Description

Based on the implementation from Rotated_IoU

Usage

contrib_sort_vertices(vertices, mask, num_valid)

Arguments

Details

All tensors should be on a CUDA device so this function can be used.

Note

This function does not make part of the official torch API.

Examples

if (torch_is_installed()) {
if (cuda_is_available()) {
  v <- torch_randn(8, 1024, 24, 2)$cuda()
  mean <- torch_mean(v, dim = 2, keepdim = TRUE)
  v <- v - mean
  m <- (torch_rand(8, 1024, 24) > 0.8)$cuda()
  nv <- torch_sum(m$to(dtype = torch_int()), dim = -1)$to(dtype = torch_int())$cuda()
  result <- contrib_sort_vertices(v, m, nv)
}
}

Description

A gradient scaler instance is used to perform dynamic gradient scaling to avoid gradient underflow when training with mixed precision.

Usage

cuda_amp_grad_scaler(
  init_scale = 2^16,
  growth_factor = 2,
  backoff_factor = 0.5,
  growth_interval = 2000,
  enabled = TRUE
)

Arguments

Value

A gradient scaler object.

Description

Returns the index of a currently selected device.

Usage

cuda_current_device()

Description

Returns the number of GPUs available.

Usage

cuda_device_count()

Description

Releases all unoccupied cached memory currently held by the caching allocator so that those can be used in other GPU application and visible in nvidia-smi.

Usage

cuda_empty_cache()

Note

cuda_empty_cache() doesn’t increase the amount of GPU memory available for torch. However, it may help reduce fragmentation of GPU memory in certain cases. See Memory management article for more details about GPU memory management.

Description

Returns the major and minor CUDA capability of device

Usage

cuda_get_device_capability(device = cuda_current_device())

Arguments

Description

Returns a bool indicating if CUDA is currently available.

Usage

cuda_is_available()

Description

The return value of this function is a dictionary of statistics, each of which is a non-negative integer.

Usage

cuda_memory_stats(device = cuda_current_device())

cuda_memory_summary(device = cuda_current_device())

Arguments

Core statistics

• "allocated.{all,large_pool,small_pool}.{current,peak,allocated,freed}": number of allocation requests received by the memory allocator.

• "allocated_bytes.{all,large_pool,small_pool}.{current,peak,allocated,freed}": amount of allocated memory.

• "segment.{all,large_pool,small_pool}.{current,peak,allocated,freed}": number of reserved segments from cudaMalloc().

• "reserved_bytes.{all,large_pool,small_pool}.{current,peak,allocated,freed}": amount of reserved memory.

• "active.{all,large_pool,small_pool}.{current,peak,allocated,freed}": number of active memory blocks.

• "active_bytes.{all,large_pool,small_pool}.{current,peak,allocated,freed}": amount of active memory.

• "inactive_split.{all,large_pool,small_pool}.{current,peak,allocated,freed}": number of inactive, non-releasable memory blocks.

• "inactive_split_bytes.{all,large_pool,small_pool}.{current,peak,allocated,freed}": amount of inactive, non-releasable memory.

For these core statistics, values are broken down as follows.

Pool type:

• all: combined statistics across all memory pools.

• large_pool: statistics for the large allocation pool (as of October 2019, for size >= 1MB allocations).

• small_pool: statistics for the small allocation pool (as of October 2019, for size < 1MB allocations).

Metric type:

• current: current value of this metric.

• peak: maximum value of this metric.

• allocated: historical total increase in this metric.

• freed: historical total decrease in this metric.

Additional metrics

• "num_alloc_retries": number of failed cudaMalloc calls that result in a cache flush and retry.

• "num_ooms": number of out-of-memory errors thrown.

Description

Returns the CUDA runtime version

Usage

cuda_runtime_version()

Description

Waits for all kernels in all streams on a CUDA device to complete.

Usage

cuda_synchronize(device = NULL)

Arguments

Description

Data loader. Combines a dataset and a sampler, and provides single- or multi-process iterators over the dataset.

Usage

dataloader(
  dataset,
  batch_size = 1,
  shuffle = FALSE,
  sampler = NULL,
  batch_sampler = NULL,
  num_workers = 0,
  collate_fn = NULL,
  pin_memory = FALSE,
  drop_last = FALSE,
  timeout = -1,
  worker_init_fn = NULL,
  worker_globals = NULL,
  worker_packages = NULL
)

Arguments

Parallel data loading

When using num_workers > 0 data loading will happen in parallel for each worker. Note that batches are taken in parallel and not observations.

The worker initialization process happens in the following order:

• num_workers R sessions are initialized.

Then in each worker we perform the following actions:

• the torch library is loaded.

• a random seed is set both using set.seed() and using torch_manual_seed.

• packages passed to the worker_packages argument are loaded.

• objects passed trough the worker_globals parameters are copied into the global environment.

• the worker_init function is ran with an id argument.

• the dataset fetcher is copied to the worker.

See Also

dataset(), sampler()

Description

Creates an iterator from a DataLoader

Usage

dataloader_make_iter(dataloader)

Arguments

Description

Get the next element of a dataloader iterator

Usage

dataloader_next(iter, completed = NULL)

Arguments

Description

All datasets that represent a map from keys to data samples should subclass this class. All subclasses should overwrite the .getitem() method, which supports fetching a data sample for a given key. Subclasses could also optionally overwrite .length(), which is expected to return the size of the dataset (e.g. number of samples) used by many sampler implementations and the default options of dataloader().

Usage

dataset(
  name = NULL,
  inherit = Dataset,
  ...,
  private = NULL,
  active = NULL,
  parent_env = parent.frame()
)

Arguments

Value

The output is a function f with class dataset_generator. Calling f() creates a new instance of the R6 class dataset. The R6 class is stored in the enclosing environment of f and can also be accessed through fs attribute Dataset.

Get a batch of observations

By default datasets are iterated by returning each observation/item individually. Often it's possible to have an optimized implementation to take a batch of observations (eg, subsetting a tensor by multiple indexes at once is faster than subsetting once for each index), in this case you can implement a .getbatch method that will be used instead of .getitem when getting a batch of observations within the dataloader. .getbatch must work for batches of size larger or equal to 1 and care must be taken so it doesn't drop the batch dimension when it's queried with a length 1 batch index - for instance by using drop=FALSE. .getitem() is expected to not include the batch dimension as it's added by the datalaoder. For more on this see the the vignette("loading-data").

Note

dataloader() by default constructs a index sampler that yields integral indices. To make it work with a map-style dataset with non-integral indices/keys, a custom sampler must be provided.

Description

Subset of a dataset at specified indices.

Usage

dataset_subset(dataset, indices)

Arguments

Description

Creates a Bernoulli distribution parameterized by probs or logits (but not both). Samples are binary (0 or 1). They take the value 1 with probability p and 0 with probability 1 - p.

Usage

distr_bernoulli(probs = NULL, logits = NULL, validate_args = NULL)

Arguments

See Also

Distribution for details on the available methods.

Other distributions: distr_chi2(), distr_gamma(), distr_multivariate_normal(), distr_normal(), distr_poisson()

Examples

if (torch_is_installed()) {
m <- distr_bernoulli(0.3)
m$sample() # 30% chance 1; 70% chance 0
}

Description

Creates a categorical distribution parameterized by either probs or logits (but not both).

Usage

distr_categorical(probs = NULL, logits = NULL, validate_args = NULL)

Arguments

Note

It is equivalent to the distribution that torch_multinomial() samples from.

Samples are integers from $\{0, \ldots, K-1\}$ where K is probs$size(-1).

If probs is 1-dimensional with length-K, each element is the relative probability of sampling the class at that index.

If probs is N-dimensional, the first N-1 dimensions are treated as a batch of relative probability vectors.

The probs argument must be non-negative, finite and have a non-zero sum, and it will be normalized to sum to 1 along the last dimension. attr:probs will return this normalized value. The logits argument will be interpreted as unnormalized log probabilities and can therefore be any real number. It will likewise be normalized so that the resulting probabilities sum to 1 along the last dimension. attr:logits will return this normalized value.

See also: torch_multinomial()

Examples

if (torch_is_installed()) {
m <- distr_categorical(torch_tensor(c(0.25, 0.25, 0.25, 0.25)))
m$sample() # equal probability of 1,2,3,4
}

Description

Creates a Chi2 distribution parameterized by shape parameter df. This is exactly equivalent to distr_gamma(alpha=0.5*df, beta=0.5)

Usage

distr_chi2(df, validate_args = NULL)

Arguments

See Also

Distribution for details on the available methods.

Other distributions: distr_bernoulli(), distr_gamma(), distr_multivariate_normal(), distr_normal(), distr_poisson()

Examples

if (torch_is_installed()) {
m <- distr_chi2(torch_tensor(1.0))
m$sample() # Chi2 distributed with shape df=1
torch_tensor(0.1046)
}

Description

Creates a Gamma distribution parameterized by shape concentration and rate.

Usage

distr_gamma(concentration, rate, validate_args = NULL)

Arguments

See Also

Distribution for details on the available methods.

Other distributions: distr_bernoulli(), distr_chi2(), distr_multivariate_normal(), distr_normal(), distr_poisson()

Examples

if (torch_is_installed()) {
m <- distr_gamma(torch_tensor(1.0), torch_tensor(1.0))
m$sample() # Gamma distributed with concentration=1 and rate=1
}

Description

The MixtureSameFamily distribution implements a (batch of) mixture distribution where all component are from different parameterizations of the same distribution type. It is parameterized by a Categorical selecting distribution" (over k component) and a component distribution, i.e., a Distribution with a rightmost batch shape (equal to ⁠[k]⁠) which indexes each (batch of) component.

Usage

distr_mixture_same_family(
  mixture_distribution,
  component_distribution,
  validate_args = NULL
)

Arguments

Examples

if (torch_is_installed()) {
# Construct Gaussian Mixture Model in 1D consisting of 5 equally
# weighted normal distributions
mix <- distr_categorical(torch_ones(5))
comp <- distr_normal(torch_randn(5), torch_rand(5))
gmm <- distr_mixture_same_family(mix, comp)
}

Description

Creates a multivariate normal (also called Gaussian) distribution parameterized by a mean vector and a covariance matrix.

Usage

distr_multivariate_normal(
  loc,
  covariance_matrix = NULL,
  precision_matrix = NULL,
  scale_tril = NULL,
  validate_args = NULL
)

Arguments

Details

The multivariate normal distribution can be parameterized either in terms of a positive definite covariance matrix $\mathbf{\Sigma}$ or a positive definite precision matrix $\mathbf{\Sigma}^{-1}$ or a lower-triangular matrix $\mathbf{L}$ with positive-valued diagonal entries, such that $\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top$. This triangular matrix can be obtained via e.g. Cholesky decomposition of the covariance.

Note

Only one of covariance_matrix or precision_matrix or scale_tril can be specified. Using scale_tril will be more efficient: all computations internally are based on scale_tril. If covariance_matrix or precision_matrix is passed instead, it is only used to compute the corresponding lower triangular matrices using a Cholesky decomposition.

See Also

Distribution for details on the available methods.

Other distributions: distr_bernoulli(), distr_chi2(), distr_gamma(), distr_normal(), distr_poisson()

Examples

if (torch_is_installed()) {
m <- distr_multivariate_normal(torch_zeros(2), torch_eye(2))
m$sample() # normally distributed with mean=`[0,0]` and covariance_matrix=`I`
}

Description

Creates a normal (also called Gaussian) distribution parameterized by loc and scale.

Usage

distr_normal(loc, scale, validate_args = NULL)

Arguments

Value

Object of torch_Normal class

See Also

Distribution for details on the available methods.

Other distributions: distr_bernoulli(), distr_chi2(), distr_gamma(), distr_multivariate_normal(), distr_poisson()

Examples

if (torch_is_installed()) {
m <- distr_normal(loc = 0, scale = 1)
m$sample() # normally distributed with loc=0 and scale=1
}

Description

Samples are nonnegative integers, with a pmf given by

$\mbox{rate}^{k} \frac{e^{-\mbox{rate}}}{k!}$

Usage

distr_poisson(rate, validate_args = NULL)

Arguments

See Also

Distribution for details on the available methods.

Other distributions: distr_bernoulli(), distr_chi2(), distr_gamma(), distr_multivariate_normal(), distr_normal()

Examples

if (torch_is_installed()) {
m <- distr_poisson(torch_tensor(4))
m$sample()
}

Description

Distribution is the abstract base class for probability distributions. Note: in Python, adding torch.Size objects works as concatenation Try for example: torch.Size((2, 1)) + torch.Size((1,))

Public fields

Active bindings

Methods

Public methods

• Distribution$new()

• Distribution$expand()

• Distribution$sample()

• Distribution$rsample()

• Distribution$log_prob()

• Distribution$cdf()

• Distribution$icdf()

• Distribution$enumerate_support()

• Distribution$entropy()

• Distribution$perplexity()

• Distribution$.extended_shape()

• Distribution$.validate_sample()

• Distribution$print()

• Distribution$clone()

Method new()

Initializes a distribution class.

Usage

Distribution$new(batch_shape = NULL, event_shape = NULL, validate_args = NULL)

Arguments

Method expand()

Returns a new distribution instance (or populates an existing instance provided by a derived class) with batch dimensions expanded to batch_shape. This method calls expand on the distribution’s parameters. As such, this does not allocate new memory for the expanded distribution instance. Additionally, this does not repeat any args checking or parameter broadcasting in initialize, when an instance is first created.

Usage

Distribution$expand(batch_shape, .instance = NULL)

Arguments

Method sample()

Generates a sample_shape shaped sample or sample_shape shaped batch of samples if the distribution parameters are batched.

Usage

Distribution$sample(sample_shape = NULL)

Arguments

Method rsample()

Generates a sample_shape shaped reparameterized sample or sample_shape shaped batch of reparameterized samples if the distribution parameters are batched.

Usage

Distribution$rsample(sample_shape = NULL)

Arguments

Method log_prob()

Returns the log of the probability density/mass function evaluated at value.

Usage

Distribution$log_prob(value)

Arguments

Method cdf()

Returns the cumulative density/mass function evaluated at value.

Usage

Distribution$cdf(value)

Arguments

Method icdf()

Returns the inverse cumulative density/mass function evaluated at value.

@description Returns tensor containing all values supported by a discrete distribution. The result will enumerate over dimension 0, so the shape of the result will be ⁠(cardinality,) + batch_shape + event_shape (where ⁠event_shape = ()⁠for univariate distributions). Note that this enumerates over all batched tensors in lock-step⁠list(c(0, 0), c(1, 1), ...)⁠. With ⁠expand=FALSE⁠, enumeration happens along dim 0, but with the remaining batch dimensions being singleton dimensions, ⁠list(c(0), c(1), ...)'.

Usage

Distribution$icdf(value)

Arguments

Method enumerate_support()

Usage

Distribution$enumerate_support(expand = TRUE)

Arguments

Returns

Tensor iterating over dimension 0.

Method entropy()

Returns entropy of distribution, batched over batch_shape.

Usage

Distribution$entropy()

Returns

Tensor of shape batch_shape.

Method perplexity()

Returns perplexity of distribution, batched over batch_shape.

Usage

Distribution$perplexity()

Returns

Tensor of shape batch_shape.

Method .extended_shape()

Returns the size of the sample returned by the distribution, given a sample_shape. Note, that the batch and event shapes of a distribution instance are fixed at the time of construction. If this is empty, the returned shape is upcast to (1,).

Usage

Distribution$.extended_shape(sample_shape = NULL)

Arguments

Method .validate_sample()

Argument validation for distribution methods such as log_prob, cdf and icdf. The rightmost dimensions of a value to be scored via these methods must agree with the distribution's batch and event shapes.

Usage

Distribution$.validate_sample(value)

Arguments

Method print()

Prints the distribution instance.

Usage

Distribution$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

Distribution$clone(deep = FALSE)

Arguments

Description

Enumerate an iterator

Usage

enumerate(x, ...)

Arguments

Description

Enumerate an iterator

Usage

## S3 method for class 'dataloader'
enumerate(x, max_len = 1e+06, ...)

Arguments

Description

List the Torch and Lantern libraries URLs to download as local files in order to proceed with install_torch_from_file().

Installs Torch and its dependencies from files.

Usage

get_install_libs_url(version = NA, type = NA)

install_torch_from_file(version = NA, type = NA, libtorch, liblantern, ...)

Arguments

Details

When "install_torch()" initiated download is not possible, but installation archive files are present on local filesystem, "install_torch_from_file()" can be used as a workaround to installation issue. "libtorch" is the archive containing all torch modules, and "liblantern" is the C interface to libtorch that is used for the R package. Both are highly dependent, and should be checked through "get_install_libs_url()"

Examples

if (torch_is_installed()) {
## Not run: 
# on a linux CPU platform 
get_install_libs_url()
# then after making both files available into /tmp/
Sys.setenv(TORCH_URL="/tmp/libtorch-v1.13.1.zip")
Sys.setenv(LANTERN_URL="/tmp/lantern-0.9.1.9001+cpu+arm64-Darwin.zip")
torch::install_torch()

## End(Not run)
}

Description

Installs Torch and its dependencies.

Usage

install_torch(reinstall = FALSE, ..., .inform_restart = TRUE)

Arguments

Details

This function is mainly controlled by environment variables that can be used to override the defaults:

• TORCH_HOME: the installation path. By default dependencies are installed within the package directory. Eg what's given by system.file(package="torch").

• TORCH_URL: A URL, path to a ZIP file or a directory containing a LibTorch version. Files will be installed/copied to the TORCH_HOME directory.

• LANTERN_URL: Same as TORCH_URL but for the Lantern library.

• TORCH_INSTALL_DEBUG: Setting it to 1, shows debug log messages during installation.

• PRECXX11ABI: Setting it to 1 will will trigger the installation of a Pre-cxx11 ABI installation of LibTorch. This can be useful in environments with older versions of GLIBC like CentOS7 and older Debian/Ubuntu versions.

• LANTERN_BASE_URL: The base URL for lantern files. This allows passing a directory where lantern binaries are located. The filename is then constructed as usual.

• TORCH_COMMIT_SHA: torch repository commit sha to be used when querying lantern uploads. Set it to 'none' to avoid looking for build for that commit and use the latest build for the branch.

• CUDA: We try to automatically detect the CUDA version installed in your system, but you might want to manually set it here. You can also disable CUDA installation by setting it to 'cpu'.

• TORCH_R_VERSION: The R torch version. It's unlikely that you need to change it, but it can be useful if you don't have the R package installed, but want to install the dependencies.

The TORCH_INSTALL environment variable can be set to 0 to prevent auto-installing torch and TORCH_LOAD set to 0 to avoid loading dependencies automatically. These environment variables are meant for advanced use cases and troubleshooting only. When timeout error occurs during library archive download, or length of downloaded files differ from reported length, an increase of the timeout value should help.

Description

Checks if the object is a dataloader

Usage

is_dataloader(x)

Arguments

Description

Checks if the object is a nn_buffer

Usage

is_nn_buffer(x)

Arguments

Description

Checks if the object is an nn_module

Usage

is_nn_module(x)

Arguments

Description

Checks if an object is a nn_parameter

Usage

is_nn_parameter(x)

Arguments

Description

Checks if the object is a torch optimizer

Usage

is_optimizer(x)

Arguments

Description

Checks if object is a device

Usage

is_torch_device(x)

Arguments

Description

Check if object is a torch data type

Usage

is_torch_dtype(x)

Arguments

Description

Check if an object is a torch layout.

Usage

is_torch_layout(x)

Arguments

Description

Check if an object is a memory format

Usage

is_torch_memory_format(x)

Arguments

Description

Checks if an object is a QScheme

Usage

is_torch_qscheme(x)

Arguments

Description

Checks if a tensor is undefined

Usage

is_undefined_tensor(x)

Arguments

Description

Creates an iterable dataset

Usage

iterable_dataset(
  name,
  inherit = IterableDataset,
  ...,
  private = NULL,
  active = NULL,
  parent_env = parent.frame()
)

Arguments

Examples

if (torch_is_installed()) {
ids <- iterable_dataset(
  name = "hello",
  initialize = function(n = 5) {
    self$n <- n
    self$i <- 0
  },
  .iter = function() {
    i <- 0
    function() {
      i <<- i + 1
      if (i > self$n) {
        coro::exhausted()
      } else {
        i
      }
    }
  }
)
coro::collect(ids()$.iter())
}

Description

See the TorchScript language reference for documentation on how to write TorchScript code.

Usage

jit_compile(source)

Arguments

Examples

if (torch_is_installed()) {
comp <- jit_compile("
def fn (x):
  return torch.abs(x)

def foo (x):
  return torch.sum(x)

")

comp$fn(torch_tensor(-1))
comp$foo(torch_randn(10))
}

Description

Loads a script_function or script_module previously saved with jit_save

Usage

jit_load(path, ...)

Arguments

Description

Call JIT operators directly from R, keeping the familiar argument types and argument order. Note, however, that:

• all arguments are required (no defaults)

• axis numbering (as well as position numbers overall) starts from 0

• scalars have to be wrapped in jit_scalar()

Usage

jit_ops

Format

An object of class torch_ops of length 0.

Examples

if (torch_is_installed()) {
t1 <- torch::torch_rand(4, 5)
t2 <- torch::torch_ones(5, 4)
# same as torch::torch_matmul(t1, t2)
jit_ops$aten$matmul(t1, t2)

# same as torch_split(torch::torch_arange(0, 3), 2, 1)
jit_ops$aten$split(torch::torch_arange(0, 3), torch::jit_scalar(2L), torch::jit_scalar(0L))

}

Description

Saves a script_function to a path

Usage

jit_save(obj, path, ...)

Arguments

Examples

if (torch_is_installed()) {
fn <- function(x) {
  torch_relu(x)
}

input <- torch_tensor(c(-1, 0, 1))
tr_fn <- jit_trace(fn, input)

tmp <- tempfile("tst", fileext = "pt")
jit_save(tr_fn, tmp)
}

Description

Saves a script_function or script_module in bytecode form, to be loaded on a mobile device

Usage

jit_save_for_mobile(obj, path, ...)

Arguments

Examples

if (torch_is_installed()) {
fn <- function(x) {
  torch_relu(x)
}

input <- torch_tensor(c(-1, 0, 1))
tr_fn <- jit_trace(fn, input)

tmp <- tempfile("tst", fileext = "pt")
jit_save_for_mobile(tr_fn, tmp)
}

Description

Allows disambiguating length 1 vectors from scalars when passing them to the jit.

Usage

jit_scalar(x)

Arguments

Description

Using jit_trace, you can turn an existing R function into a TorchScript script_function. You must provide example inputs, and we run the function, recording the operations performed on all the tensors.

Usage

jit_trace(func, ..., strict = TRUE)

Arguments

Details

The resulting recording of a standalone function produces a script_function. In the future we will also support tracing nn_modules.

Value

An script_function if func is a function and script_module if func is a nn_module().

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 script_function 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,

• Tracing will not record any control-flow like if-statements or loops. When this control-flow is constant across your module, this is fine and it often inlines the control-flow decisions. But sometimes the control-flow is actually part of the model itself. For instance, a recurrent network is a loop over the (possibly dynamic) length of an input sequence.

• In the returned script_function, operations that have different behaviors in training and eval modes will always behave as if it is in the mode it was in during tracing, no matter which mode the script_function is in.

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.

Note

Scripting is not yet supported in R.

Examples

if (torch_is_installed()) {
fn <- function(x) {
  torch_relu(x)
}
input <- torch_tensor(c(-1, 0, 1))
tr_fn <- jit_trace(fn, input)
tr_fn(input)
}

Description

Trace a module and return an executable ScriptModule that will be optimized using just-in-time compilation. When a module is passed to jit_trace(), only the forward method is run and traced. With jit_trace_module(), you can specify a named list of method names to example inputs to trace (see the inputs) argument below.

Usage

jit_trace_module(mod, ..., strict = TRUE)

Arguments

Details

See jit_trace for more information on tracing.

Examples

if (torch_is_installed()) {
linear <- nn_linear(10, 1)
tr_linear <- jit_trace_module(linear, forward = list(torch_randn(10, 10)))

x <- torch_randn(10, 10)
torch_allclose(linear(x), tr_linear(x))
}

Description

Allows specifying that an output or input must be considered a jit tuple and instead of a list or dictionary when tracing.

Usage

jit_tuple(x)

Arguments

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the Cholesky decomposition of a complex Hermitian or real symmetric positive-definite matrix $A \in \mathbb{K}^{n \times n}$ is defined as

Usage

linalg_cholesky(A)

Arguments

Details

Math could not be displayed. Please visit the package website.

where $L$ is a lower triangular matrix and $L^{H}$ is the conjugate transpose when $L$ is complex, and the transpose when $L$ is real-valued.

Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

See Also

• linalg_cholesky_ex() for a version of this operation that skips the (slow) error checking by default and instead returns the debug information. This makes it a faster way to check if a matrix is positive-definite. linalg_eigh() for a different decomposition of a Hermitian matrix. The eigenvalue decomposition gives more information about the matrix but it slower to compute than the Cholesky decomposition.

Other linalg: linalg_cholesky_ex(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_eye(10)
linalg_cholesky(a)
}

Description

This function skips the (slow) error checking and error message construction of linalg_cholesky(), instead directly returning the LAPACK error codes as part of a named tuple ⁠(L, info)⁠. This makes this function a faster way to check if a matrix is positive-definite, and it provides an opportunity to handle decomposition errors more gracefully or performantly than linalg_cholesky() does. Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions. If A 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 info stores a positive integer for the corresponding matrix. The positive integer indicates the order of the leading minor that is not positive-definite, and the decomposition could not be completed. info filled with zeros indicates that the decomposition was successful. If check_errors=TRUE and info contains positive integers, then a RuntimeError is thrown.

Usage

linalg_cholesky_ex(A, check_errors = FALSE)

Arguments

Note

If A is on a CUDA device, this function may synchronize that device with the CPU.

This function is "experimental" and it may change in a future PyTorch release.

See Also

linalg_cholesky() is a NumPy compatible variant that always checks for errors.

Other linalg: linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
A <- torch_randn(2, 2)
out <- linalg_cholesky_ex(A)
out
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the condition number $\kappa$ of a matrix $A \in \mathbb{K}^{n \times n}$ is defined as

Usage

linalg_cond(A, p = NULL)

Arguments

Details

Math could not be displayed. Please visit the package website.

The condition number of A measures the numerical stability of the linear system AX = B with respect to a matrix norm.

Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

p defines the matrix norm that is computed. See the table in 'Details' to find the supported norms.

For p is one of ⁠('fro', 'nuc', inf, -inf, 1, -1)⁠, this function uses linalg_norm() and linalg_inv().

As such, in this case, the matrix (or every matrix in the batch) A has to be square and invertible.

For p in ⁠(2, -2)⁠, this function can be computed in terms of the singular values $\sigma_1 \geq \ldots \geq \sigma_n$

Math could not be displayed. Please visit the package website.

In these cases, it is computed using linalg_svd(). For these norms, the matrix (or every matrix in the batch) A may have any shape.

Value

A real-valued tensor, even when A is complex.

Note

When inputs are on a CUDA device, this function synchronizes that device with the CPU if if p is one of ⁠('fro', 'nuc', inf, -inf, 1, -1)⁠.

Examples

if (torch_is_installed()) {
a <- torch_tensor(rbind(c(1., 0, -1), c(0, 1, 0), c(1, 0, 1)))
linalg_cond(a)
linalg_cond(a, "fro")
}

Description

Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Usage

linalg_det(A)

Arguments

See Also

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_randn(3, 3)
linalg_det(a)

a <- torch_randn(3, 3, 3)
linalg_det(a)
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the eigenvalue decomposition of a square matrix $A \in \mathbb{K}^{n \times n}$ (if it exists) is defined as

Usage

linalg_eig(A)

Arguments

Details

Math could not be displayed. Please visit the package website.

This decomposition exists if and only if $A$ is diagonalizable_. This is the case when all its eigenvalues are different. Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Value

A list ⁠(eigenvalues, eigenvectors)⁠ which corresponds to $\Lambda$ and $V$ above. eigenvalues and eigenvectors will always be complex-valued, even when A is real. The eigenvectors will be given by the columns of eigenvectors.

Warning

• This function assumes that A is diagonalizable_ (for example, when all the eigenvalues are different). If it is not diagonalizable, the returned eigenvalues will be correct but $A \neq V \operatorname{diag}(\Lambda)V^{-1}$.

• The eigenvectors of a matrix are not unique, nor are they continuous with respect to A. Due to this lack of uniqueness, different hardware and software may compute different eigenvectors. This non-uniqueness is caused by the fact that multiplying an eigenvector by a non-zero number produces another set of valid eigenvectors of the matrix. In this implmentation, the returned eigenvectors are normalized to have norm 1 and largest real component.

• Gradients computed using V will only be finite when A does not have repeated eigenvalues. Furthermore, if the distance between any two eigenvalues is close to zero, the gradient will be numerically unstable, as it depends on the eigenvalues $\lambda_i$ through the computation of $\frac{1}{\min_{i \neq j} \lambda_i - \lambda_j}$.

Note

The eigenvalues and eigenvectors of a real matrix may be complex.

See Also

• linalg_eigvals() computes only the eigenvalues. Unlike linalg_eig(), the gradients of linalg_eigvals() are always numerically stable.

• linalg_eigh() for a (faster) function that computes the eigenvalue decomposition for Hermitian and symmetric matrices.

• linalg_svd() for a function that computes another type of spectral decomposition that works on matrices of any shape.

• linalg_qr() for another (much faster) decomposition that works on matrices of any shape.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_randn(2, 2)
wv <- linalg_eig(a)
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the eigenvalue decomposition of a complex Hermitian or real symmetric matrix $A \in \mathbb{K}^{n \times n}$ is defined as

Usage

linalg_eigh(A, UPLO = "L")

Arguments

Details

Math could not be displayed. Please visit the package website.

where $Q^{H}$ is the conjugate transpose when $Q$ is complex, and the transpose when $Q$ is real-valued. $Q$ is orthogonal in the real case and unitary in the complex case.

Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

A is assumed to be Hermitian (resp. symmetric), but this is not checked internally, instead:

• If UPLO\ ⁠= 'L'⁠ (default), only the lower triangular part of the matrix is used in the computation.

• If UPLO\ ⁠= 'U'⁠, only the upper triangular part of the matrix is used. The eigenvalues are returned in ascending order.

Value

A list ⁠(eigenvalues, eigenvectors)⁠ which corresponds to $\Lambda$ and $Q$ above. eigenvalues will always be real-valued, even when A is complex.

It will also be ordered in ascending order. eigenvectors will have the same dtype as A and will contain the eigenvectors as its columns.

Warning

• The eigenvectors of a symmetric matrix are not unique, nor are they continuous with respect to A. Due to this lack of uniqueness, different hardware and software may compute different eigenvectors. This non-uniqueness is caused by the fact that multiplying an eigenvector by -1 in the real case or by $e^{i \phi}, \phi \in \mathbb{R}$ in the complex case produces another set of valid eigenvectors of the matrix. This non-uniqueness problem is even worse when the matrix has repeated eigenvalues. In this case, one may multiply the associated eigenvectors spanning the subspace by a rotation matrix and the resulting eigenvectors will be valid eigenvectors.

• Gradients computed using the eigenvectors tensor will only be finite when A has unique eigenvalues. Furthermore, if the distance between any two eigvalues is close to zero, the gradient will be numerically unstable, as it depends on the eigenvalues $\lambda_i$ through the computation of $\frac{1}{\min_{i \neq j} \lambda_i - \lambda_j}$.

Note

The eigenvalues of real symmetric or complex Hermitian matrices are always real.

See Also

• linalg_eigvalsh() computes only the eigenvalues values of a Hermitian matrix. Unlike linalg_eigh(), the gradients of linalg_eigvalsh() are always numerically stable.

• linalg_cholesky() for a different decomposition of a Hermitian matrix. The Cholesky decomposition gives less information about the matrix but is much faster to compute than the eigenvalue decomposition.

• linalg_eig() for a (slower) function that computes the eigenvalue decomposition of a not necessarily Hermitian square matrix.

• linalg_svd() for a (slower) function that computes the more general SVD decomposition of matrices of any shape.

• linalg_qr() for another (much faster) decomposition that works on general matrices.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_randn(2, 2)
linalg_eigh(a)
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the eigenvalues of a square matrix $A \in \mathbb{K}^{n \times n}$ are defined as the roots (counted with multiplicity) of the polynomial p of degree n given by

Usage

linalg_eigvals(A)

Arguments

Details

Math could not be displayed. Please visit the package website.

where $\mathrm{I}_n$ is the n-dimensional identity matrix. Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Note

The eigenvalues of a real matrix may be complex, as the roots of a real polynomial may be complex. The eigenvalues of a matrix are always well-defined, even when the matrix is not diagonalizable.

See Also

linalg_eig() computes the full eigenvalue decomposition.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_randn(2, 2)
w <- linalg_eigvals(a)
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the eigenvalues of a complex Hermitian or real symmetric matrix $A \in \mathbb{K}^{n \times n}$ are defined as the roots (counted with multiplicity) of the polynomial p of degree n given by

Usage

linalg_eigvalsh(A, UPLO = "L")

Arguments

Details

Math could not be displayed. Please visit the package website.

where $\mathrm{I}_n$ is the n-dimensional identity matrix.

The eigenvalues of a real symmetric or complex Hermitian matrix are always real. Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions. The eigenvalues are returned in ascending order.

A is assumed to be Hermitian (resp. symmetric), but this is not checked internally, instead:

• If UPLO\ ⁠= 'L'⁠ (default), only the lower triangular part of the matrix is used in the computation.

• If UPLO\ ⁠= 'U'⁠, only the upper triangular part of the matrix is used.

Value

A real-valued tensor cointaining the eigenvalues even when A is complex. The eigenvalues are returned in ascending order.

See Also

• linalg_eigh() computes the full eigenvalue decomposition.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_randn(2, 2)
linalg_eigvalsh(a)
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, for a matrix $V \in \mathbb{K}^{m \times n}$ with columns $v_i \in \mathbb{K}^m$ with $m \geq n$ and a vector $\tau \in \mathbb{K}^k$ with $k \leq n$, this function computes the first $n$ columns of the matrix

Usage

linalg_householder_product(A, tau)

Arguments

Details

Math could not be displayed. Please visit the package website.

where $\mathrm{I}_m$ is the m-dimensional identity matrix and $v^{H}$ is the conjugate transpose when $v$ is complex, and the transpose when $v$ is real-valued. See Representation of Orthogonal or Unitary Matrices for further details.

Supports inputs of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if the inputs are batches of matrices then the output has the same batch dimensions.

Note

This function only uses the values strictly below the main diagonal of A. The other values are ignored.

See Also

• torch_geqrf() can be used together with this function to form the Q from the linalg_qr() decomposition.

• torch_ormqr() is a related function that computes the matrix multiplication of a product of Householder matrices with another matrix. However, that function is not supported by autograd.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
A <- torch_randn(2, 2)
h_tau <- torch_geqrf(A)
Q <- linalg_householder_product(h_tau[[1]], h_tau[[2]])
torch_allclose(Q, linalg_qr(A)[[1]])
}

Description

Throws a runtime_error if the matrix is not invertible.

Usage

linalg_inv(A)

Arguments

Details

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, for a matrix $A \in \mathbb{K}^{n \times n}$, its inverse matrix $A^{-1} \in \mathbb{K}^{n \times n}$ (if it exists) is defined as

Math could not be displayed. Please visit the package website.

where $\mathrm{I}_n$ is the n-dimensional identity matrix.

The inverse matrix exists if and only if $A$ is invertible. In this case, the inverse is unique. Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Consider using linalg_solve() if possible for multiplying a matrix on the left by the inverse, as linalg_solve(A, B) == A$inv() %*% B It is always prefered to use linalg_solve() when possible, as it is faster and more numerically stable than computing the inverse explicitly.

See Also

linalg_pinv() computes the pseudoinverse (Moore-Penrose inverse) of matrices of any shape. linalg_solve() computes A$inv() %*% B with a numerically stable algorithm.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
A <- torch_randn(4, 4)
linalg_inv(A)
}

Description

Returns a namedtuple ⁠(inverse, info)⁠. inverse contains the result of inverting A and info stores the LAPACK error codes. If A is not an invertible matrix, or if it's a batch of matrices and one or more of them is not an invertible matrix, then info stores a positive integer for the corresponding matrix. The positive integer indicates the diagonal element of the LU decomposition of the input matrix that is exactly zero. info filled with zeros indicates that the inversion was successful. If check_errors=TRUE and info contains positive integers, then a RuntimeError is thrown. Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Usage

linalg_inv_ex(A, check_errors = FALSE)

Arguments

Note

If A is on a CUDA device then this function may synchronize that device with the CPU.

This function is "experimental" and it may change in a future PyTorch release.

See Also

linalg_inv() is a NumPy compatible variant that always checks for errors.

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv(), linalg_lstsq(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
A <- torch_randn(3, 3)
out <- linalg_inv_ex(A)
}

Description

Letting $\mathbb{K}$ be $\mathbb{R}$ or $\mathbb{C}$, the least squares problem for a linear system $AX = B$ with $A \in \mathbb{K}^{m \times n}, B \in \mathbb{K}^{m \times k}$ is defined as

Usage

linalg_lstsq(A, B, rcond = NULL, ..., driver = NULL)

Arguments

Details

Math could not be displayed. Please visit the package website.

where $\|-\|_F$ denotes the Frobenius norm. Supports inputs of float, double, cfloat and cdouble dtypes.

Also supports batches of matrices, and if the inputs are batches of matrices then the output has the same batch dimensions. driver chooses the LAPACK/MAGMA function that will be used.

For CPU inputs the valid values are 'gels', 'gelsy', ⁠'gelsd⁠, 'gelss'. For CUDA input, the only valid driver is 'gels', which assumes that A is full-rank.

To choose the best driver on CPU consider:

• If A is well-conditioned (its condition number is not too large), or you do not mind some precision loss.

• For a general matrix: 'gelsy' (QR with pivoting) (default)

• If A is full-rank: 'gels' (QR)

• If A is not well-conditioned.

• 'gelsd' (tridiagonal reduction and SVD)

• But if you run into memory issues: 'gelss' (full SVD).

See also the full description of these drivers

rcond is used to determine the effective rank of the matrices in A when driver is one of ('gelsy', 'gelsd', 'gelss'). In this case, if $\sigma_i$ are the singular values of A in decreasing order, $\sigma_i$ will be rounded down to zero if $\sigma_i \leq rcond \cdot \sigma_1$. If rcond = NULL (default), rcond is set to the machine precision of the dtype of A.

This function returns the solution to the problem and some extra information in a list of four tensors ⁠(solution, residuals, rank, singular_values)⁠. For inputs A, B of shape ⁠(*, m, n)⁠, ⁠(*, m, k)⁠ respectively, it cointains

• solution: the least squares solution. It has shape ⁠(*, n, k)⁠.

• residuals: the squared residuals of the solutions, that is, $\|AX - B\|_F^2$. It has shape equal to the batch dimensions of A. It is computed when m > n and every matrix in A is full-rank, otherwise, it is an empty tensor. If A is a batch of matrices and any matrix in the batch is not full rank, then an empty tensor is returned. This behavior may change in a future PyTorch release.

• rank: tensor of ranks of the matrices in A. It has shape equal to the batch dimensions of A. It is computed when driver is one of ('gelsy', 'gelsd', 'gelss'), otherwise it is an empty tensor.

• singular_values: tensor of singular values of the matrices in A. It has shape ⁠(*, min(m, n))⁠. It is computed when driver is one of ('gelsd', 'gelss'), otherwise it is an empty tensor.

Value

A list ⁠(solution, residuals, rank, singular_values)⁠.

Warning

The default value of rcond may change in a future PyTorch release. It is therefore recommended to use a fixed value to avoid potential breaking changes.

Note

This function computes X = A$pinverse() %*% B in a faster and more numerically stable way than performing the computations separately.

See Also

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_matrix_norm(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
A <- torch_tensor(rbind(c(10, 2, 3), c(3, 10, 5), c(5, 6, 12)))$unsqueeze(1) # shape (1, 3, 3)
B <- torch_stack(list(
  rbind(c(2, 5, 1), c(3, 2, 1), c(5, 1, 9)),
  rbind(c(4, 2, 9), c(2, 0, 3), c(2, 5, 3))
), dim = 1) # shape (2, 3, 3)
X <- linalg_lstsq(A, B)$solution # A is broadcasted to shape (2, 3, 3)
}

Description

If A is complex valued, it computes the norm of A$abs() Support input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices: the norm will be computed over the dimensions specified by the 2-tuple dim and the other dimensions will be treated as batch dimensions. The output will have the same batch dimensions.

Usage

linalg_matrix_norm(
  A,
  ord = "fro",
  dim = c(-2, -1),
  keepdim = FALSE,
  dtype = NULL
)

Arguments

Details

ord defines the norm that is computed. The following norms are supported:

See Also

Other linalg: linalg_cholesky_ex(), linalg_cholesky(), linalg_det(), linalg_eigh(), linalg_eigvalsh(), linalg_eigvals(), linalg_eig(), linalg_householder_product(), linalg_inv_ex(), linalg_inv(), linalg_lstsq(), linalg_matrix_power(), linalg_matrix_rank(), linalg_multi_dot(), linalg_norm(), linalg_pinv(), linalg_qr(), linalg_slogdet(), linalg_solve_triangular(), linalg_solve(), linalg_svdvals(), linalg_svd(), linalg_tensorinv(), linalg_tensorsolve(), linalg_vector_norm()

Examples

if (torch_is_installed()) {
a <- torch_arange(0, 8, dtype = torch_float())$reshape(c(3, 3))
linalg_matrix_norm(a)
linalg_matrix_norm(a, ord = -1)
b <- a$expand(c(2, -1, -1))
linalg_matrix_norm(b)
linalg_matrix_norm(b, dim = c(1, 3))
}

Description

Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

Usage

linalg_matrix_power(A, n)

Arguments

Details

If n=0, it returns the identity matrix (or batch) of the same shape as A. If n is negative, it returns the inverse of each matrix (if invertible) raised to the power of abs(n).