schrodinger.application.matsci.kmc module

Utilities for working with VOTCA

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.kmc.ColumnData(type, default)

Bases: tuple

default

Alias for field number 1

type

Alias for field number 0

class schrodinger.application.matsci.kmc.MoleculeData(index, name, mtype, posx, posy, posz)

Bases: tuple

index

Alias for field number 0

mtype

Alias for field number 2

name

Alias for field number 1

posx

Alias for field number 3

posy

Alias for field number 4

posz

Alias for field number 5

schrodinger.application.matsci.kmc.is_votca_prop(prop)

Check if a property is a votca property

Parameters

prop (str) – The property to check

Return type

str or None

Returns

If the property is a votca property, the type of property is returned as a module-level constant. If the property is not recognized as a VOTCA property, None is returned.

schrodinger.application.matsci.kmc.parse_mobility_or_velocity_prop(prop)

Parse a property name and return the information from it if it is a VOTCA mobility or velocity property

Parameters

prop (str) – The property to check

Return type

(int, str, str) or None

Returns

The integer is the field index, the first string is the charge (HOLE or ELECTRON) and the second string is the axis name. None is returned if the property is not a mobility or velocity property.

schrodinger.application.matsci.kmc.parse_field_prop(prop)

Parse a property name and return the information from it if it is a VOTCA field property

Parameters

prop (str) – The property to check

Return type

(int, str) or None

Returns

The integer is the field index, the string is the axis name. None is returned if the property is not a field property.

schrodinger.application.matsci.kmc.parse_database_prop(prop)

Parse a property name and return the information from it if it is a VOTCA database property

Parameters

prop (str) – The property to check

Return type

(int, list) or None

Returns

The integer is the field index, the list contains the charges (HOLE and/or ELECTRON). None is returned if the property is not a database property

class schrodinger.application.matsci.kmc.AxisData

Bases: object

Holds data that differs on the X, Y and Z axes

__init__()

Create an AxisData object

setComponent(axis, value)

Set the data for one axis

Parameters

axis (str or int) – Either the capital name of an axis (X, Y, Z) or the numerical index of that axis

class schrodinger.application.matsci.kmc.SQLCursor(path)

Bases: object

Context manager for reading or modifying an SQL database. Ensures that changes are committed and the cursor/connection are closed when finished.:

cmd = "black SQL magic"
with SQLCursor(path_to_sql_file) as cursor:
    cursor.execute(cmd)
__init__(path)
class schrodinger.application.matsci.kmc.Table(filename)

Bases: object

Base table class for internal and VOTCA SQL tables

TABLE_NAME = ''
COLUMNS = {}
CREATION_COMMAND = 'CREATE TABLE {name} ({columns});'
ADDROW_COMMAND = 'INSERT INTO {name} ({cols}) VALUES ({ph})'
NULL_ALLOWED = False
SQL_ID = '_id'
SQID = 'id'
NAME = 'name'
TYPE = 'type'
MOL = 'mol'
POSX = 'posX'
POSY = 'posY'
POSZ = 'posZ'
FRAME = 'frame'
TOP = 'top'
SEG = 'seg'
__init__(filename)

Create a Table instance

Parameters

filename (str) – The path to the SQL file

setCursor(cursor)

Set the SQL cursor this table should use

Parameters

cursor (sqlite3.Cursor) – The cursor to use for database read/writes

create()

Create this table in the database

Raises

SQLCreationError – If the cursor is not defined

getMoleculeInfo(molecule, centroid=True)

Get common database information for a molecule object

Parameters
  • molecule (schrodinger.structure._StructureMolecule) – The molecule object to get information for

  • centroid (bool) – Include information about the molecule’s centroid. If False, all centroid information will be 0.

Return type

MoleculeData

Returns

A MoleculeData object containing the information

static getSegmentType(molecule)

Get the segment type for this molecule

Segment names will be type_X, where X is the molecule number

Parameters

molecule (structure._Molecule) – The molecule object

Return type

str

Returns

The segment type for this molecule

static getAllSegmentTypes(struct)

Get all the segment types for this structure

Parameters

struct (structure.Structure) – The structure object

Return type

set

Returns

Each item of the set is the name of a segment type

class schrodinger.application.matsci.kmc.FramesTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The frames table

TABLE_NAME = 'frames'
TIME = 'time'
STEP = 'step'
BOX11 = 'box11'
BOX12 = 'box12'
BOX13 = 'box13'
BOX21 = 'box21'
BOX22 = 'box22'
BOX23 = 'box23'
BOX31 = 'box31'
BOX32 = 'box32'
BOX33 = 'box33'
CANRIGID = 'canRigid'
COLUMNS = {'box11': ColumnData(type='REAL', default=None), 'box12': ColumnData(type='REAL', default=None), 'box13': ColumnData(type='REAL', default=None), 'box21': ColumnData(type='REAL', default=None), 'box22': ColumnData(type='REAL', default=None), 'box23': ColumnData(type='REAL', default=None), 'box31': ColumnData(type='REAL', default=None), 'box32': ColumnData(type='REAL', default=None), 'box33': ColumnData(type='REAL', default=None), 'canRigid': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=0), 'step': ColumnData(type='INT', default=0), 'time': ColumnData(type='REAL', default=0)}
addRow(struct)

Add a frame row to the table

The main frame information is the PBC box

Parameters

