EnSort is a chemically aware structural analysis toolkit for proteins, ligands, peptides, and molecular ensembles. Rather than treating molecules as collections of Cartesian coordinates, EnSort reconstructs molecular topology directly from atomic positions, identifies chemically meaningful functional groups, annotates interaction sites, and provides an intuitive query language for exploring structures.
EnSort was designed for analyzing molecular docking poses, molecular dynamics trajectories, CREST conformer ensembles, and quantum chemistry calculations. It combines automated chemical perception with interactive visualization and trajectory analysis, allowing users to rapidly investigate intermolecular interactions without manually identifying atom indices or residue numbers.
The program automatically reconstructs covalent connectivity, detects bond orders, maps PDB residues onto XYZ coordinates, identifies functional groups, classifies hydrogen-bond donors and acceptors, determines aromatic and guanidinium interaction geometries, and generates chemically meaningful interaction vectors. Every atom is annotated according to its chemical environment, enabling selections based on chemistry rather than atom numbering.
EnSort supports both single structures and multi-frame XYZ trajectories. For ensemble data, the software can calculate minimum, maximum, average, and Boltzmann-weighted interaction distances, search thousands of conformers for specific interaction geometries, and compare structural motifs across an entire trajectory.
The software provides three complementary interfaces:
- Interactive JupyterLab Mode – An interactive Plotly viewer with synchronized chemical analysis tools. This mode requires JupyterLab and provides a graphical interface for exploring structures, navigating trajectories, and visualizing interaction vectors.
- Interactive Console – A chemistry-aware command interface for selecting atoms, residues, ligands, and functional groups, performing structural analysis, and measuring intermolecular interactions.
- Batch Mode – A command-line interface suitable for automated workflows, scripting, and high-throughput analysis of molecular ensembles.
Unlike traditional molecular visualization software, EnSort treats molecular structures as chemical systems rather than collections of atoms, allowing analyses to be performed using chemically meaningful concepts such as residues, functional groups, interaction motifs, and hydrogen-bonding sites instead of atom indices alone.
- Automatic covalent bond reconstruction from Cartesian coordinates
- Double bond assignment and topology reconstruction
- PDB-to-XYZ residue mapping
- Ligand identification
- Functional group detection
- Chemical role annotation
- Hydrogen-bond donor and acceptor identification
- Lone-pair vector generation
- Aromatic π-normal calculation
- Guanidinium plane detection
- Chemically aware query language
- Atom, residue, ligand, and functional-group selections
- Distance calculations between arbitrary chemical objects
- Trajectory analysis across molecular ensembles
- Boltzmann-weighted ensemble averaging using conformer energies
Clone the repository and ensure that the EnSort source files and motif library remain in the same directory structure.
git clone https://github.com/Petsen777/EnSort.git
cd EnSortEnSort relies on the included motif library to identify functional groups, assign chemical roles, and build chemically meaningful interaction models. This library is loaded automatically at runtime and must remain available when running EnSort. If the motif library is moved, renamed, or deleted, EnSort will be unable to perform chemical perception, including functional-group detection, hydrogen-bond identification, and chemistry-aware selections.
No additional configuration is required provided the repository structure is preserved.
The EnSort JupyterLab notebook provides an interactive environment for exploring molecular structures and ensembles. Once a reference PDB structure and one or more XYZ files have been loaded, EnSort automatically reconstructs the molecular topology, identifies functional groups, assigns chemically meaningful atom roles, and launches an interactive 3D viewer. At the beginning of EnSort.ipynb, ensure that
ENABLE_3D_VIEW = Trueis set before executing the notebook. If this option is set to False, EnSort will still perform all chemical analyses and command-line operations, but the interactive 3D viewer and visualization tools will be disabled.
Once enabled, load a reference PDB structure and one or more XYZ files. EnSort automatically reconstructs the molecular topology, identifies functional groups, assigns chemically meaningful atom roles, and launches the interactive 3D viewer.
The viewer is synchronized with the EnSort chemical analysis engine, allowing structural visualization and command-line analysis to be performed simultaneously. Changing frames in the viewer immediately updates all molecular annotations, functional groups, interaction vectors, and subsequent analyses.
The interactive viewer supports
- Interactive 3D molecular visualization
- Single structures and molecular ensembles
- Frame-by-frame trajectory navigation
- Multiple loaded XYZ ensembles
- Automatic bond reconstruction
- Functional-group annotations
- Residue labels
- Ligand identification
- Hydrogen-bond vectors
- Lone-pair vectors
- Aromatic π-system normals
- Guanidinium plane normals
The viewer can display molecular structures using three different grouping modes
| Display Mode | Description |
|---|---|
| Atoms | Individual atoms with element colouring and covalent bonds. |
| Residues | Groups atoms into amino acid residues and ligands. |
| Motifs | Displays automatically detected functional groups and chemical motifs. |
EnSort uses a chemistry-aware selection language that allows structures to be queried using chemically meaningful objects instead of atom indices.
Selections may represent
- Individual atoms
- Residues
- Chains
- Ligands
- Functional groups
- Chemical roles
- Backbone atoms
- Side-chain atoms
Selections may also be combined to define specific atoms within residues or functional groups.
Residues may be specified using either one-letter or three-letter amino acid codes.
Examples
K15
LYS15
R42
ARG42
E30
GLU30
Residues may optionally include chain identifiers.
A:LYS15
B:ARG42
Entire ligands may be selected directly.
LIG
EnSort automatically identifies functional groups that may be searched directly.
Supported groups include
- Primary amines (
amine1) - Secondary amines (
amine2) - Tertiary amines (
amine3) - Amides (
amide) - Carbonyls (
carbonyl) - Carboxylates (
coo) - Guanidinium groups (
guan) - Carbon dioxide (
co2)
Specific atoms inside a residue or functional group may be selected.
Examples
LYS15:NZ
ARG42:NH1
GLU30:OE2
amine1:N
coo:O
guan:N
If multiple atoms of the same element exist within a motif, an index may be appended.
amine1:N2
coo:O2
The interactive console accepts chemistry-aware commands that operate on the currently loaded structure or trajectory.
| Command | Function |
|---|---|
files |
List all loaded XYZ ensembles. |
use F# |
Restrict analysis to a specific loaded ensemble. |
use all |
Analyze all loaded ensembles simultaneously. |
frame N |
Move to frame N of the active ensemble. |
F# frame N |
Jump directly to frame N of a specific ensemble. |
dist selection1 selection2 |
Perform a detailed distance analysis between two selections. |
distmin selection1 selection2 |
Calculate the minimum distance across the ensemble. |
distmax selection1 selection2 |
Calculate the maximum distance across the ensemble. |
distavg selection1 selection2 |
Calculate the ensemble average distance (Boltzmann-weighted when energies are available). |
search selection1 selection2 cutoff |
Find every frame where the two selections are within the specified cutoff distance (Å). |
quit |
Exit the interactive console. |
dist LYS15 LIG
Measure the distance between Lys15 and the ligand.
dist amine1 coo
Measure the distance between all primary amines and all carboxylates.
dist ARG42:NH1 LIG
Measure the distance between a specific atom and the ligand.
distmin LIG K
Find the closest ligand–lysine interaction over the entire ensemble.
distavg amine1 carbonyl
Calculate the ensemble-averaged distance between primary amines and carbonyl groups.
search LIG ARG42 3.0
Locate every frame in which the ligand lies within 3.0 Å of Arg42.
use F2
Restrict analysis to the second loaded ensemble.
frame 125
Move directly to frame 125 of the active ensemble.
- Interactive 3D visualization in JupyterLab
- Batch processing for automated workflows
Batch mode allows EnSort to be integrated into automated workflows, shell scripts, and high-throughput analysis pipelines without launching the interactive console or graphical viewer. All required input files and the analysis command are supplied directly from the command line.
| Argument | Description |
|---|---|
--pdb |
Reference PDB structure used for topology and chemical perception. |
--xyz |
One or more XYZ trajectory or ensemble files to analyze. |
--batch |
Analysis command to execute. The command should be enclosed in quotation marks. |
--out |
(Optional) Write the analysis results to a text file instead of only printing them to the terminal. |
python EnSort.py \
--pdb structure.pdb \
--xyz trajectory.xyz \
--batch "distavg K2 K3"python EnSort.py \
--pdb structure.pdb \
--xyz trajectory.xyz \
--batch "distmin amine1 carboxyl" \
--out results.txt| Command | Description |
|---|---|
distavg <selection1> <selection2> |
Computes the average distance between two selections across the trajectory, reporting both the simple average and, when available, the Boltzmann-weighted average. |
distmin <selection1> <selection2> |
Finds the minimum distance observed between two selections across all frames. |
distmax <selection1> <selection2> |
Finds the maximum distance observed between two selections across all frames. |
Batch mode loads the reference structure and all supplied trajectory files, executes the requested analysis command, prints the results to the terminal, optionally writes them to the file specified with --out, and then exits. Unlike Interactive Mode, no command prompt or graphical viewer is launched, making batch mode well suited for scripting, reproducible workflows, and high-throughput analyses.
EnSort is particularly suited for protein–ligand interaction analysis, docking pose evaluation, molecular dynamics simulations, conformational ensemble analysis, quantum chemistry workflows, enzyme engineering, peptide chemistry, and computational structural biology.