What you can generate and how

hypothesis-torch tries to make most things easy to generate while also allowing the user to customize strategies.

In absense of another justification, hypothesis-torch will generally default to generating the widest possible set of valid objects for a strategy. This means that, for example, tensor_strategy (unless configured otherwise) will often generate examples with less common layouts (such as sparse tensors) or memory formats (like channels last). For many use cases, these are too broad, and can be configured to be more specific.

This document is a reference for the strategies that hypothesis-torch provides, and how to use them.

Strategies

Hypothesis strategies for various Pytorch structures (including tensors and modules).

Hypothesis is a powerful property-based testing library for Python. It lacks built-in support for Pytorch tensors and modules, so this library provides strategies for generating them.

device_strategy(*, devices=None, allow_meta_device=False)

Strategy for generating torch devices.

Parameters:

Name	Type	Description	Default
devices	Sequence[device] | None	A sequence of devices to sample from. If None, all available devices are sampled.	None
allow_meta_device	bool	Whether to allow the meta device.	False

Returns:

Type	Description
SearchStrategy[device]	A strategy for generating torch devices.

dtype_strategy(dtypes=None)

Strategy for generating torch dtypes.

Parameters:

Name	Type	Description	Default
dtypes	Sequence[dtype] | None	A strategy for generating elements of the dtype. If None, all dtypes are sampled.	None

Returns:

Type	Description
SearchStrategy[dtype]	A strategy for generating torch dtypes.

layout_strategy(accepted_layouts=None)

Strategy for generating torch layouts.

Parameters:

Name	Type	Description	Default
accepted_layouts	Sequence[layout] | None	A sequence of layouts to sample from. If None, all supported layouts are sampled.	None

linear_network_strategy(draw, input_shape, output_shape, activation_layer, hidden_layer_size, num_hidden_layers, device)

Strategy for generating random Torch sequential networks of linear layers with activation functions.

Parameters:

Name	Type	Description	Default
draw	DrawFn	The draw function provided by hypothesis.	required
input_shape	tuple[int, ...] | Size | SearchStrategy[tuple[int, ...]] | SearchStrategy[Size]	The shape of the input tensor. If a strategy is provided, it will be drawn from.	required
output_shape	tuple[int, ...] | Size | SearchStrategy[tuple[int, ...]] | SearchStrategy[Size]	The shape of the output tensor. If a strategy is provided, it will be drawn from.	required
activation_layer	Module | SearchStrategy[Module]	Activation layer to use. If a strategy is provided, it will be drawn from.	required
hidden_layer_size	int | SearchStrategy[int]	The size of the hidden layers. If a strategy is provided, it will be drawn from.	required
num_hidden_layers	int | SearchStrategy[int]	The maximum depth of the network. If a strategy is provided, it will be drawn from.	required
device	device | SearchStrategy[device]	The device on which to place the network. If a strategy is provided, it will be drawn from.	required

Returns:

Type	Description
Module	A strategy for generating random linear networks.

memory_format_strategy(accepted_formats=None)

Strategy for generating torch layouts.

Parameters:

Name	Type	Description	Default
accepted_formats	Sequence[memory_format] | None	A sequence of layouts to sample from. If None, all supported layouts are sampled.	None

optimizer_strategy(draw, optimizer_type=None, **kwargs)

Strategy for generating torch optimizers.

Parameters:

Name	Type	Description	Default
draw	DrawFn	The draw function provided by hypothesis.	required
optimizer_type	type[Optimizer] | SearchStrategy[type[Optimizer]] | None	The optimizer type or a strategy for generating optimizer types.	None
kwargs	Any	Keyword arguments to pass to the optimizer constructor. If a keyword argument is a strategy, it will be drawn from.	{}

optimizer_type_strategy(allowed_optimizer_types=None)

Strategy for generating torch optimizers.

Parameters:

Name	Type	Description	Default
allowed_optimizer_types	Sequence[type[Optimizer]] | None	A sequence of optimizers to sample from. If None, all available optimizers are sampled.	None

Returns:

