Provides the interface to a KIM API Model object for use by models within their MODEL_ROUTINE_NAME::Create routine. More...

#include <KIM_ModelDriverCreate.hpp>

Public Member Functions
void	GetParameterFileDirectoryName (std::string const **const directoryName) const
	Get absolute path name of the temporary directory where parameter files provided by the model are written. More...

void	GetNumberOfParameterFiles (int *const numberOfParameterFiles) const
	Get the number of parameter files provided by the parameterized model. More...

int	GetParameterFileName (int const index, std::string const **const parameterFileName) const
	Get a particular parameter file name. More...

int	GetParameterFileBasename (int const index, std::string const **const parameterFileBasename) const
	Get a particular parameter file basename. The file is located in the Model's parameter file directory. More...

int	SetModelNumbering (Numbering const numbering)
	Set the Model's particle Numbering. More...

void	SetInfluenceDistancePointer (double const *const influenceDistance)
	Set the Model's influence distance data pointer. More...

void	SetNeighborListPointers (int const numberOfNeighborLists, double const const cutoffs, int const const modelWillNotRequestNeighborsOfNoncontributingParticles)
	Set the Model's neighbor list data pointers. More...

int	SetRoutinePointer (ModelRoutineName const modelRoutineName, LanguageName const languageName, int const required, Function *const fptr)
	Set the function pointer for the ModelRoutineName of interest. More...

int	SetSpeciesCode (SpeciesName const speciesName, int const code)
	Set integer code for supported SpeciesName. More...

int	SetParameterPointer (int const extent, int *const ptr, std::string const &name, std::string const &description)
	Set the next parameter data pointer to be provided by the model. More...

int	SetParameterPointer (int const extent, double *const ptr, std::string const &name, std::string const &description)

void	SetModelBufferPointer (void *const ptr)
	Set the Model's buffer pointer within the Model object. More...

int	SetUnits (LengthUnit const lengthUnit, EnergyUnit const energyUnit, ChargeUnit const chargeUnit, TemperatureUnit const temperatureUnit, TimeUnit const timeUnit)
	Set the Model's base unit values. More...

void	LogEntry (LogVerbosity const logVerbosity, std::string const &message, int const lineNumber, std::string const &fileName) const
	Write a log entry into the log file. More...

void	LogEntry (LogVerbosity const logVerbosity, std::stringstream const &message, int const lineNumber, std::string const &fileName) const

std::string const &	ToString () const
	Get a string representing the internal state of the Model object. More...

Static Public Member Functions
static int	ConvertUnit (LengthUnit const fromLengthUnit, EnergyUnit const fromEnergyUnit, ChargeUnit const fromChargeUnit, TemperatureUnit const fromTemperatureUnit, TimeUnit const fromTimeUnit, LengthUnit const toLengthUnit, EnergyUnit const toEnergyUnit, ChargeUnit const toChargeUnit, TemperatureUnit const toTemperatureUnit, TimeUnit const toTimeUnit, double const lengthExponent, double const energyExponent, double const chargeExponent, double const temperatureExponent, double const timeExponent, double *const conversionFactor)
	Get the multiplicative factor to convert between a derived unit represented in two different sets of base units. More...

Detailed Description

Provides the interface to a KIM API Model object for use by models within their MODEL_ROUTINE_NAME::Create routine.

See also: ModelCreate, KIM_ModelDriverCreate, KIM_ModelCreate, kim_model_driver_create_module::kim_model_driver_create_handle_type

Since: 2.0

Definition at line 64 of file KIM_ModelDriverCreate.hpp.

Member Function Documentation

◆ ConvertUnit()

static int KIM::ModelDriverCreate::ConvertUnit	(	LengthUnit const	fromLengthUnit,
		EnergyUnit const	fromEnergyUnit,
		ChargeUnit const	fromChargeUnit,
		TemperatureUnit const	fromTemperatureUnit,
		TimeUnit const	fromTimeUnit,
		LengthUnit const	toLengthUnit,
		EnergyUnit const	toEnergyUnit,
		ChargeUnit const	toChargeUnit,
		TemperatureUnit const	toTemperatureUnit,
		TimeUnit const	toTimeUnit,
		double const	lengthExponent,
		double const	energyExponent,
		double const	chargeExponent,
		double const	temperatureExponent,
		double const	timeExponent,
		double *const	conversionFactor
	)

