ThermoLIB -- A Python Library for Constructing and Post-Processing Free Energy Surfaces to Extract Thermodynamic and Kinetic Properties

ThermoLIB is Python/Cython library designed to be used as a post-processing tool for constructing free energy surfaces from the output of molecular simulations, transforming them between different collective variables (CVs) and extracting thermodynamic and kinetic information. ThermoLIB is available for download on GitHUB and comes with extended documentation as well as many tutorials. The implementation is based on the theory of maximum likelihood estimators and includes error bars on and full covariance matrix between all points on the free energy surface using the Fisher information matrix. The free energy surfaces can be transformed a posteriori to other collective variables, projected towards lower dimensional CV-spaces and even deprojected towards higher dimensional CV-spaces if additional information from the simulation is provided in the form of a conditional probability. Finally, one can extract usefull thermodynamic and kinetic properties such as the reaction free energy and kinetic rate constant. Error bars on the free energy surfaces are propagated throughout al these operations. We briefly illustrate the capabilities of ThermoLIB by means of some tutorials and case studies.

💡 Research Summary

ThermoLIB is an open‑source Python/Cython library that streamlines the post‑processing of molecular simulation data to construct free‑energy surfaces (FES) and to extract thermodynamic and kinetic observables with rigorous uncertainty quantification. The core of the package is a maximum‑likelihood (ML) formulation of the Weighted Histogram Analysis Method (WHAM). By expanding the unbiased probability density in a set of histogram‑type basis functions and treating the biasing potentials of each umbrella window as multiplicative factors, ThermoLIB solves for the optimal coefficients and normalization constants that maximize the weighted log‑likelihood of all sampled data. Crucially, the Fisher information matrix of the ML estimator is evaluated analytically, providing a full covariance matrix and error bars for every grid point of the FES without resorting to boot‑strapping or ad‑hoc approximations. Autocorrelation analysis is also incorporated to correct for statistical inefficiencies in the raw trajectories.

Beyond error estimation, ThermoLIB addresses two pervasive challenges in enhanced‑sampling studies. First, it implements “deprojection”: given a one‑dimensional collective variable (CV) Q that may hide orthogonal degrees of freedom (e.g., a hidden CV S), the library can reconstruct a two‑dimensional FES(Q,S) using a conditional probability p(S|Q) supplied by the user. This reveals undersampled regions that are invisible in the original 1‑D free‑energy profile and guides the design of additional multidimensional umbrella simulations. Second, ThermoLIB supports deterministic and probabilistic transformations between CVs. Whether the mapping is a simple analytical function ˜Q = f(Q) or a stochastic relationship p(˜Q|Q) (as often arises in machine‑learning‑derived CVs or path‑integral MD), the library can re‑weight the FES accordingly, preserving the propagated uncertainties.

Kinetic analysis is treated with equal rigor. The authors point out that naïve application of transition‑state theory (TST) to a 1‑D free‑energy barrier yields CV‑dependent rate constants. ThermoLIB implements a CV‑independent TST formulation that incorporates both the width of the reactant basin and the average velocity of the CV at the dividing surface. The resulting rate constant inherits the error propagation from the Fisher matrix, delivering statistically sound kinetic predictions.

From an implementation standpoint, the computationally intensive parts are written in Cython for speed, while a clean Python API, extensive documentation, and Jupyter‑based tutorials are hosted on GitHub. This design promotes reproducibility and lowers the barrier for new users. The library currently relies on histogram‑type basis functions, which may limit resolution for highly continuous CVs; alternative density‑estimation schemes could be explored in future releases. Moreover, the dimensionality of the Fisher matrix grows with the number of bins and CVs, potentially leading to memory bottlenecks for very high‑dimensional umbrella ensembles. Sparse‑matrix techniques or GPU acceleration are suggested as possible remedies.

In summary, ThermoLIB unifies free‑energy reconstruction, analytical uncertainty quantification, CV transformation (including deprojection), and robust kinetic rate calculation into a single, well‑documented toolkit. By providing analytical error bars and tools to detect hidden sampling deficiencies, it fills a notable gap in the current ecosystem of WHAM‑based software. The library is poised to become a valuable resource for researchers in catalysis, materials design, and drug discovery who require reliable thermodynamic and kinetic insights from molecular simulations.