| # 📡 **LWM: Large Wireless Model** | |
| **[🚀 Click here to try the Interactive Demo!](https://huggingface.co/spaces/sadjadalikhani/lwm-interactive-demo)** | |
| Welcome to the **LWM** (Large Wireless Model) repository! This project hosts a pre-trained model designed to process and extract features from wireless communication datasets, specifically the **DeepMIMO** dataset. Follow the instructions below to set up your environment, install the required packages, clone the repository, load the data, and perform inference with LWM. | |
| --- | |
| ## 🛠 **How to Use** | |
| ### 1. **Install Conda or Mamba (via Miniforge)** | |
| First, you need to have a package manager like **Conda** or **Mamba** (a faster alternative) installed to manage your Python environments and packages. | |
| #### **Option A: Install Conda** | |
| If you prefer to use **Conda**, you can download and install **Anaconda** or **Miniconda**. | |
| - **Anaconda** includes a full scientific package suite, but it is larger in size. Download it [here](https://www.anaconda.com/products/distribution). | |
| - **Miniconda** is a lightweight version that only includes Conda and Python. Download it [here](https://docs.conda.io/en/latest/miniconda.html). | |
| #### **Option B: Install Mamba (via Miniforge)** | |
| **Mamba** is a much faster alternative to Conda. You can install **Mamba** by installing **Miniforge**. | |
| - **Miniforge** is a smaller, community-based installer for Conda that includes **Mamba**. Download it [here](https://github.com/conda-forge/miniforge/releases/latest). | |
| After installation, you can use conda for environment management. | |
| --- | |
| ### 2. **Create a New Environment** | |
| Once you have Conda (https://conda.io/projects/conda/en/latest/user-guide/install/index.html), follow these steps to create a new environment and install the necessary packages. | |
| #### **Step 1: Create a new environment** | |
| You can create a new environment called `lwm_env`: | |
| ```bash | |
| conda create -n lwm_env | |
| ``` | |
| #### **Step 2: Activate the environment** | |
| Activate the environment you just created: | |
| ```bash | |
| conda activate lwm_env | |
| ``` | |
| --- | |
| #### **Step 3: Install Required Packages** | |
| Install the necessary packages inside your new environment. | |
| # Install CUDA-enabled Pytorch | |
| ```bash | |
| conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia | |
| ``` | |
| # Install other required packages from conda-forge | |
| ```bash | |
| conda install python numpy pandas matplotlib tqdm -c conda-forge | |
| ``` | |
| # Install DeepMIMOv3 with pip | |
| ```bash | |
| pip install DeepMIMOv3 | |
| ``` | |
| --- | |
| ### 3. **Required Functions to Clone Datasets** | |
| The following functions will help you clone specific dataset scenarios: | |
| ```python | |
| import subprocess | |
| import os | |
| # Function to clone a specific dataset scenario folder | |
| def clone_dataset_scenario(scenario_name, repo_url, model_repo_dir="./LWM", scenarios_dir="scenarios"): | |
| # Create the scenarios directory if it doesn't exist | |
| scenarios_path = os.path.join(model_repo_dir, scenarios_dir) | |
| if not os.path.exists(scenarios_path): | |
| os.makedirs(scenarios_path) | |
| scenario_path = os.path.join(scenarios_path, scenario_name) | |
| # Initialize sparse checkout for the dataset repository | |
| if not os.path.exists(os.path.join(scenarios_path, ".git")): | |
| print(f"Initializing sparse checkout in {scenarios_path}...") | |
| subprocess.run(["git", "clone", "--sparse", repo_url, "."], cwd=scenarios_path, check=True) | |
| subprocess.run(["git", "sparse-checkout", "init", "--cone"], cwd=scenarios_path, check=True) | |
| subprocess.run(["git", "lfs", "install"], cwd=scenarios_path, check=True) # Install Git LFS if needed | |
| # Add the requested scenario folder to sparse checkout | |
| print(f"Adding {scenario_name} to sparse checkout...") | |
| subprocess.run(["git", "sparse-checkout", "add", scenario_name], cwd=scenarios_path, check=True) | |
| # Pull large files if needed (using Git LFS) | |
| subprocess.run(["git", "lfs", "pull"], cwd=scenarios_path, check=True) | |
| print(f"Successfully cloned {scenario_name} into {scenarios_path}.") | |
| # Function to clone multiple dataset scenarios | |
| def clone_dataset_scenarios(selected_scenario_names, dataset_repo_url, model_repo_dir): | |
| for scenario_name in selected_scenario_names: | |
| clone_dataset_scenario(scenario_name, dataset_repo_url, model_repo_dir) | |
| ``` | |
| --- | |
| ### 4. **Clone the Model** | |
| Next, you need to clone the **LWM** model from its Git repository. This will download all the necessary files to your local system. | |
| ```bash | |
| # Step 1: Clone the model repository (if not already cloned) | |
| model_repo_url = "https://huggingface.co/sadjadalikhani/lwm" | |
| model_repo_dir = "./LWM" | |
| if not os.path.exists(model_repo_dir): | |
| print(f"Cloning model repository from {model_repo_url}...") | |
| subprocess.run(["git", "clone", model_repo_url, model_repo_dir], check=True) | |
| ``` | |
| --- | |
| ### 5. **Clone the Desired Datasets** | |
| Before proceeding with tokenization and data processing, the **DeepMIMO** dataset—or any dataset generated using the operational settings outlined below—must first be loaded. The table below provides a list of available datasets and their respective links for further details: | |
| 📊 **Dataset Overview** | |
| | 📊 **Dataset** | 🏙️ **City** | 👥 **Number of Users** | 🔗 **DeepMIMO Page** | | |
| |----------------|----------------------|------------------------|------------------------------------------------------------------------------------------------------------| | |
| | Dataset 0 | 🌆 Denver | 1354 | [DeepMIMO City Scenario 18](https://www.deepmimo.net/scenarios/deepmimo-city-scenario18/) | | |
| | Dataset 1 | 🏙️ Indianapolis | 3248 | [DeepMIMO City Scenario 15](https://www.deepmimo.net/scenarios/deepmimo-city-scenario15/) | | |
| | Dataset 2 | 🌇 Oklahoma | 3455 | [DeepMIMO City Scenario 19](https://www.deepmimo.net/scenarios/deepmimo-city-scenario19/) | | |
| | Dataset 3 | 🌆 Fort Worth | 1902 | [DeepMIMO City Scenario 12](https://www.deepmimo.net/scenarios/deepmimo-city-scenario12/) | | |
| | Dataset 4 | 🌉 Santa Clara | 2689 | [DeepMIMO City Scenario 11](https://www.deepmimo.net/scenarios/deepmimo-city-scenario11/) | | |
| | Dataset 5 | 🌅 San Diego | 2192 | [DeepMIMO City Scenario 7](https://www.deepmimo.net/scenarios/deepmimo-city-scenario7/) | | |
| It is important to note that these six datasets were **not** used during the pre-training of the LWM model, and the high-quality embeddings produced are a testament to LWM’s robust generalization capabilities rather than overfitting. | |
| #### **Operational Settings**: | |
| - **Antennas at BS**: 32 | |
| - **Antennas at UEs**: 1 | |
| - **Subcarriers**: 32 | |
| - **Paths**: 20 | |
| ```python | |
| # Step 2: Clone specific dataset scenario folder(s) inside the "scenarios" folder | |
| dataset_repo_url = "https://huggingface.co/datasets/sadjadalikhani/lwm" # Base URL for dataset repo | |
| scenario_names = np.array(["city_18_denver", | |
| "city_15_indianapolis", | |
| "city_19_oklahoma", | |
| "city_12_fortworth", | |
| "city_11_santaclara", | |
| "city_7_sandiego"] | |
| ) | |
| scenario_idxs = np.array([3]) | |
| selected_scenario_names = scenario_names[scenario_idxs] | |
| # Clone the requested scenario folders (this will clone every time) | |
| clone_dataset_scenarios(selected_scenario_names, dataset_repo_url, model_repo_dir) | |
| ``` | |
| --- | |
| ### 6. **Change the working directory to LWM folder** | |
| ```bash | |
| if os.path.exists(model_repo_dir): | |
| os.chdir(model_repo_dir) | |
| print(f"Changed working directory to {os.getcwd()}") | |
| else: | |
| print(f"Directory {model_repo_dir} does not exist. Please check if the repository is cloned properly.") | |
| ``` | |
| --- | |
| ### 7. **Tokenize and Load the Model** | |
| ```python | |
| from input_preprocess import tokenizer | |
| from lwm_model import lwm | |
| import torch | |
| preprocessed_chs = tokenizer(selected_scenario_names=selected_scenario_names, | |
| manual_data=None, | |
| gen_raw=True) | |
| device = 'cuda' if torch.cuda.is_available() else 'cpu' | |
| print(f"Loading the LWM model on {device}...") | |
| model = lwm.from_pretrained(device=device) | |
| ``` | |
| --- | |
| ### 8. **Perform Inference** | |
| ```python | |
| from inference import lwm_inference, create_raw_dataset | |
| input_types = ['cls_emb', 'channel_emb', 'raw'] | |
| selected_input_type = input_types[0] | |
| if selected_input_type in ['cls_emb', 'channel_emb']: | |
| dataset = lwm_inference(preprocessed_chs, selected_input_type, model, device) | |
| else: | |
| dataset = create_raw_dataset(preprocessed_chs, device) | |
| ``` | |
| --- | |
| ### 9. **Explore the Interactive Demo** | |
| If you'd like to explore **LWM** interactively, check out the demo hosted on Hugging Face Spaces: | |
| [**Try the Interactive Demo!**](https://huggingface.co/spaces/sadjadalikhani/LWM-Interactive-Demo) | |
| --- | |
| Now you’re ready to dive into the world of **Large Wireless Model (LWM)**, process wireless communication datasets, and extract high-quality embeddings to fuel your research or application! |