Attention
You are looking at the documentation for the pymbar 3 LTS branch. If you want to update to the latest pymbar version, see this page https://pymbar.readthedocs.io/en/stable/moving_from_pymbar3.html
Utilities : pymbar.utils
¶
These functions are some miscellaneous functions used by other parts of the pymbar
library.
- exception pymbar.utils.BoundsError¶
Could not determine bounds on free energy
- exception pymbar.utils.ConvergenceError¶
Convergence could not be achieved.
- exception pymbar.utils.DataError¶
Data is inconsistent.
- exception pymbar.utils.ParameterError¶
An error in the input parameters has been detected.
- exception pymbar.utils.TypeCastPerformanceWarning¶
- pymbar.utils.check_w_normalized(W, N_k, tolerance=0.0001)¶
Check the weight matrix W is properly normalized. The sum over N should be 1, and the sum over k by N_k should aslo be 1
- Parameters
- Wnp.ndarray, shape=(N, K), dtype=’float’
The normalized weight matrix for snapshots and states. W[n, k] is the weight of snapshot n in state k.
- N_knp.ndarray, shape=(K), dtype=’int’
N_k[k] is the number of samples from state k.
- tolerancefloat, optional, default=1.0e-4
Tolerance for checking equality of sums
- Returns
- NoneNoneType
Returns a None object if test passes, otherwise raises a ParameterError with appropriate message if W is not normalized within tolerance.
- pymbar.utils.ensure_type(val, dtype, ndim, name, length=None, can_be_none=False, shape=None, warn_on_cast=True, add_newaxis_on_deficient_ndim=False)¶
Typecheck the size, shape and dtype of a numpy array, with optional casting.
- Parameters
- val{np.ndaraay, None}
The array to check
- dtype{nd.dtype, str}
The dtype you’d like the array to have
- ndimint
The number of dimensions you’d like the array to have
- namestr
name of the array. This is used when throwing exceptions, so that we can describe to the user which array is messed up.
- lengthint, optional
How long should the array be?
- can_be_nonebool
Is
val == None
acceptable?- shapetuple, optional
What should be shape of the array be? If the provided tuple has Nones in it, those will be semantically interpreted as matching any length in that dimension. So, for example, using the shape spec
(None, None, 3)
will ensure that the last dimension is of length three without constraining the first two dimensions- warn_on_castbool, default=True
Raise a warning when the dtypes don’t match and a cast is done.
- add_newaxis_on_deficient_ndimbool, default=True
Add a new axis to the beginining of the array if the number of dimensions is deficient by one compared to your specification. For instance, if you’re trying to get out an array of
ndim == 3
, but the user provides an array ofshape == (10, 10)
, a new axis will be created with length 1 in front, so that the return value is of shape(1, 10, 10)
.
- Returns
- typechecked_valnp.ndarray, None
If val=None and can_be_none=True, then this will return None. Otherwise, it will return val (or a copy of val). If the dtype wasn’t right, it’ll be casted to the right shape. If the array was not C-contiguous, it’ll be copied as well.
Notes
The returned value will always be C-contiguous.
- pymbar.utils.kln_to_kn(kln, N_k=None, cleanup=False)¶
Convert KxKxN_max array to KxN max array
if self.N is not initialized, it will be here.
- Parameters
- u_klnnp.ndarray, float, shape=(KxLxN_max)
- N_k (optional)np.array
the N_k matrix from the previous formatting form
- cleanup (optional)bool
optional command to clean up, since u_kln can get very large
- pymbar.utils.kn_to_n(kn, N_k=None, cleanup=False)¶
Convert KxN_max array to N array
- Parameters
- u_kn: np.ndarray, float, shape=(KxN_max)
- N_k (optional)np.array
the N_k matrix from the previous formatting form
- cleanup (optional)bool
optional command to clean up, since u_kln can get very large