DELFIN

📄 Preprint: Hartmann, M. et al. "DELFIN: Automated DFT-based prediction of preferred spin states and corresponding redox potentials", ChemRxiv (2025). https://doi.org/10.26434/chemrxiv-2025-4c256

DELFIN is a modular computational chemistry platform that automates end-to-end molecular workflows — from SMILES input to realistic property predictions. It combines structure generation, DFT, semi-empirical methods, ML potentials, and AI tools behind a unified interface with an interactive browser-based dashboard.

What DELFIN can do

Capability	Description
Redox Potentials	Automated spin-state prediction and redox potential calculation via OCCUPIER/classic workflows
Thermodynamics Simulations	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	ISC/RISC rates, fluorescence, phosphorescence, SOC coupling, E₀₀ energies, ΔE(S-T) gaps
TADF Screening	xTB-based singlet-triplet gap estimation for OLED material discovery
Spectroscopy	UV-Vis absorption, IR vibrational spectra, AFP (absorption/fluorescence/phosphorescence) plots
Hyperpolarizability	Static and frequency-dependent β tensors for NLO materials
Structure Generation	SMILES→3D for organic molecules and metal complexes (RDKit, Open Babel, architector, PSO builder)
Conformer Sampling	GUPPY multi-start sampling, CREST conformer search, XTB-GOAT global optimization
ML Potentials	8 backends (ANI-2x, MACE, CHGNet, M3GNet, ...) for fast energy/force evaluation
Crystal Structure Prediction	Genarris integration for random crystal generation
CO2 Coordination	Automated CO2 placement, distance/rotation scans
Reporting	DOCX reports with embedded spectra, JSON export, text summaries

🚀 Installation

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

Requirements

Python 3.10 or 3.11
ORCA 6.1.1 in your PATH (orca and orca_pltvib) — free for academic use
Optional: crest and xtb (for CREST/xTB workflows)
Optional: censo, anmr, c2anmr, and nmrplot (for ensemble-averaged NMR workflows)
Optional: xtb4stda, stda, and std2 plus the required xtb4stda runtime files (for xTB-based response/screening workflows)
Optional: Any of the 88 supported computational tools — auto-detected via PATH, installable via Dashboard
Optional (Dashboard): JupyterLab/Notebook or Voila for interactive UI usage

Install Methods

Standard install (recommended for most users):

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 .

All Python dependencies (e.g., RDKit/OpenBabel for SMILES workflows, ipywidgets/py3Dmol for dashboard visualisation) are installed automatically.

This exposes the console command delfin and enables python -m delfin.

External QM binaries are not installed automatically 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

After installing the Python package, initialise the bundled QM tool wrapper and validate the external binaries:

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

Quick start

Create a working directory with at least these two files:

CONTROL.txt — your control/config file
input.txt — either
- XYZ body (without the first two header lines), or
- a single-line SMILES string
starting from a full .xyz file is optional (delfin --define=input.xyz auto-converts)

Then run:

from the directory that contains CONTROL.txt and input.txt

delfin

alternatively

python -m delfin

You can also point DELFIN at a different workspace directory:

delfin /path/to/project

Results and reports are written to the current working directory, e.g. DELFIN.txt, OCCUPIER.txt, and per-step folders.

🧪 Dashboard

Start in Jupyter/Voila and create the dashboard from Python:

from delfin.dashboard import create_dashboard
ctx = create_dashboard(backend="auto")

backend="auto" selects SLURM if available, otherwise local execution.

Dashboard Tabs

Tab	Purpose
Submit Job	SMILES/XYZ input, 3D preview, `CONVERT SMILES`, `QUICK CONVERT`, `CONVERT + UFF`, `BUILD COMPLEX`, `ARCHITECTOR`, `SUBMIT GUPPY`
Recalc	Edit and resubmit existing CONTROL.txt
ORCA Builder	Interactive ORCA input generation with geometry preview
TURBOMOLE Builder	Turbomole define workflow (SLURM backends)
Job Status	Real-time queue monitoring (local/SLURM), resource usage, job cancellation
Calculations	File browser, search, recalculation trigger, energy statistics, browser-launched workflows such as `Calc NMR` and `Calc ANMR`
Archive	Archive browser with statistics
Settings	Tool detection, per-tool Install/Update buttons, runtime configuration

GUI with Voila

delfin-voila                 # starts on localhost:8866
delfin-voila --port 9000     # custom port
delfin-voila --ip 0.0.0.0    # bind to all interfaces if required
delfin-voila --dark          # dark theme

Detailed documentation: docs/SETTINGS_AND_SETUP.md

✨ Features

