# PyTorch

> PyTorch documentation.


---

# Tensor Accessors

For element-wise operations in custom kernels, use *accessors* to avoid
dynamic dispatch overhead.

## CPU Accessors

```
torch::Tensor foo = torch::rand({12, 12});

// Create accessor - validates type and dimensions once
auto foo_a = foo.accessor<float, 2>();

float trace = 0;
for (int i = 0; i < foo_a.size(0); i++) {
 trace += foo_a[i][i];
}
```

## CUDA Packed Accessors

For CUDA kernels, use *packed accessors* which copy metadata instead of
pointing to it:

```
__global__ void kernel(torch::PackedTensorAccessor64<float, 2> foo, float* trace) {
 int i = threadIdx.x;
 gpuAtomicAdd(trace, foo[i][i]);
}

torch::Tensor foo = torch::rand({12, 12}).cuda();
auto foo_a = foo.packed_accessor64<float, 2>();

float trace = 0;
kernel<<<1, 12>>>(foo_a, &trace);
```

Tip

Use `PackedTensorAccessor32` and `packed_accessor32` for 32-bit indexing,
which is faster on CUDA but may overflow for large tensors.

---

# Tensor Creation

Factory functions create new tensors with different initialization patterns.
All factory functions follow a general schema:

```
torch::<function-name>(<function-specific-options>, <sizes>, <tensor-options>)
```

## Available Factory Functions

- `torch::zeros` - Tensor filled with zeros
- `torch::ones` - Tensor filled with ones
- `torch::empty` - Uninitialized tensor
- `torch::full` - Tensor filled with a single value
- `torch::rand` - Uniform random values on [0, 1)
- `torch::randn` - Standard normal distribution
- `torch::randint` - Random integers in a range
- `torch::arange` - Sequence of integers
- `torch::linspace` - Linearly spaced values
- `torch::logspace` - Logarithmically spaced values
- `torch::eye` - Identity matrix
- `torch::randperm` - Random permutation of integers

## Specifying a Size

Functions that do not require specific arguments can be invoked with just a
size. For example, the following line creates a vector with 5 components:

```
torch::Tensor tensor = torch::ones(5);
```

An `IntArrayRef` is constructed by specifying the size along each dimension in
curly braces. For example, `{2, 3}` for a matrix with two rows and three
columns, `{3, 4, 5}` for a three-dimensional tensor:

```
torch::Tensor tensor = torch::randn({3, 4, 5});
assert(tensor.sizes() == std::vector<int64_t>{3, 4, 5});
```

You can also pass an `std::vector<int64_t>` instead of curly braces.
Use `tensor.size(i)` to access a single dimension.

## Passing Function-Specific Parameters

Some factory functions accept additional parameters. For example, `randint`
takes an upper bound on the value for the integers it generates:

```
torch::Tensor tensor = torch::randint(/*high=*/10, {5, 5});

// With a lower bound
torch::Tensor tensor = torch::randint(/*low=*/3, /*high=*/10, {5, 5});
```

Tip

The size always follows the function-specific arguments.

Attention

Some functions like `arange` do not need a size at all, since it is fully
determined by the function-specific arguments (the range bounds).

## Configuring Properties with TensorOptions

`TensorOptions` configures the data type, layout, device, and
`requires_grad` of a new tensor. The construction axes are:

- `dtype`: the data type of the elements (e.g. `kFloat32`, `kInt64`)
- `layout`: either `kStrided` (dense) or `kSparse`
- `device`: a compute device (e.g. `kCPU`, `kCUDA`)
- `requires_grad`: whether to track gradients

Allowed values:

- `dtype`: `kUInt8`, `kInt8`, `kInt16`, `kInt32`, `kInt64`,
`kFloat32`, `kFloat64`
- `layout`: `kStrided`, `kSparse`
- `device`: `kCPU`, or `kCUDA` (with an optional device index)
- `requires_grad`: `true` or `false`

Tip

Rust-style shorthands exist for dtypes, like `kF32` instead of
`kFloat32`. See
[torch/types.h](https://github.com/pytorch/pytorch/blob/main/torch/csrc/api/include/torch/types.h)
for the full list.

Here is an example of creating a `TensorOptions` object:

```
auto options =
 torch::TensorOptions()
 .dtype(torch::kFloat64)
 .layout(torch::kStrided)
 .device(torch::kCUDA, 1)
 .requires_grad(true);

torch::Tensor tensor = torch::full({3, 4}, /*value=*/123, options);

assert(tensor.dtype() == torch::kFloat64);
assert(tensor.layout() == torch::kStrided);
assert(tensor.device().type() == torch::kCUDA);
assert(tensor.device().index() == 1);
assert(tensor.requires_grad());
```

**Defaults:** Any axis you omit takes its default value: `kFloat32` for dtype,
`kStrided` for layout, `kCPU` for device, and `false` for
`requires_grad`. This means you can omit `TensorOptions` entirely:

```
// A 32-bit float, strided, CPU tensor that does not require a gradient.
torch::Tensor tensor = torch::randn({3, 4});
```

**Shorthand syntax:** For each axis there is a free function in the `torch::`
namespace (`torch::dtype()`, `torch::device()`, `torch::layout()`,
`torch::requires_grad()`). Each returns a `TensorOptions` object that can
be further refined with builder methods:

```
// These are equivalent:
torch::ones(10, torch::TensorOptions().dtype(torch::kFloat32))
torch::ones(10, torch::dtype(torch::kFloat32))

// Chaining:
torch::ones(10, torch::dtype(torch::kFloat32).layout(torch::kStrided))
```

**Implicit construction:** `TensorOptions` is implicitly constructible from
individual values, so when only one axis differs from the default you can
write:

```
torch::ones(10, torch::kFloat32)
```

Putting it all together, a C++ tensor creation call mirrors the Python
equivalent closely:

```
# Python
torch.randn(3, 4, dtype=torch.float32, device=torch.device('cuda', 1), requires_grad=True)
```

```
// C++
torch::randn({3, 4}, torch::dtype(torch::kFloat32).device(torch::kCUDA, 1).requires_grad(true))
```

## Using Externally Created Data

If you already have tensor data allocated in memory (CPU or CUDA), use
`from_blob` to view that memory as a `Tensor`:

```
float data[] = {1, 2, 3, 4, 5, 6};
torch::Tensor tensor = torch::from_blob(data, {2, 3});
```

Note

Tensors created with `from_blob` cannot be resized because ATen does not
own the memory.

## Tensor Conversion

Use `to()` to convert tensors between dtypes and devices. The conversion
creates a new tensor and does not occur in-place:

```
torch::Tensor source = torch::randn({2, 3}, torch::kInt64);

// Convert dtype
torch::Tensor float_tensor = source.to(torch::kFloat32);

// Move to GPU (default CUDA device)
torch::Tensor gpu_tensor = float_tensor.to(torch::kCUDA);

// Specific GPU device
torch::Tensor gpu1_tensor = float_tensor.to(torch::Device(torch::kCUDA, 1));

// Async copy
torch::Tensor async_tensor = gpu_tensor.to(torch::kCPU, /*non_blocking=*/true);
```

Attention

The result of the conversion is a new tensor pointing to new memory,
unrelated to the source tensor.

## Scalars and Zero-Dimensional Tensors

`Scalar` represents a single dynamically-typed number. Like a `Tensor`,
`Scalar` is dynamically typed and can hold any of ATen's number types.
Scalars can be implicitly constructed from C++ number types:

```
namespace torch {
Tensor addmm(Scalar beta, const Tensor & self,
 Scalar alpha, const Tensor & mat1,
 const Tensor & mat2);
Scalar sum(const Tensor & self);
} // namespace torch

// Usage
torch::Tensor a = ...;
torch::Tensor b = ...;
torch::Tensor c = ...;
torch::Tensor r = torch::addmm(1.0, a, .5, b, c);
```

Zero-dimensional tensors hold a single value and can reference elements in
larger tensors:

```
torch::Tensor matrix = torch::rand({10, 20});
matrix[1][2] = 4; // matrix[1][2] is a zero-dimensional tensor
```

---

# ATen: Tensor Library

ATen (A Tensor Library) is the foundational tensor and mathematical operation
library on which all of PyTorch is built. It provides the core `Tensor` class
and hundreds of mathematical operations that work on tensors.

**When to use ATen directly:**

- When writing low-level tensor operations or custom kernels
- When you need direct access to tensor data and metadata
- When working with the PyTorch internals or extending PyTorch

**Basic usage:**

```
#include <ATen/ATen.h>

// Create tensors
at::Tensor a = at::ones({2, 3});
at::Tensor b = at::randn({2, 3});

// Perform operations
at::Tensor c = a + b;
at::Tensor d = at::matmul(a.t(), b);

// Move to GPU
if (at::cuda::is_available()) {
 at::Tensor gpu_tensor = c.to(at::kCUDA);
}
```

For most applications, prefer using the higher-level `torch::` namespace
(see [Neural Network Modules (torch::nn)](../nn/index.html), [Optimizers (torch::optim)](../optim/index.html)) which provides a more user-friendly API.

## Header Files

The following headers are part of the ATen public API:

- `ATen/ATen.h` - Main ATen header
- `ATen/Backend.h` - Backend enumeration
- `ATen/core/Tensor.h` - Tensor class
- `ATen/core/ivalue.h` - IValue type (see [C10: Core Utilities](../c10/index.html))
- `ATen/core/ScalarType.h` - Data type definitions
- `ATen/TensorOptions.h` - Tensor creation options
- `ATen/Scalar.h` - Scalar type
- `ATen/Layout.h` - Tensor layout
- `ATen/DeviceGuard.h` - Device context management
- `ATen/native/TensorShape.h` - Tensor shape operations
- `ATen/cuda/CUDAContext.h` - CUDA context (see [CUDA Support](../cuda/index.html))
- `ATen/cudnn/Descriptors.h` - cuDNN descriptors
- `ATen/mkl/Descriptors.h` - MKL descriptors

Note

The core `at::Tensor` class is defined in a generated header file
(`TensorBody.h`) that only exists after building PyTorch. The documentation
below describes the API manually.

## ATen Categories

- [Tensor Class](tensor.html)
- [Tensor Creation](creation.html)
- [Tensor Indexing](indexing.html)
- [Tensor Accessors](accessors.html)

---

# Tensor Indexing

The PyTorch C++ API provides tensor indexing similar to Python. Use
`torch::indexing` namespace for index types:

```
using namespace torch::indexing;
```

The main difference from Python is that instead of using the `[]` operator,
the C++ API uses the `index` and `index_put_` methods:

- `torch::Tensor::index` -- read elements
- `torch::Tensor::index_put_` -- write elements

## Index Types

The `TensorIndex` class accepts six types of indices via implicit constructors:

| Type | C++ | Python equivalent |
| --- | --- | --- |
| None (unsqueeze) | `None` | `None` |
| Ellipsis | `Ellipsis` or `"..."` | `...` |
| Integer | `0`, `1`, `-1` | `0`, `1`, `-1` |
| Boolean | `true`, `false` | `True`, `False` |
| Slice | `Slice(start, stop, step)` | `start:stop:step` |
| Tensor | `torch::tensor({0, 2})` | `torch.tensor([0, 2])` |

## Getter Operations

| Python | C++ |
| --- | --- |
| `tensor[0]` | `tensor.index({0})` |
| `tensor[-1]` | `tensor.index({-1})` |
| `tensor[1, 2]` | `tensor.index({1, 2})` |
| `tensor[1, :, 3]` | `tensor.index({1, Slice(), 3})` |
| `tensor[None]` | `tensor.index({None})` |
| `tensor[:, None]` | `tensor.index({Slice(), None})` |
| `tensor[...]` | `tensor.index({Ellipsis})` or `tensor.index({"..."})` |
| `tensor[..., 0]` | `tensor.index({Ellipsis, 0})` |
| `tensor[1::2]` | `tensor.index({Slice(1, None, 2)})` |
| `tensor[True]` | `tensor.index({true})` |
| `tensor[torch.tensor([1, 2])]` | `tensor.index({torch::tensor({1, 2})})` |
| `tensor[bool_mask]` | `tensor.index({bool_mask})` |
| `tensor[:, torch.tensor([[0,1],[4,3]])]` | `tensor.index({Slice(), torch::tensor({{0,1},{4,3}})})` |
| `tensor[cond > 0]` | `tensor.index({cond > 0})` |

## Setter Operations

| Python | C++ |
| --- | --- |
| `tensor[0] = 1` | `tensor.index_put_({0}, 1)` |
| `tensor[1, 2] = 1` | `tensor.index_put_({1, 2}, 1)` |
| `tensor[1] = torch.arange(5)` | `tensor.index_put_({1}, torch::arange(5))` |
| `tensor[1::2] = 1` | `tensor.index_put_({Slice(1, None, 2)}, 1)` |
| `tensor[0, 1::2] = torch.tensor([3., 4.])` | `tensor.index_put_({0, Slice(1, None, 2)}, torch::tensor({3., 4.}))` |
| `tensor[...] = 0` | `tensor.index_put_({Ellipsis}, 0)` |
| `tensor[None] = value` | `tensor.index_put_({None}, value)` |
| `tensor[bool_mask] = 0` | `tensor.index_put_({bool_mask}, 0)` |
| `tensor[torch.tensor([0, 2])] = value` | `tensor.index_put_({torch::tensor({0, 2})}, value)` |
| `tensor[1:2, torch.tensor([1,2])] = 0` | `tensor.index_put_({Slice(1, 2), torch::tensor({1, 2})}, 0)` |

The `index_put_` method also accepts an optional `accumulate` parameter.
When `true`, values are added to existing values instead of replacing them:

```
tensor.index_put_({mask}, values, /*accumulate=*/true);
```

## Slice Syntax

The `Slice` constructor signature is:

```
Slice(
 std::optional<c10::SymInt> start = std::nullopt,
 std::optional<c10::SymInt> stop = std::nullopt,
 std::optional<c10::SymInt> step = std::nullopt);
```

Pass `None` for open-ended bounds:

| Python | C++ |
| --- | --- |
| `:` or `::` | `Slice()` or `Slice(None, None)` |
| `1:` | `Slice(1, None)` |
| `:3` | `Slice(None, 3)` |
| `1:3` | `Slice(1, 3)` |
| `1:3:2` | `Slice(1, 3, 2)` |
| `::2` | `Slice(None, None, 2)` |

## Full Example

```
#include <torch/torch.h>

using namespace torch::indexing;

auto tensor = torch::arange(2 * 3 * 4).reshape({2, 3, 4});

// Basic indexing
auto row = tensor.index({0}); // tensor[0]
auto elem = tensor.index({1, 2, 3}); // tensor[1, 2, 3]

// Slicing
auto sliced = tensor.index({Slice(), Slice(0, 2)}); // tensor[:, 0:2]

// None (unsqueeze) and Ellipsis
auto unsqueezed = tensor.index({None}); // tensor[None]
auto last_dim = tensor.index({Ellipsis, -1}); // tensor[..., -1]

// Boolean mask indexing
auto mask = tensor > 10;
auto selected = tensor.index({mask}); // tensor[tensor > 10]

// Integer tensor (fancy) indexing
auto idx = torch::tensor({0, 2});
auto gathered = tensor.index({Slice(), idx}); // tensor[:, [0, 2]]

// Setting values
tensor.index_put_({0, Slice(), 0}, 99); // tensor[0, :, 0] = 99
tensor.index_put_({mask}, 0); // tensor[tensor > 10] = 0
```

---

# Tensor Class

The `at::Tensor` class is the primary tensor class in ATen, representing
a multi-dimensional array with a specific data type and device.

## Tensor

class at::Tensor

The primary tensor class in ATen. Represents a multi-dimensional array
with a specific data type and device.

Tensor()

Default constructor. Creates an undefined tensor.

int64_t dim() const

Returns the number of dimensions of the tensor.

int64_t size(int64_t dim) const

Returns the size of the tensor at the given dimension.

IntArrayRef sizes() const

Returns the sizes of all dimensions.

IntArrayRef strides() const

Returns the strides of all dimensions.

ScalarType scalar_type() const

Returns the data type of the tensor.

Device device() const

Returns the device where the tensor is stored.

bool is_cuda() const

Returns true if the tensor is on a CUDA device.

bool is_cpu() const

Returns true if the tensor is on CPU.

bool requires_grad() const

Returns true if gradients need to be computed for this tensor.

Tensor &requires_grad_(bool requires_grad = true)

Sets whether gradients should be computed for this tensor.

Tensor to(Device device) const

Returns a tensor on the specified device.

Tensor to(ScalarType dtype) const

Returns a tensor with the specified data type.

Tensor contiguous() const

Returns a contiguous tensor with the same data.

void *data_ptr() const

Returns a pointer to the underlying data.

**Example:**

```
#include <ATen/ATen.h>

at::Tensor a = at::ones({2, 2}, at::kInt);
at::Tensor b = at::randn({2, 2});
auto c = a + b.to(at::kInt);
```

## TensorOptions

class at::TensorOptions

A class to specify options for tensor creation, including dtype, device,
layout, and requires_grad.

TensorOptions()

Default constructor.

TensorOptions dtype(ScalarType dtype) const

Returns options with the specified data type.

TensorOptions device(Device device) const

Returns options with the specified device.

TensorOptions layout(Layout layout) const

Returns options with the specified layout.

TensorOptions requires_grad(bool requires_grad) const

Returns options with the specified requires_grad setting.

**Example:**

```
auto options = at::TensorOptions()
 .dtype(at::kFloat)
 .device(at::kCUDA, 0)
 .requires_grad(true);

at::Tensor tensor = at::zeros({3, 4}, options);
```

## Scalar

class at::Scalar

Represents a scalar value that can be converted to various numeric types.

Scalar(int64_t v)

Construct from an integer.

Scalar(double v)

Construct from a double.

template<typename T>
T to() const

Convert to the specified type.

bool isIntegral(bool includeBool = false) const

Returns true if the scalar is an integral type.

bool isFloatingPoint() const

Returns true if the scalar is a floating point type.

## ScalarType

enum class at::ScalarType

Enumeration of data types supported by tensors.

enumerator Byte

8-bit unsigned integer (uint8_t)

enumerator Char

8-bit signed integer (int8_t)

enumerator Short

16-bit signed integer (int16_t)

enumerator Int

32-bit signed integer (int32_t)

enumerator Long

64-bit signed integer (int64_t)

enumerator Half

16-bit floating point (float16)

enumerator Float

32-bit floating point (float)

enumerator Double

64-bit floating point (double)

enumerator Bool

Boolean type

enumerator BFloat16

Brain floating point (bfloat16)

Convenience constants:

- `at::kByte`, `at::kChar`, `at::kShort`, `at::kInt`, `at::kLong`
- `at::kHalf`, `at::kFloat`, `at::kDouble`, `at::kBFloat16`
- `at::kBool`

## DeviceGuard

class DeviceGuard

RAII guard that sets a certain default device in its constructor, and changes it back to the device that was originally active upon destruction.

The device is always reset to the one that was active at the time of construction of the guard. Even if you `set_device` after construction, the destructor will still reset the device to the one that was active at construction time.

This device guard does NOT have an uninitialized state; it is guaranteed to reset a device on exit. If you are in a situation where you *might* want to setup a guard (i.e., are looking for the moral equivalent of std::optional<DeviceGuard>), see [OptionalDeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_optional_device_guard).

Public Functions

explicit DeviceGuard() = delete

No default constructor; see Note [Omitted default constructor from RAII].

inline explicit DeviceGuard([Device](../c10/device.html#_CPPv4N3c106DeviceE) device)

Set the current device to the passed [Device](../c10/device.html#PyTorchstructc10_1_1_device).

inline explicit DeviceGuard([Device](../c10/device.html#_CPPv4N3c106DeviceE) device, const impl::DeviceGuardImplInterface *impl)

This constructor is for testing only.

~DeviceGuard() = default

DeviceGuard(const DeviceGuard&) = delete

Copy is disallowed.

DeviceGuard &operator=(const DeviceGuard&) = delete

DeviceGuard(DeviceGuard &&other) = delete

Move is disallowed, as [DeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_device_guard) does not have an uninitialized state, which is required for moves on types with nontrivial destructors.

DeviceGuard &operator=(DeviceGuard &&other) = delete

inline void reset_device(at::Device device)

Sets the device to the given one.

The specified device must be consistent with the device type originally specified during guard construction.

TODO: The consistency check here is inconsistent with StreamGuard's behavior with set_stream, where a stream on a different device than the original one isn't an error; we just reset the stream and then switch devices.

inline void reset_device(at::Device device, const impl::DeviceGuardImplInterface *impl)

This method is for testing only.

inline void set_index(DeviceIndex index)

Sets the device index to the given one.

The device type is inferred from the original device type the guard was constructed with.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) original_device() const

Returns the device that was set at the time the guard was constructed.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) current_device() const

Returns the most recent device that was set using this device guard, either from construction, or via set_device.

**Example:**

```
{
 c10::DeviceGuard guard(at::Device(at::kCUDA, 1));
 // Operations here run on CUDA device 1
 auto tensor = at::zeros({2, 2});
}
// Previous device is restored
```

## Layout

enum class at::Layout

Enumeration of tensor memory layouts.

enumerator Strided

Dense tensor with strides.

enumerator Sparse

Sparse tensor (COO format).

enumerator SparseCsr

Sparse tensor in CSR format.

enumerator SparseCsc

Sparse tensor in CSC format.

---

# Custom Autograd Functions

PyTorch allows you to define custom autograd functions with custom forward
and backward implementations.

## Function Base Class

template<class T>
struct Function

To use custom autograd operations, implement a Function subclass with static forward and backward functions:

`forward` can take as many arguments as you want and should return either a variable list or a Variable. Use of any direct Variable arguments will be registered in the graph but no vectors/sets or any other data structures will be traversed. You can use std::optional<Tensor> as one of the arguments and it will be registered as a variable in the graph if the argument has a value. It should take a pointer to `torch::autograd::AutogradContext` as the first argument. Variables can be saved in the `ctx` using `ctx->save_for_backward` (see `torch::autograd::AutogradContext::save_for_backward`) and other data can be saved in the `ctx->saved_data` map (see `torch::autograd::AutogradContext::saved_data`) in the form of `<std::string, at::IValue>` pairs.

`backward` should take a pointer to `torch::autograd::AutogradContext` and a variable list containing as many Variables as there were outputs from `forward` as arguments. It should return as many Variables as there were inputs with each of them containing the gradient w.r.t. its corresponding input. Variables saved in `forward` can be accessed with `ctx->get_saved_variables` (see `torch::autograd::AutogradContext::get_saved_variables`) and other saved data can be accessed from `ctx->saved_data`. To enable compiled autograd support (torch.compile for backward) for your custom autograd operation, you can set MyFunction::is_traceable (see Function::istraceable notes below).

For example:

```
class MyFunction : public Function<MyFunction> {
 public:
 static constexpr bool is_traceable = true;

 static variable_list forward(AutogradContext *ctx, int n, Variable var) {
 // Save data for backward in context
 ctx->saved_data["n"] = n;
 var.mul_(n);
 // Mark var as modified by inplace operation
 ctx->mark_dirty({var});
 return {var};
 }

 static variable_list backward(AutogradContext *ctx, variable_list
 grad_output) {
 // Use data saved in forward
 auto n = ctx->saved_data["n"].toInt();
 return {grad_output[0]*n};
 }
};
```

To use `MyFunction`:

```
Variable x;
auto y = MyFunction::apply(6, x);
// Example backward call
y[0].sum().backward();
```

Public Static Functions

template<typename X = T, typename ...Args>
static auto apply(Args&&... args) -> std::enable_if_t<std::is_same_v<X, T>, forward_t<X, Args...>>

Public Static Attributes

static constexpr bool is_traceable = false

## AutogradContext

struct AutogradContext

Context to save information during `forward` that can be accessed in `backward` in custom autograd operations (see `torch::autograd::Function` for details).

Public Functions

AutogradContext() = default

AutogradContext(const AutogradContext &other) = delete

AutogradContext &operator=(const AutogradContext &other) = delete

AutogradContext(AutogradContext &&other) = delete

AutogradContext &operator=(AutogradContext &&other) = delete

~AutogradContext() = default

AutogradContext(PackedArgs &packed_args)

void save_for_backward(variable_list to_save)

Saves the list of variables for a future call to `backward`.

This should be called at most once from inside of `forward`.

void mark_dirty(const variable_list &inputs)

Marks variables in the list as modified in an in-place operation.

This should be called at most once from inside of `forward` and all arguments should be inputs.

void mark_non_differentiable(const variable_list &outputs)

Marks outputs in the list as not requiring gradients.

This should be called at most once from inside of `forward` and all arguments should be outputs.

void set_materialize_grads(bool value)

variable_list get_saved_variables() const

Get the list of variables that were saved in `forward` using `save_for_backward()`.

Before returning them to the user, a check is made to ensure that they were not modified by any in-place operations.

const std::unordered_set<at::TensorImpl*> &get_and_bump_dirty() const

const std::unordered_set<at::TensorImpl*> &get_non_differentiable() const

bool needs_input_grad(size_t output_edge_index) const

Expose the Node's `task_should_compute_output` method to the cpp custom autograd Function as `needs_input_grad`.

bool needs_input_grad(std::initializer_list<IndexRange> idxs) const

Public Members

ska::flat_hash_map<std::string, at::IValue> saved_data

Can be used to save non-variable data for `backward`.

## Creating Custom Functions

To create a custom autograd function, inherit from `torch::autograd::Function`
and implement the static `forward` and `backward` methods:

**Example:**

```
class MyReLU : public torch::autograd::Function<MyReLU> {
 public:
 static torch::Tensor forward(
 torch::autograd::AutogradContext* ctx,
 torch::Tensor input) {
 ctx->save_for_backward({input});
 return input.clamp_min(0);
 }

 static torch::autograd::variable_list backward(
 torch::autograd::AutogradContext* ctx,
 torch::autograd::variable_list grad_outputs) {
 auto saved = ctx->get_saved_variables();
 auto input = saved[0];
 auto grad_output = grad_outputs[0];
 auto grad_input = grad_output * (input > 0).to(grad_output.dtype());
 return {grad_input};
 }
};

// Usage
auto output = MyReLU::apply(input);
```

## Custom Kernels and AutoDispatchBelowADInplaceOrView

For users implementing custom kernels who want to redispatch below `Autograd` dispatch
keys, use `at::AutoDispatchBelowADInplaceOrView` instead of `InferenceMode`:

```
class ROIAlignFunction : public torch::autograd::Function<ROIAlignFunction> {
 public:
 static torch::autograd::variable_list forward(
 torch::autograd::AutogradContext* ctx,
 const torch::autograd::Variable& input,
 const torch::autograd::Variable& rois,
 double spatial_scale,
 int64_t pooled_height,
 int64_t pooled_width,
 int64_t sampling_ratio,
 bool aligned) {
 ctx->saved_data["spatial_scale"] = spatial_scale;
 ctx->saved_data["pooled_height"] = pooled_height;
 ctx->saved_data["pooled_width"] = pooled_width;
 ctx->saved_data["sampling_ratio"] = sampling_ratio;
 ctx->saved_data["aligned"] = aligned;
 ctx->saved_data["input_shape"] = input.sizes();
 ctx->save_for_backward({rois});

 at::AutoDispatchBelowADInplaceOrView guard;
 auto result = roi_align(
 input, rois, spatial_scale, pooled_height,
 pooled_width, sampling_ratio, aligned);
 return {result};
 }
};
```

For customized inplace and view kernels, see the
[custom kernel tutorial](https://pytorch.org/tutorials/advanced/cpp_extension.html#backward-pass)
for more details.

---

# Gradient Computation

PyTorch provides functions for computing gradients of tensors with respect
to graph leaves.

## Gradient Functions

void torch::autograd::backward(const variable_list &tensors, const variable_list &grad_tensors = {}, std::optional<bool> retain_graph = std::nullopt, bool create_graph = false, const variable_list &inputs = {})

Computes the sum of gradients of given tensors with respect to graph leaves.

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 (`torch::Tensor()` is an acceptable value for
all tensors that don't need gradient tensors).

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

:param tensors: Tensors of which the derivative will be computed.
:param grad_tensors: The "vector" in the Jacobian-vector product, usually
gradients w.r.t. each element of corresponding tensors.
`torch::Tensor()` values can be specified for scalar Tensors or ones
that don't require grad. If a `torch::Tensor()` value would be
acceptable for all grad_tensors, then this argument is optional.
:param retain_graph: If `false`, the graph used to compute the grad will
be freed. Note that in nearly all cases setting this option to `true`
is not needed and often can be worked around in a much more efficient
way. Defaults to the value of `create_graph`.
:param create_graph: If `true`, graph of the derivative will be
constructed, allowing to compute higher order derivative products.
Defaults to `false`.
:param inputs: Inputs w.r.t. which the gradient will be accumulated into
`at::Tensor::grad`. All other Tensors will be ignored. If not
provided, the gradient is accumulated into all the leaf Tensors that
were used to compute `tensors`.

variable_list torch::autograd::grad(const variable_list &outputs, const variable_list &inputs, const variable_list &grad_outputs = {}, std::optional<bool> retain_graph = std::nullopt, bool create_graph = false, bool allow_unused = false)

Computes and returns the sum of gradients of outputs with respect to the inputs.

`grad_outputs` should be a sequence 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 `torch::Tensor()`).

Parameters:

- **outputs** - outputs of the differentiated function.
- **inputs** - Inputs w.r.t. which the gradient will be returned (and not accumulated into `at::Tensor::grad`).
- **grad_outputs** - The "vector" in the Jacobian-vector product. Usually gradients w.r.t. each output. `torch::Tensor()` values can be specified for scalar Tensors or ones that don't require grad. If a `torch::Tensor()` value would be acceptable for all grad_tensors, then this argument is optional. Default: `{}`.
- **retain_graph** - If `false`, the graph used to compute the grad will be freed. Note that in nearly all cases setting this option to `true` is not needed and often can be worked around in a much more efficient way. Defaults to the value of `create_graph`.
- **create_graph** - If `true`, graph of the derivative will be constructed, allowing to compute higher order derivative products. Default: `false`.
- **allow_unused** - If `false`, specifying inputs that were not used when computing outputs (and therefore their grad is always zero) is an error. Defaults to `false`.

**Example:**

```
#include <torch/torch.h>

auto x = torch::randn({2, 2}, torch::requires_grad());
auto y = x * x;
auto z = y.sum();

// Compute gradients
z.backward();
std::cout << x.grad() << std::endl;

// Or use grad() for specific outputs
auto grads = torch::autograd::grad({z}, {x});
```

## Tensor Gradient Methods

Tensors have built-in methods for gradient computation:

```
// Enable gradient tracking
auto x = torch::randn({2, 2}).requires_grad_(true);

// Check if gradient is required
bool needs_grad = x.requires_grad();

// Access the gradient after backward
auto grad = x.grad();

// Detach from computation graph
auto x_detached = x.detach();
```

---

# Autograd: Automatic Differentiation

PyTorch's autograd system provides automatic differentiation for all operations
on tensors. It records operations on tensors to build a computational graph,
then computes gradients automatically via backpropagation.

**When to use Autograd:**

- When training neural networks (gradients are computed automatically)
- When implementing custom backward passes for specialized operations
- When you need fine-grained control over gradient computation

**Basic usage:**

```
#include <torch/torch.h>

// Create tensor with gradient tracking
auto x = torch::randn({2, 2}, torch::requires_grad());
auto y = x * x;
auto z = y.sum();

// Compute gradients via backpropagation
z.backward();
std::cout << x.grad() << std::endl; // dz/dx = 2x

// Disable gradient tracking for inference
{
 torch::NoGradGuard no_grad;
 auto result = model->forward(input); // No gradients computed
}
```

## Header Files

- `torch/csrc/autograd/autograd.h` - High-level autograd API
- `torch/csrc/autograd/function.h` - Custom autograd functions
- `torch/csrc/autograd/grad_mode.h` - Gradient computation modes
- `torch/csrc/api/include/torch/autograd.h` - C++ Frontend autograd

## Autograd Categories

- [Gradient Computation](gradient.html)
- [Custom Autograd Functions](custom_functions.html)
- [Gradient Modes](modes.html)

---

# Gradient Modes

PyTorch provides RAII guards to control gradient computation behavior.

## NoGradGuard

class torch::NoGradGuard

RAII guard that disables gradient computation within its scope.

NoGradGuard()

Disables gradient computation.

~NoGradGuard()

Restores previous gradient mode.

**Example:**

```
{
 torch::NoGradGuard no_grad;
 // No gradients computed in this scope
 auto result = model->forward(input);
}
```

## InferenceMode

`c10::InferenceMode` is a RAII guard analogous to `NoGradMode` designed for use
when you are certain your operations will have no interactions with autograd
(e.g., model inference). Compared to `NoGradMode`, code run under this mode gets
better performance by disabling autograd-related work like view tracking and version
counter bumps. However, tensors created inside `InferenceMode` have more limitations
when interacting with the autograd system.

class c10::InferenceMode

RAII guard that enables inference mode for optimized inference.
This is more efficient than NoGradGuard for inference-only workloads.

explicit InferenceMode(bool enabled = true)

Enables or disables inference mode.

**Inference Tensors:**

`InferenceMode` can be enabled for a given block of code. Inside `InferenceMode`,
all newly allocated (non-view) tensors are marked as inference tensors. Inference tensors:

- Do not have a version counter, so an error will be raised if you try to read their version
(e.g., because you saved this tensor for backward).
- Are immutable outside `InferenceMode`. An error will be raised if you try to:

- Mutate their data outside InferenceMode.
- Mutate them to `requires_grad=True` outside InferenceMode.
- To work around this, make a clone outside `InferenceMode` to get a normal tensor before mutating.

A non-view tensor is an inference tensor if and only if it was allocated inside `InferenceMode`.
A view tensor is an inference tensor if and only if it is a view of an inference tensor.

**Performance Guarantees:**

Inside an `InferenceMode` block:

- Like `NoGradMode`, all operations do not record `grad_fn` even if their inputs have
`requires_grad=True`. This applies to both inference tensors and normal tensors.
- View operations on inference tensors do not perform view tracking. View and non-view
inference tensors are indistinguishable.
- Inplace operations on inference tensors are guaranteed not to do a version bump.

For more implementation details, see the [RFC-0011-InferenceMode](https://github.com/pytorch/rfcs/pull/17).

**Basic Example:**

```
{
 c10::InferenceMode guard;
 // Optimized inference without gradient tracking
 auto result = model->forward(input);
}
```

**Inference Workload Example:**

```
c10::InferenceMode guard;
model.load_jit(saved_model);
auto inputs = preprocess_tensors(data);
auto out = model.forward(inputs);
auto outputs = postprocess_tensors(out);
```

**Nested InferenceMode:**

Unlike some other guards, `InferenceMode` can be nested with different enabled/disabled states:

```
{
 c10::InferenceMode guard(true);
 // InferenceMode is on
 {
 c10::InferenceMode guard(false);
 // InferenceMode is off
 }
 // InferenceMode is on
}
// InferenceMode is off
```

## InferenceMode vs NoGradMode

`InferenceMode` is preferred over `NoGradMode` for pure inference workloads because
it provides better performance. Key differences:

- Both guards affect tensor execution to skip work not related to inference, but
`InferenceMode` also affects tensor creation while `NoGradMode` doesn't.
- Tensors created inside `InferenceMode` are marked as inference tensors with
certain limitations that apply after exiting `InferenceMode`.
- `InferenceMode` can be nested with enabled/disabled states.

## Migrating from AutoNonVariableTypeMode

The legacy `AutoNonVariableTypeMode` guard (now renamed to
`AutoDispatchBelowADInplaceOrView`) was commonly used for inference workloads
but is unsafe -- it can silently bypass safety checks and produce wrong results.

- **For inference-only workloads** (e.g. loading a pretrained JIT model and
running inference in C++ runtime), use `c10::InferenceMode` as a drop-in
replacement. It preserves the performance characteristics while providing
correctness guarantees.
- **For custom autograd kernels** that need to redispatch below the Autograd
dispatch key, use `AutoDispatchBelowADInplaceOrView` instead:

```
class ROIAlignFunction : public torch::autograd::Function<ROIAlignFunction> {
 public:
 static torch::autograd::variable_list forward(
 torch::autograd::AutogradContext* ctx,
 const torch::autograd::Variable& input,
 const torch::autograd::Variable& rois,
 double spatial_scale, int64_t pooled_height,
 int64_t pooled_width, int64_t sampling_ratio, bool aligned) {
 ctx->saved_data["spatial_scale"] = spatial_scale;
 ctx->save_for_backward({rois});
 at::AutoDispatchBelowADInplaceOrView guard;
 auto result = roi_align(input, rois, spatial_scale,
 pooled_height, pooled_width, sampling_ratio, aligned);
 return {result};
 }
};
```

---

# Device and DeviceType

PyTorch provides device abstractions for writing code that works across
CPU, CUDA, and other backends.

## Device

struct Device

Represents a compute device on which a tensor is located.

A device is uniquely identified by a type, which specifies the type of machine it is (e.g. CPU or CUDA GPU), and a device index or ordinal, which identifies the specific compute device when there is more than one of a certain type. The device index is optional, and in its defaulted state represents (abstractly) "the current device". Further, there are two constraints on the value of the device index, if one is explicitly stored:

1. A negative index represents the current device, a non-negative index represents a specific, concrete device,
2. When the device type is CPU, the device index must be zero.

Public Types

using Type = DeviceType

Public Functions

inline Device(DeviceType type, DeviceIndex index = -1)

Constructs a new `Device` from a `DeviceType` and an optional device index.

Device(const std::string &device_string)

Constructs a `Device` from a string description, for convenience.

The string supplied must follow the following schema: `(cpu|cuda)[:<device-index>]` where `cpu` or `cuda` specifies the device type, and `:<device-index>` optionally specifies a device index.

inline bool operator==(const Device &other) const noexcept

Returns true if the type and index of this `Device` matches that of `other`.

inline bool operator!=(const Device &other) const noexcept

Returns true if the type or index of this `Device` differs from that of `other`.

inline void set_index(DeviceIndex index)

Sets the device index.

inline DeviceType type() const noexcept

Returns the type of device this is.

inline DeviceIndex index() const noexcept

Returns the optional index.

inline bool has_index() const noexcept

Returns true if the device has a non-default index.

inline bool is_cuda() const noexcept

Return true if the device is of CUDA type.

inline bool is_privateuseone() const noexcept

Return true if the device is of PrivateUse1 type.

inline bool is_mps() const noexcept

Return true if the device is of MPS type.

inline bool is_hip() const noexcept

Return true if the device is of HIP type.

inline bool is_ve() const noexcept

Return true if the device is of VE type.

inline bool is_xpu() const noexcept

Return true if the device is of XPU type.

inline bool is_ipu() const noexcept

Return true if the device is of IPU type.

inline bool is_xla() const noexcept

Return true if the device is of XLA type.

inline bool is_mtia() const noexcept

Return true if the device is of MTIA type.

inline bool is_hpu() const noexcept

Return true if the device is of HPU type.

inline bool is_lazy() const noexcept

Return true if the device is of Lazy type.

inline bool is_vulkan() const noexcept

Return true if the device is of Vulkan type.

inline bool is_metal() const noexcept

Return true if the device is of Metal type.

inline bool is_maia() const noexcept

Return true if the device is of MAIA type.

inline bool is_meta() const noexcept

Return true if the device is of META type.

inline bool is_cpu() const noexcept

Return true if the device is of CPU type.

inline bool supports_as_strided() const noexcept

Return true if the device supports arbitrary strides.

std::string str() const

Same string as returned from operator<<.

**Example:**

```
c10::Device cpu_device(c10::kCPU);
c10::Device cuda_device(c10::kCUDA, 0); // CUDA device 0

if (cuda_device.is_cuda()) {
 std::cout << "Using CUDA device " << cuda_device.index() << std::endl;
}
```

## DeviceType

enum class c10::DeviceType

Enumeration of supported device types.

enumerator CPU = 0

CPU device.

enumerator CUDA = 1

NVIDIA CUDA GPU.

enumerator HIP = 6

AMD HIP GPU.

enumerator XLA = 9

XLA / TPU.

enumerator Vulkan = 10

Vulkan GPU.

enumerator Metal = 11

Apple Metal GPU.

enumerator XPU = 12

Intel XPU GPU.

enumerator MPS = 13

Apple Metal Performance Shaders.

enumerator Meta = 14

Meta tensors (shape only, no data).

enumerator HPU = 15

Habana HPU.

enumerator Lazy = 17

Lazy tensors.

enumerator IPU = 18

Graphcore IPU.

enumerator MTIA = 19

Meta training and inference accelerator.

enumerator PrivateUse1 = 20

Custom backend registered via `c10::register_privateuse1_backend()`.

Convenience constants:

- `c10::kCPU`, `c10::kCUDA`, `c10::kHIP`
- `c10::kXLA`, `c10::kVulkan`, `c10::kMetal`
- `c10::kXPU`, `c10::kMPS`, `c10::kMeta`
- `c10::kHPU`, `c10::kLazy`, `c10::kIPU`, `c10::kMTIA`
- `c10::kPrivateUse1`

---

# Device Guards

C10 provides device-agnostic RAII guards for managing the current device
context. These guards work across all backends (CUDA, XPU, etc.) and
automatically restore the previous device when they go out of scope.

For backend-specific guards, see [CUDA Guards](../cuda/guards.html) and [XPU Support](../xpu/index.html).

## DeviceGuard

class DeviceGuard

RAII guard that sets a certain default device in its constructor, and changes it back to the device that was originally active upon destruction.

The device is always reset to the one that was active at the time of construction of the guard. Even if you `set_device` after construction, the destructor will still reset the device to the one that was active at construction time.

This device guard does NOT have an uninitialized state; it is guaranteed to reset a device on exit. If you are in a situation where you *might* want to setup a guard (i.e., are looking for the moral equivalent of std::optional<DeviceGuard>), see OptionalDeviceGuard.

Public Functions

explicit DeviceGuard() = delete

No default constructor; see Note [Omitted default constructor from RAII].

inline explicit DeviceGuard([Device](device.html#_CPPv4N3c106DeviceE) device)

Set the current device to the passed [Device](device.html#PyTorchstructc10_1_1_device).

inline explicit DeviceGuard([Device](device.html#_CPPv4N3c106DeviceE) device, const [impl](../aten/tensor.html#_CPPv4N3c1011DeviceGuard11DeviceGuardE6DevicePKN4impl24DeviceGuardImplInterfaceE)::DeviceGuardImplInterface *impl)

This constructor is for testing only.

~DeviceGuard() = default

DeviceGuard(const [DeviceGuard](../aten/tensor.html#_CPPv4N3c1011DeviceGuard11DeviceGuardERK11DeviceGuard)&) = delete

Copy is disallowed.

[DeviceGuard](../aten/tensor.html#_CPPv4N3c1011DeviceGuardE) &operator=(const [DeviceGuard](../aten/tensor.html#_CPPv4N3c1011DeviceGuardE)&) = delete

DeviceGuard([DeviceGuard](../aten/tensor.html#_CPPv4N3c1011DeviceGuard11DeviceGuardERR11DeviceGuard) &&other) = delete

Move is disallowed, as DeviceGuard does not have an uninitialized state, which is required for moves on types with nontrivial destructors.

[DeviceGuard](../aten/tensor.html#_CPPv4N3c1011DeviceGuardE) &operator=([DeviceGuard](../aten/tensor.html#_CPPv4N3c1011DeviceGuardE) &&other) = delete

inline void reset_device(at::Device device)

Sets the device to the given one.

The specified device must be consistent with the device type originally specified during guard construction.

TODO: The consistency check here is inconsistent with StreamGuard's behavior with set_stream, where a stream on a different device than the original one isn't an error; we just reset the stream and then switch devices.

inline void reset_device(at::Device device, const [impl](../aten/tensor.html#_CPPv4N3c1011DeviceGuard12reset_deviceEN2at6DeviceEPKN4impl24DeviceGuardImplInterfaceE)::DeviceGuardImplInterface *impl)

This method is for testing only.

inline void set_index(DeviceIndex index)

Sets the device index to the given one.

The device type is inferred from the original device type the guard was constructed with.

inline [Device](device.html#_CPPv4N3c106DeviceE) original_device() const

Returns the device that was set at the time the guard was constructed.

inline [Device](device.html#_CPPv4N3c106DeviceE) current_device() const

Returns the most recent device that was set using this device guard, either from construction, or via set_device.

**Example:**

```
#include <c10/core/DeviceGuard.h>

{
 c10::DeviceGuard guard(c10::Device(c10::kCUDA, 1));
 // All operations here run on CUDA device 1
}
// Previous device is restored
```

## OptionalDeviceGuard

class OptionalDeviceGuard

A OptionalDeviceGuard is an RAII class that sets a device to some value on initialization, and resets the device to its original value on destruction.

Morally, a OptionalDeviceGuard is equivalent to std::optional<DeviceGuard>, but with extra constructors and methods as appropriate.

Besides its obvious use (optionally applying a DeviceGuard), OptionalDeviceGuard is often also used for the following idiom:

OptionalDeviceGuard g; for (const auto& t : tensors) { g.set_device(t.device()); do_something_with(t); }

This usage is marginally more efficient than constructing a DeviceGuard every iteration of the for loop, as it avoids an unnecessary device reset.

Unlike DeviceGuard, a OptionalDeviceGuard may be uninitialized. This occurs when you use the nullary constructor, or pass a nullopt to the constructor. Uninitialized OptionalDeviceGuards do *nothing*; they do not know what the original device was and they do not reset on destruction. This is why original_device() and current_device() return std::optional<Device> rather than [Device](device.html#PyTorchstructc10_1_1_device) (as they do in DeviceGuard), and also is why we didn't just provide OptionalDeviceGuard by default and hide DeviceGuard from users.

The semantics of an OptionalDeviceGuard are exactly explained by thinking of it as an std::optional<DeviceGuard>. In particular, an initialized OptionalDeviceGuard doesn't restore device to its value at construction; it restores device to its value *at initialization*. So if you have the program:

```
setDevice(1);
OptionalDeviceGuard g;
setDevice(2);
g.reset_device(Device(DeviceType::CUDA, 3)); // initializes!
```

 On destruction, g will reset device to 2, rather than 1.

An uninitialized OptionalDeviceGuard is distinct from a (initialized) DeviceGuard whose original_device_ and current_device_ match, since the DeviceGuard will still reset the device to original_device_.

Public Functions

explicit OptionalDeviceGuard() = default

Create an uninitialized guard. Set the guard later using reset_device.

inline explicit OptionalDeviceGuard([Device](device.html#_CPPv4N3c106DeviceE) device)

Initialize the guard, setting the current device to the passed [Device](device.html#PyTorchstructc10_1_1_device).

inline explicit OptionalDeviceGuard(std::optional<[Device](device.html#_CPPv4N3c106DeviceE)> device)

Initialize the guard if a [Device](device.html#PyTorchstructc10_1_1_device) is passed; otherwise leave the guard uninitialized.

inline explicit OptionalDeviceGuard([Device](device.html#_CPPv4N3c106DeviceE) device, const impl::DeviceGuardImplInterface *impl)

Constructor for testing only.

~OptionalDeviceGuard() = default

OptionalDeviceGuard(const OptionalDeviceGuard&) = delete

Copy is disallowed.

OptionalDeviceGuard &operator=(const OptionalDeviceGuard&) = delete

OptionalDeviceGuard(OptionalDeviceGuard &&other) = delete

Move is disallowed See Note [Explicit initialization of optional fields] and // Note [Move construction for RAII guards is tricky] for rationale.

OptionalDeviceGuard &operator=(OptionalDeviceGuard &&other) = delete

inline void reset_device(at::Device device)

Sets the device to the given one.

The specified device must be consistent with the device type originally specified during guard construction.

inline void reset_device(at::Device device, const impl::DeviceGuardImplInterface *impl)

For testing only.

inline std::optional<[Device](device.html#_CPPv4N3c106DeviceE)> original_device() const

Returns the device that was set at the time the guard was constructed.

inline std::optional<[Device](device.html#_CPPv4N3c106DeviceE)> current_device() const

Returns the most recent device that was set using this device guard, either from construction, or via reset_device.

**Example:**

```
#include <c10/core/DeviceGuard.h>

c10::OptionalDeviceGuard guard;
if (use_gpu) {
 guard.reset_device(c10::Device(c10::kCUDA, 0));
}
// Guard only restores device if it was set
```

---

# C10: Core Utilities

C10 (Caffe2 + ATen = C10) is the core library that provides fundamental
utilities and data types used throughout PyTorch. It contains device
abstractions, memory management utilities, and common data structures.

**When to use C10:**

- When working with device-agnostic code (CPU, CUDA, XPU, etc.)
- When you need efficient array views without copying data
- When handling optional values or type-erased containers
- When writing code that needs to work across different PyTorch backends

**Basic usage:**

```
#include <c10/core/Device.h>
#include <c10/util/ArrayRef.h>

// Device abstraction
c10::Device device(c10::kCUDA, 0);
if (device.is_cuda()) {
 std::cout << "Using CUDA device " << device.index() << std::endl;
}

// Efficient array views (no copy)
std::vector<int64_t> sizes = {3, 4, 5};
c10::ArrayRef<int64_t> sizes_ref(sizes);

// Optional values
c10::optional<int64_t> maybe_dim = 2;
int64_t dim = maybe_dim.value_or(-1);
```

## Header Files

- `c10/core/Device.h` - Device abstraction
- `c10/core/DeviceType.h` - Device type enumeration
- `c10/util/ArrayRef.h` - Non-owning array reference
- `c10/util/OptionalArrayRef.h` - Optional array reference
- `c10/util/Optional.h` - Optional value wrapper
- `c10/util/Half.h` - Half-precision float
- `c10/util/Exception.h` - Error checking macros (`TORCH_CHECK`, `TORCH_INTERNAL_ASSERT`, etc.)
- `c10/cuda/CUDAGuard.h` - CUDA device guards (see [CUDA Support](../cuda/index.html))
- `c10/cuda/CUDAStream.h` - CUDA stream management (see [CUDA Support](../cuda/index.html))
- `c10/xpu/XPUStream.h` - Intel XPU stream management
- `ATen/core/ivalue.h` - IValue for TorchScript interop

## C10 Categories

- [Device and DeviceType](device.html)
- [Device Guards](guards.html)
- [Streams](streams.html)
- [Core Types](types.html)
- [Utilities](utilities.html)

---

# Streams

`c10::Stream` is the device-agnostic base stream class. It provides a
common interface for working with streams across different backends
(CUDA, XPU, etc.).

For backend-specific stream APIs, see [CUDA Streams](../cuda/streams.html) and [XPU Support](../xpu/index.html).

## Stream

class Stream

A stream is a software mechanism used to synchronize launched kernels without requiring explicit synchronizations between kernels.

The basic model is that every kernel launch is associated with a stream: every kernel on the same stream is implicitly synchronized so that if I launch kernels A and B on the same stream, A is guaranteed to finish before B launches. If I want B to run concurrently with A, I must schedule it on a different stream.

The Stream class is a backend agnostic value class representing a stream which I may schedule a kernel on. Every stream is associated with a device, which is recorded in stream, which is used to avoid confusion about which device a stream refers to.

Streams are explicitly thread-safe, in the sense that it is OK to pass a Stream from one thread to another, and kernels queued from two different threads will still get serialized appropriately. (Of course, the time when the kernels get queued is undetermined unless you synchronize host side ;)

Stream does NOT have a default constructor. Streams are for expert users; if you want to use Streams, we're going to assume you know how to deal with C++ template error messages if you try to resize() a vector of Streams.

Known instances of streams in backends:

- cudaStream_t (CUDA)
- hipStream_t (HIP)
- cl_command_queue (OpenCL) (NB: Caffe2's existing OpenCL integration does NOT support command queues.)

Because this class is device agnostic, it cannot provide backend-specific functionality (e.g., get the cudaStream_t of a CUDA stream.) There are wrapper classes which provide this functionality, e.g., CUDAStream.

Public Types

enum Unsafe

*Values:*

enumerator UNSAFE

enum Default

*Values:*

enumerator DEFAULT

Public Functions

inline explicit Stream(Unsafe, [Device](device.html#_CPPv4N3c106DeviceE) device, StreamId id)

Unsafely construct a stream from a [Device](device.html#PyTorchstructc10_1_1_device) and a StreamId.

In general, only specific implementations of streams for a backend should manufacture Stream directly in this way; other users should use the provided APIs to get a stream. In particular, we don't require backends to give any guarantees about non-zero StreamIds; they are welcome to allocate in whatever way they like.

inline explicit Stream(Default, [Device](device.html#_CPPv4N3c106DeviceE) device)

Construct the default stream of a [Device](device.html#PyTorchstructc10_1_1_device).

The default stream is NOT the same as the current stream; default stream is a fixed stream that never changes, whereas the current stream may be changed by StreamGuard.

inline bool operator==(const Stream &other) const noexcept

inline bool operator!=(const Stream &other) const noexcept

inline [Device](device.html#_CPPv4N3c106DeviceE) device() const noexcept

inline [DeviceType](device.html#_CPPv4N3c1010DeviceTypeE) device_type() const noexcept

inline DeviceIndex device_index() const noexcept

inline StreamId id() const noexcept

void *native_handle() const

template<typename T>
inline void wait(const T &event) const

bool query() const

void synchronize() const

bool is_capturing() const

inline uint64_t hash() const noexcept

inline struct StreamData3 pack3() const

Public Static Functions

static inline Stream unpack3(StreamId stream_id, DeviceIndex device_index, [DeviceType](device.html#_CPPv4N3c1010DeviceTypeE) device_type)

**Example:**

```
#include <c10/core/Stream.h>

// Streams are typically obtained from backend-specific APIs
auto cuda_stream = c10::cuda::getCurrentCUDAStream();

// c10::Stream provides the common interface
c10::Device device = cuda_stream.device();
c10::DeviceType type = cuda_stream.device_type();
```

---

# Core Types

C10 provides fundamental types used throughout PyTorch.

## ArrayRef

template<typename T>
class ArrayRef : public HeaderOnlyArrayRef<T>

ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory), i.e.

a start pointer and a length. It allows various APIs to take consecutive elements easily and conveniently.

This class does not own the underlying data, it is expected to be used in situations where the data resides in some other buffer, whose lifetime extends past that of the ArrayRef. For this reason, it is not in general safe to store an ArrayRef.

This is intended to be trivially copyable, so it should be passed by value.

NOTE: We have refactored out the headeronly parts of the ArrayRef struct into HeaderOnlyArrayRef. As adding `virtual` would change the performance of the underlying constexpr calls, we rely on apparent-type dispatch for inheritance. This should be fine because their memory format is the same, and it is never incorrect for ArrayRef to call HeaderOnlyArrayRef methods. However, you should prefer to use ArrayRef when possible, because its use of TORCH_CHECK will lead to better user-facing error messages.

Constructors, all inherited from HeaderOnlyArrayRef except for

SmallVector.

As inherited constructors won't work with class template argument deduction (CTAD) until C++23, we add deduction guides after the class definition to enable CTAD.

template<typename U>
inline ArrayRef(const SmallVectorTemplateCommon<T, U> &Vec)

Construct an ArrayRef from a SmallVector.

This is templated in order to avoid instantiating SmallVectorTemplateCommon<T> whenever we copy-construct an ArrayRef. NOTE: this is the only constructor that is not inherited from HeaderOnlyArrayRef.

Simple Operations, mostly inherited from HeaderOnlyArrayRef

inline constexpr const T &front() const

front - Get the first element.

We deviate from HeaderOnlyArrayRef by using TORCH_CHECK instead of STD_TORCH_CHECK

inline constexpr const T &back() const

back - Get the last element.

We deviate from HeaderOnlyArrayRef by using TORCH_CHECK instead of STD_TORCH_CHECK

inline constexpr ArrayRef<T> slice(size_t N, size_t M) const

slice(n, m) - Take M elements of the array starting at element N We deviate from HeaderOnlyArrayRef by using TORCH_CHECK instead of STD_TORCH_CHECK

inline constexpr ArrayRef<T> slice(size_t N) const

slice(n) - Chop off the first N elements of the array.

We deviate from HeaderOnlyArrayRef by using TORCH_CHECK instead of STD_TORCH_CHECK

Operator Overloads

inline constexpr const T &at(size_t Index) const

Vector compatibility We deviate from HeaderOnlyArrayRef by using TORCH_CHECK instead of STD_TORCH_CHECK.

template<typename U>
std::enable_if_t<std::is_same_v<U, T>, ArrayRef<T>> &operator=(U &&Temporary) = delete

Disallow accidental assignment from a temporary.

The declaration here is extra complicated so that "arrayRef = {}" continues to select the move assignment operator.

template<typename U>
std::enable_if_t<std::is_same_v<U, T>, ArrayRef<T>> &operator=(std::initializer_list<U>) = delete

Disallow accidental assignment from a temporary.

The declaration here is extra complicated so that "arrayRef = {}" continues to select the move assignment operator.

**Example:**

```
std::vector<int64_t> sizes = {3, 4, 5};
c10::ArrayRef<int64_t> sizes_ref(sizes);

// Can also use initializer list
auto tensor = at::zeros({3, 4, 5}); // implicitly converts
```

## OptionalArrayRef

template<typename T>
class OptionalArrayRef

Public Functions

constexpr OptionalArrayRef() noexcept = default

inline constexpr OptionalArrayRef(std::nullopt_t) noexcept

OptionalArrayRef(const OptionalArrayRef &other) = default

OptionalArrayRef(OptionalArrayRef &&other) noexcept = default

inline constexpr OptionalArrayRef(const std::optional<ArrayRef<T>> &other) noexcept

inline constexpr OptionalArrayRef(std::optional<ArrayRef<T>> &&other) noexcept

inline constexpr OptionalArrayRef(const T &value) noexcept

template<typename U = ArrayRef<T>, std::enable_if_t<!std::is_same_v<std::decay_t<U>, OptionalArrayRef> && !std::is_same_v<std::decay_t<U>, std::in_place_t> && std::is_constructible_v<ArrayRef<T>, U&&> && std::is_convertible_v<U&&, ArrayRef<T>> && !std::is_convertible_v<U&&, T>, bool> = false>
inline constexpr OptionalArrayRef(U &&value) noexcept(std::is_nothrow_constructible_v<ArrayRef<T>, U&&>)

template<typename U = ArrayRef<T>, std::enable_if_t<!std::is_same_v<std::decay_t<U>, OptionalArrayRef> && !std::is_same_v<std::decay_t<U>, std::in_place_t> && std::is_constructible_v<ArrayRef<T>, U&&> && !std::is_convertible_v<U&&, ArrayRef<T>>, bool> = false>
inline explicit constexpr OptionalArrayRef(U &&value) noexcept(std::is_nothrow_constructible_v<ArrayRef<T>, U&&>)

template<typename ...Args>
inline explicit constexpr OptionalArrayRef(std::in_place_t ip, Args&&... args) noexcept

template<typename U, typename ...Args>
inline explicit constexpr OptionalArrayRef(std::in_place_t ip, std::initializer_list<U> il, Args&&... args)

inline constexpr OptionalArrayRef(const std::initializer_list<T> &Vec)

~OptionalArrayRef() = default

inline constexpr OptionalArrayRef &operator=(std::nullopt_t) noexcept

OptionalArrayRef &operator=(const OptionalArrayRef &other) = default

OptionalArrayRef &operator=(OptionalArrayRef &&other) noexcept = default

inline constexpr OptionalArrayRef &operator=(const std::optional<ArrayRef<T>> &other) noexcept

inline constexpr OptionalArrayRef &operator=(std::optional<ArrayRef<T>> &&other) noexcept

template<typename U = ArrayRef<T>, typename = std::enable_if_t<!std::is_same_v<std::decay_t<U>, OptionalArrayRef> && std::is_constructible_v<ArrayRef<T>, U&&> && std::is_assignable_v<ArrayRef<T>&, U&&>>>
inline constexpr OptionalArrayRef &operator=(U &&value) noexcept(std::is_nothrow_constructible_v<ArrayRef<T>, U&&> && std::is_nothrow_assignable_v<ArrayRef<T>&, U&&>)

inline constexpr ArrayRef<T> *operator->() noexcept

inline constexpr const ArrayRef<T> *operator->() const noexcept

inline constexpr ArrayRef<T> &operator*() & noexcept

inline constexpr const ArrayRef<T> &operator*() const & noexcept

inline constexpr ArrayRef<T> &&operator*() && noexcept

inline constexpr const ArrayRef<T> &&operator*() const && noexcept

inline explicit constexpr operator bool() const noexcept

inline constexpr bool has_value() const noexcept

inline constexpr ArrayRef<T> &value() &

inline constexpr const ArrayRef<T> &value() const &

inline constexpr ArrayRef<T> &&value() &&

inline constexpr const ArrayRef<T> &&value() const &&

template<typename U>
inline constexpr std::enable_if_t<std::is_convertible_v<U&&, ArrayRef<T>>, ArrayRef<T>> value_or(U &&default_value) const &

template<typename U>
inline constexpr std::enable_if_t<std::is_convertible_v<U&&, ArrayRef<T>>, ArrayRef<T>> value_or(U &&default_value) &&

inline constexpr void swap(OptionalArrayRef &other) noexcept

inline constexpr void reset() noexcept

template<typename ...Args>
inline constexpr std::enable_if_t<std::is_constructible_v<ArrayRef<T>, Args&&...>, ArrayRef<T>&> emplace(Args&&... args) noexcept(std::is_nothrow_constructible_v<ArrayRef<T>, Args&&...>)

template<typename U, typename ...Args>
inline constexpr ArrayRef<T> &emplace(std::initializer_list<U> il, Args&&... args) noexcept

Friends

inline friend bool operator==(OptionalArrayRef a1, ArrayRef<T> other)

**Example:**

```
void my_function(c10::OptionalArrayRef<int64_t> sizes = c10::nullopt) {
 if (sizes.has_value()) {
 for (auto s : sizes.value()) {
 // process sizes
 }
 }
}
```

## Optional

class c10::optional

A wrapper type that may or may not contain a value.
Similar to `std::optional`.

bool has_value() const

Returns true if a value is present.

T &value()

Returns the contained value. Throws if empty.

T value_or(T default_value) const

Returns the value if present, otherwise returns the default.

**Example:**

```
c10::optional<int64_t> maybe_dim = c10::nullopt;

if (maybe_dim.has_value()) {
 std::cout << "Dim: " << maybe_dim.value() << std::endl;
}

int64_t dim = maybe_dim.value_or(-1); // Returns -1 if empty
```

## Half

class c10::Half

16-bit floating point type (IEEE 754 half-precision).

Half(float value)

Construct from a float.

operator float() const

Convert to float.

**Example:**

```
c10::Half h = 3.14f;
float f = static_cast<float>(h);
```

## Containers

C10 provides container types that store `IValue` elements internally. These
are pointer types: copies share the same underlying storage.

### Dict

An ordered hash map from `Key` to `Value`. Valid key types are `int64_t`,
`double`, `bool`, `std::string`, and `at::Tensor`.

template<class Key, class Value>
class Dict

**Example:**

```
#include <ATen/core/Dict.h>

c10::Dict<std::string, at::Tensor> named_tensors;
named_tensors.insert("weight", torch::randn({3, 3}));
named_tensors.insert("bias", torch::zeros({3}));

if (named_tensors.contains("weight")) {
 at::Tensor w = named_tensors.at("weight");
}

for (const auto& entry : named_tensors) {
 std::cout << entry.key() << ": " << entry.value().sizes() << std::endl;
}
```

### List

A type-safe list container backed by `IValue` elements.

template<class T>
class List

**Example:**

```
#include <ATen/core/List.h>

c10::List<at::Tensor> tensor_list;
tensor_list.push_back(torch::randn({2, 3}));
tensor_list.push_back(torch::zeros({2, 3}));

at::Tensor first = tensor_list.get(0);
std::cout << "List size: " << tensor_list.size() << std::endl;

c10::List<int64_t> int_list;
int_list.push_back(1);
int_list.push_back(2);
int_list.push_back(3);
```

### IListRef

`c10::IListRef<T>` is a lightweight reference type that provides a unified
interface over different list-like types (`List<T>`, `ArrayRef<T>`,
`std::vector<T>`). It avoids copying when passing list arguments to operators.

template<class T>
class IListRef

**Example:**

```
#include <ATen/core/IListRef.h>

// IListRef can wrap different underlying types
std::vector<at::Tensor> vec = {torch::randn({2}), torch::randn({3})};
c10::IListRef<at::Tensor> ref(vec);

for (const auto& t : ref) {
 std::cout << t.sizes() << std::endl;
}
```

## IValue

`c10::IValue` (Interpreter Value) is a type-erased container used extensively
for storing values of different types. It can hold tensors,
scalars, lists, dictionaries, and other types.

Note

The full API documentation for IValue is complex due to its many type
conversion methods. See the header file `ATen/core/ivalue.h` for complete
details.

**Common methods:**

- `isTensor()` / `toTensor()` - Check if tensor / convert to tensor
- `isInt()` / `toInt()` - Check if int / convert to int
- `isDouble()` / `toDouble()` - Check if double / convert to double
- `isBool()` / `toBool()` - Check if bool / convert to bool
- `isString()` / `toString()` - Check if string / convert to string
- `isList()` / `toList()` - Check if list / convert to list
- `isGenericDict()` / `toGenericDict()` - Check if dict / convert to dict
- `isTuple()` / `toTuple()` - Check if tuple / convert to tuple
- `isNone()` - Check if None/null

**Example:**

```
c10::IValue val = at::ones({2, 2});

if (val.isTensor()) {
 at::Tensor t = val.toTensor();
}
```

---

# Utilities

C10 provides utility classes for memory management and other common patterns.

## MaybeOwned

`MaybeOwned<Tensor>` is a C++ smart pointer class that dynamically
encodes whether a Tensor is *owned* or *borrowed*. It is used in
certain performance-sensitive situations to avoid unnecessarily
incrementing a Tensor's reference count (at a small cost in
overhead from the extra indirection).

Warning

MaybeOwned must be used with **extreme** care. Claims of (non-)ownership
are not statically checked, and mistakes can cause reference undercounting
and use-after-free crashes.

Due to this lack of safety net, we discourage the use of MaybeOwned
outside code paths that are known to be highly performance sensitive.
However, if you encounter pre-existing uses of MaybeOwned in code that
you want to modify, it's critical to understand how to use it correctly.

**Use Case:**

The primary use case for `MaybeOwned<Tensor>` is a function or method that
dynamically chooses between returning one of its arguments (typically
from a passthrough or "no-op" code path) and returning a freshly constructed
Tensor. Such a function would return a `MaybeOwned<Tensor>` in both cases:
the former in a "borrowed" state via `MaybeOwned<Tensor>::borrowed()`,
and the latter in an "owned" state via `MaybeOwned<Tensor>::owned()`.

**Example - expect_contiguous:**

The canonical example is `Tensor`'s `expect_contiguous` method, which shortcuts
and returns a borrowed self-reference when already contiguous:

```
inline c10::MaybeOwned<Tensor> Tensor::expect_contiguous(
 MemoryFormat memory_format) const & {
 if (is_contiguous(memory_format)) {
 return c10::MaybeOwned<Tensor>::borrowed(*this);
 } else {
 return c10::MaybeOwned<Tensor>::owned(
 __dispatch_contiguous(memory_format));
 }
}
```

Using the vocabulary of lifetimes, the essential safety requirement for borrowing
is that a borrowed Tensor must outlive any borrowing references to it. In the example
above, we can safely borrow `*this`, but the Tensor returned by
`__dispatch_contiguous()` is freshly created, and borrowing a reference would
effectively leave it ownerless.

**Rules of Thumb:**

- When in doubt, don't use `MaybeOwned<Tensor>` at all - in particular, prefer
avoiding using it in code that doesn't use it already. New usage should only be
introduced when critical (and demonstrable) performance gains result.
- When modifying or calling code that already uses `MaybeOwned<Tensor>`, remember
that it's always safe to produce a `MaybeOwned<Tensor>` from a Tensor in hand
via a call to `MaybeOwned<Tensor>::owned()`. This may result in an unnecessary
reference count, but never in misbehavior - so it's always the safer bet, unless
the lifetime of the Tensor you're looking to wrap is crystal clear.

More details and implementation code can be found at
[MaybeOwned.h](https://github.com/pytorch/pytorch/blob/main/c10/util/MaybeOwned.h) and
[TensorBody.h](https://github.com/pytorch/pytorch/blob/main/aten/src/ATen/templates/TensorBody.h).

## Error Handling and Assertions

PyTorch provides macros for error checking and assertions that produce
informative error messages with source location. These are defined in
`c10/util/Exception.h`.

### TORCH_CHECK

The primary macro for validating user input and runtime conditions. On failure,
raises `c10::Error` (which becomes `RuntimeError` in Python).

```
#include <c10/util/Exception.h>

// Basic check
TORCH_CHECK(tensor.dim() == 2, "Expected 2D tensor, got ", tensor.dim(), "D");

// Without message (default message generated)
TORCH_CHECK(x >= 0);
```

Typed variants raise specific Python exception types:

- `TORCH_CHECK_INDEX(cond, ...)` -- raises `IndexError`
- `TORCH_CHECK_VALUE(cond, ...)` -- raises `ValueError`
- `TORCH_CHECK_TYPE(cond, ...)` -- raises `TypeError`
- `TORCH_CHECK_LINALG(cond, ...)` -- raises `LinAlgError`
- `TORCH_CHECK_NOT_IMPLEMENTED(cond, ...)` -- raises `NotImplementedError`

### TORCH_INTERNAL_ASSERT

For internal invariants that should always hold (i.e., failures indicate a bug
in PyTorch, not user error). Produces a message asking users to report the bug.

```
TORCH_INTERNAL_ASSERT(googol > 0);
TORCH_INTERNAL_ASSERT(googol > 0, "googol was ", googol);
```

Note

Use `TORCH_CHECK` for conditions that can fail due to user input.
Use `TORCH_INTERNAL_ASSERT` only for conditions that indicate a PyTorch bug.
`TORCH_INTERNAL_ASSERT_DEBUG_ONLY` is the debug-build-only variant for
hot paths.

### TORCH_WARN

Issues a warning (not an error) to the user.

```
TORCH_WARN("This operation is slow for sparse tensors");
TORCH_WARN_ONCE("This warning appears only once");
```

### c10::Error

The base exception class for PyTorch C++ errors. Provides source location
and optional backtrace.

```
try {
 auto result = some_operation();
} catch (const c10::Error& e) {
 std::cerr << e.what() << std::endl;
 // Or without backtrace:
 std::cerr << e.what_without_backtrace() << std::endl;
}
```

Specialized subclasses: `c10::IndexError`, `c10::ValueError`,
`c10::TypeError`, `c10::NotImplementedError`, `c10::LinAlgError`,
`c10::OutOfMemoryError`.

---

# CUDA Guards

CUDA guards are RAII wrappers that set a CUDA device or stream as the current
context and automatically restore the previous context when the guard goes
out of scope.

## CUDAGuard

struct CUDAGuard

A variant of [DeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_device_guard) that is specialized for CUDA.

It accepts integer indices (interpreting them as CUDA devices) and is a little more efficient than [DeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_device_guard) (it compiles to straight line cudaSetDevice/cudaGetDevice calls); however, it can only be used from code that links against CUDA directly.

Public Functions

explicit CUDAGuard() = delete

No default constructor; see Note [Omitted default constructor from RAII].

inline explicit CUDAGuard(DeviceIndex device_index)

Set the current CUDA device to the passed device index.

inline explicit CUDAGuard([Device](../c10/device.html#_CPPv4N3c106DeviceE) device)

Sets the current CUDA device to the passed device.

Errors if the passed device is not a CUDA device.

CUDAGuard(const CUDAGuard&) = delete

CUDAGuard &operator=(const CUDAGuard&) = delete

CUDAGuard(CUDAGuard &&other) = delete

CUDAGuard &operator=(CUDAGuard &&other) = delete

~CUDAGuard() = default

inline void set_device([Device](../c10/device.html#_CPPv4N3c106DeviceE) device)

Sets the CUDA device to the given device.

Errors if the given device is not a CUDA device.

inline void reset_device([Device](../c10/device.html#_CPPv4N3c106DeviceE) device)

Sets the CUDA device to the given device.

Errors if the given device is not a CUDA device. (This method is provided for uniformity with [DeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_device_guard)).

inline void set_index(DeviceIndex device_index)

Sets the CUDA device to the given device index.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) original_device() const

Returns the device that was set upon construction of the guard.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) current_device() const

Returns the last device that was set via `set_device`, if any, otherwise the device passed during construction.

**Example:**

```
#include <c10/cuda/CUDAGuard.h>

{
 c10::cuda::CUDAGuard guard(1); // Switch to device 1
 // All CUDA operations here run on device 1
 auto tensor = torch::zeros({2, 2}, torch::device(torch::kCUDA));
}
// Previous device is restored
```

## CUDAStreamGuard

struct CUDAStreamGuard

A variant of StreamGuard that is specialized for CUDA.

See CUDAGuard for when you can use this.

Public Functions

explicit CUDAStreamGuard() = delete

No default constructor, see Note [Omitted default constructor from RAII].

inline explicit CUDAStreamGuard([Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Set the current CUDA device to the device associated with the passed stream, and set the current CUDA stream on that device to the passed stream.

Errors if the [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) is not a CUDA stream.

~CUDAStreamGuard() = default

CUDAStreamGuard(const CUDAStreamGuard&) = delete

Copy is disallowed.

CUDAStreamGuard &operator=(const CUDAStreamGuard&) = delete

CUDAStreamGuard(CUDAStreamGuard &&other) = delete

Move is disallowed, as CUDAStreamGuard does not have an uninitialized state, which is required for moves on types with nontrivial destructors.

CUDAStreamGuard &operator=(CUDAStreamGuard &&other) = delete

inline void reset_stream([Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Resets the currently set stream to the original stream and the currently set device to the original device.

Then, set the current device to the device associated with the passed stream, and set the current stream on that device to the passed stream. Errors if the stream passed is not a CUDA stream.

NOTE: this implementation may skip some stream/device setting if it can prove that it is unnecessary.

WARNING: reset_stream does NOT preserve previously set streams on different devices. If you need to set streams on multiple devices on CUDA, use CUDAMultiStreamGuard instead.

inline [CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) original_stream() const

Returns the CUDA stream that was set at the time the guard was constructed.

inline [CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) current_stream() const

Returns the most recent CUDA stream that was set using this device guard, either from construction, or via set_stream.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) current_device() const

Returns the most recent CUDA device that was set using this device guard, either from construction, or via set_device/reset_device/set_index.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) original_device() const

Returns the CUDA device that was set at the most recent reset_stream(), or otherwise the device at construction time.

**Example:**

```
#include <c10/cuda/CUDAGuard.h>

auto stream = c10::cuda::getStreamFromPool();
{
 c10::cuda::CUDAStreamGuard guard(stream);
 // Operations here use the specified stream
}
// Previous stream is restored
```

## OptionalCUDAGuard

struct OptionalCUDAGuard

A variant of [OptionalDeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_optional_device_guard) that is specialized for CUDA.

See CUDAGuard for when you can use this.

Public Functions

explicit OptionalCUDAGuard() = default

Create an uninitialized OptionalCUDAGuard.

inline explicit OptionalCUDAGuard(std::optional<[Device](../c10/device.html#_CPPv4N3c106DeviceE)> device_opt)

Set the current CUDA device to the passed [Device](../c10/device.html#PyTorchstructc10_1_1_device), if it is not nullopt.

inline explicit OptionalCUDAGuard(std::optional<DeviceIndex> device_index_opt)

Set the current CUDA device to the passed device index, if it is not nullopt.

OptionalCUDAGuard(const OptionalCUDAGuard&) = delete

OptionalCUDAGuard &operator=(const OptionalCUDAGuard&) = delete

OptionalCUDAGuard(OptionalCUDAGuard &&other) = delete

OptionalCUDAGuard &operator=(OptionalCUDAGuard &&other) = delete

~OptionalCUDAGuard() = default

inline void set_device([Device](../c10/device.html#_CPPv4N3c106DeviceE) device)

Sets the CUDA device to the given device, initializing the guard if it is not already initialized.

Errors if the given device is not a CUDA device.

inline void reset_device([Device](../c10/device.html#_CPPv4N3c106DeviceE) device)

Sets the CUDA device to the given device, initializing the guard if it is not already initialized.

Errors if the given device is not a CUDA device. (This method is provided for uniformity with [OptionalDeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_optional_device_guard)).

inline void set_index(DeviceIndex device_index)

Sets the CUDA device to the given device index, initializing the guard if it is not already initialized.

inline std::optional<[Device](../c10/device.html#_CPPv4N3c106DeviceE)> original_device() const

Returns the device that was set immediately prior to initialization of the guard, or nullopt if the guard is uninitialized.

inline std::optional<[Device](../c10/device.html#_CPPv4N3c106DeviceE)> current_device() const

Returns the most recent device that was set using this device guard, either from construction, or via set_device, if the guard is initialized, or nullopt if the guard is uninitialized.

inline void reset()

Restore the original CUDA device, resetting this guard to uninitialized state.

**Example:**

```
c10::cuda::OptionalCUDAGuard guard;
if (use_cuda) {
 guard.set_device(0);
}
// Guard only switches device if set_device was called
```

## OptionalCUDAStreamGuard

struct OptionalCUDAStreamGuard

A variant of OptionalStreamGuard that is specialized for CUDA.

See CUDAGuard for when you can use this.

Public Functions

explicit OptionalCUDAStreamGuard() = default

Create an uninitialized guard.

inline explicit OptionalCUDAStreamGuard([Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Set the current CUDA device to the device associated with the passed stream, and set the current CUDA stream on that device to the passed stream.

Errors if the [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) is not a CUDA stream.

inline explicit OptionalCUDAStreamGuard(std::optional<[Stream](../c10/streams.html#_CPPv4N3c106StreamE)> stream_opt)

Set the current device to the device associated with the passed stream, and set the current stream on that device to the passed stream, if the passed stream is not nullopt.

OptionalCUDAStreamGuard(const OptionalCUDAStreamGuard&) = delete

Copy is disallowed.

OptionalCUDAStreamGuard &operator=(const OptionalCUDAStreamGuard&) = delete

OptionalCUDAStreamGuard(OptionalCUDAStreamGuard &&other) = delete

OptionalCUDAStreamGuard &operator=(OptionalCUDAStreamGuard &&other) = delete

~OptionalCUDAStreamGuard() = default

inline void reset_stream([Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Resets the currently set CUDA stream to the original stream and the currently set device to the original device.

Then, set the current device to the device associated with the passed stream, and set the current stream on that device to the passed stream. Initializes the guard if it was not previously initialized.

inline std::optional<[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE)> original_stream() const

Returns the CUDA stream that was set at the time the guard was most recently initialized, or nullopt if the guard is uninitialized.

inline std::optional<[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE)> current_stream() const

Returns the most recent CUDA stream that was set using this stream guard, either from construction, or via reset_stream, if the guard is initialized, or nullopt if the guard is uninitialized.

inline void reset()

Restore the original CUDA device and stream, resetting this guard to uninitialized state.

## CUDAMultiStreamGuard

struct CUDAMultiStreamGuard

A variant of MultiStreamGuard that is specialized for CUDA.

Public Functions

inline explicit CUDAMultiStreamGuard([ArrayRef](../c10/types.html#_CPPv4I0EN3c108ArrayRefE)<[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE)> streams)

CUDAMultiStreamGuard(const CUDAMultiStreamGuard&) = delete

Copy is disallowed.

CUDAMultiStreamGuard &operator=(const CUDAMultiStreamGuard&) = delete

CUDAMultiStreamGuard(CUDAMultiStreamGuard &&other) = delete

CUDAMultiStreamGuard &operator=(CUDAMultiStreamGuard &&other) = delete

~CUDAMultiStreamGuard() = default

**Example:**

```
at::cuda::CUDAStream stream0 = at::cuda::getStreamFromPool(false, 0);
at::cuda::CUDAStream stream1 = at::cuda::getStreamFromPool(false, 1);

{
 at::cuda::CUDAMultiStreamGuard multi_guard({stream0, stream1});
 // stream0 is current on device 0, stream1 on device 1
}
// Both streams restored
```

---

# CUDA Support

PyTorch provides comprehensive CUDA support for GPU-accelerated tensor
operations and neural network training. The CUDA API allows you to manage
GPU devices, streams for asynchronous execution, and memory efficiently.

**When to use CUDA APIs:**

- When you need explicit control over which GPU device to use
- When implementing custom CUDA kernels or operations
- When optimizing performance with asynchronous stream execution
- When managing multi-GPU workloads

**Basic usage:**

```
#include <torch/torch.h>
#include <c10/cuda/CUDAGuard.h>

// Check if CUDA is available
if (torch::cuda::is_available()) {
 // Create tensor on GPU
 auto tensor = torch::randn({2, 3}, torch::device(torch::kCUDA));

 // Switch to a specific GPU
 c10::cuda::CUDAGuard guard(0); // Use GPU 0

 // Get the current CUDA stream
 auto stream = c10::cuda::getCurrentCUDAStream();

 // Move model to GPU
 model->to(torch::kCUDA);
}
```

## Header Files

- `c10/cuda/CUDAStream.h` - CUDA stream management
- `c10/cuda/CUDAGuard.h` - CUDA device guards
- `ATen/cuda/CUDAContext.h` - CUDA context management
- `ATen/cudnn/Descriptors.h` - cuDNN tensor descriptors

## CUDA Categories

- [CUDA Streams](streams.html)
- [CUDA Guards](guards.html)
- [CUDA Utility Functions](utilities.html)

---

# CUDA Streams

CUDA streams provide a mechanism for asynchronous execution of operations
on the GPU. Operations queued to the same stream execute in order, while
operations on different streams can execute concurrently.

## CUDAStream

class CUDAStream

Public Types

enum Unchecked

*Values:*

enumerator UNCHECKED

Public Functions

inline explicit CUDAStream([Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Construct a CUDAStream from a [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream).

This construction is checked, and will raise an error if the [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) is not, in fact, a CUDA stream.

inline explicit CUDAStream(Unchecked, [Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Construct a CUDAStream from a [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) with no error checking.

This constructor uses the "named" constructor idiom, and can be invoked as: CUDAStream(CUDAStream::UNCHECKED, stream)

inline bool operator==(const CUDAStream &other) const noexcept

inline bool operator!=(const CUDAStream &other) const noexcept

inline operator cudaStream_t() const

Implicit conversion to cudaStream_t.

inline operator [Stream](../c10/streams.html#_CPPv4N3c106StreamE)() const

Implicit conversion to [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) (a.k.a., forget that the stream is a CUDA stream).

inline [DeviceType](../c10/device.html#_CPPv4N3c1010DeviceTypeE) device_type() const

Used to avoid baking in device type explicitly to Python-side API.

inline DeviceIndex device_index() const

Get the CUDA device index that this stream is associated with.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) device() const

Get the full [Device](../c10/device.html#PyTorchstructc10_1_1_device) that this stream is associated with.

The [Device](../c10/device.html#PyTorchstructc10_1_1_device) is guaranteed to be a CUDA device.

inline StreamId id() const

Return the stream ID corresponding to this particular stream.

bool query() const

void synchronize() const

inline bool is_capturing() const

inline int priority() const

cudaStream_t stream() const

Explicit conversion to cudaStream_t.

inline [Stream](../c10/streams.html#_CPPv4N3c106StreamE) unwrap() const

Explicit conversion to [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream).

inline struct c10::StreamData3 pack3() const

Reversibly pack a CUDAStream into a struct representation.

Previously the stream's data was packed into a single int64_t, as it was assumed the fields would not require more than 64 bits of storage in total. See [pytorch/pytorch#75854](https://github.com/pytorch/pytorch/issues/75854) for more information regarding newer platforms that may violate this assumption.

The CUDAStream can be unpacked using unpack().

Public Static Functions

static inline CUDAStream unpack3(StreamId stream_id, DeviceIndex device_index, [DeviceType](../c10/device.html#_CPPv4N3c1010DeviceTypeE) device_type)

static inline std::tuple<int, int> priority_range()

**Example:**

```
#include <c10/cuda/CUDAStream.h>

// Get the default stream for current device
auto stream = c10::cuda::getDefaultCUDAStream();

// Create a new stream
auto new_stream = c10::cuda::getStreamFromPool();

// Get current stream
auto current = c10::cuda::getCurrentCUDAStream();

// Synchronize
stream.synchronize();
```

## Acquiring CUDA Streams

PyTorch provides several ways to acquire CUDA streams:

1. **From the stream pool** (round-robin allocation):

```
// Normal priority stream
at::cuda::CUDAStream stream = at::cuda::getStreamFromPool();

// High priority stream
at::cuda::CUDAStream high_prio = at::cuda::getStreamFromPool(/*isHighPriority=*/true);

// Stream for specific device
at::cuda::CUDAStream dev1_stream = at::cuda::getStreamFromPool(false, /*device=*/1);
```
2. **Default stream** (where most computation occurs):

```
at::cuda::CUDAStream defaultStream = at::cuda::getDefaultCUDAStream();
```
3. **Current stream** (may differ if changed with guards):

```
at::cuda::CUDAStream currentStream = at::cuda::getCurrentCUDAStream();
```

## Setting CUDA Streams

**Using setCurrentCUDAStream:**

```
torch::Tensor tensor0 = torch::ones({2, 2}, torch::device(torch::kCUDA));

// Get a new stream and set it as current
at::cuda::CUDAStream myStream = at::cuda::getStreamFromPool();
at::cuda::setCurrentCUDAStream(myStream);

// Operations now use myStream
tensor0.sum();

// Restore default stream
at::cuda::setCurrentCUDAStream(at::cuda::getDefaultCUDAStream());
```

**Using CUDAStreamGuard (recommended):**

```
torch::Tensor tensor0 = torch::ones({2, 2}, torch::device(torch::kCUDA));
at::cuda::CUDAStream myStream = at::cuda::getStreamFromPool();

{
 at::cuda::CUDAStreamGuard guard(myStream);
 // Operations use myStream within this scope
 tensor0.sum();
}
// Stream automatically restored to default
```

## Multi-Device Stream Management

**Streams on multiple devices:**

```
// Acquire streams for different devices
at::cuda::CUDAStream stream0 = at::cuda::getStreamFromPool(false, 0);
at::cuda::CUDAStream stream1 = at::cuda::getStreamFromPool(false, 1);

// Set current streams on each device
at::cuda::setCurrentCUDAStream(stream0);
at::cuda::setCurrentCUDAStream(stream1);

// Create tensors on device 0
torch::Tensor tensor0 = torch::ones({2, 2}, torch::device(at::kCUDA));
tensor0.sum(); // Uses stream0

// Switch to device 1
{
 at::cuda::CUDAGuard device_guard(1);
 torch::Tensor tensor1 = torch::ones({2, 2}, torch::device(at::kCUDA));
 tensor1.sum(); // Uses stream1
}
```

**Using CUDAMultiStreamGuard:**

```
torch::Tensor tensor0 = torch::ones({2, 2}, torch::device({torch::kCUDA, 0}));
torch::Tensor tensor1 = torch::ones({2, 2}, torch::device({torch::kCUDA, 1}));

at::cuda::CUDAStream stream0 = at::cuda::getStreamFromPool(false, 0);
at::cuda::CUDAStream stream1 = at::cuda::getStreamFromPool(false, 1);

{
 // Set streams on both devices simultaneously
 at::cuda::CUDAMultiStreamGuard multi_guard({stream0, stream1});

 tensor0.sum(); // Uses stream0 on device 0
 tensor1.sum(); // Uses stream1 on device 1
}
// Both streams restored to defaults
```

Attention

`CUDAMultiStreamGuard` does not change the current device index. It only
changes the stream on each passed-in stream's device.

## Multi-Device Stream Handling Pattern

The following skeleton shows three common patterns for acquiring and setting
streams across multiple CUDA devices:

```
// Create stream vectors on device 0
std::vector<at::cuda::CUDAStream> streams0 =
 {at::cuda::getDefaultCUDAStream(), at::cuda::getStreamFromPool()};
at::cuda::setCurrentCUDAStream(streams0[0]);

// Create stream vector on device 1 using CUDAGuard
std::vector<at::cuda::CUDAStream> streams1;
{
 at::cuda::CUDAGuard device_guard(1);
 streams1.push_back(at::cuda::getDefaultCUDAStream());
 streams1.push_back(at::cuda::getStreamFromPool());
}
at::cuda::setCurrentCUDAStream(streams1[0]);

// Pattern 1: CUDAGuard changes current device only, not streams
{
 at::cuda::CUDAGuard device_guard(1);
 // current device is 1, current stream on device 1 is still streams1[0]
}

// Pattern 2: CUDAStreamGuard changes both current device and current stream
{
 at::cuda::CUDAStreamGuard stream_guard(streams1[1]);
 // current device is 1, current stream is streams1[1]
}
// restored to device 0, stream streams0[0]

// Pattern 3: CUDAMultiStreamGuard sets streams on multiple devices at once
{
 at::cuda::CUDAMultiStreamGuard multi_guard({streams0[1], streams1[1]});
 // current device unchanged (still 0)
 // stream on device 0 is streams0[1], stream on device 1 is streams1[1]
}
// streams restored to streams0[0] and streams1[0]
```

---

# CUDA Utility Functions

PyTorch provides utility functions for querying and managing CUDA devices,
streams, and library handles.

## Device Management

c10::DeviceIndex torch::cuda::device_count()

Returns the number of CUDA devices available.

int c10::cuda::current_device()

Returns the index of the current CUDA device.

**Example:**

```
#include <c10/cuda/CUDAFunctions.h>

// Check available devices
int num_devices = c10::cuda::device_count();

// Get current device
int current = c10::cuda::current_device();
```

## Device Properties

cudaDeviceProp *at::cuda::getCurrentDeviceProperties()

cudaDeviceProp *at::cuda::getDeviceProperties(c10::DeviceIndex device)

bool at::cuda::canDeviceAccessPeer(c10::DeviceIndex device, c10::DeviceIndex peer_device)

int at::cuda::warp_size()

**Example:**

```
#include <ATen/cuda/CUDAContext.h>

// Query properties of the current device
cudaDeviceProp* props = at::cuda::getCurrentDeviceProperties();
std::cout << "Device: " << props->name << std::endl;
std::cout << "Compute capability: " << props->major << "." << props->minor << std::endl;

// Query a specific device
cudaDeviceProp* dev1_props = at::cuda::getDeviceProperties(1);

// Check peer access
bool can_access = at::cuda::canDeviceAccessPeer(0, 1);
```

## Library Handles

These functions return handles for CUDA math libraries on the current device
and stream. They are primarily useful when writing custom CUDA kernels that
call cuBLAS, cuSPARSE, or cuSOLVER directly.

cublasHandle_t at::cuda::getCurrentCUDABlasHandle(bool setup = true)

The returned cuBLAS handle uses cuBLAS's default workspace unless ATen
workspace caching is explicitly enabled. Internal ATen operations may
temporarily bind an eager workspace to this handle, but restore the default
workspace before releasing that allocation.

cublasLtHandle_t at::cuda::getCurrentCUDABlasLtHandle()

cusparseHandle_t at::cuda::getCurrentCUDASparseHandle()

cusolverDnHandle_t at::cuda::getCurrentCUDASolverDnHandle()

**Example:**

```
#include <ATen/cuda/CUDAContext.h>

// Get cuBLAS handle for current device/stream
cublasHandle_t handle = at::cuda::getCurrentCUDABlasHandle();

// Get cuSPARSE handle
cusparseHandle_t sparse_handle = at::cuda::getCurrentCUDASparseHandle();
```

## cuDNN Descriptors

When writing custom kernels that call cuDNN directly, PyTorch provides RAII
wrapper classes for cuDNN descriptors. These are defined in
`ATen/cudnn/Descriptors.h`.

### Descriptor (Base Class)

template<typename T, cudnnStatus_t (*ctor)(T**), cudnnStatus_t (*dtor)(T*)>
class Descriptor

Public Functions

inline T *desc() const

inline T *desc()

inline T *mut_desc()

A generic RAII wrapper for cuDNN descriptor types. Descriptors default
construct to a `nullptr` and are initialized on first use via `mut_desc()`.
Use `desc()` for read-only access.

### TensorDescriptor

class TensorDescriptor : public at::native::Descriptor<cudnnTensorStruct, &cudnnCreateTensorDescriptor, &cudnnDestroyTensorDescriptor>

Public Functions

TensorDescriptor() = default

inline explicit TensorDescriptor(const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &t, size_t pad = 0)

void set(const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &t, size_t pad = 0)

void set(const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &t, at::MemoryFormat memory_format, size_t pad = 0)

void set(cudnnDataType_t dataType, IntArrayRef sizes, IntArrayRef strides, size_t pad = 0)

void print()

Wraps `cudnnTensorDescriptor_t`. Supports padding lower-dimensional tensors
to meet cuDNN broadcasting requirements (see `pad` parameter).

**Example:**

```
#include <ATen/cudnn/Descriptors.h>

at::Tensor input = torch::randn({32, 3, 224, 224}, torch::kCUDA);
at::native::TensorDescriptor desc(input);
cudnnTensorDescriptor_t raw = desc.desc();
```

### FilterDescriptor

class FilterDescriptor : public at::native::Descriptor<cudnnFilterStruct, &cudnnCreateFilterDescriptor, &cudnnDestroyFilterDescriptor>

Public Functions

inline void set(const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &t, int64_t pad = 0)

void set(const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &t, const at::MemoryFormat memory_format, int64_t pad = 0)

void print()

Wraps `cudnnFilterDescriptor_t` for convolution filter weights.

### ConvolutionDescriptor

struct ConvolutionDescriptor : public at::native::Descriptor<cudnnConvolutionStruct, &cudnnCreateConvolutionDescriptor, &cudnnDestroyConvolutionDescriptor>

Public Functions

inline void set(cudnnDataType_t dataType, int dim, int *pad, int *stride, int *upscale, int groups, bool allow_tf32)

Wraps `cudnnConvolutionDescriptor_t`. Configures padding, stride, dilation,
groups, and math type (TF32, tensor ops) for convolution operations.

### RNNDataDescriptor

class RNNDataDescriptor : public at::native::Descriptor<cudnnRNNDataStruct, &cudnnCreateRNNDataDescriptor, &cudnnDestroyRNNDataDescriptor>

Public Functions

void set(const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &t, cudnnRNNDataLayout_t layout, int maxSeqLength, int batchSize, int vectorSize, const int *seqLengthArray)

Wraps `cudnnRNNDataDescriptor_t` for variable-length sequence data.

### DropoutDescriptor

struct DropoutDescriptor : public at::native::Descriptor<cudnnDropoutStruct, &cudnnCreateDropoutDescriptor, &cudnnDestroyDropoutDescriptor>

Public Functions

inline void initialize_rng(cudnnHandle_t handle, float dropout, long long int seed, const [TensorOptions](../aten/tensor.html#_CPPv4N2at13TensorOptionsE) &options)

inline void set(cudnnHandle_t handle, float dropout, const at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) &state)

inline void set_no_dropout(cudnnHandle_t handle)

Public Members

at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE) state

Wraps `cudnnDropoutDescriptor_t`. Manages RNG state for cuDNN dropout.

### ActivationDescriptor

struct ActivationDescriptor : public at::native::Descriptor<cudnnActivationStruct, &cudnnCreateActivationDescriptor, &cudnnDestroyActivationDescriptor>

Public Functions

inline void set(cudnnActivationMode_t mode)

Wraps `cudnnActivationDescriptor_t`.

### SpatialTransformerDescriptor

struct SpatialTransformerDescriptor : public at::native::Descriptor<cudnnSpatialTransformerStruct, &cudnnCreateSpatialTransformerDescriptor, &cudnnDestroySpatialTransformerDescriptor>

Public Functions

inline void set(cudnnDataType_t dataType, int dim, int *size)

### CTCLossDescriptor

struct CTCLossDescriptor : public at::native::Descriptor<cudnnCTCLossStruct, &cudnnCreateCTCLossDescriptor, &cudnnDestroyCTCLossDescriptor>

Public Functions

inline void set(cudnnDataType_t datatype)

inline void setEx(cudnnDataType_t datatype, cudnnLossNormalizationMode_t normMode, cudnnNanPropagation_t gradMode)

inline void set_v8_v9(cudnnDataType_t datatype, cudnnLossNormalizationMode_t normMode, cudnnNanPropagation_t gradMode, int maxLabelLength)

## Stream Management

[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) c10::cuda::getDefaultCUDAStream(DeviceIndex device_index = -1)

Get the default CUDA stream, for the passed CUDA device, or for the current device if no device index is passed.

The default stream is where most computation occurs when you aren't explicitly using streams.

[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) c10::cuda::getCurrentCUDAStream(DeviceIndex device_index = -1)

Get the current CUDA stream, for the passed CUDA device, or for the current device if no device index is passed.

The current CUDA stream will usually be the default CUDA stream for the device, but it may be different if someone called 'setCurrentCUDAStream' or used 'StreamGuard' or '[CUDAStreamGuard](guards.html#PyTorchstructc10_1_1cuda_1_1_c_u_d_a_stream_guard)'.

void c10::cuda::setCurrentCUDAStream([CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) stream)

Set the current stream on the device of the passed in stream to be the passed in stream.

Yes, you read that right: this function has *nothing* to do with the current device: it toggles the current stream of the device of the passed stream.

Confused? Avoid using this function; prefer using '[CUDAStreamGuard](guards.html#PyTorchstructc10_1_1cuda_1_1_c_u_d_a_stream_guard)' instead (which will switch both your current device and current stream in the way you expect, and reset it back to its original state afterwards).

[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) c10::cuda::getStreamFromPool(const bool isHighPriority = false, DeviceIndex device = -1)

Get a new stream from the CUDA stream pool.

You can think of this as "creating" a new stream, but no such creation actually happens; instead, streams are preallocated from the pool and returned in a round-robin fashion.

You can request a stream from the high priority pool by setting isHighPriority to true, or a stream for a specific device by setting device (defaulting to the current CUDA stream.)

[CUDAStream](streams.html#_CPPv4N3c104cuda10CUDAStreamE) c10::cuda::getStreamFromExternal(cudaStream_t ext_stream, DeviceIndex device_index)

Get a [CUDAStream](streams.html#PyTorchclassc10_1_1cuda_1_1_c_u_d_a_stream) from a externally allocated one.

This is mainly for interoperability with different libraries where we want to operate on a non-torch allocated stream for data exchange or similar purposes

**Example:**

```
#include <c10/cuda/CUDAStream.h>

// Create and set custom stream
auto stream = c10::cuda::getStreamFromPool();
c10::cuda::setCurrentCUDAStream(stream);

// Get default stream
auto default_stream = c10::cuda::getDefaultCUDAStream();

// Wrap an externally created CUDA stream
cudaStream_t ext_stream;
cudaStreamCreate(&ext_stream);
auto wrapped = c10::cuda::getStreamFromExternal(ext_stream, /*device_index=*/0);
```

---

# DataLoader

The DataLoader batches samples from a dataset and optionally shuffles and
parallelizes the loading process. It is the main interface for iterating
over training data.

## DataLoader Classes

template<typename Dataset, typename Batch, typename BatchRequest>
class DataLoaderBase

Public Types

using BatchType = Batch

using BatchRequestType = BatchRequest

Public Functions

inline DataLoaderBase(DataLoaderOptions options, std::unique_ptr<Dataset> main_thread_dataset = nullptr)

Constructs a new DataLoader from a `dataset` to sample from, `options` to configure the DataLoader with, and a `sampler` that specifies the sampling strategy.

DataLoaderBase(const DataLoaderBase&) = delete

DataLoaderBase(DataLoaderBase&&) = delete

DataLoaderBase &operator=(const DataLoaderBase&) = delete

DataLoaderBase &operator=(DataLoaderBase&&) = delete

inline virtual ~DataLoaderBase()

inline Iterator<Batch> begin()

Returns an iterator into the DataLoader.

The lifetime of the iterator is bound to the DataLoader. In C++ standards language, the category of the iterator is `OutputIterator`. See [https://en.cppreference.com/w/cpp/named_req/OutputIterator](https://en.cppreference.com/w/cpp/named_req/OutputIterator) for what this means. In short: you may increment the iterator and dereference it, but cannot go back, or step forward more than one position at a time. When the DataLoader is exhausted, it will compare equal with the special "sentinel" iterator returned by `DataLoader::end()`. Most of the time, you should only use range-for loops to loop over the DataLoader, but standard algorithms like `std::copy(dataloader.begin(), dataloader.end(), output_iterator)` are supported too.

inline Iterator<Batch> end()

Returns a special "sentinel" iterator that compares equal with a non-sentinel iterator once the DataLoader is exhausted.

inline void join()

Joins the DataLoader's worker threads and drains internal queues.

This function may only be invoked from the main thread (in which the DataLoader lives).

inline const FullDataLoaderOptions &options() const noexcept

Returns the options with which the DataLoader was configured.

## DataLoaderOptions

struct DataLoaderOptions

Options to configure a `DataLoader`.

Public Functions

DataLoaderOptions() = default

inline DataLoaderOptions(size_t batch_size)

inline auto batch_size(const size_t &new_batch_size) -> decltype(*this)

The size of each batch to fetch.

inline auto batch_size(size_t &&new_batch_size) -> decltype(*this)

inline const size_t &batch_size() const noexcept

inline size_t &batch_size() noexcept

inline auto workers(const size_t &new_workers) -> decltype(*this)

The number of worker threads to launch.

If zero, the main thread will synchronously perform the data loading.

inline auto workers(size_t &&new_workers) -> decltype(*this)

inline const size_t &workers() const noexcept

inline size_t &workers() noexcept

inline auto max_jobs(const std::optional<size_t> &new_max_jobs) -> decltype(*this)

The maximum number of jobs to enqueue for fetching by worker threads.

Defaults to two times the number of worker threads.

inline auto max_jobs(std::optional<size_t> &&new_max_jobs) -> decltype(*this)

inline const std::optional<size_t> &max_jobs() const noexcept

inline std::optional<size_t> &max_jobs() noexcept

inline auto timeout(const std::optional<std::chrono::milliseconds> &new_timeout) -> decltype(*this)

An optional limit on the time to wait for the next batch.

inline auto timeout(std::optional<std::chrono::milliseconds> &&new_timeout) -> decltype(*this)

inline const std::optional<std::chrono::milliseconds> &timeout() const noexcept

inline std::optional<std::chrono::milliseconds> &timeout() noexcept

inline auto enforce_ordering(const bool &new_enforce_ordering) -> decltype(*this)

Whether to enforce ordering of batches when multiple are loaded asynchronously by worker threads.

Set to `false` for better performance if you do not care about determinism.

inline auto enforce_ordering(bool &&new_enforce_ordering) -> decltype(*this)

inline const bool &enforce_ordering() const noexcept

inline bool &enforce_ordering() noexcept

inline auto drop_last(const bool &new_drop_last) -> decltype(*this)

Whether to omit the last batch if it contains less than `batch_size` examples.

inline auto drop_last(bool &&new_drop_last) -> decltype(*this)

inline const bool &drop_last() const noexcept

inline bool &drop_last() noexcept

## StatefulDataLoader

A DataLoader for `StatefulDataset` types that manage their own batching logic
internally.

template<typename Dataset>
class StatefulDataLoader : public torch::data::DataLoaderBase<Dataset, Dataset::BatchType::value_type, Dataset::BatchRequestType>

A dataloader for stateful datasets.

A dataloader for stateful datasets differs from one for stateless datasets one in that the dataset is shared among worker threads, and that this dataset is itself responsible for producing batches rather than depending on a sampler. The statefulness here actually refers to the dataset. The StatefulDataLoader simply alters the data loading algorithm to accommodate the stateful, shared nature of the dataset. Note that the dataset must be thread safe if more than one worker thread is used.

A stateful dataloader is created by calling `make_data_loader` with a stateful dataset.

Public Types

using super = DataLoaderBase<Dataset, typename Dataset::BatchType::value_type, typename Dataset::BatchRequestType>

using BatchRequestType = BatchRequest

Public Functions

inline StatefulDataLoader(Dataset dataset, DataLoaderOptions options)

Constructs the `StatefulDataLoader` from a `dataset` and some `options`.

## StatelessDataLoader

A DataLoader for `Dataset` types that use external samplers for batching.

template<typename Dataset, typename Sampler>
class StatelessDataLoader : public torch::data::DataLoaderBase<Dataset, Dataset::BatchType, Sampler::BatchRequestType>

A dataloader for stateless datasets.

This dataloader follows the traditional PyTorch dataloader design, whereby a (possibly) stateful sampler produces *batch requests* for a stateless dataset, which acts as a simple batch request to batch mapping. The batch request will often be an array of indices, and if the dataset is a simple image dataset, the dataset would produce the images at those indices.

Public Types

using super = DataLoaderBase<Dataset, typename Dataset::BatchType, typename Sampler::BatchRequestType>

using BatchRequestType = BatchRequest

Public Functions

inline StatelessDataLoader(Dataset dataset, Sampler sampler, DataLoaderOptions options)

Constructs the `StatelessDataLoader` from a `dataset`, a `sampler` and some `options`.

## Iterator

template<typename Batch>
class Iterator

Public Types

using difference_type = std::ptrdiff_t

using value_type = Batch

using pointer = Batch*

using reference = Batch&

using iterator_category = std::input_iterator_tag

Public Functions

inline explicit Iterator(std::unique_ptr<detail::IteratorImpl<Batch>> impl)

inline Iterator &operator++()

Increments the iterator.

Only permitted for valid iterators (not past the end).

inline Batch &operator*()

Returns the current batch.

Only permitted for valid iterators (not past the end).

inline Batch *operator->()

Returns a pointer to the current batch.

Only permitted for valid iterators (not past the end).

inline bool operator==(const Iterator &other) const

Compares two iterators for equality.

inline bool operator!=(const Iterator &other) const

Compares two iterators for inequality.

## Creating a DataLoader

Use `make_data_loader` to create a DataLoader from a dataset:

```
auto data_loader = torch::data::make_data_loader(
 std::move(dataset),
 torch::data::DataLoaderOptions()
 .batch_size(64)
 .workers(4));

for (auto& batch : *data_loader) {
 auto data = batch.data;
 auto target = batch.target;
 // Train on batch
}
```

## Complete Training Example

```
#include <torch/torch.h>

int main() {
 // Load dataset
 auto dataset = torch::data::datasets::MNIST("./data")
 .map(torch::data::transforms::Normalize<>(0.1307, 0.3081))
 .map(torch::data::transforms::Stack<>());

 // Create data loader
 auto data_loader = torch::data::make_data_loader(
 std::move(dataset),
 torch::data::DataLoaderOptions().batch_size(64).workers(2));

 // Create model and optimizer
 auto model = std::make_shared<Net>();
 auto optimizer = torch::optim::Adam(model->parameters(), 0.001);

 // Training loop
 for (size_t epoch = 1; epoch <= 10; ++epoch) {
 for (auto& batch : *data_loader) {
 optimizer.zero_grad();
 auto output = model->forward(batch.data);
 auto loss = torch::nll_loss(output, batch.target);
 loss.backward();
 optimizer.step();
 }
 }
}
```

---

# Datasets

The dataset abstraction defines how to access individual samples in your data.
All datasets inherit from `Dataset` and must implement `get()` and `size()`.

## Dataset Base Class

template<typename Self, typename SingleExample = Example<>>
class Dataset : public torch::data::datasets::BatchDataset<Self, std::vector<Example<>>>

A dataset that can yield data in batches, or as individual examples.

A `Dataset` is a `BatchDataset`, because it supports random access and therefore batched access is implemented (by default) by calling the random access indexing function for each index in the requested batch of indices. This can be customized.

Public Types

using ExampleType = SingleExample

Public Functions

virtual ExampleType get(size_t index) = 0

Returns the example at the given index.

inline virtual std::vector<ExampleType> get_batch(ArrayRef<size_t> indices) override

Returns a batch of data.

The default implementation calls `get()` for every requested index in the batch.

template<typename Self, typename Batch = std::vector<Example<>>, typename BatchRequest = ArrayRef<size_t>>
class BatchDataset

A dataset that can yield data only in batches.

Subclassed by torch::data::datasets::Dataset< MNIST >, torch::data::datasets::Dataset< TensorDataset, TensorExample >, torch::data::datasets::StatefulDataset< ChunkDataset< ChunkReader, samplers::RandomSampler, samplers::RandomSampler >, ChunkReader::BatchType, size_t >

Public Types

using SelfType = Self

using BatchType = Batch

using BatchRequestType = BatchRequest

Public Functions

virtual ~BatchDataset() = default

virtual Batch get_batch(BatchRequest request) = 0

Returns a batch of data given an index.

virtual std::optional<size_t> size() const = 0

Returns the size of the dataset, or an empty std::optional if it is unsized.

template<typename TransformType>
inline MapDataset<Self, TransformType> map(TransformType transform) &

Creates a `MapDataset` that applies the given `transform` to this dataset.

template<typename TransformType>
inline MapDataset<Self, TransformType> map(TransformType transform) &&

Creates a `MapDataset` that applies the given `transform` to this dataset.

Public Static Attributes

static constexpr bool is_stateful = detail::is_optional<BatchType>::value

## StatefulDataset

A dataset that manages its own state across batches (e.g., position in a stream).
Unlike `Dataset`, it produces batches directly without external samplers.

template<typename Self, typename Batch = std::vector<Example<>>, typename BatchRequest = size_t>
class StatefulDataset : public BatchDataset<Self, std::optional<std::vector<Example<>>>, size_t>

A stateful dataset is a dataset that maintains some internal state, which will be `reset()` at the beginning of each epoch.

Subclasses can override the `reset()` method to configure this behavior. Further, the return type of a stateful dataset's `get_batch()` method is always an `optional`. When the stateful dataset wants to indicate to the dataloader that its epoch has ended, it should return an empty optional. The dataloader knows to modify its implementation based on whether the dataset is stateless or stateful.

Note that when subclassing from `StatefulDataset<Self, T>`, the return type of `get_batch()`, which the subclass must override, will be `optional<T>` (i.e. the type specified in the `StatefulDataset` specialization is automatically boxed into an `optional` for the dataset's `BatchType`).

Public Functions

virtual void reset() = 0

Resets internal state of the dataset.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const = 0

Saves the statefulDataset's state to OutputArchive.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) = 0

Deserializes the statefulDataset's state from the `archive`.

## ChunkDataReader

Interface for reading chunks of data from a data source. Used with
`ChunkDataset` for large-scale data loading.

template<typename ExampleType_, typename ChunkType_ = std::vector<ExampleType_>>
class ChunkDataReader

Interface for chunk reader, which performs data chunking and reading of entire chunks.

A chunk could be an entire file, such as an audio data file or an image, or part of a file in the case of a large text-file split based on seek positions.

Public Types

using ChunkType = ChunkType_

using ExampleType = ExampleType_

Public Functions

virtual ~ChunkDataReader() = default

virtual ChunkType read_chunk(size_t chunk_index) = 0

Read an entire chunk.

virtual size_t chunk_count() = 0

Returns the number of chunks available in this reader.

virtual void reset() = 0

This will clear any internal state associate with this reader.

## Custom Dataset Example

```
class CustomDataset : public torch::data::datasets::Dataset<CustomDataset> {
 public:
 explicit CustomDataset(const std::string& root) {
 // Load data from root directory
 }

 torch::data::Example<> get(size_t index) override {
 return {images_[index], labels_[index]};
 }

 torch::optional<size_t> size() const override {
 return images_.size(0);
 }

 private:
 torch::Tensor images_, labels_;
};
```

## MapDataset

template<typename SourceDataset, typename AppliedTransform>
class MapDataset : public torch::data::datasets::BatchDataset<MapDataset<SourceDataset, AppliedTransform>, detail::optional_if_t<SourceDataset::is_stateful, AppliedTransform::OutputBatchType>, SourceDataset::BatchRequestType>

A `MapDataset` is a dataset that applies a transform to a source dataset.

Public Types

using DatasetType = SourceDataset

using TransformType = AppliedTransform

using BatchRequestType = typename SourceDataset::BatchRequestType

using OutputBatchType = detail::optional_if_t<SourceDataset::is_stateful, typename AppliedTransform::OutputBatchType>

Public Functions

inline MapDataset(DatasetType dataset, TransformType transform)

inline virtual OutputBatchType get_batch(BatchRequestType indices) override

Gets a batch from the source dataset and applies the transform to it, returning the result.

inline virtual std::optional<size_t> size() const noexcept override

Returns the size of the source dataset.

inline void reset()

Calls `reset()` on the underlying dataset.

NOTE: Stateless datasets do not have a reset() method, so a call to this method will only compile for stateful datasets (which have a reset() method).

inline const SourceDataset &dataset() noexcept

Returns the underlying dataset.

inline const AppliedTransform &transform() noexcept

Returns the transform being applied.

## ChunkDataset

template<typename ChunkReader, typename ChunkSampler = samplers::[RandomSampler](samplers.html#_CPPv4N5torch4data8samplers13RandomSamplerE), typename ExampleSampler = samplers::[RandomSampler](samplers.html#_CPPv4N5torch4data8samplers13RandomSamplerE)>
class ChunkDataset : public torch::data::datasets::StatefulDataset<ChunkDataset<ChunkReader, samplers::[RandomSampler](samplers.html#_CPPv4N5torch4data8samplers13RandomSamplerE), samplers::[RandomSampler](samplers.html#_CPPv4N5torch4data8samplers13RandomSamplerE)>, ChunkReader::BatchType, size_t>

A stateful dataset that support hierarchical sampling and prefetching of entire chunks.

Unlike regular dataset, chunk dataset require two samplers to operate and keeps an internal state. `ChunkSampler` selects, which chunk to load next, while the `ExampleSampler` determines the order of Examples that are returned in each `get_batch` call. The hierarchical sampling approach used here is inspired by this paper [https://proceedings.neurips.cc/paper_files/paper/2010/file/abea47ba24142ed16b7d8fbf2c740e0d-Paper.pdf](https://proceedings.neurips.cc/paper_files/paper/2010/file/abea47ba24142ed16b7d8fbf2c740e0d-Paper.pdf)

Public Types

using BatchType = std::optional<typename ChunkReader::BatchType>

using UnwrappedBatchType = typename ChunkReader::BatchType

using BatchRequestType = size_t

using ChunkSamplerType = ChunkSampler

using ExampleSamplerType = ExampleSampler

Public Functions

inline ChunkDataset(ChunkReader chunk_reader, ChunkSampler chunk_sampler, ExampleSampler example_sampler, ChunkDatasetOptions options, std::function<void(UnwrappedBatchType&)> preprocessing_policy = std::function<void(UnwrappedBatchType&)>())

inline ~ChunkDataset() override

inline BatchType get_batch(size_t batch_size) override

Default get_batch method of BatchDataset.

This method returns Example batches created from the preloaded chunks. The implementation is dataset agnostic and does not need overriding in different chunk datasets.

inline BatchType get_batch()

Helper method around get_batch as `batch_size` is not strictly necessary.

inline virtual void reset() override

This will clear any internal state and starts the internal prefetching mechanism for the chunk dataset.

inline virtual std::optional<size_t> size() const override

size is not used for chunk dataset.

inline ChunkSamplerType &chunk_sampler()

inline virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Saves the statefulDataset's state to OutputArchive.

inline virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the statefulDataset's state from the `archive`.

## SharedBatchDataset

template<typename UnderlyingDataset>
class SharedBatchDataset : public torch::data::datasets::BatchDataset<SharedBatchDataset<UnderlyingDataset>, UnderlyingDataset::BatchType, UnderlyingDataset::BatchRequestType>

A dataset that wraps another dataset in a shared pointer and implements the `BatchDataset` API, delegating all calls to the shared instance.

This is useful when you want all worker threads in the dataloader to access the same dataset instance. The dataset must take care of synchronization and thread-safe access itself.

Use `torch::data::datasets::make_shared_dataset()` to create a new `SharedBatchDataset` like you would a `std::shared_ptr`.

Public Types

using BatchType = typename UnderlyingDataset::BatchType

using BatchRequestType = typename UnderlyingDataset::BatchRequestType

Public Functions

inline SharedBatchDataset(std::shared_ptr<UnderlyingDataset> shared_dataset)

Constructs a new `SharedBatchDataset` from a `shared_ptr` to the `UnderlyingDataset`.

inline virtual BatchType get_batch(BatchRequestType request) override

Calls `get_batch` on the underlying dataset.

inline virtual std::optional<size_t> size() const override

Returns the `size` from the underlying dataset.

inline UnderlyingDataset &operator*()

Accesses the underlying dataset.

inline const UnderlyingDataset &operator*() const

Accesses the underlying dataset.

inline UnderlyingDataset *operator->()

Accesses the underlying dataset.

inline const UnderlyingDataset *operator->() const

Accesses the underlying dataset.

inline void reset()

Calls `reset()` on the underlying dataset.

## Built-in Datasets

### MNIST

class MNIST : public torch::data::datasets::Dataset<MNIST>

The MNIST dataset.

Public Types

enum class Mode

The mode in which the dataset is loaded.

*Values:*

enumerator kTrain

enumerator kTest

Public Functions

explicit MNIST(const std::string &root, Mode mode = Mode::kTrain)

Loads the MNIST dataset from the `root` path.

The supplied `root` path should contain the *content* of the unzipped MNIST dataset, available from [http://yann.lecun.com/exdb/mnist](http://yann.lecun.com/exdb/mnist).

virtual Example get(size_t index) override

Returns the `Example` at the given `index`.

virtual std::optional<size_t> size() const override

Returns the size of the dataset.

bool is_train() const noexcept

Returns true if this is the training subset of MNIST.

const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &images() const

Returns all images stacked into a single tensor.

const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &targets() const

Returns all targets stacked into a single tensor.

**Example:**

```
auto dataset = torch::data::datasets::MNIST("./data")
 .map(torch::data::transforms::Normalize<>(0.1307, 0.3081))
 .map(torch::data::transforms::Stack<>());
```

## Example Struct

template<typename Data = at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE), typename Target = at::[Tensor](../aten/tensor.html#_CPPv4N2at6TensorE)>
struct Example

An `Example` from a dataset.

A dataset consists of data and an associated target (label).

Public Types

using DataType = Data

using TargetType = Target

Public Functions

Example() = default

inline Example(Data data, Target target)

Public Members

Data data

Target target

---

# Data Loading (torch::data)

The `torch::data` namespace provides utilities for loading and processing
datasets during training. It includes dataset abstractions, data loaders for
batching and shuffling, samplers for controlling data access patterns, and
transforms for data augmentation.

**When to use torch::data:**

- When loading training data in batches
- When you need parallel data loading with multiple workers
- When implementing custom datasets or transforms

**Components overview:**

- **Dataset**: Defines how to access individual samples (implement `get()` and `size()`)
- **DataLoader**: Batches samples and optionally shuffles/parallelizes loading
- **Sampler**: Controls the order in which samples are accessed
- **Transform**: Applies preprocessing (normalization, augmentation) to samples

**Basic usage:**

```
#include <torch/torch.h>

// Load built-in dataset
auto dataset = torch::data::datasets::MNIST("./data")
 .map(torch::data::transforms::Normalize<>(0.1307, 0.3081))
 .map(torch::data::transforms::Stack<>());

// Create data loader with batching and shuffling
auto data_loader = torch::data::make_data_loader(
 std::move(dataset),
 torch::data::DataLoaderOptions().batch_size(64).workers(4));

// Iterate over batches
for (auto& batch : *data_loader) {
 auto images = batch.data; // Shape: [64, 1, 28, 28]
 auto labels = batch.target; // Shape: [64]
}
```

## Header Files

- `torch/csrc/api/include/torch/data.h` - Main data header
- `torch/csrc/api/include/torch/data/dataloader.h` - DataLoader
- `torch/csrc/api/include/torch/data/datasets.h` - Dataset classes
- `torch/csrc/api/include/torch/data/samplers.h` - Samplers

## Module Categories

- [Datasets](datasets.html)
- [DataLoader](dataloader.html)
- [Samplers](samplers.html)
- [Transforms](transforms.html)

---

# Samplers

Samplers control the order in which samples are accessed from a dataset.
They determine the indices that the DataLoader uses to fetch data.

## Sampler Base Class

template<typename BatchRequest = std::vector<size_t>>
class Sampler

A `Sampler` is an object that yields an index with which to access a dataset.

Subclassed by torch::data::samplers::RandomSampler, torch::data::samplers::SequentialSampler

Public Types

using BatchRequestType = BatchRequest

Public Functions

virtual ~Sampler() = default

virtual void reset(std::optional<size_t> new_size) = 0

Resets the `Sampler`'s internal state.

Typically called before a new epoch. Optionally, accepts a new size when resetting the sampler.

virtual std::optional<BatchRequest> next(size_t batch_size) = 0

Returns the next index if possible, or an empty optional if the sampler is exhausted for this epoch.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const = 0

Serializes the `Sampler` to the `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) = 0

Deserializes the `Sampler` from the `archive`.

## Sequential Sampler

Accesses samples in order from 0 to N-1. Use this for evaluation or when
order matters.

class SequentialSampler : public torch::data::samplers::Sampler<>

A `Sampler` that returns indices sequentially.

Public Functions

explicit SequentialSampler(size_t size)

Creates a `SequentialSampler` that will return indices in the range `0...size - 1`.

virtual void reset(std::optional<size_t> new_size = std::nullopt) override

Resets the `SequentialSampler` to zero.

virtual std::optional<std::vector<size_t>> next(size_t batch_size) override

Returns the next batch of indices.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the `SequentialSampler` to the `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the `SequentialSampler` from the `archive`.

size_t index() const noexcept

Returns the current index of the `SequentialSampler`.

## Random Sampler

Accesses samples in random order. Use this for training to ensure the model
sees samples in different orders each epoch.

class RandomSampler : public torch::data::samplers::Sampler<>

A `Sampler` that returns random indices.

Public Functions

explicit RandomSampler(int64_t size, Dtype index_dtype = torch::kInt64)

Constructs a `RandomSampler` with a size and dtype for the stored indices.

The constructor will eagerly allocate all required indices, which is the sequence `0 ... size - 1`. `index_dtype` is the data type of the stored indices. You can change it to influence memory usage.

~RandomSampler() override

virtual void reset(std::optional<size_t> new_size = std::nullopt) override

Resets the `RandomSampler` to a new set of indices.

virtual std::optional<std::vector<size_t>> next(size_t batch_size) override

Returns the next batch of indices.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the `RandomSampler` to the `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the `RandomSampler` from the `archive`.

size_t index() const noexcept

Returns the current index of the `RandomSampler`.

## Distributed Random Sampler

For distributed training, ensures each process gets a different subset of
the data without overlap.

class DistributedRandomSampler : public torch::data::samplers::DistributedSampler<>

Select samples randomly.

The sampling order is shuffled at each `reset()` call.

Public Functions

DistributedRandomSampler(size_t size, size_t num_replicas = 1, size_t rank = 0, bool allow_duplicates = true)

virtual void reset(std::optional<size_t> new_size = std::nullopt) override

Resets the `DistributedRandomSampler` to a new set of indices.

virtual std::optional<std::vector<size_t>> next(size_t batch_size) override

Returns the next batch of indices.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the `DistributedRandomSampler` to the `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the `DistributedRandomSampler` from the `archive`.

size_t index() const noexcept

Returns the current index of the `DistributedRandomSampler`.

## Distributed Sampler (Base)

template<typename BatchRequest = std::vector<size_t>>
class DistributedSampler : public torch::data::samplers::Sampler<std::vector<size_t>>

A `Sampler` that selects a subset of indices to sample from and defines a sampling behavior.

In a distributed setting, this selects a subset of the indices depending on the provided num_replicas and rank parameters. The `Sampler` performs a rounding operation based on the `allow_duplicates` parameter to decide the local sample count.

Subclassed by torch::data::samplers::DistributedRandomSampler, torch::data::samplers::DistributedSequentialSampler

Public Functions

inline DistributedSampler(size_t size, size_t num_replicas = 1, size_t rank = 0, bool allow_duplicates = true)

inline void set_epoch(size_t epoch)

Set the epoch for the current enumeration.

This can be used to alter the sample selection and shuffling behavior.

inline size_t epoch() const

## Distributed Sequential Sampler

class DistributedSequentialSampler : public torch::data::samplers::DistributedSampler<>

Select samples sequentially.

Public Functions

DistributedSequentialSampler(size_t size, size_t num_replicas = 1, size_t rank = 0, bool allow_duplicates = true)

virtual void reset(std::optional<size_t> new_size = std::nullopt) override

Resets the `DistributedSequentialSampler` to a new set of indices.

virtual std::optional<std::vector<size_t>> next(size_t batch_size) override

Returns the next batch of indices.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the `DistributedSequentialSampler` to the `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the `DistributedSequentialSampler` from the `archive`.

size_t index() const noexcept

Returns the current index of the `DistributedSequentialSampler`.

## Stream Sampler

class StreamSampler : public torch::data::samplers::Sampler<BatchSize>

A sampler for (potentially infinite) streams of data.

The major feature of the `StreamSampler` is that it does not return particular indices, but instead only the number of elements to fetch from the dataset. The dataset has to decide how to produce those elements.

Public Functions

explicit StreamSampler(size_t epoch_size)

Constructs the `StreamSampler` with the number of individual examples that should be fetched until the sampler is exhausted.

virtual void reset(std::optional<size_t> new_size = std::nullopt) override

Resets the internal state of the sampler.

virtual std::optional<BatchSize> next(size_t batch_size) override

Returns a `BatchSize` object with the number of elements to fetch in the next batch.

This number is the minimum of the supplied `batch_size` and the difference between the `epoch_size` and the current index. If the `epoch_size` has been reached, returns an empty optional.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the `StreamSampler` to the `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the `StreamSampler` from the `archive`.

---

# Transforms

Transforms apply preprocessing to data samples, such as normalization or
augmentation. They can be chained using the `.map()` method on datasets.

## Transform (Base Class)

The base class for all transforms. Subclass this to create custom transforms.

template<typename Input, typename Output>
class Transform : public torch::data::transforms::BatchTransform<std::vector<Input>, std::vector<Output>>

A transformation of individual input examples to individual output examples.

Just like a `Dataset` is a `BatchDataset`, a `Transform` is a `BatchTransform` that can operate on the level of individual examples rather than entire batches. The batch-level transform is implemented (by default) in terms of the example-level transform, though this can be customized.

Public Types

using InputType = Input

using OutputType = Output

Public Functions

virtual OutputType apply(InputType input) = 0

Applies the transformation to the given `input`.

inline virtual std::vector<Output> apply_batch(std::vector<Input> input_batch) override

Applies the `transformation` over the entire `input_batch`.

## BatchTransform (Base Class)

Base class for transforms that operate on entire batches.

template<typename InputBatch, typename OutputBatch>
class BatchTransform

A transformation of a batch to a new batch.

Subclassed by torch::data::transforms::Transform< Example< Tensor, Tensor >, Example< Tensor, Tensor > >, torch::data::transforms::Transform< Input, Input >, torch::data::transforms::Stack< Example<> >, torch::data::transforms::Stack< TensorExample >

Public Types

using InputBatchType = InputBatch

using OutputBatchType = OutputBatch

Public Functions

virtual ~BatchTransform() = default

virtual OutputBatch apply_batch(InputBatch input_batch) = 0

Applies the transformation to the given `input_batch`.

## TensorTransform

Base class for transforms that operate on tensors specifically.

template<typename Target = [Tensor](../aten/tensor.html#_CPPv46Tensorv)>
class TensorTransform : public torch::data::transforms::Transform<[Example](datasets.html#_CPPv4I00EN5torch4data7ExampleE)<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>, [Example](datasets.html#_CPPv4I00EN5torch4data7ExampleE)<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>>

A `Transform` that is specialized for the typical `[Example](datasets.html#PyTorchstructtorch_1_1data_1_1_example)<Tensor, Tensor>` combination.

It exposes a single `operator()` interface hook (for subclasses), and calls this function on input `[Example](datasets.html#PyTorchstructtorch_1_1data_1_1_example)` objects.

Public Types

using E = [Example](datasets.html#_CPPv4I00EN5torch4data7ExampleE)<[Tensor](../aten/tensor.html#_CPPv46Tensorv), Target>

Public Functions

virtual [Tensor](../aten/tensor.html#_CPPv46Tensorv) operator()([Tensor](../aten/tensor.html#_CPPv46Tensorv) input) = 0

Transforms a single input tensor to an output tensor.

inline virtual OutputType apply(InputType input) override

Implementation of `Transform::apply` that calls `operator()`.

## Normalize

Normalizes tensors with a given mean and standard deviation.

template<typename Target = [Tensor](../aten/tensor.html#_CPPv46Tensorv)>
struct Normalize : public torch::data::transforms::TensorTransform<[Tensor](../aten/tensor.html#_CPPv46Tensorv)>

Normalizes input tensors by subtracting the supplied mean and dividing by the given standard deviation.

Public Functions

inline Normalize(ArrayRef<double> mean, ArrayRef<double> stddev)

Constructs a `Normalize` transform.

The mean and standard deviation can be anything that is broadcastable over the input tensors (like single scalars).

inline virtual torch::Tensor operator()([Tensor](../aten/tensor.html#_CPPv46Tensorv) input) override

Transforms a single input tensor to an output tensor.

Public Members

torch::Tensor mean

torch::Tensor stddev

## Stack

Stacks a batch of tensors into a single tensor.

template<typename T = [Example](datasets.html#_CPPv4I00EN5torch4data7ExampleE)<>>
struct Stack

**Example:**

```
auto dataset = torch::data::datasets::MNIST("./data")
 .map(torch::data::transforms::Normalize<>(0.5, 0.5))
 .map(torch::data::transforms::Stack<>());
```

## Lambda

template<typename Input, typename Output = Input>
class Lambda : public torch::data::transforms::Transform<Input, Input>

Public Types

using FunctionType = std::function<Output(Input)>

Public Functions

inline explicit Lambda(FunctionType function)

Constructs the `Lambda` from the given `function` object.

inline virtual OutputType apply(InputType input) override

Applies the user-provided function object to the `input`.

## TensorLambda

template<typename Target = [Tensor](../aten/tensor.html#_CPPv46Tensorv)>
class TensorLambda : public torch::data::transforms::TensorTransform<[Tensor](../aten/tensor.html#_CPPv46Tensorv)>

A `Lambda` specialized for the typical `[Example](datasets.html#PyTorchstructtorch_1_1data_1_1_example)<Tensor, Tensor>` input type.

Public Types

using FunctionType = std::function<[Tensor](../aten/tensor.html#_CPPv46Tensorv)([Tensor](../aten/tensor.html#_CPPv46Tensorv))>

Public Functions

inline explicit TensorLambda(FunctionType function)

Creates a `TensorLambda` from the given `function`.

inline virtual [Tensor](../aten/tensor.html#_CPPv46Tensorv) operator()([Tensor](../aten/tensor.html#_CPPv46Tensorv) input) override

Applies the user-provided functor to the input tensor.

## BatchLambda

template<typename Input, typename Output = Input>
class BatchLambda : public torch::data::transforms::BatchTransform<Input, Input>

A `BatchTransform` that applies a user-provided functor to a batch.

Public Types

using FunctionType = std::function<OutputBatchType(InputBatchType)>

Public Functions

inline explicit BatchLambda(FunctionType function)

Constructs the `BatchLambda` from the given `function` object.

inline virtual OutputBatchType apply_batch(InputBatchType input_batch) override

Applies the user-provided function object to the `input_batch`.

## Chaining Transforms

Transforms can be chained together using `.map()`:

```
auto dataset = torch::data::datasets::MNIST("./data")
 .map(torch::data::transforms::Normalize<>(0.1307, 0.3081))
 .map(torch::data::transforms::Stack<>());
```

---

# C++ API Reference

This section provides reference documentation for the PyTorch C++ API,
organized by module.

Core

- [ATen: Tensor Library](aten/index.html)

- [Header Files](aten/index.html#header-files)
- [ATen Categories](aten/index.html#aten-categories)
- [C10: Core Utilities](c10/index.html)

- [Header Files](c10/index.html#header-files)
- [C10 Categories](c10/index.html#c10-categories)
- [Autograd: Automatic Differentiation](autograd/index.html)

- [Header Files](autograd/index.html#header-files)
- [Autograd Categories](autograd/index.html#autograd-categories)
- [CUDA Support](cuda/index.html)

- [Header Files](cuda/index.html#header-files)
- [CUDA Categories](cuda/index.html#cuda-categories)
- [XPU Support](xpu/index.html)

- [Header Files](xpu/index.html#header-files)
- [XPU Categories](xpu/index.html#xpu-categories)

C++ Frontend

- [Neural Network Modules (torch::nn)](nn/index.html)

- [Header Files](nn/index.html#header-files)
- [Module Base Class](nn/index.html#module-base-class)
- [Module Categories](nn/index.html#module-categories)
- [Optimizers (torch::optim)](optim/index.html)

- [Header Files](optim/index.html#header-files)
- [Optimizer Base Class](optim/index.html#optimizer-base-class)
- [Choosing an Optimizer](optim/index.html#choosing-an-optimizer)
- [Optimizer Categories](optim/index.html#optimizer-categories)
- [Data Loading (torch::data)](data/index.html)

- [Header Files](data/index.html#header-files)
- [Module Categories](data/index.html#module-categories)
- [Serialization (torch::serialize)](serialize/index.html)

- [Header Files](serialize/index.html#header-files)
- [Serialization Categories](serialize/index.html#serialization-categories)

Extensions

- [Torch Library API](library/index.html)

- [Header Files](library/index.html#header-files)
- [Library API Categories](library/index.html#library-api-categories)
- [See Also](library/index.html#see-also)
- [Torch Stable API](stable/index.html)

- [Header Files](stable/index.html#header-files)
- [Stable API Categories](stable/index.html#stable-api-categories)
- [See Also](stable/index.html#see-also)

---

# Custom Classes

PyTorch allows registering custom C++ classes that can be used from Python
and TorchScript.

Header: `torch/custom_class.h`

## class_ Template

template<class CurClass>
class class_ : public torch::detail::class_base

Entry point for custom C++ class registration.

To register a C++ class in PyTorch, instantiate `torch::class_` with the desired class as the template parameter. Typically, this instantiation should be done in the initialization of a global variable, so that the class will be made available on dynamic library loading without any additional API calls needed. For example, to register a class named Foo, you might create a global variable like so:

```
static auto register_foo = torch::class_<Foo>("myclasses", "Foo")
 .def("myMethod", &Foo::myMethod)
 .def("lambdaMethod", [](const c10::intrusive_ptr<Foo>& self) {
 // Do something with `self`
 });
```

 In addition to registering the class, this registration also chains `def()` calls to register methods. `myMethod()` is registered with a pointer to the Foo class's `myMethod()` method. `lambdaMethod()` is registered with a C++ lambda expression. 

Public Functions

inline explicit class_(const std::string &namespaceName, const std::string &className, std::string doc_string = "")

This constructor actually registers the class type.

String argument `namespaceName` is an identifier for the namespace you would like this class to appear in. String argument `className` is the name you would like to see this class exposed as in Python and TorchScript. For example, if you pass `foo` as the namespace name and `Bar` as the className, the class will appear as `torch.classes.foo.Bar` in Python and TorchScript

template<typename ...Types>
inline class_ &def(torch::detail::types<void, Types...>, std::string doc_string = "", std::initializer_list<arg> default_args = {})

def() can be used in conjunction with `torch::init()` to register a constructor for a given C++ class type.

For example, passing `torch::init<int, std::string>()` would register a two-argument constructor taking an `int` and a `std::string` as argument.

template<typename Func, typename ...ParameterTypes>
inline class_ &def(InitLambda<Func, c10::guts::typelist::typelist<ParameterTypes...>> init, std::string doc_string = "", std::initializer_list<arg> default_args = {})

template<typename Func>
inline class_ &def(std::string name, Func f, std::string doc_string = "", std::initializer_list<arg> default_args = {})

This is the normal method registration API.

`name` is the name that the method will be made accessible by in Python and TorchScript. `f` is a callable object that defines the method. Typically `f` will either be a pointer to a method on `CurClass`, or a lambda expression that takes a `c10::intrusive_ptr<CurClass>` as the first argument (emulating a `this` argument in a C++ method.)

Examples:

```
// Exposes method `foo` on C++ class `Foo` as `call_foo()` in
// Python and TorchScript
.def("call_foo", &Foo::foo)

// Exposes the given lambda expression as method `call_lambda()`
// in Python and TorchScript.
.def("call_lambda", [](const c10::intrusive_ptr<Foo>& self) {
 // do something
})
```

template<typename Func>
inline class_ &def_static(std::string name, Func func, std::string doc_string = "", std::initializer_list<arg> default_args = {})

Method registration API for static methods.

template<typename GetterFunc, typename SetterFunc>
inline class_ &def_property(const std::string &name, GetterFunc getter_func, SetterFunc setter_func, std::string doc_string = "")

Property registration API for properties with both getter and setter functions.

template<typename GetterFunc>
inline class_ &def_property(const std::string &name, GetterFunc getter_func, std::string doc_string = "")

Property registration API for properties with only getter function.

template<typename T>
inline class_ &def_readwrite(const std::string &name, T CurClass::* field)

Property registration API for properties with read-write access.

template<typename T>
inline class_ &def_readonly(const std::string &name, T CurClass::* field)

Property registration API for properties with read-only access.

inline class_ &_def_unboxed(const std::string &name, std::function<void(jit::Stack&)> func, c10::FunctionSchema schema, std::string doc_string = "")

This is an unsafe method registration API added for adding custom JIT backend support via custom C++ classes.

It is not for general purpose use.

template<typename GetStateFn, typename SetStateFn>
inline class_ &def_pickle(GetStateFn &&get_state, SetStateFn &&set_state)

def_pickle() is used to define exactly what state gets serialized or deserialized for a given instance of a custom C++ class in Python or TorchScript.

This protocol is equivalent to the Pickle concept of `__getstate__` and `__setstate__` from Python ([https://docs.python.org/2/library/pickle.html#object.__getstate__](https://docs.python.org/2/library/pickle.html#object.__getstate__))

Currently, both the `get_state` and `set_state` callables must be C++ lambda expressions. They should have the following signatures, where `CurClass` is the class you're registering and `T1` is some object that encapsulates the state of the object.

```
__getstate__(intrusive_ptr<CurClass>) -> T1
__setstate__(T2) -> intrusive_ptr<CurClass>
```

`T1` must be an object that is convertible to IValue by the same rules for custom op/method registration.

For the common case, T1 == T2. T1 can also be a subtype of T2. An example where it makes sense for T1 and T2 to differ is if **setstate** handles legacy formats in a backwards compatible way.

Example:

```
.def_pickle(
 // __getstate__
 [](const c10::intrusive_ptr<MyStackClass<std::string>>& self) {
 return self->stack_;
 },
 [](std::vector<std::string> state) { // __setstate__
 return c10::make_intrusive<MyStackClass<std::string>>(
 std::vector<std::string>{"i", "was", "deserialized"});
 })
```

**Example:**

```
#include <torch/custom_class.h>

struct MyClass : torch::CustomClassHolder {
 int value;

 MyClass(int v) : value(v) {}

 int getValue() const { return value; }
 void setValue(int v) { value = v; }
};

TORCH_LIBRARY(my_classes, m) {
 m.class_<MyClass>("MyClass")
 .def(torch::init<int>())
 .def("getValue", &MyClass::getValue)
 .def("setValue", &MyClass::setValue)
 .def_readwrite("value", &MyClass::value);
}
```

## Registering Methods

**Constructor:**

```
m.class_<MyClass>("MyClass")
 .def(torch::init<int>()) // Constructor taking int
```

**Methods:**

```
m.class_<MyClass>("MyClass")
 .def("getValue", &MyClass::getValue)
 .def("setValue", &MyClass::setValue)
```

**Properties:**

```
m.class_<MyClass>("MyClass")
 .def_readwrite("value", &MyClass::value) // Read-write
 .def_readonly("const_value", &MyClass::const_value) // Read-only
```

## Using Custom Classes

**From C++:**

```
auto my_obj = c10::make_intrusive<MyClass>(42);
int val = my_obj->getValue();
```

**From Python:**

```
import torch
torch.classes.load_library("path/to/library.so")
obj = torch.classes.my_classes.MyClass(42)
print(obj.getValue())
```

**In TorchScript:**

```
@torch.jit.script
def use_my_class(x: torch.classes.my_classes.MyClass) -> int:
 return x.getValue()
```

---

# Torch Library API

The Torch Library API provides capabilities for extending PyTorch's core library
of operators with user-defined operators and data types. This is the primary
mechanism for registering custom C++ operators that can be called from both
Python and C++.

**When to use the Library API:**

- When creating custom operators for PyTorch
- When implementing backend-specific kernels (CPU, CUDA, etc.)
- When registering custom classes for use in TorchScript
- When extending PyTorch with new functionality

**Basic usage:**

```
#include <torch/library.h>

// Define a custom operator
torch::Tensor my_add(const torch::Tensor& a, const torch::Tensor& b) {
 return a + b;
}

// Register the operator
TORCH_LIBRARY(myops, m) {
 m.def("add(Tensor a, Tensor b) -> Tensor", &my_add);
}

// Use from C++
auto result = torch::dispatcher::call("myops::add", tensor_a, tensor_b);
```

For a tutorial-style introduction to the library API, check out the
[Extending TorchScript with Custom C++ Operators](https://pytorch.org/tutorials/advanced/torch_script_custom_ops.html)
tutorial.

## Header Files

- `torch/library.h` - Main library API header
- `torch/custom_class.h` - Custom class registration

## Library API Categories

- [Operator Registration](registration.html)
- [Custom Classes](custom_classes.html)
- [Library Versioning](versioning.html)

## See Also

- [Torch Stable API](../stable/index.html) - For stable ABI operator registration

---

# Operator Registration

The library API provides macros and classes for registering custom operators
with PyTorch's dispatcher.

## Macros

### TORCH_LIBRARY

TORCH_LIBRARY(ns, m) static void TORCH_LIBRARY_init_##ns(torch::Library

&); \

static const

torch::detail::TorchLibraryInit

TORCH_LIBRARY_static_init_##ns( \

torch::Library::DEF, \

&TORCH_LIBRARY_init_##ns, \

C10_STRINGIZE(ns), \

std::nullopt, \

__FILE__, \

__LINE__); \

void TORCH_LIBRARY_init_##ns(

torch::Library& m)

Macro for defining a function that will be run at static initialization time to define a library of operators in the namespace `ns` (must be a valid C++ identifier, no quotes).

Use this macro when you want to define a new set of custom operators that do not already exist in PyTorch.

Example usage:

```
TORCH_LIBRARY(myops, m) {
 // m is a torch::Library; methods on it will define
 // operators in the myops namespace
 m.def("add", add_impl);
}
```

The `m` argument is bound to a torch::Library that is used to register operators. There may only be one TORCH_LIBRARY() for any given namespace.

**Example:**

```
TORCH_LIBRARY(myops, m) {
 m.def("add(Tensor self, Tensor other) -> Tensor", &add_impl);
 m.def("mul(Tensor self, Tensor other) -> Tensor");
 m.impl("mul", torch::kCPU, &mul_cpu_impl);
 m.impl("mul", torch::kCUDA, &mul_cuda_impl);
}
```

### TORCH_LIBRARY_IMPL

TORCH_LIBRARY_IMPL(ns, k, m) _TORCH_LIBRARY_IMPL(ns, k, m, C10_UID)

Macro for defining a function that will be run at static initialization time to define operator overrides for dispatch key `k` (must be an unqualified enum member of c10::DispatchKey) in namespace `ns` (must be a valid C++ identifier, no quotes).

Use this macro when you want to implement a preexisting set of custom operators on a new dispatch key (e.g., you want to provide CUDA implementations of already existing operators). One common usage pattern is to use TORCH_LIBRARY() to define schema for all new operators you want to define, and then use several TORCH_LIBRARY_IMPL() blocks to provide implementations of the operator for CPU, CUDA and Autograd.

In some cases, you need to define something that applies to all namespaces, not just one namespace (usually a fallback). In that case, use the reserved namespace _, e.g.,

```
TORCH_LIBRARY_IMPL(_, XLA, m) {
 m.fallback(xla_fallback);
}
```

Example usage:

```
TORCH_LIBRARY_IMPL(myops, CPU, m) {
 // m is a torch::Library; methods on it will define
 // CPU implementations of operators in the myops namespace.
 // It is NOT valid to call torch::Library::def()
 // in this context.
 m.impl("add", add_cpu_impl);
}
```

If `add_cpu_impl` is an overloaded function, use a `static_cast` to specify which overload you want (by providing the full type).

**Example:**

```
TORCH_LIBRARY_IMPL(myops, XLA, m) {
 m.impl("mul", &mul_xla_impl);
}
```

### TORCH_LIBRARY_FRAGMENT

TORCH_LIBRARY_FRAGMENT(ns, m) _TORCH_LIBRARY_FRAGMENT(ns, m, C10_UID)

This macro is a version of TORCH_LIBRARY() that doesn't enforce that there is only one library (it is a "fragment").

This is used inside the PerOpRegistration.cpp file, as well as in places where all op registrations within the same namespace cannot be easily put into one macro block (this is mostly the case for custom ops in fbcode that were ported from the old API)

**Example:**

```
// In file1.cpp
TORCH_LIBRARY(myops, m) {
 m.def("add(Tensor self, Tensor other) -> Tensor", &add_impl);
}

// In file2.cpp
TORCH_LIBRARY_FRAGMENT(myops, m) {
 m.def("mul(Tensor self, Tensor other) -> Tensor", &mul_impl);
}
```

## Classes

### Library

class Library

This object provides the API for defining operators and providing implementations at dispatch keys.

Typically, a torch::Library is not allocated directly; instead it is created by the TORCH_LIBRARY() or TORCH_LIBRARY_IMPL() macros.

Most methods on torch::Library return a reference to itself, supporting method chaining.

```
// Examples:

TORCH_LIBRARY(torchvision, m) {
 // m is a torch::Library
 m.def("roi_align", ...);
 ...
}

TORCH_LIBRARY_IMPL(aten, XLA, m) {
 // m is a torch::Library
 m.impl("add", ...);
 ...
}
```

Public Functions

Library(const Library&) = delete

Library &operator=(const Library&) = delete

Library(Library&&) = default

Library &operator=(Library&&) = default

~Library() = default

inline Library &def(c10::FunctionSchema &&s, const std::vector<at::Tag> &tags = {}, _RegisterOrVerify rv = _RegisterOrVerify::REGISTER) &

Declare an operator with a schema, but don't provide any implementations for it.

You're expected to then provide implementations using the impl() method. All template arguments are inferred.

```
// Example:
TORCH_LIBRARY(myops, m) {
 m.def("add(Tensor self, Tensor other) -> Tensor");
}
```

Parameters:

**raw_schema** - The schema of the operator to be defined. Typically, this is a `const char*` string literal, but any type accepted by torch::schema() is accepted here.

inline Library &def(const char *raw_schema, const std::vector<at::Tag> &tags = {}, _RegisterOrVerify rv = _RegisterOrVerify::REGISTER) &

inline Library &set_python_module(const char *pymodule, const char *context = "")

Declares that for all operators that are subsequently def'ed, their fake impls may be found in the given Python module (pymodule).

This registers some help text that is used if the fake impl cannot be found.

Args:

- pymodule: the python module
- context: We may include this in the error message.

inline Library &impl_abstract_pystub(const char *pymodule, const char *context = "")

Deprecated; use set_python_module instead.

template<typename NameOrSchema, typename Func>
inline Library &def(NameOrSchema &&raw_name_or_schema, Func &&raw_f, const std::vector<at::Tag> &tags = {}) &

Define an operator for a schema and then register an implementation for it.

This is typically what you would use if you aren't planning on making use of the dispatcher to structure your operator implementation. It's roughly equivalent to calling def() and then impl(), but if you omit the schema of the operator, we will infer it from the type of your C++ function. All template arguments are inferred.

```
// Example:
TORCH_LIBRARY(myops, m) {
 m.def("add", add_fn);
}
```

Parameters:

- **raw_name_or_schema** - The schema of the operator to be defined, or just the name of the operator if the schema is to be inferred from `raw_f`. Typically a `const char*` literal.
- **raw_f** - The C++ function that implements this operator. Any valid constructor of torch::CppFunction is accepted here; typically you provide a function pointer or lambda.

template<typename Name, typename Func>
inline Library &impl(Name name, Func &&raw_f, _RegisterOrVerify rv = _RegisterOrVerify::REGISTER) &

Register an implementation for an operator.

You may register multiple implementations for a single operator at different dispatch keys (see torch::dispatch()). Implementations must have a corresponding declaration (from def()), otherwise they are invalid. If you plan to register multiple implementations, DO NOT provide a function implementation when you def() the operator.

```
// Example:
TORCH_LIBRARY_IMPL(myops, CUDA, m) {
 m.impl("add", add_cuda);
}
```

Parameters:

- **name** - The name of the operator to implement. Do NOT provide schema here.
- **raw_f** - The C++ function that implements this operator. Any valid constructor of torch::CppFunction is accepted here; typically you provide a function pointer or lambda.

c10::OperatorName _resolve(const char *name) const

template<typename Name, typename Func>
inline Library &impl_UNBOXED(Name, Func*) &

inline Library &def(detail::SelectiveStr<false>, const std::vector<at::Tag> &tags[`[maybe_unused]`] = {}) &

inline Library &def(detail::SelectiveStr<true> raw_schema, const std::vector<at::Tag> &tags = {}) &

template<typename Func>
inline Library &def(detail::SelectiveStr<false>, Func&&, const std::vector<at::Tag> &tags[`[maybe_unused]`] = {}) &

template<typename Func>
inline Library &def(detail::SelectiveStr<true> raw_name_or_schema, Func &&raw_f, const std::vector<at::Tag> &tags = {}) &

template<typename Func>
inline Library &impl(detail::SelectiveStr<false>, Func&&) &

template<typename Dispatch, typename Func>
inline Library &impl(detail::SelectiveStr<false>, Dispatch&&, Func&&) &

template<typename Func>
inline Library &impl_UNBOXED(detail::SelectiveStr<false>, Func*) &

template<typename Func>
inline Library &impl(detail::SelectiveStr<true> name, Func &&raw_f) &

template<typename Dispatch, typename Func>
inline Library &impl(detail::SelectiveStr<true> name, Dispatch &&key, Func &&raw_f) &

template<typename Func>
inline Library &impl_UNBOXED(detail::SelectiveStr<true>, Func*) &

template<typename Func>
inline Library &fallback(Func &&raw_f) &

Register a fallback implementation for all operators which will be used if there is not a specific implementation for an operator available.

There MUST be a DispatchKey associated with a fallback; e.g., only call this from TORCH_LIBRARY_IMPL() with namespace `_`.

```
// Example:

TORCH_LIBRARY_IMPL(_, AutogradXLA, m) {
 // If there is not a kernel explicitly registered
 // for AutogradXLA, fallthrough to the next
 // available kernel
 m.fallback(torch::CppFunction::makeFallthrough());
}

// See aten/src/ATen/core/dispatch/backend_fallback_test.cpp
// for a full example of boxed fallback
```

Parameters:

**raw_f** - The function that implements the fallback. Unboxed functions typically do not work as fallback functions, as fallback functions must work for every operator (even though they have varying type signatures). Typical arguments are CppFunction::makeFallthrough() or CppFunction::makeFromBoxedFunction()

template<class CurClass>
inline torch::[class_](custom_classes.html#_CPPv4I0EN5torch6class_E)<CurClass> class_(const std::string &className)

template<class CurClass>
inline torch::[class_](custom_classes.html#_CPPv4I0EN5torch6class_E)<CurClass> class_(detail::SelectiveStr<true> className)

template<class CurClass>
inline detail::ClassNotSelected class_(detail::SelectiveStr<false> className)

void reset()

template<class CurClass>
inline class_<CurClass> class_(const std::string &className)

template<class CurClass>
inline class_<CurClass> class_(detail::SelectiveStr<true> className)

Friends

*friend class* detail::TorchLibraryInit

**Example:**

```
TORCH_LIBRARY(myops, m) {
 // Define with implementation
 m.def("add(Tensor self, Tensor other) -> Tensor", &add_impl);

 // Define schema only
 m.def("mul(Tensor self, Tensor other) -> Tensor");

 // Provide backend-specific implementations
 m.impl("mul", torch::kCPU, &mul_cpu_impl);
 m.impl("mul", torch::kCUDA, &mul_cuda_impl);
}
```

### CppFunction

class CppFunction

Represents a C++ function that implements an operator.

Most users won't interact directly with this class, except via error messages: the constructors this function define the set of permissible "function"-like things you can bind via the interface.

This class erases the type of the passed in function, but durably records the type via an inferred schema for the function.

Public Functions

template<typename Func>
inline explicit CppFunction(Func *f, std::enable_if_t<c10::guts::is_function_type<Func>::value, std::nullptr_t> = nullptr)

This overload accepts function pointers, e.g., `CppFunction(&add_impl)`

template<typename FuncPtr>
inline explicit CppFunction(FuncPtr f, std::enable_if_t<c10::is_compile_time_function_pointer<FuncPtr>::value, std::nullptr_t> = nullptr)

This overload accepts compile time function pointers, e.g., `CppFunction(TORCH_FN(add_impl))`

template<typename Lambda>
inline explicit CppFunction(Lambda &&f, std::enable_if_t<c10::guts::is_functor<std::decay_t<Lambda>>::value, std::nullptr_t> = nullptr)

This overload accepts lambdas, e.g., `CppFunction([](const Tensor& self) { ...`

})

~CppFunction()

CppFunction(const CppFunction&) = delete

CppFunction &operator=(const CppFunction&) = delete

CppFunction(CppFunction&&) noexcept = default

CppFunction &operator=(CppFunction&&) = default

inline CppFunction &&debug(std::string d) &&

Public Static Functions

static inline CppFunction makeFallthrough()

This creates a fallthrough function.

Fallthrough functions immediately redispatch to the next available dispatch key, but are implemented more efficiently than a hand written function done in the same way.

template<c10::BoxedKernel::BoxedKernelFunction *func>
static inline CppFunction makeFromBoxedFunction()

Create a function from a boxed kernel function with signature `void(const OperatorHandle&, Stack*)`; i.e., they receive a stack of arguments in a boxed calling convention, rather than in the native C++ calling convention.

Boxed functions are typically only used to register backend fallbacks via torch::Library::fallback().

template<c10::BoxedKernel::BoxedKernelFunction_withDispatchKeys *func>
static inline CppFunction makeFromBoxedFunction()

template<class KernelFunctor>
static inline CppFunction makeFromBoxedFunctor(std::unique_ptr<KernelFunctor> kernelFunctor)

Create a function from a boxed kernel functor which defines `operator()(const OperatorHandle&, DispatchKeySet, Stack*)` (receiving arguments from boxed calling convention) and inherits from `c10::OperatorKernel`.

Unlike makeFromBoxedFunction, functions registered in this way can also carry additional state which is managed by the functor; this is useful if you're writing an adapter to some other implementation, e.g., a Python callable, which is dynamically associated with the registered kernel.

template<typename FuncPtr, std::enable_if_t<c10::guts::is_function_type<FuncPtr>::value, std::nullptr_t> = nullptr>
static inline CppFunction makeFromUnboxedFunction(FuncPtr *f)

Create a function from an unboxed kernel function.

This is typically used to register common operators.

template<typename FuncPtr, std::enable_if_t<c10::is_compile_time_function_pointer<FuncPtr>::value, std::nullptr_t> = nullptr>
static inline CppFunction makeFromUnboxedFunction(FuncPtr f)

Create a function from a compile time unboxed kernel function pointer.

This is typically used to register common operators. Compile time function pointers can be used to allow the compiler to optimize (e.g. inline) calls to it.

### OrderedDict

template<typename Key, typename Value>
class OrderedDict

An ordered dictionary implementation, akin to Python's `OrderedDict`.

Public Types

using Iterator = typename std::vector<Item>::iterator

using ConstIterator = typename std::vector<Item>::const_iterator

Public Functions

explicit OrderedDict(std::string key_description = "Key")

Constructs the `OrderedDict` with a short description of the kinds of keys stored in the `OrderedDict`.

This description is used in error messages thrown by the `OrderedDict`.

OrderedDict(const OrderedDict &other)

Copy constructs this `OrderedDict` from `other`.

OrderedDict &operator=(const OrderedDict &other)

Assigns items from `other` to this `OrderedDict`.

OrderedDict(OrderedDict &&other) noexcept = default

OrderedDict &operator=(OrderedDict &&other) noexcept = default

~OrderedDict() = default

OrderedDict(std::initializer_list<Item> initializer_list)

Constructs a new `OrderedDict` and pre-populates it with the given `Item`s.

const std::string &key_description() const noexcept

Returns the key description string the `OrderedDict` was constructed with.

Item &front()

Returns the very first item in the `OrderedDict` and throws an exception if it is empty.

const Item &front() const

Returns the very first item in the `OrderedDict` and throws an exception if it is empty.

Item &back()

Returns the very last item in the `OrderedDict` and throws an exception if it is empty.

const Item &back() const

Returns the very last item in the `OrderedDict` and throws an exception if it is empty.

Item &operator[](size_t index)

Returns the item at the `index`-th position in the `OrderedDict`.

Throws an exception if the index is out of bounds.

const Item &operator[](size_t index) const

Returns the item at the `index`-th position in the `OrderedDict`.

Throws an exception if the index is out of bounds.

Value &operator[](const Key &key)

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `OrderedDict`. Use `find()` for a non-throwing way of accessing a value if it is present.

const Value &operator[](const Key &key) const

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `OrderedDict`. Use `find()` for a non-throwing way of accessing a value if it is present.

Value *find(const Key &key) noexcept

Returns a pointer to the value associated with the given key, or a `nullptr` if no such key is stored in the `OrderedDict`.

const Value *find(const Key &key) const noexcept

Returns a pointer to the value associated with the given key, or a `nullptr` if no such key is stored in the `OrderedDict`.

bool contains(const Key &key) const noexcept

Returns true if the key is present in the `OrderedDict`.

Iterator begin()

Returns an iterator to the first item in the `OrderedDict`.

Iteration is ordered.

ConstIterator begin() const

Returns an iterator to the first item in the `OrderedDict`.

Iteration is ordered.

Iterator end()

Returns an iterator one past the last item in the `OrderedDict`.

ConstIterator end() const

Returns an iterator one past the last item in the `OrderedDict`.

size_t size() const noexcept

Returns the number of items currently stored in the `OrderedDict`.

bool is_empty() const noexcept

Returns true if the `OrderedDict` contains no elements.

void reserve(size_t requested_capacity)

Resizes internal storage to fit at least `requested_capacity` items without requiring reallocation.

template<typename K, typename V>
Value &insert(K &&key, V &&value)

Inserts a new `(key, value)` pair into the `OrderedDict`.

Throws an exception if the key is already present. If insertion is successful, immediately returns a reference to the inserted value.

Value &insert(Key key, Value &&value)

Inserts a new `(key, value)` pair into the `OrderedDict`.

Throws an exception if the key is already present. If insertion is successful, immediately returns a reference to the inserted value.

void update(OrderedDict &&other)

Inserts all items from `other` into this `OrderedDict`.

If any key from `other` is already present in this `OrderedDict`, an exception is thrown.

void update(const OrderedDict &other)

Inserts all items from `other` into this `OrderedDict`.

If any key from `other` is already present in this `OrderedDict`, an exception is thrown.

void erase(const Key &key)

Removes the item that has `key` from this `OrderedDict` if exists and if it doesn't an exception is thrown.

void clear()

Removes all items from this `OrderedDict`.

const std::vector<Item> &items() const noexcept

Returns the items stored in the `OrderedDict`.

::std::vector<Key> keys() const

Returns a newly allocated vector and copies all keys from this `OrderedDict` into the vector.

::std::vector<Value> values() const

Returns a newly allocated vector and copies all values from this `OrderedDict` into the vector.

::std::vector<std::pair<Key, Value>> pairs() const

Returns a newly allocated vector and copies all keys and values from this `OrderedDict` into a vector of `std::pair<Key, Value>`.

Friends

template<typename K, typename V>
friend bool operator==(const OrderedDict<K, V> &a, const OrderedDict<K, V> &b)

Returns true if both dicts contain the same keys and values, in the same order.

class Item

Public Functions

inline Item(Key key, Value value)

Constructs a new item.

inline Value &operator*()

Returns a reference to the value.

inline const Value &operator*() const

Returns a reference to the value.

inline Value *operator->()

Allows access to the value using the arrow operator.

inline const Value *operator->() const

Allows access to the value using the arrow operator.

inline const Key &key() const noexcept

Returns a reference to the key.

inline Value &value() noexcept

Returns a reference to the value.

inline const Value &value() const noexcept

Returns a reference to the value.

inline const std::pair<Key, Value> &pair() const noexcept

Returns a `(key, value)` pair.

## Functions

The library API provides builder methods on the `Library` class for registering
operators. See the `Library` class documentation above for the full API including
`def()`, `impl()`, and `fallback()` methods.

## Dispatch Keys

Common dispatch keys used with `torch::dispatch()`:

- `torch::kCPU` - CPU backend
- `torch::kCUDA` - CUDA backend
- `torch::kAutograd` - Autograd backend
- `torch::kMeta` - Meta tensor backend

---

# Library Versioning

PyTorch provides version number macros for identifying the version of LibTorch in use.

**Example:**

```
#include <torch/torch.h>
#include <iostream>

int main() {
 std::cout << "PyTorch version from parts: "
 << TORCH_VERSION_MAJOR << "."
 << TORCH_VERSION_MINOR << "."
 << TORCH_VERSION_PATCH << std::endl;
 std::cout << "PyTorch version: " << TORCH_VERSION << std::endl;
}
```

This will output something like:

```
PyTorch version from parts: 1.8.0
PyTorch version: 1.8.0
```

Note

These macros are only available in PyTorch >= 1.8.0.

## Version Macros

- `TORCH_VERSION_MAJOR` - Major version number
- `TORCH_VERSION_MINOR` - Minor version number
- `TORCH_VERSION_PATCH` - Patch version number
- `TORCH_VERSION` - Full version string (e.g., "1.8.0")

---

# Activation Functions

Activation functions introduce non-linearity into neural networks, allowing them
to learn complex patterns. Without activations, stacked linear layers would collapse
into a single linear transformation.

**Common choices:**

- **ReLU family** (ReLU, LeakyReLU, PReLU, RReLU): Fast, widely used, good default choice
- **ELU family** (ELU, SELU, CELU): Smoother than ReLU, can produce negative outputs
- **GELU/SiLU/Mish**: Modern activations popular in transformers and advanced architectures
- **Sigmoid/Tanh**: Classic activations, useful for output layers (probabilities, bounded outputs)
- **Softmax**: Converts logits to probability distribution (classification output)

## ReLU

class ReLU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ReLUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ReLUImpl`.

See the documentation for `ReLUImpl` class to learn what methods it provides, and examples of how to use `ReLU` with `torch::nn::ReLUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReLUImpl

class ReLUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<ReLUImpl>

Applies the ReLU function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.ReLU](https://pytorch.org/docs/main/nn.html#torch.nn.ReLU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ReLUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
ReLU model(ReLUOptions().inplace(true));
```

Public Functions

explicit ReLUImpl(const ReLUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `ReLU` module into the given `stream`.

Public Members

ReLUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

**Example:**

```
auto relu = torch::nn::ReLU(torch::nn::ReLUOptions().inplace(true));
```

## LeakyReLU

class LeakyReLU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LeakyReLUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LeakyReLUImpl`.

See the documentation for `LeakyReLUImpl` class to learn what methods it provides, and examples of how to use `LeakyReLU` with `torch::nn::LeakyReLUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LeakyReLUImpl

class LeakyReLUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<LeakyReLUImpl>

Applies the LeakyReLU function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LeakyReLU](https://pytorch.org/docs/main/nn.html#torch.nn.LeakyReLU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LeakyReLUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LeakyReLU model(LeakyReLUOptions().negative_slope(0.42).inplace(true));
```

Public Functions

explicit LeakyReLUImpl(const LeakyReLUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `LeakyReLU` module into the given `stream`.

Public Members

LeakyReLUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## PReLU

class PReLU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<PReLUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `PReLUImpl`.

See the documentation for `PReLUImpl` class to learn what methods it provides, and examples of how to use `PReLU` with `torch::nn::PReLUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = PReLUImpl

class PReLUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<PReLUImpl>

Applies the PReLU function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.PReLU](https://pytorch.org/docs/main/nn.html#torch.nn.PReLU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::PReLUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
PReLU model(PReLUOptions().num_parameters(42));
```

Public Functions

explicit PReLUImpl(const PReLUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `PReLU` module into the given `stream`.

Public Members

PReLUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The learned weight.

## RReLU

class RReLU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<RReLUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `RReLUImpl`.

See the documentation for `RReLUImpl` class to learn what methods it provides, and examples of how to use `RReLU` with `torch::nn::RReLUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = RReLUImpl

class RReLUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<RReLUImpl>

Applies the RReLU function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.RReLU](https://pytorch.org/docs/main/nn.html#torch.nn.RReLU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::RReLUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
RReLU model(RReLUOptions().lower(0.24).upper(0.42).inplace(true));
```

Public Functions

explicit RReLUImpl(const RReLUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `RReLU` module into the given `stream`.

Public Members

RReLUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## ReLU6

Like ReLU but caps the output at 6: `min(max(0, x), 6)`. Commonly used in
mobile architectures (MobileNet).

class ReLU6 : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ReLU6Impl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ReLU6Impl`.

See the documentation for `ReLU6Impl` class to learn what methods it provides, and examples of how to use `ReLU6` with `torch::nn::ReLU6Options`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReLU6Impl

class ReLU6Impl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<ReLU6Impl>

Applies the ReLU6 function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.ReLU6](https://pytorch.org/docs/main/nn.html#torch.nn.ReLU6) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ReLU6Options` class to learn what constructor arguments are supported for this module.

Example:

```
ReLU6 model(ReLU6Options().inplace(true));
```

Public Functions

explicit ReLU6Impl(const ReLU6Options &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `ReLU6` module into the given `stream`.

Public Members

ReLU6Options options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## GLU

Gated Linear Unit. Splits the input tensor in half along a dimension,
then applies `a * sigmoid(b)`.

class GLU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<GLUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `GLUImpl`.

See the documentation for `GLUImpl` class to learn what methods it provides, and examples of how to use `GLU` with `torch::nn::GLUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = GLUImpl

class GLUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<GLUImpl>

Applies glu over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.GLU](https://pytorch.org/docs/main/nn.html#torch.nn.GLU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::GLUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
GLU model(GLUOptions(1));
```

Public Functions

explicit GLUImpl(const GLUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `GLU` module into the given `stream`.

Public Members

GLUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## LogSigmoid

Applies element-wise `log(sigmoid(x))`. Numerically more stable than
computing `log` and `sigmoid` separately.

class LogSigmoid : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LogSigmoidImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LogSigmoidImpl`.

See the documentation for `LogSigmoidImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LogSigmoidImpl

class LogSigmoidImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<LogSigmoidImpl>

Applies the LogSigmoid function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LogSigmoid](https://pytorch.org/docs/main/nn.html#torch.nn.LogSigmoid) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `LogSigmoid` module into the given `stream`.

## ELU

class ELU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ELUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ELUImpl`.

See the documentation for `ELUImpl` class to learn what methods it provides, and examples of how to use `ELU` with `torch::nn::ELUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ELUImpl

class ELUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<ELUImpl>

Applies elu over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.ELU](https://pytorch.org/docs/main/nn.html#torch.nn.ELU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ELUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
ELU model(ELUOptions().alpha(42.42).inplace(true));
```

Public Functions

explicit ELUImpl(const ELUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `ELU` module into the given `stream`.

Public Members

ELUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## SELU

class SELU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SELUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SELUImpl`.

See the documentation for `SELUImpl` class to learn what methods it provides, and examples of how to use `SELU` with `torch::nn::SELUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SELUImpl

class SELUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SELUImpl>

Applies the selu function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.SELU](https://pytorch.org/docs/main/nn.html#torch.nn.SELU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SELUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
SELU model(SELUOptions().inplace(true));
```

Public Functions

explicit SELUImpl(const SELUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `SELU` module into the given `stream`.

Public Members

SELUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## CELU

class CELU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<CELUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `CELUImpl`.

See the documentation for `CELUImpl` class to learn what methods it provides, and examples of how to use `CELU` with `torch::nn::CELUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = CELUImpl

class CELUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<CELUImpl>

Applies celu over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.CELU](https://pytorch.org/docs/main/nn.html#torch.nn.CELU) to learn about the exact behavior of this module.

See the documentation for `torch::nn::CELUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
CELU model(CELUOptions().alpha(42.42).inplace(true));
```

Public Functions

explicit CELUImpl(const CELUOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `CELU` module into the given `stream`.

Public Members

CELUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## GELU

class GELU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<GELUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `GELUImpl`.

See the documentation for `GELUImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = GELUImpl

class GELUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<GELUImpl>

Applies gelu over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.GELU](https://pytorch.org/docs/main/nn.html#torch.nn.GELU) to learn about the exact behavior of this module.

Public Functions

explicit GELUImpl(GELUOptions options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `GELU` module into the given `stream`.

Public Members

GELUOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## SiLU (Swish)

class SiLU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SiLUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SiLUImpl`.

See the documentation for `SiLUImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SiLUImpl

class SiLUImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SiLUImpl>

Applies silu over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.SiLU](https://pytorch.org/docs/main/nn.html#torch.nn.SiLU) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `SiLU` module into the given `stream`.

## Mish

class Mish : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MishImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MishImpl`.

See the documentation for `MishImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MishImpl

class MishImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MishImpl>

Applies mish over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Mish](https://pytorch.org/docs/main/nn.html#torch.nn.Mish) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Mish` module into the given `stream`.

## Sigmoid

class Sigmoid : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SigmoidImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SigmoidImpl`.

See the documentation for `SigmoidImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SigmoidImpl

class SigmoidImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SigmoidImpl>

Applies sigmoid over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Sigmoid](https://pytorch.org/docs/main/nn.html#torch.nn.Sigmoid) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Sigmoid` module into the given `stream`.

## Tanh

class Tanh : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TanhImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TanhImpl`.

See the documentation for `TanhImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TanhImpl

class TanhImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TanhImpl>

Applies Tanh over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Tanh](https://pytorch.org/docs/main/nn.html#torch.nn.Tanh) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Tanh` module into the given `stream`.

## Softmax

class Softmax : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SoftmaxImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SoftmaxImpl`.

See the documentation for `SoftmaxImpl` class to learn what methods it provides, and examples of how to use `Softmax` with `torch::nn::SoftmaxOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SoftmaxImpl

class SoftmaxImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SoftmaxImpl>

Applies the Softmax function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Softmax](https://pytorch.org/docs/main/nn.html#torch.nn.Softmax) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SoftmaxOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Softmax model(SoftmaxOptions(1));
```

Public Functions

inline explicit SoftmaxImpl(int64_t dim)

explicit SoftmaxImpl(const SoftmaxOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Softmax` module into the given `stream`.

Public Members

SoftmaxOptions options

**Example:**

```
auto softmax = torch::nn::Softmax(torch::nn::SoftmaxOptions(/*dim=*/1));
```

## Softmax2d

Applies `Softmax` over features to each spatial location in a 4D input
tensor of shape `(N, C, H, W)`.

class Softmax2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<Softmax2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `Softmax2dImpl`.

See the documentation for `Softmax2dImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = Softmax2dImpl

class Softmax2dImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<Softmax2dImpl>

Applies the Softmax2d function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Softmax2d](https://pytorch.org/docs/main/nn.html#torch.nn.Softmax2d) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Softmax2d` module into the given `stream`.

## LogSoftmax

class LogSoftmax : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LogSoftmaxImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LogSoftmaxImpl`.

See the documentation for `LogSoftmaxImpl` class to learn what methods it provides, and examples of how to use `LogSoftmax` with `torch::nn::LogSoftmaxOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LogSoftmaxImpl

class LogSoftmaxImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<LogSoftmaxImpl>

Applies the LogSoftmax function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LogSoftmax](https://pytorch.org/docs/main/nn.html#torch.nn.LogSoftmax) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LogSoftmaxOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LogSoftmax model(LogSoftmaxOptions(1));
```

Public Functions

inline explicit LogSoftmaxImpl(int64_t dim)

explicit LogSoftmaxImpl(const LogSoftmaxOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `LogSoftmax` module into the given `stream`.

Public Members

LogSoftmaxOptions options

## Softmin

class Softmin : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SoftminImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SoftminImpl`.

See the documentation for `SoftminImpl` class to learn what methods it provides, and examples of how to use `Softmin` with `torch::nn::SoftminOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SoftminImpl

class SoftminImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SoftminImpl>

Applies the Softmin function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Softmin](https://pytorch.org/docs/main/nn.html#torch.nn.Softmin) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SoftminOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Softmin model(SoftminOptions(1));
```

Public Functions

inline explicit SoftminImpl(int64_t dim)

explicit SoftminImpl(const SoftminOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Softmin` module into the given `stream`.

Public Members

SoftminOptions options

## Softplus

class Softplus : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SoftplusImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SoftplusImpl`.

See the documentation for `SoftplusImpl` class to learn what methods it provides, and examples of how to use `Softplus` with `torch::nn::SoftplusOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SoftplusImpl

class SoftplusImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SoftplusImpl>

Applies softplus over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Softplus](https://pytorch.org/docs/main/nn.html#torch.nn.Softplus) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SoftplusOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Softplus model(SoftplusOptions().beta(0.24).threshold(42.42));
```

Public Functions

explicit SoftplusImpl(const SoftplusOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Softplus` module into the given `stream`.

Public Members

SoftplusOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## Softshrink

class Softshrink : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SoftshrinkImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SoftshrinkImpl`.

See the documentation for `SoftshrinkImpl` class to learn what methods it provides, and examples of how to use `Softshrink` with `torch::nn::SoftshrinkOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SoftshrinkImpl

class SoftshrinkImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SoftshrinkImpl>

Applies the soft shrinkage function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Softshrink](https://pytorch.org/docs/main/nn.html#torch.nn.Softshrink) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SoftshrinkOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Softshrink model(SoftshrinkOptions(42.42));
```

Public Functions

explicit SoftshrinkImpl(const SoftshrinkOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Softshrink` module into the given `stream`.

Public Members

SoftshrinkOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## Softsign

class Softsign : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SoftsignImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SoftsignImpl`.

See the documentation for `SoftsignImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SoftsignImpl

class SoftsignImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SoftsignImpl>

Applies Softsign over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Softsign](https://pytorch.org/docs/main/nn.html#torch.nn.Softsign) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Softsign` module into the given `stream`.

## Hardshrink

class Hardshrink : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<HardshrinkImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `HardshrinkImpl`.

See the documentation for `HardshrinkImpl` class to learn what methods it provides, and examples of how to use `Hardshrink` with `torch::nn::HardshrinkOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = HardshrinkImpl

class HardshrinkImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<HardshrinkImpl>

Applies the hard shrinkage function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Hardshrink](https://pytorch.org/docs/main/nn.html#torch.nn.Hardshrink) to learn about the exact behavior of this module.

See the documentation for `torch::nn::HardshrinkOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Hardshrink model(HardshrinkOptions().lambda(42.42));
```

Public Functions

explicit HardshrinkImpl(const HardshrinkOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Hardshrink` module into the given `stream`.

Public Members

HardshrinkOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## Hardtanh

class Hardtanh : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<HardtanhImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `HardtanhImpl`.

See the documentation for `HardtanhImpl` class to learn what methods it provides, and examples of how to use `Hardtanh` with `torch::nn::HardtanhOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = HardtanhImpl

class HardtanhImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<HardtanhImpl>

Applies the HardTanh function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Hardtanh](https://pytorch.org/docs/main/nn.html#torch.nn.Hardtanh) to learn about the exact behavior of this module.

See the documentation for `torch::nn::HardtanhOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Hardtanh
model(HardtanhOptions().min_val(-42.42).max_val(0.42).inplace(true));
```

Public Functions

explicit HardtanhImpl(const HardtanhOptions &options_ = {})

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Hardtanh` module into the given `stream`.

Public Members

HardtanhOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## Tanhshrink

class Tanhshrink : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TanhshrinkImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TanhshrinkImpl`.

See the documentation for `TanhshrinkImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TanhshrinkImpl

class TanhshrinkImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TanhshrinkImpl>

Applies Tanhshrink over a given input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Tanhshrink](https://pytorch.org/docs/main/nn.html#torch.nn.Tanhshrink) to learn about the exact behavior of this module.

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Tanhshrink` module into the given `stream`.

## Threshold

class Threshold : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ThresholdImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ThresholdImpl`.

See the documentation for `ThresholdImpl` class to learn what methods it provides, and examples of how to use `Threshold` with `torch::nn::ThresholdOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ThresholdImpl

class ThresholdImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<ThresholdImpl>

Applies the Threshold function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Threshold](https://pytorch.org/docs/main/nn.html#torch.nn.Threshold) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ThresholdOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Threshold model(ThresholdOptions(42.42, 24.24).inplace(true));
```

Public Functions

inline ThresholdImpl(double threshold, double value)

explicit ThresholdImpl(const ThresholdOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Threshold` module into the given `stream`.

Public Members

ThresholdOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

---

# Containers

Container modules hold other modules and define how they are composed together.
Use containers to build complex architectures from simpler building blocks.

- **Sequential**: Chain modules in order, output of one feeds into the next
- **ModuleList**: Store modules in a list for iteration (not auto-forwarded)
- **ModuleDict**: Store modules in a dictionary for named access
- **ParameterList/ParameterDict**: Store parameters directly without wrapping in modules

Note

PyTorch's C++ API uses the PIMPL (Pointer to Implementation) pattern. You create
modules using the public class name (e.g., `torch::nn::Sequential`), which
internally wraps an implementation class (`SequentialImpl`). The documentation
below shows the implementation classes, which contain all the actual methods.

## Sequential

`Sequential` is a container that chains modules together. Each module's output
becomes the next module's input. This is the simplest way to build feed-forward
networks.

class Sequential : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SequentialImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SequentialImpl`.

See the documentation for `SequentialImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Functions

Sequential() = default

inline Sequential(std::initializer_list<NamedAnyModule> named_modules)

Constructs the `Sequential` from a braced-init-list of named `[AnyModule](utilities.html#PyTorchclasstorch_1_1nn_1_1_any_module)`s.

It enables the following use case: `Sequential sequential({{"m1", M(1)}, {"m2", M(2)}})`

**Example:**

```
torch::nn::Sequential seq(
 torch::nn::Conv2d(torch::nn::Conv2dOptions(1, 32, 3)),
 torch::nn::ReLU(),
 torch::nn::Conv2d(torch::nn::Conv2dOptions(32, 64, 3)),
 torch::nn::ReLU()
);

auto output = seq->forward(input);
```

## ModuleList

`ModuleList` stores modules in a list for indexed or iterated access. Unlike
`Sequential`, it does not have a built-in `forward()` method--you control how
modules are called.

class ModuleList : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ModuleListImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ModuleListImpl`.

See the documentation for `ModuleListImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ModuleListImpl

**Example:**

```
torch::nn::ModuleList layers;
layers->push_back(torch::nn::Linear(10, 20));
layers->push_back(torch::nn::Linear(20, 30));

torch::Tensor x = input;
for (const auto& layer : *layers) {
 x = layer->as<torch::nn::Linear>()->forward(x);
}
```

## ModuleDict

`ModuleDict` stores modules in a dictionary for named access. Useful when you
need to select modules by name at runtime.

class ModuleDict : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ModuleDictImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ModuleDictImpl`.

See the documentation for `ModuleDictImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ModuleDictImpl

## ParameterList

`ParameterList` stores parameters directly without wrapping them in modules.

class ParameterList : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ParameterListImpl>

Public Types

using Impl = ParameterListImpl

class ParameterListImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<ParameterListImpl>

Public Types

using Iterator = std::vector<[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, torch::Tensor>::Item>::iterator

using ConstIterator = std::vector<[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, torch::Tensor>::Item>::const_iterator

Public Functions

ParameterListImpl() = default

template<typename ...Tensors>
inline explicit ParameterListImpl(Tensors&&... params)

Constructs the `ParameterList` from a variadic list of ParameterList.

template<typename ...Tensors>
inline explicit ParameterListImpl(const Tensors&... params)

inline virtual void reset() override

`reset()` is empty for `ParameterList`, since it does not have parameters of its own.

inline virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `ParameterList` module into the given `stream`.

inline void append(torch::Tensor &¶m)

push a given parameter at the end of the list

inline void append(const torch::Tensor ¶m)

push a given parameter at the end of the list

inline void append(const [OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, torch::Tensor>::Item &pair)

push a given parameter at the end of the list And the key of the pair will be discarded, only the value will be added into the `ParameterList`

template<typename Container>
inline void extend(const Container &container)

extend parameters from a container to the end of the list

inline Iterator begin()

Returns an iterator to the start of the ParameterList the iterator returned will be type of `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)<std::string, torch::Tensor>::Item`

inline ConstIterator begin() const

Returns a const iterator to the start of the ParameterList the iterator returned will be type of `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)<std::string, torch::Tensor>::Item`

inline Iterator end()

Returns an iterator to the end of the ParameterList the iterator returned will be type of `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)<std::string, torch::Tensor>::Item`

inline ConstIterator end() const

Returns a const iterator to the end of the ParameterList the iterator returned will be type of `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)<std::string, torch::Tensor>::Item`

inline at::Tensor &at(size_t idx)

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterList`. Check contains(key) before for a non-throwing way of access

inline const at::Tensor &at(size_t idx) const

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterList`. Check contains(key) before for a non-throwing way of access

inline at::Tensor &operator[](size_t idx)

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterList`. Check contains(key) before for a non-throwing way of access

inline const at::Tensor &operator[](size_t idx) const

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterList`. Check contains(key) before for a non-throwing way of access

inline size_t size() const noexcept

Return the size of the ParameterList.

inline bool is_empty() const noexcept

True if the ParameterList is empty.

template<typename Container>
inline Container &operator+=(const Container &other)

Overload the +=, so that two ParameterList could be incrementally added.

## ParameterDict

`ParameterDict` stores parameters in a dictionary for named access.

class ParameterDict : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ParameterDictImpl>

Public Types

using Impl = ParameterDictImpl

class ParameterDictImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<ParameterDictImpl>

Public Types

using Iterator = [OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, [Tensor](../aten/tensor.html#_CPPv46Tensorv)>::Iterator

using ConstIterator = [OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, [Tensor](../aten/tensor.html#_CPPv46Tensorv)>::ConstIterator

Public Functions

ParameterDictImpl() = default

inline explicit ParameterDictImpl(const torch::[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, torch::Tensor> ¶ms)

inline virtual void reset() override

`reset()` is empty for `ParameterDict`, since it does not have parameters of its own.

inline virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `ParameterDict` module into the given `stream`.

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) &insert(const std::string &key, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) ¶m)

Insert the parameter along with the key into ParameterDict The parameter is set to be require grad by default.

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) pop(const std::string &key)

Remove key from the ParameterDict and return its value, throw exception if the key is not contained.

Please check contains(key) before for a non-throwing access.

inline ::std::vector<std::string> keys() const

Return the keys in the dict.

inline ::std::vector<torch::Tensor> values() const

Return the Values in the dict.

inline Iterator begin()

Return an iterator to the start of ParameterDict.

inline ConstIterator begin() const

Return a const iterator to the start of ParameterDict.

inline Iterator end()

Return an iterator to the end of ParameterDict.

inline ConstIterator end() const

Return a const iterator to the end of ParameterDict.

inline size_t size() const noexcept

Return the number of items currently stored in the ParameterDict.

inline bool empty() const noexcept

Return true if the ParameterDict is empty, otherwise return false.

template<typename Container>
inline void update(const Container &container)

Update the ParameterDict with the key-value pairs from another ParameterDict, overwriting existing key.

inline void clear()

Remove all parameters in the ParameterDict.

inline bool contains(const std::string &key) const noexcept

Check if the certain parameter with the key in the ParameterDict.

inline const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &get(const std::string &key) const

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterDict`. Check contains(key) before for a non-throwing way of access

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) &get(const std::string &key)

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterDict`. Check contains(key) before for a non-throwing way of access

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) &operator[](const std::string &key)

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterDict`. Check contains(key) before for a non-throwing way of access

inline const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &operator[](const std::string &key) const

Returns the value associated with the given `key`.

Throws an exception if no such key is stored in the `ParameterDict`. Check contains(key) before for a non-throwing way of access

---

# Convolution Layers

Convolutional layers apply learnable filters to input data, extracting local features
through sliding window operations. They are fundamental to CNNs for image, audio, and
sequential data processing.

- **Conv1d/2d/3d**: Standard convolution for 1D sequences, 2D images, or 3D volumes
- **ConvTranspose1d/2d/3d**: Transposed convolution (deconvolution) for upsampling

**Key parameters:**

- `in_channels`: Number of input channels
- `out_channels`: Number of output channels (number of filters)
- `kernel_size`: Size of the convolving kernel
- `stride`: Stride of the convolution (default: 1)
- `padding`: Zero-padding added to input (default: 0)
- `dilation`: Spacing between kernel elements (default: 1)
- `groups`: Number of blocked connections (default: 1, use `in_channels` for depthwise)

## Conv1d

Applies 1D convolution over an input signal composed of several input planes.

class Conv1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<Conv1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `Conv1dImpl`.

See the documentation for `Conv1dImpl` class to learn what methods it provides, and examples of how to use `Conv1d` with `torch::nn::Conv1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = Conv1dImpl

class Conv1dImpl : public torch::nn::ConvNdImpl<1, Conv1dImpl>

Applies convolution over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Conv1d](https://pytorch.org/docs/main/nn.html#torch.nn.Conv1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::Conv1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Conv1d model(Conv1dOptions(3, 2, 3).stride(1).bias(false));
```

Public Functions

inline Conv1dImpl(int64_t input_channels, int64_t output_channels, ExpandingArray<1> kernel_size)

explicit Conv1dImpl(Conv1dOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

## Conv2d

Applies 2D convolution over an input image. The most commonly used layer for
image processing tasks.

class Conv2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<Conv2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `Conv2dImpl`.

See the documentation for `Conv2dImpl` class to learn what methods it provides, and examples of how to use `Conv2d` with `torch::nn::Conv2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = Conv2dImpl

class Conv2dImpl : public torch::nn::ConvNdImpl<2, Conv2dImpl>

Applies convolution over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Conv2d](https://pytorch.org/docs/main/nn.html#torch.nn.Conv2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::Conv2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Conv2d model(Conv2dOptions(3, 2, 3).stride(1).bias(false));
```

Public Functions

inline Conv2dImpl(int64_t input_channels, int64_t output_channels, ExpandingArray<2> kernel_size)

explicit Conv2dImpl(Conv2dOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

**Example:**

```
// Create Conv2d: 3 input channels, 64 output channels, 3x3 kernel
auto conv = torch::nn::Conv2d(
 torch::nn::Conv2dOptions(3, 64, 3)
 .stride(1)
 .padding(1)
 .bias(true));

auto output = conv->forward(input); // input: [N, 3, H, W]
```

## Conv3d

Applies 3D convolution over an input volume (e.g., video frames or 3D medical images).

class Conv3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<Conv3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `Conv3dImpl`.

See the documentation for `Conv3dImpl` class to learn what methods it provides, and examples of how to use `Conv3d` with `torch::nn::Conv3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = Conv3dImpl

class Conv3dImpl : public torch::nn::ConvNdImpl<3, Conv3dImpl>

Applies convolution over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Conv3d](https://pytorch.org/docs/main/nn.html#torch.nn.Conv3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::Conv3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Conv3d model(Conv3dOptions(3, 2, 3).stride(1).bias(false));
```

Public Functions

inline Conv3dImpl(int64_t input_channels, int64_t output_channels, ExpandingArray<3> kernel_size)

explicit Conv3dImpl(Conv3dOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

## ConvTranspose1d

Applies 1D transposed convolution (fractionally-strided convolution) for upsampling.

class ConvTranspose1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ConvTranspose1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ConvTranspose1dImpl`.

See the documentation for `ConvTranspose1dImpl` class to learn what methods it provides, and examples of how to use `ConvTranspose1d` with `torch::nn::ConvTranspose1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ConvTranspose1dImpl

class ConvTranspose1dImpl : public torch::nn::ConvTransposeNdImpl<1, ConvTranspose1dImpl>

Applies the ConvTranspose1d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.ConvTranspose1d](https://pytorch.org/docs/main/nn.html#torch.nn.ConvTranspose1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ConvTranspose1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
ConvTranspose1d model(ConvTranspose1dOptions(3, 2,
3).stride(1).bias(false));
```

Public Functions

inline ConvTranspose1dImpl(int64_t input_channels, int64_t output_channels, ExpandingArray<1> kernel_size)

explicit ConvTranspose1dImpl(ConvTranspose1dOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const std::optional<at::IntArrayRef> &output_size = std::nullopt)

Friends

*friend struct* torch::nn::AnyModuleHolder

## ConvTranspose2d

Applies 2D transposed convolution for upsampling. Commonly used in decoder
networks and generative models.

class ConvTranspose2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ConvTranspose2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ConvTranspose2dImpl`.

See the documentation for `ConvTranspose2dImpl` class to learn what methods it provides, and examples of how to use `ConvTranspose2d` with `torch::nn::ConvTranspose2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ConvTranspose2dImpl

class ConvTranspose2dImpl : public torch::nn::ConvTransposeNdImpl<2, ConvTranspose2dImpl>

Applies the ConvTranspose2d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.ConvTranspose2d](https://pytorch.org/docs/main/nn.html#torch.nn.ConvTranspose2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ConvTranspose2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
ConvTranspose2d model(ConvTranspose2dOptions(3, 2,
3).stride(1).bias(false));
```

Public Functions

inline ConvTranspose2dImpl(int64_t input_channels, int64_t output_channels, ExpandingArray<2> kernel_size)

explicit ConvTranspose2dImpl(ConvTranspose2dOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const std::optional<at::IntArrayRef> &output_size = std::nullopt)

Friends

*friend struct* torch::nn::AnyModuleHolder

**Example:**

```
// Create ConvTranspose2d for upsampling
auto conv_transpose = torch::nn::ConvTranspose2d(
 torch::nn::ConvTranspose2dOptions(64, 32, 4)
 .stride(2)
 .padding(1));
```

## ConvTranspose3d

Applies 3D transposed convolution for upsampling volumetric data.

class ConvTranspose3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ConvTranspose3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `ConvTranspose3dImpl`.

See the documentation for `ConvTranspose3dImpl` class to learn what methods it provides, and examples of how to use `ConvTranspose3d` with `torch::nn::ConvTranspose3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ConvTranspose3dImpl

class ConvTranspose3dImpl : public torch::nn::ConvTransposeNdImpl<3, ConvTranspose3dImpl>

Applies the ConvTranspose3d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.ConvTranspose3d](https://pytorch.org/docs/main/nn.html#torch.nn.ConvTranspose3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::ConvTranspose3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
ConvTranspose3d model(ConvTranspose3dOptions(2, 2,
2).stride(1).bias(false));
```

Public Functions

inline ConvTranspose3dImpl(int64_t input_channels, int64_t output_channels, ExpandingArray<3> kernel_size)

explicit ConvTranspose3dImpl(ConvTranspose3dOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const std::optional<at::IntArrayRef> &output_size = std::nullopt)

Friends

*friend struct* torch::nn::AnyModuleHolder

---

# Dropout Layers

Dropout randomly zeros elements during training as a regularization technique,
preventing overfitting by forcing the network to learn redundant representations.
During evaluation, dropout is disabled and outputs are scaled appropriately.

- **Dropout**: Standard dropout for fully-connected layers
- **Dropout2d/3d**: Spatial dropout that zeros entire channels (better for CNNs)
- **AlphaDropout**: Maintains self-normalizing property (use with SELU activation)

Note

Remember to call `model->train()` during training and `model->eval()` during
inference to properly enable/disable dropout behavior.

## Dropout

class Dropout : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<DropoutImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `DropoutImpl`.

See the documentation for `DropoutImpl` class to learn what methods it provides, and examples of how to use `Dropout` with `torch::nn::DropoutOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = DropoutImpl

class DropoutImpl : public torch::nn::detail::_DropoutNd<DropoutImpl>

Applies dropout over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Dropout](https://pytorch.org/docs/main/nn.html#torch.nn.Dropout) to learn about the exact behavior of this module.

See the documentation for `torch::nn::DropoutOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Dropout model(DropoutOptions().p(0.42).inplace(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Dropout` module into the given `stream`.

**Example:**

```
auto dropout = torch::nn::Dropout(torch::nn::DropoutOptions(0.5));
```

## Dropout2d / Dropout3d

class Dropout2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<Dropout2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `Dropout2dImpl`.

See the documentation for `Dropout2dImpl` class to learn what methods it provides, and examples of how to use `Dropout2d` with `torch::nn::Dropout2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = Dropout2dImpl

class Dropout2dImpl : public torch::nn::detail::_DropoutNd<Dropout2dImpl>

Applies dropout over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Dropout2d](https://pytorch.org/docs/main/nn.html#torch.nn.Dropout2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::Dropout2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Dropout2d model(Dropout2dOptions().p(0.42).inplace(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Dropout2d` module into the given `stream`.

class Dropout3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<Dropout3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `Dropout3dImpl`.

See the documentation for `Dropout3dImpl` class to learn what methods it provides, and examples of how to use `Dropout3d` with `torch::nn::Dropout3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = Dropout3dImpl

class Dropout3dImpl : public torch::nn::detail::_DropoutNd<Dropout3dImpl>

Applies dropout over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Dropout3d](https://pytorch.org/docs/main/nn.html#torch.nn.Dropout3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::Dropout3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Dropout3d model(Dropout3dOptions().p(0.42).inplace(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Dropout3d` module into the given `stream`.

## AlphaDropout

class AlphaDropout : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AlphaDropoutImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AlphaDropoutImpl`.

See the documentation for `AlphaDropoutImpl` class to learn what methods it provides, and examples of how to use `AlphaDropout` with `torch::nn::AlphaDropoutOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AlphaDropoutImpl

class AlphaDropoutImpl : public torch::nn::detail::_DropoutNd<AlphaDropoutImpl>

Applies Alpha Dropout over the input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AlphaDropout](https://pytorch.org/docs/main/nn.html#torch.nn.AlphaDropout) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AlphaDropoutOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AlphaDropout model(AlphaDropoutOptions(0.2).inplace(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `AlphaDropout` module into the given `stream`.

## FeatureAlphaDropout

class FeatureAlphaDropout : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<FeatureAlphaDropoutImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `FeatureAlphaDropoutImpl`.

See the documentation for `FeatureAlphaDropoutImpl` class to learn what methods it provides, and examples of how to use `FeatureAlphaDropout` with `torch::nn::FeatureAlphaDropoutOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = FeatureAlphaDropoutImpl

class FeatureAlphaDropoutImpl : public torch::nn::detail::_DropoutNd<FeatureAlphaDropoutImpl>

See the documentation for `torch::nn::FeatureAlphaDropoutOptions` class to learn what constructor arguments are supported for this module.

Example:

```
FeatureAlphaDropout model(FeatureAlphaDropoutOptions(0.2).inplace(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `FeatureAlphaDropout` module into the given `stream`.

---

# Embedding Layers

Embedding layers map discrete tokens (words, categories, IDs) to dense vector
representations. They are the foundation of NLP models and recommendation systems.

- **Embedding**: Standard lookup table that maps indices to dense vectors
- **EmbeddingBag**: Computes sums or means of embeddings (efficient for sparse features)

**Key parameters:**

- `num_embeddings`: Size of the vocabulary (number of unique tokens)
- `embedding_dim`: Dimension of each embedding vector
- `padding_idx`: Index that outputs zeros (useful for padding tokens)

## Embedding

class Embedding : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<EmbeddingImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `EmbeddingImpl`.

See the documentation for `EmbeddingImpl` class to learn what methods it provides, and examples of how to use `Embedding` with `torch::nn::EmbeddingOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Static Functions

static inline Embedding from_pretrained(const torch::Tensor &embeddings, const EmbeddingFromPretrainedOptions &options = {})

See the documentation for `torch::nn::EmbeddingFromPretrainedOptions` class to learn what optional arguments are supported for this function.

class EmbeddingImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<EmbeddingImpl>

Performs a lookup in a fixed size embedding table.

See [https://pytorch.org/docs/main/nn.html#torch.nn.Embedding](https://pytorch.org/docs/main/nn.html#torch.nn.Embedding) to learn about the exact behavior of this module.

See the documentation for `torch::nn::EmbeddingOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Embedding model(EmbeddingOptions(10,
2).padding_idx(3).max_norm(2).norm_type(2.5).scale_grad_by_freq(true).sparse(true));
```

Public Functions

inline EmbeddingImpl(int64_t num_embeddings, int64_t embedding_dim)

explicit EmbeddingImpl(EmbeddingOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Embedding` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices)

Performs a lookup on the embedding table stored in `weight` using the `indices` supplied and returns the result.

Public Members

EmbeddingOptions options

The `Options` used to configure this `Embedding` module.

Changes to `EmbeddingOptions` *after construction* have no effect.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The embedding table.

**Example:**

```
auto embedding = torch::nn::Embedding(
 torch::nn::EmbeddingOptions(10000, 256) // num_embeddings, embedding_dim
 .padding_idx(0));

auto indices = torch::tensor({1, 2, 3, 4});
auto embedded = embedding->forward(indices); // [4, 256]
```

## EmbeddingBag

class EmbeddingBag : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<EmbeddingBagImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `EmbeddingBagImpl`.

See the documentation for `EmbeddingBagImpl` class to learn what methods it provides, and examples of how to use `EmbeddingBag` with `torch::nn::EmbeddingBagOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Static Functions

static inline EmbeddingBag from_pretrained(const torch::Tensor &embeddings, const EmbeddingBagFromPretrainedOptions &options = {})

See the documentation for `torch::nn::EmbeddingBagFromPretrainedOptions` class to learn what optional arguments are supported for this function.

class EmbeddingBagImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<EmbeddingBagImpl>

Computes sums or means of 'bags' of embeddings, without instantiating the intermediate embeddings.

See [https://pytorch.org/docs/main/nn.html#torch.nn.EmbeddingBag](https://pytorch.org/docs/main/nn.html#torch.nn.EmbeddingBag) to learn about the exact behavior of this module.

See the documentation for `torch::nn::EmbeddingBagOptions` class to learn what constructor arguments are supported for this module.

Example:

```
EmbeddingBag model(EmbeddingBagOptions(10,
2).max_norm(2).norm_type(2.5).scale_grad_by_freq(true).sparse(true).mode(torch::kSum).padding_idx(1));
```

Public Functions

inline EmbeddingBagImpl(int64_t num_embeddings, int64_t embedding_dim)

explicit EmbeddingBagImpl(EmbeddingBagOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `EmbeddingBag` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &offsets = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &per_sample_weights = {})

Public Members

EmbeddingBagOptions options

The `Options` used to configure this `EmbeddingBag` module.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The embedding table.

Friends

*friend struct* torch::nn::AnyModuleHolder

---

# Functional API

The `torch::nn::functional` namespace provides stateless versions of neural
network operations. Unlike module classes, functional operations do not hold
learnable parameters -- you pass weights explicitly.

**When to use functional vs modules:**

- Use **modules** (`torch::nn::Conv2d`) when you need learnable parameters
managed automatically (training, saving, loading).
- Use **functional** (`torch::nn::functional::conv2d`) when you already have
weights as tensors, or for operations without parameters (e.g., `relu`).

```
#include <torch/nn/functional.h>
namespace F = torch::nn::functional;

// Stateless activation -- no module needed
auto output = F::relu(input);

// Convolution with explicit weight tensor
auto output = F::conv2d(input, weight, F::Conv2dFuncOptions().stride(1).padding(1));

// Softmax along a dimension
auto probs = F::softmax(logits, F::SoftmaxFuncOptions(/*dim=*/1));
```

## Activation Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::elu([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const ELUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.elu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.elu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ELUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::elu(x, F::ELUFuncOptions().alpha(0.42).inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::selu([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const SELUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.selu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.selu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SELUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::selu(input, F::SELUFuncOptions(false));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::hardshrink(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const HardshrinkFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.hardshrink](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.hardshrink) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::HardshrinkFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::hardshrink(x, F::HardshrinkFuncOptions().lambda(0.42));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::hardtanh([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const HardtanhFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.hardtanh](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.hardtanh) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::HardtanhFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::hardtanh(x,
F::HardtanhFuncOptions().min_val(-1.0).max_val(1.0).inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::leaky_relu([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const LeakyReLUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.leaky_relu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.leaky_relu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LeakyReLUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::leaky_relu(x,
F::LeakyReLUFuncOptions().negative_slope(0.42).inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::logsigmoid(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::glu(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const GLUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.glu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.glu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::GLUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::glu(input, GLUFuncOptions(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::gelu(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const GELUFuncOptions &options = {})

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::silu(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::mish(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::prelu(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::relu([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const ReLUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.relu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.relu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ReLUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::relu(x, F::ReLUFuncOptions().inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::relu6([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const ReLU6FuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.relu6](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.relu6) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ReLU6FuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::relu6(x, F::ReLU6FuncOptions().inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::rrelu([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const RReLUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.rrelu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.rrelu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::RReLUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::rrelu(x, F::RReLUFuncOptions().lower(0.1).upper(0.4).inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::celu([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const CELUFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.celu](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.celu) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::CELUFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::celu(x, F::CELUFuncOptions().alpha(0.42).inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::softplus(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const SoftplusFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softplus](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softplus) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SoftplusFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::softplus(x, F::SoftplusFuncOptions().beta(0.5).threshold(3.0));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::softshrink(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const SoftshrinkFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softshrink](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softshrink) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SoftshrinkFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::softshrink(x, F::SoftshrinkFuncOptions(0.42));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::softsign(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::tanhshrink(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::threshold([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const ThresholdFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.threshold](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.threshold) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ThresholdFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::threshold(x, F::ThresholdFuncOptions(0.5, 0.5).inplace(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::softmax(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const SoftmaxFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softmax](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softmax) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SoftmaxFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::softmax(input, F::SoftmaxFuncOptions(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::softmin(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const SoftminFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softmin](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.softmin) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SoftminFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::softmin(input, F::SoftminFuncOptions(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::log_softmax(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const LogSoftmaxFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.log_softmax](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.log_softmax) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LogSoftmaxFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::log_softmax(input, LogSoftmaxFuncOptions(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::gumbel_softmax(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &logits, const GumbelSoftmaxFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.gumbel_softmax](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.gumbel_softmax) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::GumbelSoftmaxFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::gumbel_softmax(logits, F::GumbelSoftmaxFuncOptions().hard(true).dim(-1));
```

## Convolution Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::conv1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const Conv1dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::Conv1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::conv1d(x, weight, F::Conv1dFuncOptions().stride(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::conv2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const Conv2dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::Conv2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::conv2d(x, weight, F::Conv2dFuncOptions().stride(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::conv3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const Conv3dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::Conv3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::conv3d(x, weight, F::Conv3dFuncOptions().stride(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::conv_transpose1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const ConvTranspose1dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv_transpose1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv_transpose1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ConvTranspose1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::conv_transpose1d(x, weight, F::ConvTranspose1dFuncOptions().stride(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::conv_transpose2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const ConvTranspose2dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv_transpose2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv_transpose2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ConvTranspose2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::conv_transpose2d(x, weight, F::ConvTranspose2dFuncOptions().stride(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::conv_transpose3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const ConvTranspose3dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv_transpose3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.conv_transpose3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::ConvTranspose3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::conv_transpose3d(x, weight, F::ConvTranspose3dFuncOptions().stride(1));
```

## Pooling Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::avg_pool1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AvgPool1dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.avg_pool1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.avg_pool1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AvgPool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::avg_pool1d(x, F::AvgPool1dFuncOptions(3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::avg_pool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AvgPool2dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.avg_pool2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.avg_pool2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AvgPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::avg_pool2d(x, F::AvgPool2dFuncOptions(3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::avg_pool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AvgPool3dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.avg_pool3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.avg_pool3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AvgPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::avg_pool3d(x, F::AvgPool3dFuncOptions(3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::max_pool1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const MaxPool1dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_pool1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_pool1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MaxPool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_pool1d(x, F::MaxPool1dFuncOptions(3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::max_pool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const MaxPool2dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_pool2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_pool2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MaxPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_pool2d(x, F::MaxPool2dFuncOptions(3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::max_pool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const MaxPool3dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_pool3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_pool3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MaxPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_pool3d(x, F::MaxPool3dFuncOptions(3).stride(2));
```

inline std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> torch::nn::functional::max_pool1d_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const MaxPool1dFuncOptions &options)

See the documentation for `torch::nn::functional::MaxPool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_pool1d_with_indices(x, F::MaxPool1dFuncOptions(3).stride(2));
```

inline std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> torch::nn::functional::max_pool2d_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const MaxPool2dFuncOptions &options)

See the documentation for `torch::nn::functional::MaxPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_pool2d_with_indices(x, F::MaxPool2dFuncOptions(3).stride(2));
```

inline std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> torch::nn::functional::max_pool3d_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const MaxPool3dFuncOptions &options)

See the documentation for `torch::nn::functional::MaxPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_pool3d_with_indices(x, F::MaxPool3dFuncOptions(3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::adaptive_max_pool1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AdaptiveMaxPool1dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_max_pool1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_max_pool1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AdaptiveMaxPool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_max_pool1d(x, F::AdaptiveMaxPool1dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::adaptive_max_pool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AdaptiveMaxPool2dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_max_pool2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_max_pool2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AdaptiveMaxPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_max_pool2d(x, F::AdaptiveMaxPool2dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::adaptive_max_pool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AdaptiveMaxPool3dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_max_pool3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_max_pool3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AdaptiveMaxPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_max_pool3d(x, F::AdaptiveMaxPool3dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::adaptive_avg_pool1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AdaptiveAvgPool1dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_avg_pool1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_avg_pool1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AdaptiveAvgPool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_avg_pool1d(x, F::AdaptiveAvgPool1dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::adaptive_avg_pool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AdaptiveAvgPool2dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_avg_pool2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_avg_pool2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AdaptiveAvgPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_avg_pool2d(x, F::AdaptiveAvgPool2dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::adaptive_avg_pool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const AdaptiveAvgPool3dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_avg_pool3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.adaptive_avg_pool3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AdaptiveAvgPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_avg_pool3d(x, F::AdaptiveAvgPool3dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::max_unpool1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices, const MaxUnpool1dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_unpool1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_unpool1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MaxUnpool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_unpool1d(x, indices,
F::MaxUnpool1dFuncOptions(3).stride(2).padding(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::max_unpool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices, const MaxUnpool2dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_unpool2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_unpool2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MaxUnpool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_unpool2d(x, indices,
F::MaxUnpool2dFuncOptions(3).stride(2).padding(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::max_unpool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices, const MaxUnpool3dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_unpool3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.max_unpool3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MaxUnpool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::max_unpool3d(x, indices, F::MaxUnpool3dFuncOptions(3));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::fractional_max_pool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const FractionalMaxPool2dFuncOptions &options)

See the documentation for `torch::nn::functional::FractionalMaxPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::fractional_max_pool2d(x,
F::FractionalMaxPool2dFuncOptions(3).output_size(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::fractional_max_pool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const FractionalMaxPool3dFuncOptions &options)

See the documentation for `torch::nn::functional::FractionalMaxPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::fractional_max_pool3d(x,
F::FractionalMaxPool3dFuncOptions(3).output_size(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::lp_pool1d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const LPPool1dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.lp_pool1d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.lp_pool1d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LPPool1dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::lp_pool1d(x, F::LPPool1dFuncOptions(2, 3).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::lp_pool2d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const LPPool2dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.lp_pool2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.lp_pool2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LPPool2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::lp_pool2d(x, F::LPPool2dFuncOptions(2, {2, 3}).stride(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::lp_pool3d(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const LPPool3dFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.lp_pool3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.lp_pool3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LPPool3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::lp_pool3d(x, F::LPPool3dFuncOptions(3, {3, 3, 5}).stride(3));
```

## Linear Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::linear(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &bias = {})

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::bilinear(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input2, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &bias = [Tensor](../aten/tensor.html#_CPPv46Tensorv)())

## Dropout Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::dropout([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const DropoutFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.dropout](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.dropout) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::DropoutFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::dropout(input, F::DropoutFuncOptions().p(0.5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::dropout2d([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const Dropout2dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.dropout2d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.dropout2d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::Dropout2dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::dropout2d(input, F::Dropout2dFuncOptions().p(0.5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::dropout3d([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const Dropout3dFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.dropout3d](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.dropout3d) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::Dropout3dFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::dropout3d(input, F::Dropout3dFuncOptions().p(0.5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::alpha_dropout([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const AlphaDropoutFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.alpha_dropout](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.alpha_dropout) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::AlphaDropoutFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::alpha_dropout(input,
F::AlphaDropoutFuncOptions().p(0.5).training(false));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::feature_alpha_dropout([Tensor](../aten/tensor.html#_CPPv46Tensorv) input, const FeatureAlphaDropoutFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.feature_alpha_dropout](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.feature_alpha_dropout) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::FeatureAlphaDropoutFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::feature_alpha_dropout(input,
F::FeatureAlphaDropoutFuncOptions().p(0.5).training(false));
```

## Embedding Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::one_hot(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tensor, int64_t num_classes = -1)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::embedding(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const EmbeddingFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.embedding](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.embedding) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::EmbeddingFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::embedding(input, weight,
F::EmbeddingFuncOptions().norm_type(2.5).scale_grad_by_freq(true).sparse(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::embedding_bag(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &weight, const EmbeddingBagFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.embedding_bag](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.embedding_bag) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::EmbeddingBagFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::embedding_bag(input, weight,
F::EmbeddingBagFuncOptions().mode(torch::kSum).offsets(offsets));
```

## Normalization Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::batch_norm(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &running_mean, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &running_var, const BatchNormFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.batch_norm](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.batch_norm) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::BatchNormFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::batch_norm(input, mean, variance,
F::BatchNormFuncOptions().weight(weight).bias(bias).momentum(0.1).eps(1e-05).training(false));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::instance_norm(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const InstanceNormFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.instance_norm](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.instance_norm) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::InstanceNormFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::instance_norm(input,
F::InstanceNormFuncOptions().running_mean(mean).running_var(variance).weight(weight).bias(bias).momentum(0.1).eps(1e-5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::layer_norm(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const LayerNormFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.layer_norm](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.layer_norm) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LayerNormFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::layer_norm(input, F::LayerNormFuncOptions({2, 2}).eps(2e-5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::group_norm(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const GroupNormFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.group_norm](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.group_norm) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::GroupNormFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::group_norm(input, F::GroupNormFuncOptions(2).eps(2e-5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::local_response_norm(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const LocalResponseNormFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.local_response_norm](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.local_response_norm) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::LocalResponseNormFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::local_response_norm(x, F::LocalResponseNormFuncOptions(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::normalize(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, NormalizeFuncOptions options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.normalize](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.normalize) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::NormalizeFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::normalize(input, F::NormalizeFuncOptions().p(1).dim(-1));
```

## Loss Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::l1_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const L1LossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.l1_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.l1_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::L1LossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::l1_loss(input, target, F::L1LossFuncOptions(torch::kNone));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::mse_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const MSELossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.mse_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.mse_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MSELossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::mse_loss(input, target, F::MSELossFuncOptions(torch::kNone));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::binary_cross_entropy(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const BinaryCrossEntropyFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.binary_cross_entropy](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.binary_cross_entropy) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::BinaryCrossEntropyFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::binary_cross_entropy(input, target,
F::BinaryCrossEntropyFuncOptions().weight(weight));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::binary_cross_entropy_with_logits(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const BinaryCrossEntropyWithLogitsFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.binary_cross_entropy_with_logits](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.binary_cross_entropy_with_logits) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::BinaryCrossEntropyWithLogitsFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::binary_cross_entropy_with_logits(input, target,
F::BinaryCrossEntropyWithLogitsFuncOptions().pos_weight(pos_weight).reduction(torch::kSum));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::cross_entropy(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const CrossEntropyFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.cross_entropy](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.cross_entropy) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::CrossEntropyFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::cross_entropy(input, target,
F::CrossEntropyFuncOptions().ignore_index(-100).reduction(torch::kMean));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::nll_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const NLLLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.nll_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.nll_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::NLLLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::nll_loss(input, target,
F::NLLLossFuncOptions().ignore_index(-100).reduction(torch::kMean));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::kl_div(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const KLDivFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.kl_div](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.kl_div) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::KLDivFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::kl_div(input, target,
F::KLDivFuncOptions.reduction(torch::kNone).log_target(false));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::smooth_l1_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const SmoothL1LossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.smooth_l1_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.smooth_l1_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SmoothL1LossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::smooth_l1_loss(input, target, F::SmoothL1LossFuncOptions(torch::kNone));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::huber_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const HuberLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.huber_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.huber_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::HuberLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::huber_loss(input, target,
F::HuberLossFuncOptions().reduction(torch::kNone).delta(0.5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::hinge_embedding_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const HingeEmbeddingLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.hinge_embedding_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.hinge_embedding_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::HingeEmbeddingLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::hinge_embedding_loss(input, target,
F::HingeEmbeddingLossFuncOptions().margin(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::multi_margin_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const MultiMarginLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.multi_margin_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.multi_margin_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MultiMarginLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::multi_margin_loss(input, target,
F::MultiMarginLossFuncOptions().margin(2).weight(weight));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::cosine_embedding_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input2, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const CosineEmbeddingLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.cosine_embedding_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.cosine_embedding_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::CosineEmbeddingLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::cosine_embedding_loss(input1, input2, target,
F::CosineEmbeddingLossFuncOptions().margin(0.5));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::margin_ranking_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input2, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const MarginRankingLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.margin_ranking_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.margin_ranking_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MarginRankingLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::margin_ranking_loss(input1, input2, target,
F::MarginRankingLossFuncOptions().margin(0.5).reduction(torch::kSum));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::multilabel_margin_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const MultilabelMarginLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.multilabel_margin_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.multilabel_margin_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MultilabelMarginLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::multilabel_margin_loss(input, target,
F::MultilabelMarginLossFuncOptions(torch::kNone));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::soft_margin_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const SoftMarginLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.soft_margin_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.soft_margin_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::SoftMarginLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::soft_margin_loss(input, target,
F::SoftMarginLossFuncOptions(torch::kNone));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::multilabel_soft_margin_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const MultilabelSoftMarginLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.multilabel_soft_margin_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.multilabel_soft_margin_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::MultilabelSoftMarginLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::multilabel_soft_margin_loss(input, target,
F::MultilabelSoftMarginLossFuncOptions().reduction(torch::kNone).weight(weight));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::triplet_margin_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &anchor, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &positive, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &negative, const TripletMarginLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.triplet_margin_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.triplet_margin_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::TripletMarginLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::triplet_margin_loss(anchor, positive, negative,
F::TripletMarginLossFuncOptions().margin(1.0));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::triplet_margin_with_distance_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &anchor, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &positive, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &negative, const TripletMarginWithDistanceLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.triplet_margin_with_distance_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.triplet_margin_with_distance_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::TripletMarginWithDistanceLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::triplet_margin_with_distance_loss(anchor, positive, negative,
F::TripletMarginWithDistanceLossFuncOptions().margin(1.0));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::ctc_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &log_probs, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &targets, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input_lengths, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target_lengths, const CTCLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.ctc_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.ctc_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::CTCLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::ctc_loss(log_probs, targets, input_lengths, target_lengths,
F::CTCLossFuncOptions().reduction(torch::kNone));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::poisson_nll_loss(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target, const PoissonNLLLossFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.poisson_nll_loss](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.poisson_nll_loss) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::PoissonNLLLossFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::poisson_nll_loss(input, target,
F::PoissonNLLLossFuncOptions().reduction(torch::kNone));
```

## Distance Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::cosine_similarity(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &x1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &x2, const CosineSimilarityFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.cosine_similarity](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.cosine_similarity) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::CosineSimilarityFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::cosine_similarity(input1, input2,
F::CosineSimilarityFuncOptions().dim(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::pairwise_distance(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &x1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &x2, const PairwiseDistanceFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.pairwise_distance](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.pairwise_distance) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::PairwiseDistanceFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::pairwise_distance(input1, input2, F::PairwiseDistanceFuncOptions().p(1));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::pdist(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, double p = 2.0)

Computes the p-norm distance between every pair of row vectors in the input.

This function will be faster if the rows are contiguous.

## Vision Functions

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::interpolate(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const InterpolateFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.interpolate](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.interpolate) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::InterpolateFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::interpolate(input,
F::InterpolateFuncOptions().size({4}).mode(torch::kNearest));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::affine_grid(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &theta, const IntArrayRef &size, bool align_corners = false)

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::grid_sample(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &grid, const GridSampleFuncOptions &options = {})

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.grid_sample](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.grid_sample) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::GridSampleFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::grid_sample(input, grid,
F::GridSampleFuncOptions().mode(torch::kBilinear).padding_mode(torch::kZeros).align_corners(true));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::pad(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const PadFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.pad](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.pad) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::PadFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::pad(input, F::PadFuncOptions({1, 2, 2, 1, 1,
2}).mode(torch::kReplicate));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::pixel_shuffle(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const PixelShuffleFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.pixel_shuffle](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.pixel_shuffle) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::PixelShuffleFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::pixel_shuffle(x, F::PixelShuffleFuncOptions(2));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::pixel_unshuffle(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const PixelUnshuffleFuncOptions &options)

## Fold/Unfold

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::fold(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const FoldFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.fold](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.fold) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::FoldFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::fold(input, F::FoldFuncOptions({3, 2}, {2, 2}));
```

inline [Tensor](../aten/tensor.html#_CPPv46Tensorv) torch::nn::functional::unfold(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const UnfoldFuncOptions &options)

See [https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.unfold](https://pytorch.org/docs/main/nn.functional.html#torch.nn.functional.unfold) about the exact behavior of this functional.

See the documentation for `torch::nn::functional::UnfoldFuncOptions` class to learn what optional arguments are supported for this functional.

Example:

```
namespace F = torch::nn::functional;
F::unfold(input, F::UnfoldFuncOptions({2, 2}).padding(1).stride(2));
```

## Functional Options Structs

Each functional operation that takes configuration uses a corresponding options
struct. The naming convention is `<Operation>FuncOptions`.

**Activation Options:**

using torch::nn::functional::ELUFuncOptions = ELUOptions

Options for `torch::nn::functional::elu`.

See the documentation for `torch::nn::ELUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::elu(x, F::ELUFuncOptions().alpha(0.42).inplace(true));
```

using torch::nn::functional::SELUFuncOptions = SELUOptions

Options for `torch::nn::functional::selu`.

See the documentation for `torch::nn::SELUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::selu(input, F::SELUFuncOptions(false));
```

using torch::nn::functional::GLUFuncOptions = GLUOptions

Options for `torch::nn::functional::glu`.

See the documentation for `torch::nn::GLUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::glu(input, GLUFuncOptions(1));
```

using torch::nn::functional::GELUFuncOptions = GELUOptions

Options for `torch::nn::functional::gelu`.

See the documentation for `torch::nn::GELUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::gelu(input, F::GELUFuncOptions().approximate("none"));
```

using torch::nn::functional::HardshrinkFuncOptions = HardshrinkOptions

Options for `torch::nn::functional::hardshrink`.

See the documentation for `torch::nn::HardshrinkOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::hardshrink(x, F::HardshrinkFuncOptions().lambda(0.42));
```

using torch::nn::functional::HardtanhFuncOptions = HardtanhOptions

Options for `torch::nn::functional::hardtanh`.

See the documentation for `torch::nn::HardtanhOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::hardtanh(x,
F::HardtanhFuncOptions().min_val(-1.0).max_val(1.0).inplace(true));
```

using torch::nn::functional::LeakyReLUFuncOptions = LeakyReLUOptions

Options for `torch::nn::functional::leaky_relu`.

See the documentation for `torch::nn::LeakyReLUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::leaky_relu(x,
F::LeakyReLUFuncOptions().negative_slope(0.42).inplace(true));
```

using torch::nn::functional::ReLUFuncOptions = ReLUOptions

Options for `torch::nn::functional::relu`.

See the documentation for `torch::nn::ReLUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::relu(x, F::ReLUFuncOptions().inplace(true));
```

using torch::nn::functional::ReLU6FuncOptions = ReLU6Options

Options for `torch::nn::functional::relu6`.

See the documentation for `torch::nn::ReLU6Options` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::relu6(x, F::ReLU6FuncOptions().inplace(true));
```

using torch::nn::functional::CELUFuncOptions = CELUOptions

Options for `torch::nn::functional::celu`.

See the documentation for `torch::nn::CELUOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::celu(x, F::CELUFuncOptions().alpha(0.42).inplace(true));
```

using torch::nn::functional::SoftplusFuncOptions = SoftplusOptions

Options for `torch::nn::functional::softplus`.

See the documentation for `torch::nn::SoftplusOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::softplus(x, F::SoftplusFuncOptions().beta(0.5).threshold(3.0));
```

using torch::nn::functional::SoftshrinkFuncOptions = SoftshrinkOptions

Options for `torch::nn::functional::softshrink`.

See the documentation for `torch::nn::SoftshrinkOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::softshrink(x, F::SoftshrinkFuncOptions(0.42));
```

using torch::nn::functional::ThresholdFuncOptions = ThresholdOptions

Options for `torch::nn::functional::threshold`.

See the documentation for `torch::nn::ThresholdOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::threshold(x, F::ThresholdFuncOptions(0.5, 0.5).inplace(true));
```

**Convolution Options:**

using torch::nn::functional::Conv1dFuncOptions = ConvFuncOptions<1>

`ConvFuncOptions` specialized for `torch::nn::functional::conv1d`.

Example:

```
namespace F = torch::nn::functional;
F::conv1d(x, weight, F::Conv1dFuncOptions().stride(1));
```

using torch::nn::functional::Conv2dFuncOptions = ConvFuncOptions<2>

`ConvFuncOptions` specialized for `torch::nn::functional::conv2d`.

Example:

```
namespace F = torch::nn::functional;
F::conv2d(x, weight, F::Conv2dFuncOptions().stride(1));
```

using torch::nn::functional::Conv3dFuncOptions = ConvFuncOptions<3>

`ConvFuncOptions` specialized for `torch::nn::functional::conv3d`.

Example:

```
namespace F = torch::nn::functional;
F::conv3d(x, weight, F::Conv3dFuncOptions().stride(1));
```

using torch::nn::functional::ConvTranspose1dFuncOptions = ConvTransposeFuncOptions<1>

`ConvTransposeFuncOptions` specialized for `torch::nn::functional::conv_transpose1d`.

Example:

```
namespace F = torch::nn::functional;
F::conv_transpose1d(x, weight, F::ConvTranspose1dFuncOptions().stride(1));
```

using torch::nn::functional::ConvTranspose2dFuncOptions = ConvTransposeFuncOptions<2>

`ConvTransposeFuncOptions` specialized for `torch::nn::functional::conv_transpose2d`.

Example:

```
namespace F = torch::nn::functional;
F::conv_transpose2d(x, weight, F::ConvTranspose2dFuncOptions().stride(1));
```

using torch::nn::functional::ConvTranspose3dFuncOptions = ConvTransposeFuncOptions<3>

`ConvTransposeFuncOptions` specialized for `torch::nn::functional::conv_transpose3d`.

Example:

```
namespace F = torch::nn::functional;
F::conv_transpose3d(x, weight, F::ConvTranspose3dFuncOptions().stride(1));
```

**Pooling Options:**

using torch::nn::functional::AvgPool1dFuncOptions = AvgPool1dOptions

Options for `torch::nn::functional::avg_pool1d`.

See the documentation for `torch::nn::AvgPool1dOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::avg_pool1d(x, F::AvgPool1dFuncOptions(3).stride(2));
```

using torch::nn::functional::AvgPool2dFuncOptions = AvgPool2dOptions

Options for `torch::nn::functional::avg_pool2d`.

See the documentation for `torch::nn::AvgPool2dOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::avg_pool2d(x, F::AvgPool2dFuncOptions(3).stride(2));
```

using torch::nn::functional::AvgPool3dFuncOptions = AvgPool3dOptions

Options for `torch::nn::functional::avg_pool3d`.

See the documentation for `torch::nn::AvgPool3dOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::avg_pool3d(x, F::AvgPool3dFuncOptions(3).stride(2));
```

using torch::nn::functional::MaxPool1dFuncOptions = MaxPool1dOptions

Options for `torch::nn::functional::max_pool1d` and `torch::nn::functional::max_pool1d_with_indices`.

Example:

```
namespace F = torch::nn::functional;
F::max_pool1d(x, F::MaxPool1dFuncOptions(3).stride(2));
```

using torch::nn::functional::MaxPool2dFuncOptions = MaxPool2dOptions

Options for `torch::nn::functional::max_pool2d` and `torch::nn::functional::max_pool2d_with_indices`.

Example:

```
namespace F = torch::nn::functional;
F::max_pool2d(x, F::MaxPool2dFuncOptions(3).stride(2));
```

using torch::nn::functional::MaxPool3dFuncOptions = MaxPool3dOptions

Options for `torch::nn::functional::max_pool3d` and `torch::nn::functional::max_pool3d_with_indices`.

Example:

```
namespace F = torch::nn::functional;
F::max_pool3d(x, F::MaxPool3dFuncOptions(3).stride(2));
```

using torch::nn::functional::AdaptiveMaxPool1dFuncOptions = AdaptiveMaxPool1dOptions

Options for `torch::nn::functional::adaptive_max_pool1d` and `torch::nn::functional::adaptive_max_pool1d_with_indices`

Example:

```
namespace F = torch::nn::functional;
F::adaptive_max_pool1d(x, F::AdaptiveMaxPool1dFuncOptions(3));
```

using torch::nn::functional::AdaptiveMaxPool2dFuncOptions = AdaptiveMaxPool2dOptions

Options for `torch::nn::functional::adaptive_max_pool2d` and `torch::nn::functional::adaptive_max_pool2d_with_indices`

Example:

```
namespace F = torch::nn::functional;
F::adaptive_max_pool2d(x, F::AdaptiveMaxPool2dFuncOptions(3));
```

using torch::nn::functional::AdaptiveMaxPool3dFuncOptions = AdaptiveMaxPool3dOptions

Options for `torch::nn::functional::adaptive_max_pool3d` and `torch::nn::functional::adaptive_max_pool3d_with_indices`

Example:

```
namespace F = torch::nn::functional;
F::adaptive_max_pool3d(x, F::AdaptiveMaxPool3dFuncOptions(3));
```

using torch::nn::functional::AdaptiveAvgPool1dFuncOptions = AdaptiveAvgPool1dOptions

Options for `torch::nn::functional::adaptive_avg_pool1d`.

See the documentation for `torch::nn::AdaptiveAvgPool1dOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_avg_pool1d(x, F::AdaptiveAvgPool1dFuncOptions(3));
```

using torch::nn::functional::AdaptiveAvgPool2dFuncOptions = AdaptiveAvgPool2dOptions

Options for `torch::nn::functional::adaptive_avg_pool2d`.

See the documentation for `torch::nn::AdaptiveAvgPool2dOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_avg_pool2d(x, F::AdaptiveAvgPool2dFuncOptions(3));
```

using torch::nn::functional::AdaptiveAvgPool3dFuncOptions = AdaptiveAvgPool3dOptions

Options for `torch::nn::functional::adaptive_avg_pool3d`.

See the documentation for `torch::nn::AdaptiveAvgPool3dOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::adaptive_avg_pool3d(x, F::AdaptiveAvgPool3dFuncOptions(3));
```

**Other Options:**

using torch::nn::functional::CosineSimilarityFuncOptions = CosineSimilarityOptions

Options for `torch::nn::functional::cosine_similarity`.

See the documentation for `torch::nn::CosineSimilarityOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::cosine_similarity(input1, input2,
F::CosineSimilarityFuncOptions().dim(1));
```

using torch::nn::functional::PairwiseDistanceFuncOptions = PairwiseDistanceOptions

Options for `torch::nn::functional::pairwise_distance`.

See the documentation for `torch::nn::PairwiseDistanceOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::pairwise_distance(input1, input2, F::PairwiseDistanceFuncOptions().p(1));
```

using torch::nn::functional::Dropout2dFuncOptions = DropoutFuncOptions

Options for `torch::nn::functional::dropout2d`.

Example:

```
namespace F = torch::nn::functional;
F::dropout2d(input, F::Dropout2dFuncOptions().p(0.5));
```

using torch::nn::functional::Dropout3dFuncOptions = DropoutFuncOptions

Options for `torch::nn::functional::dropout3d`.

Example:

```
namespace F = torch::nn::functional;
F::dropout3d(input, F::Dropout3dFuncOptions().p(0.5));
```

using torch::nn::functional::L1LossFuncOptions = L1LossOptions

Options for `torch::nn::functional::l1_loss`.

See the documentation for `torch::nn::L1LossOptions` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::l1_loss(input, target, F::L1LossFuncOptions(torch::kNone));
```

using torch::nn::functional::FoldFuncOptions = [FoldOptions](utilities.html#_CPPv4N5torch2nn11FoldOptionsE)

Options for `torch::nn::functional::fold`.

See the documentation for `[torch::nn::FoldOptions](utilities.html#PyTorchstructtorch_1_1nn_1_1_fold_options)` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::fold(input, F::FoldFuncOptions({3, 2}, {2, 2}));
```

using torch::nn::functional::UnfoldFuncOptions = [UnfoldOptions](utilities.html#_CPPv4N5torch2nn13UnfoldOptionsE)

Options for `torch::nn::functional::unfold`.

See the documentation for `[torch::nn::UnfoldOptions](utilities.html#PyTorchstructtorch_1_1nn_1_1_unfold_options)` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::unfold(input, F::UnfoldFuncOptions({2, 2}).padding(1).stride(2));
```

using torch::nn::functional::PixelShuffleFuncOptions = [PixelShuffleOptions](utilities.html#_CPPv4N5torch2nn19PixelShuffleOptionsE)

Options for `torch::nn::functional::pixel_shuffle`.

See the documentation for `[torch::nn::PixelShuffleOptions](utilities.html#PyTorchstructtorch_1_1nn_1_1_pixel_shuffle_options)` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::pixel_shuffle(x, F::PixelShuffleFuncOptions(2));
```

using torch::nn::functional::PixelUnshuffleFuncOptions = [PixelUnshuffleOptions](utilities.html#_CPPv4N5torch2nn21PixelUnshuffleOptionsE)

Options for `torch::nn::functional::pixel_unshuffle`.

See the documentation for `[torch::nn::PixelUnshuffleOptions](utilities.html#PyTorchstructtorch_1_1nn_1_1_pixel_unshuffle_options)` class to learn what arguments are supported.

Example:

```
namespace F = torch::nn::functional;
F::pixel_unshuffle(x, F::PixelUnshuffleFuncOptions(2));
```

---

# Neural Network Modules (torch::nn)

The `torch::nn` namespace provides neural network building blocks that mirror
Python's `torch.nn` module. It uses a PIMPL (Pointer to Implementation) pattern
where user-facing classes like `Conv2d` wrap internal `Conv2dImpl` classes.

**When to use torch::nn:**

- Building neural network models in C++
- Creating custom layers and modules
- Porting Python models to C++ for production inference
- Training models entirely in C++

**Basic usage:**

```
#include <torch/torch.h>

// Define a simple model
struct Net : torch::nn::Module {
 torch::nn::Conv2d conv1{nullptr};
 torch::nn::Linear fc1{nullptr};

 Net() {
 conv1 = register_module("conv1", torch::nn::Conv2d(
 torch::nn::Conv2dOptions(1, 32, 3).stride(1).padding(1)));
 fc1 = register_module("fc1", torch::nn::Linear(32 * 28 * 28, 10));
 }

 torch::Tensor forward(torch::Tensor x) {
 x = torch::relu(conv1->forward(x));
 x = x.view({-1, 32 * 28 * 28});
 return fc1->forward(x);
 }
};

// Create and use the model
auto model = std::make_shared<Net>();
auto input = torch::randn({1, 1, 28, 28});
auto output = model->forward(input);
```

## Header Files

- `torch/nn.h` - Main neural network header (includes all modules)
- `torch/nn/module.h` - Base Module class
- `torch/nn/modules.h` - All module implementations
- `torch/nn/options.h` - Options structs for modules
- `torch/nn/functional.h` - Functional API

## Module Base Class

All neural network modules inherit from `torch::nn::Module`, which provides
parameter management, serialization, device/dtype conversion, and hooks.

class Module : public std::enable_shared_from_this<Module>

The base class for all modules in PyTorch.

- .. note::
- The design and implementation of this class is largely based on the Python
- API. You may want to consult the python documentation for
- :py:class:`pytorch:torch.nn.Module` for further clarification on certain
- methods or behavior.
- 

A `Module` is an abstraction over the implementation of some function or algorithm, possibly associated with some persistent data. A `Module` may contain further `Module`s ("submodules"), each with their own implementation, persistent data and further submodules. `Module`s can thus be said to form a recursive tree structure. A `Module` is registered as a submodule to another `Module` by calling `register_module()`, typically from within a parent module's constructor.

A distinction is made between three kinds of persistent data that may be associated with a `Module`:

1. *Parameters*: tensors that record gradients, typically weights updated during the backward step (e.g. the `weight` of a `[Linear](linear.html#PyTorchclasstorch_1_1nn_1_1_linear)` module),
2. *Buffers*: tensors that do not record gradients, typically updated during the forward step, such as running statistics (e.g. `mean` and `variance` in the `BatchNorm` module),
3. Any additional state, not necessarily tensors, required for the implementation or configuration of a `Module`.

The first two kinds of state are special in that they may be registered with the `Module` system to allow convenient access and batch configuration. For example, registered parameters in any `Module` may be iterated over via the `parameters()` accessor. Further, changing the data type of a `Module`'s registered parameters can be done conveniently via `Module::to()`, e.g. `module->to(torch::kCUDA)` to move all parameters to GPU memory. Lastly, registered parameters and buffers are handled specially during a `clone()` operation, which performs a deepcopy of a cloneable `Module` hierarchy.

Parameters are registered with a `Module` via `register_parameter`. Buffers are registered separately via `register_buffer`. These methods are part of the public API of `Module` and are typically invoked from within a concrete `Module`s constructor.

Subclassed by [torch::nn::Cloneable< SoftshrinkImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< PReLUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< LogSoftmaxImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< L1LossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SequentialImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< HardshrinkImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< GLUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< RReLUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ParameterDictImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< IdentityImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< FoldImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< EmbeddingBagImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< BilinearImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TripletMarginWithDistanceLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SoftminImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SmoothL1LossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MultiLabelMarginLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< LeakyReLUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< FunctionalImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ELUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TanhshrinkImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< PairwiseDistanceImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< LogSigmoidImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< HardtanhImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< FractionalMaxPool2dImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< FlattenImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< CrossMapLRN2dImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TransformerEncoderLayerImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ThresholdImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SoftsignImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MultiMarginLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< FractionalMaxPool3dImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< CTCLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< UnfoldImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SiLUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ParameterListImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MultiheadAttentionImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< CELUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< UpsampleImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TransformerImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SELUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< PixelUnshuffleImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< LinearImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< HingeEmbeddingLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< EmbeddingImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MultiLabelSoftMarginLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< CrossEntropyLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TripletMarginLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TransformerDecoderLayerImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SoftMarginLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< LocalResponseNormImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< BCELossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< LayerNormImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< AdaptiveLogSoftmaxWithLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ReLUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ModuleListImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< HuberLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< GELUImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SoftmaxImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< Softmax2dImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SoftplusImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< SigmoidImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< PoissonNLLLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ModuleDictImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MishImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< UnflattenImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< ReLU6Impl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MSELossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< CosineSimilarityImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< CosineEmbeddingLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TransformerDecoderImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TanhImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< NLLLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< MarginRankingLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< BCEWithLogitsLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< TransformerEncoderImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< PixelShuffleImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< KLDivLossImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< GroupNormImpl >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable), [torch::nn::Cloneable< Derived >](utilities.html#PyTorchclasstorch_1_1nn_1_1_cloneable)

Public Types

using ModuleApplyFunction = std::function<void(Module&)>

using ConstModuleApplyFunction = std::function<void(const Module&)>

using NamedModuleApplyFunction = std::function<void(const std::string&, Module&)>

using ConstNamedModuleApplyFunction = std::function<void(const std::string&, const Module&)>

using ModulePointerApplyFunction = std::function<void(const std::shared_ptr<Module>&)>

using NamedModulePointerApplyFunction = std::function<void(const std::string&, const std::shared_ptr<Module>&)>

Public Functions

explicit Module(std::string name)

Tells the base `Module` about the name of the submodule.

Module()

Constructs the module without immediate knowledge of the submodule's name.

The name of the submodule is inferred via RTTI (if possible) the first time `.name()` is invoked.

Module(const Module&) = default

Module &operator=(const Module&) = default

Module(Module&&) noexcept = default

Module &operator=(Module&&) noexcept = default

virtual ~Module() = default

const std::string &name() const noexcept

Returns the name of the `Module`.

A `Module` has an associated `name`, which is a string representation of the kind of concrete `Module` it represents, such as `"Linear"` for the `[Linear](linear.html#PyTorchclasstorch_1_1nn_1_1_linear)` module. Under most circumstances, this name is automatically inferred via runtime type information (RTTI). In the unusual circumstance that you have this feature disabled, you may want to manually name your `Module`s by passing the string name to the `Module` base class' constructor.

virtual std::shared_ptr<Module> clone(const std::optional<Device> &device = std::nullopt) const

Performs a recursive deep copy of the module and all its registered parameters, buffers and submodules.

Optionally, this method sets the current device to the one supplied before cloning. If no device is given, each parameter and buffer will be moved to the device of its source.

- .. attention::
- Attempting to call the `clone()` method inherited from the base `Module`
- class (the one documented here) will fail. To inherit an actual
- implementation of `clone()`, you must subclass `Cloneable`. `Cloneable`
- is templatized on the concrete module type, and can thus properly copy a
- `Module`. This method is provided on the base class' API solely for an
- easier-to-use polymorphic interface.
- 

void apply(const ModuleApplyFunction &function)

Applies the `function` to the `Module` and recursively to every submodule.

The function must accept a `Module&`.

- .. code-block:: cpp
- 
- ```
MyModule module;
```
- ```
module->apply([](nn::Module& module) {
```
- ```
std::cout << module.name() << std::endl;
```
- ```
});
```
- 
- 

void apply(const ConstModuleApplyFunction &function) const

Applies the `function` to the `Module` and recursively to every submodule.

The function must accept a `const Module&`.

- .. code-block:: cpp
- 
- ```
MyModule module;
```
- ```
module->apply([](const nn::Module& module) {
```
- ```
std::cout << module.name() << std::endl;
```
- ```
});
```
- 
- 

void apply(const NamedModuleApplyFunction &function, const std::string &name_prefix = std::string())

Applies the `function` to the `Module` and recursively to every submodule.

The function must accept a `const std::string&` for the key of the module, and a `Module&`. The key of the module itself is the empty string. If `name_prefix` is given, it is prepended to every key as `<name_prefix>.<key>` (and just `name_prefix` for the module itself).

- .. code-block:: cpp
- 
- ```
MyModule module;
```
- ```
module->apply([](const std::string& key, nn::Module& module) {
```
- ```
std::cout << key << ": " << module.name() << std::endl;
```
- ```
});
```
- 
- 

void apply(const ConstNamedModuleApplyFunction &function, const std::string &name_prefix = std::string()) const

Applies the `function` to the `Module` and recursively to every submodule.

The function must accept a `const std::string&` for the key of the module, and a `const Module&`. The key of the module itself is the empty string. If `name_prefix` is given, it is prepended to every key as `<name_prefix>.<key>` (and just `name_prefix` for the module itself).

- .. code-block:: cpp
- 
- ```
MyModule module;
```
- ```
module->apply([](const std::string& key, const nn::Module& module) {
```
- ```
std::cout << key << ": " << module.name() << std::endl;
```
- ```
});
```
- 
- 

void apply(const ModulePointerApplyFunction &function) const

Applies the `function` to the `Module` and recursively to every submodule.

The function must accept a `const std::shared_ptr<Module>&`.

- .. code-block:: cpp
- 
- ```
MyModule module;
```
- ```
module->apply([](const std::shared_ptr<nn::Module>& module) {
```
- ```
std::cout << module->name() << std::endl;
```
- ```
});
```
- 
- 

void apply(const NamedModulePointerApplyFunction &function, const std::string &name_prefix = std::string()) const

Applies the `function` to the `Module` and recursively to every submodule.

The function must accept a `const std::string&` for the key of the module, and a `const std::shared_ptr<Module>&`. The key of the module itself is the empty string. If `name_prefix` is given, it is prepended to every key as `<name_prefix>.<key>` (and just `name_prefix` for the module itself).

- .. code-block:: cpp
- 
- ```
MyModule module;
```
- ```
module->apply([](const std::string& key,
```
- ```
const std::shared_ptr<nn::Module>& module) {
```
- ```
std::cout << key << ": " << module->name() << std::endl;
```
- ```
});
```
- 
- 

std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> parameters(bool recurse = true) const

Returns the parameters of this `Module` and if `recurse` is true, also recursively of every submodule.

[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, [Tensor](../aten/tensor.html#_CPPv46Tensorv)> named_parameters(bool recurse = true) const

Returns an `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)` with the parameters of this `Module` along with their keys, and if `recurse` is true also recursively of every submodule.

std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> buffers(bool recurse = true) const

Returns the buffers of this `Module` and if `recurse` is true, also recursively of every submodule.

[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, [Tensor](../aten/tensor.html#_CPPv46Tensorv)> named_buffers(bool recurse = true) const

Returns an `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)` with the buffers of this `Module` along with their keys, and if `recurse` is true also recursively of every submodule.

std::vector<std::shared_ptr<Module>> modules(bool include_self = true) const

Returns the submodules of this `Module` (the entire submodule hierarchy) and if `include_self` is true, also inserts a `shared_ptr` to this module in the first position.

- .. warning::
- Only pass `include_self` as `true` if this `Module` is stored in a
- `shared_ptr`! Otherwise an exception will be thrown. You may still call
- this method with `include_self` set to false if your `Module` is not
- stored in a `shared_ptr`.
- 

[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, std::shared_ptr<Module>> named_modules(const std::string &name_prefix = std::string(), bool include_self = true) const

Returns an `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)` of the submodules of this `Module` (the entire submodule hierarchy) and their keys, and if `include_self` is true, also inserts a `shared_ptr` to this module in the first position.

If `name_prefix` is given, it is prepended to every key as `<name_prefix>.<key>` (and just `name_prefix` for the module itself).

- .. warning::
- Only pass `include_self` as `true` if this `Module` is stored in a
- `shared_ptr`! Otherwise an exception will be thrown. You may still call
- this method with `include_self` set to false if your `Module` is not
- stored in a `shared_ptr`.
- 

std::vector<std::shared_ptr<Module>> children() const

Returns the direct submodules of this `Module`.

[OrderedDict](../library/registration.html#_CPPv4I00EN5torch11OrderedDictE)<std::string, std::shared_ptr<Module>> named_children() const

Returns an `[OrderedDict](../library/registration.html#PyTorchclasstorch_1_1_ordered_dict)` of the direct submodules of this `Module` and their keys.

virtual void train(bool on = true)

Enables "training" mode.

void eval()

Calls train(false) to enable "eval" mode.

Do not override this method, override `train()` instead.

virtual bool is_training() const noexcept

True if the module is in training mode.

Every `Module` has a boolean associated with it that determines whether the `Module` is currently in *training* mode (set via `.train()`) or in *evaluation* (inference) mode (set via `.eval()`). This property is exposed via `is_training()`, and may be used by the implementation of a concrete module to modify its runtime behavior. See the `BatchNorm` or `[Dropout](dropout.html#PyTorchclasstorch_1_1nn_1_1_dropout)` modules for examples of `Module`s that use different code paths depending on this property.

virtual void to(torch::Device device, torch::Dtype dtype, bool non_blocking = false)

Recursively casts all parameters to the given `dtype` and `device`.

If `non_blocking` is true and the source is in pinned memory and destination is on the GPU or vice versa, the copy is performed asynchronously with respect to the host. Otherwise, the argument has no effect.

virtual void to(torch::Dtype dtype, bool non_blocking = false)

Recursively casts all parameters to the given dtype.

If `non_blocking` is true and the source is in pinned memory and destination is on the GPU or vice versa, the copy is performed asynchronously with respect to the host. Otherwise, the argument has no effect.

virtual void to(torch::Device device, bool non_blocking = false)

Recursively moves all parameters to the given device.

If `non_blocking` is true and the source is in pinned memory and destination is on the GPU or vice versa, the copy is performed asynchronously with respect to the host. Otherwise, the argument has no effect.

virtual void zero_grad(bool set_to_none = true)

Recursively zeros out the `grad` value of each registered parameter.

template<typename ModuleType>
ModuleType::ContainedType *as() noexcept

Attempts to cast this `Module` to the given `ModuleType`.

This method is useful when calling `apply()`.

- .. code-block:: cpp
- 
- ```
void initialize_weights(nn::Module& module) {
```
- ```
torch::NoGradGuard no_grad;
```
- ```
if (auto* linear = module.as<nn::Linear>()) {
```
- ```
linear->weight.normal_(0.0, 0.02);
```
- ```
}
```
- ```
}
```
- 
- ```
MyModule module;
```
- ```
module->apply(initialize_weights);
```
- 
- 

template<typename ModuleType>
const ModuleType::ContainedType *as() const noexcept

Attempts to cast this `Module` to the given `ModuleType`.

This method is useful when calling `apply()`.

- .. code-block:: cpp
- 
- ```
void initialize_weights(nn::Module& module) {
```
- ```
torch::NoGradGuard no_grad;
```
- ```
if (auto* linear = module.as<nn::Linear>()) {
```
- ```
linear->weight.normal_(0.0, 0.02);
```
- ```
}
```
- ```
}
```
- 
- ```
MyModule module;
```
- ```
module->apply(initialize_weights);
```
- 
- 

template<typename ModuleType, typename = torch::detail::disable_if_module_holder_t<ModuleType>>
ModuleType *as() noexcept

Attempts to cast this `Module` to the given `ModuleType`.

This method is useful when calling `apply()`.

- .. code-block:: cpp
- 
- ```
void initialize_weights(nn::Module& module) {
```
- ```
torch::NoGradGuard no_grad;
```
- ```
if (auto* linear = module.as<nn::Linear>()) {
```
- ```
linear->weight.normal_(0.0, 0.02);
```
- ```
}
```
- ```
}
```
- 
- ```
MyModule module;
```
- ```
module.apply(initialize_weights);
```
- 
- 

template<typename ModuleType, typename = torch::detail::disable_if_module_holder_t<ModuleType>>
const ModuleType *as() const noexcept

Attempts to cast this `Module` to the given `ModuleType`.

This method is useful when calling `apply()`.

- .. code-block:: cpp
- 
- ```
void initialize_weights(nn::Module& module) {
```
- ```
torch::NoGradGuard no_grad;
```
- ```
if (auto* linear = module.as<nn::Linear>()) {
```
- ```
linear->weight.normal_(0.0, 0.02);
```
- ```
}
```
- ```
}
```
- 
- ```
MyModule module;
```
- ```
module.apply(initialize_weights);
```
- 
- 

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const

Serializes the `Module` into the given `OutputArchive`.

If the `Module` contains unserializable submodules (e.g. `nn::Functional`), those submodules are skipped when serializing.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive)

Deserializes the `Module` from the given `InputArchive`.

If the `Module` contains unserializable submodules (e.g. `nn::Functional`), we don't check the existence of those submodules in the `InputArchive` when deserializing.

virtual void pretty_print(std::ostream &stream) const

Streams a pretty representation of the `Module` into the given `stream`.

By default, this representation will be the name of the module (taken from `name()`), followed by a recursive pretty print of all of the `Module`'s submodules.

Override this method to change the pretty print. The input `stream` should be returned from the method, to allow easy chaining.

virtual bool is_serializable() const

Returns whether the `Module` is serializable.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) ®ister_parameter(std::string name, [Tensor](../aten/tensor.html#_CPPv46Tensorv) tensor, bool requires_grad = true)

Registers a parameter with this `Module`.

A parameter should be any gradient-recording tensor used in the implementation of your `Module`. Registering it makes it available to methods such as `parameters()`, `clone()` or `to().`

Note that registering an undefined Tensor (e.g. `module.register_parameter("param", Tensor())`) is allowed, and is equivalent to `module.register_parameter("param", None)` in Python API.

- .. code-block:: cpp
- 
- MyModule::MyModule() {
- ```
weight_ = register_parameter("weight", torch::randn({A, B}));
```
- }
- 

[Tensor](../aten/tensor.html#_CPPv46Tensorv) ®ister_buffer(std::string name, [Tensor](../aten/tensor.html#_CPPv46Tensorv) tensor)

Registers a buffer with this `Module`.

A buffer is intended to be state in your module that does not record gradients, such as running statistics. Registering it makes it available to methods such as `buffers()`, `clone()` or `to()`.

- .. code-block:: cpp
- 
- MyModule::MyModule() {
- ```
mean_ = register_buffer("mean", torch::empty({num_features_}));
```
- }
- 

template<typename ModuleType>
std::shared_ptr<ModuleType> register_module(std::string name, std::shared_ptr<ModuleType> module)

Registers a submodule with this `Module`.

Registering a module makes it available to methods such as `modules()`, `clone()` or `to()`.

- .. code-block:: cpp
- 
- MyModule::MyModule() {
- ```
submodule_ = register_module("linear", torch::nn::Linear(3, 4));
```
- }
- 

template<typename ModuleType>
std::shared_ptr<ModuleType> register_module(std::string name, [ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ModuleType> module_holder)

Registers a submodule with this `Module`.

This method deals with `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)`s.

Registering a module makes it available to methods such as `modules()`, `clone()` or `to()`.

- .. code-block:: cpp
- 
- MyModule::MyModule() {
- ```
submodule_ = register_module("linear", torch::nn::Linear(3, 4));
```
- }
- 

template<typename ModuleType>
std::shared_ptr<ModuleType> replace_module(const std::string &name, std::shared_ptr<ModuleType> module)

Replaces a registered submodule with this `Module`.

This takes care of the registration, if you used submodule members, you should assign the submodule as well, i.e. use as module->submodule_ = module->replace_module("linear", [torch::nn::Linear(3, 4)](linear.html#PyTorchclasstorch_1_1nn_1_1_linear)); It only works when a module of the name is already registered.

This is useful for replacing a module after initialization, e.g. for finetuning.

template<typename ModuleType>
std::shared_ptr<ModuleType> replace_module(const std::string &name, [ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<ModuleType> module_holder)

Replaces a registered submodule with this `Module`.

This method deals with `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)`s.

This takes care of the registration, if you used submodule members, you should assign the submodule as well, i.e. use as module->submodule_ = module->replace_module("linear", linear_holder); It only works when a module of the name is already registered.

This is useful for replacing a module after initialization, e.g. for finetuning.

void unregister_module(const std::string &name)

Unregisters a submodule from this `Module`.

If there is no such module with `name` an exception is thrown.

**Key features:**

- `register_module()`: Register submodules for parameter tracking
- `register_parameter()`: Register learnable parameters
- `register_buffer()`: Register non-learnable state (e.g., running mean)
- `parameters()` / `named_parameters()`: Iterate over all parameters
- `to()`: Move module to a device or convert dtype
- `train()` / `eval()`: Toggle training/evaluation mode
- `save()` / `load()`: Serialize and deserialize module state

## Module Categories

- [Containers](containers.html)
- [Convolution Layers](convolution.html)
- [Pooling Layers](pooling.html)
- [Linear Layers](linear.html)
- [Activation Functions](activation.html)
- [Normalization Layers](normalization.html)
- [Dropout Layers](dropout.html)
- [Embedding Layers](embedding.html)
- [Recurrent Layers](recurrent.html)
- [Transformer Layers](transformer.html)
- [Loss Functions](loss.html)
- [Functional API](functional.html)
- [Utilities](utilities.html)

---

# Linear Layers

Linear layers apply affine transformations to input data: `y = xW^T + b`.
They are the building blocks of fully-connected networks and are used for
feature transformation, classification heads, and projection layers.

- **Linear**: Standard fully-connected layer
- **Bilinear**: Bilinear transformation of two inputs
- **Identity**: Pass-through layer (useful for skip connections)
- **Flatten/Unflatten**: Reshape tensors between convolutional and linear layers

## Linear

class Linear : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LinearImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LinearImpl`.

See the documentation for `LinearImpl` class to learn what methods it provides, and examples of how to use `Linear` with `torch::nn::LinearOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LinearImpl

class LinearImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<LinearImpl>

Applies a linear transformation with optional bias.

See [https://pytorch.org/docs/main/generated/torch.nn.Linear.html](https://pytorch.org/docs/main/generated/torch.nn.Linear.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LinearOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Linear model(LinearOptions(5, 2).bias(false));
```

Public Functions

inline LinearImpl(int64_t in_features, int64_t out_features)

explicit LinearImpl(const LinearOptions &options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Linear` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Transforms the `input` tensor by multiplying with the `weight` and optionally adding the `bias`, if `with_bias` is true in the options.

Public Members

LinearOptions options

The options used to configure this module.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The learned weight.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) bias

The learned bias.

If `bias` is false in the `options`, this tensor is undefined.

**Example:**

```
auto linear = torch::nn::Linear(torch::nn::LinearOptions(784, 256).bias(true));
auto output = linear->forward(input); // input: [N, 784]
```

## Bilinear

class Bilinear : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<BilinearImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `BilinearImpl`.

See the documentation for `BilinearImpl` class to learn what methods it provides, and examples of how to use `Bilinear` with `torch::nn::BilinearOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = BilinearImpl

class BilinearImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<BilinearImpl>

Applies a bilinear transformation with optional bias.

See [https://pytorch.org/docs/main/generated/torch.nn.Bilinear.html](https://pytorch.org/docs/main/generated/torch.nn.Bilinear.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::BilinearOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Bilinear model(BilinearOptions(3, 2, 4).bias(false));
```

Public Functions

inline BilinearImpl(int64_t in1_features, int64_t in2_features, int64_t out_features)

explicit BilinearImpl(const BilinearOptions &options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Bilinear` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input2)

Applies a bilinear transform on the `input1` and `input2` tensor by multiplying with the `weight` and optionally adding the `bias`, if `with_bias` is true in the options.

Public Members

BilinearOptions options

The options used to configure this module.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The learned weight.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) bias

The learned bias.

If `with_bias` is false in the `options`, this tensor is undefined.

## Identity

class Identity : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<IdentityImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `IdentityImpl`.

See the documentation for `IdentityImpl` class to learn what methods it provides, or the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = IdentityImpl

class IdentityImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<IdentityImpl>

A placeholder identity operator that is argument-insensitive.

See [https://pytorch.org/docs/main/generated/torch.nn.Identity.html](https://pytorch.org/docs/main/generated/torch.nn.Identity.html) to learn about the exact behavior of this module.

Public Functions

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Identity` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

## Flatten

class Flatten : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<FlattenImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `FlattenImpl`.

See the documentation for `FlattenImpl` class to learn what methods it provides, and examples of how to use `Flatten` with `torch::nn::FlattenOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = FlattenImpl

class FlattenImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<FlattenImpl>

A placeholder for Flatten operator See [https://pytorch.org/docs/main/generated/torch.nn.Flatten.html](https://pytorch.org/docs/main/generated/torch.nn.Flatten.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::FlattenOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Flatten model(FlattenOptions().start_dim(2).end_dim(4));
```

Public Functions

explicit FlattenImpl(const FlattenOptions &options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Flatten` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Applies a flatten transform on the `input`.

Public Members

FlattenOptions options

The options used to configure this module.

## Unflatten

class Unflatten : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<UnflattenImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `UnflattenImpl`.

See the documentation for `UnflattenImpl` class to learn what methods it provides, and examples of how to use `Unflatten` with `torch::nn::UnflattenOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = UnflattenImpl

class UnflattenImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<UnflattenImpl>

A placeholder for unflatten operator See [https://pytorch.org/docs/main/generated/torch.nn.Unflatten.html](https://pytorch.org/docs/main/generated/torch.nn.Unflatten.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::UnflattenOptions` class to learn what constructor arguments are supported for this module.

Example:

```
Unflatten model(UnflattenOptions(0, {2, 2}));
```

Public Functions

inline UnflattenImpl(int64_t dim, std::vector<int64_t> sizes)

explicit UnflattenImpl(UnflattenOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Unflatten` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Applies an unflatten transform on the `input`.

Public Members

UnflattenOptions options

The options used to configure this module.

---

# Loss Functions

Loss functions measure how well the model's predictions match the targets.
The choice of loss function depends on your task type and data characteristics.

**Regression losses:**

- **L1Loss/MSELoss**: Basic regression losses (MAE vs MSE)
- **SmoothL1Loss/HuberLoss**: Robust to outliers

**Classification losses:**

- **CrossEntropyLoss**: Multi-class classification (combines LogSoftmax + NLLLoss)
- **NLLLoss**: Negative log likelihood (use with LogSoftmax output)
- **BCELoss/BCEWithLogitsLoss**: Binary classification

**Specialized losses:**

- **CTCLoss**: Sequence-to-sequence without alignment (speech recognition)
- **TripletMarginLoss**: Metric learning (similarity/embedding tasks)
- **CosineEmbeddingLoss**: Similarity learning with cosine distance

## L1Loss

class L1Loss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<L1LossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `L1LossImpl`.

See the documentation for `L1LossImpl` class to learn what methods it provides, and examples of how to use `L1Loss` with `torch::nn::L1LossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = L1LossImpl

struct L1LossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<L1LossImpl>

Creates a criterion that measures the mean absolute error (MAE) between each element in the input :math:`x` and target :math:`y`.

See [https://pytorch.org/docs/main/nn.html#torch.nn.L1Loss](https://pytorch.org/docs/main/nn.html#torch.nn.L1Loss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::L1LossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
L1Loss model(L1LossOptions(torch::kNone));
```

Public Functions

explicit L1LossImpl(L1LossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `L1Loss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

L1LossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## MSELoss

class MSELoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MSELossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MSELossImpl`.

See the documentation for `MSELossImpl` class to learn what methods it provides, and examples of how to use `MSELoss` with `torch::nn::MSELossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MSELossImpl

struct MSELossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MSELossImpl>

Creates a criterion that measures the mean squared error (squared L2 norm) between each element in the input :math:`x` and target :math:`y`.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MSELoss](https://pytorch.org/docs/main/nn.html#torch.nn.MSELoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MSELossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MSELoss model(MSELossOptions(torch::kNone));
```

Public Functions

explicit MSELossImpl(MSELossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `MSELoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

MSELossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

**Example:**

```
auto loss_fn = torch::nn::MSELoss();
auto loss = loss_fn->forward(predictions, targets);
```

## CrossEntropyLoss

class CrossEntropyLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<CrossEntropyLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `CrossEntropyLossImpl`.

See the documentation for `CrossEntropyLossImpl` class to learn what methods it provides, and examples of how to use `CrossEntropyLoss` with `torch::nn::CrossEntropyLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = CrossEntropyLossImpl

struct CrossEntropyLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<CrossEntropyLossImpl>

Creates a criterion that computes cross entropy loss between input and target.

See [https://pytorch.org/docs/main/nn.html#torch.nn.CrossEntropyLoss](https://pytorch.org/docs/main/nn.html#torch.nn.CrossEntropyLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::CrossEntropyLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
CrossEntropyLoss
model(CrossEntropyLossOptions().ignore_index(-100).reduction(torch::kMean));
```

Public Functions

explicit CrossEntropyLossImpl(CrossEntropyLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `CrossEntropyLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

CrossEntropyLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

A manual rescaling weight given to each class.

**Example:**

```
auto loss_fn = torch::nn::CrossEntropyLoss();
auto logits = torch::randn({32, 10}); // [batch, num_classes]
auto targets = torch::randint(0, 10, {32}); // [batch]
auto loss = loss_fn->forward(logits, targets);
```

## NLLLoss

class NLLLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<NLLLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `NLLLossImpl`.

See the documentation for `NLLLossImpl` class to learn what methods it provides, and examples of how to use `NLLLoss` with `torch::nn::NLLLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = NLLLossImpl

struct NLLLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<NLLLossImpl>

The negative log likelihood loss.

It is useful to train a classification problem with `C` classes. See [https://pytorch.org/docs/main/nn.html#torch.nn.NLLLoss](https://pytorch.org/docs/main/nn.html#torch.nn.NLLLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::NLLLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
NLLLoss model(NLLLossOptions().ignore_index(-100).reduction(torch::kMean));
```

Public Functions

explicit NLLLossImpl(NLLLossOptions options_ = {})

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `NLLLoss` module into the given `stream`.

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

NLLLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

A manual rescaling weight given to each class.

## BCELoss

class BCELoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<BCELossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `BCELossImpl`.

See the documentation for `BCELossImpl` class to learn what methods it provides, and examples of how to use `BCELoss` with `torch::nn::BCELossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = BCELossImpl

struct BCELossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<BCELossImpl>

Creates a criterion that measures the Binary Cross Entropy between the target and the output.

See [https://pytorch.org/docs/main/nn.html#torch.nn.BCELoss](https://pytorch.org/docs/main/nn.html#torch.nn.BCELoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::BCELossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
BCELoss model(BCELossOptions().reduction(torch::kNone).weight(weight));
```

Public Functions

explicit BCELossImpl(BCELossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `BCELoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

BCELossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## BCEWithLogitsLoss

class BCEWithLogitsLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<BCEWithLogitsLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `BCEWithLogitsLossImpl`.

See the documentation for `BCEWithLogitsLossImpl` class to learn what methods it provides, and examples of how to use `BCEWithLogitsLoss` with `torch::nn::BCEWithLogitsLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = BCEWithLogitsLossImpl

struct BCEWithLogitsLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<BCEWithLogitsLossImpl>

This loss combines a `[Sigmoid](activation.html#PyTorchclasstorch_1_1nn_1_1_sigmoid)` layer and the `BCELoss` in one single class.

This version is more numerically stable than using a plain `[Sigmoid](activation.html#PyTorchclasstorch_1_1nn_1_1_sigmoid)` followed by a `BCELoss` as, by combining the operations into one layer, we take advantage of the log-sum-exp trick for numerical stability. See [https://pytorch.org/docs/main/nn.html#torch.nn.BCEWithLogitsLoss](https://pytorch.org/docs/main/nn.html#torch.nn.BCEWithLogitsLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::BCEWithLogitsLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
BCEWithLogitsLoss
model(BCEWithLogitsLossOptions().reduction(torch::kNone).weight(weight));
```

Public Functions

explicit BCEWithLogitsLossImpl(BCEWithLogitsLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `BCEWithLogitsLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

BCEWithLogitsLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

A manual rescaling weight given to the loss of each batch element.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) pos_weight

A weight of positive examples.

## HuberLoss

class HuberLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<HuberLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `HuberLossImpl`.

See the documentation for `HuberLossImpl` class to learn what methods it provides, and examples of how to use `HuberLoss` with `torch::nn::HuberLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = HuberLossImpl

struct HuberLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<HuberLossImpl>

Creates a criterion that uses a squared term if the absolute element-wise error falls below delta and a delta-scaled L1 term otherwise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.HuberLoss](https://pytorch.org/docs/main/nn.html#torch.nn.HuberLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::HuberLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
HuberLoss model(HuberLossOptions().reduction(torch::kNone).delta(0.5));
```

Public Functions

explicit HuberLossImpl(HuberLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `HuberLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

HuberLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## SmoothL1Loss

class SmoothL1Loss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SmoothL1LossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SmoothL1LossImpl`.

See the documentation for `SmoothL1LossImpl` class to learn what methods it provides, and examples of how to use `SmoothL1Loss` with `torch::nn::SmoothL1LossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SmoothL1LossImpl

struct SmoothL1LossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SmoothL1LossImpl>

Creates a criterion that uses a squared term if the absolute element-wise error falls below beta and an L1 term otherwise.

It is less sensitive to outliers than the `MSELoss` and in some cases prevents exploding gradients (e.g. see the paper `Fast R-CNN` by Ross Girshick). See [https://pytorch.org/docs/main/nn.html#torch.nn.SmoothL1Loss](https://pytorch.org/docs/main/nn.html#torch.nn.SmoothL1Loss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SmoothL1LossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
SmoothL1Loss model(SmoothL1LossOptions().reduction(torch::kNone).beta(0.5));
```

Public Functions

explicit SmoothL1LossImpl(SmoothL1LossOptions options = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `L1Loss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

SmoothL1LossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## KLDivLoss

class KLDivLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<KLDivLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `KLDivLossImpl`.

See the documentation for `KLDivLossImpl` class to learn what methods it provides, and examples of how to use `KLDivLoss` with `torch::nn::KLDivLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = KLDivLossImpl

struct KLDivLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<KLDivLossImpl>

The Kullback-Leibler divergence loss measure See [https://pytorch.org/docs/main/nn.html#torch.nn.KLDivLoss](https://pytorch.org/docs/main/nn.html#torch.nn.KLDivLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::KLDivLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
KLDivLoss model(KLDivLossOptions().reduction(torch::kNone));
```

Public Functions

explicit KLDivLossImpl(KLDivLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `KLDivLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

KLDivLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## CTCLoss

class CTCLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<CTCLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `CTCLossImpl`.

See the documentation for `CTCLossImpl` class to learn what methods it provides, and examples of how to use `CTCLoss` with `torch::nn::CTCLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = CTCLossImpl

struct CTCLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<CTCLossImpl>

The Connectionist Temporal Classification loss.

See [https://pytorch.org/docs/main/nn.html#torch.nn.CTCLoss](https://pytorch.org/docs/main/nn.html#torch.nn.CTCLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::CTCLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
CTCLoss
model(CTCLossOptions().blank(42).zero_infinity(false).reduction(torch::kSum));
```

Public Functions

explicit CTCLossImpl(CTCLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `CTCLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &log_probs, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &targets, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input_lengths, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target_lengths)

Public Members

CTCLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## PoissonNLLLoss

class PoissonNLLLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<PoissonNLLLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `PoissonNLLLossImpl`.

See the documentation for `PoissonNLLLossImpl` class to learn what methods it provides, and examples of how to use `PoissonNLLLoss` with `torch::nn::PoissonNLLLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = PoissonNLLLossImpl

struct PoissonNLLLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<PoissonNLLLossImpl>

Negative log likelihood loss with Poisson distribution of target.

See [https://pytorch.org/docs/main/nn.html#torch.nn.PoissonNLLLoss](https://pytorch.org/docs/main/nn.html#torch.nn.PoissonNLLLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::PoissonNLLLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
PoissonNLLLoss
model(PoissonNLLLossOptions().log_input(false).full(true).eps(0.42).reduction(torch::kSum));
```

Public Functions

explicit PoissonNLLLossImpl(PoissonNLLLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `PoissonNLLLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &log_input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &targets)

Public Members

PoissonNLLLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## MarginRankingLoss

class MarginRankingLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MarginRankingLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MarginRankingLossImpl`.

See the documentation for `MarginRankingLossImpl` class to learn what methods it provides, and examples of how to use `MarginRankingLoss` with `torch::nn::MarginRankingLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MarginRankingLossImpl

struct MarginRankingLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MarginRankingLossImpl>

Creates a criterion that measures the loss given inputs :math:`x1`, :math:`x2`, two 1D mini-batch `Tensors`, and a label 1D mini-batch tensor :math:`y` (containing 1 or -1).

See [https://pytorch.org/docs/main/nn.html#torch.nn.MarginRankingLoss](https://pytorch.org/docs/main/nn.html#torch.nn.MarginRankingLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MarginRankingLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MarginRankingLoss
model(MarginRankingLossOptions().margin(0.5).reduction(torch::kSum));
```

Public Functions

explicit MarginRankingLossImpl(MarginRankingLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `MarginRankingLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input2, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &targets)

Public Members

MarginRankingLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## HingeEmbeddingLoss

class HingeEmbeddingLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<HingeEmbeddingLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `HingeEmbeddingLossImpl`.

See the documentation for `HingeEmbeddingLossImpl` class to learn what methods it provides, and examples of how to use `HingeEmbeddingLoss` with `torch::nn::HingeEmbeddingLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = HingeEmbeddingLossImpl

struct HingeEmbeddingLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<HingeEmbeddingLossImpl>

Creates a criterion that measures the loss given an input tensor :math:`x` and a labels tensor :math:`y` (containing 1 or -1).

See [https://pytorch.org/docs/main/nn.html#torch.nn.HingeEmbeddingLoss](https://pytorch.org/docs/main/nn.html#torch.nn.HingeEmbeddingLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::HingeEmbeddingLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
HingeEmbeddingLoss
model(HingeEmbeddingLossOptions().margin(4).reduction(torch::kNone));
```

Public Functions

explicit HingeEmbeddingLossImpl(HingeEmbeddingLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `HingeEmbeddingLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

HingeEmbeddingLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## CosineEmbeddingLoss

class CosineEmbeddingLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<CosineEmbeddingLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `CosineEmbeddingLossImpl`.

See the documentation for `CosineEmbeddingLossImpl` class to learn what methods it provides, and examples of how to use `CosineEmbeddingLoss` with `torch::nn::CosineEmbeddingLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = CosineEmbeddingLossImpl

struct CosineEmbeddingLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<CosineEmbeddingLossImpl>

Creates a criterion that measures the loss given input tensors `input1`, `input2`, and a `Tensor` label `target` with values 1 or -1.

This is used for measuring whether two inputs are similar or dissimilar, using the cosine distance, and is typically used for learning nonlinear embeddings or semi-supervised learning. See [https://pytorch.org/docs/main/nn.html#torch.nn.CosineEmbeddingLoss](https://pytorch.org/docs/main/nn.html#torch.nn.CosineEmbeddingLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::CosineEmbeddingLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
CosineEmbeddingLoss model(CosineEmbeddingLossOptions().margin(0.5));
```

Public Functions

explicit CosineEmbeddingLossImpl(CosineEmbeddingLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `CosineEmbeddingLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input1, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input2, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

CosineEmbeddingLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## MultiMarginLoss

class MultiMarginLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MultiMarginLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MultiMarginLossImpl`.

See the documentation for `MultiMarginLossImpl` class to learn what methods it provides, and examples of how to use `MultiMarginLoss` with `torch::nn::MultiMarginLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MultiMarginLossImpl

struct MultiMarginLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MultiMarginLossImpl>

Creates a criterion that optimizes a multi-class classification hinge loss (margin-based loss) between input :math:`x` (a 2D mini-batch `Tensor`) and output :math:`y` (which is a 1D tensor of target class indices, :math:`0 \leq y \leq \text{x.size}(1)-1`).

See [https://pytorch.org/docs/main/nn.html#torch.nn.MultiMarginLoss](https://pytorch.org/docs/main/nn.html#torch.nn.MultiMarginLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MultiMarginLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MultiMarginLoss model(MultiMarginLossOptions().margin(2).weight(weight));
```

Public Functions

explicit MultiMarginLossImpl(MultiMarginLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `MultiMarginLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

MultiMarginLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## MultiLabelMarginLoss

class MultiLabelMarginLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MultiLabelMarginLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MultiLabelMarginLossImpl`.

See the documentation for `MultiLabelMarginLossImpl` class to learn what methods it provides, and examples of how to use `MultiLabelMarginLoss` with `torch::nn::MultiLabelMarginLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MultiLabelMarginLossImpl

struct MultiLabelMarginLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MultiLabelMarginLossImpl>

Creates a criterion that optimizes a multi-class multi-classification hinge loss (margin-based loss) between input :math:`x` (a 2D mini-batch `Tensor`) and output :math:`y` (which is a 2D `Tensor` of target class indices).

See [https://pytorch.org/docs/main/nn.html#torch.nn.MultiLabelMarginLoss](https://pytorch.org/docs/main/nn.html#torch.nn.MultiLabelMarginLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MultiLabelMarginLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MultiLabelMarginLoss model(MultiLabelMarginLossOptions(torch::kNone));
```

Public Functions

explicit MultiLabelMarginLossImpl(MultiLabelMarginLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `L1Loss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

MultiLabelMarginLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## MultiLabelSoftMarginLoss

class MultiLabelSoftMarginLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MultiLabelSoftMarginLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MultiLabelSoftMarginLossImpl`.

See the documentation for `MultiLabelSoftMarginLossImpl` class to learn what methods it provides, and examples of how to use `MultiLabelSoftMarginLoss` with `torch::nn::MultiLabelSoftMarginLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MultiLabelSoftMarginLossImpl

struct MultiLabelSoftMarginLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MultiLabelSoftMarginLossImpl>

Creates a criterion that optimizes a multi-label one-versus-all loss based on max-entropy, between input :math:`x` and target :math:`y` of size :math:`(N, C)`.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MultiLabelSoftMarginLoss](https://pytorch.org/docs/main/nn.html#torch.nn.MultiLabelSoftMarginLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MultiLabelSoftMarginLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MultiLabelSoftMarginLoss
model(MultiLabelSoftMarginLossOptions().reduction(torch::kNone).weight(weight));
```

Public Functions

explicit MultiLabelSoftMarginLossImpl(MultiLabelSoftMarginLossOptions options_ = {})

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `MultiLabelSoftMarginLoss` module into the given `stream`.

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

MultiLabelSoftMarginLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## SoftMarginLoss

class SoftMarginLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<SoftMarginLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `SoftMarginLossImpl`.

See the documentation for `SoftMarginLossImpl` class to learn what methods it provides, and examples of how to use `SoftMarginLoss` with `torch::nn::SoftMarginLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = SoftMarginLossImpl

struct SoftMarginLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<SoftMarginLossImpl>

Creates a criterion that optimizes a two-class classification logistic loss between input tensor :math:`x` and target tensor :math:`y` (containing 1 or -1).

See [https://pytorch.org/docs/main/nn.html#torch.nn.SoftMarginLoss](https://pytorch.org/docs/main/nn.html#torch.nn.SoftMarginLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::SoftMarginLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
SoftMarginLoss model(SoftMarginLossOptions(torch::kNone));
```

Public Functions

explicit SoftMarginLossImpl(SoftMarginLossOptions options_ = {})

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `SoftMarginLoss` module into the given `stream`.

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &target)

Public Members

SoftMarginLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## TripletMarginLoss

class TripletMarginLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TripletMarginLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TripletMarginLossImpl`.

See the documentation for `TripletMarginLossImpl` class to learn what methods it provides, and examples of how to use `TripletMarginLoss` with `torch::nn::TripletMarginLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TripletMarginLossImpl

struct TripletMarginLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TripletMarginLossImpl>

Creates a criterion that measures the triplet loss given an input tensors :math:`x1`, :math:`x2`, :math:`x3` and a margin with a value greater than :math:`0`.

This is used for measuring a relative similarity between samples. A triplet is composed by `a`, `p` and `n` (i.e., `anchor`, `positive examples` and `negative examples` respectively). The shapes of all input tensors should be :math:`(N, D)`. See [https://pytorch.org/docs/main/nn.html#torch.nn.TripletMarginLoss](https://pytorch.org/docs/main/nn.html#torch.nn.TripletMarginLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::TripletMarginLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
TripletMarginLoss
model(TripletMarginLossOptions().margin(3).p(2).eps(1e-06).swap(false));
```

Public Functions

explicit TripletMarginLossImpl(TripletMarginLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `TripletMarginLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &anchor, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &positive, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &negative)

Public Members

TripletMarginLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

## TripletMarginWithDistanceLoss

class TripletMarginWithDistanceLoss : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TripletMarginWithDistanceLossImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TripletMarginWithDistanceLossImpl`.

See the documentation for `TripletMarginWithDistanceLossImpl` class to learn what methods it provides, and examples of how to use `TripletMarginWithDistanceLoss` with `torch::nn::TripletMarginWithDistanceLossOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TripletMarginWithDistanceLossImpl

struct TripletMarginWithDistanceLossImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TripletMarginWithDistanceLossImpl>

Creates a criterion that measures the triplet loss given input tensors :math:`a`, :math:`p`, and :math:`n` (representing anchor, positive, and negative examples, respectively); and a nonnegative, real-valued function ("distance function") used to compute the relationships between the anchor and positive example ("positive distance") and the anchor and negative example ("negative distance").

See [https://pytorch.org/docs/main/nn.html#torch.nn.TripletMarginWithDistanceLoss](https://pytorch.org/docs/main/nn.html#torch.nn.TripletMarginWithDistanceLoss) to learn about the exact behavior of this module.

See the documentation for `torch::nn::TripletMarginWithDistanceLossOptions` class to learn what constructor arguments are supported for this module.

Example:

```
TripletMarginWithDistanceLoss
model(TripletMarginWithDistanceLossOptions().margin(3).swap(false));
```

Public Functions

explicit TripletMarginWithDistanceLossImpl(TripletMarginWithDistanceLossOptions options_ = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `TripletMarginWithDistanceLoss` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &anchor, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &positive, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &negative)

Public Members

TripletMarginWithDistanceLossOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

---

# Normalization Layers

Normalization layers stabilize and accelerate training by normalizing intermediate
activations. They help with gradient flow and allow higher learning rates.

- **BatchNorm**: Normalizes across batch dimension; most common in CNNs
- **InstanceNorm**: Normalizes each sample independently; popular in style transfer
- **LayerNorm**: Normalizes across feature dimension; standard in transformers
- **GroupNorm**: Normalizes within groups of channels; works with small batches
- **LocalResponseNorm**: Lateral inhibition inspired by neuroscience (less common today)

## BatchNorm1d / BatchNorm2d / BatchNorm3d

class BatchNorm1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<BatchNorm1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `BatchNorm1dImpl`.

See the documentation for `BatchNorm1dImpl` class to learn what methods it provides, and examples of how to use `BatchNorm1d` with `torch::nn::BatchNorm1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = BatchNorm1dImpl

class BatchNorm1dImpl : public torch::nn::BatchNormImplBase<1, BatchNorm1dImpl>

Applies the BatchNorm1d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.BatchNorm1d](https://pytorch.org/docs/main/nn.html#torch.nn.BatchNorm1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::BatchNorm1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
BatchNorm1d
model(BatchNorm1dOptions(4).eps(0.5).momentum(0.1).affine(false).track_running_stats(true));
```

class BatchNorm2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<BatchNorm2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `BatchNorm2dImpl`.

See the documentation for `BatchNorm2dImpl` class to learn what methods it provides, and examples of how to use `BatchNorm2d` with `torch::nn::BatchNorm2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = BatchNorm2dImpl

class BatchNorm2dImpl : public torch::nn::BatchNormImplBase<2, BatchNorm2dImpl>

Applies the BatchNorm2d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.BatchNorm2d](https://pytorch.org/docs/main/nn.html#torch.nn.BatchNorm2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::BatchNorm2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
BatchNorm2d
model(BatchNorm2dOptions(4).eps(0.5).momentum(0.1).affine(false).track_running_stats(true));
```

class BatchNorm3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<BatchNorm3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `BatchNorm3dImpl`.

See the documentation for `BatchNorm3dImpl` class to learn what methods it provides, and examples of how to use `BatchNorm3d` with `torch::nn::BatchNorm3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = BatchNorm3dImpl

class BatchNorm3dImpl : public torch::nn::BatchNormImplBase<3, BatchNorm3dImpl>

Applies the BatchNorm3d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.BatchNorm3d](https://pytorch.org/docs/main/nn.html#torch.nn.BatchNorm3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::BatchNorm3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
BatchNorm3d
model(BatchNorm3dOptions(4).eps(0.5).momentum(0.1).affine(false).track_running_stats(true));
```

**Example:**

```
auto bn = torch::nn::BatchNorm2d(
 torch::nn::BatchNorm2dOptions(64) // num_features
 .eps(1e-5)
 .momentum(0.1)
 .affine(true)
 .track_running_stats(true));
```

## InstanceNorm1d / InstanceNorm2d / InstanceNorm3d

class InstanceNorm1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<InstanceNorm1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `InstanceNorm1dImpl`.

See the documentation for `InstanceNorm1dImpl` class to learn what methods it provides, and examples of how to use `InstanceNorm1d` with `torch::nn::InstanceNorm1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = InstanceNorm1dImpl

class InstanceNorm1dImpl : public torch::nn::InstanceNormImpl<1, InstanceNorm1dImpl>

Applies the InstanceNorm1d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.InstanceNorm1d](https://pytorch.org/docs/main/nn.html#torch.nn.InstanceNorm1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::InstanceNorm1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
InstanceNorm1d
model(InstanceNorm1dOptions(4).eps(0.5).momentum(0.1).affine(false).track_running_stats(true));
```

class InstanceNorm2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<InstanceNorm2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `InstanceNorm2dImpl`.

See the documentation for `InstanceNorm2dImpl` class to learn what methods it provides, and examples of how to use `InstanceNorm2d` with `torch::nn::InstanceNorm2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = InstanceNorm2dImpl

class InstanceNorm2dImpl : public torch::nn::InstanceNormImpl<2, InstanceNorm2dImpl>

Applies the InstanceNorm2d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.InstanceNorm2d](https://pytorch.org/docs/main/nn.html#torch.nn.InstanceNorm2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::InstanceNorm2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
InstanceNorm2d
model(InstanceNorm2dOptions(4).eps(0.5).momentum(0.1).affine(false).track_running_stats(true));
```

class InstanceNorm3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<InstanceNorm3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `InstanceNorm3dImpl`.

See the documentation for `InstanceNorm3dImpl` class to learn what methods it provides, and examples of how to use `InstanceNorm3d` with `torch::nn::InstanceNorm3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = InstanceNorm3dImpl

class InstanceNorm3dImpl : public torch::nn::InstanceNormImpl<3, InstanceNorm3dImpl>

Applies the InstanceNorm3d function.

See [https://pytorch.org/docs/main/nn.html#torch.nn.InstanceNorm3d](https://pytorch.org/docs/main/nn.html#torch.nn.InstanceNorm3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::InstanceNorm3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
InstanceNorm3d
model(InstanceNorm3dOptions(4).eps(0.5).momentum(0.1).affine(false).track_running_stats(true));
```

## LayerNorm

class LayerNorm : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LayerNormImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LayerNormImpl`.

See the documentation for `LayerNormImpl` class to learn what methods it provides, and examples of how to use `LayerNorm` with `torch::nn::LayerNormOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LayerNormImpl

class LayerNormImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<LayerNormImpl>

Applies Layer Normalization over a mini-batch of inputs as described in the paper `Layer Normalization`_ .

See [https://pytorch.org/docs/main/nn.html#torch.nn.LayerNorm](https://pytorch.org/docs/main/nn.html#torch.nn.LayerNorm) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LayerNormOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LayerNorm model(LayerNormOptions({2,
2}).elementwise_affine(false).eps(2e-5));
```

Public Functions

inline LayerNormImpl(std::vector<int64_t> normalized_shape)

explicit LayerNormImpl(LayerNormOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `LayerNorm` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Applies layer normalization over a mini-batch of inputs as described in the paper `Layer Normalization`_ .

The mean and standard-deviation are calculated separately over the last certain number of dimensions which have to be of the shape specified by input `normalized_shape`.

`Layer Normalization`: [https://arxiv.org/abs/1607.06450](https://arxiv.org/abs/1607.06450)

Public Members

LayerNormOptions options

The options with which this module was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The learned weight.

Initialized to ones if the `elementwise_affine` option is set to `true` upon construction.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) bias

The learned bias.

Initialized to zeros `elementwise_affine` option is set to `true` upon construction.

**Example:**

```
auto ln = torch::nn::LayerNorm(
 torch::nn::LayerNormOptions({768})); // normalized_shape
```

## GroupNorm

class GroupNorm : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<GroupNormImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `GroupNormImpl`.

See the documentation for `GroupNormImpl` class to learn what methods it provides, and examples of how to use `GroupNorm` with `torch::nn::GroupNormOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = GroupNormImpl

class GroupNormImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<GroupNormImpl>

Applies Group Normalization over a mini-batch of inputs as described in the paper `Group Normalization`_ .

See [https://pytorch.org/docs/main/nn.html#torch.nn.GroupNorm](https://pytorch.org/docs/main/nn.html#torch.nn.GroupNorm) to learn about the exact behavior of this module.

See the documentation for `torch::nn::GroupNormOptions` class to learn what constructor arguments are supported for this module.

Example:

```
GroupNorm model(GroupNormOptions(2, 2).eps(2e-5).affine(false));
```

Public Functions

inline GroupNormImpl(int64_t num_groups, int64_t num_channels)

explicit GroupNormImpl(const GroupNormOptions &options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `GroupNorm` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Public Members

GroupNormOptions options

The options with which this module was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) weight

The learned weight.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) bias

The learned bias.

**Example:**

```
auto gn = torch::nn::GroupNorm(
 torch::nn::GroupNormOptions(32, 256)); // num_groups, num_channels
```

## LocalResponseNorm

class LocalResponseNorm : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LocalResponseNormImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LocalResponseNormImpl`.

See the documentation for `LocalResponseNormImpl` class to learn what methods it provides, and examples of how to use `LocalResponseNorm` with `torch::nn::LocalResponseNormOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LocalResponseNormImpl

class LocalResponseNormImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<LocalResponseNormImpl>

Applies local response normalization over an input signal composed of several input planes, where channels occupy the second dimension.

Applies normalization across channels. See [https://pytorch.org/docs/main/nn.html#torch.nn.LocalResponseNorm](https://pytorch.org/docs/main/nn.html#torch.nn.LocalResponseNorm) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LocalResponseNormOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LocalResponseNorm
model(LocalResponseNormOptions(2).alpha(0.0002).beta(0.85).k(2.));
```

Public Functions

inline LocalResponseNormImpl(int64_t size)

explicit LocalResponseNormImpl(const LocalResponseNormOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `LocalResponseNormImpl` module into the given `stream`.

Public Members

LocalResponseNormOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

---

# Pooling Layers

Pooling layers reduce spatial dimensions by aggregating values in local regions,
providing translation invariance and reducing computational cost in deeper layers.

- **MaxPool**: Takes the maximum value in each pooling window (preserves strong features)
- **AvgPool**: Takes the average value in each pooling window (smoother downsampling)
- **AdaptivePool**: Automatically calculates kernel size to produce a target output size
- **FractionalMaxPool**: Randomized pooling with fractional output size
- **MaxUnpool**: Computes the partial inverse of MaxPool using stored indices
- **LPPool**: Power-average pooling (generalization of avg/max pooling)

## MaxPool1d / MaxPool2d / MaxPool3d

class MaxPool1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MaxPool1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MaxPool1dImpl`.

See the documentation for `MaxPool1dImpl` class to learn what methods it provides, and examples of how to use `MaxPool1d` with `torch::nn::MaxPool1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MaxPool1dImpl

class MaxPool1dImpl : public torch::nn::MaxPoolImpl<1, MaxPool1dImpl>

Applies maxpool over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MaxPool1d](https://pytorch.org/docs/main/nn.html#torch.nn.MaxPool1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MaxPool1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MaxPool1d model(MaxPool1dOptions(3).stride(2));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the outputs and the indices of the max values.

Useful for `torch::nn::MaxUnpool1d` later.

class MaxPool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MaxPool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MaxPool2dImpl`.

See the documentation for `MaxPool2dImpl` class to learn what methods it provides, and examples of how to use `MaxPool2d` with `torch::nn::MaxPool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MaxPool2dImpl

class MaxPool2dImpl : public torch::nn::MaxPoolImpl<2, MaxPool2dImpl>

Applies maxpool over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MaxPool2d](https://pytorch.org/docs/main/nn.html#torch.nn.MaxPool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MaxPool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MaxPool2d model(MaxPool2dOptions({3, 2}).stride({2, 2}));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the outputs and the indices of the max values.

Useful for `torch::nn::MaxUnpool2d` later.

class MaxPool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MaxPool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MaxPool3dImpl`.

See the documentation for `MaxPool3dImpl` class to learn what methods it provides, and examples of how to use `MaxPool3d` with `torch::nn::MaxPool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MaxPool3dImpl

class MaxPool3dImpl : public torch::nn::MaxPoolImpl<3, MaxPool3dImpl>

Applies maxpool over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MaxPool3d](https://pytorch.org/docs/main/nn.html#torch.nn.MaxPool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MaxPool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MaxPool3d model(MaxPool3dOptions(3).stride(2));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the outputs and the indices of the max values.

Useful for `torch::nn::MaxUnpool3d` later.

**Example:**

```
auto pool = torch::nn::MaxPool2d(
 torch::nn::MaxPool2dOptions(2).stride(2));
```

## AvgPool1d / AvgPool2d / AvgPool3d

class AvgPool1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AvgPool1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AvgPool1dImpl`.

See the documentation for `AvgPool1dImpl` class to learn what methods it provides, and examples of how to use `AvgPool1d` with `torch::nn::AvgPool1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AvgPool1dImpl

class AvgPool1dImpl : public torch::nn::AvgPoolImpl<1, AvgPool1dImpl>

Applies avgpool over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AvgPool1d](https://pytorch.org/docs/main/nn.html#torch.nn.AvgPool1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AvgPool1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AvgPool1d model(AvgPool1dOptions(3).stride(2));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

class AvgPool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AvgPool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AvgPool2dImpl`.

See the documentation for `AvgPool2dImpl` class to learn what methods it provides, and examples of how to use `AvgPool2d` with `torch::nn::AvgPool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AvgPool2dImpl

class AvgPool2dImpl : public torch::nn::AvgPoolImpl<2, AvgPool2dImpl>

Applies avgpool over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AvgPool2d](https://pytorch.org/docs/main/nn.html#torch.nn.AvgPool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AvgPool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AvgPool2d model(AvgPool2dOptions({3, 2}).stride({2, 2}));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

class AvgPool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AvgPool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AvgPool3dImpl`.

See the documentation for `AvgPool3dImpl` class to learn what methods it provides, and examples of how to use `AvgPool3d` with `torch::nn::AvgPool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AvgPool3dImpl

class AvgPool3dImpl : public torch::nn::AvgPoolImpl<3, AvgPool3dImpl>

Applies avgpool over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AvgPool3d](https://pytorch.org/docs/main/nn.html#torch.nn.AvgPool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AvgPool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AvgPool3d model(AvgPool3dOptions(5).stride(2));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

## AdaptiveAvgPool1d / AdaptiveAvgPool2d / AdaptiveAvgPool3d

class AdaptiveAvgPool1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AdaptiveAvgPool1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AdaptiveAvgPool1dImpl`.

See the documentation for `AdaptiveAvgPool1dImpl` class to learn what methods it provides, and examples of how to use `AdaptiveAvgPool1d` with `torch::nn::AdaptiveAvgPool1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AdaptiveAvgPool1dImpl

class AdaptiveAvgPool1dImpl : public torch::nn::AdaptiveAvgPoolImpl<1, ExpandingArray<1>, AdaptiveAvgPool1dImpl>

Applies adaptive avgpool over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveAvgPool1d](https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveAvgPool1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AdaptiveAvgPool1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AdaptiveAvgPool1d model(AdaptiveAvgPool1dOptions(5));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

class AdaptiveAvgPool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AdaptiveAvgPool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AdaptiveAvgPool2dImpl`.

See the documentation for `AdaptiveAvgPool2dImpl` class to learn what methods it provides, and examples of how to use `AdaptiveAvgPool2d` with `torch::nn::AdaptiveAvgPool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AdaptiveAvgPool2dImpl

class AdaptiveAvgPool2dImpl : public torch::nn::AdaptiveAvgPoolImpl<2, ExpandingArrayWithOptionalElem<2>, AdaptiveAvgPool2dImpl>

Applies adaptive avgpool over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveAvgPool2d](https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveAvgPool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AdaptiveAvgPool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AdaptiveAvgPool2d model(AdaptiveAvgPool2dOptions({3, 2}));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

class AdaptiveAvgPool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AdaptiveAvgPool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AdaptiveAvgPool3dImpl`.

See the documentation for `AdaptiveAvgPool3dImpl` class to learn what methods it provides, and examples of how to use `AdaptiveAvgPool3d` with `torch::nn::AdaptiveAvgPool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AdaptiveAvgPool3dImpl

class AdaptiveAvgPool3dImpl : public torch::nn::AdaptiveAvgPoolImpl<3, ExpandingArrayWithOptionalElem<3>, AdaptiveAvgPool3dImpl>

Applies adaptive avgpool over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveAvgPool3d](https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveAvgPool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AdaptiveAvgPool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AdaptiveAvgPool3d model(AdaptiveAvgPool3dOptions(3));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

**Example:**

```
// Output will always be 7x7 regardless of input size
auto adaptive_pool = torch::nn::AdaptiveAvgPool2d(
 torch::nn::AdaptiveAvgPool2dOptions({7, 7}));
```

## AdaptiveMaxPool1d / AdaptiveMaxPool2d / AdaptiveMaxPool3d

class AdaptiveMaxPool1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AdaptiveMaxPool1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AdaptiveMaxPool1dImpl`.

See the documentation for `AdaptiveMaxPool1dImpl` class to learn what methods it provides, and examples of how to use `AdaptiveMaxPool1d` with `torch::nn::AdaptiveMaxPool1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AdaptiveMaxPool1dImpl

class AdaptiveMaxPool1dImpl : public torch::nn::AdaptiveMaxPoolImpl<1, ExpandingArray<1>, AdaptiveMaxPool1dImpl>

Applies adaptive maxpool over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveMaxPool1d](https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveMaxPool1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AdaptiveMaxPool1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AdaptiveMaxPool1d model(AdaptiveMaxPool1dOptions(3));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the indices along with the outputs.

Useful to pass to nn.MaxUnpool1d.

class AdaptiveMaxPool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AdaptiveMaxPool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AdaptiveMaxPool2dImpl`.

See the documentation for `AdaptiveMaxPool2dImpl` class to learn what methods it provides, and examples of how to use `AdaptiveMaxPool2d` with `torch::nn::AdaptiveMaxPool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AdaptiveMaxPool2dImpl

class AdaptiveMaxPool2dImpl : public torch::nn::AdaptiveMaxPoolImpl<2, ExpandingArrayWithOptionalElem<2>, AdaptiveMaxPool2dImpl>

Applies adaptive maxpool over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveMaxPool2d](https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveMaxPool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AdaptiveMaxPool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AdaptiveMaxPool2d model(AdaptiveMaxPool2dOptions({3, 2}));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the indices along with the outputs.

Useful to pass to nn.MaxUnpool2d.

class AdaptiveMaxPool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<AdaptiveMaxPool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `AdaptiveMaxPool3dImpl`.

See the documentation for `AdaptiveMaxPool3dImpl` class to learn what methods it provides, and examples of how to use `AdaptiveMaxPool3d` with `torch::nn::AdaptiveMaxPool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = AdaptiveMaxPool3dImpl

class AdaptiveMaxPool3dImpl : public torch::nn::AdaptiveMaxPoolImpl<3, ExpandingArrayWithOptionalElem<3>, AdaptiveMaxPool3dImpl>

Applies adaptive maxpool over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveMaxPool3d](https://pytorch.org/docs/main/nn.html#torch.nn.AdaptiveMaxPool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::AdaptiveMaxPool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
AdaptiveMaxPool3d model(AdaptiveMaxPool3dOptions(3));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the indices along with the outputs.

Useful to pass to nn.MaxUnpool3d.

## FractionalMaxPool2d / FractionalMaxPool3d

class FractionalMaxPool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<FractionalMaxPool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `FractionalMaxPool2dImpl`.

See the documentation for `FractionalMaxPool2dImpl` class to learn what methods it provides, and examples of how to use `FractionalMaxPool2d` with `torch::nn::FractionalMaxPool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = FractionalMaxPool2dImpl

class FractionalMaxPool2dImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<FractionalMaxPool2dImpl>

Applies fractional maxpool over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.FractionalMaxPool2d](https://pytorch.org/docs/main/nn.html#torch.nn.FractionalMaxPool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::FractionalMaxPool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
FractionalMaxPool2d model(FractionalMaxPool2dOptions(5).output_size(1));
```

Public Functions

inline FractionalMaxPool2dImpl(ExpandingArray<2> kernel_size)

explicit FractionalMaxPool2dImpl(FractionalMaxPool2dOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `FractionalMaxPool2d` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the outputs and the indices of the max values.

Useful for `torch::nn::MaxUnpool2d` later.

Public Members

FractionalMaxPool2dOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) _random_samples

class FractionalMaxPool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<FractionalMaxPool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `FractionalMaxPool3dImpl`.

See the documentation for `FractionalMaxPool3dImpl` class to learn what methods it provides, and examples of how to use `FractionalMaxPool3d` with `torch::nn::FractionalMaxPool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = FractionalMaxPool3dImpl

class FractionalMaxPool3dImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<FractionalMaxPool3dImpl>

Applies fractional maxpool over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.FractionalMaxPool3d](https://pytorch.org/docs/main/nn.html#torch.nn.FractionalMaxPool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::FractionalMaxPool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
FractionalMaxPool3d model(FractionalMaxPool3dOptions(5).output_size(1));
```

Public Functions

inline FractionalMaxPool3dImpl(ExpandingArray<3> kernel_size)

explicit FractionalMaxPool3dImpl(FractionalMaxPool3dOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `FractionalMaxPool3d` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_indices(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

Returns the outputs and the indices of the max values.

Useful for `torch::nn::MaxUnpool3d` later.

Public Members

FractionalMaxPool3dOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) _random_samples

## MaxUnpool1d / MaxUnpool2d / MaxUnpool3d

Computes a partial inverse of `MaxPool`, using the indices of the maximum
values computed during pooling to place values back into unpooled positions.

class MaxUnpool1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MaxUnpool1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MaxUnpool1dImpl`.

See the documentation for `MaxUnpool1dImpl` class to learn what methods it provides, and examples of how to use `MaxUnpool1d` with `torch::nn::MaxUnpool1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MaxUnpool1dImpl

class MaxUnpool1dImpl : public torch::nn::MaxUnpoolImpl<1, MaxUnpool1dImpl>

Applies maxunpool over a 1-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MaxUnpool1d](https://pytorch.org/docs/main/nn.html#torch.nn.MaxUnpool1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MaxUnpool1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MaxUnpool1d model(MaxUnpool1dOptions(3).stride(2).padding(1));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices, const std::optional<std::vector<int64_t>> &output_size = std::nullopt)

Friends

*friend struct* torch::nn::AnyModuleHolder

class MaxUnpool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MaxUnpool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MaxUnpool2dImpl`.

See the documentation for `MaxUnpool2dImpl` class to learn what methods it provides, and examples of how to use `MaxUnpool2d` with `torch::nn::MaxUnpool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MaxUnpool2dImpl

class MaxUnpool2dImpl : public torch::nn::MaxUnpoolImpl<2, MaxUnpool2dImpl>

Applies maxunpool over a 2-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MaxUnpool2d](https://pytorch.org/docs/main/nn.html#torch.nn.MaxUnpool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MaxUnpool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MaxUnpool2d model(MaxUnpool2dOptions(3).stride(2).padding(1));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices, const std::optional<std::vector<int64_t>> &output_size = std::nullopt)

Friends

*friend struct* torch::nn::AnyModuleHolder

class MaxUnpool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MaxUnpool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MaxUnpool3dImpl`.

See the documentation for `MaxUnpool3dImpl` class to learn what methods it provides, and examples of how to use `MaxUnpool3d` with `torch::nn::MaxUnpool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MaxUnpool3dImpl

class MaxUnpool3dImpl : public torch::nn::MaxUnpoolImpl<3, MaxUnpool3dImpl>

Applies maxunpool over a 3-D input.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MaxUnpool3d](https://pytorch.org/docs/main/nn.html#torch.nn.MaxUnpool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MaxUnpool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MaxUnpool3d model(MaxUnpool3dOptions(3).stride(2).padding(1));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &indices, const std::optional<std::vector<int64_t>> &output_size = std::nullopt)

Friends

*friend struct* torch::nn::AnyModuleHolder

**Example:**

```
auto pool = torch::nn::MaxPool2d(
 torch::nn::MaxPool2dOptions(2).stride(2).return_indices(true));
auto unpool = torch::nn::MaxUnpool2d(
 torch::nn::MaxUnpoolOptions<2>(2).stride(2));

auto [output, indices] = pool->forward_with_indices(input);
auto reconstructed = unpool->forward(output, indices);
```

## LPPool1d / LPPool2d / LPPool3d

class LPPool1d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LPPool1dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LPPool1dImpl`.

See the documentation for `LPPool1dImpl` class to learn what methods it provides, and examples of how to use `LPPool1d` with `torch::nn::LPPool1dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LPPool1dImpl

class LPPool1dImpl : public torch::nn::LPPoolImpl<1, LPPool1dImpl>

Applies the LPPool1d function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LPPool1d](https://pytorch.org/docs/main/nn.html#torch.nn.LPPool1d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LPPool1dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LPPool1d model(LPPool1dOptions(1, 2).stride(5).ceil_mode(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

class LPPool2d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LPPool2dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LPPool2dImpl`.

See the documentation for `LPPool2dImpl` class to learn what methods it provides, and examples of how to use `LPPool2d` with `torch::nn::LPPool2dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LPPool2dImpl

class LPPool2dImpl : public torch::nn::LPPoolImpl<2, LPPool2dImpl>

Applies the LPPool2d function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LPPool2d](https://pytorch.org/docs/main/nn.html#torch.nn.LPPool2d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LPPool2dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LPPool2d model(LPPool2dOptions(1, std::vector<int64_t>({3, 4})).stride({5,
6}).ceil_mode(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

class LPPool3d : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LPPool3dImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LPPool3dImpl`.

See the documentation for `LPPool3dImpl` class to learn what methods it provides, and examples of how to use `LPPool3d` with `torch::nn::LPPool3dOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LPPool3dImpl

class LPPool3dImpl : public torch::nn::LPPoolImpl<3, LPPool3dImpl>

Applies the LPPool3d function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LPPool3d](https://pytorch.org/docs/main/nn.html#torch.nn.LPPool3d) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LPPool3dOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LPPool3d model(LPPool3dOptions(1, std::vector<int64_t>({3, 4, 5})).stride(
{5, 6, 7}).ceil_mode(true));
```

Public Functions

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input)

---

# Recurrent Layers

Recurrent layers process sequential data by maintaining hidden state across time steps.
They are essential for tasks involving sequences: language modeling, speech recognition,
time series prediction, and more.

- **RNN**: Basic recurrent layer (simple but prone to vanishing gradients)
- **LSTM**: Long Short-Term Memory (gated architecture, handles long-range dependencies)
- **GRU**: Gated Recurrent Unit (simpler than LSTM, often similar performance)
- **Cell variants**: Single-step versions for custom loop implementations

**Key parameters:**

- `input_size`: Number of features in input
- `hidden_size`: Number of features in hidden state
- `num_layers`: Number of stacked recurrent layers
- `batch_first`: If true, input shape is `[batch, seq, features]`
- `bidirectional`: Process sequence in both directions

## RNN

class RNN : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<RNNImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `RNNImpl`.

See the documentation for `RNNImpl` class to learn what methods it provides, and examples of how to use `RNN` with `torch::nn::RNNOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = RNNImpl

class RNNImpl : public torch::nn::detail::RNNImplBase<RNNImpl>

A multi-layer Elman RNN module with [Tanh](activation.html#PyTorchclasstorch_1_1nn_1_1_tanh) or [ReLU](activation.html#PyTorchclasstorch_1_1nn_1_1_re_l_u) activation.

See [https://pytorch.org/docs/main/generated/torch.nn.RNN.html](https://pytorch.org/docs/main/generated/torch.nn.RNN.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::RNNOptions` class to learn what constructor arguments are supported for this module.

Example:

```
RNN model(RNNOptions(128,
64).num_layers(3).dropout(0.2).nonlinearity(torch::kTanh));
```

Public Functions

inline RNNImpl(int64_t input_size, int64_t hidden_size)

explicit RNNImpl(const RNNOptions &options_)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, [Tensor](../aten/tensor.html#_CPPv46Tensorv) hx = {})

std::tuple<torch::nn::utils::rnn::[PackedSequence](utilities.html#_CPPv4N5torch2nn5utils3rnn14PackedSequenceE), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_packed_input(const torch::nn::utils::rnn::[PackedSequence](utilities.html#_CPPv4N5torch2nn5utils3rnn14PackedSequenceE) &packed_input, [Tensor](../aten/tensor.html#_CPPv46Tensorv) hx = {})

Public Members

RNNOptions options

Friends

*friend struct* torch::nn::AnyModuleHolder

**Example:**

```
auto rnn = torch::nn::RNN(
 torch::nn::RNNOptions(128, 256) // input_size, hidden_size
 .num_layers(2)
 .batch_first(true)
 .bidirectional(false));

auto input = torch::randn({32, 10, 128}); // [batch, seq_len, input_size]
auto [output, hidden] = rnn->forward(input);
```

## LSTM

class LSTM : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LSTMImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LSTMImpl`.

See the documentation for `LSTMImpl` class to learn what methods it provides, and examples of how to use `LSTM` with `torch::nn::LSTMOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LSTMImpl

class LSTMImpl : public torch::nn::detail::RNNImplBase<LSTMImpl>

A multi-layer long-short-term-memory (LSTM) module.

See [https://pytorch.org/docs/main/generated/torch.nn.LSTM.html](https://pytorch.org/docs/main/generated/torch.nn.LSTM.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LSTMOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LSTM model(LSTMOptions(2,
4).num_layers(3).batch_first(false).bidirectional(true));
```

Public Functions

inline LSTMImpl(int64_t input_size, int64_t hidden_size)

explicit LSTMImpl(const LSTMOptions &options_)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>> forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, std::optional<std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>> hx_opt = {})

std::tuple<torch::nn::utils::rnn::[PackedSequence](utilities.html#_CPPv4N5torch2nn5utils3rnn14PackedSequenceE), std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>> forward_with_packed_input(const torch::nn::utils::rnn::[PackedSequence](utilities.html#_CPPv4N5torch2nn5utils3rnn14PackedSequenceE) &packed_input, std::optional<std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>> hx_opt = {})

Public Members

LSTMOptions options

Friends

*friend struct* torch::nn::AnyModuleHolder

**Example:**

```
auto lstm = torch::nn::LSTM(
 torch::nn::LSTMOptions(128, 256)
 .num_layers(2)
 .batch_first(true)
 .dropout(0.1)
 .bidirectional(true));

auto input = torch::randn({32, 10, 128});
auto [output, state] = lstm->forward(input);
auto [h_n, c_n] = state; // hidden state, cell state
```

## GRU

class GRU : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<GRUImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `GRUImpl`.

See the documentation for `GRUImpl` class to learn what methods it provides, and examples of how to use `GRU` with `torch::nn::GRUOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = GRUImpl

class GRUImpl : public torch::nn::detail::RNNImplBase<GRUImpl>

A multi-layer gated recurrent unit (GRU) module.

See [https://pytorch.org/docs/main/generated/torch.nn.GRU.html](https://pytorch.org/docs/main/generated/torch.nn.GRU.html) to learn about the exact behavior of this module.

See the documentation for `torch::nn::GRUOptions` class to learn what constructor arguments are supported for this module.

Example:

```
GRU model(GRUOptions(2,
4).num_layers(3).batch_first(false).bidirectional(true));
```

Public Functions

inline GRUImpl(int64_t input_size, int64_t hidden_size)

explicit GRUImpl(const GRUOptions &options_)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, [Tensor](../aten/tensor.html#_CPPv46Tensorv) hx = {})

std::tuple<torch::nn::utils::rnn::[PackedSequence](utilities.html#_CPPv4N5torch2nn5utils3rnn14PackedSequenceE), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward_with_packed_input(const torch::nn::utils::rnn::[PackedSequence](utilities.html#_CPPv4N5torch2nn5utils3rnn14PackedSequenceE) &packed_input, [Tensor](../aten/tensor.html#_CPPv46Tensorv) hx = {})

Public Members

GRUOptions options

Friends

*friend struct* torch::nn::AnyModuleHolder

## RNNCell

class RNNCell : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<RNNCellImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `RNNCellImpl`.

See the documentation for `RNNCellImpl` class to learn what methods it provides, and examples of how to use `RNNCell` with `torch::nn::RNNCellOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = RNNCellImpl

class RNNCellImpl : public torch::nn::detail::RNNCellImplBase<RNNCellImpl>

An Elman RNN cell with tanh or [ReLU](activation.html#PyTorchclasstorch_1_1nn_1_1_re_l_u) non-linearity.

See [https://pytorch.org/docs/main/nn.html#torch.nn.RNNCell](https://pytorch.org/docs/main/nn.html#torch.nn.RNNCell) to learn about the exact behavior of this module.

See the documentation for `torch::nn::RNNCellOptions` class to learn what constructor arguments are supported for this module.

Example:

```
RNNCell model(RNNCellOptions(20,
10).bias(false).nonlinearity(torch::kReLU));
```

Public Functions

inline RNNCellImpl(int64_t input_size, int64_t hidden_size)

explicit RNNCellImpl(const RNNCellOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &hx = {})

Public Members

RNNCellOptions options

Friends

*friend struct* torch::nn::AnyModuleHolder

## LSTMCell

class LSTMCell : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<LSTMCellImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `LSTMCellImpl`.

See the documentation for `LSTMCellImpl` class to learn what methods it provides, and examples of how to use `LSTMCell` with `torch::nn::LSTMCellOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = LSTMCellImpl

class LSTMCellImpl : public torch::nn::detail::RNNCellImplBase<LSTMCellImpl>

A long short-term memory (LSTM) cell.

See [https://pytorch.org/docs/main/nn.html#torch.nn.LSTMCell](https://pytorch.org/docs/main/nn.html#torch.nn.LSTMCell) to learn about the exact behavior of this module.

See the documentation for `torch::nn::LSTMCellOptions` class to learn what constructor arguments are supported for this module.

Example:

```
LSTMCell model(LSTMCellOptions(20, 10).bias(false));
```

Public Functions

inline LSTMCellImpl(int64_t input_size, int64_t hidden_size)

explicit LSTMCellImpl(const LSTMCellOptions &options_)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, std::optional<std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)>> hx_opt = {})

Public Members

LSTMCellOptions options

Friends

*friend struct* torch::nn::AnyModuleHolder

## GRUCell

class GRUCell : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<GRUCellImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `GRUCellImpl`.

See the documentation for `GRUCellImpl` class to learn what methods it provides, and examples of how to use `GRUCell` with `torch::nn::GRUCellOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = GRUCellImpl

class GRUCellImpl : public torch::nn::detail::RNNCellImplBase<GRUCellImpl>

A gated recurrent unit (GRU) cell.

See [https://pytorch.org/docs/main/nn.html#torch.nn.GRUCell](https://pytorch.org/docs/main/nn.html#torch.nn.GRUCell) to learn about the exact behavior of this module.

See the documentation for `torch::nn::GRUCellOptions` class to learn what constructor arguments are supported for this module.

Example:

```
GRUCell model(GRUCellOptions(20, 10).bias(false));
```

Public Functions

inline GRUCellImpl(int64_t input_size, int64_t hidden_size)

explicit GRUCellImpl(const GRUCellOptions &options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &input, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &hx = {})

Public Members

GRUCellOptions options

Friends

*friend struct* torch::nn::AnyModuleHolder

---

# Transformer Layers

Transformer layers use self-attention mechanisms to process sequences in parallel,
enabling efficient training on long sequences. They are the foundation of modern
NLP models (BERT, GPT) and increasingly used in vision and other domains.

- **Transformer**: Complete encoder-decoder architecture
- **TransformerEncoder/Decoder**: Standalone encoder or decoder stacks
- **TransformerEncoderLayer/DecoderLayer**: Individual transformer blocks
- **MultiheadAttention**: Core attention mechanism used throughout

**Key parameters:**

- `d_model`: Dimension of the model (embedding dimension)
- `nhead`: Number of attention heads
- `num_encoder_layers/num_decoder_layers`: Number of stacked layers
- `dim_feedforward`: Dimension of feedforward network
- `dropout`: Dropout rate for regularization

## Transformer

Complete encoder-decoder transformer architecture.

class Transformer : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TransformerImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TransformerImpl`.

See the documentation for `TransformerImpl` class to learn what methods it provides, and examples of how to use `Transformer` with `torch::nn::TransformerOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TransformerImpl

class TransformerImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TransformerImpl>

A transformer model.

User is able to modify the attributes as needed. The architecture is based on the paper "Attention Is All You Need". Ashish Vaswani, Noam Shazeer, Niki Parmar, Jakob Uszkoreit, Llion Jones, Aidan N Gomez, Lukasz Kaiser, and Illia Polosukhin. 2017. Attention is all you need. In Advances in Neural Information Processing Systems, pages 6000-6010.

See [https://pytorch.org/docs/stable/generated/torch.nn.Transformer.html](https://pytorch.org/docs/stable/generated/torch.nn.Transformer.html) to learn about the exact behavior of this transformer model

See the documentation for `torch::nn::Transformer` class to learn what constructor arguments are supported for this encoder layer model

Example:

```
Transformer trans(TransformerOptions(512, 8));
```

Public Functions

explicit TransformerImpl(TransformerOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tgt, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tgt_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &memory_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src_key_padding_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tgt_key_padding_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &memory_key_padding_mask = {})

forward function for Transformer [Module](index.html#PyTorchclasstorch_1_1nn_1_1_module) Args: src: the sequence to the encoder (required).

tgt: the sequence to the decoder (required). src_mask: the additive mask for the src sequence (optional). tgt_mask: the additive mask for the tgt sequence (optional). memory_mask: the additive mask for the encoder output (optional). src_key_padding_mask: the ByteTensor mask for src keys per batch (optional). tgt_key_padding_mask: the ByteTensor mask for tgt keys per batch (optional). memory_key_padding_mask: the ByteTensor mask for memory keys per batch (optional).

Shape: src: `(S, N, E)` tgt: `(T, N, E)` src_mask: `(S, S)` tgt_mask: `(T, T)` memory_mask: `(T, S)` src_key_padding_mask: `(N, S)` tgt_key_padding_mask: `(N, T)` memory_key_padding_mask: `(N, S)`

Note: [src/tgt/memory]_mask ensures that position i is allowed to attend the unmasked positions. If a ByteTensor is provided, the non-zero positions are not allowed to attend while the zero positions will be unchanged. If a BoolTensor is provided, positions with `True` are not allowed to attend while `False` values will be unchanged. If a FloatTensor is provided, it will be added to the attention weight.

[src/tgt/memory]_key_padding_mask provides specified elements in the key to be ignored by the attention. If a ByteTensor is provided, the non-zero positions will be ignored while the zero positions will be unchanged. If a BoolTensor is provided, the positions with the value of `True` will be ignored while the position with the value of `False` will be unchanged.

output: `(T, N, E)`

Note: Due to the multi-head attention architecture in the transformer model, the output sequence length of a transformer is same as the input sequence (i.e. target) length of the decode.

where S is the source sequence length, T is the target sequence length, N is the batch size, E is the feature number.

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

Public Members

TransformerOptions options

options with which this `Transformer` was constructed

[AnyModule](utilities.html#_CPPv4N5torch2nn9AnyModuleE) encoder

encoder module

[AnyModule](utilities.html#_CPPv4N5torch2nn9AnyModuleE) decoder

decoder module

Public Static Functions

static [Tensor](../aten/tensor.html#_CPPv46Tensorv) generate_square_subsequent_mask(int64_t sz)

Generate a square mask for the sequence.

The masked positions are filled with `-inf` in float type. Unmasked positions are filled with `0.0` in float type. Note:

1. This function will always return a CPU tensor.
2. This function requires the platform support IEEE754, since `-inf` is guaranteed to be valid only when IEEE754 is supported. If the platform doesn't support IEEE754, this function will fill the mask with the smallest float number instead of `-inf`, a one time warning will pop up as well.

Friends

*friend struct* torch::nn::AnyModuleHolder

**Example:**

```
auto transformer = torch::nn::Transformer(
 torch::nn::TransformerOptions()
 .d_model(512)
 .nhead(8)
 .num_encoder_layers(6)
 .num_decoder_layers(6)
 .dim_feedforward(2048)
 .dropout(0.1));
```

## TransformerEncoder

Stack of encoder layers for processing source sequences.

class TransformerEncoder : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TransformerEncoderImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TransformerEncoderImpl`.

See the documentation for `TransformerEncoderImpl` class to learn what methods it provides, and examples of how to use `TransformerEncoder` with `torch::nn::TransformerEncoderOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TransformerEncoderImpl

class TransformerEncoderImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TransformerEncoderImpl>

TransformerEncoder module.

See [https://pytorch.org/docs/main/generated/torch.nn.TransformerEncoder.html](https://pytorch.org/docs/main/generated/torch.nn.TransformerEncoder.html) to learn about the exact behavior of this encoder layer module.

See the documentation for `torch::nn::TransformerEncoder` class to learn what constructor arguments are supported for this encoder module.

Example:

```
TransformerEncoderLayer encoderLayer(TransformerEncoderLayerOptions(512,
8).dropout(0.1)); TransformerEncoder
encoder(TransformerEncoderOptions(encoderLayer,
6).norm(LayerNorm(LayerNormOptions({2}))));
```

Public Functions

inline TransformerEncoderImpl(TransformerEncoderLayer encoder_layer, int64_t num_layers)

explicit TransformerEncoderImpl(TransformerEncoderOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src_key_padding_mask = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

Public Members

TransformerEncoderOptions options

options with which this `TransformerEncoder` was constructed

[ModuleList](containers.html#_CPPv4N5torch2nn10ModuleListE) layers = nullptr

module list that contains all the encoder layers

[AnyModule](utilities.html#_CPPv4N5torch2nn9AnyModuleE) norm

optional normalization module

Friends

*friend struct* torch::nn::AnyModuleHolder

## TransformerDecoder

Stack of decoder layers for generating target sequences.

class TransformerDecoder : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<TransformerDecoderImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `TransformerDecoderImpl`.

See the documentation for `TransformerDecoderImpl` class to learn what methods it provides, and examples of how to use `TransformerDecoder` with `torch::nn::TransformerDecoderOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = TransformerDecoderImpl

class TransformerDecoderImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TransformerDecoderImpl>

TransformerDecoder is a stack of N decoder layers.

See [https://pytorch.org/docs/main/generated/torch.nn.TransformerDecoder.html](https://pytorch.org/docs/main/generated/torch.nn.TransformerDecoder.html) to learn about the exact behavior of this decoder module

See the documentation for `torch::nn::TransformerDecoderOptions` class to learn what constructor arguments are supported for this decoder module

Example:

```
TransformerDecoderLayer decoder_layer(TransformerDecoderLayerOptions(512,
8).dropout(0.1)); TransformerDecoder
transformer_decoder(TransformerDecoderOptions(decoder_layer,
6).norm(LayerNorm(LayerNormOptions({2})))); const auto memory =
torch::rand({10, 32, 512}); const auto tgt = torch::rand({20, 32, 512});
auto out = transformer_decoder(tgt, memory);
```

Public Functions

inline TransformerDecoderImpl(TransformerDecoderLayer decoder_layer, int64_t num_layers)

explicit TransformerDecoderImpl(TransformerDecoderOptions options_)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tgt, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &memory, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tgt_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &memory_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tgt_key_padding_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &memory_key_padding_mask = {})

Pass the inputs (and mask) through the decoder layer in turn.

Args: tgt: the sequence to the decoder layer (required). memory: the sequence from the last layer of the encoder (required). tgt_mask: the mask for the tgt sequence (optional). memory_mask: the mask for the memory sequence (optional). tgt_key_padding_mask: the mask for the tgt keys per batch (optional). memory_key_padding_mask: the mask for the memory keys per batch (optional).

Public Members

TransformerDecoderOptions options

The options used to configure this module.

[ModuleList](containers.html#_CPPv4N5torch2nn10ModuleListE) layers = {nullptr}

Cloned layers of decoder layers.

[AnyModule](utilities.html#_CPPv4N5torch2nn9AnyModuleE) norm

optional layer normalization module

Friends

*friend struct* torch::nn::AnyModuleHolder

## TransformerEncoderLayer

Single encoder layer with self-attention and feedforward network.

class TransformerEncoderLayerImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<TransformerEncoderLayerImpl>

TransformerEncoderLayer module.

See [https://pytorch.org/docs/main/generated/torch.nn.TransformerEncoderLayer.html](https://pytorch.org/docs/main/generated/torch.nn.TransformerEncoderLayer.html) to learn about the exact behavior of this encoder layer model

See the documentation for `torch::nn::TransformerEncoderLayer` class to learn what constructor arguments are supported for this encoder layer model

Example:

```
TransformerEncoderLayer encoderLayer(TransformerEncoderLayerOptions(512,
8).dropout(0.1));
```

Public Functions

inline TransformerEncoderLayerImpl(int64_t d_model, int64_t nhead)

explicit TransformerEncoderLayerImpl(TransformerEncoderLayerOptions options_)

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src_mask = {}, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &src_key_padding_mask = {})

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void reset_parameters()

Public Members

TransformerEncoderLayerOptions options

options with which this `TransformerEncoderLayer` was constructed

MultiheadAttention self_attn = nullptr

self attention

[Linear](linear.html#_CPPv4N5torch2nn6LinearE) linear1 = nullptr

feedforward first linear layer

[Dropout](dropout.html#_CPPv4N5torch2nn7DropoutE) dropout = nullptr

feedforward dropout layer

[Linear](linear.html#_CPPv4N5torch2nn6LinearE) linear2 = nullptr

feedforward second linear layer

[LayerNorm](normalization.html#_CPPv4N5torch2nn9LayerNormE) norm1 = nullptr

pre feedforward, normalization layer

[LayerNorm](normalization.html#_CPPv4N5torch2nn9LayerNormE) norm2 = nullptr

post feedforward, normalization layer

[Dropout](dropout.html#_CPPv4N5torch2nn7DropoutE) dropout1 = nullptr

pre feedforward, dropout layer

[Dropout](dropout.html#_CPPv4N5torch2nn7DropoutE) dropout2 = nullptr

post feedforward, dropout layer

Friends

*friend struct* torch::nn::AnyModuleHolder

## TransformerDecoderLayer

Single decoder layer with self-attention, cross-attention, and feedforward network.

Warning

doxygenclass: Cannot find class "TransformerDecoderLayerImpl" in doxygen xml output for project "PyTorch" from directory: ../build/xml

## MultiheadAttention

Scaled dot-product attention with multiple parallel heads.

class MultiheadAttention : public torch::nn::[ModuleHolder](utilities.html#_CPPv4I0EN5torch2nn12ModuleHolderE)<MultiheadAttentionImpl>

A `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` subclass for `MultiheadAttentionImpl`.

See the documentation for `MultiheadAttentionImpl` class to learn what methods it provides, and examples of how to use `MultiheadAttention` with `torch::nn::MultiheadAttentionOptions`. See the documentation for `[ModuleHolder](utilities.html#PyTorchclasstorch_1_1nn_1_1_module_holder)` to learn about PyTorch's module storage semantics.

Public Types

using Impl = MultiheadAttentionImpl

class MultiheadAttentionImpl : public torch::nn::[Cloneable](utilities.html#_CPPv4I0EN5torch2nn9CloneableE)<MultiheadAttentionImpl>

Applies the MultiheadAttention function element-wise.

See [https://pytorch.org/docs/main/nn.html#torch.nn.MultiheadAttention](https://pytorch.org/docs/main/nn.html#torch.nn.MultiheadAttention) to learn about the exact behavior of this module.

See the documentation for `torch::nn::MultiheadAttentionOptions` class to learn what constructor arguments are supported for this module.

Example:

```
MultiheadAttention model(MultiheadAttentionOptions(20, 10).bias(false));
```

Public Functions

inline MultiheadAttentionImpl(int64_t embed_dim, int64_t num_heads)

explicit MultiheadAttentionImpl(const MultiheadAttentionOptions &options_)

std::tuple<[Tensor](../aten/tensor.html#_CPPv46Tensorv), [Tensor](../aten/tensor.html#_CPPv46Tensorv)> forward(const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &query, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &key, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &value, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &key_padding_mask = {}, bool need_weights = true, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &attn_mask = {}, bool average_attn_weights = true)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

void _reset_parameters()

Public Members

MultiheadAttentionOptions options

The options with which this `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` was constructed.

bool _qkv_same_embed_dim = {}

[Tensor](../aten/tensor.html#_CPPv46Tensorv) in_proj_weight

[Tensor](../aten/tensor.html#_CPPv46Tensorv) in_proj_bias

[Tensor](../aten/tensor.html#_CPPv46Tensorv) bias_k

[Tensor](../aten/tensor.html#_CPPv46Tensorv) bias_v

[Linear](linear.html#_CPPv4N5torch2nn6LinearE) out_proj = nullptr

[Tensor](../aten/tensor.html#_CPPv46Tensorv) q_proj_weight

[Tensor](../aten/tensor.html#_CPPv46Tensorv) k_proj_weight

[Tensor](../aten/tensor.html#_CPPv46Tensorv) v_proj_weight

int64_t head_dim = {}

Friends

*friend struct* torch::nn::AnyModuleHolder

---

# Utilities

Additional utilities for building neural networks: parameter initialization,
module cloning, type-erased containers, padding layers, and vision utilities.

## Parameter Initialization

The `torch::nn::init` namespace provides functions for initializing module parameters:

```
#include <torch/nn/init.h>

// Xavier/Glorot initialization
torch::nn::init::xavier_uniform_(linear->weight);
torch::nn::init::xavier_normal_(linear->weight);

// Kaiming/He initialization
torch::nn::init::kaiming_uniform_(conv->weight, /*a=*/0, torch::kFanIn, torch::kReLU);
torch::nn::init::kaiming_normal_(conv->weight);

// Other initializations
torch::nn::init::zeros_(linear->bias);
torch::nn::init::ones_(bn->weight);
torch::nn::init::constant_(linear->bias, 0.1);
torch::nn::init::normal_(linear->weight, /*mean=*/0, /*std=*/0.01);
torch::nn::init::uniform_(linear->weight, /*a=*/-0.1, /*b=*/0.1);
torch::nn::init::orthogonal_(rnn->weight_hh);
```

## Cloneable

template<typename Derived>
class Cloneable : public torch::nn::[Module](index.html#_CPPv4N5torch2nn6ModuleE)

The `clone()` method in the base `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` class does not have knowledge of the concrete runtime type of its subclasses.

Therefore, `clone()` must either be called from within the subclass, or from a base class that has knowledge of the concrete type. `Cloneable` uses the CRTP to gain knowledge of the subclass' static type and provide an implementation of the `clone()` method. We do not want to use this pattern in the base class, because then storing a module would always require templatizing it.

Public Functions

virtual void reset() = 0

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

inline virtual std::shared_ptr<Module> clone(const std::optional<Device> &device = std::nullopt) const override

Performs a recursive "deep copy" of the `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)`, such that all parameters and submodules in the cloned module are different from those in the original module.

explicit Module(std::string name)

Tells the base `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` about the name of the submodule.

Module()

Constructs the module without immediate knowledge of the submodule's name.

The name of the submodule is inferred via RTTI (if possible) the first time `.[name()](index.html#PyTorchclasstorch_1_1nn_1_1_module_1a09407fc8e8eca674c18dd4436f1a7ad2)` is invoked.

Module(const Module&) = default

Module(Module&&) noexcept = default

All `torch::nn` modules inherit from `Cloneable`, enabling deep copies:

```
auto model = torch::nn::Linear(10, 5);
auto model_copy = std::dynamic_pointer_cast<torch::nn::LinearImpl>(model->clone());
```

## AnyModule

`AnyModule` provides type-erased storage for any module, allowing you to
store heterogeneous modules in a single container.

class AnyModule

Stores a type erased `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)`.

The PyTorch C++ API does not impose an interface on the signature of `forward()` in `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` subclasses. This gives you complete freedom to design your `forward()` methods to your liking. However, this also means there is no unified base type you could store in order to call `forward()` polymorphically for any module. This is where the `AnyModule` comes in. Instead of inheritance, it relies on type erasure for polymorphism.

An `AnyModule` can store any `[nn::Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` subclass that provides a `forward()` method. This `forward()` may accept any types and return any type. Once stored in an `AnyModule`, you can invoke the underlying module's `forward()` by calling `AnyModule::forward()` with the arguments you would supply to the stored module (though see one important limitation below). Example:

- .. code-block:: cpp
- 
- struct GenericTrainer {
- ```
torch::nn::AnyModule module;
```
- 
- ```
void train(torch::Tensor input) {
```
- ```
module.forward(input);
```
- ```
}
```
- };
- 
- GenericTrainer trainer1{torch::nn::Linear(3, 4)};
- GenericTrainer trainer2{torch::nn::Conv2d(3, 4, 2)};
- 

As `AnyModule` erases the static type of the stored module (and its `forward()` method) to achieve polymorphism, type checking of arguments is moved to runtime. That is, passing an argument with an incorrect type to an `AnyModule` will compile, but throw an exception at runtime:

- .. code-block:: cpp
- 
- torch::nn::AnyModule module(torch::nn::Linear(3, 4));
- // Linear takes a tensor as input, but we are passing an integer.
- // This will compile, but throw a `torch::Error` exception at runtime.
- module.forward(123);
- 

- .. attention::
- One noteworthy limitation of `AnyModule` is that its `forward()` method
- does not support implicit conversion of argument types. For example, if
- the stored module's `forward()` method accepts a `float` and you call
- `any_module.forward(3.4)` (where `3.4` is a `double`), this will throw
- an exception.
- 

The return type of the `AnyModule`'s `forward()` method is controlled via the first template argument to `AnyModule::forward()`. It defaults to `torch::Tensor`. To change it, you can write `any_module.forward<int>()`, for example.

- .. code-block:: cpp
- 
- torch::nn::AnyModule module(torch::nn::Linear(3, 4));
- auto output = module.forward(torch::ones({2, 3}));
- 
- struct IntModule {
- ```
int forward(int x) { return x; }
```
- };
- torch::nn::AnyModule module(IntModule{});
- int output = module.forward(5);
- 

The only other method an `AnyModule` provides access to on the stored module is `clone()`. However, you may acquire a handle on the module via `.ptr()`, which returns a `shared_ptr<[nn::Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)>`. Further, if you know the concrete type of the stored module, you can get a concrete handle to it using `.get<T>()` where `T` is the concrete module type.

- .. code-block:: cpp
- 
- torch::nn::AnyModule module(torch::nn::Linear(3, 4));
- std::shared_ptr[nn::Module](nn::Module) ptr = module.ptr();
- torch::nn::Linear linear(module.get[torch::nn::Linear](torch::nn::Linear)());
- 

Public Functions

AnyModule() = default

A default-constructed `AnyModule` is in an empty state.

template<typename ModuleType>
explicit AnyModule(std::shared_ptr<ModuleType> module)

Constructs an `AnyModule` from a `shared_ptr` to concrete module object.

template<typename ModuleType, typename = torch::detail::enable_if_module_t<ModuleType>>
explicit AnyModule(ModuleType &&module)

Constructs an `AnyModule` from a concrete module object.

template<typename ModuleType>
explicit AnyModule(const ModuleHolder<ModuleType> &module_holder)

Constructs an `AnyModule` from a module holder.

AnyModule(AnyModule&&) = default

Move construction and assignment is allowed, and follows the default behavior of move for `std::unique_ptr`.

AnyModule &operator=(AnyModule&&) = default

inline AnyModule(const AnyModule &other)

Creates a shallow copy of an `AnyModule`.

inline AnyModule &operator=(const AnyModule &other)

inline AnyModule clone(std::optional<Device> device = std::nullopt) const

Creates a deep copy of an `AnyModule` if it contains a module, else an empty `AnyModule` if it is empty.

template<typename ModuleType>
AnyModule &operator=(std::shared_ptr<ModuleType> module)

Assigns a module to the `AnyModule` (to circumvent the explicit constructor).

template<typename ...ArgumentTypes>
AnyValue any_forward(ArgumentTypes&&... arguments)

Invokes `forward()` on the contained module with the given arguments, and returns the return value as an `AnyValue`.

Use this method when chaining `AnyModule`s in a loop.

template<typename ReturnType = torch::Tensor, typename ...ArgumentTypes>
ReturnType forward(ArgumentTypes&&... arguments)

Invokes `forward()` on the contained module with the given arguments, and casts the returned `AnyValue` to the supplied `ReturnType` (which defaults to `torch::Tensor`).

template<typename T, typename = torch::detail::enable_if_module_t<T>>
T &get()

Attempts to cast the underlying module to the given module type.

Throws an exception if the types do not match.

template<typename T, typename = torch::detail::enable_if_module_t<T>>
const T &get() const

Attempts to cast the underlying module to the given module type.

Throws an exception if the types do not match.

template<typename T, typename ContainedType = typename T::ContainedType>
T get() const

Returns the contained module in a `nn::ModuleHolder` subclass if possible (i.e.

if `T` has a constructor for the underlying module type).

inline std::shared_ptr<[Module](index.html#_CPPv4N5torch2nn6ModuleE)> ptr() const

Returns a `std::shared_ptr` whose dynamic type is that of the underlying module.

template<typename T, typename = torch::detail::enable_if_module_t<T>>
std::shared_ptr<T> ptr() const

Like `ptr()`, but casts the pointer to the given type.

inline const std::type_info &type_info() const

Returns the `type_info` object of the contained value.

inline bool is_empty() const noexcept

Returns true if the `AnyModule` does not contain a module.

**Example:**

```
torch::nn::AnyModule any_module(torch::nn::Linear(10, 5));
auto output = any_module.forward(input);
```

## Functional

Wraps a function or callable as a module, useful for inserting arbitrary
functions into a `Sequential` container.

class FunctionalImpl : public torch::nn::Cloneable<FunctionalImpl>

Wraps a function in a `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)`.

The `Functional` module allows wrapping an arbitrary function or function object in an `[nn::Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)`. This is primarily handy for usage in `[Sequential](containers.html#PyTorchclasstorch_1_1nn_1_1_sequential)`.

- .. code-block:: cpp
- 
- Sequential sequential(
- ```
Linear(3, 4),
```
- ```
Functional(torch::relu),
```
- ```
BatchNorm1d(3),
```
- ```
Functional(torch::elu, /*alpha=*‍/1));
```
- 

While a `Functional` module only accepts a single `Tensor` as input, it is possible for the wrapped function to accept further arguments. However, these have to be bound *at construction time*. For example, if you want to wrap `torch::leaky_relu`, which accepts a `slope` scalar as its second argument, with a particular value for its `slope` in a `Functional` module, you could write

- .. code-block:: cpp
- 
- Functional(torch::leaky_relu, /*slope=*‍/0.5)
- 

The value of `0.5` is then stored within the `Functional` object and supplied to the function call at invocation time. Note that such bound values are evaluated eagerly and stored a single time. See the documentation of [std::bind](https://en.cppreference.com/w/cpp/utility/functional/bind) for more information on the semantics of argument binding.

- .. attention::
- After passing any bound arguments, the function must accept a single
- tensor and return a single tensor.
- 

Note that `Functional` overloads the call operator (`operator()`) such that you can invoke it with `my_func(...)`.

Public Types

using Function = std::function<[Tensor](../aten/tensor.html#_CPPv46Tensorv)([Tensor](../aten/tensor.html#_CPPv46Tensorv))>

Public Functions

explicit FunctionalImpl(Function function)

Constructs a `Functional` from a function object.

template<typename SomeFunction, typename ...Args, typename = std::enable_if_t<(sizeof...(Args) > 0)>>
inline explicit FunctionalImpl(SomeFunction original_function, Args&&... args)

virtual void reset() override

`reset()` must perform initialization of all members with reference semantics, most importantly parameters, buffers and submodules.

virtual void pretty_print(std::ostream &stream) const override

Pretty prints the `Functional` module into the given `stream`.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) forward([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

Forwards the `input` tensor to the underlying (bound) function object.

[Tensor](../aten/tensor.html#_CPPv46Tensorv) operator()([Tensor](../aten/tensor.html#_CPPv46Tensorv) input)

Calls forward(input).

virtual bool is_serializable() const override

Returns whether the `[Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` is serializable.

## ModuleHolder

template<typename Contained>
class ModuleHolder : private torch::detail::ModuleHolderIndicator

A `ModuleHolder` is essentially a wrapper around `std::shared_ptr<M>` where `M` is an `[nn::Module](index.html#PyTorchclasstorch_1_1nn_1_1_module)` subclass, with convenient constructors defined for the kind of constructions we want to allow for our modules.

Public Types

using ContainedType = Contained

Public Functions

inline ModuleHolder()

Default constructs the contained module if it has a default constructor, else produces a static error.

NOTE: This uses the behavior of template classes in C++ that constructors (or any methods) are only compiled when actually used.

inline ModuleHolder(std::nullptr_t)

Constructs the `ModuleHolder` with an empty contained value.

Access to the underlying module is not permitted and will throw an exception, until a value is assigned.

template<typename Head, typename ...Tail, typename = std::enable_if_t<!(torch::detail::is_module_holder_of<Head, ContainedType>::value && (sizeof...(Tail) == 0))>>
inline explicit ModuleHolder(Head &&head, Tail&&... tail)

Constructs the `ModuleHolder` with a contained module, forwarding all arguments to its constructor.

inline ModuleHolder(std::shared_ptr<Contained> module)

Constructs the `ModuleHolder` from a pointer to the contained type.

Example: `[Linear](linear.html#PyTorchclasstorch_1_1nn_1_1_linear)(std::make_shared<[LinearImpl](linear.html#PyTorchclasstorch_1_1nn_1_1_linear_impl)>(...))`.

inline explicit operator bool() const noexcept

Returns true if the `ModuleHolder` contains a module, or false if it is `nullptr`.

inline Contained *operator->()

Forwards to the contained module.

inline const Contained *operator->() const

Forwards to the contained module.

inline Contained &operator*()

Returns a reference to the contained module.

inline const Contained &operator*() const

Returns a const reference to the contained module.

inline const std::shared_ptr<Contained> &ptr() const

Returns a shared pointer to the underlying module.

inline Contained *get()

Returns a pointer to the underlying module.

inline const Contained *get() const

Returns a const pointer to the underlying module.

template<typename ...Args>
inline auto operator()(Args&&... args) -> torch::detail::return_type_of_forward_t<Contained, Args...>

Calls the `forward()` method of the contained module.

template<typename Arg>
inline auto operator[](Arg &&arg)

Forwards to the subscript operator of the contained module.

NOTE: std::forward is qualified to prevent VS2017 emitting error C2872: 'std': ambiguous symbol

inline bool is_empty() const noexcept

Returns true if the `ModuleHolder` does not contain a module.

## CosineSimilarity

class CosineSimilarity : public torch::nn::ModuleHolder<CosineSimilarityImpl>

A `ModuleHolder` subclass for `CosineSimilarityImpl`.

See the documentation for `CosineSimilarityImpl` class to learn what methods it provides, and examples of how to use `CosineSimilarity` with `torch::nn::CosineSimilarityOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = CosineSimilarityImpl

## PairwiseDistance

class PairwiseDistance : public torch::nn::ModuleHolder<PairwiseDistanceImpl>

A `ModuleHolder` subclass for `PairwiseDistanceImpl`.

See the documentation for `PairwiseDistanceImpl` class to learn what methods it provides, and examples of how to use `PairwiseDistance` with `torch::nn::PairwiseDistanceOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = PairwiseDistanceImpl

## PackedSequence

class torch::nn::utils::rnn::PackedSequence

Holds the data and list of `batch_sizes` of a packed sequence.
All RNN modules accept packed sequences as inputs.

const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &data() const

Returns the packed tensor containing all sequence elements.

const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &batch_sizes() const

Returns a 1D tensor of batch sizes at each time step.

const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &sorted_indices() const

Returns indices used to sort sequences by length (descending).

const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &unsorted_indices() const

Returns indices to restore the original sequence order.

PackedSequence to(torch::Device device) const

Moves the packed sequence to the specified device.

See also: `torch::nn::utils::rnn::pack_padded_sequence` and
`torch::nn::utils::rnn::pad_packed_sequence`.

## Padding Layers

### ReflectionPad1d / ReflectionPad2d / ReflectionPad3d

class ReflectionPad1d : public torch::nn::ModuleHolder<ReflectionPad1dImpl>

A `ModuleHolder` subclass for `ReflectionPad1dImpl`.

See the documentation for `ReflectionPad1dImpl` class to learn what methods it provides, and examples of how to use `ReflectionPad1d` with `torch::nn::ReflectionPad1dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReflectionPad1dImpl

class ReflectionPad2d : public torch::nn::ModuleHolder<ReflectionPad2dImpl>

A `ModuleHolder` subclass for `ReflectionPad2dImpl`.

See the documentation for `ReflectionPad2dImpl` class to learn what methods it provides, and examples of how to use `ReflectionPad2d` with `torch::nn::ReflectionPad2dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReflectionPad2dImpl

class ReflectionPad3d : public torch::nn::ModuleHolder<ReflectionPad3dImpl>

A `ModuleHolder` subclass for `ReflectionPad3dImpl`.

See the documentation for `ReflectionPad3dImpl` class to learn what methods it provides, and examples of how to use `ReflectionPad3d` with `torch::nn::ReflectionPad3dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReflectionPad3dImpl

### ReplicationPad1d / ReplicationPad2d / ReplicationPad3d

class ReplicationPad1d : public torch::nn::ModuleHolder<ReplicationPad1dImpl>

A `ModuleHolder` subclass for `ReplicationPad1dImpl`.

See the documentation for `ReplicationPad1dImpl` class to learn what methods it provides, and examples of how to use `ReplicationPad1d` with `torch::nn::ReplicationPad1dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReplicationPad1dImpl

class ReplicationPad2d : public torch::nn::ModuleHolder<ReplicationPad2dImpl>

A `ModuleHolder` subclass for `ReplicationPad2dImpl`.

See the documentation for `ReplicationPad2dImpl` class to learn what methods it provides, and examples of how to use `ReplicationPad2d` with `torch::nn::ReplicationPad2dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReplicationPad2dImpl

class ReplicationPad3d : public torch::nn::ModuleHolder<ReplicationPad3dImpl>

A `ModuleHolder` subclass for `ReplicationPad3dImpl`.

See the documentation for `ReplicationPad3dImpl` class to learn what methods it provides, and examples of how to use `ReplicationPad3d` with `torch::nn::ReplicationPad3dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ReplicationPad3dImpl

### ZeroPad1d / ZeroPad2d / ZeroPad3d

class ZeroPad1d : public torch::nn::ModuleHolder<ZeroPad1dImpl>

A `ModuleHolder` subclass for `ZeroPad1dImpl`.

See the documentation for `ZeroPad1dImpl` class to learn what methods it provides, and examples of how to use `ZeroPad1d` with `torch::nn::ZeroPad1dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ZeroPad1dImpl

class ZeroPad2d : public torch::nn::ModuleHolder<ZeroPad2dImpl>

A `ModuleHolder` subclass for `ZeroPad2dImpl`.

See the documentation for `ZeroPad2dImpl` class to learn what methods it provides, and examples of how to use `ZeroPad2d` with `torch::nn::ZeroPad2dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ZeroPad2dImpl

class ZeroPad3d : public torch::nn::ModuleHolder<ZeroPad3dImpl>

A `ModuleHolder` subclass for `ZeroPad3dImpl`.

See the documentation for `ZeroPad3dImpl` class to learn what methods it provides, and examples of how to use `ZeroPad3d` with `torch::nn::ZeroPad3dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ZeroPad3dImpl

### ConstantPad1d / ConstantPad2d / ConstantPad3d

class ConstantPad1d : public torch::nn::ModuleHolder<ConstantPad1dImpl>

A `ModuleHolder` subclass for `ConstantPad1dImpl`.

See the documentation for `ConstantPad1dImpl` class to learn what methods it provides, and examples of how to use `ConstantPad1d` with `torch::nn::ConstantPad1dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ConstantPad1dImpl

class ConstantPad2d : public torch::nn::ModuleHolder<ConstantPad2dImpl>

A `ModuleHolder` subclass for `ConstantPad2dImpl`.

See the documentation for `ConstantPad2dImpl` class to learn what methods it provides, and examples of how to use `ConstantPad2d` with `torch::nn::ConstantPad2dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ConstantPad2dImpl

class ConstantPad3d : public torch::nn::ModuleHolder<ConstantPad3dImpl>

A `ModuleHolder` subclass for `ConstantPad3dImpl`.

See the documentation for `ConstantPad3dImpl` class to learn what methods it provides, and examples of how to use `ConstantPad3d` with `torch::nn::ConstantPad3dOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = ConstantPad3dImpl

## Vision Layers

### PixelShuffle

class PixelShuffle : public torch::nn::ModuleHolder<PixelShuffleImpl>

A `ModuleHolder` subclass for `PixelShuffleImpl`.

See the documentation for `PixelShuffleImpl` class to learn what methods it provides, and examples of how to use `PixelShuffle` with `torch::nn::PixelShuffleOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = PixelShuffleImpl

struct PixelShuffleOptions

Options for the `PixelShuffle` module.

Example:

```
PixelShuffle model(PixelShuffleOptions(5));
```

Public Functions

inline PixelShuffleOptions(int64_t upscale_factor)

inline auto upscale_factor(const int64_t &new_upscale_factor) -> decltype(*this)

Factor to increase spatial resolution by.

inline auto upscale_factor(int64_t &&new_upscale_factor) -> decltype(*this)

inline const int64_t &upscale_factor() const noexcept

inline int64_t &upscale_factor() noexcept

### PixelUnshuffle

class PixelUnshuffle : public torch::nn::ModuleHolder<PixelUnshuffleImpl>

A `ModuleHolder` subclass for `PixelUnshuffleImpl`.

See the documentation for `PixelUnshuffleImpl` class to learn what methods it provides, and examples of how to use `PixelUnshuffle` with `torch::nn::PixelUnshuffleOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = PixelUnshuffleImpl

struct PixelUnshuffleOptions

Options for the `PixelUnshuffle` module.

Example:

```
PixelUnshuffle model(PixelUnshuffleOptions(5));
```

Public Functions

inline PixelUnshuffleOptions(int64_t downscale_factor)

inline auto downscale_factor(const int64_t &new_downscale_factor) -> decltype(*this)

Factor to decrease spatial resolution by.

inline auto downscale_factor(int64_t &&new_downscale_factor) -> decltype(*this)

inline const int64_t &downscale_factor() const noexcept

inline int64_t &downscale_factor() noexcept

### Upsample

class Upsample : public torch::nn::ModuleHolder<UpsampleImpl>

A `ModuleHolder` subclass for `UpsampleImpl`.

See the documentation for `UpsampleImpl` class to learn what methods it provides, and examples of how to use `Upsample` with `torch::nn::UpsampleOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = UpsampleImpl

struct UpsampleOptions

Options for the `Upsample` module.

Example:

```
Upsample
model(UpsampleOptions().scale_factor(std::vector<double>({3})).mode(torch::kLinear).align_corners(false));
```

Public Functions

inline auto size(const std::optional<std::vector<int64_t>> &new_size) -> decltype(*this)

output spatial sizes.

inline auto size(std::optional<std::vector<int64_t>> &&new_size) -> decltype(*this)

inline const std::optional<std::vector<int64_t>> &size() const noexcept

inline std::optional<std::vector<int64_t>> &size() noexcept

inline auto scale_factor(const std::optional<std::vector<double>> &new_scale_factor) -> decltype(*this)

multiplier for spatial size.

inline auto scale_factor(std::optional<std::vector<double>> &&new_scale_factor) -> decltype(*this)

inline const std::optional<std::vector<double>> &scale_factor() const noexcept

inline std::optional<std::vector<double>> &scale_factor() noexcept

inline auto mode(const mode_t &new_mode) -> decltype(*this)

inline auto mode(mode_t &&new_mode) -> decltype(*this)

inline const mode_t &mode() const noexcept

inline mode_t &mode() noexcept

inline auto align_corners(const std::optional<bool> &new_align_corners) -> decltype(*this)

if "True", the corner pixels of the input and output tensors are aligned, and thus preserving the values at those pixels.

This only has effect when :attr:`mode` is "linear", "bilinear", "bicubic", or "trilinear". Default: "False"

inline auto align_corners(std::optional<bool> &&new_align_corners) -> decltype(*this)

inline const std::optional<bool> &align_corners() const noexcept

inline std::optional<bool> &align_corners() noexcept

### Fold / Unfold

class Fold : public torch::nn::ModuleHolder<FoldImpl>

A `ModuleHolder` subclass for `FoldImpl`.

See the documentation for `FoldImpl` class to learn what methods it provides, and examples of how to use `Fold` with `torch::nn::FoldOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = FoldImpl

struct FoldOptions

Options for the `Fold` module.

Example:

```
Fold model(FoldOptions({8, 8}, {3, 3}).dilation(2).padding({2,
1}).stride(2));
```

Public Functions

inline FoldOptions(ExpandingArray<2> output_size, ExpandingArray<2> kernel_size)

inline auto output_size(const ExpandingArray<2> &new_output_size) -> decltype(*this)

describes the spatial shape of the large containing tensor of the sliding local blocks.

It is useful to resolve the ambiguity when multiple input shapes map to same number of sliding blocks, e.g., with stride > 0.

inline auto output_size(ExpandingArray<2> &&new_output_size) -> decltype(*this)

inline const ExpandingArray<2> &output_size() const noexcept

inline ExpandingArray<2> &output_size() noexcept

inline auto kernel_size(const ExpandingArray<2> &new_kernel_size) -> decltype(*this)

the size of the sliding blocks

inline auto kernel_size(ExpandingArray<2> &&new_kernel_size) -> decltype(*this)

inline const ExpandingArray<2> &kernel_size() const noexcept

inline ExpandingArray<2> &kernel_size() noexcept

inline auto dilation(const ExpandingArray<2> &new_dilation) -> decltype(*this)

controls the spacing between the kernel points; also known as the à trous algorithm.

inline auto dilation(ExpandingArray<2> &&new_dilation) -> decltype(*this)

inline const ExpandingArray<2> &dilation() const noexcept

inline ExpandingArray<2> &dilation() noexcept

inline auto padding(const ExpandingArray<2> &new_padding) -> decltype(*this)

controls the amount of implicit zero-paddings on both sides for padding number of points for each dimension before reshaping.

inline auto padding(ExpandingArray<2> &&new_padding) -> decltype(*this)

inline const ExpandingArray<2> &padding() const noexcept

inline ExpandingArray<2> &padding() noexcept

inline auto stride(const ExpandingArray<2> &new_stride) -> decltype(*this)

controls the stride for the sliding blocks.

inline auto stride(ExpandingArray<2> &&new_stride) -> decltype(*this)

inline const ExpandingArray<2> &stride() const noexcept

inline ExpandingArray<2> &stride() noexcept

class Unfold : public torch::nn::ModuleHolder<UnfoldImpl>

A `ModuleHolder` subclass for `UnfoldImpl`.

See the documentation for `UnfoldImpl` class to learn what methods it provides, and examples of how to use `Unfold` with `torch::nn::UnfoldOptions`. See the documentation for `ModuleHolder` to learn about PyTorch's module storage semantics.

Public Types

using Impl = UnfoldImpl

struct UnfoldOptions

Options for the `Unfold` module.

Example:

```
Unfold model(UnfoldOptions({2, 4}).dilation(2).padding({2, 1}).stride(2));
```

Public Functions

inline UnfoldOptions(ExpandingArray<2> kernel_size)

inline auto kernel_size(const ExpandingArray<2> &new_kernel_size) -> decltype(*this)

the size of the sliding blocks

inline auto kernel_size(ExpandingArray<2> &&new_kernel_size) -> decltype(*this)

inline const ExpandingArray<2> &kernel_size() const noexcept

inline ExpandingArray<2> &kernel_size() noexcept

inline auto dilation(const ExpandingArray<2> &new_dilation) -> decltype(*this)

controls the spacing between the kernel points; also known as the à trous algorithm.

inline auto dilation(ExpandingArray<2> &&new_dilation) -> decltype(*this)

inline const ExpandingArray<2> &dilation() const noexcept

inline ExpandingArray<2> &dilation() noexcept

inline auto padding(const ExpandingArray<2> &new_padding) -> decltype(*this)

controls the amount of implicit zero-paddings on both sides for padding number of points for each dimension before reshaping.

inline auto padding(ExpandingArray<2> &&new_padding) -> decltype(*this)

inline const ExpandingArray<2> &padding() const noexcept

inline ExpandingArray<2> &padding() noexcept

inline auto stride(const ExpandingArray<2> &new_stride) -> decltype(*this)

controls the stride for the sliding blocks.

inline auto stride(ExpandingArray<2> &&new_stride) -> decltype(*this)

inline const ExpandingArray<2> &stride() const noexcept

inline ExpandingArray<2> &stride() noexcept

---

# Adaptive Learning Rate Optimizers

These optimizers automatically adapt the learning rate for each parameter based
on historical gradient information. They typically require less hyperparameter
tuning and work well across a wide range of problems.

## Adam (Adaptive Moment Estimation)

Adam combines the benefits of RMSprop and momentum, maintaining per-parameter
adaptive learning rates. It's an excellent default choice for most deep learning
tasks, especially when you want fast convergence with minimal tuning.

**When to use:**

- Transformers and attention-based models
- Quick prototyping and experimentation
- When you don't have time for extensive hyperparameter search
- General-purpose deep learning

**Key parameters:**

- `lr`: Learning rate (typical: 1e-3 to 1e-4)
- `betas`: Coefficients for running averages (default: {0.9, 0.999})
- `eps`: Numerical stability term (default: 1e-8)
- `weight_decay`: L2 regularization (note: applied differently than in SGD)

class Adam : public torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE)

Public Functions

inline explicit Adam(const std::vector<[OptimizerParamGroup](index.html#_CPPv4N5torch5optim19OptimizerParamGroupE)> ¶m_groups, AdamOptions defaults = {})

inline explicit Adam(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, AdamOptions defaults = {})

virtual torch::Tensor step(LossClosure closure = nullptr) override

A loss function closure, which is expected to return the loss value.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the optimizer state from the given `archive`.

**Example:**

```
// Standard Adam configuration
auto optimizer = torch::optim::Adam(
 model->parameters(),
 torch::optim::AdamOptions(1e-3) // learning rate
 .betas({0.9, 0.999}) // momentum terms
 .eps(1e-8) // numerical stability
 .weight_decay(0)); // L2 penalty

// For transformers, lower learning rate with warmup
auto optimizer = torch::optim::Adam(
 model->parameters(),
 torch::optim::AdamOptions(1e-4)
 .betas({0.9, 0.98})); // β2=0.98 for transformers
```

## AdamW (Adam with Decoupled Weight Decay)

AdamW fixes a subtle issue with Adam's weight decay implementation. In Adam,
weight decay is coupled with the gradient update, which can lead to suboptimal
regularization. AdamW decouples weight decay, applying it directly to the
weights as in SGD.

**When to use:**

- Always prefer AdamW over Adam when using weight decay
- Training transformers (BERT, GPT, etc.)
- When you want proper L2 regularization behavior

**Key difference from Adam:**

- In Adam: `weight = weight - lr * (grad + weight_decay * weight)`
- In AdamW: `weight = weight - lr * grad - lr * weight_decay * weight`

class AdamW : public torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE)

Public Functions

inline explicit AdamW(const std::vector<[OptimizerParamGroup](index.html#_CPPv4N5torch5optim19OptimizerParamGroupE)> ¶m_groups, AdamWOptions defaults = {})

inline explicit AdamW(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, AdamWOptions defaults = {})

virtual torch::Tensor step(LossClosure closure = nullptr) override

A loss function closure, which is expected to return the loss value.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the optimizer state from the given `archive`.

**Example:**

```
// AdamW with decoupled weight decay - preferred for transformers
auto optimizer = torch::optim::AdamW(
 model->parameters(),
 torch::optim::AdamWOptions(1e-4)
 .betas({0.9, 0.999})
 .weight_decay(0.01)); // Decoupled regularization
```

## RMSprop (Root Mean Square Propagation)

RMSprop adapts the learning rate by dividing by a running average of recent
gradient magnitudes. It's particularly effective for recurrent neural networks
and problems with non-stationary objectives.

**When to use:**

- Training RNNs and LSTMs
- Non-stationary problems where gradient scale varies significantly
- Online learning scenarios

**Key parameters:**

- `lr`: Learning rate (typical: 1e-3 to 1e-2)
- `alpha`: Smoothing constant (default: 0.99)
- `momentum`: Optional momentum term
- `centered`: Use centered RMSprop (normalizes by variance)

class RMSprop : public torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE)

Public Functions

inline explicit RMSprop(const std::vector<[OptimizerParamGroup](index.html#_CPPv4N5torch5optim19OptimizerParamGroupE)> ¶m_groups, RMSpropOptions defaults = {})

inline explicit RMSprop(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, RMSpropOptions defaults = {})

virtual torch::Tensor step(LossClosure closure = nullptr) override

A loss function closure, which is expected to return the loss value.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the optimizer state from the given `archive`.

**Example:**

```
// RMSprop for RNN training
auto optimizer = torch::optim::RMSprop(
 model->parameters(),
 torch::optim::RMSpropOptions(1e-3)
 .alpha(0.99) // smoothing constant
 .momentum(0.9) // optional momentum
 .centered(true)); // normalize by variance
```

## Adagrad (Adaptive Gradient)

Adagrad adapts the learning rate based on the accumulated sum of squared
gradients. Parameters with frequent updates get smaller learning rates, while
parameters with infrequent updates get larger rates. This makes it ideal for
sparse data.

**When to use:**

- NLP tasks with sparse features
- Embedding layers with infrequent updates
- Recommendation systems with sparse user/item features

**Limitation:** Learning rate monotonically decreases, which can cause training
to stop prematurely. For long training runs, consider Adam or RMSprop.

class Adagrad : public torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE)

Public Functions

inline explicit Adagrad(const std::vector<[OptimizerParamGroup](index.html#_CPPv4N5torch5optim19OptimizerParamGroupE)> ¶m_groups, AdagradOptions defaults = {})

inline explicit Adagrad(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, AdagradOptions defaults = {})

virtual torch::Tensor step(LossClosure closure = nullptr) override

A loss function closure, which is expected to return the loss value.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the optimizer state from the given `archive`.

**Example:**

```
// Adagrad for sparse NLP features
auto optimizer = torch::optim::Adagrad(
 model->parameters(),
 torch::optim::AdagradOptions(0.01)
 .lr_decay(0) // learning rate decay
 .weight_decay(0)
 .initial_accumulator_value(0));
```

---

# Gradient Descent Optimizers

These optimizers use gradient descent with optional enhancements like momentum.
They are the foundation of neural network training and work well when you can
afford careful hyperparameter tuning.

## SGD (Stochastic Gradient Descent)

The classic optimization algorithm. SGD with momentum is often the best choice
for convolutional neural networks when properly tuned. While requiring more
careful learning rate selection than adaptive methods, it frequently achieves
the best final accuracy.

**When to use:**

- Training CNNs (ResNet, VGG, etc.) where you want maximum accuracy
- When you have time for hyperparameter tuning
- When combined with learning rate schedules (warmup, cosine annealing)

**Key parameters:**

- `lr`: Learning rate (typical: 0.01-0.1 for CNNs)
- `momentum`: Accelerates convergence (typical: 0.9)
- `weight_decay`: L2 regularization coefficient
- `nesterov`: Use Nesterov momentum (often improves convergence)

class SGD : public torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE)

Public Functions

inline explicit SGD(const std::vector<[OptimizerParamGroup](index.html#_CPPv4N5torch5optim19OptimizerParamGroupE)> ¶m_groups, SGDOptions defaults)

inline explicit SGD(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, SGDOptions defaults)

virtual torch::Tensor step(LossClosure closure = nullptr) override

A loss function closure, which is expected to return the loss value.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the optimizer state from the given `archive`.

**Example:**

```
// Standard SGD with momentum - good for CNNs
auto optimizer = torch::optim::SGD(
 model->parameters(),
 torch::optim::SGDOptions(0.01) // learning rate
 .momentum(0.9) // momentum factor
 .weight_decay(1e-4) // L2 regularization
 .nesterov(true)); // Nesterov momentum
```

---

# Optimizers (torch::optim)

The `torch::optim` namespace provides optimization algorithms for
training neural networks. These optimizers update model parameters based
on computed gradients to minimize the loss function.

**When to use torch::optim:**

- When training neural networks with gradient descent
- When you need different optimization strategies (SGD, Adam, etc.)
- When implementing learning rate schedules

**Basic usage:**

```
#include <torch/torch.h>

// Create model and optimizer
auto model = std::make_shared<Net>();
auto optimizer = torch::optim::Adam(
 model->parameters(),
 torch::optim::AdamOptions(1e-3));

// Training loop
for (auto& batch : *data_loader) {
 optimizer.zero_grad(); // Clear gradients
 auto loss = loss_fn(model->forward(batch.data), batch.target);
 loss.backward(); // Compute gradients
 optimizer.step(); // Update parameters
}
```

## Header Files

- `torch/csrc/api/include/torch/optim.h` - Main optim header
- `torch/csrc/api/include/torch/optim/optimizer.h` - Optimizer base class
- `torch/csrc/api/include/torch/optim/sgd.h` - SGD optimizer
- `torch/csrc/api/include/torch/optim/adam.h` - Adam optimizer

## Optimizer Base Class

All optimizers inherit from the `Optimizer` base class, which provides common
functionality for parameter updates, gradient zeroing, and state management.

class Optimizer

Subclassed by [torch::optim::Adagrad](adaptive.html#PyTorchclasstorch_1_1optim_1_1_adagrad), [torch::optim::Adam](adaptive.html#PyTorchclasstorch_1_1optim_1_1_adam), [torch::optim::AdamW](adaptive.html#PyTorchclasstorch_1_1optim_1_1_adam_w), [torch::optim::LBFGS](second_order.html#PyTorchclasstorch_1_1optim_1_1_l_b_f_g_s), [torch::optim::RMSprop](adaptive.html#PyTorchclasstorch_1_1optim_1_1_r_m_sprop), [torch::optim::SGD](gradient_descent.html#PyTorchclasstorch_1_1optim_1_1_s_g_d)

Public Types

using LossClosure = std::function<[Tensor](../aten/tensor.html#_CPPv46Tensorv)()>

Public Functions

Optimizer(const Optimizer &optimizer) = delete

Optimizer(Optimizer &&optimizer) = default

Optimizer &operator=(const Optimizer &optimizer) = delete

Optimizer &operator=(Optimizer &&optimizer) = default

inline explicit Optimizer(const std::vector<OptimizerParamGroup> ¶m_groups, std::unique_ptr<OptimizerOptions> defaults)

inline explicit Optimizer(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> parameters, std::unique_ptr<OptimizerOptions> defaults)

Constructs the `Optimizer` from a vector of parameters.

void add_param_group(const OptimizerParamGroup ¶m_group)

Adds the given param_group to the optimizer's param_group list.

virtual ~Optimizer() = default

virtual [Tensor](../aten/tensor.html#_CPPv46Tensorv) step(LossClosure closure = nullptr) = 0

A loss function closure, which is expected to return the loss value.

void add_parameters(const std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> ¶meters)

Adds the given vector of parameters to the optimizer's parameter list.

void zero_grad(bool set_to_none = true)

Zeros out the gradients of all parameters.

const std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> ¶meters() const noexcept

Provides a const reference to the parameters in the first param_group this optimizer holds.

std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> ¶meters() noexcept

Provides a reference to the parameters in the first param_group this optimizer holds.

size_t size() const noexcept

Returns the number of parameters referenced by the optimizer.

OptimizerOptions &defaults() noexcept

const OptimizerOptions &defaults() const noexcept

std::vector<OptimizerParamGroup> ¶m_groups() noexcept

Provides a reference to the param_groups this optimizer holds.

const std::vector<OptimizerParamGroup> ¶m_groups() const noexcept

Provides a const reference to the param_groups this optimizer holds.

ska::flat_hash_map<void*, std::unique_ptr<OptimizerParamState>> &state() noexcept

Provides a reference to the state this optimizer holds.

const ska::flat_hash_map<void*, std::unique_ptr<OptimizerParamState>> &state() const noexcept

Provides a const reference to the state this optimizer holds.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive)

Deserializes the optimizer state from the given `archive`.

### OptimizerOptions

class OptimizerOptions

Public Functions

OptimizerOptions() = default

OptimizerOptions(const OptimizerOptions&) = default

OptimizerOptions &operator=(const OptimizerOptions&) = default

OptimizerOptions(OptimizerOptions&&) noexcept = default

OptimizerOptions &operator=(OptimizerOptions&&) noexcept = default

virtual std::unique_ptr<OptimizerOptions> clone() const

virtual void serialize(torch::serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive)

virtual void serialize(torch::serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const

virtual ~OptimizerOptions() = default

virtual double get_lr() const

virtual void set_lr(const double lr)

### OptimizerParamGroup

class OptimizerParamGroup

Stores parameters in the param_group and stores a pointer to the OptimizerOptions.

Public Functions

inline OptimizerParamGroup(const OptimizerParamGroup ¶m_group)

OptimizerParamGroup(OptimizerParamGroup &¶m_group) = default

inline OptimizerParamGroup(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params)

inline OptimizerParamGroup(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, std::unique_ptr<OptimizerOptions> options)

OptimizerParamGroup &operator=(const OptimizerParamGroup ¶m_group) = delete

OptimizerParamGroup &operator=(OptimizerParamGroup &¶m_group) noexcept = default

~OptimizerParamGroup() = default

bool has_options() const

OptimizerOptions &options()

const OptimizerOptions &options() const

void set_options(std::unique_ptr<OptimizerOptions> options)

std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> ¶ms()

const std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> ¶ms() const

### OptimizerParamState

class OptimizerParamState

Public Functions

OptimizerParamState() = default

OptimizerParamState(const OptimizerParamState&) = default

OptimizerParamState &operator=(const OptimizerParamState&) = default

OptimizerParamState(OptimizerParamState&&) noexcept = default

OptimizerParamState &operator=(OptimizerParamState&&) noexcept = default

virtual std::unique_ptr<OptimizerParamState> clone() const

virtual void serialize(torch::serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive)

virtual void serialize(torch::serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const

virtual ~OptimizerParamState() = default

## Choosing an Optimizer

Selecting the right optimizer depends on your model architecture, dataset, and
training requirements:

| Optimizer | Best For | Trade-offs |
| --- | --- | --- |
| **SGD + Momentum** | CNNs, well-understood problems, when you can tune hyperparameters | Requires careful learning rate tuning; often achieves best final accuracy |
| **Adam/AdamW** | General-purpose, transformers, quick prototyping | Works well out-of-the-box; AdamW preferred with weight decay |
| **RMSprop** | RNNs, non-stationary objectives | Good for recurrent architectures; handles varying gradient scales |
| **Adagrad** | Sparse data (NLP, embeddings) | Learning rate decreases over time; good for infrequent features |
| **LBFGS** | Small models, fine-tuning, convex problems | Memory-intensive; requires closure function |

## Optimizer Categories

- [Gradient Descent Optimizers](gradient_descent.html)
- [Adaptive Learning Rate Optimizers](adaptive.html)
- [Second-Order Optimizers](second_order.html)
- [Learning Rate Schedulers](schedulers.html)

---

# Learning Rate Schedulers

Learning rate schedulers adjust the learning rate during training, which often
improves convergence and final accuracy. Common strategies include:

- **Step decay**: Reduce LR by a factor every N epochs
- **Exponential decay**: Multiply LR by gamma each epoch
- **Cosine annealing**: Smoothly decrease LR following a cosine curve
- **Warmup**: Gradually increase LR at the start of training

## LRScheduler Base Class

class LRScheduler

Subclassed by torch::optim::StepLR

Public Functions

LRScheduler(torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE) &optimizer)

virtual ~LRScheduler() = default

void step()

## StepLR

Decays the learning rate by `gamma` every `step_size` epochs. This is the
simplest and most commonly used scheduler.

class StepLR : public torch::optim::LRScheduler

Public Functions

StepLR(torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE) &optimizer, const unsigned step_size, const double gamma = 0.1)

**Example:**

```
auto optimizer = torch::optim::SGD(
 model->parameters(),
 torch::optim::SGDOptions(0.1));

// Reduce LR by 10x every 30 epochs
auto scheduler = torch::optim::StepLR(
 optimizer,
 /*step_size=*/30,
 /*gamma=*/0.1);

for (int epoch = 0; epoch < 90; ++epoch) {
 train_one_epoch(model, optimizer, data_loader);
 scheduler.step();
 // LR: 0.1 (epochs 0-29), 0.01 (30-59), 0.001 (60-89)
}
```

## ReduceLROnPlateau

Reduces the learning rate when a metric has stopped improving. Useful when
you want the scheduler to respond to validation loss rather than follow a
fixed schedule.

class ReduceLROnPlateauScheduler

Public Types

enum SchedulerMode

*Values:*

enumerator min

enumerator max

enum ThresholdMode

*Values:*

enumerator rel

enumerator abs

Public Functions

ReduceLROnPlateauScheduler([Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE) &optimizer, SchedulerMode mode = min, float factor = 0.1, int patience = 10, double threshold = 1e-4, ThresholdMode threshold_mode = rel, int cooldown = 0, const std::vector<float> &min_lr = std::vector<float>(), double eps = 1e-8, bool verbose = false)

virtual ~ReduceLROnPlateauScheduler() = default

void step(float metric)

## ExponentialLR

Decays the learning rate by `gamma` every epoch. Provides smoother decay than
StepLR but may be slower to reduce the learning rate.

**Example:**

```
auto optimizer = torch::optim::Adam(
 model->parameters(),
 torch::optim::AdamOptions(1e-3));

// Reduce LR by 5% each epoch
auto scheduler = torch::optim::ExponentialLR(
 optimizer,
 /*gamma=*/0.95);

for (int epoch = 0; epoch < num_epochs; ++epoch) {
 train_one_epoch(model, optimizer, data_loader);
 scheduler.step();
}
```

## Complete Training Example

Here's a complete example showing optimizer usage with learning rate scheduling:

```
#include <torch/torch.h>

struct Net : torch::nn::Module {
 Net() {
 fc1 = register_module("fc1", torch::nn::Linear(784, 256));
 fc2 = register_module("fc2", torch::nn::Linear(256, 10));
 }

 torch::Tensor forward(torch::Tensor x) {
 x = torch::relu(fc1->forward(x.view({-1, 784})));
 return fc2->forward(x);
 }

 torch::nn::Linear fc1{nullptr}, fc2{nullptr};
};

int main() {
 // Create model
 auto model = std::make_shared<Net>();

 // Create optimizer with weight decay
 auto optimizer = torch::optim::AdamW(
 model->parameters(),
 torch::optim::AdamWOptions(1e-3)
 .weight_decay(0.01));

 // Learning rate scheduler
 auto scheduler = torch::optim::StepLR(optimizer, 10, 0.5);

 // Loss function
 auto loss_fn = torch::nn::CrossEntropyLoss();

 // Training loop
 for (int epoch = 0; epoch < 30; ++epoch) {
 model->train();
 double epoch_loss = 0.0;

 for (auto& batch : *train_loader) {
 optimizer.zero_grad();

 auto output = model->forward(batch.data);
 auto loss = loss_fn(output, batch.target);

 loss.backward();
 optimizer.step();

 epoch_loss += loss.item<double>();
 }

 scheduler.step();
 std::cout << "Epoch " << epoch
 << " Loss: " << epoch_loss
 << " LR: " << scheduler.get_last_lr()[0]
 << std::endl;
 }

 return 0;
}
```

---

# Second-Order Optimizers

Second-order methods use curvature information (Hessian or its approximations)
to make better optimization steps. They can converge faster but are more
computationally expensive and memory-intensive.

## LBFGS (Limited-memory Broyden-Fletcher-Goldfarb-Shanno)

LBFGS is a quasi-Newton method that approximates the inverse Hessian using
gradient history. It can converge much faster than first-order methods for
smooth, convex-like loss surfaces.

**When to use:**

- Small models where memory isn't a concern
- Fine-tuning pre-trained models
- Convex or near-convex optimization problems
- Full-batch training (not mini-batch)

**Key parameters:**

- `lr`: Learning rate (often 1.0 for LBFGS)
- `max_iter`: Maximum iterations per step
- `history_size`: Number of past gradients to store

**Important:** LBFGS requires a closure function that recomputes the loss.

class LBFGS : public torch::optim::[Optimizer](index.html#_CPPv4N5torch5optim9OptimizerE)

Public Functions

inline explicit LBFGS(const std::vector<[OptimizerParamGroup](index.html#_CPPv4N5torch5optim19OptimizerParamGroupE)> ¶m_groups, LBFGSOptions defaults = {})

inline explicit LBFGS(std::vector<[Tensor](../aten/tensor.html#_CPPv46Tensorv)> params, LBFGSOptions defaults = {})

virtual [Tensor](../aten/tensor.html#_CPPv46Tensorv) step(LossClosure closure) override

A loss function closure, which is expected to return the loss value.

virtual void save(serialize::[OutputArchive](../serialize/archives.html#_CPPv4N5torch9serialize13OutputArchiveE) &archive) const override

Serializes the optimizer state into the given `archive`.

virtual void load(serialize::[InputArchive](../serialize/archives.html#_CPPv4N5torch9serialize12InputArchiveE) &archive) override

Deserializes the optimizer state from the given `archive`.

**Example:**

```
auto optimizer = torch::optim::LBFGS(
 model->parameters(),
 torch::optim::LBFGSOptions(1.0)
 .max_iter(20)
 .history_size(10));

// LBFGS requires a closure that recomputes the model
for (int epoch = 0; epoch < num_epochs; ++epoch) {
 auto closure = [&]() {
 optimizer.zero_grad();
 auto output = model->forward(data);
 auto loss = loss_fn(output, target);
 loss.backward();
 return loss;
 };
 optimizer.step(closure);
}
```

---

# Archives

Archives provide a lower-level interface for serialization, allowing you to
save multiple values to a single file with named keys.

## OutputArchive

class OutputArchive

Public Functions

explicit OutputArchive(std::shared_ptr<jit::CompilationUnit> cu)

inline explicit OutputArchive()

OutputArchive(OutputArchive&&) = default

OutputArchive &operator=(OutputArchive&&) = default

OutputArchive(OutputArchive&) = delete

OutputArchive &operator=(OutputArchive&) = delete

inline std::shared_ptr<jit::CompilationUnit> compilation_unit() const

void write(const std::string &key, const c10::IValue &ivalue)

Writes an `IValue` to the `OutputArchive`.

void write(const std::string &key, const [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tensor, bool is_buffer = false)

Writes a `(key, tensor)` pair to the `OutputArchive`, and marks it as being or not being a buffer (non-differentiable tensor).

void write(const std::string &key, OutputArchive &nested_archive)

Writes a nested `OutputArchive` under the given `key` to this `OutputArchive`.

void save_to(const std::string &filename)

Saves the `OutputArchive` into a serialized representation in a file at `filename`.

void save_to(std::ostream &stream)

Saves the `OutputArchive` into a serialized representation into the given `stream`.

void save_to(const std::function<size_t(const void*, size_t)> &func)

Saves the `OutputArchive` into a serialized representation using the given writer function.

template<typename ...Ts>
inline void operator()(Ts&&... ts)

Forwards all arguments to `write()`.

Useful for generic code that can be reused for both `OutputArchive` and `InputArchive` (where `operator()` forwards to `read()`).

**Example:**

```
torch::serialize::OutputArchive archive;
archive.write("tensor1", tensor1);
archive.write("tensor2", tensor2);
archive.save_to("multi_tensor.pt");
```

## InputArchive

class InputArchive

A recursive representation of tensors that can be deserialized from a file or stream.

In most cases, users should not have to interact with this class, and should instead use `[torch::load](save_load.html#PyTorchnamespacetorch_1ad98de93d4a74dd9a91161f64758f1a76)`.

Public Functions

InputArchive()

Default-constructs the `InputArchive`.

InputArchive(InputArchive&&) = default

InputArchive &operator=(InputArchive&&) = default

InputArchive(InputArchive&) = delete

InputArchive &operator=(InputArchive&) = delete

~InputArchive() = default

void read(const std::string &key, c10::IValue &ivalue)

Reads an `IValue` associated with a given `key`.

bool try_read(const std::string &key, c10::IValue &ivalue)

Reads an `IValue` associated with a given `key`.

If there is no `IValue` associated with the `key`, this returns false, otherwise it returns true.

bool try_read(const std::string &key, [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tensor, bool is_buffer = false)

Reads a `tensor` associated with a given `key`.

If there is no `tensor` associated with the `key`, this returns false, otherwise it returns true. If the tensor is expected to be a buffer (not differentiable), `is_buffer` must be `true`.

void read(const std::string &key, [Tensor](../aten/tensor.html#_CPPv46Tensorv) &tensor, bool is_buffer = false)

Reads a `tensor` associated with a given `key`.

If the tensor is expected to be a buffer (not differentiable), `is_buffer` must be `true`.

bool try_read(const std::string &key, InputArchive &archive)

Reads a `InputArchive` associated with a given `key`.

If there is no `InputArchive` associated with the `key`, this returns false, otherwise it returns true.

void read(const std::string &key, InputArchive &archive)

Reads an `InputArchive` associated with a given `key`.

The archive can thereafter be used for further deserialization of the nested data.

void load_from(const std::string &filename, std::optional<torch::Device> device = std::nullopt)

Loads the `InputArchive` from a serialized representation stored in the file at `filename`.

Storage are remapped using device option. If device is not specified, the module is loaded to the original device.

void load_from(std::istream &stream, std::optional<torch::Device> device = std::nullopt)

Loads the `InputArchive` from a serialized representation stored in the given `stream`.

Storage are remapped using device option. If device is not specified, the module is loaded to the original device.

void load_from(const char *data, size_t size, std::optional<torch::Device> device = std::nullopt)

void load_from(const std::function<size_t(uint64_t pos, void *buf, size_t nbytes)> &read_func, const std::function<size_t(void)> &size_func, std::optional<torch::Device> device = std::nullopt)

std::vector<std::string> keys()

template<typename ...Ts>
inline void operator()(Ts&&... ts)

Forwards all arguments to `read()`.

Useful for generic code that can be reused for both `InputArchive` and `OutputArchive` (where `operator()` forwards to `write()`).

**Example:**

```
torch::serialize::InputArchive archive;
archive.load_from("multi_tensor.pt");

torch::Tensor tensor1, tensor2;
archive.read("tensor1", tensor1);
archive.read("tensor2", tensor2);
```

## Saving Multiple Values

Archives are useful when you need to save multiple related values together:

```
// Save multiple tensors and metadata
torch::serialize::OutputArchive out_archive;
out_archive.write("weights", model_weights);
out_archive.write("biases", model_biases);
out_archive.write("epoch", torch::tensor(current_epoch));
out_archive.write("loss", torch::tensor(best_loss));
out_archive.save_to("training_state.pt");

// Load them back
torch::serialize::InputArchive in_archive;
in_archive.load_from("training_state.pt");

torch::Tensor weights, biases, epoch_tensor, loss_tensor;
in_archive.read("weights", weights);
in_archive.read("biases", biases);
in_archive.read("epoch", epoch_tensor);
in_archive.read("loss", loss_tensor);

int epoch = epoch_tensor.item<int>();
float loss = loss_tensor.item<float>();
```

---

# Checkpoints

Checkpoints save the complete training state so you can resume training
after interruption. A checkpoint typically includes:

- Model parameters
- Optimizer state (momentum buffers, learning rates)
- Current epoch number
- Best validation loss/accuracy

## Creating Checkpoints

```
void save_checkpoint(
 std::shared_ptr<Net> model,
 torch::optim::Adam& optimizer,
 int epoch,
 const std::string& path) {
 torch::serialize::OutputArchive archive;
 model->save(archive);
 archive.write("epoch", torch::tensor(epoch));
 optimizer.save(archive);
 archive.save_to(path);
}
```

## Loading Checkpoints

```
int load_checkpoint(
 std::shared_ptr<Net> model,
 torch::optim::Adam& optimizer,
 const std::string& path) {
 torch::serialize::InputArchive archive;
 archive.load_from(path);
 model->load(archive);
 torch::Tensor epoch_tensor;
 archive.read("epoch", epoch_tensor);
 optimizer.load(archive);
 return epoch_tensor.item<int>();
}
```

## Complete Checkpoint Example

```
#include <torch/torch.h>
#include <iostream>
#include <filesystem>

struct Net : torch::nn::Module {
 Net() {
 fc1 = register_module("fc1", torch::nn::Linear(784, 256));
 fc2 = register_module("fc2", torch::nn::Linear(256, 10));
 }

 torch::Tensor forward(torch::Tensor x) {
 x = torch::relu(fc1->forward(x.view({-1, 784})));
 return fc2->forward(x);
 }

 torch::nn::Linear fc1{nullptr}, fc2{nullptr};
};

int main() {
 auto model = std::make_shared<Net>();
 auto optimizer = torch::optim::Adam(model->parameters(), 1e-3);

 int start_epoch = 0;
 const std::string checkpoint_path = "checkpoint.pt";

 // Resume from checkpoint if it exists
 if (std::filesystem::exists(checkpoint_path)) {
 std::cout << "Loading checkpoint..." << std::endl;
 start_epoch = load_checkpoint(model, optimizer, checkpoint_path);
 std::cout << "Resuming from epoch " << start_epoch << std::endl;
 }

 // Training loop
 for (int epoch = start_epoch; epoch < 100; ++epoch) {
 // ... training code ...

 // Save checkpoint every 10 epochs
 if ((epoch + 1) % 10 == 0) {
 save_checkpoint(model, optimizer, epoch + 1, checkpoint_path);
 std::cout << "Saved checkpoint at epoch " << epoch + 1 << std::endl;
 }
 }

 return 0;
}
```

## Best Practices

1. **Save periodically**: Save checkpoints at regular intervals (e.g., every epoch
or every N batches) to minimize lost work.
2. **Keep multiple checkpoints**: Maintain the last few checkpoints in case the
most recent one is corrupted or represents a poor model state.
3. **Include all state**: Save everything needed to resume training, including
learning rate scheduler state if using one.
4. **Verify checkpoints**: Occasionally verify that checkpoints can be loaded
correctly.

---

# Serialization (torch::serialize)

The `torch::serialize` namespace provides utilities for saving and loading
model weights, tensors, and optimizer state. This enables checkpointing during
training and deployment of trained models.

**When to use torch::serialize:**

- When saving trained models to disk
- When implementing training checkpoints
- When loading pre-trained weights
- When transferring models between C++ and Python

**Basic usage:**

```
#include <torch/torch.h>

// Save a model
auto model = std::make_shared<Net>();
// ... train the model ...
torch::save(model, "model.pt");

// Load a model
auto loaded_model = std::make_shared<Net>();
torch::load(loaded_model, "model.pt");

// Save and load tensors
torch::Tensor tensor = torch::randn({2, 3});
torch::save(tensor, "tensor.pt");

torch::Tensor loaded_tensor;
torch::load(loaded_tensor, "tensor.pt");
```

## Header Files

- `torch/csrc/api/include/torch/serialize.h` - Main serialization header
- `torch/csrc/api/include/torch/serialize/archive.h` - Archive classes
- `torch/csrc/api/include/torch/serialize/input-archive.h` - Input archive
- `torch/csrc/api/include/torch/serialize/output-archive.h` - Output archive

## Serialization Categories

- [Saving and Loading](save_load.html)
- [Archives](archives.html)
- [Checkpoints](checkpoints.html)

---

# Saving and Loading

The primary interface for serialization uses the `torch::save` and
`torch::load` functions, which can save and load tensors, modules,
and optimizers.

## Save Functions

template<typename Value, typename ...SaveToArgs>
void torch::save(const Value &value, SaveToArgs&&... args)

Serializes the given `value`.

There must be an overload of `operator<<` between `[serialize::OutputArchive](archives.html#PyTorchclasstorch_1_1serialize_1_1_output_archive)` and `Value` for this method to be well-formed. Currently, such an overload is provided for (subclasses of):

- `[torch::nn::Module](../nn/index.html#PyTorchclasstorch_1_1nn_1_1_module)`,
- `[torch::optim::Optimizer](../optim/index.html#PyTorchclasstorch_1_1optim_1_1_optimizer)`
- `torch::Tensor`

To perform the serialization, a `[serialize::OutputArchive](archives.html#PyTorchclasstorch_1_1serialize_1_1_output_archive)` is constructed, and all arguments after the `value` are forwarded to its `save_to` method. For example, you can pass a filename, or an `ostream`.

- .. code-block:: cpp
- 
- torch::nn::Linear model(3, 4);
- torch::save(model, "model.pt");
- 
- torch::optim::SGD sgd(model->parameters(), 0.9); // 0.9 is learning rate
- std::ostringstream stream;
- // Note that the same stream cannot be used in multiple torch::save(...)
- // invocations, otherwise the header will be corrupted.
- torch::save(sgd, stream);
- 
- auto tensor = torch::ones({3, 4});
- torch::save(tensor, "my_tensor.pt");
- 

template<typename ...SaveToArgs>
void torch::save(const std::vector<torch::Tensor> &tensor_vec, SaveToArgs&&... args)

Serializes the given `tensor_vec` of type `std::vector<torch::Tensor>`.

To perform the serialization, a `[serialize::OutputArchive](archives.html#PyTorchclasstorch_1_1serialize_1_1_output_archive)` is constructed, and all arguments after the `tensor_vec` are forwarded to its `save_to` method. For example, you can pass a filename, or an `ostream`.

- .. code-block:: cpp
- 
- std::vector[torch::Tensor](torch::Tensor) tensor_vec = { torch::randn({1, 2}),
- torch::randn({3, 4}) }; torch::save(tensor_vec, "my_tensor_vec.pt");
- 
- std::vector[torch::Tensor](torch::Tensor) tensor_vec = { torch::randn({5, 6}),
- torch::randn({7, 8}) }; std::ostringstream stream;
- // Note that the same stream cannot be used in multiple torch::save(...)
- // invocations, otherwise the header will be corrupted.
- torch::save(tensor_vec, stream);
- 

## Load Functions

template<typename Value, typename ...LoadFromArgs>
void torch::load(Value &value, LoadFromArgs&&... args)

Deserializes the given `value`.

There must be an overload of `operator>>` between `[serialize::InputArchive](archives.html#PyTorchclasstorch_1_1serialize_1_1_input_archive)` and `Value` for this method to be well-formed. Currently, such an overload is provided for (subclasses of):

- `[torch::nn::Module](../nn/index.html#PyTorchclasstorch_1_1nn_1_1_module)`,
- `[torch::optim::Optimizer](../optim/index.html#PyTorchclasstorch_1_1optim_1_1_optimizer)`
- `torch::Tensor`

To perform the serialization, a `[serialize::InputArchive](archives.html#PyTorchclasstorch_1_1serialize_1_1_input_archive)` is constructed, and all arguments after the `value` are forwarded to its `load_from` method. For example, you can pass a filename, or an `istream`.

- .. code-block:: cpp
- 
- torch::nn::Linear model(3, 4);
- torch::load(model, "model.pt");
- 
- torch::optim::SGD sgd(model->parameters(), 0.9); // 0.9 is learning rate
- std::istringstream stream("...");
- torch::load(sgd, stream);
- 
- auto tensor = torch::ones({3, 4});
- torch::load(tensor, "my_tensor.pt");
- 

template<typename ...LoadFromArgs>
void torch::load(std::vector<torch::Tensor> &tensor_vec, LoadFromArgs&&... args)

Deserializes the given `tensor_vec` of type `std::vector<torch::Tensor>`.

To perform the serialization, a `[serialize::InputArchive](archives.html#PyTorchclasstorch_1_1serialize_1_1_input_archive)` is constructed, and all arguments after the `value` are forwarded to its `load_from` method. For example, you can pass a filename, or an `istream`.

- .. code-block:: cpp
- 
- std::vector[torch::Tensor](torch::Tensor) tensor_vec;
- torch::load(tensor_vec, "my_tensor_vec.pt");
- 
- std::vector[torch::Tensor](torch::Tensor) tensor_vec;
- std::istringstream stream("...");
- torch::load(tensor_vec, stream);
- 

## Saving and Loading Tensors

```
// Save a tensor
torch::Tensor tensor = torch::randn({2, 3});
torch::save(tensor, "tensor.pt");

// Load a tensor
torch::Tensor loaded;
torch::load(loaded, "tensor.pt");
```

## Saving and Loading Modules

```
// Define a model
struct Net : torch::nn::Module {
 Net() {
 fc1 = register_module("fc1", torch::nn::Linear(784, 64));
 fc2 = register_module("fc2", torch::nn::Linear(64, 10));
 }

 torch::Tensor forward(torch::Tensor x) {
 x = torch::relu(fc1->forward(x));
 return fc2->forward(x);
 }

 torch::nn::Linear fc1{nullptr}, fc2{nullptr};
};

// Save model
auto model = std::make_shared<Net>();
torch::save(model, "model.pt");

// Load model
auto loaded_model = std::make_shared<Net>();
torch::load(loaded_model, "model.pt");
```

## Saving Optimizer State

```
auto model = std::make_shared<Net>();
auto optimizer = torch::optim::Adam(model->parameters(), 0.001);

// Train...

// Save both model and optimizer
torch::save(model, "model.pt");
torch::save(optimizer, "optimizer.pt");

// Load both
torch::load(model, "model.pt");
torch::load(optimizer, "optimizer.pt");
```

---

# Torch Stable API

The PyTorch Stable C++ API provides a binary-compatible interface for calling
tensor operations and utilities that is guaranteed to remain stable across
PyTorch versions. This enables ahead-of-time compiled extensions that don't
need recompilation when PyTorch is updated.

**When to use the Stable API:**

- When building extensions that must work across multiple PyTorch versions
- When distributing pre-compiled binaries
- When binary compatibility is more important than access to the latest features
- When writing custom operators for production deployment

**Basic usage:**

```
#include <torch/csrc/stable/library.h>
#include <torch/csrc/stable/ops.h>

// Create a tensor using stable API
auto tensor = torch::stable::empty(
 {3, 4},
 torch::headeronly::ScalarType::Float,
 torch::headeronly::Layout::Strided,
 torch::stable::Device(torch::headeronly::DeviceType::CPU),
 false,
 torch::headeronly::MemoryFormat::Contiguous);

// Register operators with stable ABI
STABLE_TORCH_LIBRARY(myops, m) {
 m.def("my_op(Tensor input) -> Tensor");
}

STABLE_TORCH_LIBRARY_IMPL(myops, CPU, m) {
 m.impl("my_op", TORCH_BOX(&my_cpu_kernel));
}
```

For more information on the stable ABI, see the
[Stable ABI notes](https://docs.pytorch.org/docs/stable/notes/libtorch_stable_abi.html).

## Header Files

- `torch/csrc/stable/library.h` - Stable library registration
- `torch/csrc/stable/ops.h` - Stable operator definitions
- `torch/csrc/stable/tensor.h` - Stable tensor structures
- `torch/csrc/stable/device.h` - Stable device structures
- `torch/csrc/stable/accelerator.h` - Accelerator support
- `torch/csrc/stable/macros.h` - Stable API macros

## Stable API Categories

- [Library Registration Macros](registration.html)
- [Stable Operators](operators.html)
- [Utilities](utilities.html)

## See Also

- [Torch Library API](../library/index.html) - For standard (non-stable) operator registration
- [Stable ABI documentation](https://pytorch.org/docs/stable/cpp_extension.html)

---

# Stable Operators

The stable API provides tensor operations that maintain binary compatibility
across PyTorch versions.

## Tensor Class

class Tensor

An ABI stable wrapper around PyTorch tensors.

This class is modeled after TensorBase, as custom op kernels primarily need to interact with Tensor metadata (sizes, strides, device, dtype). Other tensor operations (like `empty_like`) exist as standalone functions outside of this struct.

Minimum compatible version: PyTorch 2.9.

Public Functions

inline Tensor()

Constructs a Tensor with an uninitialized AtenTensorHandle.

Creates a new stable::Tensor by allocating an uninitialized tensor handle. The ownership of the handle is managed internally via shared_ptr.

Minimum compatible version: PyTorch 2.9.

inline explicit Tensor(AtenTensorHandle ath)

Constructs a Tensor from an existing AtenTensorHandle.

Steals ownership of the provided AtenTensorHandle.

Minimum compatible version: PyTorch 2.9.

Parameters:

**ath** - The AtenTensorHandle to wrap. Ownership is transferred to this Tensor.

inline AtenTensorHandle get() const

Returns a borrowed reference to the underlying AtenTensorHandle.

Minimum compatible version: PyTorch 2.9.

Returns:

The underlying AtenTensorHandle.

inline void *data_ptr() const

Returns a pointer to the tensor's data.

Minimum compatible version: PyTorch 2.9.

Returns:

A void pointer to the tensor's data storage.

inline void *mutable_data_ptr() const

Returns a mutable pointer to the tensor's data.

Minimum compatible version: PyTorch 2.10.

Returns:

A mutable void pointer to the tensor's data storage.

inline const void *const_data_ptr() const

Returns a const pointer to the tensor's data.

Minimum compatible version: PyTorch 2.10.

Returns:

A const void pointer to the tensor's data storage.

template<typename T>
T *mutable_data_ptr() const

Returns a typed mutable pointer to the tensor's data.

Minimum compatible version: PyTorch 2.10.

Template Parameters:

**T** - The type to cast the data pointer to.

Returns:

A mutable pointer to the tensor's data cast to type T*.

template<typename T, std::enable_if_t<!std::is_const_v<T>, int> = 0>
const T *const_data_ptr() const

Returns a typed const pointer to the tensor's data.

Minimum compatible version: PyTorch 2.10.

Template Parameters:

**T** - The type to cast the data pointer to. Must not be const-qualified.

Returns:

A const pointer to the tensor's data cast to type const T*.

inline const Tensor &set_requires_grad(bool requires_grad) const

Sets whether this tensor requires gradient computation.

Minimum compatible version: PyTorch 2.10.

Parameters:

**requires_grad** - If true, gradients will be computed for this tensor during backpropagation.

Returns:

A reference to this Tensor.

inline int64_t dim() const

Returns the number of dimensions of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The number of dimensions (rank) of the tensor.

inline int64_t numel() const

Returns the total number of elements in the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The total number of elements across all dimensions.

inline IntHeaderOnlyArrayRef sizes() const

Returns the sizes (shape) of the tensor.

Returns a borrowed reference of the dimension sizes of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

An IntHeaderOnlyArrayRef containing the size of each dimension.

inline IntHeaderOnlyArrayRef strides() const

Returns the strides of the tensor.

Returns a borrowed reference of the strides of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

An IntHeaderOnlyArrayRef containing the stride of each dimension.

inline bool is_contiguous() const

Checks if the tensor is contiguous in memory.

Minimum compatible version: PyTorch 2.9.

Note

This is a subset of the original TensorBase API. It takes no arguments whereas the original API takes a memory format argument. Here, we assume the default contiguous memory format.

Returns:

true if the tensor is contiguous, false otherwise.

inline int64_t stride(int64_t dim) const

Returns the stride of a specific dimension.

Minimum compatible version: PyTorch 2.9.

Parameters:

**dim** - The dimension index to query.

Returns:

The stride of the specified dimension.

inline DeviceIndex get_device_index() const

Returns the device index of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The device index as DeviceIndex (int32_t).

inline bool is_cuda() const

Checks if the tensor is on a CUDA device.

Minimum compatible version: PyTorch 2.9.

Returns:

true if the tensor is on a CUDA device, false otherwise.

inline bool is_cpu() const

Checks if the tensor is on the CPU.

Minimum compatible version: PyTorch 2.9.

Returns:

true if the tensor is on the CPU, false otherwise.

inline int64_t size(int64_t dim) const

Returns the size of a specific dimension.

Minimum compatible version: PyTorch 2.9.

Parameters:

**dim** - The dimension index to query.

Returns:

The size of the specified dimension.

inline bool defined() const

Checks if the tensor is defined (not null).

Minimum compatible version: PyTorch 2.9.

Returns:

true if the tensor is defined, false otherwise.

inline bool has_storage() const

Checks whether the tensor has an associated storage.

Returns false for undefined tensors and for tensors that do not own a storage (e.g. sparse tensors).

Minimum compatible version: PyTorch 2.14.

Returns:

true if the tensor has a storage, false otherwise.

inline int64_t storage_offset() const

Returns the storage offset of the tensor.

The storage offset is the number of elements from the beginning of the underlying storage to the first element of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The storage offset in number of elements.

inline size_t element_size() const

Returns the size in bytes of each element in the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The element size in bytes.

ScalarType scalar_type() const

Returns the scalar type (dtype) of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The ScalarType of the tensor.

Device device() const

Returns the device of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The Device on which the tensor resides.

Layout layout() const

Returns the layout of the tensor.

Minimum compatible version: PyTorch 2.9.

Returns:

The Layout of the tensor (e.g., Strided, Sparse).

**Example:**

```
torch::stable::Tensor tensor = torch::stable::empty({3, 4}, ...);
float* data = tensor.data_ptr<float>();
auto shape = tensor.sizes();
```

## Device Class

class Device

A stable version of [c10::Device](../c10/device.html#PyTorchstructc10_1_1_device).

Minimum compatible version: PyTorch 2.9.

Public Functions

inline Device(DeviceType type, DeviceIndex index = -1)

Constructs a Device from a DeviceType and optional device index.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **type** - The type of device (e.g., DeviceType::CPU, DeviceType::CUDA).
- **index** - The device index. Default is -1 (current device).

Device(const std::string &device_string)

Constructs a stable::Device from a string description.

The string must follow the schema: (cpu|cuda|...)[:<device-index>]

Minimum compatible version: PyTorch 2.10.

Parameters:

**device_string** - A string describing the device (e.g., "cuda:0", "cpu").

inline bool operator==(const Device &other) const noexcept

Checks if two devices are equal.

Minimum compatible version: PyTorch 2.9.

Parameters:

**other** - The device to compare with.

Returns:

true if both type and index match, false otherwise.

inline bool operator!=(const Device &other) const noexcept

Checks if two devices are not equal.

Minimum compatible version: PyTorch 2.9.

Parameters:

**other** - The device to compare with.

Returns:

true if type or index differ, false otherwise.

inline void set_index(DeviceIndex index)

Sets the device index.

Minimum compatible version: PyTorch 2.9.

Parameters:

**index** - The new device index.

inline DeviceType type() const noexcept

Returns the device type.

Minimum compatible version: PyTorch 2.9.

Returns:

The DeviceType of this device.

inline DeviceIndex index() const noexcept

Returns the device index.

Minimum compatible version: PyTorch 2.9.

Returns:

The device index, or -1 if no specific index is set.

inline bool has_index() const noexcept

Checks if this device has a specific index.

Minimum compatible version: PyTorch 2.9.

Returns:

true if index is not -1, false otherwise.

inline bool is_cuda() const noexcept

Checks if this is a CUDA device.

Minimum compatible version: PyTorch 2.9.

Returns:

true if the device type is CUDA, false otherwise.

inline bool is_cpu() const noexcept

Checks if this is a CPU device.

Minimum compatible version: PyTorch 2.9.

Returns:

true if the device type is CPU, false otherwise.

**Example:**

```
torch::stable::Device cpu_device(torch::headeronly::DeviceType::CPU);
torch::stable::Device cuda_device(torch::headeronly::DeviceType::CUDA, 0);
```

## Tensor Creation

inline torch::stable::Tensor torch::stable::empty(torch::headeronly::IntHeaderOnlyArrayRef size, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt, std::optional<torch::headeronly::Layout> layout = std::nullopt, std::optional<torch::stable::Device> device = std::nullopt, std::optional<bool> pin_memory = std::nullopt, std::optional<torch::headeronly::MemoryFormat> memory_format = std::nullopt)

Stable version of the empty.memory_format op.

Creates a new uninitialized tensor with the specified size and options. This function supports full tensor creation options including device, dtype, layout, and memory format.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **size** - The desired size of the output tensor.
- **dtype** - Optional scalar type for the tensor elements.
- **layout** - Optional memory layout (e.g., strided, sparse).
- **device** - Optional device to place the tensor on.
- **pin_memory** - Optional flag to use pinned memory (for CUDA tensors).
- **memory_format** - Optional memory format for the tensor.

Returns:

A new uninitialized tensor with the specified properties.

inline torch::stable::Tensor torch::stable::empty_like(const torch::stable::Tensor &self)

Stable version of the empty_like op.

Creates a new uninitialized tensor with the same size, dtype, layout, and device as the input tensor. This version does not support kwargs (device, dtype, layout, memory_format) - kwargs support may be added in the future.

Minimum compatible version: PyTorch 2.9.

Parameters:

**self** - The input tensor whose properties will be used for the new tensor.

Returns:

A new uninitialized tensor with the same properties as self.

inline torch::stable::Tensor torch::stable::new_empty(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef size, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt, std::optional<torch::headeronly::Layout> layout = std::nullopt, std::optional<torch::stable::Device> device = std::nullopt, std::optional<bool> pin_memory = std::nullopt)

Stable version of the new_empty op (2.10 version with full kwargs).

Creates a new uninitialized tensor with the specified size and options. This version supports all tensor creation kwargs. For versions < 2.10, a simpler overload that only takes dtype is available.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor whose properties may be inherited if kwargs are not provided.
- **size** - The desired size of the output tensor.
- **dtype** - Optional scalar type for the tensor elements.
- **layout** - Optional memory layout (e.g., strided, sparse).
- **device** - Optional device to place the tensor on.
- **pin_memory** - Optional flag to use pinned memory (for CUDA tensors).

Returns:

A new uninitialized tensor with the specified properties.

inline torch::stable::Tensor torch::stable::new_zeros(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef size, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt, std::optional<torch::headeronly::Layout> layout = std::nullopt, std::optional<torch::stable::Device> device = std::nullopt, std::optional<bool> pin_memory = std::nullopt)

Stable version of the new_zeros op (2.10 version with full kwargs).

Creates a new zero-filled tensor with the specified size and options. This version supports all tensor creation kwargs. For versions < 2.10, a simpler overload that only takes dtype is available.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor whose properties may be inherited if kwargs are not provided.
- **size** - The desired size of the output tensor.
- **dtype** - Optional scalar type for the tensor elements.
- **layout** - Optional memory layout (e.g., strided, sparse).
- **device** - Optional device to place the tensor on.
- **pin_memory** - Optional flag to use pinned memory (for CUDA tensors).

Returns:

A new zero-filled tensor with the specified properties.

inline torch::stable::Tensor torch::stable::full(torch::headeronly::IntHeaderOnlyArrayRef size, double fill_value, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt, std::optional<torch::headeronly::Layout> layout = std::nullopt, std::optional<torch::stable::Device> device = std::nullopt, std::optional<bool> pin_memory = std::nullopt)

Stable version of the full.default op.

Creates a tensor of the specified size filled with the given value.

Minimum compatible version: PyTorch 2.10.

Note

The fill_value parameter is typed C shim API uses double for the Scalar parameter.

Parameters:

- **size** - The desired size of the output tensor.
- **fill_value** - The value to fill the tensor with.
- **dtype** - Optional scalar type for the tensor elements.
- **layout** - Optional memory layout.
- **device** - Optional device to place the tensor on.
- **pin_memory** - Optional flag to use pinned memory.

Returns:

A new tensor filled with the specified value.

inline torch::stable::Tensor torch::stable::from_blob(void *data, torch::headeronly::IntHeaderOnlyArrayRef sizes, torch::headeronly::IntHeaderOnlyArrayRef strides, torch::stable::Device device, torch::headeronly::ScalarType dtype, int64_t storage_offset = 0, torch::headeronly::Layout layout = torch::headeronly::Layout::Strided)

Creates a tensor from an existing data blob.

Creates a tensor that uses the provided data pointer as its storage. The tensor does not own the data, so the caller must ensure the data remains valid for the lifetime of the tensor.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **data** - Pointer to the data buffer.
- **sizes** - The size of each dimension of the tensor.
- **strides** - The stride for each dimension.
- **device** - The device where the data resides.
- **dtype** - The scalar type of the data.
- **storage_offset** - The offset into the data buffer. Defaults to 0.
- **layout** - The memory layout. Defaults to Strided.

Returns:

A tensor backed by the provided data.

inline torch::stable::Tensor torch::stable::from_file(const std::string &filename, std::optional<bool> shared = std::nullopt, std::optional<int64_t> size = 0, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt, std::optional<torch::headeronly::Layout> layout = std::nullopt, std::optional<torch::stable::Device> device = std::nullopt, std::optional<bool> pin_memory = std::nullopt)

Stable version of the from_file op.

Creates a CPU tensor backed by a memory-map of the file at filename. Unlike at::from_file, filename is a const std::string& rather than a std::string_view.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **filename** - Path of the file to read.
- **shared** - Optional flag to write tensor changes back to the file.
- **size** - Optional number of elements to read from the file.
- **dtype** - Optional scalar type for the tensor elements.
- **layout** - Optional memory layout, which must be strided for this op.
- **device** - Optional device, which must be CPU for this op.
- **pin_memory** - Optional pinning flag, which must be false for this op.

Returns:

A new tensor holding the file contents.

**Example:**

```
auto tensor = torch::stable::empty(
 {3, 4},
 torch::headeronly::ScalarType::Float,
 torch::headeronly::Layout::Strided,
 torch::stable::Device(torch::headeronly::DeviceType::CUDA, 0),
 false,
 torch::headeronly::MemoryFormat::Contiguous);
```

## Tensor Manipulation

inline torch::stable::Tensor torch::stable::clone(const torch::stable::Tensor &self)

Stable version of the clone op.

Returns a copy of the input tensor. The returned tensor has the same data and type as the input, but is stored in a new memory location.

Minimum compatible version: PyTorch 2.9.

Note

Optional memory_format kwarg support

Parameters:

**self** - The input tensor to clone.

Returns:

A new tensor with copied data.

inline torch::stable::Tensor torch::stable::contiguous(const torch::stable::Tensor &self, torch::headeronly::MemoryFormat memory_format = torch::headeronly::MemoryFormat::Contiguous)

Stable version of the contiguous op.

Returns a contiguous in memory tensor containing the same data as the input tensor. If the input tensor is already contiguous in the specified memory format, the input tensor is returned.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor.
- **memory_format** - The desired memory format.

Returns:

A contiguous tensor.

inline torch::stable::Tensor torch::stable::reshape(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef shape)

Stable version of the reshape op.

Returns a tensor with the same data and number of elements as the input, but with the specified shape. When possible, the returned tensor will be a view of the input.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor.
- **shape** - The desired output shape.

Returns:

A tensor with the specified shape.

inline torch::stable::Tensor torch::stable::view(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef size)

Stable version of the view op.

Returns a new tensor with the same data as the input tensor but with a different shape. The returned tensor shares the same data and must have the same number of elements.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor.
- **size** - The desired output shape.

Returns:

A view tensor with the specified shape.

inline torch::stable::Tensor torch::stable::view(const torch::stable::Tensor &self, torch::headeronly::ScalarType dtype)

Stable version of the view.dtype op.

Returns a view of the input tensor with the same data reinterpreted as the given dtype. This is a different overload than the shape-based view op.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The input tensor.
- **dtype** - The dtype to reinterpret the data as.

Returns:

A view of the input tensor with the specified dtype.

inline torch::stable::Tensor torch::stable::permute(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef dims)

Stable version of the permute op.

Returns a view of the input tensor with its dimensions rearranged according to dims. The returned tensor shares the same underlying data with the input.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The input tensor.
- **dims** - The desired ordering of dimensions.

Returns:

A permuted view of the input tensor.

inline torch::stable::Tensor torch::stable::flip(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef dims)

Stable version of the flip op.

Reverses the order of elements along the given dimensions and returns the result as a new tensor. Negative dimensions are wrapped.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **self** - The input tensor.
- **dims** - The dimensions to flip.

Returns:

A new tensor with the given dimensions reversed.

inline torch::stable::Tensor torch::stable::flatten(const torch::stable::Tensor &self, int64_t start_dim = 0, int64_t end_dim = -1)

Stable version of the flatten.using_ints op.

Flattens the input tensor by reshaping it into a one-dimensional tensor. If start_dim or end_dim are specified, only dimensions starting from start_dim to end_dim are flattened.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The input tensor to flatten.
- **start_dim** - The first dimension to flatten. Defaults to 0.
- **end_dim** - The last dimension to flatten. Defaults to -1 (last dim).

Returns:

A flattened tensor.

inline torch::stable::Tensor torch::stable::squeeze(const torch::stable::Tensor &self, int64_t dim)

Stable version of the squeeze.dim op.

Returns a tensor with the dimension of size one at the specified position removed. The returned tensor shares the same underlying data with the input tensor.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The input tensor.
- **dim** - The dimension to squeeze. the tensor is returned unchanged.

Returns:

A tensor with the specified dimension removed (if size was 1).

inline torch::stable::Tensor torch::stable::unsqueeze(const torch::stable::Tensor &self, int64_t dim)

Stable version of the unsqueeze op.

Returns a new tensor with a dimension of size one inserted at the specified position. The returned tensor shares the same underlying data with the input tensor.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The input tensor.
- **dim** - The index at which to insert values are supported.

Returns:

A tensor with an additional dimension.

inline torch::stable::Tensor torch::stable::transpose(const torch::stable::Tensor &self, int64_t dim0, int64_t dim1)

Stable version of the transpose.int op.

Returns a tensor that is a transposed version of the input, with dimensions dim0 and dim1 swapped. The returned tensor shares storage with the input.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The input tensor.
- **dim0** - The first dimension to transpose.
- **dim1** - The second dimension to transpose.

Returns:

A transposed view of the input tensor.

inline torch::stable::Tensor torch::stable::select(const torch::stable::Tensor &self, int64_t dim, int64_t index)

Stable version of the select.int op.

Slices the input tensor along the specified dimension at the given index. This function returns a view of the original tensor with the given dimension removed.

Minimum compatible version: PyTorch 2.9.

Note

The index parameter is typed header-only.

Parameters:

- **self** - The input tensor.
- **dim** - The dimension to slice.
- **index** - The index to select along the dimension.

Returns:

A tensor with one fewer dimension.

inline torch::stable::Tensor torch::stable::index_select(const torch::stable::Tensor &self, int64_t dim, const torch::stable::Tensor &index)

Stable version of the index_select op.

Returns a new tensor which indexes the input tensor along dimension dim using the entries in index.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The input tensor.
- **dim** - The dimension to index along.
- **index** - A 1-D tensor of indices to select.

Returns:

A tensor with values selected along dim.

inline torch::stable::Tensor torch::stable::narrow(torch::stable::Tensor &self, int64_t dim, int64_t start, int64_t length)

Stable version of the narrow.default op.

Returns a new tensor that is a narrowed version of the input tensor. The dimension dim is narrowed from start to start + length.

Minimum compatible version: PyTorch 2.9.

Note

The start and length parameters is not yet header-only.

Parameters:

- **self** - The input tensor to narrow.
- **dim** - The dimension along which to narrow.
- **start** - The starting index for the narrowed dimension.
- **length** - The length of the narrowed dimension.

Returns:

A new tensor that is a narrowed view of the input.

inline torch::stable::Tensor torch::stable::pad(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef pad, const std::string &mode = "constant", double value = 0.0)

Stable version of the pad.default op.

Pads the input tensor according to the specified padding sizes. The padding is applied symmetrically to each dimension, with the padding sizes specified in reverse order (last dimension first).

Minimum compatible version: PyTorch 2.9.

Note

The pad parameter is typed not yet header-only.

Parameters:

- **self** - The input tensor to pad.
- **pad** - The padding sizes for each dimension (in pairs, starting from the last dimension).
- **mode** - The padding mode: "constant", "reflect", "replicate", or "circular". Defaults to "constant".
- **value** - The fill value for constant padding. Defaults to 0.0.

Returns:

A new padded tensor.

## Device and Type Conversion

inline torch::stable::Tensor torch::stable::to(const torch::stable::Tensor &self, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt, std::optional<torch::headeronly::Layout> layout = std::nullopt, std::optional<torch::stable::Device> device = std::nullopt, std::optional<bool> pin_memory = std::nullopt, bool non_blocking = false, bool copy = false, std::optional<torch::headeronly::MemoryFormat> memory_format = std::nullopt)

Stable version of the to.dtype_layout op.

Converts a tensor to the specified dtype, layout, device, and/or memory format. Returns a new tensor with the specified properties.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor.
- **dtype** - Optional target scalar type.
- **layout** - Optional target memory layout.
- **device** - Optional target device.
- **pin_memory** - Optional flag to use pinned memory.
- **non_blocking** - If true, the operation may be asynchronous. Defaults to false.
- **copy** - If true, always create a copy. Defaults to false.
- **memory_format** - Optional target memory format.

Returns:

A tensor with the specified properties.

inline torch::stable::Tensor torch::stable::to(const torch::stable::Tensor &self, torch::stable::Device device, bool non_blocking = false, bool copy = false)

Convenience overload for moving a tensor to a device.

Moves the tensor to the specified device. This is a convenience wrapper around the full to() function.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor.
- **device** - The target device.
- **non_blocking** - If true, the operation may be asynchronous. Defaults to false.
- **copy** - If true, always create a copy. Defaults to false.

Returns:

A tensor on the specified device.

inline bool torch::stable::is_pinned(const torch::stable::Tensor &self)

Stable version of the is_pinned op.

Returns true if the tensor's storage is allocated in pinned memory.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

**self** - The input tensor.

Returns:

true if the tensor is pinned, false otherwise.

## In-place Operations

inline torch::stable::Tensor torch::stable::fill_(const torch::stable::Tensor &self, double value)

Stable version of the fill_.Scalar op.

Fills the input tensor with the specified scalar value in-place and returns it. This has identical semantics to the existing fill_.Scalar op.

Minimum compatible version: PyTorch 2.9.

Note

The value parameter is typed as double This is because Scalar.h is currently not header-only.

Parameters:

- **self** - The tensor to fill.
- **value** - The scalar value to fill the tensor with.

Returns:

The input tensor, now filled with the specified value.

inline torch::stable::Tensor torch::stable::zero_(torch::stable::Tensor &self)

Stable version of the zero_ op.

Fills the input tensor with zeros in-place and returns it. Unlike the tensor method version (t.zero_()), this is called as a function: zero_(t).

Minimum compatible version: PyTorch 2.9.

Parameters:

**self** - The tensor to fill with zeros.

Returns:

The input tensor, now filled with zeros.

inline torch::stable::Tensor torch::stable::copy_(torch::stable::Tensor &self, const torch::stable::Tensor &src, std::optional<bool> non_blocking = std::nullopt)

Stable version of the copy_ op.

Copies the elements from the source tensor into the destination tensor in-place and returns the destination tensor. The tensors must be broadcastable.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The destination tensor (modified in-place).
- **src** - The source tensor to copy from.
- **non_blocking** - If true, the copy may occur asynchronously with respect to the host. Defaults to false.

Returns:

The destination tensor with copied values.

## Mathematical Operations

inline torch::stable::Tensor torch::stable::matmul(const torch::stable::Tensor &self, const torch::stable::Tensor &other)

Stable version of the matmul op.

Performs matrix multiplication between two tensors. The behavior depends on the dimensionality of the tensors (see PyTorch documentation for details on broadcasting rules for matmul).

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The first input tensor.
- **other** - The second input tensor.

Returns:

The result of matrix multiplication.

inline torch::stable::Tensor &torch::stable::mm_out(torch::stable::Tensor &out, const torch::stable::Tensor &self, const torch::stable::Tensor &mat2)

Stable version of the mm.out op.

Computes the matrix product of the 2-D tensors self and mat2, storing the result in out.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **out** - The output tensor (modified in-place).
- **self** - The first 2-D input tensor.
- **mat2** - The second 2-D input tensor.

Returns:

Reference to the output tensor.

inline torch::stable::Tensor &torch::stable::mm_out(torch::stable::Tensor &out, const torch::stable::Tensor &self, const torch::stable::Tensor &mat2, torch::headeronly::ScalarType out_dtype)

Stable version of the mm.dtype_out op.

Computes the matrix product of self and mat2 in out_dtype. This is a different overload than mm_out without the out_dtype argument.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **out** - The output tensor (modified in-place).
- **self** - The first 2-D input tensor.
- **mat2** - The second 2-D input tensor.
- **out_dtype** - The dtype of the result.

Returns:

Reference to the output tensor.

inline torch::stable::Tensor &torch::stable::bmm_out(torch::stable::Tensor &out, const torch::stable::Tensor &self, const torch::stable::Tensor &mat2)

Stable version of the bmm.out op.

Computes the batch matrix product of the 3-D tensors self and mat2, storing the result in out.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **out** - The output tensor (modified in-place).
- **self** - The first 3-D input tensor of shape (b, n, m).
- **mat2** - The second 3-D input tensor of shape (b, m, p).

Returns:

Reference to the output tensor.

inline torch::stable::Tensor &torch::stable::bmm_out(torch::stable::Tensor &out, const torch::stable::Tensor &self, const torch::stable::Tensor &mat2, torch::headeronly::ScalarType out_dtype)

Stable version of the bmm.dtype_out op.

Computes the batch matrix product of self and mat2 in out_dtype. This is a different overload than bmm_out without the out_dtype argument.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **out** - The output tensor (modified in-place).
- **self** - The first 3-D input tensor of shape (b, n, m).
- **mat2** - The second 3-D input tensor of shape (b, m, p).
- **out_dtype** - The dtype of the result.

Returns:

Reference to the output tensor.

inline torch::stable::Tensor torch::stable::amax(const torch::stable::Tensor &self, int64_t dim, bool keepdim = false)

Stable version of the amax.default op (single dimension).

Computes the maximum value along the specified dimension. If keepdim is true, the output tensor has the same number of dimensions as the input, with the reduced dimension having size 1. Otherwise, the reduced dimension is removed.

Minimum compatible version: PyTorch 2.9.

Parameters:

- **self** - The input tensor.
- **dim** - The dimension along which to compute the maximum.
- **keepdim** - Whether to retain

Returns:

A tensor containing the maximum values along the specified dimension.

inline torch::stable::Tensor torch::stable::amax(const torch::stable::Tensor &self, torch::headeronly::IntHeaderOnlyArrayRef dims, bool keepdim = false)

Stable version of the amax.default op (multiple dimensions).

Computes the maximum value reducing over all the specified dimensions. If keepdim is true, the output tensor has the same number of dimensions as the input, with the reduced dimensions having size 1. Otherwise, the reduced dimensions are removed.

Minimum compatible version: PyTorch 2.9.

Note

The dims parameter is typed is not yet header-only.

Parameters:

- **self** - The input tensor.
- **dims** - The dimensions along which to compute the maximum.
- **keepdim** - Whether to retain the reduced dimensions. Defaults to false.

Returns:

A tensor containing the maximum values.

inline torch::stable::Tensor torch::stable::sum(const torch::stable::Tensor &self, std::optional<torch::headeronly::IntHeaderOnlyArrayRef> dim = std::nullopt, bool keepdim = false, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt)

Stable version of the sum.dim_IntList op.

Computes the sum of the input tensor along the specified dimensions. If dim is not provided, sums over all dimensions.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **self** - The input tensor.
- **dim** - Optional dimensions to reduce. If not provided, reduces all dimensions.
- **keepdim** - Whether to retain the reduced dimensions. Defaults to false.
- **dtype** - Optional output dtype. If not provided, uses the input dtype.

Returns:

A tensor containing the sum.

inline torch::stable::Tensor &torch::stable::sum_out(torch::stable::Tensor &out, const torch::stable::Tensor &self, std::optional<torch::headeronly::IntHeaderOnlyArrayRef> dim = std::nullopt, bool keepdim = false, std::optional<torch::headeronly::ScalarType> dtype = std::nullopt)

Stable version of the sum.IntList_out op.

Computes the sum of the input tensor along the specified dimensions, storing the result in the provided output tensor. Following C++ convention, the out parameter comes first.

Minimum compatible version: PyTorch 2.10.

Parameters:

- **out** - The output tensor (modified in-place).
- **self** - The input tensor.
- **dim** - Optional dimensions to reduce.
- **keepdim** - Whether to retain the reduced dimensions. Defaults to false.
- **dtype** - Optional output dtype.

Returns:

Reference to the output tensor.

inline torch::stable::Tensor torch::stable::add(const torch::stable::Tensor &self, const torch::stable::Tensor &other, double alpha = 1.0)

Stable version of the add.Tensor op.

Adds the other tensor to self, scaled by alpha: self + alpha * other. Unlike at::add, alpha is a double rather than a Scalar. Adding two integral or boolean tensors is not supported.

Minimum compatible version: PyTorch 2.16. Build time minimum version: PyTorch 2.16.

Parameters:

- **self** - The input tensor.
- **other** - The tensor to add.
- **alpha** - The scaling factor for other. Defaults to 1.0.

Returns:

The result of self + alpha * other.

inline torch::stable::Tensor torch::stable::subtract(const torch::stable::Tensor &self, const torch::stable::Tensor &other, double alpha = 1.0)

Stable version of the subtract.Tensor op.

Subtracts the other tensor from self, with an optional scaling factor alpha. Computes: self - alpha * other.

Minimum compatible version: PyTorch 2.10.

Note

The alpha parameter is typed as double API uses double for the Scalar parameter.

Parameters:

- **self** - The input tensor.
- **other** - The tensor to subtract.
- **alpha** - The scaling factor for other. Defaults to 1.0.

Returns:

The result of self - alpha * other.

inline torch::stable::Tensor torch::stable::bitwise_and(const torch::stable::Tensor &self, const torch::stable::Tensor &other)

Stable version of the bitwise_and.Tensor op.

Computes the element-wise bitwise AND of self and other.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The first input tensor.
- **other** - The second input tensor.

Returns:

The result of the bitwise AND.

inline torch::stable::Tensor torch::stable::bitwise_or(const torch::stable::Tensor &self, const torch::stable::Tensor &other)

Stable version of the bitwise_or.Tensor op.

Computes the element-wise bitwise OR of self and other.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The first input tensor.
- **other** - The second input tensor.

Returns:

The result of the bitwise OR.

inline torch::stable::Tensor torch::stable::bitwise_left_shift(const torch::stable::Tensor &self, const torch::stable::Tensor &other)

Stable version of the bitwise_left_shift.Tensor op.

Computes the element-wise left bitwise shift of self by other.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The input tensor to shift.
- **other** - The tensor of shift amounts.

Returns:

The result of the left bitwise shift.

inline torch::stable::Tensor torch::stable::bitwise_right_shift(const torch::stable::Tensor &self, const torch::stable::Tensor &other)

Stable version of the bitwise_right_shift.Tensor op.

Computes the element-wise right bitwise shift of self by other.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The input tensor to shift.
- **other** - The tensor of shift amounts.

Returns:

The result of the right bitwise shift.

inline torch::stable::Tensor torch::stable::floor_divide(const torch::stable::Tensor &self, const torch::stable::Tensor &other)

Stable version of the floor_divide op.

Computes the element-wise floor division of self by other.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.14.

Parameters:

- **self** - The dividend tensor.
- **other** - The divisor tensor.

Returns:

The result of floor division.

inline std::tuple<torch::stable::Tensor, torch::stable::Tensor> torch::stable::sort(const torch::stable::Tensor &self, int64_t dim = -1, bool descending = false)

Stable version of the sort op.

Sorts the input tensor along dim, returning the values and their indices.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **self** - The input tensor.
- **dim** - The dimension to sort along.
- **descending** - Whether to sort in descending order.

Returns:

A tuple of the sorted values and their indices.

inline std::tuple<torch::stable::Tensor, torch::stable::Tensor> torch::stable::sort(const torch::stable::Tensor &self, std::optional<bool> stable, int64_t dim = -1, bool descending = false)

Stable version of the sort.stable op.

Sorts the input tensor along dim, returning the values and their indices. This is a different overload than the sort op without the stable argument.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **self** - The input tensor.
- **stable** - Whether equal elements keep their original order.
- **dim** - The dimension to sort along.
- **descending** - Whether to sort in descending order.

Returns:

A tuple of the sorted values and their indices.

inline torch::stable::Tensor torch::stable::masked_select(const torch::stable::Tensor &self, const torch::stable::Tensor &mask)

Stable version of the masked_select op.

Returns a 1-D tensor of the elements of self where mask is true.

Minimum compatible version: PyTorch 2.10. Build time minimum version: PyTorch 2.15.

Parameters:

- **self** - The input tensor.
- **mask** - A boolean tensor broadcastable with self.

Returns:

A 1-D tensor of the selected elements.

---

# Library Registration Macros

These macros provide stable ABI equivalents of the standard PyTorch operator
registration macros (`TORCH_LIBRARY`, `TORCH_LIBRARY_IMPL`, etc.).
Use these when building custom operators that need to maintain binary
compatibility across PyTorch versions.

## STABLE_TORCH_LIBRARY

STABLE_TORCH_LIBRARY(ns, m)

Defines a library of operators in a namespace using the stable ABI.

This is the stable ABI equivalent of [`TORCH_LIBRARY`](../library/registration.html#c.TORCH_LIBRARY).
Use this macro to define operator schemas that will maintain
binary compatibility across PyTorch versions. Only one `STABLE_TORCH_LIBRARY`
block can exist per namespace; use `STABLE_TORCH_LIBRARY_FRAGMENT` for
additional definitions in the same namespace from different translation units.

:param ns: The namespace in which to define operators (e.g., `mylib`).
:param m: The name of the StableLibrary variable available in the block.

**Example:**

```
STABLE_TORCH_LIBRARY(mylib, m) {
 m.def("my_op(Tensor input, int size) -> Tensor");
 m.def("another_op(Tensor a, Tensor b) -> Tensor");
}
```

Minimum compatible version: PyTorch 2.9.

```
## STABLE_TORCH_LIBRARY_IMPL

```{c:macro} STABLE_TORCH_LIBRARY_IMPL(ns, k, m)

Registers operator implementations for a specific dispatch key using the stable ABI.

This is the stable ABI equivalent of `TORCH_LIBRARY_IMPL`. Use this macro
to provide implementations of operators for a specific dispatch key (e.g.,
CPU, CUDA) while maintaining binary compatibility across PyTorch versions.
```

Note

All kernel functions registered with this macro must be boxed using
the `TORCH_BOX` macro.

:param ns: The namespace in which the operators are defined.
:param k: The dispatch key (e.g., `CPU`, `CUDA`).
:param m: The name of the StableLibrary variable available in the block.

**Example:**

```
STABLE_TORCH_LIBRARY_IMPL(mylib, CPU, m) {
 m.impl("my_op", TORCH_BOX(&my_cpu_kernel));
}

STABLE_TORCH_LIBRARY_IMPL(mylib, CUDA, m) {
 m.impl("my_op", TORCH_BOX(&my_cuda_kernel));
}
```

Minimum compatible version: PyTorch 2.9.

## STABLE_TORCH_LIBRARY_FRAGMENT

STABLE_TORCH_LIBRARY_FRAGMENT(ns, m)

Extends operator definitions in an existing namespace using the stable ABI.

This is the stable ABI equivalent of `TORCH_LIBRARY_FRAGMENT`. Use this macro
to add additional operator definitions to a namespace that was already
created with `STABLE_TORCH_LIBRARY`.

:param ns: The namespace to extend.
:param m: The name of the StableLibrary variable available in the block.

Minimum compatible version: PyTorch 2.9.

## TORCH_BOX

TORCH_BOX(func)

Wraps a function to conform to the stable boxed kernel calling convention.

This macro takes an unboxed kernel function pointer and generates a boxed wrapper
that can be registered with the stable library API.

:param func: The unboxed kernel function to wrap.

**Example:**

```
Tensor my_kernel(const Tensor& input, int64_t size) {
 return input.reshape({size});
}

STABLE_TORCH_LIBRARY_IMPL(my_namespace, CPU, m) {
 m.impl("my_op", TORCH_BOX(&my_kernel));
}
```

Minimum compatible version: PyTorch 2.9.

```

```

---

# Utilities

The stable API provides various utility functions and types for working with
tensors and CUDA operations.

## DeviceGuard Class

class DeviceGuard

A stable ABI version of [c10::DeviceGuard](../c10/guards.html#PyTorchclassc10_1_1_device_guard).

RAII class that sets the current device to the specified device index on construction and restores the previous device on destruction.

Minimum compatible version: PyTorch 2.9.

Public Functions

inline explicit DeviceGuard(DeviceIndex device_index)

Constructs a DeviceGuard that sets the current device.

Minimum compatible version: PyTorch 2.9.

Parameters:

**device_index** - The device index to set as the current device.

inline void set_index(DeviceIndex device_index)

Changes the current device to the specified device index.

Minimum compatible version: PyTorch 2.9.

Parameters:

**device_index** - The new device index to set.

inline DeviceIndex torch::stable::accelerator::getCurrentDeviceIndex()

Gets the current device index.

Returns the index of the currently active device for the accelerator.

Minimum compatible version: PyTorch 2.9.

Returns:

The current device index.

**Example:**

```
{
 torch::stable::accelerator::DeviceGuard guard(1);
 // Operations here run on device 1
}
// Previous device is restored
```

## Stream

class Stream

Public Functions

explicit Stream() = delete

inline explicit Stream(StreamHandle stream)

inline StreamId id() const

inline void *nativeHandle() const

## Stream Utilities

### Getting the Current CUDA Stream

To obtain the current `cudaStream_t` for use in CUDA kernels:

PyTorch version 2.13+

```
#include <torch/csrc/stable/accelerator.h>

// nativeHandle() requires PyTorch 2.13+
cudaStream_t stream = static_cast<cudaStream_t>(
 torch::stable::accelerator::getCurrentStream(tensor.get_device_index()).nativeHandle());

// Now you can use 'stream' in your CUDA kernel launches
my_kernel<<<blocks, threads, 0, stream>>>(args...);
```

PyTorch version 2.9-2.12

```
#include <torch/csrc/inductor/aoti_torch/c/shim.h>
#include <torch/headeronly/util/shim_utils.h>

// Use the ABI-stable C shim API to get the current CUDA stream.
void* stream_ptr = nullptr;
TORCH_ERROR_CODE_CHECK(
 aoti_torch_get_current_cuda_stream(tensor.get_device_index(), &stream_ptr));
cudaStream_t stream = static_cast<cudaStream_t>(stream_ptr);

// Now you can use 'stream' in your CUDA kernel launches
my_kernel<<<blocks, threads, 0, stream>>>(args...);
```

Note

When using C shim APIs, the `TORCH_ERROR_CODE_CHECK` macro is required to properly check error codes and throw appropriate exceptions. `nativeHandle()`, along with all our highlevel C++ utility APIs, does this check for you.

## CUDA Error Checking Macros

These macros provide stable ABI equivalents for CUDA error checking.
They wrap CUDA API calls and kernel launches, providing detailed error
messages using PyTorch's error formatting.

### STD_CUDA_CHECK

STD_CUDA_CHECK(EXPR)

Checks the result of a CUDA API call and throws an exception on error.
Users of this macro are expected to include `cuda_runtime.h`.

**Example:**

```
STD_CUDA_CHECK(cudaMalloc(&ptr, size));
STD_CUDA_CHECK(cudaMemcpy(dst, src, size, cudaMemcpyDeviceToHost));
```

Minimum compatible version: PyTorch 2.10.

```
### STD_CUDA_KERNEL_LAUNCH_CHECK

```{c:macro} STD_CUDA_KERNEL_LAUNCH_CHECK()

Checks for errors from the most recent CUDA kernel launch. Equivalent to
`STD_CUDA_CHECK(cudaGetLastError())`.

**Example:**

```cpp
my_kernel<<<blocks, threads, 0, stream>>>(args...);
STD_CUDA_KERNEL_LAUNCH_CHECK();
```

Minimum compatible version: PyTorch 2.10.

```
## Warning Macros

These macros are the stable ABI counterparts of `TORCH_WARN` and
`TORCH_WARN_ONCE`.

They differ from `TORCH_WARN` and `TORCH_WARN_ONCE` in two ways:

- Arguments are streamed through `std::ostringstream` rather than `c10::str`,
 so `std::optional`, scoped enums without an `operator<<`, and wide strings
 compile with `TORCH_WARN` but not with `STABLE_TORCH_WARN`.
- The warning is always a `UserWarning`. There is not yet a stable ABI
 equivalent of `TORCH_WARN_DEPRECATION`.

### STABLE_TORCH_WARN

```{c:macro} STABLE_TORCH_WARN(...)

Emits a warning with the given message.

**Example:**

```cpp
STABLE_TORCH_WARN("my_op got n=", n, ", which may be slow");
```

Minimum compatible version: PyTorch 2.9.
Build time minimum version: PyTorch 2.16.

```
### STABLE_TORCH_WARN_ONCE

```{c:macro} STABLE_TORCH_WARN_ONCE(...)

Emits a warning the first time the call site is reached, or on every call while
`torch.set_warn_always(True)` is in effect.

**Example:**

```cpp
STABLE_TORCH_WARN_ONCE("my_op is deprecated, use my_new_op instead");
```

Minimum compatible version: PyTorch 2.16.
Build time minimum version: PyTorch 2.16.

```
## Header-Only Utilities

The `torch::headeronly` namespace provides header-only versions of common
PyTorch types and utilities. These can be used without linking against libtorch
at all! This portability makes them ideal for maintaining binary compatibility
across PyTorch versions.

### Error Checking

`STD_TORCH_CHECK` is a header-only macro for runtime assertions:

```cpp
#include <torch/headeronly/util/Exception.h>

STD_TORCH_CHECK(condition, "Error message with ", variable, " interpolation");
```

Wherever you used `TORCH_CHECK` before, you can replace usage with `STD_TORCH_CHECK`
to remove the need to link against libtorch. The only difference is that when the
condition check fails, `TORCH_CHECK` throws a fancier `c10::Error` while
`STD_TORCH_CHECK` throws a `std::runtime_error`.

### Core Types

The following `c10::` types are available as header-only versions under
`torch::headeronly::`:

- `torch::headeronly::ScalarType` - Tensor data types (Float, Double, Int, etc.)
- `torch::headeronly::DeviceType` - Device types (CPU, CUDA, etc.)
- `torch::headeronly::MemoryFormat` - Memory layout formats (Contiguous, ChannelsLast, etc.)
- `torch::headeronly::Layout` - Tensor layouts (Strided, Sparse, etc.)

```
#include <torch/headeronly/core/ScalarType.h>
#include <torch/headeronly/core/DeviceType.h>
#include <torch/headeronly/core/MemoryFormat.h>
#include <torch/headeronly/core/Layout.h>

auto dtype = torch::headeronly::ScalarType::Float;
auto device_type = torch::headeronly::DeviceType::CUDA;
auto memory_format = torch::headeronly::MemoryFormat::Contiguous;
auto layout = torch::headeronly::Layout::Strided;
```

### Accumulate Types

`acc_type<T, is_cuda>` and `acc_type_device<T, DeviceType>` give the dtype a
reduction over `T` should accumulate into, using the same tables as `at::acc_type`:

```
#include <torch/headeronly/core/AccumulateType.h>

using acc_t = torch::headeronly::acc_type<torch::headeronly::Half, /*is_cuda*/true>;
```

### TensorAccessor

`TensorAccessor` provides efficient, bounds-checked access to tensor data.
You can construct one from a stable tensor's data pointer, sizes, and strides:

```
#include <torch/headeronly/core/TensorAccessor.h>

// Create a TensorAccessor for a 2D float tensor
auto sizes = tensor.sizes();
auto strides = tensor.strides();
torch::headeronly::TensorAccessor<float, 2> accessor(
 static_cast<float*>(tensor.mutable_data_ptr()),
 sizes.data(),
 strides.data());

// Access elements
float value = accessor[i][j];
```

### Dispatch Macros

Header-only dispatch macros (THO = Torch Header Only) are available for
dtype dispatching:

```
#include <torch/headeronly/core/Dispatch_v2.h>

THO_DISPATCH_V2(
 tensor.scalar_type(), // will be resolved as scalar_t
 "my_kernel",
 AT_WRAP(([&]() {
 // code to specialize with scalar_t
 // scalar_t is the resolved C++ type (e.g. float, double)
 auto* data = static_cast<scalar_t*>(tensor.mutable_data_ptr());
 Scalar s(*data);
 })),
 AT_EXPAND(AT_ALL_TYPES),
 AT_EXPAND(AT_COMPLEX_TYPES),
 torch::headeronly::ScalarType::Half,
 // as many type arguments as needed
);
```

`THO_DISPATCH_V2` works the same way as `AT_DISPATCH_V2` (see
`ATen/Dispatch_v2.h`) but does not require linking against libtorch.
As a result, whereas `AT_DISPATCH_V2` would have thrown `c10::NotImplementedError`
for unimplemented paths, `THO_DISPATCH_V2` will throw `std::runtime_error`.

For ease of use, we've also migrated the below AT_* macros representing
collections of types to be header-only and thus have no dependency on libtorch:

- `AT_FLOATING_TYPES`
- `AT_INTEGRAL_TYPES`
- `AT_INTEGRAL_TYPES_V2`
- `AT_ALL_TYPES`
- `AT_COMPLEX_TYPES`
- `AT_ALL_TYPES_AND_COMPLEX`
- `AT_FLOAT8_TYPES`
- `AT_BAREBONES_UNSIGNED_TYPES`
- `AT_QINT_TYPES`

If your extension uses our older AT_DISPATCH version 1 infrastructure,
you can also migrate to a header-only libtorch-free world without upgrading
everything to version 2.

`THO_DISPATCH_SWITCH` and `THO_DISPATCH_CASE` are the header-only
equivalents of `AT_DISPATCH_SWITCH` and `AT_DISPATCH_CASE`. Similarly,
the only user-visible difference is the exception type on an unhandled dtype,
where the `AT_` version throws a `c10::NotImplementedError` and the `THO_`
version throws a `std::runtime_error`.

The migration is pretty mechanical:

- `AT_DISPATCH_SWITCH` → `THO_DISPATCH_SWITCH`
- `AT_DISPATCH_CASE` → `THO_DISPATCH_CASE`
- `AT_PRIVATE_CASE_TYPE_USING_HINT` → `THO_PRIVATE_CASE_TYPE_USING_HINT`
- `at::ScalarType::X` → `torch::headeronly::ScalarType::X`

```
// ---- Before (requires linking against libtorch) ----
#include <torch/all.h>

#define MY_DISPATCH_CASE_FLOATING_TYPES(...) \
 AT_DISPATCH_CASE(at::ScalarType::Float, __VA_ARGS__) \
 AT_DISPATCH_CASE(at::ScalarType::Half, __VA_ARGS__) \
 AT_DISPATCH_CASE(at::ScalarType::BFloat16, __VA_ARGS__)

#define MY_DISPATCH_FLOATING_TYPES(TYPE, NAME, ...) \
 AT_DISPATCH_SWITCH(TYPE, NAME, \
 MY_DISPATCH_CASE_FLOATING_TYPES(__VA_ARGS__))
```

```
// ---- After (header-only, no libtorch dependency) ----
#include <torch/headeronly/core/Dispatch.h>

#define MY_DISPATCH_CASE_FLOATING_TYPES(...) \
 THO_DISPATCH_CASE(torch::headeronly::ScalarType::Float, __VA_ARGS__) \
 THO_DISPATCH_CASE(torch::headeronly::ScalarType::Half, __VA_ARGS__) \
 THO_DISPATCH_CASE(torch::headeronly::ScalarType::BFloat16, __VA_ARGS__)

#define MY_DISPATCH_FLOATING_TYPES(TYPE, NAME, ...) \
 THO_DISPATCH_SWITCH(TYPE, NAME, \
 MY_DISPATCH_CASE_FLOATING_TYPES(__VA_ARGS__))
```

For the complete list of header-only APIs, see `torch/header_only_apis.txt`
in the PyTorch source tree.

## Parallelization Utilities

template<class F>
inline void torch::stable::parallel_for(const int64_t begin, const int64_t end, const int64_t grain_size, const F &f)

Stable parallel_for utility.

Provides a stable interface to at::parallel_for for parallel execution. The function f will be called with (begin, end) ranges to process in parallel. grain_size controls the minimum work size per thread for efficient parallelization.

Minimum compatible version: PyTorch 2.10.

Template Parameters:

**F** - The callable type

Parameters:

- **begin** - The start of the iteration range.
- **end** - The end of the iteration range (exclusive).
- **grain_size** - The minimum number of iterations per thread.
- **f** - The function to execute in parallel.

inline uint32_t torch::stable::get_num_threads()

Gets the number of threads for the parallel backend.

Provides a stable interface to at::get_num_threads.

Minimum compatible version: PyTorch 2.10.

Returns:

The number of threads

---

# XPU Support

PyTorch provides XPU support for Intel GPU-accelerated tensor operations.
The XPU API allows you to manage Intel GPU devices, streams for asynchronous
execution, and synchronization.

**When to use XPU APIs:**

- When running on Intel GPUs (Data Center GPU Max, Arc, etc.)
- When implementing custom XPU kernels or operations
- When managing asynchronous execution with XPU streams
- When writing device-portable code alongside CUDA

**Basic usage:**

```
#include <torch/torch.h>

// Check if XPU is available
if (torch::xpu::is_available()) {
 // Create tensor on XPU
 auto tensor = torch::randn({2, 3}, torch::device(torch::kXPU));

 // Move model to XPU
 model->to(torch::kXPU);
}
```

## Header Files

- `torch/xpu.h` - High-level XPU utilities (device count, availability, seeding)
- `c10/xpu/XPUStream.h` - XPU stream management

## XPU Categories

- [XPU Streams](streams.html)
- [XPU Utility Functions](utilities.html)

---

# XPU Streams

XPU streams provide a mechanism for asynchronous execution of operations
on Intel GPUs. Like CUDA streams, operations queued to the same stream execute
in order, while operations on different streams can execute concurrently.

## XPUStream

class XPUStream

Public Types

enum Unchecked

*Values:*

enumerator UNCHECKED

Public Functions

inline explicit XPUStream([Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Construct a XPUStream from a [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream).

This construction is checked, and will raise an error if the [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) is not, in fact, a XPU stream.

inline explicit XPUStream(Unchecked, [Stream](../c10/streams.html#_CPPv4N3c106StreamE) stream)

Construct a XPUStream from a [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) with no error checking.

inline bool operator==(const XPUStream &other) const noexcept

inline bool operator!=(const XPUStream &other) const noexcept

inline operator sycl::queue&() const

Implicit conversion to sycl::queue&.

inline operator sycl::queue*() const

Implicit conversion to sycl::queue*.

inline operator [Stream](../c10/streams.html#_CPPv4N3c106StreamE)() const

Implicit conversion to [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream) (a.k.a., forget that the stream is a XPU stream).

inline [DeviceType](../c10/device.html#_CPPv4N3c1010DeviceTypeE) device_type() const

Get the XPU device type that this stream is associated with.

inline DeviceIndex device_index() const

Get the XPU device index that this stream is associated with.

inline [Device](../c10/device.html#_CPPv4N3c106DeviceE) device() const

Get the full [Device](../c10/device.html#PyTorchstructc10_1_1_device) that this stream is associated with.

The [Device](../c10/device.html#PyTorchstructc10_1_1_device) is guaranteed to be a XPU device.

inline StreamId id() const

Return the stream ID corresponding to this particular stream.

StreamId is a int64_t representation generated by its type and index.

inline bool query() const

Return true if all enqueued tasks in this stream have been completed, otherwise return false.

inline void synchronize() const

Performs a blocking wait for the completion of all enqueued tasks in this stream.

inline bool is_capturing() const

int priority() const

Return the priority that this stream is associated with.

Lower numbers represent higher priority.

sycl::queue &queue() const

Explicit conversion to sycl::queue&.

inline [Stream](../c10/streams.html#_CPPv4N3c106StreamE) unwrap() const

Explicit conversion to [Stream](../c10/streams.html#PyTorchclassc10_1_1_stream).

inline struct c10::StreamData3 pack3() const

Reversibly pack a XPUStream into a struct representation.

The XPUStream can be unpacked using unpack3().

Public Static Functions

static inline XPUStream unpack3(StreamId stream_id, DeviceIndex device_index, [DeviceType](../c10/device.html#_CPPv4N3c1010DeviceTypeE) device_type)

Unpack a XPUStream from the 3 fields generated by pack3().

static inline std::tuple<int, int> priority_range()

Return the range of priority **supported by PyTorch**.

**Example:**

```
#include <c10/xpu/XPUStream.h>

// Get the current XPU stream
auto stream = c10::xpu::getCurrentXPUStream();

// Create a new stream from the pool
auto new_stream = c10::xpu::getStreamFromPool();

// Synchronize
stream.synchronize();
```

## Acquiring XPU Streams

XPUStream c10::xpu::getCurrentXPUStream(DeviceIndex device = -1)

Get the current XPU stream, for the passed XPU device, or for the current device if no device index is passed.

void c10::xpu::setCurrentXPUStream(XPUStream stream)

Set the current stream on the device of the passed in stream to be the passed in stream.

XPUStream c10::xpu::getStreamFromPool(const bool isHighPriority = false, DeviceIndex device = -1)

Get a stream from the pool in a round-robin fashion.

You can request a stream from the highest priority pool by setting isHighPriority to true for a specific device.

## Stream Synchronization

void c10::xpu::syncStreamsOnDevice(DeviceIndex device = -1)

Block all reserved SYCL queues in the stream pools on the device, and wait for their synchronizations.

---

# XPU Utility Functions

High-level utility functions for querying and managing XPU devices.

## Device Management

size_t torch::xpu::device_count()

Returns the number of XPU devices available.

bool torch::xpu::is_available()

Returns true if at least one XPU device is available.

void torch::xpu::synchronize(int64_t device_index)

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

**Example:**

```
#include <torch/torch.h>

if (torch::xpu::is_available()) {
 size_t num_devices = torch::xpu::device_count();
 std::cout << "Found " << num_devices << " XPU device(s)" << std::endl;

 // Synchronize all streams on device 0
 torch::xpu::synchronize(0);
}
```

## Random Number Generation

void torch::xpu::manual_seed(uint64_t seed)

Sets the seed for the current GPU.

void torch::xpu::manual_seed_all(uint64_t seed)

Sets the seed for all available GPUs.

**Example:**

```
// Set seed for reproducibility on current XPU device
torch::xpu::manual_seed(42);

// Set seed for all XPU devices
torch::xpu::manual_seed_all(42);
```

---

# FAQ

Listed below are a number of common issues users face with the various parts of
the C++ API.

## C++ Extensions

### Undefined symbol errors from PyTorch/ATen

**Problem**: You import your extension and get an `ImportError` stating that
some C++ symbol from PyTorch or ATen is undefined. For example:

```
>>> import extension
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
ImportError: /home/user/.pyenv/versions/3.7.1/lib/python3.7/site-packages/extension.cpython-37m-x86_64-linux-gnu.so: undefined symbol: _ZN2at19UndefinedTensorImpl10_singletonE
```

**Fix**: The fix is to `import torch` before you import your extension. This will make
the symbols from the PyTorch dynamic (shared) library that your extension
depends on available, allowing them to be resolved once you import your extension.

### I created a tensor using a function from `at::` and get errors

**Problem**: You created a tensor using e.g. `at::ones` or `at::randn` or
any other tensor factory from the `at::` namespace and are getting errors.

**Fix**: Replace `at::` with `torch::` for factory function calls. You
should never use factory functions from the `at::` namespace, as they will
create tensors. The corresponding `torch::` functions will create variables,
and you should only ever deal with variables in your code.

## LibTorch

### How do I move a model to GPU?

**Problem**: You want to run your model on GPU but are unsure how to move both
the model and tensors to the correct device.

**Fix**: Use the `to()` method to move your model and tensors to a CUDA device:

```
torch::Device device(torch::kCUDA);
model->to(device);
auto input = torch::randn({1, 3, 224, 224}).to(device);
auto output = model->forward(input);
```

You can also check for CUDA availability before moving:

```
torch::Device device(torch::cuda::is_available() ? torch::kCUDA : torch::kCPU);
```

Make sure to compile with the TorchScript headers by including `<torch/script.h>`.

### My model runs slower in C++ than in Python

**Problem**: Your model inference is slower in C++ compared to Python.

**Fix**: There are several common causes:

1. **Enable inference mode**: Wrap your inference code with `torch::NoGradGuard`
to disable gradient computation:

```
torch::NoGradGuard no_grad;
auto output = model->forward(input);
```

1. **Enable optimizations**: For TorchScript models, use `optimize_for_inference`:

```
module = torch::jit::optimize_for_inference(module);
```

1. **Warm up the model**: Run a few inference passes before benchmarking to allow
JIT compilation and memory allocation to complete.
2. **Check thread settings**: Ensure proper thread configuration:

```
at::set_num_threads(4); // Adjust based on your hardware
```

## Neural Network Modules

### How do I register submodules in a custom module?

**Problem**: You created a custom module but the submodules are not being
recognized during `forward()` or when saving/loading the model.

**Fix**: You must register submodules in the constructor using
`register_module()`:

```
struct MyModel : torch::nn::Module {
 MyModel() {
 fc1 = register_module("fc1", torch::nn::Linear(784, 128));
 fc2 = register_module("fc2", torch::nn::Linear(128, 10));
 }

 torch::Tensor forward(torch::Tensor x) {
 x = torch::relu(fc1->forward(x));
 return fc2->forward(x);
 }

 torch::nn::Linear fc1{nullptr}, fc2{nullptr};
};
```

### How do I set a module to evaluation mode?

**Problem**: Layers like Dropout and BatchNorm behave differently during training
and evaluation, and you need to switch between modes.

**Fix**: Use the `eval()` and `train()` methods:

```
model->eval(); // Set to evaluation mode
// ... run inference ...
model->train(); // Set back to training mode
```

## Data Loading

### How do I create a custom dataset?

**Problem**: You want to load your own data instead of using built-in datasets.

**Fix**: Create a class that inherits from `torch::data::datasets::Dataset` and
implement the `get()` and `size()` methods:

```
class CustomDataset : public torch::data::datasets::Dataset<CustomDataset> {
 public:
 explicit CustomDataset(const std::string& data_path) {
 // Load your data here
 }

 torch::data::Example<> get(size_t index) override {
 // Return a single data sample
 torch::Tensor data = /* load data at index */;
 torch::Tensor label = /* load label at index */;
 return {data, label};
 }

 torch::optional<size_t> size() const override {
 return dataset_size_;
 }

 private:
 size_t dataset_size_;
};
```

Then use it with a DataLoader:

```
auto dataset = CustomDataset("path/to/data")
 .map(torch::data::transforms::Stack<>());
auto dataloader = torch::data::make_data_loader(
 std::move(dataset),
 torch::data::DataLoaderOptions().batch_size(32).workers(4));
```

## Serialization

### How do I save and load model weights?

**Problem**: You want to save trained model weights and load them later.

**Fix**: Use `torch::save()` and `torch::load()`:

```
// Saving
torch::save(model, "model.pt");

// Loading
torch::load(model, "model.pt");
```

For saving only specific tensors or state:

```
torch::serialize::OutputArchive archive;
model->save(archive);
archive.save_to("model_weights.pt");

// Loading
torch::serialize::InputArchive archive;
archive.load_from("model_weights.pt");
model->load(archive);
```

## Build and Compilation

### CMake cannot find Torch

**Problem**: When building your project with CMake, you get an error that
`Torch` package cannot be found.

**Fix**: You need to specify the path to the LibTorch installation using
`CMAKE_PREFIX_PATH`:

```
cmake -DCMAKE_PREFIX_PATH=/path/to/libtorch ..
```

Alternatively, set `Torch_DIR` to point to the directory containing
`TorchConfig.cmake`:

```
cmake -DTorch_DIR=/path/to/libtorch/share/cmake/Torch ..
```

### Linker errors with undefined references

**Problem**: Your project compiles but you get linker errors with undefined
references to PyTorch symbols.

**Fix**: Ensure you're linking against all required libraries in your
`CMakeLists.txt`:

```
find_package(Torch REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app "${TORCH_LIBRARIES}")
```

Also ensure that the compiler flags are set correctly:

```
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${TORCH_CXX_FLAGS}")
```

---

# The C++ Frontend

The PyTorch C++ frontend is a C++17 library for CPU and GPU
tensor computation, with automatic differentiation and high level building
blocks for state of the art machine learning applications.

## Description

The PyTorch C++ frontend can be thought of as a C++ version of the
PyTorch Python frontend, providing automatic differentiation and various higher
level abstractions for machine learning and neural networks. Specifically,
it consists of the following components:

| Component | Description |
| --- | --- |
| `torch::Tensor` | Automatically differentiable, efficient CPU and GPU enabled tensors |
| `torch::nn` | A collection of composable modules for neural network modeling |
| `torch::optim` | Optimization algorithms like SGD, Adam or RMSprop to train your models |
| `torch::data` | Datasets, data pipelines and multi-threaded, asynchronous data loader |
| `torch::serialize` | A serialization API for storing and loading model checkpoints |
| `torch::python` | Glue to bind your C++ models into Python |
| `torch::jit` | Pure C++ access to the TorchScript JIT compiler |

## End-to-end example

Here is a simple, end-to-end example of defining and training a simple
neural network on the MNIST dataset:

```
#include <torch/torch.h>

// Define a new Module.
struct Net : torch::nn::Module {
 Net() {
 // Construct and register two Linear submodules.
 fc1 = register_module("fc1", torch::nn::Linear(784, 64));
 fc2 = register_module("fc2", torch::nn::Linear(64, 32));
 fc3 = register_module("fc3", torch::nn::Linear(32, 10));
 }

 // Implement the Net's algorithm.
 torch::Tensor forward(torch::Tensor x) {
 // Use one of many tensor manipulation functions.
 x = torch::relu(fc1->forward(x.reshape({x.size(0), 784})));
 x = torch::dropout(x, /*p=*/0.5, /*train=*/is_training());
 x = torch::relu(fc2->forward(x));
 x = torch::log_softmax(fc3->forward(x), /*dim=*/1);
 return x;
 }

 // Use one of many "standard library" modules.
 torch::nn::Linear fc1{nullptr}, fc2{nullptr}, fc3{nullptr};
};

int main() {
 // Create a new Net.
 auto net = std::make_shared<Net>();

 // Create a multi-threaded data loader for the MNIST dataset.
 auto data_loader = torch::data::make_data_loader(
 torch::data::datasets::MNIST("./data").map(
 torch::data::transforms::Stack<>()),
 /*batch_size=*/64);

 // Instantiate an SGD optimization algorithm to update our Net's parameters.
 torch::optim::SGD optimizer(net->parameters(), /*lr=*/0.01);

 for (size_t epoch = 1; epoch <= 10; ++epoch) {
 size_t batch_index = 0;
 // Iterate the data loader to yield batches from the dataset.
 for (auto& batch : *data_loader) {
 // Reset gradients.
 optimizer.zero_grad();
 // Execute the model on the input data.
 torch::Tensor prediction = net->forward(batch.data);
 // Compute a loss value to judge the prediction of our model.
 torch::Tensor loss = torch::nll_loss(prediction, batch.target);
 // Compute gradients of the loss w.r.t. the parameters of our model.
 loss.backward();
 // Update the parameters based on the calculated gradients.
 optimizer.step();
 // Output the loss and checkpoint every 100 batches.
 if (++batch_index % 100 == 0) {
 std::cout << "Epoch: " << epoch << " | Batch: " << batch_index
 << " | Loss: " << loss.item<float>() << std::endl;
 // Serialize your model periodically as a checkpoint.
 torch::save(net, "net.pt");
 }
 }
 }
}
```

To see more complete examples of using the PyTorch C++ frontend, see [the example repository](https://github.com/pytorch/examples/tree/master/cpp).

## Philosophy

PyTorch's C++ frontend was designed with the idea that the Python frontend is
great, and should be used when possible; but in some settings, performance and
portability requirements make the use of the Python interpreter infeasible. For
example, Python is a poor choice for low latency, high performance or
multithreaded environments, such as video games or production servers. The
goal of the C++ frontend is to address these use cases, while not sacrificing
the user experience of the Python frontend.

As such, the C++ frontend has been written with a few philosophical goals in mind:

- **Closely model the Python frontend in its design**, naming, conventions and
functionality. While there may be occasional differences between the two
frontends (e.g., where we have dropped deprecated features or fixed "warts"
in the Python frontend), we guarantee that the effort in porting a Python model
to C++ should lie exclusively in **translating language features**,
not modifying functionality or behavior.
- **Prioritize flexibility and user-friendliness over micro-optimization.**
In C++, you can often get optimal code, but at the cost of an extremely
unfriendly user experience. Flexibility and dynamism is at the heart of
PyTorch, and the C++ frontend seeks to preserve this experience, in some
cases sacrificing performance (or "hiding" performance knobs) to keep APIs
simple and explicable. We want researchers who don't write C++ for a living
to be able to use our APIs.

A word of warning: Python is not necessarily slower than
C++! The Python frontend calls into C++ for almost anything computationally expensive
(especially any kind of numeric operation), and these operations will take up
the bulk of time spent in a program. If you would prefer to write Python,
and can afford to write Python, we recommend using the Python interface to
PyTorch. However, if you would prefer to write C++, or need to write C++
(because of multithreading, latency or deployment requirements), the
C++ frontend to PyTorch provides an API that is approximately as convenient,
flexible, friendly and intuitive as its Python counterpart. The two frontends
serve different use cases, work hand in hand, and neither is meant to
unconditionally replace the other.

## Installation

Instructions on how to install the C++ frontend library distribution, including
an example for how to build a minimal application depending on LibTorch, may be
found by following [this](https://pytorch.org/cppdocs/installing.html) link.

---

# PyTorch C++ API

These pages provide the documentation for the public portions of the PyTorch C++
API. This API can roughly be divided into five parts:

- **ATen**: The foundational tensor and mathematical operation library on which all else is built.
- **Autograd**: Augments ATen with automatic differentiation.
- **C++ Frontend**: High level constructs for training and evaluation of machine learning models.
- **TorchScript**: An interface to the TorchScript JIT compiler and interpreter.
- **C++ Extensions**: A means of extending the Python API with custom C++ and CUDA routines.

Combined, these building blocks form a research and
production ready C++ library for tensor computation and dynamic neural
networks with strong emphasis on GPU acceleration as well as fast CPU
performance. It is currently in use at Facebook in research and
production; we are looking forward to welcoming more users of the PyTorch C++ API.

Warning

At the moment, the C++ API should be considered "beta" stability; we may
make major breaking changes to the backend in order to improve the API,
or in service of providing the Python interface to PyTorch, which is our
most stable and best supported interface.

## ATen

ATen is fundamentally a tensor library, on top of which almost all other Python
and C++ interfaces in PyTorch are built. It provides a core `Tensor` class,
on which many hundreds of operations are defined. Most of these operations have
both CPU and GPU implementations, to which the `Tensor` class will
dynamically dispatch based on its type. A small example of using ATen could
look as follows:

```
#include <ATen/ATen.h>

at::Tensor a = at::ones({2, 2}, at::kInt);
at::Tensor b = at::randn({2, 2});
auto c = a + b.to(at::kInt);
```

This `Tensor` class and all other symbols in ATen are found in the `at::`
namespace, documented
[here](https://pytorch.org/cppdocs/api/namespace_at.html#namespace-at).

## Autograd

What we term *autograd* are the portions of PyTorch's C++ API that augment the
ATen `Tensor` class with capabilities concerning automatic differentiation.
The autograd system records operations on tensors to form an *autograd graph*.
Calling `backwards()` on a leaf variable in this graph performs reverse mode
differentiation through the network of functions and tensors spanning the
autograd graph, ultimately yielding gradients. The following example provides
a taste of this interface:

```
#include <torch/csrc/autograd/variable.h>
#include <torch/csrc/autograd/function.h>

torch::Tensor a = torch::ones({2, 2}, torch::requires_grad());
torch::Tensor b = torch::randn({2, 2});
auto c = a + b;
c.backward(); // a.grad() will now hold the gradient of c w.r.t. a.
```

The `at::Tensor` class in ATen is not differentiable by default. To add the
differentiability of tensors the autograd API provides, you must use tensor
factory functions from the `torch::` namespace instead of the `at::` namespace.
For example, while a tensor created with `at::ones` will not be differentiable,
a tensor created with `torch::ones` will be.

## C++ Frontend

The PyTorch C++ frontend provides a high level, pure C++ modeling interface for
neural networks and general ML (Machine Learning) research and production use cases,
largely following the Python API in design and provided functionality. The C++
frontend includes the following:

- An interface for defining machine learning models through a hierarchical module system (like `torch.nn.Module`);
- A "standard library" of pre-existing modules for the most common modeling purposes (e.g. convolutions, RNNs, batch normalization etc.);
- An optimization API, including implementations of popular optimizers such as SGD, Adam, RMSprop and others;
- A means of representing datasets and data pipelines, including functionality to load data in parallel over many CPU cores;
- A serialization format for storing and loading checkpoints of a training session (like `torch.utils.data.DataLoader`);
- Automatic parallelization of models onto multiple GPUs (like `torch.nn.parallel.DataParallel`);
- Support code to easily bind C++ models into Python using pybind11;
- Entry points to the TorchScript JIT compiler;
- Helpful utilities to facilitate interfacing with the ATen and Autograd APIs.

See [this document](https://pytorch.org/cppdocs/frontend.html) for a more
detailed description of the C++ frontend. Relevant sections of the `torch::`
namespace related to the C++ Frontend include [torch::nn](https://pytorch.org/cppdocs/api/namespace_torch__nn.html#namespace-torch-nn),
[torch::optim](https://pytorch.org/cppdocs/api/namespace_torch__optim.html#namespace-torch-optim),
[torch::data](https://pytorch.org/cppdocs/api/namespace_torch__data.html#namespace-torch-data),
[torch::serialize](https://docs.pytorch.org/cppdocs/api/serialize/index.html),
[torch::jit](https://pytorch.org/cppdocs/api/namespace_torch__jit.html#namespace-torch-jit)
and `torch::python`.
Examples of the C++ frontend can be found in [this repository](https://github.com/pytorch/examples/tree/master/cpp) which is being
expanded on a continuous and active basis.

Note

Unless you have a particular reason to constrain yourself exclusively to ATen
or the Autograd API, the C++ frontend is the recommended entry point to the
PyTorch C++ ecosystem. While it is still in beta as we collect user feedback
(from you!), it provides both more functionality and better stability
guarantees than the ATen and Autograd APIs.

## TorchScript

TorchScript is a representation of a PyTorch model that can be understood,
compiled and serialized by the TorchScript compiler. Fundamentally, TorchScript
is a programming language in its own right. It is a subset of Python using
the PyTorch API. The C++ interface to TorchScript encompasses three primary pieces of
functionality:

- A mechanism for loading and executing serialized TorchScript models defined in Python;
- An API for defining custom operators that extend the TorchScript standard library of operations;
- Just-in-time compilation of TorchScript programs from C++.

The first mechanism may be of great interest to you if you would like to define
your models in Python as much as possible, but subsequently export them to C++
for production environments and no-Python inference. You can find out more
about this by following [this](https://pytorch.org/tutorials/advanced/cpp_export.html) link. The second
API concerns itself with scenarios in which you would like to extend
TorchScript with custom operators, which can similarly be serialized and
invoked from C++ during inference. Lastly, the `torch::jit::compile`
function may be used to access the TorchScript compiler directly from C++.

## C++ Extensions

*C++ Extensions* offer a simple yet powerful way of accessing all of the above
interfaces for the purpose of extending regular Python use-cases of PyTorch.
C++ extensions are most commonly used to implement custom operators in C++ or
CUDA to accelerate research in vanilla PyTorch setups. The C++ extension API
does not add any new functionality to the PyTorch C++ API. Instead, it
provides integration with Python setuptools as well as JIT compilation
mechanisms that allow access to ATen, the autograd and other C++ APIs from
Python. To learn more about the C++ extension API, go through
[this tutorial](https://pytorch.org/tutorials/advanced/cpp_extension.html).

## Contents

- [Installing C++ Distributions of PyTorch](installing.html)

- [Minimal Example](installing.html#minimal-example)
- [System Requirements](installing.html#system-requirements)
- [Visual Studio Extension](installing.html#visual-studio-extension)
- [Support](installing.html#support)
- [The C++ Frontend](frontend.html)

- [Description](frontend.html#description)
- [End-to-end example](frontend.html#end-to-end-example)
- [Philosophy](frontend.html#philosophy)
- [Installation](frontend.html#installation)
- [C++ API Reference](api/index.html)

- [ATen: Tensor Library](api/aten/index.html)
- [C10: Core Utilities](api/c10/index.html)
- [Autograd: Automatic Differentiation](api/autograd/index.html)
- [CUDA Support](api/cuda/index.html)
- [XPU Support](api/xpu/index.html)
- [Neural Network Modules (torch::nn)](api/nn/index.html)
- [Optimizers (torch::optim)](api/optim/index.html)
- [Data Loading (torch::data)](api/data/index.html)
- [Serialization (torch::serialize)](api/serialize/index.html)
- [Torch Library API](api/library/index.html)
- [Torch Stable API](api/stable/index.html)
- [FAQ](faq.html)

- [C++ Extensions](faq.html#c-extensions)
- [LibTorch](faq.html#libtorch)
- [Neural Network Modules](faq.html#neural-network-modules)
- [Data Loading](faq.html#data-loading)
- [Serialization](faq.html#serialization)
- [Build and Compilation](faq.html#build-and-compilation)

# Indices and tables

- [Index](genindex.html)
- [Module Index](py-modindex.html)
- [Search Page](search.html)

## Acknowledgements

This documentation website for the PyTorch C++ universe uses the Sphinx
C++ domain for API documentation.

---

# Installing C++ Distributions of PyTorch

We provide binary distributions of all headers, libraries and CMake
configuration files required to depend on PyTorch. We call this distribution
*LibTorch*, and you can download ZIP archives containing the latest LibTorch
distribution on [our website](https://pytorch.org/get-started/locally/). Below
is a small example of writing a minimal application that depends on LibTorch
and uses the `torch::Tensor` class which comes with the PyTorch C++ API.

## Minimal Example

The first step is to download the LibTorch ZIP archive via the link above. For
example:

```
wget https://download.pytorch.org/libtorch/nightly/cpu/libtorch-shared-with-deps-latest.zip
unzip libtorch-shared-with-deps-latest.zip
```

Note that the above link has CPU-only libtorch. If you would like to download a GPU-enabled
libtorch, find the right link in the link selector on https://pytorch.org

If you're a Windows developer and wouldn't like to use CMake, you could jump to the Visual Studio
Extension section.

Next, we can write a minimal CMake build configuration to develop a small
application that depends on LibTorch. CMake is not a hard requirement for using
LibTorch, but it is the recommended and blessed build system and will be well
supported into the future. A most basic `CMakeLists.txt` file could look like
this:

```
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
project(example-app)

find_package(Torch REQUIRED)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${TORCH_CXX_FLAGS}")

add_executable(example-app example-app.cpp)
target_link_libraries(example-app "${TORCH_LIBRARIES}")

# The following code block is suggested to be used on Windows.
# According to https://github.com/pytorch/pytorch/issues/25457,
# the DLLs need to be copied to avoid memory errors.
if (MSVC)
 file(GLOB TORCH_DLLS "${TORCH_INSTALL_PREFIX}/lib/*.dll")
 add_custom_command(TARGET example-app
 POST_BUILD
 COMMAND ${CMAKE_COMMAND} -E copy_if_different
 ${TORCH_DLLS}
 $<TARGET_FILE_DIR:example-app>)
endif (MSVC)
```

The implementation of our example will simply create a new `torch::Tensor` and
print it:

```
#include <torch/torch.h>
#include <iostream>

int main() {
 torch::Tensor tensor = torch::rand({2, 3});
 std::cout << tensor << std::endl;
}
```

While there are more fine-grained headers you can include to access only parts
of the PyTorch C++ API, including `torch/torch.h` is the most sure-proof way of
including most of its functionality.

The last step is to build the application. For this, assume our example
directory is laid out like this:

```
example-app/
 CMakeLists.txt
 example-app.cpp
```

We can now run the following commands to build the application from within the
`example-app/` folder:

```
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=/absolute/path/to/libtorch ..
cmake --build . --config Release
```

where `/absolute/path/to/libtorch` should be the absolute (!) path to the unzipped LibTorch
distribution. If PyTorch was installed via pip, `CMAKE_PREFIX_PATH` can be queried
using `torch.utils.cmake_prefix_path` variable. In that case CMake configuration step would look something like follows:

```
cmake -DCMAKE_PREFIX_PATH=`python3 -c 'import torch;print(torch.utils.cmake_prefix_path)'` ..
```

If all goes well, it will look something like this:

```
root@4b5a67132e81:/example-app# mkdir build
root@4b5a67132e81:/example-app# cd build
root@4b5a67132e81:/example-app/build# cmake -DCMAKE_PREFIX_PATH=/path/to/libtorch ..
-- The C compiler identification is GNU 5.4.0
-- The CXX compiler identification is GNU 5.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Looking for pthread.h
-- Looking for pthread.h - found
-- Looking for pthread_create
-- Looking for pthread_create - not found
-- Looking for pthread_create in pthreads
-- Looking for pthread_create in pthreads - not found
-- Looking for pthread_create in pthread
-- Looking for pthread_create in pthread - found
-- Found Threads: TRUE
-- Configuring done
-- Generating done
-- Build files have been written to: /example-app/build
root@4b5a67132e81:/example-app/build# cmake --build . --config Release
Scanning dependencies of target example-app
[ 50%] Building CXX object CMakeFiles/example-app.dir/example-app.cpp.o
[100%] Linking CXX executable example-app
[100%] Built target example-app
```

Executing the resulting `example-app` binary found in the `build` folder
should now merrily print the tensor (exact output subject to randomness):

```
root@4b5a67132e81:/example-app/build# ./example-app
0.2063 0.6593 0.0866
0.0796 0.5841 0.1569
[ Variable[CPUFloatType]{2,3} ]
```

Tip

On Windows, debug and release builds are not ABI-compatible. If you plan to
build your project in debug mode, please try the debug version of LibTorch.
Also, make sure you specify the correct configuration in the `cmake --build .`
line above.

## System Requirements

To ensure smooth installation and usage of LibTorch, please ensure your system
meets the following requirements:

1. **GLIBC Version**:

- GLIBC 2.29 or newer for cxx11 ABI version
2. **GCC Version**:

- GCC 9 or newer for cxx11

## Visual Studio Extension

[LibTorch Project Template](https://marketplace.visualstudio.com/items?itemName=YiZhang.LibTorch001) can help Windows developers
set all libtorch project settings and link options for debug and release.
It's easy to use and you could check out the [demo video](https://ossci-windows.s3.us-east-1.amazonaws.com/vsextension/demo.mp4).
The only prerequisite is to download the libtorch on https://pytorch.org

## Support

If you run into any troubles with this installation and minimal usage guide,
please use our [forum](https://discuss.pytorch.org/) or [GitHub issues](https://github.com/pytorch/pytorch/issues) to get in touch.