schrodinger.application.matsci.nano.xtal module¶

Classes and functions for creating crystals by unit cell.

class schrodinger.application.matsci.nano.xtal.AXIS(X, Y, Z)¶

Bases: tuple

X¶: Alias for field number 0

Y¶: Alias for field number 1

Z¶: Alias for field number 2

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

__len__()¶: Return len(self).

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

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

Return first index of value.

Raises ValueError if the value is not present.

schrodinger.application.matsci.nano.xtal.find_furthest_atom_along_vector(struct, vector)¶

Find the atom in struct that is furthest in the direction of vector. For instance, if vector is the Z-axis, this will find the atom with the largest z coordinate

Parameters

struct (schrodinger.structure.Structure) – The structure to check
vector (numpy.array) – The vector that gives the direction to search

Return type

schrodinger.structure._StructureAtom

Returns

The atom furthest in the vector direction

schrodinger.application.matsci.nano.xtal.find_origin_on_structure_exterior(struct, vector)¶: Find the point to originate the normal plane to the passed vector so that the passed structure is entirely behind the vector (i.e. the structure will be entirely on one side of the plane, and vector on the other side).

schrodinger.application.matsci.nano.xtal.is_infinite(astructure)¶

Return a boolean indicating whether the given structure is infinitely bonded, meaning that it has bonds that cross the periodic boundary which can not be eliminated by means of molecule contraction. If any molecule in the given structure is infinitely bonded then the structure itself is considered infinite. As examples of infinite systems consider graphene, gold, infinite polymer, etc.

Parameters: astructure (schrodinger.structure.Structure) – the structure whose infiniteness is in question, can be a unit cell or an ASU
Raises: ValueError – if there is an issue with the input
Return type: bool
Returns: True if infinite, False otherwise

schrodinger.application.matsci.nano.xtal.get_check_also_reg_bond(struct, pbc=None, is_cg=None)¶

Get the value of the check_also_reg_bond that is passed to is_pbc_bond based on the PBC cell lengths.

Parameters

astructure (schrodinger.structure.Structure) – Structure for which to check the value of check_also_reg_bond flag
pbc (schrodinger.infra.structure.PBC or None) – The infrastructure PBC created from the Chorus box properties
is_cg (bool or None) – True, if structure is CG, otherwise False. If None, this will be evaluated

Return type

bool

Returns

Flag value

schrodinger.application.matsci.nano.xtal.is_infinite2(astructure, check_also_reg_bond=None, is_cg=None, atom_indices=None)¶

Return a boolean indicating whether the given structure is infinitely bonded, meaning that it has bonds that cross the periodic boundary which can not be eliminated by means of molecule contraction. If any molecule in the given structure is infinitely bonded then the structure itself is considered infinite. As examples of infinite systems consider graphene, gold, infinite polymer, etc. Note that, correct bond information is expected in the input structure.

Parameters

astructure (schrodinger.structure.Structure) – the structure whose infiniteness is in question, can be a unit cell or an ASU
check_also_reg_bond (bool or None) – Deprecated. Check if the PBC bond is also a regular bond, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell. If None, bool value will be decided automatically (preferred)
is_cg (bool) – Deprecated. True, if structure is CG, otherwise False. Needed if check_also_reg_bond is None. If None, this will be evaluated

Paran atom_indices

Atom indices to check from the structure. If None, entire stucture is checked

Return type

bool

Returns

True if infinite, False otherwise

schrodinger.application.matsci.nano.xtal.check_bond_vec_proj(xyz1, xyz2, unit_lattice_vectors, threshold)¶: Check if any of the bond vector projections on the lattice vectors is close to the half length of a lattice vector.

schrodinger.application.matsci.nano.xtal.has_pbc_bond(struct, pbc=None)¶

Check if structure has a PBC bond.

Parameters

struct (structure.Structure) – the structure to check
pbc (schrodinger.infra.structure.PBC) – PBC of the structure

Return type

bool

Returns

Whether the structure has a PBC bond

schrodinger.application.matsci.nano.xtal.store_chorus_box_props(struct, ax, ay=0.0, az=0.0, bx=0.0, by=None, bz=0.0, cx=0.0, cy=0.0, cz=None)¶

Add properties to the structure that define the periodic boundary condition in the way Desmond wants it defined.

Parameters

struct (schrodinger.structure.Structure) – The structure to add the properties to
ax (float) – The value of the ax box property
ay (float) – The value of the ay box property. Defaults to 0.
az (float) – The value of the az box property. Defaults to 0.
bx (float) – The value of the bx box property. Defaults to 0.
by (float) – The value of the by box property. If not given, this value is set the same as ax.
bz (float) – The value of the bz box property. Defaults to 0.
cx (float) – The value of the cx box property. Defaults to 0.
cy (float) – The value of the cy box property. Defaults to 0.
cz (float) – The value of the cz box property. If not given, this value is set the same as ax.

schrodinger.application.matsci.nano.xtal.copy_chorus_box_props(struct1, struct2)¶

Copy the Chorus box PBC properties from one struct to another if they exist. If no Chorus properties exist, no error is raised.

Parameters

struct1 (structure.Structure) – The structure to copy props from
struct2 (structure.Structure) – The structure to copy props to

schrodinger.application.matsci.nano.xtal.clear_asu_and_fractional_properties(struct)¶

Clear the atomic ASU and Fractional coordinate properties

Parameters: struct (schrodinger.structure.Structure) – The structure to clear the ASU and fractional properties from

schrodinger.application.matsci.nano.xtal.get_cov_radii()¶

Return a dictionary of atomic covalent radii.

Return type: dict
Returns: dictionary where keys are atomic numbers and values are atomic covalent radii in Angstrom

schrodinger.application.matsci.nano.xtal.get_cov_radius(st, idx, is_cg=None)¶

Return the covalent radius in Angstrom of the given atom or coarse grain particle index.

Parameters

st (schrodinger.structure.Structure) – the structure
idx (int) – the atom or coarse grain particle index
is_cg (bool or None) – True, if structure is CG, otherwise False. If None, structure will be evaluated (slow)

Return type

float

Returns

the covalent radius in Angstrom

schrodinger.application.matsci.nano.xtal.get_max_cov_radius(st, is_cg=None)¶

For atomic input return the maximum covalent radius in Angstrom over all atoms in the periodic table, for CG input return the same but over all particles in the given structure.

Parameters

st (schrodinger.structure.Structure) – the structure
is_cg (bool or None) – True, if structure is CG, otherwise False. If None, structure will be evaluated (slow)

Return type

float

Returns

the maximum covalent radius in Angstrom

schrodinger.application.matsci.nano.xtal.get_cov_parameter(st, atomistic_cov_param, is_cg=None)¶

Return the covalent parameter in Angstrom for the given structure.

Parameters

st (schrodinger.structure.Structure) – the structure
atomistic_cov_param (float) – the atomistic covalent parameter in Angstrom
is_cg (bool or None) – True, if structure is CG, otherwise False. If None, structure will be evaluated (slow)

Return type

float

Returns

the covalent parameter in Angstrom

schrodinger.application.matsci.nano.xtal.get_params_from_vectors(a_vec, b_vec, c_vec)¶

Return the lattice parameters from the given lattice vectors.

Parameters

a_vec (numpy.array) – the a lattice vector
b_vec (numpy.array) – the b lattice vector
c_vec (numpy.array) – the c lattice vector

Return type

list

Returns

contains the a, b, c, alpha, beta, and gamma parameters

schrodinger.application.matsci.nano.xtal.get_lattice_vectors(a_param, b_param, c_param, alpha_param, beta_param, gamma_param)¶

Get the lattice vectors of the specified parallelepiped.

Parameters

a_param (float) – the length of the parallelepiped along edge a
b_param (float) – the length of the parallelepiped along edge b
c_param (float) – the length of the parallelepiped along edge c
alpha_param (float) – the angle between edges b and c
beta_param (float) – the angle between edges a and c
gamma_param (float) – the angle between edges a and b

Return type

numpy.array, numpy.array, numpy.array

Returns

the lattice vectors of the parallelepiped

class schrodinger.application.matsci.nano.xtal.ParserWrapper(args, scriptname, description)¶

Bases: object

Manages the argparse module to parse user command line arguments.

SPACE_GROUP = None¶

A_PARAM = None¶

B_PARAM = None¶

C_PARAM = None¶

ALPHA_PARAM = None¶

BETA_PARAM = None¶

GAMMA_PARAM = None¶

MIN_ANGLE = 0.0¶

MAX_ANGLE = 180.0¶

NCELLA = 1¶

NCELLB = 1¶

NCELLC = 1¶

ORIGIN = (0.0, 0.0, 0.0)¶

CHOICE_ON = 'on'¶

CHOICE_OFF = 'off'¶

BONDING_CHOICES = ['on', 'off']¶

