[Commit-gnuradio] [gnuradio] 30/39: fec: Updated docs for Forward Error Correction section in manual.

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch master
in repository gnuradio.

commit 7c0ff8a410528ca3eed769c595d91e2b89f30a0f
Author: Tom Rondeau <address@hidden>
Date:   Wed Jun 17 16:24:19 2015 -0400

    fec: Updated docs for Forward Error Correction section in manual.
    
    Adds information on the different coders, especially on the LDPC
    implementations.
---
 gr-fec/doc/fec.dox | 108 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 92 insertions(+), 16 deletions(-)

diff --git a/gr-fec/doc/fec.dox b/gr-fec/doc/fec.dox
index 9d48214..fc51428 100644
--- a/gr-fec/doc/fec.dox
+++ b/gr-fec/doc/fec.dox
@@ -227,6 +227,7 @@ fec/fecapi_async_encoders.grc and 
fec/fecapi_async_decoders.grc.
 
 GNU Radio currently has a minor subset of coders available:
 
+
 Coders:
 
 \li gr::fec::code::dummy_encoder
@@ -234,8 +235,9 @@ Coders:
 \li gr::fec::code::cc_encoder
 \li gr::fec::code::ccsds_encoder
 \li gr::fec::code::polar_encoder
-\li gr::fec::code::ldpc_R_U_encoder
+\li gr::fec::ldpc_encoder
 \li gr::fec::code::ldpc_gen_mtrx_encoder
+\li gr::fec::code::ldpc_R_U_encoder
 
 Decoders:
 \li gr::fec::code::dummy_decoder
@@ -243,30 +245,103 @@ Decoders:
 \li gr::fec::code::cc_decoder
 \li gr::fec::code::polar_decoder_sc
 \li gr::fec::code::polar_decoder_sc_list
+\li gr::fec::ldpc_decoder
 \li gr::fec::code::ldpc_bit_flip_decoder
 
-When building a new FECAPI encoder or decoder variable, the dummy
-encoder/decoder block would be a good place to start. This coding set
-does no processing on the data. For the encoder, each bit is simply
-passed through directly. For the dummy decoder, the input data are
-floats, so -1's become 0 and 1's stay as 1, but nothing else is done
-to the data. Mainly, these blocks are used for references and to make
-it easy to compare implementations with and without codes by easily
-dropping in these objects instead of restructuring the entire
-flowgraph. The ber_curve_gen.grc example file uses the dummy codes to
-show the curve to compare against the actual codes.
+
+\subsubsection fec_dummy Dummy Encoder/Decoder
+
+When building a new FECAPI encoder or decoder variable, the
+gr::fec::code::dummy_encoder / gr::fec::code::dummy_decoder blocks are a good
+place to start. This coding set does no processing on the data. For
+the encoder, each bit is simply passed through directly. For the dummy
+decoder, the input data are floats, so -1's become 0 and 1's stay as
+1, but nothing else is done to the data. Mainly, these blocks are used
+for references and to make it easy to compare implementations with and
+without codes by easily dropping in these objects instead of
+restructuring the entire flowgraph. The ber_curve_gen.grc example file
+uses the dummy codes to show the curve to compare against the actual
+codes.
+
+
+\subsubsection fec_repetition Repetition Encoder/Decoder
+
+The simplest example of FEC is the repetition code in
+gr::fec::code::repetition_encoder and
+gr::fec::code::repetition_decoder. The basic idea is to repeat the
+information several times so that even if parts of the received
+message are corrupted, the majority of the data is received correctly
+and the original message can be discerned. The repetition decoder is
+not particularly sophisticated and other coders offer better
+performance, but it is useful for comparison.
+
+
+\subsubsection fec_cc Convolutional Encoder/Decoder
 
 Although mentioned in the convolutional coder and decoder classes, it
-is worth another mention. The cc_encoder is a generic convolutional
-encoder that can take any value of K, rate, and polynomials to encode
-a data stream. However, the cc_decoder is not as general, even though
-it is technically parameterized as such. The cc_decoder block
+is worth another mention. The gr::fec::code::cc_encoder is a generic
+convolutional encoder that can take any value of K, rate, and
+polynomials to encode a data stream. However, the
+gr::fec::code::cc_decoder is not as general, even though it is
+technically parameterized as such. The gr::fec::code::cc_decoder block
 currently <i>only</i> uses K=7, rate=2, and two polynomials (because
 the rate is two). We can, in fact, alter the polynomials, but a
 default of [109, 79] is typically. Eventually, we will make this block
 more generic for different rates and constraint lengths and take this
 particular code implementation as the set CCSDS decoder, much like we
-have the ccsds_encoder class.
+have the gr::fec::code::ccsds_encoder class.
+
+
+\subsubsection fec_ldpc LDPC Encoders and Decoders
+
+There are a few different LDPC encoders and decoders available in
+gr-fec. The LDPC decoder used does not necessarily depend on the LDPC
+encoder used; different decoders can be used with a given
+encoder. Python scripts are included in gr-fec for constructing parity
+check matrices with specified properties.
+
+The simplest LDPC encoder is
+gr::fec::code::ldpc_gen_mtrx_encoder. From a generator matrix in
+systematic form G=[I P], the codeword x is generated from the
+information word s via simple matrix multiplication: x=G*s.  This
+encoder can be used if either a parity check matrix H or a generator
+matrix G is input. (If a H matrix is provided, the class
+gr::fec::code::ldpc_HorG_mtrx will convert it to the corresponding G
+matrix for use with this encoder.)
+
+The gr::fec::ldpc_encoder uses the same method to generate a codeword,
+x=G*s.  However, the provided matrix file must be for a parity check
+matrix.
+
+The gr::fec::code::ldpc_R_U_encoder uses a reduced complexity
+algorithm. Compared to the gr::fec::code::ldpc_gen_mtrx_encoder, this
+requires orders of magnitude fewer operations at each encoding
+step. This is accomplished by completing a significant amount of the
+complex matrix manipulation (including inverse, multiplication, and
+Gaussian elimination operations) during preprocessing. The
+disadvantage of this encoder is that it requires a specially formatted
+matrix. However, GNU Radio includes Python scripts to format a
+standard parity check matrix appropriately for this encoder, as well
+as a small library of encoding-ready matrices for use. More details
+for using this encoder are in the gr::fec::code::ldpc_R_U_mtrx class
+reference in the manual.
+
+The simplest LDPC decoder is probably the
+gr::fec::code::ldpc_bit_flip_decoder, a hard decision decoding
+scheme. The decoder seeks to find the codeword that was most likely
+sent, which must satisfy Hx'= 0.  If the received codeword does not
+satisfy this parity check, then the decoder computes the parity checks
+on all of the bits. The bit(s) associated with the most failed parity
+checks are flipped.  The process repeats until a valid codeword is
+found, or a maximum number of iterations is reached, whichever comes
+first.
+
+The gr::fec::ldpc_decoder is a soft-decision decoder that uses belief
+propagation (also known as message passing). Designed for a memoryless
+AWGN channel, it assumes a noise variance entered in as 'Sigma' in the
+block. This is a suboptimal, yet efficient method of decoding LDPC
+codes.
+
 
 
 \subsection fec_parallelism Parallelism
@@ -324,6 +399,7 @@ parallelism discussed above with the <b>None</b>, 
<b>Ordinary</b>, and
 <b>Capillary</b> models of threading.
 
 
+
 \section fec_api The API of the FECAPI
 
 The FECAPI defined by the parent generic_encoder and generic_decoder