Update README.md

README.md

@@ -1,106 +1,120 @@
-#  DualMaxwell (pinn_electromagnetics)
+# DualMaxwell: Hybrid Dual-Network PINN for Maxwell's Equations
 
-[cite_start]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"**[cite: 1].
+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"**.
 
-[cite_start]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)[cite: 8, 19].
+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).
 
-[cite_start]The primary goal of this framework is to overcome the fundamental challenges that cause naive PINN implementations to fail in real-world engineering problems[cite: 6, 8].
+---
 
-##  Key Challenges Addressed
+## Key Features & Challenges Addressed
 
-This framework is specifically engineered to solve three critical failure modes:
+This framework is specifically engineered to solve critical failure modes in standard PINN implementations:
 
-1.  [cite_start]**The Scale Challenge:** The inherent "Scale Imbalance" (up to $10^9$) between the Electric (E) and Magnetic (B) fields in SI units, which causes the optimizer to ignore the B-field loss[cite: 10, 41].
-2.  [cite_start]**The Geometry Challenge:** The "Smoothing Bias" of standard MLPs, which fails to learn the "Sharp Corners" of real geometries (producing a "Squircle" instead)[cite: 11, 53].
-3.  [cite_start]**The Training Challenge:** The "Loss War" between the physics (PDE) and data (boundaries), leading to "Trivial Solutions" (e.g., $E=0$) and "Catastrophic Forgetting" during training[cite: 13, 46, 48].
+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.
 
-##  The Dual-Network Framework
+---
 
-[cite_start]To solve these challenges, we developed a novel, hybrid, dual-network architecture[cite: 14].
+##  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.
 
-Our system is composed of:
+### Option 1: Google Colab (Recommended for Testing)
 
-* **1. [cite_start]Non-Dimensionalization:** We non-dimensionalize the entire Maxwell problem, which completely resolves the E/B "Scale Imbalance" (Solution to Challenge 1)[cite: 16, 58].
-* **2. [cite_start]GeoNet (v26):** An advanced **"Multi-Resolution Hash Grid"** network (inspired by Instant-NGP)[cite: 17, 60]. [cite_start]It is pre-trained to learn the "sharp" geometry SDF and is then frozen (Solution to Challenge 2)[cite: 18, 60].
-* **3. [cite_start]PhysNet (v34):** A 4D (x,y,z,t) PINN that solves the full, non-dimensionalized Maxwell's equations[cite: 19, 61].
-* **4. [cite_start]Novel Training Strategy (v34):** A two-stage **"Pre-training and Annealing"** strategy combined with **"Aggressive Weight Balancing"** ($\lambda_{source}=10000$)[cite: 20, 62]. [cite_start]This forces the model to learn the "Source" first and prevents "Catastrophic Forgetting" (Solution to Challenge 3)[cite: 21].
+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
 
-##  Installation and Usage
+# 2. Enter the directory
+%cd DualMaxwell
 
-**IMPORTANT:** This repository uses **Git LFS** (Large File Storage) to manage large model (`.pth`) and data (`.npz`) files. You **must** have Git LFS installed to clone this repository correctly.
+# 3. Install the package and dependencies
+!pip install .
+!pip install torch numpy matplotlib huggingface_hub
+````
 
-### Step 1: Install Git LFS
+### Option 2: Local Machine (Terminal)
 
-If you don't have it, install it from [https://git-lfs.github.com](https://git-lfs.github.com).
-Then, enable it (you only need to do this once per machine):
 ```bash
+# Install Git LFS if you haven't already
 git lfs install
-```
 
-### Step 2: Clone the Repository
+# Clone the repository
+git clone https://huggingface.co/ayda138000/DualMaxwell
 
-Clone this repository. Git LFS will automatically download the large files.
-```bash
-git clone [https://huggingface.co/ayda138000/DualMaxwell](https://huggingface.co/ayda138000/DualMaxwell)
+# Navigate to the folder
+cd DualMaxwell
+
+# Install the package
+pip install .
 ```
 
-### Step 3: Install the Package
+---
 
-Navigate into the cloned directory and install the package using `pip`. This will also install all required dependencies listed in `setup.py` (like `torch`, `numpy`, etc.).
-```bash
-cd DualMaxwell
-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
 ```
 
-### Step 4: Run the Example
+**In Terminal:**
 
-You can now run the example script to load the pre-trained models, run the simulation, and visualize the results.
 ```bash
 python example_usage.py
 ```
 
 ---
 
-##  Expected Data Format
+##  Expected Output
 
-The `example_usage.py` script expects a `ground_truth.npz` file containing the following NumPy arrays:
+The script performs the following actions:
 
-* **`coords`**: `(N, 3)` array of 3D coordinates for sampling the geometry.
-* **`sdf`**: `(N,)` array of Signed Distance Function (SDF) values for the `coords`.
-* **`E0`**: `(N, 3)` array of initial E-field values (at $t=0$) at `coords`.
-* **`B0`**: `(N, 3)` array of initial B-field values (at $t=0$) at `coords`.
-* **`source_position`**: `(3,)` array for the (x,y,z) coordinates of the antenna source.
-* **`source_orientation`**: `(3,)` array for the orientation of the source E-field (e.g., `[1,0,0]` for x-polarized).
-* **`source_signal`**: `(T_steps,)` array for the time-varying signal of the source.
-* **`t`**: `(T_steps,)` array of time points corresponding to `source_signal`.
+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`.
 
 ---
 
-##  Core Components
-
-### Models Included
-
-* `HashGridEncoder`: Efficient multi-resolution hash grid encoder for spatial coordinates.
-* [cite_start]`GeoNetHash`: A geometry network that learns Signed Distance Functions (SDFs) of complex objects using `HashGridEncoder`[cite: 68, 119, 120].
-* `PositionalEncoder4D`: A standard positional encoder for 4D (x, y, z, t) inputs.
-* [cite_start]`MaxwellPINN`: The core physics-informed neural network that predicts electromagnetic fields (E, B) based on space and time coordinates[cite: 72].
+##  Models Included
 
-### Loss Functions Inc
-* `compute_all_derivatives`: Helper function to compute all necessary partial derivatives of E and B fields with respect to x, y, z, and t.
-* [cite_start]`compute_maxwell_loss`: Implements the physics-based loss derived from the non-dimensionalized Maxwell's equations [cite: 78, 144-150].
-* [cite_start]`compute_data_loss`: Computes the data-driven loss from initial conditions (E0, B0) and source boundary conditions [cite: 75, 204-207].
+* **GeoNetHash:** Pre-trained on the geometry SDF using Multi-Resolution Hash Grids.
+* **MaxwellPINN:** The physics-informed network trained to solve Maxwell's equations.
 
-## Citation
 
-If you use this framework or code in your research, please cite our paper:
+## License
 
-```bibtex
-  title   = {A Novel, Hybrid, Dual-Network PINN Framework for Solving Maxwell's Equations: Overcoming Numerical Instabilities, Scale Imbalance, and Sharp Geometries},
+This project is licensed under the MIT License.
 
-##  License
-
-This project is licensed under the MIT License.
+```
+```