schrodinger.application.matsci.freevolume module¶

Analyzes free volume in a structure

class schrodinger.application.matsci.freevolume.GridRadius(grid, radius)¶

Bases: tuple

__contains__(key, /)¶: Return key in self.

__len__()¶: Return len(self).

count(value, /)¶: Return number of occurrences of value.

grid¶: Alias for field number 0

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

radius¶: Alias for field number 1

exception schrodinger.application.matsci.freevolume.FatalCoordinateError¶

Bases: Exception

Raised if something is wrong with matching the current coordinates to the ones used to compute free volume. Typically and atom number or element mismatch

__init__(*args, **kwargs)¶

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

schrodinger.application.matsci.freevolume.archive_folder(filename, archive_folder)¶

Archive and delete the passed folder

Parameters

filename (str) – Filename of the archived file
archive_folder (str) – The folder to archive

schrodinger.application.matsci.freevolume.unarchive_surf_data(struct)¶

Unarchive the free volume surface folders related to the passed structure

Parameters: struct (schrodinger.structure.Structure) – The structure for which freevolume was calculated

schrodinger.application.matsci.freevolume.get_free_volume_structure(struct)¶

Get the structure that the free volume calculation was run on

Parameters: struct (schrodinger.structure.Structure) – The structure that contains the properties that point to the free volume structure
Return type: schrodinger.structure.Structure or None
Returns: The structure from the free volume calculation or None if it couldn’t be found (due to missing property or file)

schrodinger.application.matsci.freevolume.check_coordinates_changed(struct)¶

Check that the given structure matches the structure the free volume calculation was run on. In addition to basic number/type of atoms, the coordinates must also be the same since the void data has XYZ information incorporated in it.

Parameters: struct (schrodinger.structure.Structure) – The structure that contains the properties that point to the free volume structure
Return type: schrodinger.structure.Structure, False, or None
Returns: False if the structures match (number of atoms, elements and XYZ), Structure if the coordinates do not match - in this case the returned structure is a structure with the original free volume coordinates suitable for passing to fix_free_volume_coordinates, None if the free volume structure couldn’t be found (due to missing property or file)
Raises: FatalCoordinateError – If something unfixable does not match between the two structures, such as number of atoms or elements

schrodinger.application.matsci.freevolume.fix_free_volume_coordinates(struct, fv_struct=None)¶

Change the coordinates of struct to be those from the free volume calculation. Note that this assumes check_coordinates_changed has been called first (and the results dealt with).

The structure is modified in-place

Parameters

struct (structure.Structure) – The structure to modify
struct – The structure with the coordinates to transfer to struct. If not given, the structure obtained by get_free_volume_structure will be used.

schrodinger.application.matsci.freevolume.get_xlink_type_atoms(struct)¶

Get atom indexes for atoms that are either crosslinkable, crosslinked or both.

Parameters: struct (schrodinger.structure.Structure) – The structure to look for atoms in.
Return type: set, set, set
Returns: In order, indexes for atoms that are both crosslinked AND crosslinkable, atoms that are crosslinkable, atoms that are crosslinked. The sets are mutually exclusive.

schrodinger.application.matsci.freevolume.get_atom_layers(atom, origin, num_layers, layer_width, axis)¶

Get the range of layers that the given atom would intersect.

Parameters

atom (schrodinger.structure._StructureAtom) – The atom to find the layers for
origin (float) – The offset to add to each layer because the system starts at a point other than zero. The offset is along the axis defined by the axis parameter.
num_layers (int) – The number of layers
layer_width (float) – The width of each layer
axis (int) – 0, 1 or 2 to indicate the layers are cross sections of the X, Y or Z axis

Return type

list

Returns

Each item of the list is a layer the atom intersects based on its VdW radius

schrodinger.application.matsci.freevolume.extract_grid_and_radius(word)¶

Given a string, extract the floating point grid spacing and probe radius values

Parameters: word (str) – The string to extract the grid & radius from
Return type: GridRadius
Returns: The GridRadius namedtuple with the extracted values

schrodinger.application.matsci.freevolume.get_grid_radius_property_values(struct, propbase)¶

Get all the grid and radius values for properties on the structure that begin with the given base string.

Parameters

struct (schrodinger.structure.Structure) – The structure to extract the properties from
propbase (str) – The starting string for properties to search for

Return type

dict

Returns

Keys are GridRadius instances, values are the property value for that set of grid/radius values.

schrodinger.application.matsci.freevolume.get_file_data(struct, propbase, file_reader, override_path=None)¶

Use file_reader to extract the data from the files specified by the given structure properties

Parameters

struct (schrodinger.structure.Structure) – The structure to get data for
propbase (str) – The starting string for properties to search for
file_reader (callable) – The function that will read the data from the file
override_path (str or None) – If given, look for files in this directory rather than the one specified in the structure property

