快捷方式

torch.testing

torch.testing.assert_close(actual, expected, *, allow_subclasses=True, rtol=None, atol=None, equal_nan=False, check_device=True, check_dtype=True, check_layout=True, check_stride=False, msg=None)[source]

断言 actualexpected 接近。

如果 actualexpected 是带步幅的、非量化的、实值的且有限的,则如果它们满足以下条件,则被认为是接近的

actualexpectedatol+rtolexpected\lvert \text{actual} - \text{expected} \rvert \le \texttt{atol} + \texttt{rtol} \cdot \lvert \text{expected} \rvert

非有限值 (-infinf) 仅当且仅当它们相等时才被认为是接近的。 NaN 仅当 equal_nanTrue 时才被认为彼此相等。

此外,只有当它们具有相同的

  • device(如果 check_deviceTrue),

  • dtype(如果 check_dtypeTrue),

  • layout(如果 check_layoutTrue),以及

  • 步幅(如果 check_strideTrue)。

如果 actualexpected 是元张量,则只执行属性检查。

如果 actualexpected 是稀疏的(具有 COO、CSR、CSC、BSR 或 BSC 布局),则分别检查它们的步长成员。索引,即 indices 用于 COO,crow_indicescol_indices 用于 CSR 和 BSR,或者 ccol_indicesrow_indices 用于 CSC 和 BSC 布局,始终检查是否相等,而值根据上面的定义检查是否接近。

如果 actualexpected 是量化的,如果它们具有相同的 qscheme() 并且 dequantize() 的结果根据上面的定义是接近的,则它们被认为是接近的。

actualexpected 可以是 Tensor 或任何可以用 torch.as_tensor() 构造 torch.Tensor 的张量或标量类。除了 Python 标量外,输入类型必须直接相关。此外,actualexpected 可以是 SequenceMapping,在这种情况下,如果它们的结构匹配并且根据上述定义,它们的所有元素都被认为是接近的,则它们被认为是接近的。

注意

Python 标量是类型关系要求的例外,因为它们的 type(),即 intfloatcomplex 等效于类张量的 dtype。因此,可以检查不同类型的 Python 标量,但需要 check_dtype=False

参数
  • actual (Any) – 实际输入。

  • expected (Any) – 预期输入。

  • allow_subclasses (bool) – 如果为 True(默认)并且除了 Python 标量外,允许直接相关类型的输入。否则需要类型相等。

  • rtol (Optional[float]) – 相对容差。如果指定 atol,则也必须指定。如果省略,则根据 dtype 选择默认值,如下表所示。

  • atol (Optional[float]) – 绝对容差。如果指定 rtol,则也必须指定。如果省略,则根据 dtype 选择默认值,如下表所示。

  • equal_nan (Union[bool, str]) – 如果为 True,则两个 NaN 值将被视为相等。

  • check_device (bool) – 如果为 True(默认),则断言相应的张量位于相同的 device 上。如果禁用此检查,则在比较之前,将位于不同 device 上的张量移动到 CPU。

  • check_dtype (bool) – 如果为 True(默认),则断言相应的张量具有相同的 dtype。如果禁用此检查,则在比较之前,将具有不同 dtype 的张量提升为通用 dtype(根据 torch.promote_types())。

  • check_layout (bool) – 如果为 True(默认),则断言相应的张量具有相同的 layout。如果禁用此检查,则在比较之前,将具有不同 layout 的张量转换为步长张量。

  • check_stride (bool) – 如果为 True 并且相应的张量是步长的,则断言它们具有相同的步长。

  • msg (Optional[Union[str, Callable[[str], str]]]) – 比较失败时使用的可选错误消息。也可以作为可调用函数传递,在这种情况下,它将使用生成的 message 调用,并且应该返回新的 message。

引发

下表显示了不同 dtype 的默认 rtolatol。如果 dtype 不匹配,则使用两种容差的最大值。

dtype

rtol

atol

float16

1e-3

1e-5

bfloat16

1.6e-2

1e-5

float32

1.3e-6

1e-5

float64

1e-7

1e-7

complex32

1e-3

1e-5

complex64

1.3e-6

1e-5

complex128

1e-7

1e-7

quint8

1.3e-6

1e-5

quint2x4

1.3e-6

