itpp::LDPC_Code Class Reference
Communications Module » Forward Error Correcting Codes

Low-density parity check (LDPC) codec. More...

`#include <itpp/comm/ldpc.h>`

Inheritance diagram for itpp::LDPC_Code:

## Public Member Functions

| LDPC_Code ()
| Default constructor.
| LDPC_Code (const LDPC_Parity *const H, LDPC_Generator *const G=0, bool perform_integrity_check=true)
| Constructor, from a parity check matrix and optionally a generator.
| LDPC_Code (const std::string &filename, LDPC_Generator *const G=0)
| Constructor, from a saved file.
virtual | ~LDPC_Code ()
| Destructor.
void | set_code (const LDPC_Parity *const H, LDPC_Generator *const G=0, bool perform_integrity_check=true)
| Set the codec, from a parity check matrix and optionally a generator.
void | load_code (const std::string &filename, LDPC_Generator *const G=0)
| Set the codec, by reading from a saved file.
void | save_code (const std::string &filename) const
| Save the codec to a file.
void | set_decoding_method (const std::string &method)
| Set the decoding method.
void | set_exit_conditions (int max_iters, bool syndr_check_each_iter=true, bool syndr_check_at_start=false)
| Set the decoding loop exit conditions.
void | set_llrcalc (const LLR_calc_unit &llrcalc)
| Set LLR calculation unit.
virtual void | encode (const bvec &input, bvec &output)
| Encode codeword.
virtual bvec | encode (const bvec &input)
| Encode codeword.
virtual void | decode (const bvec &, bvec &)
| Inherited from the base class - not implemented here.
virtual bvec | decode (const bvec &)
| Inherited from the base class - not implemented here.
virtual void | decode (const vec &llr_in, bvec &syst_bits)
| This function outputs systematic bits of the decoded codeword.
virtual bvec | decode (const vec &llr_in)
| This function outputs systematic bits of the decoded codeword.
void | decode_soft_out (const vec &llr_in, vec &llr_out)
| This function is a wrapper for `bp_decode()`
vec | decode_soft_out (const vec &llr_in)
| This function is a wrapper for `bp_decode()`
int | bp_decode (const QLLRvec &LLRin, QLLRvec &LLRout)
| Belief propagation decoding.
bool | syndrome_check (const QLLRvec &LLR) const
| Syndrome check, on QLLR vector.
bool | syndrome_check (const bvec &b) const
| Syndrome check, on bit vector.
QLLRvec | soft_syndrome_check (const QLLRvec &LLR) const
| Soft syndrome check.
double | get_rate () const
| Get the coderate.
int | get_nvar () const
| Get the number of variable nodes.
int | get_ncheck () const
| Get the number of check nodes.
int | get_ninfo () const
| Get the number of information bits per codeword.
std::string | get_decoding_method () const
| Return the decoding method.
int | get_nrof_iterations () const
| Get the maximum number of iterations of the decoder.
LLR_calc_unit | get_llrcalc () const
| Get LLR calculation unit used in decoder.

## Protected Member Functions

void | decoder_parameterization (const LDPC_Parity *const H)
| Function to compute decoder parameterization.
void | integrity_check ()
| Function to check the integrity of the parity check matrix and generator.
void | setup_decoder ()
| Initialize decoder.

## Friends

ITPP_EXPORT std::ostream & | operator<< (std::ostream &os, const LDPC_Code &C)
| Print some properties of the codec in plain text.

## Related Symbols

(Note that these are not member symbols.)
ITPP_EXPORT std::ostream & | operator<< (std::ostream &os, const LDPC_Code &C)
| Print some properties of the LDPC codec in plain text.

## Detailed Description

Low-density parity check (LDPC) codec.

This class provides the functionality for encoding and decoding of LDPC codes defined via `LDPC_Parity` and `LDPC_Generator` classes.

LDPC codecs are constructed from parity check and generator matrices. Since the procedure of constructing the codec can be time-consuming (for example, due to optimization of the parity matrix and computation of the generator matrix), codecs can be saved to a file for later use. This class provides functionality and a special file format (the file format is designed to optimize the operation of the decoder) to do this. Some examples of load and save operations follow:

Saving a codec without generator matrix:

// assume the parity matrix is already defined and stored in H
LDPC_Code C(&H);
C.save_code("filename.it");
itpp::LDPC_Code
Low-density parity check (LDPC) codec.
Definition ldpc.h:732

Saving a codec with generator matrix (for the example of systematic generator):

// assume the parity matrix is already defined and stored in H
LDPC_Generator_Systematic G(&H); // create generator
LDPC_Code C(&H, &G);
C.save_code("filename.it");
itpp::LDPC_Generator_Systematic
Systematic LDPC Generator class.
Definition ldpc.h:571

