kim-api  2.1.4-git+v2.1.3-git-3-g4c859c7f.GNU
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
Public Member Functions | Static Public Member Functions | List of all members
KIM::SimulatorModel Class Reference

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

Detailed Description

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:

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

{
"kim-api-sm-schema-version" 1
"model-name" "Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu"
"simulator-name" "LAMMPS"
"simulator-version" "12 Dec 2018"
"supported-species" "Pb Au"
"units" "metal"
"model-defn" [ "pair_style lj/cut 10.4057000"
"variable alchemy_mapping index @<atom-type-sym-list>@"
"variable alchemy_curr_type loop 10000"
"include @<parameter-file-1>@"
"pair_modify mix arithmetic"
]
}

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.


See also
KIM_SimulatorModel, kim_simulator_model_module::kim_simulator_model_handle_type
Since
2.1

Definition at line 141 of file KIM_SimulatorModel.hpp.

Member Function Documentation

◆ AddTemplateMap()

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.

Parameters
[in]keyThe key value. Must consist only of digits (0-9), lower case letters (a-z), and dashes (-).
[in]valueThe value value. All valid strings are allowed.
Returns
true if the template map has been closed by a call to CloseTempateMap().
true if key contains invalid characters.
false otherwise.
See also
KIM_SimulatorModel_AddTemplateMap, kim_simulator_model_module::kim_add_template_map
Since
2.1

◆ CloseTemplateMap()

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().

See also
KIM_SimulatorModel_CloseTemplateMap, kim_simulator_model_module::kim_close_template_map
Since
2.1

◆ Create()

static int KIM::SimulatorModel::Create ( std::string const &  simulatorModelName,
SimulatorModel **const  simulatorModel 
)
static

Create a new KIM API SimulatorModel object.

Allocates a new KIM API SimulatorModel object for use by a Simulator.

Parameters
[in]simulatorModelNameThe name of the SimulatorModel to be created.
[out]simulatorModelPointer to the newly created SimulatorModel object.
Note
The value of simulatorModelName is required to be a valid C-identifier.
Returns
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.
Postcondition
simulatorModel == NULL if an error occurs.
See also
KIM_SimulatorModel_Create, kim_simulator_model_module::kim_simulator_model_create
Since
2.1

◆ Destroy()

static void KIM::SimulatorModel::Destroy ( SimulatorModel **const  simulatorModel)
static

Destroy a previously SimulatorModel::Create'd object.

Deallocate the SimulatorModel object.

Parameters
[in,out]simulatorModelPointer to the SimulatorModel object.
Precondition
simulatorModel points to a previously created KIM API SimulatorModel object.
Postcondition
simulatorModel == NULL.
See also
KIM_SimulatorModel_Destroy, kim_simulator_model_module::kim_simulator_model_destroy

◆ GetNumberOfParameterFiles()

void KIM::SimulatorModel::GetNumberOfParameterFiles ( int *const  numberOfParameterFiles) const

Get the number of parameter files provided by the SimulatorModel.

Parameters
[out]numberOfParameterFilesThe number of parameter files.
See also
KIM_SimulatorModel_GetNumberOfParameterFiles, kim_simulator_model_module::kim_get_number_of_parameter_files
Since
2.1

◆ GetNumberOfSimulatorFields()

void KIM::SimulatorModel::GetNumberOfSimulatorFields ( int *const  numberOfSimulatorFields) const

Get the number of simulator fields provided by the SimulatorModel.

Parameters
[out]numberOfSimulatorFieldsThe number of simulator fields provided by the SimulatorModel.
See also
KIM_SimulatorModel_GetNumberOfSimulatorFields, kim_simulator_model_module::kim_get_number_of_simulator_fields
Since
2.1

◆ GetNumberOfSupportedSpecies()

void KIM::SimulatorModel::GetNumberOfSupportedSpecies ( int *const  numberOfSupportedSpecies) const

Get the number of species supported by the SimulatorModel.

Parameters
[out]numberOfSupportedSpeciesThe number of species supported by the Simulator Model.
See also
KIM_SimulatorModel_GetNumberOfSupportedSpecies, kim_simulator_model_module::kim_get_number_of_supported_species
Since
2.1

◆ GetParameterFileDirectoryName()

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.

Parameters
[out]directoryNameThe absolute path name of the SimulatorModel's temporary parameter file directory.
See also
KIM_SimulatorModel_GetParameterFileDirectoryName, kim_simulator_model_module::kim_get_parameter_file_directory_name
Since
2.1

◆ GetParameterFileName()

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.

Parameters
[in]indexZero-based index for the parameter file of interest.
[out]parameterFileNameBasename (file name without path) of the parameter file.
Postcondition
parameterFileName is unchanged if an error occurs.
Returns
true if index is invalid.
false otherwise.
See also
KIM_SimulatorModel_GetParameterFileName, kim_simulator_model_module::kim_get_parameter_file_name
Since
2.1

◆ GetSimulatorBufferPointer()

void KIM::SimulatorModel::GetSimulatorBufferPointer ( void **const  ptr) const

