=========================== The openkim-api package ===========================

This directory contains template files for creating new KIM-compliant Models.
See the instructions below on how to use these files.

-----------------------------------------------------------------------------

This directory contains the following files:

Makefile.template
     A template for the Makefile that needs to be placed in the new Model
     directory.

README
     This file.

model_El_PF_Template.F90
     Fortran 90 template file for a pair functional (EAM, Finnis-Sinclair,
     effective medium theory, glue, etc.) Model.

model_El_PF_Template.f.kim
     KIM descriptor file for the Fortran pair functional template.

model_El_P_Template.F90
     Fortran 90 template file for a pair potential Model.

model_El_P_Template.c
     C template file for a pair potential Model.

model_El_P_Template.c.kim
     KIM descriptor file for the C pair potential template.

model_El_P_Template.f.kim
     KIM descriptor file for the Fortran pair potential template.

-----------------------------------------------------------------------------

A first look at the templates.

The templates are designed to facilitate the creation of new KIM-compliant
Models.  As a first step, we suggest that you compare the templates with
functioning KIM Models provided with this KIM API release.  This will allow you
to see what changes are needed to turn the templates into Models.  Detailed
directions are also given below.

1. The template `model_El_P_Template.c' can be compared with 
   `model_Ar_P_MLJ_C.c'. 

2. The template `model_El_P_Template.F90' can be compared with
   `model_Ar_P_MLJ_F90.F90'.

3. The template `model_El_PF_Template.F90' can be compared with
   `model_Al_PF_ErcolessiAdams.F90'.

To compare files, you can for example use the `vimdiff' command:

   % cd $KIM_DIR
   % vimdiff MODELs/model_Ar_P_MLJ_F90/model_Ar_P_MLJ_F90.F90 DOCs/TEMPLATEs/model_El_P_Template.F90

Alternatively use the `ediff' feature of the emacs editor.

-----------------------------------------------------------------------------

Direction for using the supplied templates to create a new KIM-compliant Model.

These direction show how to use the Fortran 90 template for a pair potential
(model_El_P_Template.F90) and turn it into a Model for argon (Ar) using a
Buckingham potential.  (The procedure for a Model written in C is essentially
identical. See comments below.)

1. Create a new directory under MODELs for the Ar pair potential:

   % cd $KIM_DIR/MODELs
   % mkdir model_Ar_P_Buckingham

2. Copy the .F90, .kim and Makefile templates into the new directory and
   rename:

   % cd $KIM_DIR/MODELs/model_Ar_P_Buckingham
   % cp $KIM_DIR/DOCs/TEMPLATEs/model_El_P_Template.F90 model_Ar_P_Buckingham.F90
   % cp $KIM_DIR/DOCs/TEMPLATEs/model_El_P_Template.f.kim model_Ar_P_Buckingham.kim
   % cp $KIM_DIR/DOCs/TEMPLATEs/Makefile.template Makefile

   Note: For a Model written in C, copy the .c and .c.kim templates.

3. Edit the .kim file and change the Model name to conform to the new Model and
   enter the species type.  (Search for the word "FILL" which indicates where
   changes are necessary.)  To edit a file on a unix machine, use for example:

   % pico model_Ar_P_Buckingham.kim

4. Edit the .F90 (or .c) file making all necessary changes.  (Search for the
   word "FILL".)  The main changes are:

   - Model name which appears in several places in the file.

   - Fill in the Model cutoff radius.

   - Define static parameters if necessary.  If these parameters need to be
     accessed outside the module (as in the _init() routine) add them to the
     list of public variables at the top of the module.

     Note: A Model cannot rely on static storage between calls.  A basic
     assumption in the KIM API is that *all* information needed by a Model to
     run is stored in the KIM API object.  This is necessary to allow multiple
     instances of the same Model being used simultaneously (see the Test
     `test_Ar_multiple_models' for an example of such usage).  The only case
     where static variables can be used is if they are "hard-wired" so that the
     Model can only work with those constant values.  In Fortran this is done
     using the "parameter" statement.  In C, use preprocessor DEFINE
     statements.  Otherwise variables need to be stored as PARAM_FREE_ or
     PARAM_FIXED_ variables in the KIM API object.  See the discussion in the
     standard.kim file.

   - Fill in the necessary code in the routines calc_phi() and calc_phi_dphi().

   - Add any necessary initialization into the _init() routine.

5. Edit the Makefile and change the Model name appropriately.  (Search
   for the word "FILL".)

6. Compile the new Model into the API package:

   % cd $KIM_DIR
   % make

   Correct any errors until the compilation succeeds.

7. You can now run Tests that are compatible with your Model simply by
   giving your new Model name as an argument.

   Note: If you run a Test and it does not seem to be working, remember to
         check the kim.log file for any messages.

*******************************************************************************

SUPPORT

If you have problems or questions, send an email with your question and all
relevant information to

openkim@googlegroups.com

The members of the openkim development team actively monitor this email list
and will do their best to help you with your question in a timely fashion.

*******************************************************************************