Loading a codec without a generator:

LDPC_Code("filename.it");
itpp::LDPC_Code::LDPC_Code
LDPC_Code()
Default constructor.
Definition ldpc.cpp:1206

Loading a codec with a generator (systematic in this example):

LDPC_Generator_Systematic G; // the generator object must be created first
LDPC_Code("filename.it", &G);

Note
  Please refer to the tutorials Generation of LDPC codes and Simulation of LDPC codes the AWGN channel for extensive examples of how to use LDPC codes.
  For issues relating to the accuracy of LLR computations, please see the documentation of `LLR_calc_unit`

Author
  Erik G. Larsson, Adam Piatyszek and Gorka Prieto (decoder improvements)

Definition at line 731 of file ldpc.h.

## Constructor & Destructor Documentation

## LDPC_Code() [1/3]

itpp::LDPC_Code::LDPC_Code | ( |  | ) |

Default constructor.

Definition at line 1206 of file ldpc.cpp.

References set_decoding_method().

## LDPC_Code() [2/3]

itpp::LDPC_Code::LDPC_Code | ( | const LDPC_Parity *const | H,
|  | LDPC_Generator *const | G = `0`,
|  | bool | perform_integrity_check = `true`
| ) |  |

Constructor, from a parity check matrix and optionally a generator.

This constructor simply calls `set_code()`.

Parameters

  H | The parity check matrix
  G | A pointer to the optional generator object
  perform_integrity_check | if true, then check that the parity and generator matrices are consistent

Definition at line 1210 of file ldpc.cpp.

References set_code(), and set_decoding_method().

## LDPC_Code() [3/3]

itpp::LDPC_Code::LDPC_Code | ( | const std::string & | filename,
|  | LDPC_Generator *const | G = `0`
| ) |  |

Constructor, from a saved file.

This constructor simply calls `load_code()`.

Definition at line 1220 of file ldpc.cpp.

References load_code(), and set_decoding_method().

## ~LDPC_Code()

virtual itpp::LDPC_Code::~LDPC_Code | ( |  | ) |

inlinevirtual

Destructor.

Definition at line 758 of file ldpc.h.

## Member Function Documentation

## set_code()

void itpp::LDPC_Code::set_code | ( | const LDPC_Parity *const | H,
|  | LDPC_Generator *const | G = `0`,
|  | bool | perform_integrity_check = `true`
| ) |  |

Set the codec, from a parity check matrix and optionally a generator.

Parameters

  H | The parity check matrix
  G | A pointer to the optional generator object
  perform_integrity_check | if true, then check that the parity and generator matrices are consistent

Definition at line 1230 of file ldpc.cpp.

References decoder_parameterization(), integrity_check(), it_info_debug, and setup_decoder().

Referenced by LDPC_Code().

## load_code()

void itpp::LDPC_Code::load_code | ( | const std::string & | filename,
|  | LDPC_Generator *const | G = `0`
| ) |  |

Set the codec, by reading from a saved file.

The file format is defined in the source code. LDPC codecs can be saved with the function `save_code()`.

Parameters

  filename | Name of the file where the codec is stored
  G | A pointer to the optional generator object

Note
  If `G` points at `0` (default), the generator data is not read from the saved file. This means that the encoding can not be performed.

Definition at line 1247 of file ldpc.cpp.

References itpp::it_ifile::close(), it_assert, it_info_debug, itpp::LDPC_binary_file_version, itpp::LDPC_Generator::load(), and setup_decoder().

Referenced by LDPC_Code().

## save_code()

void itpp::LDPC_Code::save_code | ( | const std::string & | filename | ) | const

Save the codec to a file.

Parameters

  filename | Name of the file where to store the codec

Note
  The decoder parameters (`max_iters`, `syndr_check_each_iter`, `syndr_check_at_start` and `llrcalc`) are not saved to a file.

Definition at line 1289 of file ldpc.cpp.

References itpp::it_file::close(), it_assert, it_info_debug, itpp::LDPC_binary_file_version, itpp::it_file::open(), and itpp::LDPC_Generator::save().

## set_decoding_method()

void itpp::LDPC_Code::set_decoding_method | ( | const std::string & | method | ) |

Set the decoding method.

Currently only a belief propagation method ("BP" or "bp") is supported.

Note
  The default method set in the class constructors is "BP".

Definition at line 1323 of file ldpc.cpp.

References it_assert.

Referenced by LDPC_Code(), LDPC_Code(), and LDPC_Code().

## set_exit_conditions()

