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::Model Class Reference

Provides the primary interface to a KIM API Model object and is meant to be used by simulators. More...

#include <KIM_Model.hpp>

Public Member Functions

int IsRoutinePresent (ModelRoutineName const modelRoutineName, int *const present, int *const required) const
 Determine presence and required status of the given ModelRoutineName. More...
 
void GetInfluenceDistance (double *const influenceDistance) const
 Get the Model's influence distance. More...
 
void GetNeighborListPointers (int *const numberOfNeighborLists, double const **const cutoffs, int const **const modelWillNotRequestNeighborsOfNoncontributingParticles) const
 Get the Model's neighbor list information. More...
 
void GetUnits (LengthUnit *const lengthUnit, EnergyUnit *const energyUnit, ChargeUnit *const chargeUnit, TemperatureUnit *const temperatureUnit, TimeUnit *const timeUnit) const
 Get the Model's base unit values. More...
 
int ComputeArgumentsCreate (ComputeArguments **const computeArguments) const
 Create a new ComputeArguments object for the Model object. More...
 
int ComputeArgumentsDestroy (ComputeArguments **const computeArguments) const
 Destroy a previously Model::ComputeArgumentsCreate'd object. More...
 
int Compute (ComputeArguments const *const computeArguments) const
 Call the Model's MODEL_ROUTINE_NAME::Compute routine. More...
 
int Extension (std::string const &extensionID, void *const extensionStructure)
 Call the Model's MODEL_ROUTINE_NAME::Extension routine. More...
 
int ClearThenRefresh ()
 Clear influence distance and neighbor list pointers and refresh Model object after parameter changes. More...
 
int WriteParameterizedModel (std::string const &path, std::string const &modelName) const
 Call the Model's MODEL_ROUTINE_NAME::WriteParameterizedModel routine. More...
 
int GetSpeciesSupportAndCode (SpeciesName const speciesName, int *const speciesIsSupported, int *const code) const
 Get the Model's support and code for the requested SpeciesName. More...
 
void GetNumberOfParameters (int *const numberOfParameters) const
 Get the number of parameter arrays provided by the Model. More...
 
int GetParameterMetadata (int const parameterIndex, DataType *const dataType, int *const extent, std::string const **const name, std::string const **const description) const
 Get the metadata associated with one of the Model's parameter arrays. More...
 
int GetParameter (int const parameterIndex, int const arrayIndex, int *const parameterValue) const
 Get a parameter value from the Model. More...
 
int GetParameter (int const parameterIndex, int const arrayIndex, double *const parameterValue) const
 
int SetParameter (int const parameterIndex, int const arrayIndex, int const parameterValue)
 Set a parameter value for the Model. More...
 
int SetParameter (int const parameterIndex, int const arrayIndex, double const parameterValue)
 
void SetSimulatorBufferPointer (void *const ptr)
 Set the Simulator's buffer pointer within the Model object. More...
 
void GetSimulatorBufferPointer (void **const ptr) const
 Get the Simulator's buffer pointer from the Model object. More...
 
std::string const & ToString () const
 Get a string representing the internal state of the Model object. More...
 
void SetLogID (std::string const &logID)
 Set the identity of the Log object associated with the Model object. More...
 
void PushLogVerbosity (LogVerbosity const logVerbosity)
 Push a new LogVerbosity onto the Model object's Log object verbosity stack. More...
 
void PopLogVerbosity ()
 Pop a LogVerbosity from the Model object's Log object verbosity stack. More...
 

Static Public Member Functions

static int Create (Numbering const numbering, LengthUnit const requestedLengthUnit, EnergyUnit const requestedEnergyUnit, ChargeUnit const requestedChargeUnit, TemperatureUnit const requestedTemperatureUnit, TimeUnit const requestedTimeUnit, std::string const &modelName, int *const requestedUnitsAccepted, Model **const model)
 Create a new KIM API Model object. More...
 
static void Destroy (Model **const model)
 Destroy a previously Model::Create'd object. More...
 

Detailed Description

Provides the primary interface to a KIM API Model object and is meant to be used by simulators.

