Fenton-Karma model: clarify and standardize units for diffusion coefficient, dx, and dt

[bjornverstraeten]

In the original model paper (https://doi.org/10.1063/1.166311), the diffusion coefficient is expressed in $cm^2/s$, while $dx$ is given in centimeters and $dt$ in milliseconds.
In the current implementation, however, the units are not specified and the diffusion coefficient is simply set to $1.0$.

Omitting units in this case is not trivial: as an example, using the parameters from Figure 5 of the paper

• $dx = 0.0262\text{cm} $,
• $dt = 0.17\text{ms} $,
• $D = 1\text{cm}^2/\text{s} $

leads to a violation of the CFL condition if units are ignored, resulting in non-convergent simulations.

I don’t think users should be expected to look up the original paper to determine the correct units. To avoid hidden pitfalls, I suggest the following:

• Set the diffusion coefficient to $0.1 \text{mm}^2/\text{ms}$.
• Explicitly specify that $dx$ is in millimeters and $dt$ in milliseconds.

With these conventions, users can safely omit unit conversions without risking instability.

I am not sure if the Fenton–Karma model is the only case where units cannot safely be ignored, but might also be worth discussing a general policy for handling and documenting physical units, especially if external contributors are expected to add new models.

[TiNezlobinsky]

Good point.

We usually always indicate the dimensions of dr and dt in examples - and these are always mm and ms. There are exceptions, such as dimensionless models. But in Fenton-Karma specifically, we didn't specify the dimensions, and that needs to be fixed.

Regarding diffusion, the framework as a whole currently lacks many "safeguards" and relies on user understanding. Will we change this? Yes, but not much - we will likely limit this to the informational part and try to provide stability assessment.