Dependencies and Legal Notice

DELFIN is an open-source, AI-orchestrated computational chemistry platform for automated molecular property prediction and inverse molecular design. Behind a single SMILES-in / property-out interface, it connects structure generation, quantum-chemistry workflows, machine-learning potentials, interactive dashboards, automated reports, and AI agents into one practical research platform.

DELFIN is operated by AI agents. They configure and submit calculations, monitor them, interpret the outputs, and modify DELFIN's own code where a workflow has to be extended. Work that stands on its own is delegated to subagents running in parallel, each with its own tools and permissions.

Hosted models (Claude, OpenAI, KIT Toolbox) and local open-source models (Ollama, vLLM, LM Studio) are supported alike. With a local model server the model calls stay on your own hardware; what else reaches the network, and how to run without outside access, is listed under Network access and offline use. The agents' shell commands run under bubblewrap or Landlock on Linux, or Seatbelt on macOS, where the host supports one of them; on a host where none works they are not confined, and DELFIN says so at start (Tools, MCP and safety). Their permissions are explicit, and what they may do is described under AI agents. Every agent prompt opens with the same operating principles, which put the protection of people and the environment ahead of any single instruction.

🧬 organic chemistry · 🧲 transition-metal complexes · 💡 photoactive materials · 🔋 redox systems · 🔬 spectroscopy · ⚛ excited-state dynamics

Three ways to use it:

CLI — delfin runs workflows from a CONTROL.txt configuration file
Dashboard — browser UI for job setup, result analysis, and configuration
Agent — an autonomous AI coding agent (model-agnostic: Claude, OpenAI, or local via Ollama) that operates the dashboard, runs and interprets workflows, and implements code itself — extending DELFIN and carrying multi-step projects through to completion (shell commands isolated where the host supports it, subagents, persistent memory)

Design principles

One interface across the QM stack. Each stage is routed to an established engine — RDKit / Architector for structure, xTB / CREST / GOAT for conformer pre-screening, and ORCA for the DFT workflow — and the outputs are reconciled into a single workflow. Turbomole, the periodic codes and the ML potentials (MACE / ANI and others) are reachable as individual pipeline steps.
Reproducible, documented runs. Every prediction ships with its provenance: input SMILES, method choices, solver logs, spectra, and a generated DOCX report — ready for direct inclusion in supplementary information.
Geometry sanity checks. Generated structures pass a default-on gate against severe covalent distortion and bad angles; a stricter topology gate (DELFIN_TOPOLOGY_HARD_GATE=2) additionally rejects detached metal–donor bonds, extra fragments and atomic collisions. π-system planarity and hapticity are enforced constructively by the MANTA builder rather than checked afterwards.
From prediction to inverse design. ChemDarwin enumerates structural variants from a seed molecule, the same pipelines predict their properties, and the computed property becomes the fitness criterion that selects the seeds for the next round. Today that loop is closed by the chemist: DELFIN computes and ranks, ChemDarwin varies, and the selection is a deliberate step rather than an automatic one.

DELFIN is research infrastructure: it does not replace chemical judgement — it makes rigorous computational chemistry (structure generation, DFT, semi-empirical methods, ML potentials, and spectroscopy) routine enough to inform it.

What DELFIN can do

Domain legend: 🧪 organic · 🧲 metal complex · 🔬 both / general · 🧱 solid state

