netrl 0.1.0__tar.gz

netrl-0.1.0/LICENSE

@@ -0,0 +1,279 @@
+GNU GENERAL PUBLIC LICENSE
+Version 2, June 1991
+
+Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+PREAMBLE
+
+The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General
+Public License is intended to guarantee your freedom to share
+and change free software--to make sure the software is free for
+all its users.  This General Public License applies to most of
+the Free Software Foundation's software and to any other program
+whose authors commit to using it.  (Some other Free Software
+Foundation software is covered by the GNU Lesser General Public
+License instead.)  You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and
+charge for this service if you wish), that you receive source code
+or can get it if you want it, that you can change the software or
+use pieces of it in new free programs; and that you know you can
+do these things.
+
+To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if
+you distribute copies of the software, or if you modify it.
+
+For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights
+that you have.  You must make sure that they, too, receive or can
+get the source code.  And you must show them these terms so they
+know their rights.
+
+We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+TERMS AND CONDITIONS
+
+0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any work containing the Program or a portion
+of it, either verbatim or with modifications and/or translated into
+another language.  (Hereinafter, translation is included without limitation
+in the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the Program
+(independent of having been made by running the Program).  Whether that
+is true depends on what the Program does.
+
+1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+a) You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+b) You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+c) If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License.  (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or a work based on the Program) on a volume of a
+storage or distribution medium does not bring the other work under
+the scope of this License.
+
+3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+a) Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+b) Accompany it with a written offer, valid for at
+least three years, to give any third party, for a charge no
+more than your cost of physically performing source distribution, a
+complete machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+c) Accompany it with the information you received as to the offer
+to distribute corresponding source code.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy along with the object code.
+
+4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free
+Software Foundation.
+
+10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are incompatible with these, write
+to the author to ask for permission.  For software which is copyrighted
+by the Free Software Foundation, write to the Free Software Foundation;
+we sometimes make exceptions for this.  Our decision will be guided by
+the two goals of preserving the free status of all derivative works of
+our free software and of promoting the sharing and reusefulness of
+software generally.
+
+NO WARRANTY
+
+11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSS OF PROFITS OR
+LOSS OF SAVINGS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGES.
+
+END OF TERMS AND CONDITIONS

