This graph shows which files directly or indirectly include this file:

Typedefs
typedef struct KIM_LogVerbosity	KIM_LogVerbosity
	Forward declaration. More...

typedef struct KIM_SimulatorModel	KIM_SimulatorModel
	Provides the primary interface to a KIM API SimulatorModel object and is meant to be used by simulators. More...

Functions
int	KIM_SimulatorModel_Create (char const const simulatorModelName, KIM_SimulatorModel *const simulatorModel)
	Create a new KIM API SimulatorModel object. More...

void	KIM_SimulatorModel_Destroy (KIM_SimulatorModel **const simulatorModel)
	Destroy a previously SimulatorModel::Create'd object. More...

void	KIM_SimulatorModel_GetSimulatorNameAndVersion (KIM_SimulatorModel const const simulatorModel, char const const simulatorName, char const *const simulatorVersion)
	Get the SimulatorModel's simulator name and version. More...

void	KIM_SimulatorModel_GetNumberOfSupportedSpecies (KIM_SimulatorModel const const simulatorModel, int const numberOfSupportedSpecies)
	Get the number of species supported by the SimulatorModel. More...

int	KIM_SimulatorModel_GetSupportedSpecies (KIM_SimulatorModel const const simulatorModel, int const index, char const *const speciesName)
	Get a species name supported by the SimulatorModel. More...

void	KIM_SimulatorModel_OpenAndInitializeTemplateMap (KIM_SimulatorModel const *const simulatorModel)
	Open and initialize the template map for simulator field line substitutions. More...

int	KIM_SimulatorModel_TemplateMapIsOpen (KIM_SimulatorModel const *const simulatorModel)
	Determine if the template map is open. More...

int	KIM_SimulatorModel_AddTemplateMap (KIM_SimulatorModel const const simulatorModel, char const const key, char const *const value)
	Add a new key-value entry to the template map. More...

void	KIM_SimulatorModel_CloseTemplateMap (KIM_SimulatorModel const *const simulatorModel)
	Close the template map and perform template substitutions. More...

void	KIM_SimulatorModel_GetNumberOfSimulatorFields (KIM_SimulatorModel const const simulatorModel, int const numberOfSimulatorFields)
	Get the number of simulator fields provided by the SimulatorModel. More...

int	KIM_SimulatorModel_GetSimulatorFieldMetadata (KIM_SimulatorModel const const simulatorModel, int const fieldIndex, int const extent, char const **const fieldName)
	Get the metadata for the simulator field of interest. More...

int	KIM_SimulatorModel_GetSimulatorFieldLine (KIM_SimulatorModel const const simulatorModel, int const fieldIndex, int const lineIndex, char const *const lineValue)
	Get a line for the simulator field of interest with all template substitutions performed (Requires the template map is closed). More...

void	KIM_SimulatorModel_GetParameterFileDirectoryName (KIM_SimulatorModel const const simulatorModel, char const *const directoryName)
	Get absolute path name of the temporary directory where parameter files provided by the simulator model are written. More...

void	KIM_SimulatorModel_GetSpecificationFileName (KIM_SimulatorModel const const simulatorModel, char const *const specificationFileName)
	Get the SimulatorModel's specification file basename (file name without path). The file is located in the SimulatorModel's parameter file directory. More...

void	KIM_SimulatorModel_GetNumberOfParameterFiles (KIM_SimulatorModel const const simulatorModel, int const numberOfParameterFiles)
	Get the number of parameter files provided by the SimulatorModel. More...

int	KIM_SimulatorModel_GetParameterFileName (KIM_SimulatorModel const const simulatorModel, int const index, char const *const parameterFileName)
	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	KIM_SimulatorModel_GetParameterFileBasename (KIM_SimulatorModel const const simulatorModel, int const index, char const *const parameterFileBasename)
	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	KIM_SimulatorModel_SetSimulatorBufferPointer (KIM_SimulatorModel const simulatorModel, void const ptr)
	Set the Simulator's buffer pointer within the SimulatorModel object. More...

void	KIM_SimulatorModel_GetSimulatorBufferPointer (KIM_SimulatorModel const const simulatorModel, void *const ptr)
	Get the Simulator's buffer pointer from the SimulatorModel object. More...

char const *	KIM_SimulatorModel_ToString (KIM_SimulatorModel const *const simulatorModel)
	Get a string representing the internal state of the SimulatorModel object. More...

void	KIM_SimulatorModel_SetLogID (KIM_SimulatorModel const simulatorModel, char const const logID)
	Set the identity of the Log object associated with the SimulatorModel object. More...

void	KIM_SimulatorModel_PushLogVerbosity (KIM_SimulatorModel *const simulatorModel, KIM_LogVerbosity const logVerbosity)
	Push a new LogVerbosity onto the SimulatorModel object's Log object verbosity stack. More...

void	KIM_SimulatorModel_PopLogVerbosity (KIM_SimulatorModel *const simulatorModel)
	Pop a LogVerbosity from the SimulatorModel object's Log object verbosity stack. More...

Typedef Documentation