Return type

(OrderedDict, list)

Returns

Keys of the dict are GridRadius objects, values are the data extracted from the file for that set of Grid and Radius values. keys are orderd by (radius, grid) sort order. Each item of the list is a str that gives the path of a file that could not be located.

schrodinger.application.matsci.freevolume.read_volume_file(path)¶

Read the void volume data file located at path

Parameters: path (str) – The path to the file
Return type: list
Returns: The volumes from the file, each item is a float

schrodinger.application.matsci.freevolume.read_trj_volume_file(path)¶

Read the trajectory void volume data file located at path

Parameters: path (str) – The path to the file
Return type: dict
Returns: The volumes from the file where the key is the frame id and values are list of volume in that frame

schrodinger.application.matsci.freevolume.read_void_file(path)¶

Read the void data file located at path

Parameters: path (str) – The path to the file
Return type: dict
Returns: Keys are INFO and VOIDS. INFO value is a VoidInfo object, VOIDS value is a list of Void objects sorted from largest to smallest.

schrodinger.application.matsci.freevolume.read_trj_void_file(path)¶

Read the all frames void data files located inside the path

Parameters: path (str) – The path to the void files folder
Return type: dict
Returns: Dictionary where the key is the frame id and value is the void data for the frame. Void data is a dictionary where keys are INFO and VOIDS. INFO value is a VoidInfo object, VOIDS value is a list of Void objects sorted from largest to smallest.

schrodinger.application.matsci.freevolume.get_volume_data(struct, path=None, read_trj=False)¶

Get all the volume data available for the given structure

Parameters

struct (schrodigner.structure.Structure) – The structure to get volume data for
path (str or None) – If given, look for files in this directory rather than the one specified in the structure property
read_trj (bool) – Read trajectory analysis volume data if True, else will read the static structure analysis data.

Return type

(See read_volume_file or read_trj_volume_file function, list)

Returns

The volume data collected from struct, and a list of paths to files that could not be read

schrodinger.application.matsci.freevolume.get_voids_data(struct, path=None, read_trj=False)¶

Get all the void data available for the given structure

Parameters

struct (schrodigner.structure.Structure) – The structure to get volume data for
path (str or None) – If given, look for files in this directory rather than the one specified in the structure property
read_trj (bool) – Read trajectory analysis void data if True, else will read the static structure analysis data.

Return type

(See read_void_file or read_trj_void_file function, list)

Returns

The volume data collected from struct, and a list of paths to the files that could not be read.

schrodinger.application.matsci.freevolume.create_surface_from_void(void, void_info)¶

Create void surface

Parameters

void (Void) – The void to make a surface for
void_info (VoidInfo) – The VoidInfo object for this void

Return type

surface.Surface

Returns

surface created using the void and void info

class schrodinger.application.matsci.freevolume.JsonObject¶

Bases: object

Base class for custom objects that can be serialized and deserialized by json

jsonData()¶

Return a json-serializable object for this instance

Return type: dict
Returns: A json-serializable object for this instance

classmethod fromJsonData(data)¶

Create a new VoidInfo object from json data

Parameters: data (dict) – A dict such as returned by the jsonData method
Return type: class
Returns: A new class object created using the data in dict

class schrodinger.application.matsci.freevolume.VoidInfo(origin, numxyz, spacing, periodic, probe)¶

Bases: schrodinger.application.matsci.freevolume.JsonObject

Holds general information about the void calculation

__init__(origin, numxyz, spacing, periodic, probe)¶

Create a VoidInfo object

Parameters

origin (iterable) – The x, y, z coordinates of the grid origin
numxyz (iterable) – The number of gridpoints in the x, y and z direction
spacing (iterable) – The spacing of gridpoints in the x, y and z direction
periodic (bool) – Whether the grid is periodic
probe (float) – The probe radius used in the void calculation

getNodeXYZ(node)¶

Get the xyz coordinates a node represents

Parameters: node (tuple) – A graph node (a, b, c) for coordinate a, b, c in the grid
Return type: list
Returns: [x, y, z] coordinates of the node

classmethod fromJsonData(data)¶

Create a new VoidInfo object from json data

Parameters: data (dict) – A dict such as returned by the jsonData method
Return type: class
Returns: A new class object created using the data in dict

jsonData()¶

Return a json-serializable object for this instance

Return type: dict
Returns: A json-serializable object for this instance

class schrodinger.application.matsci.freevolume.Void(size=0, volume=0, nodes=None, surf_name=None, surf_comment=None, surf_file=None)¶

Bases: schrodinger.application.matsci.freevolume.JsonObject

Holds information about a single Void

__init__(size=0, volume=0, nodes=None, surf_name=None, surf_comment=None, surf_file=None)¶

