kim-api  2.3.0+v2.3.0.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
KIM_Model.hpp
Go to the documentation of this file.
1 //
2 // KIM-API: An API for interatomic models
3 // Copyright (c) 2013--2022, Regents of the University of Minnesota.
4 // All rights reserved.
5 //
6 // Contributors:
7 // Ryan S. Elliott
8 //
9 // SPDX-License-Identifier: LGPL-2.1-or-later
10 //
11 // This library is free software; you can redistribute it and/or
12 // modify it under the terms of the GNU Lesser General Public
13 // License as published by the Free Software Foundation; either
14 // version 2.1 of the License, or (at your option) any later version.
15 //
16 // This library is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 // Lesser General Public License for more details.
20 //
21 // You should have received a copy of the GNU Lesser General Public License
22 // along with this library; if not, write to the Free Software Foundation,
23 // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
24 //
25 
26 //
27 // Release: This file is part of the kim-api-2.3.0 package.
28 //
29 
30 
31 #ifndef KIM_MODEL_HPP_
32 #define KIM_MODEL_HPP_
33 
34 #include <string>
35 
36 namespace KIM
37 {
38 // Forward declarations
39 class LogVerbosity;
40 class DataType;
41 class ModelRoutineName;
42 class SpeciesName;
43 class Numbering;
44 class LengthUnit;
45 class EnergyUnit;
46 class ChargeUnit;
47 class TemperatureUnit;
48 class TimeUnit;
49 class ComputeArguments;
50 class ModelImplementation;
51 
58 class Model
59 {
60  public:
78 
119  static int Create(Numbering const numbering,
120  LengthUnit const requestedLengthUnit,
121  EnergyUnit const requestedEnergyUnit,
122  ChargeUnit const requestedChargeUnit,
123  TemperatureUnit const requestedTemperatureUnit,
124  TimeUnit const requestedTimeUnit,
125  std::string const & modelName,
126  int * const requestedUnitsAccepted,
127  Model ** const model);
128 
142  // \since 2.0
143  static void Destroy(Model ** const model);
144 
165  int IsRoutinePresent(ModelRoutineName const modelRoutineName,
166  int * const present,
167  int * const required) const;
168 
180  void GetInfluenceDistance(double * const influenceDistance) const;
181 
208  int * const numberOfNeighborLists,
209  double const ** const cutoffs,
210  int const ** const modelWillNotRequestNeighborsOfNoncontributingParticles)
211  const;
212 
234  void GetUnits(LengthUnit * const lengthUnit,
235  EnergyUnit * const energyUnit,
236  ChargeUnit * const chargeUnit,
237  TemperatureUnit * const temperatureUnit,
238  TimeUnit * const timeUnit) const;
239 
260  int ComputeArgumentsCreate(ComputeArguments ** const computeArguments) const;
261 
283  int ComputeArgumentsDestroy(ComputeArguments ** const computeArguments) const;
284 
301  int Compute(ComputeArguments const * const computeArguments) const;
302 
319  int Extension(std::string const & extensionID,
320  void * const extensionStructure);
321 
341  int ClearThenRefresh();
342 
364  int WriteParameterizedModel(std::string const & path,
365  std::string const & modelName) const;
366 
387  int GetSpeciesSupportAndCode(SpeciesName const speciesName,
388  int * const speciesIsSupported,
389  int * const code) const;
390 
400  void GetNumberOfParameters(int * const numberOfParameters) const;
401 
426  int GetParameterMetadata(int const parameterIndex,
427  DataType * const dataType,
428  int * const extent,
429  std::string const ** const name,
430  std::string const ** const description) const;
431 
450  int GetParameter(int const parameterIndex,
451  int const arrayIndex,
452  int * const parameterValue) const;
453 
455  int GetParameter(int const parameterIndex,
456  int const arrayIndex,
457  double * const parameterValue) const;
458 
477  int SetParameter(int const parameterIndex,
478  int const arrayIndex,
479  int const parameterValue);
480 
482  int SetParameter(int const parameterIndex,
483  int const arrayIndex,
484  double const parameterValue);
485 
498  void SetSimulatorBufferPointer(void * const ptr);
499 
512  void GetSimulatorBufferPointer(void ** const ptr) const;
513 
523  std::string const & ToString() const;
524 
533  void SetLogID(std::string const & logID);
534 
543  void PushLogVerbosity(LogVerbosity const logVerbosity);
544 
551  void PopLogVerbosity();
552 
553  private:
554  // do not allow copy constructor or operator=
555  Model(Model const &);
556  void operator=(Model const &);
557 
558  Model();
559  ~Model();
560 
561  ModelImplementation * pimpl;
562 }; // class Model
563 } // namespace KIM
564 
565 #endif // KIM_MODEL_HPP_
void SetLogID(std::string const &logID)
Set the identity of the Log object associated with the Model object.
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.
void GetUnits(LengthUnit *const lengthUnit, EnergyUnit *const energyUnit, ChargeUnit *const chargeUnit, TemperatureUnit *const temperatureUnit, TimeUnit *const timeUnit) const
Get the Model&#39;s base unit values.
An Extensible Enumeration for the TemperatureUnit&#39;s supported by the KIM API.
An Extensible Enumeration for the TimeUnit&#39;s supported by the KIM API.
int WriteParameterizedModel(std::string const &path, std::string const &modelName) const
Call the Model&#39;s MODEL_ROUTINE_NAME::WriteParameterizedModel routine.
An Extensible Enumeration for the ModelRoutineName&#39;s supported by the KIM API.
std::string const & ToString() const
Get a string representing the internal state of the Model object.
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&#39;s parameter arrays.
void GetNeighborListPointers(int *const numberOfNeighborLists, double const **const cutoffs, int const **const modelWillNotRequestNeighborsOfNoncontributingParticles) const
Get the Model&#39;s neighbor list information.
void SetSimulatorBufferPointer(void *const ptr)
Set the Simulator&#39;s buffer pointer within the Model object.
An Extensible Enumeration for the DataType&#39;s supported by the KIM API.
int ComputeArgumentsCreate(ComputeArguments **const computeArguments) const
Create a new ComputeArguments object for the Model object.
SupportStatus const required
The standard required status.
An Extensible Enumeration for the LengthUnit&#39;s supported by the KIM API.
int Compute(ComputeArguments const *const computeArguments) const
Call the Model&#39;s MODEL_ROUTINE_NAME::Compute routine.
int SetParameter(int const parameterIndex, int const arrayIndex, int const parameterValue)
Set a parameter value for the Model.
void GetInfluenceDistance(double *const influenceDistance) const
Get the Model&#39;s influence distance.
int Extension(std::string const &extensionID, void *const extensionStructure)
Call the Model&#39;s MODEL_ROUTINE_NAME::Extension routine.
An Extensible Enumeration for the LogVerbosity&#39;s supported by the KIM API.
An Extensible Enumeration for the Numbering&#39;s supported by the KIM API.
Provides the primary interface to a KIM API Model object and is meant to be used by simulators...
Definition: KIM_Model.hpp:58
static void Destroy(Model **const model)
Destroy a previously Model::Create&#39;d object.
An Extensible Enumeration for the EnergyUnit&#39;s supported by the KIM API.
void PopLogVerbosity()
Pop a LogVerbosity from the Model object&#39;s Log object verbosity stack.
void GetSimulatorBufferPointer(void **const ptr) const
Get the Simulator&#39;s buffer pointer from the Model object.
Provides the primary interface to a KIM API ComputeArguments object and is meant to be used by simula...
void GetNumberOfParameters(int *const numberOfParameters) const
Get the number of parameter arrays provided by the Model.
An Extensible Enumeration for the ChargeUnit&#39;s supported by the KIM API.
int GetParameter(int const parameterIndex, int const arrayIndex, int *const parameterValue) const
Get a parameter value from the Model.
int GetSpeciesSupportAndCode(SpeciesName const speciesName, int *const speciesIsSupported, int *const code) const
Get the Model&#39;s support and code for the requested SpeciesName.
int ComputeArgumentsDestroy(ComputeArguments **const computeArguments) const
Destroy a previously Model::ComputeArgumentsCreate&#39;d object.
int IsRoutinePresent(ModelRoutineName const modelRoutineName, int *const present, int *const required) const
Determine presence and required status of the given ModelRoutineName.
An Extensible Enumeration for the SpeciesName&#39;s supported by the KIM API.
int ClearThenRefresh()
Clear influence distance and neighbor list pointers and refresh Model object after parameter changes...
void PushLogVerbosity(LogVerbosity const logVerbosity)
Push a new LogVerbosity onto the Model object&#39;s Log object verbosity stack.