dyson-orca-tools 0.1.0__tar.gz

dyson_orca_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andres Ortega-Guerrero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dyson_orca_tools-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+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)
+

dyson_orca_tools-0.1.0/README.md

@@ -0,0 +1,163 @@
+# 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)

dyson_orca_tools-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "dyson_orca_tools"
+
+[project]
+name = "dyson_orca_tools"
+dynamic = ["version", "description"]
+authors = [
+    {name = "Andres Ortega Guerrero", email = "andres.ortega-guerrero@empa.ch"},
+    {name = "Gonçalo Catarina", email = "goncalo.catarina@empa.ch"}
+
+]
+readme = "README.md"
+license = {file = 'LICENSE'}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typer",
+    "numpy",
+]
+
+
+
+[project.optional-dependencies]
+cube = [
+  "pyscf",
+]
+plot = [
+  "matplotlib",
+]
+dev = [
+  "bumpver==2023.1129",
+  "pre-commit==3.6.0",
+  "pytest",
+
+]
+
+[project.urls]
+Homepage = "https://github.com/AndresOrtegaGuerrero/dyson-orca-tools"
+Issues = "https://github.com/AndresOrtegaGuerrero/dyson-orca-tools/issues"
+
+[project.scripts]
+dyson_orca_tools = 'dyson_orca_tools.cli.main:app'
+
+[tool.bumpver]
+current_version = "v0.1.0"
+version_pattern = "vMAJOR.MINOR.PATCH[PYTAGNUM]"
+commit_message = "Bump version {old_version} -> {new_version}."
+tag_message = "Release {new_version}."
+tag_scope = "default"
+pre_commit_hook = ""
+post_commit_hook = ""
+commit = true
+tag = true
+push = true
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = [
+    'current_version = "{version}"',
+]
+"src/dyson_orca_tools/version.py" = [
+    '__version__ = "{pep440_version}"',
+]

dyson_orca_tools-0.1.0/src/dyson_orca_tools/__init__.py

@@ -0,0 +1,6 @@
+"Dyson orca tools package"
+
+from .version import __version__
+
+
+__all__ = ["__version__"]

dyson_orca_tools-0.1.0/src/dyson_orca_tools/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI for dyson_orca_tools."""