Repository navigation
Home
Welcome to the EnsembleLab wiki!
EnsembleLab is an open source Python library for computational chemistry focused on molecular conformational ensembles: generating, optimizing, filtering, and analyzing the diverse structures a molecule can adopt.
The project is built around the idea that a conformational ensemble is more useful as a scientific object than as a collection of independent molecular structures. EnsembleLab provides tools to work with these ensembles throughout a computational workflow, from initial conformer generation to structural, energetic, and population analysis.
Current Focus: Developing a convergence algorithm that maps molecule sizes to optimized conformer counts in generated ensembles. Output N counts should represent the minimum number of conformers needed for the resulting ensemble to accurately represent molecular properties.
EnsembleLab currently provides tools for:
- Conformer generation using RDKit
- Geometry optimization using molecular mechanics and quantum-mechanical methods
- Hierarchical optimization workflows combining multiple computational methods
- Conformer filtering and selection based on structural and energetic properties
- RMSD analysis and structural comparison
- Torsional analysis of conformational space
- Molecular and 3D conformer descriptors
- Ensemble metadata and computational provenance
- Visualization and analysis of conformational data
The library integrates established computational chemistry packages such as RDKit, ASE, and xTB while providing higher level abstractions for ensemble-based workflows.
How many conformers are enough?
Computational conformer generation often requires choosing a sampling size in advance. EnsembleLab is being used to investigate how sampling size affects ensemble-level structural and energetic properties, with the eventual goal of developing ML-based methods for choosing an appropriate sampling size for a given molecule. This can be done through the analysis of the convergence of ensemble-wide metrics (such as conformer population or entropy spreads) as conformer sample size increases, mapping where changes in such metrics become negligible.
The wiki is organized around the major components of EnsembleLab:
Understand the fundamental objects and ideas behind EnsembleLab, including molecules, conformers, ensembles, and the distinction between molecular and conformer-level properties.
Learn how EnsembleLab is structured internally, how its modules interact, and the design principles behind the library.
Learn how molecular conformational ensembles are generated, including RDKit embedding, conformer identifiers, reproducibility, and generation provenance.
Learn about the available optimization backends, hierarchical optimization workflows, energies, convergence, and computational provenance.
Learn how conformers are selected and removed based on population, energy, structural similarity, and other criteria.
Explore the analytical tools used to characterize conformational ensembles, including RMSD, torsions, molecular descriptors, clustering, and conformational landscapes.
- Descriptors: Reference for molecular and conformer-level descriptors calculated by EnsembleLab.
- RMSD Analysis: Detailed documentation for pairwise RMSD calculations, RMSD matrices, structural comparison, and visualization.
- Torsional Analysis: Documentation for identifying, measuring, and analyzing molecular torsions across an ensemble.
Methods for grouping conformers according to structural or conformational similarity.
Higher-level analysis combining structural, torsional, energetic, and population information to characterize conformational space.
Practical examples demonstrating common EnsembleLab workflows, from basic ensemble generation to more advanced conformational analysis.
A record of major changes, new features, and breaking changes across EnsembleLab releases.
EnsembleLab is an evolving research-oriented project. The underlying computational methods are built on established scientific software and algorithms; the project aims to provide a higher-level framework for understanding and analyzing conformational ensembles, while leaving room for new methods and research ideas to develop within that framework.
The documentation reflects the current implementation and will evolve alongside the library.