API reference¶

This page documents the public API of the bayesmbar package. The documentation is generated automatically from the docstrings in the source code.

BayesMBAR¶

bayesmbar.BayesMBAR ¶

Bayesian Multistate Bennett Acceptance Ratio (BayesMBAR) method

init ¶

__init__(energy: ndarray, num_conf: ndarray, prior: Literal['uniform', 'normal'] = 'uniform', mean: Literal['constant', 'linear', 'quadratic'] = 'constant', kernel: Literal['SE', 'Matern52', 'Matern32', 'RQ'] = 'SE', state_cv: ndarray = None, sample_size: int = 1000, warmup_steps: int = 500, optimize_steps: int = 10000, verbose: bool = True, random_seed: int = 0, method: Literal['Newton', 'L-BFGS'] = 'Newton') -> None

Parameters:

Name	Type	Description	Default
`energy`	`ndarray`	Energy matrix of shape (m, n), where m is the number of states and n is the number of configurations.	required
`num_conf`	`ndarray`	Number of configurations in each state. It is a 1D array of length m.	required
`prior`	`str`	Prior distribution of dF. It can be either "uniform" or "normal". Defaults to "uniform".	`'uniform'`
`mean`	`str`	Mean function of the prior. It can be either "constant", "linear", or "quadratic". Defaults to "constant".	`'constant'`
`kernel`	`str`	Kernel function of the prior. It can be either "SE", "Matern52", "Matern32", or "RQ". Defaults to "SE".	`'SE'`
`state_cv`	`ndarray`	State collective variables. It is a 2D array of shape (m, d), where m is the number of states and d is the dimension of the collective variables. Defaults to None.	`None`
`sample_size`	`int`	Number of samples drawn from the posterior distribution. Defaults to 1000.	`1000`
`warmup_steps`	`int`	Number of warmup steps used to find the step size and mass matrix of the NUTS sampler. Defaults to 500.	`500`
`optimize_steps`	`int`	Number of optimization steps used to learn the hyperparameters when normal priors are used. Defaults to 10000.	`10000`
`verbose`	`bool`	Whether to print the progress bar for the optimization and sampling. Defaults to True.	`True`
`random_seed`	`int`	Random seed. Defaults to 0.	`0`
`method`	`str`	Optimization method used to compute the mode of the likelihood and the posterior distribution. It can be either "Newton" or "L-BFGS". Defaults to "Newton".	`'Newton'`

F_mode `property` ¶

F_mode: NDArray

The posterior mode estimate of the free energies of the states under the constraints that :math:\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k and :math:F_k are the number of conformations and the free energy of the k-th state, respectively.

F_mean `property` ¶

F_mean: NDArray

The posterior mean of the free energies of the states under the constraints that :math:\\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k and :math:F_k are the number of conformations and the free energy of the k-th state, respectively.

F_cov `property` ¶

F_cov: NDArray

The posterior covariance matrix of the free energies of the states under the constraints that :math:\\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k and :math:F_k are the number of conformations and the free energy of the k-th state, respectively.

F_std `property` ¶

F_std: NDArray

The posterior standard deviation of the free energies of the states under the constraints that :math:\\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k and :math:F_k are the number of conformations and the free energy of the k-th state, respectively.

F_samples `property` ¶

F_samples: NDArray

The samples of the free energies of the states from the posterior distribution under the constraints that :math:\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k and :math:F_k are the number of conformations and the free energy of the k-th state, respectively.

DeltaF_mode `property` ¶

DeltaF_mode: NDArray

The posterior mode estimate of free energy difference between states. DeltaF_mode[i,j] is the free energy difference between state :math:j and state :math:i, i.e., DeltaF_mode[i,j] = F_mode[j] - F_mode[i].

DeltaF_mean `property` ¶

DeltaF_mean: NDArray

The posterior mean of free energy difference between states. DeltaF_mean[i,j] is the free energy difference between state :math:j and state :math:i, i.e., DeltaF_mean[i,j] = F_mean[j] - F_mean[i].

DeltaF_std `property` ¶

DeltaF_std: NDArray

The posterior standard deviation of free energy difference between states. DeltaF_std[i,j] is the posterior standard deviation of the free energy difference between state :math:j and state :math:i,

CBayesMBAR¶

bayesmbar.CBayesMBAR ¶

Coupled BayesMBAR

init ¶

__init__(energies: list[ndarray], nums_conf: list[ndarray], identical_states: list[list[tuple[int, int]]], sample_size: int = 1000, warmup_steps: int = 500, method: str = 'Newton', random_seed: int = None, verbose: bool = True)

Parameters:

