philtorch 0.1__tar.gz

philtorch-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chin-Yun Yu
+
+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.

philtorch-0.1/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include philtorch *.txt
+recursive-include philtorch *.cuh

philtorch-0.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: philtorch
+Version: 0.1
+Summary: A PyTorch library for time-varying IIR filters.
+Author-email: Chin-Yun Yu <chin-yun.yu@qmul.ac.uk>
+Maintainer-email: Chin-Yun Yu <chin-yun.yu@qmul.ac.uk>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchlpc>=0.7.2
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: scipy; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# PhilTorch
+
+A PyTorch package for fast automatic differentiation of discrete time linear filters.
+
+Our principle design goals are:
+
+- Provide fast and differentiable version of `scipy.signal.*` functions.
+- Focus on time-domain implementation without using FFT.
+- Support batch processing, parameter-varying filters, and GPU acceleration.
+- Pure functional implementation and no stateful objects.
+
+## Installation
+
+### Stable release
+```bash
+pip install philtorch
+```
+
+### Development version
+```bash
+pip install -i https://test.pypi.org/simple/ philtorch
+# or
+pip install git+https://github.com/yoyolicoris/philtorch.git
+``` 
+> **_Note:_**
+> - The installation process compiles C++/CUDA extensions, so make sure you have a working C++ compiler and CUDA toolkit (if you want to use GPU acceleration) installed.
+> - We recommend using `--no-build-isolation` flag to avoid potential issues with building the package in an isolated environment, especially when installing with CUDA support.
+
+## 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.
+        - `state_space_recursion`: 
+            - The core recursion function for state-space models.
+        - `linear_recurrence`: 
+            - A linear recurrence function with scalar coefficients.
+    - `utils`: Utility functions.
+    - `mat`: Matrix operations.
+    - `poly`: Polynomial operations.
+
+For detailed API reference, please refer to the docstring of each function.
+
+
+
+## Examples
+
+### Recreating `scipy.signal.lfilter` example
+
+```python
+import torch
+from philtorch.lti import lfilter, lfilter_zi, filtfilt
+from scipy.signal import butter
+
+x = torch.randn(201)
+
+b_np, a_np = butter(3, 0.05)
+# note that in philtorch a_0 is always 1
+b_np /= a_np[0]
+a_np = a_np[1:] / a_np[0]
+b, a = torch.from_numpy(b_np), torch.from_numpy(a_np)
+
+# note that the position of a and b are swapped compared to scipy
+zi = lfilter_zi(a, b)
+
+z, _ = lfilter(b, a, x, zi=zi * x[0])
+z2 = filtfilt(b, a, x)
+```
+
+If `lfilter` is imported from `philtorch.lpv`, it can also handle parameter-varying filters, where `a` and `b` are at least 2D tensors with an additional time dimension.
+
+### Computing the first 10 Fibonacci numbers using `state_space`
+
+The function `philtorch.lti.state_space` compute the following recursion:
+
+```math
+\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}
+```
+
+We can use it to compute the Fibonacci numbers by setting:
+
+```math
+\begin{aligned}
+\mathbf{A} = \begin{bmatrix} 1 & 1 \\ 1 & 0 \end{bmatrix}, \quad
+\mathbf{C} = \begin{bmatrix} 1 & 0 \end{bmatrix}, \quad
+\mathbf{B} = \mathbf{D} = 0, \\
+\mathbf{h}_0 = \begin{bmatrix} 1 \\ 0 \end{bmatrix}
+\end{aligned}
+```
+
+```python
+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]])
+```
+The result is the first 10 Fibonacci numbers, which has the following recursion relation:
+
+```math
+F_n = F_{n-1} + F_{n-2}, \quad F_0 = 1, \quad F_1 = 1
+```

philtorch-0.1/README.md