BONDING_DEFAULT = 'off'¶

BOND_ORDERS_CHOICES = ['on', 'off']¶

BOND_ORDERS_DEFAULT = 'off'¶

TRANSLATE_CHOICES = ['on', 'off']¶

TRANSLATE_DEFAULT = 'off'¶

COV_MIN = 0.4¶

COV_OFFSET = 0.4¶

COV_FACTOR = 1.0¶

PRINT_INFO = False¶

PBC_BONDING = True¶

__init__(args, scriptname, description)¶

Create a ParserWrapper object and process it.

Parameters

args (tuple) – command line arguments
scriptname (str) – name of this script
description (str) – description of this script

loadIt()¶: Load ParserWrapper with options.

parseArgs(args)¶

Parse the command line arguments.

Parameters: args (tuple) – command line arguments

validate()¶: Validate parser options.

class schrodinger.application.matsci.nano.xtal.CheckInput¶

Bases: object

Check user input.

TITLE_KEY = 's_m_title'¶

ENTRY_NAME_KEY = 's_m_entry_name'¶

checkInputFile(input_file)¶

Check input file.

Parameters: input_file (str) – the name of the input file

checkASU(asu, logger=None)¶

Check the asymmetric unit structure object.

Parameters

asu (schrodinger.Structure.structure) – the structure object of the asymmetric unit
logger (logging.getLogger) – output logger

checkFractionalRedundancies(asu, logger=None)¶

Check the redundancy of fractional coordinate definitions.

Raises

ValueError – If redundancy is found

Parameters

asu (schrodinger.Structure.structure) – the structure object of the asymmetric unit
logger (logging.getLogger) – output logger

checkSpaceGroup(space_group, space_groups, logger=None)¶

Check the specified space group.

Parameters

space_group (str) – the specified space group
space_groups (space_groups.SpaceGroups) – SpaceGroups object
logger (logging.getLogger) – output logger

Raises

ValueError – If no space group is specified, or if the provided space group symbol is not valid

Return type

space_goups.SpaceGroup

Returns

Space group object

checkLatticeAngleValues(alpha, beta, gamma, logger=None)¶

Check the values of the specified lattice angles.

Parameters

alpha (float) – lattice angle alpha in degrees
beta (float) – lattice angle beta in degrees
gamma (float) – lattice angle gamma in degrees
logger (logging.getLogger) – output logger

Return type

float, float, float

Returns

alpha_new, beta_new, gamma_new, updated lattice angles

checkLatticeParameters(a_param, b_param, c_param, alpha_param, beta_param, gamma_param, logger=None)¶

Check the specified lattice parameters.

Parameters

a_param (float) – lattice vector a in Angstrom
b_param (float) – lattice vector b in Angstrom
c_param (float) – lattice vector c in Angstrom
alpha_param (float) – lattice angle alpha in degrees
beta_param (float) – lattice angle beta in degrees
gamma_param (float) – lattice angle gamma in degrees
logger (logging.getLogger) – output logger

Return type

six floats

Returns

a_param, b_param, c_param, alpha_param, beta_param, gamma_param

checkLatticeMaxVolume(a_param, b_param, c_param, logger=None)¶

Using the lattice lengths check the maximum volume.

Parameters

a_param (float) – lattice vector a in Angstrom
b_param (float) – lattice vector b in Angstrom
c_param (float) – lattice vector c in Angstrom
logger (logging.getLogger) – output logger

Raises

ValueError – If the lattice vector lengths result in a unit cell that has too small of a volume

checkNumUnitCellParams(ncella, ncellb, ncellc, logger=None)¶

Check the number of unit cells requested by the user.

Parameters

ncella (int) – number of unit cells along lattice vector a
ncellb (int) – number of unit cells along lattice vector b
ncellc (int) – number of unit cells along lattice vector c
logger (logging.getLogger) – output logger

Raises

ValueError – At least one of the ncell* parameters is not a positive integer

checkOrigin(origin)¶

Check the origin.

Parameters: origin (list or None) – the unit cell origin, list of three floats, in fractional coordinates or None if not provided
Raises: ValueError – The specified origin is invalid
Return type: list
Returns: the unit cell origin, list of three floats, in fractional coordintes

checkBondingAndTranslate(bonding, bond_orders, translate, logger=None)¶

Check the bonding and translate options.

Parameters

bonding (str) – specify how the bonding should be handled
bond_orders (str) – specify how the bond orders should be handled
translate (str) – specify how the translation to the first unit cell should be handled
logger (logging.getLogger) – output logger

Raises

ValueError – The bonding or translation options are invalid

schrodinger.application.matsci.nano.xtal.get_duplicate_atoms(struct, pbc=None, atoms_to_check=None, duplicate_thresh=0.25)¶

Get atoms to keep and atoms to delete from a structure that possibly contains duplicate atoms that are within the defined threshold. Of the redundant atoms that with the lowest index is kept.

Parameters

struct (schrodinger.Structure.structure) – the structure object to find duplicate atoms
pbc (schrodinger.infra.structure.PBC or None) – The infrastructure PBC created from the Chorus box properties, if None, system will be treated as finite
atoms_to_check (set) – indices of atoms that are to be checked for duplicate copies
duplicate_thresh (float) – distance used to define duplicate atoms, conservatively chosen based on considering the resolutions of some crystal structures and the wavelengths of light used to obtain the diffraction patterns

Return type

list, list

Returns

First list of atom indices to keep. Second is list of lists of atom indices to be removed. Each item in the list is a list of duplicated atom indices corresponding to the atom index from to_keep list

schrodinger.application.matsci.nano.xtal.delete_duplicate_atoms(astructure, atoms_to_check=None, duplicate_thresh=0.25, fract_offset=0.0001, preserve_bonding=False)¶

Delete duplicate atoms that are within the defined threshold. Of the redundant atoms that with the lowest index is kept. If transform is not None then this function will use the periodic boundary conditions defined in transform when determining redundant atoms.

Parameters

astructure (schrodinger.Structure.structure) – the structure object from which the duplicate atoms will be deleted
atoms_to_check (set) – indices of atoms that are to be checked for duplicate copies, for a given redundant set of atoms any index can be passed in
duplicate_thresh (float) – distance used to define duplicate atoms, conservatively chosen based on considering the resolutions of some crystal structures and the wavelengths of light used to obtain the diffraction patterns
fract_offset (float) – the threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary
preserve_bonding (bool) – If True, preserve bonding between atoms (might be slow)

Return type

dict

Returns

renumber_map, keys are original indices, values are new indices or None if the atom was deleted

schrodinger.application.matsci.nano.xtal.max_connect_distance(cov_rad_a, cov_rad_b, cov_factor=1.0, cov_offset=0.4)¶

Return the maximum bonding distance for the given covalent radii and distance equation parameters.

Parameters

cov_rad_a (float) – covalent radii for atom a
cov_rad_b (float) – covalent radii for atom b
cov_factor (float) – the maximum distance for a connection is the sum of the covalent radii of the two atoms weighted by this factor plus the cov_offset in angstrom, increasing this value will increase the number of connections, this value is unit-less
cov_offset (float) – the maximum distance for a connection is the sum of the covalent radii of the two atoms weighted by cov_factor plus this offset in angstrom, increasing this value will increase the number of connections

Return type

float

Returns

the maximum bonding distance

schrodinger.application.matsci.nano.xtal.connect_atoms(astructure, atoms_to_connect=None, cov_min=0.4, cov_offset=0.4, cov_factor=1.0, delete_existing=True, cov_radii_props=False, pbc_bonding=True, only_pbc_bonds=False, check_also_reg_bond=None, max_valencies=None)¶

Connect the atoms in a structure.

Parameters

astructure (schrodinger.Structure.structure) – the structure object for which the connections are wanted
atoms_to_connect (list) – atom indices to consider connecting, if None then all atoms will be considered
cov_min (float) – the minimum distance for a connection in angstrom
cov_offset (float) – the maximum distance for a connection is the sum of the covalent radii of the two atoms weighted by cov_factor plus this offset in angstrom, increasing this value will increase the number of connections
cov_factor (float) – the maximum distance for a connection is the sum of the covalent radii of the two atoms weighted by this factor plus the cov_offset in angstrom, increasing this value will increase the number of connections, this value is unit-less
delete_existing (bool) – indicates whether existing connections should first be deleted, i.e. any bonds to atoms in atoms_to_connect will be deleted
cov_radii_props (bool) – set the atomic covalent radii used in the connectivity protocol as atom properties. Enabling this, causes a decrease in performance of approx. 10%.
pbc_bonding (bool) – if True and if the input structure has the chorus properties defined, then PBC bonds will be created
only_pbc_bonds (bool) – if True then only PBC bonds will be created, i.e. regular bonds will not be created
check_also_reg_bond (bool or None) – if True then PBC bonds will be checked to see if they are also regular bonds, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell. If None, this will be evaluated
max_valencies (dict or None) – The maximum valencies to use for each element. If None, the valencies defined in get_max_valencies() will be used.

