Add documentation for physical simulators

doc/physical-simulators.md

@@ -0,0 +1,135 @@
+This document describes the physical simulators, also called "unitary
+simulators", or short "physims".
+
+[[_TOC_]]
+
+# Introduction
+
+There are several unitary simulations for the physical layer, testing
+individual L1 transport/control channels using Monte-Carlo simulations, for
+instance:
+
+- `nr_pucchsim` for 5G PUCCH,
+- `nr_dlsim` for 5G DLSCH/PDSCH,
+- `nr_prachsim` for 5G PRACH,
+- `dlsim` for 4G DLSCH/PDSCH, etc.
+
+These simulators constitute the starting point for testing any new code in the
+PHY layer, and are required tests to be performed before committing any new
+code to the repository, in the sense that all of these should compile and
+execute correctly. They provide estimates of the transport block error rates
+and HARQ thoughput, DCI error rates, etc. The simulators reside in
+`openair1/SIMULATION/LTE_PHY` and `openair1/SIMULATION/NR_PHY`. For instance,
+`nr_dlsim` is built from `openair1/SIMULATION/NR_PHY/dlsim.c`.
+
+Further unitary simulation of the coding subsystem components also exists in
+`openair1/PHY/CODING/TESTBENCH`, e.g., `ldpctest` for encoding/decoding of
+LDPC.
+
+These are the simulators known to work properly and tested in CI:
+- 4G: `dlsim`, `ulsim`
+- 5G: `nr_dlsim`, `nr_ulsim`, `nr_dlschsim`, `nr_ulschsim`, `ldpctest`,
+  `nr_pbchsim`, `nr_prachsim`, `nr_pucchsim`, `polartest`, `smallblocktest`,
+  `nr_psbchsim` (sidelink)
+
+# How to run
+
+You first have to build simulators:
+
+```bash
+cd openairinterface5g/
+. oaienv                 # important for the run_exec_autotests.bash script
+cd cmake_targets/
+./build_oai --ninja -P
+```
+
+This builds the simulators in the default build directory `ran_build/build`
+(all paths given here are relative to `cmake_targets/` in the root of
+`openairinterface5g/`). To run all simulators in this default build directory
+of above `build_oai` invocation, run the `run_exec_autotests.bash` script:
+```bash
+autotests/run_exec_autotests.bash
+```
+
+This runs all simulations as defined in `autotests/test_case_list.xml`.
+
+To run a group of tests, you can specify the group using `-g`. You can also
+specify the build directory, after building the simulators, which, for the
+default directory, is:
+
+```bash
+autotests/run_exec_autotests.bash -g "nr_dlsim.basic" -d ran_build/build/
+```
+
+This will run the `nr_dlsim.basic` group, as listed in
+`autotests/test_case_list.xml`.
+
+## How to interpret the output
+
+From the output, you can see the invoked tests, its parameters, and the log files.
+Example:
+
+```
+[user@oai cmake_targets]$ autotests/run_exec_autotests.bash -g "nr_dlsim.basic" -d ran_build/build/
+[...]
+Test case nr_dlsim.basic match found in group
+name = nr_dlsim.basic
+Description = nr_dlsim Test cases. (Test1: 106 PRB),
+                                 (Test2: 217 PRB),
+                                 (Test3: 273 PRB),
+                                 (Test4: HARQ test 25% TP 4 rounds),
+                                 (Test5: HARQ test 33% TP 3 rounds),
+                                 (Test6: HARQ test 50% TP 2 rounds),
+                                 (Test7: 25 PRBs, 15 kHz SCS)
+main_exec = ran_build/build//nr_dlsim
+main_exec_args = -n100 -R106 -b106 -s5
+                      -n100 -R217 -b217 -s5
+                      -n100 -R273 -b273 -s5
+                      -n100 -s1 -S2 -t25
+                      -n100 -s1 -S2 -t33
+                      -n100 -s5 -S7 -t50
+                      -n100 -m0 -e0 -R25 -b25 -i 2 1 0
+search_expr_true = PDSCH test OK
+search_expr_false = segmentation fault|assertion|exiting|fatal
+tags = test1 test2 test3 test4 test5 test6 test7
+nruns = 3
+i = PDSCH test OK
+Test1: 106 PRB
+Executing test case nr_dlsim.basic.test1, Run Index = 1, Execution Log file = /home/oai/openairinterface5g/cmake_targets/autotests/log/nr_dlsim.basic/test.nr_dlsim.basic.test1.run_1
+Executing test case nr_dlsim.basic.test1, Run Index = 2, Execution Log file = /home/oai/openairinterface5g/cmake_targets/autotests/log/nr_dlsim.basic/test.nr_dlsim.basic.test1.run_2
+Executing test case nr_dlsim.basic.test1, Run Index = 3, Execution Log file = /home/oai/openairinterface5g/cmake_targets/autotests/log/nr_dlsim.basic/test.nr_dlsim.basic.test1.run_3
+[...]
+nr_dlsim.basic.test1 RUN = 1 Result = PASS
+nr_dlsim.basic.test1 RUN = 2 Result = PASS
+nr_dlsim.basic.test1 RUN = 3 Result = PASS
+execution nr_dlsim.basic.test1 {Test1: 106 PRB} Run_Result = " Run_1 =PASS Run_2 =PASS Run_3 =PASS"  Result = PASS
+```
+
+You see:
+- the `Description` of the test cases (here, 7 tests)
+- the executable that is used, and the parameters (`main_exec` and
+  `main_exec_args`), for instance `-n100 -R106 -b106 -s5` for `Test1`
+- what is the condition for a successful test
+- where are the log files
+- if the tests passed or not `PASS`, otherwise `FAIL` and a summary for the
+  three runs.
+
+## How to change the parameters
+
+You can modify the parameters in `autotests/test_case_list.xml`. To learn about
+their meaning, run the simulator manually with flag `-h` ("help"). For
+instance, for the above run, it would be
+
+```bash
+ran_build/build/nr_dlsim -h
+```
+
+## How to change the code
+
+You can modify the source files to adapt to your needs. For instance, for
+`nr_dlsim` above, refer to file `openair1/SIMULATION/NR_PHY/dlsim.c`.
+
+# CI
+
+These tests are run in this pipeline:
+[RAN-PhySim-Cluster](https://jenkins-oai.eurecom.fr/job/RAN-PhySim-Cluster/).