Type	Description
SearchStrategy[type[Optimizer]]	A strategy for generating torch optimizers.

same_shape_activation_strategy(allowed_activation_functions=None)

Strategy for generating activation functions that have the same shape input and output shape.

Parameters:

Name	Type	Description	Default
allowed_activation_functions	Sequence[type[Module]] | Sequence[SearchStrategy[Module]] | None	Activation functions to sample from. - If a sequence of strategies is provided, only these strategies are sampled from. - If a sequence of module types is provided, the elements are the activation functions to sample from. - If None, all supported activation functions are sampled. - For None or sequence of module type inputs, see complete list of supported activation functions in activation_strategies.	None

Returns:

Type	Description
SearchStrategy[Module]	A strategy for generating activation functions that have the same shape input and output shape.

tensor_strategy(draw, dtype, shape, *, elements=None, fill=None, unique=False, device=None, requires_grad=None, pin_memory=None, layout=None, memory_format=None, names=False)

A strategy for generating PyTorch tensors.

Parameters:

Name	Type	Description	Default
draw	DrawFn	The draw function provided by hypothesis.	required
dtype	dtype | SearchStrategy[dtype]	Any PyTorch dtype or a strategy for generating PyTorch dtypes.	required
shape	int | SearchStrategy[int] | tuple[int, ...] | SearchStrategy[tuple[int, ...]]	The shape of the tensor. Can be an integer >= 0, a tuple of such integers, or a strategy for generating such values.	required
elements	SearchStrategy[Any] | None	A strategy for generating elements of the tensor. If None, a suitable strategy is inferred from the dtype. Note that this may give any legal value (including NaNs and infinities for floats).	None
fill	SearchStrategy[Any] | None	A strategy for generating a single background value for the tensor. If None, a suitable default will be inferred based on the other arguments. If set to ~hypothesis.strategies.nothing then filling behaviour will be disabled entirely and every element will be generated independently.	None
unique	bool | SearchStrategy[bool]	Whether the tensor's elements should all be distinct from one another. Note that multiple NaN values may still be allowed.	False
device	device | SearchStrategy[device] | None	The device on which to place the tensor. If None, the default device is used.	None
requires_grad	bool | SearchStrategy[bool] | None	Whether the tensor requires gradients. If None, a suitable default will be inferred based on the other arguments.	None
pin_memory	bool | SearchStrategy[bool] | None	Whether the tensor should be pinned in memory. If None, a suitable default will be inferred based on the other arguments.	None
layout	layout | SearchStrategy[layout] | None	The memory layout of the tensor. If None, a suitable default will be inferred based on the other arguments. Note that sparse layouts are not supported on MPS devices.	None
memory_format	memory_format | SearchStrategy[memory_format] | None	The memory format of the tensor. If None, a suitable default will be inferred based on the other arguments. Note that channel_last memory formats are only supported for 4D tensors and channel_last_3d memory formats are only supported for 5D tensors.	None
names	bool | SearchStrategy[bool]	Whether to give explicit names to the tensor's dimensions, using the "Named Tensors" API. names will default to False until the Named Tensors API is no longer experimental.	False

Returns:

Type	Description
Tensor	A strategy for generating PyTorch tensors.

transformer_strategy(draw, cls, *, instantiate_weights=True, **kwargs)

Strategy for generating Hugging Face transformers.

Parameters:

Name	Type	Description	Default
draw	DrawFn	The draw function provided by hypothesis.	required
cls	type[TransformerT] | SearchStrategy[type[TransformerT]]	The transformer class to generate.	required
instantiate_weights	bool | SearchStrategy[bool]	Whether to instantiate the weights of the transformer. If False, the transformer will be instantiated on the meta device. This is useful for testing uses of transformers models that do not require a forward pass.	True
kwargs	Any	Keyword arguments to pass to the transformer constructor. If a keyword argument is a strategy, it will be drawn from.	{}

Returns:

Type	Description
TransformerT	A strategy for generating Hugging Face transformers.

Raises:

Type	Description
ValueError	If instantiate_weights==False on PyTorch<2, because the torch meta device cannot be used as a context manager.