PhilTorch $\Huge \overset{🔥}{\Phi}$

PhilTorch provides differentiable, time-domain linear digital filters for PyTorch.

• Differentiate through filter coefficients, inputs, and initial states with PyTorch autograd.
• Process batched signals and filters whose coefficients vary at every time step.
• Compute in the time domain without FFTs, through a pure functional API with no stateful objects.
• Run on native CPU, CUDA, and MPS kernels.

The documentation, with the API reference of every module, is at philtorch.readthedocs.io.

News

• 2025-12-06: We presented our paper, Accelerating Automatic Differentiation of Direct Form Digital Filters, at the Differentiable Systems and Scientific Machine Learning Workshop at EurIPS 2025. The poster is available here.
• 2025-11-10: PhilTorch was first presented at the Audio Developer Conference 2025. The presentation slides are available here.
• 2025-10-31: Our short paper describing the LTI filter implementation in PhilTorch was accepted by the Differentiable Systems and Scientific Machine Learning Workshop at EurIPS 2025. The preprint is available here.

Installation

PhilTorch requires its compiled philtorch._C extension; there is no pure-PyTorch fallback when the extension is missing.

PyPI wheels

python -m pip install philtorch

Wheels contain no CUDA kernels. Each wheel is built against one PyTorch minor release and requires it (e.g. torch == 2.14.*), because the compiled extension does not load with other minor releases. pip therefore installs that PyTorch minor with PhilTorch, replacing a different one if needed. If a different minor is installed anyway, for example with --no-deps, import philtorch raises an ImportError naming the minor it needs. For CUDA on Linux, use the CUDA wheels; for another PyTorch minor release, build from source.

CUDA wheels

Linux wheels with CUDA kernels are published on a separate package index rather than PyPI. Wheel tags don't record which PyTorch and CUDA build a wheel is for, and PyPI rejects the local version labels that do (e.g. +torch2.14.1.cu132). There is one index per PyTorch minor and CUDA version that PyTorch publishes wheels for. Install PyTorch first, then install PhilTorch from the index that matches it:

python -m pip install torch==2.14.1 --index-url https://download.pytorch.org/whl/cu132
python -m pip install philtorch --index-url https://yoyolicoris.github.io/philtorch/whl/torch2.14-cu132/

To find the matching index for an installed PyTorch, run python -c "import torch; print(torch.__version__, torch.version.cuda)". For example, 2.14.1+cu132 13.2 matches whl/torch2.14-cu132/. On Linux, pip install torch from PyPI installs PyTorch's default CUDA build; the command above shows which.

The index URLs are relative to https://yoyolicoris.github.io/philtorch/, which lists every index, including those for earlier releases.

• Requirements: a Python the table above lists for the wheel's PyTorch, an NVIDIA GPU with compute capability 7.5, 8.x, 9.0, 10.x or 12.x, and a driver that supports the wheel's CUDA version.
• PyTorch: each wheel requires its PyTorch minor (e.g. torch == 2.14.*), so pip keeps the PyTorch you installed.
• Mismatches: import philtorch raises an ImportError if the installed PyTorch is a different minor release, has no CUDA support, or uses a different CUDA major version. It only warns if the CUDA minor version differs.
• Use --index-url, not --extra-index-url: with PyPI also searched, pip installs PyPI's CPU-only wheel whenever it is a newer release than the CUDA build in the index, without warning.

Source builds

Install PyTorch first with the PyTorch installation selector, then build PhilTorch against it without build isolation:

python -m pip install "setuptools>=77.0.3" "setuptools_scm>=8" wheel
python -m pip install --no-binary=philtorch --no-build-isolation philtorch

The build compiles a CUDA extension when torch.cuda.is_available() is true and CUDA_HOME is set, and a CPU-only C++ extension otherwise. On a headless build server with no visible GPU, set PHILTORCH_FORCE_CUDA=1 to compile the CUDA extension anyway. In that case the installed PyTorch must be a CUDA build, and TORCH_CUDA_ARCH_LIST must also be set to the target architectures (e.g. TORCH_CUDA_ARCH_LIST="8.0 8.6"), because there is no GPU to infer them from. On macOS, when the installed PyTorch supports OpenMP, the build also needs Homebrew llvm and libomp, unless PHILTORCH_DISABLE_OPENMP=1 is set.

For an editable install from Git:

