[ ... ]
By the way, we are preparing for another beta replease (kim-api-v2-2.0.0-beta.3) in the next few days. The updates for this release are (essentiall) all aready in the 'devel-v2' branch of the kim-api github repo.
Great. I will wait for the release to avoid double work.
Significant changes/additions include:
* A new KIM_RoutineNames enumeration providing a run-time discoverable interface for the list of "top-level" model routines (Create, ComputeArgumentsCreate, Compute, etc.) defined by the kim api.
I don’t really see the point of this, so I am probably completely misunderstanding it. Could you elaborate what this is doing?
This is needed for use with IsRoutinePresent below.
* A new IsRoutinePresent() mechanism that Simulators need to use in order to determine if they are fully compatible with a particular model.
I am not sure what a model Routine is. Is it stuff like Compute etc? If so, why is this needed, don’t you already get a NULL pointer if you try to get a routine that the model does not provide?
The main need for this is to support backward compatibility in the case where new features are added to the kim-api.
Yes, these are the routines:
Compute, WriteParameterizedModel, ComputeArgumentsCreate/Destroy, Extension, etc.
Using this mechanism, a simulator can discover if a model it wants to use requires that the simulator employ features if the api that it does not know anything about. In that case the simulator can fail gracefully.
Suppose, as a hypothetical, in v2.2.0 we add a ChargeCompute() routine and, if it is provided by a model, it must be called by the simulator before the Compute routine. Then, your simulator, written for v2.0.0, doesn’t know anything about ChargeCompute(). But, using this mechanism, it can discover that there is something defined by the kim-api that it doesn’t know about but is required by the model...
* A change in the ModelCreate interface from individual calls to set routine pointer (SetComputePointer(), SetDestroyPointer(), etc.) to a unified call for each ModelRoutine: SetRoutinePointer().
OK. Will a ComputeArgumentsDestroy then be needed? My current model does not set any, mainly because I don’t think I need it, but also because I was not able to work out what the prototype should be.
Yes; often this can just be a no-op. (We decided it was simpler overall to require this function to be present than to deal with the complexity of handling two cases of present/absent.)
The necessary prototypes are defined in the KIM_FunctionTypes.hpp header file...
* Two new top-level routines added:
- WriteParameterizedModel(): This provides a mechanism whereby a ModelDriver
may be asked to write out its current parameters (which may have been
adjusted from their default values by the simulator's use of SetParameter()
and ClearThenRefresh()).
So this returns a big string? This makes a lot of sense, since it can be formatted in a more clever way that what the Simulator could do, as the simulator does not know what the parameters mean (nor does it know their “natural” shape, see below).
Not quite, it actually writes them to a specified directory on disk. Since there are, generally, an unknown number of files to be written, this seems like the only workable solution.
- Extension(): This proivides a very general way to extend the KIM API. A
Simulator and Model must both know about and agree on an extension data
strucuture. Once this requirement is met, then they may communicate in a
standard fashion that allows for any task to be performed.
Cool, but a bit dangerous, since it might cause models to lose their generality.
Yes, but we think this is necessary to encourage developers to work with the kim api even if their model’s needs are not fully supported by the standard. (The alternative is to implement their model fully in another system like lammps, and this will make it more difficult down the line to convert to KIM once the api supports the needed features.). This also provides an avenue for experimentation and proposals for official additions to future versions of the api.
May I suggest an optional feature: GetParameterShapeHint(int const parameterIndex) returning a string giving information about the shape of the parameter array. If not supported, it returns the empty string, and the simulator only knows the information returned by GetParameterMetadata(). The list of possible return values can be extended, but includes
“OneDimensional”. A 1-D array, the size is known from GetParameterMetadata().
“Square” An N*N matrix, N can be deducted from the size of the array (N^2).
“Cube” An N*N*N array, the size is N^3.
“UpperTriangular” An upper triangular matrix of size N*N, where the actual size of the array is N*(N-1)/2
“UpperTriangularWithZeros” Like “Square”, but elements below the diagonal are ignored.
“LowerTriangular”
“LowerTriangularWithZeros"
“(2, 43, 32, 10)” Actual dimensions of the array.
“” None of the above, or a scalar.
Interesting suggestion. Can you elaborate on a couple of use cases for this?
Why not just include this info. in the freeform parameter description text? In particular, how can the simulator really make use of this information? How does knowing this, programmatically, at run-time help? If all the program knows is that there is a double UpperTriangular parameter matrix, how is that better than knowing there is a list of parameters of a certain number?
* Some minor new functionality relateing to the KIM API logging mechanism has been added to the KIM::Log class: (PushDefaultVerbosity() and PopDefaultVerbosity()).
Some kind of documentation on how to use the logging would be nice. Also, is there a way for the simulator to discover the errors that the model may have logged, so they may be passed on to the user?
Yes. The next task is to document all the routines in the api and this will give me the chance to describe these features. (This is the last item on the list for final v2 release.)
The examples in the kim-api repo have been updated and adjusted to provide usage examples of the significant additions/changes described above.
Nice! The examples are very useful indeed
Yes, these need to eventually (after v2 official release) be fully redone. I want to carefully think out how best to illustrate all the features and requirements of the api and keep maintenance of the examples manageable...
Ryan