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

Provides the interface to the KIM API Collections and is meant to be used by simulators. More...

#include <KIM_Collections.hpp>

Public Member Functions

int GetItemType (std::string const &itemName, CollectionItemType *const itemType) const
 Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name. More...
 
int GetItemLibraryFileNameAndCollection (CollectionItemType const itemType, std::string const &itemName, std::string const **const fileName, Collection *const collection) const
 Get the item's library file name and its KIM::Collection. More...
 
int CacheListOfItemMetadataFiles (CollectionItemType const itemType, std::string const &itemName, int *const extent)
 Cache a list of an item's metadata files. More...
 
int GetItemMetadataFile (int const index, std::string const **const fileName, unsigned int *const fileLength, unsigned char const **const fileRawData, int *const availableAsString, std::string const **const fileString) const
 Get the name and content of one of an item's metadata files. More...
 
int CacheListOfItemNamesByType (CollectionItemType const itemType, int *const extent)
 Cache a list of all item names of a specific type in the KIM API collections. More...
 
int GetItemNameByType (int const index, std::string const **const itemName) const
 Get the name of an item from the cached list. More...
 
int CacheListOfItemNamesByCollectionAndType (Collection const collection, CollectionItemType const itemType, int *const extent)
 Cache a list of all item names of a specific type in a specific collection. More...
 
int GetItemNameByCollectionAndType (int const index, std::string const **const itemName) const
 Get the name of an item from the cached list. More...
 
int GetItemLibraryFileNameByCollectionAndType (Collection const collection, CollectionItemType const itemType, std::string const &itemName, std::string const **const fileName) const
 Get the item's library file name. More...
 
int CacheListOfItemMetadataFilesByCollectionAndType (Collection const collection, CollectionItemType const itemType, std::string const &itemName, int *const extent)
 Cache a list of an item's metadata files. More...
 
int GetItemMetadataFileByCollectionAndType (int const index, std::string const **const fileName, unsigned int *const fileLength, unsigned char const **const fileRawData, int *const availableAsString, std::string const **const fileString) const
 Get the name and content of one of an item's metadata files. More...
 
void GetProjectNameAndSemVer (std::string const **const projectName, std::string const **const semVer) const
 Get the KIM API project name and full Semantic Version string. More...
 
int GetEnvironmentVariableName (CollectionItemType const itemType, std::string const **const name) const
 Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection. More...
 
void GetConfigurationFileEnvironmentVariable (std::string const **const name, std::string const **const value) const
 Get the name and value of the environment variable that stores the name of the KIM API user configuration file. More...
 
void GetConfigurationFileName (std::string const **const fileName) const
 Get the absolute file and path name of the KIM API user configuration file. More...
 
int CacheListOfDirectoryNames (Collection const collection, CollectionItemType const itemType, int *const extent)
 Cache a list of directory names where a specific KIM API collection stores library files for a specific item type. More...
 
int GetDirectoryName (int const index, std::string const **const directoryName) const
 Get the name of a directory from the cached list. More...
 
void SetLogID (std::string const &logID)
 Set the identity of the Log object associated with the Collections object. More...
 
void PushLogVerbosity (LogVerbosity const logVerbosity)
 Push a new LogVerbosity onto the Collections object's Log object verbosity stack. More...
 
void PopLogVerbosity ()
 Pop a LogVerbosity from the Collections object's Log object verbosity stack. More...
 

Static Public Member Functions

static int Create (Collections **const collections)
 Create a new KIM API Collections object. More...
 
static void Destroy (Collections **const collections)
 Destroy a previously Collections::Create'd object. More...
 

Detailed Description

Provides the interface to the KIM API Collections and is meant to be used by simulators.

The KIM API defines interfaces to various types of "items" (KIM::CollectionItemType) and these items are organized and stored in various "collections" (KIM::Collection) on the user's system. Items are generally installed to or removed from the collections by using the kim-api-collections-management utility, and the KIM API/PMI and KIM API/SMI find items within the collections using the KIM::Collections interface. Typically, the collections are associated with different levels of user permissions on the system. The KIM::COLLECTION::system collection is available to all users on the system and is managed by the system administrator and cannot be changed by users without administrator privileges. The KIM::COLLECTION::user collection is specific to each user and the use has full privileges to manage the collection. The KIM::COLLECTION::environmentVariable and the KIM::COLLECTION::currentWorkingDirectory collections allow users more dynamic flexibility to manage and store items for special purposes.