git clone --branch main https://github.com/yoyolicoris/philtorch.git
cd philtorch
python -m pip install torch  # Choose the correct CPU or CUDA build first.
python -m pip install "setuptools>=77.0.3" "setuptools_scm>=8" wheel
python -m pip install --editable . --no-build-isolation

Package versions come from Git tags through setuptools_scm, so keep the tag metadata when building from a checkout.

Development version

Development builds from dev are published to TestPyPI:

python -m pip install -i https://test.pypi.org/simple/ philtorch

Quickstart

Filtering with SciPy-designed coefficients

import torch
from scipy.signal import butter

from philtorch.lti import filtfilt, lfilter, lfilter_zi

x = torch.randn(201, dtype=torch.float64)

b_np, a_np = butter(3, 0.05)
# Normalize so that a0 = 1, then drop a0 from the denominator.
b = torch.from_numpy(b_np / a_np[0])
a = torch.from_numpy(a_np[1:] / a_np[0])

# lfilter_zi takes (a, b), the reverse of SciPy's lfilter_zi(b, a).
zi = lfilter_zi(a, b)

y, _ = lfilter(b, a, x, zi=zi * x[0])
y_zero_phase = filtfilt(b, a, x)

Module overview

• philtorch: Root module.
  • lpv: Functions under it are for linear parameter-varying filters.
    • fir:
      • Finite Impulse Response filters.
    • allpole:
      • All-pole filters.
    • lfilter:
      • Parameter-varying version of scipy.signal.lfilter. It supports not only transposed direct form II but also transposed direct form I, direct form I, and direct form II structures.
    • state_space:
      • Parameter-varying state-space models.
    • state_space_recursion:
      • The core recursion function for state-space models.
    • linear_recurrence:
      • A linear recurrence function with scalar coefficients.
  • lti: Functions under it are for linear time-invariant filters.
    • fir:
      • Finite Impulse Response filters.
    • lfilter:
      • A differentiable version of scipy.signal.lfilter. It supports not only transposed direct form II but also transposed direct form I, direct form I, and direct form II structures.
    • filtfilt:
      • A differentiable version of scipy.signal.filtfilt.
    • lfilter_zi:
      • A differentiable version of scipy.signal.lfilter_zi.
    • lfiltic:
      • A differentiable version of scipy.signal.lfiltic.
    • state_space:
      • State-space models.
    • diag_state_space:
      • State-space models with diagonalisable state matrix.
    • delay_state_space:
      • State-space models whose states are delay lines of arbitrary integer length, such as feedback delay networks, with optional absorption filters on each line.
    • state_space_recursion:
      • The core recursion function for state-space models.
    • linear_recurrence:
      • A linear recurrence function with scalar coefficients.
    • comb_filter:
      • Delayed all-pole comb filters.
    • cubic_spline:
      • Cubic-spline interpolation for integer upsampling.
  • estimation: Functions under it estimate hidden states from noisy measurements and fit the models by expectation-maximization.
    • kalman_filter, kalman_smoother:
      • Kalman filters and Rauch–Tung–Striebel smoothers for linear Gaussian state-space models, parallelized over time with associative scans, with the log-likelihood and the smoother's lag-one cross-covariances for fitting by gradients or EM.
    • hmm_filter, hmm_smoother, hmm_viterbi:
      • The forward algorithm, forward-backward smoothing and Viterbi decoding for hidden Markov models, parallelized over time and differentiable to any order in reverse mode. CUDA GPUs only, as Triton kernels.
    • em, kalman_em_step, hmm_em_step:
      • Expectation-maximization: em repeats any model's step until the log-likelihood stops rising; the Kalman step has Shumway and Stoffer's closed-form M-step, the HMM step is Baum–Welch for the transitions and initial distribution. Parameters are shared or per signal.
  • align: Functions under it align sequences.
    • dtw, dtw_path, soft_dtw_divergence:
      • Dynamic time warping and soft-DTW distances from a cost matrix, whose gradients are the alignments, differentiable to any order, and DTW's optimal warping path. CUDA GPUs only, as Triton kernels.
    • ctc_loss, forced_align:
      • The connectionist temporal classification loss, as soft-DTW between frames and a target's states, differentiable to any order, and its most probable alignment. CUDA GPUs only, as Triton kernels.
  • utils: Utility functions.
  • mat: Matrix operations.
  • poly: Polynomial operations.

For detailed API reference, please refer to the docstring of each function.

