openairinterface5g/doc/physical-simulators.md

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/PHY/CODING/tests/CMakeLists.txt

Use the add_physim_test macro with the following arguments:

add_physim_test(<test_gen> <test_exec> <test_description> <test_label> <test_cl_options>)

Arguments:

• <test_gen>: Test generation (e.g., 4g or 5g)
• <test_exec>: Name of the test executable (e.g., nr_prachsim)
• <test_description>: Description shown in ctest output, useful for categorization and indexing.
• <test_label>: Label used for filtering tests (via -L), shown in the ctest output summary as a descriptive tag.
• <test_cl_options>: Command line options passed to the test

Example:

# add_physim_test(<test_gen> <test_exec> <test_description> <test_label> <test_cl_options>)
add_physim_test(5g nr_prachsim test8 "15kHz SCS, 25 PRBs" -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