README.md

# DualMaxwell: Hybrid Dual-Network PINN for Maxwell's Equations

This repository provides the official Python implementation for the paper: **"A Novel, Hybrid, Dual-Network PINN Framework for Solving Maxwell's Equations: Overcoming Numerical Instabilities, Scale Imbalance, and Sharp Geometries"**.

This package implements a framework for simulating electromagnetic (EM) fields by solving the full, 4D, vector Maxwell's equations using Physics-Informed Neural Networks (PINNs).

---

## Key Features & Challenges Addressed

This framework is specifically engineered to solve critical failure modes in standard PINN implementations:

1. **The Scale Challenge:** Overcomes the inherent "Scale Imbalance" (up to $10^9$) between Electric ($E$) and Magnetic ($B$) fields using non-dimensionalization.  
2. **The Geometry Challenge:** Utilizes **GeoNet** (a Multi-Resolution Hash Grid) to learn "sharp" geometry SDFs, avoiding the smoothing bias of standard MLPs.  
3. **The Training Challenge:** Implements a dual-network strategy with aggressive weight balancing to prevent "Catastrophic Forgetting" and trivial solutions.

---

##  Installation

You can install and run this framework on a local machine or in cloud environments like Google Colab.

**Note:** This repository contains large model files (`.pth`). If running locally, ensure you have **Git LFS** installed.

### Option 1: Google Colab (Recommended for Testing)

If you are running this on Google Colab, copy and paste the following commands into a code cell:

```python
# 1. Clone the repository from Hugging Face
!git clone https://huggingface.co/ayda138000/DualMaxwell

# 2. Enter the directory
%cd DualMaxwell

# 3. Install the package and dependencies
!pip install .
!pip install torch numpy matplotlib huggingface_hub
````

### Option 2: Local Machine (Terminal)

```bash
# Install Git LFS if you haven't already
git lfs install

# Clone the repository
git clone https://huggingface.co/ayda138000/DualMaxwell

# Navigate to the folder
cd DualMaxwell

# Install the package
pip install .
```

---

##  Running the Simulation

The repository includes an `example_usage.py` script that loads the pre-trained models (GeoNet and PhysNet) and visualizes the results.

### CRITICAL: Prepare Your Data (`ground_truth.npz`)

Before running the example, provide your own data file:

* The script expects a file named `ground_truth.npz` in the root `DualMaxwell` directory.
* **Google Colab:** Upload your `.npz` file into the `DualMaxwell` folder via the "Files" tab on the left sidebar.
* **Local:** Place the file in the cloned directory.

#### Required Data Structure

Your `ground_truth.npz` file must contain the following NumPy arrays:

* `coords`: Shape `(N, 3)`. Spatial coordinates $(x, y, z)$ used to normalize the geometry inputs.
* `t`: Shape `(T_steps,)` or `(N, 1)`. Time data, used to determine the maximum simulation time ($T_{max}$).

**Note:** If this file is missing or the keys `coords` and `t` do not exist, the script will exit with an error.

### Execution

Once the file is uploaded/placed, run the script:

**In Google Colab:**

```python
!python example_usage.py
```

**In Terminal:**

```bash
python example_usage.py
```

---

##  Expected Output

The script performs the following actions:

1. Loads GeoNet (`geonet_real_v30.pth`) to handle geometry boundaries.
2. Loads PhysNet (`physnet_v31_real.pth`) to predict EM fields.
3. Visualizes the $E_x$ field at time $t = 0.75 \times T_{max}$.
4. Saves the result as an image: `v35_final_plot_defense.png`.

---

##  Models Included

* **GeoNetHash:** Pre-trained on the geometry SDF using Multi-Resolution Hash Grids.
* **MaxwellPINN:** The physics-informed network trained to solve Maxwell's equations.


## License

This project is licensed under the MIT License.

```
```