Flexible units.

Moving this message to [email protected], which is more appropriate since it is of interest to the entire OpenKIM community....


I have a question regarding flexible unit handling in models. I would like to check if this is the right thing to do:

1) Use "Unit_handling := flexible" in the descriptor file.

What about the five lines describing the units? It looks like they still have to be there, but do they serve a purpose in this case?

Yes, they are required. As you indicate below, in many cases these values will not serve a useful purpose. However, it is conceivable that Models will exist which cannot handle unit conversions in the "best-practice" way described below. For example, a Model might use legacy subroutines that are hard-coded to a particular non-consistent set of units. In such a case the Model must perform unit conversions "on-the-fly".

Such a scenario implies a performance penalty. So, one use for the Unit_* lines for a flexible Model is to indicate a set of "preferred" units. If a Test uses these units the Model might be able to avoid "on-the-fly" conversions and be more computationally efficient.

2) When the model initialises, convert all parameters to the actual units used. This is done by calling KIM_API_convert_to_act_unit() and multiplying with the conversion factor returned. I seems that the actual units used then need to be specified in this call (I guess they should be consistent with what is in the descriptor file, but it looks like the specification here is what is important).


Do I need to do anything more? In particular, do I need to call KIM_API_get_unit_handling() to check for whether the actual unit handling is flexible or fixed?

When the Model supports flexible units as you describe above, there is no need for it to call KIM_API_get_unit_handling(). (Of course, you could avoid some multiplications by 1.0 if you used the result of this function to test for the need to do unit conversions. But, this is clearly optional.)

Or is that call and KIM_API_get_unit_length() and friends intended to let the *test* handle unit conversion if the model does not support it?

These routines are really for Models not Tests. Effectively, they always return the values specified in the Test's KIM descriptor file. So, they are generally not needed when the Model handles unit conversion as described above. However, there may be scenarios where a Model handles units in a different way, and in such cases there may be legitimate reasons that a Model would want to call KIM_API_get_unit_handling() and KIM_API_get_unit_length() and friends.