Create a Void instance

Parameters

size (int) – The number of nodes in the void
volume (float) – The volume the void represents
nodes (iterable) – The collection of grid nodes that make up the void
surf_name (str) – Name of the surface of the void
surf_comment (str) – Comment for the surface of the void
surf_file (str) – Name of the surface file associated with the current void

getSurfaceNodes(vinfo)¶

Find all the surface nodes in the void

Parameters: vinfo (VoidInfo) – The VoidInfo object used to compute the void

classmethod fromJsonData(data)¶

Create a new VoidInfo object from json data

Parameters: data (dict) – A dict such as returned by the jsonData method
Return type: class
Returns: A new class object created using the data in dict

jsonData()¶

Return a json-serializable object for this instance

Return type: dict
Returns: A json-serializable object for this instance

exception schrodinger.application.matsci.freevolume.FreeVolumeException¶

Bases: Exception

Raised if something goes wrong with computing the Free Volume

__init__(*args, **kwargs)¶

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class schrodinger.application.matsci.freevolume.FreeVolumeDriver(grid=0.25, probe=1.4, generic_title='free_volume', logger=None, verbose=True, only_large_void_surf=True)¶

Bases: object

Driver to compute Free Volume

__init__(grid=0.25, probe=1.4, generic_title='free_volume', logger=None, verbose=True, only_large_void_surf=True)¶

Create a FreeVolumeDriver instance

Parameters

grid (float) – The requested grid spacing
probe (float) – The probe radius
generic_title (str) – The title to use if a structure does not have one
logger (None or logging.logger) – If None, no logging will be done and FreeVolumeException will be raised if an error occurs. If a logger, logging will be done and the system will exit on an error.
verbose (bool) – Turns on additional logging
only_large_void_surf (bool) – Will calculate surface of all voids if True. If case of False it will calculate surface of voids with volume greater than 1 A^3.

property is_cms¶

Return type: bool
Returns: whether the last structure loaded into the driver was a Cms object

log(msg, is_verbose=False, **kwargs)¶

Log a message if logging is being used

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to textlogger.log_msg

logError(msg, **kwargs)¶

Log an error message if logging is being used and exit, otherwise raise an Exception.

Parameters: msg (str) – The message to log

Additional keyword arguments are passed to textlogger.log_error

Raises

FreeVolumeException – if self.logger
SystemExit – if not self.logger

findFreeVolume(struct)¶

Find the free volume in the structure. Results are stored as properties on the structure

Parameters

struct (schrodinger.structure.Structure or cms.Cms) – The structure/system to find the free volume in

Raises

FreeVolumeException – if the PBC dimensions are too small or memory usage grows too large and no logger exists
SystemExit – if the PBC dimensions are too small or memory usage grows too large and a logger exists

getVoidVolumes()¶

Get the volume of each void

Return type: list
Returns: A list of void volumes. Each item is a float.

getPropName(propbase)¶

Get the property name with grbit for the class added as a suffix to the passed property base name.

Parameters: propbase (str) – the property basename (prefix) to add the grbit to
Return type: str
Returns: property name with grbit added to it

getFreeVolumeData()¶

Calculate the absolute free volume and free volume percentage from the analyzed graph

Return type: (float, float)
Returns: Tuple with two values. First is the absolute free volume and second is the free volume percentage.

defineVoids()¶: Define all the voids found in the structure

volumeOfGraph()¶

Get the current total volume of the graph

Return type: float
Returns: The volume of all the remaining nodes in the graph

getVoidData(voids_filename, archive_data=True)¶

Get the void data from the current analysis

Parameters

voids_filename (str) – name of the voids json file
archive_data (bool) – whether to archive void data. Archiving helps transferring of files easier.

Return type

dict

Returns

Keys are INFO and VOIDS. INFO value is a VoidInfo object, VOIDS value is a list of Void objects sorted from largest to smallest.

createSurfaces(voids, void_info, surf_folder)¶

Create a surfaces for voids larger than 1 A^3 and store them inside surf folder. Also set the name, comment, and location of the created surface file for the void as an attribute in the void.

Parameters

void (Void) – The void to make a surface for
void_info (VoidInfo) – The VoidInfo object for this void
surf_folder (str) – Folder to store all the surface files inside

writeFiles(basename=None)¶

Write all the data to files

The actual node graph is written to a pkl file

The void data is written to a json file

The volumes are written to a simple text file, one volume per line

The structure is written to a Maestro file

Parameters: basename (str) – Use this instead of the structure title as the base file name
Return type: str, str, str
Returns: The paths to the files written (volume file, void file, graph file)

getBasename()¶

Get the basename from the structure

Return type: str
Returns: basename from structure title or the generic name cleaned and uniquified.

clearGraph()¶: Clear out the graph for this driver to preserve memory space