static

Get the multiplicative factor to convert between a derived unit represented in two different sets of base units.

Parameters

[in]	fromLengthUnit	The "from" base length unit.
[in]	fromEnergyUnit	The "from" base energy unit.
[in]	fromChargeUnit	The "from" base charge unit.
[in]	fromTemperatureUnit	The "from" base temperature unit.
[in]	fromTimeUnit	The "from" base time unit.
[in]	toLengthUnit	The "to" base length unit.
[in]	toEnergyUnit	The "to" base energy unit.
[in]	toChargeUnit	The "to" base charge unit.
[in]	toTemperatureUnit	The "to" base temperature unit.
[in]	toTimeUnit	The "to" base time unit.
[in]	lengthExponent	The derived unit's length exponent.
[in]	energyExponent	The derived unit's energy exponent.
[in]	chargeExponent	The derived unit's charge exponent.
[in]	temperatureExponent	The derived unit's temperature exponent.
[in]	timeExponent	The derived unit's time exponent.
[out]	conversionFactor	The desired conversion factor.

Returns: true if any of the base units are unknown.; true if any of the base units are unused and the corresponding exponent is nonzero.; false otherwise.

See also: ModelCreate::ConvertUnit, KIM_ModelDriverCreate_ConvertUnit, KIM_ModelCreate_ConvertUnit, kim_model_driver_create_module::kim_convert_unit

Since: 2.0

◆ GetNumberOfParameterFiles()

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

Get the number of parameter files provided by the parameterized model.

Parameters

[out] numberOfParameterFiles The number of parameter files.

See also: KIM_ModelDriverCreate_GetNumberOfParameterFiles, kim_model_driver_create_module::kim_get_number_of_parameter_files

Since: 2.0

◆ GetParameterFileBasename()

int KIM::ModelDriverCreate::GetParameterFileBasename	(	int const	index,
		std::string const **const	parameterFileBasename
	)		const

Get a particular parameter file basename. The file is located in the Model's parameter file directory.

Parameters

[in]	index	Zero-based index for the parameter file of interest.
[out]	parameterFileBasename	The basename (file name without path) for the parameter file of interest.

Returns: true if the Model object is not a parameterized model; true if index is invalid.; true if parameterFileBasename == NULL.; false otherwise.

See also: KIM_ModelDriverCreate_GetParameterFileBasename, kim_model_driver_create_module::kim_get_parameter_file_basename

Since: 2.2

◆ GetParameterFileDirectoryName()

void KIM::ModelDriverCreate::GetParameterFileDirectoryName ( std::string const **const directoryName ) const

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

Parameters

[out] directoryName The absolute path name of the Model's temporary parameter file directory.

See also: KIM_ModelDriverCreate_GetParameterFileDirectoryName, kim_model_driver_create_module::kim_get_parameter_file_directory_name

Since: 2.2

◆ GetParameterFileName()

int KIM::ModelDriverCreate::GetParameterFileName	(	int const	index,
		std::string const **const	parameterFileName
	)		const

Get a particular parameter file name.

Parameters

[in]	index	Zero-based index for the parameter file of interest.
[out]	parameterFileName	The fully-qualified path name for the parameter file of interest.

Returns: true if the Model object is not a parameterized model; true if index is invalid.; true if parameterFileName == NULL.; false otherwise.

See also: KIM_ModelDriverCreate_GetParameterFileName, kim_model_driver_create_module::kim_get_parameter_file_name

Since: 2.0

Deprecated:: As of 2.2. Please use GetParameterFileDirectoryName() and GetParameterFileBasename() instead.

◆ LogEntry() [1/2]

void KIM::ModelDriverCreate::LogEntry	(	LogVerbosity const	logVerbosity,
		std::string const &	message,
		int const	lineNumber,
		std::string const &	fileName
	)		const

Write a log entry into the log file.

This results in a no-op if logVerbosity is LOG_VERBOSITY::silent or if logVerbosity is greater-than the Log object's top LogVerbosity on its stack.

Parameters

[in]	logVerbosity	The LogVerbosity level for the entry.
[in]	message	The body text of the log entry.
[in]	lineNumber	The source code file line number.
[in]	fileName	The source code file name.

See also: KIM_ModelDriverCreate_LogEntry, kim_model_driver_create_module::kim_log_entry

Since: 2.0

◆ LogEntry() [2/2]