Capability	Domain	Description
Redox Potentials	🔬 both	Automated spin-state prediction and redox potential calculation via OCCUPIER/classic workflows — works for organic radicals AND transition-metal complexes
Thermodynamics Simulations	🔬 both	Automated log K prediction and free-energy analysis via Born-Haber thermodynamic cycles with OCCUPIER-aware metal, ligand, and solvent sub-workflows
Excited-State Dynamics	🔬 both	Automated orchestration of ISC / RISC / IC rates, fluorescence and phosphorescence lifetimes (incl. per-sublevel), SOC coupling, E₀₀ adiabatic energies, and ΔE(S-T) singlet-triplet gaps — from the states and transitions you list in `CONTROL.txt`
TADF Screening	🧪 organic	xTB-based singlet-triplet gap estimation for OLED material discovery
Spectroscopy	🔬 both	UV-Vis absorption, IR vibrational spectra, AFP (absorption/fluorescence/phosphorescence) plots
Ensemble NMR	🧪 organic	CREST → CENSO → c2anmr → ANMR Boltzmann-weighted ensemble shieldings/couplings
Hyperpolarizability	🔬 both	Static and frequency-dependent β tensors for NLO materials (organic and organometallic)
Structure Generation	🔬 both	SMILES→3D for organics (RDKit/Open Babel) AND metal complexes (MANTA, DELFIN's own deterministic coordination constructor; Architector; stepwise ORCA/xTB `%DOCKER` assembly)
Conformer Sampling	🔬 both	MANTA multi-start sampling with energy ranking, CREST conformer search, XTB-GOAT global optimization
ML Potentials	🔬 both	8 backends (ANI-2x, AIMNet2, MACE, CHGNet, M3GNet, SchNetPack, NequIP, ALIGNN) for fast energy/force evaluation
Crystal Structure Generation	🧱 solid state	Genarris integration for random organic crystal generation with configurable space groups (generation, not lattice-energy ranking)
Fukui Indices	🔬 both	Atomic Fukui indices from three ORCA single points (N, N±1) at fixed geometry, with ESP reporting
Imaginary-Mode Elimination	🔬 both	Iterative saddle escape: displaced single points on both sides of the imaginary mode, re-optimisation and frequency per round. ESD rates are refused on a structure still at a saddle
CO₂ Coordination	🧲 metal	Automated CO₂ placement around metal centers, distance/rotation scans
Reporting	🔬 both	Auto-generated DOCX combining all visualized output — spectra plots (UV-Vis, IR, AFP), ESD rate tables (ISC / RISC / IC, ΔE(S-T), E₀₀), redox-potential summaries, free energies, and full method provenance; JSON export and text summaries also available
AI Agent	🔬 both	Conversational coding agent on any tool-capable model (Claude / OpenAI / KIT / local Ollama) — bash isolated where the host supports it, subagents, MCP, persistent memory, dashboard control, literature research, result analysis
Structure Enumeration	🔬 both	ChemDarwin morphs a seed molecule with user-supplied reaction SMARTS over N iterations — forbidden/protected substructure filters, ligand-wise mutation for metal complexes, results drawn and mapped in chemical space. Candidates are submitted to a DELFIN workflow by hand; there is no automated fitness loop

Use cases

Catalysis & energy 🧲

Multi-step redox tuning of transition-metal complexes (up to 3 sequential oxidation/reduction steps per pipeline)
Spin-state-resolved energetics with adaptive broken-symmetry configuration evolution
Topology-aware structure generation across σ-donors, π-haptic modes (η²–η⁶), and mono- to multi-metallic complexes
Born-Haber stability-constant (log K) cycles for individual complexes, for ligand-variant comparison
Structural variants enumerated with ChemDarwin, then ranked by computed redox potentials or log K

Photophysics & emissive materials 🧪 / 🧱

End-to-end TADF screening: ΔE(S-T) from xTB pre-screen → ISC / RISC rates from DFT
Phosphorescence design: per-sublevel lifetimes for Ir(III) / Pt(II) / Cu(I) and organic phosphors
Excited-state-geometry-aware fluorescence/phosphorescence rates (IC, ISC, RISC; E₀₀ adiabatic energies)
NLO chromophore design via β tensors; random organic crystal generation (Genarris)

Pharmaceutical & medicinal chemistry 🧪

Conformer ensembles and free-energy ranking for drug-like scaffolds (CREST + xTB-GOAT + DFT)
Redox-potential and spin-state prediction for metallodrug / metalloenzyme-mimic design
Boltzmann-weighted ensemble NMR for stereo-/regioisomer assignment

Spectroscopy & characterization 🔬

UV-Vis (TD-DFT) absorption, IR vibrational spectra, AFP overlay plots
Boltzmann-weighted ensemble NMR (¹H / ¹³C shieldings + J-couplings)
Hyperpolarizability β-tensors and dipole moments; imaginary-frequency cleanup (delfin --imag)

Overview — what it can do · design principles · use cases
Installation
Quick start — dashboard · command line · Python
Dashboard
Workflows
Structure generation from SMILES
Configuration (CONTROL.txt)
AI agents
CLI reference
Architecture
External programs
Cluster and HPC
Troubleshooting
Development
References · Dependencies and legal notice · Please cite · License

🚀 Installation

PyPI package: https://pypi.org/project/delfin-complat/

Requirements

Python 3.10, 3.11 or 3.12 (3.12 with numpy 2.2 is the reference environment of the MANTA construction; install.sh still sets up 3.10/3.11, because the ML and AI stacks it can add are not verified on 3.12)
ORCA 6.1.1 in your PATH (orca and orca_pltvib) — free for academic use
Optional: crest and xtb (CREST/xTB workflows)
Optional: censo, anmr, c2anmr, nmrplot (ensemble NMR)
Optional: xtb4stda, stda, std2 plus the xtb4stda runtime files (TADF screening, xTB-based response)
Optional: any of the 90+ supported programs — see External programs
Optional (dashboard): JupyterLab/Notebook or Voila

Install methods

Installer (any Linux workstation or cluster login node):

git clone https://github.com/ComPlat/DELFIN.git ~/software/delfin
bash ~/software/delfin/install.sh              # DELFIN, ORCA wiring, QM/analysis tools, Ketcher
bash ~/software/delfin/install.sh --all        # everything, ML and AI stacks included (several GB)
bash ~/software/delfin/install.sh --only crest,gxtb
bash ~/software/delfin/install.sh --dry-run    # print the plan, change nothing
bash ~/software/delfin/install.sh --update     # pull DELFIN, update it and every installed tool
bash ~/software/delfin/install.sh --repair     # check everything, fix what is broken

It needs no root and no module system: a Python 3.10/3.11 is taken from the machine or fetched with micromamba, ORCA is found where it was unpacked (or pass --orca DIR|TARBALL; ORCA is licensed and never downloaded), and OpenMPI — the version ORCA's directory name gives, 4.1.8 when there is no ORCA yet, configured as ORCA needs it — is found or built. Nothing in it is specific to one site. The script itself lives in delfin/installers/install_delfin.sh.

Whatever is left out can be added later, three ways that share one list of tools (delfin/installer.py): install.sh --only …, the install buttons in the dashboard's Settings tab, or automatically the moment a calculation needs a tool (DELFIN_AUTO_INSTALL_QM_TOOLS=0 switches that off). python -m delfin.installer --list shows what can be installed, --status what is.

PyPI install:

pip install delfin-complat

Development install (from source):

git clone https://github.com/ComPlat/DELFIN.git
cd DELFIN
python -m venv .venv
source .venv/bin/activate
pip install -e ".[agent,docs,dev]"

All Python dependencies (RDKit/Open Babel for SMILES workflows, ipywidgets/py3Dmol for dashboard visualisation, python-docx for reports) are installed automatically. This exposes the console command delfin and enables python -m delfin.

PyMOL is optional. It renders the ESP, dipole-moment and orbital pictures of the Word and ESD reports; without it those pictures are skipped with a notice in the log and everything else works. Install it with the pymol extra, pip install "delfin-complat[pymol]" (or -e ".[pymol]" from source). Its PyPI wheels need glibc 2.35 or newer, so on RHEL 9 and its clones (glibc 2.34, the usual HPC login nodes) the extra does not resolve; leave it out there.

Reference environment for reproducible MANTA builds

pyproject.toml admits version ranges, so a plain pip install resolves whatever is newest inside them, and MANTA geometry comes out of RDKit, Open Babel and numpy. The published MANTA structures were built with CPython 3.12.11, numpy 2.2.2, RDKit 2025.9.3, openbabel-wheel 3.1.1.22, SciPy 1.16.2, NetworkX 3.1 and stk 2026.1.4.0; env/reference-environment.lock lists every Python package of that interpreter at its exact version. To rebuild against it, use it as a constraints file:

python -m venv .venv          # with a Python 3.12 interpreter
source .venv/bin/activate
pip install -e ".[agent,docs,dev]" -c env/reference-environment.lock

A byte-identical rebuild of published structures is only to be expected in this environment. The C math library belongs to it as well: the structures are built with the libm of glibc 2.34 (RHEL 9); another glibc rounds a few transcendental functions differently in the last digit at rare arguments, so a handful of systems can come out different. CI installs it on every push (job reference environment in .github/workflows/ci.yml) and runs the MANTA tests in it, so the file keeps resolving and the construction keeps passing there. The lock also pins pymol-open-source; as a constraint that only takes effect when the pymol extra is requested, so the command above does not ask for it and resolves on glibc 2.34 systems (RHEL 9) as well. The construction does not use PyMOL, so the rebuild is the same with or without it.

External QM binaries are not installed by pip. For the local binary-based setup of xtb, crest, xtb4stda, stda, std2 and the xtb4stda runtime bundle, see delfin/qm_tools/README.txt.

External QM tool setup

The installer above does this. By hand, after installing the Python package:

source delfin/qm_tools/env.sh
USE_SYSTEM_TOOLS=1 bash delfin/qm_tools/install_qm_tools.sh
bash delfin/qm_tools/check_qm_tools.sh

To check an installation at any time:

delfin doctor              # ORCA, xTB, OpenMPI, scratch, SLURM, doc index
delfin qm_check            # how each QM binary is resolved
delfin mlp_check           # ML-potential backends, PyTorch, CUDA
delfin analysis_check      # Multiwfn / CENSO / ANMR / morfeus
delfin csp_check           # Genarris

🏁 Quick start

The dashboard

The usual way to run DELFIN. Start it as a standalone web app:

delfin-voila                 # starts on 127.0.0.1:8866

delfin-voila prints a URL containing an access token. The token cannot be switched off: the dashboard, its files and its kernels all require it (only the server's own static assets, such as the login page's, are served without it); see the dashboard section of docs/SECURITY_MODEL.md. Open that URL, go to Submit Job, paste a SMILES or load an XYZ, choose the workflow settings, and submit. Job Status follows the queue; Calculations browses the results.

The command line

A working directory needs two files:

CONTROL.txt — the configuration (create one with delfin --define)
input.txt — either an XYZ body (without the two header lines) or a single-line SMILES string

Starting from a full .xyz file works too: delfin --define=input.xyz converts it.

delfin                       # run in the current directory
python -m delfin             # same thing
delfin /path/to/project      # run in another workspace directory

Results are written into the workspace: DELFIN.txt (redox potentials), OCCUPIER.txt (occupation tracking), ESD.txt (excited-state results), DELFIN_Data.json, the DOCX report, and one folder per step.

Python

from delfin.api import run

run(control_file="CONTROL.txt")

from delfin.dashboard import create_dashboard

ctx = create_dashboard(backend="auto")   # SLURM when available, else local

🧪 Dashboard

Tab	Purpose
Submit Job	SMILES/XYZ input, 3D preview and editor, converter choice (`QUICK`, `NORMAL`, `MANTA`, `ARCHITECTOR`, `MOLSIMPLIFY`, `MACE`), `BUILD COMPLEX`, `MANTA`, `ARCHITECTOR`, `MOLSIMPLIFY`, `MACE`, `SUBMIT FUKUI`, `SUBMIT ONLY GOAT`, `SUBMIT DELFIN + CO2`, `VALIDATE CONTROL`
Recalc	Edit an existing `CONTROL.txt` and resubmit; a smart recalc recomputes only what the edit changed
ORCA Builder	Interactive ORCA input generation with geometry preview
TURBOMOLE Builder	Turbomole define workflow (SLURM backends)
ChemDarwin	Reaction-SMARTS structure enumeration and chemical-space map (off by default)
DELFIN Agent	The AI agent: subagents, MCP, bash isolated where the host supports it, dashboard control, result analysis, persistent memory
Agent Activity	Running and recent agent and subagent work
Job Status	Queue monitoring (local/SLURM), resource usage, fairshare and limits, job cancellation
Calculations	File browser, search, recalculation trigger, energy statistics, browser-launched workflows such as `Calc NMR` and `Calc CENSO/ANMR`
Archive	Archive browser with statistics
Remote Archive	Browse and transfer results on a remote machine over SSH
Office	Documents and spreadsheets, with an agent that has no chemistry tools
Literature	The indexed literature corpus
Tools	The registered tool steps and their parameters
Ketcher	2D structure drawing
Reactions	Reaction graph
Pipelines	Declarative step pipelines
Settings	Tool detection, per-tool Install/Update buttons, runtime configuration, agent model settings

Some tabs are hidden by default and are enabled in Settings.

Running the dashboard

delfin-voila                 # 127.0.0.1:8866, prints a URL with an access token
delfin-voila --port 9000     # custom port
delfin-voila --dark          # dark theme
delfin-voila --keep          # run inside a tmux session, survives a dropped terminal
delfin-voila --resume SID    # reopen a previous agent session

# On HPC/login nodes keep the default 127.0.0.1 bind and use an SSH tunnel.
# A direct network bind needs an explicit override:
delfin-voila --ip 0.0.0.0 --allow-remote-bind

Windows SSH desktop launcher (OTP, separate working terminal, tmux reconnect): Setup and installation. Copy that folder to your Windows PC.

Detailed documentation: docs/SETTINGS_AND_SETUP.md

✨ Workflows

Redox potentials (OCCUPIER)

DELFIN's core workflow automates spin-state identification and redox-potential calculation:

Multi-step redox: up to 3 sequential oxidation and reduction steps
Parallel workflows: oxidation and reduction run simultaneously with automatic PAL splitting (PAL=12 → 6+6)
Adaptive broken symmetry: broken-symmetry configurations evolve along the OCCUPIER tree
Smart recalc: a SHA-256 fingerprint of each input and its dependencies skips jobs an edit did not change

Stability constants (log K)

A Born-Haber-type thermodynamic cycle for one coordination complex per run:

Automatic reaction analysis: unique ligands, denticities, displaced solvent count and the matching metal-solvent reference complex are extracted from the complex SMILES
OCCUPIER-aware metal treatment: the target complex and the solvated metal reference can use the same converter, pre-optimisation, multiplicity and broken-symmetry logic as the main workflow
Efficient sub-workflows: duplicate ligands are computed once; ligand, solvent and metal-solvent jobs run in parallel
Output: OPT+FREQ free energies for complex, solvated metal, ligand(s) and solvent, combined into ΔG and log K

The CONTROL keys are stability_constant, stability_constant_mode and stability_reaction (the older spellings thermodynamics* are still read).

Excited-state dynamics (ESD)

Photophysical properties from a list of states and transitions that you specify — DELFIN orchestrates the jobs, it does not choose the states for you:

Electronic states: S0, S1, S2, T1, T2 geometry optimisation
ISC / RISC rates: intersystem and reverse intersystem crossing
Internal conversion (IC): non-radiative decay rates
Fluorescence and phosphorescence: radiative lifetimes, including per-sublevel phosphorescence
E₀₀: adiabatic 0-0 transition energies
ΔE(S-T): singlet-triplet gaps

ESD_modul=yes
states=[S1,T1,S2,T2]
ISCs=[S1>T1,T1>S1]
ICs=[S1>S0]
emission_rates=[f,p]

There is no delfin ESD subcommand: a normal delfin run performs the ESD work when ESD_modul=yes. Rates are refused on a structure that still sits at a saddle point — see imaginary-mode elimination below.

TADF screening (xTB-based)

Fast triage of TADF candidates with semi-empirical methods (needs xtb, xtb4stda with its runtime files, and stda/std2):

S0/T1 optimisation via xTB, S1 estimated from the Stokes shift
ΔE(S-T), vertical and as a relaxed estimate
First allowed and brightest singlet, with oscillator strengths
Estimated absorption and emission wavelengths, T1 adiabatic and vertical

Spectroscopy and properties

Module	Output
UV-Vis	TD-DFT absorption spectra, oscillator strengths, transition analysis
IR	Vibrational frequencies, intensities, Lorentzian broadening, transmittance
AFP	Combined absorption/fluorescence/phosphorescence plot (`--afp-fwhm`, default 50 nm)
Hyperpolarizability	Static and frequency-dependent β tensors (β_HRS, β_VEC, DR), dipole moments
Fukui	Atomic Fukui indices from three ORCA single points (N, N±1) at fixed geometry, plus ESP reporting

Ensemble NMR via CREST + CENSO + ANMR

A browser-launched ensemble NMR workflow for .xyz inputs, started from the Calculations tab:

Calc NMR — single-structure ORCA NMR workflow
Calc CENSO/ANMR — end-to-end ensemble workflow: CREST conformer sampling with -nmr → CENSO re-ranking and refinement → ORCA shieldings and couplings for the survivors → Boltzmann-weighted ANMR spectra → PNG, PDF, SVG and JSON/text summaries

The four helper programs (censo, anmr, c2anmr, nmrplot) are external; they are detected in DELFIN's runtime layer and can be installed from the dashboard's Settings tab, or automatically on first use.

Imaginary-mode elimination (IMAG)

A structure with an imaginary frequency is not a minimum, and rate constants computed on it are meaningless. delfin --imag (or IMAG=yes in CONTROL) walks out of the saddle iteratively: it displaces the geometry along the imaginary mode in both directions, takes single points, re-optimises and recomputes the frequencies, round after round, until the mode is gone or the round cap is reached. Modes below allow_imaginary_freq count as numerical noise. The ESD module refuses to compute rates on a structure that is still at a saddle.

ML potentials and the calculator factory

34 computational backends behind one interface, each returning a standard ASE Calculator:

from delfin.calculators import create_calculator

calc = create_calculator("ani2x", device="cuda")          # ML potential
calc = create_calculator("orca", method="B3LYP")          # DFT
calc = create_calculator("xtb")                           # Semi-empirical
calc = create_calculator("vasp", xc="PBE", kpts=[4,4,4])  # Periodic DFT

atoms.calc = calc
energy = atoms.get_potential_energy()

All backends are lazily loaded — nothing is imported until it is used — and the ML backends validate CUDA with a CPU fallback. Of the 8 ML potentials, six ship usable pre-trained weights; SchNetPack and NequIP need a trained model of your own (model_path). These calculators and the non-ORCA engines are used through the step and pipeline system (delfin-step, delfin-pipeline); the CONTROL.txt workflow itself runs on ORCA.

Crystal structure generation (Genarris)

Random organic crystal generation with configurable space groups, Z values and MPI-parallel execution. This is generation, not polymorph ranking: no lattice energies are computed and no structures are scored. It needs the external gnrs binary and mpirun, and is driven from a Genarris configuration file through the step adapter.

CO₂ coordinator

Automated CO₂ placement around metal centres with relaxed distance scans (1.6–4.0 Å) and rotation scans (±180°). Run with delfin co2 … or from the Submit tab.

Reporting and export

Format	Command	Content
Text	automatic	`DELFIN.txt` (redox potentials), `OCCUPIER.txt` (occupation tracking), `ESD.txt` (excited-state results)
DOCX	automatic, or `delfin --report docx`	Word document with embedded spectra plots and structured tables
JSON	automatic, or `delfin --json`	Machine-readable `DELFIN_Data.json` (`--json-output` for another path)
UV-Vis	`delfin_ESD output.out`	Parsed UV-Vis spectrum with transitions and oscillator strengths
IR	`delfin_IR output.out`	Parsed IR spectrum with vibrational modes and intensities
NMR	`delfin_NMR output.out`	¹H NMR spectrum plot and report from an ORCA NMR output
AFP	`delfin --afp`	Absorption/fluorescence/phosphorescence combined plot

The DOCX and JSON reports are written at the end of every main run; a failure there is logged as a warning and does not fail the run.

🧬 Structure generation from SMILES

Which builder runs is decided by one CONTROL key, and a SMILES run must set it:

smiles_converter=[QUICK|NORMAL|MANTA|ARCHITECTOR|MOLSIMPLIFY|MACE]

Value	What it does	Best for
`QUICK`	One ETKDGv3 embedding; for metals it tries stk → RDKit → unsanitised → Open Babel and returns on the first success. One structure.	Quick previews
`NORMAL`	RDKit ETKDG with multi-seed embedding and optional UFF refinement (RDKit / Open Babel). One structure. This is the default when nothing is set.	Organic molecules
`MANTA`	DELFIN's own deterministic constructor: the isomer–conformer ensemble of the complex, then screening, optimisation and refinement down to one geometry.	Metal complexes
`ARCHITECTOR`	architector automated 3D generation; needs a metal-containing SMILES.	Metal complexes, instant preview
`MOLSIMPLIFY`	molSimplify, one structure per geometry of the coordination number; needs a metal-containing SMILES.	Metal complexes
`MACE`	epic-MACE (Chernyshov & Pidko, JCTC 2024): every stereomer of the geometries that fit the donor sites, ten conformers each; runs in its own Python 3.7 environment.	Metal complexes, hapto ligands

epic-MACE (Chernyshov & Pidko, J. Chem. Theory Comput. 2024, 20, 2313; EPiCs-group/epic-mace, GPL-3.0) needs Python 3.7 and RDKit 2020.09, so it is never installed beside DELFIN: python -m delfin.installer --install epic-mace (or install.sh --only epic-mace, or the Install button in Settings) builds an environment of its own with micromamba under ~/.delfin/ai_tools/.mamba_env/epic_mace (from the pinned GitHub commit efb5778e, which adds hapto ligands and the TET/SPY/TBP/SAN geometries to the octahedron and square of the PyPI release), and DELFIN calls it there as an external program; DELFIN_MACE_PYTHON points it to another interpreter. The geometry follows from the number of donor sites (a hapto ligand is one site): OH for 6, SP + TET for 4, SPY + TBP for 5, SAN for two hapto ligands. Every stereomer (enantiomers kept) gets ten conformers; MACE has no random seed, so two builds can differ.

In the Submit tab the same choice appears as the converter dropdown, next to BUILD COMPLEX (stepwise assembly using ORCA's %DOCKER, submitted as a job) and the CONVERT SMILES, QUICK CONVERT SMILES and CONVERT SMILES + UFF buttons of the structure editor.

For many SMILES at once -- a list of ID;SMILES lines, up to hundreds of thousands -- delfin cluster builds with MANTA, Architector, molSimplify or epic-MACE as a sharded, resumable Slurm array (or shard by shard on a workstation) and merges the result into one multi-frame xyz archive, with code and environment recorded for reproduction: see docs/CONSTRUCTION_BATCH.md.

MANTA

MANTA is DELFIN's deterministic constructor for metal complexes — construct, don't search. From a transition-metal SMILES it enumerates the coordination isomers as symmetry orbits (Burnside–Pólya counting over the donor arms and the coordination polyhedron), seats each isomer on an ideal polyhedron with metal–donor distances from covalent radii, and adds ring-pucker, pose and mirror siblings. The frames emitted for one SMILES form its isomer–conformer ensemble. No force field acts on a free metal centre on this path: universal force fields have only generic parameters for the metal, which is what distorts M–D lengths and L–M–L angles in conventional builders; force fields relax only free ligands and, with metal and donors fixed, ring puckers. Inputs outside the constructor's scope, or whose isomers all fail its self-gate, are built by a legacy path that minimises UFF over the whole complex. See delfin/manta/README.md.

The ensemble then goes through a funnel that CONTROL.txt steers:

build ensemble → screen (one single point per frame and multiplicity)
               → optimise (xTB per survivor)
               → refine (GOAT or CREST on the best)
               → winner written to start.txt

The ranked unit is a (frame, multiplicity) pair, not a frame. The MANTA_* block in CONTROL.txt steers how thorough the construction is, which gates filter the ensemble, what the screen and the optimisation use, whether GOAT or CREST refines the winner, and how long the whole thing may take. delfin --define writes the block with its defaults. delfin-manta runs the builder on its own.

What MANTA is for: starting geometries, not production geometries. The output is a constructive geometry of roughly force-field quality — correct in topology and coordination, not xTB- or DFT-accurate.

GUPPY and MANTA. GUPPY was the earlier name for MANTA plus the energy-rank-and-pick driver around it. smiles_converter=MANTA is the current spelling; GUPPY and the older bare GUPPY=yes are still read and mean the same thing, and every MANTA_* key falls back to its GUPPY_* predecessor, so CONTROL files written before the rename keep working. The driver module, its working directory and the delfin-guppy / delfin-guppy-batch commands still carry the GUPPY name.

Conformer search and sampling

CREST — conformer-rotamer ensemble generation and sorting
xTB-GOAT — gradient-based global optimisation
GUPPY sampling (MANTA ensemble + xTB ranking) — the MANTA ensemble optimised in parallel with xTB and ranked by energy (delfin-guppy, delfin-guppy-batch for a batch of SMILES)

⚙️ Configuration (CONTROL.txt)

DELFIN is configured by CONTROL.txt in the working directory. delfin --define writes a fully commented template with every key and its default; the groups below are the ones you touch most.

Workflow control

method = OCCUPIER | classic | manually (leave empty for ESD-only runs)
OCCUPIER_method = auto | manually (auto uses adaptive tree-based sequences)
calc_initial = yes | no
oxidation_steps = 1,2,3 / reduction_steps = 1,2,3
parallel_workflows = yes | no | auto

Structure

smiles_converter = QUICK | NORMAL | MANTA | ARCHITECTOR | MOLSIMPLIFY | MACE (required for a SMILES run)
MANTA_* — the MANTA builder and its funnel: construction quality, gates, screening, optimisation, refinement, time budget
XTB_preOPT = yes | no / global_optimizer = GOAT | CREST
- the older spellings XTB_OPT / XTB_GOAT / CREST are still accepted
XTB_SOLVATOR = yes | no

Resource management

PAL = N / maxcore = MB
pal_jobs = N (parallel PAL processes; auto-detected on a cluster when unset)
orca_parallel_strategy = auto | threads | serial

Optional modules

ESD_modul = yes | no with states, ISCs, ICs, emission_rates
IMAG = yes | no
- IMAG_scope = all | initial (default all: every redox step too)
- allow_imaginary_freq = -50 (cm⁻¹, ≤ 0: smaller imaginary modes count as numerical noise)
- IMAG_max_rounds = 2 (each round is one frequency calculation)
stability_constant, co2_coordination, calc_prop_of_interest, reorganisation_energy
TDDFT_*, deltaSCF_*, elprop_*, tadf_xTB*, hyperpol_xTB*

Error recovery

enable_auto_recovery = yes | no (ORCA error recovery, continuing from the last .gbw and geometry)
max_recovery_attempts = N (default: 3)
enable_job_timeouts = yes | no (no for unlimited runtime)

🤖 AI agents

DELFIN ships a conversational AI agent: it reads and edits code, runs shell commands (isolated where the host supports it; see Tools, MCP and safety), drives the dashboard, researches methods, analyses results and delegates self-contained work to subagents. It runs in the DELFIN Agent dashboard tab and as the standalone terminal program delfin-agent. It is a single, direct agent — there is no fixed review pipeline; when work benefits from extra hands it spins up subagents on demand.

Operating principles

Every role prompt opens with the same principles, ahead of any instruction about tools, modes or permissions: delfin/agent/pack/shared/principles_addendum.md. The stated highest objective is

to advance science so that the great problems of our time can be solved, and to contribute to the long-term well-being of humanity and the planet.

The rest covers human dignity, safety and self-determination, a refusal to assist with serious harm or coercion, and precedence for human life and the environment when objectives conflict.

tests/test_the_principles_come_first.py checks that the file exists, that it has not been emptied to a heading, that the principles come first in every role's composed prompt, and that the sentence above reaches the model. The agent may not edit the file unasked, and the prompt token budget exempts it from trimming.

Modes

A mode decides which role prompt and which surface the agent gets:

Mode	Where	For
`dashboard` (default)	dashboard, terminal	Operating DELFIN: settings, submissions, results
`solo`, shown as Code	dashboard, terminal	Reading and writing code
`office`	dashboard, terminal	Documents and spreadsheets, without the chemistry tools
`research`	dashboard, terminal	Literature and method research: web search and code reading, read-only — no file changes, no shell commands

plan is not a mode but a permission profile — see below.

Works with any tool-capable model

The agent is provider-agnostic. A model that cannot call tools is refused with an explanation, because every non-trivial action is a tool call.

Provider	Primary backend	Notes
Claude (default)	API via `ANTHROPIC_API_KEY`	Claude Code CLI when `claude` is on PATH
OpenAI / Codex	API via `OPENAI_API_KEY`	Codex CLI when `codex` is on PATH
KIT Toolbox	API via `KIT_TOOLBOX_API_KEY`	university-hosted, OpenAI-compatible (vLLM)
Ollama / vLLM / LM Studio (local & open source)	OpenAI-compatible endpoint via `OLLAMA_HOST` (default `http://localhost:11434`)	no API key, runs offline. Any pulled model, e.g. `ollama pull qwen2.5-coder`. Tool-capable models (`qwen2.5-coder`, `qwen3-coder`, `llama3.3`) are the ones to pick.

A model-capability layer detects each model's real context window and its tool, vision and reasoning support — live from Ollama's /api/show and from OpenAI-compatible /v1/models, with a curated fallback table — and sizes context management to it. For Ollama it sends the correct num_ctx, so local models are not silently capped at 2–4k; it skips parameters local servers reject and strips <think> leaks. Weak or small models automatically get a slimmer prompt and a reduced tool surface.

Available providers are auto-detected from environment variables and PATH. DELFIN treats each LLM the way it treats ORCA, xTB or CREST: a dependency that you install and authenticate yourself. DELFIN bundles no LLM and redistributes none; it calls each provider's official API, OpenAI-compatible endpoint or CLI binary. Hosted usage runs under your own account and billing; local models run on your own hardware at no per-token cost.

Network access and offline use

DELFIN's workflows (ORCA, xTB, CREST and the other engines) run on your machines and need no network. With a local model server (Ollama, vLLM, LM Studio via OLLAMA_HOST) the agent's model calls stay on your network as well. The following parts connect to outside hosts:

Part	Connects to	Without outside network
Hosted model providers	the provider's API; the KIT Toolbox provider uses the fixed endpoint `https://ki-toolbox.scc.kit.edu/api/v1`	choose a local model server
Agent tools `web_search` and `web_fetch`	a fixed set of public search services (`delfin/agent/web_tools.py`) and the URL fetched	not available; the other tools are unaffected
CLI terminal tab (`delfin-voila --claude-terminal`)	the browser loads xterm.js from `cdn.jsdelivr.net` (pinned version, SRI hash); the CLI it runs talks to its own provider	not available; no local copy of xterm.js is supported yet
Diagrams in the agent chat	mermaid from `cdn.jsdelivr.net` (pinned version, SRI hash), fetched only when a diagram appears	place `mermaid.min.js` in `delfin/dashboard/static/`; without it the diagram is shown as source text
3D structure viewers	none: the bundled `delfin/dashboard/static/3Dmol-min.js` is loaded at start, and no viewer fetches a copy from elsewhere (the page's Content-Security-Policy would refuse it)	works with the bundled copy
Ketcher editor, xtb and g-xTB installers	GitHub, once, on first use and after confirmation (Ketcher and every binary or source archive an installer fetches itself: one pinned version, refused unless its SHA-256 matches; packages installed through conda or pip: see docs/RELEASING.md)	install on a machine with network access and copy the files

Subagents

For parallel research, read-only audits or planning that must not edit, the agent delegates to isolated subagents — each with its own tool loop and usually tighter permissions:

explore — read-only investigation, reports findings
plan — step-by-step plan, makes no edits
code-reviewer — independent read-only review
general-purpose — self-contained task, inherits permissions

Your own presets can be added as markdown files in ~/.delfin/subagents/. Subagents run in parallel (a writer preset gets its own git worktree, so concurrent edits cannot clobber) or in the background; a finished one can be continued with its context intact. Every delegated run is bounded — in wall-clock time, in how many tool calls it may make and in how much it may write back — so a subagent cannot run away with the session; the bounds are in Settings. A subagent may not spawn subagents of its own unless that depth is raised. Launch one with /explore, /review, /plan or /delegate <task>.

Tools, MCP and safety

Built-in tools: read/edit/write files, grep, bash with long-running background jobs (isolation as below), code navigation, test runner, notebooks, documents and spreadsheets, web search and fetch, task tracking, scheduling, git worktrees, delegation, plus DELFIN-specific calculation and manual search.
MCP (Model Context Protocol): connect external MCP servers over stdio or Streamable HTTP — their tools, resources and prompts join the agent's surface (configured in ~/.delfin/mcp_servers.json). A tool reached through MCP runs in a process DELFIN did not launch a command line for, so the shell sandbox is not around it: give a stdio server "roots": [...] (read-write) or "read_roots": [...] (read-only) and it starts inside a namespace holding only those paths. Servers that declare neither run uncontained, and the startup banner, /mcp and delfin-agent doctor all say so. DELFIN's own servers can take their roots from your settings instead — agent.mcp_isolation: "builtin" binds the calculations, office, workspace and state folders read-write and the archive and runtime trees read-only; it is off by default because the roots are inferred.
Shell isolation: every shell command passes the permission gate first, then runs under the first layer that works on the host — bubblewrap, else Landlock (both Linux), else Seatbelt (macOS). Under these layers writes are confined to the workspace roots, credential directories (~/.ssh, ~/.aws, ~/.gnupg, …) are unreadable, and terminal and SSH-agent sockets are not reachable. The network goes only through an egress proxy with a domain allow-list under bubblewrap, Seatbelt, and Landlock with seccomp user notification; Landlock without seccomp user notification restricts TCP by port only (ABI 4) or not at all (older ABI). Where no layer works (for example on Windows, or on Linux with neither bubblewrap nor Landlock) a command is not confined: the gate's reading of its text is the only check, and the start banner and /status say NOT isolated. An attended session then still runs commands (those off the auto-allow list are asked), bypassPermissions asks once at start or, unattended, starts in default, and a locked session or --isolate refuses each command unless you approve that one command unconfined. delfin-agent capabilities prints which layer holds on the current host; the guarantees per host are in docs/SECURITY_MODEL.md. --no-isolate turns isolation off.
Dashboard CLI-backend runner: the dashboard's approval of a CLI-backend Bash call goes through a separate runner (delfin/agent/sandbox.py, DELFIN_AGENT_SANDBOX={auto,bwrap,firejail,allowlist,off}). auto uses bubblewrap or firejail where available, else allowlist. allowlist is a command allow-list, not a sandbox: it admits python, awk, sed, find and tee, which can run any program; git and pip pass only with a read-only sub-command, in every spelling (pip3, python -m pip), and env, nohup and xargs are judged by the command they run. In that mode the command runs under Landlock (writes only in the repository) where the kernel has it, with the network denied unless DELFIN_AGENT_SANDBOX_NETWORK=1: fully where seccomp user notification exists (net=off), TCP only on Landlock ABI 4 (net=off-tcp), and not at all on older kernels (net=open). Where the kernel has no Landlock the command runs unconfined. The line printed for each approved command names what was applied (mode=…, fs=…, net=…) and what is missing.
Security model: what the containment protects, against whom, what each layer guarantees on which host and the residual risks are in docs/SECURITY_MODEL.md; vulnerabilities are reported privately as described in SECURITY.md.
Permission modes: plan (read-only) · default (destructive actions ask) · diff_approval (writes stage a diff for /approve) · acceptEdits (writes allowed, bash still asks) · bypassPermissions (no prompts; the deny lists and, where the host has one, the isolation layer still apply). Per-pattern allow-list rules can be remembered across sessions. Files that define the agent's own permissions always require confirmation, in every mode.
Workspace trust: settings, hook commands and MCP servers that come from a checked-out repository are ignored until you trust that directory (/trust).

Slash commands

Built-in commands cover the session (/help, /status, /cost, /context, /compact, /export, /undo), the setup (/model, /mode, /permissions, /effort, /doctor, /mcp, /trust, /tools, /agents, /skills), the history (/session, /rewind, /tasks, /memories, /plans), pending changes (/pending, /approve, /reject) and the workspace (/git, /bash, /jobs). The dashboard adds direct control of DELFIN:

/control key <key> <value>   — change a single CONTROL key
/orca set <param> <value>    — configure the ORCA Builder
/calc ls, /calc read, /calc info, /calc tree — browse calculations
/analyze energy, /analyze convergence, /analyze errors — analyse ORCA outputs
/recalc check-all, /recalc auto — smart recalculation
/submit, /cancel — job management (with confirmation)

Beyond those, a markdown file in ~/.delfin/commands/ or <workspace>/.delfin/commands/ becomes a slash command of its own, and a skill (~/.delfin/skills/<name>/SKILL.md) can be invoked either by you or by the model. Fourteen skills ship with DELFIN, among them diagnose-failed-run, recalc-failed, tddft-excited-states, freq-thermochemistry, solvation-setup and tune-control.

Memory and sessions

Persistent memory: facts and preferences survive across sessions and are recalled by relevance (/remember, /memories, /forget). Memory is scoped by domain, so a preference recorded while coding does not surface in an office session.
Project instructions: a DELFIN.md or AGENTS.md in the project is loaded automatically.
Long sessions: token-aware compaction keeps long conversations coherent; /compact and /context expose the state.
Agent workspace: ~/agent_workspace/ for uploaded reference files.
Cost tracking: per-session token usage and cost in real time (local models are free).
Session persistence: conversations are saved, restored, forked and exported as Markdown.

📋 CLI reference

Running a workflow

delfin — run the workflow in the current directory (needs CONTROL.txt and input.txt)
delfin /path/to/project — run it in another directory
python -m delfin — the same entry point

Setup and configuration

delfin --define[=input.xyz] [--overwrite] (short: -D) — create or update CONTROL.txt, optionally converting an XYZ to input.txt
delfin /path/to/project --define[=input.xyz] — the same, in another workspace
delfin --control /path/to/CONTROL.txt — run with a CONTROL file from elsewhere; it sets the workspace root
delfin --version (short: -V)

Diagnostics

delfin doctor [--json] [--scratch DIR] — installation self-check: ORCA, xTB, OpenMPI, scratch directory, SLURM, API keys, documentation index. Runs no calculation and needs no network.
delfin qm_check [TOOLS…] — how DELFIN resolves each QM binary
delfin qm_run TOOL [--cwd DIR] [--capture] -- ARGS — run one QM tool through DELFIN's resolver
delfin mlp_check — ML-potential backends, PyTorch and CUDA
delfin analysis_check — Multiwfn, CENSO, ANMR, morfeus
delfin csp_check — Genarris availability

Execution control

delfin --recalc — re-parse existing results and restart only what is missing or incomplete
delfin WORKSPACE --recalc --occupier-override STAGE=INDEX — force an OCCUPIER index for a stage during a recalc
delfin --report — recompute redox potentials from existing outputs (bare: text; --report docx for Word)
delfin --imag — eliminate imaginary modes from existing ORCA results and regenerate the summary
delfin run_orca [file.inp] [-i FILE] [-o FILE] — run a single ORCA input through DELFIN's runner
delfin stop --workspace PATH [--signal INT|TERM|KILL] [--dry-run] [--cleanup] [--wait-seconds S] — stop running DELFIN processes for a workspace

Cleanup and maintenance

delfin --no-cleanup — keep temporary files and scratch folders after the run
delfin --cleanup (short: -C) — remove intermediates and exit
delfin cleanup [--dry-run] [--workspace PATH] [--scratch PATH] — fine control over workspace and scratch cleanup
delfin cleanup --orca — stop running ORCA jobs and purge OCCUPIER scratch folders
delfin --purge — remove DELFIN-generated artifacts after confirmation

Export and reporting

delfin --json [--json-output FILE] — collect results into DELFIN_Data.json
delfin --report docx — Word report with embedded plots
delfin --afp [--afp-fwhm NM] — AFP spectrum plot from existing ESD results (default FWHM 50 nm)

Specialised workflows

delfin co2 [--define] [--recalc] [--charge N] [--multiplicity M] [--solvent S] [--metal M] [--broken_sym B] — CO₂ coordinator
delfin tadf_xtb … — xTB/sTDA TADF screening batch runner (--smiles, --xyz-file, --crest, --goat, --t1-opt, --pal, --parallel-jobs)
delfin hyperpol / delfin hyperpol_xtb … — xTB-based hyperpolarizability batch runner

Excited-state dynamics has no subcommand of its own: set ESD_modul=yes in CONTROL.txt and run delfin.

Companion commands

Command	What it does
`delfin-voila`	Launch the dashboard as a standalone web app
`delfin-agent`	The AI agent in the terminal (`chat`, `run`, `init`, `doctor`, `session`, `approvals`, `scheduler`, …)
`delfin-manta`	MANTA: the isomer–conformer ensemble of a metal SMILES
`delfin-guppy [input.txt]`	Multi-start sampling with repeated xTB optimisation and ranked trajectories (`--runs`, `--parallel-jobs`, `--pal`, `--refine`, `--screen`, `--max-isomers`, …)
`delfin-guppy-batch`	The same over every SMILES in a batch file (`--row` for SLURM arrays)
`delfin-build [input.txt]`	Build metal complexes stepwise from SMILES using ORCA's `%DOCKER` (`--goat`, `--no-ligand-goat`, `--dry-run`, …)
`delfin-fukui`	Atomic Fukui indices from three ORCA single points
`delfin-step`	Run one registered tool step (`--list`, `--describe`, `--slurm`)
`delfin-pipeline`	Run a declarative YAML pipeline (`--param`, `--scheduled`, `--dry-run`)
`delfin-app`	Application registry: `list`, `template`, `run <keyfile>`, `describe`
`delfin-json <project_dir>`	Collect project outputs into JSON (`-o FILE`)
`delfin_ESD output.out`	UV-Vis spectrum report from an ORCA output
`delfin_IR output.out`	IR spectrum report from an ORCA frequency output
`delfin_NMR output.out`	¹H NMR spectrum report from an ORCA NMR output
`delfin-docs-index`	Build the documentation search index from `literature/`
`delfin-docs-server` · `delfin-ops-server` · `delfin-tools-server`	The three MCP servers

🏗️ Architecture

Package layout

delfin/
  cli.py                   # command-line entry point and subcommand dispatch
  cli_helpers.py           # the top-level argument parser
  api.py                   # programmatic API for notebooks and workflow engines
  config.py                # CONTROL.txt parsing, aliases and defaults
  define.py                # the CONTROL.txt template (every key and its default)
  calculators.py           # unified ASE calculator factory (34 backends)

  # ── Orchestration ──
  workflows/               # where the workflow logic lives
    pipeline.py            # high-level orchestration (classic / manually / OCCUPIER)
    engine/                # classic.py, occupier.py, scheduler.py
    scheduling/            # manager.py (global job manager), pool.py, priority.py
    contrib/               # co2, esd, hyperpol, imag, occupier, tadf_xtb workflows
    registry.py, types.py

  # ── Core workflows ──
  occupier.py              # OCCUPIER sequence execution and summary
  occupier_auto.py         # adaptive sequence rules and populated-state branching
  bs_evolution.py          # broken-symmetry evolution along the OCCUPIER tree
  esd_module.py            # excited-state dynamics (ISC / IC / fluorescence / phosphorescence)
  esd_input_generator.py   # ORCA input builders for ESD states
  stability_constant.py    # Born-Haber cycle, log K
  tadf_xtb.py              # TADF screening via xTB/sTDA
  hyperpol.py              # hyperpolarizability (NLO)
  fukui.py, cli_fukui.py   # atomic Fukui indices
  xtb_crest.py             # xTB / GOAT / CREST / ALPB solvation workflows
  imag.py, cli_imag.py     # imaginary-frequency elimination
  co2/                     # CO2 coordinator

  # ── Structure generation ──
  manta/                   # the coordination-structure engine (~120 modules)
  cli_manta.py             # the delfin-manta CLI
  smiles_converter.py      # SMILES→3D entry points, orchestrates delfin.manta
  guppy_sampling.py        # multi-start sampling, ranking and refinement funnel
  build_up_complex.py      # stepwise metal-complex assembly (ORCA %DOCKER)
  class_modules/           # chemistry-domain SMILES→XYZ specialists
  topology_hard_gate.py    # optional SMILES-vs-XYZ topology gate

  # ── ORCA and recovery ──
  orca.py                  # running ORCA, retries
  orca_recovery.py         # error detection and input repair
  common/orca_input.py     # reading and writing ORCA inputs

  # ── Recalculation ──
  smart_recalc.py          # fingerprints: what may be skipped
  recalc_control.py        # what a CONTROL edit invalidates

  # ── Resource management and clusters ──
  cluster_utils.py         # SLURM / PBS / LSF resource detection
  slurm_submit.py, scheduler_profiles.py, submit_templates/
  ssh_transfer_jobs.py, remote_archive.py, quota.py
  runtime_setup.py         # auto-detection of external programs

  # ── Tool integrations ──
  tools/                   # step and pipeline system, 25 adapters, mcp_server.py
  mlp_tools/               # ML potentials (ANI-2x, MACE, CHGNet, M3GNet, …)
  ai_tools/                # AI/ML tool registry (21 tools across 9 categories)
  analysis_tools/          # cclib, Packmol, Multiwfn, CENSO, morfeus wrappers
  csp_tools/               # crystal structure generation (Genarris)
  qm_tools/                # external QM binary management

  # ── Interfaces ──
  dashboard/               # the browser dashboard (Voila / JupyterLab)
  agent/                   # the AI agent (engine, clients, tools, sandbox, memory)
  doc_server/              # MCP documentation server
  ops_server/              # MCP operations server
  installers/              # install_delfin.sh
  reporting/               # DOCX, JSON and text reports
  common/                  # logging, paths, ORCA block assembly

delfin/pipeline.py, global_manager.py, global_scheduler.py, dynamic_pool.py, job_priority.py and parallel_*.py still exist as backward-compatible shims that re-export from delfin/workflows/.

Global resource management

DELFIN coordinates all computational work through a global job-manager singleton:

Single source of truth — PAL is read once from CONTROL.txt and managed centrally
Automatic PAL splitting — parallel oxidation and reduction workflows share cores (PAL=12 → 6+6)
Thread-safe execution — a shared resource pool prevents race conditions
Subprocess coordination — OCCUPIER subprocesses inherit their limits through the environment

Tool integration pattern

Lazy loading — availability is checked with importlib.util.find_spec(); nothing is imported until used
Per-tool install — individual Install/Update buttons in the dashboard's Settings tab
Auto-detection — shutil.which() for binaries, compatible with cluster module systems
Unified interface — the calculator backends all return standard ASE Calculator objects

Automatic error recovery

ORCA failures are detected and repaired automatically, continuing from the last .gbw and geometry:

ORCA fails → detect the error type → modify the input → continue from the last .gbw and xyz → retry

Error	Automatic fix
SCF not converged	SlowConv → VerySlowConv + KDIIS
TRAH segfault	NoAutoTRAH
Geometry not converged	Smaller trust radius → looser criteria
MPI crashes	Fewer cores
Memory errors	Lower maxcore and PAL
Transient system errors	Exponential backoff

Enable it with enable_auto_recovery=yes; max_recovery_attempts (default 3) bounds the attempts per error type. See docs/RETRY_LOGIC.md for the complete guide.

🔌 External programs

DELFIN finds the 90+ supported programs by itself, in two ways: external binaries are looked for on PATH, through the module system and in the usual HPC directories — so module load gaussian/16 is all it takes — and Python packages are recognised by probing whether they import. Programs that cannot be pip-installed — ORCA, Gaussian, VASP, TURBOMOLE, Multiwfn and other licensed or externally managed software — are detected and reported, never installed.

Install and update buttons for the pip-installable integrations are in the dashboard under Settings → Tool Installation.

Of the AI/ML tools listed below, DELFIN detects and installs all of them, and architector, molSimplify and epic-MACE are additionally wired into structure generation (epic-MACE in an environment of its own); the others are made available for you to use, not called by a DELFIN workflow.

Linked overview of supported tools

ML Potentials (8): ANI-2x, AIMNet2, MACE-OFF, CHGNet, M3GNet/MatGL, SchNetPack, NequIP/Allegro, ALIGNN

QM Programs — Ab initio / DFT (11): ORCA, Gaussian (g16/g09), TURBOMOLE, NWChem, Q-Chem, GAMESS, Molpro, Dalton, Psi4, CFOUR, MRCC

QM Programs — Periodic / Solid State (11): VASP, Quantum ESPRESSO, CP2K, FHI-aims, CRYSTAL, SIESTA, GPAW, FLEUR, WIEN2k, Elk, ABINIT

QM Programs — Multireference (3): OpenMolcas, BAGEL, Columbus

Semi-empirical & Workflow Helpers (8): xTB, CREST, MOPAC, Sparrow, DFTB+, xTB4STDA, sTDA, sTD2

MD Engines (5): GROMACS, LAMMPS, AMBER, NAMD, OpenMM

AI/ML — Foundation Models (3): MoLFormer, Uni-Mol, ChemBERTa

AI/ML — Generative (2): REINVENT4, SyntheMol

AI/ML — Conformers (2): GeoMol, torsional-diffusion

AI/ML — Crystal Generation (2): MatterGen, CDVAE

AI/ML — Retrosynthesis (3): AiZynthFinder, RXNMapper, LocalRetro

AI/ML — Screening / ADMET (2): DeepChem, ADMETlab

AI/ML — Metal Complex ML (3): molSimplify, architector, epic-MACE

Analysis / Post-Processing (15): cclib, Multiwfn, CENSO, ANMR, c2anmr, nmrplot, morfeus, nglview, Packmol, NBO, AIMAll, critic2, Chargemol, LOBSTER, phonopy

Wrapper Libraries (5): ASE, pymatgen, QCEngine, MDAnalysis, pymolpro

Visualization (6): plotly, VMD, Avogadro, Jmol, ChimeraX, IQmol

Python-Only Backends (2): PySCF, PLAMS

Crystal Structure Prediction (1): Genarris

🖥️ Cluster and HPC

Backends: local execution, SLURM, SSH-based remote transfer
Automatic resource detection: CPUs and memory on SLURM/PBS/LSF
Site profiles: module names, node sizes and partitions per site, with automatic detection of the login node
Node-local staging: the virtual environment and ORCA are staged onto node-local disk so Python does not start off a network home
Scratch directory: DELFIN_SCRATCH=/path/to/scratch
Queue insight: partitions, pending reasons, fairshare and account limits in the Job Status tab
Logging: delfin_run.log per workspace, occupier.log per subprocess

Cluster templates: see examples/ for SLURM, PBS and LSF submit scripts.

🩺 Troubleshooting

CONTROL.txt not found — create it with delfin --define (or copy your own).
Input file not found — run delfin --define=your.xyz to convert an XYZ.
ORCA not found — check that orca is on your PATH (which orca), then delfin doctor.
CREST/xTB tools missing — install them and add them to PATH, or disable the corresponding flags in CONTROL.txt.
Optional tool not detected — check the dashboard's Settings tab, or run delfin doctor (and delfin qm_check, delfin mlp_check, delfin analysis_check for the specific families).
A SMILES run stops immediately — smiles_converter must be set to QUICK, NORMAL, MANTA, ARCHITECTOR, MOLSIMPLIFY or MACE.

🛠️ Development

CLI entry points are defined in pyproject.toml
Development install: pip install -e ".[agent,docs,dev]"
Run the fast test suite: pytest -m "not slow"
Format: black . · Lint: ruff check .
Build a wheel: pip wheel .

Contributions are welcome — see CONTRIBUTING.md. Security problems are reported privately, not as issues — see SECURITY.md.

References

The generic references for ORCA, xTB and CREST are:

Frank Neese. The ORCA program system. Wiley Interdiscip. Rev. Comput. Mol. Sci., 2(1):73–78, 2012. doi:https://doi.wiley.com/10.1002/wcms.81.
Frank Neese. Software update: the ORCA program system, version 4.0. Wiley Interdiscip. Rev. Comput. Mol. Sci., 8(1):e1327, 2018. doi:https://doi.wiley.com/10.1002/wcms.1327.
Frank Neese, Frank Wennmohs, Ute Becker, and Christoph Riplinger. The ORCA quantum chemistry program package. J. Chem. Phys., 152(22):224108, 2020. doi:https://aip.scitation.org/doi/10.1063/5.0004608.
Christoph Bannwarth, Erik Caldeweyher, Sebastian Ehlert, Andreas Hansen, Philipp Pracht, Jan Seibert, Sebastian Spicher, and Stefan Grimme. Extended tight-binding quantum chemistry methods. WIREs Comput. Mol. Sci., 11:e1493, 2021. doi:https://doi.org/10.1002/wcms.1493. (xTB & GFN methods)
Philipp Pracht, Stefan Grimme, Christoph Bannwarth, Florian Bohle, Sebastian Ehlert, Gunnar Feldmann, Jan Gorges, Max Müller, Timo Neudecker, Christoph Plett, Sebastian Spicher, Pascal Steinbach, Piotr A. Wesołowski, and Fabian Zeller. CREST — A program for the exploration of low-energy molecular chemical space. J. Chem. Phys., 160:114110, 2024. doi:https://doi.org/10.1063/5.0197592. (CREST)

Please always check the output files — at the end you will find a list of relevant papers for the calculations. Kindly cite them. Please do not only cite the generic references above, but also the original papers that report the development and ORCA implementation of the methods DELFIN has used. The publications that describe the functionality implemented in ORCA are given in the manual.

Dependencies and Legal Notice

DISCLAIMER: DELFIN is an agentic workflow framework that interfaces with external quantum chemistry software. Users are responsible for obtaining proper licenses for all required software.

ORCA Requirements

To use DELFIN, you must be authorized to use ORCA 6.1.1. You can download the latest version of ORCA here: https://orcaforum.kofo.mpg.de/app.php/portal

IMPORTANT: ORCA 6.1.1 requires a valid license and registration. Academic users can obtain free access, but commercial use requires a commercial license. Please carefully review and comply with ORCA's license terms before use. https://www.faccts.de/

ORCA License Requirements:

Academic use: Free after registration and license agreement
Commercial use: Requires commercial license
Users must register and agree to license terms before downloading
Redistribution of ORCA is prohibited
Each user must obtain their own license
DELFIN does not include or distribute ORCA
ORCA is proprietary software, developed at the Max-Planck-Institut für Kohlenforschung (Max Planck Institute for Coal Research) together with FACCTs GmbH (ORCA 6.1 manual, title page); its terms are those of the ORCA End User License Agreement
End users must comply with ORCA's terms of service and usage restrictions
DELFIN authors are not affiliated with or endorsed by the ORCA development team

xTB Requirements

xTB is free software under the GNU Lesser General Public License, version 3 or later (LGPL-3.0-or-later). The code and license are available here: https://github.com/grimme-lab/xtb (files COPYING and COPYING.LESSER)

The LGPL places no restriction on academic or commercial use; its conditions apply to modifying and redistributing xTB
DELFIN does not include or distribute xTB: it uses an xtb found on PATH, or delfin/qm_tools/install_qm_tools.sh installs one from conda-forge

CREST Requirements

CREST is free software under the GNU Lesser General Public License, version 3 or later (LGPL-3.0-or-later). The code and license are available here: https://github.com/crest-lab/crest (files COPYING and COPYING.LESSER)

The LGPL places no restriction on academic or commercial use; its conditions apply to modifying and redistributing CREST
DELFIN does not include or distribute CREST: it uses a crest found on PATH, or install_qm_tools.sh installs one from conda-forge

Other programs the installers download

install_qm_tools.sh and the terminal-window setup can also fetch xtb4stda and stda, std2, DFTB+ (LGPL-3.0-or-later), g-xTB (GPL-3.0), MOPAC (Apache-2.0) and Bun (MIT, with JavaScriptCore under LGPL-2.0) from their upstream. None of them is part of a DELFIN wheel or sdist. Their licences, and the notices of the code DELFIN does ship from other authors (3Dmol.js, the OpenTUI patches), are listed in THIRD_PARTY_NOTICES.md. Whoever redistributes a prepared installation that contains these programs (a container image, an environment archive, a cluster module) conveys them under their own licences.

Python dependencies with copyleft licences

Open Babel (openbabel-wheel, a core dependency) is licensed GPL-2.0-only. That does not restrict your own installation. It does mean that a bundle shipping DELFIN together with Open Babel (a container image, an environment archive, a cluster module) cannot meet both licences at once, so such a bundle should not be redistributed; let the target environment install Open Babel itself.
PyMuPDF is licensed AGPL-3.0 (or commercially by Artifex) and is therefore not installed by default. The file browser's PDF viewer, OCR page images and PDF previews in the chat need it: pip install "delfin-complat[pdf]". Without it the viewer and the OCR check say that PyMuPDF is missing and a chat card shows the file without a preview; PDF text, forms and merging keep working through pypdf.
The full list, with the reasoning, is in THIRD_PARTY_NOTICES.md section 3.

Legal Notice: DELFIN itself is licensed under LGPL-3.0-or-later, but this does not grant any rights to use ORCA, xTB, CREST or any other external program. Users must comply with the individual license terms of each external software package.

Warranty and Liability

DELFIN is provided "AS IS" without warranty of any kind. The authors disclaim all warranties, express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose. In no event shall the authors be liable for any damages arising from the use of this software.

Please cite

If you use DELFIN in a scientific publication, please cite the article and the software version you used. The same metadata are in CITATION.cff.

Hartmann, M.; Schoenle, F.; Wagner, J.; Herrmann, D.; Hodapp, P.; Jung, N.; Bräse, S. (2025). DELFIN: Automated DFT-based prediction of preferred spin states and corresponding redox potentials. ChemRxiv (preprint). https://doi.org/10.26434/chemrxiv-2025-4c256 · article page
Hartmann, M. (2026). DELFIN: Automated prediction of preferred spin states and associated redox potentials (v1.3.3). Zenodo. https://doi.org/10.5281/zenodo.17208144

The concept DOI 10.5281/zenodo.17208144 stands for all versions and resolves to the latest; each release has its own version DOI on Zenodo.

BibTeX

@article{hartmann2025chemrxiv,
  author  = {Hartmann, Maximilian and Schoenle, Fabian and Wagner, Jérome and Herrmann, David and Hodapp, Patrick and Jung, Nicole and Bräse, Stefan},
  title   = {DELFIN: Automated DFT-based prediction of preferred spin states and corresponding redox potentials},
  journal = {ChemRxiv},
  year    = {2025},
  doi     = {10.26434/chemrxiv-2025-4c256},
  url     = {https://www.cambridge.org/engage/chemrxiv/article-details/68fa0e233e6156d3be78797a}
}

@software{hartmann2026delfin,
  author    = {Hartmann, Maximilian},
  title     = {DELFIN: Automated prediction of preferred spin states and associated redox potentials},
  version   = {1.3.3},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.17208144},
  url       = {https://doi.org/10.5281/zenodo.17208144}
}

License

This project is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later).

The licence notice is in LICENSE. The full text of the GNU Lesser General Public License version 3 is in COPYING.LESSER; it supplements the GNU General Public License version 3, whose full text is in COPYING. Both files are also inside every wheel (*.dist-info/licenses/) and sdist. The texts are also published at https://www.gnu.org/licenses/.

Non-binding citation request: If you use this software in research, please cite the associated paper (see CITATION.cff).

Name		Name	Last commit message	Last commit date
.github		.github
LICENSES		LICENSES
delfin		delfin
docs		docs
env		env
examples		examples
literature		literature
scripts		scripts
tests		tests
tools		tools
tui		tui
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYING		COPYING
COPYING.LESSER		COPYING.LESSER
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
REUSE.toml		REUSE.toml
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
bench_audit_measure.py		bench_audit_measure.py
install.sh		install.sh
pyproject.toml		pyproject.toml
pyrightconfig.json		pyrightconfig.json
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

Design principles

What DELFIN can do

Use cases

Contents

🚀 Installation

Requirements

Install methods

Reference environment for reproducible MANTA builds

External QM tool setup

🏁 Quick start

The dashboard

The command line

Python

🧪 Dashboard

Running the dashboard

✨ Workflows

Redox potentials (OCCUPIER)

Stability constants (log K)

Excited-state dynamics (ESD)

TADF screening (xTB-based)

Spectroscopy and properties

Ensemble NMR via CREST + CENSO + ANMR

Imaginary-mode elimination (IMAG)

ML potentials and the calculator factory

Crystal structure generation (Genarris)

CO₂ coordinator

Reporting and export

🧬 Structure generation from SMILES

MANTA

Conformer search and sampling

⚙️ Configuration (CONTROL.txt)

Workflow control

Structure

Resource management

Optional modules

Error recovery

🤖 AI agents

Operating principles

Modes

Works with any tool-capable model

Network access and offline use

Subagents

Tools, MCP and safety

Slash commands

Memory and sessions

📋 CLI reference

Running a workflow

Setup and configuration

Diagnostics

Execution control

Cleanup and maintenance

Export and reporting

Specialised workflows

Companion commands

🏗️ Architecture

Package layout

Global resource management

Tool integration pattern

Automatic error recovery

🔌 External programs

🖥️ Cluster and HPC

🩺 Troubleshooting

🛠️ Development

References

Dependencies and Legal Notice

ORCA Requirements

xTB Requirements

CREST Requirements

Other programs the installers download

Python dependencies with copyleft licences

Warranty and Liability

Please cite

BibTeX

License

About

Topics