/*                                                                            */
/* 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.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, 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,
  KIM::Collection, KIM::CollectionItemType).
  This allows for backward-compatible additions to the enumerations in future
  versions of the %KIM API.  Further, the strong-typing greatly facilitates
  debugging.

- **Discoverable Collections Interface**: Support is provided (via a
  KIM::Collections object) for programatic discovery of all
  KIM::CollectionItemType%s (Model Drivers, Portable Models, and Simulator
  Models) in each of the KIM::Collection%s which are configured and
  installed on the computing system.

- **Portable Model Interface (the %KIM API/PMI)**:

  See \ref kim_api_pmi "The KIM API/PMI" for a description of the PMI. Features
  for the PMI include

  - **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 *portable 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 should ensure that these lists contain only a
    small number of particles that are located outside the cutoff distance.
    Models must provide "hints" in a standard format (explained \ref
    neighbor_list_hint "here") 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, along with
    some user-defined species for development purposes and toy models.  In the
    future support for models that require multiple types of each element may
    be added.

  - **Model Parameters**: The %KIM philosophy views a *portable 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 portable
    model to (optionally) "publish" its parameters so that a simulator may
    modify them during the course of a simulation.  This feature is also useful
    for codes designed to fit interatomic models.

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

- **Simulator Model Interface (the %KIM API/SMI)**:

  See \ref kim_api_smi "The KIM API/SMI" for a description of the SMI.
  Features of the SMI include

  - **Simulator Model (SM) Specification File**: The SM specification file
    records simulator input commands and other important metadata needed to run
    the SM in its native simulator.

  - **Simulator Name and Version Tracking**: The SM's associated simulator name
    and version are recorded in the specification file to allow for explicitly
    verifying compatibility of the SM package with the simulator's identity and
    version.

  - **Supported Species List**: The SM's supported species strings (arbitrary
    strings identifying the atomic species the model simulates) are recorded in
    the specification file and are made available to the simulator.

  - **Parameter Files**: Any number of parameter files may be encapsulated
    within the SM package and provided to the simulator in a simple and
    unobtrusive manner.

  - **Flexible Simulator Field/Line Framework**: Simulator input commands and
    additional metadata necessary to run the SM are stored in the SM
    specification file.  A flexible framework of "Simulator Fields" containing
    one or more "Simulator Field Lines" give each simulator maximum flexibility
    in defining its own specialized interface and satisfying its own needs.

  - **Template Substitution**: Simulator Field Lines can contain template keys
    that will be replaced by values stored in a "Template Map".  The template
    map contains mappings defined by the %KIM API/SMI as well as custom
    mappings defined by the simulator.  This mechanism provides flexibility and
    dynamic behavior allowing the simulator's handling of the SM to be adjusted
    at run time.

- **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, KIM::ComputeArguments, and
  KIM::SimulatorModel).  In each object there is a "SimulatorBufferPointer"
  which is for use by the simulator.  For the KIM::Model and
  KIM::ComputeArguments objects there is also a "ModelBufferPointer" which is
  for use by the portable model's routines.  (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 PMI SMI SM
LocalWords:  ComputeCallbackName ModelBufferPointer SimulatorBufferPointer pmi
LocalWords:  programatic metadata SM's smi