Redox Potential Prediction (OCCUPIER)

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

Multi-step redox: Up to 3 sequential oxidation/reduction steps
Parallel workflows: Oxidation and reduction run simultaneously with automatic PAL splitting
Smart recalc: Fingerprint-based skip logic avoids unnecessary reruns

Thermodynamics Simulations

DELFIN can run thermodynamics simulations for coordination complexes, including stability-constant (log K) prediction from a Born-Haber-type thermodynamic cycle:

Automatic reaction analysis: Extracts unique ligands, denticities, displaced solvent count, and the matching metal-solvent reference complex directly from complex SMILES
OCCUPIER-aware metal treatment: Both the target complex and the solvated metal reference can use the same converter, preoptimization, multiplicity, and broken-symmetry logic as the main workflow
Efficient sub-workflows: Duplicate ligands are detected and computed only once, while ligand, solvent, and metal-solvent jobs run in parallel
Free-energy output: Combines OPT+FREQ free energies for complex, solvated metal, ligand(s), and solvent into ΔG and log K

Excited-State Dynamics (ESD)

The ESD module calculates photophysical properties:

Electronic states: S0, S1, S2, T1, T2 geometry optimization
ISC / RISC rates: Intersystem and reverse intersystem crossing - Internal conversion (IC): Non-radiative decay rates
Fluorescence & phosphorescence rates: Radiative lifetimes including per-sublevel phosphorescence
E₀₀ energies: Adiabatic 0-0 transition energies
ΔE(S-T): Singlet-triplet energy gaps

ESD_modul=yes
states=S0,S1,T1,T2
ISCs=S1>T1,T1>S1
ICs=S1>S0

TADF Screening (xTB-based)

Fast screening of TADF candidates using semi-empirical methods:

S0/T1 optimization via xTB, S1 estimation via Stokes shift
ΔE(S-T) gap calculation
First allowed singlet state detection
TADF efficiency metrics

Spectroscopy & 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 spectrum plot
Hyperpolarizability	Static & frequency-dependent β tensors (NLO), dipole moments

Ensemble NMR via CREST + CENSO + ANMR

DELFIN includes a browser-launched ensemble NMR workflow for .xyz inputs:

Calc NMR: single-structure ORCA NMR workflow
Calc ANMR: end-to-end ensemble workflow based on CREST -> CENSO -> c2anmr -> ANMR

The ensemble workflow:

starts from an input .xyz geometry
performs CREST conformer sampling with -nmr
re-ranks and refines the ensemble with CENSO
runs ORCA-based NMR shieldings/couplings for the surviving conformers
builds Boltzmann-weighted ANMR spectra
writes PNG, PDF, SVG, and JSON/text summaries into the workflow folder

The required helper tools (censo, anmr, c2anmr, nmrplot) are detected in DELFIN's shared runtime layer and can be installed or updated from the Dashboard Settings tab. When a supported analysis tool is missing, DELFIN can also auto-install it on first use in the workflow.

SMILES→3D Structure Generation

DELFIN provides multiple conversion methods for organic and metal-containing systems:

Button	Method	Best for
`CONVERT SMILES`	Full isomer/conformer search (RDKit + Open Babel)	Thorough exploration
`QUICK CONVERT`	Fast single-conformer generation	Quick previews
`CONVERT + UFF`	Full search + UFF force-field refinement	Refined geometries
`BUILD COMPLEX`	ORCA/XTB DOCKER stepwise complex assembly	Metal complexes (job submission)
`ARCHITECTOR`	architector automated 3D generation	Metal complexes (instant preview)
`SUBMIT GUPPY`	Multi-start XTB sampling with ranked trajectories	Robust start structures

For coordination complexes, DELFIN combines Open Babel conformer pools, RDKit multi-seed embedding, topological isomer enumeration, and fragment sanity checks.

ML Potentials & Unified Calculator Factory

34 computational backends accessible through a single interface returning standard ASE Calculator objects:

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()

Automatic CUDA validation with CPU fallback. All backends are lazily loaded — only imported when actually used.

AI/ML Tools Integration

21 AI/ML tools across molecular generation, retrosynthesis, screening, and metal complex design — all behind runtime validation with per-tool Install/Update buttons in the Dashboard Settings tab.

Auto-Detection of External Programs

DELFIN automatically detects 88 computational chemistry programs via PATH search. This works seamlessly with cluster module systems (module load gaussian/16 → DELFIN detects it). Programs that can't be pip-installed (ORCA, Gaussian, VASP, Turbomole, ...) are detected and reported but not installed.

Install/update buttons for pip-installable integrations are available in the Dashboard under Settings -> Tool Installation. Licensed or externally managed binaries such as ORCA, Gaussian, VASP, and TURBOMOLE are detected and reported by DELFIN, but not installed by the dashboard.

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 (2): molSimplify, architector

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

Conformer Search & Sampling

CREST: Conformer-rotamer ensemble generation and sorting
XTB-GOAT: Gradient-based global optimization
GUPPY: Multi-start SMILES sampling with parallel XTB optimization and energy-ranked trajectories

Crystal Structure Prediction (CSP)

Genarris integration for random crystal structure generation with configurable space groups, Z values, and MPI-parallel execution.

CO2 Coordinator

Automated CO2 placement around metal centers with relaxed distance scans (1.6–4.0 Å) and rotation scans (±180°).

Reporting & Export

Format	Command	Content
Text	automatic	`DELFIN.txt` (redox potentials), `OCCUPIER.txt` (occupation tracking), `ESD_report.txt`
DOCX	`delfin --report docx`	Word document with embedded spectra plots and structured tables
JSON	`delfin --json`	Machine-readable `DELFIN_Data.json` with all energies, rates, spectra
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
AFP	`delfin --afp`	Absorption/fluorescence/phosphorescence combined plot

📋 CLI Reference

Basic Commands

delfin — Run DELFIN workflow in current directory (requires CONTROL.txt and input.txt)
delfin /path/to/project — Run DELFIN workflow in specified directory
python -m delfin — Alternative way to run DELFIN

Companion CLI Tools

delfin-build [input.txt] — Build metal complexes stepwise from SMILES using ORCA/XTB Docker workflow
delfin-guppy [input.txt] — Multi-start SMILES sampling workflow with repeated XTB optimization and ranked trajectories
delfin-voila — Launch the DELFIN Dashboard as a standalone web app via Voila
delfin-json — Collect DELFIN project outputs into JSON
delfin_ESD — UV-Vis spectrum report from ORCA ESD output
delfin_IR — IR spectrum report from ORCA frequency output

Setup & Configuration

delfin --define[=input.xyz] [--overwrite] — Create/update CONTROL.txt and optionally convert XYZ to input.txt
delfin /path/to/project --define[=input.xyz] [--overwrite] — Same as above, but in a different workspace directory
delfin --control /path/to/CONTROL.txt — Run workflow from another directory while normalising all paths

Execution Control

