Ensemble Analyzer

July 22, 2026 · View on GitHub

Conformer Ensemble Pruning Software

Ensemble Analysis (EnAn) is a Python framework for automated conformational analysis and ensemble processing in computational chemistry workflows.

🎯 Key Features

Core Capabilities

⚡ Multi-Protocol Workflows: Sequential optimization/frequency calculations with automatic pruning
🔬 Quantum Chemistry Integration: Support for ORCA, Gaussian, NWChem, semi-empirical (TBLite), and ML potentials (AIMNet)
🧪 Transition State Optimization: TS mode validation with fragment localization, automatic displacement and re-optimization of spurious imaginary frequencies
📊 Advanced Clustering: PCA-based conformer clustering with multiple feature extraction methods
🎨 Spectral Analysis: Generate weighted IR, VCD, UV-vis, and ECD spectra
🔄 Checkpoint System: Automatic restart capability with atomic file operations

Analysis Tools

Thermochemistry: Grimme's qRRHO implementation for every integration
Clustering Method: Distance matrix eigenvalues (rotation/translation invariant).
Pruning: Intelligent energy-based filtering with Boltzmann weighting

📦 Installation

Requirements

Python ≥ 3.11
Core: NumPy, SciPy, Matplotlib, ASE
Clustering: scikit-learn
Acceleration: Numba

# Base install (ORCA/Gaussian only)
pip install ensemble-analyzer

# With ML potentials (TBLite, AIMNet, UMA, FairChem, MACE)
pip install "ensemble-analyzer[ml]"

External QM Programs (optional)

Program	Requirement	Env Var
ORCA	Installed binary	`ORCAVERSION="x.y.z"`
Gaussian	Licensed installation	—
NWChem	Installed binary	`NWCHEMCOMMAND` or `PATH`

Semi-empirical & ML Potentials (optional)

Calculator	Type	Extra	Model Weights
TBLite	Semi-empirical (GFN-xTB)	`[tblite]`	Built-in
AIMNet	ML potential	`[aimnet]`	`ENAN_MODELS_DIR/aimnet/`
UMA	ML potential	`[uma]`	`ENAN_MODELS_DIR/uma/`
FairChem	ML potential	`[fairchem]`	`ENAN_MODELS_DIR/fairchem/`
Mace	ML potential	`[mace]`	`ENAN_MODELS_DIR/mace/`

Point to your model weights directory:

export ENAN_MODELS_DIR="/path/to/ml_weights"
# Default: ~/.ensemble_analyzer/models/<calculator>/

🚀 Quick Start

1. Define your protocol file

Create protocol.json

{
    "0": {"functional": "r2SCAN-3c", "opt": true, "freq": true,"cluster": 5, "comment": "Initial Optimization cluster into 5 families"},
    "1": {"functional": "wB97X-D4rev", "basis": "def2-QZVPPD", "comment": "Single Point energy evaluation"}
}

2. Basic Usage

ensemble_analyzer --ensemble conformers.xyz --protocol protocol.json --output calculation.out --cpu 8 --temperature 298.15

3. Using Semi-empirical & ML Potentials

{
    "0": {"calculator": "tblite", "functional": "GFN2-xTB", "opt": true, "freq": true},
    "1": {"calculator": "aimnet", "functional": "<aimnet_weights.pt", "cluster": 10},
}

ML calculators skip file I/O and parsing — energies are read directly from ASE atoms.

4. Transition State Optimization with Mode Validation

{
    "0": {"calculator": "orca", "functional": "wB97X-D4rev", "basis": "def2-TZVPPD", "opt": true, "ts": true, "freq": true,
          "loc_freq": [[0, 1, 2, 3], [4, 5, 6, 7, 8, 9]],
          "comment": "TS optimization with fragment-based imag mode validation"}
}

ts: true enables Sella optimizer for ML calculators and OptTS/opt=(ts,…) for QM programs. When loc_freq is set, the localization logic validates whether the imaginary frequency is mainly on the listed atom groups (Frag1, Frag2, …), displaces and re-optimizes when a spurious mode is detected.

5. Restart from Checkpoint

# Automatically resumes from last completed protocol
ensemble_analyzer --restart

Protocol Parameters

Parameter	Type	Description	Example
Calculation Settings
`functional`	str	DFT functional or method	`"B3LYP"`, `"xtb"`, `"HF-3c"`
`basis`	str	Basis set (auto for composite methods)	`"def2-SVP"`, `"def2-TZVP"`
`calculator`	str	QM program / ML potential	`"orca"` (default), `"gaussian"`, `"nwchem"`, `"tblite"`, `"aimnet"`
`opt`	bool	Optimize geometry	`true`, `false`
`freq`	bool	Calculate frequencies	`true`, `false`
`mult`	int	Spin multiplicity	`1` (singlet), `2` (doublet)
`charge`	int	Molecular charge	`0` (default)
`fmax`	float	Convergence threshold for ML optimizers (BFGS/Sella) [eV/Å]	`0.01` (default)
`solvent`	dict	Implicit solvation	`{"solvent": "water", "smd": true}`
TS Analysis
`ts`	bool	Enable TS optimization (uses Sella for ML calculators)	`false`
`loc_freq`	list[list]	Atom index groups for TS mode validation	`[[0,1,2], [3,4,5]]`
`min_localization`	float	Min % displacement on `loc_freq` fragments to accept negative freq	`50.0`
`auto_displace`	bool	Auto-displace along imaginary mode + re-optimize	`false`
`displace_scale`	float	Displacement scale factor [Å]	`0.3`
`neg_freq_threshold`	float	Frequencies with	ν
Pruning Thresholds
`thrG`	float	Energy similarity threshold [kcal/mol]	`3.0`, `5.0`
`thrB`	float	Rotatory constant threshold [cm⁻¹]	`5e-5`, `1e-5`
`thrGMAX`	float	Energy window cutoff [kcal/mol]	`10.0`
`cluster`	bool/int	Enable clustering	`true` (auto), `5` (fixed)
`no_prune`	bool	Disable pruning	`false` (default)
TD-DFT Settings
`nroots`	int	Number of excited states for TD-DFT calculation	`10`, `30`
`tda`	bool	Use Tamm-Dancoff approximation (ORCA defaults to `true`, set `false` for full TD-DFT)	`true`, `false`
Advanced
`constraints`	list[list]	Geometry constraints (only on cartesians)	`[[1,2],[1],[1,2,3],[4,3,2,1]]`
`monitor_internals`	list	Track bond/angle/dihedral	`[[0,1], [0,1,2]]`
`skip_opt_fail`	bool	Skip failed optimizations	`false` (default)
`block_on_retention_rate`	bool	Block the calculation has a retention rate lower than the `MIN_RETENTION_RATE` (20%)	`false` (default)

