CIF_TCOD

Version: 0.020 (2023-11-15)

TCOD_METHOD

_tcod_structure_type

This data item specifies what kind of computationally optimised structure does the file record. Structures that record stable crystal polymorphs with long time-lifes (i.e. time lifes much longer than duration of a typical diffraction experiment) are 'ground-state'; however, short-lived structures that can be refined with the help of DFT or other methods can be included into TCOD, but must be tagged accordingly.

Possibly, we can classify structures by their half-lifes at certain temperatures.

Values:

_tcod_model

S.G. 2016-10-28: FIXME:

‒ merge with the NOMAD 'Electronic structure method';

‒ add indication that this data item is related to the NOMAD 'Electronic structure method';

‒ see also: NOMAD 'calcuation_method'

This should define the theoretical model used to calculate the structure.

L.V. The list is by no means exhaustive and should be constantly updated.

Main classes of models: DFT, ab initio (post-Hartree-Fock: Moeller-Plesset (MPx), Configuration Interaction (CI), coupled cluster (CC), Quantum Monte Carlo (QMC), Symmetry-adapted perturbation theory (SAPT), semi-empirical (OF-DFT, DFTB, NDDO, MINDO etc.), force field (empirical), coarse-grained (non-atomistic).

Keywords: DFT (Density model theory), HF (Hartree-Fock), MPn (Moller-Plesset) perturbation theory, e.g. local MP2 by Kresse, Schutz, Scuseria etc.), MI (Method of increments by H. Stoll et al.), CC (Periodic coupled cluster e.g. by Grüneis et al.), QMC (Quantum Monte Carlo by Ceperley, Mitas, Recently FCI-QMC by Alavi et al.), Orbital-free DFT (E. Carter et al.), DFTB (Density model tight binding by Seifert, Frauenheim etc.), Semi-empirical methods, Force field models (fixed charged, polarizable, distributed multipoles etc.), Coarse-grained models (e.g. Martini)

L.V. Tried to compile a short list of methods used for periodic calculations

L.V. in principal one should also define a class for hybrid models (QM/MM)

One can add a human-readable description of the mehtod here as well as the reference.

L.V. Is it possible to add full cif syntax to define the reference? S.G. Yes, done in the ..._citation_id and _tcod_citation_linkage data items.

Values:

TCOD_DATABASE

Data items from this category are used for TCOD bookkeeping records, such as assigned TCOD number (aka TCOD database code).

Examples:

_tcod_database_code

Specifies TCOD number assigned upon deposition into TCOD to the crystal structure described in the CIF.

TCOD_DATA_SOURCE

Data items from this category are used to record and trace sources of information deposited into TCOD.

_tcod_data_source_file

Specifies file name of the file that served as a source of data in this TCOD entry. The file should be recorded without the path or other URL components, since these components usually have no sense on the recipient's system. In Unix parlance, the value recorded should be the basename of the original file. For many data sources, however, the basename contains enough information to locate the original source. For instance, CIFs published in IUCr journals have Coeditor Code as a CIF file name, permitting to identify the original paper where the structure is discussed. Other journals may used original article's DOI as a part of the filename for the supplementary CIF file, which also permits one to trace back the original paper.

_tcod_data_source_block

Specifies the name of the data block within the file specified in the _tcod_data_source_file tag that served as a source of data in this TCOD entry. Only the data block name following the 'data_' header keyword should be recorded, not the whole data block header; i.e. the value specified here should be 'I', *not* 'data_I', for a data block with the header 'data_I'.

TCOD_SOURCE_STRUCTURE_DATABASE

Data items in this category are used to identify the source database record of the structure in question.

_tcod_source_structure_database_uuid

