Module measure

Use this function to find all atoms within a specified distance of each
other in roughly O(N) time.
Returns a list of tuples in the form of: (atom1, atom2), where atom1 and
atom2 are atom indices.

This function is only roughly O(N) in the number of atoms in the
molecule because as dist increases it will reach the limit of O(N^2).
Its true cost is O(N*m) where m is the number of atoms in a cubic box
with edges of dist length.

st - Structure object
dist - distance threshold, in angstroms.
atoms - optionally consider only atoms with these indices
        (all atoms in CT by are scanned by default)

NOTE: Each atom pair is listed only once in the output.
NOTE: This funtion is efficient only for small distances (<3A)
NOTE: Periodic boundary conditions (PBC) are NOT honored.

Create a DistanceCell for the given structure and cutoff. If struct has the Chorus box properties, the distance cell will be PBC-aware.

Parameters:

• st (schrodinger.structure.Structure) - The input structure, may have the Chorus box properties.
• distance (float) - The cutoff for finding nearest neighbor atoms.
• honor_pbc (bool) - Whether to honor Periodic Boundary Conditions, if defined as properties in the "st" structure. Default is True.

Returns: schrodinger.infra.structure.DistanceCell

The distance cell.

Returns a list of atoms from st that are within the threshold distance
of st2.

Example: Get a list of receptor atoms close to the ligand:
    close_atoms = measure.get_atoms_close_to_structure(re_st, lig_st, 3.0)

@param st: Structure atoms from wich should be analyzed/returned.
@type st: L{structure.Structure}

@param other_st: Query structure.
@type other_st: L{structure.Structure}

@param cutoff: Distance theshold.
@type cutoff: float

@param honor_pbc: Honor Periodic Boundary Conditions, if defined as
    properties in the "st" structure. Default is True.
@type honor_pbc: bool

Returns a list of atoms from that are within the threshold distance
of "other_atoms" subset, and are not themselves in that subset.

Example: Get a list of receptor atoms close to the ligand:
    close_atoms = measure.get_atoms_close_to_subset(st, lig_atoms, 3.0)

@param st: Structure atoms from wich should be analyzed/returned.
@type st: L{structure.Structure}

@param other_atoms: Query atoms.
@type other_atoms: list of int

@param cutoff: Distance theshold.
@type cutoff: float

@param honor_pbc: Honor Periodic Boundary Conditions, if defined as
    properties in the "st" structure. Default is True.
@type honor_pbc: bool

Determines the shortest distance and indices of the nearest atoms
between two structures or between a groups of atoms in a single
structure.
NOTE: Periodic boundary conditions (PBC) are NOT honored.

@type st: L{schrodinger.structure.Structure}
@param st: Structure containing group(s) of atoms for
                nearest distance search.

@type atoms: list of ints
@param atoms: If specified, the distances between this group
              of atoms and all other atoms in st are evaluated.
                 Either atoms or st2, but not both, must be specified.

@type st2: L{schrodinger.structure.Structure}
@param st2: Structure of second group of atoms for
                nearest-distance search. Either st2 or
                atoms, but not both, must be specified.

@type cutoff: float
@param cutoff: Cutoff distance in Angstroms for nearest-distance search
               (by default no cutoff is used). Setting this parameter can
               speed the calculation by considering only points between
               sets that are within the cutoff value. None will be returned
               if no neighbors are found within the specified cutoff.

@rtype: tuple of float, int, int or None
@return: A tuple containing the nearest distance between atoms
         and the indices of the closest atoms between each set.

Create an iterator that uses a distance cell to iterate through neighbors of the specified atoms

Parameters:

• st (schrodinger.structure.Structure) - The structure to examine
• dist (float) - The distance cutoff for calculating neighbors. Either dist or cell_handle must be given, but not both.
• atoms (list) - A list of atom numbers to calculate neighbors for. If not, given, st.atom will be used.
• cell_handle (int) - A handle to an existing distance cell. If not given, a new distance cell will be created with distance dist. Either dist or cell_handle must be given, but not both.
• delete_dist_cell (bool) - If cell_handle is given and delete_dist_cell is True, then distance cell cell_handle will be deleted after iteration is complete. Has no effect if cell_handle is not given. Defaults to True.

Returns: iter

An iterator that iterates through neighbors of the specified atoms

Raises:

• ValueError - If both dist and cell_handle are not None

Measure the distance between two atoms.

All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.

See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.

NOTE: Periodic boundary conditions (PBC) are NOT honored.

Measure the atom between 3 specified atoms.

All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.

See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.

NOTE: Periodic boundary conditions (PBC) are NOT honored.

Measure the dihedral angle between the specified atoms.

All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.

See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.

NOTE: Periodic boundary conditions (PBC) are NOT honored.

Measure the angle between planes of the provided atoms.

All atom arguments must be _StructureAtom objects (returned from the
Structure.atom list, and can be from different structures), or XYZ
coordinates, as lists or numpy arrays.

See also the Structure.measure method. It can use integer atom indices
in addition to _StructureAtom objects, but is restricted to measurements
within the structure and cannot do plane angle measurements.

NOTE: Periodic boundary conditions (PBC) are NOT honored.

Parameters

minangle (bool)
    This applies to the planar angle calculation and if True restricts
    the angle to <= 90.0 degrees.  That is, it treats the order of atoms
    defining a plane as unimportant, and the directionality of the plane
    normals is ignored.

Fit a plane to a set of xyz coordinates

This method comes from http://stackoverflow.com/questions/15959411/fit-points-to-a-plane-algorithms-how-to-iterpret-results It is the SVD method appearing there.

Parameters:

• coords (numpy.array) - The coordinates to fit the plane to, such as come from struct.getXYZ()

Returns: numpy.array

An array of 3 floats that defines a normalized vector that is normal to the best-fit plane

Raises:

• LinearError - If there are only 3 coordinates and they are colinear. If there are 4 or more colinear coordinates, one of the infinite number of possible vectors will be returned.
• ValueError - If there are fewer than 3 sets of coordinates
• numpy.linalg.LinAlgError - If the SVD does not converge (note - I was unable to find a case where this happened)