Choose the right API

The supported high-level interfaces are exported from philtorch.lti for fixed coefficients, philtorch.lpv for coefficients that vary over time, philtorch.estimation for state estimation, and philtorch.align for sequence alignment.

Comparison with scipy.signal

PhilTorch functions take PyTorch tensors, support autograd and batching, and keep the input dtype and device. Coefficients are normalized so that a0 = 1: divide SciPy's b and a by a[0], then pass a[1:] as the denominator, as in the Quickstart example.

Performance

Recursive filters are hard to parallelize, so PhilTorch implements custom C++, CUDA and Triton kernels. With the default unroll_factor=None, the state-space paths (lfilter, state_space, and state_space_recursion) choose a kernel from the device, the dtype and the filter order, which is the state size M:

✓ native or Triton kernel · ✗ raises NotImplementedError, since no kernel takes the input; pass unroll_factor=1 for the sequential loop, or 2 up to one less than the sequence length for a block-unrolled recursion, or use CPU. ¹ Triton, up to M = 128 (64 for complex dtypes); larger M raises. A native kernel takes M = 3 in float32. ² float32 only.

The kernels take floating-point and complex dtypes, and int64, exactly; other dtypes raise.

Passing an integer unroll_factor runs PyTorch ops instead. unroll_factor=1 runs the sequential loop. In 0.7 it ran the kernels; to keep that, omit the argument or pass None. Until 0.9, 1 emits a FutureWarning. Setting 1 < unroll_factor < sequence length switches to a block-unrolled recursion, which computes blocks in parallel with matrix multiplications (background); larger values run the sequential loop too. Both run on any device, in the dtypes PyTorch's matrix products take there: integers on CPU, but not on CUDA. The block-unrolled recursion is slower than the native kernels but much faster than the sequential loop. Good starting points are 8 on CPU and 16–32 on CUDA, but benchmark your own batch size, sequence length, state size, dtype, and device, for example with torch.utils.benchmark. Native kernels are fastest for filters of order 1 to 3, so prefer cascades or parallel banks of such sections, especially on CUDA.

Examples

Fibonacci numbers with state_space

philtorch.lti.state_space computes

\begin{aligned}
\mathbf{h}_{n+1} &= \mathbf{A} \mathbf{h}_n + \mathbf{B} \mathbf{x}_n, \\
\mathbf{y}_n &= \mathbf{C} \mathbf{h}_n + \mathbf{D} \mathbf{x}_n.
\end{aligned}

Setting the following, with $\mathbf{B} = \mathbf{D} = 0$ and no input, yields the Fibonacci numbers:

\mathbf{A} = \begin{bmatrix} 1 & 1 \\ 1 & 0 \end{bmatrix}, \qquad
\mathbf{C} = \begin{bmatrix} 1 & 0 \end{bmatrix}, \qquad
\mathbf{h}_0 = \begin{bmatrix} 1 \\ 0 \end{bmatrix}.

import torch

from philtorch.lti import state_space

A = torch.tensor([[1, 1], [1, 0]])
C = torch.tensor([1, 0])
x = torch.zeros(1, 10).long()
h0 = torch.tensor([1, 0])
y, _ = state_space(A, x, C=C, zi=h0)
print(y)

tensor([[ 1,  1,  2,  3,  5,  8, 13, 21, 34, 55]])

This produces the first ten Fibonacci numbers, where $F_n = F_{n-1} + F_{n-2}$ with $F_0 = F_1 = 1$.

Learning filter parameters

The low-pass estimation notebook demonstrates learning filter parameters by gradient descent.

Project links

• The contribution guide documents the development and pull-request workflow, and the PhilTorch Roadmap lists current priorities.
• The issue tracker is the place for bug reports and feature requests.
• PhilTorch is distributed under the MIT License; third-party notices are in LICENSES.

Paper and citation

PhilTorch's LTI direct-form filtering work is described in Accelerating Automatic Differentiation of Direct Form Digital Filters by Chin-Yun Yu and György Fazekas.

@inproceedings{yu2025accelerating,
  title={Accelerating Automatic Differentiation of Direct Form Digital Filters},
  author={Yu, Chin-Yun and Fazekas, György},
  booktitle={Differentiable Systems and Scientific Machine Learning Workshop at EurIPS 2025},
  year={2025},
  url={https://openreview.net/forum?id=ZhwIyvtBNB}
}