@@ -0,0 +1,138 @@
+# PhilTorch
+
+A PyTorch package for fast automatic differentiation of discrete time linear filters.
+
+Our principle design goals are:
+
+- Provide fast and differentiable version of `scipy.signal.*` functions.
+- Focus on time-domain implementation without using FFT.
+- Support batch processing, parameter-varying filters, and GPU acceleration.
+- Pure functional implementation and no stateful objects.
+
+## Installation
+
+### Stable release
+```bash
+pip install philtorch
+```
+
+### Development version
+```bash
+pip install -i https://test.pypi.org/simple/ philtorch
+# or
+pip install git+https://github.com/yoyolicoris/philtorch.git
+``` 
+> **_Note:_**
+> - The installation process compiles C++/CUDA extensions, so make sure you have a working C++ compiler and CUDA toolkit (if you want to use GPU acceleration) installed.
+> - We recommend using `--no-build-isolation` flag to avoid potential issues with building the package in an isolated environment, especially when installing with CUDA support.
+
+## 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.
+        - `state_space_recursion`: 
+            - The core recursion function for state-space models.
+        - `linear_recurrence`: 
+            - A linear recurrence function with scalar coefficients.
+    - `utils`: Utility functions.
+    - `mat`: Matrix operations.
+    - `poly`: Polynomial operations.
+
+For detailed API reference, please refer to the docstring of each function.
+
+
+
+## Examples
+
+### Recreating `scipy.signal.lfilter` example
+
+```python
+import torch
+from philtorch.lti import lfilter, lfilter_zi, filtfilt
+from scipy.signal import butter
+
+x = torch.randn(201)
+
+b_np, a_np = butter(3, 0.05)
+# note that in philtorch a_0 is always 1
+b_np /= a_np[0]
+a_np = a_np[1:] / a_np[0]
+b, a = torch.from_numpy(b_np), torch.from_numpy(a_np)
+
+# note that the position of a and b are swapped compared to scipy
+zi = lfilter_zi(a, b)
+
+z, _ = lfilter(b, a, x, zi=zi * x[0])
+z2 = filtfilt(b, a, x)
+```
+
+If `lfilter` is imported from `philtorch.lpv`, it can also handle parameter-varying filters, where `a` and `b` are at least 2D tensors with an additional time dimension.
+
+### Computing the first 10 Fibonacci numbers using `state_space`
+
+The function `philtorch.lti.state_space` compute the following recursion:
+
+```math
+\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}
+```
+
+We can use it to compute the Fibonacci numbers by setting:
+
+```math
+\begin{aligned}
+\mathbf{A} = \begin{bmatrix} 1 & 1 \\ 1 & 0 \end{bmatrix}, \quad
+\mathbf{C} = \begin{bmatrix} 1 & 0 \end{bmatrix}, \quad
+\mathbf{B} = \mathbf{D} = 0, \\
+\mathbf{h}_0 = \begin{bmatrix} 1 \\ 0 \end{bmatrix}
+\end{aligned}
+```
+
+```python
+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]])
+```
+The result is the first 10 Fibonacci numbers, which has the following recursion relation:
+
+```math
+F_n = F_{n-1} + F_{n-2}, \quad F_0 = 1, \quad F_1 = 1
+```

philtorch-0.1/philtorch/VERSION.txt

@@ -0,0 +1 @@
+0.1

philtorch-0.1/philtorch/__init__.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+import warnings
+import torch
+
+try:
+    from . import _C
+
+    EXTENSION_LOADED = True
+except ImportError:
+    EXTENSION_LOADED = False
+    warnings.warn("Custom extension not loaded.")
+
+__version__ = Path(__file__).parent.joinpath("VERSION.txt").read_text()

philtorch-0.1/philtorch/_version.py

@@ -0,0 +1,18 @@
+import re
+
+
+def format_branch_name(name):
+    # "(fix|feat)/issue-name" or CICD's branch "HEAD"
+    pattern = re.compile("^((fix|feat)\/(?P<branch>.+))|((head|HEAD))")
+
+    match = pattern.search(name)
+    if match:
+        return f"dev+{match.group(0)}"  # => dev+"(fix|feat)/issue-name"
+
+    # function is called even if branch name is not used in a current template
+    # just left properly named branches intact
+    if name in ["master", "dev", "main"]:
+        return name
+
+    # fail in case of wrong branch names like "bugfix/issue-unknown"
+    raise ValueError(f"Wrong branch name: {name}")

