Python
Functions
The molentropy module provides:
load_system(top_path, traj_path, start=None, stop=None, torsions_only=None, stride=None, tree_bonds=False, phase_angles=True, drop_constrained=False). See Coordinates.estimate_entropy(data_or_system, mie_order=None, periods=None, periodic=True, exact_constant=False, theiler_window=0).mie_orderdefaults to 2;mie_order=1gives the sum of the marginal entropies.estimate_coordinate_entropy(data_or_system, mie_order=None, periods=None, periodic=True, exact_constant=False, theiler_window=0). Returns each coordinate's share of the entropy;mie_orderdefaults to 2. The values sum toestimate_entropyat the same order. See Per-coordinate entropies.estimate_coordinate_mutual_information(data_or_system, periods=None, periodic=True, exact_constant=False, theiler_window=0). Returns the mutual information of each coordinate pair.estimate_quasi_harmonic_entropy(data_or_system, periods=None, periodic=True, histogram_bins=None, periodic_correlation="complex", exact_constant=False, theiler_window=0). Returns a dict withquasi_harmonic,boltzmann_quasi_harmonic,first_order_gaussian,first_order_boltzmannandcorrelation. See Quasi-harmonic estimators.estimate_coordinate_quasi_harmonic_entropy(data_or_system, periods=None, periodic=True, histogram_bins=None, periodic_correlation="complex", exact_constant=False, theiler_window=0). Each coordinate's share of the QH and BQH entropy: a dict with the same keys, each a list with one value per coordinate that sums to the matching total. See Quasi-harmonic estimators.estimate_split_entropy(data_or_system, soft=None, soft_estimator="mie", mie_order=2, hard_estimator="qh", coupling="gaussian", soft_features="harmonics", harmonics=None, state_coordinates=None, state_labels=None, min_state_frames=300, histogram_bins=None, periodic_correlation="centered", periods=None, periodic=True, exact_constant=False, theiler_window=0, per_coordinate=False, network_parents=5). Returns a dict withtotal,soft,hard,coupling,soft_coordinates,hard_coordinates,basin_countsandstates; withper_coordinate=True, alsocoordinates, a dict of liststotal,ownandcouplingwith one value per coordinate (see Per-coordinate entropies).softisNone,"topology","detect"or a list of coordinate indices from 0;Nonemeans"topology"for aSystemand"detect"for an array.soft_estimatoris"mie","mist","network"(withnetwork_parentsparents per coordinate) or"joint";hard_estimatoris"qh","bqh","qh-mie1"or"qh-mie2";soft_featuresis"harmonics"(3 unlessharmonicssays otherwise),"cossin"or"complex". See Split estimator.detect_basins(values, period=2π, bins=72, smoothing=2.0, saddle_fraction=0.5, min_population=0.02, free_rotor_resultant=0.3). Returns a dict withcount,labels,boundaries,populations,resultantandsoft.Systemhas the same six estimators as methods, each takingperiodic,exact_constantandtheiler_window(andmie_orderfor the two MIE entropy estimators,histogram_binsandperiodic_correlationfor the quasi-harmonic ones). Itssoft_torsions,symmetric_rotor_torsionsandring_torsionsproperties give the split estimator's topological classes. Itsinternal_coordinatesproperty holds the coordinate values of the selected frames as a list of lists, one per coordinate (np.array(system.internal_coordinates)has shape coordinates × frames), andperiodsgives each coordinate's period, orNonefor a linear one. Itsatoms,kindsandphase_referencesproperties describe the coordinates, in the order of every per-coordinate result: the topology atom indices of each (counted from 0), its kind ("bond","angle","torsion"or"phase angle"), and for a phase angle the index of its reference torsion, otherwiseNone. Itsconstrained_atomsproperty lists the atoms of each bond and angle dropped bydrop_constrained=True(empty otherwise). Itsmean_log_jacobianproperty is the mean log BAT Jacobian over the selected frames. It raisesValueErrorunless the system was loaded withtree_bonds=Trueand withouttorsions_only.- To start from an Amber topology and trajectory, call
load_system(...)once and use theSystemmethods or pass theSystemto any estimator. The coordinate metrics come from the generated BAT coordinates automatically, and the trajectory is only read once no matter how many quantities you compute.
exact_constant=True uses the exact finite-sample term, like the CLI's --exact-constant, and theiler_window matches the CLI's --theiler-window. periodic=False measures every coordinate linearly for that calculation, like the CLI's --no-periodic; a System keeps its own periods. For a raw array it cannot be combined with periods.
For a raw array, periods is a sequence with one entry per coordinate. Use None for a linear dimension and a positive period for a periodic dimension. Omitting periods preserves the linear behavior of the original raw-array API.
Example
import molentropy
system = molentropy.load_system("system.parm7", "trajectory.nc")
bqh = system.estimate_quasi_harmonic_entropy()["boltzmann_quasi_harmonic"]
entropy = molentropy.estimate_entropy(system, mie_order=2) # NN MIE
coordinate_entropy = system.estimate_coordinate_entropy() # order 2, sums to `entropy`
marginal_entropy = system.estimate_coordinate_entropy(mie_order=1)
See Installation for building the module.
Threads
- The Python wrappers release the GIL while loading trajectories and running entropy calculations, so multiple Python threads can call into
molentropyconcurrently. - Internal parallelism is handled in Rust with Rayon. Set
RAYON_NUM_THREADS=Nif you want to cap or tune the Rust worker pool.