An ns-3-based Open RAN simulation environment with native support for intent-based orchestration.
The original contributions in this repository are licensed under the MIT License.
This means you are free to use, modify, and distribute this software, with or without modification, provided you retain the original copyright notice. See the
LICENSEfile for the full terms.
This project makes use of third-party open-source components. Their copyright
notices and license terms are preserved in their respective directories and
summarized in THIRD-PARTY.txt. Do not remove or modify
the license and copyright files present in any third-party component directory.
- Overview
- Architecture
- Getting Started
- Visualization via NetAnim
- Troubleshooting
- Acknowledgements
- Further Reading
ib-ORAN (module name: ns3-iboran) is a comprehensive simulation environment and design framework built on the proven ns-3 network simulator. It is primarily developed to implement and verify intent-based operations within Open RAN architectures.
This framework enables direct control of Physical Layer (PHY) and Medium Access Control (MAC) functions through RAN applications — rApps and xApps hosted on RAN Intelligent Controllers (RICs), as well as distributed dApps — spanning the full spectrum of control timescales from non-real-time (non-RT) to near-real-time (near-RT) to real-time.
ib-ORAN bridges high-performance ns-3 C++ simulations and Python-based policy logic via a shared-memory interface, decoupling the simulation engine from the control plane without sacrificing performance. This architecture natively supports non-RT and near-RT RIC implementations alongside real-time dApp design, enabling intent-based, semantics-aware exchange of payload data across diverse use cases.
Building on the foundations of ns3-gym and ns3-ai, ib-ORAN extends both frameworks with intent-based and semantics-aware capabilities purpose-built for Open RAN network control — going beyond reinforcement learning hooks to provide a full orchestration layer for intelligent, policy-driven RAN behavior.
ib-ORAN supports the 3GPP LTE standard:
- LTE: implemented through an adapted version of the built-in
ltemodule in ns-3.
The architecture spans three control planes — non-RT RIC, near-RT RIC, and real-time dApp layer — interconnected through standardized E2 and A1 interfaces and the newly introduced E3 interface. The shared-memory bridge between ns-3 and the Python orchestration layer is a core design principle, enabling clean separation of simulation logic from intelligent control.
See the detailed message structure reference for the complete lists of control messages exchanged through the implemented interfaces under their respective service models.
Browse the App catalog for the full list of developed dApps, xApps, and rApps. To contribute new Apps, please refer to CONTRIBUTING.md.
Before installing ib-ORAN, ensure you have:
- ns-3 (compatible version — see installation guide)
- Python 3.x with
pip - CMake and a C++ build toolchain
- NetAnim (optional, for visualization)
A full, structured installation guide is available here.
python3 iboran_run.py [--rat_type RAT_TYPE] [--k K] [--dapp_algo_ue_selection ALGO] ...All parameters are optional. If omitted, default values are used.
Parameters:
| Parameter | Description | Default |
|---|---|---|
--rat_type |
Radio Access Technology: "LTE" |
"LTE" |
--dapp_control_period_sf |
dApp control period (in subframes) | 1 |
--xapp_control_period_f |
xApp control period (in frames) | 1 |
--k |
Maximum parallel UEs scheduled per TTI | 1 |
--dapp_algo_ue_selection |
dApp MAC scheduling algorithm (see Built-In Algorithms) | "Random" |
--xapp_algo_rbg_bounding |
xApp RBG bounding algorithm | "Bypass" |
--show_flowstats |
Print flow statistics to console: "true" or "false" |
"true" |
--show_iqa_diagnosis |
Print IQA diagnosis to console: "true" or "false" |
"true" |
--save_dapp_log |
Save dApp control log to file: "true" or "false" |
"false" |
Examples:
# Run with all defaults
python3 iboran_run.py
# LTE with Random scheduler, k=1
python3 iboran_run.py --rat_type="LTE" --k=1 --dapp_algo_ue_selection="Random"
# Override a single argument
python3 iboran_run.py --k=4The default RAN configuration parameters are defined in iboran-ran-params.cc.
ib-ORAN accepts datasets formatted according to the configured payload format:
IMAGE→ labeled images, each containing a specific object ID (stored in/notebook/dataset)
Note: Additional payload formats are currently under development.
Each simulation run produces the following outputs:
| Output | Location |
|---|---|
| Performance metrics logs | Console / log files |
| Recovered payload dataset | /notebook/dataset_dscv |
| NetAnim XML animation file | /notebook/netanim/ |
| Real-time console flow stats | Console (optional) |
| Detailed dApp / xApp control logs | /notebook/logs/ (optional) |
Beyond single runs, the ib-ORAN Campaign script facilitates large-scale evaluation by sweeping over different parameters and algorithms. This makes it easy to compare RAN operation strategies from multiple perspectives using interactive computing platforms (e.g., Jupyter Notebook).
See iboran_evaluation.ipynb for an illustrative example showing how to set up comparisons across key parameters and scheduling algorithms.
ib-ORAN automatically generates an XML animation file compatible with NetAnim, enabling graphical visualization of nodes, packet transmissions, and mobility patterns.
Step 1: Clone and Build NetAnim
cd /path/to/ns-3
git clone https://gitlab.com/nsnam/netanim.git
cd netanim
mkdir build && cd build
cmake .. && cmake --build .Step 2: Launch NetAnim
cd build
./netanim- Click File → Open XML
- Navigate to
iboran/notebook/netanim/ - Open the generated XML file (
iboran-lte-anim.xml)
Verify that Python dependencies are installed in the correct environment:
pip install -e contrib/ai/python_utils
pip install -e contrib/ai/model/gym-interface/pyIf you encounter further issues, please check the existing GitHub Issues before opening a new one. When reporting a bug, include your ns-3 version, Python version, OS, and the full error output.
ib-ORAN is part of the ANR COMSEMA project, supported by the French National Research Agency (Agence Nationale de la Recherche).
If you use ib-ORAN in your research, please cite this repository:
@software{iboran,
author = {Agheli, Pouya and Lefebvre, Grégoire},
title = {ib-ORAN: Intent-Based Open RAN},
year = {2026},
url = {https://github.com/Orange-OpenSource/ns3-iboran},
license = {MIT}
}Or the corresponding publication:
@inproceedings{iboran,
author = {Agheli, Pouya and Lefebvre, Grégoire},
title = {Intent-Based Orchestration in Open RAN: An ns-3 Simulation Framework},
booktitle = {Proceedings of the EuCNC \& 6G Summit},
year = {2026}
}