Metadata-Version: 2.4
Name: dyson_orca_tools
Version: 0.1.0
Summary: Dyson orca tools package
Author-email: Andres Ortega Guerrero <andres.ortega-guerrero@empa.ch>, Gonçalo Catarina <goncalo.catarina@empa.ch>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: numpy
Requires-Dist: pyscf ; extra == "cube"
Requires-Dist: bumpver==2023.1129 ; extra == "dev"
Requires-Dist: pre-commit==3.6.0 ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: matplotlib ; extra == "plot"
Project-URL: Homepage, https://github.com/AndresOrtegaGuerrero/dyson-orca-tools
Project-URL: Issues, https://github.com/AndresOrtegaGuerrero/dyson-orca-tools/issues
Provides-Extra: cube
Provides-Extra: dev
Provides-Extra: plot

# 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

```shell
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:

```shell
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:

```shell
# 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

| file | content |
|---|---|
| `dyson_peaks.csv` | label, side (−/+), multiplicity, ω (eV), strength, branch (CASCI/CASSCF) |
| `dyson_composition.csv` | per peak: strength, Σc² of the root, leading determinant, and d_p² for every active MO (HOMO−k / LUMO+k of the initial state); the d_p² sum to the strength |
| `spectral_function.dat` | ω, ρ(ω) on a grid (`--omega-min/max`, `--npts`) |
| `dyson_orbitals_ao.txt` | one column of AO coefficients per peak (ORCA AO order) |
| `dyson_<side><j>_m<mult>.cube` | with `--cube`, needs `pip install "dyson-orca-tools[cube]"` (PySCF) |
| `spectral_function.png/.pdf` | with `--plot`, needs `pip install "dyson-orca-tools[plot]"` (matplotlib) |

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.

```json
{
  "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:

```shell
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:

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

After that you can obtain json file from the calculations

```bash
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`:

```shell
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](andres.ortega-guerrero@empa.ch) , [goncalo.catarina@empa.ch](goncalo.catarina@empa.ch)

