Communications Toolbox Release Notes

Upgrading from an Earlier Release

This section describes the upgrade issues involved in moving from the Communications Toolbox 2.0.1 to Version 2.1. This section discusses the following topics:

• Updating Existing Galois Field Code
• Updating Existing Reed-Solomon M-Code
• Changes in Functionality
• Obsolete Functions

If you are upgrading from a version earlier than 2.0.1, then you should see Upgrading from an Earlier Release of the Communications Toolbox 2.0 Release Notes.

Updating Existing Galois Field Code

If your existing code performs computations in Galois fields having 2^m elements, where m is an integer between 1 and 16, then you might want to update your code to use the new Galois field capabilities.

Replacing Functions

The table below lists Release 12 functions that correspond to Release 13 functions or operators acting on the new Galois field data type. Compared to the syntax of their Release 12 counterparts, the syntaxes of the Release 13 functions are different, but generally easier to use.

Release 12 Function	Release 13 Function or Operator	Comments
gfadd	+
gfconv	conv
gfcosets	cosets	cosets returns a cell array, whereas gfcosets returns a NaN-padded matrix.
gfdeconv	deconv
gfdiv	./
gffilter	filter	Unlike gffilter, filter also returns the final states.
gflineq	\
gfplus	+
gfprimck	isprimitive	isprimitive detects primitivity but not reducibility.
gfprimdf	primpoly
gfprimfd	primpoly
gfrank	rank
gfroots	roots	Unlike gfroots, roots indicates multiplicities of roots and can process polynomials in an extension field
gfsub	-
gftuple	.^, log, polyval	See Converting and Simplifying Formats Using R13 Galois Arrays for more details.

Converting Between Release 12 and Release 13 Representations of Field Elements

In some parts of your existing code, you might need to convert data between the exponential format supported in Release 12 and the new Galois array. The code example below performs such conversions on a sample vector that represents elements of GF(16).

• % Sample data
  m = 4; % For example, work in GF(2^4) = GF(16).
  a_r12 = [2 5 0 -Inf]; % GF(16) elements in exponential format
  
  % 1. Convert to the Release 13 Galois array.
  A = gf(2,m); % Primitive element of the field
  a_r13 = A.^(a_r12); % Positive exponents mean A to that power.
  a_r13(find(a_r12 < 0)) = 0; % Negative exponents mean zero.
  
  % 2. Convert back to the Release 12 exponential format.
  m = a_r13.m; A = gf(2,m);
  a_r12again = zeros(size(a_r13)); % Preallocate space in a matrix.
  zerolocations = find(a_r13 == 0);
  nonzerolocations = find(a_r13 ~= 0);
  a_r12again(zerolocations) = -Inf; % Map 0 to negative exponent.
  a_r12again(nonzerolocations) = log(a_r13(nonzerolocations));
  
  % Check that the two conversions are inverses.
  ck = isequal(a_r12,a_r12again)
  
  ck =
  
       1
  

Converting Between Release 12 and Release 13 Representations of Polynomials

Release 12 and Release 13 use different formats for representing polynomials over GF(2^m). Release 12 represents a polynomial as a vector of coefficients in order of ascending powers. Depending on the context, each coefficient listed in the vector represents either an element in a prime field or the exponential format of an element in an extension field. Release 13 uses the conventions described below.

Primitive polynomials..   The functions gf, isprimitive, and primpoly represent a primitive polynomial using an integer scalar whose binary representation lists the coefficients of the polynomial. The least significant bit is the constant term.

For example, the scalar 13 has binary representation 1101 and represents the polynomial D³ + D² + 1.

Other polynomials.   When performing arithmetic with, evaluating, or finding roots of a polynomial, or when finding a minimal polynomial of a field element, you represent the polynomial using a Galois vector of coefficients in order of descending powers. Each coefficient listed in the vector represents an element in the field using the representation described in How Integers Correspond to Galois Field Elements.

For example, the Galois vector gf([1 1 0 1],1) represents the polynomial x³ + x² + 1. Also, the Galois vector gf([1 2 3],3) represents the polynomial x² + Ax + (A+1), where A is a root of the default primitive polynomial for GF(2³). The coefficient of A+1 corresponds to the vector entry of 3 because the binary representation of 3 is 11.

Example Showing Conversions.   The code example below might help you determine how to convert between the Release 12 and Release 13 formats for polynomials.

