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]¶
断言
actual
和expected
接近。如果
actual
和expected
是带步幅的、非量化的、实值的且有限的,则如果它们满足以下条件,则被认为是接近的非有限值 (
-inf
和inf
) 仅当且仅当它们相等时才被认为是接近的。NaN
仅当equal_nan
为True
时才被认为彼此相等。此外,只有当它们具有相同的
device
(如果check_device
为True
),dtype
(如果check_dtype
为True
),layout
(如果check_layout
为True
),以及步幅(如果
check_stride
为True
)。
如果
actual
或expected
是元张量,则只执行属性检查。如果
actual
和expected
是稀疏的(具有 COO、CSR、CSC、BSR 或 BSC 布局),则分别检查它们的步长成员。索引,即indices
用于 COO,crow_indices
和col_indices
用于 CSR 和 BSR,或者ccol_indices
和row_indices
用于 CSC 和 BSC 布局,始终检查是否相等,而值根据上面的定义检查是否接近。如果
actual
和expected
是量化的,如果它们具有相同的qscheme()
并且dequantize()
的结果根据上面的定义是接近的,则它们被认为是接近的。actual
和expected
可以是Tensor
或任何可以用torch.as_tensor()
构造torch.Tensor
的张量或标量类。除了 Python 标量外,输入类型必须直接相关。此外,actual
和expected
可以是Sequence
或Mapping
,在这种情况下,如果它们的结构匹配并且根据上述定义,它们的所有元素都被认为是接近的,则它们被认为是接近的。注意
Python 标量是类型关系要求的例外,因为它们的
type()
,即int
、float
和complex
等效于类张量的dtype
。因此,可以检查不同类型的 Python 标量,但需要check_dtype=False
。- 参数
actual (Any) – 实际输入。
expected (Any) – 预期输入。
allow_subclasses (bool) – 如果为
True
(默认)并且除了 Python 标量外,允许直接相关类型的输入。否则需要类型相等。rtol (Optional[float]) – 相对容差。如果指定
atol
,则也必须指定。如果省略,则根据dtype
选择默认值,如下表所示。atol (Optional[float]) – 绝对容差。如果指定
rtol
,则也必须指定。如果省略,则根据dtype
选择默认值,如下表所示。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。
- 引发
ValueError – 如果无法从输入构造任何
torch.Tensor
。ValueError – 如果只指定
rtol
或atol
。AssertionError – 如果相应的输入不是 Python 标量并且不直接相关。
AssertionError – 如果
allow_subclasses
为False
,但相应的输入不是 Python 标量并且具有不同的类型。AssertionError – 如果输入是
Sequence
,但它们的长度不匹配。AssertionError – 如果输入是
Mapping
,但它们的键集不匹配。AssertionError – 如果相应的张量没有相同的
shape
。AssertionError – 如果
check_layout
为True
,但相应的张量没有相同的layout
。AssertionError – 如果相应的张量中只有一个是量化的。
AssertionError – 如果相应的张量是量化的,但具有不同的
qscheme()
。AssertionError – 如果
check_device
为True
,但相应的张量不在相同的device
上。AssertionError – 如果
check_dtype
为True
,但相应的张量没有相同的dtype
。AssertionError – 如果
check_stride
为True
,但相应的步长张量没有相同的步长。AssertionError – 如果相应张量的值根据上面的定义不接近。
下表显示了不同
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
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]¶
创建一个具有给定
shape
、device
和dtype
的张量,并用从[low, high)
范围内均匀采样的值填充。如果指定了
low
或high
,并且它们超出了dtype
可表示的有限值的范围,那么它们将分别被钳制到可表示的最小或最大有限值。如果为None
,则下表描述了low
和high
的默认值,它们取决于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 – 如果
low
或high
为nan
。ValueError – 如果同时传递了
noncontiguous
和memory_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()
。您可以在 此处 找到详细的升级说明。