Metadata-Version: 2.1
Name: molbar
Version: 1.2.0rc1
Summary: Molecular Barcode (MolBar): Molecular Identifier for Organic and Inorganic Molecules
Home-page: https://git.rwth-aachen.de/bannwarthlab/MolBar
Author: Nils van Staalduinen
Author-email: Nils van Staalduinen <van.staalduinen@pc.rwth-aachen.de>, Christoph Bannwarth <bannwarth@pc.rwth-aachen.de>
Maintainer-email: Nils van Staalduinen <van.staalduinen@pc.rwth-aachen.de>
License: MIT License
Project-URL: Homepage, https://git.rwth-aachen.de/bannwarthlab/molbar/
Project-URL: Documentation, https://git.rwth-aachen.de/bannwarthlab/molbar/
Project-URL: Repository, https://git.rwth-aachen.de:bannwarthlab/molbar.git
Project-URL: Issues, https://git.rwth-aachen.de/bannwarthlab/molbar/-/issues
Project-URL: Changelog, https://git.rwth-aachen.de/bannwarthlab/molbar/-/issues
Keywords: molecular identifier,chemical data science,stereoisomerism
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: joblib
Requires-Dist: ase
Requires-Dist: numpy
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: numpy; extra == "dev"
Requires-Dist: scipy; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov>=2.0; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: scipy; extra == "test"



# MolBar

<div align="center">
<img src="https://git.rwth-aachen.de/bannwarthlab/molbar/-/raw/main/logo.png?ref_type=heads" alt="logo" width="400" />
</div>

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![PyPI - Version](https://img.shields.io/pypi/v/molbar.svg)](https://pypi.org/project/molbar)
[![Python Versions](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/molbar)
[![Coverage](https://img.shields.io/badge/coverage-84.8%25-green.svg)](./htmlcov/index.html)
[![Downloads](https://static.pepy.tech/badge/molbar)](https://pepy.tech/project/molbar)
[![Downloads](https://static.pepy.tech/badge/molbar/month)](https://pepy.tech/project/molbar)
[![Paper](https://img.shields.io/badge/DOI-10.1038%2Fs41586--020--2649--2-blue)](
https://doi.org/10.1039/D4DD00208C)

- **Digital Discovery Paper:** https://doi.org/10.1039/D4DD00208C
- **Documentation:** https://bannwarthlab.pages.rwth-aachen.de/molbardocs/
- **Source code:** https://git.rwth-aachen.de/bannwarthlab/molbar
- **Bug reports:** https://git.rwth-aachen.de/bannwarthlab/molbar/-/issues
- **Email contact:** van.staalduinen@pc.rwth-aachen.de

This package provides an implementation of the Molecular Barcode (MolBar), a molecular identifier based on quantum chemistry. It is designed to ensure the uniqueness of data in chemical 3D structure databases. The identifier is optimized for computational chemistry applications such as black-box chemical space exploration. It generates the identifier directly from 3D Cartesian coordinates, encoding the 3D shape of the molecule:

- **🧪 Universal**: Works with organic molecules, metal complexes, and inorganic systems
- **🔀 Stereochemistry**: Encodes central, axial, planar, and helical chirality
- **🔒 Atropisomerism**: When rotation around single bond is hindered, MolBar recognizes this and describe the absolute configurations for both enantiomers.
- **🔬 3D-Aware**: MolBar encodes 3D arrangement of the molecule.
- **🔄 Conformer-invariant**: Same identifier across conformers
- **⚛️ Direct from QC files**: Generates MolBar directly from Cartesian coordinates without XYZ to Molfile conversion beforehand.
- **🐍 Python Native**: CLI and library interfaces


## 🚀 Quick Start

### Installation

```bash
# Install from PyPI (recommended)
pip install molbar

# Install from source
git clone https://git.rwth-aachen.de/bannwarthlab/molbar.git
cd molbar
make install
```

### Basic Usage

**Command Line:**
```bash
# Generate molecular barcode
molbar molecule.xyz
```

**Python API:**
```python
from molbar import get_molbar_from_coordinates
import numpy as np

# From coordinates and elements
coordinates = np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]])  # 2 atoms
elements = ['C', 'H']
molbar_id = get_molbar_from_coordinates(coordinates, elements)
print(molbar_id)

# From structure file
from molbar import get_molbar_from_file
molbar_id = get_molbar_from_file("molecule.xyz")
```

## 📊 Example Output

```bash
$ molbar caffeine.xyz
MolBar | 1.2.0 | C8N4O2H10 | 0 | 1 | -377 -288 -241 -170 -129 -88 -51 20 20 20 20 20 20 38 147 160 279 377 441 495 556 721 784 896 | -345 -207 -152 -96 40 69 115 243 246 369 448 615 680 846 | -145 -143 -136 -37 4 9 9 9 9 9 9 25 29 43 81 94 128 172 240 290 365 536 609 1465 | 0 0 0 0 
```

The barcode format: `MolBar | version | formula | charge | multiplicity | topology | heavy_topology | topography | chirality`

## 📖 Documentation

**📚 [Complete Documentation](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/)** - Full documentation, tutorials, and API reference

Quick links:
- **[Installation Guide](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/installation/)** - Detailed installation instructions
- **[User Guide](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/commandline/)** - Command-line usage and workflows
- **[API Reference](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/api/)** - Python library documentation
- **[Tutorials](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/tutorials/)** - Step-by-step examples
- **[Utility Tools](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/tools/)** - Complete tool reference
- **[Theory](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/theory/)** - Mathematical background


## 🛠️ Utility Tools

MolBar includes additional tools described in the [documentation](https://bannwarthlab.pages.rwth-aachen.de/molbardocs/tools):

- **`ensplit`** - Split ensemble files by molecular barcodes
- **`fragcount`** - Count molecular fragments
- **`mbslice`** - Extract molecular fragments
- **`molopt`** - Optimize geometries with MolBar's structure unification force field
- **`moldiff`** - Compare molecular structures

## 📄 Citation

If you use MolBar in your research, please cite:

```bibtex
@article{molbar2024,
  title={MolBar: a molecular identifier for inorganic and organic molecules with full support of stereoisomerism},
  author={van Staalduinen, Nils and Bannwarth, Christoph},
  journal={Digital Discovery},
  volume={3},
  pages={2298--2319},
  year={2024},
  publisher={Royal Society of Chemistry},
  doi={10.1039/D4DD00208C}
}
```

## 📞 Support

- **📧 Contact**: [van.staalduinen@pc.rwth-aachen.de](mailto:van.staalduinen@pc.rwth-aachen.de)
- **🐛 Issues**: [GitLab Issues](https://git.rwth-aachen.de/bannwarthlab/molbar/-/issues)

## MolBar License and Disclaimer

MIT License

Copyright (c) 2022 Nils van Staalduinen, Christoph Bannwarth

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
