/*                                                                            */
/* CDDL HEADER START                                                          */
/*                                                                            */
/* The contents of this file are subject to the terms of the Common           */
/* Development and Distribution License Version 1.0 (the "License").          */
/*                                                                            */
/* You can obtain a copy of the license at                                    */
/* http://www.opensource.org/licenses/CDDL-1.0.  See the License for the      */
/* specific language governing permissions and limitations under the License. */
/*                                                                            */
/* When distributing Covered Code, include this CDDL HEADER in each file and  */
/* include the License file in a prominent location with the name             */
/* LICENSE.CDDL.                                                              */
/* If applicable, add the following below this CDDL HEADER, with the fields   */
/* enclosed by brackets "[]" replaced with your own identifying information:  */
/*                                                                            */
/* Portions Copyright (c) [yyyy] [name of copyright owner].                   */
/* All rights reserved.                                                       */
/*                                                                            */
/* CDDL HEADER END                                                            */
/*                                                                            */

/*                                                                            */
/* Copyright (c) 2017--2019, Regents of the University of Minnesota.          */
/* All rights reserved.                                                       */
/*                                                                            */
/* Contributors:                                                              */
/*    Ryan S. Elliott                                                         */
/*    Ellad B. Tadmor                                                         */
/*    Daniel Karls                                                            */
/*                                                                            */

/*                                                                            */
/* Release: This file is part of the kim-api-2.0.2 package.                   */
/*                                                                            */

/**
\page features Features of the %KIM API package

Previous Section: \ref index.

This version of the %KIM API package is distributed under the [CDDL 1.0 Open
Source License](http://www.opensource.org/licenses/CDDL-1.0).

The current version of the %KIM API package supports the following features:

- **Programming Languages**: Currently supported programming languages include
  C, C++, Fortran.

- **Best Practice API Design**: The guiding design principle for the %KIM API
  has been *simplicity*.  In addition to this, general API design *best
  practices* have been used.  These include: implementation hiding (pimpl
  idiom), loose coupling, minimal-completeness, ease of use (discoverable,
  difficult to misuse, consistent, orthogonal), static factory methods, use of
  namespaces, const-correctness, and avoiding the use of abbreviations.

- **Language Idiom Support**: Wherever it makes sense and is possible the %KIM
  API supports common idioms of the native language.  For example, all C API
  routines that return an error status do so using the C function return value.
  For Fortran, all such API routines are SUBROUTINES and have their final
  argument as an error status.

- **Extensible, Strongly-Typed Enumerations**: \anchor extensible_enumeration
  The %KIM API implements a set of typed constants for each category of entity
  that it defines (KIM::ChargeUnit, KIM::ComputeArgumentName,
  KIM::ComputeCallbackName, KIM::DataType, KIM::EnergyUnit, KIM::LanguageName,
  KIM::LengthUnit, KIM::LogVerbosity, KIM::ModelRoutineName, KIM::Numbering,
  KIM::SpeciesName, KIM::SupportStatus, KIM::TemperatureUnit, KIM::TimeUnit).
  This allows for backward-compatible additions to the enumerations in future
  versions of the %KIM API.  Further, the strong-typing greatly facilitates
  debugging.

- **Numbering Origin Support**: Support for automatic translation between
  zero-based numbering of particles (C-style numbering beginning with zero) and
  one-based numbering (Fortran-style numbering beginning with one).

- **Data Communication**: Communication of an arbitrary number of *arguments*
  and *callback* routines between a *model* (interatomic potential) and
  a *simulator* (simulation code that uses a model).

- **Data types**: integer and double.

  Each of the data types can be used to create multi-dimensional array
  arguments that are exchanged between models and simulators.  The %KIM API
  standard defines the dimension and extent of these arrays for each argument.
  However, this information is not discoverable at run-time.  Thus, it is left
  to the programmer to ensure that the correct values are used.

  Currently, the %KIM API does not define any (more complex) data structures.
  However, in the future (as the need arises, and in consultation with the
  atomistic and molecular simulation community) additional data types and data
  structures may be introduced.

- **Physical Units**: The %KIM API standard defines the physical units for each
  argument exchanged between a model and simulator.  A simulator provides a set
  of *requested units* to define a unit system and a model either accepts this
  unit system (and performs appropriate unit conversions for its parameters),
  or it rejects the request and reports the unit system to be used.

- **Neighbor lists**: Neighbor list routines are expected to be provided by the
  calling simulator.  All neighbor lists are full, unsorted lists that must
  contain all particles within the specified cutoff distance (but may contain
  additional particles).  A model must request one or more neighbor lists, each
  with an associated cutoff distance.  (Cutoff distances are typically
  distinct, but may repeat.  Repeated cutoff distances allow a model to
  simultaneously access the neighbors of multiple particles without needing to
  make copies of the neighbor list(s).)  A simulator must provide all such
  requested lists and ensure that these lists contain only a small number of
  particles that are located outside the cutoff distance.  Models must provide
  "hints" about how they use neighbor lists.  These hints allow the simulator
  to, optionally, optimize its neighbor list build algorithm.

- **Particle Species**: The %KIM API provides the ability to designate the
  physical species of each particle in a simulation.  Currently, only one
  identifier is provided for each element in the periodic table.  In the future
  support for models that require multiple types of each element may be added.

- **Model Parameters**: The %KIM philosophy views a *model* as a well-defined
  computational code that includes specific values for all parameters needed to
  perform an actual computation.  However, it is often useful to explore how a
  model's predictions vary as the values of its parameters are varied.  For
  this reason, the %KIM API allows a model to (optionally) "publish" its
  parameters so that a simulator may modify them during the course of a
  simulation.

- **Model Drivers**: The %KIM API package provides the ability to create model
  driver routines.  A model driver is an implementation of an interatomic
  potential functional-form.  A model for a given material can be created which
  uses an existing model driver by providing a file or files with the
  appropriate parameter values for the material system of interest.

- **Logging capabilities**: The %KIM API package provides a full-featured
  logging capability that facilitates the identification and debugging of
  errors.  In addition to built-in support for logging within model codes, the
  %KIM API also provides access to logging capabilities for general use by
  simulator codes.

- **Caching capabilities**: \anchor cache_buffer_pointers The %KIM API package
  provides a mechanism to store a pointer to a memory (cache) buffer in the
  main API objects (KIM::Model and KIM::ComputeArguments).  In each case there
  is a "ModelBufferPointer" which is for use by the model's routines and a
  "SimulatorBufferPointer" which is for use by the simulator.  (These buffer
  pointers are not to be used for communication between the simulator and
  model, and therefore the ModelBufferPointer is not accessible to the
  simulator and vise-versa.)

- **Semantic Versioning**: The %KIM API package conforms to the [Semantic
  Versioning 2.0.0](https://semver.org) standard.  This standard is useful
  because its version numbers and the way they change convey meaning about the
  underlying code and what has been modified from one version to the next.  In
  addition, the %KIM API provides basic tools for comparing and parsing Semantic
  Version strings.


Next Section: \ref theory.

*/

LocalWords:  CDDL yyyy Ellad Tadmor Karls kim api pimpl discoverable const ref
LocalWords:  DataType LanguageName SpeciesName LengthUnit EnergyUnit TimeUnit
LocalWords:  ChargeUnit TemperatureUnit ArgumentName CallbackName interatomic
LocalWords:  SupportStatus atomistic Versioning ComputeArgumentName
LocalWords:  ComputeCallbackName ModelBufferPointer SimulatorBufferPointer