UUID (Universally Unique Identifier, https://en.wikipedia.org/wiki/Universally_unique_identifier) of the database output structure (node, record) that was exported to this entry.

_tcod_source_structure_database_id

Internal database identifier of a structure.

_tcod_source_structure_database_URI

Database URI of a structure.

_tcod_source_structure_database_version

Version of a structure.

TCOD_SOURCE_DATABASE

Data items in this category are used to identify the source database of the structure in question.

_tcod_source_database_name

A name of a database that was used to produce (to compute) this structure.

Example:

_tcod_source_database_name AiiDA

_tcod_source_database_URI

A (stable) URI (or URL) of the database Web site describing the database that produced the structure.

Example:

_tcod_source_database_URI https://www.aiida.net

_tcod_source_database_version

A version of the database that produced a structure under consideration.

Example:

_tcod_source_database_version 1.0

TCOD_SOFTWARE

Data items in this category are used to describe computation software.

_tcod_software_package

Software package used to compute and produce the DFT-computed structure file. Only package or program name should be used, e.g. 'VASP', 'psi3', 'Abinit', etc.

_tcod_software_package_version

Software package version used to compute and produce the computed structure file. Only version designator should be used, e.g. '3.4.0', '2.1rc3'. It is desirable that the combination of the _tcod_software_package and _tcod_software_package_version values would uniquely identify the code that was used for computations.

_tcod_software_package_compilation_date

ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601) format timestamp of the time when the executable was compiled.

Should correspond to the https://www.xml-cml.org/dictionary/compchem/#compileDate data element, but MUST be expressed in the ISO standard format.

_tcod_software_package_compilation_environment

A set of environment variable definitions, in /bin/sh syntax (i.e. using the "NAME=VALUE" syntax) for all relevant environment variables that were active when compiling this package. You can get the list in this syntax from the Unix/Linux 'printenv' command.

_tcod_software_package_binary_uri

An URI (Web reference) where the binary package of the software used for this computation can be fetched.

_tcod_software_package_source_uri

An URI (Web reference) where the source code package of the software used for this computation can be fetched.

_tcod_software_executable_path

The file-system path to the executable that was run for this computation.

_tcod_software_runtime_OS

Operating system used to compute and produce the DFT-computed structure file. Only OS name should be used, e.g. 'Irix', 'Windows XP', 'Ubuntu GNU/Linux', etc.

_tcod_software_OS_version

Operating system version used to compute and produce the DFT-computed structure file. Only version designator should be used, e.g. '3.4.0', '2.1rc3'. It is desirable that the combination of the _dft_software_operating_system and _dft_software_package_operating_system_version values would uniquely identify the OS that was used for computations.

_tcod_software_OS_compilation_date

ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601) format timestamp of the time when the operating system image was compiled.

_tcod_software_runtime_OS_binary_uri

An URI (Web reference) where the binary image (e.g. an ISO file, or a virtual machine image) of the operating system on which computations were peformed can be fetched.

_tcod_software_runtime_OS_source_uri

An URI (Web reference) where the source code of the operating system on which computations were performed can be fetched.

_tcod_software_runtime_CPU

Name (type) of the central processing unit (CPU), together with the floating-point processing unit, that was used to compute the results.

_tcod_software_runtime_CPU_version

Version or release number of the central processing unit (CPU), together with the floating-point processing unit, that was used to compute the results.

_tcod_software_compiler

The compiler which compiled the code used for the described calcualtion. Only the compiler name should be given, e.g. 'gcc', 'icc', 'gfortran'.

If more than one compiler was used, these items must be looped.

_tcod_software_compiler_version

A version string (number) of the compiler used to compile the code for this computation.

_tcod_software_compiler_options

A string with all options that were used to compile the given package.

TCOD_SOFTWARE_LIBRARY

Describes computational libraries.

_tcod_software_library_id

Identifies a software library in a loop

_tcod_software_library

The subroutine library (e.g. linear algebra) that was linked with the code used for the described calculation. Only the library name should be given, e.g. 'pthreads', 'libc', 'lapack'.

If more than one library was used, these items must be looped.

_tcod_software_library_version