• m = 3; % Work in GF(8).
  
  poly_r12 = [1 1 0 1]; % 1+x+x^3, ascending order
  poly_r13 = gf([1 0 1 1],m); % x^3+x+1 in GF(8), descending order
  
  % R12 polynomials
  pp_r12 = gfprimdf(m); % A primitive polynomial
  mp_r12 = gfminpol(4,m); % The minimal polynomial of an element
  rts_r12 = gfroots(poly_r12); % Find roots.
  
  % R13 polynomials
  pp_r13 = primpoly(m,'nodisplay'); % A primitive polynomial
  mp_r13 = minpol(gf(4,m)); % The minimal polynomial of an element
  rts_r13 = roots(poly_r13); % Find roots.
  
  % R12 polynomials converted to R13 formats
  % For primitive poly, change binary vector to decimal scalar.
  pp_r12_conv = bi2de(pp_r12);
  % For minimal poly, change ordering and make it a Galois array.
  mp_r12_conv = gf(fliplr(mp_r12));
  % For roots of polynomial, note that R12 answers are in
  % exponential format. Convert to Galois array format.
  rts_r12_conv = gf(2,m) .^ rts_r12;
  
  % Check that R12 and R13 yield the same answers.
  c1 = isequal(pp_r13,pp_r12_conv); % True.
  c2 = isequal(mp_r13,mp_r12_conv); % True.
  c3 = isequal(rts_r13,rts_r12_conv); % True.
  

Converting and Simplifying Formats Using R13 Galois Arrays

If your existing code uses gftuple to convert between exponential and polynomial formats, or to simplify one of these formats, then the code example below might help you determine how to perform those tasks using the Release 13 Galois array.

• % First define key characteristics of the field.
  m = 4; % For example, work in GF(2^4) = GF(16).
  A = gf(2,m); % Primitive element of the field
  
  % 1. Simplifying a Polynomial Format
  poly_big = 2^10 + 2^7;
  % Want to refer to the element A^10 + A^7. However,
  % cannot use gf(poly_big,m) because poly_big is too large.
  poly1 = A.^10 + A.^7 % One way to define the element.
  poly2 = polyval(de2bi(poly_big,'left-msb'),A); % Another way.
  % The results show that A^10 + A^7 equals A^3 + A^2 in this
  % field, using the binary representation of 12 as 1100.
  
  % 2. Simplifying an Exponential Format
  exp_big = 39;
  exp_simple = log(A.^exp_big) % Simplest exponential format.
  % The results show that A^39 equals A^9 in this field.
  
  % 3. Converting from Exponential to Polynomial Format
  expf1 = 7;
  pf1 = A.^expf1
  % The results show that A^7 equals A^3 + A + 1 in this
  % field, using the binary representation of 11 as 1011.
  
  % 4. Converting from Polynomial to Exponential Format
  pf2 = 11; % Represents the element A^3 + A + 1
  expf2 = log(gf(pf2,m))
  % The results show that A^3 + A + 1 equals A^7 in this field.
  

The output is below.

• poly1 = GF(2^4) array. Primitive polynomial = D^4+D+1 (19 decimal)
   
  Array elements = 
   
      12
  
  
  exp_simple =
  
       9
  
   
  pf1 = GF(2^4) array. Primitive polynomial = D^4+D+1 (19 decimal)
   
  Array elements = 
   
      11
  
  
  expf2 =
  
       7
  

Updating Existing Reed-Solomon M-Code

If your existing M-code processes Reed-Solomon codes, then you might want to update it to use the enhanced Reed-Solomon capabilities. Below are some important points to keep in mind:

• Use rsenc instead of rsenco, rsencode, and encode(...,'rs').
• Use rsdec instead of rsdeco, rsdecode, and decode(...,'rs').
• Use rsgenpoly instead of rspoly.
• rsenc and rsdec use Galois arrays for the messages and codewords. To learn more about Galois arrays, see Representing Elements of Galois Fields.
• rsenc and rsdec interpret symbols in a different way compared to the Release 12 functions. For an example showing how to convert between Release 12 and Release 13 interpretations, see Converting Between Release 12 and Release 13 Representations of Code Data.
• The Release 12 functions support three different data formats. The exponential format is most easily converted to the Release 13 format. To convert your data among the various Release 12 formats as you prepare to upgrade to the new Release 13 functions, see Converting Among Various Release 12 Representations of Coding Data.
• rsenc, rsdec, and rsgenpoly use a Galois array in descending order to represent the generator polynomial argument. The commands below indicate how to convert generator polynomials from the Release 12 format to the Release 13 format.

• n = 7; k = 3; % Examples of code parameters
  m = log2(n+1); % Number of bits in each symbol
  gp_r12 = rspoly(n,k); % R12 exponential format, ascending order
  gp_r13 = gf(2,m).^fliplr(gp_r12); % Convert to R13 format.
  

