physical_validation.util subpackage
Warning
This subpackage is intended for internal use. Documentation and input validation is reduced.
physical_validation.util.kinetic_energy module
This module contains low-level functionality of the physical_validation.kinetic_energy module. The functions in this module should generally not be called directly. Please use the high-level functions from physical_validation.kinetic energy.
- physical_validation.util.kinetic_energy.is_close(value1: float, value2: float, relative_tolerance: float = 1e-09, absolute_tolerance: float = 1e-09) bool[source]
Whether two float values are close, as defined by a given relative and absolute tolerance.
- physical_validation.util.kinetic_energy.check_distribution(kin: numpy.ndarray, temp: float, ndof: float, kb: float, verbosity: int, screen: bool, filename: Optional[str], ene_unit: Optional[str], temp_unit: Optional[str], data_is_uncorrelated: bool) float[source]
Checks if a kinetic energy trajectory is Maxwell-Boltzmann distributed.
- Parameters
kin – Kinetic energy snapshots of the system.
temp – Target temperature of the system. Used to construct the Maxwell-Boltzmann distribution.
ndof – Number of degrees of freedom in the system. Used to construct the Maxwell-Boltzmann distribution.
kb – Boltzmann constant \(k_B\).
verbosity – 0: Silent. 1: Print minimal information. 2: Print result details. 3: Print additional information.
screen – Plot distributions on screen.
filename – Plot distributions to filename. If None, no plotting.
ene_unit – Energy unit - used for output only.
temp_unit – Temperature unit - used for output only.
data_is_uncorrelated – Whether the provided data is uncorrelated. If this option is set, the equilibration, decorrelation and tail pruning of the trajectory is skipped. This can speed up the analysis, but note that if the provided data is correlated, the results of the physical validation checks might be invalid.
- Returns
The p value of the test.
- Return type
result
See also
physical_validation.kinetic_energy.distributionHigh-level version
- physical_validation.util.kinetic_energy.check_mean_std(kin: numpy.ndarray, temp: float, ndof: float, kb: float, verbosity: int, bs_repetitions: int, bootstrap_seed: Optional[int], screen: bool, filename: Optional[str], ene_unit: Optional[str], temp_unit: Optional[str], data_is_uncorrelated: bool) Tuple[float, float][source]
Calculates the mean and standard deviation of a trajectory (+ bootstrap error estimates), and compares them to the theoretically expected values.
- Parameters
kin – Kinetic energy snapshots of the system.
temp – Target temperature of the system. Used to construct the Maxwell-Boltzmann distribution.
ndof – Number of degrees of freedom in the system. Used to construct the Maxwell-Boltzmann distribution.
kb – Boltzmann constant \(k_B\).
verbosity – 0: Silent. 1: Print minimal information. 2: Print result details. 3: Print additional information.
bs_repetitions – Number of bootstrap samples used for error estimate.
bootstrap_seed – Sets the random number seed for bootstrapping. If set, bootstrapping will be reproducible. If None, bootstrapping is non-reproducible.
screen – Plot distributions on screen.
filename – Plot distributions to filename. If None, no plotting.
ene_unit – Energy unit - used for output only.
temp_unit – Temperature unit - used for output only.
data_is_uncorrelated – Whether the provided data is uncorrelated. If this option is set, the equilibration, decorrelation and tail pruning of the trajectory is skipped. This can speed up the analysis, but note that if the provided data is correlated, the results of the physical validation checks might be invalid.
- Returns
Distance of the estimated T(mu) and T(sigma) from the expected temperature, measured in standard deviations of the estimates.
- Return type
result
See also
physical_validation.kinetic_energy.distributionHigh-level version
- physical_validation.util.kinetic_energy.check_equipartition(positions: numpy.ndarray, velocities: numpy.ndarray, masses: numpy.ndarray, molec_idx: numpy.ndarray, molec_nbonds: numpy.ndarray, natoms: int, nmolecs: int, temp: float, kb: float, strict: bool, ndof_reduction_tra: float, ndof_reduction_rot: float, molec_groups: Optional[List[numpy.ndarray]], random_divisions: int, random_groups: int, random_division_seed: Optional[int], ndof_molec: Optional[List[Dict[str, float]]], kin_molec: Optional[List[List[Dict[str, float]]]], verbosity: int, screen: bool, filename: Optional[str], ene_unit: Optional[str], temp_unit: Optional[str], bootstrap_seed: Optional[int], data_is_uncorrelated: bool) Tuple[Union[List[float], List[Tuple[float, float]]], List[Dict[str, float]], List[List[Dict[str, float]]]][source]
Checks the equipartition of a simulation trajectory.
- Parameters
positions (array-like (nframes x natoms x 3)) – 3d array containing the positions of all atoms for all frames
velocities (array-like (nframes x natoms x 3)) – 3d array containing the velocities of all atoms for all frames
masses (array-like (natoms x 1)) – 1d array containing the masses of all atoms
molec_idx (array-like (nmolecs x 1)) – Index of first atom for every molecule
molec_nbonds (array-like (nmolecs x 1)) – Number of bonds for every molecule
natoms – Number of atoms in the system
nmolecs – Number of molecules in the system
temp – Target temperature of the simulation.
kb – Boltzmann constant \(k_B\).
strict – If True, check full kinetic energy distribution via K-S test. Otherwise, check mean and width of kinetic energy distribution.
ndof_reduction_tra – Number of center-of-mass translational degrees of freedom to remove.
ndof_reduction_rot – Number of center-of-mass rotational degrees of freedom to remove.
molec_groups (List[array-like] (ngroups x ?), optional) –
List of 1d arrays containing molecule indeces defining groups. Useful to pre-define groups of molecules (e.g. solute / solvent, liquid mixture species, …). If None, no pre-defined molecule groups will be tested.
Note: If an empty 1d array is found as last element in the list, the remaining molecules are collected in this array. This allows, for example, to only specify the solute, and indicate the solvent by giving an empty array.
random_divisions – Number of random division tests attempted.
random_groups – Number of groups the system is randomly divided in.
random_division_seed – Seed making the random divisions reproducible. If None, random divisions not reproducible
ndof_molec – Pass in the degrees of freedom per molecule. Slightly increases speed of repeated analysis of the same simulation run.
kin_molec – Pass in the kinetic energy per molecule. Greatly increases speed of repeated analysis of the same simulation run.
verbosity – Verbosity level, where 0 is quiet and 3 very chatty.
screen – Plot distributions on screen. Default: False.
filename – Plot distributions to filename. If None, no plotting.
ene_unit – Energy unit - used for output only.
temp_unit – Temperature unit - used for output only.
bootstrap_seed – Sets the random number seed for bootstrapping (if strict=False). If set, bootstrapping will be reproducible. If None, bootstrapping is non-reproducible.
data_is_uncorrelated – Whether the provided data is uncorrelated. If this option is set, the equilibration, decorrelation and tail pruning of the trajectory is skipped. This can speed up the analysis, but note that if the provided data is correlated, the results of the physical validation checks might be invalid.
- Returns
result (List[float] or List[Tuple[float]]) – If strict=True: The p value for every test. If strict=False: Distance of the estimated T(mu) and T(sigma) from the expected temperature, measured in standard deviations of the respective estimate, for every test.
ndof_molec (List[dict]) – List of the degrees of freedom per molecule. Can be saved to increase speed of repeated analysis of the same simulation run.
kin_molec (List[List[dict]]) – List of the kinetic energy per molecule per frame. Can be saved to increase speed of repeated analysis of the same simulation run.
See also
physical_validation.kinetic_energy.check_equipartitionHigh-level version
- physical_validation.util.kinetic_energy.calc_ndof(natoms: int, nmolecs: int, molec_idx: numpy.ndarray, molec_nbonds: numpy.ndarray, ndof_reduction_tra: float, ndof_reduction_rot: float) List[Dict[str, float]][source]
Calculates the total / translational / rotational & internal / rotational / internal degrees of freedom per molecule.
- Parameters
natoms – Total number of atoms in the system
nmolecs – Total number of molecules in the system
molec_idx – Index of first atom for every molecule
molec_nbonds – Number of bonds for every molecule
ndof_reduction_tra – Number of center-of-mass translational degrees of freedom tobremove.
ndof_reduction_rot – Number of center-of-mass rotational degrees of freedom to remove.
- Returns
List of dictionaries containing the degrees of freedom for each molecule Keys: [‘total’, ‘translational’, ‘rotational and internal’, ‘rotational’, ‘internal’]
- Return type
ndof_molec
- physical_validation.util.kinetic_energy.calc_molec_kinetic_energy(pos: numpy.ndarray, vel: numpy.ndarray, masses: numpy.ndarray, molec_idx: numpy.ndarray, natoms: int, nmolecs: int) Dict[str, numpy.ndarray][source]
Calculates the total / translational / rotational & internal / rotational / internal kinetic energy per molecule.
- Parameters
pos (nd-array (natoms x 3)) – 2d array containing the positions of all atoms
vel (nd-array (natoms x 3)) – 2d array containing the velocities of all atoms
masses (nd-array (natoms x 1)) – 1d array containing the masses of all atoms
molec_idx (nd-array (nmolecs x 1)) – Index of first atom for every molecule
natoms – Total number of atoms in the system
nmolecs – Total number of molecules in the system
- Returns
Dictionary of lists containing the kinetic energies for each molecule Keys: [‘total’, ‘translational’, ‘rotational and internal’, ‘rotational’, ‘internal’]
- Return type
kin
- physical_validation.util.kinetic_energy.group_kinetic_energy(kin_molec: Dict[str, numpy.ndarray], nmolecs: int, molec_group=typing.Optional[typing.Iterable[int]]) Dict[str, float][source]
Sums up the partitioned kinetic energy for a given group or the entire system.
- Parameters
kin_molec – Partitioned kinetic energies per molecule.
nmolecs – Total number of molecules in the system.
molec_group – Indices of the group to be summed up. None defaults to all molecules in the system.
- Returns
kin – Dictionary of partitioned kinetic energy for the group.
- Return type
dict
- physical_validation.util.kinetic_energy.group_ndof(ndof_molec: List[Dict[str, float]], nmolecs: int, molec_group=typing.Optional[typing.Iterable[int]]) Dict[str, float][source]
Sums up the partitioned degrees of freedom for a given group or the entire system.
- Parameters
ndof_molec – Partitioned degrees of freedom per molecule.
nmolecs – Total number of molecules in the system.
molec_group – Indeces of the group to be summed up. None defaults to all molecules in the system.
- Returns
ndof – Dictionary of partitioned degrees of freedom for the group.
- Return type
dict
- physical_validation.util.kinetic_energy.test_group(kin_molec: List[Dict[str, numpy.ndarray]], ndof_molec: List[Dict[str, float]], nmolecs: int, temp: float, kb: float, dict_keys: List[str], strict: bool, group: Optional[Iterable[int]], verbosity: int, screen: bool, filename: Optional[str], ene_unit: Optional[str], temp_unit: Optional[str], bootstrap_seed: Optional[int], data_is_uncorrelated: bool) Union[List[float], List[Tuple[float, float]]][source]
Tests if the partitioned kinetic energy trajectory of a group (or, if group is None, of the entire system) are separately Maxwell-Boltzmann distributed.
- Parameters
kin_molec – Partitioned kinetic energies per molecule for every frame.
ndof_molec – Partitioned degrees of freedom per molecule.
nmolecs – Total number of molecules in the system.
temp – Target temperature of the simulation.
kb – Boltzmann constant \(k_B\).
dict_keys – List of dictionary keys representing the partitions of the degrees of freedom.
strict – If True, check full kinetic energy distribution via K-S test. Otherwise, check mean and width of kinetic energy distribution.
group – Indices of the group to be tested. None defaults to all molecules in the system.
verbosity – Verbosity level, where 0 is quiet and 3 very chatty.
screen – Plot distributions on screen.
filename – Plot distributions to filename. If None, no plotting.
ene_unit – Energy unit - used for output only.
temp_unit – Temperature unit - used for output only.
bootstrap_seed – Sets the random number seed for bootstrapping (if strict=False). If set, bootstrapping will be reproducible. If None, bootstrapping is non-reproducible.
data_is_uncorrelated – Whether the provided data is uncorrelated. If this option is set, the equilibration, decorrelation and tail pruning of the trajectory is skipped. This can speed up the analysis, but note that if the provided data is correlated, the results of the physical validation checks might be invalid.
- Returns
p value for every partition (strict) or tuple of distance of estimated T(mu) and T(sigma) for every partition (non-strict)
- Return type
result
physical_validation.util.ensemble module
This file reimplements most functionality of the checkensemble.py code
originally published on https://github.com/shirtsgroup/checkensemble. It
serves as the low-level functionality of the high-level module
physical_validation.ensemble.
- physical_validation.util.ensemble.pymbar_bar(work_forward: numpy.ndarray, work_backward: numpy.ndarray) Dict[str, float][source]
Wrapper around the pymbar BAR functionality, allowing the remaining code to be agnostic of the pymbar version used.
- Parameters
work_forward (Array of forward work values) –
work_backward (Array of backward work values) –
- Returns
- Return type
A dictionary containing the free energy estimate and its error estimate
- physical_validation.util.ensemble.chemical_potential_energy(chemical_potential: numpy.ndarray, number_of_species: numpy.ndarray) numpy.ndarray[source]
Calculates the chemical potential energy of a trajectory by returning the sum of the current number of species multiplied by the chemical potential.
- physical_validation.util.ensemble.generate_histograms(traj1: numpy.ndarray, traj2: numpy.ndarray, g1: float, g2: float, bins: numpy.ndarray) Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]
- physical_validation.util.ensemble.do_linear_fit(traj1: numpy.ndarray, traj2: numpy.ndarray, g1: float, g2: float, bins: numpy.ndarray, screen: bool, filename: Optional[str], trueslope: float, trueoffset: float, units: Optional[str], xlabel: str, ylabel: str) Tuple[numpy.ndarray, numpy.ndarray][source]
- physical_validation.util.ensemble.do_max_likelihood_fit(traj1: numpy.ndarray, traj2: numpy.ndarray, g1: Union[float, numpy.ndarray], g2: Union[float, numpy.ndarray], init_params: numpy.ndarray, verbose: bool) Tuple[numpy.ndarray, numpy.ndarray][source]
- physical_validation.util.ensemble.checkensemble_solver(fun, x0, args, jac, hess, tol=1e-10, maxiter=20) scipy.optimize._optimize.OptimizeResult[source]
- physical_validation.util.ensemble.check_bins(traj1: numpy.ndarray, traj2: numpy.ndarray, bins: numpy.ndarray) numpy.ndarray[source]
- physical_validation.util.ensemble.print_stats(title: str, fitvals: numpy.ndarray, dfitvals: Optional[numpy.ndarray], kb: float, param1: Union[float, numpy.ndarray], param2: Union[float, numpy.ndarray], trueslope: Union[float, numpy.ndarray], temp: Optional[float], pvconvert: Optional[float], dtemp: bool, dpress: bool, dmu: bool, dtempdpress: bool, dtempdmu: bool) None[source]
- physical_validation.util.ensemble.estimate_interval(ens_string: str, ens_temp: float, energy: numpy.ndarray, kb: float, ens_press: Optional[float], volume: Optional[numpy.ndarray], pvconvert: Optional[float], ens_mu: Optional[numpy.ndarray], species_number: Optional[numpy.ndarray], verbosity: int, cutoff: float, tunit: str, punit: str, munit: str, data_is_uncorrelated: bool) Dict[str, Union[float, List[float]]][source]
- physical_validation.util.ensemble.check_1d(traj1: numpy.ndarray, traj2: numpy.ndarray, param1: float, param2: float, kb: float, quantity: str, dtemp: bool, dpress: bool, dmu: bool, temp: Optional[float], pvconvert: Optional[float], nbins: int, cutoff: float, bootstrap_seed: Optional[int], bootstrap_error: bool, bootstrap_repetitions: int, verbosity: int, screen: bool, filename: str, xlabel: str, xunit: Optional[str], data_is_uncorrelated: bool) List[float][source]
Checks whether the energy trajectories of two simulation performed at different temperatures have sampled distributions at the analytically expected ratio.
- Parameters
traj1 –
Trajectory of the first simulation If dtemp:
NVT: Potential energy U or total energy E = U + K
NPT: Enthalpy H = U + pV or total energy E = H + K
If dpress:
NPT: Volume V
traj2 –
Trajectory of the second simulation If dtemp:
NVT: Potential energy U or total energy E = U + K
NPT: Enthalpy H = U + pV or total energy E = H + K
If dpress:
NPT: Volume V
param1 – Target temperature or pressure of the first simulation
param2 – Target temperature or pressure of the second simulation
kb – Boltzmann constant in same units as the energy trajectories
quantity – Name of quantity analyzed (used for printing only)
dtemp – Set to True if trajectories were simulated at different temperature
dpress – Set to True if trajectories were simulated at different pressure
temp – The temperature in equal temperature, differing pressure NPT simulations. Needed to print optimal dP.
pvconvert – Conversion from pressure * volume to energy units. Needed to print optimal dP.
dmu – Set to True if trajectories were simulated at different chemical potential
nbins – Number of bins used to assess distributions of the trajectories
cutoff – Tail cutoff of distributions.
bootstrap_seed – Sets the random number seed for bootstrapping. If set, bootstrapping will be reproducible. If None, bootstrapping is non-reproducible.
bootstrap_error – Calculate the standard error via bootstrap resampling
bootstrap_repetitions – Number of bootstrap repetitions drawn
verbosity – Verbosity level.
screen – Plot distributions on screen.
filename – Plot distributions to filename. If None, no plotting.
xlabel – x-axis label used for plotting
xunit – x-axis label unit used for plotting
data_is_uncorrelated – Whether the provided data is uncorrelated. If this option is set, the equilibration, decorrelation and tail pruning of the trajectory is skipped. This can speed up the analysis, but note that if the provided data is correlated, the results of the physical validation checks might be invalid.
- Returns
- Return type
The number of quantiles the computed result is off the analytical one.
- physical_validation.util.ensemble.check_2d(traj1: numpy.ndarray, traj2: numpy.ndarray, param1: numpy.ndarray, param2: numpy.ndarray, kb: float, pvconvert: Optional[float], quantity: List[str], dtempdpress: bool, dtempdmu: bool, cutoff: float, bootstrap_seed: Optional[int], bootstrap_error: bool, bootstrap_repetitions: int, verbosity: int, screen: bool, filename: Optional[str], data_is_uncorrelated: bool) List[float][source]
Checks whether the energy trajectories of two simulation performed at different temperatures have sampled distributions at the analytically expected ratio.
- Parameters
traj1 –
Trajectory of the first simulation If dtempdpress:
traj[0,:]: Potential energy U or total energy E = U + K
traj[1,:]: Volume V
traj2 –
Trajectory of the second simulation If dtempdpress:
traj[0,:]: Potential energy U or total energy E = U + K
traj[1,:]: Volume V
param1 –
- If dtempdpress:
Target temperature and pressure of the first simulation
param2 –
- If dtempdpress:
Target temperature and pressure of the first simulation
kb – Boltzmann constant in same units as the energy trajectories
pvconvert – Conversion from pressure * volume to energy units
quantity – Names of quantities analyzed (used for printing only)
dtempdpress – Set to True if trajectories were simulated at different temperature and pressure
dtempdmu – Set to True if trajectories were simulated at different temperature and chemical potential
cutoff – Tail cutoff of distributions.
bootstrap_seed – Sets the random number seed for bootstrapping. If set, bootstrapping will be reproducible. If None, bootstrapping is non-reproducible.
bootstrap_error – Calculate the standard error via bootstrap resampling
bootstrap_repetitions – Number of bootstrap repetitions drawn
verbosity – Verbosity level.
screen – Plot distributions on screen.
filename – Plot distributions to filename. If None, no plotting.
data_is_uncorrelated – Whether the provided data is uncorrelated. If this option is set, the equilibration, decorrelation and tail pruning of the trajectory is skipped. This can speed up the analysis, but note that if the provided data is correlated, the results of the physical validation checks might be invalid. Default: False
- Returns
- Return type
The number of quantiles the computed result is off the analytical one.
physical_validation.util.integrator module
This module contains low-level functionality of the physical_validation.integrator module. The functions in this module should generally not be called directly. Please use the high-level functions from physical_validation.integrator.
- physical_validation.util.integrator.calculate_rmsd(data: numpy.ndarray, time: Optional[numpy.ndarray]) Tuple[float, float, float][source]
physical_validation.util.trajectory module
- physical_validation.util.trajectory.cut_tails(traj: numpy.ndarray, cut: float) numpy.ndarray[source]
- physical_validation.util.trajectory.prepare(traj: numpy.ndarray, cut: Optional[float] = None, verbosity: int = 1, name: Optional[str] = None, skip_preparation: bool = False) numpy.ndarray[source]
physical_validation.util.plot module
- physical_validation.util.plot.plot(res: List[Dict[str, Union[numpy.ndarray, str, Dict]]], legend: Optional[str] = None, title: Optional[str] = None, xlabel: Optional[str] = None, ylabel: Optional[str] = None, xlim: Optional[Tuple[float, float]] = None, ylim: Optional[Tuple[float, float]] = None, inv_x: bool = False, inv_y: bool = False, sci_x: bool = False, sci_y: bool = False, axtext: Optional[str] = None, annotation_location: Optional[str] = None, percent: bool = False, filename: Optional[str] = None, screen: bool = True) None[source]
physical_validation.util.error module
Module containing the custom exception classes for the physical_validation package.
- exception physical_validation.util.error.PhysicalValidationError[source]
Base class for exceptions in the physical_validation module.
physical_validation.util.gromacs_interface module
GROMACS python interface.
Warning
This is a mere place holder, as an official python API is currently being developed by the gromacs development team. It is probably neither especially elegant nor especially safe. Use of this module in any remotely critical application is strongly discouraged.
- class physical_validation.util.gromacs_interface.GromacsInterface(exe: Optional[str] = None, dp: bool = False, includepath: Optional[Union[str, List[str]]] = None)[source]
- property exe: str
exe is a string pointing to the gmx executable.
- property double: bool
double is a bool defining whether the simulation was ran at double precision
- property includepath: List[str]
includepath defines a path the parser looks for system files
- get_quantities(edr: str, quantities: List[str], cwd: Optional[str] = None, begin: Optional[float] = None, end: Optional[float] = None, args: Optional[List[str]] = None) Dict[str, numpy.ndarray][source]
- read_trr(trr: str) Dict[str, Optional[Union[numpy.ndarray, physical_validation.data.trajectory_data.RectangularBox]]][source]
- static read_gro(gro: str) Dict[str, Optional[Union[numpy.ndarray, physical_validation.data.trajectory_data.RectangularBox]]][source]
- read_system_from_top(top: str, define: Optional[str] = None, include: Optional[str] = None) List[Dict[str, Any]][source]