Scoring

This module consists of several built in scoring functions as well as helper functions to setup scoring. In addition to the built in scoring functions, users can also define their own scoring functions. The only requirements are that the scoring function accepts a RotamerEnsemble or SpinLabel object and outputs an energy score for each rotamer in the ensemble. The energy score should be in kcal/mol.

clash_only(func)

Decorator to convert a Lennard-Jones style clash evaluation function into a chiLife compatible energy func.

Parameters:

func (callable) – Python function object that computes the (modified) Lennard-Jones potential given arrays of atom pair distances, r, rmin values rmin, energies, eps, and additional keyword arguments.

Returns:

energy_func – The original input function now wrapped to accept a protein object and, optionally, a RotamerEnsemble/SpinLabel object.

Return type:

callable

get_lj_energy(r, rmin, eps, forgive=1, cap=10, rmax=10)

Return a vector with the energy values for the flat bottom lenard-jones potential from a set of atom pairs with distance r, rmin values of rmin and epsilon values of eps.

Parameters:

• r (numpy.ndarray) – Vector of inter-atomic distances between non-bonded atoms of a system.

• rmin (numpy.ndarray) – Vector of rmin parameters, in angstoms, corresponding to atoms pairs of r.

• eps (numpy.ndarray) – Vector of epsilon parameters corresponding to atom pairs of r

• forgive (numpy.ndarray) – The forgive factor is a softening term to mitigate rigid body artifacts. It is set to a value between 0 1nd 1 and modifies the rmin parameter of all atom pairs in r to be the fraction, forgive of the thair original value. This allows atoms to be closer than otherwise allowed to prevent explosion of the jennard-jones repulsion in situations that would otherwise be resolved with minor atomic displacements.

• cap (flaot) – Maximum allowed energy factor. Sets a cap on the maximum energy contribution of one atom pair interaction as another mechanism for softening. cap is sets the actual max value as a multiple of the eps parameter. i.e. the maximum allowed energy from a single atom pair interaction is the eps parameter multiplied by cap.

• rmax (float) – Maximum distance to consider for potential calculation. Any atom pairs with r > rmax will be set to 0.

Returns:

lj_energy – Vector of atom pair energies calculated using the modified lj potential function.

Return type:

numpy.ndarray

get_lj_scwrl(r, rmin, eps, forgive=1)

Calculate a scwrl-like lenard-jones potential from a set of atom pairs with distance r, rmin values of rmin and epsilon values of eps.

Parameters:

• r (numpy.ndarray) – Vector of inter-atomic distances between non-bonded atoms of a system.

• rmin (numpy.ndarray) – Vector of rmin parameters, in angstoms, corresponding to atoms pairs of r.

• eps (numpy.ndarray) – Vector of epsilon parameters corresponding to atom pairs of r

• forgive (numpy.ndarray) – The forgive factor is a softening term to mitigate rigid body artifacts. It is set to a value between 0 1nd 1 and modifies the rmin parameter of all atom pairs in r to be the fraction, forgive of the thair original value. This allows atoms to be closer than otherwise allowed to prevent explosion of the jennard-jones repulsion in situations that would otherwise be resolved with minor atomic displacements.

Returns:

lj_energy – Vector of atom pair energies calculated using the modified lj potential function.

Return type:

numpy.ndarray

get_lj_rep(r, rmin, eps, forgive=0.9, cap=10)

Calculate only the repulsive terms of the lenard-jones potential from a set of atom pairs with distance r, rmin values of rmin and epsilon values of eps.

Parameters:

• r (numpy.ndarray) – Vector of inter-atomic distances between non-bonded atoms of a system.

• rmin (numpy.ndarray) – Vector of rmin parameters, in angstoms, corresponding to atoms pairs of r.

• eps (numpy.ndarray) – Vector of epsilon parameters corresponding to atom pairs of r

• forgive (numpy.ndarray) – The forgive factor is a softening term to mitigate rigid body artifacts. It is set to a value between 0 1nd 1 and modifies the rmin parameter of all atom pairs in r to be the fraction, forgive of the thair original value. This allows atoms to be closer than otherwise allowed to prevent explosion of the jennard-jones repulsion in situations that would otherwise be resolved with minor atomic displacements.

• cap (flaot) – Maximum allowed energy factor. Sets a cap on the maximum energy contribution of one atom pair interaction as another mechanism for softening. cap is sets the actual max value as a multiple of the eps parameter. i.e. the maximum allowed energy from a single atom pair interaction is the eps parameter multiplied by cap.

Returns:

lj_energy – Vector of atom pair energies calculated using the modified lj potential function.

Return type:

numpy.ndarray

get_lj_attr(r, rmin, eps, forgive=0.9, floor=-2)

Calculate only the attractive terms of the lenard-jones potential from a set of atom pairs with distance r, rmin values of rmin and epsilon values of eps.

Parameters:

• r (numpy.ndarray) – Vector of inter-atomic distances between non-bonded atoms of a system.

• rmin (numpy.ndarray) – Vector of rmin parameters, in angstoms, corresponding to atoms pairs of r.

• eps (numpy.ndarray) – Vector of epsilon parameters corresponding to atom pairs of r

• forgive (numpy.ndarray) – The forgive factor is a softening term to mitigate rigid body artifacts. It is set to a value between 0 1nd 1 and modifies the rmin parameter of all atom pairs in r to be the fraction, forgive of the thair original value. This allows atoms to be closer than otherwise allowed to prevent explosion of the jennard-jones repulsion in situations that would otherwise be resolved with minor atomic displacements.

• cap (flaot) – Maximum allowed energy factor. Sets a cap on the maximum energy contribution of one atom pair interaction as another mechanism for softening. cap is sets the actual max value as a multiple of the eps parameter. i.e. the maximum allowed energy from a single atom pair interaction is the eps parameter multiplied by cap.

Returns:

lj_energy – Vector of atom pair energies calculated using the modified lj potential function.

Return type:

numpy.ndarray

prep_external_clash(ensemble, forcefield=None)

Helper function to prepare the lj parameters of a rotamer ensemble, presumably with an associated protein.

Parameters:

ensemble (RotamerEnsemble) – The RotamerEnsemble to prepare the clash parameters for. The RotamerEnsemble should have an associated protein.

Returns:

• dist (numpy.ndarray) – Array of pairwise distances between atoms in the RotamerEnsemble and atoms in the associated protein.

• rmin_ij (numpy.ndarray) – rmin parameters of the lj potential associated with the atom i and atom j pair.

• eps_ij (numpy.ndarray) – eps parameters of the lj potential associated with the atom i and atom j pair.

• shape (Tuple[int]) – Shape the array should be so that the energy is evaluated for each rotamer of the ensemble separately.

prep_internal_clash(ensemble)

Helper function to prepare the lj parameters of a rotamer ensemble to evaluate internal clashes.

Parameters:

ensemble (RotamerEnsemble) – The RotamerEnsemble to prepare the clash parameters for.

Returns:

• dist (numpy.ndarray) – Array of pairwise distances between atoms in the RotamerEnsemble and atoms in the associated protein.

• rmin_ij (numpy.ndarray) – rmin parameters of the lj potential associated with the atom i and atom j pair.

• eps_ij (numpy.ndarray) – eps parameters of the lj potential associated with the atom i and atom j pair.

• shape (Tuple[int]) – Shape the array should be so that the energy is evaluated for each rotamer of the ensemble separately.

reweight_rotamers(energies, temp, weights)

Adjust rotamer population weights based on external energies (from clash evaluations).

Parameters:

• energies (numpy.ndarray) – Array of external energies, in kcal/mol

• temp (scalar) – Temperature, in kelvin

• weights (numpy.ndarray) – Current weights of rotamers

• return_partition (bool) – If True, return the value of the partition function an additional argument; see below

Returns:

• new_weights (numpy.ndarray) – Adjusted weights

• partition (float (optional)) – The partition function relative to the free label. A small partition function suggests the interactions with neighboring atoms are unfavorable while a large partition function suggests the opposite.

join_geom(a, b, flat=False)

Function to join Lennard-Jones parameters (rmin or eps) using their geometric mean. Parameters can be joined in two different ways (see keyword argument flat)

Parameters:

• a (numpy.ndarray) – Single atom parameters of atoms of group a

• b (numpy.ndarray) – Single atom parameters of atoms of group b

• flat (bool) – Only join parameters i of group a and j of group b if i=j. If false all combinations of i,j are computed.

Returns:

param – The joined parameters of group a and b

Return type:

numpy.ndarray

join_arith(a, b, flat=False)

Function to join Lennard-Jones parameters (rmin or eps) using their arithmatic mean. Parameters can be joined in two different ways (see keyword argument flat)

Parameters:

• a (numpy.ndarray) – Single atom parameters of atoms of group a

• b (numpy.ndarray) – Single atom parameters of atoms of group b

• flat (bool) – Only join parameters i of group a and j of group b if i=j. If false all combinations of i,j are computed.

Returns:

param – The joined parameters of group a and b

Return type:

numpy.ndarray