Name	Type	Description	Default
`energies`	`List[ndarray]`	A list of energies for all coupled MBAR systems. The energies should be in the unit of kT.	required
`nums_conf`	`List[ndarray]`	A list of the number of configurations for all coupled MBAR systems.	required
`identical_states`	`List[List[int, int]]`	A list of identical states. Each element in the outer list is a list of tuples and represents a group of states that are identical to each other. States are represented by a tuple where the first element is the index of a MBAR system and the second element is the index of the state in that MBAR system. For example, identical_states = [[(0, 3), (1, 0)], [(1, 3), (2, 0), (3, 0)]] means that state 3 in system 0 is identical to state 0 in system 1, and state 3 in system 1 is identical to state 0 in system 2, and state 0 in system 3.	required
`sample_size`	`int`	The number of samples to draw from the likelihood. Defaults to 1000.	`1000`
`warmup_steps`	`int`	The number of warmup steps for the HMC sampler. Defaults to 500.	`500`
`method`	`str`	The optimization method for finding the mode of the likelihood. Options are "Newton" or "L-BFGS". Defaults to "Newton".	`'Newton'`
`random_seed`	`int`	The random seed. Defaults to None, which means the random seed is generated from the current time.	`None`
`verbose`	`bool`	Whether to print out the progress of the sampling. Defaults to True.	`True`

F_mode `property` ¶

F_mode: list[ndarray]

The mode of free energies of all states in all MBAR systems. The free energy of state 0 in each system is set to 0.

F_samples `property` ¶

F_samples: list[ndarray]

The samples of free energies of all states in all MBAR systems. The free energy of state 0 in each system is set to 0.

F_mean `property` ¶

F_mean: list[ndarray]

The mean of free energies of all states in all MBAR systems. The free energy of state 0 in each system is set to 0.

DeltaF_mode `property` ¶

DeltaF_mode: list[ndarray]

The mode of free energy differences between all pairs of states in every MBAR system.

DeltaF_mean `property` ¶

DeltaF_mean: list[ndarray]

The mean of free energy differences between all pairs of states in every MBAR system.

DeltaF_std `property` ¶

DeltaF_std: list[ndarray]

The standard deviation of free energy differences between all pairs of states in every MBAR system.

BayesBAR¶

bayesmbar.BayesBAR ¶

Bayesian Bennett acceptance ratio method

init ¶

__init__(energy: ndarray, num_conf: ndarray, sample_size: int = 1000, method: str = 'Newton', verbose=False, dF_init=jnp.zeros(1, dtype=(jnp.float64)))

Initialize the BayesBAR class.

Parameters:

Name	Type	Description	Default
`energy`	`ndarray`	An energy matrix in reduced units. Its size should be 2xN, where N is the total number of samples from the two states.	required
`num_conf`	`ndarray`	Number of configurations in each state. Its size should be (2,).	required
`sample_size`	`int`	The number of samples from the posterior distribution. Defaults to 1000.	`1000`
`method`	`str`	Optimization method for finding the mode. Options are "Newton" or "L-BFGS". Defaults to "Newton".	`'Newton'`
`verbose`	`bool`	Whether to print running information. Defaults to False.	`False`

DeltaF_mode `property` ¶

DeltaF_mode: ndarray

The posterior mode of the free energy difference.

DeltaF_mean `property` ¶

DeltaF_mean: ndarray

The posterior mean of the free energy difference.

DeltaF_std `property` ¶

DeltaF_std: ndarray

The posterior standard deviation of the free energy difference.

DeltaF_samples `property` ¶

DeltaF_samples: ndarray

The samples from the posterior distribution of the free energy difference.

FastMBAR¶

bayesmbar.FastMBAR ¶

The FastMBAR class is initialized with an energy matrix and an array of num of conformations. The corresponding MBAR equation is solved in the constructor. Therefore, the relative free energies of states used in the energy matrix is calculated in the constructor. The method calculate_free_energies_for_perturbed_states can be used to calculated the relative free energies of perturbed states.

init ¶

__init__(energy: NDArray[float64], num_conf: NDArray[int64], bootstrap: bool = False, bootstrap_block_size: int = 3, bootstrap_num_rep: int = 100, verbose: bool = False, method: str = 'Newton', F_init: NDArray[float64] = None) -> None

Initializer for the class FastMBAR

Parameters:

