HION Module Guide¶

The HION (Hydrogen Ionization) module is an extension for the MHD solar simulation that provides a more detailed treatment of hydrogen ionization, moving beyond the approximations of local thermodynamic equilibrium (LTE). This guide outlines the steps for enabling, troubleshooting, and optimizing the HION module.

1. Initial Setup and Activation¶

To enable the HION module for a simulation, you need to adjust the input parameters and link the necessary data tables.

Steps for Activation¶

Enable the Module in Parameters: In your primary input parameters file, set the do_hion flag to 1:
```
do_hion = 1
```
Link HION Data Tables: The module requires specific data tables. Link all files from the HION_TAB directory into your experiment's working directory.
```
ln -s $BIFROST/INPUT/HION_TAB/* .
```
File Conflict

Linking these files will create a conflict with the existing radtab.dat file. It is crucial to remove the old radtab.dat and use the one provided in the HION_TAB directory.

Initial Run Behavior¶

When the simulation starts with HION for the first time, it will initialize the Hydrogen populations and begin calculations.

Initial Cost: The first iteration can be computationally expensive. The solver may require a significant number of Newton-Raphson (NR) iterations (often more than 10) for a few problematic cells to converge. [1, 9, 12]
Stabilization: After approximately one minute of solar time, the solver should stabilize. The number of NR iterations per step will decrease significantly, reducing the computational cost.

Monitoring Performance

You can monitor the number of Newton-Raphson iterations by saving the auxiliary variable it_h. This will help you visualize convergence behavior across the simulation domain and identify regions that require more computational effort.

2. Troubleshooting Convergence Issues¶

If you encounter problems with HION convergence, especially when starting from difficult snapshots, the following "tricks" can help stabilize the simulation. They are listed in order of recommended application.

2.1. Ensure Threshold Heating in `radtab.dat`¶

This is the most common and effective solution for initial stability problems.

Open the radtab.dat file.
Ensure a threshold heating value is set. A sensible value is 3000.0 K.
Critically, make sure the second argument on that line is greater than 1.0. A good starting point is 10.0 to ensure the temperature floor of 3000 K is actually reached.

Understanding the Threshold Heating Parameters

The second parameter for threshold heating in radtab.dat is often mislabeled as a time scale but is, in fact, a heating scaling factor. As shown in the get_thresh subroutine, the heating mechanism is not time-based but adds energy to cells that fall below a specified temperature floor (tmin). The amount of heating is proportional to the square of the temperature deficit: Heating ∝ (tmin - tg)². The second parameter (scl) directly multiplies this term. Therefore, a larger value applies stronger heating, helping the simulation to reach and maintain the minimum temperature more effectively.

Important: The scaling factor is > 1.0, which can cause problems with Ce. It is recommended to reduce Cdt to a small value and start with a small initial dt. The simulation will heat up quickly, and HION will fully engage within a few minutes of solar time.

2.2. Disable Rate Interpolation¶

If the simulation is still crashing, you can switch to a more explicit (though slower) calculation for exponential integrals.

In the input parameters file, set HionRateInterp to 0:
```
HionRateInterp = 0
```
This will increase the computation cost but can provide crucial stability during the initial phases of the simulation. You can re-enable it later for better performance once the run is stable.

2.3. Use the LAPACK LU Solver¶

If crashes persist, the issue may lie with the default LU solver. The LAPACK version provides enhanced numerical refinement and can resolve these issues. [3, 4]

Modify Source Code: Open the file math_mpi.f90.
Switch Subroutines: Comment out the default lineq subroutine and uncomment the version that uses LAPACK.
Recompile: Recompile the experiment. You will likely encounter an error during the final linking stage due to missing LAPACK symbols.
Link LAPACK Library: To fix the linking error, copy the final command from your terminal output (the one that starts with the compiler and ends with -o hion.x). Before the -o hion.x part, add the appropriate flag to link the LAPACK library. [4, 6, 13, 15] This is typically -llapack or -lqmkl if you are using the Intel MKL library.

Example:
```
# Original command from compiler output
ifort [..options..] -o hion.x

# Modified command to link LAPACK
ifort [..options..] -llapack -o hion.x
```

This sequence should be sufficient to start HION even from the most challenging initial snapshots.

3. Optimizing Performance¶

Once your simulation with HION has been running smoothly for some time, you can implement several changes to speed up the calculations. A "smooth" run is characterized by a low number of Newton-Raphson steps for most cells in the domain (which you can verify with the it_h auxiliary variable).

The following parameters can be set in your input file to increase performance:

Enable Rate Interpolation: This provides a significant speed-up by using pre-calculated tables for rates.
```
HionRateInterp = 1
```
Use the Fast Solver: This switches back to a less numerically intensive LU solver. Do not use this if you are experiencing convergence issues.
```
HionFastSolver = 1
```
Adjust Damping: The vdamp parameter controls the damping of the NR solver. You can try reducing it.
```
vdamp = 2.000E+00
```
Enable Adaptive Damping: This allows the module to automatically adjust the damping of the NR solver. A lower value leads to faster convergence.
```
adaptive_vdamp = 1
```

By applying these optimizations, you can significantly reduce the computational overhead of the HION module in a stable simulation.