Return type

list, dict, dict

Returns

maximally_bonded_atoms, contains the indices of any maximally bonded atoms, and two dictionaries (one for regular bonds and one for PBC bonds) where keys are tuples of bonding atom indices and values are bond orders (for regular bonds) or tuples of bond orders and booleans indicating whether the PBC bond is also a regular bond (for PBC bonds)

schrodinger.application.matsci.nano.xtal.translate_to_cell(astructure, fract_offset=0.0001, origin=(0.0, 0.0, 0.0), extents=None)¶

Translate the fractional coordinate definitions of the atoms of the given structure so that they are all in the cell defined with the given origin and given extents and optionally also actually transform the Cartesian coordinates of the atoms using the specified fractional-to-Cartesian transform.

Parameters

astructure (schrodinger.Structure.structure) – the structure object whose atoms will be translated
fract_offset (float) – the threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary
origin (list) – the origin of the cell to which to translate in fractional coordinates
extents (list) – the number of cells along each lattice vector

schrodinger.application.matsci.nano.xtal.get_gcd_list_ints(list_of_ints)¶

Return the greatest common divisor (GCD) of a list of integers.

Parameters: list_of_ints (list) – the list of ints for which the GCD is desired
Return type: int
Returns: gcd, the GCD

schrodinger.application.matsci.nano.xtal.get_carts_from_anchor_string(anchor)¶

Return the Cartesian coordinates from the given ‘s_mae_pbc_position’ anchor string, i.e. ‘anchor_x_y_z’.

Parameters: anchor (str) – the anchor string
Raises: ValueError – if the given string is not an anchor string
Return type: list
Returns: the Cartesians floats

class schrodinger.application.matsci.nano.xtal.Crystal(asymmetric_unit, space_group=None, a_param=None, b_param=None, c_param=None, alpha_param=None, beta_param=None, gamma_param=None, ncella=1, ncellb=1, ncellc=1, origin=None, bonding='off', bond_orders='off', translate='off', translate_centroids=False, cov_offset=0.4, fract_offset=0.0001, overlap_tresh=0.25, use_existing_pbc_bonds=False, logger=None, valency_exceptions=None)¶

Bases: object

Main class for generating crystals.

SPACE_GROUP_KEY = 's_pdb_PDB_CRYST1_Space_Group'¶

A_KEY = 'r_pdb_PDB_CRYST1_a'¶

B_KEY = 'r_pdb_PDB_CRYST1_b'¶

C_KEY = 'r_pdb_PDB_CRYST1_c'¶

ALPHA_KEY = 'r_pdb_PDB_CRYST1_alpha'¶

BETA_KEY = 'r_pdb_PDB_CRYST1_beta'¶

GAMMA_KEY = 'r_pdb_PDB_CRYST1_gamma'¶

SPACE_GROUP_ID_KEY = 'i_matsci_Space_Group_ID'¶

CHORUS_BOX_BASE_KEY = 'r_chorus_box_'¶

CHORUS_BOX_AX_KEY = 'r_chorus_box_ax'¶

CHORUS_BOX_AY_KEY = 'r_chorus_box_ay'¶

CHORUS_BOX_AZ_KEY = 'r_chorus_box_az'¶

CHORUS_BOX_BX_KEY = 'r_chorus_box_bx'¶

CHORUS_BOX_BY_KEY = 'r_chorus_box_by'¶

CHORUS_BOX_BZ_KEY = 'r_chorus_box_bz'¶

CHORUS_BOX_CX_KEY = 'r_chorus_box_cx'¶

CHORUS_BOX_CY_KEY = 'r_chorus_box_cy'¶

CHORUS_BOX_CZ_KEY = 'r_chorus_box_cz'¶

CHORUS_BOX_A_KEYS = ['r_chorus_box_ax', 'r_chorus_box_ay', 'r_chorus_box_az']¶

CHORUS_BOX_B_KEYS = ['r_chorus_box_bx', 'r_chorus_box_by', 'r_chorus_box_bz']¶

CHORUS_BOX_C_KEYS = ['r_chorus_box_cx', 'r_chorus_box_cy', 'r_chorus_box_cz']¶

CHORUS_BOX_KEYS = ['r_chorus_box_ax', 'r_chorus_box_ay', 'r_chorus_box_az', 'r_chorus_box_bx', 'r_chorus_box_by', 'r_chorus_box_bz', 'r_chorus_box_cx', 'r_chorus_box_cy', 'r_chorus_box_cz']¶

CHORUS_BOX_KEY_VECTORS = [['r_chorus_box_ax', 'r_chorus_box_ay', 'r_chorus_box_az'], ['r_chorus_box_bx', 'r_chorus_box_by', 'r_chorus_box_bz'], ['r_chorus_box_cx', 'r_chorus_box_cy', 'r_chorus_box_cz']]¶

NUM_DECIMAL_COORDS = 4¶

MSGWIDTH = 80¶

GENERAL_VEC_1 = array([1., 0., 0.])¶

GENERAL_VEC_2 = array([0., 1., 0.])¶

GENERAL_VEC_3 = array([0., 0., 1.])¶

SYMMETRY_LABEL_KEY = 'i_matsci_Symmetry_Label'¶

ASU_LABEL_KEY = 'b_matsci_ASU_Atom'¶

CM_TO_ANGSTROM = 100000000.0¶

UNIT_CELL_FORMULA_KEY = 's_m_Unit_Cell_Formula'¶

UNIT_CELL_VOLUME_KEY = 'r_m_Unit_Cell_Volume/Ang.^3'¶

UNIT_CELL_DENSITY_KEY = 'r_m_Unit_Cell_Density/g/cm^3'¶

__init__(asymmetric_unit, space_group=None, a_param=None, b_param=None, c_param=None, alpha_param=None, beta_param=None, gamma_param=None, ncella=1, ncellb=1, ncellc=1, origin=None, bonding='off', bond_orders='off', translate='off', translate_centroids=False, cov_offset=0.4, fract_offset=0.0001, overlap_tresh=0.25, use_existing_pbc_bonds=False, logger=None, valency_exceptions=None)¶

Create an instance.

Parameters

asymmetric_unit (schrodinger.Structure.structure) – the ASU
space_group (str) – the full or short Hermann-Mauguin symbol of the space group
a_param (float) – the lattice parameter a in Angstrom
b_param (float) – the lattice parameter b in Angstrom
c_param (float) – the lattice parameter c in Angstrom
alpha_param (float) – the lattice parameter alpha in degrees
beta_param (float) – the lattice parameter beta in degrees
gamma_param (float) – the lattice parameter gamma in degrees
ncella (int) – the number of unit cells to generate along lattice vector a
ncellb (int) – the number of unit cells to generate along lattice vector b
ncellc (int) – the number of unit cells to generate along lattice vector c
origin (list or None) – the origin of the unit cell, i.e. list of three floats, in fractional coordinates or None if one is not provided
bonding (str) – specifies how the bonding should be handled, takes a string in BONDING_CHOICES
bond_orders (str) – specifies how the bond orders should be handled, takes a string in BOND_ORDERS_CHOICES
translate (str) – specifies how the translation to the first unit cell should be handled, takes a string in TRANSLATE_CHOICES
translate_centroids (bool) – If True, after the cell is built, entire molecules are moved into the first cell. Cannot be used together with translate
cov_offset (float) – the maximum distance for drawn bonds is the sum of the covalent radii of the two atoms plus this offset in angstrom
fract_offset (float) – the threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary
overlap_tresh (float) – distance used to define overlapping atoms. If 0, no atoms will be deleted
use_existing_pbc_bonds (bool) – rather than recalculating PBC bonds use existing PBC bonds
logger (logging.getLogger) – output logger
valency_exceptions (dict) – The exceptions to update default valencies with.

handleSettings()¶: Handle the settings of this crystal build.

doBonding()¶

Determine if this script should handle the bonding both inside and between unit cells.

Return type: bool
Returns: True if this script should handle the bonding, False otherwise.

doBondOrders()¶

Determine if this script should handle the assignment of bond orders both inside and between unit cells.

Return type: bool
Returns: True if this script should handle the assignment, False otherwise.

doTranslation()¶

Determine if a translation to the first unit cell should be performed.

Return type: bool
Returns: True if this translation should be performed, False otherwise.

getLatticeParameters()¶: Get lattice parameters.

checkInputParams()¶: Check input parameters.

updateLatticeProperties()¶: Update the lattice properties for the asymmetric unit structure.

setCrystalSymmetry()¶: Set the crystal symmetry.