• rsenc places (and rsdec expects to find) the parity symbols at the end of each word by default. To process codes in which the parity symbols are at the beginning of each word, use the string 'beginning' as the last input argument when you invoke rsenc and rsdec.

Converting Between Release 12 and Release 13 Representations of Code Data

To help you update your existing M-code that processes Reed-Solomon codes, the example below illustrates how to encode data using the new rsenc function and the earlier rsenco function.

• % Basic parameters for coding
  m = 4; % Number of bits per symbol in each codeword
  t = 2; % Error-correction capability                                                    
  n = 2^m-1; k = n-2*t; % Message length and codeword length
  w = 10; % Number of words to encode in this example
  
  % Lookup tables to translate formats between rsenco and rsenc
  p2i = [0 gf(2,m).^[0:2^m-2]]; % Galois vector listing powers
  i2p = [-1 log(gf(1:2^m-1,m))]; % Integer vector listing logs
  
  % R12 method, exponential format
  % Exponential format uses integers between -1 and 2^m-2.
  mydata_r12 = randint(w,k,2^m)-1;
  code_r12 = rsenco(mydata_r12,n,k,'power'); % * Encode the data. *
  % Convert any -Inf values to -1 to facilitate comparisons.
  code_r12(isinf(code_r12)) = -1;
  code_r12 = reshape(code_r12,n,w)'; % One codeword per row
  
  % R12 method, decimal format
  % This yields same results as R12 exponential format.
  mydata_r12_dec = mydata_r12 + 1; % Convert to decimal.
  code_r12_dec = rsenco(mydata_r12_dec,n,k,'decimal'); % Encode.
  code_r12_dectoexp = code_r12_dec - 1; % Convert to exponential.
  c1 = isequal(code_r12,code_r12_dectoexp); % True.
  
  % R12 method, binary format
  % This yields same results as R12 exponential format.
  mydata_r12_bin = de2bi(mydata_r12_dec',m); % Convert to binary.
  code_r12_bin = rsenco(mydata_r12_bin,n,k,'binary'); % Encode.
  code_r12_bintoexp = reshape(bi2de(code_r12_bin),n,w)' - 1;
  c2 = isequal(code_r12,code_r12_bintoexp); % True.
  
  % R13 method
  mydata_r13 = fliplr(mydata_r12); % Reverse the order.
  % Convert format, using +2 to get in the right range for indexing.
  mydata_r13 = p2i(mydata_r13+2);
  code_r13 = rsenc(mydata_r13,n,k); % * Encode the data. *
  codeX = double(code_r13.x); % Retrieve data from Galois array.
  % Convert format, using +1 to get in the right range for indexing.
  codelogX = i2p(codeX+1);
  codelogX = fliplr(codelogX); % Reverse the order again.
  
  c3 = isequal(code_r12,codelogX) % True.
  
  c3 =
  
       1
  

Converting Among Various Release 12 Representations of Coding Data

These rules indicate how to convert among the exponential, decimal, and binary formats that the Release 12 Reed-Solomon functions support:

• To convert from decimal format to exponential format, subtract one.
• To convert from exponential format to decimal format, replace any negative values by -1 and then add one.
• To convert between decimal and binary formats, use de2bi and bi2de. The right-most bit is the most significant bit in this context.

The commands below illustrate these conversions.

• msgbin = randint(11,4); % Message for a (15,11) = (2^4-1, 11) code
  msgdec = bi2de(msgbin)'; % Binary to decimal
  msgexp = msgdec - 1; % Decimal to exponential
  codeexp = rsenco(msgexp,15,11,'power');
  codeexp(find(codeexp < 0)) = -1; % Use -1 consistently.
  codedec = codeexp + 1; % Exponential to decimal
  codebin = de2bi(codedec); % Decimal to binary
  

Changes in Functionality

The table below lists functions whose behavior has changed.

Function	Change in Functionality
wgn	The default measurement unit is the dBW, formerly documented as "dB." To specify this unit explicitly in the syntax, set the powertype input argument to 'dBW', not 'dB'. The output of the function is unaffected by this change in syntax.

Obsolete Functions

The table below lists functions that are obsolete. Although they are included in Release 13 for backward compatibility, they might be removed in a future release. The second column lists functions that provide similar functionality. In some cases, the similar function requires different input arguments or produces different output arguments, compared to the original function.

Function	Similar Function
gfplus	+ operator for Galois arrays
rsdeco	rsdec
rsdecode	rsdec
rsenco	rsenc
rsencode	rsenc
rspoly	rsgenpoly

Major Bug Fixes

Known Software and Documentation Problems