KIM API V2
Summary of Differences Between kim-api-v1 and kim-api-v2

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; 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

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

Routine Identifier Name translation table:

kim-api-v1 kim-api-v2 C++ Binding
KIM_API_file_init() N/A
KIM_API_string_init() KIM::Model::Create()
KIM_API_get_version() KIM::SEM_VER::GetSemVer()
KIM_API_get_version_major() N/A
KIM_API_get_version_minor() N/A
KIM_API_get_version_prerelease() N/A
KIM_API_get_version_build_metadata() N/A
N/A KIM::SEM_VER::ParseSemVer()
KIM_API_version_newer() KIM::SEM_VER::IsLessThan()
KIM_API_model_info() N/A
KIM_API_allocate() N/A
KIM_API_c_free() N/A
KIM_API_free() KIM::Model::Destroy()
KIM_API_print() KIM::Model::String(), KIM::ModelCreate::String(), KIM::ModelComputeArgumentsCreate::String(), KIM::ModelComputeArgumentsDestroy::String(), KIM::ModelCompute::String(), KIM::ModelRefresh::String(), KIM::ModelDestroy::String(), KIM::ComputeArguments::String()
KIM_API_model_compute() KIM::Model::Compute()
KIM_API_model_destroy() N/A
KIM_API_get_model_index_shift() N/A
N/A KIM::ModelCreate::SetModelNumbering(), KIM::ModelDriverCreate::SetModelNumbering()
KIM_API_set_model_buffer() KIM::ModelCreate::SetModelBufferPointer(), KIM::ModelDriverCreate::SetModelBufferPointer(), KIM::ModelComputeArgumentsCreate::SetModelBufferPointer()
KIM_API_set_sim_buffer() KIM::Model::SetSimulatorBufferPointer(), KIM::ComputeArguments::SetSimulatorBufferPointer()
KIM_API_get_model_buffer() KIM::ModelCompute::GetModelBufferPointer(), KIM::ModelDestroy::GetModelBufferPointer(), KIM::ModelRefresh::GetModelBufferPointer(), KIM::ModelComputeArguments::GetModelBufferPointer(), KIM::ModelComputeArgumentsDestroy::GetModelBufferPointer()
KIM_API_get_sim_buffer() KIM::Model::GetSimulatorBufferPointer(), KIM::ComputeArguments::GetSimulatorBufferPointer()
KIM_API_is_half_neighbors() N/A
KIM_API_set_data() KIM::ComputeArguments::SetArgumentPointer()
N/A KIM::ModelComputeArgumentsCreate::SetArgumentSupportStatus()
N/A KIM::ComputeArguments::GetArgumentSupportStatus()
N/A KIM::ModelComputeArgumentsCreate::SetCallbackSupportStatus()
N/A KIM::ComputeArguments::GetCallbackSupportStatus()
KIM_API_set_method() KIM::ComputeArguments::SetCallbackPointer()
KIM_API_get_data() KIM::ModelComputeArguments::GetArgumentPointer()
KIM_API_get_method() N/A
N/A KIM::ModelComputeArguments::IsCallbackPresent()
N/A KIM::ComputeArguments::AreAllRequiredArgumentsAndCallbacksPresent()
KIM_API_get_size() N/A
KIM_API_get_rank() N/A
KIM_API_get_shape() N/A
KIM_API_set_shape() N/A
KIM_API_set_compute() N/A
KIM_API_get_compute() N/A
N/A KIM::ModelCreate::SetInfluenceDistancePointer(), KIM::ModelDriverCreate::SetInfluenceDistancePointer(), KIM::ModelRefresh::SetInfluenceDistancePointer()
N/A KIM::Model::GetInfluenceDistance()
N/A KIM::Model::GetNeighborListPointers()
N/A KIM::ModelCreate::SetNeighborListPointers(), KIM::ModelDriverCreate::SetNeighborListPointers(), KIM::ModelRefresh::SetNeighborListPointers()
N/A KIM::ModelCreate::SetRefreshPointer(), KIM::ModelDriverCreate::SetRefreshPointer()
N/A KIM::ModelCreate::SetDestroyPointer(), KIM::ModelDriverCreate::SetDestroyPointer()
N/A KIM::ModelCreate::SetComputeArgumentsCreatePointer(), KIM::ModelDriverCreate::SetComputeArgumentsCreatePointer()
N/A KIM::ModelCreate::SetComputeArgumentsDestroyPointer(), KIM::ModelDriverCreate::SetComputeArgumentsDestroyPointer()
N/A KIM::ModelCreate::SetComputePointer(), KIM::ModelDriverCreate::SetComputePointer()
KIM_API_get_index() N/A
KIM_API_model_init() N/A
KIM_API_model_reinit() KIM::Model::ClearThenRefresh()
KIM_API_get_num_model_species() N/A
KIM_API_get_model_species() KIM::Model::GetSpeciesSupportAndCode()
KIM_API_get_num_sim_species() N/A
KIM_API_get_sim_species() N/A
N/A KIM::ModelDriverCreate::GetNumberOfParameterFiles()
N/A KIM::ModelDriverCreate::GetParameterFileName()
KIM_API_get_num_params() KIM::Model::GetNumberOfParameters()
KIM_API_get_parameter() KIM::Model::GetParameter()
N/A KIM::Model::SetParameter()
N/A KIM::Model::GetParameterDataTypeExtentAndDescription()
N/A KIM::ModelCreate::SetParameterPointer(), KIM::ModelDriverCreate::SetParameterPointer()
KIM_API_get_num_free_params() N/A
KIM_API_get_free_parameter() N/A
KIM_API_get_num_fixed_params() N/A
KIM_API_get_fixed_parameter() N/A
KIM_API_get_NBC_method() N/A
KIM_API_get_species_code() KIM::Model::GetSpeciesSupportAndCode()
KIM_API_set_species_code() KIM::ModelCreate::SetSpeciesCode(), KIM::ModelDriverCreate::SetSpeciesCode()
KIM_API_get_model_kim_str_len() N/A
KIM_API_get_model_kim_str() N/A
KIM_API_get_neigh_mode() N/A
KIM_API_get_neigh() KIM::ModelComputeArguments::GetNeighborList()
KIM_API_process_dEdr() KIM::ModelComputeArguments::ProcessDEDrTerm()
KIM_API_process_d2Edr2() KIM::ModelComputeArguments::ProcessD2EDr2Term()
KIM_API_get_status_msg() N/A
KIM_API_report_error() KIM::Log::LogEntry(), KIM::ModelCreate::LogEntry(), KIM::ModelCompute::LogEntry(), KIM::ModelRefresh::LogEntry(), KIM::ModelDestroy::LogEntry(), KIM::ModelComputeArguments::LogEntry(), KIM::ModelComputeArgumentsCreate::LogEntry(), KIM::ModelComputeArgumentsDestroy::LogEntry()
N/A KIM::Model::SetLogID(), KIM::ComputeArguments::SetLogID()
N/A KIM::Model::PushLogVerbosity(), KIM::ComputeArguments::PushLogVerbosity()
N/A KIM::Model::PopLogVerbosity(), KIM::ComputeArguments::PopLogVerbosity()
KIM_API_get_scale_conversion() KIM::ModelCreate::ConvertUnit(), KIM::ModelDriverCreate::ConvertUnit()
KIM_API_get_unit_handling() N/A
KIM_API_get_unit_length() KIM::Model::GetUnits()
KIM_API_get_unit_energy() KIM::Model::GetUnits()
KIM_API_get_unit_charge() KIM::Model::GetUnits()
KIM_API_get_unit_temperature() KIM::Model::GetUnits()
KIM_API_get_unit_time() KIM::Model::GetUnits()
N/A KIM::ModelCreate::SetUnits(), KIM::ModelDriverCreate::SetUnits()
KIM_API_convert_to_act_unit() N/A
KIM_API_set_data_by_index() N/A
KIM_API_set_method_by_index() N/A
KIM_API_get_data_by_index() N/A
KIM_API_get_method_by_index() N/A
KIM_API_get_size_by_index() N/A
KIM_API_get_rank_by_index() N/A
KIM_API_get_shape_by_index() N/A
KIM_API_set_compute_by_index() N/A
KIM_API_get_compute_by_index() N/A
KIM_API_getm_compute() N/A
KIM_API_setm_compute() N/A
KIM_API_getm_compute_by_index() N/A
KIM_API_setm_compute_by_index() N/A
KIM_API_getm_data() N/A
KIM_API_getm_method() N/A
KIM_API_setm_data() N/A
KIM_API_setm_method() N/A
KIM_API_getm_data_by_index() N/A
KIM_API_getm_method_by_index() N/A
KIM_API_setm_data_by_index() N/A
KIM_API_setm_method_by_index() N/A
KIM_API_getm_index() N/A