◆ KIM_LogVerbosity

typedef struct KIM_LogVerbosity KIM_LogVerbosity

Forward declaration.

Since: 2.0

Definition at line 42 of file KIM_SimulatorModel.h.

◆ KIM_SimulatorModel

typedef struct KIM_SimulatorModel KIM_SimulatorModel

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:

"kim-api-sm-schema-version", integer
"model-name", string
"simulator-name", string
"simulator-version", string
"supported-species", string

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 54 of file KIM_SimulatorModel.h.

Function Documentation

◆ KIM_SimulatorModel_AddTemplateMap()

int KIM_SimulatorModel_AddTemplateMap	(	KIM_SimulatorModel const *const	simulatorModel,
		char const *const	key,
		char const *const	value
	)

Add a new key-value entry to the template map.

See also: KIM::SimulatorModel::AddTemplateMap, kim_simulator_model_module::kim_add_template_map

Since: 2.1

◆ KIM_SimulatorModel_CloseTemplateMap()

void KIM_SimulatorModel_CloseTemplateMap ( KIM_SimulatorModel const *const simulatorModel )

Close the template map and perform template substitutions.

See also: KIM::SimulatorModel::CloseTemplateMap, kim_simulator_model_module::kim_close_template_map

Since: 2.1

◆ KIM_SimulatorModel_Create()

int KIM_SimulatorModel_Create	(	char const *const	simulatorModelName,
		KIM_SimulatorModel **const	simulatorModel
	)

Create a new KIM API SimulatorModel object.

See also: KIM::SimulatorModel::Create, kim_simulator_model_module::kim_simulator_model_create

Since: 2.1

◆ KIM_SimulatorModel_Destroy()

void KIM_SimulatorModel_Destroy ( KIM_SimulatorModel **const simulatorModel )

Destroy a previously SimulatorModel::Create'd object.

See also: KIM::SimulatorModel::Destroy, kim_simulator_model_module::kim_simulator_model_destroy

Since: 2.1

◆ KIM_SimulatorModel_GetNumberOfParameterFiles()

void KIM_SimulatorModel_GetNumberOfParameterFiles	(	KIM_SimulatorModel const *const	simulatorModel,
		int *const	numberOfParameterFiles
	)

Get the number of parameter files provided by the SimulatorModel.

See also: KIM::SimulatorModel::GetNumberOfParameterFiles, kim_simulator_model_module::kim_get_number_of_parameter_files

Since: 2.1

◆ KIM_SimulatorModel_GetNumberOfSimulatorFields()

void KIM_SimulatorModel_GetNumberOfSimulatorFields	(	KIM_SimulatorModel const *const	simulatorModel,
		int *const	numberOfSimulatorFields
	)

Get the 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

◆ KIM_SimulatorModel_GetNumberOfSupportedSpecies()

void KIM_SimulatorModel_GetNumberOfSupportedSpecies	(	KIM_SimulatorModel const *const	simulatorModel,
		int *const	numberOfSupportedSpecies
	)

Get the number of species supported by the SimulatorModel.

See also: KIM::SimulatorModel::GetNumberOfSupportedSpecies, kim_simulator_model_module::kim_get_number_of_supported_species

Since: 2.1

◆ KIM_SimulatorModel_GetParameterFileBasename()

int KIM_SimulatorModel_GetParameterFileBasename	(	KIM_SimulatorModel const *const	simulatorModel,
		int const	index,
		char const **const	parameterFileBasename
	)

Get the basename (file name without path) of a particular parameter file. The file is located in the SimulatorModel's parameter file directory.

See also: KIM::SimulatorModel::GetParameterFileBasename, kim_simulator_model_module::kim_get_parameter_file_basename

Since: 2.2

◆ KIM_SimulatorModel_GetParameterFileDirectoryName()

void KIM_SimulatorModel_GetParameterFileDirectoryName	(	KIM_SimulatorModel const *const	simulatorModel,
		char const **const	directoryName
	)

Get absolute path name of the temporary directory where parameter files provided by the simulator model are written.

See also: KIM::SimulatorModel::GetParameterFileDirectoryName, kim_simulator_model_module::kim_get_parameter_file_directory_name

Since: 2.1

◆ KIM_SimulatorModel_GetParameterFileName()

int KIM_SimulatorModel_GetParameterFileName	(	KIM_SimulatorModel const *const	simulatorModel,
		int const	index,
		char const **const	parameterFileName
	)

Get the basename (file name without path) of a particular parameter file. The file is located in the SimulatorModel's parameter file directory.

See also: KIM::SimulatorModel::GetParameterFileName, kim_simulator_model_module::kim_get_parameter_file_name

Since: 2.1

Deprecated:: As of 2.2. Please use KIM_SimulatorModel_GetParameterFileBasename() instead.

◆ KIM_SimulatorModel_GetSimulatorBufferPointer()

void KIM_SimulatorModel_GetSimulatorBufferPointer	(	KIM_SimulatorModel const *const	simulatorModel,
		void **const	ptr
	)

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

