Skip to content

Tutorials

The following exercises must be done in order and are designed to gradually introduce you to the simulation tool. They only cover the "user" side of the tool, i.e., configuration and result analysis.

All scenarios are located in Simulations/Tutorial/.

Ex1 — First Exploration (1 sat - 1 term - 1 GS)

Story: Your university wants to deploy a terminal and a ground station on its campus, and launch a CubeSat. You have been assigned to this simulation task. However, it seems like someone has tampered with the parameters…

This scenario is located in Simulations/Tutorial/01-First_Exploration. In this scenario, we have only one satellite, one terminal, and one ground station.

For this first example, we will study only a single visibility window to understand how simulations work.

1. Packet transmission

Open the Scenarios.ini file and try to understand:

  • How many repetitions are made for each packet
  • What the packet generation scheme is
  • How the ground station and terminal are positioned
  • …

Once you have this information in mind, you can find it again in the simulation logs. To do so, launch a simulation and run it in the classic "with full animation" mode. You will see the logs scrolling at the bottom. When packets are sent, you will find all the information about them there.

2. Packet reception

I suggest playing a bit with the parameters to understand how they work. If you are curious, there are many more in the main file First_Exploration.ini.

With the default parameters, you will notice that packets do not reach their destination. By reading the information available in the simulation logs, try to understand what is wrong. To help you, there are 2 steps in the reception process:

  • When a packet starts arriving at the satellite, its C/N0 is computed and compared to a threshold. If the value is below it, the packet is immediately rejected.
  • When the reception ends, the PER of the packet is computed, which gives the probability that the packet is received… or not.

Both steps are closely related, and since the PER does not depend on C/N0 in this example, the only option is to lower the threshold to accept all packets. However, let's try setting a threshold of around 29 dB-Hz, then increase the transmission power to get packets through.

3. Result analysis

Once you have run the simulation, you can analyze the results to understand how the parameters influence network performance. You do not have to produce a graph for these results, but spend some time in the results menu to understand how the different metrics are computed and how they evolve as a function of the parameters you changed. Ask questions if anything is unclear!

4. Playing with the MAC layer

I now suggest starting to play with the Blind transmission parameters. Try increasing the number of repetitions, the number of generated packets, etc. Then spend some time looking at the results to check whether all the packets you sent were received, among other things. To do so, look for the parameters Ntx and timeToNextPacket. You will see that one belongs to the MAC layer and the other to the APP layer.

Ex2 — A Constellation (X sats - 1 term - X GS)

Story: After the successful launch of your CubeSat, you are hired by a SatCom company to perform performance analysis. Your budget is limited, so you would like to know the average coverage a terminal would have with your constellation if deployed in Toulouse.

This scenario is located in Simulations/Tutorial/02-First_Constellation. In this scenario, we have a deployed constellation and a distribution of ground stations.

0. Importing constellation files

Use the Iridium constellation import (already provided in the tool) as a reference and import your own constellation. Do the same for the ground stations, following the same model.

1. Parameter verification

Before every simulation run, always verify which parameters are being used. Reuse the configuration files from Exercise 1 to maintain consistency with the work already done.

Place a terminal in Toulouse. Note that longitude has little impact on visibility — latitude is what matters. You can try several latitudes to understand how average visibility evolves with latitude.

2. Parameter choices

To answer the problem, the right parameter choices must be made, especially for packet generation. Generating one packet per second lets you see that average coverage can look good, but it does not mean that a terminal can send a packet at any moment and expect that average coverage to hold. On the other hand, generating one packet per minute can give the impression that visibility is poor, when that is not necessarily the case.

In our case, we are interested in average visibility. I suggest generating one packet per second to observe the average terminal coverage.

A small tip: do not set the simulation time too long, even though in this case it should not cause too many issues. But do not set it too short either, otherwise you will not have enough data for a meaningful analysis. I recommend 1 day of simulation time (i.e., 86400 seconds).

3. Getting started with the analysis tool

While the simulations are running, open the simulation_analysis folder. In practice, each metric can be used in many ways to achieve our goals. For example, you can save the delay of packets received at the satellite and count the number of elements in that vector to get the number of received packets, which you can then compare to the number of sent packets.

The analysis tool (.ipynb) needs .csv files. To get them, run the Python script (simulation_analysis/Tutorial/02-First_Constellation/00-exportMultiCpu.py), which will export the simulation results into .csv files. Make sure to update the path to point to the correct results folder.

To launch the notebook (from the 02-First_Constellation folder):

jupyter lab .

4. Understanding the results

Depending on the latitudes you chose for your analysis, you can compare visibility and understand to what extent it holds for shorter or longer time windows. If the "time step" is 30 min, it means the simulation was split into 30-min periods, and the ratio of received to sent packets was computed for each period and then averaged. You can modify the post-processing to get data for 2 h, 2 h 30 min, or even 10 min windows (depending on the simulated duration).

Depending on the chosen latitude, the same packet may be received by several satellites (multiple satellites in view at once). This is not a problem, as the algorithm looks at all received packets and identifies gaps in visibility.

Almost any analysis can be performed from this data. I also added a PDF and CDF plot of visibility windows, just to show what is possible. This is mainly because the recorded vectors also contain the time at which packets were received, which enables very detailed temporal analyses.

Note the difference between the collected statistics. In particular, "expected" packets have been recorded, which correspond to packets that could have been received at a given elevation angle but did not necessarily pass all conditions to be effectively received.

You are starting to understand that a metric means nothing on its own — it depends on how you use it. The most important thing is to always understand exactly what it represents, but be careful not to over-interpret it either :)

