Improve documentation

Author: awvwgk

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”);

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.
+

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.
+