See also
KIM_Model, kim_model_module::kim_model_handle_type
Since
2.0

Definition at line 61 of file KIM_Model.hpp.

Member Function Documentation

◆ ClearThenRefresh()

int KIM::Model::ClearThenRefresh ( )

Clear influence distance and neighbor list pointers and refresh Model object after parameter changes.

Nullify the Model's influence distance, neighbor list cutoff, and modelWillNotRequestNeighborsOfNoncontributingParticles pointers. Then call the Model's MODEL_ROUTINE_NAME::Refresh routine.

Returns
true if the Model does not register any parameters.
true if the Model's MODEL_ROUTINE_NAME::Refresh routine returns true.
true if the Model's MODEL_ROUTINE_NAME::Refresh routine does not set the influence distance, the number of neighbor lists, the neighbor list cutoffs, or the modelWillNotRequestNeighborsOfNoncontributingParticles pointer.
false otherwise.
See also
KIM_Model_ClearThenRefresh, kim_model_module::kim_clear_then_refresh
Since
2.0

◆ Compute()

int KIM::Model::Compute ( ComputeArguments const *const  computeArguments) const

Call the Model's MODEL_ROUTINE_NAME::Compute routine.

Parameters
[in]computeArgumentsA ComputeArguments object.
Returns
true if computeArguments was created by a different Model (as identified by its name string).
true if ComputeArguments::AreAllRequiredArgumentsAndCallbacksPresent returns false for computeArguments.
true if the Model's MODEL_ROUTINE_NAME::Compute routine returns true.
false otherwise.
See also
KIM_Model_Compute, kim_model_module::kim_compute
Since
2.0

◆ ComputeArgumentsCreate()

int KIM::Model::ComputeArgumentsCreate ( ComputeArguments **const  computeArguments) const

Create a new ComputeArguments object for the Model object.

Allocates a new ComputeArguments object for use by a Simulator and calls the Model's MODEL_ROUTINE_NAME::ComputeArgumentsCreate routine.

Parameters
[in,out]computeArgumentsPointer to the newly created ComputeArguments object.
Returns
true if the KIM API is unable to allocate a new ComputeArguments object.
true if the Model's MODEL_ROUTINE_NAME::ComputeArgumentsCreate routine returns true.
false otherwise.
Postcondition
computeArguments == NULL if an error occurs.
See also
KIM_Model_ComputeArgumentsCreate, kim_model_module::kim_compute_arguments_create
Since
2.0

◆ ComputeArgumentsDestroy()

int KIM::Model::ComputeArgumentsDestroy ( ComputeArguments **const  computeArguments) const

Destroy a previously Model::ComputeArgumentsCreate'd object.

Call the Model's MODEL_ROUTINE_NAME::ComputeArgumentsDestroy routine and deallocate the ComputeArguments object.

Parameters
[in,out]computeArgumentsPointer to the ComputeArguments object.
Returns
true if the ComputeArguments object was created by a different Model (as identified by its name string).
true if the Model's MODEL_ROUTINE_NAME::ComputeArgumentsDestroy routine returns true.
false otherwise.
Postcondition
computeArguments is unchanged if an error occurs, otherwise computeArguments == NULL.
See also
KIM_Model_ComputeArgumentsDestroy, kim_model_module::kim_compute_arguments_destroy
Since
2.0

◆ Create()

static int KIM::Model::Create ( Numbering const  numbering,
LengthUnit const  requestedLengthUnit,
EnergyUnit const  requestedEnergyUnit,
ChargeUnit const  requestedChargeUnit,
TemperatureUnit const  requestedTemperatureUnit,
TimeUnit const  requestedTimeUnit,
std::string const &  modelName,
int *const  requestedUnitsAccepted,
Model **const  model 
)
static

Create a new KIM API Model object.

Allocates a new KIM API Model object for use by a Simulator and calls the Model's MODEL_ROUTINE_NAME::Create routine.

