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).
Typedefs | Functions
KIM_Collections.h File Reference
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct KIM_LogVerbosity KIM_LogVerbosity
 Forward declaration. More...
 
typedef struct KIM_Collection KIM_Collection
 
typedef struct KIM_CollectionItemType KIM_CollectionItemType
 
typedef struct KIM_Collections KIM_Collections
 Provides the interface to the KIM API Collections and is meant to be used by simulators. More...
 

Functions

int KIM_Collections_Create (KIM_Collections **const collections)
 Create a new KIM API Collections object. More...
 
void KIM_Collections_Destroy (KIM_Collections **const collections)
 Destroy a previously Collections::Create'd object. More...
 
int KIM_Collections_GetItemType (KIM_Collections *const collections, char const *const itemName, KIM_CollectionItemType *const itemType)
 Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name. More...
 
int KIM_Collections_GetItemLibraryFileNameAndCollection (KIM_Collections *const collections, KIM_CollectionItemType const itemType, char const *const itemName, char const **const fileName, KIM_Collection *const collection)
 Get the item's library file name and its KIM::Collection. More...
 
int KIM_Collections_CacheListOfItemMetadataFiles (KIM_Collections *const collections, KIM_CollectionItemType const itemType, char const *const itemName, int *const extent)
 Cache a list of an item's metadata files. More...
 
int KIM_Collections_GetItemMetadataFile (KIM_Collections *const collections, int const index, char const **const fileName, unsigned int *const fileLength, unsigned char const **const fileRawData, int *const availableAsString, char const **const fileString)
 Get the name and content of one of an item's metadata files. More...
 
int KIM_Collections_CacheListOfItemNamesByType (KIM_Collections *const collections, KIM_CollectionItemType const itemType, int *const extent)
 Cache a list of all item names of a specific type in the KIM API collections. More...
 
int KIM_Collections_GetItemNameByType (KIM_Collections *const collections, int const index, char const **const itemName)
 Get the name of an item from the cached list. More...
 
int KIM_Collections_CacheListOfItemNamesByCollectionAndType (KIM_Collections *const collections, KIM_Collection const collection, KIM_CollectionItemType const itemType, int *const extent)
 Cache a list of all item names of a specific type in a specific collection. More...
 
int KIM_Collections_GetItemNameByCollectionAndType (KIM_Collections *const collections, int const index, char const **const itemName)
 Get the name of an item from the cached list. More...
 
int KIM_Collections_GetItemLibraryFileNameByCollectionAndType (KIM_Collections *const collections, KIM_Collection const collection, KIM_CollectionItemType const itemType, char const *const itemName, char const **const fileName)
 Get the item's library file name. More...
 
int KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType (KIM_Collections *const collections, KIM_Collection const collection, KIM_CollectionItemType const itemType, char const *const itemName, int *const extent)
 Cache a list of an item's metadata files. More...
 
int KIM_Collections_GetItemMetadataFileByCollectionAndType (KIM_Collections *const collections, int const index, char const **const fileName, unsigned int *const fileLength, unsigned char const **const fileRawData, int *const availableAsString, char const **const fileString)
 Get the name and content of one of an item's metadata files. More...
 
void KIM_Collections_GetProjectNameAndSemVer (KIM_Collections *const collections, char const **const projectName, char const **const semVer)
 Get the KIM API project name and full Semantic Version string. More...
 
int KIM_Collections_GetEnvironmentVariableName (KIM_Collections *const collections, KIM_CollectionItemType const itemType, char const **const name)
 Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection. More...
 
void KIM_Collections_GetConfigurationFileEnvironmentVariable (KIM_Collections *const collections, char const **const name, char const **const value)
 Get the name and value of the environment variable that stores the name of the KIM API user configuration file. More...
 
void KIM_Collections_GetConfigurationFileName (KIM_Collections *const collections, char const **const fileName)
 Get the absolute file and path name of the KIM API user configuration file. More...
 