struct (schrodinger.structure.Structure) – The structure with the PBC information

class schrodinger.application.matsci.kmc.MoleculesTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The molecules table

TABLE_NAME = 'molecules'
COLUMNS = {'frame': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'top': ColumnData(type='INT', default=0), 'type': ColumnData(type='TEXT', default=None)}
addRow(molecule)

Add a row

Parameters

molecule (schrodinger.structure._StructureMolecule) – The molecule object to add a row for

class schrodinger.application.matsci.kmc.SitesMixin

Bases: object

Mixin for votca and matsci site tables

HAS_E = 'has_e'
HAS_H = 'has_h'
OCCPE = 'occPe'
OCCPH = 'occPh'
COMMON_COLUMNS = {'UcCnNe': ColumnData(type='REAL', default=0), 'UcCnNh': ColumnData(type='REAL', default=0), 'UcNcCe': ColumnData(type='REAL', default=0), 'UcNcCh': ColumnData(type='REAL', default=0), 'UnCnNe': ColumnData(type='REAL', default=0), 'UnCnNh': ColumnData(type='REAL', default=0), 'has_e': ColumnData(type='INT', default=0), 'has_h': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'mol': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'occPe': ColumnData(type='REAL', default=-1), 'occPh': ColumnData(type='REAL', default=-1), 'posX': ColumnData(type='REAL', default=None), 'posY': ColumnData(type='REAL', default=None), 'posZ': ColumnData(type='REAL', default=None), 'type': ColumnData(type='TEXT', default=None)}
class schrodinger.application.matsci.kmc.SegmentsTable(filename)

Bases: schrodinger.application.matsci.kmc.SitesMixin, schrodinger.application.matsci.kmc.Table

The segments table

TABLE_NAME = 'segments'
EANION = 'eAnion'
ENEUTRAL = 'eNeutral'
ECATION = 'eCation'
COLUMNS = {'UcCnNe': ColumnData(type='REAL', default=0), 'UcCnNh': ColumnData(type='REAL', default=0), 'UcNcCe': ColumnData(type='REAL', default=0), 'UcNcCh': ColumnData(type='REAL', default=0), 'UnCnNe': ColumnData(type='REAL', default=0), 'UnCnNh': ColumnData(type='REAL', default=0), 'eAnion': ColumnData(type='REAL', default=0), 'eCation': ColumnData(type='REAL', default=0), 'eNeutral': ColumnData(type='REAL', default=0), 'frame': ColumnData(type='INT', default=0), 'has_e': ColumnData(type='INT', default=0), 'has_h': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'mol': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'occPe': ColumnData(type='REAL', default=-1), 'occPh': ColumnData(type='REAL', default=-1), 'posX': ColumnData(type='REAL', default=None), 'posY': ColumnData(type='REAL', default=None), 'posZ': ColumnData(type='REAL', default=None), 'top': ColumnData(type='INT', default=0), 'type': ColumnData(type='TEXT', default=None)}
addRow(molecule, stypes)

Add a row

Parameters
  • molecule (schrodinger.structure._StructureMolecule) – The molecule object to add a row for

  • stypes (dict) – Keys are segment names (atom pdbres names), values are the index of that segment

class schrodinger.application.matsci.kmc.SegmentTypesTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The segmentTypes table

TABLE_NAME = 'segmentTypes'
BASIS = 'basis'
ORBFILE = 'orbfile'
TORBNRS = 'torbnrs'
COORDFILE = 'coordfile'
CANRIGID = 'canRigid'
COLUMNS = {'basis': ColumnData(type='TEXT', default='noname'), 'canRigid': ColumnData(type='INT', default=0), 'coordfile': ColumnData(type='TEXT', default='nofile'), 'frame': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'orbfile': ColumnData(type='TEXT', default='nofile'), 'top': ColumnData(type='INT', default=0), 'torbnrs': ColumnData(type='TEXT', default='NOT_USED')}
addRow(stype, index)

Add a row

Parameters
  • stype (str) – The segment type name (should be an atom.pdbres name)

  • index (int) – The segment type index

class schrodinger.application.matsci.kmc.FragmentsTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The fragments table

TABLE_NAME = 'fragments'
SYMMETRY = 'symmetry'
LEG1 = 'leg1'
LEG2 = 'leg2'
LEG3 = 'leg3'
COLUMNS = {'frame': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'leg1': ColumnData(type='INT', default=1), 'leg2': ColumnData(type='INT', default=2), 'leg3': ColumnData(type='INT', default=3), 'mol': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'posX': ColumnData(type='REAL', default=None), 'posY': ColumnData(type='REAL', default=None), 'posZ': ColumnData(type='REAL', default=None), 'seg': ColumnData(type='INT', default=None), 'symmetry': ColumnData(type='INT', default=-1), 'top': ColumnData(type='INT', default=0), 'type': ColumnData(type='TEXT', default=None)}
addRow(molecule)

Add a row

Parameters

molecule (schrodinger.structure._StructureMolecule) – The molecule object to add a row for

class schrodinger.application.matsci.kmc.AtomsTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The atoms table

