/srsRAN_matlab

MATLAB-based testing tools for the srsRAN Project https://github.com/srsran/srsRAN_Project

Primary LanguageMATLABBSD 2-Clause "Simplified" LicenseBSD-2-Clause

srsRAN-matlab

srsRAN-matlab, developed by SRS, provides a number of MATLAB-based tools for testing and benchmarking the srsRAN Project software.

Overview

The project includes utilities for generating the test vectors used for testing in the srsRAN Project, MEX wrappers of a number of srsRAN PHY components, end-to-end simulators, and analysis tools for the baseband captures obtained with the srsRAN gNB (see phy_rx_symbols_filename for how to obtain them).

For a better user experience, we suggest adding the root directory of srsRAN-matlab to the MATLAB search path

addpath path/to/srsran_matlab

License

For license details, see the LICENSE file.

Requirements

srsRAN-matlab runs on MATLAB and builds upon the 5G Toolbox (tested on MATLAB R2022a, R2022b and R2023a under Linux, but other recent releases should also work).

The srsRAN Project is required to build the MEX wrappers and to run the applications that include them (see the MEX section for further details).

Compatibility Table

The development of srsRAN-matlab closely follows all new features of the srsRAN Project. For this reason, it is important that you always use the latest version of both software: this is the only way to ensure that test vectors agree with the srsRAN API and that MEX binaries compile. The following compatibility table provides a list of reference commits on both repositories that are guaranteed to work together.

srsRAN-matlab srsRAN Project
0a235460 56a771df
3c050654 0112729f
73f47e3e bcb449d7
f38c2c32 583c92b1
80f4a105 5e6f50a2
068e472a e38e418b
62c459a2 55c984b5
62c459a2 dcd905cc
040c50b5 0b2702cc
842e0293 32dae89e
b37e6ee5 50fe9623
b93615b7 bcf941b3
85bb333e 4d9f2232
6a268a15 2f90c8b6
fe585a5a 1483bda3
1a81404d 78238fd1
2a6f71b2 f3ed07a5
0841ab86 c33cacba
52c07fbb 40b17b42
f6a11714 4cf7513e
a3bd2f8a 4ac5300d
d952d014 51e44a64
36fa859f ee1d86cd
36fa859f e73b4618
e5155ae9 9d5dd742
latest cda0033b

Contents

The repository is organized as follows.

  • Root directory: MATLAB classes for testing the srsRAN Project, see the Vector Tests section. This directory also contains the LICENSE, COPYRIGHT and README files.
  • +srsLib: MATLAB implementation of several NR blocks and functionalities, mostly wrappers around MathWorks 5G Toolbox classes and functions. The internal structure of this directory follows the organization of the lib directory in the srsRAN Project. The content of this directory is intended for expert users only. Using functions and classes from this directory is discouraged.
  • +srsMEX: MEX version of a number of srsRAN blocks. The corresponding C++ source files are located in +srsMEX/source. See the MEX section for more details.
  • +srsTest: Testing framework and utilities. The content of this directory is intended for expert users only. Using functions and classes from this directory is discouraged.
  • apps: End user applications, including simulators and analyzers. See the Apps section for more details.
  • unitTests: Repository CI/CD tools. The content of this directory is intended for expert users only.

Help

Please read this file for a general overview of the project and its features.

All classes and functions are documented and extensive information can be obtained by typing help ClassName at the MATLAB Command Window.

For support requests and community announcements, please use the srsRAN Project Discussion Board with the category "srsRAN-matlab".

Test Vectors

The classes in the root folder can be used to generate test vectors (a header file and, typically, a tarball file containing the vectors) for the srsRAN Project (see the last paragraph of the Build Instructions).

Call runSRSRANUnittest with the testvector tag to generate the set of test vectors of all supported blocks with the command:

runSRSRANUnittest('all', 'testvector')

To generate the test vectors for a specific block, for instance pbch_encoder, simply run the command:

runSRSRANUnittest('pbch_encoder', 'testvector')

All generated files will be automatically placed in a directory named testvector_outputs. They can be copied to the proper subfolders inside the srsRAN Project folder with

srsTest.copySRStestvectors('testvector_outputs', 'path/to/srsRAN_Project')

Customizing Tests

The classes in the root directory define the tests following the MATLAB class-based testing framework. As a result, all the tools from the framework can be used to run and customize the tests. For instance, the following code will run the pdcch_candidates_common tests only for a subset of values of the numCCEs parameter.

% Select the block to test.
testedBlock = ?srsPDCCHCandidatesCommonUnittest;
% Test only for numCCEs = {24, 72}. By default, the test uses {24, 48, 72, 96, 120, 144}.
extParams = matlab.unittest.parameters.Parameter.fromData('numCCEs', {24, 72});
% Create a test suite.
vecTest = matlab.unittest.TestSuite.fromClass(testedBlock, 'ExternalParameters', extParams);
% Run the tests.
results = vecTest.run;