delfin --recalc — Re-parse existing results and only restart missing or incomplete jobs
delfin WORKSPACE --recalc --occupier-override STAGE=INDEX — Force a specific OCCUPIER index for a stage during recalc
delfin --report — Re-calculate redox potentials from existing output files without launching new calculations
delfin --imag — Eliminate imaginary modes from existing ORCA results (*.out/*.hess) and regenerate the summary report
delfin stop --workspace PATH — Send a graceful stop signal to running DELFIN processes associated with a workspace

Cleanup & Maintenance

delfin --no-cleanup — Keep temporary files and scratch folders after the pipeline finishes
delfin --cleanup — Remove previously generated intermediates and exit immediately
delfin cleanup [--dry-run] [--workspace PATH] [--scratch PATH] — Fine control over workspace/scratch cleanup
delfin cleanup --orca — Stop running ORCA jobs, purge OCCUPIER scratch folders
delfin --purge — Remove DELFIN-generated artifacts after confirmation

Export & Reporting

delfin --json — Collect key results into DELFIN_Data.json
delfin --report docx — Generate a Word report in DOCX format
delfin --afp — Generate an AFP spectrum plot from existing ESD results

Specialized Workflows

delfin co2 ... — CO2 Coordinator helper workflow
delfin ESD — Run excited-state dynamics workflow (requires ESD_modul=yes in CONTROL)
delfin-guppy --runs N --parallel-jobs M --pal P — Broadened start-structure sampling
delfin-build --goat [--no-ligand-goat] — Ligand docking with optional GOAT optimization

⚙️ Configuration (CONTROL.txt)

DELFIN is configured via CONTROL.txt in your working directory. Key settings include:

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

Resource Management

pal_jobs = N (number of parallel PAL processes; auto-detected from cluster if not set)
orca_parallel_strategy = auto | threads | serial

Optional Modules

XTB_OPT = yes | no / XTB_GOAT = yes | no / CREST = yes | no
XTB_SOLVATOR = yes | no
ESD_modul = yes | no (excited-state dynamics)
- states = S0,S1,T1,T2
- ISCs = S1>T1,... / ICs = S1>S0,...
IMAG = yes | no (imaginary frequency elimination)
- IMAG_scope = initial | all
- allow_imaginary_freq = N

Error Recovery

enable_auto_recovery = yes | no (intelligent ORCA error recovery with MOREAD)
max_recovery_attempts = N (default: 1)
enable_job_timeouts = yes | no (set to 'no' for unlimited runtime)

🏗️ Architecture

Global Resource Management

DELFIN uses a global job manager singleton to coordinate all computational workflows:

Single source of truth: PAL is read once from CONTROL.txt and managed centrally
Automatic PAL splitting: Parallel ox/red workflows share cores (PAL=12 → 6+6)
Thread-safe execution: Shared resource pool prevents race conditions
Subprocess coordination: OCCUPIER subprocesses inherit limits via environment variables

Modular Tool Architecture

delfin/
  calculators.py       ← Unified ASE calculator factory (34 backends)
  mlp_tools/           ← ML potential backends with lazy loading
  ai_tools/            ← AI/ML tools registry and per-tool installers
  analysis_tools/      ← Analysis wrappers (cclib, Packmol, Multiwfn, CENSO, ANMR, ...)
  csp_tools/           ← Crystal structure prediction (Genarris)
  runtime_setup.py     ← Auto-detection of 88 external programs
  dashboard/           ← 10-tab interactive dashboard (Voila/JupyterLab)

All tool integrations follow the same pattern:

Lazy loading — importlib.util.find_spec() for availability checks, no imports until use
Per-tool install — Individual Install/Update buttons in Dashboard Settings
Auto-detection — shutil.which() for binaries, compatible with cluster module systems
Unified interface — All backends return standard ASE Calculator objects

Cluster & HPC Integration

Backends: Local execution, SLURM, SSH-based remote transfer
Auto-resource detection: CPUs and memory on SLURM/PBS/LSF clusters
Scratch directory: DELFIN_SCRATCH=/path/to/scratch
Logging: delfin_run.log per workspace, occupier.log per subprocess
Programmatic API: delfin.api.run(control_file="CONTROL.txt") for notebooks and workflow engines

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

🔧 Automatic Error Recovery & Retry System

DELFIN includes an intelligent error recovery system that automatically detects and fixes common ORCA calculation failures.

Quick Enable

enable_auto_recovery=yes
max_recovery_attempts=1

How It Works

ORCA fails → Detect error type → Modify input with fixes → Continue from last .gbw and xyz → Retry

Error	Automatic Fix
SCF not converged	SlowConv → VerySlowConv + KDIIS
TRAH segfault	NoAutoTRAH
Geometry not converged	Smaller trust radius → Loose criteria
MPI crashes	Reduce cores
Memory errors	Reduce maxcore and PAL
Transient system errors	Exponential backoff retry

See docs/RETRY_LOGIC.md for the complete guide.

Troubleshooting

CONTROL.txt not found — Create it via delfin --define (or copy your own).
Input file not found — Run delfin --define=your.xyz to auto-convert.
ORCA not found — Ensure orca is in your PATH: which orca.
CREST/xTB tools missing — Disable corresponding flags in CONTROL.txt or install and add to PATH.
Optional tool not detected — Check Dashboard Settings tab or run delfin --diagnostics.

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 above generic references, but also cite in addition 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 a workflow tool 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 owned by the Max Planck Institute for Coal Research
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 for academic use under the GNU General Public License (GPLv3). The code and license information are available here: https://github.com/grimme-lab/xtb

Commercial use may require different licensing terms
DELFIN does not include or distribute xTB

CREST Requirements

CREST is free for academic use under the GNU General Public License (GPLv3). The code and license information are available here: https://github.com/crest-lab/crest

Commercial use may require different licensing terms
DELFIN does not include or distribute CREST

Legal Notice: DELFIN itself is licensed under LGPL-3.0-or-later, but this does not grant any rights to use ORCA, xTB, or CREST. 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:

Hartmann, M. (2026). DELFIN: Automated DFT-based prediction of preferred spin states and corresponding redox potentials (v1.1.0). Zenodo. https://doi.org/10.5281/zenodo.17208145
Hartmann, M. (2025). DELFIN: Automated prediction of preferred spin states and redox potentials. ChemRxiv. https://chemrxiv.org/engage/chemrxiv/article-details/68fa0e233e6156d3be78797a

BibTeX

@software{hartmann2025delfin,
  author  = {Hartmann, Maximilian},
  title   = {DELFIN: Automated DFT-based prediction of preferred spin states and corresponding redox potentials},
  version = {v1.1.0},
  year    = {2026},
  publisher = {Zenodo},
  doi     = {10.5281/zenodo.17208145},
  url     = {https://doi.org/10.5281/zenodo.17208145}
}

@article{hartmann2025chemrxiv,
  author  = {Hartmann, Maximilian},
  title   = {DELFIN: Automated prediction of preferred spin states and redox potentials},
  journal = {ChemRxiv},
  year    = {2025},
  url     = {https://chemrxiv.org/engage/chemrxiv/article-details/68fa0e233e6156d3be78797a}
}

📚 Appendix (For Developers)

Project Layout

delfin/
  __init__.py
  __main__.py              # enables `python -m delfin`
  cli.py                   # main CLI entry point
  pipeline.py              # high-level orchestration (classic/manually/OCCUPIER)
  config.py                # CONTROL.txt parsing & helpers
  calculators.py           # unified ASE calculator factory (34 backends)
  api.py                   # programmatic API for notebooks/workflows

  # ── Core Workflows ──
  occupier.py              # OCCUPIER workflow (sequence execution + summary)
  occupier_auto.py         # auto OCCUPIER sequence management and tree navigation
  deep_auto_tree.py        # adaptive BS evolution tree
  esd_module.py            # excited-state dynamics (ISC/IC/fluorescence/phosphorescence)
  esd_input_generator.py   # ORCA input builders for ESD states
  tadf_xtb.py              # TADF screening via xTB
  hyperpol.py              # hyperpolarizability (NLO)
  xtb_crest.py             # xTB / GOAT / CREST / ALPB solvation workflows
  imag.py                  # imaginary frequency elimination
  guppy_sampling.py        # multi-start SMILES sampling + ranking
  build_up_complex.py      # stepwise metal-complex assembly (ORCA/XTB DOCKER)
  build_up_complex2.py     # PSO-based metal complex builder

  # ── Resource Management ──
  global_manager.py        # singleton global job manager
  global_scheduler.py      # dynamic shared resource scheduling
  dynamic_pool.py          # dynamic core pool for job scheduling
  cluster_utils.py         # SLURM/PBS/LSF resource detection
  runtime_setup.py         # auto-detection of 88 external programs

  # ── Tool Integrations ──
  mlp_tools/               # ML potentials (ANI-2x, MACE, CHGNet, M3GNet, ...)
  ai_tools/                # AI/ML tools (21 tools across 9 categories)
  analysis_tools/          # analysis wrappers (cclib, Packmol, Multiwfn, CENSO, morfeus)
  csp_tools/               # crystal structure prediction (Genarris)
  qm_tools/                # external QM binary management

  # ── Dashboard ──
  dashboard/               # 10-tab interactive dashboard (Voila/JupyterLab)

  # ── Reporting ──
  reporting/               # DOCX, JSON, text report generation
  co2/                     # CO2 coordinator workflows

  # ── Shared ──
  common/                  # logging, paths, ORCA block assembly

Development Notes

CLI entry points are defined in pyproject.toml
Build a wheel: pip wheel .
Install development tools: pip install -e '.[dev]'
Format code: black . / Lint code: ruff check .

License

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

You should have received a copy of the GNU Lesser General Public License along with this repository in the files COPYING and COPYING.LESSER. If not, see 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
Latest commit History 1,209 Commits
delfin		delfin
docs		docs
examples		examples
scripts		scripts
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
delfin_dashboard.ipynb		delfin_dashboard.ipynb
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

DELFIN

What DELFIN can do

🚀 Installation

Requirements

Install Methods

External QM Tool Setup

Quick start

🧪 Dashboard

Dashboard Tabs

GUI with Voila

✨ Features

Redox Potential Prediction (OCCUPIER)

Thermodynamics Simulations

Excited-State Dynamics (ESD)

TADF Screening (xTB-based)

Spectroscopy & Properties

Ensemble NMR via CREST + CENSO + ANMR

SMILES→3D Structure Generation

ML Potentials & Unified Calculator Factory

AI/ML Tools Integration

Auto-Detection of External Programs

Conformer Search & Sampling

Crystal Structure Prediction (CSP)

CO2 Coordinator

Reporting & Export

📋 CLI Reference

Basic Commands

Companion CLI Tools

Setup & Configuration

Execution Control

Cleanup & Maintenance

Export & Reporting

Specialized Workflows

⚙️ Configuration (CONTROL.txt)

Workflow Control

Resource Management

Optional Modules

Error Recovery

🏗️ Architecture

Global Resource Management

Modular Tool Architecture

Cluster & HPC Integration

🔧 Automatic Error Recovery & Retry System

Quick Enable

How It Works

Troubleshooting

References

Dependencies and Legal Notice

ORCA Requirements

xTB Requirements

CREST Requirements

Warranty and Liability

Please cite

BibTeX

📚 Appendix (For Developers)

Project Layout

Development Notes

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages