Add new utility functions

[jeff231li]

This PR adds and improves on utility functions used to aid in system setup and restraint preparation.

Modified

1. align.py::zalign
   • Adds an option to choose an axis other than z to align to. Example,

structure = zalign(structure, ":BUT@C", ":BUT@C3", axis='y')

2. align.py::get_theta

   • Generalize the choice of axis using the align.py::_return_array function.

3. align.py::offset_structure

   • Generalize the offset so that the user can specify a single number and choose a specific dimension to shift the coordinates.
   • The two lines below achieves the same thing.

structure = offset_structure(structure, np.array([0, 0, 5]))
structure = offset_structure(structure, 5.0, axis='z')

New

1. align.py::align_principal_axes
   • Aligns a principal axis of a structure to a Cartesian axis. The function is based on the method in https://www.ks.uiuc.edu/Research/vmd/script_library/scripts/orient/

structure = align_principal_axes(structure, principal_axis=1, axis='z')

2. align.py::translate_to_origin

   • Translate the center of a structure to the origin.

3. align.py::get_rotation_matrix

   • Generate a rotation matrix that will be used to rotate a vector to a reference ref_vector.
   • This module is created as a refactorization for align.py::zalign and align.py::align_principal_axes.

4. align.py::_return_array

   • A private function that will return an array for the axis or dimension used a number of functions in align.py.
   • This function allows the user to specify an axis with a string (like "x"), a list ([0,0,1]) or a numpy array and returns an array.

5. restraints/utils.py::extract_guest_restraints

   • This function is useful for analysis, in particular when calculating the ref_state_work. It basically extracts the guest restraints from a list of restraints that is loaded from a json file.
   • Generalizes the search to all the reaction coordinate of the guest molecule (r, theta, phi, alpha, beta, gamma) without user intervention.

6. restraints/utils.py::restraints_from_ascii

   • A function to read a comma-separated ASCII file of restraint definition and stores the restraint definition to a dictionary.
   • This is useful if the atom names of the host/guest do not follow a specific pattern. VMD can be used to define the bond, angle and dihedral with a mouse and these can be extracted to a file.

[codecov-commenter]

Codecov Report

Merging #129 into master will increase coverage by 0.44%.
The diff coverage is 80.47%.

[slochower]

align.py::align_principal_axes

Perhaps we should generalize align.py::zalign to also allow the user to specify the reference axs-vector other than [0,0,1].

Opps, yeah. I commented on the PR before thoroughly reading your text. Probably best to merge these two functions since they are so similar.

restraints/utils.py::restraints_from_ascii

A function to read a list of user-defined restraints from an ASCII file. This is useful is the atom names of the host/guest do not follow a specific pattern (usually when a structure is generated from docking, OE-toolkit, RDkit etc).

Is this somehow better than reading and writing JSON? I think this seems a little more fragile because of how the file is parsed.

Maybe better placed in io.py?

Good point.

restraints/utils.py::extract_guest_restraints

👍

[lgtm-com]

This pull request introduces 1 alert when merging 96219fe into 1bfce3a - view on LGTM.com

new alerts:

• 1 for Syntax error

[jeff231li]

@slochower can you take a look at this PR again, I want to move on to implementing the Gromacs support module.

Probably best to merge these two functions since they are so similar.

I've decided to keep the two functions (zalign and align_principal_axes) separate. I tried combining them but the input argument gets too convoluted and way too many if statements in the function. I did, however, refactor the code so that a separate function is created for generating the rotation matrix.

Is this somehow better than reading and writing JSON? I think this seems a little more fragile because of how the file is parsed.

I use this primarily for parsing restraints from a file generated from VMD. It's more convenient to use the mouse-click in VMD to select bonds, angles and dihedrals and then extract them to a file with a TCL script. I've added an example in the docs.

[slochower]

Lookin' good.

[slochower]

I use this primarily for parsing restraints from a file generated from VMD. It's more convenient to use the mouse-click in VMD to select bonds, angles and dihedrals and then extract them to a file with a TCL script. I've added an example in the docs.

Thanks, that definitely helped clarify things.

[slochower]

Looks good to go.