Metadata-Version: 2.4
Name: waveflow-sim
Version: 2.0.3
Summary: Waveflow: RIS-assisted wireless network simulator with beam sweeping, OFDM waveform simulation, and ML-guided beam optimization
Author: Mohd Adil Mokti
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
           "License" shall mean the terms and conditions for use, reproduction,
           and distribution as defined by Sections 1 through 9 of this document.
        
           "Licensor" shall mean the copyright owner or entity authorized by
           the copyright owner that is granting the License.
        
           "Legal Entity" shall mean the union of the acting entity and all
           other entities that control, are controlled by, or are under common
           control with that entity. For the purposes of this definition,
           "control" means (i) the power, direct or indirect, to cause the
           direction or management of such entity, whether by contract or
           otherwise, or (ii) ownership of fifty percent (50%) or more of the
           outstanding shares, or (iii) beneficial ownership of such entity.
        
           "You" (or "Your") shall mean an individual or Legal Entity
           exercising permissions granted by this License.
        
           "Source" form shall mean the preferred form for making modifications,
           including but not limited to software source code, documentation
           source, and configuration files.
        
           "Object" form shall mean any form resulting from mechanical
           transformation or translation of a Source form, including but
           not limited to compiled object code, generated documentation,
           and conversions to other media types.
        
           "Work" shall mean the work of authorship made available under
           the License, as indicated by a copyright notice that is included in
           or attached to the work (an example is provided in the Appendix below).
        
           "Derivative Works" shall mean any work, whether in Source or Object
           form, that is based on (or derived from) the Work and for which the
           editorial revisions, annotations, elaborations, or other modifications
           represent, as a whole, an original work of authorship. For the purposes
           of this License, Derivative Works shall not include works that remain
           separable from, or merely link (or bind by name) to the interfaces of,
           the Work and Derivative Works thereof.
        
           "Contribution" shall mean, as submitted to the Licensor for inclusion
           in the Work by the copyright owner or by an individual or Legal Entity
           authorized to submit on behalf of the copyright owner. For the purposes
           of this definition, "submitted" means any form of electronic, verbal,
           or written communication sent to the Licensor or its representatives,
           including but not limited to communication on electronic mailing lists,
           source code control systems, and issue tracking systems that are managed
           by, or on behalf of, the Licensor for the purpose of discussing and
           improving the Work, but excluding communication that is conspicuously
           marked or designated in writing by the copyright owner as "Not a
           Contribution."
        
           "Contributor" shall mean Licensor and any Legal Entity on behalf of
           whom a Contribution has been received by the Licensor and included
           within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of
           this License, each Contributor hereby grants to You a perpetual,
           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
           copyright license to reproduce, prepare Derivative Works of,
           publicly display, publicly perform, sublicense, and distribute the
           Work and such Derivative Works in Source or Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of
           this License, each Contributor hereby grants to You a perpetual,
           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
           (except as stated in this section) patent license to make, have made,
           use, offer to sell, sell, import, and otherwise transfer the Work,
           where such license applies only to those patent claims licensable
           by such Contributor that are necessarily infringed by their
           Contribution(s) alone or by combination of their Contribution(s)
           with the Work to which such Contribution(s) was submitted. If You
           institute patent litigation against any entity (including a cross-claim
           or counterclaim in a lawsuit) alleging that the Work or any
           Contribution embodied within the Work constitutes direct or
           contributory patent infringement, then any patent licenses granted to
           You under this License for that Work shall terminate as of the date
           such litigation is filed.
        
        4. Redistribution. You may reproduce and distribute copies of the
           Work or Derivative Works thereof in any medium, with or without
           modifications, and in Source or Object form, provided that You
           meet the following conditions:
        
           (a) You must give any other recipients of the Work or Derivative
               Works a copy of this License; and
        
           (b) You must cause any modified files to carry prominent notices
               stating that You changed the files; and
        
           (c) You must retain, in the Source form of any Derivative Works
               that You distribute, all copyright, patent, trademark, and
               attribution notices from the Source form of the Work,
               excluding those notices that do not pertain to any part of
               the Derivative Works; and
        
           (d) If the Work includes a "NOTICE" text file as part of its
               distribution, You must include a readable copy of the
               attribution notices contained within such NOTICE file, in
               at least one of the following places: within a NOTICE text
               file distributed as part of the Derivative Works; within
               the Source form or documentation, if provided along with the
               Derivative Works; or, within a display generated by the
               Derivative Works, if and wherever such third-party notices
               normally appear. The contents of the NOTICE file are for
               informational purposes only and do not modify the License.
               You may add Your own attribution notices within Derivative
               Works that You distribute, alongside or in addition to the
               NOTICE text from the Work, provided that such additional
               attribution notices cannot be construed as modifying the
               License.
        
           You may add Your own license statement for Your modifications and
           may provide additional grant of rights to use, copy, modify, merge,
           publish, distribute, sublicense, and/or sell copies of the
           Derivative Works, as separate terms and conditions for use,
           reproduction, or distribution of Your modifications, or for such
           Derivative Works as a whole, provided Your use, reproduction, and
           distribution of the Work otherwise complies with the conditions
           stated in this License.
        
        5. Submission of Contributions. Unless You explicitly state otherwise,
           any Contribution intentionally submitted for inclusion in the Work
           by You to the Licensor shall be under the terms and conditions of
           this License, without any additional terms or conditions.
           Notwithstanding the above, nothing herein shall supersede or modify
           the terms of any separate license agreement you may have executed
           with Licensor regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade
           names, trademarks, service marks, or product names of the Licensor,
           except as required for reasonable and customary use in describing the
           origin of the Work and reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or
           agreed to in writing, Licensor provides the Work (and each
           Contributor provides its Contributions) on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
           implied, including, without limitation, any warranties or conditions
           of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
           PARTICULAR PURPOSE. You are solely responsible for determining the
           appropriateness of using or reproducing the Work and assume any
           risks associated with Your exercise of permissions under this License.
        
        8. Limitation of Liability. In no event and under no legal theory,
           whether in tort (including negligence), contract, or otherwise,
           unless required by applicable law (such as deliberate and grossly
           negligent acts) or agreed to in writing, shall any Contributor be
           liable to You for damages, including any direct, indirect, special,
           incidental, or exemplary damages of any character arising as a
           result of this License or out of the use or inability to use the
           Work (including but not limited to damages for loss of goodwill,
           work stoppage, computer failure or malfunction, or all other
           commercial damages or losses), even if such Contributor has been
           advised of the possibility of such damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing
           the Work or Derivative Works thereof, You may choose to offer,
           and charge a fee for, acceptance of support, warranty, indemnity,
           or other liability obligations and/or rights consistent with this
           License. However, in accepting such obligations, You may act only
           on Your own behalf and on Your sole responsibility, not on behalf
           of any other Contributor, and only if You agree to indemnify,
           defend, and hold each Contributor harmless for any liability
           incurred by, or claims asserted against, such Contributor by reason
           of your accepting any such warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
        APPENDIX: How to apply the Apache License to your work.
        
           To apply the Apache License to your work, attach the following
           boilerplate notice, with the fields enclosed by brackets "[]"
           replaced with your own identifying information. (Don't include
           the brackets!) The text should be enclosed in the appropriate
           comment syntax for the syntax of the file format. We also recommend
           that a file or directory "LICENSE" or "COPYING" be added to your
           source code repository or distributed archive.
        
           Copyright 2024 Waveflow Contributors
        
           Licensed under the Apache License, Version 2.0 (the "License");
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at
        
               http://www.apache.org/licenses/LICENSE-2.0
        
           Unless required by applicable law or agreed to in writing, software
           distributed under the License is distributed on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
           implied. See the License for the specific language governing
           permissions and limitations under the License.
        
Project-URL: Homepage, https://github.com/nqmn/waveflow
Project-URL: Documentation, https://github.com/nqmn/waveflow#readme
Project-URL: Repository, https://github.com/nqmn/waveflow.git
Project-URL: Issues, https://github.com/nqmn/waveflow/issues
Keywords: wireless,waveform,simulation,network,ris,reconfigurable-intelligent-surface,beam-sweeping,ofdm,snr,pathfinding,machine-learning,5g,mmwave
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Communications
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pyyaml
Provides-Extra: web
Requires-Dist: flask; extra == "web"
Requires-Dist: waitress; extra == "web"
Provides-Extra: vision
Requires-Dist: opencv-python; extra == "vision"
Provides-Extra: optimization
Requires-Dist: cvxpy; extra == "optimization"
Requires-Dist: scs; extra == "optimization"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: terminal
Requires-Dist: typer; extra == "terminal"
Requires-Dist: rich; extra == "terminal"
Provides-Extra: ml
Requires-Dist: torch>=1.9.0; extra == "ml"
Requires-Dist: scikit-learn; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: all
Requires-Dist: flask; extra == "all"
Requires-Dist: waitress; extra == "all"
Requires-Dist: opencv-python; extra == "all"
Requires-Dist: cvxpy; extra == "all"
Requires-Dist: scs; extra == "all"
Requires-Dist: typer; extra == "all"
Requires-Dist: rich; extra == "all"
Requires-Dist: torch>=1.9.0; extra == "all"
Requires-Dist: scikit-learn; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: pytest>=6.0; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: black; extra == "all"
Requires-Dist: flake8; extra == "all"
Requires-Dist: mypy; extra == "all"
Dynamic: license-file