determineBasisVectors()¶: Determine the lattice vectors in the cartesian basis and the cartesian vectors in the lattice basis. Also determine the reciprocal lattice vectors.

buildCrystalUnitCell(mmcrystal_handle)¶

Build a crystal unit cell.

Parameters: mmcrystal_handle (handle) – the mmcrystal handle

labelSymEquivPos()¶: Label the symmetry equivalent positions.

labelAsuAtoms(astructure)¶

Label the atoms that make up an ASU, i.e. the symmetry unique atoms.

Parameters: astructure (schrodinger.Structure.structure) – the structure whose atoms will be labeled

doPropertyEvaluation()¶: Compute some properties of the unit cell. In order for the properties to be consistent with their standard definitions the provided unit cell must be void of the redundant edge, meaning that the fractionals must be defined on n < f < n + 1 rather than n < f <= n + 1, as well as any other redundancies.

setStructureProperties()¶: Set some structure properties.

setChorusProperties(astructure, ncella=1, ncellb=1, ncellc=1)¶

Set the chorus structure properties on the given structure.

Parameters

astructure (schrodinger.structure.Structure) – the structure that needs the chorus properties
ncella (int) – the number of cells along a
ncellb (int) – the number of cells along b
ncellc (int) – the number of cells along c

printCrystalParams()¶: Print some crystal parameters.

setAsuAtomsFalse(astructure)¶

Set the ASU atom labels to false for this structure.

Parameters: astructure (schrodinger.Structure.structure) – the structure object to be updated

buildCrystalSuperCell(ncella, ncellb, ncellc)¶

Build a crystal super cell.

Parameters

ncella (int) – the number of unit cells to generate along lattice vector a
ncellb (int) – the number of unit cells to generate along lattice vector b
ncellc (int) – the number of unit cells to generate along lattice vector c

setOrigin()¶: Set the origin.

orchestrate()¶: Orchestrate the construction of the crystal.

schrodinger.application.matsci.nano.xtal.get_reciprocal_lattice_vectors(a_vec, b_vec, c_vec)¶

Return the reciprocal lattice vectors.

Parameters

a_vec (numpy.array) – the a lattice vector
b_vec (numpy.array) – the b lattice vector
c_vec (numpy.array) – the c lattice vector

Return type

numpy.array

Returns

the three reciprocal lattice vectors

schrodinger.application.matsci.nano.xtal.get_collapsed_index(abc, alimit, blimit, climit)¶

Given a three dimensional grid of integers defined on [1, limit] for the given a, b, and c limits and a traversal path of c then b then a return the number of integers traversed in order to reach the given abc integer index triple.

Parameters

abc (tuple) – the integer indices
alimit (int) – the upper bound on a (unused)
blimit (int) – the upper bound on b
climit (int) – the upper bound on c

Return type

int

Returns

the number of integers traversed

schrodinger.application.matsci.nano.xtal.modified_sawtooth(n, x)¶

Given a positive integer variable x in [0, n+1] return a signal from a modified sawtooth function. This function is linear on [1, n] but is n for x = 0 and is 1 for x = n+1.

Parameters

n (int) – the period
x (int) – the variable

Return type

int

Returns

the signal

schrodinger.application.matsci.nano.xtal.assign_bond_orders(astructure, logger=None)¶

Return a copy of the input structure that has bond orders assigned.

Parameters

astructure (schrodinger.Structure.structure) – the structure object for which bond orders will be assigned
logger (logging.getLogger or None) – output logger or None if there isn’t one

Return type

schrodinger.Structure.structure

Returns

a copy of the input structure with the bond orders assigned

schrodinger.application.matsci.nano.xtal.fix_metal_bonding(astructure)¶

Fix metal bonding in the given structure.

Parameters: astructure (schrodinger.Structure.structure) – the structure object for which metal bonding will be fixed

schrodinger.application.matsci.nano.xtal.assign_bond_orders_w_mmlewis(astructure, fix_metals=True, logger=None)¶

Return a copy of the input structure that has bond orders assigned.

Parameters

astructure (schrodinger.Structure.structure) – the structure object for which bond orders will be assigned
fix_metals (bool) – fix metals coming from mmlewis
logger (logging.getLogger or None) – output logger or None if there isn’t one

Return type

schrodinger.Structure.structure

Returns

a copy of the input structure with the bond orders assigned

schrodinger.application.matsci.nano.xtal.get_chorus_properties(astructure)¶

Return a tuple containing the nine chorus properties of the given structure.

Parameters: astructure (schrodinger.Structure.structure) – the structure that has the chorus properties defined
Return type: tuple
Returns: contains the nine chorus properties

schrodinger.application.matsci.nano.xtal.extract_chorus_lattice_vector(struct, letter)¶

Extract the lattice vector from the chorus box properties. Each vector is comprised of 3 properites ending in mx, my, and mz, where m is either a, b or c. For instance, the a vector properties end in ax, ay and az.

Parameters

struct (schrodinger.structure.Structure) – The structure with the periodic boundary information
letter (str) – The single letter, a, b or c, that indicates which of the three vectors is desired

Return type

np.array

Returns

Numpy array of chrous for the given lattice letter (direction).

schrodinger.application.matsci.nano.xtal.get_params_from_chorus(chorus_properties)¶

Return the a, b, c, alpha, beta, and gamma lattice properties from the nine chorus properties.

Parameters: chorus_properties (list) – contains the nine chorus properties, i.e. ax, ay, az, bx, …, cz
Return type: list
Returns: a, b, c, alpha, beta, and gamma lattice properties

schrodinger.application.matsci.nano.xtal.get_chorus_from_params(params)¶

Return the nine chorus properties, i.e. [ax, ay, az, bx, …, cz], from the six lattice parameters a, b, c, alpha, beta, and gamma.

Parameters: params (list) – contains the a, b, c, alpha, beta, and gamma lattice parameters
Return type: list
Returns: contains the nine chorus properties

schrodinger.application.matsci.nano.xtal.get_volume_from_params(params)¶

Return cell volume (in Angstrom^3) from cell parameters.

Parameters: params (list) – contains the a, b, c, alpha, beta, and gamma lattice parameters
Return type: float
Returns: Cell volume in Angstrom^3

schrodinger.application.matsci.nano.xtal.get_volume_from_vecs(vecs)¶

Return cell volume (in Angstrom^3) from lattice vectors.

Parameters: params (list) – lattice vectors parameters
Return type: float
Returns: Cell volume in Angstrom^3

schrodinger.application.matsci.nano.xtal.get_cell_pairs(astructure, cell_distance, pbc_bonding=True, atom_indices=None, chorus_properties=None)¶

Using a distance cell that optionally honors a PBC return a list of tuples of atom index pairs that are within the specified distance.

Parameters

astructure (schrodinger.Structure.structure) – the structure containing the pairs
cell_distance (float) – the distance used in the distance cell, if using a PBC then min([cell_distance, a, b, c]) is actually what is used
pbc_bonding (bool) – if True and the chorus box properties exist on the incoming structure then the distance cell will honor the PBC, otherwise any PBC is not considered
atom_indices (list or None) – a list of atom indices to search for pairs, each atom is searched for pairs that may or may not already be in this list, if None then all atoms are searched
chorus_properties (list or None) – contains the nine chorus box properties that define a PBC, i.e. [ax, ay, az, bx, …, cz], if None then the chorus structure properties will be used if available and if not available then no PBC will be used in the DistanceCell

Return type

list

Returns

contains tuples of unique atom index pairs within the specified distance

class schrodinger.application.matsci.nano.xtal.PBCBond(atom1, atom2, order, also_reg_bond)¶

Bases: object

Class to manage a PBC bond, i.e. a long bond connecting two real atoms on opposite sides of a unit cell that is used in lieu of the bond between the real and image atoms.

PBC_BOND_THRESHOLD = 0.001¶

PBC_BOND_KEY = 'b_matsci_PBC_bond'¶

ALSO_REG_BOND_KEY = 'b_matsci_also_reg_bond'¶

PBC_BOND_COLOR_KEY = 'i_m_color'¶

PBC_BOND_COLOR = 4¶

AHEAD = 'ahead'¶

BEHIND = 'behind'¶

__init__(atom1, atom2, order, also_reg_bond)¶

Create an instance.

Parameters

atom1 (int) – the first atom index of the bond
atom2 (int) – the second atom index of the bond
order (int) – the bond order
also_reg_bond (bool) – indicates whether this PBC bond is also a regular bond, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell

setDeltasToNeighboringCells(atom1_vec, atom2_vec, spanning_vectors)¶

Set two dictionaries, one for moving to neighboring cells ahead and one for moving behind. Keys are tuples of integer cell deltas and values are (tail, head) tuples giving a directionality of this PBC bond along the given direction.

Parameters

