Metadata-Version: 2.1
Name: hypothesis-torch
Version: 0.7.2
Summary: Hypothesis strategies for various Pytorch structures, including tensors and modules.
Author-email: "Andrew P. Sansom" <andrew@euleriancircuit.com>
License: MIT License
        
        Copyright (c) 2024 Andrew Sansom
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/qthequartermasterman/hypothesis-torch
Project-URL: Documentation, https://hypothesis-torch.readthedocs.io/en/stable/
Project-URL: Repository, https://github.com/qthequartermasterman/hypothesis-torch.git
Project-URL: Issues, https://github.com/qthequartermasterman/hypothesis-torch/issues
Keywords: hypothesis,torch,pytorch,testing,property-based testing,deep learning,tensor,neural network,artificial intelligence,machine learning
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Framework :: Hypothesis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hypothesis >=6.0.0
Requires-Dist: torch >=1.13.0
Provides-Extra: dev
Requires-Dist: mypy ==1.10.0 ; extra == 'dev'
Requires-Dist: ruff ==0.4.5 ; extra == 'dev'
Requires-Dist: pyright ==1.1.364 ; extra == 'dev'
Requires-Dist: pytest ==8.2.1 ; extra == 'dev'
Requires-Dist: pytest-cov ==5.0.0 ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs ==1.6.0 ; extra == 'docs'
Requires-Dist: mkdocstrings[python] ==0.25.1 ; extra == 'docs'
Requires-Dist: mkdocs-autolinks-plugin ==0.7.1 ; extra == 'docs'
Requires-Dist: mkdocs-material ==9.5.25 ; extra == 'docs'
Requires-Dist: mkdocs-snippets ==1.3.0 ; extra == 'docs'
Requires-Dist: mkdocs-exclude ==1.0.2 ; extra == 'docs'
Provides-Extra: huggingface
Requires-Dist: transformers <=4.41.1,>=4.0.0 ; extra == 'huggingface'

[![PyPI version](https://img.shields.io/pypi/v/hypothesis-torch.svg)](https://pypi.org/project/hypothesis-torch) ![PyPI - Downloads](https://img.shields.io/pypi/dm/hypothesis-torch)
[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)

# hypothesis-torch
Hypothesis strategies for various Pytorch structures (including tensors and modules).

[Hypothesis](https://hypothesis.readthedocs.io/en/latest/) 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.

## Installation
`hypothesis-torch` can be installed via pip:
```bash
pip install hypothesis-torch
```

Optionally, you can also install the `huggingface` extra to also install the `transformers` library:
```bash
pip install hypothesis-torch[huggingface]
```

Strategies for generating Hugging Face transformer models are provided in the `hypothesis_torch.huggingface` module. If 
and only if `transformers` is installed when `hypothesis-torch` is imported, these strategies will be available from
the root `hypothesis_torch` module.

## What you can generate

### Tensors

Tensors can be generated with the `tensor_strategy` function. This function takes in optional arguments for the shape,
dtype, device, and other properties of the desired tensors. Each property can be specified as a fixed value or as a
strategy. For example, to generate a tensor with a shape of 3x3, a dtype of `torch.float32`, and values between 0 and 1,

```python
import hypothesis_torch
from hypothesis import strategies as st
import torch
hypothesis_torch.tensor_strategy(dtype=torch.float32, shape=(3, 3), elements=st.floats(0, 1))
```

Note that specifying other hypothesis strategies that return the same type as an argument will sample from that strategy
while generating the tensor. For example, to generate a tensor with any dtype, specify a strategy that returns a dtype:

```python
import hypothesis_torch
from hypothesis import strategies as st
import torch
hypothesis_torch.tensor_strategy(dtype=st.sampled_from([torch.float32, torch.float64]), shape=(3, 3), elements=st.floats(0, 1))
```

### Dtypes

Dtypes can be generated with the `dtype_strategy` function. If no arguments are provided, this function will default to 
sampling from the set of all Pytorch dtypes. 
    
```python
import hypothesis_torch
hypothesis_torch.dtype_strategy()
```

If a set of dtypes is provided, the function will sample from that set.

```python
import hypothesis_torch
import torch
hypothesis_torch.dtype_strategy(dtypes={torch.float32, torch.float64})
```

### Devices

Devices can be generated with the `device_strategy` function. If no arguments are provided, this function will default to
sampling from the set of all available, physical devices.

```python
import hypothesis_torch
hypothesis_torch.device_strategy()
```

If a set of devices is provided, the function will sample from that set.

```python
import hypothesis_torch
import torch
hypothesis_torch.device_strategy(devices={torch.device('cuda:0'), torch.device('cpu')})
```

If `allow_meta_device` is set to `True`, the strategy may also return meta devices, i.e. `torch.device('meta')`.

```python
import hypothesis_torch
hypothesis_torch.device_strategy(allow_meta_device=True)
```

### Modules

Various types of PyTorch modules have their own strategies.

#### Activation functions

Activation functions can be generated with the `same_shape_activation_strategy` function. 

```python
import hypothesis_torch
hypothesis_torch.same_shape_activation_strategy()
```

#### Fully-connected/Feed forward neural networks

Fully-connected neural networks can be generated with the `linear_network_strategy` function. This function takes in 
optional arguments for the input size, output size, and number of hidden layers. Each of these arguments can be 
specified as a fixed value or as a strategy. For example, to generate a fully-connected neural network with an input
size of 10, an output size of 5, and 3 hidden layers with sizes between 5 and 10:

```python
import hypothesis_torch
from hypothesis import strategies as st
hypothesis_torch.linear_network_strategy(input_shape=(1,10), output_shape=(1,5), hidden_layer_size=st.integers(5, 10), num_hidden_layers=3)
```

#### Hugging Face Transformer Models

Hugging Face transformer models can be generated with the `transformer_strategy` function. This function takes in any
Hugging Face `PreTrainedModel` subclass (or a strategy that generates references `PreTrainedModel` subclasses) and 
returns an instance of that model. For example, to generate an arbitrary Llama2 model:

```python
import hypothesis_torch
import transformers
hypothesis_torch.transformer_strategy(transformers.LlamaForCausalLM)
```

The strategy also accepts `kwargs` to pass to the model constructor. These can be either fixed values or strategies to 
generate those corresponding values. For example, to generate an arbitrary Llama2 model with a hidden size between 64 and
128, but a fixed vocabulary size of 1000:

```python
import hypothesis_torch
import transformers
from hypothesis import strategies as st
hypothesis_torch.transformer_strategy(transformers.LlamaForCausalLM, hidden_size=st.integers(64, 128), vocab_size=1000)
```

[! Note]
    Currently, the `transformer_strategy` only accepts `kwargs` that can be passed to the constructor of the model's 
    config class. Thus, it cannot currently replicate all the behavior of calling `from_pretrained` on a model class.