A version string (number) of the library linked with the code for this computation.

_tcod_software_library_compilation_date

ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601) format timestamp of the time when the subroutine library file was compiled.

_tcod_software_library_compilation_environment

A set of environment variable definitions, in /bin/sh syntax (i.e. using the "NAME=VALUE" syntax) for all relevant environment variables that were active when compiling this library. You can get the list in this syntax from the Unix/Linux 'printenv' command.

_tcod_software_library_compiler_name

Library compiler name (same syntax as for a package compiler).

_tcod_software_library_compiler_version

Library compiler version (same syntax as for a package compiler).

_tcod_software_library_compiler_options

Library compiler options that were used (same syntax as for a package compiler).

_tcod_software_library_path

A file sytem path of the library file (especially the shared library, *.so or *.dll) linked with the code for this computation.

_tcod_software_library_binary_uri

An URI (Web reference) where the binary software library used for this computation can be fetched.

_tcod_software_library_source_uri

An URI (Web reference) where the source code software library used for this computation can be fetched.

TCOD_INITIAL_COORDINATE

Initial atomic coordinate source.

_tcod_initial_coordinate_db_name

Coordinate source database name (e.g. "Crystallography Open Database")

_tcod_initial_coordinate_db_abbrev

Coordinate source database abbreviated name (e.g. "COD")

_tcod_initial_coordinate_db_URI

Coordinate source database stable URI, e.g. https://www.crystallography.net

_tcod_initial_coordinate_db_code

Coordinate source database stable stable identifier, e.g. 1518187 (for COD entry 1518187).

_tcod_initial_coordinate_URI

A stable URI of coordinate file, e.g. https://www.crystallography.net/cod/1518187.cif

TCOD_INITIAL_CELL_PARAM

Initial crystallographic unit cell parameter source.

_tcod_initial_cell_param_db_name

Unit cell parameter source database name (e.g. "Crystallography Open Database")

_tcod_initial_cell_param_db_abbrev

Unit cell parameter source database abbreviated name (e.g. "COD")

_tcod_initial_cell_param_db_URI

Unit cell parameter source database stable URI, e.g. https://www.crystallography.net

_tcod_initial_cell_param_db_code

Unit cell parameter source database stable identifier, e.g. 1518187 (for COD entry 1518187).

_tcod_initial_cell_param_URI

A stable URI of a file with the initial unit cell parameters, e.g. https://www.crystallography.net/cod/1518187.cif

TCOD_FF

Data items in this category are used to describe force fields.

_tcod_ff_id

A unique identifier (primary key) of a force field in a loop, in case the COD datablock containing it refers to more than one force field.

_tcod_ff_type

Fixed charge (standard biomolecular and materials: amber, opls, gromos etc.) Polarizable (AMOEBA, iAMOEBA etc.) Distributed multipole based FFs (multipoles instead of fixed point charges S. Price et al.) Hybrid (Different types for interatomic and intraatomic interactions)
Reactive (ReaxFF etc.) L.V. The list is non-exhaustive

Values:

_tcod_ff_name

Standard name for the FF used. If there is no standard name use 'custom' Examples: charmm, opls, amber, gromos etc. L.V. One must add a reference to the original paper here

_tcod_ff_version

Version of a force field. Usually year of the publication.

_tcod_ff_citation_id

A reference to the citation describing the force field in the _citation_... category loop

TCOD_FILE

Data items in this category are used to describe input and output files.

_tcod_file_id

Primary key for the _tcod_file_... table.

_tcod_file_name

_tcod_file_source_database_name

_tcod_file_source_database_URI

_tcod_file_source_database_version

_tcod_file_source_reference_id

_tcod_file_source_reference_version

_tcod_file_source_reference_uuid

_tcod_file_md5sum

MD5 checksum of the file.

_tcod_file_sha1sum

SHA1 checksum of the file.

_tcod_file_format

_tcod_file_interpreter