atom1_vec (numpy.array) – vector to the first atom of the PBC bond
atom2_vec (numpy.array) – vector to the second atom of the PBC bond
spanning_vectors (dict) – keys are tuples of cell index triples, values are tuples of normalized spanning vectors for the cell and their original lengths

getNeighborPBCBond(cell_indices, ncella, ncellb, ncellc, cell_size, cell_delta, tail_head)¶

Return a (tail, head) ordered tuple of atom indices for the neighboring PBC bond in the cell given by the cell delta. If this cell is the first or last cell then it will wrap around to the ending or beginning cell, respectively.

Parameters

cell_indices (tuple) – a triple of cell indices
ncella (int) – the number of cells along a
ncellb (int) – the number of cells along b
ncellc (int) – the number of cells along c
cell_size (int) – the number of atoms in a cell
cell_delta (tuple) – a triple of cell deltas which provide the neighboring cells location
tail_head (tuple) – provides the tail and head atom indices for this PBC bond given the cell delta

Return type

tuple

Returns

atom indices for the neighboring PBC bond

offsetAtomData(offset)¶

Offset the atom data of this instance.

Parameters: offset (int) – the offset to use

class schrodinger.application.matsci.nano.xtal.PBCBonds(cell_indices=None, pbc_bonds_dict=None, cell_size=None, cov_offset=0.4)¶

Bases: object

Class to manage a collection of PBC bonds.

FIRST_CELL = (1, 1, 1)¶

__init__(cell_indices=None, pbc_bonds_dict=None, cell_size=None, cov_offset=0.4)¶

Create an instance.

Parameters

cell_indices (tuple or None) – a triple of cell indices indicating to which cell the given PBC bonds belong, if None then the first cell will be used
pbc_bonds_dict (dict or None) – used to create a dictionary of PBCBond objects, keys are tuples of PBC bond atom index pairs, values are tuples of bond orders and booleans indicating whether the PBC bond is also a regular bond, if None then the dictionary of PBCBond ojects will be empty
cell_size (int) – the number of atoms in a cell
cov_offset (float) – the maximum distance for a connection is the sum of the covalent radii of the two atoms weighted by cov_factor plus this offset in angstrom, increasing this value will increase the number of connections

setPBCBonds(pbc_bonds_dict)¶

Create a dictionary of PBCBond objects from a dictionary containing PBC bonds.

Parameters: pbc_bonds_dict (dict) – keys are tuples of PBC bond atom index pairs, values are tuples of bond orders and booleans indicating whether the PBC bond is also a regular bond

updatePBCBondOrders(astructure)¶

Update the bond orders in this instance given a structure with updated PBC bond orders.

Parameters: astructure (schrodinger.Structure.structure) – the structure with the updated PBC bond orders

setDeltasToNeighboringCells(astructure, lattice_vectors)¶

For each PBC bond in this cell determine the cell deltas that are needed to move ahead and behind to relevant neighboring cells.

Parameters

astructure (schrodinger.Structure.structure) – the structure with the PBC bonds
lattice_vectors (list of numpy.array) – the lattice a, b, and c vectors

cleanUpPBCBonds(astructure, pairs, delete)¶

Clean up the specified PBC bonds in the structure.

Parameters

astructure (schrodinger.Structure.structure) – the structure with the PBC bonds
pairs (list) – tuples of PBC bonding atom index pairs
delete (bool) – if True then the PBC bonds will be deleted

getOffsetPBCBonds(cell_indices, offset)¶

Return a PBCBonds instance for the provided cell indices in which the atom indices have been offset by the given amount.

Parameters

cell_indices (tuple) – a triple of cell indices indicating to which cell the offset PBC bonds belong
offset (int) – the offset to use in setting the atom indices

Return type

PBCBonds

Returns

a PBCBonds object for the given cell containing the offset atoms

connectToCells(astructure, ncella, ncellb, ncellc, direction)¶

Connect the PBC bonds in this cell with those relevant neighboring cells ahead of or behind this one so as to create real bonds from pairs of PBC bonds or new PBC bonds. If this cell is the first or last along a given direction then if possible it will create new PBC bonds by wrapping around to ending or beginning cells, respectively.

Parameters

astructure (schrodinger.Structure.structure) – the structure for which the connections are sought
ncella (int) – the number of cells along a
ncellb (int) – the number of cells along b
ncellc (int) – the number of cells along c
direction (str) – the direction in which to go for the next PBC bond, either PBCBond.AHEAD or PBCBond.BEHIND

schrodinger.application.matsci.nano.xtal.add_labeled_pbc_bond(astructure, atom1, atom2, order, is_pbc_bond=False, also_reg_bond=False, color=4)¶

Add the specified bond to the provided structure and label it depending on if it is a PBC bond.

Parameters

astructure (schrodinger.Structure.structure) – the structure to which the bond will be added
atom1 (int) – the first atom index of the bond
atom2 (int) – the second atom index of the bond
order (int) – the bond order
is_pbc_bond (bool) – if True then the specified bond is a PBC bond so we will label it as so
also_reg_bond (bool) – if True indicates that the given PBC bond is also a regular bond, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell
color (int or None) – if integer specifies that PBC bonds, that are not also regular bonds, should be colored with this color

schrodinger.application.matsci.nano.xtal.get_natom_btw_two_cells(cell1, cell2, extents, size)¶

Using a traversal path of c then b then a, return the number of atoms between two cells, of the given size, in a super cell with the given extents.

Parameters

cell1 (tuple) – a triple of cell indices for the first cell
cell2 (tuple) – a triple of cell indices for the second cell
extents (list) – contains the number of cells along a, b, and c lattice vectors in the super cell
size (int) – the number of atoms in a cell

Return type

int

Returns

the number of atoms between the two cells

schrodinger.application.matsci.nano.xtal.delete_all_pbc_bonds(astructure)¶

Delete all PBC bonds from the given structure.

Parameters: astructure (schrodinger.Structure.structure) – the structure from which the bonds will be deleted

schrodinger.application.matsci.nano.xtal.is_pbc_bond(astructure, atom1, atom2, check_also_reg_bond=False, unit_lattice_vectors=None, pbc=None)¶

Return a (is_pbc_bond, also_reg_bond, bond_distance) tuple that indicates (1) whether the specified bond is a PBC bond, (2) if checked whether that PBC bond is also a regular bond, and (3) the bond length.

Parameters

astructure (schrodinger.Structure.structure) – the structure that has the bond
atom1 (schrodinger.structure._StructureAtom) – the first atom of the bond
atom2 (schrodinger.structure._StructureAtom) – the second atom of the bond
check_also_reg_bond (bool) – check if the PBC bond is also a regular bond, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell
unit_lattice_vectors (list of (numpy.array, float) tuples or None) – contains normalized a, b, and c lattice vectors and their original lengths, is None if no check for PBC bonds that are also regular bonds is being performed
pbc (schrodinger.infra.structure.PBC or None) – The infrastructure PBC created from the Chorus box properties, if None, pbc object will be created

Return type

tuple

Returns

a (is_pbc_bond, also_reg_bond, bond_distance) tuple

schrodinger.application.matsci.nano.xtal.get_lattice_param_properties(astructure)¶

Return a tuple containing the six lattice parameter properties of the given structure.

Parameters: astructure (schrodinger.Structure.structure) – the structure that has the lattice parameter properties defined
Return type: tuple
Returns: contains the six lattice parameter properties

schrodinger.application.matsci.nano.xtal.get_normalized_spanning_vectors(lattice_vectors)¶

Return the thirteen unique normalized spanning vectors for the cell.

Parameters: lattice_vectors (list of numpy.array) – the lattice a, b, and c vectors
Return type: dict
Returns: keys are tuples of cell index triples, values are tuples of normalized spanning vectors and their original lengths

schrodinger.application.matsci.nano.xtal.get_element_priority(pair)¶

Return the formula ordering priority of the element in the given pair.

Parameters: pair (tuple) – (element, number) tuple
Return type: int
Returns: the element priority

schrodinger.application.matsci.nano.xtal.get_unit_cell_formula(unit_cell)¶

Return the formatted unit cell formula of the given unit cell.

Parameters: unit_cell (schrodinger.Structure.structure) – the structure object for the unit cell
Return type: str
Returns: the formatted unit cell formula

schrodinger.application.matsci.nano.xtal.trans_cart_to_fract(cart_vec, a_param, b_param, c_param, alpha_param, beta_param, gamma_param)¶

Transform the given vector in the Cartesian basis to the fractional basis.

Parameters

cart_vec (numpy.array) – the vector to be transformed from the Cartesian basis to the fractional basis
a_param (float) – the lattice a parameter
b_param (float) – the lattice b parameter
c_param (float) – the lattice c parameter
alpha_param (float) – the lattice alpha parameter
beta_param (float) – the lattice beta parameter
gamma_param (float) – the lattice gamma parameter

Return type

numpy.array

Returns

the given vector in the fractional basis

