kim-api 2.4.1+v2.4.1-1-g0e2675b.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
 
Loading...
Searching...
No Matches
Summary of Differences Between kim-api-v1 and kim-api-v2

Previous Section: Implementation.

Note
This section describes version 2.0 of the KIM API. Additions made in version 2.1 and above to the KIM API package are not included.

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.

High-level changes between kim-api-v1 and kim-api-v2

  • NBCs Have Been Eliminated: kim-api-v2 supports only one type of configuration (as described in Section Theory for the Portable Model Interface). This corresponds, roughly, to the kim-api-v1 NEIGH_PURE_F NBC. Additionally:
    • All neighbor lists in kim-api-v2 are full, unordered, and random-access. (However, see Neighbor List Hint.)
    • Particle Contributing (a.k.a., padding or ghost-atom) status (contributing or non-contributing) is explicitly specified in the particleContributing argument. A particle with zero neighbors in (one of) its neighbor lists has no special meaning in kim-api-v2, as opposed to in kim-api-v1 where this indicates the particle is non-contributing.
  • Compute Routine Arguments and Callbacks Have Been Separated From the Model Object: kim-api-v2 separates the arguments and callbacks of the compute routine from the model object. These items are now stored in a separate compute-arguments object that must be provided to the model's compute routine. This new approach provides a cleaner conceptual distinction between things the model is responsible for (influence distance, cutoffs, parameters, and create / compute / destroy routines), and things that the simulator is responsible for (the configuration, compute-arguments, and compute-callback routines). One practical advantage of this separation occurs for multi-threaded simulators. Such a simulator can use a single model object with multiple compute-arguments objects to compute (energy, forces, etc.) for many different configurations simultaneously. Without the model/compute-arguments separation multiple model objects would be necessary. This would require multiple in-memory copies of the model's parameter set, which can be very wasteful since (in particular, for "machine learning" models) a model's parameter set can be very large.

  • 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.

  • Improved Logging Facilities and Error Messages: kim-api-v2 has been redesigned and rewritten from the ground up. Significantly improved facilities for logging events and execution progress have been included. Along with these general enhancements, all error messages have been rewritten with an eye toward improved clarity.

Lower-level changes between kim-api-v2 and kim-api-v1

Next Seciton: Browse files.