eccgen 0.1.2

ECCGen: Error Correcting Code Generator

ECCGen: Error Correcting Code Generator

A Python tool that solves for a valid ECC construction given some input parameters and writes the generator (G) and parity-check (H) matrices to plain text output files. You can use the generator matrix to implement an encoder and the parity-check matrix to implement the complementary decoder.

Usage (uv)

Setup:

uv sync

Run the installed CLI:

uv run eccgen --help
uv run eccgen --scheme hsiao_secded --message-size 42 --generator-matrix-output "$(pwd)/G.txt" --parity-check-matrix-output "$(pwd)/H.txt"

Or run it as a module:

uv run python -m eccgen --help
uv run python -m eccgen -s hsiao_secded -k 42 -G "$(pwd)/G.txt" -H "$(pwd)/H.txt"

Build distributable artifacts:

uv build

Install the built wheel into another environment:

uv pip install dist/eccgen-*.whl

Run the Python tests:

uv run python -m unittest eccgen.hsiao_secded_test eccgen.matrix_parser_test

Run lint and formatting:

uv run ruff check . --fix
uv run ruff format .
uv run pre-commit run --all-files

You can find pre-generated G-H pairs for powers-of-2 message and codeword sizes in eccgen/matrices.

Usage (Bazel)

You can use Bazel to run and test the tool, as well as depend on it from your own Bazel-based projects with Bzlmod. Bazel tests are currently the source of truth for the repo.

Run the tool:

bazel run //eccgen:eccgen -- --scheme hsiao_secded --message-size 42 --generator-matrix-output "$(pwd)/G.txt" --parity-check-matrix-output "$(pwd)/H.txt"

Run the unit tests:

bazel test //...

To depend on the tool from your own Bazel-based project, add the following to your MODULE.bazel file:

bazel_dep(name = "eccgen", version = "0.1.0")
git_override(
    module_name = "eccgen",
    commit = <FILL IN SHA HERE>,
    remote = "https://github.com/xlsynth/eccgen",
)

(At some point, we'll publish to the Bazel Central Registry.)

Hsiao Codes

Currently, the tool only supports Hsiao single-error-correcting, double-error-detecting (SECDED) codes, which are commonly found in digital circuit designs. The tool can be extended to support other codes.

The Hsiao code solver is based on the algorithms from the following papers:

• Hsiao et. al. 1970
• Chen et. al. 2008

We only use the optimal solver up to k = 256; beyond that, we use a greedy solution which is still SECDED, but does not qualify as a Hsiao code.

Contributing

We welcome your contributions. Please feel free to open an issue or submit a pull request.

We use GitHub Actions for CI: we run the pre-commit checks and all the Bazel tests. For local Python dependency management we use uv; if you change Python dependencies, regenerate the Bazel lockfile with bazel run //:requirements_3_12.update.

License

This project is licensed under the Apache License 2.0.