AlgoMol Core Library

C++ library for fast molecular graph representation and equivalence detection with Python bindings

Get Started

Overview

AlgoMol Core provides a robust framework for molecular modeling with specific focus on:

Molecular graph representation
Atom and bond management
Chemical and topological equivalence detection
VSEPR geometry modeling of molecular structures

Features

Molecular Graph Representation

Model molecules as graphs with atoms as nodes and bonds as edges

Equivalence Classes

Generate equivalence classes based on topological or geometrical properties

Stereochemistry Support

Handle cis/trans isomerism and other stereochemical features

VSEPR Geometry

Automatically assign and manage molecular geometries

Python Bindings

Use the library directly from Python with full API support

High Performance

Fast C++ core optimized for computational chemistry applications

Installation

Requirements

C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2019+)
CMake 3.15 or newer
Python 3.9+ (for Python bindings)
pybind11 (for Python bindings)

Python Package (Recommended)

The easiest way to get started:

pip install algomol

Build from Source

For development or custom builds:

# Clone the repository
git clone https://github.com/lanl2vz/algomol-core.git
cd algomol-core

# Create a build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Build
cmake --build . --config Release

# Install (optional)
cmake --install .

Usage Examples

Python API

import algomol

# Create a molecule
molecule = algomol.MolGraph("ethane")

# Add atoms
molecule.add_atom(1, 6)  # Carbon (atomic number 6)
molecule.add_atom(2, 6)  # Carbon
molecule.add_atom(3, 1)  # Hydrogen (atomic number 1)
molecule.add_atom(4, 1)  # Hydrogen
molecule.add_atom(5, 1)  # Hydrogen
molecule.add_atom(6, 1)  # Hydrogen
molecule.add_atom(7, 1)  # Hydrogen
molecule.add_atom(8, 1)  # Hydrogen

# Add bonds
molecule.add_bond(1, 2, algomol.BondType.SINGLE)
molecule.add_bond(1, 3, algomol.BondType.SINGLE)
molecule.add_bond(1, 4, algomol.BondType.SINGLE)
molecule.add_bond(1, 5, algomol.BondType.SINGLE)
molecule.add_bond(2, 6, algomol.BondType.SINGLE)
molecule.add_bond(2, 7, algomol.BondType.SINGLE)
molecule.add_bond(2, 8, algomol.BondType.SINGLE)

# Initialize the molecule
molecule.init_mol()

# Generate equivalence classes
molecule.generate_equivalence_classes(algomol.QueryTypeFlag.TOPOLOGICAL)

# Get equivalence classes
classes = molecule.get_equivalence_classes(algomol.QueryTypeFlag.TOPOLOGICAL)

C++ API

#include "AlgoMol/molecules.hpp"

int main() {
    // Create a molecule
    auto molecule = std::make_shared<AlgoMol::molecules::MolGraph>("ethane");
    
    // Add atoms
    molecule->addAtom(1, AlgoMol::elements::_CARBON);
    molecule->addAtom(2, AlgoMol::elements::_CARBON);
    molecule->addAtom(3, AlgoMol::elements::_HYDROGEN);
    molecule->addAtom(4, AlgoMol::elements::_HYDROGEN);
    molecule->addAtom(5, AlgoMol::elements::_HYDROGEN);
    molecule->addAtom(6, AlgoMol::elements::_HYDROGEN);
    molecule->addAtom(7, AlgoMol::elements::_HYDROGEN);
    molecule->addAtom(8, AlgoMol::elements::_HYDROGEN);
    
    // Add bonds
    molecule->addBond(1, 2, AlgoMol::bonds::BondType::SINGLE);
    molecule->addBond(1, 3, AlgoMol::bonds::BondType::SINGLE);
    molecule->addBond(1, 4, AlgoMol::bonds::BondType::SINGLE);
    molecule->addBond(1, 5, AlgoMol::bonds::BondType::SINGLE);
    molecule->addBond(2, 6, AlgoMol::bonds::BondType::SINGLE);
    molecule->addBond(2, 7, AlgoMol::bonds::BondType::SINGLE);
    molecule->addBond(2, 8, AlgoMol::bonds::BondType::SINGLE);
    
    // Initialize the molecule
    molecule->init();
    
    // Generate equivalence classes
    molecule->generateEquivalenceClasses(AlgoMol::molecules::QueryTypeFlag::TOPOLOGICAL);
    
    // Get equivalence classes
    auto classes = molecule->getEquivalenceClasses(AlgoMol::molecules::QueryTypeFlag::TOPOLOGICAL);
}

API Reference

Core Classes

MolGraph

Main class for molecular graph representation

Atom<Element>

Templated class for atoms of different elements

Bond<BondType>

Templated class for different bond types

Geometry<GeometryType>

Templated class for VSEPR geometries

Key Functions

addAtom()

Add an atom to a molecule

addBond()

Add a bond between atoms

init()

Initialize a molecule after adding atoms and bonds

generateEquivalenceClasses()

Compute equivalence classes

isTopologyEquivalent()

Check if two atoms are topologically equivalent

isChemicallyEquivalent()

Check if two atoms are chemically equivalent

setCisAtoms()

Set cis stereochemistry

setOrientations()

Set atom orientations

Get Started

Ready to integrate AlgoMol Core into your project? Install the library and explore the examples to see how it can accelerate your molecular modeling workflows.

Install from PyPI

For questions and support, please contact: lanl2vz@algomol.com