kim-api
2.3.0+v2.3.0.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
|
Previous Section: Implementation.
Experience with using and supporting the kim-api-v1 package has shown that the package's complexity (in terms of the number of different "modes of operation"; e.g., neighbor lists: half, full, iterator, locator; Neighbor-list Boundary Conditions (NBCs): cluster, miopbc, neigh_pure, neigh_rvec; etc.) makes it difficult for new users to become competent kim-api-v1 code developers. This also means that KIM Models will only work with KIM-compliant codes that support the same modes of operation, thereby limiting the utility of the kim-api as a standard. Further, the kim-api's complexity results in model implementations that are convoluted due to developers' desire to support all modes of operation. This experience has led us to an approach that gives kim-api-v2 a dramatically simplified form, while still retaining a high degree of flexibility. Thus, in regard to feature design and selection for the kim-api-v2 package, we have taken "simplicity" as a guiding principle.
KIM Descriptor Files Have Been Eliminated: kim-api-v2 does not use KIM descriptor files. Instead, kim-api-v2 models register their units, conventions, and parameters in their ModelCreate initialization routine, and they register their arguments and callbacks in their ModelComputeArgumentsCreate initialization routine. Simulator–model matching is now the responsibility of the simulator. This is facilitated by kim-api-v2 through the availability of routines for obtaining the model's registered values of all necessary quantities at run-time.
Best practice for kim-api-v2 simulators is to, first create a model object and an associated compute-arguments object (which also execute the model's initialization routines), second interrogate the model's capabilities to determine if the desired computation can be successfully performed with the model, and third, if possible, perform the desired computation.
This scheme for simulator–model matching places a larger burden (as compared to kim-api-v1) on the simulator. However, it has been determined that a full-featured "KIM descriptor file"–based matching specification (covering all possibilities) is too complex. Thus, it is best to perform this matching process in the simulator's code at run-time. In the worst-case, a simulator can simply assume that it matches with the model and attempt to perform the desired computation. As long as the simulator carefully checks for any and all errors reported by the KIM API, it should detect an error at some point during its processing if the simulator, in fact, does not match with the model.
A New Memory Management Scheme: kim-api-v2 requires the simulator to be responsible for storage memory associated with all input and output compute-arguments communicated between the simulator and the model via a compute-arguments object. Similarly, kim-api-v2 requires the model to be responsible for storage memory associated with its influence distance, its neighbor list cutoff values, and its published parameters.
kim-api-v2 does not provide a routine analogous to the KIM_API_Allocate() of kim-api-v1. This routine is now seen as a source of much confusion regarding the memory management model employed in kim-api-v1. Thus, it is best not to provide such a capability as part of kim-api-v2.
Language Consistency: kim-api-v2 aims to conform to standard practice and idioms of the native code language, as opposed to kim-api-v1 which aimed to maintain consistency of the api across languages.
This means that using the kim-api-v2 in your preferred language feels more natural. For example, the C++ api bindings extensively use namespaces, objects, std::string, and error codes as function return values. The Fortran api binding provides error codes as arguments to SUBROUTINES, uses handles to objects, and hides (as much as possible) the effort of making Fortran interoperable with C and other languages. In particular, the need for explicit use of the intrinsic C_F_POINTER() subroutine has been minimized.
Consistent identifier naming schemes have been established within each language binding. Abbreviations have been avoided to make names easier to remember.
Explicit Definitions: Clear definitions for all concepts used by the kim-api-v2 package are provided in Section Theory for the Portable Model Interface.
In most cases, these are the same concepts and definitions employed by kim-api-v1. However, they were not explicitly stated in the kim-api-v1 documentation.
FIXED Parameters Have Been Eliminated: kim-api-v2 defines only one type of "published" parameters for a model. These are all changeable, and thus, would correspond to the "FREE" parameters of kim-api-v1.
The FIXED parameters of kim-api-v1 must now be stored in the model buffer and are inaccessible to the simulator.
Argument Shape and Extent: For simplicity, explicit api tracking of argument shape and extent has been eliminated from kim-api-v2. These values are defined as part of the api documentation. All arguments must have fixed shape and extent values that are either given numbers or defined in terms of numberOfParticles.
Published model parameters are always taken to be one-dimensional arrays with a specified extent that must be defined by the model and communicated to the API through the get/set routines for parameters. Thus, scalar parameters have extent 1. Multidimensional array parameters are treated by the API as one-dimensional arrays with extent equal to the total number of values in the multidimensional array.
Consistent and Descriptive Identifier Names: The entire set of kim-api-v2 identifier names (namespace, module, object, subroutine, function, enumerations) have been reviewed and selected for clarity and consistency. As a result many of the identifier names from kim-api-v1 have changed in kim-api-v2. Here we provide complete tables of routine names, external enumeration constants, and external enumeration discovery routines.
Routine identifier name table:
Extensible enumeration identifier name table:
Extensible enumeration discovery and comparison routine identifier name table:
Next Seciton: Browse files.