Extensible enumeration Identifier Name translation table:

kim-api-v1 kim-api-v2 C++ Binding
"numberOfParticles" KIM::COMPUTE_ARGUMENT_NAME::numberOfParticles
"particleSpecies" KIM::COMPUTE_ARGUMENT_NAME::particleSpeciesCodes
N/A KIM::COMPUTE_ARGUMENT_NAME::particleContributing
"coordinates" KIM::COMPUTE_ARGUMENT_NAME::coordinates
"energy" KIM::COMPUTE_ARGUMENT_NAME::partialEnergy
"forces" KIM::COMPUTE_ARGUMENT_NAME::partialForces
"particleEnergy" KIM::COMPUTE_ARGUMENT_NAME::partialParticleEnergy
"virial" KIM::COMPUTE_ARGUMENT_NAME::partialVirial
"particleVirial" KIM::COMPUTE_ARGUMENT_NAME::partialParticleVirial
"cutoff" N/A
"numberContributingParticles" N/A
"numberOfSpecies" N/A
"particleCharge" N/A
"particleSize" N/A
"neighObject" N/A
"boxSideLengths" N/A
"temperature" N/A
"hessian" N/A
"PARAM_FREE_cutoff" N/A
"get_neigh" KIM::COMPUTE_CALLBACK_NAME::GetNeighborList
"process_dEdr" KIM::COMPUTE_CALLBACK_NAME::ProcessDEDrTerm
"process_d2Edr2" KIM::COMPUTE_CALLBACK_NAME::ProcessD2EDr2Term
"ZeroBasedLists" KIM::NUMBERING::zeroBased
"OneBasedLists" KIM::NUMBERING::oneBased
"Neigh_IterAccess" N/A
"Neigh_LocaAccess" N/A
"Neigh_BothAccess" N/A
"CLUSTER" N/A
"NEIGH_PURE_H" N/A
"NEIGH_PURE_F" N/A
"NEIGH_RVEC_H" N/A
"NEIGH_RVEC_F" N/A
"MI_OPBC_H" N/A
"MI_OPBC_F" N/A
"electron" KIM::SPECIES_NAME::electron
"H" KIM::SPECIES_NAME::H
"He" KIM::SPECIES_NAME::He
etc. etc.
"user20" KIM::SPECIES_NAME::user20
"C" KIM::CHARGE_UNIT::C
"e" KIM::CHARGE_UNIT::e
"statC" KIM::CHARGE_UNIT::statC
N/A KIM::CHARGE_UNIT::unused
"amu_A2_per_ps2" KIM::ENERGY_UNIT::amu_A2_per_ps2
"erg" KIM::ENERGY_UNIT::erg
"eV" KIM::ENERGY_UNIT::eV
"Hartree" KIM::ENERGY_UNIT::Hartree
"J" KIM::ENERGY_UNIT::J
"kcal_mol" KIM::ENERGY_UNIT::kcal_mol
N/A KIM::ENERGY_UNIT::unused
"A" KIM::LENGTH_UNIT::A
"Bohr" KIM::LENGTH_UNIT::Bohr
"cm" KIM::LENGTH_UNIT::cm
"m" KIM::LENGTH_UNIT::m
"nm" KIM::LENGTH_UNIT::nm
N/A KIM::LENGTH_UNIT::unused
"K" KIM::TEMPERATURE_UNIT::K
N/A KIM::TEMPERATURE_UNIT::unused
"fs" KIM::TIME_UNIT::fs
"ps" KIM::TIME_UNIT::ps
"ns" KIM::TIME_UNIT::ns
"s" KIM::TIME_UNIT::s
N/A KIM::TIME_UNIT::unused

Each of the extensible enumerations in kim-api-v2 has an interface for discovering all of the members of the enumeration. This is implemented using two functions. One provides the number of members in the enumeration, and the other provides a copy of the \(i\)-th enumeration member. (The ordering is undefined, but guaranteed to be stable during any single run-time program execution using the KIM API.) For example, the KIM::ChargeUnit enumeration has the KIM::CHARGE_UNIT::GetNumberOfChargeUnits() and the KIM::CHARGE_UNIT::GetChargeUnit() functions.

In addition, the KIM::ComputeArgumentName enumeration also has the KIM::COMPUTE_ARGUMENT_NAME::GetComputeArgumentDataType() function.

Next Section: Guide for porting content from KIM API v1 to v2.