Parameters
[in]numberingThe Numbering value used by the Simulator.
[in]requestedLengthUnitThe base LengthUnit requested by the Simulator.
[in]requestedEnergyUnitThe base EnergyUnit requested by the Simulator.
[in]requestedChargeUnitThe base ChargeUnit requested by the Simulator.
[in]requestedTemperatureUnitThe base TemperatureUnit requested by the Simulator.
[in]requestedTimeUnitThe base TimeUnit requested by the Simulator.
[in]modelNameThe name of the Model to be created.
[out]requestedUnitsAcceptedAn integer that is set to true if the Model accepts the Simulator's requested base units, false if the Model will use base units other than those requested by the Simulator.
[out]modelPointer to the newly created Model object.
Note
The value of modelName is required to be a valid C-identifier.
A requested unit of unused indicates that the Simulator will not employ any derived units connected to the associated base unit. This avoids the need for the Simulator to make an arbitrary choice that could cause the Model to not accept its requested base units.
Returns
true if the KIM API is unable to allocate a new log object.
true if numbering or any of the base units are unknown.
true if the requested model's library cannot be found, opened, is of the wrong type, or has some other problem.
true if the Model's MODEL_ROUTINE_NAME::Create routine returns true.
true if the Model's MODEL_ROUTINE_NAME::Create routine does not set the Model's (1) numbering, (2) base units, (3) influence distance, (4) numberOfNeighborLists, (5) cutoff values, (6) modelWillNotRequesNeighborsOfNoncontributingParticles, (7) required ModelRoutineName pointers, or (8) supported species codes.
true if max(cutoffs) > influenceDistance.
true if parameters are registered but not a MODEL_ROUTINE_NAME::Refresh pointer, or vise-versa.
true if a MODEL_ROUTINE_NAME::WriteParameterizedModel pointer is provided but no parameters are registered.
true if the Model's MODEL_ROUTINE_NAME::Create routine does not set the Model's Numbering.
false otherwise.
Postcondition
requestedUnitsAccepted is unchanged and model == NULL if an error occurs.
See also
KIM_Model_Create, kim_model_module::kim_model_create
Since
2.0

◆ Destroy()

static void KIM::Model::Destroy ( Model **const  model)
static

Destroy a previously Model::Create'd object.

Call the Model's MODEL_ROUTINE_NAME::Destroy routine and deallocate the Model object.

Parameters
[in,out]modelPointer to the Model object.
Precondition
model points to a previously created KIM API Model object.
Postcondition
model == NULL.
See also
KIM_Model_Destroy, kim_model_module::kim_model_destroy

◆ Extension()

int KIM::Model::Extension ( std::string const &  extensionID,
void *const  extensionStructure 
)

Call the Model's MODEL_ROUTINE_NAME::Extension routine.

Parameters
[in]extensionIDA string uniquely identifying the extension to be executed.
[in,out]extensionStructurePointer to a data structure of the type defined by the extension to be executed.
Returns
true if the Model does not provide a MODEL_ROUTINE_NAME::Extension routine.
true if the Model's MODEL_ROUTINE_NAME::Extension routine returns true.
false otherwise.
See also
KIM_Model_Extension, kim_model_module::kim_extension
Since
2.0

◆ GetInfluenceDistance()

void KIM::Model::GetInfluenceDistance ( double *const  influenceDistance) const

Get the Model's influence distance.

Parameters
[out]influenceDistance
Todo:
Add more detailed description of influenceDistance. (or link to docs elsewhere?)
See also
KIM_Model_GetInfluenceDistance, kim_model_module::kim_get_influence_distance
Since
2.0

◆ GetNeighborListPointers()

void KIM::Model::GetNeighborListPointers ( int *const  numberOfNeighborLists,
double const **const  cutoffs,
int const **const  modelWillNotRequestNeighborsOfNoncontributingParticles 
) const

Get the Model's neighbor list information.

Each neighbor list has a cutoff value and a flag indicating if the Model will request the neighbors of non-contributing particles.