Standalone CLI applications

Protocol Wizard

If you don't want to create from scratch the protocol file, the enan_protocol_wizard is an automatic and interactive way to create this essential file. It is divided into three different level of configuration: i) basic, where all the essential parameters are asked, ii) intermediate, and iii) advance. Feel free to browse all the possible protocol options and parameters.

Regrapher

If you want to change the convolution of your graphs, you can edit the settings.json file. Here, all the global settings are present. When finished, the command enan_regraph come handy. It re-run the Graph workflow with these new setting and in few time, you'll have your new graphs.

usage: enan_regraph [-h] [-rb READ_BOLTZ] [-no-nm] [-w] [--disable-color] idx [idx ...]

positional arguments:
  idx                   Protocol's number to (re-)generate the graphs

options:
  -h, --help            show this help message and exit
  -rb READ_BOLTZ, --read-boltz READ_BOLTZ
                        Read Boltzmann population from a specific protocol
  -no-nm, --no-nm       Do not save the nm graphs
  -w, --weight          Show Weighting function
  --disable-color       Disable colored output

Graph Editor

All graphs are saved also as a pickle. This file can be reloaded and from there you can modify every single element of the Matplotlib Figure store in it. This requires some programming skills and, especially, time. Here is where enan_graph_editor comes to play. It is once again an interactive terminal interface (based both on rich or InquierPy library) where you can change and personalize every pickle. If you have to modify more files at once, a batch mode is implemented as well, so to by-pass the limitation of the manual selection of the interactive TUI.

usage: enan_graph_editor [-h] [--batch] [--list] [--rename OLD NEW] [--rename-file RENAME_FILE] [--color LABEL COLOR] [--linestyle LABEL STYLE] [--linewidth LABEL WIDTH] [--alpha LABEL ALPHA] [--visibility LABEL bool] [--output OUTPUT] [--format {pickle,png,pdf,svg}] [--no-strict]
                         [--verbose]
                         pickle_file

Interactive/batch editor for matplotlib pickles

positional arguments:
  pickle_file           Matplotlib pickle file

options:
  -h, --help            show this help message and exit
  --batch, -b           Batch mode (non-interactive)
  --no-strict           Disable strict validation
  --verbose, -v         Verbose output

batch mode options:
  --list, -l            List labels and exit
  --rename OLD NEW, -r OLD NEW
                        Rename label
  --rename-file RENAME_FILE, -rf RENAME_FILE
                        Mapping file OLD=NEW
  --color LABEL COLOR, -c LABEL COLOR
                        Change color
  --linestyle LABEL STYLE, -ls LABEL STYLE
                        Change line style (e.g., -, --, :, -.)
  --linewidth LABEL WIDTH, -lw LABEL WIDTH
                        Change line linewidth (float)
  --alpha LABEL ALPHA, -a LABEL ALPHA
                        Change line transparency (0-1)
  --visibility LABEL bool, -vis LABEL bool
                        Toggle line visibility (True/False)
  --output OUTPUT, -o OUTPUT
                        Output file
  --format {pickle,png,pdf,svg}, -f {pickle,png,pdf,svg}
                        Output format
                        
DEFAULT MODE: Interactive TUI
  enan_graph_editor plot.pkl

BATCH MODE (examples):
  enan_graph_editor plot.pkl --batch --list
  enan_graph_editor plot.pkl --batch --rename "Protocol 1" "Proto A"
  enan_graph_editor plot.pkl --batch --color "Experimental" red --output new.pkl

Cite

@article{
  title = {Ensemble Analyzer: An Open-Source Python Framework for Automated Conformer Ensemble Refinement},
  shorttitle = {Ensemble Analyzer},
  author = {Pellegrini, Andrea and Righi, Paolo and Mazzanti, Andrea and Mancinelli, Michele},
  date = {2026-05-11},
  journaltitle = {Journal of Chemical Information and Modeling},
  shortjournal = {J. Chem. Inf. Model.},
  volume = {66},
  number = {9},
  pages = {5018--5025},
  doi = {10.1021/acs.jcim.6c00273},
  url = {https://pubs.acs.org/doi/10.1021/acs.jcim.6c00273},
}

🤝 Contributing

Development Workflow

# Fork and clone
git clone https://github.com/andre-cloud/ensemble_analyzer.git
cd ensemble_analyzer

# Create feature branch
git checkout -b feature/awesome-feature

# Install dev dependencies
pip install -e .

# Commit and push
git commit -m "Add awesome feature"
git push origin feature/awesome-feature

📄 License

This software is licensed under the MIT License. See the LICENSE file for details.

📞 Support and contact

For any questions or support, please contact by email.