$Id: mimosim.txt,v 1.1 2004/08/16 22:22:04 miguel Exp miguel $ Documentation for Mimosim * Compilation To compile mimosim just type 'make'. Be sure to modify the Makefile to suit your needs and to specify any optimizations you'd want to use. 'make debug' will compile with -g, to enable debugging. * Results reporting The program creates a number of files in the directory ./results. These files contain details on the results of the simulation, power estimates, estimated BER and BLER, etc. * Debugging The debug functionality must be activated before compilation by changing the line #define debug 0 to #define debug 1 at the beginning of the file mimosim.c. When debug is defined, debugging code will be compiled. Undefine for faster run times. * Complexity In order to enable the complexity counters, change line 194 of mimosim.c from: #define xx if(1) to #define xx if(0) Complexity results are stored in file results/MxNy.com where x and y are the number of tx and rx antennas, respectively. * Parser commands Mimosim is configured via commands read from file mimosim.ini. These commands are described in what follows; default values are in parenthesis. Data type expected is indicated in brackets. Commands are case sensitive. Data types, ranges and syntax are not checked by the parser. A line that begins with something that is not a command is assumed to be a comment. -------- Debug (default = 0) [type = unsigned int] Sets debug mode. This mode writes certain internal variables to disk. The argument controls which variables are written. 0 - no debug 1 - activate SVD warnings when not meeting the tolerance. Output file: mimosim-svd.out 2 - print channel matrix and estimated channel matrix to file mimosim-h.out 4 - print received matrix to file mimosim.out 8 - print power estimates (noise and received signal) to file mimosim-power.out 16 - print coded matrix to mimosim.out 32 - print modulated matrix to mimosim.out 64 - print VBLAST variables to mimosim.out 128 - print calculated singular values to mimosim.out 256 - print information on errored bits to mimosim-err.out 512 - read data, noise and H info from data.out and noise.out instead of generating it randomly. This setting overrides any other setting that controls data, noise and H generation. 1024 - print mlreceiver matrices and data to mimosim.out 2048 - print lll data to mimosim.out 4096 - print matrices in pinv_vblast_formula To use more than one debug feature at a time, set the argument of Debug to the sum of the desired features. For example, to set SVD warnings and to print singular values, set the argument to 129. This command has no effect if compile-time define debug is not defined (see above). -------- ReceiverType (default = 0) [type = int] Specifies which receiver to use. 0 - use ML (Agrell algorithm) 1:4 - use VBLAST and variants 1: use svd 2: use formula 3: use thin qr decomposition 4: use qr decomposition with updates 5: use ls-blast (see CHANGELOG) 6: use v-sqr (see CHANGELOG) Receivers 1 and 2 work only if you have the needed functions from the book "Numerical Recipes in C". If you have these, then define NR_LICENSED when compiling. -------- ConstellationSymbolEnergy (default = 0.3162) [type = double] Specifies the energy of the constellation used. Its meaning depends on the constellation selected with parser command ConstellationType. For QAM constellations, the argument specifies the coordinates of the constellation point in the first quadrant that is closest to the origin. For example, the default value sets this point to (0.3162 + 0.3162j), which produces a QAM-16 constellation of average energy equal to 1. -------- ConstellationType (default = 0) [type = int] Specifies which constellation to use. 0 - QAM-16 --------- Lt (default = 4) [type = int] Specifies how many training symbols to send per block, per transmit antenna. It must be a number larger than 0 divisible by the number of bits per symbol selected through command ConstellationType. The program does not check that this is the case. The total number of training bits sent per block is: Lt * bits per symbol * tx antennas --------- L (default = 10) [type = int] Specifies how many information symbols to send per block, per transmit antenna. It must be a number larger than 0 divisible by the number of bits per symbol selected through command ConstellationType. The program does not check that this is the case. The number of bits sent per block is: L * bits per symbol * tx antennas --------- SourceType (default = 2) [type = int] Specifies the kind of information to transmit. 0 - all zeroes 1 - all ones 2 - random (uniform distribution) ---------- SourceSeed (default = 0) [type = integer] Specifies the seed used to generate the transmitted bits. 0 - random seed any other int - uses this number as seed. ---------- TransmitAntennas (default =8 ) [type = int] Specifies the number of transmit antennas. It must be equal to or less than the number of receive antennas. The program does not check that this is the case. ---------- ReceiveAntennas (default =8 ) [type = int] Specifies the number of transmit antennas. It must be equal to or larger than the number of receive antennas. The program does not check that this is the case. ---------- NoisePower (default = 20.0) [type = double] Specifies, in dB, the average SNR that should be present at the receiver. The average SNR is the total transmitted power divided by the power of the noise at each transmitter. ---------- NoiseSeed (default = 0) [type = int] Specifies the seed used to generate the channel noise. 0 - random seed any other int - uses this number as seed ---------- MatrixHComponentGen (default = 0) [type = int] Specifies how to create the channel matrix H. 0 - random entries 1 - Channel matrix is the identity matrix. Channel has no effect on signal. Should be used only on square (M=N) systems. ---------- HSeed (default = 0) [type = int] Specifies the seed used to generate the channel matrix H when the program is instructed to generate it randomly with command MatrixHComponentGen. 0 - random seed any other int - uses this number as seed ---------- MethodChannelEstimation (default = 0) [type = int] Specifies how to estimate the channel matrix H. 0 - reproduce channel matrix exactly from genie knowledge ---------- ChannelCode (default = 0) [type = int] Specifies which channel code to use. 0 - none ---------- TypeTrainingSeq (default = 0) [type = int] Specifies what kind of training sequence to send. 0 - alternating 1s and 0s ---------- NumberOfErrors (default = 1000) [type = integer] Sets the error threshold. If larger than 0, the simulation ends when the number of block errors detected passes this threshold. If set to 0, the simulation then runs for the number of frames specified by the command RunFrames. ---------- RunFrames (default = 0) [type = int] When NumberOfErrors is set to 0, the simulation runs for the number of frames specified by this command. ---------- DoLLL (default = 1) [type = int] If set to 1, do lll during ML decoding. If set to 0, skip the lll. ---------- CycleVblastTypes (default = 0) [type = int] When CycleVblastTypes is set to 1, the simulation is repeated for each different VBLast implementation. ---------- CycleLLL (default = 0) [type = int] When CycleLLL is set to 1, the simulation is repeated twice, one with DoLLL set to 0, and once with it set to 1. ---------- CycleL (default = 0) [type = int] LIterations (default = 1) [type = int] LStep (default = 10) [type = int] When CycleL is set to 1, the simulation is repeated LIterations times, each time increasing L by LStep. ---------- NIterations (default = 1) [type = int] NStep (default = 1) [type = int] The simulation is repeated NIterations times. The first time the SNR is set to that specified by the command NoisePower. Each subsequent run increments the SNR by the value specified by NStep. ----------- ScreenFeedback (default = 1) [type = int] Controls whether to output the current BLER to the screen each time a frame is simulated. * Simulating several cases in one run With the Cycle and NIterations commands several test cases can be run in one single command. For VBLast, it works like this: If CycleVblastTypes = 1, then repeat for each VBlast implementation If CycleL = 1, then repeat for L=10 and then L=100 Repeat NIterations times Run simulation For ML it works like this: If CycleLLL = 1, then repeat for DoLLL=1 and then DoLLL=0 If CycleL = 1, then repeat for L=10 and then L=100 Repeat NIterations times Run simulation * Constellations This section shows the configuration of the different constellations used by the program. The number in parenthesis is the symbol that corresponds to each constellation point. The position of the points is set through the ConstellationSymbolEnergy parser command. QAM-16 | X X --- X X (13) (9) | (8) (12) | | | X X --- X X (5) (1) | (0) (4) | | ---|------|------|------|------|--- | | | X X --- X X (7) (3) | (2) (6) | | | X X --- X X (15) (11) | (10) (14) * Matrix data format All matrix data types follow the convention of Numerical Receipes in C. Notable advantages of this convention are matrices that are defined from 1 to n instead of 0 to n-1, and the fact that element i,j of matrix A is addressed in a straightforward manner as A[i][j]. See section 1.2 of the book for details.