Note
Output pointers obtained from this routine are valid until the next call to Model::ClearThenRefresh of the KIM::Model object is Model::Destroy'd.
Parameters
[out]numberOfNeighborListsThe number of neighbor lists required by the Model.
[out]cutoffsThe cutoff distance for each neighbor list.
[out]modelWillNotRequestNeighborsOfNoncontributingParticlestrue if such neighbor lists will not be requested, false otherwise.
Precondition
numberOfNeighborLists, cutoffs, or modelWillNotRequestNeighborsOfNoncontributingParticles may be NULL if the corresponding value is not needed.
See also
KIM_Model_GetNeighborListPointers, kim_model_module::kim_get_number_of_neighbor_lists, kim_model_module::kim_get_neighbor_list_values
Since
2.0

◆ GetNumberOfParameters()

void KIM::Model::GetNumberOfParameters ( int *const  numberOfParameters) const

Get the number of parameter arrays provided by the Model.

Parameters
[out]numberOfParametersThe number of parameter arrays provided by the Model.
See also
KIM_Model_GetNumberOfParameters, kim_model_module::kim_get_number_of_parameters
Since
2.0

◆ GetParameter() [1/2]

int KIM::Model::GetParameter ( int const  parameterIndex,
int const  arrayIndex,
int *const  parameterValue 
) const

Get a parameter value from the Model.

Parameters
[in]parameterIndexZero-based index for the parameter array of interest.
[in]arrayIndexZero-based index within the array for the parameter of interest.
[out]parameterValueThe value of the parameter of interest.
Returns
true if parameterIndex is invalid.
true if the specified parameter and parameterValue are of different data types.
true if arrayIndex is invalid.
false otherwise.
See also
KIM_Model_GetParameterInteger, KIM_Model_GetParameterDouble, kim_model_module::kim_get_parameter
Since
2.0

◆ GetParameter() [2/2]

int KIM::Model::GetParameter ( int const  parameterIndex,
int const  arrayIndex,
double *const  parameterValue 
) const

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

◆ GetParameterMetadata()

int KIM::Model::GetParameterMetadata ( int const  parameterIndex,
DataType *const  dataType,
int *const  extent,
std::string const **const  name,
std::string const **const  description 
) const

Get the metadata associated with one of the Model's parameter arrays.

Note
String pointers obtained from this routine are valid until the KIM::Model object is Model::Destroy'd.
Parameters
[in]parameterIndexZero-based index for the parameter array.
[out]dataTypeThe DataType value for the parameter array.
[out]extentThe number of parameters in the array.
[out]nameA string identifying the parameter array (will be a valid C identifier).
[out]descriptionA free-form string description of the parameter array's content.
Returns
true if parameterIndex is invalid
false otherwise.
Precondition
dataType, extent, name, or description may be NULL if the corresponding value is not needed.
See also
KIM_Model_GetParameterMetadata, kim_model_module::kim_get_parameter_metadata
Since
2.0

◆ GetSimulatorBufferPointer()

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

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

Parameters
[out]ptrThe simulator buffer data pointer.
Note
ptr == NULL if the simulator has not previously called Model::SetSimulatorBufferPointer.
See also
KIM_Model_GetSimulatorBufferPointer, kim_model_module::kim_get_simulator_buffer_pointer
Since
2.0

◆ GetSpeciesSupportAndCode()

int KIM::Model::GetSpeciesSupportAndCode ( SpeciesName const  speciesName,
int *const  speciesIsSupported,
int *const  code 
) const

Get the Model's support and code for the requested SpeciesName.

Parameters
[in]speciesNameThe SpeciesName of interest.
[out]speciesIsSupportedtrue if the Model supports the species of interest, false otherwise.
[out]codeValue used by the Model to refer to the species of interest.
Returns
true if speciesName is unknown.
false otherwise.
Precondition
code may be NULL if the value is not needed.
Postcondition
speciesIsSupported and code are unchanged if an error occurs. code is unchanged if speciesIsSupported == false.
See also
KIM_Model_GetSpeciesSupportAndCode, kim_model_module::kim_get_species_support_and_code
Since
2.0

◆ GetUnits()

void KIM::Model::GetUnits ( LengthUnit *const  lengthUnit,
EnergyUnit *const  energyUnit,
ChargeUnit *const  chargeUnit,
TemperatureUnit *const  temperatureUnit,
TimeUnit *const  timeUnit 
) const