See also: KIM::SimulatorModel::GetSimulatorBufferPointer, kim_simulator_model_module::kim_get_simulator_buffer_pointer

Since: 2.1

◆ KIM_SimulatorModel_GetSimulatorFieldLine()

int KIM_SimulatorModel_GetSimulatorFieldLine	(	KIM_SimulatorModel const *const	simulatorModel,
		int const	fieldIndex,
		int const	lineIndex,
		char const **const	lineValue
	)

Get a line for the simulator field of interest with all template substitutions performed (Requires the template map is closed).

See also: KIM::SimulatorModel::GetSimulatorFieldLine, kim_simulator_model_module::kim_get_simulator_field_line

Since: 2.1

◆ KIM_SimulatorModel_GetSimulatorFieldMetadata()

int KIM_SimulatorModel_GetSimulatorFieldMetadata	(	KIM_SimulatorModel const *const	simulatorModel,
		int const	fieldIndex,
		int *const	extent,
		char const **const	fieldName
	)

Get the metadata for the simulator field of interest.

See also: KIM::SimulatorModel::GetSimulatorFieldMetadata, kim_simulator_model_module::kim_get_simulator_field_metadata

Since: 2.1

◆ KIM_SimulatorModel_GetSimulatorNameAndVersion()

void KIM_SimulatorModel_GetSimulatorNameAndVersion	(	KIM_SimulatorModel const *const	simulatorModel,
		char const **const	simulatorName,
		char const **const	simulatorVersion
	)

Get the SimulatorModel's simulator name and version.

See also: KIM::SimulatorModel::GetSimulatorNameAndVersion, kim_simulator_model_module::kim_get_simulator_name_and_version

Since: 2.1

◆ KIM_SimulatorModel_GetSpecificationFileName()

void KIM_SimulatorModel_GetSpecificationFileName	(	KIM_SimulatorModel const *const	simulatorModel,
		char const **const	specificationFileName
	)

Get the SimulatorModel's specification file basename (file name without path). The file is located in the SimulatorModel's parameter file directory.

See also: KIM::SimulatorModel::GetSpecificationFileName, kim_simulator_model_module::kim_get_specification_file_name

Since: 2.1

◆ KIM_SimulatorModel_GetSupportedSpecies()

int KIM_SimulatorModel_GetSupportedSpecies	(	KIM_SimulatorModel const *const	simulatorModel,
		int const	index,
		char const **const	speciesName
	)

Get a species name supported by the SimulatorModel.

See also: KIM::SimulatorModel::GetSupportedSpecies, kim_simulator_model_module::kim_get_supported_species

Since: 2.1

◆ KIM_SimulatorModel_OpenAndInitializeTemplateMap()

void KIM_SimulatorModel_OpenAndInitializeTemplateMap ( KIM_SimulatorModel const *const simulatorModel )

Open and initialize the template map for simulator field line substitutions.

See also: KIM::SimulatorModel::OpenAndInitializeTemplateMap, kim_simulator_model_module::kim_open_and_initialize_template_map

Since: 2.1

◆ KIM_SimulatorModel_PopLogVerbosity()

void KIM_SimulatorModel_PopLogVerbosity ( KIM_SimulatorModel *const simulatorModel )

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

◆ KIM_SimulatorModel_PushLogVerbosity()

void KIM_SimulatorModel_PushLogVerbosity	(	KIM_SimulatorModel *const	simulatorModel,
		KIM_LogVerbosity const	logVerbosity
	)

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

See also: KIM::SimulatorModel::PushLogVerbosity, kim_simulator_model_module::kim_push_log_verbosity

Since: 2.1

◆ KIM_SimulatorModel_SetLogID()

void KIM_SimulatorModel_SetLogID	(	KIM_SimulatorModel *const	simulatorModel,
		char const *const	logID
	)

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

See also: KIM::SimulatorModel::SetLogID, kim_simulator_model_module::kim_set_log_id

Since: 2.1

◆ KIM_SimulatorModel_SetSimulatorBufferPointer()

void KIM_SimulatorModel_SetSimulatorBufferPointer	(	KIM_SimulatorModel *const	simulatorModel,
		void *const	ptr
	)

Set the Simulator's buffer pointer within the SimulatorModel object.

See also: KIM::SimulatorModel::SetSimulatorBufferPointer, kim_simulator_model_module::kim_set_simulator_buffer_pointer

Since: 2.1

◆ KIM_SimulatorModel_TemplateMapIsOpen()

int KIM_SimulatorModel_TemplateMapIsOpen ( KIM_SimulatorModel const *const simulatorModel )

Determine if the template map is open.

See also: KIM::SimulatorModel::TemplateMapIsOpen, kim_simulator_model_module::kim_template_map_is_open

Since: 2.1

◆ KIM_SimulatorModel_ToString()

char const* KIM_SimulatorModel_ToString ( KIM_SimulatorModel const *const simulatorModel )

Get a string representing the internal state of the SimulatorModel object.

See also: KIM::SimulatorModel::ToString, kim_simulator_model_module::kim_to_string

Since: 2.1

Typedefs

Functions