netrl-0.1.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: netrl
+Version: 0.1.0
+Summary: Networked RL simulation platform — gymnasium wrapper with communication channel simulation.
+Author-email: Pietro Talli <pietrotalli@gmail.com>
+License-Expression: GPL-2.0-only
+Project-URL: Homepage, https://github.com/pietro-talli/NetRL
+Project-URL: Documenation, https://netrl.readthedocs.io/en/latest/index.html
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gymnasium>=0.29
+Requires-Dist: numpy>=1.24
+Requires-Dist: pybind11>=2.11
+Requires-Dist: ns3>=3.44.post
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-python
+
+# NetRL — Networked Reinforcement Learning Simulation Platform
+
+NetRL wraps any [Gymnasium](https://gymnasium.farama.org/) environment and simulates a **noisy communication channel** between the agent and the environment. At every `step()`, the raw observation is transmitted through a configurable channel backend (loss, delay, retransmissions). The agent receives a **sliding-window buffer** of past observations together with a boolean mask indicating which slots actually arrived.
+
+Full documentation: https://netrl.readthedocs.io/en/latest/index.html
+
+Four channel backends are available:
+
+| Backend | Model | Config class | Requires |
+|---|---|---|---|
+| **Gilbert-Elliott** (default) | Two-state Markov chain with configurable loss per state and fixed delay | `NetworkConfig` | Built-in |
+| **ns-3 802.11a WiFi (fast)** ⚡ | Full MAC/PHY simulation via ns-3 — same physics as below but compiled as a Python C++ extension (pybind11), **no subprocess overhead** | `NS3WiFiChannelFastConfig` | `pip install ns3` — built automatically |
+| **ns-3 802.11a WiFi** | Full MAC/PHY simulation via ns-3 — CSMA/CA, retransmissions, path-loss | `NS3WifiConfig` | `pip install ns3` + manual binary build |
+| **ns-3 5G mmWave** | Full EPC/NR simulation via ns-3-mmwave — 3GPP TR 38.901 path-loss, HARQ, RLC | `NS3MmWaveConfig` | ns-3-mmwave source build |
+| **ns-3 5G-LENA NR** | Full NR + EPC simulation via 5G-LENA (contrib/nr) — 3GPP channel, beamforming, numerology | `NS3LenaConfig` | 5G-LENA source build |
+
+> **Recommendation:** Use `NS3WiFiChannelFastConfig` for all 802.11a WiFi experiments. It provides identical physical simulation to `NS3WifiConfig` but runs **2-3× faster** by eliminating subprocess IPC overhead — and it is compiled automatically when you run `pip install -e .`.
+
+---
+
+## Table of Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+   - [Python package, GE channel, and fast WiFi channel](#1-python-package-ge-channel-and-fast-wifi-channel)
+   - [ns-3 WiFi binary (subprocess version)](#2-ns-3-wifi-binary-subprocess-version)
+   - [ns-3 5G mmWave binary](#3-ns-3-5g-mmwave-binary)
+    - [ns-3 5G-LENA binary](#4-ns-3-5g-lena-binary)
+3. [Quick Start](#quick-start)
+   - [Gilbert-Elliott channel](#gilbert-elliott-channel)
+   - [ns-3 WiFi channel (fast — recommended)](#ns-3-wifi-channel-fast--recommended)
+   - [ns-3 WiFi channel (subprocess)](#ns-3-wifi-channel-subprocess)
+   - [ns-3 5G mmWave channel](#ns-3-5g-mmwave-channel)
+    - [ns-3 5G-LENA channel](#ns-3-5g-lena-channel)
+4. [Observation Space](#observation-space)
+
+---
+
+## Requirements
+
+- Python ≥ 3.10
+- GCC ≥ 10 or Clang ≥ 11
+  - C++20 for the pybind11 extensions (`netcomm` GE channel and `netrl_ext` fast WiFi channel)
+  - **C++20** for the ns-3 mmWave binary (ns-3-mmwave 3.42 uses `std::remove_cvref_t`)
+- For the fast WiFi channel and the subprocess WiFi channel:
+  - `pip install ns3` (ns-3 ≥ 3.43, headers + shared libs) — the **fast WiFi channel is built automatically** during `pip install -e .`
+- For the 5G mmWave channel:
+  - A compiled **ns-3-mmwave** source build at `/path/to/ns3-mmwave/build` (ns-3 3.42)
+
+---
+
+## Installation
+
+### 1. Python package, GE channel, and fast WiFi channel
+
+The Gilbert-Elliott channel (`netcomm`) and the fast ns-3 WiFi channel (`_netrl_ext`) are both compiled as C++ pybind11 extensions. Install everything with a single command:
+
+```bash
+pip install -e .
+```
+
+This automatically:
+1. Installs all Python dependencies (including `ns3 ≥ 3.44`)
+2. Compiles `netcomm` — the Gilbert-Elliott C++ backend
+3. Detects the pip-installed `ns3` library and **compiles `_netrl_ext`** — the fast WiFi pybind11 binding
+
+The fast WiFi channel (`NS3WiFiChannelFastConfig`) is then immediately available — no extra build step required.
+
+```python
+from netrl import NetworkedEnv, NetworkConfig, NS3WiFiChannelFastConfig
+```
+
+### 2. ns-3 WiFi binary (subprocess version)
+
+The subprocess ns-3 backend runs the simulation in a **separate process** and communicates via stdin/stdout pipes. Compile the binary once before use:
+
+```bash
+bash src/build_ns3_sim.sh
+```
+
+The script auto-detects your ns-3 installation, compiles `src/ns3_wifi_sim.cc`, and writes the binary to `src/ns3_wifi_sim`.
+
+### 3. ns-3 5G mmWave binary
+
+The mmWave backend requires a separate binary built against [ns-3-mmwave](https://github.com/nyuwireless-unipd/ns3-mmwave) (ns-3 3.42). Compile it once before use:
+
+```bash
+bash src/build_ns3_mmwave_sim.sh --ns3-mmwave-dir /path/to/ns3-mmwave
+```
+
+The script expects ns-3-mmwave to be built at `/home/dianalab/Projects/ns3-mmwave/build` (edit the `NS3_MMWAVE_BUILD` variable at the top of the script to change the path).
+
+### 4. ns-3 5G-LENA binary
+
+The 5G-LENA backend requires a separate binary built against your local 5G-LENA tree (contrib/nr). Compile it once before use:
+
+```bash
+bash src/build_ns3_lena_sim.sh --ns3-lena-dir /path/to/5g-lena/ns-3-dev
+```
+
+By default, the script expects 5G-LENA at `/home/dianalab/Projects/5g-lena/ns-3-dev`.
+
+## Quick Start
+
+### Gilbert-Elliott channel
+
+```python
+import gymnasium as gym
+from netrl import NetworkedEnv, NetworkConfig
+
+config = NetworkConfig(
+    p_gb=0.1,        # Good -> Bad transition probability per step
+    p_bg=0.3,        # Bad  -> Good transition probability per step
+    loss_good=0.01,  # packet loss probability in Good state
+    loss_bad=0.20,   # packet loss probability in Bad state
+    delay_steps=3,   # fixed one-way delay in env steps
+    buffer_size=10,  # observation window length
+    seed=42,
+)
+
+env = NetworkedEnv(gym.make("CartPole-v1"), config)
+obs, info = env.reset()
+
+# obs["observations"].shape == (10, 4)   — buffer of last 10 obs
+# obs["recv_mask"].shape    == (10,)     — True where a packet arrived
+
+for _ in range(1000):
+    obs, reward, term, trunc, info = env.step(env.action_space.sample())
+    print(info["channel_info"]["state"])   # "GOOD" or "BAD"
+    print(info["arrived_this_step"])       # True / False
+    if term or trunc:
+        obs, info = env.reset()
+```
+
+### ns-3 WiFi channel 
+
+```python
+import gymnasium as gym
+from netrl import NetworkedEnv, NetworkConfig, NS3WiFiChannelFastConfig
+
+env = NetworkedEnv(
+    gym.make("CartPole-v1"),
+    NetworkConfig(buffer_size=10, seed=42),
+    channel_config=NS3WiFiChannelFastConfig(
+        distance_m=20.0,         # STA-to-AP distance
+        step_duration_ms=5.0,    # 5 ms of ns-3 time per env step
+        tx_power_dbm=20.0,
+        loss_exponent=3.0,
+        max_retries=7,
+        packet_size_bytes=256,
+    ),
+)
+
+obs, info = env.reset()
+
+for _ in range(1000):
+    obs, reward, term, trunc, info = env.step(env.action_space.sample())
+    print(info["channel_info"]["state"])   # "NS3_WIFI"
+    if term or trunc:
+        obs, info = env.reset()
+```
+
+> **No subprocess, no binary to build.** The `netrl_ext` extension is compiled automatically during `pip install -e .` and linked directly into the Python process.  Performance is **2-3× faster** than the subprocess variant, with lower memory usage and instant startup.
+
+### ns-3 WiFi channel (subprocess)
+
+```python
+import gymnasium as gym
+from netrl import NetworkedEnv, NetworkConfig, NS3WifiConfig
+
+env = NetworkedEnv(
+    gym.make("CartPole-v1"),
+    NetworkConfig(buffer_size=10),
+    channel_config=NS3WifiConfig(
+        distance_m=20.0,         # STA-to-AP distance
+        step_duration_ms=5.0,    # 5 ms of ns-3 time per env step
+        tx_power_dbm=20.0,
+        loss_exponent=3.0,
+        max_retries=7,
+        packet_size_bytes=256,
+    ),
+)
+
+obs, info = env.reset()
+
+for _ in range(1000):
+    obs, reward, term, trunc, info = env.step(env.action_space.sample())
+    print(info["channel_info"]["state"])   # "NS3_WIFI"
+    if term or trunc:
+        obs, info = env.reset()
+```
+
+> The ns-3 simulation is **persistent across steps** — MAC-layer state (backoff counters, retry timers) carries over between steps, giving temporally correlated, realistic channel behaviour. The simulation is only rebuilt on `env.reset()`.
+
+### ns-3 5G mmWave channel
+
+```python
+import gymnasium as gym
+from netrl import NetworkedEnv, NetworkConfig, NS3MmWaveConfig
+
+env = NetworkedEnv(
+    gym.make("CartPole-v1"),
+    NetworkConfig(buffer_size=10),
+    channel_config=NS3MmWaveConfig(
+        distance_m=50.0,           # UE-to-eNB distance
+        frequency_ghz=28.0,        # 28 GHz (n257/n261 band)
+        bandwidth_ghz=0.2,         # 200 MHz component carrier
+        tx_power_dbm=23.0,         # UE transmit power
+        scenario="UMa",            # Urban Macro (3GPP TR 38.901)
+        harq_enabled=True,
+        step_duration_ms=1.0,
+        packet_size_bytes=64,
+    ),
+)
+
+obs, info = env.reset()
+
+for _ in range(1000):
+    obs, reward, term, trunc, info = env.step(env.action_space.sample())
+    print(info["channel_info"]["state"])   # "NS3_MMWAVE"
+    if term or trunc:
+        obs, info = env.reset()
+```
+
+> The mmWave simulation models a full 5G EPC stack (UE → eNB → SGW/PGW → remote host) with 3GPP TR 38.901 path-loss, HARQ retransmissions, and configurable RLC mode. The first `reset()` call waits up to 60 s for the EPC to initialise — subsequent resets are faster.
+
+### ns-3 5G-LENA channel
+
+```python
+import gymnasium as gym
+from netrl import NetworkedEnv, NetworkConfig, NS3LenaConfig
+
+env = NetworkedEnv(
+    gym.make("CartPole-v1"),
+    NetworkConfig(buffer_size=10),
+    channel_config=NS3LenaConfig(
+        distance_m=80.0,
+        frequency_ghz=28.0,
+        bandwidth_ghz=0.1,
+        scenario="UMa",
+        numerology=3,
+        step_duration_ms=2.0,
+    ),
+)
+
+obs, info = env.reset()
+for _ in range(1000):
+    obs, reward, term, trunc, info = env.step(env.action_space.sample())
+    print(info["channel_info"]["state"])   # "NS3_LENA"
+    if term or trunc:
+        obs, info = env.reset()
+```
+
+> The 5G-LENA simulation is persistent across steps and only rebuilt on `env.reset()`. It uses the same NetRL subprocess protocol as the WiFi and mmWave backends.
+
+---
+
+## Observation Space
+
+`NetworkedEnv` replaces the wrapped env's `Box` observation space with:
+
+```python
+gymnasium.spaces.Dict({
+    "observations": Box(
+        shape=(buffer_size, *original_obs_shape),
+        dtype=original_obs_dtype,
+    ),
+    "recv_mask": MultiBinary(buffer_size),
+})
+```
+
+- `observations[-1]` is the **most recent** slot; `observations[0]` is the oldest.
+- Slots where no packet arrived (dropped or not yet delivered) are zero-filled with `recv_mask = False`.
+- The buffer always has exactly `buffer_size` entries, providing a **fixed-shape input** for neural network policies.
+
+The `info` dict returned by `step()` is augmented with:
+
+| Key | Type | Description |
+|---|---|---|
+| `"channel_info"` | `dict` | Diagnostic snapshot from the channel backend |
+| `"arrived_this_step"` | `bool` | `True` if at least one packet arrived during this step |
+
+**GE `channel_info` keys:** `state` (`"GOOD"` / `"BAD"`), `pending_count`
+
+**ns-3 fast WiFi `channel_info` keys:** `state` (`"NS3_WIFI"`), `distance_m`, `step_duration_ms`, `tx_power_dbm`, `loss_exponent`, `max_retries`, `packet_size_bytes`, `pending_tx_count`, `pending_rx_count`
+
+**ns-3 WiFi `channel_info` keys:** `state` (`"NS3_WIFI"`), `pending_count`, `arrived_buffered`, `distance_m`, `step_duration_ms`, `tx_power_dbm`, `loss_exponent`, `max_retries`
+
+**ns-3 mmWave `channel_info` keys:** `state` (`"NS3_MMWAVE"`), `pending_count`, `arrived_buffered`, `distance_m`, `frequency_ghz`, `bandwidth_ghz`, `tx_power_dbm`, `enb_tx_power_dbm`, `noise_figure_db`, `scenario`, `harq_enabled`, `rlc_am_enabled`, `step_duration_ms`
+