So, I'll try to consicely state the current behavior:
1) KIM_API_get_num_model_species() returns the number of "spec" lines in the model's kim descriptor file.
2) KIM_API_get_num_sim_species() returns the number of "spec" lines in the simulator's kim descriptor file.
3) nubmerOfSpecies is an argument stored in the KIM API object that specifies the number of distinct species in the configuration represented by the data stored in the KIM API object. In principle, this is different than either of the above two values (although it must be less than or equal to both). The simulator is responsible for allocating and registering memory in which to store this value as well as setting this value. The KIM_API_allocate() routine is a convenience routine provided for simulators to use to help allocate and register all the memory that simulators are responsible for.
I'll leave it here and see what questions you still have.
As you can probably see from my previous email, I had overlooked this email. So the simulator should allocate most stuff, probably using KIM_API_allocate.
Hi Jakob, No problem. It is great to have your "outsider" view on all of this. You are identifying some aspects that we have been blind to. As a result of our not fully considering all of these issues, I see that there are a number of ways in wich the current definitions are conventions are confusing and ambiguous. Ultimately, this may lead to revisions of the KIM API to improve, clarify, and simplify its handling of parameters. For now, I'll try to describe the current system and best practice behavior within that system.
Also, if you have not already noticed, there is a lot of good information about who allocates/controls what/when in the "standard.kim" file.
But to summarize my main doubt from the previous email: what about the parameters (PARAM_FREE_XXX and friends). It sounds like KIM_API_allocate does not allocate these, so I assume the model should do it.
Should it read numberOfSpecies, read the actual species, allocate the arrays, and fill in the values for the relevant species? And what if the simulator wants to change some of the values in this array? If the model reallocates it during reinitialization, then the simulator cannot pass values in these arrays. If the simulator has not changed numberOfSpecies then I guess there is no problem, but what if it has changed?
This is something that was not clearly thoughtout, and so there is ambiguity in my own mind. However, now that the issue is clear, I'll try to create a definition of expected behavior.
First, I should note that is somewhat odd for a Model's parameters to depend on anything but the number of species supported by the *Model*. Thus, a parameter being defined with shape [numberOfSpecies] is really ill-defined. It would be more reasonable/common to have the explicit number of species supported by the Model listed in the shape, or if a model driver supports a variable number of speices, then a shape of the form [:] would be appropraite.
Second, I believe that a Model's parameters should not depend in any way on the information provided by the Simulator (in its kim descriptor file or in any of the input/output arguments stored in the KIM API object). In fact, in "standard.kim" there is a comment to the effect "...this storage should not depend on the content provided by the Simulator."
Now, the Model needs to allocate and set its parameters when KIM_API_model_init() is called (by the simulator). At the time of this call, only the "cutoff" argument is required to be allocated and registered (by the simulator) within the KIM API object. Thus, the model cannot expect to be able to access the "numberOfSpecies" argument at this time.
Until this discussion thread, I have been working under the (unconsious) tacit assumption that `numberOfSpecies' was identical to the value returned by KIM_API_get_num_sim_species(). (In fact, this api routine was only added at v1.6.0) However, the definition (given in "standard.kim") clearly says that `numberOfSpecies' is supposed to be the number of species in the configuration. This can certainly be different (less than) from the number of species listed in the simulator's kim descriptor file. So, it makes sense to allow this. Again, however, I don't see any situation in which a Model's parameters should depend on this value.
According to the documentation in "standard.kim" for parameters, the Model must allocate its parameters in its model_init() function and deallocate them in the model_destroy() function. It is not explicitly stated, but implied, that the memory should not be reallocated anywhere else. However, I can see that this policy should be reisited and documented. I can imagine a reasonable need for reallocation of the memory associated with a model's parameters. However, I believe this should only be allowed within the model_reinit() function. If that seams reasonable, then there should be no problem. The model would need to account for any changes to its parameter values before it reallocates the memory for these parameters. The main implication here would be that the simulator would have to update its pointers to the parameter memory locations after every call to KIM_API_model_reinit(), instead of being able to get them once and then assume that they are always valid.
I'm open to either policy, let me know what you think.