The goal of this exercise was not specifically to understand that you can simulate a constellation to get average visibility, but rather to realize the possibilities of the tool in terms of modeling and simulation. It shows that the same metric can be analyzed in different ways depending on the context.

Ex3 — MAC Layer Optimization (X sats - 10 terms - X GS)

Story: Your manager has become more demanding. He wants a performance analysis at a global scale. Your goal is to impress him by finding the number of repetitions needed to reach 95% packet reception in Blind mode at different latitudes.

This scenario is located in Simulations/Tutorial/03-BlindOptimization.

0. Parameter verification

Once again, copy the parameters from the previous exercises to maintain continuity. Make sure everything is properly adapted.

1. Placing terminals to answer the problem

You have 2 ways to place terminals to address the problem. Either run a single simulation with x terminals placed at different latitudes with collisions disabled, or run x simulations with 1 terminal each and run them in parallel. Note that the data processing approach differs between the two. I suggest using option 2.

2. Setting up simulation batches

To understand how to create simulation batches, here are a few key points:

  • ${<name>= values} creates a series of configurations to test different parameter values.
  • ${name1= values ! name2} pairs each value of name1 with the corresponding value of name2. The first value of name1 maps to the first value of name2, and so on.
  • ${name1= k..k+n step i} iterates from k to k+n in steps of i.

For example, the following line creates 10 scenarios, each with a terminal placed at a different latitude:

*.terminal[0].mob.centerLatitude = ${lat = 0.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0}

And this line associates a number of repetitions to each terminal:

**.Ntx = ${Ntx = 10,10,8,8,7,6,5,3,3,2 ! lat}

I suggest picking a specific latitude and testing different numbers of repetitions to see their impact on network performance.

3. Launching batch simulations

Manually launching simulations when multiple configurations need to be tested can become tedious. To address this, there is a small run.sh script in each scenario folder that launches all selected configurations at once.

In run.sh, update the path to inet4.5 to match your installation. Then:

source ~/omnetpp-6.3.0/setenv
cd Simulations/Tutorial/03-BlindOptimization/
chmod +x run.sh
./run.sh

Keep in mind that simulations are single-threaded, so depending on the number of cores on your machine, you can run several simulations simultaneously to save time. However, be careful about side effects: I do not recommend splitting the same scenario across multiple parallel simulations, but rather running different scenarios at the same time.

In run.sh, the -j and -b flags respectively allocate a number of cores for parallel simulation runs and group scenarios on the same core. -b can produce errors for values above 1, so it is recommended to always use -b1.

4. Result analysis

In the results analysis folder (simulation_analysis/Tutorial/03-Blind_Optimization) you will find a Jupyter notebook for analyzing this scenario. You can use it for your own analyses, including custom plots. The summary table allows you to sort and compare the different configurations.

Originally, the file was created to compare Blind and Sat Detect, but you can use it for any comparative analysis between configurations. Many lines of code remain as leftovers from analyses that were only useful once but kept anyway (if it works, don't touch it). Don't focus on the details — follow the main analysis steps instead.

The goal of this exercise was to see how to create simulation batches to test a range of parameters. Be careful: data file sizes can grow large if you are not paying attention. The same goes for the number of simulation scenarios, as it grows exponentially with the number of parameters added. That is why I always recommend running at least a short test of a hundred simulated seconds to make sure everything is working correctly.

Ex4 — A Terminal Population (X sats - X terms - X GS)

Story: You came back with your results and your manager promises you a raise. However, he would like to know how your new protocol holds up under load. Run the necessary tests and report back.

This scenario is located in Simulations/Tutorial/04-Capacity.

Running simulations, then exporting, then running the notebook to generate plots… that takes a while. From now on, you can use the all-in-one script that handles launching, exporting, and analyzing everything in one click!

1. Configuration parameterization

You know the drill — make the right parameter choices to run the simulations. There are two ways to model packet error rate (PER) depending on what data you have available.

Option A — Load + C/N0 map (recommended, most accurate)

The PER is looked up from a 2D table indexed by normalized load and C/N0. This requires a loadVsPERvsCNO.csv file generated by a physical layer simulator. Place it in your constellations/ folder and add:

**.useLoadCn0PerCsv = true
**.loadCn0PerMapFile = "constellations/loadVsPERvsCNO.csv"

To verify it is working, check the simulation logs: you should see the line PER(load,C/N0): ... (mode=csv).

Option B — Polynomial approximation (no CSV needed)

If you do not have the CSV file, the simulator falls back to a polynomial PER(load) curve that is independent of C/N0. This is the default behavior when useLoadCn0PerCsv = false (or is not set). The curve is controlled by three coefficients:

**.useLoadCn0PerCsv = false   # default, can be omitted
**.perFromLoad_a = 1.0        # cubic coefficient
**.perFromLoad_b = 0.5        # quadratic coefficient
**.perFromLoad_c = 0.1        # linear coefficient

The resulting PER is a·x³ - b·x² + c·x where x is the normalized load. Check the simulation logs for PER(load): ... (mode=average) to confirm this mode is active.

Choose your parameters and the configurations you want to test carefully.

2. Configuration and simulation script

Once you have chosen the parameters to test, all that remains is to launch the simulations. Open Analysis_Toolkit.ipynb, select the number of allocated cores and the scenario to run, then launch the notebook. It will handle running the simulations, exporting the data, and generating the plots for you. You will have access to a wide range of data as well as automatically generated plots, but you can also build your own from the raw data.

At this point, I think you are ready to run your own experiments. I encourage you to do something that makes sense to you, set your own parameters, and create your own scenarios.

Story: You think you have struck gold, so you leave your old company to join a competitor who promises you a better salary.

Next Steps