Metadata-Version: 2.4
Name: pyqirs
Version: 0.1.0
Summary: Package and command-line interface to extract quantum-informed representations for machine learning in chemistry
Author-email: Raul Santiago <rsantiago.works@gmail.com>, Sergi Vela <sergi.vela@gmail.com>
Maintainer-email: Raul Santiago <rsantiago.works@gmail.com>, Sergi Vela <sergi.vela@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/QTC-IQAC/pyqirs
Project-URL: Repository, https://github.com/QTC-IQAC/pyqirs
Project-URL: Tutorials, https://github.com/QTC-IQAC/pyqirs-tutorials
Project-URL: Issues, https://github.com/QTC-IQAC/pyqirs/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase
Requires-Dist: pyscf
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: click
Requires-Dist: pyyaml
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Requires-Dist: plotly; extra == "plot"
Requires-Dist: nbformat>=4.2.0; extra == "plot"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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:

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

From PyPI, once released:

```bash
python -m pip install pyqirs
```

From a local clone:

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

For development:

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

Optional plotting dependencies can be installed with:

```bash
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

```python
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:

```python
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.

```python
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:

```bash
pyqirs --help
pyqirs get_moda --help
```

The legacy command name is also kept:

```bash
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:

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

## License

This project is distributed under the MIT License. See [LICENSE](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.