TABLE_NAME = 'atoms'
FRAG = 'frag'
RESNR = 'resnr'
RESNAME = 'resname'
WEIGHT = 'weight'
ELEMENT = 'element'
QMID = 'qmid'
QMPOSX = 'qmPosX'
QMPOSY = 'qmPosY'
QMPOSZ = 'qmPosZ'
COLUMNS = {'element': ColumnData(type='TEXT', default=None), 'frag': ColumnData(type='INT', default=None), 'frame': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'mol': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'posX': ColumnData(type='REAL', default=None), 'posY': ColumnData(type='REAL', default=None), 'posZ': ColumnData(type='REAL', default=None), 'qmPosX': ColumnData(type='REAL', default=0.0), 'qmPosY': ColumnData(type='REAL', default=0.0), 'qmPosZ': ColumnData(type='REAL', default=0.0), 'qmid': ColumnData(type='INT', default=0), 'resname': ColumnData(type='TEXT', default=None), 'resnr': ColumnData(type='INT', default=1), 'seg': ColumnData(type='INT', default=None), 'top': ColumnData(type='INT', default=0), 'type': ColumnData(type='INT', default=None), 'weight': ColumnData(type='REAL', default=None)}
addRow(atom)

Add a row

Parameters

atom (structure.Structure._StructureAtom) – The atom to add a row for

class schrodinger.application.matsci.kmc.PairsMixin

Bases: object

Mixin for Matsci and VOTCA pair tables

DRX = 'drx'
DRY = 'dry'
DRZ = 'drz'
COM_DRX = 'com_drx'
COM_DRY = 'com_dry'
COM_DRZ = 'com_drz'
PERIODIC_Z = 'periodic_z'
RATE12E = 'rate12e'
RATE21E = 'rate21e'
RATE12H = 'rate12h'
RATE21H = 'rate21h'
addRow(index, dimer, struct)

Add a row to the table

Parameters
classmethod setRowValues(mols, val_dict, cursor)

Set the values of columns in the row for the given pair of molecules

Parameters
  • mols (iterable) – The two mol numbers involved in this pair

  • val_dict (dict) – Dict mapping column names to their values

  • cursor (sqlite3.Cursor) – The cursor to use

Raises

RuntimeError – If value has spaces

class schrodinger.application.matsci.kmc.PairsTable(filename)

Bases: schrodinger.application.matsci.kmc.PairsMixin, schrodinger.application.matsci.kmc.Table

The votca pairs table

TABLE_NAME = 'pairs'
SEG1 = 'seg1'
SEG2 = 'seg2'
SITE1 = 'seg1'
SITE2 = 'seg2'
LOE = 'lOe'
LOH = 'lOh'
HAS_E = 'has_e'
HAS_H = 'has_h'
JEFF2E = 'Jeff2e'
JEFF2H = 'Jeff2h'
COLUMNS = {'Jeff2e': ColumnData(type='REAL', default=0), 'Jeff2h': ColumnData(type='REAL', default=0), 'com_drx': ColumnData(type='REAL', default=None), 'com_dry': ColumnData(type='REAL', default=None), 'com_drz': ColumnData(type='REAL', default=None), 'drx': ColumnData(type='REAL', default=None), 'dry': ColumnData(type='REAL', default=None), 'drz': ColumnData(type='REAL', default=None), 'frame': ColumnData(type='INT', default=0), 'has_e': ColumnData(type='INT', default=0), 'has_h': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'lOe': ColumnData(type='REAL', default=0), 'lOh': ColumnData(type='REAL', default=0), 'rate12e': ColumnData(type='REAL', default=0), 'rate12h': ColumnData(type='REAL', default=0), 'rate21e': ColumnData(type='REAL', default=0), 'rate21h': ColumnData(type='REAL', default=0), 'seg1': ColumnData(type='INT', default=None), 'seg2': ColumnData(type='INT', default=None), 'top': ColumnData(type='INT', default=0), 'type': ColumnData(type='INT', default=0)}
COUPLING_COLUMNS = {'electron': ['Jeff2e'], 'hole': ['Jeff2h']}
class schrodinger.application.matsci.kmc.SuperExchangeTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The superExchange table

Note: unused

TABLE_NAME = 'superExchange'
COLUMNS = {'frame': ColumnData(type='INT', default=0), 'top': ColumnData(type='INT', default=0), 'type': ColumnData(type='TEXT', default=None)}
class schrodinger.application.matsci.kmc.SchrodingerTable(filename)

Bases: schrodinger.application.matsci.kmc.Table

The schrodinger table. This contains Schrodinger-specific information and is not used by VOTCA