void itpp::LDPC_Code::set_exit_conditions | ( | int | max_iters,
|  | bool | syndr_check_each_iter = `true`,
|  | bool | syndr_check_at_start = `false`
| ) |  |

Set the decoding loop exit conditions.

Parameters

  max_iters | Maximum number of the decoding iterations
  syndr_check_each_iter | If true, break the decoding loop as soon as valid codeword is found. Recommended value: `true`.
  syndr_check_at_start | If true, perform a syndrome check before entering the decoding loop. If LLRin corresponds to a valid codeword, set LLRout = LLRin. Recommended value: `false`.

Note
  The default values set in the class constructor are: "50", "true" and "false", respectively.

Definition at line 1330 of file ldpc.cpp.

References it_assert.

## set_llrcalc()

void itpp::LDPC_Code::set_llrcalc | ( | const LLR_calc_unit & | llrcalc | ) |

Set LLR calculation unit.

Definition at line 1341 of file ldpc.cpp.

## encode() [1/2]

void itpp::LDPC_Code::encode | ( | const bvec & | input,
|  | bvec & | output
| ) |  |

virtual

Encode codeword.

This is a wrapper functions which calls a proper implementation from the `LDPC_Generator` object.

Parameters

  input | Vector of `ncheck` input bits
  output | Vector of `nvar` output bits

Implements itpp::Channel_Code.

Definition at line 1347 of file ldpc.cpp.

References itpp::LDPC_Generator::encode(), it_assert, it_assert_debug, and syndrome_check().

Referenced by encode().

## encode() [2/2]

bvec itpp::LDPC_Code::encode | ( | const bvec & | input | ) |

virtual

Encode codeword.

Implements itpp::Channel_Code.

Definition at line 1356 of file ldpc.cpp.

References encode().

## decode() [1/4]

virtual void itpp::LDPC_Code::decode | ( | const bvec & | ,
|  | bvec & |
| ) |  |

inlinevirtual

Inherited from the base class - not implemented here.

Implements itpp::Channel_Code.

Definition at line 848 of file ldpc.h.

References it_error.

Referenced by decode().

## decode() [2/4]

virtual bvec itpp::LDPC_Code::decode | ( | const bvec & |  | ) |

inlinevirtual

Inherited from the base class - not implemented here.

Implements itpp::Channel_Code.

Definition at line 852 of file ldpc.h.

References it_error.

## decode() [3/4]

void itpp::LDPC_Code::decode | ( | const vec & | llr_in,
|  | bvec & | syst_bits
| ) |  |

virtual

This function outputs systematic bits of the decoded codeword.

Implements itpp::Channel_Code.

Definition at line 1363 of file ldpc.cpp.

References bp_decode(), itpp::Array< T >::left(), and itpp::LLR_calc_unit::to_qllr().

## decode() [4/4]

bvec itpp::LDPC_Code::decode | ( | const vec & | llr_in | ) |

virtual

This function outputs systematic bits of the decoded codeword.

Implements itpp::Channel_Code.

Definition at line 1371 of file ldpc.cpp.

References decode().

## decode_soft_out() [1/2]

void itpp::LDPC_Code::decode_soft_out | ( | const vec & | llr_in,
|  | vec & | llr_out
| ) |  |

This function is a wrapper for `bp_decode()`

Definition at line 1378 of file ldpc.cpp.

References bp_decode(), itpp::LLR_calc_unit::to_double(), and itpp::LLR_calc_unit::to_qllr().

Referenced by decode_soft_out().

## decode_soft_out() [2/2]

vec itpp::LDPC_Code::decode_soft_out | ( | const vec & | llr_in | ) |

This function is a wrapper for `bp_decode()`

Definition at line 1386 of file ldpc.cpp.

References decode_soft_out().

## bp_decode()

int itpp::LDPC_Code::bp_decode | ( | const QLLRvec & | LLRin,
|  | QLLRvec & | LLRout
| ) |  |

Belief propagation decoding.