philtorch-0.1/philtorch/csrc/host_lti_recur.cpp

@@ -0,0 +1,85 @@
+#include <torch/script.h>
+#include <torch/torch.h>
+
+template <typename scalar_t>
+void host_lti_batch_linear_recurrence(int B, int T,
+                                      const scalar_t *a,
+                                      scalar_t *out)
+{
+// Process each batch in parallel
+#pragma omp parallel for
+    for (int b = 0; b < B; ++b)
+    {
+        const scalar_t a_b = a[b];
+        scalar_t *out_b = out + b * T;
+
+        // t loop
+        for (int t = 1; t < T; ++t)
+        {
+            out_b[t] += a_b * out_b[t - 1];
+        }
+    }
+}
+
+template <typename scalar_t>
+void host_lti_shared_linear_recurrence(int B, int T,
+                                       const scalar_t a,
+                                       scalar_t *out)
+{
+// Process each batch in parallel
+#pragma omp parallel for
+    for (int b = 0; b < B; ++b)
+    {
+        scalar_t *out_b = out + b * T;
+        // t loop
+        for (int t = 1; t < T; ++t)
+        {
+            out_b[t] += a * out_b[t - 1];
+        }
+    }
+}
+
+at::Tensor lti_recur_cpu_impl(const at::Tensor &a,
+                              const at::Tensor &zi, const at::Tensor &x)
+{
+    TORCH_CHECK(zi.scalar_type() == x.scalar_type(),
+                "zi must have the same scalar type as input");
+    TORCH_CHECK(a.scalar_type() == x.scalar_type(),
+                "A must have the same scalar type as input");
+    TORCH_CHECK(a.dim() <= 1, "A must be a vector or a scalar");
+    TORCH_CHECK(zi.dim() == 1, "zi must be a vector");
+
+    auto n_steps = x.size(1) + 1; // +1 for the initial state
+    auto n_batches = x.size(0);
+    auto output =
+        at::cat({zi.unsqueeze(1), x}, 1).contiguous();
+    auto a_contiguous = a.contiguous();
+
+    if (a.dim() == 1 && a.numel() == n_batches)
+    {
+
+        AT_DISPATCH_FLOATING_AND_COMPLEX_TYPES(
+            x.scalar_type(), "host_lti_batch_linear_recurrence", [&]
+            { host_lti_batch_linear_recurrence<scalar_t>(
+                  n_batches, n_steps,
+                  a_contiguous.const_data_ptr<scalar_t>(),
+                  output.mutable_data_ptr<scalar_t>()); });
+    }
+    else
+    {
+        AT_DISPATCH_FLOATING_AND_COMPLEX_TYPES(
+            x.scalar_type(), "host_lti_shared_linear_recurrence", [&]
+            { host_lti_shared_linear_recurrence<scalar_t>(
+                  n_batches, n_steps,
+                  a_contiguous.item<scalar_t>(),
+                  output.mutable_data_ptr<scalar_t>()); });
+    }
+
+    return output.slice(1, 1, output.size(1))
+        .contiguous(); // Remove the initial state from the output
+}
+
+TORCH_LIBRARY_IMPL(philtorch, CPU, m)
+{
+    m.impl("lti_recur", &lti_recur_cpu_impl);
+}

philtorch-0.1/philtorch/csrc/host_lti_recurN.cpp

