Robert Schmidt
b7cb74699d
Change signature of the macro to take the full test name, a separate description (previously called a label?), and the executable and test invocation. The overall signature becomes easier. The rational for the full test name is that a later commit will introduce the possibility to define physim tests that are checked for specific times, in which case we need to reuse the test name. Thus, using the full name from the beginning leads to more clarity, even though they are a bit longer. Add an additional safety check that the given simulator is actually a target defined within the project (in other words, it actually exists). Update the documentation correspondingly.
5.6 KiB
Physical Simulators ("Physims") User Guide
This document provides an overview and usage guide for the physical simulators, also referred to as unitary simulators or simply physims, used in the OpenAirInterface (OAI) project for LTE and 5G PHY layer validation.
[[TOC]]
Introduction
Unitary simulations are standalone test programs designed to validate individual physical layer (L1) transport or control channels. These simulations are based on Monte Carlo techniques, enabling statistical evaluation of performance metrics such as block error rate (BLER), hybrid automatic repeat request (HARQ) throughput, and decoding accuracy under various signal conditions.
Physims are essential for:
- Debugging and evaluating new PHY code in isolation
- Regression testing
- Ensuring correctness before merging new contributions into the repository
Examples of Simulators
| Technology | Simulators | Description |
|---|---|---|
| 4G LTE | dlsim, ulsim |
Downlink and uplink simulators |
| 5G NR | nr_dlsim, nr_ulsim |
Downlink and uplink simulators |
nr_dlschsim, nr_ulschsim |
HARQ and TB throughput tests | |
nr_pucchsim |
Control channel simulation | |
nr_pbchsim |
Broadcast channel simulation | |
nr_prachsim |
PRACH simulation | |
nr_psbchsim |
Sidelink simulation | |
| Coding | ldpctest, polartest, smallblocktest |
LDPC, Polar, and other FEC tests |
Source Locations
- 4G PHY simulators:
openair1/SIMULATION/LTE_PHY/ - 5G PHY simulators:
openair1/SIMULATION/NR_PHY/ - Coding unit tests:
openair1/PHY/CODING/TESTBENCH/
Example:
# 5G Downlink simulator
openair1/SIMULATION/NR_PHY/dlsim.c
How to Run Simulators Using ctest
Option 1: Using CMake
cd openairinterface5g
mkdir build && cd build
cmake .. -GNinja -DENABLE_PHYSIM_TESTS=ON
ninja tests
ctest
Option 2: Using the build_oai script
This method simplifies the process by automatically building the simulators with ctest support.
cd openairinterface5g/cmake_targets
./build_oai --ninja --phy_simulators
cd ran_build/build
ctest
ctest Usage Tips
Useful Options
Use the following options to customize test execution:
| Option | Description |
|---|---|
-R <regex> |
Run tests matching the regex pattern (by name) |
-L <regex> |
Run tests with labels matching the regex pattern |
-E <regex> |
Exclude tests matching the regex pattern (by name) |
-LE <regex> |
Exclude tests with labels matching the regex pattern |
--print-labels |
Display all available test labels |
-j <jobs> |
Run tests in parallel using specified number of jobs |
For the complete list of ctest options, refer to the manual:
man ctest
Example
# Run only NR ULSCH simulator tests, in parallel
ctest -L nr_ulsch -j 4
Adding a New Physim Test
To define a new test or modify existing ones, update the following file:
openair1/SIMULATION/tests/CMakeLists.txt
Use the add_physim_test() macro with the following arguments:
add_physim_test(<test_name> <test_description> <test_exec> <test_options>)
where:
<test_name>can be any name, but the canonical, historical format is to put itphysim.<gen>.<test_exec>.test<XYZ>where<gen>is 4g/5g, and<XYZ>is an increasing number<test_description>is a human-readable description of the test<test_exec> <test_options>is the test invocation, where<test_exec>must be a target built by OAI cmake (e.g.,nr_prachsim), followed by any options.
For instance, a PRACHsim looks like this:
add_physim_test(physim.5g.nr_prachsim.test8 "15kHz SCS, 25 PRBs" nr_prachsim -a -s -30 -n 300 -p 99 -R 25 -m 0)
These tests are run automatically as part of the following pipelines: RAN-PhySim-Cluster-4G and RAN-PhySim-Cluster-5G
How to rerun failed CI tests using ctest
Ctest automatically logs the failed tests in LastTestsFailed.log. This log is archived in the CI artifacts and can be reused locally to rerun only those failed tests.
# 1. Navigate to the build directory, build physims
cd ~/openairinterface5g/build
cmake .. -GNinja -DENABLE_PHYSIM_TESTS=ON && ninja tests
# 2. Create ctest directory structure
ctest -N --quiet
# 3. Unzip the test logs artifact from the CI run
unzip /path/to/test_logs_123.zip
# 4. Copy the LastTestsFailed.log file to the expected location
cp /path/to/test_logs_123/test_logs/LastTestsFailed.log ./Testing/Temporary/
# 5. Rerun only the failed tests using ctest
ctest --rerun-failed
Legacy Bash Autotest (Deprecated)
Note: Autotest script, configuration, and documentation, are no longer maintained.
For legacy support or archival purposes, you can still find this implementation by checking out the historical tag:
git checkout 2025.w18
Unmaintained tests
A few tests dedicated to 4G are unmaintained:
mbmssimscansim- all simulators of format
www-tmyyyy(for instance,dlsim_tm4)