schrodinger.application.matsci.nano.xtal.trans_fract_to_cart(fract_vec, a_param, b_param, c_param, alpha_param, beta_param, gamma_param)¶

Transform the given vector in the fractional basis to the Cartesian basis.

Parameters

fract_vec (numpy.array) – the vector to be transformed from the fractional basis to the Cartesian basis
a_param (float) – the lattice a parameter
b_param (float) – the lattice b parameter
c_param (float) – the lattice c parameter
alpha_param (float) – the lattice alpha parameter
beta_param (float) – the lattice beta parameter
gamma_param (float) – the lattice gamma parameter

Return type

numpy.array

Returns

the given vector in the Cartesian basis

schrodinger.application.matsci.nano.xtal.trans_cart_to_frac_from_vecs(coords, a_vec, b_vec, c_vec, rec=False)¶

Transform coordinates from (reciprocal) Cartesian to (reciprocal) fractional using lattice vectors.

Parameters

coords (numpy.array) – a list of Cartesian coordinates
a_vec (list of 3 floats) – ‘a’ lattice vector
b_vec (list of 3 floats) – ‘b’ lattice vector
c_vec (list of 3 floats) – ‘c’ lattice vector
rec (bool) – If True, work in reciprocal space

Return type

numpy array

Returns

Coordinates in fractional coordinates

schrodinger.application.matsci.nano.xtal.trans_frac_to_cart_from_vecs(coords, a_vec, b_vec, c_vec, rec=False)¶

Transform coordinates from (reciprocal) fractional to (reciprocal) Cartesian using lattice vectors.

Parameters

coords (numpy.array) – a list of fractional coordinates
a_vec (list of 3 floats) – ‘a’ lattice vector
b_vec (list of 3 floats) – ‘b’ lattice vector
c_vec (list of 3 floats) – ‘c’ lattice vector
rec (bool) – If True, work in reciprocal space

Return type

numpy array

Returns

Coordinates in Cartesian coordinates

schrodinger.application.matsci.nano.xtal.get_cell(asu, space_group=None, lattice_params=None, extents=None, xtal_kwargs=None)¶

Build and return a crystalline cell using the given asymmetric unit, space group, lattice parameters, and extents.

Parameters

asu (schrodinger.structure.Structure) – the asymmetric unit
space_group (str or None) – the full or short Hermann-Mauguin symbol of the space group or None in which case the asu structure property Crystal.SPACE_GROUP_KEY will be used
lattice_params (list or None) – the six lattice parameters or None in which case the asu structure properties Crystal.A_KEY, Crystal.B_KEY, Crystal.C_KEY, Crystal.ALPHA_KEY, Crystal.BETA_KEY, and Crystal.GAMMA_KEY will be used
extents (list or None) – the integer extents along the a, b, and c lattice vectors or None if there are none
xtal_kwargs (dict or None) – extra xtal.Crystal kwargs or None if there are none

Return type

schrodinger.structure.Structure

Returns

the built cell

schrodinger.application.matsci.nano.xtal.get_vectors_from_chorus(astructure)¶

Return the three lattice vectors from the nine lattice chorus properties.

Parameters: astructure (schrodinger.structure.Structure) – the structure that has the chorus properties
Raises: ValueError – if any chorus property is missing
Return type: numpy.array
Returns: the three lattice vectors

schrodinger.application.matsci.nano.xtal.get_conv_from_vecs(a_vec, b_vec, c_vec)¶

Generate matrices to convert from fractional to Cartesian and back.

Parameters

a_vec (list of 3 floats) – ‘a’ lattice vector
b_vec (list of 3 floats) – ‘b’ lattice vector
c_vec (list of 3 floats) – ‘c’ lattice vector

Return type

tuple of matrices

Returns

Matrices that convert fractional atomic coordinates to Cartesian and back

schrodinger.application.matsci.nano.xtal.create_new_box(struct, minval=0.0, buffer=2)¶

Create a new box that is large enough to encompass the X, Y and Z lengths of the system

Parameters

struct (schrodinger.structure.Structure) – The structure to work on
minval (float) – Minimum length of the cell edge or 0. if vdW is fine
buffer (float) – The buffer to add to all PBC lengths. We add 2.0 as the default vdw buffer to make sure atoms at the boundary don’t clash with their mirror images.

schrodinger.application.matsci.nano.xtal.set_lattice_properties(astructure, lattice_properties)¶

Set the given lattice properties on the structure.

Parameters

astructure (schrodinger.structure.Structure) – the structure on which to set the lattice properties
lattice_properties (list) – a, b, c, alpha, beta, and gamma lattice properties

schrodinger.application.matsci.nano.xtal.make_p1(astructure, logger=None, in_place=False)¶

Make a P1 cell.

Parameters

astructure (schrodinger.structure.Structure) – the structure to make P1
logger (logging.Logger or None) – if not None then the logger for printing
in_place (bool) – if True then operate directly on the given structure as opposed to a copy of it

Return type

schrodinger.structure.Structure

Returns

the P1 cell

schrodinger.application.matsci.nano.xtal.sync_pbc(st, create_pbc=False, in_place=False)¶

Return the given structure with a synchronized PBC, if create_pbc is True and the structure lacks a PBC then one will be created, otherwise this function will return False if there is no PBC.

Parameters

st (structure.Structure) – the structure with the PBC to be synchronized
create_pbc (bool) – if True and the given structure lacks a PBC then a minimal PBC will be created, if False and if the given structure lacks a PBC then this function will return False
in_place (bool) – if True then operate directly on the given structure as opposed to a copy of it

Return type

structure.Structure or bool

Returns

the structure with a synchronized PBC or False if there was no PBC and one wasn’t created

schrodinger.application.matsci.nano.xtal.sync_pbc2(struct, lattice_params=None, chorus_params=None, prioritize_cparams=True)¶

Sync PBC properties in place (without creating a new structure) for struct. If all PBC properties are absent (both chorus and PDB) return False. It is possible to provide new lattice or chorus parameters and to prioritize one of the sets.

Type

schrodinger.structure.Structure

Param

Structure to be modified

Parameters

lattice_params (list or numpy.array or None) – contains the a, b, c, alpha, beta, and gamma lattice parameters or None. These will be used instead of ones possibly obtained from the struct
chorus_params (list or numpy.array or None) – contains the nine chorus properties, i.e. ax, ay, az, bx, …, cz or None. These will be used instead of ones possibly obtained from the struct

Param

Prioritize chorus params over lattice params if True. If False, lattice params have priority

Return type

bool

Returns

True on syncing success, False if both sets were not provided or empty

schrodinger.application.matsci.nano.xtal.get_pbc_bonds_dict(astructure)¶

Return a PBC bonds dict for the given structure.

Parameters: astructure (schrodinger.structure.Structure) – the structure with the PBC bonds from which to create the dict
Return type: dict
Returns: keys are tuples of PBC bond atom index pairs, values are tuples of bond orders and booleans indicating whether the PBC bond is also a regular bond

schrodinger.application.matsci.nano.xtal.set_representation_bond(abond)¶

Set the representation of the given bond.

Parameters: abond (schrodinger.structure._StructureBond) – the bond to set the representation for

schrodinger.application.matsci.nano.xtal.set_pbc_properties(astructure, chorus_properties)¶

Set the chorus and PDB properties on the given structure using the given chorus properties.

Parameters

astructure (schrodinger.structure.Structure) – the structure on which the properties are set
chorus_properties (list) – contains the nine chorus properties, i.e. ax, ay, az, bx, …, cz

schrodinger.application.matsci.nano.xtal.transform_pbc(struct_in, supercell_matrix, scale_only=False, cell_only=False, origin_shift=None, overlap_threshold=0.25)¶

Create a new structure based on the transformation matrix. If both ‘scale_only’ and ‘cell_only’ are False (default behavior), atoms will be added or subtracted based on the expansion/contraction of the PBC.

Parameters

struct_in (schrodinger.structure.Structure) – Structure to which transformation will be applied
supercell_matrix (3 x 3 floats) – Transformation matrix
scale_only (bool) – If True, scale atoms to the new cell defined by supercell_matrix, this keeps constant fractional coordinates and number of atoms from the original ‘struct’
cell_only (bool) – If True, change cell frame to a new cell. This keeps constant Cartesian coordinates and number of atoms from the original ‘struct’. Note that if supercell cell is smaller than original cell, atoms could be cut by the new smaller cell frame
origin_shift (list of 3 floats) – Origin shift in fractional coordinates
overlap_threshold (float) – (Ang) distance used to define overlapping atoms
struct – Transformed structure

Rtype struct

schrodinger.structure.Structure

schrodinger.application.matsci.nano.xtal.get_simple_supercell_matrix(supercell_matrix)¶

