3. Tools API

3.1. Functions

3.1.1. add_hydrogen function

moldesign.add_hydrogen(mol, ph=None, wait=True)[source]

Add hydrogens to saturate atomic valences.

Parameters:
  • mol (moldesign.Molecule) – Molecule to saturate
  • ph (float) – Assign formal charges and protonation using pH model; if None (the default), neutral protonation will be assigned where possible.
Returns:

New molecule with all valences saturated
Return type:

moldesign.Molecule

3.1.2. add_missing_data function

moldesign.add_missing_data(mol)[source]

Add missing hydrogens, bond orders, and formal charges to a structure (often from the PDB)

Specifically, this is a convenience function that runs: mdt.guess_bond_orders, mdt.add_hydrogen, and mdt.assign_formal_charges

Note

This does NOT add missing residues to biochemical structures. This functionality will be available as moldesign.add_missing_residues()

Parameters:mol (moldesign.Molecule) – molecule to clean
Returns:cleaned version of the molecule
Return type:moldesign.Molecule

3.1.3. add_water function

moldesign.add_water(mol, min_box_size=None, padding=None, ion_concentration=None, neutralize=True, positive_ion='Na+', negative_ion='Cl-', wait=True)[source]

Solvate a molecule in a water box with optional ions

Parameters:
  • mol (moldesign.Molecule) – solute molecule
  • min_box_size (u.Scalar[length] or u.Vector[length]) – size of the water box - either a vector of x,y,z dimensions, or just a uniform cube length. Either this or padding (or both) must be passed
  • padding (u.Scalar[length]) – distance to edge of water box from the solute in each dimension
  • neutralize (bool) – add ions to neutralize solute charge (in addition to specified ion concentration)
  • positive_ion (str) – type of positive ions to add, if needed. Allowed values (from OpenMM modeller) are Cs, K, Li, Na (the default) and Rb
  • negative_ion (str) – type of negative ions to add, if needed. Allowed values (from OpenMM modeller) are Cl (the default), Br, F, and I
  • ion_concentration (float or u.Scalar[molarity]) – ionic concentration in addition to whatever is needed to neutralize the solute. (if float is passed, we assume the number is Molar)
Returns:

new Molecule object containing both solvent and solute
Return type:

moldesign.Molecule

3.1.4. assign_forcefield function

moldesign.assign_forcefield(mol, **kwargs)[source]

run_tleap(mol, forcefields=None, parameters=None, engine=None, image=None, wait=True, jobname=None, display=True) Drives tleap to create a prmtop and inpcrd file. Specifically uses the AmberTools 16 tleap distribution.

Defaults are as recommended in the ambertools manual.

Parameters:
  • mol (moldesign.Molecule) – Molecule to set up
  • forcefields (List[str]) – list of the names of forcefields to use (see AmberTools manual for descriptions)
  • parameters (List[ExtraAmberParameters]) – (optional) list of amber parameters for non-standard residues
  • engine (pyccc.Engine) – Engine to run this job on (default: moldesign.compute.get_engine())
  • image (str) – URL for the docker image
  • wait (bool) – if True, block until this function completes and return the function’s return value. Otherwise, return a job object immediately that can be queried later.
  • jobname – argument for moldesign.compute.compute.run_job()
  • display (bool) – if True, show logging output for this job

References

Ambertools Manual, http://ambermd.org/doc12/Amber16.pdf. See page 33 for forcefield recommendations.

3.1.5. assign_formal_charges function

moldesign.assign_formal_charges(mol, ignore_nonzero=True)[source]

Assign formal charges to C,N,O,F atoms in this molecule based on valence

Parameters:
  • mol (moldesign.Molecule) – Molecule to assign formal charges to. The formal charges of its atoms and its total charge will be adjusted in place.
  • ignore_nonzero (bool) – If formal charge is already set to a nonzero value, ignore this atom

Note

This method ONLY applies to C,N, O and F, based on a simple valence model. These results should be manually inspected for consistency.

Raises:UnhandledValenceError – for cases not handled by the simple valence model

References

These assignments are illustrated by the formal charge patterns in
http://www.chem.ucla.edu/~harding/tutorials/formalcharge.pdf

3.1.6. build_assembly function

moldesign.build_assembly(mol, assembly_name)[source]

Create biological assembly using a bioassembly specification.

This routine builds a biomolecular assembly using the specification from a PDB header (if present, this data can be found in the “REMARK 350” lines in the PDB file). Assemblies are author-assigned structures created by copying, translating, and rotating a subset of the chains in the PDB file.

See also

http://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies

Parameters:
  • mol (moldesign.Molecule) – Molecule with assembly data (assembly data will be created by the PDB parser at molecule.properties.bioassembly)
  • assembly_name (str OR int) – id of the biomolecular assembly to build.
Returns:

mol – molecule containing the complete assembly
Return type:

moldesign.Molecule
Raises:
  • AttributeError – If the molecule does not contain any biomolecular assembly data
  • KeyError – If the specified assembly is not present

3.1.7. build_bdna function

moldesign.build_bdna(sequence, **kwargs)[source]

Uses Ambertools’ Nucleic Acid Builder to build a 3D double-helix B-DNA structure.

