Commit c19aa7ab authored by Renaud Pacalet's avatar Renaud Pacalet
Browse files

update README.md and Makefile for doc and help

parent d0ae0a5e
......@@ -45,19 +45,10 @@ CDEPS := $(patsubst $(CSRCDIR)/%.c,$(BUILDDIR)/%.d,$(CSRCS))
CEXECNAMES := make-pchk alist-to-pchk pchk-to-alist make-ldpc print-pchk make-gen print-gen rand-src encode transmit decode extract verify mod2dense-test mod2sparse-test mod2convert-test rand-test qc-to-pchk make-standard-qc-matrix
CEXECS := $(addprefix $(BUILDDIR)/,$(CEXECNAMES))
define COMPILE_HELP_message
Goals:
help This message
all Compile
clean Clean-up all generated files
endef
export COMPILE_HELP_message
.PHONY: help all clean
help::
@printf "$$COMPILE_HELP_message"
help:
@cat README.md | grep -v '^```' | less
all: $(CEXECS)
......@@ -109,19 +100,12 @@ clean::
# Testing #
###########
# T: Number of transmitted code words
# I: Number of decoding iterations
# Q: Bit-width of fixed-point data
# V: Verbose (0: no, 1: yes)
T := 100
I := 16
Q := 8
V := 0
SIGMA := 0.5
CHANNEL := awgn $(SIGMA)
DECMETHOD := scmsla $(I) $(Q)
CHANNEL := awgn 0.5
DECMETHOD := scmsla 16 8
SEED := 19
GENMETHOD := dense
STANDARD := 802.11n
......@@ -137,74 +121,6 @@ QCTOPCHK := $(BUILDDIR)/qc-to-pchk
RANDSRC := $(BUILDDIR)/rand-src
TRANSMIT := $(BUILDDIR)/transmit
define TEST_HELP_message
Codes can be defined by providing a text file in the ad-hoc format:
Z M N
HB(0,0) HB(0,1) ... HB(0,N-1)
...
HB(M-1,0) HB(M-1,1) ... HB(M-1,N-1)
where the HB(i,j) is the right-rotation factor (modulus Z) of the ZxZ identity
matrix of block row i, block column j. Negative values of HB(i,j) indicate the
ZxZ zero matrix. Codes can also be defined by a {STANDARD,Z,M,N} tuple where:
STANDARD is any of 802.11n, 3GPP
Z is a lifting factor (e.g. 27, 54 or 81 for 802.11n)
M is the number of block rows of the quasi-cyclic matrix
N is the number of block columns of the quasi-cyclic matrix
If a text file is provided the {STANDARD,Z,M,N} is ignored. Else, the
{STANDARD,Z,M,N} tuple is used to generate the text file correponding to a
standard code. The tuple must be a valid one for the specified standard.
Goals:
test Run test
test-all Run tests with all matrices
test-clean Delete test files
Variables (current value):
T Number of transmitted code words ($(T))
I Number of decoding iterations ($(I))
Q Bit-width of fixed-point data ($(Q))
V Verbose (0: no, 1: yes)
SIGMA Standard deviation of AWGN channel ($(SIGMA))
SEED Seed on pseudo-random number generator ($(SEED))
CHANNEL Channel type ($(CHANNEL))
DECMETHOD Decoding method ($(DECMETHOD))
QCMATRIX Quasi-Cyclic matrix text file$(if $(QCMATRIX), ($(QCMATRIX)))
STANDARD Standard ($(STANDARD))
Z Lifting factor ($(Z))
M Number of block rows ($(M))
N Number of block columns ($(N))
Standard deviations vs SNR (with Eb=1):
0.40 7.96
0.50 6.02
0.60 4.44
0.70 3.10
0.80 1.94
0.90 0.92
1.00 0.00
Channels:
bsc error-probability (Binary Symmetric Channel)
awgn standard-deviation (Additive White Gaussian Noise)
awln width (Additive White Logistic Noise)
Decoding methods:
enum-block gen-file
enum-bit gen-file
prprp [-]max-iterations (probability propagation)
scms [-]max-iterations (Self-Corrected Min-Sum, floating point)
scmsfp [-]max-iterations 1<=bit-width<=31 (SCMS, fixed point)
scmsla [-]max-iterations 1<=bit-width<=31 (SCMS, fixed point, layered schedule)
scmspp [-]max-iterations 1<=bit-width<=31 1<= parallel-level (SCMS, fixed point, layered schedule disturbed by parallel processing)
endef
export TEST_HELP_message
help::
@printf "$$TEST_HELP_message" | more
ifeq ($(V),0)
DEVNULL := &> /dev/null
AT := @
......@@ -246,7 +162,7 @@ $(foreach Z,$(3GPPZVALUES),$(eval $(call TEST_rule,3GPP,$(Z),42,52)))
PCHKS := $(patsubst %.qc,%.pchk,$(QCMATRICES))
GENS := $(patsubst %.qc,%.gen,$(QCMATRICES))
SRSC := $(patsubst %.qc,%.srs,$(QCMATRICES))
SRCS := $(patsubst %.qc,%.src,$(QCMATRICES))
ENCS := $(patsubst %.qc,%.enc,$(QCMATRICES))
RECS := $(patsubst %.qc,%.rec,$(QCMATRICES))
DECS := $(patsubst %.qc,%.dec,$(QCMATRICES))
......@@ -274,7 +190,7 @@ $(DECS): %.dec: %.rec %.pchk $(DECODE)
test: $(qcmatrix).dec
.PHONY: test-all
.PHONY: $(SRCS) test-all
test-all: $(CEXECS) $(QCMATRICES)
......@@ -292,25 +208,15 @@ list: $(MAKEQC)
# Documentation #
#################
DOCDIR := doc
LATEX := pdflatex
DOCSCMS := scms
LATEX := pdflatex
BIBTEX := bibtex
define DOC_HELP_message
Goals:
doc Compile the SCMS documentation scms.pdf
scms.pdf Same as doc
doc-clean Clean-up all generated files
endef
export DOC_HELP_message
help::
@printf "$$DOC_HELP_message"
doc: $(DOCSCMS).pdf
$(DOCSCMS).pdf: $(DOCSCMS).tex biblio.bib
$(DOCSCMS).pdf: $(DOCDIR)/$(DOCSCMS).tex $(DOCDIR)/biblio.bib
$(LATEX) $< && \
$(BIBTEX) $(DOCSCMS) && \
$(LATEX) $< && \
......
# LDPC-codes with Self-Corrected Min-Sum method
This is a fork of the original [LDPC-codes] work by Radford M. Neal. It adds:
This is a fork of the original [LDPC-codes](https://github.com/radfordneal/LDPC-codes) work by Radford M. Neal. It adds:
* The [Self-Corrected Min-Sum] method (floating and fixed point versions)
* The [Self-Corrected Min-Sum] method with layered schedule (fixed point version)
* Routines to convert text files describing quasi-cyclic parity matrices to the `pchk` format used by the original library.
* A utility to generate text files describing the 802.11.n and 3GPP Nex Radio (5G) quasi-cyclic parity matrices.
* A real `Makefile` with dependencies handling, compilation and test targets.
* SCMS, a [Self-Corrected Min-Sum](https://arxiv.org/pdf/0803.1090) decoding method (floating and fixed point versions),
* SCMSLA a SCMS variant with layered schedule (fixed point version),
* SCMSPP a SCMSLA variant with emulated parallel decoding,
* routines to convert text files describing quasi-cyclic parity matrices to the binary format used by the original library,
* a utility to generate the standard 802.11.n and 3GPP New Radio (5G) quasi-cyclic parity matrices,
* a real `Makefile` with dependencies handling, compilation and test targets,
* documentation.
# Compiling and testing
To compile the sources and run a test for the default LDPC code, type:
```bash
$ make test
```
Usage:
make [GOAL [VARIABLE=VALUE...]]
Goals:
help This message (default goal)
all Compile C sources
test Run test for one code
test-all Run tests for all supported standard codes
doc Compile SCMS documentation (`scms.pdf`)
clean Delete all generated files
Variables (default value):
BUILDDIR Build directory (build)
T Number of transmitted code words (100)
CHANNEL Transmission channel (awgn 0.5)
DECMETHOD Decoding method (scmsla 16 8)
GENMETHOD Method used to generate the generator matrix (dense)
SEED Random generator seed (19)
V Verbose (0: no, 1: yes)
QCMATRIX Quasi-Cyclic matrix text file
STANDARD Standard (802.11n)
Z Lifting factor (27)
M Number of block rows (12)
N Number of block columns (24)
```
The test:
## Transmission channels
* generates the parity check matrix of the code in text format,
* converts the text format to `pchk` format,
* randomly generates source frames,
* encodes them,
* adds AWGN to emulate a real transmission channel,
* decodes the *received* frames.
* Binary Symmetric Channel: `CHANNEL='bsc P'` where `P` is the error probability
* Additive White Logistic Noise: `CHANNEL='awln W'` where `W` is the width
* Additive White Gaussian Noise: `CHANNEL='awgn S'` where `S` is the noise standard deviation
To test a different code type:
AWGN noise standard deviations vs SNR (with Eb=1):
```bash
$ make test QCMATRIX=file
```
| S | SNR (dB) |
|:-----|:---------|
| 0.40 | 7.96 |
| 0.50 | 6.02 |
| 0.60 | 4.44 |
| 0.70 | 3.10 |
| 0.80 | 1.94 |
| 0.90 | 0.92 |
| 1.00 | 0.00 |
where `file` is the name of a text file containing the compact form of a quasi-cyclic parity matrix. The format of `file` shall be:
## Decoding methods
Z M N
HB(0,0) HB(0,1) ... HB(0,N-1)
...
HB(M-1,0) HB(M-1,1) ... HB(M-1,N-1)
* Exhaustive enumeration of code words: `DECMETHOD='enum-block gen-file'` (most likely code word)
* Exhaustive enumeration of code words: `DECMETHOD='enum-bit gen-file'` (most likely individual bits)
* Probability propagation: `DECMETHOD='prprp [-]I'`
* Self-Corrected Min-Sum, floating point: `DECMETHOD='scms [-]I'`
* Self-Corrected Min-Sum, fixed point: `DECMETHOD='scmsfp [-]I Q'`
* Self-Corrected Min-Sum, fixed point, layered schedule: `DECMETHOD='scmsla [-]I Q'`
* Self-Corrected Min-Sum, fixed point, layered schedule, by parallel processing: `DECMETHOD='scmspp [-]I Q P'`
where:
* `Z` is the lifting factor (size of the square sub-matrices),
* `M` is the number of block rows of the quasi-cyclic matrix,
* `N` is the number of block columns of the quasi-cyclic matrix,
* `HB(i,j)` is the right-rotation factor (modulus `Z`) of the `ZxZ` identity matrix of block row `i`, block column `j`. Negative values of `HB(i,j)` indicate the `ZxZ` zero matrix.
* `gen-file` is the file containing the code's generator matrix
* `I` is the maximum number of iterations; if positive the decoding stops when a valid code word is encountered or after `I` iterations; if negative the decoding stops after `I` iterations
* `Q` is the bit-width of fixed point data
* `P` is the number of parallel decoding units
To test one of the supported standard codes type:
## Running tests for a standard code
```bash
$ make test STANDARD=name Z=z M=m N=n
```
Supported standard codes are specified using four variables:
where:
* `STANDARD`: short name of a supported standard
* `Z`: lifting factor (e.g. 27, 54 or 81 for 802.11n)
* `M`: number of block rows of the quasi-cyclic matrix (e.g. 12 for 802.11n)
* `N`: number of block columns of the quasi-cyclic matrix (e.g. 24 for 802.11n)
* `name` is the short name of one of the supported standards (`802.11n`, `3GPP`),
* `Z` is the lifting factor (size of the square sub-matrices),
* `M` is the number of block rows of the quasi-cyclic matrix,
* `N` is the number of block columns of the quasi-cyclic matrix
To get the list of the supported standard codes type:
Currently supported standards are `802.11n` and `3GPP`. To get the list of all supported standard codes and their `Z`, `M`, `N` parameters, type:
```bash
$ make list
```
For more information about the available goals and customizable make variables, type:
Example to run a test for the 3GPP code base graph 1 with `Z=384`, on 10 code words, transmitted over a AWGN channel with 0.4 noise standard deviation (8 dB SNR), decoded using layered SCMS with 16 iterations and 8 bits fixed-point data:
```bash
$ make
$ make test STANDARD=3GPP Z=384 M=46 N=68 T=10 CHANNEL="awgn 0.4" DECMETHOD="scmsla 16 8"
```
or:
The test:
* generates the parity check matrix of the code in text format (`build/3GPP_384_46_68.qc`),
* converts the text format to `pchk` format (`build/3GPP_384_46_68.pchk`),
* generates the code's generator matrix (`build/3GPP_384_46_68.gen`),
* randomly generates source frames (`build/3GPP_384_46_68.src`),
* encodes them (`build/3GPP_384_46_68.enc`),
* adds AWGN to emulate a real transmission channel (`build/3GPP_384_46_68.rec`),
* decodes the _received_ frames (`build/3GPP_384_46_68.dec`).
## Running tests for a custom code
Create a text file containing the compact description of the quasi-cyclic parity matrix of the custom code:
```bash
$ make help
host> cat foo.txt
Z M N
HB(0,0) HB(0,1) ... HB(0,N-1)
...
HB(M-1,0) HB(M-1,1) ... HB(M-1,N-1)
```
[LDPC-codes]: https://github.com/radfordneal/LDPC-codes
[Self-Corrected Min-Sum]: https://arxiv.org/pdf/0803.1090
where:
* `Z` is the lifting factor (size of the square sub-matrices),
* `M` is the number of block rows of the quasi-cyclic matrix,
* `N` is the number of block columns of the quasi-cyclic matrix,
* `HB(i,j)` is the right-rotation factor (modulus `Z`) of the `ZxZ` identity matrix of block row `i`, block column `j`. Negative values of `HB(i,j)` indicate the `ZxZ` zero matrix.
Then:
```bash
host> make test QCMATRIX=foo.txt [VARIABLE=VALUE...]
```
<!-- vim: set tabstop=4 softtabstop=4 shiftwidth=4 noexpandtab textwidth=0: -->
<!-- vim: set tabstop=4 softtabstop=4 shiftwidth=4 expandtab textwidth=0: -->
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment