WiInSim

This repository contains the official WiInSim (Wireless Indoor Simulation) dataset implementation of the Wi3R and WiPTR dataset. The two datasets are part of the paper "Differentiable and Learnable Wireless Simulation with Geometric Transformers" by Thomas Hehn, Markus Peschl, Tribhuvanesh Orekondy, Arash Behboodi, and Johann Brehmer, published at ICLR 2025. The code of the main paper will be published soon in the Wi-GATr repository.

Getting started

Download the data

WiInSim is intended to be used with the Wi3R and WiPTR datasets. You can go to the Qualcomm Developer Hub and download the zip files of Wi3R.zip and WiPTR.zip there.

If you want to use the default configurations of this repository, unpack the files into the data/ folder or create symlinks there. The default config files expect two subfolders data/Wi3R and data/WiPTR.

Setup

Clone the repository

First, let's define the path where we want the repository to be downloaded:

REPO_PATH=<path/to/repo>

Now we can clone the repository:

git clone https://github.com/Qualcomm-AI-research/WiInSim $REPO_PATH

Optional: Environment setup

Here we go through detailed steps to setup a virtual environment to avoid interfering with your system Python installation. If you prefer to use your system Python installation, you can skip this step.

Next, if desired, create a virtual environment. Note: This code-base has been tested with Python 3.10.

cd $REPO_PATH
python3 -m venv env
source env/bin/activate
pip install --upgrade --no-deps pip

Installation via pip

Finally, install WiInSim and its dependencies:

cd $REPO_PATH
pip install .

Running tests

After following the installation instructions above, you can check that the package was installed correctly, by running some regression tests.

cd $REPO_PATH
pytest

Visualizing the data

You can check some visualization examples in a Jupyter notebook. Start the notebook as follows:

cd $REPO_PATH
pip install .[notebook]  # Install visualization dependencies.
jupyter lab notebooks/

This will generate visualizations of the 3D mesh of a floor plan including a transmitter (big red dot) and some receiver locations colored by the respective received power. This looks something like this:

Train/test splits

WiPTR comes with predefined training, test, and validation splits. You can find the relevant configuration files in the config/ folder. For Wi3R there are no predefined splits. You can see the Wi-GATr repository for more information on what splits were used in the paper.

Repository structure

$REPO_PATH
├── config  # Config files to load the different datasets.
│   ├── baseconfig.yaml  # Shared base configuration.
│   ├── wi3r_main_5tx.yaml  # Wi3R main dataset (5k floor plans, no predefined splits).
│   ├── wi3r_ood_fourrooms.yaml  # Out-of-distribution data with four rooms.
│   ├── wi3r_ood_scaled.yaml  # Out-of-distribution data with a rescaled coordinates (not used in Wi-GATr paper).
│   ├── wi3r_ood_squared.yaml  # Out-of-distribution data with squared floor layouts (not used in Wi-GATr paper).
│   ├── wi3r_grid.yaml  # Wi3R floor plans with receivers laid out on a 2D grid (visualization data).
│   ├── wiptr_train.yaml  # WiPTR training data (10k floor plans).
│   ├── wiptr_test.yaml  # WiPTR test data (1k floor plans).
│   ├── wiptr_val.yaml  # WiPTR Validation data (1k floor plans).
│   ├── wiptr_val_ood.yaml  # WiPTR Out-of-distribution data where some walls are dropped to connect rooms.
│   ├── wiptr_train_grid.yaml  # WiPTR training floor plans with receivers laid out on a 2D grid (used for visualization).
│   ├── wiptr_val_grid.yaml  # WiPTR validation floor plans with receivers laid out on a 2D grid (used for visualization).
│   ├── test_regression_wi3r.yaml  # Config used for pytest testing.
│   └── test_regression_wiptr.yaml  # Config used for pytest testing.
├── data
│   └── test_regression
│       ├── wi3r  # Subset of the Wi3R data used for testing.
│       │   ├── ...
│       │   ...
│       └── wiptr  # Subset of the WiPTR data used for testing.
│           ├── ...
│           ...
├── media
│   └── WiPTR_sample.png  # Example of visualizations.
├── notebooks
│   └── visualize_multifloor_dataset.ipynb  # Notebook with visualization examples.
├── pyproject.toml  # Project configuration file.
├── README.md  # This instruction text.
├── setup.py  # Setup file for packaging.
├── src
│   └── wiinsim
│       ├── __init__.py
│       ├── dataset.py  # Main dataset class for loading data per floor plan.
│       ├── multifloordataset.py  # Wrapper class to combine multiple floor datasets into a single dataset.
│       ├── utils.py  # Helper functions.
│       └── visualization.py  # Visualization functions.
└── tests
    ├── __init__.py
    ├── test_regressions  # Directory for expected test output.
    │   └── ...
    └── test_regressions.py  # Black-box regression tests.

Citation

If you use our dataset, please cite:

@misc{hehn2024wigatr,
      title={Differentiable and Learnable Wireless Simulation with Geometric Transformers},
      author={Thomas Hehn and Markus Peschl and Tribhuvanesh Orekondy and Arash Behboodi and Johann Brehmer},
      year={2024},
      eprint={2406.14995},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2406.14995},
}