/*                                                                            */
/* 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--2018, 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.git repository.                  */
/*                                                                            */

/**
\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, avoiding the use of abbreviations, etc.

- **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**: The %KIM API implements a set of
    typed constants for each category of entity that it defines (DataType,
    LanguageName, Numbering, SpeciesName, LengthUnit, EnergyUnit, ChargeUnit,
    TemperatureUnit, TimeUnit, ComputeArgumentName, ComputeCallbackName,
    SupportStatus).  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 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 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.

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