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
Moleculeobjects from ASE atoms orextxyzfiles. - 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:
asepyscfnumpyscipypandasclickpyyaml
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.
Metadata
Release files for pyqirs 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyqirs-0.1.0.tar.gz | 24.3 kB | Without provenance | Details for pyqirs-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyqirs-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pyqirs-0.1.0-py3-none-any.whl |
Total release size: 51.3 kB
Release files / pyqirs-0.1.0.tar.gz
| Download URL | pyqirs-0.1.0.tar.gz |
|---|---|
| Size | 24.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
382a42a23a1e17d8aa1981994e3b5552ee049241495bfa457e041c823cf90ace
|
|
BLAKE2b-256 checksum How to use checksums |
a6850c36e6691962eb043bba8ab57d0c6e4f89bb236e61a29cb41fa4beb15f65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.1
|
Release files / pyqirs-0.1.0-py3-none-any.whl
| Download URL | pyqirs-0.1.0-py3-none-any.whl |
|---|---|
| Size | 26.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c238a097bbc50fd20836252d609f0a84f43ba126c92d3fc481d30d6bdaf221e7
|
|
BLAKE2b-256 checksum How to use checksums |
01218b363d765f1bedebbcca0fa19f621f1897e68e045c7d60f569ddb15b9aa0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.1
|
Security for pyqirs 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.