MEX

The directory +srsMEX contains MEX versions of a number of classes and functions from the srsRAN Project. Typically, MEX can be accessed as class methods for a better user experience: for instance, the class srsMEX.phy.srsPUSCHDecoder provides access to the MEX version of the srsRAN pusch_decoder.

Building the MEX

The following steps are needed to compile MEX binaries.

  1. Export the srsRAN libraries: clone a local copy of the srsRAN Project (if not done already) and generate the CMake project with the -DENABLE_EXPORT=True option. This creates the file srsran.cmake in your srsRAN binary folder (that is, the folder at the top level of CMake build tree).

  2. Build the srsRAN Project: Follow the instructions in the srsRAN Project repository. You can use the target srsran_exported_libs to compile only the libraries needed by srsRAN-matlab and reduce compilation time.

  3. Generate the CMake project: In your local copy of srsRAN-matlab, do the following:

    cd +srsMEX/source
mkdir build
cd build
cmake ..

    If the path to your srsran.cmake file matches the patterns ~/srsRAN_Project/{build,build*,cmake-build-*}/srsran.cmake, ~/*/srsRAN_Project/{build,build*,cmake-build-*}/srsran.cmake or ~/*/*/srsRAN_Project/{build,build*,cmake-build-*}/srsran.cmake, running CMake should find the exported libraries automatically. If this doesn't happen or if you have multiple copies of srsRAN on your machine, you should specify the path when running CMake.

    cmake -DSRSRAN_BINARY_DIR="~/new_srsran/new_build" ..

    Similarly, you can use the CMake option Matlab_ROOT_DIR if you have multiple versions of MATLAB on your machine or if MATLAB is not in your system path.

    cmake -DMatlab_ROOT_DIR="/usr/local/MATLAB/R2023a" ..

  4. Build the MEX: Simply run make to build the MEX binaries, which will be automatically placed in the proper folder to be accessed from the srsMEX library.

    Run make doxygen to build extra documentation, which can be accessed from +srsMEX/source/build/docs/html/index.html.

    Depending on your setup, you may need to instruct MATLAB to use the system libraries instead of the internal ones: do the following and (re)start MATLAB.

    cd /usr/local/MATLAB/R2023a/sys/os/glnxa64
sudo mv libstdc++.so.6 libstdc++.so.6.bak

The examples in this section assume you have MATLAB R2023a installed in the typical path /usr/local/MATLAB/R2023a/. For other MATLAB releases or paths, adapt the examples accordingly.

Testing the MEX

Call runSRSRANUnittest with the testmex tag to test the MEX. This command runs the same code as with the testvector tag but sends the generated vectors directly to the MEX instead of writing them on file.

runSRSRANUnittest('all', 'testmex')

Apps

The folder apps contains a number of applications and examples that use tools of the srsRAN-matlab project. Before running them, remember to add the main srsRAN-matlab folder to the MATLAB search path.

apps/simulators/PUSCHBLER

An instance of the PUSCHBLER class provides a simulator object for PUSCH BLER and throughput evaluation. The following example shows how to evaluate BLER and throughput at SNR = -6:0.2:-4 dB for the default configuration. For more information, enter help PUSCHBLER at the MATLAB command line.

sim = PUSCHBLER       % Create a PUSCHBLER object.
sim(-6:0.2:-4)        % Run the simulation.
sim.ThroughputMATLAB  % Display the evaluated throughput.
sim.plot              % Plot the evaluated throughput and BLER vs SNR.
save my_sim.mat sim   % Save the PUSCHBLER object, including the simulation results,
                      % to file my_sim.mat.

Function combinePUSCHSims can be used to obtain a summary of several simulation results in graphic and table formats. For instance, the following command will draw the BLER and throughput curves from the PUSCHBLER objects saved in files my_sim1.mat and my_sim2.mat, as well as creating two tables, namely tableS and tableM, with the main simulation results using the SRS and MATLAB PUSCH decoder, respectively.

[tableS, tableM] = combinePUSCHSims(["my_sim1.mat", "my_sim2.mat"])

See help combinePUSCHSims for more details.

apps/simulators/PUCCHBLER

An instance of the PUCCHBLER class provides a simulator object for the evaluation of the performance (in terms of BLER, detection and false detection probability, depending on the case) of the PUCCH processors, for PUCCH Formats 0, 1 and 2. The following example shows how to evaluate the PUCCH Format 2 BLER at SNR = -10:0 dB for the default configuration. For more information, enter help PUCCHBLER at the MATLAB command line.