@@ -0,0 +1,114 @@
+#include <torch/script.h>
+#include <torch/torch.h>
+
+template <typename scalar_t>
+void host_lti_batch_mat_recur_N_order(int B, int T, int N,
+                                      const scalar_t *A, // [B][N][N]
+                                      scalar_t *H_out    // [B][T][N]
+)
+{
+// Process each batch in parallel
+#pragma omp parallel for
+    for (int b = 0; b < B; ++b)
+    {
+        const scalar_t *A_b = A + b * N * N;
+        scalar_t *H_b = H_out + b * T * N;
+
+        // t loop
+        for (int t = 1; t < T; ++t)
+        {
+            const scalar_t *H_prev = H_b + (t - 1) * N;
+            scalar_t *H_curr = H_b + t * N;
+
+            for (int i = 0; i < N; ++i)
+            {
+                scalar_t sum = 0;
+                const scalar_t *Arow = A_b + i * N;
+                for (int j = 0; j < N; ++j)
+                    sum += Arow[j] * H_prev[j];
+                H_curr[i] += sum;
+            }
+        }
+    }
+}
+
+template <typename scalar_t>
+void host_lti_share_mat_recur_N_order(int B, int T, int N,
+                                      const scalar_t *A, // N][N]
+                                      scalar_t *H_out    // [B][T][N]
+)
+{
+// Process each batch in parallel
+#pragma omp parallel for
+    for (int b = 0; b < B; ++b)
+    {
+        scalar_t *H_b = H_out + b * T * N;
+        // t loop
+        for (int t = 1; t < T; ++t)
+        {
+            const scalar_t *H_prev = H_b + (t - 1) * N;
+            scalar_t *H_curr = H_b + t * N;
+            for (int i = 0; i < N; ++i)
+            {
+                scalar_t sum = 0;
+                const scalar_t *Arow = A + i * N;
+                for (int j = 0; j < N; ++j)
+                    sum += Arow[j] * H_prev[j];
+                H_curr[i] += sum;
+            }
+        }
+    }
+}
+
+at::Tensor lti_mat_recur_N_order_cpu_impl(const at::Tensor &A,
+                                          const at::Tensor &zi,
+                                          const at::Tensor &x)
+{
+    TORCH_CHECK(zi.scalar_type() == x.scalar_type(),
+                "zi must have the same scalar type as input");
+    TORCH_CHECK(A.scalar_type() == x.scalar_type(),
+                "A must have the same scalar type as input");
+    TORCH_CHECK(A.dim() == 2 || A.dim() == 3, "A must be a 2D or 3D tensor");
+    TORCH_CHECK(x.size(2) == A.size(-1),
+                "Last dimension of x must match last dimension of A");
+    TORCH_CHECK(A.size(-1) == A.size(-2),
+                "Last two dimensions of A must be equal");
+
+    auto n_steps = x.size(1) + 1; // +1 for the initial state
+    auto n_batches = x.size(0);
+    auto order = A.size(-1);
+
+    auto A_contiguous = A.contiguous();
+    auto out = at::cat({zi.unsqueeze(1), x}, 1).contiguous();
+
+    if (A.dim() == 3)
+    {
+        AT_DISPATCH_FLOATING_AND_COMPLEX_TYPES_AND1(
+            at::kLong, x.scalar_type(), "host_lti_batch_mat_recur_N_order",
+            [&]
+            {
+                host_lti_batch_mat_recur_N_order<scalar_t>(
+                    n_batches, n_steps, order,
+                    A_contiguous.const_data_ptr<scalar_t>(),
+                    out.mutable_data_ptr<scalar_t>());
+            });
+    }
+    else
+    {
+        // Shared
+        AT_DISPATCH_FLOATING_AND_COMPLEX_TYPES_AND1(
+            at::kLong, x.scalar_type(), "host_lti_share_mat_recur_N_order", [&]
+            { host_lti_share_mat_recur_N_order<scalar_t>(
+                  n_batches, n_steps, order,
+                  A_contiguous.const_data_ptr<scalar_t>(),
+                  out.mutable_data_ptr<scalar_t>()); });
+    }
+    return out.slice(1, 1, n_steps)
+        .contiguous(); // Remove the initial state from the output
+}
+
+TORCH_LIBRARY_IMPL(philtorch, CPU, m)
+{
+    m.impl("lti_recurN", &lti_mat_recur_N_order_cpu_impl);
+    m.impl("lti_recur2", &lti_mat_recur_N_order_cpu_impl);
+}