TABLE_NAME = 'schrodinger'
NULL_ALLOWED = True
MOLFORM = 'mol_formula'
VOLUME = 'pbc_volume_Ang3'
JOBID = 'jobid'
STRUCTURE_PATH = 'structure_path'
STRUCTURE_FILE = 'structure_file'
CONCENTRATIONS_FILE = 'concentrations_file'
PAIR_DISTANCE = 'pair_distance_Ang'
PAIR_TYPE = 'pair_type'
VERSION = 'version'
JUMPFILE = 'jumpfile'
JUMPSUMMARY = 'jumpsummary'
RUNTIME = 'runtime'
SEED = 'seed'
FIELDX = 'fieldX'
FIELDY = 'fieldY'
FIELDZ = 'fieldZ'
AVECTOR = 'a_vector'
BVECTOR = 'b_vector'
CVECTOR = 'c_vector'
TEMPERATURE = 'temperature'
RATEFILE = 'ratefile'
CARRIERTYPE = 'carriertype'
SITE_KEYWORDS = 'site_keywords'
FIX_SITE_KEYWORDS = 'site_fix_keywords'
MATSCI_ENGINE = 'matsci_engine'
AVERAGE_JEFF = 'average_jeff'
COLUMNS = {'a_vector': ColumnData(type='TEXT', default=None), 'average_jeff': ColumnData(type='INT', default=1), 'b_vector': ColumnData(type='TEXT', default=None), 'c_vector': ColumnData(type='TEXT', default=None), 'carriertype': ColumnData(type='TEXT', default=None), 'concentrations_file': ColumnData(type='TEXT', default=None), 'fieldX': ColumnData(type='REAL', default=None), 'fieldY': ColumnData(type='REAL', default=None), 'fieldZ': ColumnData(type='REAL', default=None), 'jobid': ColumnData(type='TEXT', default=None), 'jumpsummary': ColumnData(type='TEXT', default=None), 'matsci_engine': ColumnData(type='INT', default=0), 'mol_formula': ColumnData(type='TEXT', default=None), 'pair_distance_Ang': ColumnData(type='REAL', default=0.0), 'pair_type': ColumnData(type='REAL', default=None), 'pbc_volume_Ang3': ColumnData(type='REAL', default=0.0), 'ratefile': ColumnData(type='TEXT', default=None), 'runtime': ColumnData(type='REAL', default=None), 'seed': ColumnData(type='INT', default=None), 'site_fix_keywords': ColumnData(type='TEXT', default=None), 'site_keywords': ColumnData(type='TEXT', default=None), 'structure_file': ColumnData(type='TEXT', default=None), 'structure_path': ColumnData(type='TEXT', default=None), 'temperature': ColumnData(type='REAL', default=None), 'version': ColumnData(type='REAL', default=0.92)}
addRow(struct)

Add a row

Parameters

struct (schrodinger.structure.Structure) – The structure for the database

class schrodinger.application.matsci.kmc.BaseDatabaseManager(struct, filename)

Bases: object

Manage initialization and filling of SQL database tables

SITES_TABLE = None
PAIRS_TABLE = None
class Cursor(manager)

Bases: schrodinger.application.matsci.kmc.SQLCursor

Context manager for obtaining a cursor object for use by the tables. Note that when adding many rows it saves a huge amount of time to create the cursor once and then close it when finished rather than create/close a cursor for each row.

__init__(manager)
__init__(struct, filename)

Create a BaseDatabaseManager instance

Parameters
fillSchrodinger()

Fill the schrodinger table

fillPairs(dist, pair_type='heavy')

Find all dimers in the given structure based on the normal Schrodinger dimer finding algorithm. Add all found dimers to the given SQL file.

Parameters
  • dist (float) – The distance threshold for defining dimers

  • pair_type (str) – Either SQL_HEAVY (heavy atom distances only) or SQL_ALL (all atoms are considered when determining pair distance)

Return type

int

Returns

The number of dimers found

initializeDatabase()

Should be overwritten by child classes to create the tables

class schrodinger.application.matsci.kmc.VotcaDatabaseManager(struct, filename)

Bases: schrodinger.application.matsci.kmc.BaseDatabaseManager

Database manager for votca engine

TABLE_CLASSES = (<class 'schrodinger.application.matsci.kmc.FramesTable'>, <class 'schrodinger.application.matsci.kmc.PairsTable'>, <class 'schrodinger.application.matsci.kmc.MoleculesTable'>, <class 'schrodinger.application.matsci.kmc.SegmentsTable'>, <class 'schrodinger.application.matsci.kmc.FragmentsTable'>, <class 'schrodinger.application.matsci.kmc.AtomsTable'>, <class 'schrodinger.application.matsci.kmc.SegmentTypesTable'>, <class 'schrodinger.application.matsci.kmc.SchrodingerTable'>, <class 'schrodinger.application.matsci.kmc.SuperExchangeTable'>)
SITES_TABLE

alias of schrodinger.application.matsci.kmc.SegmentsTable

PAIRS_TABLE

alias of schrodinger.application.matsci.kmc.PairsTable

initializeDatabase()

Create all the tables and fill all but the pairs table with initial data

fillAtoms()

Fill the atoms table

fillFragments()

Fill the fragments table

fillFrames()

Fill the frames table

fillMolecules()

Fill the molecules table

fillSegmentTypes()

Fill the segmentTypes table

fillSegments()

Fill the segments table

Raises

RuntimeError – If fillSegmentTypes has not been called yet

schrodinger.application.matsci.kmc.sql_command(cursor, cmd)

Perform the given command without closing the cursor or saving the results to the database

Parameters
  • cursor (sqlite3.Cursor) – The cursor used

  • cmd (str) – The SQL command to perform

Return type

bool

Returns

True if the command executed, False if the command raised a no such table error

Raises

sqlite3.OperationalError – in unknown circumstances

schrodinger.application.matsci.kmc.table_rows(db_path, table, orderby=None)

Generator for all the rows in a specific table of the database

Parameters
  • db_path (str or pathlib.Path) – The path to the database

  • table (str) – The name of the table to get the rows for

Return type

sqlite3.Row

Returns

Yields each row in the table

schrodinger.application.matsci.kmc.delete_all_rows(db_path, table)

Delete all the rows in this table

Parameters
  • db_path (str or pathlib.Path) – The path to the database

  • table (str) – The name of the table to get the rows for

