From 0afbe528b226f7ff2733acbc996c7a81264f62a2 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Fri, 12 Dec 2025 09:43:58 +0000 Subject: [PATCH 1/3] Improve documentation --- AGENTS.md | 305 ++++++++++++++++++++++++++++++++++++++ README.md | 189 ++++++++++++++++++++++- doc/format-aims.md | 52 +++++-- doc/format-cjson.md | 40 ++++- doc/format-ctfile.md | 34 +++-- doc/format-ein.md | 53 ++++--- doc/format-gen.md | 65 ++++---- doc/format-pdb.md | 40 +++-- doc/format-pymatgen.md | 50 ++++++- doc/format-qchem.md | 46 ++++-- doc/format-qcschema.md | 50 +++++-- doc/format-tmol.md | 113 +++++++------- doc/format-vasp.md | 97 +++++++----- doc/format-xyz.md | 46 +++--- doc/index.md | 48 ++++-- docs.md | 295 ++++++++++++++++++++++++++++++------ man/mctc-convert.1.adoc | 197 ++++++++++++++++++++---- src/mctc/data.f90 | 23 ++- src/mctc/env.f90 | 26 +++- src/mctc/io.f90 | 39 +++-- src/mctc/io/structure.f90 | 18 ++- src/mctc/ncoord.f90 | 31 +++- 22 files changed, 1518 insertions(+), 339 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..4a8b7054 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,305 @@ +# AGENTS.md - Development Guide for mctc-lib + +This document provides guidance for AI agents and contributors working with the mctc-lib codebase. + +## Project Overview + +**mctc-lib** (Modular Computation Tool Chain Library) is a Fortran library providing unified molecular structure data handling and geometry file format I/O for computational chemistry applications. + +### Supported Geometry Formats + +The library supports reading and writing 12+ geometry formats: + +*General ASCII formats:* +- **xyz** - Xmol/xyz files (`.xyz`, `.log`) +- **pdb** - Protein Data Bank format (`.pdb`) +- **mol/sdf** - MDL connection table files (`.mol`, `.sdf`) + +*JSON-based formats:* +- **QCSchema** - MolSSI QCSchema JSON (`.qcjson`, `.json`) +- **Chemical JSON** - Avogadro Chemical JSON (`.cjson`, `.json`) +- **Pymatgen JSON** - Pymatgen Molecule/Structure (`.pmgjson`, `.json`) + +*Program-specific formats:* +- **Turbomole coord** - Turbomole/riper coordinates (`.tmol`, `.coord`) +- **VASP POSCAR** - VASP geometry files (`.vasp`, `.poscar`, `.contcar`) +- **DFTB+ gen** - DFTB+ genFormat (`.gen`) +- **Gaussian external** - Gaussian external program input (`.ein`) +- **FHI-aims** - FHI-aims geometry input (`geometry.in`) +- **Q-Chem** - Q-Chem molecule block (`.qchem`) + +## Repository Structure + +``` +mctc-lib/ +├── src/mctc/ # Main library source code +│ ├── io/ # I/O module (readers/writers for all formats) +│ │ ├── read/ # Format-specific readers +│ │ └── write/ # Format-specific writers +│ ├── env/ # Environment module (error handling, testing) +│ ├── data/ # Element data (radii, electronegativities) +│ └── ncoord/ # Coordination number utilities +├── app/ # Application code (mctc-convert tool) +├── test/ # Unit test suite +├── doc/ # FORD documentation pages (format descriptions) +├── man/ # Manual pages (asciidoc format) +├── include/ # Public include files +├── config/ # Build configuration scripts +└── subprojects/ # Meson wrap dependencies (jonquil, toml-f, test-drive) +``` + +## Build Systems + +This project supports three build systems. Choose based on your workflow: + +### Meson (Recommended) + +```bash +# Configure +meson setup _build + +# Build +meson compile -C _build + +# Test +meson test -C _build --print-errorlogs + +# Install +meson install -C _build +``` + +**Note**: Meson version 1.8.0 has a known bug and is explicitly unsupported. Use any other version ≥ 0.55. + +### CMake + +```bash +# Configure +cmake -B _build -G Ninja + +# Build +cmake --build _build + +# Test +cd _build && ctest && cd .. +``` + +### fpm (Fortran Package Manager) + +```bash +# Build +fpm build + +# Test +fpm test + +# Run application +fpm run -- --help +``` + +## Dependencies + +- **jonquil** (v0.3.0 or later) - JSON parsing (optional, enables JSON format support) +- **toml-f** (v0.4.3 or later) - TOML parsing (dependency of jonquil) +- **test-drive** - Testing framework (test dependency only) + +Dependencies are managed via Meson subprojects (wrap files), CMake find modules, or fpm. + +## Testing + +### Running Tests + +Tests are organized by functionality in `test/`: + +- `test_read_*.f90` - Reader tests for each format +- `test_write_*.f90` - Writer tests for each format +- `test_math.f90` - Mathematical utility tests +- `test_ncoord.f90` - Coordination number tests +- `test_symbols.f90` - Element symbol conversion tests + +```bash +# Run all tests with meson +meson test -C _build --print-errorlogs --suite mctc-lib + +# Run specific test +meson test -C _build test_read_xyz --print-errorlogs +``` + +### Writing Tests + +Tests use the `mctc_env_testing` module: + +```fortran +use mctc_env_testing, only : new_unittest, unittest_type, error_type, check + +subroutine collect_my_tests(testsuite) + type(unittest_type), allocatable, intent(out) :: testsuite(:) + testsuite = [ & + & new_unittest("test-name", test_procedure), & + & new_unittest("expected-fail", test_fail, should_fail=.true.) & + ] +end subroutine +``` + +## Code Style and Conventions + +### Fortran Style + +- Use Fortran 2008 standard features +- Free-form source format (`.f90`, `.F90` for preprocessed) +- Module names: `mctc__` (e.g., `mctc_io_read`) +- Private by default, explicitly export public entities +- Use `implicit none` in all program units + +### File Header + +All source files must include the Apache-2.0 license header: + +```fortran +! This file is part of mctc-lib. +! +! Licensed under the Apache License, Version 2.0 (the "License"); +! ... +``` + +### Error Handling + +Use the `error_type` for error propagation: + +```fortran +use mctc_env, only : error_type, fatal_error + +subroutine my_routine(result, error) + type(error_type), allocatable, intent(out) :: error + + if (some_error_condition) then + call fatal_error(error, "Descriptive error message") + return + end if +end subroutine +``` + +### Documentation + +- Use FORD-compatible docstrings (`!>` for preceding, `!<` for trailing) +- Document all public interfaces +- Run `ford docs.md` to generate documentation + +## CI/CD Workflow + +### GitHub Actions + +The CI pipeline (`.github/workflows/build.yml`) runs on push and pull requests: + +- **Platforms**: Ubuntu, macOS +- **Compilers**: GCC (10, 11, 12, 14), Intel oneAPI (2021) +- **Build systems**: Meson, CMake, fpm +- **Coverage**: Collected with GCC 11 and uploaded to Codecov + +### DCO (Developer Certificate of Origin) + +Contributions require sign-off. The DCO bot checks all commits. Sign your commits: + +```bash +git commit -s -m "Your commit message" +``` + +### Documentation Deployment + +Documentation is built with FORD and deployed to GitHub Pages on: +- Pushes to `main` branch +- Tagged releases + +## Adding New Features + +### Adding a New File Format + +1. Create reader in `src/mctc/io/read/` (e.g., `format.f90`) +2. Create writer in `src/mctc/io/write/` (e.g., `format.f90`) +3. Add filetype enum in `src/mctc/io/filetype.f90` +4. Register in `src/mctc/io/read.f90` and `src/mctc/io/write.f90` +5. Update meson.build and CMakeLists.txt in relevant directories +6. Add tests in `test/test_read_format.f90` and `test/test_write_format.f90` +7. Document in `doc/format-.md` + +### Core Data Types + +- `structure_type` (`mctc_io_structure`) - Main molecular structure container +- `error_type` (`mctc_env`) - Error handling type + +## Common Tasks + +### Convert Geometry Files + +```bash +# Using the mctc-convert tool +meson compile -C _build +./_build/app/mctc-convert input.xyz output.mol +``` + +### Read Structure in Your Code + +```fortran +use mctc_io +use mctc_env + +type(structure_type) :: mol +type(error_type), allocatable :: error + +call read_structure(mol, "input.xyz", error) +if (allocated(error)) then + print '(a)', error%message + error stop +end if +``` + +## Build Options + +### Meson Options (`meson_options.txt`) + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `openmp` | boolean | false | Enable OpenMP parallelization | +| `json` | feature | auto | Enable JSON format support | + +```bash +meson setup _build -Djson=enabled -Dopenmp=true +``` + +### CMake Options + +| Option | Description | +|--------|-------------| +| `WITH_JSON` | Enable JSON support | +| `WITH_OpenMP` | Enable OpenMP | + +## Troubleshooting + +### Common Issues + +1. **Meson 1.8.0 error**: Upgrade or downgrade meson (`pip install meson!=1.8.0`) + +2. **JSON tests fail**: Ensure jonquil dependency is available or disable with `-Djson=disabled` + +3. **Missing Fortran compiler**: Set `FC` environment variable: + ```bash + FC=gfortran meson setup _build + ``` + +## External Resources + +- [GitHub Repository](https://github.com/grimme-lab/mctc-lib) +- [API Documentation](https://grimme-lab.github.io/mctc-lib) +- [Issue Tracker](https://github.com/grimme-lab/mctc-lib/issues) + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Make changes following the code style guidelines +4. Add tests for new functionality +5. Ensure all tests pass +6. Sign off commits (DCO requirement) +7. Submit a pull request + +Error messages in mctc-lib are designed to be helpful with source location information. +If you encounter unclear error messages, please report them as bugs. diff --git a/README.md b/README.md index 501f24ea..8e9c95ef 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,44 @@ [![docs](https://github.com/grimme-lab/mctc-lib/workflows/docs/badge.svg)](https://grimme-lab.github.io/mctc-lib) [![codecov](https://codecov.io/gh/grimme-lab/mctc-lib/branch/main/graph/badge.svg)](https://codecov.io/gh/grimme-lab/mctc-lib) +A Fortran library providing unified molecular structure data handling and geometry file format I/O for computational chemistry applications. +The library supports reading and writing of molecular structures in more than twelve different geometry formats and provides element data and coordination number utilities. + + +## Features + +- **Unified structure representation**: A common [``structure_type``](https://grimme-lab.github.io/mctc-lib/type/structure_type.html) for handling molecular and periodic systems +- **Multi-format I/O**: Read and write structures in 12+ geometry formats +- **Element data**: Access to atomic/covalent/vdW radii and Pauling electronegativities +- **Coordination numbers**: Multiple counting functions (exponential, error function, electronegativity-weighted) +- **Helpful error messages**: Detailed error reporting with source location information +- **Multiple build systems**: Support for meson, CMake, and fpm + + +## Quick Start + +```f90 +program example + use mctc_io + use mctc_env + implicit none + type(structure_type) :: mol + type(error_type), allocatable :: error + + ! Read a structure (format auto-detected from extension) + call read_structure(mol, "molecule.xyz", error) + if (allocated(error)) stop error%message + + ! Access structure data + print '(a,i0)', "Number of atoms: ", mol%nat + print '(a,f12.6)', "Total charge: ", mol%charge + + ! Write to different format + call write_structure(mol, "molecule.mol", error) + if (allocated(error)) stop error%message +end program +``` + ## Supported formats @@ -175,10 +213,32 @@ mctc-lib.git = "https://github.com/grimme-lab/mctc-lib" An example application is provided with the [``mctc-convert``](man/mctc-convert.1.adoc) program to convert between different supported input formats. + +### Using mctc-convert + +After building, the ``mctc-convert`` tool can convert between any supported formats: + +```bash +# Convert xyz to Turbomole coord +mctc-convert molecule.xyz molecule.coord + +# Convert VASP POSCAR to xyz +mctc-convert POSCAR structure.xyz + +# Pipe from stdin to stdout +cat input.xyz | mctc-convert -i xyz -o mol - - + +# Preserve bond information from SDF when converting +mctc-convert optimized.xyz final.sdf --template original.sdf +``` + + +### Library Usage + To read an input file using the IO library use the ``read_structure`` routine. The final geometry data is stored in a ``structure_type``: -```fortran +```f90 use mctc_io use mctc_env type(structure_type) :: mol @@ -197,7 +257,7 @@ Alternatively, the ``filetype`` enumerator provides the identifiers of all suppo In a similar way the ``write_structure`` routine allows to write a ``structure_type`` to a file or unit: -``` fortran +```f90 use mctc_io use mctc_env type(structure_type) :: mol @@ -214,6 +274,120 @@ The [``mctc-convert``](man/mctc-convert.1.adoc) program provides a chained reade Checkout the implementation in [``app/main.f90``](app/main.f90). +## Working with the Structure Type + +The [``structure_type``](https://grimme-lab.github.io/mctc-lib/type/structure_type.html) is the central data structure for representing molecular systems: + +```f90 +type(structure_type) :: mol + +! Basic properties +mol%nat ! Number of atoms +mol%nid ! Number of unique species +mol%charge ! Total molecular charge +mol%uhf ! Number of unpaired electrons + +! Atomic data (arrays) +mol%xyz(:, :) ! Cartesian coordinates (3, nat) in Bohr +mol%id(:) ! Species index for each atom (nat) +mol%num(:) ! Atomic numbers for each species (nid) +mol%sym(:) ! Element symbols for each species (nid) + +! Periodic systems +mol%lattice(:, :) ! Lattice vectors (3, 3) in Bohr +mol%periodic(:) ! Periodic directions (3) + +! Optional data +mol%bond(:, :) ! Bond connectivity +mol%comment ! Structure title/comment +``` + +### Creating Structures Programmatically + +All inputs use atomic units. Coordinates must be provided in Bohr (1 Bohr ≈ 0.529 Å). + +```f90 +use mctc_io +use mctc_env, only : wp +implicit none +type(structure_type) :: mol +integer :: num(3) +real(wp) :: xyz(3, 3) + +! Water molecule (coordinates in Bohr) +num = [8, 1, 1] ! O, H, H +xyz = reshape([ & + & 0.0_wp, 0.0_wp, 0.2372_wp, & + & 0.0_wp, 1.4939_wp, -0.9487_wp, & + & 0.0_wp, -1.4939_wp, -0.9487_wp], [3, 3]) + +call new(mol, num, xyz, charge=0.0_wp, uhf=0) +``` + + +## Using Element Data + +Access element-specific properties from the [``mctc_data``](https://grimme-lab.github.io/mctc-lib/module/mctc_data.html) module: + +```f90 +use mctc_data +use mctc_env, only : wp +implicit none +real(wp) :: radius + +! Get covalent radius for carbon (atomic number 6) +radius = get_covalent_rad(6) + +! Available functions: +! get_covalent_rad(num) - Covalent radii in Bohr +! get_vdw_rad(num) - van der Waals radii in Bohr +! get_atomic_rad(num) - Atomic radii in Bohr +! get_pauling_en(num) - Pauling electronegativities +``` + + +## Element Symbol Conversion + +Convert between element symbols and atomic numbers: + +```f90 +use mctc_io, only : to_number, to_symbol + +integer :: num +character(len=2) :: sym + +num = to_number("C") ! Returns 6 +sym = to_symbol(6) ! Returns "C" +``` + + +## Specifying File Formats + +When the file extension is non-standard, use the ``filetype`` enumerator: + +```f90 +use mctc_io + +call read_structure(mol, "geometry.in", error, filetype%aims) +call write_structure(mol, "output.dat", error, filetype%xyz) +``` + +Available format identifiers: +- ``filetype%xyz`` - xyz format +- ``filetype%tmol`` - Turbomole coord +- ``filetype%molfile`` - mol file +- ``filetype%sdf`` - SDF format +- ``filetype%vasp`` - VASP POSCAR +- ``filetype%pdb`` - PDB format +- ``filetype%gen`` - DFTB+ genFormat +- ``filetype%gaussian`` - Gaussian external +- ``filetype%qcschema`` - QCSchema JSON +- ``filetype%cjson`` - Chemical JSON +- ``filetype%pymatgen`` - Pymatgen JSON +- ``filetype%aims`` - FHI-aims +- ``filetype%qchem`` - Q-Chem + + ## Error reporting The geometry input readers try to be provide helpful error messages, no user should be left alone with an error message like *invalid input*. @@ -272,6 +446,17 @@ Error: Conflicting lattice and cell groups We try to retain as much information as possible when displaying the error message to make it easy to fix the offending part in the input. +## API Documentation + +Full API documentation is available at [grimme-lab.github.io/mctc-lib](https://grimme-lab.github.io/mctc-lib). + +Key modules: +- [``mctc_io``](https://grimme-lab.github.io/mctc-lib/module/mctc_io.html) - Structure I/O (``read_structure``, ``write_structure``, ``structure_type``) +- [``mctc_env``](https://grimme-lab.github.io/mctc-lib/module/mctc_env.html) - Environment utilities (``error_type``, ``wp`` working precision) +- [``mctc_data``](https://grimme-lab.github.io/mctc-lib/module/mctc_data.html) - Element data (radii, electronegativities) +- [``mctc_ncoord``](https://grimme-lab.github.io/mctc-lib/module/mctc_ncoord.html) - Coordination number evaluation + + ## License Licensed under the Apache License, Version 2.0 (the “License”); diff --git a/doc/format-aims.md b/doc/format-aims.md index d09636aa..890ee16a 100644 --- a/doc/format-aims.md +++ b/doc/format-aims.md @@ -1,19 +1,48 @@ --- -title: FHI-aims geometry.in format +title: FHI-aims Geometry Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extension | (none, typically `geometry.in`) | +| Coordinate units | Ångström | +| Supports periodicity | Yes (via `lattice_vector`) | +| Format hint | `aims` | + ## Specification -Format used by FHI-aims program. -Atoms are specified by ``atom`` or ``atom_frac`` keyword followed by three real numbers and an character identifier. -Lattice parameters are given with the ``lattice_vector`` keyword followed by three real numbers. +The FHI-aims geometry format is the native input format for the FHI-aims all-electron DFT code. + +### Format Detection +The format is identified by: +- Basename: `geometry.in` (case-insensitive) +- Format specifier: `aims` -## Example +### Keywords -Caffeine molecule in xyz format +| Keyword | Description | +|---------|-------------| +| `atom` | Cartesian coordinates in Ångström | +| `atom_frac` | Fractional coordinates (periodic systems) | +| `lattice_vector` | Lattice vector (3 reals, one per line) | +### Atom Specification + +```text +atom x y z element +atom_frac a b c element ``` + +## Examples + +### Molecular System + +Caffeine molecule: + +```text atom 1.07320000000000 0.04890000000000 -0.07570000000000 C atom 2.51370000000000 0.01260000000000 -0.07580000000000 N atom 3.35200000000000 1.09590000000000 -0.07530000000000 C @@ -40,9 +69,11 @@ atom 4.40230000000000 -5.15920000000000 0.82840000000000 H atom 4.40020000000000 -5.16930000000000 -0.94780000000000 H ``` +### 3D Periodic System + Carbondioxide in FHI-aims format: -``` +```text atom 6.62447969041000 6.62412068645100 6.63464984519600 C atom 9.39832080661700 6.63600723231600 9.41199064870100 C atom 9.39627410479100 9.39525191972100 6.64954571641900 C @@ -60,10 +91,9 @@ lattice_vector 0.00000000000000 5.68032472285798 0.0000000 lattice_vector 0.00000000000000 0.00000000000000 5.68032472285798 ``` - -## Missing Features +## Limitations The implementation of this format is (to our knowledge) feature-complete. -@Note Feel free to contribute support for missing features - or bring missing features to our attention by opening an issue. +@Note Feel free to bring missing features to our attention by opening an issue. + diff --git a/doc/format-cjson.md b/doc/format-cjson.md index 94e5624b..ef681142 100644 --- a/doc/format-cjson.md +++ b/doc/format-cjson.md @@ -1,19 +1,42 @@ --- -title: Chemical JSON +title: Chemical JSON (cjson) --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.cjson`, `.json` | +| Coordinate units | Ångström | +| Supports periodicity | Yes (via `unit cell`) | +| Supports bonds | Yes | +| Format hint | `cjson` | + +@Note Requires JSON support (jonquil dependency) + ## Specification @Note [Reference](https://github.com/OpenChemistry/avogadrolibs/blob/master/avogadro/io/cjsonformat.cpp) -Chemical JSON files are identified by the extension ``cjson`` or ``json`` and parsed following the format implemented in Avogadro 2. -The entries *name*, *atoms.elements.number*, *atoms.coords.3d*, *atoms.coords.3d fractional*, *unit cell*, *atoms.formalCharges*, *bonds.connections.index*, and *bonds.order* are recognized by the reader. +Chemical JSON is a JSON-based format developed for Avogadro 2. +It provides a structured way to represent molecular data including geometry, bonds, and properties. +### Supported Fields -## Example +| Field | Description | +|-------|-------------| +| `name` | Molecule name | +| `atoms.elements.number` | Atomic numbers array | +| `atoms.coords.3d` | Cartesian coordinates (Ångström) | +| `atoms.coords.3dFractional` | Fractional coordinates | +| `atoms.formalCharges` | Formal charges per atom | +| `unitCell` | Unit cell parameters | +| `bonds.connections.index` | Bond connectivity (pairs of atom indices) | +| `bonds.order` | Bond orders | -Caffeine molecule in ``qcschema_molecule`` format. +## Example +Caffeine molecule: ```json { @@ -90,10 +113,11 @@ Caffeine molecule in ``qcschema_molecule`` format. } ``` +## Limitations -## Missing features - -The schema is not verified on completeness and not all data is stored in the final structure type. +- Schema completeness is not verified during reading +- Not all Chemical JSON fields are preserved in the structure type @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-ctfile.md b/doc/format-ctfile.md index 93485a65..e12757d4 100644 --- a/doc/format-ctfile.md +++ b/doc/format-ctfile.md @@ -1,14 +1,27 @@ --- -title: Connection table format +title: Connection Table Format (MOL/SDF) --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.mol`, `.sdf` | +| Coordinate units | Ångström | +| Supports periodicity | No | +| Supports bonds | Yes | +| Format hints | `mol`, `sdf` | + ## Specification @Note [Reference](https://www.daylight.com/meetings/mug05/Kappler/ctfile.pdf) -The molfile is identified by the extension ``mol`` and the structure data format -is identified by ``sdf``. -Both V2000 and V3000 connection tables can be read. +The MDL connection table format stores molecular structures with bond connectivity information. + +- **Molfile** (`.mol`): Single molecule format +- **SDF** (`.sdf`): Structure Data Format, can contain multiple molecules with additional properties + +Both V2000 and V3000 connection table formats are supported. ## Example @@ -46,17 +59,14 @@ Caffeine molecule in mol format: M END ``` -## Extensions - -No extension implemented to the original format. - -## Missing Features +## Limitations The following features are currently not supported: -- Not all modifiers are supported for the connection table -- SDF key-value pair annotations are dropped -- continuation lines in V3000 format are not supported +- Not all atom and bond modifiers are supported in the connection table +- SDF key-value pair annotations are dropped during reading +- Continuation lines in V3000 format are not supported @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-ein.md b/doc/format-ein.md index 550b26a7..578327bc 100644 --- a/doc/format-ein.md +++ b/doc/format-ein.md @@ -1,30 +1,40 @@ --- -title: Gaussian external format +title: Gaussian External Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extension | `.ein` | +| Coordinate units | Bohr (atomic units) | +| Supports periodicity | No | +| Supports charge/spin | Yes | +| Format hint | `ein` | + ## Specification @Note [Reference](https://gaussian.com/external/) -The first line of the input is read as four integers of width 10, ``(4i10)``, -containing the number of atoms in the first integer. -A run mode specific integer is given in the second entry. -The third integer contains the total charge and the fourth integer the spin as -number of unpaired electrons. -The total charge and the systems spin are stored in the [[structure_type]]. +The Gaussian external format is used for interfacing Gaussian with external programs. +It uses fixed-format input with atomic coordinates in atomic units (Bohr). + +### Format Structure -The structure is specified by atomic numbers, cartesian coordinates in atomic units -(Bohr) and a scalar quantity, usually partial charges using the fixed format -``(i10,4f20.12)``. -The element is identified by its atomic number, -which is converted to its capitalized element symbol internally. -Only positive, non-zero integers are allowed as atomic numbers. +**Line 1**: Header (fixed format `4i10`) +- Number of atoms +- Run mode (ignored when reading) +- Total charge +- Number of unpaired electrons (spin) -The expected file extension is ``ein``. +**Atom lines**: Fixed format `(i10,4f20.12)` +- Atomic number (positive integer) +- x, y, z coordinates in Bohr +- Scalar quantity (typically partial charge, ignored when reading) -## Examples +## Example -Caffeine molecule in Gaussian external format: +Caffeine molecule: ```text 24 1 0 0 @@ -54,16 +64,13 @@ Caffeine molecule in Gaussian external format: 1 8.315114380769 -9.768540219438 -1.791082028670 0.000000000000 ``` -## Extensions - -No extension implemented to the original format. - -## Missing Features +## Limitations The following features are currently not supported: -- the requested run-mode is dropped while reading. -- scalar atomic quantities are not preserved and dropped. +- Run mode (second integer in header) is dropped when reading +- Scalar atomic quantities (fourth column) are not preserved @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-gen.md b/doc/format-gen.md index d99b8e3a..aaf4dae6 100644 --- a/doc/format-gen.md +++ b/doc/format-gen.md @@ -1,40 +1,52 @@ --- -title: DFTB+ general format +title: DFTB+ General Format (gen) --- +## Overview + +| Property | Value | +|----------|-------| +| File extension | `.gen` | +| Coordinate units | Ångström (Cartesian) or fractional | +| Supports periodicity | Yes (0D, 3D, helical) | +| Supports bonds | No | +| Format hint | `gen` | + ## Specification @Note [Reference](https://dftbplus.org/fileadmin/DFTBPLUS/public/dftbplus/latest/manual.pdf) -The general (gen) format is used for DFTB+ as geometry input format. +The general (gen) format is the standard geometry input format for DFTB+. It is based on the [xyz format](./format-xyz.html). -The first line contains the number of atoms and the specific kind of provided -geometry. -Available types are cluster (``C``), supercell (``S``), fractional (``F``), -and helical (``H``), the letter defining the format is case-insensitive. +### Format Structure + +**Line 1**: Number of atoms and geometry type + +| Type | Code | Description | Coordinates | +|------|------|-------------|-------------| +| Cluster | `C` | Non-periodic molecule | Ångström | +| Supercell | `S` | 3D periodic with Cartesian | Ångström | +| Fractional | `F` | 3D periodic with fractional | Lattice fractions | +| Helical | `H` | Helical symmetry | Ångström | -The second line gives the element symbols for each group of atoms separated by -spaces, the groups are indexed starting from 1 and references in the specification -of the atomic coordinates by this index rather than their element symbol. +**Line 2**: Element symbols (space-separated), indexed starting from 1 -The following lines are specified as two integers and three reals separated by -spaces. The first integer is currently ignored. The second integer references -the element symbol in the second line. -The atomic coordinates are given in Ångström for cluster, supercell and helical, -while they are given as fraction of the lattice vector for fractional input types. +**Atom lines**: `index element_index x y z` +- First integer is currently ignored +- Second integer references element symbol in line 2 -For supercell and fractional input the next lines contains three reals containing -the origin of the structure, followed by three lines of each three reals for the -lattice vectors. +**Periodic systems** (S, F, H): Additional lines after atoms: +- Origin (3 reals) +- Three lattice vectors (3 lines × 3 reals) -Lines starting with the ``#`` are comments and are ignored while parsing. +Lines starting with `#` are comments. -The format is identified by the extension ``gen``. +## Examples -## Example +### Molecular System (Cluster) -Caffeine molecule in genFormat: +Caffeine molecule: ```text 24 C @@ -65,6 +77,8 @@ Caffeine molecule in genFormat: 24 4 4.40017000000000E+00 -5.16929000000000E+00 -9.47800000000000E-01 ``` +### 3D Periodic System (Supercell) + Ammonia molecular crystal: ```text @@ -92,13 +106,8 @@ Ammonia molecular crystal: 0.00000000000000 0.00000000000000 5.01336000000000 ``` -## Extensions - -No extension implemented to the original format. - -## Missing Features +## Limitations The implementation of this format is (to our knowledge) feature-complete. -@Note Feel free to contribute support for missing features - or bring missing features to our attention by opening an issue. +@Note Feel free to bring missing features to our attention by opening an issue. diff --git a/doc/format-pdb.md b/doc/format-pdb.md index 405fbf1a..19b43607 100644 --- a/doc/format-pdb.md +++ b/doc/format-pdb.md @@ -1,16 +1,36 @@ --- -title: Protein data bank (PDB) format +title: Protein Data Bank (PDB) Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extension | `.pdb` | +| Coordinate units | Ångström | +| Supports periodicity | No (cell info is discarded) | +| Supports bonds | Yes (via CONECT records) | +| Format hint | `pdb` | + ## Specification @Note [Reference](http://www.wwpdb.org/documentation/file-format-content/format33/v3.3.html) -The extension identifying this format is ``pdb``. +The Protein Data Bank (PDB) format is a standard for representing macromolecular structures. +This implementation reads atomic coordinates from ATOM and HETATM records and bond connectivity from CONECT records. + +### Supported Record Types + +| Record | Description | +|--------|-------------| +| `ATOM` | Standard amino acid atoms | +| `HETATM` | Heteroatoms (ligands, water, ions) | +| `CONECT` | Bond connectivity | +| `END` | End of structure | ## Example -4QXX protein with explicit hydrogen: +4QXX protein fragment with explicit hydrogen: ```text HEADER PROTEIN FIBRIL 22-JUL-14 4QXX @@ -155,18 +175,14 @@ CONECT 76 78 80 END ``` -## Extensions - -No extension implemented to the original format. - -## Missing Features +## Limitations The following features are currently not supported: -- Support for multiple file PDB input is not available -- Fractional side occupation is currently not supported - all optional sides count as full atoms -- Cell information is not preserved, PDB input is always handled molecular +- Multiple model/file PDB input (only first model is read) +- Fractional site occupancy (all alternative locations are treated as full atoms) +- Cell information (CRYST1 record) is not preserved; PDB input is always handled as molecular +- Anisotropic displacement parameters (ANISOU records) @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. diff --git a/doc/format-pymatgen.md b/doc/format-pymatgen.md index 170fa82f..5a71eb92 100644 --- a/doc/format-pymatgen.md +++ b/doc/format-pymatgen.md @@ -2,16 +2,49 @@ title: Pymatgen JSON --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.pmgjson`, `.json` | +| Coordinate units | Ångström | +| Supports periodicity | Yes (`Structure` class) | +| Supports charge/spin | Yes | +| Format hint | `pymatgen` | + +@Note Requires JSON support (jonquil dependency) + ## Specification @Note [Reference](https://pymatgen.org) -Pymatgen formatted JSON files are identified by the extension ``pmgjson`` or ``json`` and parsed following the ``Molecule`` or ``Structure`` format. +Pymatgen JSON format represents molecular and periodic structures using the Python Materials Genomics library schema. + +### Supported Classes + +| Class | Description | Periodicity | +|-------|-------------|-------------| +| `Molecule` | Molecular structure | Non-periodic | +| `Structure` | Periodic structure with lattice | 3D periodic | +### Key Fields -## Example +| Field | Description | +|-------|-------------| +| `@class` | `Molecule` or `Structure` | +| `charge` | Total charge | +| `spin_multiplicity` | Spin multiplicity (Molecule only) | +| `lattice` | Lattice parameters (Structure only) | +| `sites` | Array of atomic sites | +| `sites[].species` | Element and occupancy | +| `sites[].xyz` | Cartesian coordinates (Ångström) | +| `sites[].abc` | Fractional coordinates (Structure) | -Water molecules using ``Molecule`` schema. +## Examples + +### Molecular System + +Water molecules using `Molecule` schema: ```json { @@ -88,7 +121,9 @@ Water molecules using ``Molecule`` schema. } ``` -Rutile using ``Structure`` schema: +### Periodic System + +Rutile TiO₂ using `Structure` schema: ```json { @@ -158,9 +193,12 @@ Rutile using ``Structure`` schema: } ``` -## Missing features +## Limitations -The schema is not verified on completeness and not all data is stored in the final structure type. +- Schema completeness is not verified during reading +- Not all pymatgen fields are preserved in the structure type +- Site occupancies other than 1.0 are not fully supported @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-qchem.md b/doc/format-qchem.md index 2baa13cd..ddad0f69 100644 --- a/doc/format-qchem.md +++ b/doc/format-qchem.md @@ -1,20 +1,45 @@ --- -title: Q-Chem molecule format +title: Q-Chem Molecule Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extension | `.qchem` | +| Coordinate units | Ångström | +| Supports periodicity | No | +| Supports charge/spin | Yes | +| Format hint | `qchem` | + ## Specification -@Note: Reference can be found in the [Q-Chem manual](https://manual.q-chem.com/5.1/sect-molinput.html). +@Note Reference: [Q-Chem manual](https://manual.q-chem.com/5.1/sect-molinput.html) + +The Q-Chem molecule format specifies molecular geometry within a `$molecule` block. -Format used by the Q-Chem program. -Elements can be specified either by atomic numbers or element symbols while the geometry is provided in Ångström by default. +### Format Structure +```text +$molecule + charge multiplicity + element x y z + element x y z + ... +$end +``` + +### Elements + +Elements can be specified by: +- Element symbols (e.g., `C`, `H`, `O`) +- Atomic numbers (e.g., `6`, `1`, `8`) ## Example -Caffeine molecule in xyz format +Caffeine molecule: -``` +```text $molecule 0 1 C 1.07320000000000 0.04890000000000 -0.07570000000000 @@ -44,13 +69,12 @@ $molecule $end ``` +## Limitations -## Missing Features +The following features are currently not supported: -Following features are missing - -- reading of z-matrix input -- possibility to change coordinate units to Bohr +- Coordinate units other than Ångström (Bohr option) @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-qcschema.md b/doc/format-qcschema.md index 2b6137f9..d96c48b5 100644 --- a/doc/format-qcschema.md +++ b/doc/format-qcschema.md @@ -1,19 +1,47 @@ --- -title: QCSchema JSON +title: MolSSI QCSchema JSON --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.qcjson`, `.json` | +| Coordinate units | Bohr (atomic units) | +| Supports periodicity | Yes (via `extras.periodic.lattice`) | +| Supports bonds | Yes (via `connectivity`) | +| Supports charge/spin | Yes | +| Format hint | `qcschema` | + +@Note Requires JSON support (jonquil dependency) + ## Specification @Note [Reference](https://molssi-qc-schema.readthedocs.io) -JSON files are identified by the extension ``qcjson`` or ``json`` and parsed following the ``qcschema_molecule`` or ``qcschema_input`` format. -The ``molecule`` entry from a ``qcschema_input`` will be extracted, but there is no guarantee that the input information will be used by the program. +QCSchema is a JSON-based format standardized by the Molecular Sciences Software Institute (MolSSI) +for quantum chemistry data interchange. +### Supported Schemas -## Example +| Schema | Description | +|--------|-------------| +| `qcschema_molecule` | Molecular geometry and properties | +| `qcschema_input` | Complete calculation input (molecule extracted) | -Caffeine molecule in ``qcschema_molecule`` format. +### Key Fields +| Field | Description | +|-------|-------------| +| `symbols` | Element symbols array | +| `geometry` | Coordinates in Bohr (flattened [x1,y1,z1,x2,y2,z2,...]) | +| `molecular_charge` | Total charge | +| `molecular_multiplicity` | Spin multiplicity | +| `connectivity` | Bond connectivity (atom1, atom2, bond_order) | + +## Example + +Caffeine molecule in `qcschema_molecule` format: ```json { @@ -87,10 +115,10 @@ Caffeine molecule in ``qcschema_molecule`` format. ## Extensions -The reader supports the following extensions: +### Periodic Systems -- Periodic boundary conditions are specified by providing the lattice vectors in Bohr - as extras to the molecule in periodic.lattice as flattened array. +Periodic boundary conditions are supported via the `extras` field. +Lattice vectors are specified in Bohr as a flattened 3×3 array: ```json "extras": { @@ -104,9 +132,11 @@ The reader supports the following extensions: } ``` -## Missing features +## Limitations -The schema is not verified on completeness and not all data is stored in the final structure type. +- Schema completeness is not verified during reading +- Not all QCSchema fields are preserved in the structure type @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-tmol.md b/doc/format-tmol.md index 0603abf4..ab9653e8 100644 --- a/doc/format-tmol.md +++ b/doc/format-tmol.md @@ -1,77 +1,77 @@ --- -title: Turbomole's coordinate data group +title: Turbomole Coordinate Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.tmol`, `.coord` | +| Coordinate units | Bohr (default), Ångström (`angs`), or fractional (`frac`) | +| Supports periodicity | Yes (0D, 1D, 2D, 3D) | +| Supports charge/spin | Yes (via `$eht` data group) | +| Format hints | `tmol`, `coord` | + ## Specification @Note [Reference](https://www.turbomole.org/wp-content/uploads/2019/11/Turbomole_Manual_7-4-1.pdf) -The Turbomole format mainly builds around the ``control`` file. -The ``control`` file contains several data groups which are delimited by -their identifier, groups are either present in the ``control`` file or -references from the ``control`` file. -This format is defined by the geometry related information from the -``control`` file, mainly the: +The Turbomole coordinate format uses data groups delimited by `$` identifiers. +This format supports molecules and periodic systems (1D, 2D, 3D). + +### Format Detection + +The format is identified by: +- File extension: `.tmol`, `.coord` +- Basename: `coord` (case-insensitive) -- ``coord`` data group -- ``lattice`` data group -- ``cell`` data group -- ``periodic`` data group -- ``eht`` data group +### Data Groups -For simplicity file references are not allowed and all data groups should be -in the same file. The data groups are not required to be in any particular order. +| Data Group | Purpose | +|------------|---------| +| `$coord` | Cartesian or fractional atomic coordinates | +| `$lattice` | Lattice vectors (Bohr or Ångström) | +| `$cell` | Cell parameters (lengths and angles) | +| `$periodic` | Periodicity (0, 1, 2, or 3) | +| `$eht` | Charge and unpaired electrons | +| `$end` | End of file marker | -A group is started by a ``$`` symbol and accept modifiers. It is terminated by -another group or the ``end`` group which stops the scanning for further groups: +### Coordinate Data Group ```text -$group1 [modifier]... -[entries]... -$group2 [modifier]... -[entries]... -$end +$coord [bohr|angs|frac] + x1 y1 z1 element1 + x2 y2 z2 element2 + ... ``` -The ``coord`` data group contains the cartesian coordinates of all atoms and -their element symbols at the end of each line. -Atomic coordinates can either be specified in Bohr, by default or with the ``bohr`` -modifier on the ``coord`` data group, in Ångström with the modifier ``angs`` or -as fractions of the lattice vectors with the modifier ``frac``. -Fractional coordinates can only be present for periodicities greater than zero. - -The periodicity of the system is specified as modifier to the ``periodic`` data -group, the group itself is empty. +- **Default**: Bohr (atomic units) +- **`angs`**: Ångström +- **`frac`**: Fractional coordinates (periodic systems only) -The lattice parameters can either be specified in the ``lattice`` or the ``cell`` -data group, which require different amounts of entries depending on the systems -periodicity. Both data groups are either given in atomic units (Bohr) or in -Ångström with the ``angs`` modifier. +### Lattice Specification -For 3D periodic systems three lines with each three reals are required in the -``lattice`` data group. For a 2D periodic system two lines with each two reals -are required and the aperiodic direction is the z-axis. -Finally, for 1D periodic systems one real is required, giving the translation -vector in the x-direction. -The periodic directions are fixed in this format. +Lattice vectors via `$lattice` data group: +- **3D**: Three lines, three values each (3×3 matrix) +- **2D**: Two lines, two values each (z-axis is aperiodic) +- **1D**: One value (translation in x-direction) -Similarly, the ``cell`` data groups allows for six, three, and one entries for -3D, 2D, and 1D periodic systems, respectively. The cell parameters are given -as the length of the lattice vectors and their angles, with the angles given -in degrees. +Cell parameters via `$cell` data group: +- **3D**: a, b, c, α, β, γ (lengths in Bohr/Å, angles in degrees) +- **2D**: a, b, γ +- **1D**: a -Charge and spin can be given in the ``eht`` data group with +### Charge and Spin ```text $eht charge= unpaired= ``` -The format is identified by ``coord`` or ``tmol`` extension or by using ``coord`` -as basename. +## Examples -## Example +### Molecular System -Caffeine molecule in Turbomole's coord format +Caffeine molecule: ```text $coord @@ -102,6 +102,8 @@ $coord $end ``` +### 3D Periodic System + Ammonia molecular crystal: ```text @@ -132,18 +134,17 @@ $end ## Extensions -The original format does only allow for the ``periodic`` or ``eht`` group to -appear in the ``control`` file, to make the format self-contained, all groups -must appear in the same file. +This implementation extends the original Turbomole format: -The ``coord`` group only supports the ``frac`` modifier in Turbomole, but this -reader also allows ``angs`` and ``bohr``. +- All data groups can appear in the same file (original format requires some groups in separate `control` file) +- The `$coord` group supports `angs` and `bohr` modifiers (original only supports `frac`) -## Missing Features +## Limitations The following features are currently not supported: -- Preserving information about frozen atoms from ``coord`` data group +- Preserving information about frozen atoms from `$coord` data group @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/format-vasp.md b/doc/format-vasp.md index a494dce8..f300b0ba 100644 --- a/doc/format-vasp.md +++ b/doc/format-vasp.md @@ -1,43 +1,45 @@ --- -title: Vasp's POSCAR format +title: VASP POSCAR Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.vasp`, `.poscar`, `.contcar` | +| Coordinate units | Ångström or fractional (direct) | +| Supports periodicity | Yes (required) | +| Supports bonds | No | +| Format hint | `vasp` | + +## Specification + @Note [Reference](https://www.vasp.at/wiki/index.php/POSCAR) -The format is identified by the extension ``vasp``, ``poscar`` or ``contcar``. -Alternatively, the basenames ``poscar`` and ``contcar`` identify the format as well. +POSCAR is the standard geometry input format for the Vienna Ab initio Simulation Package (VASP). +The format supports both Cartesian and fractional (direct) coordinates. -## Examples +### Format Detection -Ammonia molecular crystal in pre Vasp 5 POSCAR format: +The format is identified by: +- File extension: `.vasp`, `.poscar`, `.contcar` +- Basename: `POSCAR`, `CONTCAR` (case-insensitive) -```text - H N - 1.0000000000000000 - 5.0133599999999996 0.0000000000000000 0.0000000000000000 - 0.0000000000000000 5.0133599999999996 0.0000000000000000 - 0.0000000000000000 0.0000000000000000 5.0133599999999996 - 12 4 -Cartesian - 2.1985588943999996 1.7639005823999998 0.8801454815999999 - 1.7639005823999998 0.8801454815999999 2.1985588943999996 - 0.8801454815999999 2.1985588943999996 1.7639005823999998 - 4.8411510839999998 1.6194155471999998 4.9398140088000000 - 4.3563090384000001 2.4998116967999997 3.6324801215999996 - 3.5195792543999995 1.1535741359999998 4.0840334567999994 - 4.0840334567999994 3.5195792543999995 1.1535741359999998 - 4.9398140088000000 4.8411510839999998 1.6194155471999998 - 3.6324801215999996 4.3563090384000001 2.4998116967999997 - 2.4998116967999997 3.6324801215999996 4.3563090384000001 - 1.1535741359999998 4.0840334567999994 3.5195792543999995 - 1.6194155471999998 4.9398140088000000 4.8411510839999998 - 1.3746131783999997 1.3746131783999997 1.3746131783999997 - 3.9981545999999994 1.9910559239999999 4.4636450759999997 - 4.4636450759999997 3.9981545999999994 1.9910559239999999 - 1.9910559239999999 4.4636450759999997 3.9981545999999994 -``` +### Format Structure + +1. **Line 1**: Comment line (may contain element symbols in pre-VASP 5 format) +2. **Line 2**: Scaling factor +3. **Lines 3-5**: Lattice vectors (3×3 matrix) +4. **Line 6**: Element symbols (VASP 5+ format) or atom counts (pre-VASP 5) +5. **Line 7**: Number of atoms per element (VASP 5+) or coordinate type (pre-VASP 5) +6. **Line 8**: Coordinate type (`Cartesian` or `Direct`) +7. **Remaining lines**: Atomic coordinates -Carbondioxide in POSCAR format: +## Examples + +### VASP 5 Format + +Carbondioxide molecular crystal: ```text 4CO2 @@ -62,12 +64,39 @@ Cartesian 1.63121749440000 3.04345865280000 4.40230480320000 ``` -## Extensions +### Pre-VASP 5 Format + +Ammonia molecular crystal (element symbols in comment line): -No extension implemented to the original format. +```text + H N + 1.0000000000000000 + 5.0133599999999996 0.0000000000000000 0.0000000000000000 + 0.0000000000000000 5.0133599999999996 0.0000000000000000 + 0.0000000000000000 0.0000000000000000 5.0133599999999996 + 12 4 +Cartesian + 2.1985588943999996 1.7639005823999998 0.8801454815999999 + 1.7639005823999998 0.8801454815999999 2.1985588943999996 + 0.8801454815999999 2.1985588943999996 1.7639005823999998 + 4.8411510839999998 1.6194155471999998 4.9398140088000000 + 4.3563090384000001 2.4998116967999997 3.6324801215999996 + 3.5195792543999995 1.1535741359999998 4.0840334567999994 + 4.0840334567999994 3.5195792543999995 1.1535741359999998 + 4.9398140088000000 4.8411510839999998 1.6194155471999998 + 3.6324801215999996 4.3563090384000001 2.4998116967999997 + 2.4998116967999997 3.6324801215999996 4.3563090384000001 + 1.1535741359999998 4.0840334567999994 3.5195792543999995 + 1.6194155471999998 4.9398140088000000 4.8411510839999998 + 1.3746131783999997 1.3746131783999997 1.3746131783999997 + 3.9981545999999994 1.9910559239999999 4.4636450759999997 + 4.4636450759999997 3.9981545999999994 1.9910559239999999 + 1.9910559239999999 4.4636450759999997 3.9981545999999994 +``` -## Missing Features +## Limitations The implementation of this format is (to our knowledge) feature-complete. @Note Feel free to bring missing features to our attention by opening an issue. + diff --git a/doc/format-xyz.md b/doc/format-xyz.md index 9c153f99..622e468a 100644 --- a/doc/format-xyz.md +++ b/doc/format-xyz.md @@ -1,27 +1,34 @@ --- -title: xyz format +title: XYZ Format --- +## Overview + +| Property | Value | +|----------|-------| +| File extensions | `.xyz`, `.log` | +| Coordinate units | Ångström | +| Supports periodicity | No | +| Supports bonds | No | +| Format hint | `xyz` | + ## Specification @Note [Reference](http://www.ccl.net/chemistry/resources/messages/1996/10/21.005-dir/index.html) -Simple format to store cartesian coordinates and element symbols. -The first line contains the number of atoms in the geometry. -The second line is a comment line and ignored, some program store additional -information here. -The following lines contain a short character identifier and three reals. -The first entry is interpreted as element symbol and defines the atomic species. -The atomic coordinates are given in Ångström. +The xyz format is a simple ASCII format for storing Cartesian coordinates and element symbols. -A scalar quantity can be added to each atom with one real as well as a vector -quantity by three reals, allowing additional four reals per atomic entry. +**File structure:** -The format is identified by the file extension ``xyz`` or ``log``. +1. **Line 1**: Number of atoms (integer) +2. **Line 2**: Comment line (can be empty, often contains title or energy) +3. **Lines 3+**: Element symbol followed by three coordinates (x, y, z) -## Examples +Coordinates are given in Ångström and are internally converted to Bohr. -Caffeine molecule in xyz format +## Example + +Caffeine molecule in xyz format: ```text 24 @@ -54,17 +61,18 @@ H 4.40017000000000 -5.16929000000000 -0.94780000000000 ## Extensions -The reader supports the following extensions: +The reader supports the following extensions beyond the standard format: -- Atomic numbers are allowed instead of element symbols. - They are automatically converted to capitalized element symbols +- **Atomic numbers**: Integer atomic numbers are accepted instead of element symbols + and are automatically converted to capitalized element symbols -## Missing Features +## Limitations The following features are currently not supported: -- Scalar atomic quantities are not preserved and dropped. -- Vector atomic quantities are not preserved and dropped. +- Scalar atomic quantities (4th column) are not preserved and dropped +- Vector atomic quantities (columns 5-7) are not preserved and dropped @Note Feel free to contribute support for missing features or bring missing features to our attention by opening an issue. + diff --git a/doc/index.md b/doc/index.md index 05ffbeef..6414d87d 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,18 +1,36 @@ --- -title: Formats +title: Supported Geometry Formats --- -This library supports reading and writing of the following formats: - -- [xyz with extensions](./format-xyz.html) -- [Turbomole's coord](./format-tmol.html) -- [connection table files: molfile, structure data format](./format-ctfile.html) -- [Vasp's POSCAR format](./format-vasp.html) -- [a subset of PDB format](./format-pdb.html) -- [DFTB+ general format](./format-gen.html) -- [Gaussian external format](./format-ein.html) -- [Chemical JSON format](./format-cjson.html) -- [QCSchema JSON format](./format-qcschema.html) -- [Pymatgen JSON format](./format-pymatgen.html) -- [FHI-aims geometry.in](./format-aims.html) -- [Q-Chem molecule format](./format-qchem.html) +This library supports reading and writing molecular structures in the following formats. +All formats can be auto-detected by file extension or explicitly specified using the `filetype` enumerator. + +## General ASCII Formats + +- [xyz format](./format-xyz.html) - Simple Cartesian coordinate format (`.xyz`, `.log`) +- [Connection table files](./format-ctfile.html) - MDL molfile and SDF formats (`.mol`, `.sdf`) +- [Protein Data Bank](./format-pdb.html) - PDB format for biomolecules (`.pdb`) + +## JSON-based Formats + +- [QCSchema JSON](./format-qcschema.html) - MolSSI QCSchema format (`.qcjson`, `.json`) +- [Chemical JSON](./format-cjson.html) - Avogadro Chemical JSON (`.cjson`, `.json`) +- [Pymatgen JSON](./format-pymatgen.html) - Pymatgen Molecule/Structure (`.pmgjson`, `.json`) + +## Program-specific Formats + +- [Turbomole coord](./format-tmol.html) - Turbomole/riper coordinate format (`.tmol`, `.coord`) +- [VASP POSCAR](./format-vasp.html) - VASP geometry input (`.vasp`, `.poscar`, `.contcar`) +- [DFTB+ gen format](./format-gen.html) - DFTB+ general format (`.gen`) +- [Gaussian external](./format-ein.html) - Gaussian external program input (`.ein`) +- [FHI-aims geometry.in](./format-aims.html) - FHI-aims input format (`geometry.in`) +- [Q-Chem molecule](./format-qchem.html) - Q-Chem molecule block (`.qchem`) + +## Format Detection + +File formats are detected automatically based on: + +1. File extension (e.g., `.xyz`, `.mol`, `.vasp`) +2. Basename (e.g., `coord`, `POSCAR`, `CONTCAR`, `geometry.in`) + +When automatic detection is not possible (e.g., reading from stdin), use the format hint options in `mctc-convert` or the `filetype` enumerator in the library API. diff --git a/docs.md b/docs.md index 2feeca85..a19edd8d 100644 --- a/docs.md +++ b/docs.md @@ -22,86 +22,285 @@ md_extensions: markdown.extensions.toc markdown.extensions.smarty --- -Common tool chain for working with molecular structure data in various applications. -This library provides a unified way to perform operations on molecular structure data, like reading and writing to common geometry file formats. +API documentation for the modular computation tool chain library. +For installation instructions and getting started, see the [README](https://github.com/grimme-lab/mctc-lib). [TOC] +## Module Overview + +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 | + +### Units Convention + +All quantities in mctc-lib use **atomic units**: + +- Coordinates and radii are in **Bohr** (1 Bohr = 0.529177 Å) +- Energies are in **Hartree** (where applicable) + +The [[mctc_io_convert]] module provides conversion factors derived from CODATA constants: + +```f90 +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 | + + +## Structure Representation + +The [[structure_type]] is the central data structure for molecular and periodic systems. + +### Key Components + +| 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 | + +### Creating Structures + +Use [[new]] for programmatic construction: + +```f90 +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.]) +``` + + ## Input and Output -The IO module ([[mctc_io]]) provides access to a common type to declare molecular structure data ([[structure_type]]). -Also, reader routines ([[mctc_io_read]]) to obtain [[structure_type]] objects from input files are available. -To write a [[structure_type]] object a set of writer routines are available as well ([[mctc_io_write]]). +The [[mctc_io]] module provides format-agnostic structure I/O. +### Reading Structures -## Standard environment +Use [[read_structure]] to read from files: -The tool chain library provides an environment module ([[mctc_env]]) to allow the usage of common constants across different users. -For a minimal error handling the [[error_type]] is available and should be passed as allocatable type to the library procedures. -The allocation status of the [[error_type]] is used to determine failed executions and the respective error message is stored transparently in the [[error_type]]. +```f90 +use mctc_io +use mctc_env +type(structure_type) :: mol +type(error_type), allocatable :: error -## Light testing framework +! Auto-detect format from extension +call read_structure(mol, "input.xyz", error) -Additionally, the environment module provides a testsuite implementation to setup a slim and light testing framework in dependent applications. -The test framework can be easily setup by the [[mctc_env_testing]] module. +! Explicit format specification +call read_structure(mol, "input.dat", error, filetype%xyz) +``` +### Writing Structures -## Getting Started +Use [[write_structure]] to write to files: -### Meson +```f90 +! Auto-detect format +call write_structure(mol, "output.mol", error) -Create a new meson project and include `mctc-lib` either as git-submodule in your subprojects directory or create a wrap file to fetch it from upstream: +! Explicit format +call write_structure(mol, "output.dat", error, filetype%gen) +``` -```ini -[wrap-git] -directory = mctc-lib -url = https://github.com/grimme-lab/mctc-lib -revision = head +### Format Detection + +The [[filetype]] enumerator identifies supported formats: + +```f90 +use mctc_io, only : filetype, get_filetype + +integer :: ftype +ftype = get_filetype("molecule.xyz") ! Returns filetype%xyz ``` -To load the project the necessary boilerplate code for subprojects is just +See the [format documentation](./page/index.html) for details on each format. - -```python -mctc_prj = subproject( - 'mctc-lib', - version: '>=0.1', - default_options: [ - 'default_library=static', - ], -) -mctc_dep = mctc_prj.get_variable('mctc_dep') + +## Error Handling + +The [[mctc_env]] module provides the [[error_type]] for error propagation. + +### Error Pattern + +```f90 +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 +``` + +### Creating Errors + +Use [[fatal_error]] in your own routines: + +```f90 +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 ``` -Now you can add `mctc_dep` to your dependencies and access the public API by the `mctc` module. -We recommend to set the default library type of `mctc-lib` to static when linking your applications or library against it. -Note for library type both and shared `mctc-lib` will install itself along with your project. +## Element Data -For more fine-tuned control you can access: +The [[mctc_data]] module provides element-specific data. +All radii are returned in **Bohr**. -- the library target with `mctc_lib` -- the private include dir of this target, containing the Fortran module files, with `mctc_inc` -- the license files of `mctc-lib` with `mctc_lic` +### Available Functions -If you are linking your application statically against `mctc-lib` and still want to distribute the license files of `mctc-lib` (thank you), just use +| Function | Description | +|----------|-------------| +| [[get_covalent_rad]] | Covalent radii | +| [[get_vdw_rad]] | van der Waals radii | +| [[get_atomic_rad]] | Atomic radii | +| [[get_pauling_en]] | Pauling electronegativities | -```python -install_data( - mctc_prj.get_variable('mctc_lic'), - install_dir: get_option('datadir')/'licenses'/meson.project_name()/'mctc-lib', -) +### Usage + +```f90 +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) +``` + + +## Coordination Numbers + +The [[mctc_ncoord]] module provides coordination number evaluators. + +### Counting Functions + +The [[cn_count]] enumerator selects the counting function: + +| Function | Description | Typical Use | +|----------|-------------|-------------| +| `cn_count%exp` | Exponential | General purpose | +| `cn_count%dexp` | Double-exponential | Sharper cutoff | +| `cn_count%erf` | Error function | GFN methods | +| `cn_count%erf_en` | EN-weighted error function | Electronegativity corrections | +| `cn_count%dftd4` | DFT-D4 error function | Dispersion corrections | + +### Usage + +```f90 +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) ``` -### Fortran Package Manager (fpm) +## Symbol Conversion + +Convert between element symbols and atomic numbers: -This project supports [fpm](https://github.com/fortran-lang/fpm) as build system as well. -Just add it to the dependencies in your `fpm.toml` file: +```f90 +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 +``` + + +## Integration Guide + +### As Meson Subproject + +Add to `subprojects/mctc-lib.wrap`: + +```ini +[wrap-git] +directory = mctc-lib +url = https://github.com/grimme-lab/mctc-lib +revision = head +``` + +In `meson.build`: + +```python +mctc_dep = dependency('mctc-lib', fallback: ['mctc-lib', 'mctc_dep']) +``` + +### As fpm Dependency + +In `fpm.toml`: ```toml -[dependencies] [dependencies.mctc-lib] git = "https://github.com/grimme-lab/mctc-lib" ``` + diff --git a/man/mctc-convert.1.adoc b/man/mctc-convert.1.adoc index 8847cc25..35ea007b 100644 --- a/man/mctc-convert.1.adoc +++ b/man/mctc-convert.1.adoc @@ -2,63 +2,198 @@ :doctype: manpage == Name -mctc-convert - Convert between supported input formats of the tool chain library +mctc-convert - Convert between supported geometry file formats == Synopsis *mctc-convert* [_options_] _input_ _output_ +*mctc-convert* *--help* + +*mctc-convert* *--version* + == Description -Read structure from input file and writes it to output file. -The format is determined by the file extension or the format hint. -The input structure can be read from standard input by providing - as argument. -Similarly, the output structure can be written to standard output with - as argument. -Standard input and standard output should be combined with a format hint option. +The *mctc-convert* program reads molecular structure data from an input file and writes it to an output file, optionally converting between different geometry file formats. +The format is automatically determined by the file extension, or can be explicitly specified using format hint options. + +The program supports reading from standard input and writing to standard output by using `-` as the file argument. +When using standard input/output, a format hint option should be provided. + + +== Supported Formats + +The following geometry formats are supported for both reading and writing: + +[cols="1,3,2"] +|=== +|Format hint |Description |File extensions + +|xyz +|Xmol/xyz coordinate files +|.xyz, .log + +|tmol, coord +|Turbomole coord files (including periodic/riper) +|.tmol, .coord + +|gen +|DFTB+ genFormat (cluster, supercell, fractional) +|.gen + +|vasp, poscar, contcar +|VASP POSCAR/CONTCAR geometry files +|.vasp, .poscar, .contcar + +|pdb +|Protein Data Bank files (single structures only) +|.pdb -Supported formats: +|mol +|MDL Molfile connection table +|.mol -- Xmol/xyz files (xyz, log) -- Turbomole's coord, riper's periodic coord (tmol, coord) -- DFTB+ genFormat geometry inputs as cluster, supercell or fractional (gen) -- VASP's POSCAR/CONTCAR input files (vasp, poscar, contcar) -- Protein Database files, only single files (pdb) -- Connection table files, molfile (mol) and structure data format (sdf) -- Gaussian's external program input (ein) -- JSON input with `qcschema_molecule` or `qcschema_input` structure (qcjson, json) -- Chemical JSON input (cjson, json) -- Pymatgen JSON with `Molecule` or `Structure` schema (pmgjson, json) -- FHI-AIMS' input files (geometry.in) -- Q-Chem molecule block inputs (qchem) +|sdf +|MDL Structure Data Format +|.sdf + +|ein +|Gaussian external program input +|.ein + +|qcjson, json +|QCSchema JSON (`qcschema_molecule` or `qcschema_input`) +|.qcjson, .json + +|cjson, json +|Chemical JSON (Avogadro) +|.cjson, .json + +|pmgjson, json +|Pymatgen JSON (`Molecule` or `Structure` schema) +|.pmgjson, .json + +|aims +|FHI-aims geometry input +|geometry.in + +|qchem +|Q-Chem molecule block +|.qchem +|=== + +NOTE: JSON format support requires mctc-lib to be compiled with the jonquil dependency. == Options *-i, --input* _format_:: -Hint for the format of the input file +Specify the format of the input file. +Use this option when the input file has a non-standard extension or when reading from standard input. +See <> for valid format hints. *-o, --output* _format_:: -Hint for the format of the output file +Specify the format of the output file. +Use this option when the output file should have a non-standard extension or when writing to standard output. +See <> for valid format hints. *--normalize*:: -Normalize all element symbols to capitalized format +Normalize all element symbols to standard capitalized format (e.g., "CL" becomes "Cl", "h" becomes "H"). +Useful when working with files that have non-standard element symbol casing. *--template* _file_:: -File to use as template to fill in meta data (useful to add back SDF or PDB annotions). -Transfers lattice, periodicity, comments and format specific annotations from the template -to the input structure. -If the standard input, -, is provided the template structure will -be read _before_ the input structure. +Use the specified file as a template to transfer metadata to the output. +This option transfers lattice parameters, periodicity information, comments, and format-specific annotations (such as PDB residue information or SDF bond data) from the template to the input structure. +The input and template structures must have the same number of atoms. ++ +If `-` is provided as the template file, the template structure is read from standard input _before_ the input structure. *--template-format* _format_:: -Hint for the format of the template file (only used if template file name is provided) +Specify the format of the template file. +Only used when a template file is provided via *--template*. *--ignore-dot-files*:: -Do not read charge and spin from .CHRG and .UHF files +Do not read molecular charge from `.CHRG` files or spin state from `.UHF` files in the input file's directory. +By default, these files are read if present. *--version*:: -Print program version and exit +Print the program version and exit. *--help*:: -Show this help message +Display a brief help message and exit. + + +== Examples + +Convert an xyz file to Turbomole coord format:: ++ +---- +mctc-convert molecule.xyz molecule.coord +---- + +Convert a VASP POSCAR to xyz format:: ++ +---- +mctc-convert POSCAR structure.xyz +---- + +Read from standard input and write to standard output:: ++ +---- +cat molecule.xyz | mctc-convert -i xyz -o mol - - +---- + +Convert format while preserving SDF bond information:: ++ +---- +mctc-convert optimized.xyz final.sdf --template original.sdf +---- + +Normalize element symbols during conversion:: ++ +---- +mctc-convert --normalize input.xyz output.xyz +---- + +Force input format for non-standard extension:: ++ +---- +mctc-convert -i xyz geometry.dat output.mol +---- + + +== Environment + +*.CHRG*:: +If a file named `.CHRG` exists in the same directory as the input file, the molecular charge is read from it (unless *--ignore-dot-files* is specified). + +*.UHF*:: +If a file named `.UHF` exists in the same directory as the input file, the number of unpaired electrons is read from it (unless *--ignore-dot-files* is specified). + + +== Exit Status + +*0*:: +Success. + +*non-zero*:: +An error occurred during file reading, writing, or conversion. +Error messages are written to standard error with source location information when available. + + +== See Also + +The mctc-lib API documentation: https://grimme-lab.github.io/mctc-lib + + +== Authors + +mctc-lib is developed by the Grimme group at the University of Bonn. +See https://github.com/grimme-lab/mctc-lib/graphs/contributors for a list of all contributors. + + +== Reporting Bugs + +Report bugs and unclear error messages at: https://github.com/grimme-lab/mctc-lib/issues + diff --git a/src/mctc/data.f90 b/src/mctc/data.f90 index ac671c92..f3482e2a 100644 --- a/src/mctc/data.f90 +++ b/src/mctc/data.f90 @@ -18,7 +18,28 @@ !> @file mctc/data.f90 !> Reexports access to element-specific data. -!> Proxy module for providing access to element data. +!> Element data module providing atomic properties. +!> +!> This module provides access to element-specific data indexed by atomic number. +!> All radii are returned in atomic units (Bohr). +!> +!> Available functions: +!> +!> - [[get_covalent_rad]]: Covalent radii in Bohr +!> - [[get_vdw_rad]]: van der Waals radii in Bohr +!> - [[get_atomic_rad]]: Atomic radii in Bohr +!> - [[get_pauling_en]]: Pauling electronegativities +!> +!> Example usage: +!> +!>```f90 +!> use mctc_data +!> use mctc_env, only : wp +!> real(wp) :: radius +!> +!> ! Get covalent radius for carbon (Z=6) +!> radius = get_covalent_rad(6) +!>``` module mctc_data use mctc_data_atomicrad, only : get_atomic_rad use mctc_data_covrad, only : get_covalent_rad diff --git a/src/mctc/env.f90 b/src/mctc/env.f90 index 5be861c2..5e4d047e 100644 --- a/src/mctc/env.f90 +++ b/src/mctc/env.f90 @@ -12,7 +12,31 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> Public API reexport of environment library +!> Environment module providing common utilities and error handling. +!> +!> This module exports fundamental types and constants used throughout mctc-lib: +!> +!> - [[error_type]]: Allocatable error type for error propagation +!> - [[fatal_error]]: Subroutine to create error messages +!> - [[wp]]: Working precision for real numbers (double precision) +!> - [[sp]], [[dp]]: Single and double precision kind parameters +!> - [[i1]], [[i2]], [[i4]], [[i8]]: Integer kind parameters (1, 2, 4, 8 bytes) +!> +!> Error handling follows a simple pattern: pass an allocatable [[error_type]] +!> to library routines, then check if it is allocated to detect errors. +!> +!> Example usage: +!> +!>```f90 +!> use mctc_env +!> type(error_type), allocatable :: error +!> +!> call some_routine(result, error) +!> if (allocated(error)) then +!> print '(a)', error%message +!> error stop +!> end if +!>``` module mctc_env use mctc_env_accuracy, only : sp, dp, wp, i1, i2, i4, i8 use mctc_env_error, only : error_type, fatal_error, mctc_stat diff --git a/src/mctc/io.f90 b/src/mctc/io.f90 index e2b719cc..edc0639c 100644 --- a/src/mctc/io.f90 +++ b/src/mctc/io.f90 @@ -12,17 +12,38 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> Input and output module of the tool chain library. +!> Input and output module for molecular structure data. !> -!> This module exports the basic [[structure_type]] as well as routines -!> to read it from a file or formatted unit ([[read_structure]]) or write -!> it to a formatted unit ([[write_structure]]). +!> This module provides the main interface for reading and writing molecular +!> structures in various geometry file formats. It exports: !> -!> Both [[read_structure]] and [[write_structure]] take format hints from -!> the filetype enumerator. File names can be translated to the respective -!> enumerator by using the [[get_filetype]] function. This can be useful in -!> case the caller routine wants to open the formatted unit itself or uses -!> a non-standard file extension. +!> - [[structure_type]]: Central data structure for molecular and periodic systems +!> - [[read_structure]]: Read structures from files or formatted units +!> - [[write_structure]]: Write structures to files or formatted units +!> - [[filetype]]: Enumerator for supported file formats +!> - [[to_symbol]] / [[to_number]]: Convert between element symbols and atomic numbers +!> +!> The file format is automatically detected from file extensions, or can be +!> explicitly specified using the [[filetype]] enumerator. Use [[get_filetype]] +!> to translate file names to format identifiers. +!> +!> Supported formats include xyz, mol/sdf, pdb, Turbomole coord, VASP POSCAR, +!> DFTB+ gen, Gaussian external, QCSchema JSON, Chemical JSON, Pymatgen JSON, +!> FHI-aims geometry.in, and Q-Chem molecule blocks. +!> +!> Example usage: +!> +!>```f90 +!> use mctc_io +!> use mctc_env +!> type(structure_type) :: mol +!> type(error_type), allocatable :: error +!> +!> call read_structure(mol, "input.xyz", error) +!> if (allocated(error)) stop error%message +!> +!> call write_structure(mol, "output.mol", error) +!>``` module mctc_io use mctc_io_filetype, only : filetype, get_filetype use mctc_io_read, only : read_structure diff --git a/src/mctc/io/structure.f90 b/src/mctc/io/structure.f90 index f4920247..630f7fcd 100644 --- a/src/mctc/io/structure.f90 +++ b/src/mctc/io/structure.f90 @@ -12,7 +12,23 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> Basic structure representation of the system of interest +!> Molecular structure representation. +!> +!> This module defines [[structure_type]], the central data structure for +!> representing molecular and periodic systems. All quantities are in atomic +!> units (coordinates and lattice vectors in Bohr). +!> +!> Key components of [[structure_type]]: +!> +!> - `nat`: Number of atoms +!> - `xyz(3, nat)`: Cartesian coordinates in Bohr +!> - `num(nid)`: Atomic numbers for each unique species +!> - `id(nat)`: Species index for each atom +!> - `charge`: Total molecular charge +!> - `uhf`: Number of unpaired electrons +!> - `lattice(3, 3)`: Lattice vectors for periodic systems (optional) +!> +!> Use [[new]] or [[new_structure]] to create structure instances. module mctc_io_structure use mctc_env_accuracy, only : wp use mctc_io_symbols, only : to_number, to_symbol, symbol_length, get_identity, & diff --git a/src/mctc/ncoord.f90 b/src/mctc/ncoord.f90 index 60ac97fd..99d6e1ac 100644 --- a/src/mctc/ncoord.f90 +++ b/src/mctc/ncoord.f90 @@ -18,7 +18,36 @@ !> @file mctc/ncoord.f90 !> Reexports the coordination number evaluation modules. -!> Proxy module to expose coordination number containers +!> Coordination number evaluation module. +!> +!> This module provides various coordination number counting functions for +!> molecular structures. Coordination numbers are computed based on interatomic +!> distances and covalent radii using different counting functions. +!> +!> Available counting functions (via [[cn_count]] enumerator): +!> +!> - `cn_count%exp`: Exponential counting function +!> - `cn_count%dexp`: Double-exponential counting function +!> - `cn_count%erf`: Error-function-based counting function +!> - `cn_count%erf_en`: Electronegativity-weighted error function +!> - `cn_count%dftd4`: DFT-D4 error-function-based counting function +!> +!> Use [[new_ncoord]] to create a coordination number evaluator, then call +!> the `get_cn` method to compute coordination numbers for a structure. +!> +!> Example usage: +!> +!>```f90 +!> use mctc_ncoord +!> use mctc_io, only : structure_type +!> use mctc_env, only : wp +!> class(ncoord_type), allocatable :: ncoord +!> real(wp), allocatable :: cn(:) +!> +!> call new_ncoord(ncoord, mol, cn_count%exp, error) +!> allocate(cn(mol%nat)) +!> call ncoord%get_cn(mol, cn) +!>``` module mctc_ncoord use mctc_env, only : error_type, fatal_error, wp use mctc_io, only : structure_type From ad1ad6b09c4456ab28269aef869d454d9f80106d Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Fri, 12 Dec 2025 10:03:59 +0000 Subject: [PATCH 2/3] Declare types in example --- src/mctc/ncoord.f90 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/mctc/ncoord.f90 b/src/mctc/ncoord.f90 index 99d6e1ac..f70804d3 100644 --- a/src/mctc/ncoord.f90 +++ b/src/mctc/ncoord.f90 @@ -40,8 +40,10 @@ !>```f90 !> use mctc_ncoord !> use mctc_io, only : structure_type -!> use mctc_env, only : wp +!> use mctc_env, only : wp, error_type !> class(ncoord_type), allocatable :: ncoord +!> type(structure_type) :: mol +!> type(error_type), allocatable :: error !> real(wp), allocatable :: cn(:) !> !> call new_ncoord(ncoord, mol, cn_count%exp, error) From a51ed6d492b23a05593d183941dc201c2d62717b Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Fri, 12 Dec 2025 11:07:43 +0000 Subject: [PATCH 3/3] Use ford docs config via fpm.toml --- docs.md | 41 ++++------------------------------- fpm.toml | 24 ++++++++++++++++++++ src/mctc/env.f90 | 12 +++++----- src/mctc/io.f90 | 4 ++-- src/mctc/io/filetype.f90 | 20 +++++++++++++++++ src/mctc/ncoord.f90 | 14 +++++++----- src/mctc/ncoord/dexp.f90 | 3 --- src/mctc/ncoord/erf.f90 | 6 ----- src/mctc/ncoord/erf/dftd4.f90 | 3 --- src/mctc/ncoord/erf/en.f90 | 3 --- src/mctc/ncoord/exp.f90 | 3 --- src/mctc/ncoord/type.f90 | 3 --- 12 files changed, 64 insertions(+), 72 deletions(-) diff --git a/docs.md b/docs.md index a19edd8d..f2dc889b 100644 --- a/docs.md +++ b/docs.md @@ -1,27 +1,3 @@ ---- -project: MCTC-library -summary: Modular computation tool chain library -project_github: https://github.com/grimme-lab/mctc-lib -project_download: https://github.com/grimme-lab/mctc-lib/releases -author: Grimme group, Bonn -github: https://github.com/grimme-lab -src_dir: ./src - ./app -output_dir: ./_docs -exclude_dir: ./test -page_dir: ./doc -docmark: < -predocmark: > -source: true -graph: false -sort: alpha -print_creation_date: true -extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html -creation_date: %Y-%m-%d %H:%M %z -md_extensions: markdown.extensions.toc - markdown.extensions.smarty ---- - API documentation for the modular computation tool chain library. For installation instructions and getting started, see the [README](https://github.com/grimme-lab/mctc-lib). @@ -150,7 +126,9 @@ call write_structure(mol, "output.dat", error, filetype%gen) ### Format Detection -The [[filetype]] enumerator identifies supported formats: +Use [[get_filetype]] to determine the file format from a filename, or the +[[mctc_io_filetype:filetype]] enumerator directly when the format is known. +See [[mctc_io_filetype]] for the complete list of supported formats. ```f90 use mctc_io, only : filetype, get_filetype @@ -228,18 +206,7 @@ en = get_pauling_en(6) ## Coordination Numbers The [[mctc_ncoord]] module provides coordination number evaluators. - -### Counting Functions - -The [[cn_count]] enumerator selects the counting function: - -| Function | Description | Typical Use | -|----------|-------------|-------------| -| `cn_count%exp` | Exponential | General purpose | -| `cn_count%dexp` | Double-exponential | Sharper cutoff | -| `cn_count%erf` | Error function | GFN methods | -| `cn_count%erf_en` | EN-weighted error function | Electronegativity corrections | -| `cn_count%dftd4` | DFT-D4 error function | Dispersion corrections | +See the module documentation for the complete list of available counting functions. ### Usage diff --git a/fpm.toml b/fpm.toml index 02bb0702..8d445334 100644 --- a/fpm.toml +++ b/fpm.toml @@ -15,3 +15,27 @@ toml-f.tag = "v0.4.3" [[executable]] name = "mctc-convert" + +[extra.ford] +project = "MCTC-library" +summary = "Modular computation tool chain library" +project_github = "https://github.com/grimme-lab/mctc-lib" +project_download = "https://github.com/grimme-lab/mctc-lib/releases" +author = "Grimme group, Bonn" +github = "https://github.com/grimme-lab" +src_dir = ["./src", "./app"] +output_dir = "./_docs" +exclude_dir = ["./test"] +page_dir = "./doc" +docmark = "<" +predocmark = ">" +source = true +graph = false +sort = "alpha" +print_creation_date = true +creation_date = "%Y-%m-%d %H:%M %z" +md_extensions = ["markdown.extensions.toc", "markdown.extensions.smarty"] + +[extra.ford.extra_mods] +iso_fortran_env = "https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html" +jonquil = "https://toml-f.github.io/jonquil/module/jonquil.html" \ No newline at end of file diff --git a/src/mctc/env.f90 b/src/mctc/env.f90 index 5e4d047e..80c2800c 100644 --- a/src/mctc/env.f90 +++ b/src/mctc/env.f90 @@ -16,13 +16,13 @@ !> !> This module exports fundamental types and constants used throughout mctc-lib: !> -!> - [[error_type]]: Allocatable error type for error propagation -!> - [[fatal_error]]: Subroutine to create error messages -!> - [[wp]]: Working precision for real numbers (double precision) -!> - [[sp]], [[dp]]: Single and double precision kind parameters -!> - [[i1]], [[i2]], [[i4]], [[i8]]: Integer kind parameters (1, 2, 4, 8 bytes) +!> - [[mctc_env_error:error_type]]: Allocatable error type for error propagation +!> - [[mctc_env_error:fatal_error]]: Subroutine to create error messages +!> - [[mctc_env_accuracy:wp]]: Working precision for real numbers (double precision) +!> - [[mctc_env_accuracy:sp]], [[mctc_env_accuracy:dp]]: Single and double precision kind parameters +!> - [[mctc_env_accuracy:i1]], [[mctc_env_accuracy:i2]], [[mctc_env_accuracy:i4]], [[mctc_env_accuracy:i8]]: Integer kind parameters (1, 2, 4, 8 bytes) !> -!> Error handling follows a simple pattern: pass an allocatable [[error_type]] +!> Error handling follows a simple pattern: pass an allocatable [[mctc_env_error:error_type]] !> to library routines, then check if it is allocated to detect errors. !> !> Example usage: diff --git a/src/mctc/io.f90 b/src/mctc/io.f90 index edc0639c..d5014f6f 100644 --- a/src/mctc/io.f90 +++ b/src/mctc/io.f90 @@ -20,11 +20,11 @@ !> - [[structure_type]]: Central data structure for molecular and periodic systems !> - [[read_structure]]: Read structures from files or formatted units !> - [[write_structure]]: Write structures to files or formatted units -!> - [[filetype]]: Enumerator for supported file formats +!> - [[mctc_io_filetype:filetype]]: Enumerator for supported file formats !> - [[to_symbol]] / [[to_number]]: Convert between element symbols and atomic numbers !> !> The file format is automatically detected from file extensions, or can be -!> explicitly specified using the [[filetype]] enumerator. Use [[get_filetype]] +!> explicitly specified using the [[mctc_io_filetype:filetype]] enumerator. Use [[get_filetype]] !> to translate file names to format identifiers. !> !> Supported formats include xyz, mol/sdf, pdb, Turbomole coord, VASP POSCAR, diff --git a/src/mctc/io/filetype.f90 b/src/mctc/io/filetype.f90 index 10d64adf..5ca37e3e 100644 --- a/src/mctc/io/filetype.f90 +++ b/src/mctc/io/filetype.f90 @@ -13,6 +13,10 @@ ! limitations under the License. !> File type support +!> +!> This module provides file type identification for molecular structure files. +!> Use [[get_filetype]] to determine the format from a filename, or use the +!> [[mctc_io_filetype:filetype]] enumerator directly when the format is known. module mctc_io_filetype use mctc_io_utils, only : to_lower implicit none @@ -72,6 +76,22 @@ module mctc_io_filetype end type enum_filetype !> File type enumerator + !> + !> | Enumerator | Format | Description | + !> |------------|--------|-------------| + !> | `filetype%xyz` | xyz | Xmol/xyz format | + !> | `filetype%tmol` | Turbomole | Turbomole coord format | + !> | `filetype%molfile` | MOL | MDL Molfile V2000/V3000 | + !> | `filetype%sdf` | SDF | Structure Data File | + !> | `filetype%vasp` | VASP | POSCAR/CONTCAR format | + !> | `filetype%pdb` | PDB | Protein Data Bank format | + !> | `filetype%gen` | gen | DFTB+ genFormat | + !> | `filetype%gaussian` | Gaussian | External program format | + !> | `filetype%qcschema` | QCSchema | MolSSI QCSchema JSON | + !> | `filetype%cjson` | Chemical JSON | Avogadro Chemical JSON | + !> | `filetype%pymatgen` | Pymatgen | Pymatgen JSON format | + !> | `filetype%aims` | FHI-aims | geometry.in format | + !> | `filetype%qchem` | Q-Chem | Molecule block format | type(enum_filetype), parameter :: filetype = enum_filetype() diff --git a/src/mctc/ncoord.f90 b/src/mctc/ncoord.f90 index f70804d3..93e6ce2c 100644 --- a/src/mctc/ncoord.f90 +++ b/src/mctc/ncoord.f90 @@ -12,12 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @dir mctc/ncoord -!> Contains the implementation for the coordination number evaluators. - -!> @file mctc/ncoord.f90 -!> Reexports the coordination number evaluation modules. - !> Coordination number evaluation module. !> !> This module provides various coordination number counting functions for @@ -86,6 +80,14 @@ module mctc_ncoord end type enum_cn_count !> Actual enumerator possible coordination numbers + !> + !> | Enumerator | Description | Typical Use | + !> |------------|-------------|-------------| + !> | `cn_count%exp` | Exponential counting function | General purpose | + !> | `cn_count%dexp` | Double-exponential counting function | Sharper cutoff | + !> | `cn_count%erf` | Error-function-based counting | GFN methods | + !> | `cn_count%erf_en` | Electronegativity-weighted error function | EN corrections | + !> | `cn_count%dftd4` | DFT-D4 error-function-based counting | Dispersion corrections | type(enum_cn_count), parameter :: cn_count = enum_cn_count() contains diff --git a/src/mctc/ncoord/dexp.f90 b/src/mctc/ncoord/dexp.f90 index e95fafd7..307e8489 100644 --- a/src/mctc/ncoord/dexp.f90 +++ b/src/mctc/ncoord/dexp.f90 @@ -12,9 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @file mctc/ncoord/dexp.f90 -!> Provides a coordination number implementation with double exponential counting function - !> Coordination number implementation using a double exponential counting function as in GFN2-xTB module mctc_ncoord_dexp use mctc_env, only : wp diff --git a/src/mctc/ncoord/erf.f90 b/src/mctc/ncoord/erf.f90 index c2a1f500..5ea3c2c4 100644 --- a/src/mctc/ncoord/erf.f90 +++ b/src/mctc/ncoord/erf.f90 @@ -12,12 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @dir mctc/ncoord/erf -!> Provides variations (EN) of the error function based coordination number - -!> @file mctc/ncoord/erf.f90 -!> Provides error function based coordination number - !> Coordination number implementation with single error function module mctc_ncoord_erf use mctc_env, only : wp diff --git a/src/mctc/ncoord/erf/dftd4.f90 b/src/mctc/ncoord/erf/dftd4.f90 index aa71079e..830098d3 100644 --- a/src/mctc/ncoord/erf/dftd4.f90 +++ b/src/mctc/ncoord/erf/dftd4.f90 @@ -12,9 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @file mctc/ncoord/erf_en.f90 -!> Provides an implementation for the CN as used dftd4 - !> Coordination number implementation with single error function and EN-weighting for dftd4 module mctc_ncoord_erf_dftd4 use mctc_env, only : wp diff --git a/src/mctc/ncoord/erf/en.f90 b/src/mctc/ncoord/erf/en.f90 index 9c36e8b8..80d2ea15 100644 --- a/src/mctc/ncoord/erf/en.f90 +++ b/src/mctc/ncoord/erf/en.f90 @@ -12,9 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @file mctc/ncoord/erf/en.f90 -!> Provides an implementation for the electronegativity-weighted CN - !> Coordination number implementation with single error function and EN-weighting. module mctc_ncoord_erf_en use mctc_env, only : wp diff --git a/src/mctc/ncoord/exp.f90 b/src/mctc/ncoord/exp.f90 index 0436bc7b..c41db684 100644 --- a/src/mctc/ncoord/exp.f90 +++ b/src/mctc/ncoord/exp.f90 @@ -12,9 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @file mctc/ncoord/exp.f90 -!> Provides a coordination number implementation with exponential counting function - !> Coordination number implementation using an exponential counting function as in dftd3. module mctc_ncoord_exp use mctc_env, only : wp diff --git a/src/mctc/ncoord/type.f90 b/src/mctc/ncoord/type.f90 index 272a08f5..38eb682e 100644 --- a/src/mctc/ncoord/type.f90 +++ b/src/mctc/ncoord/type.f90 @@ -12,9 +12,6 @@ ! See the License for the specific language governing permissions and ! limitations under the License. -!> @file mctc/ncoord/type.f90 -!> Provides a coordination number evalulator base class - !> Declaration of base class for coordination number evalulations module mctc_ncoord_type use mctc_env, only : wp