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

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

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_equipartition

High-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.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.integrator.max_deviation(dts: numpy.ndarray, rmsds: numpy.ndarray) float[source]
physical_validation.util.integrator.check_convergence(const_traj: Dict[str, numpy.ndarray], convergence_test: Callable[[numpy.ndarray, numpy.ndarray], float], verbose: bool, screen: bool, filename: Optional[str]) float[source]

physical_validation.util.trajectory module

physical_validation.util.trajectory.equilibrate(traj: numpy.ndarray) numpy.ndarray[source]
physical_validation.util.trajectory.decorrelate(traj: numpy.ndarray) numpy.ndarray[source]
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.trajectory.overlap(traj1: numpy.ndarray, traj2: numpy.ndarray, cut=None) Tuple[numpy.ndarray, numpy.ndarray, Optional[float], Optional[float]][source]
physical_validation.util.trajectory.bootstrap(traj: numpy.ndarray, n_samples: int) Iterator[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.

exception physical_validation.util.error.InputError(argument, message)[source]

Exception raised for input errors

exception physical_validation.util.error.FileFormatError(argument, message)[source]

Exception raised for files not following expected format

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]
static read_mdp(mdp: str) Dict[str, str][source]
static write_mdp(options: Dict[str, str], mdp: str)[source]
read_system_from_top(top: str, define: Optional[str] = None, include: Optional[str] = None) List[Dict[str, Any]][source]
grompp(mdp: str, top: str, gro: str, tpr: Optional[str] = None, cwd: str = '.', args: Optional[List[str]] = None, stdin: Union[None, int, IO[Any]] = None, stdout: Union[None, int, IO[Any]] = None, stderr: Union[None, int, IO[Any]] = None) int[source]
mdrun(tpr: str, edr: Optional[str] = None, deffnm: Optional[str] = None, cwd: str = '.', args: Optional[List[str]] = None, stdin: Union[None, int, IO[Any]] = None, stdout: Union[None, int, IO[Any]] = None, stderr: Union[None, int, IO[Any]] = None, mpicmd: Optional[str] = None) int[source]