schrodinger.application.matsci.kmc.is_no_table_error(exc)

Detect if this exception is due to the requested table not existing

Parameters

exc (Exception) – The Exception to check

Return type

bool

Returns

Whether this exception is for a missing table

schrodinger.application.matsci.kmc.add_schrodinger_column(db_path, name)

Add a column to the schrodinger table. This may be needed if the SQL file was created with an older version that didn’t include this column

Parameters
  • db_path (str or pathlib.Path) – The path to the SQL file

  • name (str) – The name of the column, must be a key in SchrodingerTable.COLUMNS

Raises
  • DuplicateColumnError – If the column already exists

  • KeyError – If name is not a SchrodingerTable column name

exception schrodinger.application.matsci.kmc.DuplicateColumnError

Bases: sqlite3.OperationalError

Specific to trying to ADD COLUMN when one already exists

schrodinger.application.matsci.kmc.add_column(cursor, table_name, col_name, extra_sql=None)

Add a column to a given database using the given cursor.

Parameters
  • cursor (sqlite3.Cursor) – The cursor to use for database read/writes

  • table_name (str) – The name of the table to add a column to

  • col_name (str) – The name of the new column

  • extra_sql (str or None) – Optional additional text to add to the sql command, for example, “REAL DEFAULT ‘0.0’”

Raises

DuplicateColumnError – If the column already exists in the table

schrodinger.application.matsci.kmc.get_dimer_com_sep(dimer, struct)

Get the centroid separation vector for a dimer taking into account periodic boundaries.

Parameters
Return type

tuple(float, float, float)

Returns

the x, y, and z components of the centroid separation between the dimer molecules, taking into account PBC.

schrodinger.application.matsci.kmc.pairs_table_has_com(db_path)

Check if the pairs table has COM distance columns or not. This is useful for validating both GUI and driver and as a check before calling add_com_to_pairs_table.

Parameters

db_path (str) – The path to the SQL file

Return type

bool

Returns

True if the pairs table in the db already has COM_DX,Y,Z cols, otherwise False

schrodinger.application.matsci.kmc.matsci_pairs_table_has_periodic_z(db_path)

Check if the pairs table has PERIODIC_Z column or not. This is useful for validating / detecting outdated database.

Parameters

db_path (str) – The path to the SQL file

Return type

bool

Returns

True if the pairs table in the db has PERIODIC_Z col, otherwise False

schrodinger.application.matsci.kmc.missing_periodic_z_msg(db_path)

Get the error message to send to the user about missing PERIODIC_Z column.

Parameters

db_path – The path to the SQL file

Return type

str

Returns

The message to send to the user about missing PERIODIC_Z column.

schrodinger.application.matsci.kmc.add_com_to_pairs_table(db_path, struct=None)

Add center of mass (COM) distance to pairs table.

This function can work in one of two ways: provide a struct if one is available, or if a struct is not available, set struct=None and the necessary data will be gathered if available from the existing database tables.

Parameters
  • db_path (str) – The path to the SQL file

  • struct (Structure) – the structure with associated PBC and molecule information. If None, the PBC and molecule information will be obtained from the database, if it is available.

schrodinger.application.matsci.kmc.set_schrodinger_db_value(db_path, name, value)

Set the value of the given column in the Schrodinger table.

Parameters
  • db_path (str or pathlib.Path) – The path to the SQL file

  • name (str) – The name of the column, must be a key in SchrodingerTable.COLUMNS

  • value – The value to put into the database. The type of the parameter should be consistent with the expected type for that column.

schrodinger.application.matsci.kmc.store_schrodinger_job_props(db_path, mae_name, struct)

Store Schrodinger information about the current job in the database

Parameters
  • db_path (str or pathlib.Path) – The path to the SQL file

  • mae_name (str) – The name of the Maestro file that will hold the structure

  • struct (schrodinger.structure.Structure) – The structure to add corresponding job info props to

schrodinger.application.matsci.kmc.get_schrodinger_db_value(db_path, name)

Get the value for the given column from the Schrodinger table in the database

Parameters
  • db_path (str or pathlib.Path) – The path to the SQL file

  • name (str) – The name of the column to get the data from

Return type

variable or None

Returns

The value for the given column in the Schrodinger table, or None if no such table exists or no such column exists

schrodinger.application.matsci.kmc.get_db_structure_path(db_path, existence_check=True)

Get the path to the structure that created this database

Parameters
  • db_path (str or pathlib.Path) – The path to the SQL file

  • existence_check (bool) – If True, return None if the path in the database does not point to an existing file. If False, return the path regardless of whether the file exists.

Return type

pathlib.Path or None

Returns

The Path to the structure file, or None if no path is found in the database or existence_check=True and the file does not exist

schrodinger.application.matsci.kmc.add_pairs_to_database(struct, path, dist, pair_type='heavy')

Find all dimers in the given structure based on the normal Schrodinger dimer finding algorithm. Add all found dimers to the given VOTCA SQL file.

Parameters
  • struct (schrodinger.structure.Structure) – The structure with the pairs

  • path (str) – The path to the SQL database

  • dist (float) – The distance threshold for defining dimers

  • pair_type (str) – Either SQL_HEAVY (heavy atom distances only) or SQL_ALL (all atoms are considered when determining pair distance)

Return type

int

Returns

The number of dimers found

