Data-Driven Magnetofrictional Relaxation

This demo relaxes a potential-field snapshot toward a force-free state while holding the bottom vector magnetic field fixed from a Python V1 data-driven boundary frame.

It deliberately uses the legacy magnetofriction implementation embedded in the MHD physics module (mhd_magnetofriction=.true.), not the newer standalone mf physics module. The MHD energy equation and gravity are disabled. Density remains uniformly one in code units because the legacy implementation uses it only in its Alfvén-speed/CFL estimate; the artificial velocity is constructed internally from the Lorentz force.

Expected workflow:

cd /path/to/potential/case
"$AMRVAC_DIR/setup.pl" -d=3
make
mpirun -np 4 ./amrvac -i amrvac.par data_driven_boundary.par
 
cd /path/to/magnetofrictional/case
"$AMRVAC_DIR/setup.pl" -d=3
make
mpirun -np 4 ./amrvac -i amrvac.par data_driven_mfr.par

The second run reads restart_from_file from data_driven_mfr.par; the notebook writes this path to the potential-field snapshot generated by the first run. The same B_0001.dat boundary frame is also passed through boundary_filename.

The boundary-frame binary layout is:

snapshot_time, nx, ny, dx, dy, Bx, By, Bz

dx and dy are stored in km, magnetic-field components in Gauss, and the arrays are written as a Fortran (nx, ny, 3) cube. The Python pipeline writes horizontal ghost padding into the frame; the AMRVAC physical domain size is set from the metadata fields excluding that padding.

The normalization is identical to the PotentialField case:

unit_length        = 1e9 cm
unit_temperature   = 1e6 K
unit_numberdensity = 1e9 cm^-3

AMRVAC derives the remaining units before initializing MHD, including unit_magneticfield (approximately 1.9976 G with the default fully ionized coronal composition). This ensures that both the restart field and the bottom magnetogram are converted from Gauss with the same factor.

The main user-facing relaxation controls are in mf_list:

mf_it_max=100000       ! total relaxation iterations
mf_ditsave=20000       ! checkpoint/VTU output interval
mf_cc=0.5d0            ! stability/CFL coefficient
mf_cy=0.2d0            ! magnetofriction velocity coefficient
mf_cdivb=0.01d0        ! diffusive div(B) cleaning coefficient
mf_log_mode='auto'     ! 'auto', 'append', or 'replace'
mf_log_filename=''     ! empty: <base_filename>_mflog.csv
mf_write_detailed_history=.false. ! enable the legacy _mflog.csv

With ‘mf_log_mode='auto’, a run starting from a potential snapshot (it=0) replaces the diagnostics CSV, while a restart from an MF checkpoint (it>0) appends to it. A nonemptymf_log_filename` gives the CSV any user-selected name.

refine_max_level=1 is valid and needs no AMR work. For higher levels, the Python staging helper rebuilds the restart grid immediately and the user refinement callback forces every block touching the driven lower boundary to the maximum level. Other blocks follow the magnetic-field refinement settings in meshlist.

The relaxation writes AMRVAC checkpoint snapshots and, when autoconvert is enabled, cell-centered VTU files under base_filename. It always writes <base_filename>_nlfff_metrics.csv, using the same compact external schema as the optimization and Grad–Rubin extrapolators:

iteration,CW_sin_theta,epsilon_force,epsilon_div,magnetic_energy

The existing _mflog.csv is available for compatibility and for its artificial MF time step, fractional-flux metric, mean current, and mean Lorentz force. It is disabled by default; add detailed_history.par to the input list or set mf_write_detailed_history=.true. in mf_list to enable it. The common file uses all active cells and is the preferred cross-method plot.