Python PyTorch assert_close用法及代码示例

本文简要介绍python语言中 torch.testing.assert_close 的用法。

用法:

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

参数：

• actual(任何) -实际输入。

• expected(任何) -预期输入。

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

• rtol(可选的[float]) -相对容差。如果指定了atol，还必须指定。如果省略，则使用下表选择基于dtype 的默认值。

• atol(可选的[float]) -绝对的宽容。如果指定了rtol，还必须指定。如果省略，则使用下表选择基于dtype 的默认值。

• equal_nan(联盟[bool,str]) -如果 True ，两个 NaN 值将被视为相等。

• check_device(bool) -如果 True(默认)，则断言相应的张量在同一个 device 上。如果禁用此检查，则不同 device 上的张量会在比较之前移至 CPU。

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

• check_stride(bool) -如果 True 和相应的张量是跨步的，则断言它们具有相同的跨步。

• check_is_coalesced(bool) -如果 True(默认)和相应的张量是稀疏 COO，则检查 actual 和 expected 是否已合并或未合并。如果禁用此检查，则张量在比较之前会被 coalesce() 编辑。

• msg(可选的[联盟[str,可调用[[Tensor,Tensor,诊断],str]]]) - 如果相应张量的值不匹配，则使用可选的错误消息。可以作为 callable 传递，在这种情况下，它将使用不匹配的张量和关于不匹配的诊断名称空间来调用。详情见下文。

抛出：

• ValueError - 如果没有 torch.Tensor 可以从输入构造。

• ValueError - 如果仅指定 rtol 或 atol。

• AssertionError - 如果相应的输入不是 Python 标量并且不直接相关。

• AssertionError - 如果 allow_subclasses 是 False ，但相应的输入不是 Python 标量并且具有不同的类型。

• AssertionError - 如果输入是 Sequence 的，但它们的长度不匹配。

• AssertionError - 如果输入是 Mapping 的，但它们的键集不匹配。

• AssertionError - 如果相应的张量没有相同的 shape 。

• AssertionError - 如果相应的张量没有相同的 layout 。

• AssertionError - 如果相应的张量被量化，但具有不同的 qscheme() 。

• AssertionError - 如果 check_device 是 True ，但对应的张量不在同一个 device 上。

• AssertionError - 如果 check_dtype 是 True ，但对应的张量没有相同的 dtype 。

• AssertionError - 如果 check_stride 是 True ，但对应的跨步张量没有相同的跨度。

• AssertionError - 如果 check_is_coalesced 是 True ，但相应的稀疏 COO 张量既不是合并的也不是未合并的。

• AssertionError - 如果对应张量的值根据上面的定义不接近。

断言actual 和expected 接近。

如果 actual 和 expected 是跨步的、非量化的、实值的和有限的，则它们被认为是接近的，如果

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

并且它们具有相同的 device (如果 check_device 是 True )、相同的 dtype (如果 check_dtype 是 True )和相同的步幅(如果 check_stride 是 True )。非有限值(-inf 和 inf)仅当且仅当它们相等时才被视为接近。仅当 equal_nan 为 True 时，NaN 才被视为彼此相等。

如果 actual 和 expected 是稀疏的(具有 COO 或 CSR 布局)，则单独检查它们的跨步成员。索引，即 COO 的 indices 或 CSR 布局的 crow_indices 和 col_indices，始终检查是否相等，而根据上述定义检查值是否接近。仅当两者都合并或未合并时(如果 check_is_coalesced 为 True )，稀疏 COO 张量才被视为接近。

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

actual 和 expected 可以是 Tensor 或任何 tensor-or-scalar-likes，从中可以使用 torch.Tensor 构造 torch.as_tensor() 。除了 Python 标量，输入类型必须直接相关。此外，actual 和 expected 可以是 Sequence 或 Mapping 在这种情况下，如果它们的结构匹配并且根据上述定义，它们的所有元素都被认为是接近的，则它们被认为是接近的。

注意

Python 标量是类型关系要求的一个例外，因为它们的 type() ，即 int 、 float 和 complex 等价于 tensor-like 的 dtype。因此，可以检查不同类型的 Python 标量，但需要将 check_dtype 设置为 False 。

下表显示了不同 dtype 的默认 rtol 和 atol。如果 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
other	0.0	0.0

如果其可调用对象具有以下属性，则将传递给msg 的诊断名称空间：

• number_of_elements (int)：每个被比较的张量中的元素数。

• total_mismatches (int)：不匹配的总数。

• max_abs_diff (Union[int, float])：输入的最大绝对差。

• max_abs_diff_idx (Union[int, Tuple[int, ...]])：最大绝对差的索引。

• atol(浮点数)：允许的绝对公差。

• max_rel_diff (Union[int, float])：输入的最大相对差异。

• max_rel_diff_idx (Union[int, Tuple[int, ...]])：最大相对差异的索引。

• rtol(浮点数)：允许的相对公差。

对于max_abs_diff 和max_rel_diff，类型取决于输入的dtype。

注意

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!

Absolute difference: 8.999999703829253e-10
Relative difference: 8.999999583666371

例子

>>> # 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):
...
AssertionError: Except for Python scalars, type equality is required if
allow_subclasses=False, but got <class 'torch.nn.parameter.Parameter'> and
<class 'torch.Tensor'> instead.
>>> # If the inputs are not directly related, they are never considered close
>>> torch.testing.assert_close(actual.numpy(), expected)
Traceback (most recent call last):
...
AssertionError: Except for Python scalars, input types need to be directly
related, but got <class 'numpy.ndarray'> and <class 'torch.Tensor'> instead.
>>> # 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!

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 mismatch 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!
>>> # The error message can also created at runtime by passing a callable.
>>> def custom_msg(actual, expected, diagnostics):
...     ratio = diagnostics.total_mismatches / diagnostics.number_of_elements
...     return (
...         f"Argh, we found {diagnostics.total_mismatches} mismatches! "
...         f"That is {ratio:.1%}!"
...     )
>>> torch.testing.assert_close(actual, expected, msg=custom_msg)
Traceback (most recent call last):
...
AssertionError: Argh, we found 2 mismatches! That is 66.7%!