Enhance README with MACE-Field documentation

Added detailed documentation for MACE-Field, including data format, required labels, and training instructions.

Author: Neutrino155

README.md

@@ -1,3 +1,99 @@
+## MACE-Field: Field-Aware MACE Models
+
+**MACE-Field** extends the MACE architecture to learn **electric-field–dependent properties** of molecules and materials.  
+In addition to standard **energies, forces, and stresses**, MACE-Field can simultaneously predict
+
+- macroscopic **polarisation**,
+- **Born effective charges (BECs)**,
+- **polarizabilities**,
+
+as explicit functions of an applied **electric field**.
+
+This makes MACE-Field suitable for finite-field simulations, dielectric response, and field-driven molecular dynamics.
+
+---
+
+## 1. Data format and required labels
+
+MACE-Field is trained from ASE-readable datasets (typically extended XYZ). In addition to the usual structural data, field-aware training requires extra keys.
+
+### 1.1. Required `atoms.info` keys (configuration-level)
+
+- `REF_energy`  
+  Total DFT energy (eV)
+
+- `REF_stress` *or* `REF_virials`  
+  Stress / virials tensor (Voigt-6 or 3×3)
+
+- `REF_electric_field`  
+  Applied electric field vector, shape `(3,)` (V/Å)
+
+- `REF_polarization`  
+  Macroscopic polarisation vector, shape `(3,)` (typically in e/Ų)
+
+- `REF_polarizability`  
+  Polarizability tensor, shape `(3,3)` or flattened `(9,)` (in units of ε₀)
+
+- `head` *(optional)*  
+  Head label, e.g. `"Default"`
+
+### 1.2. Required `atoms.arrays` keys (per-atom)
+
+- `REF_forces`  
+  Atomic forces, shape `(N, 3)` (eV/Å)
+
+- `REF_becs`  
+  Born effective charges, shape `(N, 3, 3)` (units of |e|)
+
+Key names can be overridden from the command line, but the above are the recommended defaults.
+
+---
+
+## 2. Training a MACE-Field model
+
+Training is done via the standard MACE CLI with `--model MACEField` and the `universal_field` loss.
+
+### 2.1. Example training command
+
+```bash
+python -m mace.scripts.run_train \
+    --model MACEField \
+    --name macefield_model \
+    --train_file data/field_train.xyz \
+    --valid_fraction 0.2 \
+    \
+    --device cuda \
+    --default_dtype float32 \
+    \
+    --r_max 5.0 \
+    --num_interactions 2 \
+    --num_channels 128 \
+    --max_L 1 \
+    --correlation 3 \
+    \
+    --loss universal_field \
+    \
+    --energy_key REF_energy \
+    --forces_key REF_forces \
+    --stress_key REF_stress \
+    --virials_key REF_virials \
+    --electric_field_key REF_electric_field \
+    --polarization_key REF_polarization \
+    --becs_key REF_becs \
+    --polarizability_key REF_polarizability \
+    \
+    --energy_weight 1.0 \
+    --forces_weight 100.0 \
+    --stress_weight 1.0 \
+    --polarization_weight 1.0 \
+    --becs_weight 1.0 \
+    --polarizability_weight 1.0 \
+    \
+    --batch_size 8 \
+    --max_num_epochs 50 \
+    --lr 1e-3
+```
+
 # <span style="font-size:larger;">MACE</span>
 
 [![GitHub release](https://img.shields.io/github/release/ACEsuit/mace.svg)](https://GitHub.com/ACEsuit/mace/releases/)