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 forcentroid (bool) – Include information about the molecule’s centroid. If False, all centroid information will be 0.
- Return type
- 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 forstypes (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
index (int) – The index of this pair
dimer (
schrodinger.application.matsci.clusterstruct.Dimer
) – The Dimer object for this row
- 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
struct (
schrodinger.structure.Structure
) – The structure to find dimers infilename (str) – The name of the SQL file to create
- 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¶
- PAIRS_TABLE¶
- 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 filename (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
dimer (
schrodinger.application.matsci.clusterstruct.Dimer
) – The Dimer object for this rowstruct (
schrodinger.structure.Structure
) – The structure associated with this dimer
- 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 filename (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 filemae_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 filename (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 fileexistence_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 pairspath (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
- 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
- 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
orELECTRON
- 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
orELECTRON
- 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 fileparticle_type (str) –
H_ENDING
for hole, orE_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 forbackend (
scschrodigner.job.jobcontrol._Backend
) – The backend if one existsmatsci_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
orargparse._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
orargparse._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