schrodinger.application.matsci.kmc.get_pairs_from_database(db_path)

Get the pairs from the database

Parameters

db_path (str or pathlib.Path) – The path to the SQL file

Return type

list

Returns

Each item of the list is a schrodinger.application.matsci.clusterstruct.Dimer object. The list is empty if the pairs table has not been populated. Note that the Dimer objects will not have set the home_atom or neighbor_atom properties of the neighbor_info property.

schrodinger.application.matsci.kmc.has_pair_data(db_path)

Check if the database has pair data

Parameters

db_path (str or pathlib.Path) – The path to the database

Return type

bool or str

Returns

If no data, False. If data, the distance type used to find pairs - either SQL_HEAVY or SQL_ALL

schrodinger.application.matsci.kmc.get_pair_info(db_path)

Get the parameters used to determine the existing pairs in the database

Parameters

db_path (str or pathlib.Path) – The path to the database

Return type

(str, float) or None

Returns

The type of distance used to find pairs (SQL_HEAVY or SQL_ALL) and the distance cutoff for pairs. None is returned if no pair data exists.

schrodinger.application.matsci.kmc.is_matsci_engine_db(db_path)

Get whether the database is made for the internal engine. Returns False if the corresponding column doesn’t exist in the database (older versions)

Parameters

db_path (str) – The path to database file

Return bool

Whether the database is for internal engine

schrodinger.application.matsci.kmc.get_database_manager_class(db_path=None, is_matsci=None)

Get the database manager class using either the database path or the explicit is_matsci bool

Parameters
  • db_path (str) – The path to an existing database file

  • is_matsci (bool) – Whether the database will be for matsci engine

Return BaseDatabaseManager

either MatSciDatabaseManager or VotcaDatabaseManager

schrodinger.application.matsci.kmc.get_sites_table(db_path)

Get the sites table class for the sql file

Parameters

db_path (str) – The path to sql file

Return type

SegmentsTable or MatSciSitesTable

Returns

The sites table class

schrodinger.application.matsci.kmc.get_pairs_table(db_path)

Get the pairs table class for the sql file

Parameters

db_path (str) – The path to sql file

Return type

PairsTable or MatSciPairsTable

Returns

The pairs table class

schrodinger.application.matsci.kmc.find_missing_coupling_data(path, charge)

Find any pair coupings that are 0

Parameters
  • path (str) – The path to the database file

  • charge (str) – Either HOLE or ELECTRON

Return type

list

Returns

Each item is a tuple with the molecule numbers of the two molecules involved in the missing coupling term.

schrodinger.application.matsci.kmc.find_missing_site_energies(path, charge)

Find any segment that has any site energy property equal to 0

Parameters
  • path (str) – The path to the database file

  • charge (str) – Either HOLE or ELECTRON

Return type

list

Returns

Each item is the integer SQID (which translates to molecule number) of any segment with missing site energy information

schrodinger.application.matsci.kmc.copy_rates_csv_to_db(db_path, e12_csv=None, e21_csv=None, h12_csv=None, h21_csv=None)

Copy rates from formatted rates csv file from ML workflow to sql database

Parameters
  • db_path (str) – the path to the database sql file

  • e12_csv (Optional[str]) – the path to the electron 12 rate csv file

  • e21_csv (Optional[str]) – the path to the electron 21 rate csv file

  • h12_csv (Optional[str]) – the path to the hole 12 rate csv file

  • h21_csv (Optional[str]) – the path to the hole 21 rate csv file

schrodinger.application.matsci.kmc.get_h_pair_rates_from_database(db_path)

Get the hole hopping rates from the database

Parameters

db_path (str or pathlib.Path) – The path to the SQL file

Return type

dict (key: tuple(int,int). val: float)

Returns

Dictionary where the key is the directed pair of site indices (source site, destination site) the val is the hole hopping rate in that direction

schrodinger.application.matsci.kmc.get_e_pair_rates_from_database(db_path)

Get the electron hopping rates from the database. Note: site indexes here are 1-indexed, taken directly from the database.

Parameters

db_path (str or pathlib.Path) – The path to the SQL file

Return type

dict (key: tuple(int,int). val: float)

Returns

Dictionary where the key is the directed pair of site indices (source site, destination site), the val is the electron hopping rate in that direction

schrodinger.application.matsci.kmc.get_pair_rates_from_database(db_path, particle_type='h')

Get the hopping rates from the database. Note: site indexes here are 1-indexed, taken directly from the database.

Parameters
  • db_path (str or pathlib.Path) – The path to the SQL file

  • particle_type (str) – H_ENDING for hole, or E_ENDING for electron

Return type

dict (key: tuple(int,int). val: float)

Returns

Dictionary where the key is the directed pair of site indices (source site, destination site), the val is the hopping rate in that direction

schrodinger.application.matsci.kmc.copy_sql_data(source, destination, table, columns)

Copy the column from table in the source database to the destination database

Parameters
  • source (str or pathlib.path) – the path to the source database

  • destination (str or pathlib.path) – the path to the destination database

  • table (str) – The name of the table to copy from

  • columns (list) – A list of column names to copy

Raises
  • IndexError – If the two databases do not have the same number of rows

  • DuplicateColumnError – If new_cals=True is used but the cols already exist in the destination table

schrodinger.application.matsci.kmc.set_column_constant(db_path, table, column, constant)

Set all rows of a given column to the value constant.