This function implements the sum-product message passing decoder (Pearl's belief propagation) using LLR values as messages. A fast update mechanism is used for nodes with large degrees.

Parameters

  LLRin | vector of `nvar` input LLR values
  LLRout | vector of `nvar` output LLR values

If the decoder converged to a valid codeword, the function returns the number of iterations performed. Otherwise the function returns the number of iterations performed but with negative sign.

One can use `set_exit_conditions()` method to change the number of decoding iterations and related parameters parameters. The decoding function uses `LLR_calc_unit` to implement table-lookup for the Boxplus operator. By setting the parameters of the `LLR_calc_unit` provided in `set_llrcalc()`, one can change the resolution, for example to use a logmax approximation. See the documentation of `LLR_calc_unit` for details on how to do this.

Definition at line 1393 of file ldpc.cpp.

References itpp::LLR_calc_unit::Boxplus(), it_assert, it_error, it_info_debug, it_info_no_endl_debug, itpp::Array< T >::set_size(), itpp::Array< T >::size(), and syndrome_check().

Referenced by decode(), and decode_soft_out().

## syndrome_check() [1/2]

bool itpp::LDPC_Code::syndrome_check | ( | const QLLRvec & | LLR | ) | const

Syndrome check, on QLLR vector.

This function performs a syndrome check on a softbit (LLR vector). The function returns true for a valid codeword, false else.

Parameters

  LLR | LLR-vector to check

Definition at line 1642 of file ldpc.cpp.

Referenced by bp_decode(), encode(), integrity_check(), and syndrome_check().

## syndrome_check() [2/2]

bool itpp::LDPC_Code::syndrome_check | ( | const bvec & | b | ) | const

Syndrome check, on bit vector.

Definition at line 1636 of file ldpc.cpp.

References syndrome_check(), and itpp::to_ivec().

## soft_syndrome_check()

QLLRvec itpp::LDPC_Code::soft_syndrome_check | ( | const QLLRvec & | LLR | ) | const

Soft syndrome check.

This function checks all parity constraints and computes for each one the posterior probability that it is satisfied. The result is a vector, whose i:th element is given by

where

is the index of the j:th nonzero element of the i:th row of the code's parity check matrix.

Definition at line 1665 of file ldpc.cpp.

References itpp::LLR_calc_unit::Boxplus().

## get_rate()

double itpp::LDPC_Code::get_rate | ( | void |  | ) | const

inlinevirtual

Get the coderate.

Implements itpp::Channel_Code.

Definition at line 917 of file ldpc.h.

## get_nvar()

int itpp::LDPC_Code::get_nvar | ( |  | ) | const

inline

Get the number of variable nodes.

Definition at line 922 of file ldpc.h.

## get_ncheck()

int itpp::LDPC_Code::get_ncheck | ( |  | ) | const

inline

Get the number of check nodes.

Definition at line 925 of file ldpc.h.

## get_ninfo()

int itpp::LDPC_Code::get_ninfo | ( |  | ) | const

inline

Get the number of information bits per codeword.

Definition at line 928 of file ldpc.h.

## get_decoding_method()

std::string itpp::LDPC_Code::get_decoding_method | ( |  | ) | const

inline

Return the decoding method.

Definition at line 931 of file ldpc.h.

## get_nrof_iterations()

int itpp::LDPC_Code::get_nrof_iterations | ( |  | ) | const

inline

Get the maximum number of iterations of the decoder.

Definition at line 934 of file ldpc.h.

## get_llrcalc()

LLR_calc_unit itpp::LDPC_Code::get_llrcalc | ( |  | ) | const

inline

Get LLR calculation unit used in decoder.

Definition at line 937 of file ldpc.h.

## decoder_parameterization()

void itpp::LDPC_Code::decoder_parameterization | ( | const LDPC_Parity *const | H | ) |

protected

Function to compute decoder parameterization.

Definition at line 1687 of file ldpc.cpp.

References it_info_debug, itpp::length(), itpp::max(), and itpp::zeros_i().

Referenced by set_code().

## integrity_check()

void itpp::LDPC_Code::integrity_check | ( |  | ) |

protected

Function to check the integrity of the parity check matrix and generator.

Definition at line 1766 of file ldpc.cpp.

References itpp::LDPC_Generator::encode(), it_assert, it_info_debug, itpp::Array< T >::shift_right(), and syndrome_check().

Referenced by set_code().

## setup_decoder()

void itpp::LDPC_Code::setup_decoder | ( |  | ) |

protected

Initialize decoder.

Definition at line 1757 of file ldpc.cpp.

References itpp::max().

Referenced by load_code(), and set_code().

## Friends And Related Symbol Documentation

## operator<< [1/2]

ITPP_EXPORT std::ostream & operator<< | ( | std::ostream & | os,
|  | const LDPC_Code & | C
| ) |  |

friend

Print some properties of the codec in plain text.

Definition at line 1791 of file ldpc.cpp.

## operator<<() [2/2]

ITPP_EXPORT std::ostream & operator<< | ( | std::ostream & | os,
|  | const LDPC_Code & | C
| ) |  |

related

Print some properties of the LDPC codec in plain text.

Definition at line 1791 of file ldpc.cpp.

The documentation for this class was generated from the following files:

- itpp/comm/ldpc.h
- itpp/comm/ldpc.cpp

Generated on Mon Jun 10 2024 11:49:36 for IT++ by Doxygen 1.9.8