API documentation for the modular computation tool chain library. For installation instructions and getting started, see the README.
The library is organized into four main modules:
| Module | Purpose |
|---|---|
| mctc_io | Structure I/O and representation |
| mctc_env | Error handling and precision constants |
| mctc_data | Element data (radii, electronegativities) |
| mctc_ncoord | Coordination number evaluation |
All quantities in mctc-lib use atomic units:
The mctc_io_convert module provides conversion factors derived from CODATA constants:
use mctc_io_convert, only : aatoau, autoaa
! Convert Ångström to Bohr (atomic units)
xyz_bohr = xyz_ang * aatoau
! Convert Bohr to Ångström
xyz_ang = xyz_bohr * autoaa
Available conversion factors:
| Factor | Description |
|---|---|
aatoau |
Ångström → Bohr |
autoaa |
Bohr → Ångström |
autoeV |
Hartree → electron volts |
evtoau |
electron volts → Hartree |
autokj |
Hartree → kJ/mol |
kjtoau |
kJ/mol → Hartree |
autokcal |
Hartree → kcal/mol |
kcaltoau |
kcal/mol → Hartree |
autorcm |
Hartree → cm⁻¹ |
rcmtoau |
cm⁻¹ → Hartree |
autonm |
Hartree → nm (wavelength) |
nmtoau |
nm (wavelength) → Hartree |
The structure_type is the central data structure for molecular and periodic systems.
| Component | Type | Description |
|---|---|---|
nat |
integer | Number of atoms |
nid |
integer | Number of unique species |
xyz(3, nat) |
real(wp) | Cartesian coordinates (Bohr) |
num(nid) |
integer | Atomic numbers for each species |
id(nat) |
integer | Species index for each atom |
sym(nid) |
character | Element symbols for each species |
charge |
real(wp) | Total molecular charge |
uhf |
integer | Number of unpaired electrons |
lattice(3, 3) |
real(wp) | Lattice vectors (Bohr), optional |
periodic(3) |
logical | Periodic directions, optional |
bond(2, nbd) |
integer | Bond connectivity, optional |
Use new for programmatic construction:
use mctc_io
type(structure_type) :: mol
! From atomic numbers and coordinates (in Bohr)
call new(mol, [8, 1, 1], xyz, charge=0.0_wp, uhf=0)
! From element symbols
call new(mol, ["O", "H", "H"], xyz)
! With periodicity
call new(mol, num, xyz, lattice=lattice, periodic=[.true., .true., .true.])
The mctc_io module provides format-agnostic structure I/O.
Use read_structure to read from files:
use mctc_io
use mctc_env
type(structure_type) :: mol
type(error_type), allocatable :: error
! Auto-detect format from extension
call read_structure(mol, "input.xyz", error)
! Explicit format specification
call read_structure(mol, "input.dat", error, filetype%xyz)
Use write_structure to write to files:
! Auto-detect format
call write_structure(mol, "output.mol", error)
! Explicit format
call write_structure(mol, "output.dat", error, filetype%gen)
Use get_filetype to determine the file format from a filename, or the filetype enumerator directly when the format is known. See mctc_io_filetype for the complete list of supported formats.
use mctc_io, only : filetype, get_filetype
integer :: ftype
ftype = get_filetype("molecule.xyz") ! Returns filetype%xyz
See the format documentation for details on each format.
The mctc_env module provides the error_type for error propagation.
use mctc_env
type(error_type), allocatable :: error
call library_routine(result, error)
if (allocated(error)) then
write(*, '(a)') error%message
error stop 1
end if
Use fatal_error in your own routines:
use mctc_env, only : error_type, fatal_error
subroutine my_routine(input, output, error)
type(error_type), allocatable, intent(out) :: error
if (invalid_condition) then
call fatal_error(error, "Descriptive error message")
return
end if
end subroutine
The mctc_data module provides element-specific data. All radii are returned in Bohr.
| Function | Description |
|---|---|
| get_covalent_rad | Covalent radii |
| get_vdw_rad | van der Waals radii |
| get_atomic_rad | Atomic radii |
| get_pauling_en | Pauling electronegativities |
use mctc_data
use mctc_env, only : wp
real(wp) :: r_cov, r_vdw, en
r_cov = get_covalent_rad(6) ! Carbon
r_vdw = get_vdw_rad(6)
en = get_pauling_en(6)
The mctc_ncoord module provides coordination number evaluators. See the module documentation for the complete list of available counting functions.
use mctc_ncoord
use mctc_io, only : structure_type
use mctc_env, only : wp, error_type
class(ncoord_type), allocatable :: ncoord
type(error_type), allocatable :: error
real(wp), allocatable :: cn(:)
call new_ncoord(ncoord, mol, cn_count%exp, error)
if (allocated(error)) stop error%message
allocate(cn(mol%nat))
call ncoord%get_cn(mol, cn)
Convert between element symbols and atomic numbers:
use mctc_io, only : to_symbol, to_number
character(len=2) :: sym
integer :: num
sym = to_symbol(6) ! Returns "C"
num = to_number("C") ! Returns 6
num = to_number("c") ! Case-insensitive, returns 6
Add to subprojects/mctc-lib.wrap:
[wrap-git]
directory = mctc-lib
url = https://github.com/grimme-lab/mctc-lib
revision = head
In meson.build:
mctc_dep = dependency('mctc-lib', fallback: ['mctc-lib', 'mctc_dep'])
In fpm.toml:
[dependencies.mctc-lib]
git = "https://github.com/grimme-lab/mctc-lib"