Get minimal diagonal elements of a simple supercell matrix starting from (non)-diagonal supercell matrix. Supercell matrix can be: -1, 1, 1 2, -3, 4 -5, 6, 7 Resulting simple supercell (described by the matrix) must be able to hold the supercell above.

In the case of a smaller lattice, for example: 0.5 0 0 0 0.5 0 0 0 0.5

[1, 1, 1] will be returned

Parameters: supercell_matrix (3 x 3 list of floats) – Supercell matrix
Return type: list of three ints
Returns: Diagonal elements of the simple supercell matrix (must be positive nonzero integers)

schrodinger.application.matsci.nano.xtal.get_transformed_vectors(vecs, tmatrix)¶

Get new lattice vectors based on the original vectors and the transformation matrix.

Parameters

vecs (numpy.array) – Input lattice vectors (3x3)
tmatrix (numpy.array) – Transformation matrix

Return type

tuple

Returns

Transformed vectors (3x3), extents for the original vecs (3), trimmed transformation matrix (3x3)

schrodinger.application.matsci.nano.xtal.get_simple_supercell(struct, supercell_matrix)¶

Get supercell structure.

Parameters

struct (structure.Structure) – Input structure
supercell_matrix (List of 3 floats) – Diagonal elements of the supercell matrix

Return type

structure.Structure

Returns

Supercell structure

schrodinger.application.matsci.nano.xtal.get_transformation_matrix(vecs, new_vecs)¶

Get transformation matrix between old and new set of lattice vectors.

Parameters

vecs (3 x 3 float list) – Old lattice vectors
new_vecs (3 x 3 float list) – New lattice vectors

Return type

3 x 3 float list

Returns

Transformation matrix

schrodinger.application.matsci.nano.xtal.get_physical_properties(struct, vecs=None)¶

Get cell formula, volume and density of a struct.

Type: structure.Structure
Param: Input structure
Parameters: vecs (list(list) or None) – Lattice vectors. If None, will be obtained from structure
Return type: float, float, float
Returns: formula, volume and density

schrodinger.application.matsci.nano.xtal.set_physical_properties(struct)¶

Set cell formula, volume and density to struct.

Type: structure.Structure
Param: Input structure

schrodinger.application.matsci.nano.xtal.pdist_vec_row_col(d, i)¶

Convert from triangular indices of distance matrix to indices of the square form.

Parameters

d (int) – row length of the original triangular matrix
i (numpy.array(int)) – Condensed triangular indices, 0-indexed

Return type

numpy.array(int), numpy.array(int)

Returns

row and column indices (0-indexed) from the corresponding square form

schrodinger.application.matsci.nano.xtal.preserve_bonds(struct, to_keep, to_remove)¶

Try to preserve bonding during the remove of the duplicates atoms.

Parameters

struct (structure.Structure) – Structure to preserve bonding for
to_keep (list) – List of atom indices to keep
to_remove (list(list)) – List of lists of atom indices to be removed. Each item in the list is a list of duplicated atom indices corresponding to the atom index from to_keep list

schrodinger.application.matsci.nano.xtal.translate_to_1st_cell(coords, vecs, is_cartesian=True, fract_offset=0.0001, axes=None, origin=(0.0, 0.0, 0.0))¶