# Waveflow v2.0

[![PyPI version](https://img.shields.io/pypi/v/waveflow-sim)](https://pypi.org/project/waveflow-sim)
[![Python](https://img.shields.io/pypi/pyversions/waveflow-sim)](https://pypi.org/project/waveflow-sim)
[![License](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-nqmn%2Fwaveflow-lightgrey?logo=github)](https://github.com/nqmn/waveflow)

Waveflow is a Python simulator for wireless networks assisted by Reconfigurable Intelligent Surfaces (RIS). It lets researchers and engineers model how passive reflective panels improve signal coverage, optimize beam angles, and evaluate link quality — without physical hardware.

Use it to prototype RIS-assisted network topologies, benchmark beam sweeping algorithms, study propagation physics, simulate OFDM waveforms, and run ML-guided beam prediction — through a scriptable Python API, interactive CLI, or modern terminal commands.

## Quick Start

```bash
pip install waveflow-sim
waveflow
```

Or install from source:

```bash
git clone https://github.com/nqmn/waveflow
cd waveflow
pip install -e .
waveflow
```

Full installation options: **[INSTALL.md](INSTALL.md)**  
Step-by-step tutorials: **[TUTORIAL.md](TUTORIAL.md)**

## Features

| Category | Capability |
|---|---|
| **Network** | 2D/3D node placement (AP, RIS, UE), walls and obstacles, JSON/YAML topology files, random RIS-aware layout generation |
| **Physics** | FSPL, atmospheric absorption, Rician fading, mutual coupling, RIS array gain, phase quantization loss (1–4 bit) |
| **Beam sweeping** | Linear, coarse-fine, differential evolution, ML-guided, hierarchical, PRIME localization, HOG/ArUco vision |
| **Pathfinding** | Dijkstra, A\*, Greedy, Exhaustive across multi-hop RIS networks |
| **Waveform** | OFDM signal simulation, per-subcarrier SNR, multipath, PAPR, waveform-level vs system-level comparison |
| **Feedback** | Closed-loop UE→AP SNR feedback with adaptive beam tracking |
| **ML** | Random Forest, XGBoost, SVR, KNN, LGBM, MLP beam angle predictors; trainable from generated datasets |
| **Streaming** | Per-chunk BER, SER, throughput, and Shannon capacity over active RIS links |
| **Interface** | Interactive CLI, Typer/Rich terminal UI (`waveflow ui`), Python API, headless scenario runner |
| **Validation** | 14-section physics validation suite, 66 physics checks; 504 pytest checks across full suite |
| **MATLAB** | Optional bridge for far-field beam pattern plots and phase visualisation |

## Channel Engines

Waveflow now exposes two official RIS channel engines:

| Engine | Role | Best for |
|---|---|---|
| `simris` | Published/reference stochastic channel engine | literature-aligned channel studies, `H/G/D` channel tensors, supported channel-aware connect scenarios |
| `lightris` | Native analytical engine | fast system-level evaluation, beam control, tapering-aware workflows, feedback loops, large sweeps, ML dataset generation |

Design intent:
- `SimRIS` and `LightRIS` are complementary, not replacements for each other.
- `connect()` is now **SimRIS-first** by default.
- If a request is outside current SimRIS support, Waveflow falls back explicitly to `lightris` and reports the reason in the result metadata and CLI output.
- Sweep, tapering-heavy, and feedback-heavy workflows remain `LightRIS`-native by design.

## Usage

### Interactive CLI

```bash
waveflow
waveflow> add ap ap1 0 0
waveflow> add ris ris1 5 0 0 16 2
waveflow> add ue ue1 10 3
waveflow> connect ap1 ris1 ue1
SNR: 29.9 dB   Power: -52.3 dBm   Beam angle: 16.7°
waveflow> sweep ap1 ris1 ue1 60 10 --algo coarse-fine
waveflow> stream ap1 ris1 ue1
waveflow> status
waveflow> save mynet.json
waveflow> help
```

Key shell commands:

| Command | What it does |
|---|---|
| `add ap/ris/ue` | Add a node at specific coordinates |
| `add random` | Auto-generate a valid AP + RIS + UE layout |
| `connect` | Compute SNR, power, and beam angle for a link |
| `sweep` | Search for the best beam angle using a chosen algorithm |
| `stream` | Simulate a live data stream and measure throughput |
| `status` | Show all nodes, distances, and active links |
| `list` | Print an ASCII map of the network |
| `links` | Show active links only |
| `clear` | Remove links or the entire network |
| `save / load` | Persist and restore network state to/from JSON |
| `plot` | Visualise sweep or connect results (requires `[plot]`) |
| `signal` | Detailed per-hop signal breakdown |
| `testall` | Run the built-in test suite |
| `testphysics` | Run the physics validation suite |

### Modern Terminal UI

`waveflow ui` now covers both one-shot Rich commands and a native interactive modern shell. Use one-shot commands for scripts, CI, and reproducible runs; use `waveflow ui shell` when you want persistent in-memory state with the same modern command surface.

```bash
# Network status from a topology file
waveflow ui status --topology examples/json/example_1_simple.json

# Connect and get link metrics
waveflow ui connect AP1 R1 UE1 --topology examples/json/example_1_simple.json

# Force the reference engine explicitly
waveflow ui connect AP1 R1 UE1 --topology examples/json/example_1_simple.json --channel-model simris --environment indoor --scenario 1

# Force the native analytical engine explicitly
waveflow ui connect AP1 R1 UE1 --topology examples/json/example_1_simple.json --channel-model lightris

# Beam sweep with live progress bar
waveflow ui sweep AP1 R1 UE1 --topology examples/json/example_1_simple.json --fov 60 --step 10

# Rich-native topology and link inspection
waveflow ui list --topology examples/json/example_1_simple.json
waveflow ui links --topology examples/json/example_1_simple.json

# Run physics validation suite
waveflow ui testphysics

# Run the comprehensive test suite
waveflow ui testall

# Run any legacy CLI command non-interactively
waveflow ui run --topology examples/json/example_1_simple.json signal AP1 R1 UE1 --breakdown

# Open the native interactive modern shell
waveflow ui shell

# All available commands
waveflow ui --help
```

### Python API

High-level API:

```python
from waveflow import RISnet

net = RISnet()
ap  = net.addAP('ap1',  position=(0, 0))
ris = net.addRIS('ris1', position=(5, 0), N=16, bits=2)
ue  = net.addUE('ue1',  position=(10, 3))
net.start()

result = net.ping(ap, ue)
print(f"SNR: {result['snr_dB']:.1f} dB, hops: {result['hops']}")

throughput = net.iperf(ap, ue)
print(f"Throughput: {throughput['throughput_Mbps']:.1f} Mbps")

net.stop()
```

Low-level API:

```python
from core import RISNetwork

net = RISNetwork(enable_messaging=False)
net.add_ap('ap1', 0, 0)
net.add_ris('ris1', 5, 0, N=16, bits=2, max_angle_deg=90)
net.add_ue('ue1', 10, 3)

result = net.connect('ap1', 'ris1', 'ue1', use_get_snr=False)
print(f"SNR:        {result['snr_dB']:.1f} dB")
print(f"Beam angle: {result['beam_angle']:.1f}°")
print(f"Array gain: {result['gain_dBi']:.1f} dBi")
print(f"Quant loss: {result['quant_loss_dB']:.2f} dB")
print(f"Engine used: {result['channel_model_used']}")
```

Explicit engine selection:

```python
simris_result = net.connect(
    'ap1',
    'ris1',
    'ue1',
    channel_model='simris',
    environment='indoor',
    scenario=1,
    use_get_snr=False,
)

lightris_result = net.connect(
    'ap1',
    'ris1',
    'ue1',
    channel_model='lightris',
    use_get_snr=False,
)
```

Notes:
- If `channel_model` is omitted, `connect()` requests `simris` first.
- Unsupported SimRIS requests fall back to `lightris` with:
  - `channel_model_requested`
  - `channel_model_used`
  - `channel_model_fallback_reason`

### Headless Scenario Runner

Run simulations from JSON or YAML files — no Flask, no interactive shell:

```python
from risnet import ScenarioRunner, ScenarioRequest

runner = ScenarioRunner()

# From a topology file
result = runner.run_connect('examples/json/example_1_simple.json', use_get_snr=False)
print(f"SNR: {result.result['snr_dB']:.1f} dB")

# From a YAML scenario file
request = ScenarioRequest.from_file('scenario.yaml')
result = runner.run(request)
```

`scenario.yaml`:

```yaml
topology_path: examples/json/example_1_simple.json
connect:
  ap_name: ap1
  ris_name: ris1
  ue_name: ue1
```

## Beam Sweep Algorithms

```bash
waveflow> sweep ap1 ris1 ue1 60 10 --algo linear
waveflow> sweep ap1 ris1 ue1 60 10 --algo coarse-fine
waveflow> sweep ap1 ris1 ue1 60 10 --algo de
waveflow> sweep ap1 ris1 ue1 60 10 --algo ml-guided --ml-predictor rf
waveflow> sweep ap1 ris1 ue1 60 10 --algo prime
```

| Algorithm | Key | Notes |
|---|---|---|
| Linear brute-force | `linear` | Uniform steps over full FOV |
| Coarse-fine | `coarse-fine` | Two-phase search, ~30% fewer evaluations |
| Differential Evolution | `de` | Population-based global search |
| ML-guided | `ml-guided` | RF / XGBoost / SVR / KNN / LGBM predictor + refinement |
| Hierarchical | `hierarchical` | Multi-resolution sweep |
| PRIME localization | `prime` | Beam measurement → UE position estimate |
| DE localization | `de-localization` | Blind UE localization via DE |

## Optional Extras

```bash
pip install -e ".[plot]"         # matplotlib — enables plot command and charts
pip install -e ".[ml]"           # scikit-learn + torch — ML beam predictors
pip install -e ".[terminal]"     # typer + rich — waveflow ui commands
pip install -e ".[vision]"       # opencv-python — ArUco / HOG vision workflows
pip install -e ".[web]"          # flask + waitress — web interface
pip install -e ".[optimization]" # cvxpy + scs — phase optimization
pip install -e ".[dev]"          # pytest, black, flake8, mypy
pip install -e ".[all]"          # everything above
```

## Vision Integration

The `[vision]` extra enables two camera-assisted workflows:

**ArUco marker positioning** — generate printable fiducial markers, detect them from a camera feed, and derive UE position estimates for use as sweep inputs:

```bash
pip install -e ".[vision]"
PYTHONPATH=. python3 examples/script/example_18_aruco_markers.py
```

```
✓ Successfully saved: aruco_markers/aruco_id_0.png
Generated 5 markers: aruco_markers/batch/aruco_id_{0..4}.png
```

**HOG human detection** — use a histogram-of-oriented-gradients detector on a live webcam feed to locate a person and derive a candidate beam direction:

```bash
PYTHONPATH=. python3 examples/script/example_19_hog_human_detection.py
# Requires a connected webcam
```

Vision is example-driven rather than a full CLI product surface. The intended workflow is: detection output → target angle or position → feed into a sweep algorithm as a candidate beam direction.

## MATLAB Integration

Waveflow includes an optional MATLAB bridge for far-field beam pattern visualisation. The bridge is lazy-loaded — if MATLAB is not installed, all non-MATLAB functionality continues to work normally.

Standalone MATLAB scripts (no Python required) live in `examples/matlab/`:

| Script | What it shows |
|---|---|
| `example_1_beam_pattern_3d.m` | 3D far-field beam pattern, 1D/polar cuts, phase heatmap |
| `example_2_compare_steering_angles.m` | Side-by-side patterns for 6 steering angles |
| `example_3_ris_phase_farfield.m` | Phase maps + 3D far-field (Python-matched parameters) |
| `example_4_ris_phase_farfield_cst_style.m` | CST-style annotated 3D pattern with source/beam arrows |

Run from the MATLAB command window:

```matlab
cd examples/matlab
example_1_beam_pattern_3d
example_3_ris_phase_farfield(0, 5.8e9, 0.45, 0, 45, 0, 16, 16)
```

From Python, the bridge is accessed via `MatlabBridge`:

```python
from matlab_integration import MatlabBridge
bridge = MatlabBridge.get_instance()   # lazy-loaded; MATLAB starts on first use
bridge.plot_beam_pattern(...)
```

The library functions under `matlab_integration/scripts/` (`compute_beam_pattern`, `plot_ris_geometry`, etc.) are called by the Python bridge — they are not intended to be run directly.

## Project Structure

```
waveflow/
├── core/               # Physics, nodes, network manager, waveform, environment
├── controller/         # Beam sweeping, pathfinding, ML predictors, phase control
├── cli/                # Interactive shell (main_shell.py)
├── risnet/             # High-level API, scenario runner (backward-compatible package)
├── waveflow/           # Public package alias (forward-looking name)
├── app/                # Optional Flask web interface
├── config/             # Configuration management
├── utils/              # Link budget, SNR, RSSI, CSI helpers
├── matlab_integration/ # Optional MATLAB bridge for beam pattern plots
├── risformula/         # Standalone formula implementations
├── examples/
│   ├── script/         # 19 runnable Python examples
│   ├── json/           # Topology fixture files
│   └── matlab/         # Standalone MATLAB scripts
├── tests/              # Test suite (pytest)
├── INSTALL.md
├── TUTORIAL.md
└── FUTURE.md           # v3 architecture roadmap
```

## Testing

```bash
# Compile check
python3 -m compileall core controller cli risnet waveflow config utils

# Physics regression
PYTHONPATH=. python3 tests/test_physics_fixes.py

# Physics model validation suite (14 sections, 66 checks)
waveflow ui testphysics

# Full test suite via terminal UI
waveflow ui testall

# Full suite with pytest (504 checks across all test files)
pip install -e ".[dev]"
pytest tests/ -v
```

## Roadmap

See [FUTURE.md](FUTURE.md) for the full v3 architecture migration plan — phased arrays, spatial channels, AI-native runtime, and web interface.

## Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.

## Citation

If you use Waveflow in your research, please cite:

```bibtex
@software{waveflow,
  title  = {Waveflow: RIS-Assisted Wireless Network Simulator with Beam Sweeping, OFDM Waveform Simulation, and ML-Guided Beam Optimization},
  author = {Mohd Adil Mokti},
  year   = {2026},
  url    = {https://github.com/nqmn/waveflow}
}
```

## License

Apache 2.0 — see [LICENSE](LICENSE)
