Skip to content

GitLab

Commit 80cc954a authored by peastman's avatar peastman
Browse files

Merge pull request #1228 from rmcgibbo/docstrings 

Better docstrings
parents d137b536 1db3314e
Hide whitespace changes
Inline Side-by-side
Showing with 1162 additions and 692 deletions
wrappers/python/simtk/openmm/app/charmmpsffile.py
View file @ 80cc954a
......@@ -116,12 +116,8 @@ def _strip_optunit(thing, unit):
_resre = re.compile(r'(\d+)([a-zA-Z]*)')
class CharmmPsfFile(object):
"""
A chemical structure instantiated from CHARMM files.
"""A chemical structure instantiated from CHARMM files.
Example:
>>> cs = CharmmPsfFile("testfiles/test.psf")
This structure has numerous attributes that are lists of the elements of
this structure, including atoms, bonds, torsions, etc. The attributes are
- residue_list
......@@ -138,13 +134,14 @@ class CharmmPsfFile(object):
Additional attribute is available if a CharmmParameterSet is loaded into
this structure.
- urey_bradley_list
The lengths of each of these lists gives the pointers (e.g., natom, nres,
etc.)
Example:
Examples
--------
>>> cs = CharmmPsfFile("testfiles/test.psf")
>>> len(cs.atom_list)
33
......@@ -163,19 +160,21 @@ class CharmmPsfFile(object):
CMAP_FORCE_GROUP = 5
NONBONDED_FORCE_GROUP = 6
GB_FORCE_GROUP = 6
@_catchindexerror
def __init__(self, psf_name):
"""
Opens and parses a PSF file, then instantiates a CharmmPsfFile
"""Opens and parses a PSF file, then instantiates a CharmmPsfFile
instance from the data.
Parameters:
psf_name (str) : Name of the PSF file (it must exist)
Exceptions Raised:
IOError : If file "psf_name" does not exist
CharmmPSFError: If any parsing errors are encountered
Parameters
----------
psf_name : str
Name of the PSF file (it must exist)
Raises
------
IOError : If file "psf_name" does not exist
CharmmPSFError: If any parsing errors are encountered
"""
conv = CharmmPsfFile._convert
# Make sure the file exists
......@@ -388,14 +387,17 @@ class CharmmPsfFile(object):
@staticmethod
def _convert(string, type, message):
"""
Converts a string to a specific type, making sure to raise
"""Converts a string to a specific type, making sure to raise
CharmmPSFError with the given message in the event of a failure.
Parameters:
- string (str) : Input string to process
- type (type) : Type of data to convert to
- message (str) : Error message to put in exception if failed
Parameters
----------
string : str
Input string to process
type : type
Type of data to convert to
message : str
Error message to put in exception if failed
"""
try:
return type(string)
......@@ -405,23 +407,24 @@ class CharmmPsfFile(object):
@staticmethod
def _parse_psf_section(psf):
"""
This method parses a section of the PSF file
Parameters:
- psf (CharmmFile) : Open file that is pointing to the first line
of the section that is to be parsed
Returns:
(title, pointers, data)
- title (str) : The label of the PSF section we are parsing
- pointers (int/tuple of ints) : If one pointer is set, pointers is
simply the integer that is value of that pointer. Otherwise
it is a tuple with every pointer value defined in the first
line
- data (list) : A list of all data in the parsed section converted
to `dtype'
"""This method parses a section of the PSF file
Parameters
----------
psf : CharmmFile
Open file that is pointing to the first line of the section
that is to be parsed
Returns
--------
str
The label of the PSF section we are parsing
int/tuple of ints
If one pointer is set, pointers is simply the integer that is
value of that pointer. Otherwise it is a tuple with every pointer
value defined in the first line
list
A list of all data in the parsed section converted to `dtype'
"""
conv = CharmmPsfFile._convert
line = psf.readline()
......@@ -462,25 +465,25 @@ class CharmmPsfFile(object):
return title, pointers, data
def loadParameters(self, parmset):
"""
Loads parameters from a parameter set that was loaded via CHARMM RTF,
"""Loads parameters from a parameter set that was loaded via CHARMM RTF,
PAR, and STR files.
Parameters:
- parmset (CharmmParameterSet) : List of all parameters
Notes:
- If any parameters that are necessary cannot be found, a
MissingParameter exception is raised.
- If any dihedral or improper parameters cannot be found, I will try
inserting wildcards (at either end for dihedrals and as the two
central atoms in impropers) and see if that matches. Wild-cards
will apply ONLY if specific parameters cannot be found.
- This method will expand the dihedral_parameter_list attribute by
adding a separate Dihedral object for each term for types that
have a multi-term expansion
Parameters
----------
parmset : CharmmParameterSet
List of all parameters
Notes
-----
- If any parameters that are necessary cannot be found, a
MissingParameter exception is raised.
- If any dihedral or improper parameters cannot be found, I will try
inserting wildcards (at either end for dihedrals and as the two
central atoms in impropers) and see if that matches. Wild-cards
will apply ONLY if specific parameters cannot be found.
- This method will expand the dihedral_parameter_list attribute by
adding a separate Dihedral object for each term for types that
have a multi-term expansion
"""
# First load the atom types
types_are_int = False
......@@ -588,13 +591,22 @@ class CharmmPsfFile(object):
def setBox(self, a, b, c, alpha=90.0*u.degrees, beta=90.0*u.degrees,
gamma=90.0*u.degrees):
"""
Sets the periodic box boundary conditions.
Parameters:
- a, b, c (floats) : Lengths of the periodic cell
- alpha, beta, gamma (floats, optional) : Angles between the
periodic cell vectors.
"""Sets the periodic box boundary conditions.
Parameters
----------
a : length
Lengths of the periodic cell
b : length
Lengths of the periodic cell
c : length
Lengths of the periodic cell
alpha : floats, optional
Angles between the periodic cell vectors.
beta : floats, optional
Angles between the periodic cell vectors.
gamma : floats, optional
Angles between the periodic cell vectors.
"""
try:
# Since we are setting the box, delete the cached box lengths if we
......@@ -620,7 +632,7 @@ class CharmmPsfFile(object):
pass
# Cache the topology for easy returning later
self._topology = topology = Topology()
last_chain = None
last_residue = None
# Add each chain (separate 'system's) and residue
......@@ -752,52 +764,60 @@ class CharmmPsfFile(object):
ewaldErrorTolerance=0.0005,
flexibleConstraints=True,
verbose=False):
"""
Construct an OpenMM System representing the topology described by the
"""Construct an OpenMM System representing the topology described by the
prmtop file. You MUST have loaded a parameter set into this PSF before
calling createSystem. If not, AttributeError will be raised. ValueError
is raised for illegal input.
Parameters:
- params (CharmmParameterSet) The parameter set to use to parametrize
this molecule
- nonbondedMethod (object=NoCutoff) The method to use for nonbonded
interactions. Allowed values are NoCutoff, CutoffNonPeriodic,
CutoffPeriodic, Ewald, or PME.
- nonbondedCutoff (distance=1*nanometer) The cutoff distance to use
for nonbonded interactions.
- switchDistance (distance=0*nanometer) The distance at which the
switching function is active for nonbonded interactions. If the
switchDistance evaluates to boolean False (if it is 0), no
switching function will be used. Illegal values will raise a
ValueError
- constraints (object=None) Specifies which bonds or angles should be
implemented with constraints. Allowed values are None, HBonds,
AllBonds, or HAngles.
- rigidWater (boolean=True) If true, water molecules will be fully
rigid regardless of the value passed for the constraints argument
- implicitSolvent (object=None) If not None, the implicit solvent
model to use. Allowed values are HCT, OBC1, OBC2, or GBn
- implicitSolventKappa (float=None): Debye screening parameter to
model salt concentrations in GB solvent.
- implicitSolventSaltConc (float=0.0*u.moles/u.liter): Salt
concentration for GB simulations. Converted to Debye length
`kappa'
- temperature (float=298.15*u.kelvin): Temperature used in the salt
concentration-to-kappa conversion for GB salt concentration term
- soluteDielectric (float=1.0) The solute dielectric constant to use
in the implicit solvent model.
- solventDielectric (float=78.5) The solvent dielectric constant to
use in the implicit solvent model.
- removeCMMotion (boolean=True) If true, a CMMotionRemover will be
added to the System.
- hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to
heavy atoms. Any mass added to a hydrogen is subtracted from the
heavy atom to keep their total mass the same.
- ewaldErrorTolerance (float=0.0005) The error tolerance to use if the
nonbonded method is Ewald or PME.
- flexibleConstraints (bool=True) Are our constraints flexible or not?
- verbose (bool=False) Optionally prints out a running progress report
Parameters
----------
params : CharmmParameterSet
The parameter set to use to parametrize this molecule
nonbondedMethod : object=NoCutoff
The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
nonbondedCutoff : distance=1*nanometer
The cutoff distance to use for nonbonded interactions.
switchDistance : distance=0*nanometer
The distance at which the switching function is active for nonbonded
interactions. If the switchDistance evaluates to boolean False (if
it is 0), no switching function will be used. Illegal values will
raise a ValueError
constraints : object=None
Specifies which bonds or angles should be implemented with
constraints. Allowed values are None, HBonds, AllBonds, or HAngles.
rigidWater : boolean=True
If true, water molecules will be fully rigid regardless of the value
passed for the constraints argument
implicitSolvent : object=None
If not None, the implicit solvent model to use. Allowed values are
HCT, OBC1, OBC2, or GBn
implicitSolventKappa : float=None
Debye screening parameter to model salt concentrations in GB
solvent.
implicitSolventSaltConc : float=0.0*u.moles/u.liter
Salt concentration for GB simulations. Converted to Debye length
`kappa'
temperature : float=298.15*u.kelvin
Temperature used in the salt concentration-to-kappa conversion for
GB salt concentration term
soluteDielectric : float=1.0
The solute dielectric constant to use in the implicit solvent model.
solventDielectric : float=78.5
The solvent dielectric constant to use in the implicit solvent
model.
removeCMMotion : boolean=True
If true, a CMMotionRemover will be added to the System.
hydrogenMass : mass=None
The mass to use for hydrogen atoms bound to heavy atoms. Any mass
added to a hydrogen is subtracted from the heavy atom to keep their
total mass the same.
ewaldErrorTolerance : float=0.0005
The error tolerance to use if the nonbonded method is Ewald or PME.
flexibleConstraints : bool=True
Are our constraints flexible or not?
verbose : bool=False
Optionally prints out a running progress report
"""
# Load the parameter set
self.loadParameters(params.condense())
......@@ -821,7 +841,7 @@ class CharmmPsfFile(object):
raise ValueError('Illegal implicit solvent model choice.')
if not constraints in (None, ff.HAngles, ff.HBonds, ff.AllBonds):
raise ValueError('Illegal constraints choice')
# Define conversion factors
length_conv = u.angstrom.conversion_factor_to(u.nanometer)
_chmfrc = u.kilocalorie_per_mole/(u.angstrom*u.angstrom)
......@@ -833,7 +853,7 @@ class CharmmPsfFile(object):
dihe_frc_conv = u.kilocalorie_per_mole.conversion_factor_to(
u.kilojoule_per_mole)
ene_conv = dihe_frc_conv
# Create the system and determine if any of our atoms have NBFIX (and
# therefore requires a CustomNonbondedForce instead)
typenames = set()
......@@ -1358,7 +1378,7 @@ class CharmmPsfFile(object):
def boxLengths(self, stuff):
raise RuntimeError('Use setBox to set a box with lengths and angles '
'or set the boxVectors attribute with box vectors')
@property
def boxVectors(self):
""" Return the box vectors """
......@@ -1403,12 +1423,12 @@ def set_molecules(atom_list):
owner = []
# The way I do this is via a recursive algorithm, in which
# the "set_owner" method is called for each bonded partner an atom
# has, which in turn calls set_owner for each of its partners and
# has, which in turn calls set_owner for each of its partners and
# so on until everything has been assigned.
molecule_number = 1 # which molecule number we are on
for i in range(len(atom_list)):
# If this atom has not yet been "owned", make it the next molecule
# However, we only increment which molecule number we're on if
# However, we only increment which molecule number we're on if
# we actually assigned a new molecule (obviously)
if not atom_list[i].marked:
tmp = [i]
......@@ -1429,7 +1449,7 @@ def _set_owner(atom_list, owner_array, atm, mol_id):
owner_array.append(partner.idx)
_set_owner(atom_list, owner_array, partner.idx, mol_id)
elif partner.marked != mol_id:
raise MoleculeError('Atom %d in multiple molecules' %
raise MoleculeError('Atom %d in multiple molecules' %
partner.idx)
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
......
wrappers/python/simtk/openmm/app/checkpointreporter.py
View file @ 80cc954a
......@@ -8,7 +8,7 @@ Medical Research, grant U54 GM072970. See https://simtk.org.
Portions copyright (c) 2014 Stanford University and the Authors.
Authors: Robert McGibbon
Contributors:
Contributors:
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
......@@ -71,10 +71,12 @@ class CheckpointReporter(object):
def __init__(self, file, reportInterval):
"""Create a CheckpointReporter.
Parameters:
- file (string or open file object) The file to write to. Any current
contents will be overwritten.
- reportInterval (int) The interval (in time steps) at which to write checkpoints
Parameters
----------
file : string or open file object
The file to write to. Any current contents will be overwritten.
reportInterval : int
The interval (in time steps) at which to write checkpoints.
"""
self._reportInterval = reportInterval
......@@ -88,12 +90,18 @@ class CheckpointReporter(object):
def describeNextReport(self, simulation):
"""Get information about the next report this object will generate.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
Returns: A five element tuple. The first element is the number of steps until the
next report. The remaining elements specify whether that report will require
positions, velocities, forces, and energies respectively.
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
Returns
-------
tuple
A five element tuple. The first element is the number of steps
until the next report. The remaining elements specify whether
that report will require positions, velocities, forces, and
energies respectively.
"""
steps = self._reportInterval - simulation.currentStep%self._reportInterval
return (steps, False, False, False, False)
......@@ -101,9 +109,12 @@ class CheckpointReporter(object):
def report(self, simulation, state):
"""Generate a report.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
- state (State) The current state of the simulation
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
state : State
The current state of the simulation
"""
self._out.seek(0)
chk = simulation.context.createCheckpoint()
......
wrappers/python/simtk/openmm/app/dcdfile.py
View file @ 80cc954a
......@@ -55,12 +55,19 @@ class DCDFile(object):
def __init__(self, file, topology, dt, firstStep=0, interval=1):
"""Create a DCD file and write out the header.
Parameters:
- file (file) A file to write to
- topology (Topology) The Topology defining the molecular system being written
- dt (time) The time step used in the trajectory
- firstStep (int=0) The index of the first step in the trajectory
- interval (int=1) The frequency (measured in time steps) at which states are written to the trajectory
Parameters
----------
file : file
A file to write to
topology : Topology
The Topology defining the molecular system being written
dt : time
The time step used in the trajectory
firstStep : int=0
The index of the first step in the trajectory
interval : int=1
The frequency (measured in time steps) at which states are written
to the trajectory
"""
self._file = file
self._topology = topology
......@@ -83,14 +90,21 @@ class DCDFile(object):
def writeModel(self, positions, unitCellDimensions=None, periodicBoxVectors=None):
"""Write out a model to the DCD file.
The periodic box can be specified either by the unit cell dimensions (for a rectangular box), or the full set of box
vectors (for an arbitrary triclinic box). If neither is specified, the box vectors specified in the Topology will be
used. Regardless of the value specified, no dimensions will be written if the Topology does not represent a periodic system.
Parameters:
- positions (list) The list of atomic positions to write
- unitCellDimensions (Vec3=None) The dimensions of the crystallographic unit cell.
- periodicBoxVectors (tuple of Vec3=None) The vectors defining the periodic box.
The periodic box can be specified either by the unit cell dimensions
(for a rectangular box), or the full set of box vectors (for an
arbitrary triclinic box). If neither is specified, the box vectors
specified in the Topology will be used. Regardless of the value
specified, no dimensions will be written if the Topology does not
represent a periodic system.
Parameters
----------
positions : list
The list of atomic positions to write
unitCellDimensions : Vec3=None
The dimensions of the crystallographic unit cell.
periodicBoxVectors : tuple of Vec3=None
The vectors defining the periodic box.
"""
if len(list(self._topology.atoms())) != len(positions):
raise ValueError('The number of positions must match the number of atoms')
......
wrappers/python/simtk/openmm/app/dcdreporter.py
View file @ 80cc954a
......@@ -45,9 +45,12 @@ class DCDReporter(object):
def __init__(self, file, reportInterval):
"""Create a DCDReporter.
Parameters:
- file (string) The file to write to
- reportInterval (int) The interval (in time steps) at which to write frames
Parameters
----------
file : string
The file to write to
reportInterval : int
The interval (in time steps) at which to write frames
"""
self._reportInterval = reportInterval
self._out = open(file, 'wb')
......@@ -56,11 +59,18 @@ class DCDReporter(object):
def describeNextReport(self, simulation):
"""Get information about the next report this object will generate.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
Returns: A five element tuple. The first element is the number of steps until the
next report. The remaining elements specify whether that report will require
positions, velocities, forces, and energies respectively.
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
Returns
-------
tuple
A five element tuple. The first element is the number of steps
until the next report. The remaining elements specify whether
that report will require positions, velocities, forces, and
energies respectively.
"""
steps = self._reportInterval - simulation.currentStep%self._reportInterval
return (steps, True, False, False, False)
......@@ -68,10 +78,14 @@ class DCDReporter(object):
def report(self, simulation, state):
"""Generate a report.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
- state (State) The current state of the simulation
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
state : State
The current state of the simulation
"""
if self._dcd is None:
self._dcd = DCDFile(self._out, simulation.topology, simulation.integrator.getStepSize(), 0, self._reportInterval)
a,b,c = state.getPeriodicBoxVectors()
......
wrappers/python/simtk/openmm/app/desmonddmsfile.py
View file @ 80cc954a
......@@ -46,10 +46,11 @@ class DesmondDMSFile(object):
def __init__(self, file):
"""Load a DMS file
Parameters:
- file (string) the name of the file to load
Parameters
----------
file : string
the name of the file to load
"""
# sqlite3 is included in the standard lib, but at python
# compile time, you can disable support (I think), so it's
# not *guarenteed* to be available. Doing the import here
......@@ -157,16 +158,24 @@ class DesmondDMSFile(object):
def createSystem(self, nonbondedMethod=ff.NoCutoff, nonbondedCutoff=1.0*nanometer,
ewaldErrorTolerance=0.0005, removeCMMotion=True, hydrogenMass=None):
"""Construct an OpenMM System representing the topology described by this dms file
Parameters:
- nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
- nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
- ewaldErrorTolerance (float=0.0005) The error tolerance to use if nonbondedMethod is Ewald or PME.
- removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
- hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms. Any mass added to a hydrogen is
subtracted from the heavy atom to keep their total mass the same.
"""Construct an OpenMM System representing the topology described by this
DMS file
Parameters
----------
nonbondedMethod : object=NoCutoff
The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
nonbondedCutoff : distance=1*nanometer
The cutoff distance to use for nonbonded interactions
ewaldErrorTolerance : float=0.0005
The error tolerance to use if nonbondedMethod is Ewald or PME.
removeCMMotion : boolean=True
If true, a CMMotionRemover will be added to the System
hydrogenMass : mass=None
The mass to use for hydrogen atoms bound to heavy atoms. Any mass
added to a hydrogen is subtracted from the heavy atom to keep their
total mass the same.
"""
self._checkForUnsupportedTerms()
sys = mm.System()
......
wrappers/python/simtk/openmm/app/element.py
View file @ 80cc954a
......@@ -58,11 +58,16 @@ class Element(object):
def __init__(self, number, name, symbol, mass):
"""Create a new element
Parameters:
number (int) The atomic number of the element
name (string) The name of the element
symbol (string) The chemical symbol of the element
mass (float) The atomic mass of the element
Parameters
----------
number : int
The atomic number of the element
name : string
The name of the element
symbol : string
The chemical symbol of the element
mass : float
The atomic mass of the element
"""
## The atomic number of the element
self._atomic_number = number
......@@ -115,7 +120,7 @@ class Element(object):
Returns
-------
element : Element
Element
The element whose atomic mass is closest to the input mass
"""
# Assume masses are in daltons if they are not units
......
wrappers/python/simtk/openmm/app/forcefield.py
View file @ 80cc954a
......@@ -104,12 +104,14 @@ class ForceField(object):
def __init__(self, *files):
"""Load one or more XML files and create a ForceField object based on them.
Parameters:
- files (list) A list of XML files defining the force field. Each entry may
be an absolute file path, a path relative to the current working
directory, a path relative to this module's data subdirectory
(for built in force fields), or an open file-like object with a
read() method from which the forcefield XML data can be loaded.
Parameters
----------
files : list
A list of XML files defining the force field. Each entry may
be an absolute file path, a path relative to the current working
directory, a path relative to this module's data subdirectory
(for built in force fields), or an open file-like object with a
read() method from which the forcefield XML data can be loaded.
"""
self._atomTypes = {}
self._templates = {}
......@@ -123,12 +125,14 @@ class ForceField(object):
def loadFile(self, file):
"""Load an XML file and add the definitions from it to this FieldField.
Parameters:
- file (string or file) An XML file containing force field definitions. It may
be either an absolute file path, a path relative to the current working
directory, a path relative to this module's data subdirectory
(for built in force fields), or an open file-like object with a
read() method from which the forcefield XML data can be loaded.
Parameters
----------
file : string or file
An XML file containing force field definitions. It may be either an
absolute file path, a path relative to the current working
directory, a path relative to this module's data subdirectory (for
built in force fields), or an open file-like object with a read()
method from which the forcefield XML data can be loaded.
"""
try:
# this handles either filenames or open file-like objects
......@@ -417,20 +421,36 @@ class ForceField(object):
constraints=None, rigidWater=True, removeCMMotion=True, hydrogenMass=None, **args):
"""Construct an OpenMM System representing a Topology with this force field.
Parameters:
- topology (Topology) The Topology for which to create a System
- nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
- nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
- constraints (object=None) Specifies which bonds and angles should be implemented with constraints.
Allowed values are None, HBonds, AllBonds, or HAngles.
- rigidWater (boolean=True) If true, water molecules will be fully rigid regardless of the value passed for the constraints argument
- removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
- hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms. Any mass added to a hydrogen is
subtracted from the heavy atom to keep their total mass the same.
- args Arbitrary additional keyword arguments may also be specified. This allows extra parameters to be specified that are specific to
particular force fields.
Returns: the newly created System
Parameters
----------
topology : Topology
The Topology for which to create a System
nonbondedMethod : object=NoCutoff
The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
nonbondedCutoff : distance=1*nanometer
The cutoff distance to use for nonbonded interactions
constraints : object=None
Specifies which bonds and angles should be implemented with constraints.
Allowed values are None, HBonds, AllBonds, or HAngles.
rigidWater : boolean=True
If true, water molecules will be fully rigid regardless of the value
passed for the constraints argument
removeCMMotion : boolean=True
If true, a CMMotionRemover will be added to the System
hydrogenMass : mass=None
The mass to use for hydrogen atoms bound to heavy atoms. Any mass
added to a hydrogen is subtracted from the heavy atom to keep
their total mass the same.
args
Arbitrary additional keyword arguments may also be specified.
This allows extra parameters to be specified that are specific to
particular force fields.
Returns
-------
system
the newly created System
"""
data = ForceField._SystemData()
data.atoms = list(topology.atoms())
......@@ -658,12 +678,20 @@ def _createResidueSignature(elements):
def _matchResidue(res, template, bondedToAtom):
"""Determine whether a residue matches a template and return a list of corresponding atoms.
Parameters:
- res (Residue) The residue to check
- template (_TemplateData) The template to compare it to
- bondedToAtom (list) Enumerates which other atoms each atom is bonded to
Returns: a list specifying which atom of the template each atom of the residue corresponds to,
or None if it does not match the template
Parameters
----------
res : Residue
The residue to check
template : _TemplateData
The template to compare it to
bondedToAtom : list
Enumerates which other atoms each atom is bonded to
Returns
-------
list
a list specifying which atom of the template each atom of the residue
corresponds to, or None if it does not match the template
"""
atoms = list(res.atoms())
if len(atoms) != len(template.atoms):
......
wrappers/python/simtk/openmm/app/gromacsgrofile.py
View file @ 80cc954a
......@@ -114,10 +114,11 @@ class GromacsGroFile(object):
The atom positions can be retrieved by calling getPositions().
Parameters:
- file (string) the name of the file to load
Parameters
----------
file : string
the name of the file to load
"""
xyzs = []
elements = [] # The element, most useful for quantum chemistry calculations
atomname = [] # The atom name, for instance 'HW1'
......@@ -183,10 +184,14 @@ class GromacsGroFile(object):
def getPositions(self, asNumpy=False, frame=0):
"""Get the atomic positions.
Parameters:
- asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
- frame (int=0) the index of the frame for which to get positions
"""
Parameters
----------
asNumpy : boolean=False
if true, the values are returned as a numpy array instead of a list
of Vec3s
frame : int=0
the index of the frame for which to get positions
"""
if asNumpy:
if self._numpyPositions is None:
self._numpyPositions = [None]*len(self._positions)
......@@ -198,16 +203,20 @@ class GromacsGroFile(object):
def getPeriodicBoxVectors(self, frame=0):
"""Get the vectors defining the periodic box.
Parameters:
- frame (int=0) the index of the frame for which to get the box vectors
Parameters
----------
frame : int=0
the index of the frame for which to get the box vectors
"""
return self._periodicBoxVectors[frame]
def getUnitCellDimensions(self, frame=0):
"""Get the dimensions of the crystallographic unit cell.
Parameters:
- frame (int=0) the index of the frame for which to get the unit cell dimensions
Parameters
----------
frame : int=0
the index of the frame for which to get the unit cell dimensions
"""
xsize = self._periodicBoxVectors[frame][0][0].value_in_unit(nanometers)
ysize = self._periodicBoxVectors[frame][1][1].value_in_unit(nanometers)
......
wrappers/python/simtk/openmm/app/gromacstopfile.py
View file @ 80cc954a
......@@ -433,16 +433,22 @@ class GromacsTopFile(object):
def __init__(self, file, periodicBoxVectors=None, unitCellDimensions=None, includeDir=None, defines=None):
"""Load a top file.
Parameters:
- file (string) the name of the file to load
- periodicBoxVectors (tuple of Vec3=None) the vectors defining the periodic box
- unitCellDimensions (Vec3=None) the dimensions of the crystallographic unit cell. For
non-rectangular unit cells, specify periodicBoxVectors instead.
- includeDir (string=None) A directory in which to look for other files
included from the top file. If not specified, we will attempt to locate a gromacs
installation on your system. When gromacs is installed in /usr/local, this will resolve
to /usr/local/gromacs/share/gromacs/top
- defines (dict={}) preprocessor definitions that should be predefined when parsing the file
Parameters
----------
file : str
the name of the file to load
periodicBoxVectors : tuple of Vec3=None
the vectors defining the periodic box
unitCellDimensions : Vec3=None
the dimensions of the crystallographic unit cell. For
non-rectangular unit cells, specify periodicBoxVectors instead.
includeDir : string=None
A directory in which to look for other files included from the
top file. If not specified, we will attempt to locate a gromacs
installation on your system. When gromacs is installed in
/usr/local, this will resolve to /usr/local/gromacs/share/gromacs/top
defines : dict={}
preprocessor definitions that should be predefined when parsing the file
"""
if includeDir is None:
includeDir = _defaultGromacsIncludeDir()
......@@ -539,23 +545,43 @@ class GromacsTopFile(object):
def createSystem(self, nonbondedMethod=ff.NoCutoff, nonbondedCutoff=1.0*unit.nanometer,
constraints=None, rigidWater=True, implicitSolvent=None, soluteDielectric=1.0, solventDielectric=78.5, ewaldErrorTolerance=0.0005, removeCMMotion=True, hydrogenMass=None):
"""Construct an OpenMM System representing the topology described by this prmtop file.
Parameters:
- nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
- nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
- constraints (object=None) Specifies which bonds and angles should be implemented with constraints.
Allowed values are None, HBonds, AllBonds, or HAngles.
- rigidWater (boolean=True) If true, water molecules will be fully rigid regardless of the value passed for the constraints argument
- implicitSolvent (object=None) If not None, the implicit solvent model to use. The only allowed value is OBC2.
- soluteDielectric (float=1.0) The solute dielectric constant to use in the implicit solvent model.
- solventDielectric (float=78.5) The solvent dielectric constant to use in the implicit solvent model.
- ewaldErrorTolerance (float=0.0005) The error tolerance to use if nonbondedMethod is Ewald or PME.
- removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
- hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms. Any mass added to a hydrogen is
subtracted from the heavy atom to keep their total mass the same.
Returns: the newly created System
"""Construct an OpenMM System representing the topology described by this
prmtop file.
Parameters
----------
nonbondedMethod : object=NoCutoff
The method to use for nonbonded interactions. Allowed values are
NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
nonbondedCutoff : distance=1*nanometer
The cutoff distance to use for nonbonded interactions
constraints : object=None
Specifies which bonds and angles should be implemented with
constraints. Allowed values are None, HBonds, AllBonds, or HAngles.
rigidWater : boolean=True
If true, water molecules will be fully rigid regardless of the value
passed for the constraints argument
implicitSolvent : object=None
If not None, the implicit solvent model to use. The only allowed
value is OBC2.
soluteDielectric : float=1.0
The solute dielectric constant to use in the implicit solvent model.
solventDielectric : float=78.5
The solvent dielectric constant to use in the implicit solvent
model.
ewaldErrorTolerance : float=0.0005
The error tolerance to use if nonbondedMethod is Ewald or PME.
removeCMMotion : boolean=True
If true, a CMMotionRemover will be added to the System
hydrogenMass : mass=None
The mass to use for hydrogen atoms bound to heavy atoms. Any mass
added to a hydrogen is subtracted from the heavy atom to keep their
total mass the same.
Returns
-------
System
the newly created System
"""
# Create the System.
......@@ -586,9 +612,9 @@ class GromacsTopFile(object):
topologyAtoms = list(self.topology.atoms())
exceptions = []
fudgeQQ = float(self._defaults[4])
# Build a lookup table to let us process dihedrals more quickly.
dihedralTypeTable = {}
for key in self._dihedralTypes:
if key[1] != 'X' and key[2] != 'X':
......@@ -837,7 +863,7 @@ class GromacsTopFile(object):
for atom in atoms[1:]:
if atom > atoms[0]:
exceptions.append((baseAtomIndex+atoms[0], baseAtomIndex+atom, 0, 0, 0))
# Create nonbonded exceptions.
......@@ -855,9 +881,9 @@ class GromacsTopFile(object):
nb.setNonbondedMethod(methodMap[nonbondedMethod])
nb.setCutoffDistance(nonbondedCutoff)
nb.setEwaldErrorTolerance(ewaldErrorTolerance)
# Adjust masses.
if hydrogenMass is not None:
for atom1, atom2 in self.topology.bonds():
if atom1.element == elem.hydrogen:
......
wrappers/python/simtk/openmm/app/internal/charmm/topologyobjects.py
View file @ 80cc954a
......@@ -76,22 +76,33 @@ class AtomType(object):
new atom types with the "add" constructor to make sure the registry is
filled with only unique types
Parameters and Attributes:
- name (str) : The name of the atom type
- number (int) : The integer index of the atom type
- mass (float) : The mass of the atom type
- atomic_number (int) : The atomic number of the element of the atom
type
Attributes:
- name (str) : The name of the atom type
- number (int) : The integer index of the atom type
- _member_number (int, private) : The order in which this atom type
was 'added' this is used to make sure that atom types added
last have priority in assignment in the generated hash tables
- nbfix (dict) : Dictionary that maps nbfix terms with other atom types.
Dict entries are (rmin, epsilon) -- precombined values
for that particular atom pair
Example:
Parameters
----------
name : str
The name of the atom type
number : int
The integer index of the atom type
mass : float
The mass of the atom type
atomic_number : int
The atomic number of the element of the atom type
Attributes
----------
name : str
The name of the atom type
number : int
The integer index of the atom type
_member_number : int, private)
The order in which this atom type was 'added' this is used to make
sure that atom types added last have priority in assignment in the
generated hash tables
nbfix : dict
Dictionary that maps nbfix terms with other atom types. Dict entries
are (rmin, epsilon) -- precombined values for that particular atom pair
Examples
--------
>>> at = AtomType('HA', 1, 1.008, 1)
>>> at.name, at.number
('HA', 1)
......@@ -212,34 +223,59 @@ WildCard = WildCard() # Turn it into a singleton
class Atom(object):
""" An atom in a structure.
Parameters:
system (str) : Name of the system this atom belongs to
name (str): name of the atom
type (str or int) : Type of the atom
charge (float) : Partial atomic charge (elementary charge units)
mass (float) : Atomic mass (amu)
props (list) : Other properties from the PSF
Attributes:
- attype (str) : Name of the atom type
- system (str) : The system name associated with this atom
- name (str) : Name of the atom (str)
- charge (float) : Partial atomic charge
- mass (float) : Mass of the atom (amu)
- idx (int) : index of the atom in the system, starting from 0
- props (list) : List of extraneous properties parsed from a PSF
- type (AtomType) : If assigned, has additional properties like the
non-bonded LJ parameters. If None, it has not yet been assigned
Possible Attributes (SOA == Set of Atom instances)
- bond_partners (SOA) : List of all atoms I am bonded to
- angle_partners (SOA) : List of all atoms I am angled to
- dihedral_partners (SOA) : List of all atoms I am dihedraled to
- bonds (list of Bond's) : All bonds to which I belong
- angles (list of Angle's) : All angles to which I belong
- dihedrals (list of Dihedral's) : All dihedrals to which I belong
- impropers (list of Improper's) : All impropers to which I belong
- cmaps (list of Cmap's) : All correction maps to which I belong
Parameters
----------
system : str
Name of the system this atom belongs to
name : str
name of the atom
type : str or int
Type of the atom
charge : float
Partial atomic charge (elementary charge units)
mass : float
Atomic mass (amu)
props : list
Other properties from the PSF
Attributes
----------
attype : str
Name of the atom type
system : str
The system name associated with this atom
name : str
Name of the atom (str)
charge : float
Partial atomic charge
mass : float
Mass of the atom (amu)
idx : int
index of the atom in the system, starting from 0
props : list
List of extraneous properties parsed from a PSF
type : AtomType
If assigned, has additional properties like the non-bonded LJ
parameters. If None, it has not yet been assigned
Possible Attributes
-------------------
bond_partners : set of Atoms
List of all atoms I am bonded to
angle_partners set of Atoms
List of all atoms I am angled to
dihedral_partners : et of Atoms
List of all atoms I am dihedraled to
bonds : list of Bonds
All bonds to which I belong
angles : list of Angles
All angles to which I belong
dihedrals : list of Dihedrals
All dihedrals to which I belong
impropers : list of Impropers
All impropers to which I belong
cmaps : list of Cmaps
All correction maps to which I belong
"""
def __init__(self, system, name, attype, charge, mass, props=None):
self.name = name
......@@ -450,22 +486,33 @@ class ResidueList(list):
def add_atom(self, system, resnum, resname, name,
attype, charge, mass, inscode, props=None):
"""
Adds an atom to the list of residues. If the residue is not the same as
the last residue that was created, a new Residue is created and added
to this list
Parameters:
- system (str) : The system this atom belongs to
- resnum (int) : Residue number
- resname (str) : Name of the residue
- name (str) : Name of the atom
- attype (int or str) : Type of the atom
- charge (float) : Partial atomic charge of the atom
- mass (float) : Mass (amu) of the atom
- inscode (str) : Insertion code, if it is specified
Returns:
"""Adds an atom to the list of residues. If the residue is not the same as
the last residue that was created, a new Residue is created and added to
this list
Parameters
----------
system : str
The system this atom belongs to
resnum : int
Residue number
resname : str
Name of the residue
name : str
Name of the atom
attype : int or str
Type of the atom
charge : float
Partial atomic charge of the atom
mass : float
Mass (amu) of the atom
inscode : str
Insertion code, if it is specified
props : list
Other properties from the PSF
Returns
-------
The Atom instance created and added to the list of residues
"""
lr = self._last_residue
......@@ -482,7 +529,7 @@ class ResidueList(list):
atom = Atom(system, name, attype, float(charge), float(mass), props)
res.add_atom(atom)
return atom
def append(self, thing):
raise NotImplemented('Use "add_atom" to build a residue list')
......@@ -491,13 +538,16 @@ class ResidueList(list):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class Bond(object):
"""
A bond object that links 2 atoms
Parameters:
- atom1 (Atom) : First atom included in the bond
- atom2 (Atom) : Second atom included in the bond
- bond_type (BondType) : Type for the bond (None if unknown)
"""A bond object that links 2 atoms
Parameters
----------
atom1 : Atom
First atom included in the bond
atom2 : Atom
Second atom included in the bond
bond_type : BondType
Type for the bond (None if unknown)
"""
def __init__(self, atom1, atom2, bond_type=None):
self.atom1 = atom1
......@@ -519,14 +569,18 @@ class Bond(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class Angle(object):
"""
An angle object that links 3 atoms
Parameters:
- atom1 (Atom) : First atom included in the angle
- atom2 (Atom) : Central atom in the valence angle
- atom3 (Atom) : Third atom in the valence angle
- angle_type (AngleType) : Type for the angle (None if unknown)
"""An angle object that links 3 atoms
Parameters
----------
atom1 : Atom
First atom included in the angle
atom2 : Atom
Central atom in the valence angle
atom3 : Atom
Third atom in the valence angle
angle_type : AngleType
Type for the angle (None if unknown)
"""
def __init__(self, atom1, atom2, atom3, angle_type=None):
self.atom1 = atom1
......@@ -554,15 +608,17 @@ class Angle(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class UreyBradley(object):
"""
A harmonic restraint between two atoms separated by 2 valence bonds (i.e.,
involved in a valence angle with each other
Parameters:
- atom1 (Atom) : The first atom included in the Urey-Bradley term
- atom2 (Atom) : The second atom included in the Urey-Bradley term
- ub_type (UreyBradleyType) : The type for the Urey-Bradley term (None
if unknown)
"""A harmonic restraint between two atoms separated by 2 valence bonds
(i.e., involved in a valence angle with each other
Parameters
----------
atom1 : Atom
The first atom included in the Urey-Bradley term
atom2 : Atom
The second atom included in the Urey-Bradley term
ub_type : UreyBradleyType
The type for the Urey-Bradley term (None if unknown)
"""
def __init__(self, atom1, atom2, ub_type=None):
self.atom1 = atom1
......@@ -599,15 +655,20 @@ class UreyBradley(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class Dihedral(object):
"""
A torsion angle object that links 4 atoms
Parameters:
- atom1 (Atom) : First atom included in the torsion
- atom2 (Atom) : Second atom included in the torsion
- atom3 (Atom) : Third atom included in the torsion
- atom4 (Atom) : Fourth atom included in the torsion
- dihedral_type (DihedralType) : Type for the torsion (None if unknown)
"""A torsion angle object that links 4 atoms
Parameters
----------
atom1 : Atom
First atom included in the torsion
atom2 : Atom
Second atom included in the torsion
atom3 : Atom
Third atom included in the torsion
atom4 : Atom
Fourth atom included in the torsion
dihedral_type : DihedralType
Type for the torsion (None if unknown)
"""
def __init__(self, atom1, atom2, atom3, atom4, dihedral_type=None):
self.atom1 = atom1
......@@ -648,15 +709,20 @@ class Dihedral(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class Improper(object):
"""
An improper torsion object. The third atom is bonded to each other atom
Parameters:
- atom1 (Atom) : First atom included in the torsion
- atom2 (Atom) : Second atom included in the torsion
- atom3 (Atom) : Third atom included in the torsion
- atom4 (Atom) : Fourth atom included in the torsion
- improper_type (ImproperType) : Type for the improper (None if unknown)
"""An improper torsion object. The third atom is bonded to each other atom
Parameters
----------
atom1 : Atom
First atom included in the torsion
atom2 : Atom
Second atom included in the torsion
atom3 : Atom
Third atom included in the torsion
atom4 : Atom
Fourth atom included in the torsion
improper_type : ImproperType
Type for the improper (None if unknown)
"""
def __init__(self, atom1, atom2, atom3, atom4, improper_type=None):
self.atom1 = atom1
......@@ -685,7 +751,7 @@ class Improper(object):
|
|
A4 ----- A1 ----- A2
So the bonds will either be between atom1 and any other atom
"""
if isinstance(thing, Bond):
......@@ -703,12 +769,14 @@ class Improper(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class AcceptorDonor(object):
"""
Just a holder for donors and acceptors in CHARMM speak
Parameters:
- atom1 (Atom) : First atom in the donor/acceptor group
- atom2 (Atom) : Second atom in the donor/acceptor group
"""Just a holder for donors and acceptors in CHARMM speak
Parameters
----------
atom1 : Atom
First atom in the donor/acceptor group
atom2 : Atom
Second atom in the donor/acceptor group
"""
def __init__(self, atom1, atom2):
self.atom1 = atom1
......@@ -724,13 +792,16 @@ class AcceptorDonor(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class Group(object):
"""
An 'interacting' group defined by the PSF.
"""An 'interacting' group defined by the PSF.
Parameters:
- bs (int) : ??
- type (int) : The group type
- move (int) : If the group moves ??
Parameters
----------
bs : int
??
type : int
The group type
move : int
If the group moves ??
Disclaimer: I really don't know what these numbers mean. I'm speculating
based on the source code of 'chamber', and this section is simply ignored
......@@ -749,36 +820,61 @@ class Cmap(object):
consecutive correction maps). "Consecutive torsions" (i.e., those definable
by 5 atoms) will only be recognized if the two torsions have the same order
Parameters:
- atom1 (Atom) : 1st atom of first dihedral
- atom2 (Atom) : 2nd atom of first dihedral
- atom3 (Atom) : 3rd atom of first dihedral
- atom4 (Atom) : 4th atom of first dihedral
- atom5 (Atom) : 1st atom of second dihedral
- atom6 (Atom) : 2nd atom of second dihedral
- atom7 (Atom) : 3rd atom of second dihedral
- atom8 (Atom) : 4th atom of second dihedral
- cmap_type (CmapType) : Cmap type for this cmap (None if unknown)
Attributes:
- consecutive (bool) : Are the dihedrals consecutive?
if consecutive:
- atom1 (Atom) : 1st atom of 1st dihedral
- atom2 (Atom) : 2nd atom of 1st dihedral && 1st atom of 2nd dihedral
- atom3 (Atom) : 3rd atom of 1st dihedral && 2nd atom of 2nd dihedral
- atom4 (Atom) : 4th atom of 1st dihedral && 3rd atom of 2nd dihedral
- atom5 (Atom) : 4th atom of 2nd dihedral
Parameters
----------
atom1 : Atom
1st atom of first dihedral
atom2 : Atom
2nd atom of first dihedral
atom3 : Atom
3rd atom of first dihedral
atom4 : Atom
4th atom of first dihedral
atom5 : Atom
1st atom of second dihedral
atom6 : Atom
2nd atom of second dihedral
atom7 : Atom
3rd atom of second dihedral
atom8 : Atom
4th atom of second dihedral
cmap_type : CmapType
Cmap type for this cmap (None if unknown)
Attributes
----------
consecutive : bool
Are the dihedrals consecutive?
if consecutive:
atom1 : Atom
1st atom of 1st dihedral
atom2 L Atom
2nd atom of 1st dihedral && 1st atom of 2nd dihedral
atom3 : Atom
3rd atom of 1st dihedral && 2nd atom of 2nd dihedral
atom4 : Atom
4th atom of 1st dihedral && 3rd atom of 2nd dihedral
atom5 : Atom
4th atom of 2nd dihedral
if not consecutive:
- atom1 (Atom) : 1st atom of first dihedral
- atom2 (Atom) : 2nd atom of first dihedral
- atom3 (Atom) : 3rd atom of first dihedral
- atom4 (Atom) : 4th atom of first dihedral
- atom5 (Atom) : 1st atom of second dihedral
- atom6 (Atom) : 2nd atom of second dihedral
- atom7 (Atom) : 3rd atom of second dihedral
- atom8 (Atom) : 4th atom of second dihedral
atom1 : Atom
1st atom of first dihedral
atom2 : Atom
2nd atom of first dihedral
atom3 : Atom
3rd atom of first dihedral
atom4 : Atom
4th atom of first dihedral
atom5 : Atom
1st atom of second dihedral
atom6 : Atom
2nd atom of second dihedral
atom7 : Atom
3rd atom of second dihedral
atom8 : Atom
4th atom of second dihedral
"""
def __init__(self, atom1, atom2, atom3, atom4, atom5, atom6, atom7,
atom8, cmap_type=None):
......@@ -866,9 +962,12 @@ class BondType(object):
A bond type with an equilibrium length (Angstroms) and force constant
(kcal/mol/Angstrom^2)
Parameters:
- k (float) : Force constant (kcal/mol/A^2)
- req (float) : Equilibrium distance
Parameters
----------
k : float
: Force constant (kcal/mol/A^2)
req : float
: Equilibrium distance
"""
def __init__(self, k, req):
self.k = k
......@@ -880,13 +979,15 @@ class BondType(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class AngleType(object):
"""
An angle type with an equilibrium angle (degrees) and force constant
"""An angle type with an equilibrium angle (degrees) and force constant
(kcal/mol/radians^2)
Parameters:
- k (float) : Force constant (kcal/mol/radians^2)
- theteq (float) : Equilibrium angle value (degrees)
Parameters
----------
k : float
Force constant (kcal/mol/radians^2)
theteq : float
Equilibrium angle value (degrees)
"""
def __init__(self, k, theteq):
self.k = k
......@@ -911,14 +1012,17 @@ NoUreyBradley = UreyBradleyType(None, None)
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class DihedralType(object):
"""
A torsion angle type with a force constant (kcal/mol), periodicity (int),
and phase (degrees)
Parameters:
- phi_k (float) : Force constant (kcal/mol)
- per (int) : Periodicity
- phase (float): Phase of the torsion
"""A torsion angle type with a force constant (kcal/mol), periodicity
(int), and phase (degrees)
Parameters
----------
phi_k : float
Force constant (kcal/mol)
per : int
Periodicity
phase : float
Phase of the torsion
"""
def __init__(self, phi_k, per, phase):
self.phi_k = float(phi_k)
......@@ -936,13 +1040,15 @@ class DihedralType(object):
# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
class ImproperType(object):
"""
An improper torsion angle type with a force constant (kcal/mol) and
"""An improper torsion angle type with a force constant (kcal/mol) and
equilibrium angle (degrees)
Parameters:
- k (float) : Force constant (kcal/mol)
- phieq (int) : Equilibrium angle (degrees)
Parameters
----------
k : float
: Force constant (kcal/mol)
phieq : int
: Equilibrium angle (degrees)
"""
def __init__(self, k, phieq):
self.k = k
......@@ -950,7 +1056,7 @@ class ImproperType(object):
def __eq__(self, other):
return self.k == other.k and self.phieq == other.phieq
def __repr__(self):
return '<ImproperType; k=%s; phieq=%s>' % (self.k, self.phieq)
......@@ -959,11 +1065,14 @@ class ImproperType(object):
class CmapType(object):
"""
Contains a correction map interpolation grid
Parameters:
- resolution (int) : Number of interpolation points for each dihedral
- grid (list of floats) : resolution x resolution list of energy values
(kcal/mol) for the angles with the 2nd angle changing fastest.
Parameters
----------
resolution : int
Number of interpolation points for each dihedral
grid : list of floats
resolution x resolution list of energy values (kcal/mol) for the
angles with the 2nd angle changing fastest.
The grid object is converted to a _CmapGrid instance which can be treated
like a normal list, but also has the ability to quickly return a transpose
......
wrappers/python/simtk/openmm/app/internal/pdbstructure.py
View file @ 80cc954a
......@@ -123,15 +123,18 @@ class PdbStructure(object):
"""
def __init__(self, input_stream, load_all_models = False):
def __init__(self, input_stream, load_all_models=False):
"""Create a PDB model from a PDB file stream.
Parameters:
- self (PdbStructure) The new object that is created.
- input_stream (stream) An input file stream, probably created with
open().
- load_all_models (bool) Whether to load every model of an NMR
structure or trajectory, or just load the first model, to save memory.
Parameters
----------
self : PdbStructure
The new object that is created.
input_stream : stream
An input file stream, probably created with open().
load_all_models : bool
Whether to load every model of an NMR structure or trajectory, or
just load the first model, to save memory.
"""
# initialize models
self.load_all_models = load_all_models
......@@ -201,7 +204,7 @@ class PdbStructure(object):
def _reset_atom_numbers(self):
self._atom_numbers_are_hex = False
self._next_atom_number = 1
def _reset_residue_numbers(self):
self._residue_numbers_are_hex = False
self._next_residue_number = 1
......@@ -269,8 +272,11 @@ class PdbStructure(object):
Iterate over atomic positions.
Parameters
- use_all_models (bool=False) Get positions from all models or just the first one.
- include_alt_loc (bool=False) Get all positions for each atom, or just the first one.
----------
use_all_models : bool=False
Get positions from all models or just the first one.
include_alt_loc : bool=False
Get all positions for each atom, or just the first one.
"""
for model in self.iter_models(use_all_models):
for loc in model.iter_positions(include_alt_loc):
......@@ -711,7 +717,7 @@ class Atom(object):
self.is_first_atom_in_chain = False
self.is_final_atom_in_chain = False
self.is_first_residue_in_chain = False
self.is_final_residue_in_chain = False
self.is_final_residue_in_chain = False
# Start parsing fields from pdb line
self.record_name = pdb_line[0:6].strip()
if pdbstructure is not None and pdbstructure._atom_numbers_are_hex:
......
wrappers/python/simtk/openmm/app/modeller.py
View file @ 80cc954a
......@@ -63,9 +63,12 @@ class Modeller(object):
def __init__(self, topology, positions):
"""Create a new Modeller object
Parameters:
- topology (Topology) the initial Topology of the model
- positions (list) the initial atomic positions
Parameters
----------
topology : Topology
the initial Topology of the model
positions : list
the initial atomic positions
"""
## The Topology describing the structure of the system
self.topology = topology
......@@ -85,12 +88,16 @@ class Modeller(object):
def add(self, addTopology, addPositions):
"""Add chains, residues, atoms, and bonds to the model.
Specify what to add by providing a new Topology object and the corresponding atomic positions.
All chains, residues, atoms, and bonds contained in the Topology are added to the model.
Specify what to add by providing a new Topology object and the
corresponding atomic positions. All chains, residues, atoms, and bonds
contained in the Topology are added to the model.
Parameters:
- addTopoology (Topology) a Topology whose contents should be added to the model
- addPositions (list) the positions of the atoms to add
Parameters
----------
addTopology : Topology
a Topology whose contents should be added to the model
addPositions : list
the positions of the atoms to add
"""
# Copy over the existing model.
......@@ -137,8 +144,11 @@ class Modeller(object):
You also can specify a bond (as a tuple of Atom objects) to delete just that bond without
deleting the Atoms it connects.
Parameters:
- toDelete (list) a list of Atoms, Residues, Chains, and bonds (specified as tuples of Atoms) to delete
Parameters
----------
toDelete : list
a list of Atoms, Residues, Chains, and bonds (specified as tuples of
Atoms) to delete
"""
newTopology = Topology()
newTopology.setPeriodicBoxVectors(self.topology.getPeriodicBoxVectors())
......@@ -176,10 +186,14 @@ class Modeller(object):
def convertWater(self, model='tip3p'):
"""Convert all water molecules to a different water model.
Parameters:
- model (string='tip3p') the water model to convert to. Supported values are 'tip3p', 'spce', 'tip4pew', and 'tip5p'.
@deprecated Use addExtraParticles() instead. It performs the same function but in a more general way.
@deprecated Use addExtraParticles() instead. It performs the same
function but in a more general way.
Parameters
----------
model : string='tip3p'
the water model to convert to. Supported values are 'tip3p',
'spce', 'tip4pew', and 'tip5p'.
"""
if model in ('tip3p', 'spce'):
sites = 3
......@@ -245,6 +259,7 @@ class Modeller(object):
"""Add solvent (both water and ions) to the model to fill a rectangular box.
The algorithm works as follows:
1. Water molecules are added to fill the box.
2. Water molecules are removed if their distance to any solute atom is less than the sum of their van der Waals radii.
3. If the solute is charged and neutralize=True, enough positive or negative ions are added to neutralize it. Each ion is added by
......@@ -252,28 +267,39 @@ class Modeller(object):
4. Ion pairs are added to give the requested total ionic strength.
The box size can be specified in any of several ways:
1. You can explicitly give the vectors defining the periodic box to use.
2. Alternatively, for a rectangular box you can simply give the dimensions of the unit cell.
3. You can give a padding distance. The largest dimension of the solute (along the x, y, or z axis) is determined, and a cubic
box of size (largest dimension)+2*padding is used.
4. You can specify the total number of molecules (both waters and ions) to add. A cubic box is then created whose size is
just large enough to hold the specified amount of solvent.
just large enough hold the specified amount of solvent.
5. Finally, if none of the above options is specified, the existing Topology's box vectors are used.
Parameters:
- forcefield (ForceField) the ForceField to use for determining van der Waals radii and atomic charges
- model (string='tip3p') the water model to use. Supported values are 'tip3p', 'spce', 'tip4pew', and 'tip5p'.
- boxSize (Vec3=None) the size of the box to fill with water
- boxVectors (tuple of Vec3=None) the vectors defining the periodic box to fill with water
- padding (distance=None) the padding distance to use
- numAdded (int=None) the total number of molecules (waters and ions) to add
- positiveIon (string='Na+') the type of positive ion to add. Allowed values are 'Cs+', 'K+', 'Li+', 'Na+', and 'Rb+'
- negativeIon (string='Cl-') the type of negative ion to add. Allowed values are 'Cl-', 'Br-', 'F-', and 'I-'. Be aware
that not all force fields support all ion types.
- ionicStrength (concentration=0*molar) the total concentration of ions (both positive and negative) to add. This
does not include ions that are added to neutralize the system.
- neutralize (bool=True) whether to add ions to neutralize the system
Parameters
----------
forcefield : ForceField
the ForceField to use for determining van der Waals radii and atomic charges
model : str='tip3p'
the water model to use. Supported values are 'tip3p', 'spce', 'tip4pew', and 'tip5p'.
boxSize : Vec3=None
the size of the box to fill with water
boxVectors : tuple of Vec3=None
the vectors defining the periodic box to fill with water
padding : distance=None
the padding distance to use
numAdded : int=None
the total number of molecules (waters and ions) to add
positiveIon : string='Na+'
the type of positive ion to add. Allowed values are 'Cs+', 'K+', 'Li+', 'Na+', and 'Rb+'
negativeIon : string='Cl-'
the type of negative ion to add. Allowed values are 'Cl-', 'Br-', 'F-', and 'I-'. Be aware
that not all force fields support all ion types.
ionicStrength : concentration=0*molar
the total concentration of ions (both positive and negative) to add. This
does not include ions that are added to neutralize the system.
neutralize : bool=True
whether to add ions to neutralize the system
"""
if len([x for x in (boxSize, boxVectors, padding, numAdded) if x is not None]) > 1:
raise ValueError('At most one of the following arguments may be specified: boxSize, boxVectors, padding, numAdded')
......@@ -295,13 +321,13 @@ class Modeller(object):
pdbTopology = pdb.getTopology()
pdbPositions = pdb.getPositions().value_in_unit(nanometer)
pdbResidues = list(pdbTopology.residues())
pdbBoxSize = pdbTopology.getUnitCellDimensions().value_in_unit(nanometer)
pdbBoxSize = pdbTopology.getUnitCellDimensions().value_in_unit(nanometer)
# Pick a unit cell size.
if numAdded is not None:
# Select a padding distance which is guaranteed to give more than the specified number of molecules.
padding = 1.1*(numAdded/((len(pdbResidues)/pdbBoxSize[0]**3)*8))**(1.0/3.0)
if padding < 0.5:
padding = 0.5 # Ensure we have enough when adding very small numbers of molecules
......@@ -443,20 +469,20 @@ class Modeller(object):
if numAdded is not None:
# We added many more waters than we actually want. Sort them based on distance to the nearest box edge and
# only keep the ones in the middle.
lowerBound = center-box/2
upperBound = center+box/2
distToEdge = (min(min(pos-lowerBound), min(upperBound-pos)) for index, pos in addedWaters)
sortedIndex = [i[0] for i in sorted(enumerate(distToEdge), key=lambda x: -x[1])]
addedWaters = [addedWaters[i] for i in sortedIndex[:numAdded]]
# Compute a new periodic box size.
maxSize = max(max((pos[i] for index, pos in addedWaters))-min((pos[i] for index, pos in addedWaters)) for i in range(3))
newTopology.setUnitCellDimensions(Vec3(maxSize, maxSize, maxSize))
else:
# There could be clashes between water molecules at the box edges. Find ones to remove.
upperCutoff = center+box/2-Vec3(waterCutoff, waterCutoff, waterCutoff)
lowerCutoff = center-box/2+Vec3(waterCutoff, waterCutoff, waterCutoff)
lowerSkinPositions = [pos for index, pos in addedWaters if pos[0] < lowerCutoff[0] or pos[1] < lowerCutoff[1] or pos[2] < lowerCutoff[2]]
......@@ -606,16 +632,29 @@ class Modeller(object):
Definitions for standard amino acids and nucleotides are built in. You can call loadHydrogenDefinitions() to load
additional definitions for other residue types.
Parameters:
- forcefield (ForceField=None) the ForceField to use for determining the positions of hydrogens. If this is None,
positions will be picked which are generally reasonable but not optimized for any particular ForceField.
- pH (float=7.0) the pH based on which to select variants
- variants (list=None) an optional list of variants to use. If this is specified, its length must equal the number
of residues in the model. variants[i] is the name of the variant to use for residue i (indexed starting at 0).
If an element is None, the standard rules will be followed to select a variant for that residue.
- platform (Platform=None) the Platform to use when computing the hydrogen atom positions. If this is None,
the default Platform will be used.
Returns: a list of what variant was actually selected for each residue, in the same format as the variants parameter
Parameters
----------
forcefield : ForceField=None
the ForceField to use for determining the positions of hydrogens.
If this is None, positions will be picked which are generally
reasonable but not optimized for any particular ForceField.
pH : float=7.0
the pH based on which to select variants
variants : list=None
an optional list of variants to use. If this is specified, its
length must equal the number of residues in the model. variants[i]
is the name of the variant to use for residue i (indexed starting at
0). If an element is None, the standard rules will be followed to
select a variant for that residue.
platform : Platform=None
the Platform to use when computing the hydrogen atom positions. If
this is None, the default Platform will be used.
Returns
-------
list
a list of what variant was actually selected for each residue,
in the same format as the variants parameter
"""
# Check the list of variants.
......@@ -804,7 +843,7 @@ class Modeller(object):
if forcefield is not None:
# Use the ForceField the user specified.
system = forcefield.createSystem(newTopology, rigidWater=False)
atoms = list(newTopology.atoms())
for i in range(system.getNumParticles()):
......@@ -814,7 +853,7 @@ class Modeller(object):
else:
# Create a System that restrains the distance of each hydrogen from its parent atom
# and causes hydrogens to spread out evenly.
system = System()
nonbonded = CustomNonbondedForce('100/((r/0.1)^4+1)')
bonds = HarmonicBondForce()
......@@ -838,7 +877,7 @@ class Modeller(object):
for residue in newTopology.residues():
if residue.name == 'HOH':
# Add an angle term to make the water geometry correct.
atoms = list(residue.atoms())
oindex = [i for i in range(len(atoms)) if atoms[i].element == elem.oxygen]
if len(atoms) == 3 and len(oindex) == 1:
......@@ -846,12 +885,12 @@ class Modeller(object):
angles.addAngle(atoms[hindex[0]].index, atoms[oindex[0]].index, atoms[hindex[1]].index, 1.824, 836.8)
else:
# Add angle terms for any hydroxyls.
for atom in residue.atoms():
index = atom.index
if atom.element == elem.oxygen and len(bondedTo[index]) == 2 and elem.hydrogen in (a.element for a in bondedTo[index]):
angles.addAngle(bondedTo[index][0].index, index, bondedTo[index][1].index, 1.894, 460.24)
if platform is None:
context = Context(system, VerletIntegrator(0.0))
else:
......@@ -864,18 +903,24 @@ class Modeller(object):
return actualVariants
def addExtraParticles(self, forcefield):
"""Add missing extra particles to the model that are required by a force field.
Some force fields use "extra particles" that do not represent actual atoms, but still need to be included in
the System. Examples include lone pairs, Drude particles, and the virtual sites used in some water models
to adjust the charge distribution. Extra particles can be recognized by the fact that their element is None.
This method is primarily used to add extra particles, but it can also remove them. It tries to match every
residue in the Topology to a template in the force field. If there is no match, it will both add and remove
extra particles as necessary to make it match.
Parameters:
- forcefield (ForceField) the ForceField defining what extra particles should be present
"""Add missing extra particles to the model that are required by a force
field.
Some force fields use "extra particles" that do not represent
actual atoms, but still need to be included in the System. Examples
include lone pairs, Drude particles, and the virtual sites used in some
water models to adjust the charge distribution. Extra particles can be
recognized by the fact that their element is None.
This method is primarily used to add extra particles, but it can also
remove them. It tries to match every residue in the Topology to a
template in the force field. If there is no match, it will both add
and remove extra particles as necessary to make it match.
Parameters
----------
forcefield : ForceField
the ForceField defining what extra particles should be present
"""
# Create copies of all residue templates that have had all extra points removed.
......
wrappers/python/simtk/openmm/app/pdbfile.py
View file @ 80cc954a
......@@ -64,8 +64,10 @@ class PDBFile(object):
The atom positions and Topology can be retrieved by calling getPositions() and getTopology().
Parameters:
- file (string) the name of the file to load
Parameters
----------
file : string
the name of the file to load
"""
top = Topology()
## The Topology read from the PDB file
......@@ -176,10 +178,14 @@ class PDBFile(object):
def getPositions(self, asNumpy=False, frame=0):
"""Get the atomic positions.
Parameters:
- asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
- frame (int=0) the index of the frame for which to get positions
"""
Parameters
----------
asNumpy : boolean=False
if true, the values are returned as a numpy array instead of a list
of Vec3s
frame : int=0
the index of the frame for which to get positions
"""
if asNumpy:
if self._numpyPositions is None:
self._numpyPositions = [None]*len(self._positions)
......@@ -234,13 +240,19 @@ class PDBFile(object):
def writeFile(topology, positions, file=sys.stdout, keepIds=False):
"""Write a PDB file containing a single model.
Parameters:
- topology (Topology) The Topology defining the model to write
- positions (list) The list of atomic positions to write
- file (file=stdout) A file to write to
- keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
new ones. Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
the PDB format. Otherwise, the output file will be invalid.
Parameters
----------
topology : Topology
The Topology defining the model to write
positions : list
The list of atomic positions to write
file : file=stdout
A file to write to
keepIds : bool=False
If True, keep the residue and chain IDs specified in the Topology
rather than generating new ones. Warning: It is up to the caller to
make sure these are valid IDs that satisfy the requirements of the
PDB format. Otherwise, the output file will be invalid.
"""
PDBFile.writeHeader(topology, file)
PDBFile.writeModel(topology, positions, file, keepIds=keepIds)
......@@ -250,9 +262,12 @@ class PDBFile(object):
def writeHeader(topology, file=sys.stdout):
"""Write out the header for a PDB file.
Parameters:
- topology (Topology) The Topology defining the molecular system being written
- file (file=stdout) A file to write the file to
Parameters
----------
topology : Topology
The Topology defining the molecular system being written
file : file=stdout
A file to write the file to
"""
print("REMARK 1 CREATED WITH OPENMM %s, %s" % (Platform.getOpenMMVersion(), str(date.today())), file=file)
vectors = topology.getPeriodicBoxVectors()
......@@ -266,15 +281,24 @@ class PDBFile(object):
def writeModel(topology, positions, file=sys.stdout, modelIndex=None, keepIds=False):
"""Write out a model to a PDB file.
Parameters:
- topology (Topology) The Topology defining the model to write
- positions (list) The list of atomic positions to write
- file (file=stdout) A file to write the model to
- modelIndex (int=None) If not None, the model will be surrounded by MODEL/ENDMDL records with this index
- keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
new ones. Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
the PDB format. Otherwise, the output file will be invalid.
Parameters
----------
topology : Topology
The Topology defining the model to write
positions : list
The list of atomic positions to write
file : file=stdout
A file to write the model to
modelIndex : int=None
If not None, the model will be surrounded by MODEL/ENDMDL records
with this index
keepIds : bool=False
If True, keep the residue and chain IDs specified in the Topology
rather than generating new ones. Warning: It is up to the caller to
make sure these are valid IDs that satisfy the requirements of the
PDB format. Otherwise, the output file will be invalid.
"""
if len(list(topology.atoms())) != len(positions):
raise ValueError('The number of positions must match the number of atoms')
if is_quantity(positions):
......@@ -331,12 +355,15 @@ class PDBFile(object):
def writeFooter(topology, file=sys.stdout):
"""Write out the footer for a PDB file.
Parameters:
- topology (Topology) The Topology defining the molecular system being written
- file (file=stdout) A file to write the file to
Parameters
----------
topology : Topology
The Topology defining the molecular system being written
file : file=stdout
A file to write the file to
"""
# Identify bonds that should be listed as CONECT records.
standardResidues = ['ALA', 'ASN', 'CYS', 'GLU', 'HIS', 'LEU', 'MET', 'PRO', 'THR', 'TYR',
'ARG', 'ASP', 'GLN', 'GLY', 'ILE', 'LYS', 'PHE', 'SER', 'TRP', 'VAL',
'A', 'G', 'C', 'U', 'I', 'DA', 'DG', 'DC', 'DT', 'DI', 'HOH']
......@@ -347,9 +374,9 @@ class PDBFile(object):
elif atom1.name == 'SG' and atom2.name == 'SG' and atom1.residue.name == 'CYS' and atom2.residue.name == 'CYS':
conectBonds.append((atom1, atom2))
if len(conectBonds) > 0:
# Work out the index used in the PDB file for each atom.
atomIndex = {}
nextAtomIndex = 0
prevChain = None
......@@ -360,9 +387,9 @@ class PDBFile(object):
prevChain = atom.residue.chain
atomIndex[atom] = nextAtomIndex
nextAtomIndex += 1
# Record which other atoms each atom is bonded to.
atomBonds = {}
for atom1, atom2 in conectBonds:
index1 = atomIndex[atom1]
......@@ -373,9 +400,9 @@ class PDBFile(object):
atomBonds[index2] = []
atomBonds[index1].append(index2)
atomBonds[index2].append(index1)
# Write the CONECT records.
for index1 in sorted(atomBonds):
bonded = atomBonds[index1]
while len(bonded) > 4:
......
wrappers/python/simtk/openmm/app/pdbreporter.py
View file @ 80cc954a
......@@ -44,9 +44,12 @@ class PDBReporter(object):
def __init__(self, file, reportInterval):
"""Create a PDBReporter.
Parameters:
- file (string) The file to write to
- reportInterval (int) The interval (in time steps) at which to write frames
Parameters
----------
file : string
The file to write to
reportInterval : int
The interval (in time steps) at which to write frames
"""
self._reportInterval = reportInterval
self._out = open(file, 'w')
......@@ -56,11 +59,18 @@ class PDBReporter(object):
def describeNextReport(self, simulation):
"""Get information about the next report this object will generate.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
Returns: A five element tuple. The first element is the number of steps until the
next report. The remaining elements specify whether that report will require
positions, velocities, forces, and energies respectively.
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
Returns
-------
tuple
A five element tuple. The first element is the number of steps
until the next report. The remaining elements specify whether
that report will require positions, velocities, forces, and
energies respectively.
"""
steps = self._reportInterval - simulation.currentStep%self._reportInterval
return (steps, True, False, False, False)
......@@ -68,9 +78,12 @@ class PDBReporter(object):
def report(self, simulation, state):
"""Generate a report.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
- state (State) The current state of the simulation
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
state : State
The current state of the simulation
"""
if self._nextModel == 0:
PDBFile.writeHeader(simulation.topology, self._out)
......@@ -95,9 +108,12 @@ class PDBxReporter(PDBReporter):
def report(self, simulation, state):
"""Generate a report.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
- state (State) The current state of the simulation
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
state : State
The current state of the simulation
"""
if self._nextModel == 0:
PDBxFile.writeHeader(simulation.topology, self._out)
......
wrappers/python/simtk/openmm/app/pdbxfile.py
View file @ 80cc954a
......@@ -53,10 +53,14 @@ class PDBxFile(object):
def __init__(self, file):
"""Load a PDBx/mmCIF file.
The atom positions and Topology can be retrieved by calling getPositions() and getTopology().
Parameters:
- file (string) the name of the file to load. Alternatively you can pass an open file object.
The atom positions and Topology can be retrieved by calling
getPositions() and getTopology().
Parameters
----------
file : string
the name of the file to load. Alternatively you can pass an open
file object.
"""
top = Topology()
## The Topology read from the PDBx/mmCIF file
......@@ -193,10 +197,14 @@ class PDBxFile(object):
def getPositions(self, asNumpy=False, frame=0):
"""Get the atomic positions.
Parameters:
- asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
- frame (int=0) the index of the frame for which to get positions
"""
Parameters
----------
asNumpy : bool=False
if true, the values are returned as a numpy array instead of a list
of Vec3s
frame : int=0
the index of the frame for which to get positions
"""
if asNumpy:
if self._numpyPositions is None:
self._numpyPositions = [None]*len(self._positions)
......@@ -210,14 +218,21 @@ class PDBxFile(object):
entry=None):
"""Write a PDBx/mmCIF file containing a single model.
Parameters:
- topology (Topology) The Topology defining the model to write
- positions (list) The list of atomic positions to write
- file (file=stdout) A file to write to
- keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
new ones. Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
the PDBx/mmCIF format. Otherwise, the output file will be invalid.
- entry (str=None) The entry ID to assign to the CIF file
Parameters
----------
topology : Topology
The Topology defining the model to write
positions : list
The list of atomic positions to write
file : file=stdout
A file to write to
keepIds : bool=False
If True, keep the residue and chain IDs specified in the Topology
rather than generating new ones. Warning: It is up to the caller to
make sure these are valid IDs that satisfy the requirements of the
PDBx/mmCIF format. Otherwise, the output file will be invalid.
entry : str=None
The entry ID to assign to the CIF file
"""
PDBxFile.writeHeader(topology, file, entry)
PDBxFile.writeModel(topology, positions, file, keepIds=keepIds)
......@@ -226,10 +241,14 @@ class PDBxFile(object):
def writeHeader(topology, file=sys.stdout, entry=None):
"""Write out the header for a PDBx/mmCIF file.
Parameters:
- topology (Topology) The Topology defining the molecular system being written
- file (file=stdout) A file to write the file to
- entry (str=None) The entry ID to assign to the CIF file
Parameters
----------
topology : Topology
The Topology defining the molecular system being written
file : file=stdout
A file to write the file to
entry : str=None
The entry ID to assign to the CIF file
"""
if entry is not None:
print('data_%s' % entry, file=file)
......@@ -280,14 +299,21 @@ class PDBxFile(object):
def writeModel(topology, positions, file=sys.stdout, modelIndex=1, keepIds=False):
"""Write out a model to a PDBx/mmCIF file.
Parameters:
- topology (Topology) The Topology defining the model to write
- positions (list) The list of atomic positions to write
- file (file=stdout) A file to write the model to
- modelIndex (int=1) The model number of this frame
- keepIds (bool=False) If True, keep the residue and chain IDs specified in the Topology rather than generating
new ones. Warning: It is up to the caller to make sure these are valid IDs that satisfy the requirements of
the PDBx/mmCIF format. Otherwise, the output file will be invalid.
Parameters
----------
topology : Topology
The Topology defining the model to write
positions : list
The list of atomic positions to write
file : file=stdout
A file to write the model to
modelIndex : int=1
The model number of this frame
keepIds : bool=False
If True, keep the residue and chain IDs specified in the Topology
rather than generating new ones. Warning: It is up to the caller to
make sure these are valid IDs that satisfy the requirements of the
PDBx/mmCIF format. Otherwise, the output file will be invalid.
"""
if len(list(topology.atoms())) != len(positions):
raise ValueError('The number of positions must match the number of atoms')
......
wrappers/python/simtk/openmm/app/simulation.py
View file @ 80cc954a
......@@ -55,13 +55,19 @@ class Simulation(object):
def __init__(self, topology, system, integrator, platform=None, platformProperties=None):
"""Create a Simulation.
Parameters:
- topology (Topology) A Topology describing the the system to simulate
- system (System) The OpenMM System object to simulate
- integrator (Integrator) The OpenMM Integrator to use for simulating the System
- platform (Platform=None) If not None, the OpenMM Platform to use
- platformProperties (map=None) If not None, a set of platform-specific properties to pass
to the Context's constructor
Parameters
----------
topology : Topology
A Topology describing the the system to simulate
system : System
The OpenMM System object to simulate
integrator : Integrator
The OpenMM Integrator to use for simulating the System
platform : Platform=None
If not None, the OpenMM Platform to use
platformProperties : map=None
If not None, a set of platform-specific properties to pass to the
Context's constructor
"""
## The Topology describing the system being simulated
self.topology = topology
......@@ -84,35 +90,48 @@ class Simulation(object):
def minimizeEnergy(self, tolerance=10*unit.kilojoule/unit.mole, maxIterations=0):
"""Perform a local energy minimization on the system.
Parameters:
- tolerance (energy=10*kilojoules/mole) The energy tolerance to which the system should be minimized
- maxIterations (int=0) The maximum number of iterations to perform. If this is 0, minimization is continued
until the results converge without regard to how many iterations it takes.
Parameters
----------
tolerance : energy=10*kilojoules/mole
The energy tolerance to which the system should be minimized
maxIterations : int=0
The maximum number of iterations to perform. If this is 0,
minimization is continued until the results converge without regard
to how many iterations it takes.
"""
mm.LocalEnergyMinimizer.minimize(self.context, tolerance, maxIterations)
def step(self, steps):
"""Advance the simulation by integrating a specified number of time steps."""
self._simulate(endStep=self.currentStep+steps)
def runForClockTime(self, time, checkpointFile=None, stateFile=None, checkpointInterval=None):
"""Advance the simulation by integrating time steps until a fixed amount of clock time has elapsed.
This is useful when you have a limited amount of computer time available, and want to run the longest simulation
possible in that time. This method will continue taking time steps until the specified clock time has elapsed,
then return. It also can automatically write out a checkpoint and/or state file before returning, so you can
later resume the simulation. Another option allows it to write checkpoints or states at regular intervals, so
you can resume even if the simulation is interrupted before the time limit is reached.
Parameters:
- time (time) the amount of time to run for. If no units are specified, it is assumed to be a number of hours.
- checkpointFile (string or file=None) if specified, a checkpoint file will be written at the end of the
simulation (and optionally at regular intervals before then) by passing this to saveCheckpoint().
- stateFile (string or file=None) if specified, a state file will be written at the end of the
simulation (and optionally at regular intervals before then) by passing this to saveState().
- checkpointInterval (time=None) if specified, checkpoints and/or states will be written at regular intervals
during the simulation, in addition to writing a final version at the end. If no units are specified, this is
assumed to be in hours.
Parameters
----------
time : time
the amount of time to run for. If no units are specified, it is
assumed to be a number of hours.
checkpointFile : string or file=None
if specified, a checkpoint file will be written at the end of the
simulation (and optionally at regular intervals before then) by
passing this to saveCheckpoint().
stateFile : string or file=None
if specified, a state file will be written at the end of the
simulation (and optionally at regular intervals before then) by
passing this to saveState().
checkpointInterval : time=None
if specified, checkpoints and/or states will be written at regular
intervals during the simulation, in addition to writing a final
version at the end. If no units are specified, this is assumed to
be in hours.
"""
if unit.is_quantity(time):
time = time.value_in_unit(unit.hours)
......@@ -131,7 +150,7 @@ class Simulation(object):
self.saveCheckpoint(checkpointFile)
if stateFile is not None:
self.saveState(stateFile)
def _simulate(self, endStep=None, endTime=None):
if endStep is None:
endStep = sys.maxsize
......@@ -174,30 +193,36 @@ class Simulation(object):
def saveCheckpoint(self, file):
"""Save a checkpoint of the simulation to a file.
The output is a binary file that contains a complete representation of the current state of the Simulation.
It includes both publicly visible data such as the particle positions and velocities, and also internal data
such as the states of random number generators. Reloading the checkpoint will put the Simulation back into
precisely the same state it had before, so it can be exactly continued.
A checkpoint file is highly specific to the Simulation it was created from. It can only be loaded into
another Simulation that has an identical System, uses the same Platform and OpenMM version, and is running on
identical hardware. If you need a more portable way to resume simulations, consider using saveState() instead.
Parameters:
- file (string or file) a File-like object to write the checkpoint to, or alternatively a filename
Parameters
----------
file : string or file
a File-like object to write the checkpoint to, or alternatively a
filename
"""
if isinstance(file, str):
with open(file, 'wb') as f:
f.write(self.context.createCheckpoint())
else:
file.write(self.context.createCheckpoint())
def loadCheckpoint(self, file):
"""Load a checkpoint file that was created with saveCheckpoint().
Parameters:
- file (string or file) a File-like object to load the checkpoint from, or alternatively a filename
Parameters
----------
file : string or file
a File-like object to load the checkpoint from, or alternatively a
filename
"""
if isinstance(file, str):
with open(file, 'rb') as f:
......@@ -207,18 +232,21 @@ class Simulation(object):
def saveState(self, file):
"""Save the current state of the simulation to a file.
The output is an XML file containing a serialized State object. It includes all publicly visible data,
including positions, velocities, and parameters. Reloading the State will put the Simulation back into
approximately the same state it had before.
Unlike saveCheckpoint(), this does not store internal data such as the states of random number generators.
Therefore, you should not expect the following trajectory to be identical to what would have been produced
with the original Simulation. On the other hand, this means it is portable across different Platforms or
hardware.
Parameters:
- file (string or file) a File-like object to write the state to, or alternatively a filename
Parameters
----------
file : string or file
a File-like object to write the state to, or alternatively a
filename
"""
state = self.context.getState(getPositions=True, getVelocities=True, getParameters=True)
xml = mm.XmlSerializer.serialize(state)
......@@ -227,12 +255,15 @@ class Simulation(object):
f.write(xml)
else:
file.write(xml)
def loadState(self, file):
"""Load a State file that was created with saveState().
Parameters:
- file (string or file) a File-like object to load the state from, or alternatively a filename
Parameters
----------
file : string or file
a File-like object to load the state from, or alternatively a
filename
"""
if isinstance(file, str):
with open(file, 'r') as f:
......
wrappers/python/simtk/openmm/app/statedatareporter.py
View file @ 80cc954a
......@@ -60,31 +60,54 @@ class StateDataReporter(object):
progress=False, remainingTime=False, speed=False, elapsedTime=False, separator=',', systemMass=None, totalSteps=None):
"""Create a StateDataReporter.
Parameters:
- file (string or file) The file to write to, specified as a file name or file object
- reportInterval (int) The interval (in time steps) at which to write frames
- step (boolean=False) Whether to write the current step index to the file
- time (boolean=False) Whether to write the current time to the file
- potentialEnergy (boolean=False) Whether to write the potential energy to the file
- kineticEnergy (boolean=False) Whether to write the kinetic energy to the file
- totalEnergy (boolean=False) Whether to write the total energy to the file
- temperature (boolean=False) Whether to write the instantaneous temperature to the file
- volume (boolean=False) Whether to write the periodic box volume to the file
- density (boolean=False) Whether to write the system density to the file
- progress (boolean=False) Whether to write current progress (percent completion) to the file.
If this is True, you must also specify totalSteps.
- remainingTime (boolean=False) Whether to write an estimate of the remaining clock time until
completion to the file. If this is True, you must also specify totalSteps.
- speed (bool=False) Whether to write an estimate of the simulation speed in ns/day to the file
- elapsedTime (bool=False) Whether to write the elapsed time of the simulation in seconds to the file.
- separator (string=',') The separator to use between columns in the file
- systemMass (mass=None) The total mass to use for the system when reporting density. If this is
None (the default), the system mass is computed by summing the masses of all particles. This
parameter is useful when the particle masses do not reflect their actual physical mass, such as
when some particles have had their masses set to 0 to immobilize them.
- totalSteps (int=None) The total number of steps that will be included in the simulation. This
is required if either progress or remainingTime is set to True, and defines how many steps will
indicate 100% completion.
Parameters
----------
file : string or file
The file to write to, specified as a file name or file object
reportInterval : int
The interval (in time steps) at which to write frames
step : bool=False
Whether to write the current step index to the file
time : bool=False
Whether to write the current time to the file
potentialEnergy : bool=False
Whether to write the potential energy to the file
kineticEnergy : bool=False
Whether to write the kinetic energy to the file
totalEnergy : bool=False
Whether to write the total energy to the file
temperature : bool=False
Whether to write the instantaneous temperature to the file
volume : bool=False
Whether to write the periodic box volume to the file
density : bool=False
Whether to write the system density to the file
progress : bool=False
Whether to write current progress (percent completion) to the file.
If this is True, you must also specify totalSteps.
remainingTime : bool=False
Whether to write an estimate of the remaining clock time until
completion to the file. If this is True, you must also specify
totalSteps.
speed : bool=False
Whether to write an estimate of the simulation speed in ns/day to
the file
elapsedTime : bool=False
Whether to write the elapsed time of the simulation in seconds to
the file.
separator : string=','
The separator to use between columns in the file
systemMass : mass=None
The total mass to use for the system when reporting density. If
this is None (the default), the system mass is computed by summing
the masses of all particles. This parameter is useful when the
particle masses do not reflect their actual physical mass, such as
when some particles have had their masses set to 0 to immobilize
them.
totalSteps : int=None
The total number of steps that will be included in the simulation.
This is required if either progress or remainingTime is set to True,
and defines how many steps will indicate 100% completion.
"""
self._reportInterval = reportInterval
self._openedFile = isinstance(file, str)
......@@ -129,11 +152,18 @@ class StateDataReporter(object):
def describeNextReport(self, simulation):
"""Get information about the next report this object will generate.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
Returns: A five element tuple. The first element is the number of steps until the
next report. The remaining elements specify whether that report will require
positions, velocities, forces, and energies respectively.
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
Returns
-------
tuple
A five element tuple. The first element is the number of steps
until the next report. The remaining elements specify whether
that report will require positions, velocities, forces, and
energies respectively.
"""
steps = self._reportInterval - simulation.currentStep%self._reportInterval
return (steps, self._needsPositions, self._needsVelocities, self._needsForces, self._needEnergy)
......@@ -141,9 +171,12 @@ class StateDataReporter(object):
def report(self, simulation, state):
"""Generate a report.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
- state (State) The current state of the simulation
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
state : State
The current state of the simulation
"""
if not self._hasInitialized:
self._initializeConstants(simulation)
......@@ -174,11 +207,16 @@ class StateDataReporter(object):
def _constructReportValues(self, simulation, state):
"""Query the simulation for the current state of our observables of interest.
Parameters:
- simulation (Simulation) The Simulation to generate a report for
- state (State) The current state of the simulation
Parameters
----------
simulation : Simulation
The Simulation to generate a report for
state : State
The current state of the simulation
Returns: A list of values summarizing the current state of
Returns
-------
A list of values summarizing the current state of
the simulation, to be printed or saved. Each element in the list
corresponds to one of the columns in the resulting CSV file.
"""
......
wrappers/python/simtk/openmm/app/topology.py
View file @ 80cc954a
......@@ -89,10 +89,16 @@ class Topology(object):
def addChain(self, id=None):
"""Create a new Chain and add it to the Topology.
Parameters:
- id (string=None) An optional identifier for the chain. If this is omitted, an id
is generated based on the chain index.
Returns: the newly created Chain
Parameters
----------
id : string=None
An optional identifier for the chain. If this is omitted, an id is
generated based on the chain index.
Returns
-------
Chain
the newly created Chain
"""
if id is None:
id = str(len(self._chains)+1)
......@@ -103,12 +109,20 @@ class Topology(object):
def addResidue(self, name, chain, id=None):
"""Create a new Residue and add it to the Topology.
Parameters:
- name (string) The name of the residue to add
- chain (Chain) The Chain to add it to
- id (string=None) An optional identifier for the residue. If this is omitted, an id
is generated based on the residue index.
Returns: the newly created Residue
Parameters
----------
name : string
The name of the residue to add
chain : Chain
The Chain to add it to
id : string=None
An optional identifier for the residue. If this is omitted, an id
is generated based on the residue index.
Returns
-------
Residue
the newly created Residue
"""
if id is None:
id = str(self._numResidues+1)
......@@ -120,13 +134,22 @@ class Topology(object):
def addAtom(self, name, element, residue, id=None):
"""Create a new Atom and add it to the Topology.
Parameters:
- name (string) The name of the atom to add
- element (Element) The element of the atom to add
- residue (Residue) The Residue to add it to
- id (string=None) An optional identifier for the atom. If this is omitted, an id
is generated based on the atom index.
Returns: the newly created Atom
Parameters
----------
name : string
The name of the atom to add
element : Element
The element of the atom to add
residue : Residue
The Residue to add it to
id : string=None
An optional identifier for the atom. If this is omitted, an id is
generated based on the atom index.
Returns
-------
Atom
the newly created Atom
"""
if id is None:
id = str(self._numAtoms+1)
......@@ -138,9 +161,12 @@ class Topology(object):
def addBond(self, atom1, atom2):
"""Create a new bond and add it to the Topology.
Parameters:
- atom1 (Atom) The first Atom connected by the bond
- atom2 (Atom) The second Atom connected by the bond
Parameters
----------
atom1 : Atom
The first Atom connected by the bond
atom2 : Atom
The second Atom connected by the bond
"""
self._bonds.append((atom1, atom2))
......@@ -274,10 +300,13 @@ class Topology(object):
self.addBond(atomMaps[fromResidue][fromAtom], atomMaps[toResidue][toAtom])
def createDisulfideBonds(self, positions):
"""Identify disulfide bonds based on proximity and add them to the Topology.
"""Identify disulfide bonds based on proximity and add them to the
Topology.
Parameters:
- positions (list) The list of atomic positions based on which to identify bonded atoms
Parameters
----------
positions : list
The list of atomic positions based on which to identify bonded atoms
"""
def isCyx(res):
names = [atom.name for atom in res._atoms]
......
wrappers/python/simtk/openmm/mtsintegrator.py
View file @ 80cc954a
......@@ -10,7 +10,7 @@ Portions copyright (c) 2013-2015 Stanford University and the Authors.
Authors: Peter Eastman
Contributors:
Permission is hereby granted, free of charge, to any person obtaining a
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
......@@ -36,49 +36,52 @@ from simtk.openmm import CustomIntegrator
class MTSIntegrator(CustomIntegrator):
"""MTSIntegrator implements the rRESPA multiple time step integration algorithm.
This integrator allows different forces to be evaluated at different frequencies,
for example to evaluate the expensive, slowly changing forces less frequently than
the inexpensive, quickly changing forces.
To use it, you must first divide your forces into two or more groups (by calling
setForceGroup() on them) that should be evaluated at different frequencies. When
you create the integrator, you provide a tuple for each group specifying the index
of the force group and the frequency (as a fraction of the outermost time step) at
which to evaluate it. For example:
<pre>
integrator = MTSIntegrator(4*femtoseconds, [(0,1), (1,2), (2,8)])
</pre>
This specifies that the outermost time step is 4 fs, so each step of the integrator
will advance time by that much. It also says that force group 0 should be evaluated
once per time step, force group 1 should be evaluated twice per time step (every 2 fs),
and force group 2 should be evaluated eight times per time step (every 0.5 fs).
A common use of this algorithm is to evaluate reciprocal space nonbonded interactions
less often than the bonded and direct space nonbonded interactions. The following
example looks up the NonbondedForce, sets the reciprocal space interactions to their
own force group, and then creates an integrator that evaluates them once every 4 fs,
but all other interactions every 2 fs.
<pre>
nonbonded = [f for f in system.getForces() if isinstance(f, NonbondedForce)][0]
nonbonded.setReciprocalSpaceForceGroup(1)
integrator = MTSIntegrator(4*femtoseconds, [(1,1), (0,2)])
</pre>
For details, see Tuckerman et al., J. Chem. Phys. 97(3) pp. 1990-2001 (1992).
"""
def __init__(self, dt, groups):
"""Create an MTSIntegrator.
Parameters:
- dt (time) The largest (outermost) integration time step to use
- groups (list) A list of tuples defining the force groups. The first element of each
tuple is the force group index, and the second element is the number of times that force
group should be evaluated in one time step.
Parameters
----------
dt : time
The largest (outermost) integration time step to use
groups : list
A list of tuples defining the force groups. The first element of
each tuple is the force group index, and the second element is the
number of times that force group should be evaluated in one time step.
"""
if len(groups) == 0:
raise ValueError("No force groups specified")
......@@ -88,7 +91,7 @@ class MTSIntegrator(CustomIntegrator):
self.addUpdateContextState();
self._createSubsteps(1, groups)
self.addConstrainVelocities();
def _createSubsteps(self, parentSubsteps, groups):
group, substeps = groups[0]
stepsPerParentStep = substeps/parentSubsteps
......
wrappers/python/simtk/unit/unit.py 100644 → 100755
View file @ 80cc954a
......@@ -54,9 +54,12 @@ class Unit(object):
def __init__(self, base_or_scaled_units):
"""Create a new Unit.
Parameters:
- self (Unit) The newly created Unit.
- base_or_scaled_units (dict) Keys are BaseUnits or ScaledUnits. Values are exponents (numbers).
Parameters
----------
self : Unit
The newly created Unit.
base_or_scaled_units : dict
Keys are BaseUnits or ScaledUnits. Values are exponents (numbers).
"""
# Unit contents are of two types: BaseUnits and ScaledUnits
self._top_base_units = {}
......@@ -389,7 +392,8 @@ class Unit(object):
Strips off any ScaledUnits in the Unit, leaving only BaseUnits.
Parameters
- system: a dictionary of (BaseDimension, BaseUnit) pairs
----------
system : a dictionary of (BaseDimension, BaseUnit) pairs
"""
return system.express_unit(self)
......@@ -583,7 +587,7 @@ class UnitSystem(object):
Parameters
----------
units: ``list``
units : list
List of base units from which to construct the unit system
"""
def __init__(self, units):
......@@ -678,7 +682,7 @@ def is_unit(x):
Returns True if x is a Unit, False otherwise.
Examples
--------
>>> is_unit(16)
False
"""
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment