kim-api
2.2.1+v2.2.1.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
|
Provides the primary interface to a KIM API SimulatorModel object and is meant to be used by simulators. More...
#include <KIM_SimulatorModel.hpp>
Public Member Functions | |
void | GetSimulatorNameAndVersion (std::string const **const simulatorName, std::string const **const simulatorVersion) const |
Get the SimulatorModel's simulator name and version. More... | |
void | GetNumberOfSupportedSpecies (int *const numberOfSupportedSpecies) const |
Get the number of species supported by the SimulatorModel. More... | |
int | GetSupportedSpecies (int const index, std::string const **const speciesName) const |
Get a species name supported by the SimulatorModel. More... | |
void | OpenAndInitializeTemplateMap () |
Open and initialize the template map for simulator field line substitutions. More... | |
int | TemplateMapIsOpen () const |
Determine if the template map is open. More... | |
int | AddTemplateMap (std::string const &key, std::string const &value) |
Add a new key-value entry to the template map. More... | |
void | CloseTemplateMap () |
Close the template map and perform template substitutions. More... | |
void | GetNumberOfSimulatorFields (int *const numberOfSimulatorFields) const |
Get the number of simulator fields provided by the SimulatorModel. More... | |
int | GetSimulatorFieldMetadata (int const fieldIndex, int *const extent, std::string const **const fieldName) const |
Get the metadata for the simulator field of interest. More... | |
int | GetSimulatorFieldLine (int const fieldIndex, int const lineIndex, std::string const **const lineValue) const |
Get a line for the simulator field of interest with all template substitutions performed (Requires the template map is closed). More... | |
void | GetParameterFileDirectoryName (std::string const **const directoryName) const |
Get absolute path name of the temporary directory where parameter files provided by the simulator model are written. More... | |
void | GetSpecificationFileName (std::string const **const specificationFileName) const |
Get the SimulatorModel's specification file basename (file name without path). The file is located in the SimulatorModel's parameter file directory. More... | |
void | GetNumberOfParameterFiles (int *const numberOfParameterFiles) const |
Get the number of parameter files provided by the SimulatorModel. More... | |
int | GetParameterFileName (int const index, std::string const **const parameterFileName) const |
Get the basename (file name without path) of a particular parameter file. The file is located in the SimulatorModel's parameter file directory. More... | |
int | GetParameterFileBasename (int const index, std::string const **const parameterFileBasename) const |
Get the basename (file name without path) of a particular parameter file. The file is located in the SimulatorModel's parameter file directory. More... | |
void | SetSimulatorBufferPointer (void *const ptr) |
Set the Simulator's buffer pointer within the SimulatorModel object. More... | |
void | GetSimulatorBufferPointer (void **const ptr) const |
Get the Simulator's buffer pointer from the SimulatorModel object. More... | |
std::string const & | ToString () const |
Get a string representing the internal state of the SimulatorModel object. More... | |
void | SetLogID (std::string const &logID) |
Set the identity of the Log object associated with the SimulatorModel object. More... | |
void | PushLogVerbosity (LogVerbosity const logVerbosity) |
Push a new LogVerbosity onto the SimulatorModel object's Log object verbosity stack. More... | |
void | PopLogVerbosity () |
Pop a LogVerbosity from the SimulatorModel object's Log object verbosity stack. More... | |
Static Public Member Functions | |
static int | Create (std::string const &simulatorModelName, SimulatorModel **const simulatorModel) |
Create a new KIM API SimulatorModel object. More... | |
static void | Destroy (SimulatorModel **const simulatorModel) |
Destroy a previously SimulatorModel::Create'd object. More... | |
Provides the primary interface to a KIM API SimulatorModel object and is meant to be used by simulators.
Simulator Models (SMs) are a mechanism by which the KIM API provides support for models that are implemented natively in simulation codes ("Simulators"). An SM consists of all the information and data required to use the model from within its simulator. This includes a specification file in EDN format (see https://openkim.org/about-edn/) containing instructions and settings that must be specified for the simulator to define and use the model, and one or more parameter files. The KIM API SimulatorModel model object provides a generic interface to access the parameter files and the contents of the specification file. Each simulator may define its own set of "simulator fields" that contain simulator-specific content for the model's setup. A simulator field consists of zero or more "lines". Each line is a string containing information that is meaningful to the simulator. To allow the simulator to specialize the field lines based on user input, the SimulatorModel interface provides a template substitution mechanism. Each simulator field line may contain template tags of the form "@<key>@" and will be replaced by an appropriate value provided by the SimulatorModel object or the simulator.
The KIM API defines the following set of standard template key-value entries:
parameter-file-dir
, with a value equal to the absolute path name of the SimulatorModel's temporary parameter file directory. This directory is created when the SimulatorModel object is SimulatorModel::Create'd and is removed when the object is SimulatorModel::Destroy'd.parameter-file-basename-#
(# ranges from 1 to the SimulatorModel's number of parameter files), with a value equal to the basename (file name without path) of the corresponding parameter file. (Parameter file ordering is defined by the order files are listed in the SMs CMakeLists.txt file.)parameter-file-#
(# ranges from 1 to the SimulatorModel's number of parameter files), with a value equal to the full absolute file name (path and base name) of the corresponding parameter file.To facilitate backward-compatibility, the schema of the specification file is explicitly versioned. Each version of the schema is documented here.
kim-api-sm-schema-version = 1
(Since 2.1):The specification file consists of a single EDN Map. Each key-value pair in the map has a key element-type of string. The following list gives the required key values and the element-type of their corresponding value:
The "model-name" string value must be identical to the SimulatorModel's name. The "supported-species" string value is a space separated list of labels that identify the species supported by the model. The KIM API does not impose any additional constraints on these species labels.
All other key-value pairs in the EDN map are "simulator fields" which must have a value with element-type string or vector. If a vector of length zero or greater is provided, each element of the vector must have element-type string.
Example of kim-api-sm-schema-version = 1
file format
In this example the "units" and "model-defn" key-value pairs are "simulator fields" whose format is defined by the LAMMPS kim_init command. There are also two examples of template tags: "@<atom-type-sym-list>@", which is defined by the LAMMPS simulator, and "@<parameter-file-1>@", which is defined by the SimulatorModel object.
Definition at line 141 of file KIM_SimulatorModel.hpp.
int KIM::SimulatorModel::AddTemplateMap | ( | std::string const & | key, |
std::string const & | value | ||
) |
Add a new key-value entry to the template map.
As part of the SimulatorModel::Create'ion of a SimulatorModel object its template map is opened and initialized by (internally) executing a call to OpenAndInitializeTemplateMap(). The AddTemplateMap() routine allows new key-value entries to be added to the open template map.
Once the CloseTemplateMap() routine is executed, the map entries are used to perform template substitution on the simulator field line strings. In each simulator field line and for each map key-value entry, when key
, surrounded by the template tags "@<" and ">@", is found it will be replaced by value
. For example, if key
is my-key
, and value
is the-result
, then wherever the string @<my-key>@
is found within a simulator field line it will be replaced by the string the-result
.
[in] | key | The key value. Must consist only of digits (0-9), lower case letters (a-z), and dashes (-). |
[in] | value | The value value. All valid strings are allowed. |
true
if the template map has been closed by a call to CloseTempateMap(). true
if key
contains invalid characters. false
otherwise.void KIM::SimulatorModel::CloseTemplateMap | ( | ) |
Close the template map and perform template substitutions.
Close the template map and use the map entries to perform search-and-replace substitutions on all simulator field lines. The template map must be closed to access the simulator field lines via GetSimulatorFieldLine().
|
static |
Create a new KIM API SimulatorModel object.
Allocates a new KIM API SimulatorModel object for use by a Simulator.
[in] | simulatorModelName | The name of the SimulatorModel to be created. |
[out] | simulatorModel | Pointer to the newly created SimulatorModel object. |
simulatorModelName
is required to be a valid C-identifier.true
if the KIM API is unable to allocate a new log object. true
if the requested simulator model's library cannot be found, opened, is of the wrong type, or has some other problem. true
if the simulator model's parameter files cannot be written to scratch space. true
if the simulator model's specification file is invalid EDN, is written in an unsupported schema version, or does not provide all required data. false
otherwise.simulatorModel == NULL
if an error occurs.
|
static |
Destroy a previously SimulatorModel::Create'd object.
Deallocate the SimulatorModel object.
[in,out] | simulatorModel | Pointer to the SimulatorModel object. |
simulatorModel
points to a previously created KIM API SimulatorModel object.simulatorModel == NULL
.void KIM::SimulatorModel::GetNumberOfParameterFiles | ( | int *const | numberOfParameterFiles | ) | const |
Get the number of parameter files provided by the SimulatorModel.
[out] | numberOfParameterFiles | The number of parameter files. |
void KIM::SimulatorModel::GetNumberOfSimulatorFields | ( | int *const | numberOfSimulatorFields | ) | const |
Get the number of simulator fields provided by the SimulatorModel.
[out] | numberOfSimulatorFields | The number of simulator fields provided by the SimulatorModel. |
void KIM::SimulatorModel::GetNumberOfSupportedSpecies | ( | int *const | numberOfSupportedSpecies | ) | const |
Get the number of species supported by the SimulatorModel.
[out] | numberOfSupportedSpecies | The number of species supported by the Simulator Model. |
int KIM::SimulatorModel::GetParameterFileBasename | ( | int const | index, |
std::string const **const | parameterFileBasename | ||
) | const |
Get the basename (file name without path) of a particular parameter file. The file is located in the SimulatorModel's parameter file directory.
[in] | index | Zero-based index for the parameter file of interest. |
[out] | parameterFileBasename | Basename (file name without path) of the parameter file. |
parameterFileBasename
is unchanged if an error occurs.true
if index
is invalid. false
otherwise.void KIM::SimulatorModel::GetParameterFileDirectoryName | ( | std::string const **const | directoryName | ) | const |
Get absolute path name of the temporary directory where parameter files provided by the simulator model are written.
[out] | directoryName | The absolute path name of the SimulatorModel's temporary parameter file directory. |
int KIM::SimulatorModel::GetParameterFileName | ( | int const | index, |
std::string const **const | parameterFileName | ||
) | const |
Get the basename (file name without path) of a particular parameter file. The file is located in the SimulatorModel's parameter file directory.
[in] | index | Zero-based index for the parameter file of interest. |
[out] | parameterFileName | Basename (file name without path) of the parameter file. |
parameterFileName
is unchanged if an error occurs.true
if index
is invalid. false
otherwise.void KIM::SimulatorModel::GetSimulatorBufferPointer | ( | void **const | ptr | ) | const |
Get the Simulator's buffer pointer from the SimulatorModel object.
[out] | ptr | The simulator buffer data pointer. |
ptr == NULL
if the simulator has not previously called SimulatorModel::SetSimulatorBufferPointer.int KIM::SimulatorModel::GetSimulatorFieldLine | ( | int const | fieldIndex, |
int const | lineIndex, | ||
std::string const **const | lineValue | ||
) | const |
Get a line for the simulator field of interest with all template substitutions performed (Requires the template map is closed).
[in] | fieldIndex | Zero-based index of the simulator field of interest. |
[in] | lineIndex | Zero-based index of the line of interest. |
[out] | lineValue | The value of the simulator field line. |
lineValue
is unchanged if an error occurs.true
if the template map is open. true
if fieldIndex
is invalid. true
if lineIndex
is invalid. false
otherwise.int KIM::SimulatorModel::GetSimulatorFieldMetadata | ( | int const | fieldIndex, |
int *const | extent, | ||
std::string const **const | fieldName | ||
) | const |
Get the metadata for the simulator field of interest.
[in] | fieldIndex | Zero-based index of the simulator field of interest. |
[out] | extent | Number of lines in the simulator field of interest. |
[out] | fieldName | Name of the simulator field. |
extent
and fieldName
may be NULL
if the corresponding value is not needed.extent
and fieldName
are unchanged if an error occurs.true
if fieldIndex
is invalid. false
otherwise.void KIM::SimulatorModel::GetSimulatorNameAndVersion | ( | std::string const **const | simulatorName, |
std::string const **const | simulatorVersion | ||
) | const |
Get the SimulatorModel's simulator name and version.
[out] | simulatorName | Simulator name. |
[out] | simulatorVersion | Simulator version. |
simulatorName
and simulatorVersion
may be NULL
if the cooresponding value is not needed.void KIM::SimulatorModel::GetSpecificationFileName | ( | std::string const **const | specificationFileName | ) | const |
Get the SimulatorModel's specification file basename (file name without path). The file is located in the SimulatorModel's parameter file directory.
[out] | specificationFileName | The basename (file name without path) of the specification file. |
int KIM::SimulatorModel::GetSupportedSpecies | ( | int const | index, |
std::string const **const | speciesName | ||
) | const |
Get a species name supported by the SimulatorModel.
[in] | index | Zero-based index for the species name. |
[out] | speciesName | The value of the species name of interest. |
true
if index
is invalid. false
otherwise.void KIM::SimulatorModel::OpenAndInitializeTemplateMap | ( | ) |
Open and initialize the template map for simulator field line substitutions.
This routine clears the template map of all existing entries, adds the KIM API standard template entries, and opens the template map for addition of new entries. This allows the simulator significant flexibilty. For instance, when only a partial set of the simulator's template map key-value entries are known (such as when the simulator's input file has been only partially processed). In this case, the simulator can close the template map to obtain certain field lines that it knows to be complete. Then it can open and initialize the template map and continue processing its input.
void KIM::SimulatorModel::PopLogVerbosity | ( | ) |
Pop a LogVerbosity from the SimulatorModel object's Log object verbosity stack.
void KIM::SimulatorModel::PushLogVerbosity | ( | LogVerbosity const | logVerbosity | ) |
Push a new LogVerbosity onto the SimulatorModel object's Log object verbosity stack.
[in] | logVerbosity | A LogVerbosity value. |
void KIM::SimulatorModel::SetLogID | ( | std::string const & | logID | ) |
Set the identity of the Log object associated with the SimulatorModel object.
[in] | logID | String identifying the SimulatorModel object's Log object. |
void KIM::SimulatorModel::SetSimulatorBufferPointer | ( | void *const | ptr | ) |
Set the Simulator's buffer pointer within the SimulatorModel object.
The simulator buffer pointer may be used by the simulator to associate a memory buffer with the SimulatorModel object.
[in] | ptr | The simulator buffer data pointer. |
int KIM::SimulatorModel::TemplateMapIsOpen | ( | ) | const |
Determine if the template map is open.
true
if the template map is open. false
if the template map is closed.std::string const& KIM::SimulatorModel::ToString | ( | ) | const |
Get a string representing the internal state of the SimulatorModel object.
This string is primarily meant for use as a debugging tool. The string may be quite long. It begins and ends with lines consisting only of ='s
.