# IGSS – Intelligent gprMax Simulation Software

**IGSS (Intelligent gprMax Simulation Software)** is a graphical tool built on top of **gprMax** for generating synthetic ground-penetrating radar (GPR) data and labeled datasets for machine learning (ML).

With IGSS, you can:

- Design a variety of subsurface scenarios (layers, materials, moisture, etc.)
- Run GPR simulations using gprMax
- Generate and visualize received signals
- Save signals together with labels for downstream ML training

---

## Citation

If you use IGSS in your research, please cite:

> H. Namdari, M. Moradikia, S. Zekavat, R. Askari, O. Mangoubi and D. Petkie,  
> "Advancing Precision Agriculture: Machine Learning-Enhanced GPR Analysis for Root-Zone Soil Moisture Assessment in Mega Farms,"  
> in *IEEE Transactions on AgriFood Electronics*, 2024, doi: **10.1109/TAFE.2024.3455238**.

**Keywords:** Feature extraction; Mathematical models; Data models; Soil moisture; Synthetic data; Moisture; Radar; Permittivity; Training; Soil measurements; Feature extraction; gprMax simulations; ground penetration radar (GPR); machine learning (ML); root zone soil moisture estimation (SME).

---

## Overview

IGSS is designed as an end-to-end environment for **intelligent GPR simulation**:

- A **GUI** for configuring gprMax simulations (materials, layers, antenna, domain, etc.)
- Integration with gprMax to compute **received signals**
- Tools to **save signals and corresponding labels** in formats suitable for ML pipelines
- Support for creating large, labeled synthetic datasets for:
  - Soil moisture estimation
  - Subsurface structure characterization
  - General GPR ML research and development

Whether you work in **academia** or **industry**, IGSS helps you:

- Prototype and test GPR scenarios quickly
- Generate controlled, labeled data for ML models
- Explore relationships between subsurface parameters and radar responses

---

## Requirements

IGSS requires the following software and hardware:

- **Python** 3.6 or higher  
- **gprMax** – Ground Penetrating Radar Simulation Tool  
  - Official repo: https://github.com/gprMax/gprMax  
- **Python packages**:
  - [NumPy](https://numpy.org/)
  - [Matplotlib](https://matplotlib.org/)
  - [Scikit-learn](https://scikit-learn.org/)
- A computer with at least **8 GB of RAM**

> ⚠️ **Important:** Please install and configure **gprMax** according to its official documentation before running IGSS. gprMax has its own dependencies and may require additional system libraries.

---

## Installation

### 1. Download the Repository

Using **git** (recommended):

```bash
git clone https://github.com/<your-username>/IGSS-Intelligent-gprMax-simulation-software.git
cd IGSS-Intelligent-gprMax-simulation-software

Or:

1. Go to the GitHub page of this project.
2. Click “Code” → “Download ZIP”.
3. Unzip the downloaded file.
4. Open a terminal and cd into the unzipped project folder.

2. (Optional) Create a Virtual Environment

It is recommended to use a virtual environment:

python -m venv .venv
# Activate on macOS / Linux:
source .venv/bin/activate
# Or on Windows:
# .venv\Scripts\activate

3. Install Python Dependencies

If you have a requirements.txt, you can use:

pip install -r requirements.txt

Otherwise, install dependencies manually:

pip install gprMax numpy matplotlib scikit-learn

Make sure that gprMax is correctly installed and accessible in the same environment.

---

How to Run IGSS

Once dependencies are installed and you are inside the project directory:

1. Launch the IGSS GUI

   python igss.py

   This command starts the IGSS graphical user interface.

2. Set Up a GPR Simulation Scenario

   In the GUI, you can:

   • Define subsurface layers and their material properties (e.g., permittivity, conductivity, moisture).
   • Configure antenna parameters and survey geometry.
   • Adjust domain size, grid resolution, and simulation time.

3. Run the Simulation

   • Use the appropriate button in the GUI to start the simulation.
   • IGSS internally calls gprMax to generate the received GPR signals.

4. Visualize and Inspect Results

   • View the simulated received signal within the GUI.
   • Optionally adjust visualization settings to analyze the signal.

5. Save Signals and Labels

   • Save the received signals along with their corresponding labels (e.g., soil composition, layer depths, moisture levels, etc.).
   • Data is stored in a machine-learning-friendly format (e.g., CSV, NumPy arrays) depending on your configuration.

6. Repeat for Additional Scenarios

   • Modify the scenario configuration (materials, layers, parameters).
   • Run new simulations and save more signals + labels.
   • Build a dataset covering a wide range of subsurface conditions.

7. Use the Data for ML Training

   • Load the saved signals and labels into your ML framework of choice (Scikit-learn, PyTorch, TensorFlow, etc.).

   • Train models for tasks such as:

     • Soil moisture estimation
     • Subsurface classification
     • Regression on physical parameters

---

Typical Workflow

1. Install gprMax and Python dependencies.
2. Download/clone the IGSS repository.
3. Run python igss.py to open the GUI.
4. Configure a GPR scenario in the interface.
5. Run the simulation and inspect the output signal.
6. Save the signal and labels.
7. Repeat to build a dataset.
8. Train ML models using the generated labeled data.

---

Contributing

Contributions are welcome!

If you:

• Find a bug
• Have an idea for a new feature
• Want to improve the GUI, documentation, or ML workflows

please open an issue or submit a pull request.

When reporting an issue, please include:

• Operating system and Python version
• gprMax version
• Steps to reproduce the problem
• Any error messages or screenshots

---

Contact

For questions about IGSS or related research, please contact:

Himan Namdari Lead developer / corresponding author

(You can also refer to the contact information listed in the cited publication.)