Parameters:
  • sequence (str) – DNA sequence for one of the strands (a complementary sequence will automatically be created)
  • engine (pyccc.Engine) – Engine to run this job on (default: moldesign.compute.get_engine())
  • image (str) – URL for the docker image
  • wait (bool) – if True, block until this function completes and return the function’s return value. Otherwise, return a job object immediately that can be queried later.
  • jobname – argument for moldesign.compute.compute.run_job()
  • display (bool) – if True, show logging output for this job
Returns:

B-DNA double helix
Return type:

moldesign.Molecule

3.1.8. build_dna_helix function

moldesign.build_dna_helix(sequence, helix_type='B', **kwargs)[source]

Uses Ambertools’ Nucleic Acid Builder to build a 3D DNA double-helix.

Parameters:
  • sequence (str) – DNA sequence for one of the strands (a complementary sequence will automatically be created)
  • helix_type (str) – Type of helix - ‘A’=Arnott A-DNA ‘B’=B-DNA (from standard templates and helical params), ‘LB’=Langridge B-DNA, ‘AB’=Arnott B-DNA, ‘SB’=Sasisekharan left-handed B-DNA
  • engine (pyccc.Engine) – Engine to run this job on (default: moldesign.compute.get_engine())
  • image (str) – URL for the docker image
  • wait (bool) – if True, block until this function completes and return the function’s return value. Otherwise, return a job object immediately that can be queried later.
  • jobname – argument for moldesign.compute.compute.run_job()
  • display (bool) – if True, show logging output for this job

All helix types except ‘B’ are taken from fiber diffraction data (see the refernce for details)

Returns:B-DNA double helix
Return type:moldesign.Molecule

References

See NAB / AmberTools documentation: http://ambermd.org/doc12/Amber16.pdf, pg 771-2

3.1.9. calc_am1_bcc_charges function

moldesign.calc_am1_bcc_charges(mol, **kwargs)[source]

Calculate am1 bcc charges

Parameters:mol (moldesign.Molecule) – assign partial charges to this molecule (they will be stored at mol.properties['am1-bcc'])

Note

This will implicity run an AM1 energy minimization before calculating the final partial charges. For more control over this process, use the moldesign.models.SQMPotential energy model to calculate the charges.

Returns:AM1-BCC partial charges on each atom
Return type:Mapping[moldesign.Atom, units.Scalar[charge]]

3.1.10. calc_gasteiger_charges function

moldesign.calc_gasteiger_charges(mol, **kwargs)[source]

Calculate gasteiger charges

Parameters:mol (moldesign.Molecule) – assign partial charges to this molecule
Returns:
gasteiger partial charges on each atom
(they will be stored at mol.properties['gasteiger'])
Return type:Mapping[moldesign.Atom, units.Scalar[charge]]

3.1.11. guess_bond_orders function

moldesign.guess_bond_orders(mol, wait=True)[source]

Use OpenBabel to guess bond orders using geometry and functional group templates.

Parameters:mol (moldesign.Molecule) – Molecule to perceive the bonds of
Returns:New molecule with assigned bonds
Return type:moldesign.Molecule

3.1.12. guess_histidine_states function

moldesign.guess_histidine_states(mol)[source]

Attempt to assign protonation states to histidine residues.

Note

This function is highly unlikely to give accurate results! It is intended for convenience when histidine states can easily be guessed from already-present hydrogens or when they are judged to be relatively unimportant.

This can be done simply by renaming HIS residues:
  1. If HE2 and HD1 are present, the residue is renamed to HIP
  2. If only HE2 is present, the residue is renamed to HIE
  3. Otherwise, the residue is renamed to HID (the most common form)
Parameters:mol (moldesign.Molecule) – molecule to change (in place)

3.1.13. mutate function

moldesign.mutate(mol, mutationmap, wait=True)[source]

3.1.14. parameterize function

moldesign.parameterize(mol, charges='esp', ffname='gaff2', **kwargs)[source]

Parameterize mol, typically using GAFF parameters.

This will both assign a forcefield to the molecule (at mol.ff) and produce the parameters so that they can be used in other systems (e.g., so that this molecule can be simulated embedded in a larger protein)

Note

‘am1-bcc’ and ‘gasteiger’ partial charges will be automatically computed if necessary. Other charge types must be precomputed.

Parameters:
  • mol (moldesign.Molecule) –
  • charges (str or dict) –
    what partial charges to use? Can be a dict ({atom:charge}) OR
    a string, in which case charges will be read from

    mol.properties.[charges name]; typical values will be ‘esp’, ‘mulliken’, ‘am1-bcc’, etc. Use ‘zero’ to set all charges to 0 (for QM/MM and testing)

  • ffname (str) – Name of the gaff-like forcefield file (default: gaff2)
Returns:

Parameters for the molecule; this object can be used to create

forcefield parameters for other systems that contain this molecule
Return type:

ExtraAmberParameters

3.2. Unexported API

3.2.1. ATNUM_VALENCE_CHARGE

tools.ATNUM_VALENCE_CHARGE = {8: {1: -1, 2: 0, 3: 1}, 9: {1: 0, 2: 1}, 6: {3: -1, 4: 0}, 7: {2: -1, 3: 0, 4: 1}}

3.2.2. ION_CHARGE

tools.ION_CHARGE = {1: 1, 19: 1, 20: 2, 53: -1, 35: -1, 17: -1, 9: -1, 11: 1, 12: 2}