Get the Simulator's buffer pointer from the SimulatorModel object.

Parameters
[out]ptrThe simulator buffer data pointer.
Note
ptr == NULL if the simulator has not previously called SimulatorModel::SetSimulatorBufferPointer.
See also
KIM_SimulatorModel_GetSimulatorBufferPointer, kim_simulator_model_module::kim_get_simulator_buffer_pointer
Since
2.1

◆ GetSimulatorFieldLine()

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).

Parameters
[in]fieldIndexZero-based index of the simulator field of interest.
[in]lineIndexZero-based index of the line of interest.
[out]lineValueThe value of the simulator field line.
Postcondition
lineValue is unchanged if an error occurs.
Returns
true if the template map is open.
true if fieldIndex is invalid.
true if lineIndex is invalid.
false otherwise.
See also
KIM_SimulatorModel_GetSimulatorFieldLine, kim_simulator_model_module::kim_get_simulator_field_line
Since
2.1

◆ GetSimulatorFieldMetadata()

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.

Parameters
[in]fieldIndexZero-based index of the simulator field of interest.
[out]extentNumber of lines in the simulator field of interest.
[out]fieldNameName of the simulator field.
Precondition
extent and fieldName may be NULL if the corresponding value is not needed.
Postcondition
extent and fieldName are unchanged if an error occurs.
Returns
true if fieldIndex is invalid.
false otherwise.
See also
KIM_SimulatorModel_GetSimulatorFieldMetadata, kim_simulator_model_module::kim_get_simulator_field_metadata
Since
2.1

◆ GetSimulatorNameAndVersion()

void KIM::SimulatorModel::GetSimulatorNameAndVersion ( std::string const **const  simulatorName,
std::string const **const  simulatorVersion 
) const

Get the SimulatorModel's simulator name and version.

Parameters
[out]simulatorNameSimulator name.
[out]simulatorVersionSimulator version.
Precondition
simulatorName and simulatorVersion may be NULL if the cooresponding value is not needed.
See also
KIM_SimulatorModel_GetSimulatorNameAndVersion, kim_simulator_model_module::kim_get_simulator_name_and_version
Since
2.1

◆ GetSpecificationFileName()

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.

Parameters
[out]specificationFileNameThe basename (file name without path) of the specification file.
See also
KIM_SimulatorModel_GetSpecificationFileName, kim_simulator_model_module::kim_get_specification_file_name
Since
2.1

◆ GetSupportedSpecies()

int KIM::SimulatorModel::GetSupportedSpecies ( int const  index,
std::string const **const  speciesName 
) const

Get a species name supported by the SimulatorModel.

Parameters
[in]indexZero-based index for the species name.
[out]speciesNameThe value of the species name of interest.
Returns
true if index is invalid.
false otherwise.
See also
KIM_SimulatorModel_GetSupportedSpecies, kim_simulator_model_module::kim_get_supported_species
Since
2.1

◆ OpenAndInitializeTemplateMap()

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.

See also
KIM_SimulatorModel_OpenAndInitializeTemplateMap, kim_simulator_model_module::kim_open_and_initialize_template_map
Since
2.1

◆ PopLogVerbosity()

void KIM::SimulatorModel::PopLogVerbosity ( )

Pop a LogVerbosity from the SimulatorModel object's Log object verbosity stack.

See also
KIM_SimulatorModel_PopLogVerbosity, kim_simulator_model_module::kim_pop_log_verbosity
Since
2.1

◆ PushLogVerbosity()

void KIM::SimulatorModel::PushLogVerbosity ( LogVerbosity const  logVerbosity)

Push a new LogVerbosity onto the SimulatorModel object's Log object verbosity stack.

Parameters
[in]logVerbosityA LogVerbosity value.
See also
KIM_SimulatorModel_PushLogVerbosity, kim_simulator_model_module::kim_push_log_verbosity
Since
2.1

◆ SetLogID()

void KIM::SimulatorModel::SetLogID ( std::string const &  logID)

Set the identity of the Log object associated with the SimulatorModel object.

Parameters
[in]logIDString identifying the SimulatorModel object's Log object.
See also
KIM_SimulatorModel_SetLogID, kim_simulator_model_module::kim_set_log_id
Since
2.1

◆ SetSimulatorBufferPointer()

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.

Parameters
[in]ptrThe simulator buffer data pointer.
See also
KIM_SimulatorModel_SetSimulatorBufferPointer, kim_simulator_model_module::kim_set_simulator_buffer_pointer
Since
2.1

◆ TemplateMapIsOpen()

int KIM::SimulatorModel::TemplateMapIsOpen ( ) const

Determine if the template map is open.

Returns
true if the template map is open.
false if the template map is closed.
See also
KIM_SimulatorModel_TemplateMapIsOpen, kim_simulator_model_module::kim_template_map_is_open
Since
2.1

◆ ToString()

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.

See also
KIM_SimulatorModel_ToString, kim_simulator_model_module::kim_to_string
Since
2.1

The documentation for this class was generated from the following file: