torch-struct

library0.5pypypi✓ verified 85d ago

A library for structured prediction (e.g., parsing, sequence labeling) with PyTorch. Provides differentiable implementations of dynamic programming algorithms like CYK, Inside-Outside, and Viterbi. Current version 0.5, last updated 2022. Low release cadence.

ai-ml

pip install torch-struct

github ↗package ↗

INSTALL

IMPORT

SIG · TORCH-STRUCT

torch-struct

ai-mlpythonv0.5

Install

67.0s avg

Import

5428ms

Disk

4787MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 76.5s

py 3.11

✕ build_error

✓ 67.5s

py 3.12

✕ build_error

✓ 66s

py 3.13

✕ build_error

✓ 57.8s

py 3.9

✕ build_error

✕ timeout

4787MB installed

● package 4787MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

torch_struct

✓ import torch_struct

Standard import path; not from torch import struct.

LineCRF

✓ from torch_struct import LineCRF

✗ from torch_struct.models import LineCRF

Common mistake: models submodule does not exist in v0.5.

TorchStruct

✓ from torch_struct import TorchStruct

✗ import torch_struct.TorchStruct

TorchStruct is a class within the package, not a submodule.

Creates a linear-chain CRF from random potentials and computes the log-partition function.

import torch import torch_struct device = torch.device('cuda' if torch.cuda.is_available() else 'cpu') batch, N, C = 2, 5, 3 log_potentials = torch.randn(batch, N, C, device=device) dist = torch_struct.LineCRF(log_potentials) log_partition = dist.partition print(f"Log partition: {log_partition}")

Debug

Known issues

breakingIn v0.5, the `genbmm` dependency was dropped and some lesser-used features were removed (e.g., NeuralPottsModel). If you upgrade from v0.4, code relying on those features will break.

fix

Remove `genbmm` imports; use torch.bmm or einsum instead. Replace removed models with custom implementations.

affects: 0.4 -> 0.5

deprecatedThe `Semiring` API is deprecated in favor of `StructDistribution`. Old code using `Semiring` will still work but generate deprecation warnings.

fix

Replace `Semiring` usage with `StructDistribution` and log-potential pattern.

affects: >=0.4

gotchaPotentials must be in log-space (logits). The library does not check for this; using raw probabilities leads to incorrect results.

fix

Ensure inputs are log-space (e.g., use torch.log(probs) if you have probabilities).

affects: all

gotchaMany struct classes require the length of each sequence (mask) for variable-length sequences. Without a mask, the algorithms assume fully-observed sequences of length N, which can produce incorrect gradients.

fix

Pass a `lengths` tensor of shape (batch,) to the constructor: `dist = LineCRF(log_potentials, lengths=lengths)`.

affects: all

Errors

Common errors & fixes

AttributeError: module 'torch_struct' has no attribute 'Semiring'

Semiring was removed in v0.5 or used via incorrect import.

fix

Use `StructDistribution` instead: `from torch_struct import StructDistribution`.

RuntimeError: The size of tensor a (3) must match the size of tensor b (4) at non-singleton dimension 2

Potentials tensor shape (batch, N, C) does not match the expected shape for the chosen struct (e.g., for Trees, you need (batch, N, N, C) or similar).

fix

Check the expected input shape for the struct class. For LineCRF, use (batch, N, C). For TreeCRF, use (batch, N, N, C).

ValueError: Expected more than 1 value per channel when training, got input size ...

Batch normalization layer in the model receiving too few samples; not directly a torch-struct issue but common when integrating.

fix

Ensure batch size > 1 or set model.eval() during inference.

Upgrade

Version history

0.5latest on PyPI · released Feb 14, 2021

Audit

Dependencies

torchrequiredCore dependency — requires PyTorch.

genbmmoptionalWas a dependency in v0.4, dropped in v0.5.

Agent activity

16 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/harvardnlp/pytorch-struct ↗

packagehttps://pypi.org/project/torch-struct/ ↗