1e-5

quint4x2

1.3e-6

1e-5

qint8

1.3e-6

1e-5

qint32

1.3e-6

1e-5

其他

0.0

0.0

注意

assert_close() 在默认情况下高度可配置,并具有严格的设置。鼓励用户使用 partial() 来适应他们的用例。例如,如果需要进行相等性检查,可以使用 assert_equal,默认情况下,它对所有 dtype 使用零容差。

>>> import functools
>>> assert_equal = functools.partial(torch.testing.assert_close, rtol=0, atol=0)
>>> assert_equal(1e-9, 1e-10)
Traceback (most recent call last):
...
AssertionError: Scalars are not equal!

Expected 1e-10 but got 1e-09.
Absolute difference: 9.000000000000001e-10
Relative difference: 9.0

示例

>>> # tensor to tensor comparison
>>> expected = torch.tensor([1e0, 1e-1, 1e-2])
>>> actual = torch.acos(torch.cos(expected))
>>> torch.testing.assert_close(actual, expected)
>>> # scalar to scalar comparison
>>> import math
>>> expected = math.sqrt(2.0)
>>> actual = 2.0 / math.sqrt(2.0)
>>> torch.testing.assert_close(actual, expected)
>>> # numpy array to numpy array comparison
>>> import numpy as np
>>> expected = np.array([1e0, 1e-1, 1e-2])
>>> actual = np.arccos(np.cos(expected))
>>> torch.testing.assert_close(actual, expected)
>>> # sequence to sequence comparison
>>> import numpy as np
>>> # The types of the sequences do not have to match. They only have to have the same
>>> # length and their elements have to match.
>>> expected = [torch.tensor([1.0]), 2.0, np.array(3.0)]
>>> actual = tuple(expected)
>>> torch.testing.assert_close(actual, expected)
>>> # mapping to mapping comparison
>>> from collections import OrderedDict
>>> import numpy as np
>>> foo = torch.tensor(1.0)
>>> bar = 2.0
>>> baz = np.array(3.0)
>>> # The types and a possible ordering of mappings do not have to match. They only
>>> # have to have the same set of keys and their elements have to match.
>>> expected = OrderedDict([("foo", foo), ("bar", bar), ("baz", baz)])
>>> actual = {"baz": baz, "bar": bar, "foo": foo}
>>> torch.testing.assert_close(actual, expected)
>>> expected = torch.tensor([1.0, 2.0, 3.0])
>>> actual = expected.clone()
>>> # By default, directly related instances can be compared
>>> torch.testing.assert_close(torch.nn.Parameter(actual), expected)
>>> # This check can be made more strict with allow_subclasses=False
>>> torch.testing.assert_close(
...     torch.nn.Parameter(actual), expected, allow_subclasses=False
... )
Traceback (most recent call last):
...
TypeError: No comparison pair was able to handle inputs of type
<class 'torch.nn.parameter.Parameter'> and <class 'torch.Tensor'>.
>>> # If the inputs are not directly related, they are never considered close
>>> torch.testing.assert_close(actual.numpy(), expected)
Traceback (most recent call last):
...
TypeError: No comparison pair was able to handle inputs of type <class 'numpy.ndarray'>
and <class 'torch.Tensor'>.
>>> # Exceptions to these rules are Python scalars. They can be checked regardless of
>>> # their type if check_dtype=False.
>>> torch.testing.assert_close(1.0, 1, check_dtype=False)
>>> # NaN != NaN by default.
>>> expected = torch.tensor(float("Nan"))
>>> actual = expected.clone()
>>> torch.testing.assert_close(actual, expected)
Traceback (most recent call last):
...
AssertionError: Scalars are not close!

Expected nan but got nan.
Absolute difference: nan (up to 1e-05 allowed)
Relative difference: nan (up to 1.3e-06 allowed)
>>> torch.testing.assert_close(actual, expected, equal_nan=True)
>>> expected = torch.tensor([1.0, 2.0, 3.0])
>>> actual = torch.tensor([1.0, 4.0, 5.0])
>>> # The default error message can be overwritten.
>>> torch.testing.assert_close(actual, expected, msg="Argh, the tensors are not close!")
Traceback (most recent call last):
...
AssertionError: Argh, the tensors are not close!
>>> # If msg is a callable, it can be used to augment the generated message with
>>> # extra information
>>> torch.testing.assert_close(
...     actual, expected, msg=lambda msg: f"Header\n\n{msg}\n\nFooter"
... )
Traceback (most recent call last):
...
AssertionError: Header

