{"id":19984521,"url":"https://github.com/intellabs/networkgym","last_synced_at":"2025-10-12T13:14:23.275Z","repository":{"id":187103181,"uuid":"675840954","full_name":"IntelLabs/networkgym","owner":"IntelLabs","description":"NetworkGym is a Simulation-aaS framework to support Network AI algorithm development by providing high-fidelity full-stack e2e network simulation in cloud and allowing AI developers to interact with the simulated network environment through open APIs.","archived":false,"fork":false,"pushed_at":"2024-05-22T17:17:24.000Z","size":5963,"stargazers_count":3,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-22T18:30:00.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://intellabs.github.io/networkgym/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IntelLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-07T21:19:58.000Z","updated_at":"2024-05-28T02:50:28.703Z","dependencies_parsed_at":"2023-10-25T00:33:13.721Z","dependency_job_id":"2ab60e7f-b5d0-4871-a73e-c6c85a60dd36","html_url":"https://github.com/IntelLabs/networkgym","commit_stats":null,"previous_names":["intellabs/networkgym"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelLabs%2Fnetworkgym","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelLabs%2Fnetworkgym/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelLabs%2Fnetworkgym/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelLabs%2Fnetworkgym/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntelLabs","download_url":"https://codeload.github.com/IntelLabs/networkgym/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224386276,"owners_count":17302630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T04:19:24.782Z","updated_at":"2025-10-12T13:14:18.253Z","avatar_url":"https://github.com/IntelLabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NetworkGym\n\n📋 **[NetworkGym Docs Website](https://intellabs.github.io/networkgym)**\n\n📧 **[Contact Us](mailto:netaigym@gmail.com)**\n\n💻 **[Slack](https://join.slack.com/t/networkgym/shared_invite/zt-23c6nvd5s-1l1m5iVtDZj3LcMgVspdNg)**\n\nNetworkGym is an open-source based network simulation software framework consisting of four modules: Client, Server, Environment, and Simulator. Gym is referenced to OpenAI’s Gym library – an API standard for reinforcement learning (https://gymnasium.farama.org/).\n\n## 💡 Overview\n\nThis repository provides source code for all four modules: Client (`network_gym_client`), Server (`network_gym_server`), Environment (`network_gym_env`), and Simulator (`network_gym_sim`): \n\n- network_gym_sim (license: GPLv2): a ns-3.41 (https://www.nsnam.org/) based full-stack multi-access network simulator enhanced with the support of the Generic Multi Access (GMA) protocol (https://github.com/IntelLabs/gma)\n\n- network_gym_server (license: Apachev2): application software based on ZMQ socket APIs (https://zeromq.org/socket-api/) to support info exchange between network_gym_client and network_gym_sim\n\n- network_gym_client (license: Apachev2): application software to configure network simulation, collect synthetic data and traces, and run algorithms to generate commands and control the simulation\t\n\n- network_gym_env (license: Apachev2): application software to connect network simulator with network_gym_server\t\n\n\n## ⌛ Installation\n1. (Optional) Create a new virtual python environment.\n```\npython3 -m venv network_venv\nsource network_venv/bin/activate\n```\n2. Install Required Libraries.\n```\npip3 install -r requirements.txt\n```\n3. (For ns-3 Environment Only) Build the `network_gym_sim`\n- Install ns-3.41. In the root directory, clone the [ns-3.41](https://www.nsnam.org/releases/ns-3-41/) and name it as `network_gym_sim`:\n  ```\n  git clone -b ns-3.41 https://gitlab.com/nsnam/ns-3-dev.git network_gym_sim\n  ```\n  After downloading ns-3, install the dependencies and libraries following the [ns-3 prerequisites](https://www.nsnam.org/docs/tutorial/html/getting-started.html#prerequisites). Build the ns-3 with the following commands. You can find more information on building ns-3 [here](https://www.nsnam.org/docs/tutorial/html/getting-started.html#building-ns-3).\n  ```\n  cd network_gym_sim\n  ./ns3 clean\n  ./ns3 configure --build-profile=optimized --disable-examples --disable-tests\n  ./ns3 build\n  ```\n\n- Copy gma and networkgym module files:\n  ```\n  cp ../network_gym_ns3/scratch/unified-network-slicing.cc scratch/\n  cp ../network_gym_ns3/network_gym_sim.py .\n  cp -r ../network_gym_ns3/contrib/* contrib/\n  ```\n- Install the ZeroMQ socket C++ library (required by networkgym module):\n  ```\n  apt-get install libczmq-dev\n  ```\n- In the `network_gym_sim/contrib` folder, clone the 5G nr module from [here](https://gitlab.com/cttc-lena/nr/-/tree/5g-lena-v3.0.y?ref_type=heads), using the 5g-lena-v3.0.y branch:\n  ```\n  cd contrib\n  git clone -b 5g-lena-v3.0.y https://gitlab.com/cttc-lena/nr\n  ```\n- Add C++ Json library. Replace the `network_gym_sim/contrib/networkgym/model/json.hpp` with the [json.hpp](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp):\n  ```\n  cd networkgym/model/\n  rm json.hpp\n  wget https://raw.githubusercontent.com/nlohmann/json/develop/single_include/nlohmann/json.hpp\n  ```\n\n- Finally, we need to fix a few bugs in the ns-3. The lte module hard coded the IP addresses for the backhaul links. This two files allows we to customize the IP addresses for the backhaul links. \n  ```\n  cd ../../../../\n  cp network_gym_sim/contrib/modified/no-backhaul-epc-helper.cc network_gym_sim/src/lte/helper/no-backhaul-epc-helper.cc\n  cp network_gym_sim/contrib/modified/point-to-point-epc-helper.cc network_gym_sim/src/lte/helper/point-to-point-epc-helper.cc\n  ```\n- Try to build ns-3 once again to see if there is any errors:\n  ```\n  cd network_gym_sim\n  ./ns3 build\n  ```\n- (Optional) With the previous steps, the code should be running without any issue. However, we also identified a few more issues related to TCP or BBR and proposed fixes in the modified files located in `network_gym_sim/contrib/modified/` folder. You can also replace the original files with them if needed. Again, this is not required.\n\n## ☕ Quick Start\nFirst, open 3 terminals (or 3 screen sessions), one per component. Make sure all terminals have activated the virtual environment created in the previous step.\n### start server\nIn the first terminal type following command to start the server:\n```\npython3 start_server.py\n```\nThe expected output is as following:\n```\nMax instances per client:\n{'test': 1, 'admin': 100}\n┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓\n┃ Worker ┃ Status ┃ Time since Last Seen (seconds) ┃ Environment ┃\n┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩\n└────────┴────────┴────────────────────────────────┴─────────────┘\n```\n\n### start environment\nIn the second terminal type following command to start the ns-3 based environment:\n```\npython3 start_env_ns3.py\n```\nThe expected output from the first (**server**) terminal should be updated as following:\n```\n[b'admin-0-intel-Z390-AORUS-ULTRA', b'', b'{\\n  \"type\": \"env-hello\",\\n  \"env_list\": [\\n    \n\"nqos_split\"\\n]\\n}']\n┏━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓\n┃ Worker      ┃ Status ┃ Time since Last Seen (seconds) ┃ Environment    ┃\n┡━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩\n│ admin-0-*** │ idle   │ 13.100512027740479             │ ['nqos_split'] │\n└─────────────┴────────┴────────────────────────────────┴────────────────┘\n```\n\n### start client\nIn the third terminal, type the following command to start the client:\n```\npython3 start_client.py\n```\nA progress bar should be displayed at the third (client) terminal:\n```\nsystem_default agent is interacting with NetworkGym's                     \n⠴ Progress ━╸━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   5% 0:04:41 env time: 4600/101100 ms   \n```\n\n## 🔧 Client Configuration\nNetworkGym Client includes two configuration files, a common configure file and environement dependent configure file. \n\n- Update the common configuration parameters in [common_config.json](network_gym_client/common_config.json):\n\n```json\n{\n  \"connect_via_server_ip_and_server_port\": false, //set to ture to use the server_ip and server_port to connect to a Intel cloud server (this method requires Intel VPN);\n  \"server_ip\": \"gmasim-v01.jf.intel.com\", //do not change (for internal users only).\n  \"server_port\": 8092, //set to 8088 to access stable version or 8092 to access dev version.\n  \"local_fowarded_port\": 8092, // the local port that used to forward to the external server.\n  \"enable_wandb\": false, // sending data to wandb database.\n  \"enable_terminal_redering\": true, // render the network in the terminal.\n  \"session_name\": \"admin\",//This is for connecting to Intel Cloud server. Make sure to change the \"session_name\" to your assigned session name. Cannot use '-' in the name! Test account is for testing only (shared by every one). Contact us to apply for an account. \n  \"session_key\": \"admin\",//This is for connecting to Intel Cloud server. Make sure to change the \"session_key\" to your assigned keys.\n}\n```\n\n- Update the environment dependent configuration file, e.g., [network_gym_client/envs/nqos_split/config.json](network_gym_client/envs/nqos_split/config.json).\n  - View configuration suggestions for arguments at [NetworkGym Docs Website](https://intellabs.github.io/networkgym/environments/mx_traffic_management/mx_traffic_splitting.html#arguments).\n\n\n## 📁 Client File Structure\n\n```\n📦 NetworkGym\n┣ 📜 start_client_demo.py\n┗ 📂 network_gym_client\n  ┣ 📜 adapter.py (➡️ WanDB)\n  ┣ 📜 common_config.json\n  ┣ 📜 env.py\n  ┣ 📜 northbound_interface.py (➡️ network_gym_server and network_gym_env)\n  ┗ 📂 envs\n    ┗ 📂 [ENV_NAME]\n      ┣ 📜 adapter.py\n      ┗ 📜 config.json\n```\n\n- Excuting the 📜 start_client_demo.py file will start a new simulation. To change the environment, modify the `env_name` parameter. The 📜 common_config.json is used in all environments. Depends on the selected environments, the 📜 config.json and 📜 adapter.py in the [ENV_NAME] folder will be loaded. The 📜 adapter.py helps preparing observations, rewards and actions for the selected environment.\n- The 📜 start_client_demo.py create a NetworkGym environment, which remotely connects to the ns-3 based NetworkGym Simualtor (hosted in vLab machine) using the 📜 northbound_interface. 📜 start_client_demo.py also uses random samples from the action space to interact with the NetworkGym environment. The results are synced to ➡️ WanDB database. We provide the following code snippet from the 📜 start_client_demo.py as an example:\n\n```python\n#Copyright(C) 2023 Intel Corporation\n#SPDX-License-Identifier: Apache-2.0\n#File : start_client_demo.py\n\nfrom network_gym_client import load_config_file\nfrom network_gym_client import Env as NetworkGymEnv\n\nclient_id = 0\nenv_name = \"nqos_split\"\nconfig_json = load_config_file(env_name)\nconfig_json[\"rl_config\"][\"agent\"] = \"random\"\n# Create the environment\nenv = NetworkGymEnv(client_id, config_json) # make a network env using pass client id and configure file arguements.\n\nnum_steps = 1000\nobs, info = env.reset()\n\nfor step in range(num_steps):\n\n    action = env.action_space.sample()  # agent policy that uses the observation and info\n    obs, reward, terminated, truncated, info = env.step(action)\n\n    # If the environment is end, exit\n    if terminated:\n        break\n\n    # If the epsiode is up (environment still running), then start another one\n    if truncated:\n        obs, info = env.reset()\n```\n\n## 📚 How to reference \"NetworkGym\"?\n\nPlease use the following to reference \"NetworkGym\" in your paper if it is used to generate data for the paper: \n\nMenglei Zhang and Jing Zhu, \"NetworkGym: Democratizing Network AI via Simulation-as-a-Service\", https://github.com/IntelLabs/networkgym \n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintellabs%2Fnetworkgym","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintellabs%2Fnetworkgym","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintellabs%2Fnetworkgym/lists"}