Translate coordinates to the 1st cell (in range [0, 1). If it is a supercell with original vectors, overlap atoms are expected.

Parameters

coords (list) – Coordinates (can be Cartesian or fractional, see is_cartesian)
vecs (list) – Lattice vectors
is_cartesian (bool) – Whether input coordinates are Cartesian or fractional
fract_offset (float) – DEPRECATED. The threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary
axes (iterable or None) – List of axes to use
origin (tuple) – the origin of the cell to which to translate in fractional coordinates

Returns

Translated Cartesian coordinates

schrodinger.application.matsci.nano.xtal.coords_outside_1st_cell(coords, vecs, is_cartesian=True, axes=None, above=False, below=False, is_hb=False)¶

Returns coordinate indices (atom indices - 1) of the atoms outside of the cell defined with vecs.

Parameters

coords (list) – Coordinates (can be Cartesian or fractional, see is_cartesian)
vecs (list) – Lattice vectors
is_cartesian (bool) – Whether input coordinates are Cartesian or fractional
fract_offset (float) – The threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary
axes (iterable or None) – List of axes to use
above (bool) – Whether to return indices that are “above” the first cell separately
below (bool) – Whether to return indices that are “below” the first cell separately
is_hb (bool) – Whether system is located in the cell around origin (between -0.5 and 0.5) or between 0 and 1

Return type

numpy.array

Returns

Indices outside the first cell

schrodinger.application.matsci.nano.xtal.is_normal_surface(vecs=None, pbc=None)¶

Checks if C-axis is normal to the a-b plane from lattice vectors or pbc object

Parameters

vecs (numpy.array) – Lattice vectors
pbc (schrodinger.infra.structure.PBC) – The structure pbc object

Return type

bool

Returns

Whether C-axis is normal to the a-b plane

schrodinger.application.matsci.nano.xtal.are_c_and_z_parallel(pbc, tolerance=0.98)¶

Return whether c vector is parallel to Z axis within a tolerance

Parameters: pbc (schrodinger.infra.structure.PBC) – The pbc object
Return type: bool
Returns: Whether C and Z are parallel

schrodinger.application.matsci.nano.xtal.move_atoms_into_cell(struct, frac_coords=None, overlap_tresh=0.25, fract_offset=0.0001, preserve_bonding=False)¶

Get structure with all the atoms moved into the first cell.

Type

structure.Structure

Param

Input structure

Parameters

frac_coords (numpy arrays of arrays of 3 floats or None) – Fractional coordinates
overlap_tresh (float) – Distance between two atoms, such that they are considered overlapping
fract_offset (float) – The threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary
preserve_bonding (bool) – If True, preserve bonding between atoms (might be slow)

Return type

structure.Structure

Returns

Structure with all the atoms moved inside first unit cell

schrodinger.application.matsci.nano.xtal.get_unit_lattice_vector_info(astructure)¶

Return a list of tuples containing unit lattice vector information, i.e. the unit lattice vectors and their original lengths.

Parameters: astructure (schrodinger.structure.Structure) – the structure with lattice vectors defined by chorus box properties
Return type: list of tuples
Returns: each (numpy.array, float) tuple contains (1) the unit lattice vector and (2) the length of the original vector

schrodinger.application.matsci.nano.xtal.label_pbc_bonds(astructure, pbc=None, check_also_reg_bond=None, is_cg=None)¶

Label PBC bonds.

Parameters

astructure (schrodinger.structure.Structure) – the structure with the bonds to label
pbc (schrodinger.infra.structure.PBC or None) – The infrastructure PBC created from the Chorus box properties, if None, pbc object will be created
check_also_reg_bond (bool or None) – if True then PBC bonds will be checked to see if they are also regular bonds, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell. If None, this will be evaluated
is_cg (bool or None) – True, if structure is CG, otherwise False. If None, structure will be evaluated (slow)
pbc – The infrastructure PBC created from the Chorus box properties, if None, pbc object will be created

schrodinger.application.matsci.nano.xtal.label_pbc_bond(abond, also_reg_bond=False, color=4)¶

Label this PBC bond.

Parameters

abond (schrodinger.structure._StructureBond) – the PBC bond to label
also_reg_bond (bool) – if True indicates that the given PBC bond is also a regular bond, meaning that one of the atoms of the PBC bond is covalently bound to two copies of the other atom, one inside the cell and one outside the cell
color (int or None) – if integer specifies that a PBC bond, that is not also a regular bond, should be colored with this color, if None then no coloring is performed

schrodinger.application.matsci.nano.xtal.get_primitive_cell(struct_in, set_space_group=False)¶

Get primitive cell.

Parameters: struct (schrodinger.structure.Structure) – Original structure
Return type: schrodinger.structure.Structure
Returns: Primitive cell with the space group set, if requested

schrodinger.application.matsci.nano.xtal.get_std_cell_from_spglib_dataset(struct, dataset)¶

Get standardized cell (structure) from spglib dataset and copy all the structure properties (except symmetry related) from struct_in.

Parameters

struct (schrodinger.structure.Structure) – Structure to get structure properties from
dataset (dict) – Dataset containing cell and space group properties, see: https://atztogo.github.io/spglib/python-spglib.html#get-symmetry-dataset

Return type

schrodinger.structure.Structure

Returns

Standardized cell with the space group set

schrodinger.application.matsci.nano.xtal.assign_space_group(struct_in, symprec=0.01, search_alt_cells=False)¶

Set space group and space group id to the input structure. An error message is returned on failure.

Type

schrodinger.structure.Structure

Param

Input structure that will be modified

Parameters

symprec (float) – Symmetry tolerance used for atomic coordinates to assign space group
search_alt_cells (bool) – If True, search for alternative cells

Return type

list

Returns

If search_alt_cells is True, conventional and primitive cells are returned. Otherwise, empty list.

schrodinger.application.matsci.nano.xtal.get_normal_surf(struct, restore_vacuum=True, overlap_threshold=0.25)¶

Enforce system to have C-axis normal to the a-b plane. This is done by straining the structure.

Parameters

struct (schrodinger.structure.Structure) – Input structure
restore_vacuum (bool) – If True, set vacuum value in Z direction to the original value, before the surface is “normalized”. Should be set to True for infinite systems. If False, don’t modify cell after normalization
overlap_threshold (float) – (Ang) distance used to define overlapping atoms

Return type

schrodinger.structure.Structure

Returns

Output structure with C-axis normal to the a-b plane

schrodinger.application.matsci.nano.xtal.get_normal_surf_from_HKL(hkl, vecs, max_normal_search=10)¶

Calculate transformation matrix with c-axis most normal to a-b plane from HKL plane indices and lattice vectors.

Parameters

hkl (list of 3 integers) – Miller plane indices
vecs (list of 3 lists of floats) – Lattice vectors
max_normal_search (int) – Maximum number of linear combinations of lattice vectors to be considered when search most normal surface

Return type

bool, numpy.array 3 x 3 of integers

Returns

True, if normal is found, otherwise False and transformation matrix

schrodinger.application.matsci.nano.xtal.lcm(numbers)¶

Get the lowest common multiple of a sequence of numbers.

Parameters: numbers (list of integers) – Sequence of integers
Return type: int
Returns: Lowest common multiple

schrodinger.application.matsci.nano.xtal.reduce_vector(vector)¶

Get reduced vector of a transformation matrix.

Parameters: vector (list of integers) – Components of a vector of transformation matrix
Return type: list of integers
Returns: Components of a reduced vector of transformation matrix

schrodinger.application.matsci.nano.xtal.get_struct_from_CIF(cif_fn)¶

Get structure from CIF file.

Parameters: cif_fn (str) – CIF file name
Return type: schrodinger.structure.Structure
Returns: Structure from CIF file
Raises: ValueError – If file doesn’t exist or the structure could not be read

schrodinger.application.matsci.nano.xtal.translate_atoms(cell, origin=None)¶

Translate all atoms to the first unit cell.

Parameters

cell (schrodinger.structure.Structure) – the structure to translate, must have chorus properties defined
origin (list or None) – the list with origin of the cell to which to translate in fractional coordinates. If none it will be set to [-0.5, -0.5, -0.5] for system with s_ffio_ct_type set and ParserWrapper.ORIGIN for others.

schrodinger.application.matsci.nano.xtal.translate_molecules(cell, centroids=False, maxes=False, fract_offset=0.0001)¶

Translate all molecules to the first unit cell.

Parameters

cell (schrodinger.structure.Structure) – the structure to translate, must have chorus properties defined
centroids (bool) – If True, translation is using molecular centroid
maxes (bool) – If True, translation is using maximum in x, y, z direction for each molecule. Cannot be used together with centroids option
fract_offset (float) – The threshold used to compare floating point fractional coordinate values and in particular those that are on the cell boundary

schrodinger.application.matsci.nano.xtal.get_cell_fast(asu, symm_ops)¶

Get crystal cell with all applied symmetry operators on the ASU.

Parameters

asu (structure.Structure) – Asymmetric unit
symm_ops (list) – List of symmetry operations (4 x 4 matrices)

Return type

structure.Structure

Returns

Crystal cell

schrodinger.application.matsci.nano.xtal.create_nonbonded_extents(struct, extents=None)¶

Place the given structure in the middle of extents, adding one cell in each of the +/- directions of the indicated vectors. No bonding is performed - the structure created this way is only good for representing atom locations/sterics. If struct has no pbc, a copy of it will be returned.

The atoms from the given structure will retain their order and be the first atoms in the returned structure.

The diagram below demonstrates what the structure looks like if extents=[1,1,0] is given. “o” represents an added extent image, “x” represents the given system, and the lines are just there for visual reference:

 o | o | o
-----------
 o | x | o
-----------
 o | o | o

Parameters

struct (structure.Structure) – The original structure to extend
extents (list) – Which vectors should be extended and by how many images in the + and - directions. For instance, [1, 1, 1] indicates to extend by 1 cell each in the + and - a, b and c directions. [2, 1, 0] extend by 2 cells in +/- a, 1 cell in +/- b, and will not extend in the c direction. The default is [1, 1, 1].

Return type

schrodinger.structure.Structure

Returns

The extended structure

schrodinger.application.matsci.nano.xtal.get_pbc_origin(st)¶

Return the PBC origin in Angstrom from the given structure.

Parameters: st (structure.Structure) – the structure
Raises: KeyError – if no PBC exists
Return type: numpy.array
Returns: the origin in Angstrom

schrodinger.application.matsci.nano.xtal.get_pbc_bonded_atom_pairs(st, along_vector_idxs=None, exclusive=False, only_infinite=False)¶

Return a dictionary of PBC bonded atom pairs along the specified directions.

Parameters

st (structure.Structure) – the structure
along_vector_idxs (list or None) – the directions to consider, 0 for a-vector, 1 for b-vector, and/or 2 for c-vector, if None then the c-vector is used by default
exclusive (bool) – if True then consider PBC bonds that wrap only the specified directions, if False then must wrap the specified directions but can also wrap other directions
only_infinite (bool) – if True then consider only PBC bonds that are responsible for the system being infinite (meaning that breaking such bonds makes the infinite system finite)

Return type

dict

Returns

contains atom index pairs for PBC bonds, keys are direction indices, values are lists of atom index (near, far) pair tuples where the fractional coordinate along the keyed direction is near < far

schrodinger.application.matsci.nano.xtal.delete_pbc_bonds(st, along_vector_idxs=None, exclusive=False, only_infinite=False)¶

Delete PBC bonds from the given structure along the specified directions.

Parameters

st (structure.Structure) – the structure
along_vector_idxs (list or None) – the directions to consider, 0 for a-vector, 1 for b-vector, and/or 2 for c-vector, if None then the c-vector is used by default
exclusive (bool) – if True then consider PBC bonds that wrap only the specified directions, if False then must wrap the specified directions but can also wrap other directions
only_infinite (bool) – if True then consider only PBC bonds that are responsible for the system being infinite (meaning that breaking such bonds makes the infinite system finite)

Return type

dict

Returns

contains atom index pairs for PBC bonds, keys are direction indices, values are lists of atom index (near, far) pair tuples where the fractional coordinate along the keyed direction is near < far

schrodinger.application.matsci.nano.xtal.has_pbc(st)¶

Return True if the given structure has a PBC.

Parameters: st (schrodinger.structure.Structure) – the structure
Return type: bool
Returns: True if the given structure has a PBC

schrodinger.application.matsci.nano.xtal.scale_cell(vecs, new_volume)¶

Return a new Lattice with volume new_volume by performing a scaling of the lattice vectors so that length proportions and angles are preserved.

Parameters

vecs (numpy.array) – Original lattice vectors
new_volume (float) – New volume

Return type

numpy.array

Returns

New lattice vectors with the desired volume

schrodinger.application.matsci.nano.xtal.both_bond_types_exist(st)¶

Raise a ValueError if the given structure does not have at least both a single regular bond and a single PBC bond, otherwise return sample atom indices for both.

Parameters: st (schrodinger.structure.Structure) – the structure to check
Raises: ValueError – if both bond types do not exist
Return type: tuple
Returns: pair tuple containing two pair tuples, one for a regular bond and one for a PBC bond

schrodinger.application.matsci.nano.xtal.get_strained_cell(pos, vecs, new_vecs, remap=True)¶

Strain cell using the vectors and atom coordinates are scaled proportionally if remap is True.

Parameters

pos (list) – Atomic positions
vecs (list[3x3]) – Lattice vectors
new_vecs (list[3x3]) – New lattice vectors
remap (bool) – whether to strain the atom coordinates in the cell

Return type

list, list[3x3]

Returns

Updated positions, updated lattice vectors

schrodinger.application.matsci.nano.xtal.is_valid_lower_triangle(pbc_vecs)¶

Check if vectors obey lower triangle right hand-side convention. Valid vecs have zeros in the upper triangle and positive along the diagonal.

Parameters: pbc_vecs (list or PBC) – Lattice vectors or a PBC object
Return type: bool
Returns: Whether vectors obey lower triangle right hand-side convention

schrodinger.application.matsci.nano.xtal.chorus_to_lower_triangle(struct)¶

Update chorus properties and with them atom coordinates so that upper triangle of the lattice vectors are all zeros. This is needed so that maestro displays structure correctly.

Parameters: struct (structure.Structure) – Structure to update
Return type: structure.Structure
Returns: Updated structure (not a copy!!)