dyson-orca-tools

Python-based tool for computing Dyson orbitals from CASCI and CASSCF wavefunctions generated by the ORCA quantum chemistry package. It parses ORCA’s JSON-formatted wavefunction outputs to extract and process the relevant one-electron transition amplitudes.

Installation

pip install dyson-orca-tools            # core: Dyson orbitals, spectral functions, e-h maps
pip install "dyson-orca-tools[plot]"    # + matplotlib figures
pip install "dyson-orca-tools[cube]"    # + PySCF cube files

For development, clone the repository and install it editable with the test tools:

git clone https://github.com/AndresOrtegaGuerrero/dyson-orca-tools.git
cd dyson-orca-tools
pip install -e ".[dev,plot]"
pre-commit install

Usage

Three commands, in the order of a typical workflow:

# 1. build the parameters file from the ORCA outputs (CI vectors, root energies, active space)
dyson_orca_tools prepare -i neutral/out.out \
    -f cation/out.out:cation/mol.json \
    -f anion/out.out:anion/mol.json \
    -o results/params.json

# 2. Dyson orbitals + multireference spectral function
dyson_orca_tools spectrum -i neutral/mol.json -p results/params.json -o results \
    --eta 0.05 [--shift E_F] [--cube] [--plot [--vertical]]

# 3. re-plot later without recomputing
dyson_orca_tools plot -o results --title "pentacene CASCI(12,12)" [--vertical]

spectrum implements the spectral function of Kumar et al., JACS 2025, 147, 24993 (eq. 10):

ρ(ω) = η Σ_j |⟨Ψ±,j| a / a† |Ψ0⟩|² / ((ω − E_j)² + η²)

one peak per charged root j, with its Dyson orbital ϱ±,j and strength ⟨ϱ|ϱ⟩.

A single pair (one initial, one final state) is still available as dyson_orca_tools dyson -i initial.json -f final.json -p params.json.

prepare

Reads the ORCA output of the initial state (-i) and of each N±1 calculation (-f, repeatable) and writes the parameters file. Each -f names the ORCA output; its orca_2json file is taken as <name>.json next to it, or given explicitly after a colon: -f run/out.out:run/mol.json. Every MULT= block of an output becomes one run, so one output with mult 2,4 yields two runs. JSON paths are stored relative to the written parameters file.

The ORCA inputs need PrintWF det and a small TPrintWF (e.g. 1e-6) in %casscf; prepare prints Σc² per root so you can see how much the printout truncated.

spectrum outputs

Peaks are labelled ϱ−,j / ϱ+,j by increasing energy of the N±1 state within each side (j = 0 is the ground state of the ion); energies are relative to the initial ground state (removal negative, addition positive); --shift adds a rigid offset.

Orbitals: CASCI vs CASSCF

The tool detects from the MO overlap whether initial and final states share their orbitals. With one orbital set (CASCI, !MORead NoIter with ActOrbs/IntOrbs/ExtOrbs unchanged) the Dyson orbital is a pure active-space object. With separately optimized CASSCF orbitals the non-orthogonal branch is used, including the relaxation of the inactive orbitals via the core-block determinant (Schur complement); spectrum prints that determinant per run.

Parameters file

initial is the reference state (any charge/multiplicity); final is a list of runs, one per ORCA JSON (one orbital set and multiplicity), each with its roots. Energies in Hartree. Runs may differ from the initial state by ±1 electron and must change the multiplicity parity; spin-forbidden roots (|ΔS| ≠ ½) are accepted and give zero strength.

{
  "parameters": {
    "initial": {
      "nelc": 4, "norb": 4, "mult": 1, "energy": -230.5123,
      "spin_ci": {"[2200]": 0.957520133, "[2020]": -0.224387606, "[0202]": -0.063982267}
    },
    "final": [
      {"file": "../anion/mol.json", "nelc": 5, "norb": 4, "mult": 2,
       "roots": [
         {"energy": -230.4901, "spin_ci": {"[22u0]": 0.993890846, "[20u2]": -0.052026571}},
         {"energy": -230.4012, "spin_ci": {"[2u20]": 0.98}}
       ]},
      {"file": "../cation/mol.json", "nelc": 3, "norb": 4, "mult": 2,
       "roots": [{"energy": -230.2410, "spin_ci": {"[2u00]": 0.97}}]}
    ]
  }
}

The dyson command still accepts the old single-state format (final as one dict with spin_ci).

🧪 ORCA Instructions

To extract the required data from your CASSCF or CASCI calculations in ORCA, you must use the utility program orca_2json.

This tool converts ORCA wavefunction files into structured .json format for downstream processing.

🔧 Configuration File

You can create a basename-dependent configuration file, named:

BaseName.json.conf

📌 Notes

Replace BaseName with the actual name of your ORCA Basename described in your input (e.g., mol.gbw → mol.json.conf)

This file tells orca_2json which parts of the wavefunction to extract. You must include the molecular orbital coefficients and the overlap matrix.

Here is a recommended configuration:

{
  "MOCoefficients": true,
  "Basisset": true,
  "MullikenCharge": false,
  "LoewdinCharge": false,
  "1elIntegrals": ["S"],
  "JSONFormats": ["json"]
}

After that you can obtain json file from the calculations

orca_2json mol.gbw

Releasing

Releases are published to PyPI by GitHub Actions when a v* tag is pushed. From an up-to-date main:

bumpver update --patch    # or --minor / --major: bumps pyproject.toml + version.py, commits, tags and pushes

The release workflow then checks that the tag matches dyson_orca_tools.__version__, builds the sdist and wheel, uploads them to PyPI via trusted publishing, and creates a GitHub release with auto-generated notes.

Contact

If you have any questions or suggestions, feel free to reach out:

• Authors: Andres Ortega-Guerrero, Gonçalo Catarina
• Email: andres.ortega-guerrero@empa.ch , goncalo.catarina@empa.ch