Each collection consists of a set of items organized by their item type (KIM::CollectionItemType). There are currently three item types: KIM::COLLECTION_ITEM_TYPE::portableModel represents KIM Portable Models that can be used with any simulator that supports the KIM API/PMI; KIM::COLLECTION_ITEM_TYPE::simulatorModel represents the KIM Simulator Models that can be used with a specific simulator that supports the KIM API/SMI; and KIM::COLLECTION_ITEM_TYPE::modelDriver represents KIM Model Drivers that are libraries of code that can be used by multiple Portable Models to help reduce code duplication. The KIM::Collections interface provides programatic access to the contents and system settings for the KIM API collections and items stored within them. The contents and settings of the collections can change during the lifetime of a KIM::Collections object (due to installation or removal of items by other processes on the machine and/or changes to environment variables or the configuration file). Therefore, when lists of information about the collections are requested (via a "CacheListOf...()" routine), the KIM::Collections interface first creates a cache of the list and then provides access to the cached list via a getter ("Get...()") routine. The cached list is only updated when the simulator makes another request for the list (via a "CacheListOf...()" routine).

Items in the KIM API collections are generally referred to by name. An item name is required to be a valid C-identifier (no other restrictions are imposed by the KIM API). Items in different collections can have the same name and items of different type can have the same name. However, this should generally be avoided. Typically, an item is referred to by specifying its type and name. In such cases the KIM API will search through the KIM API collections in a specific order (first the KIM::COLLECTION::currentWorkingDirectory, then KIM::COLLECTION::environmentVariable, then KIM::COLLECTION::user, and finally KIM::COLLECTION::system) and return the first occurrence of an item with the requested type and name that is found. In some cases only the name of the desired item is known, and Collections::GetItemType must be used first to determine the item's type. The Collections::GetItemType routine will search through each collection (in the order described just above) and through each item type within each collection in a specific order (first the KIM::COLLECTION_ITEM_TYPE::portableModel type, then the KIM::COLLECTION_ITEM_TYPE::simulatorModel type, and finally the KIM::COLLECTION_ITEM_TYPE::modelDriver type) and return the first occurrence of an item with the requested name that is found.

See also
KIM_Collections, kim_collections_module::kim_collections_handle_type
Since
2.1

Definition at line 113 of file KIM_Collections.hpp.

Member Function Documentation

◆ CacheListOfDirectoryNames()

int KIM::Collections::CacheListOfDirectoryNames ( Collection const  collection,
CollectionItemType const  itemType,
int *const  extent 
)

Cache a list of directory names where a specific KIM API collection stores library files for a specific item type.

Parameters
[in]collectionThe KIM::Collection of the items.
[in]itemTypeThe KIM::CollectionItemType of the items.
[out]extentThe number of directory names in the list.
Returns
true if collection or itemType are unknown.
true if the list is not successfully cached for some reason.
false otherwise.
Postcondition
extent == 0 and the cached list is empty if an error occurs.
See also
KIM_Collections_CacheListOfDirectoryNames, kim_collections_module::kim_cache_list_of_directory_names
Since
2.1

◆ CacheListOfItemMetadataFiles()

int KIM::Collections::CacheListOfItemMetadataFiles ( CollectionItemType const  itemType,
std::string const &  itemName,
int *const  extent 
)

Cache a list of an item's metadata files.

Parameters
[in]itemTypeThe KIM::CollectionItemType of the item.
[in]itemNameThe name of the item.
[out]extentThe number of metadata files in the list.
Returns
true if itemType is unknown.
true if the list is not successfully cached for some reason.
false otherwise.
Postcondition
extent == 0 and the cached list is empty if an error occurs.
See also
KIM_Collections_CacheListOfItemMetadataFiles, kim_collections_module::kim_cache_list_of_item_metadata_files
Since
2.1

◆ CacheListOfItemMetadataFilesByCollectionAndType()

int KIM::Collections::CacheListOfItemMetadataFilesByCollectionAndType ( Collection const  collection,
CollectionItemType const  itemType,
std::string const &  itemName,
int *const  extent 
)

Cache a list of an item's metadata files.

Parameters
[in]collectionThe KIM::Collection of the item.
[in]itemTypeThe KIM::CollectionItemType of the item.
[in]itemNameThe name of the item.
[out]extentThe number of metadata files in the list.
Returns
true if collection or itemType are unknown.
true if the list is not successfully cached for some reason.
false otherwise.
Postcondition
extent == 0 and the cached list is empty if an error occurs.
See also
KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType, kim_collections_module::kim_cache_list_of_item_metadata_files_by_collection_and_type
Since
2.1

◆ CacheListOfItemNamesByCollectionAndType()

int KIM::Collections::CacheListOfItemNamesByCollectionAndType ( Collection const  collection,
CollectionItemType const  itemType,
int *const  extent 
)

Cache a list of all item names of a specific type in a specific collection.

Parameters
[in]collectionThe KIM::Collection of the items.
[in]itemTypeThe KIM::CollectionItemType of the items.
[out]extentThe number of item names in the list.
Returns
true if collection or itemType are unknown.
false otherwise.
Postcondition
extent == 0 and the cached list is empty if an error occurs.
See also
KIM_Collections_CacheListOfItemNamesByCollectionAndType, kim_collections_module::kim_cache_list_of_item_names_by_collection_and_type
Since
2.1

◆ CacheListOfItemNamesByType()

int KIM::Collections::CacheListOfItemNamesByType ( CollectionItemType const  itemType,
int *const  extent 
)

Cache a list of all item names of a specific type in the KIM API collections.

Parameters
[in]itemTypeThe KIM::CollectionItemType of the items.
[out]extentThe number of item names in the list.
Returns
true if itemType is unknown.
false otherwise.
Postcondition
extent == 0 and the cached list is empty if an error occurs.
See also
KIM_Collections_CacheListOfItemNamesByType, kim_collections_module::kim_cache_list_of_item_names_by_type
Since
2.1

◆ Create()

static int KIM::Collections::Create ( Collections **const  collections)
static

Create a new KIM API Collections object.

Parameters
[out]collectionsPointer to the newly created Collections object.
Returns
true if the KIM API is unable to allocate a new log object.
false otherwise.
Postcondition
collections == NULL if an error occurs.
See also
KIM_Collections_Create, kim_collections_module::kim_collections_create
Since
2.1

◆ Destroy()

static void KIM::Collections::Destroy ( Collections **const  collections)
static

Destroy a previously Collections::Create'd object.

Parameters
[in,out]collectionsPointer to the Collections object.
Precondition
collections points to a previously created KIM API Collections object.
Postcondition
collections == NULL.
See also
KIM_Collections_Destroy, kim_collections_module::kim_collections_destroy
Since
2.1

◆ GetConfigurationFileEnvironmentVariable()

void KIM::Collections::GetConfigurationFileEnvironmentVariable ( std::string const **const  name,
std::string const **const  value 
) const

Get the name and value of the environment variable that stores the name of the KIM API user configuration file.

The KIM API user configuration file contains configuration settings for the KIM::COLLECTION::user collection.

Note
String pointers obtained from this routine are valid until the next call to Collections::GetConfigurationFileEnvironmentVariable or the KIM::Collections object is Collections::Destroy'd.
Parameters
[out]nameThe name of the environment variable.
[out]valueThe current value of the environment variable.
Precondition
name and value may be NULL if the corresponding value is not needed.
See also
KIM_Collections_GetConfigurationFileEnvironmentVariable, kim_collections_module::kim_get_configuration_file_environment_variable
Since
2.1

◆ GetConfigurationFileName()

void KIM::Collections::GetConfigurationFileName ( std::string const **const  fileName) const

Get the absolute file and path name of the KIM API user configuration file.

The KIM API user configuration file contains configuration settings for the KIM::COLLECTION::user collection.

Note
String pointer obtained from this routine are valid until the next call to Collections::GetConfigurationFileName or the KIM::Collections object is Collections::Destroy'd.
Parameters
[out]fileNameThe absolute file and path name of the configuration file.
See also
KIM_Collections_GetConfigurationFileName, kim_collections_module::kim_get_configuration_file_name
Since
2.1

◆ GetDirectoryName()

int KIM::Collections::GetDirectoryName ( int const  index,
std::string const **const  directoryName 
) const

Get the name of a directory from the cached list.

Parameters
[in]indexZero-based index for the directory name of interest.
[out]directoryNameThe directory's name.
Note
String pointers obtained from this routine are valid until the next call to Collections::CacheListOfDirectoryNames or the KIM::Collections object is Collections::Destroy'd.
Returns
true if index is invalid.
false otherwise.
Precondition
Collections::CacheListOfDirectoryNames must have been successfully executed before Collections::GetDirectoryName is called.
Postcondition
directoryName is unchanged if an error occurs.
See also
KIM_Collections_GetDirectoryName, kim_collections_module::kim_get_directory_name
Since
2.1

◆ GetEnvironmentVariableName()

int KIM::Collections::GetEnvironmentVariableName ( CollectionItemType const  itemType,
std::string const **const  name 
) const

Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection.