Caution: this loses all current data in that column.

Parameters
  • db_path (str) – The path to the SQL file

  • table (str) – The name of the table to copy from

  • column (str) – The name of the column

  • constant (float or str) – The value to set

exception schrodinger.application.matsci.kmc.SQLCreationError

Bases: Exception

Raised if an issue occurs when creating the database

schrodinger.application.matsci.kmc.generate_votca_database(struct, backend=None, matsci_engine=False)

Create a VOTCA SQL database and include data on species and pairs

Note that VOTCA requires the segments in a system be ordered such that all segments of the same type appear together in order. This function returns the reordered structure used to create the database. (segments=molecules)

Parameters
  • struct (schrodinger.structure.Structure) – The structure to create a database for

  • backend (scschrodigner.job.jobcontrol._Backend) – The backend if one exists

  • matsci_engine (bool) – Whether the database will be for the internal engine

Return type

str

Returns

The name of the sql file that was created

Raises

SQLCreationError – If the sql file can’t be created

class schrodinger.application.matsci.kmc.MatSciSitesTable(filename)

Bases: schrodinger.application.matsci.kmc.SitesMixin, schrodinger.application.matsci.kmc.Table

Sites table for the internal engine

TABLE_NAME = 'sites'
OCCP_SING = 'occP_singlet'
OCCP_TRIP = 'occP_triplet'
INJECTS_E = 'injects_e'
INJECTS_H = 'injects_h'
E_INJECTIONS = 'e_injections'
H_INJECTIONS = 'h_injections'
E_ANNIHILIATIONS = 'e_annihilations'
H_ANNIHILIATIONS = 'h_annihilations'
RAD_DECAYS = 'radiative_decays'
NONRAD_DECAYS = 'nonradiative_decays'
CURRENT_MAGNITUDE_E = 'current_magnitude_e'
CURRENT_X_E = 'current_x_e'
CURRENT_Y_E = 'current_y_e'
CURRENT_Z_E = 'current_z_e'
CURRENT_MAGNITUDE_H = 'current_magnitude_h'
CURRENT_X_H = 'current_x_h'
CURRENT_Y_H = 'current_y_h'
CURRENT_Z_H = 'current_z_h'
COLUMNS = {'UcCnNe': ColumnData(type='REAL', default=0), 'UcCnNh': ColumnData(type='REAL', default=0), 'UcNcCe': ColumnData(type='REAL', default=0), 'UcNcCh': ColumnData(type='REAL', default=0), 'UnCnNe': ColumnData(type='REAL', default=0), 'UnCnNh': ColumnData(type='REAL', default=0), 'current_magnitude_e': ColumnData(type='REAL', default=0), 'current_magnitude_h': ColumnData(type='REAL', default=0), 'current_x_e': ColumnData(type='REAL', default=0), 'current_x_h': ColumnData(type='REAL', default=0), 'current_y_e': ColumnData(type='REAL', default=0), 'current_y_h': ColumnData(type='REAL', default=0), 'current_z_e': ColumnData(type='REAL', default=0), 'current_z_h': ColumnData(type='REAL', default=0), 'e_annihilations': ColumnData(type='INT', default=0), 'e_injections': ColumnData(type='INT', default=0), 'h_annihilations': ColumnData(type='INT', default=0), 'h_injections': ColumnData(type='INT', default=0), 'has_e': ColumnData(type='INT', default=0), 'has_h': ColumnData(type='INT', default=0), 'id': ColumnData(type='INT', default=None), 'injects_e': ColumnData(type='INT', default=0), 'injects_h': ColumnData(type='INT', default=0), 'mol': ColumnData(type='INT', default=None), 'name': ColumnData(type='TEXT', default=None), 'nonradiative_decays': ColumnData(type='INT', default=0), 'occP_singlet': ColumnData(type='REAL', default=-1), 'occP_triplet': ColumnData(type='REAL', default=-1), 'occPe': ColumnData(type='REAL', default=-1), 'occPh': ColumnData(type='REAL', default=-1), 'posX': ColumnData(type='REAL', default=None), 'posY': ColumnData(type='REAL', default=None), 'posZ': ColumnData(type='REAL', default=None), 'radiative_decays': ColumnData(type='INT', default=0), 'type': ColumnData(type='TEXT', default=None)}
addRow(molecule)

Add a row

Parameters

molecule (schrodinger.structure._StructureMolecule) – The molecule object to add a row for

class schrodinger.application.matsci.kmc.MatSciPairsTable(filename)

Bases: schrodinger.application.matsci.kmc.PairsMixin, schrodinger.application.matsci.kmc.Table

Pairs table for the internal engine

