nn-entropy

Estimate the configurational entropy of a molecular system, with a Rust library, CLI, and Python bindings.

This crate provides non-parametric entropy estimation using the nearest neighbor method with mutual information expansion on internal coordinates (i.e., bonds lengths, bond angles, and torsion angles) with built-in conversion from MD trajectory files.

Features

• Rust library API for MIE entropy up to fourth order, per-coordinate entropy, and mutual information estimates.
• CLI that reads .parm7 + .nc and converts to internal coordinates and prints total configurational entropy.
• Python bindings via pyo3 for in-memory arrays or direct file-based calculation.
• Entropy calculations parallelized with rayon.

Requirements

• Rust toolchain (edition 2024).
• For Python bindings: a Python environment with build tooling for pyo3 (see below).

Build

cargo build --release

CLI usage

cargo run --release <path_to_parm7> <path_to_nc> [--torsions-only] [--start N] [--stop N] [--mie-order 1|2|3|4]

Example:

cargo run --release <path_to_parm7> <path_to_nc>

Notes:

• --stop limits the number of frames read to N.
• --start skips the first N frames
• --mie-order selects the expansion order. The default is 2, matching previous behavior.

Rust library usage

use nn_entropy::calculate_entropy_from_data;

// one_d_data is Vec<Vec<f64>> with shape [n_coords][n_frames]
let entropy = calculate_entropy_from_data(one_d_data, frames_end)?;

Other helpers:

• calculate_entropy_from_data_with_order for explicit MIE order 1, 2, 3, or 4.
• estimate_coordinate_entropy_rust for per-coordinate entropy.
• estimate_coordinate_mutual_information_rust for pairwise mutual information.
• estimate_coordinate_mie_entropy_rust for per-coordinate second-order MIE entropy contributions. Each pairwise mutual information term is split evenly between the two coordinates, so the returned values sum to the order-2 total entropy.

Python bindings

The crate exposes a nn_entropy Python module (built from src/pyo3_api.rs) with:

• load_system(top_path, traj_path, start=None, stop=None, torsions_only=None)
• estimate_entropy(data_or_system, mie_order=None)
• estimate_mie_entropy(data, mie_order=None)
• estimate_coordinate_entropy(data)
• estimate_coordinate_mutual_information(data)
• estimate_coordinate_mie_entropy(data)
• estimate_mie_entropy_from_files(top_path, traj_path, start=None, stop=None, torsions_only=None, mie_order=None)
• estimate_coordinate_entropy_from_files(top_path, traj_path, start=None, stop=None, torsions_only=None)
• estimate_coordinate_mutual_information_from_files(top_path, traj_path, start=None, stop=None, torsions_only=None)
• estimate_coordinate_mie_entropy_from_files(top_path, traj_path, start=None, stop=None, torsions_only=None)

Preferred usage:

import nn_entropy

system = nn_entropy.load_system("system.parm7", "trajectory.nc")
entropy = nn_entropy.estimate_entropy(system, mie_order=2)

coordinate_entropy = system.estimate_coordinate_entropy()
coordinate_mie_entropy = system.estimate_coordinate_mie_entropy()

A typical build workflow uses maturin:

maturin develop --release

Tests

cargo test --release

Project layout

• src/lib.rs: core entropy estimation and internal coordinate utilities.
• src/bat_library/: NetCDF reader for .parm7 + .nc, and internal coordinate (BAT) conversion.
• src/main.rs: CLI entry point.
• src/pyo3_api.rs: Python bindings.
• tests/: unit and regression tests.

Further Reading

• Grid inhomogeneous solvation theory: Hydration structure and thermodynamics of the miniature receptor cucurbit[7]uril - Uses nearest neighbor method to calculate first-order estimate of solvent entropy
• Extraction of configurational entropy from molecular simulations via an expansion approximation - Uses mutual information expansion to increase accuracy of entropy estimation of highly correlated systems like molecules
• Sample Estimate of the Entropy of a Random Vector - First introduction of nearest neighbors entropy estimation

License

© 2026 Helmut Carter, Kurtzman Lab. All rights reserved.