Parameters
[in]itemTypeThe KIM::CollectionItemType of interest.
[out]nameThe environment variable name.
Returns
true if itemType is unknown.
false otherwise.
Postcondition
name is unchanged if an error occurs.
See also
KIM_Collections_GetEnvironmentVariableName, kim_collections_module::kim_get_environment_variable_name
Since
2.1

◆ GetItemLibraryFileNameAndCollection()

int KIM::Collections::GetItemLibraryFileNameAndCollection ( CollectionItemType const  itemType,
std::string const &  itemName,
std::string const **const  fileName,
Collection *const  collection 
) const

Get the item's library file name and its KIM::Collection.

Parameters
[in]itemTypeThe KIM::CollectionItemType of the item.
[in]itemNameThe name of the item.
[out]fileNameThe absolute file and path name of the item's library.
[out]collectionThe KIM::Collection in which the item was found.
Returns
true if itemType is unknown.
true if a item with the specified type and name cannot be found.
false otherwise.
Precondition
fileName and collection may be NULL if the corresponding value is not needed.
Postcondition
fileName and collection are unchanged if an error occurs.
See also
KIM_Collections_GetItemLibraryFileNameAndCollection, kim_collections_module::kim_get_item_library_file_name_and_collection
Since
2.1

◆ GetItemLibraryFileNameByCollectionAndType()

int KIM::Collections::GetItemLibraryFileNameByCollectionAndType ( Collection const  collection,
CollectionItemType const  itemType,
std::string const &  itemName,
std::string const **const  fileName 
) const

Get the item's library file name.

Parameters
[in]collectionThe KIM::Collection of the item.
[in]itemTypeThe KIM::CollectionItemType of the item.
[in]itemNameThe name of the item.
[out]fileNameThe absolute file and path name of the item's library.
Returns
true if collection or itemType are unknown.
true if a item with the specified type and name cannot be found in the specified collection.
false otherwise.
Postcondition
fileName is unchanged if an error occurs.
See also
KIM_Collections_GetItemLibraryFileNameByCollectionAndType, kim_collections_module::kim_get_item_library_file_name_by_collection_and_type
Since
2.1

◆ GetItemMetadataFile()

int KIM::Collections::GetItemMetadataFile ( int const  index,
std::string const **const  fileName,
unsigned int *const  fileLength,
unsigned char const **const  fileRawData,
int *const  availableAsString,
std::string const **const  fileString 
) const

Get the name and content of one of an item's metadata files.

Provide access to the specified metadata file's name and raw data. If there are no embedded NULL characters in the raw data, the file contents are also provided as a string, for convenience.

Parameters
[in]indexZero-based index for the metadata file of interest.
[out]fileNameThe basename (file name without path) of the metadata file.
[out]fileLengthThe length of the metadata file.
[out]fileRawDataThe raw metadata file content, as a contiguous block of memory of length fileLength.
[out]availableAsStringAn integer that is set to true if the metadata file has no embedded NULL characters, and set to fales otherwise.
[out]fileStringThe contents of the metadata file as a string, if availableAsString == true, NULL otherwise.
Note
String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemMetadataFiles or the KIM::Collections object is Collections::Destroy'd.
Returns
true if index is invalid.
false otherwise.
Precondition
Collections::CacheListOfItemMetadataFiles must have been successfully executed before Collections::GetItemMetadataFile is called.
fileName, fileLength, fileRawData, availableAsString, and fileString may be NULL if the corresponding value is not needed.
Postcondition
fileName, fileLength, fileRawData, availableAsString, fileString are unchanged if an error occurs.
See also
KIM_Collections_GetItemMetadataFile, kim_collections_module::kim_get_item_metadata_file_length, kim_collections_module::kim_get_item_metadata_file_values
Since
2.1

◆ GetItemMetadataFileByCollectionAndType()

int KIM::Collections::GetItemMetadataFileByCollectionAndType ( int const  index,
std::string const **const  fileName,
unsigned int *const  fileLength,
unsigned char const **const  fileRawData,
int *const  availableAsString,
std::string const **const  fileString 
) const

Get the name and content of one of an item's metadata files.

Provide access to the specified metadata file's name and raw data. If there are no embedded NULL characters in the raw data, the file contents are also provided as a string, for convenience.

