Metadata-Version: 2.1
Name: torch-shapeguard
Version: 1.0.3
Summary: ShapeGuard allows you to very succinctly assert the expected shapes of tensors in a dynamic, einsum inspired way.
Home-page: https://github.com/rasmusbergpalm/shapeguard
Author: Rasmus Berg Palm
Author-email: rasmusbergpalm@gmail.com
License: UNKNOWN
Description: # ShapeGuard
        ShapeGuard allows you to very succinctly assert the expected shapes of tensors in a dynamic, einsum inspired way
        
        Turn this:
        
        ```python
        def batch_outer_product(x, y):
            # x has shape (batch, x_channels)
            # y has shape (batch, y_channels)
            # return has shape (batch, x_channels, y_channels)
        
            return x.unsqueeze(-1) * y.unsqueeze(-2)
        ```
        
        Into this:
        
        ```python
        def batch_outer_product(x, y):        
            x.sg(("batch", "x_channels"))
            y.sg(("batch", "y_channels"))
            
            return (x.unsqueeze(-1) * y.unsqueeze(-2)).sg(("batch", "x_channels", "y_channels"))
            
        ```
        
        
        ### Installation
        
        `pip install torch-shapeguard`
        
        ### Motivation
        
        It’s easy to make bugs in ml. 
        One particular rich source of bugs is due to the flexibility of the operators: `a*b` works whether a and b are vectors, scalar vector, vector vector, etc. 
        Similarly `.sum()` will work regardless of the shape of your tensor. 
        Since we're doing optimization whatever computation we end up performing, we can probably optimize it to work reasonably, even if it's not doing what we intended. 
        So our algorithm might "work" even if we have bugs (just less well). 
        This makes bugs super hard to discover.
        
        The best way I’ve found to avoid bugs is to religiously check the shapes of all my tensors, all the time, so I end up spending a lot of time debugging and writing comments like `#(bs, n_samples, z_size)` all over the place.
        
        So why not algorithmically check the shapes then? Well it gets ugly fast.
        
        You have to add assert `foo.shape == (bs, n_samples, x_size)` everywhere, which essentially doubles your linecount and
        you have to define all your dimensional sizes (bs, etc.), which might vary across train/test, batches, etc.
        So I made a small helper that makes it much nicer. I call it ShapeGuard.
        
        ### Usage
        
        When you `import shapeguard`, It adds the `sg` method to `torch.Tensor` and `torch.distributions.Distribution`.
        
        You can use the `sg` method like an assert:
        
        ```python
        def forward(self, x, y):
            x.sg("bchw")
            y.sg("by")
        ```
        
        This will verify that x has 4 dimensions, y has 2 dimensions and that x and y have the same size in the first dimension 'b'. 
        
        If the assert passes, the tensor is returned. 
        This means you can also chain it inline on results of operations: 
        
        ```python
        z = f(x).sg("bnz").mean(axis=1).sg("bz")
        ```
        
        If the assert fails it produces a nice error message:
        
        `AssertionError: expected 'b' to be 2 but was 4`
        
        If you want to verify an exact dimension you can pass an int as the shape e.g.
        
        ```python
        def forward(self, x, y):
            x.sg(("b", 1, "h", "w"))
            y.sg("by")
        ```
        
        The special shape '\*' is reserved for shapes that should not be asserted, e.g. `x.sg("*chw")` will assert all shapes except the first.
        
        ### How it works
        
        The first time `sg` is called for an unseen shape, the size of the tensor for that shape is saved in the `ShapeGuard.shapes` global dict. 
        Subsequent calls are checked against this stored shape. 
        
        You can call `ShapeGuard.reset(shape)` to reset a specific shape. 
        This can be useful if e.g. your batch size varies between runs. 
        `ShapeGuard.reset()` resets all shapes.
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
