Input file

When Quoll is run as an app (quoll <input_file.toml>), its behaviour is driven entirely by a TOML input file. This page documents every section and key that is currently wired into the pipeline. An example covering the most common options is included in the repository at input_file.toml.

Top-level structure

[input]              # required — what to read
[output]             # required — what to write
[kpoint_grid]        # optional — k-point grid used by projection
[basis_projection]   # optional — core-orbital projection
[symmetry]           # optional — symmetry options passed to k-grid construction

[input]

Describes the data Quoll should read.

Format names

The format string is case- and whitespace-insensitive. Internally it resolves to a metadata type via get_readformat(Val(:...)) — see src/operators/ for the mapping.

Directory

Each directory is used as a root from which Quoll finds every leaf subdirectory (directories that don't contain further directories). Each leaf is treated as one atomic configuration. This lets you point Quoll at a tree of many calculations and have it process all of them in one run.

If multiple root directories are supplied, the output tree for each root is placed under a subdirectory named after the root's basename, so individual trees stay separate.

Operators

The operators key accepts shorthand strings that expand to one or more OperatorKinds. The most useful strings are:

For bespoke selections, extend the get_operatorkinds dispatch table.

Radii

When provided, each entry has the shape "<species> <radius> <unit>", e.g. "Au 5.0 ang" or "C 3.0 bohr". Two species interact if the distance between their atoms is at most r₁ + r₂. If radii is omitted, the sparsity pattern is taken directly from the input operator data.

[output]

Describes the data Quoll should write.

If hermitian is omitted, Quoll uses the input's own hermicity. Most DeepH-based training pipelines want hermitian = false.

[kpoint_grid]

Controls construction of the k-point grid used by core projection (and, in future, by postprocessing). Has effect only when an operation that needs a grid is requested.

Supplying kpoints disables mesh, density and shift. When kpoints is a file path, the file is read with readdlm — one k-point per line.

For non-periodic systems Quoll always uses a trivial single-Γ-point grid, so the options above are ignored.

[basis_projection]

Turns on core-orbital projection (see the MACE-H / DeepH-E3 tutorial for background). Omit the section to skip projection entirely.

Basis syntax

Each string has the shape:

<species> (<n>, <l>, <m>) [key = value ...]

• <species> is the chemical element symbol (e.g. Au, O, H).
• <n>, <l> are integer principal and angular-momentum quantum numbers.
• <m> is either an integer magnetic quantum number or * to include all 2l + 1 components.
• Any number of key = value tags may follow, used to disambiguate multiple subblocks that share the same (n, l, m). For FHI-aims data, type is the most common — the available types are those that appear in basis-indices.out (e.g. atomic, hydro, ionic).

Example (gold; all core + semicore orbitals):

projected_basis = [
    "Au (1, 0, 0) type = atomic",
    "Au (2, 0, 0) type = atomic",
    "Au (3, 0, 0) type = atomic",
    "Au (4, 0, 0) type = atomic",
    "Au (5, 0, 0) type = atomic",
    "Au (2, 1, *) type = atomic",
    "Au (3, 1, *) type = atomic",
    "Au (4, 1, *) type = atomic",
    "Au (5, 1, *) type = atomic",
    "Au (3, 2, *) type = atomic",
    "Au (4, 2, *) type = atomic",
    "Au (4, 3, *) type = atomic",
]

Requirements

Core projection requires an Overlap(source=:ref) among the input operators.

[symmetry]

Tweaks the symmetry reduction used when building the k-point grid.

Quoll makes conservative automatic choices: spin-polarised operators turn off the symmetries, and basis-projection turns off crystal symmetry (which the projection code does not currently handle). You can force either on by setting the corresponding key explicitly — but see src/parser/methods.jl for the cases where the parser will refuse.