kim-api
2.1.1+v2.1.1.GNU
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
|
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... | |
Provides the primary interface to a KIM API Model object and is meant to be used by simulators.
Definition at line 61 of file KIM_Model.hpp.
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.
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.int KIM::Model::Compute | ( | ComputeArguments const *const | computeArguments | ) | const |
Call the Model's MODEL_ROUTINE_NAME::Compute routine.
[in] | computeArguments | A ComputeArguments object. |
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.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.
[in,out] | computeArguments | Pointer to the newly created ComputeArguments object. |
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.computeArguments == NULL
if an error occurs.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.
[in,out] | computeArguments | Pointer to the ComputeArguments object. |
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.computeArguments
is unchanged if an error occurs, otherwise computeArguments == NULL
.
|
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.
[in] | numbering | The Numbering value used by the Simulator. |
[in] | requestedLengthUnit | The base LengthUnit requested by the Simulator. |
[in] | requestedEnergyUnit | The base EnergyUnit requested by the Simulator. |
[in] | requestedChargeUnit | The base ChargeUnit requested by the Simulator. |
[in] | requestedTemperatureUnit | The base TemperatureUnit requested by the Simulator. |
[in] | requestedTimeUnit | The base TimeUnit requested by the Simulator. |
[in] | modelName | The name of the Model to be created. |
[out] | requestedUnitsAccepted | An 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] | model | Pointer to the newly created Model object. |
modelName
is required to be a valid C-identifier.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.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.requestedUnitsAccepted
is unchanged and model == NULL
if an error occurs.
|
static |
Destroy a previously Model::Create'd object.
Call the Model's MODEL_ROUTINE_NAME::Destroy routine and deallocate the Model object.
[in,out] | model | Pointer to the Model object. |
model
points to a previously created KIM API Model object.model == NULL
.int KIM::Model::Extension | ( | std::string const & | extensionID, |
void *const | extensionStructure | ||
) |
Call the Model's MODEL_ROUTINE_NAME::Extension routine.
[in] | extensionID | A string uniquely identifying the extension to be executed. |
[in,out] | extensionStructure | Pointer to a data structure of the type defined by the extension to be executed. |
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.void KIM::Model::GetInfluenceDistance | ( | double *const | influenceDistance | ) | const |
Get the Model's influence distance.
[out] | influenceDistance |
influenceDistance
. (or link to docs elsewhere?)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.
[out] | numberOfNeighborLists | The number of neighbor lists required by the Model. |
[out] | cutoffs | The cutoff distance for each neighbor list. |
[out] | modelWillNotRequestNeighborsOfNoncontributingParticles | true if such neighbor lists will not be requested, false otherwise. |
numberOfNeighborLists
, cutoffs
, or modelWillNotRequestNeighborsOfNoncontributingParticles
may be NULL
if the corresponding value is not needed.void KIM::Model::GetNumberOfParameters | ( | int *const | numberOfParameters | ) | const |
Get the number of parameter arrays provided by the Model.
[out] | numberOfParameters | The number of parameter arrays provided by the Model. |
int KIM::Model::GetParameter | ( | int const | parameterIndex, |
int const | arrayIndex, | ||
int *const | parameterValue | ||
) | const |
Get a parameter value from the Model.
[in] | parameterIndex | Zero-based index for the parameter array of interest. |
[in] | arrayIndex | Zero-based index within the array for the parameter of interest. |
[out] | parameterValue | The value of the parameter of interest. |
true
if parameterIndex
is invalid. true
if the specified parameter and parameterValue
are of different data types. true
if arrayIndex
is invalid. false
otherwise.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.
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.
[in] | parameterIndex | Zero-based index for the parameter array. |
[out] | dataType | The DataType value for the parameter array. |
[out] | extent | The number of parameters in the array. |
[out] | name | A string identifying the parameter array (will be a valid C identifier). |
[out] | description | A free-form string description of the parameter array's content. |
true
if parameterIndex
is invalid false
otherwise.dataType
, extent
, name
, or description
may be NULL
if the corresponding value is not needed.void KIM::Model::GetSimulatorBufferPointer | ( | void **const | ptr | ) | const |
Get the Simulator's buffer pointer from the Model object.
[out] | ptr | The simulator buffer data pointer. |
ptr == NULL
if the simulator has not previously called Model::SetSimulatorBufferPointer.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.
[in] | speciesName | The SpeciesName of interest. |
[out] | speciesIsSupported | true if the Model supports the species of interest, false otherwise. |
[out] | code | Value used by the Model to refer to the species of interest. |
true
if speciesName
is unknown. false
otherwise.code
may be NULL
if the value is not needed.speciesIsSupported
and code
are unchanged if an error occurs. code
is unchanged if speciesIsSupported == false
.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.
[out] | lengthUnit | The Model's base LengthUnit. |
[out] | energyUnit | The Model's base EnergyUnit. |
[out] | chargeUnit | The Model's base ChargeUnit. |
[out] | temperatureUnit | The Model's base TemperatureUnit. |
[out] | timeUnit | The Model's base TimeUnit. |
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
.lengthUnit
, energyUnit
, chargeUnit
, temperatureUnit
, or timeUnit
may be NULL
if the corresponding value is not needed.int KIM::Model::IsRoutinePresent | ( | ModelRoutineName const | modelRoutineName, |
int *const | present, | ||
int *const | required | ||
) | const |
Determine presence and required status of the given ModelRoutineName.
[in] | modelRoutineName | The ModelRoutineName of interest. |
[out] | present | true if the Model provides the routine, false otherwise. |
[out] | required | true if the Model requires the use of the routine, false otherwise. |
true
if modelRoutineName
is unknown. false
otherwise.present
or required
may be NULL
if the corresponding value is not needed.present
and required
are unchanged if an error occurs.void KIM::Model::PopLogVerbosity | ( | ) |
Pop a LogVerbosity from the Model object's Log object verbosity stack.
void KIM::Model::PushLogVerbosity | ( | LogVerbosity const | logVerbosity | ) |
Push a new LogVerbosity onto the Model object's Log object verbosity stack.
[in] | logVerbosity | A LogVerbosity value. |
void KIM::Model::SetLogID | ( | std::string const & | logID | ) |
Set the identity of the Log object associated with the Model object.
int KIM::Model::SetParameter | ( | int const | parameterIndex, |
int const | arrayIndex, | ||
int const | parameterValue | ||
) |
Set a parameter value for the Model.
[in] | parameterIndex | Zero-based index for the parameter array of interest. |
[in] | arrayIndex | Zero-based index within the array for the parameter of interest. |
[in] | parameterValue | The new value for the parameter of interest. |
true
if parameterIndex
is invalid. true
if the specified parameter and parameterValue
are of different data types. true
if arrayIndex
is invalid. false
otherwise.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.
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.
[in] | ptr | The simulator buffer data pointer. |
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
.
int KIM::Model::WriteParameterizedModel | ( | std::string const & | path, |
std::string const & | modelName | ||
) | const |
Call the Model's MODEL_ROUTINE_NAME::WriteParameterizedModel routine.
[in] | path | Path string to directory within which the new parameterized model files should be written. |
[in] | modelName | Name of the parameterized model to be created. Must be a valid C identifier. |
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.