Name	Type	Description	Default
`energy`	`2D ndarray`	It has a size of (M x N), where M is the number of states and N is the total number of conformations. The entry energy[i,j] is the reduced (unitless) energy of conformation j in state i. If bootstrapping is used to calculate the uncertainty, the order of conformations matters. Conformations sampled from one state need to occpy a continuous chunk of collumns. Conformations sampled from state k need to occupy collumns to the left of conformations sampled from state l if k < l. If bootstrapping is not used, then the order of conformation does not matter.	required
`num_conf`	`1D int ndarray`	It should have a size of M, where num_conf[i] is the num of conformations sampled from state i. Therefore, np.sum(num_conf) has to be equal to N. All entries in num_conf have to be strictly greater than 0.	required
`bootstrap`	`bool`	If bootstrap is True, the uncertainty of the calculated free energies will be estimate using block bootstraping. Defaults to False.	`False`
`bootstrap_block_size`	`int`	block size used in block bootstrapping. Defaults to 3.	`3`
`bootstrap_num_rep`	`int`	number of repreats in block bootstrapping. Defaults to 100.	`100`
`verbose`	`bool`	if verbose is true, the detailed information of solving MBAR equations is printed. Defaults to False.	`False`
`method`	`str`	the method used to solve the MBAR equation. Defaults to "Newton".	`'Newton'`
`F_init`	`1D ndarray`	The initial guess for the relative free energies. If None, the initial guess is set to zero. Defaults to None.	`None`

F `property` ¶

F: ndarray

Free energies of the states under the constraint :math:\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k is the number of conformations sampled from state k.

F_std `property` ¶

F_std: ndarray

Standard deviation of the free energies of the states under the constraint :math:\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k is the number of conformations sampled from state k.

F_cov `property` ¶

F_cov: ndarray

Covariance matrix of the free energies of the states under the constraint :math:\sum_{k=1}^{M} N_k * F_k = 0, where :math:N_k is the number of conformations sampled from state k.

DeltaF `property` ¶

DeltaF: ndarray

Free energy difference between states. :math:\mathrm{DeltaF}[i,j] is the free energy difference between state j and state i, i.e., :math:\mathrm{DeltaF}[i,j] = F[j] - F[i] .

DeltaF_std `property` ¶

DeltaF_std: ndarray

Standard deviation of the free energy difference between states. :math:\mathrm{DeltaF_std}[i,j] is the standard deviation of the free energy difference :math:\mathrm{DeltaF}[i,j].

log_prob_mix `property` ¶

log_prob_mix: ndarray

the log probability density of conformations in the mixture distribution.

calculate_free_energies_of_perturbed_states ¶

calculate_free_energies_of_perturbed_states(energy_perturbed: NDArray[float64]) -> dict

calculate free energies for perturbed states.

Parameters:

Name	Type	Description	Default
`energy_perturbed`	`2-D float ndarray`	A matrix with size of (L, N). Each row of the energy_perturbed matrix represents a state and the value energy_perturbed[l,n] represents the reduced energy of the n'th conformation in the l'th perturbed state.	required

Returns:

Name	Type	Description
`dict`	`dict`	a dictionary containing the following keys: F - the free energy of the perturbed states. F_std - the standard deviation of the free energy of the perturbed states. F_cov - the covariance between the free energies of the perturbed states. DeltaF - \(\mathrm{DeltaF}[k,l]\) is the free energy difference between state \(k\) and state \(l\), i.e., \(\mathrm{DeltaF}[k,l] = F[l] - F[k]\). DeltaF_std - the standard deviation of the free energy difference.

API reference¶

BayesMBAR¶

bayesmbar.BayesMBAR ¶

__init__ ¶

F_mode property ¶

F_mean property ¶

F_cov property ¶

F_std property ¶

F_samples property ¶

DeltaF_mode property ¶

DeltaF_mean property ¶

DeltaF_std property ¶

CBayesMBAR¶

bayesmbar.CBayesMBAR ¶

__init__ ¶

F_mode property ¶

F_samples property ¶

F_mean property ¶

DeltaF_mode property ¶

DeltaF_mean property ¶

DeltaF_std property ¶

BayesBAR¶

bayesmbar.BayesBAR ¶

__init__ ¶

DeltaF_mode property ¶

DeltaF_mean property ¶

DeltaF_std property ¶

DeltaF_samples property ¶

FastMBAR¶

bayesmbar.FastMBAR ¶

__init__ ¶

F property ¶

F_std property ¶

F_cov property ¶

DeltaF property ¶

DeltaF_std property ¶

log_prob_mix property ¶

calculate_free_energies_of_perturbed_states ¶

init ¶

F_mode `property` ¶

F_mean `property` ¶

F_cov `property` ¶

F_std `property` ¶

F_samples `property` ¶

DeltaF_mode `property` ¶

DeltaF_mean `property` ¶

DeltaF_std `property` ¶

init ¶

F_mode `property` ¶

F_samples `property` ¶

F_mean `property` ¶

DeltaF_mode `property` ¶

DeltaF_mean `property` ¶

DeltaF_std `property` ¶

init ¶

DeltaF_mode `property` ¶

DeltaF_mean `property` ¶

DeltaF_std `property` ¶

DeltaF_samples `property` ¶

init ¶

F `property` ¶

F_std `property` ¶

F_cov `property` ¶

DeltaF `property` ¶

DeltaF_std `property` ¶

log_prob_mix `property` ¶