Tensor-likes are not close!

Mismatched elements: 2 / 3 (66.7%)
Greatest absolute difference: 2.0 at index (1,) (up to 1e-05 allowed)
Greatest relative difference: 1.0 at index (1,) (up to 1.3e-06 allowed)

Footer
torch.testing.make_tensor(*shape, dtype, device, low=None, high=None, requires_grad=False, noncontiguous=False, exclude_zero=False, memory_format=None)[source]

创建一个具有给定 shapedevicedtype 的张量,并用从 [low, high) 范围内均匀采样的值填充。

如果指定了 lowhigh,并且它们超出了 dtype 可表示的有限值的范围,那么它们将分别被钳制到可表示的最小或最大有限值。如果为 None,则下表描述了 lowhigh 的默认值,它们取决于 dtype

dtype

low

high

布尔类型

0

2

无符号整数类型

0

10

有符号整数类型

-9

10

浮点类型

-9

9

复数类型

-9

9

参数
  • shape (Tuple[int, ...]) – 单个整数或一系列定义输出张量形状的整数。

  • dtype (torch.dtype) – 返回张量的数据类型。

  • device (Union[str, torch.device]) – 返回张量的设备。

  • low (Optional[Number]) – 设置给定范围的下限(包括)。如果提供数字,它将被钳制到给定 dtype 的最小可表示有限值。当为 None(默认)时,该值将根据 dtype 确定(参见上表)。默认值:None

  • high (Optional[Number]) –

    设置给定范围的上限(不包括)。如果提供数字,它将被钳制到给定 dtype 的最大可表示有限值。当为 None(默认)时,该值将根据 dtype 确定(参见上表)。默认值:None

    自版本 2.1 起已弃用: 从 2.1 开始,为浮点或复数类型将 low==high 传递给 make_tensor() 已被弃用,并将在 2.3 中删除。请改用 torch.full()

  • requires_grad (Optional[bool]) – 如果应在返回的张量上记录 autograd 操作。默认值:False

  • noncontiguous (Optional[bool]) – 如果为 True,则返回的张量将是非连续的。如果构建的张量元素少于两个,则忽略此参数。与 memory_format 互斥。

  • exclude_zero (Optional[bool]) – 如果为 True,则将零替换为取决于 dtype 的 dtype 的小正值。对于布尔值和整数类型,零将被替换为一。对于浮点类型,它将被替换为 dtype 的最小正规数(dtype 的 finfo() 对象的“微小”值),对于复数类型,它将被替换为一个实部和虚部都是复数类型可表示的最小正规数的复数。默认值 False

  • memory_format (Optional[torch.memory_format]) – 返回张量的内存格式。与 noncontiguous 互斥。

引发
  • ValueError – 如果为整数 dtype 传递了 requires_grad=True

  • ValueError – 如果 low >= high

  • ValueError – 如果 lowhighnan

  • ValueError – 如果同时传递了 noncontiguousmemory_format

  • TypeError – 如果 dtype 不受此函数支持。

返回类型

张量

示例

>>> from torch.testing import make_tensor
>>> # Creates a float tensor with values in [-1, 1)
>>> make_tensor((3,), device='cpu', dtype=torch.float32, low=-1, high=1)
tensor([ 0.1205, 0.2282, -0.6380])
>>> # Creates a bool tensor on CUDA
>>> make_tensor((2, 2), device='cuda', dtype=torch.bool)
tensor([[False, False],
        [False, True]], device='cuda:0')
torch.testing.assert_allclose(actual, expected, rtol=None, atol=None, equal_nan=True, msg='')[source]

警告

torch.testing.assert_allclose()1.12 起已弃用,并将在未来版本中删除。请改用 torch.testing.assert_close()。您可以在 此处 找到详细的升级说明。

文档

访问 PyTorch 的全面的开发人员文档

查看文档

教程

获取针对初学者和高级开发人员的深入教程

查看教程

资源

查找开发资源并获得问题的解答

查看资源