Parameters
[in]indexZero-based index for the metadata file of interest.
[out]fileNameThe basename (file name without path) of the metadata file.
[out]fileLengthThe length of the metadata file.
[out]fileRawDataThe raw metadata file content, as a contiguous block of memory of length fileLength.
[out]availableAsStringAn integer that is set to true if the metadata file has no embedded NULL characters, and set to fales otherwise.
[out]fileStringThe contents of the metadata file as a string, if availableAsString == true, NULL otherwise.
Note
String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemMetadataFilesByCollectionAndType or the KIM::Collections object is Collections::Destroy'd.
Returns
true if index is invalid.
false otherwise.
Precondition
Collections::CacheListOfItemMetadataFilesByCollectionAndType must have been successfully executed before Collections::GetItemMetadataFileByCollectionAndType is called.
fileName, fileLength, fileRawData, availableAsString, and fileString may be NULL if the corresponding value is not needed.
Postcondition
fileName, fileLength, fileRawData, availableAsString, fileString are unchanged if an error occurs.
See also
KIM_Collections_GetItemMetadataFileByCollectionAndType, kim_collections_module::kim_get_item_metadata_file_length_by_collection_and_type, kim_collections_module::kim_get_item_metadata_file_values_by_collection_and_type
Since
2.1

◆ GetItemNameByCollectionAndType()

int KIM::Collections::GetItemNameByCollectionAndType ( int const  index,
std::string const **const  itemName 
) const

Get the name of an item from the cached list.

Parameters
[in]indexZero-based index for the item name of interest.
[out]itemNameThe item's name.
Note
String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemNamesByCollectionAndType or the KIM::Collections object is Collections::Destroy'd.
Returns
true if index is invalid.
false otherwise.
Precondition
Collections::CacheListOfItemNamesByCollectionAndType must have been successfully executed before Collections::GetItemNameByCollectionAndType is called.
Postcondition
itemName is unchanged if an error occurs.
See also
KIM_Collections_GetItemNameByCollectionAndType, kim_collections_module::kim_get_item_name_by_collection_and_type
Since
2.1

◆ GetItemNameByType()

int KIM::Collections::GetItemNameByType ( int const  index,
std::string const **const  itemName 
) const

Get the name of an item from the cached list.

Parameters
[in]indexZero-based index for the item name of interest.
[out]itemNameThe item's name.
Note
String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemNamesByType or the KIM::Collections object is Collections::Destroy'd.
Returns
true if index is invalid.
false otherwise.
Precondition
Collections::CacheListOfItemNamesByType must have been successfully executed before Collections::GetItemNameByType is called.
Postcondition
itemName is unchanged if an error occurs.
See also
KIM_Collections_GetItemNameByType, kim_collections_module::kim_get_item_name_by_type
Since
2.1

◆ GetItemType()

int KIM::Collections::GetItemType ( std::string const &  itemName,
CollectionItemType *const  itemType 
) const

Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name.

Searches for an item with the given name in the KIM API collections and item types (using the standard order for collections and item types).

Parameters
[in]itemNameThe item name to be found.
[out]itemTypeThe KIM::CollectionItemType of the item.
Returns
true if an item with the specificed name cannot be found.
false otherwise.
Postcondition
itemType is unchanged if an error occurs.
See also
KIM_Collections_GetItemType, kim_collections_module::kim_get_item_type
Since
2.1

◆ GetProjectNameAndSemVer()

void KIM::Collections::GetProjectNameAndSemVer ( std::string const **const  projectName,
std::string const **const  semVer 
) const

Get the KIM API project name and full Semantic Version string.

The KIM API project name and version string are controlled by CMake settings during the configuration process.

Note
String pointers obtained from this routine are valid until the KIM::Collections object is Collections::Destroy'd.
Parameters
[out]projectNameThe project name.
[out]semVerThe complete Semantic Version string.
Precondition
projectName and semVer may be NULL if the corresponding value is not needed.
See also
KIM_Collections_GetProjectNameAndSemVer, kim_collections_module::kim_get_project_name_and_sem_ver
Since
2.1

◆ PopLogVerbosity()

void KIM::Collections::PopLogVerbosity ( )

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

See also
KIM_Collections_PopLogVerbosity, kim_collections_module::kim_pop_log_verbosity
Since
2.1

◆ PushLogVerbosity()

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

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

Parameters
[in]logVerbosityA LogVerbosity value.
See also
KIM_Collections_PushLogVerbosity, kim_collections_module::kim_push_log_verbosity
Since
2.1

◆ SetLogID()

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

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

Parameters
[in]logIDString identifying the Collections object's Log object.
See also
KIM_Collections_SetLogID, kim_collections_module::kim_set_log_id
Since
2.1

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