Contributing and development

This page is for contributors who want to build lattice-dsp from source, run checks locally, or add a feature. It describes the public development workflow rather than any private maintainer process.

Local setup

python -m pip install -e ".[dev,examples,benchmark]"
pytest
pre-commit install

The quoted extras form works in shells such as zsh that otherwise treat square brackets as glob patterns.

The package is built with scikit-build-core, CMake, and pybind11. OpenMP is used when the compiler and platform provide it. If OpenMP is unavailable, the package still builds and uses serial batch processing for the affected routines.

Linting and formatting

ruff check .
ruff format .

The repository includes .pre-commit-config.yaml so Ruff checks can run through pre-commit before commits.

Where changes usually belong

Most low-level filtering changes touch the C++ layer first and then the Python API surface:

  1. declare or update C++ APIs in include/lattice_dsp/lattice.hpp,

  2. implement them in src/lattice.cpp,

  3. expose Python bindings in src/bindings.cpp,

  4. add Python regression tests in tests/, and

  5. add a small example or benchmark when the change affects user-visible behavior or performance.

Pure-Python algorithms, documentation-only changes, and examples may not need all of these steps.

Numerical stability expectations

Adaptive recursive filters can become hard to test and explain if intermediate IIR models become unstable. Public APIs should therefore prefer one of these stability strategies:

  • reflection/PARCOR coefficients constrained by |k| < 1,

  • unconstrained raw parameters mapped through tanh, or

  • explicit projection policies for algorithms that update denominator-like parameters directly.

When a new method can produce unstable intermediate filters, document that behavior and add tests that make the expected failure or projection mode clear.

Parallelism expectations

OpenMP should be used for independent rows, independent signals, or independent filter instances. A single recursive IIR stream should not be described as sample-parallel unless a specific algorithmic transformation makes that true.

Clean-room contributions

Do not copy third-party source code unless its license is compatible and the attribution requirements are clear. Implement algorithms from public specifications, papers, books, and independently written tests.