sim = PUCCHBLER           % Create a PUCCHBLER object.
sim(-10:10)               % Run the simulation.
sim.BlockErrorRateMATLAB  % Display the evaluated BLER.
sim.plot                  % Plot the evaluated BLER.
save my_sim.mat sim       % Save the PUCCHBLER object, including the simulation results,
                          % to file my_sim.mat.

apps/simulators/PRACHPERF

An instance of the PRACHPERF class provides a simulator object for the evaluation of the PRACH probability of detection and of false alarm. The following example show how to evaluate the probability of PRACH detection at SNR = -6:0.2:-4 dB for the default configuration. For more information, enter help PRACHPERF at the MATLAB command line.

sim = PRACHPERF           % Create a PRACHPERF object.
sim(-26:0.5:-20)          % Run the simulation.
sim.ProbabilityDetection  % Display the evaluated detection probability.
sim.plot                  % Plot the evaluated detection probability.
save my_sim.mat sim       % Save the PRACHPERF object, including the simulation results,
                          % to file my_sim.mat.

apps/analyzers/srsParseLogs

This app parses a section of the logs generated by the srsRAN gNB and returns carrier and channel (either PUSCH or PUCCH) configuration objects to be fed to one of the analyzers below (srsPUSCHAnalyzer or srsPUCCHAnalyzer). See the Configuration Parameters Section of the srsRAN Project documentation for information on how to configure the logging level of the SRS gNB to record the received samples.

See help srsParseLogs for more details.

apps/analyzers/srsPUSCHAnalyzer

This app analyzes a PUSCH transmission from the baseband complex-valued samples corresponding to one slot, as received by the gNB. See the Configuration Parameters Section of the srsRAN Project documentation for information on how to configure the logging level of the SRS gNB to record the received samples.

See help srsPUSCHAnalyzer for more details.

apps/analyzers/srsPUCCHAnalyzer

This app analyzes a PUCCH (Formats 1 or 2) transmission from the baseband complex-valued samples corresponding to one slot, as received by the gNB. See the Configuration Parameters Section of the srsRAN Project documentation for information on how to configure the logging level of the SRS gNB to record the received samples.

See help srsPUCCHAnalyzer for more details.

apps/analyzers/srsPRACHAnalyzer

This app analyzes a PRACH transmission from the baseband complex-valued samples corresponding to one PRACH occasion, as received by the gNB. See the Configuration Parameters Section of the srsRAN Project documentation for information on how to configure the logging level of the SRS gNB to record the received samples.

See help srsPRACHAnalyzer for more details.

apps/analyzers/srsResourceGridAnalyzer

This app displays the content of a resource grid (all subcarriers and one slot) as a heat map of the resource element amplitudes. See the Configuration Parameters Section of the srsRAN Project documentation for information on how to configure the logging level of the SRS gNB to record the received samples.

See help srsResourceGridAnalyzer for more details.

Repository CI/CD

CheckTests.m

The class unitTests/CheckTests implements a series of checks to provide a basic level of quality assurance for the unit tests in the root folder.

These checks have been designed mainly for automatic CI/CD procedures. Nevertheless, they can be executed locally by running the following commands from the srsRAN-matlab root folder.

addpath .
runtests("unitTests/CheckTests.m")

CheckSimulators.m

The class unitTests/CheckSimulators carries out short runs of the simulators in the Apps folder to ensure their functioning.

These checks have been designed mainly for automatic CI/CD procedures. Nevertheless, they can be executed locally by running the following commands from the srsRAN-matlab root folder.

addpath .
runtests("unitTests/CheckSimulators.m")

CheckAnalyzers.m

The class unitTests/CheckAnalyzers carries out a demo run of the analyzers in the Apps folder to ensure their functioning.

These checks have been designed mainly for automatic CI/CD procedures. Nevertheless, they can be executed locally by running the following commands from the srsRAN-matlab root folder.

addpath .
runtests("unitTests/CheckAnalyzers.m")

Conformance Tests

The classes CheckPUSCHConformance, CheckPUCCHF0Conformance, CheckPUCCHF1Conformance and CheckPUCCHF2Conformace run a set of conformance tests (as defined in TS38.104 and TS38.141) of the corresponding PHY channel receivers.

These checks have been designed mainly for automatic CI/CD procedures. Nevertheless, they can be executed locally by running the following commands from the srsRAN-matlab root folder (be aware that these tests may run for several hours).

addpath .
runtests("unitTests/CheckPUSCHConformance.m")
runtests("unitTests/CheckPUCCHF0Conformance.m")
runtests("unitTests/CheckPUCCHF1Conformance.m")
runtests("unitTests/CheckPUCCHF2Conformance.m")