Skip to main content

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.

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)

Source distribution for pyqirs 0.1.0
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)

Table of built distributions (wheels) for pyqirs 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page