Metadata-Version: 2.4
Name: speccert
Version: 1.2.0
Summary: Checked UV-Vis and IR spectra from ORCA outputs and d-band moments from VASP DOSCAR files
Author-email: Andrés Monreal-Hernández <andres.monreal@ues.mx>
License: MIT
Project-URL: Homepage, https://github.com/sircalch/speccert
Project-URL: Documentation, https://github.com/sircalch/speccert#readme
Project-URL: Repository, https://github.com/sircalch/speccert.git
Project-URL: Bug Tracker, https://github.com/sircalch/speccert/issues
Project-URL: Changelog, https://github.com/sircalch/speccert/blob/main/CHANGELOG.md
Keywords: spectroscopy,uv-vis,td-dft,infrared-spectroscopy,raman-spectroscopy,density-of-states,pdos,d-band-center,electronic-structure,vibrational-scaling,orca,gaussian,vasp,computational-chemistry,reproducibility
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: jinja2>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# SpecCert

[![CI](https://github.com/sircalch/speccert/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/speccert/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22217588.svg)](https://doi.org/10.5281/zenodo.22217588)

SpecCert turns ORCA TD-DFT and frequency outputs into UV-Vis and IR spectra, and VASP DOSCAR files into d-band
moments, and checks the inputs on the way: whether the absorption maximum depends on how many excited states
were computed, whether a frequency scaling factor exists for the method and basis set, whether there are
imaginary modes, and whether the DOSCAR has d projections. A PASS means that these checks found nothing wrong;
it does not validate the level of theory.

## What it computes

| Part | Input | Output | Checks |
|---|---|---|---|
| UV-Vis | ORCA TD-DFT output (ORCA 5/6), Gaussian TD-DFT log (not validated), CSV | Gaussian-broadened molar absorption coefficient ε (L mol⁻¹ cm⁻¹), λmax | WARNING if all states are dark, if λmax lies at the window edge, or within 2 FWHM of the highest computed state (where uncomputed states would also absorb) |
| IR | ORCA frequency output (frequencies, IR intensities, level of theory read from the input echo), CSV, or a list of frequencies | scaled frequencies; Lorentzian-broadened IR spectrum (km mol⁻¹ per cm⁻¹) when intensities are given | scaling factor looked up by method **and** basis set in NIST CCCBDB; WARNING and no scaling if not tabulated; WARNING if there are no intensities (no spectrum is made); FAIL with imaginary modes |
| d band | VASP DOSCAR (plain or .gz; ISPIN 1 or 2; LORBIT 10 or 11, with or without f), CSV | centre of the occupied part and of the whole d band, width (square root of the second central moment) of the occupied part, filling | d projections summed over both spins and over all ions (or `--ions`); WARNING without projections or if the grid stops less than 2 eV above E_F |

ε follows from the oscillator strengths through f = 4.319 × 10⁻⁹ ∫ε dν̃ (ν̃ in cm⁻¹), so the broadened
spectrum integrates back to Σf.

## Validation (`validation/`)

Every number below is regenerated by the scripts in `validation/`.

- **UV-Vis** (`benchmark_uv_ir.py`): eight molecules (formaldehyde, acetone, acrolein, butadiene, hexatriene,
  benzene, pyridine, naphthalene) with ORCA 6.1.1 TD-DFT (B3LYP-D3(BJ)/def2-SVP, 15 states). ε agrees with
  ORCA's own `orca_mapspc` spectrum to 1.2 × 10⁻⁴ (relative, wherever ε exceeds 1% of its maximum); integrating
  the spectrum returns Σf to 8 × 10⁻¹⁰. Versions 1.0.0 and 1.1.0 used a prefactor of 2.174 × 10⁴ instead of
  2.8706 × 10⁴: their ε was 0.757 times the correct value. Version 1.0.0 found no transitions in ORCA 6 outputs.
- **IR** (`benchmark_uv_ir.py`): frequencies and intensities read from the eight frequency outputs agree with
  the `.hess` files (0 and 0.005 km/mol); the broadened spectra integrate to the summed intensities.
- **Scaling factors** (`extract_cccbdb.py`): the 299 factors of the CCCBDB table for 16 methods. Versions 1.0.0
  and 1.1.0 applied one factor per functional whatever the basis set (B3LYP 0.9679, while CCCBDB lists 0.892–0.975
  across basis sets), matched functional names by substring (wB97X-D3 received the wB97X-D factor) and used 0.965
  for unknown methods. Their command line accepted frequencies only and gave every mode an IR intensity of
  50 km/mol.
- **d band** (`fetch_nomad_doscar.py`, `benchmark_dos.py`): nine real VASP calculations from NOMAD (CC BY 4.0;
  bulk Cu, Ag, Ni, Pt, Fe, Co and the spin-polarised clusters Fe₃₉, Ni₄₇, Co₁₈). The d-band centres, width and
  filling read from DOSCAR agree with pymatgen 2026.9.24 reading the vasprun.xml of the same calculations to
  0.002 eV (0.0006 in filling). Versions 1.0.0 and 1.1.0 used the first ion only, the spin-up total DOS, and the
  wrong columns for spin-polarised projections: on the clusters their occupied d-band centre was off by
  −0.22 to −0.77 eV.

### Not validated
- Gaussian TD-DFT parser (no Gaussian installation was available); Raman activities are stored but not broadened.

## Installation

```bash
pip install "git+https://github.com/sircalch/speccert@v1.2.0"
```

From source:

```bash
git clone https://github.com/sircalch/speccert.git
cd speccert
pip install -e .[dev]
```

## Command line

```bash
# ORCA TD-DFT and frequency outputs (level of theory read from the outputs)
speccert assess --input-uv tddft.out --input-ir freq.out --system acrolein -o report/

# a scaling factor of your own (e.g. for a basis set not in CCCBDB)
speccert assess --input-ir freq.out --scaling-factor 0.965 -o report/

# VASP DOSCAR, d projections of ions 1-4 only
speccert assess --input-dos DOSCAR --ions 1,2,3,4 -o report/

# synthetic demonstration (not a real calculation)
speccert demo -o demo/
```

The report directory contains `report.html`, figures, a summary table (CSV and LaTeX), a draft methods paragraph
stating what was found, and `citation.bib`.

## Python

```python
from speccert.parsers.orca_tddft import parse_orca_tddft_output
from speccert.parsers.orca_freq import parse_orca_freq_output
from speccert.parsers.vasp_doscar import parse_vasp_doscar
from speccert.core.uv_vis import calculate_uv_vis_spectrum
from speccert.core.vibrational import calculate_scaled_vibrational_spectrum
from speccert.core.dos_dband import calculate_dos_and_dband_center

t = parse_orca_tddft_output("tddft.out")
uv = calculate_uv_vis_spectrum(t["energies_ev"], t["oscillator_strengths"], fwhm_ev=0.30)

f = parse_orca_freq_output("freq.out")
ir = calculate_scaled_vibrational_spectrum(f["frequencies_cm1"], f["ir_intensities_km_mol"],
                                           functional=f["method"], basis=f["basis"])

d = parse_vasp_doscar("DOSCAR")
dband = calculate_dos_and_dband_center(d["energies_ev"], d["total_dos"], d["projected_d_dos"], d["fermi_energy_ev"])
print(uv.status, ir.status, dband.status, dband.d_band_center_filled_ev)
```

## Citation

`speccert cite` prints the APA and BibTeX entries for the installed version (concept DOI 10.5281/zenodo.22217588).
CCCBDB: NIST Computational Chemistry Comparison and Benchmark Database, NIST Standard Reference Database 101.

## License

MIT, see [LICENSE](LICENSE).
