High-Level Interface

KIMCalculator(model_name::String; kwargs...) -> AtomsCalculators.AbstractCalculator

Create a simple AtomsCalculators-compatible calculator that wraps a KIM model.

This provides a minimal interface to KIM models that works with the AtomsCalculators ecosystem. The calculator can compute energies and forces for AtomsBase systems.

Arguments

• model_name::String: KIM model identifier

Keyword Arguments

• units::Symbol: Unit system (default: :metal)
• compute::Vector{Symbol}: Properties to compute (default: [:energy, :forces])

Example

using AtomsBase, AtomsCalculators
calc = KIMCalculator("SW_StillingerWeber_1985_Si__MO_405512056662_006")
energy = AtomsCalculators.potential_energy(calc, system)
forces = AtomsCalculators.forces(calc, system)

KIMModel(model_name::String; units=:metal, neighbor_function=nothing, compute=[:energy, :forces]) -> Function

Create a high-level KIM model computation function.

This function initializes a KIM-API model and returns a closure that can be called repeatedly to perform energy and force calculations. The returned function handles all low-level KIM-API operations automatically.

Arguments

• model_name::String: KIM model identifier (e.g., "SWStillingerWeber1985Si__MO405512056662_006")

Keyword Arguments

• units::Union{Symbol,NamedTuple}: Unit system to use. Can be:

  • :metal: Å, eV, e, K, ps (LAMMPS metal units)
  • :real: Å, kcal/mol, e, K, fs (LAMMPS real units)
  • :si: m, J, C, K, s (SI units)
  • :cgs: cm, erg, statC, K, s (CGS units)
  • :electron: Bohr, Hartree, e, K, fs (Atomic units)
  • Custom named tuple of units: (leng)

• neighbor_function: Custom neighbor function (not yet implemented)

• compute::Vector{Symbol}: Properties to compute, can include :energy and/or :forces

Returns

A function f(species, positions, cell, pbc) that:

• Accepts:
  • species::Vector{String}: Chemical symbols for each atom
  • positions::Vector{SVector{3,Float64}}: Atomic positions
  • cell::Matrix{Float64}: Unit cell matrix (3×3)
  • pbc::Vector{Bool}: Periodic boundary conditions [x,y,z]
• Returns:
  • NamedTuple: Results with fields :energy and/or :forces

Throws

• ErrorException: If model creation fails or requested properties not supported

Example

using KIM_API, StaticArrays, LinearAlgebra

# Create model function
model = KIM_API.KIMModel("SW_StillingerWeber_1985_Si__MO_405512056662_006")

# Define system
species = ["Si", "Si"]
positions = [
    SVector(0.    , 0.    , 0.    ),
    SVector(1.3575, 1.3575, 1.3575),
]
cell = Matrix([[0.0 2.715 2.715] 
               [2.715 0.0 2.715] 
               [2.715 2.71, 0.0]])
pbc = [true, true, true]

# Compute properties
results = model(species, positions, cell, pbc)
println("Energy: ", results[:energy])
println("Forces: ", results[:forces])

Implementation Notes

• Automatically generates ghost atoms for periodic boundary conditions
• Pre-computes species mappings for efficiency
• Handles multiple cutoff distances if required by the model
• Uses zero-based indexing internally to match KIM-API conventions