pyqirs 0.1.0

Package and command-line interface to extract quantum-informed representations for machine learning in chemistry

PyQIRS

pyqirs is a Python package and command-line interface (CLI) to create quantum-informed representations (QIRs) for machine learning in chemistry.

The current public descriptor implementation is MODA: a molecular-orbital density aggregation descriptor built from PySCF basis functions and a Huckel-type molecular-orbital construction.

Features

• Build Molecule objects from ASE atoms or extxyz files.
• Generate MODA descriptors from a consistent atom/orbital label space.
• Select specific molecular orbitals when computing MODA, for example frontier orbitals.
• Use spherical-average atomic RHF reference data through PySCF.
• Run descriptor generation from Python or from the command line.

Installation

We recommend installing pyqirs in a fresh conda environment:

conda create -n pyqirs_env "python>=3.11" pip
conda activate pyqirs_env

From PyPI, once released:

python -m pip install pyqirs

From a local clone:

git clone https://github.com/QTC-IQAC/pyqirs.git
cd pyqirs
python -m pip install .

For development:

python -m pip install -e ".[dev]"

Optional plotting dependencies can be installed with:

python -m pip install "pyqirs[plot]"

Requirements

pyqirs requires Python 3.11 or newer.

Core dependencies include:

• ase
• pyscf
• numpy
• scipy
• pandas
• click
• pyyaml

Python Usage

The examples below are meant to give a quick idea of the Python API. For complete, executable workflows, see the tutorial notebooks in the sister repository: https://github.com/QTC-IQAC/pyqirs-tutorials

For One Molecule

from pyqirs import Molecule, SphericalAverageRHFDict
from pyqirs.descriptors import MODA

# Select the basis set.
rhfdict = SphericalAverageRHFDict(basis="STO-3G")

# Create one Molecule from an extxyz file.
target, molecule = Molecule.from_extxyz("molecule.xyz",index=0,RHFDict=rhfdict)

# For one molecule, the MODA label space can be built directly from its basis.
moda = MODA(atoms_qns=molecule.get_basis_tuple())
labels, values = moda(molecule)

To compute MODA for selected molecular orbitals:

labels, values = moda(molecule, orbital_numbers=[10, 11])

The orbital indices refer to the molecular orbitals generated by pyqirs for that molecule.

For a Dataset // For a Fixed Type of Atoms

When comparing descriptors across many molecules, all molecules should use the same MODA space of atom-orbital pairs. Build that space once from the allowed chemical symbols, then reuse the same MODA instance for every molecule.

from pyqirs import Molecule, SphericalAverageRHFDict
from pyqirs.descriptors import MODA

rhfdict = SphericalAverageRHFDict(basis="STO-3G")

allowed_symbols = ["H", "C", "N", "O"]
atoms_qns = Molecule.get_tuple_for_symbols(symbols=allowed_symbols, RHFDict=rhfdict)
moda = MODA(atoms_qns=atoms_qns)

targets, molecules = Molecule.from_extxyz("dataset.xyz",index=":",RHFDict=rhfdict)

modas = []
for molecule in molecules:
    labels, values = moda(molecule)
    modas.append(values)

If a molecule contains an atom outside allowed_symbols, its descriptor will not include labels for that atom type. In dataset workflows, filter those molecules out or include all relevant elements in allowed_symbols.

Command Line Usage

After installation, the command-line interface is available as:

pyqirs --help
pyqirs get_moda --help

The legacy command name is also kept:

pyqirs_run --help

Tutorials

The examples and fuller workflows live in the sister tutorial repository:

https://github.com/QTC-IQAC/pyqirs-tutorials

That repository includes notebooks for quick-start usage, molecule loading, decorators, performance checks, and the command-line interface.

Development Checks

Useful local checks before publishing:

python -m compileall pyqirs tests
pytest
python -m build
twine check dist/*

License

This project is distributed under the MIT License. See LICENSE.

Citation

If you use MODA descriptors, please cite the original MODA article:

https://pubs.rsc.org/en/content/articlehtml/2023/dd/d3dd00187c

If you use pyqirs, please cite the PyQIRS ChemRxiv preprint:

https://chemrxiv.org/doi/full/10.26434/chemrxiv.15003485/v1

Contributing

The project is still maturing. Issues and suggestions are welcome, but please open a discussion before proposing large changes.