Source code for schrodinger.analysis.visanalysis.volumedatastructureutils

# ----------------------------------------------------------------------------
# Name:
#
#   VOLUMEDATASTRUCTUREUTILS.py
#
# Purpose:
#
#   The VolumeDataStructureUtils module contains a number of helper functions
#   that facilitate setting up and calculating VolumeData instances that have
#   connected molecular-structure information.  In all cases the
#   molecular-structure information is presented in the form of a
#   schrodinger.structure.Structure instance.
#
# Copyright of:
#
#   Copyright Schrodinger, LLC. All rights reserved.
#
# Version:
#
#   Version         Author          Notes
#       1.0            DDR          Original Implementation
#
# Notes:
#
# ----------------------------------------------------------------------------

# ----------------------------------------------------------------------------
# Module imports.

import numpy as np

from . import volumedata as volumedata
from . import volumedatautils as vdutils

# End of module imports.
# ----------------------------------------------------------------------------

# ----------------------------------------------------------------------------
# Global constants.

_DOWN_COLUMNS = 0
_ACROSS_ROWS = 1

# End of global constants.
# ----------------------------------------------------------------------------


# ----------------------------------------------------------------------------
# Function definition:
#
#   BoundingInformation
#
# ----------------------------------------------------------------------------
def BoundingInformation(st, resolution=None, extend=(0.0, 0.0, 0.0)):
    """
    This function calculates values for N, resolution and origin for a
    VolumeData instance that would enclose the specified structure. The
    function accepts an optional extend value, which enlarges the overall
    VolumeData by the specified amount in each direction.

    :param st: The structure to be processed by the function.
    :type st: `schrodinger.structure.Structure`
    :param resolution: The resolution to use, specified in world-coordinates.
    :type resolution: `iterable< float, 3 >`
    :param extend: How much to extend the VolumeData around the molecule.
        The default value will ensure that the minimum X, Y, Z coordinate just fit
        within the VolumeData i.e. no account will be made for atomic volume.
    :type extend: `iterable< float, 3 >`

    :return: These are the values of N, resolution and origin required by a new
        VolumeData instance.
    :rtype: C{tuple< iterable< int, 3 >, iterable< float, 3 >,
        iterable< float, 3 > >
    """

    atomCoordinates = st.getXYZ()
    minAtomCoordinates = atomCoordinates - extend
    maxAtomCoordinates = atomCoordinates + extend
    resolutions = [resolution for ac in atomCoordinates]
    N, resolution, origin = vdutils.CalculateContainingVolume(
        minAtomCoordinates,
        maxAtomCoordinates,
        resolutions,
        resolutionMode="fixed",
        resolutionValue=resolution)
    return N, resolution, origin


# End of function: BoundingInformation.
# ----------------------------------------------------------------------------


# ----------------------------------------------------------------------------
# Function definition:
#
#   BoundingInformationL
#
# ----------------------------------------------------------------------------
def BoundingInformationL(sts, resolution=None, extend=(0.0, 0.0, 0.0)):
    """
    This function calculates values for N, resolution and origin for a
    VolumeData instance that would enclose the specified set of structures.
    The function accepts an optional extend value, which enlarges the overall
    VolumeData by the specified amount in each direction.

    :param sts: The set of structures to be processed. (This could be a
        StructureReader instance).
    :type sts: `iterable< schrodinger.structure.Structure >`
    :param resolution: The resolution to use, specified in world-coordinates.
    :type resolution: `iterable< float, 3 >`
    :param extend: How much to extend the VolumeData around the molecule.
        The default value will ensure that the minimum X, Y, Z coordinate just fit
        within the VolumeData i.e. no account will be made for atomic volume.
    :type extend: `iterable< float, 3 >`

    :return: These are the values of N, resolution and origin required by a new
        VolumeData instance.
    :rtype: C{tuple< iterable< int, 3 >, iterable< float, 3 >,
        iterable< float, 3 > >
    """

    atomCoordinates = list()
    for st in sts:
        atomCoordinates.extend(st.getXYZ())
    atomCoordinates = np.array(atomCoordinates)
    minAtomCoordinates = atomCoordinates - extend
    maxAtomCoordinates = atomCoordinates + extend
    resolutions = [resolution for ac in atomCoordinates]
    N, resolution, origin = vdutils.CalculateContainingVolume(
        minAtomCoordinates,
        maxAtomCoordinates,
        resolutions,
        resolutionMode="fixed",
        resolutionValue=resolution)
    return N, resolution, origin


# End of function: BoundingInformationL.
# ----------------------------------------------------------------------------


# ----------------------------------------------------------------------------
# Function definition:
#
#   VDWMask
#
# ----------------------------------------------------------------------------
def VDWMask(atoms, N=None, resolution=None, origin=None, vdwScale=1.0):
    """
    This function creates a new VolumeData instance that stores a vdW-mask for
    the specified molecule. A vdW-mask stores 1.0 for data-point within the
    vdW-surface of the molecule and 0.0 elsewhere.

    :param atoms: Atoms to be considered.
    :type atoms: iterable over `schrodinger.structure.StructureAtom`
    :param N: The parameters to use when sizing the output VolumeData
    :type N: `iterable< int, 3 >`
    :param resolution: The parameters to use when sizing the output VolumeData
    :type resolution: `iterable< float, 3 >`
    :param origin: The parameters to use when sizing the output VolumeData
    :type origin: `iterable< float, 3 >`
    :param vdwScale: A scaling factor for the atomic vdW-radii
    :type vdwScale: `float`

    :return: The calculated vdW-mask
    :rtype: ``VolumeData``
    """

    # ------------------------------------------------------------------------
    # Create the return VolumeData instance and an associated DataPointLocator
    ret = volumedata.VolumeData(N=N, resolution=resolution, origin=origin)
    dpl = vdutils.DataPointLocator(ret)

    # ------------------------------------------------------------------------
    # Loop across all of the atoms in the molecule. Locate data-points within
    # the scaled vdW-radius of each atom.
    for at in atoms:
        radius = at.vdw_radius * vdwScale
        dpl.SearchForDataPointsWithin((at.x, at.y, at.z), radius)

    # ------------------------------------------------------------------------
    # Get all of the array coordinates that should be set to 1.0 and do the
    # assignment.
    dpl.UniquifyResults()
    for x, y, z in dpl.Results:
        ret.getData()[x][y][z] = 1.0

    return ret


# End of function: VDWMask.
# ----------------------------------------------------------------------------

# End of file: volumedatastructureutils.py
# ----------------------------------------------------------------------------