kim-api  2.1.4-git+v2.1.3-git-1-g7847914a.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::ModelDriverCreate Class Reference

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 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 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 67 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]fromLengthUnitThe "from" base length unit.
[in]fromEnergyUnitThe "from" base energy unit.
[in]fromChargeUnitThe "from" base charge unit.
[in]fromTemperatureUnitThe "from" base temperature unit.
[in]fromTimeUnitThe "from" base time unit.
[in]toLengthUnitThe "to" base length unit.
[in]toEnergyUnitThe "to" base energy unit.
[in]toChargeUnitThe "to" base charge unit.
[in]toTemperatureUnitThe "to" base temperature unit.
[in]toTimeUnitThe "to" base time unit.
[in]lengthExponentThe derived unit's length exponent.
[in]energyExponentThe derived unit's energy exponent.
[in]chargeExponentThe derived unit's charge exponent.
[in]temperatureExponentThe derived unit's temperature exponent.
[in]timeExponentThe derived unit's time exponent.
[out]conversionFactorThe 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]numberOfParameterFilesThe number of parameter files.
See also
KIM_ModelDriverCreate_GetNumberOfParameterFiles, kim_model_driver_create_module::kim_get_number_of_parameter_files
Since
2.0

◆ GetParameterFileName()

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

Get a particular parameter file name.

Parameters
[in]indexZero-based index for the parameter file of interest.
[out]parameterFileNameThe 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

◆ 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]logVerbosityThe LogVerbosity level for the entry.
[in]messageThe body text of the log entry.
[in]lineNumberThe source code file line number.
[in]fileNameThe 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]influenceDistancePointer 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]ptrThe 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]numberingThe 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]numberOfNeighborListsThe number of neighbor lists required by the Model.
[in]cutoffsArray of cutoff values for each of the required neighbor lists.
[in]modelWillNotRequestNeighborsOfNoncontributingParticlesArray 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]extentThe number of entries in the parameter array.
[in]ptrThe parameter array data pointer.
[in]nameA brief unique name for the parameter array. This name must be a valid C identifier.
[in]descriptionA 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]modelRoutineNameThe ModelRoutineName of interest.
[in]languageNameThe LanguageName of the ModelRoutineName.
[in]requiredInteger, true if the model requires the simulator to call the associated ModelRoutineName in order to be used correctly, false otherwise.
[in]fptrFunction 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]speciesNameThe SpeciesName of interest.
[in]codeThe 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]lengthUnitThe Model's base LengthUnit.
[in]energyUnitThe Model's base EnergyUnit.
[in]chargeUnitThe Model's base ChargeUnit.
[in]temperatureUnitThe Model's base TemperatureUnit.
[in]timeUnitThe 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: