Miscellaneous functions¶
-
function
chfl_version
()¶ Get the version of the Chemfiles library.
- Return
character (len=CHFL_STRING_LENGTH)
-
CHFL_STRING_LENGTH
[integer]¶ Chemfiles uses fixed length strings, containing at most
CHFL_STRING_LENGTH
characters. If you need longer strings than the default (1024), you will need to edit the corresponding source code.
Error handling¶
-
function
chfl_last_error
()¶ Get the last error message emitted by Chemfiles.
- Return
character (len=CHFL_STRING_LENGTH)
-
subroutine
chfl_clear_errors
([status])¶ Clear the last error message emitted by Chemfiles.
- Options
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.
All chemfiles functions have an optional status
argument which is an integer
of kind chfl_status
, and can take the following values:
-
chfl_status
[integer]¶ Kind parameter for subroutine and function optional integer status.
-
CHFL_SUCCESS
[integer(chfl_status)]¶ Status for successful operations.
-
CHFL_MEMORY_ERROR
[integer(chfl_status)]¶ Status code for error concerning memory: out of memory, wrong size for pre-allocated buffers, etc.
-
CHFL_FILE_ERROR
[integer(chfl_status)]¶ Status code for error concerning files: the file do not exist, the user does not have rights to open it, etc.
-
CHFL_FORMAT_ERROR
[integer(chfl_status)]¶ Status code for error in file formatting, i.e. for invalid files.
-
CHFL_SELECTION_ERROR
[integer(chfl_status)]¶ Status code for invalid selection strings.
-
CHFL_CONFIGURATION_ERROR
[integer(chfl_status)]¶ Status code for configuration files errors.
-
CHFL_OUT_OF_BOUNDS
[integer(chfl_status)]¶ Status code for out of bounds indexing.
-
CHFL_PROPERTY_ERROR
[integer(chfl_status)]¶ Status code for errors related to properties.
-
CHFL_GENERIC_ERROR
[integer(chfl_status)]¶ Status code for any other error from Chemfiles.
-
CHFL_CXX_ERROR
[integer(chfl_status)]¶ Status code for error in the C++ standard library.
Warnings¶
-
subroutine
chfl_set_warning_callback
(callback[, status])¶ Chemfiles sends warning on various events, for example invalid files or errors in the API usage. By default they are printed to the standard error stream, but you can redirect them by setting a callback to be called on each event with the event message. This function set the callback for all warning events.
- Parameters
callback [procedure(chfl_warning_callback)] :: warning callback
- Options
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.
-
subroutine
chfl_warning_callback
(message)¶ Interface for the warning callback to be used with
chfl_set_warning_callback
.- Parameters
message [string] :: The warning message
Configuration files¶
-
subroutine
chfl_add_configuration
(path[, status])¶ Read configuration data from the file at
path
.By default, chemfiles reads configuration from any file named
.chemfiles.toml
orchemfiles.toml
in the current directory or any parent directory. This function can be used to add data from another configuration file.This function will fail if there is no file at path, or if the file is incorrectly formatted. Data from the new configuration file will overwrite any existing data.
- Parameters
path [character(len=*)] :: the new configuration file path
- Options
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.
List known formats¶
-
type
chfl_format_metadata
¶ A
chfl_format_metadata
contains metadata associated with one format- Type fields
%
name
[character(len=CHFL_STRING_LENGTH)] :: name of the format%
extension
[character(len=CHFL_STRING_LENGTH)] :: extension associated with the format, or empty string if there is no associated extension%
description
[character(len=CHFL_STRING_LENGTH)] :: extended, user-facing description of the format%
reference
[character(len=CHFL_STRING_LENGTH)] :: URL pointing to the format definition/reference%
read
[logical] :: is reading files in this format implemented?%
write
[logical] :: is writing files in this format implemented?%
memory
[logical] :: does this format support in-memory IO?%
positions
[logical] :: does this format support storing atomic positions?%
velocities
[logical] :: does this format support storing atomic velocities?%
unit_cell
[logical] :: does this format support storing unit cell information?%
atoms
[logical] :: does this format support storing atom names or types?%
bonds
[logical] :: does this format support storing bonds between atoms?%
residues
[logical] :: does this format support storing residues?
-
subroutine
chfl_formats_list
(metadata[, status])¶ Get the list of formats known by chemfiles, as well as all associated metadata.
This function allocate memory for all known formats. Users of this function are responsible with cleaning up this memory using the standard
deallocate
.- Parameters
type (chfl_format_metadata), allocatable metadata(:) :: array that will be allocated and filled with all formats metadata
- Options
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.