_tcod_file_role

Values:

_tcod_file_contents_type

Values:

_tcod_file_contents

_tcod_file_content_encoding

Must match a single _tcod_content_encoding_id from the same datablock.

_tcod_file_URI

A stable URI (Web reference) where the file can be fetched.

TCOD_CONTENT_ENCODING

Data items in this category are used to describe content encodings used for file contents inserted into CIF files.

Examples:

loop_
_tcod_content_encoding_id
_tcod_content_encoding_layer_id
_tcod_content_encoding_layer_type
gzip+base64 1 gzip
gzip+base64 2 base64

_tcod_content_encoding_id

_tcod_content_encoding_layer_id

One-based number of an encoding layer in the encoding stack, starting from the innermost layer.

_tcod_content_encoding_layer_type

Values:

TCOD_COMPUTATION

Data items in this category are used to describe computation steps.

_tcod_computation_input_file

Link to '_tcod_file_id' of a file with STDIN contents for a computation.

_tcod_computation_log_file

Link to '_tcod_file_id' of a file with a log file for a computation.

_tcod_computation_stdout

Link to '_tcod_file_id' of a file with STDOUT contents for a computation.

_tcod_computation_stderr

Link to '_tcod_file_id' of a file with STDERR contents for a computation.

_tcod_computation_CPU_time

CPU time in seconds (excluding I/O).

Units: seconds

_tcod_computation_wallclock_time

The elapsed wall-clock time in seconds, from the start to the finish of this computation.

Units: seconds

_tcod_computation_command

_tcod_computation_step

One-based position of the computation step, designating the order of execution of this step. Steps with lesser values are to be executed before the steps with greater values of this data item.

_tcod_computation_environment

A set of environment variable definitions, in /bin/sh syntax (i.e. using the "NAME=VALUE" syntax) for all relevant environment variables that are needed to reproduce this computation. You can get the list in this syntax from the Unix/Linux 'printenv' command.

_tcod_computation_reference_uuid

_tcod_computation_reference_id

Reference to a computation description (its primary key) in the remote database that published and stored this computation.

_tcod_computation_reference_URI

Reference to a computation description (its stable REST URI) in the remote database that published and stored this computation.

_tcod_computation_database_name

A name of the database that was used to publish and document this computation.

_tcod_computation_database_version

A version of the database that was used to publish and document this computation.

_tcod_computation_database_URI

A stable URI (of a human-readable description) of the database that was used to publish and document this computation.

TCOD_TOTAL_ENERGY

_tcod_total_energy

Ideally, should correspond to https://www.xml-cml.org/dictionary/compchem/ "total energy" (ID: totalEnergy) whenever applicable.

The total energy for a system of electrons and nuclei. The exact method of computing this parameter depends on the method. The formula used to compute it should be given in the _tcod_total_energy_formula data item; in CIF2 this will be a DRel method (i.e. a formal computable expression in a strictly specified computer language).

CAUTION: total energies are comparable only between computations made by the same method, under the same approximations and with the same or similar input parameters. Therefore, the value of this data item *SHOULD NOT* be used to rank different TCOD entries without proper scaling, analysis and justification.

Units: electron_volts

_tcod_total_energy_formula

Formula used to compute the _tcod_total_energy value; the exact syntax details are still to be specified.

_tcod_total_energy_details

A human-readable description of the _tcod_total_energy computation ‒ its physical meaning and usability.

_tcod_total_energy_gradient

Gives an total energy gradient at the end of the computation (e.g. at the last optimisation cycle). Derivatives to be taken by nuclei positions and cell parameters.

Units: electron_volts_per_angstrom

_tcod_total_energy_gradient_formula

Formula or computer code used to compute the _tcod_total_energy_gradient value; the exact syntax details are still to be specified.

_tcod_total_energy_gradient_details

A human-readable description of the _tcod_total_energy_gradient computation ‒ its physical meaning and usability.