Get the Model's base unit values.

Parameters
[out]lengthUnitThe Model's base LengthUnit.
[out]energyUnitThe Model's base EnergyUnit.
[out]chargeUnitThe Model's base ChargeUnit.
[out]temperatureUnitThe Model's base TemperatureUnit.
[out]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.
Precondition
lengthUnit, energyUnit, chargeUnit, temperatureUnit, or timeUnit may be NULL if the corresponding value is not needed.
See also
KIM_Model_GetUnits, kim_model_module::kim_get_units
Since
2.0

◆ IsRoutinePresent()

int KIM::Model::IsRoutinePresent ( ModelRoutineName const  modelRoutineName,
int *const  present,
int *const  required 
) const

Determine presence and required status of the given ModelRoutineName.

Parameters
[in]modelRoutineNameThe ModelRoutineName of interest.
[out]presenttrue if the Model provides the routine, false otherwise.
[out]requiredtrue if the Model requires the use of the routine, false otherwise.
Returns
true if modelRoutineName is unknown.
false otherwise.
Precondition
present or required may be NULL if the corresponding value is not needed.
Postcondition
present and required are unchanged if an error occurs.
See also
KIM_Model_IsRoutinePresent, kim_model_module::kim_is_routine_present
Since
2.0

◆ PopLogVerbosity()

void KIM::Model::PopLogVerbosity ( )

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

See also
KIM_Model_PopLogVerbosity, kim_model_module::kim_pop_log_verbosity
Since
2.0

◆ PushLogVerbosity()

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

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

Parameters
[in]logVerbosityA LogVerbosity value.
See also
KIM_Model_PushLogVerbosity, kim_model_module::kim_push_log_verbosity
Since
2.0

◆ SetLogID()

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

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

Parameters
[in]logIDString identifying the Model object's Log object.
See also
KIM_Model_SetLogID, kim_model_module::kim_set_log_id
Since
2.0

◆ SetParameter() [1/2]

int KIM::Model::SetParameter ( int const  parameterIndex,
int const  arrayIndex,
int const  parameterValue 
)

Set a parameter value for the Model.

Parameters
[in]parameterIndexZero-based index for the parameter array of interest.
[in]arrayIndexZero-based index within the array for the parameter of interest.
[in]parameterValueThe new value for the parameter of interest.
Returns
true if parameterIndex is invalid.
true if the specified parameter and parameterValue are of different data types.
true if arrayIndex is invalid.
false otherwise.
See also
KIM_Model_SetParameterInteger, KIM_Model_SetParameterDouble, kim_model_module::kim_set_parameter
Since
2.0

◆ SetParameter() [2/2]

int KIM::Model::SetParameter ( int const  parameterIndex,
int const  arrayIndex,
double const  parameterValue 
)

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

◆ SetSimulatorBufferPointer()

void KIM::Model::SetSimulatorBufferPointer ( void *const  ptr)

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

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

Parameters
[in]ptrThe simulator buffer data pointer.
See also
KIM_Model_SetSimulatorBufferPointer, kim_model_module::kim_set_simulator_buffer_pointer
Since
2.0

◆ ToString()

std::string const& KIM::Model::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_Model_ToString, kim_model_module::kim_to_string
Since
2.0

◆ WriteParameterizedModel()

int KIM::Model::WriteParameterizedModel ( std::string const &  path,
std::string const &  modelName 
) const

Call the Model's MODEL_ROUTINE_NAME::WriteParameterizedModel routine.

Parameters
[in]pathPath string to directory within which the new parameterized model files should be written.
[in]modelNameName of the parameterized model to be created. Must be a valid C identifier.
Returns
true if the Model object is not a parameterized model.
true if modelName is not a valid C identifier.
true if the Model's MODEL_ROUTINE_NAME::WriteParameterizedModel routine returns true.
true if the KIM API is unable to write the CMakeLists.txt file.
false otherwise.
See also
KIM_Model_WriteParameterizedModel, kim_model_module::kim_write_parameterized_model
Since
2.0

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