TABLE_NAME = 'pairs'
SITE1 = 'site1'
SITE2 = 'site2'
JEFF2_12E = 'Jeff2_12e'
JEFF2_21E = 'Jeff2_21e'
JEFF2_12H = 'Jeff2_12h'
JEFF2_21H = 'Jeff2_21h'
LAMBDA_12E = 'Lambda_12e'
LAMBDA_21E = 'Lambda_21e'
LAMBDA_12H = 'Lambda_12h'
LAMBDA_21H = 'Lambda_21h'
DELTAE_12E = 'DeltaE_12e'
DELTAE_21E = 'DeltaE_21e'
DELTAE_12H = 'DeltaE_12h'
DELTAE_21H = 'DeltaE_21h'
JUMPS_12E = 'Jumps_12e'
JUMPS_21E = 'Jumps_21e'
JUMPS_12H = 'Jumps_12h'
JUMPS_21H = 'Jumps_21h'
COUPLING_COLUMNS = {'electron': ['Jeff2_12e', 'Jeff2_21e'], 'hole': ['Jeff2_12h', 'Jeff2_21h']}
LAMBDA_COLUMNS = {'electron': ['Lambda_12e', 'Lambda_21e'], 'hole': ['Lambda_12h', 'Lambda_21h']}
DELTAE_COLUMNS = {'electron': ['DeltaE_12e', 'DeltaE_21e'], 'hole': ['DeltaE_12h', 'DeltaE_21h']}
JUMP_COLUMNS = {'electron': ['Jumps_12e', 'Jumps_21e'], 'hole': ['Jumps_12h', 'Jumps_21h']}
RATE_COLUMNS = {'electron': ['rate12e', 'rate21e'], 'hole': ['rate12h', 'rate21h']}
COLUMNS = {'DeltaE_12e': ColumnData(type='REAL', default=0), 'DeltaE_12h': ColumnData(type='REAL', default=0), 'DeltaE_21e': ColumnData(type='REAL', default=0), 'DeltaE_21h': ColumnData(type='REAL', default=0), 'Jeff2_12e': ColumnData(type='REAL', default=0), 'Jeff2_12h': ColumnData(type='REAL', default=0), 'Jeff2_21e': ColumnData(type='REAL', default=0), 'Jeff2_21h': ColumnData(type='REAL', default=0), 'Jumps_12e': ColumnData(type='INT', default=0), 'Jumps_12h': ColumnData(type='INT', default=0), 'Jumps_21e': ColumnData(type='INT', default=0), 'Jumps_21h': ColumnData(type='INT', default=0), 'Lambda_12e': ColumnData(type='REAL', default=0), 'Lambda_12h': ColumnData(type='REAL', default=0), 'Lambda_21e': ColumnData(type='REAL', default=0), 'Lambda_21h': ColumnData(type='REAL', default=0), 'com_drx': ColumnData(type='REAL', default=None), 'com_dry': ColumnData(type='REAL', default=None), 'com_drz': ColumnData(type='REAL', default=None), 'drx': ColumnData(type='REAL', default=None), 'dry': ColumnData(type='REAL', default=None), 'drz': ColumnData(type='REAL', default=None), 'id': ColumnData(type='INT', default=None), 'periodic_z': ColumnData(type='INT', default=None), 'rate12e': ColumnData(type='REAL', default=0), 'rate12h': ColumnData(type='REAL', default=0), 'rate21e': ColumnData(type='REAL', default=0), 'rate21h': ColumnData(type='REAL', default=0), 'site1': ColumnData(type='INT', default=None), 'site2': ColumnData(type='INT', default=None)}
class schrodinger.application.matsci.kmc.MatSciDatabaseManager(struct, filename)

Bases: schrodinger.application.matsci.kmc.BaseDatabaseManager

Database manager for the internal database

TABLE_CLASSES = (<class 'schrodinger.application.matsci.kmc.MatSciSitesTable'>, <class 'schrodinger.application.matsci.kmc.MatSciPairsTable'>, <class 'schrodinger.application.matsci.kmc.SchrodingerTable'>)
SITES_TABLE

alias of schrodinger.application.matsci.kmc.MatSciSitesTable

PAIRS_TABLE

alias of schrodinger.application.matsci.kmc.MatSciPairsTable

initializeDatabase()

Create all the tables and fill all but the pairs table with initial data

fillSites()

Fill the sites table

schrodinger.application.matsci.kmc.add_charge_flag(parser)

Add the charge flag to the parser

Parameters

parser (parserutils.DriverParser or argparse._ArgumentGroup) – The parser or argument group to add the flag to

schrodinger.application.matsci.kmc.add_kmc_flags(parser)

Add KMC flags to the parser

Parameters

parser (parserutils.DriverParser or argparse._ArgumentGroup) – The parser or argument group to add the flag to

schrodinger.application.matsci.kmc.type_field(value)

Type the field command line parameter

Parameters

value (str) – The command line field parameter

Return type

list of tuple

Returns

Each item of the list is (X, Y, Z) field strengths in MV/m for one field. Field strengths are floats.

Raises

argparse.ArgumentTypeError – If the argument cannot be converted to a length 3 list of floats

schrodinger.application.matsci.kmc.get_sql_output_name(jobname)

Get the name of the SQL file that will be created

Parameters

jobname (str) – The name of the job

Return type

str

Returns

The name the output sql file will have

schrodinger.application.matsci.kmc.get_db_table_length(db_path, table)

Get the number of rows in the given table

Parameters
  • db_path (str) – The path to the database

  • table (str) – The name of the table

Return int

The number of rows

schrodinger.application.matsci.kmc.form_set_val_string(val_dict)

Create the string to set multiple values in a sql row

Parameters

val_dict (dict) – Dict mapping column names to their values

Return str

The string to put in sql comand

schrodinger.application.matsci.kmc.get_num_missing_data(sql_file, charge)

Get the number of missing sites and coupling data

Parameters
  • sql_file (str) – The path to the sql file

  • charge (str) – The charge to check for

Return type

tuple of int

Returns

The number of missing sites and couplings