void KIM::ModelDriverCreate::LogEntry	(	LogVerbosity const	logVerbosity,
		std::stringstream const &	message,
		int const	lineNumber,
		std::string const &	fileName
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ SetInfluenceDistancePointer()

void KIM::ModelDriverCreate::SetInfluenceDistancePointer ( double const *const influenceDistance )

Set the Model's influence distance data pointer.

Todo:: Add more detailed description of influenceDistance (or link to docs elsewhere?)

Parameters

[in] influenceDistance Pointer to Model's influence distance.

Note: The model is responsible for allocating the memory associated with the influence distance data. The model must use the Model's buffer pointer to retain access to this memory location and avoid a memory leak.

See also: ModelCreate::SetInfluenceDistancePointer, KIM_ModelDriverCreate_SetInfluenceDistancePointer, KIM_ModelCreate_SetInfluenceDistancePointer, kim_model_driver_create_module::kim_set_influence_distance_pointer

Since: 2.0

◆ SetModelBufferPointer()

void KIM::ModelDriverCreate::SetModelBufferPointer ( void *const ptr )

Set the Model's buffer pointer within the Model object.

The model buffer pointer may be used by the Model to associate a memory buffer with the Model object.

Parameters

[in] ptr The model buffer data pointer.

See also: ModelCreate::SetModelBufferPointer, KIM_ModelDriverCreate_SetModelBufferPointer, KIM_ModelCreate_SetModelBufferPointer, kim_model_driver_create_module::kim_set_model_buffer_pointer

Since: 2.0

◆ SetModelNumbering()

int KIM::ModelDriverCreate::SetModelNumbering ( Numbering const numbering )

Set the Model's particle Numbering.

Parameters

[in] numbering The Model's particle Numbering.

Returns: true if numbering is unknown.; false otherwise.

See also: ModelCreate::SetModelNumbering, KIM_ModelDriverCreate_SetModelNumbering, KIM_ModelCreate_SetModelNumbering, kim_model_driver_create_module::kim_set_model_numbering

Since: 2.0

◆ SetNeighborListPointers()

void KIM::ModelDriverCreate::SetNeighborListPointers	(	int const	numberOfNeighborLists,
		double const *const	cutoffs,
		int const *const	modelWillNotRequestNeighborsOfNoncontributingParticles
	)

Set the Model's neighbor list data pointers.

Todo:: Add more detailed description

Parameters

[in]	numberOfNeighborLists	The number of neighbor lists required by the Model.
[in]	cutoffs	Array of cutoff values for each of the required neighbor lists.
[in]	modelWillNotRequestNeighborsOfNoncontributingParticles	Array of integers; `true` or `false` for each neighbor list required by the Model.

Note: The model is responsible for allocating the memory associated with the neighbor list cutoffs and modelWillNotRequestNeighborsOfNoncontributingParticles data. The model must use the Model's buffer pointer to retain access to this memory location and avoid a memory leak.

See also: ModelCreate::SetNeighborListPointers, KIM_ModelDriverCreate_SetNeighborListPointers, KIM_ModelCreate_SetNeighborListPointers, kim_model_driver_create_module::kim_set_neighbor_list_pointers

Since: 2.0

◆ SetParameterPointer() [1/2]

int KIM::ModelDriverCreate::SetParameterPointer	(	int const	extent,
		int *const	ptr,
		std::string const &	name,
		std::string const &	description
	)

Set the next parameter data pointer to be provided by the model.

This routine is called once for each parameter array to be provided by the model. The order of these calls is important and determines the index assigned to each parameter array for use in the Model::GetParameter and related routines.

Parameters

[in]	extent	The number of entries in the parameter array.
[in]	ptr	The parameter array data pointer.
[in]	name	A brief unique name for the parameter array. This name must be a valid C identifier.
[in]	description	A free-form text description of the parameter array. This should include details about the data layout (e.g., the array corresponds to a square upper-triangular matrix in row-major storage).

Note: The model is responsible for allocating the memory associated with the parameter array data. The model must use the Model's buffer pointer to retain access to this memory location and avoid a memory leak.

See also: ModelCreate::SetParameterPointer, KIM_ModelDriverCreate_SetParameterPointerInteger, KIM_ModelDriverCreate_SetParameterPointerDouble, KIM_ModelCreate_SetParameterPointerInteger, KIM_ModelCreate_SetParameterPointerDouble, kim_model_driver_create_module::kim_set_parameter_pointer

Since: 2.0

◆ SetParameterPointer() [2/2]

int KIM::ModelDriverCreate::SetParameterPointer	(	int const	extent,
		double *const	ptr,
		std::string const &	name,
		std::string const &	description
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ SetRoutinePointer()

int KIM::ModelDriverCreate::SetRoutinePointer	(	ModelRoutineName const	modelRoutineName,
		LanguageName const	languageName,
		int const	required,
		Function *const	fptr
	)

Set the function pointer for the ModelRoutineName of interest.

Parameters

[in]	modelRoutineName	The ModelRoutineName of interest.
[in]	languageName	The LanguageName of the ModelRoutineName.
[in]	required	Integer, `true` if the model requires the simulator to call the associated ModelRoutineName in order to be used correctly, `false` otherwise.
[in]	fptr	Function pointer for the Model's ModelRoutineName routine.

Returns: true if modelRoutineName or langaugeName are unknown.; true if required == false and modelRoutineName has SupportStatus SUPPORT_STATUS::requiredByAPI.; false otherwise.

See also: ModelCreate::SetRoutinePointer, KIM_ModelCreate_SetRoutinePointer, KIM_ModelDriverCreate_SetRoutinePointer, kim_model_driver_create_module::kim_set_routine_pointer

Since: 2.0

◆ SetSpeciesCode()

int KIM::ModelDriverCreate::SetSpeciesCode	(	SpeciesName const	speciesName,
		int const	code
	)

Set integer code for supported SpeciesName.

A call to this routine adds/updates the list of SpeciesName's supported by the Model and associates the specified SpeciesName with the integer code to be used within the COMPUTE_ARGUMENT_NAME::particleSpeciesCodes argument.

Parameters

[in]	speciesName	The SpeciesName of interest.
[in]	code	The associated code.

Returns: true if speciesName is unknown.; false otherwise.

See also: ModelCreate::SetSpeciesCode, KIM_ModelDriverCreate_SetSpeciesCode, KIM_ModelCreate_SetSpeciesCode, kim_model_driver_create_module::kim_set_species_code

Since: 2.0

◆ SetUnits()

int KIM::ModelDriverCreate::SetUnits	(	LengthUnit const	lengthUnit,
		EnergyUnit const	energyUnit,
		ChargeUnit const	chargeUnit,
		TemperatureUnit const	temperatureUnit,
		TimeUnit const	timeUnit
	)

Set the Model's base unit values.

Parameters

[in]	lengthUnit	The Model's base LengthUnit.
[in]	energyUnit	The Model's base EnergyUnit.
[in]	chargeUnit	The Model's base ChargeUnit.
[in]	temperatureUnit	The Model's base TemperatureUnit.
[in]	timeUnit	The Model's base TimeUnit.

Note: A unit of unused indicates the the Model does not deal with any quantities whose derived unit involves the corresponding base unit. For example, many models only deal with quantities that are derived from just the energy and length base units (such as force, virial, etc.), and thus should set chargeUnit, temperatureUnit, and timeUnit to unused.

Returns: true if any of the base units are unknown.; true if lengthUnit or energyUnit are unused.; false otherwise.

See also: ModelCreate::SetUnits, KIM_ModelDriverCreate_SetUnits, KIM_ModelCreate_SetUnits, kim_model_driver_create_module::kim_set_units

Since: 2.0

◆ ToString()

std::string const& KIM::ModelDriverCreate::ToString ( ) const

Get a string representing the internal state of the Model 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_ModelCreate_ToString, kim_model_driver_create_module::kim_to_string

Since: 2.0

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

latest/cpp/include/KIM_ModelDriverCreate.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ConvertUnit()

◆ GetNumberOfParameterFiles()

◆ GetParameterFileBasename()

◆ GetParameterFileDirectoryName()

◆ GetParameterFileName()

◆ LogEntry() [1/2]

◆ LogEntry() [2/2]

◆ SetInfluenceDistancePointer()

◆ SetModelBufferPointer()

◆ SetModelNumbering()

◆ SetNeighborListPointers()

◆ SetParameterPointer() [1/2]

◆ SetParameterPointer() [2/2]

◆ SetRoutinePointer()

◆ SetSpeciesCode()

◆ SetUnits()

◆ ToString()