molbar 1.2.0rc1

Molecular Barcode (MolBar): Molecular Identifier for Organic and Inorganic Molecules

MolBar

• 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: [e-mail]

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

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

# Generate molecular barcode
molbar molecule.xyz

Python API:

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

$ 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 - Full documentation, tutorials, and API reference

Quick links:

• Installation Guide - Detailed installation instructions
• User Guide - Command-line usage and workflows
• API Reference - Python library documentation
• Tutorials - Step-by-step examples
• Utility Tools - Complete tool reference
• Theory - Mathematical background

🛠️ Utility Tools

MolBar includes additional tools described in the documentation:

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

@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: [e-mail]
• 🐛 Issues: GitLab 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.