int KIM_Collections_CacheListOfDirectoryNames (KIM_Collections *const collections, KIM_Collection const collection, KIM_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 KIM_Collections_GetDirectoryName (KIM_Collections *const collections, int const index, char const **const directoryName)
 Get the name of a directory from the cached list. More...
 
void KIM_Collections_SetLogID (KIM_Collections *const collections, char const *const logID)
 Set the identity of the Log object associated with the Collections object. More...
 
void KIM_Collections_PushLogVerbosity (KIM_Collections *const collections, KIM_LogVerbosity const logVerbosity)
 Push a new LogVerbosity onto the Collections object's Log object verbosity stack. More...
 
void KIM_Collections_PopLogVerbosity (KIM_Collections *const collections)
 Pop a LogVerbosity from the Collections object's Log object verbosity stack. More...
 

Typedef Documentation

◆ KIM_Collection

Definition at line 57 of file KIM_Collections.h.

◆ KIM_CollectionItemType

Definition at line 67 of file KIM_Collections.h.

◆ KIM_Collections

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 79 of file KIM_Collections.h.

◆ KIM_LogVerbosity

Forward declaration.

Since
2.1

Definition at line 47 of file KIM_Collections.h.

Function Documentation

◆ KIM_Collections_CacheListOfDirectoryNames()

int KIM_Collections_CacheListOfDirectoryNames ( KIM_Collections *const  collections,
KIM_Collection const  collection,
KIM_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.

See also
KIM::Collections::CacheListOfDirectoryNames, kim_collections_module::kim_cache_list_of_directory_names
Since
2.1

◆ KIM_Collections_CacheListOfItemMetadataFiles()

int KIM_Collections_CacheListOfItemMetadataFiles ( KIM_Collections *const  collections,
KIM_CollectionItemType const  itemType,
char const *const  itemName,
int *const  extent 
)

Cache a list of an item's metadata files.

See also
KIM::Collections::CacheListOfItemMetadataFiles, kim_collections_module::kim_cache_list_of_item_metadata_files
Since
2.1

◆ KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType()

int KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType ( KIM_Collections *const  collections,
KIM_Collection const  collection,
KIM_CollectionItemType const  itemType,
char const *const  itemName,
int *const  extent 
)

Cache a list of an item's metadata files.

See also
KIM::Collections::CacheListOfItemMetadataFilesByCollectionAndType, kim_collections_module::kim_cache_list_of_item_metadata_files_by_collection_and_type
Since
2.1

◆ KIM_Collections_CacheListOfItemNamesByCollectionAndType()

int KIM_Collections_CacheListOfItemNamesByCollectionAndType ( KIM_Collections *const  collections,
KIM_Collection const  collection,
KIM_CollectionItemType const  itemType,
int *const  extent 
)

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

See also
KIM::Collections::CacheListOfItemNamesByCollectionAndType, kim_collections_module::kim_cache_list_of_item_names_by_collection_and_type
Since
2.1

◆ KIM_Collections_CacheListOfItemNamesByType()

int KIM_Collections_CacheListOfItemNamesByType ( KIM_Collections *const  collections,
KIM_CollectionItemType const  itemType,
int *const  extent 
)

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

See also
KIM::Collections::CacheListOfItemNamesByType, kim_collections_module::kim_cache_list_of_item_names_by_type
Since
2.1

◆ KIM_Collections_Create()

int KIM_Collections_Create ( KIM_Collections **const  collections)

Create a new KIM API Collections object.

See also
KIM::Collections::Create, kim_collections_module::kim_collections_create
Since
2.1

◆ KIM_Collections_Destroy()

void KIM_Collections_Destroy ( KIM_Collections **const  collections)

Destroy a previously Collections::Create'd object.

See also
KIM::Collections::Destroy, kim_collections_module::kim_collections_destroy
Since
2.1

◆ KIM_Collections_GetConfigurationFileEnvironmentVariable()

void KIM_Collections_GetConfigurationFileEnvironmentVariable ( KIM_Collections *const  collections,
char const **const  name,
char const **const  value 
)

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

See also
KIM::Collections::GetConfigurationFileEnvironmentVariable, kim_collections_module::kim_get_configuration_file_environment_variable
Since
2.1

◆ KIM_Collections_GetConfigurationFileName()

void KIM_Collections_GetConfigurationFileName ( KIM_Collections *const  collections,
char const **const  fileName 
)

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

See also
KIM::Collections::GetConfigurationFileName, kim_collections_module::kim_get_configuration_file_name
Since
2.1

◆ KIM_Collections_GetDirectoryName()

int KIM_Collections_GetDirectoryName ( KIM_Collections *const  collections,
int const  index,
char const **const  directoryName 
)

Get the name of a directory from the cached list.

See also
KIM::Collections::GetDirectoryName, kim_collections_module::kim_get_directory_name
Since
2.1

◆ KIM_Collections_GetEnvironmentVariableName()

int KIM_Collections_GetEnvironmentVariableName ( KIM_Collections *const  collections,
KIM_CollectionItemType const  itemType,
char const **const  name 
)

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

See also
KIM::Collections::GetEnvironmentVariableName, kim_collections_module::kim_get_environment_variable_name
Since
2.1

◆ KIM_Collections_GetItemLibraryFileNameAndCollection()

int KIM_Collections_GetItemLibraryFileNameAndCollection ( KIM_Collections *const  collections,
KIM_CollectionItemType const  itemType,
char const *const  itemName,
char const **const  fileName,
KIM_Collection *const  collection 
)

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

See also
KIM::Collections::GetItemLibraryFileNameAndCollection, kim_collections_module::kim_get_item_library_file_name_and_collection
Since
2.1

◆ KIM_Collections_GetItemLibraryFileNameByCollectionAndType()

int KIM_Collections_GetItemLibraryFileNameByCollectionAndType ( KIM_Collections *const  collections,
KIM_Collection const  collection,
KIM_CollectionItemType const  itemType,
char const *const  itemName,
char const **const  fileName 
)

Get the item's library file name.

See also
KIM::Collections::GetItemLibraryFileNameByCollectionAndType, kim_collections_module::kim_get_item_library_file_name_by_collection_and_type
Since
2.1

◆ KIM_Collections_GetItemMetadataFile()

int KIM_Collections_GetItemMetadataFile ( KIM_Collections *const  collections,
int const  index,
char const **const  fileName,
unsigned int *const  fileLength,
unsigned char const **const  fileRawData,
int *const  availableAsString,
char const **const  fileString 
)

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

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

◆ KIM_Collections_GetItemMetadataFileByCollectionAndType()

int KIM_Collections_GetItemMetadataFileByCollectionAndType ( KIM_Collections *const  collections,
int const  index,
char const **const  fileName,
unsigned int *const  fileLength,
unsigned char const **const  fileRawData,
int *const  availableAsString,
char const **const  fileString 
)

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

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

◆ KIM_Collections_GetItemNameByCollectionAndType()

int KIM_Collections_GetItemNameByCollectionAndType ( KIM_Collections *const  collections,
int const  index,
char const **const  itemName 
)

Get the name of an item from the cached list.

See also
KIM::Collections::GetItemNameByCollectionAndType, kim_collections_module::kim_get_item_name_by_collection_and_type
Since
2.1

◆ KIM_Collections_GetItemNameByType()

int KIM_Collections_GetItemNameByType ( KIM_Collections *const  collections,
int const  index,
char const **const  itemName 
)

Get the name of an item from the cached list.

See also
KIM::Collections::GetItemNameByType, kim_collections_module::kim_get_item_name_by_type
Since
2.1

◆ KIM_Collections_GetItemType()

int KIM_Collections_GetItemType ( KIM_Collections *const  collections,
char const *const  itemName,
KIM_CollectionItemType *const  itemType 
)

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

See also
KIM::Collections::GetItemType, kim_collections_module::kim_get_item_type
Since
2.1

◆ KIM_Collections_GetProjectNameAndSemVer()

void KIM_Collections_GetProjectNameAndSemVer ( KIM_Collections *const  collections,
char const **const  projectName,
char const **const  semVer 
)

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

See also
KIM::Collections::GetProjectNameAndSemVer, kim_collections_module::kim_get_project_name_and_sem_ver
Since
2.1

◆ KIM_Collections_PopLogVerbosity()

void KIM_Collections_PopLogVerbosity ( KIM_Collections *const  collections)

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

◆ KIM_Collections_PushLogVerbosity()

void KIM_Collections_PushLogVerbosity ( KIM_Collections *const  collections,
KIM_LogVerbosity const  logVerbosity 
)

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

See also
KIM::Collections::PushLogVerbosity, kim_collections_module::kim_push_log_verbosity
Since
2.1

◆ KIM_Collections_SetLogID()

void KIM_Collections_SetLogID ( KIM_Collections *const  collections,
char const *const  logID 
)

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

See also
KIM::Collections::SetLogID, kim_collections_module::kim_set_log_id
Since
2.1