Class SbcUtil

A class for writing substructure/constraint files to accompany jobname.com.

MacroModel has different ways to define freely moving, restrained and constrained atoms. A good understanding of the SUBS/FXAT behavior is often essential; see the MacroModel Reference Manual for more details. Below are a few examples of some common idioms.

This class now support ASL2 with half-width flat-bottomed restraint potential. If self.use_flat_bottom_asl2 is True, then the ASL2 arguments are formatted thus:

   ASL2 arg1 = Flat-bottom width, in units of tenths of an angstrom.
   ASL2 arg2 = Force constant.
   ASL2 arg3 = Atom selection language string

otherwise, ASL2 argument are formated as:

   ASL2 arg1 = Force constant. 
   ASL2 arg2 = Atom selection language string

API examples:

   # Example 1 ############################################################
   # Writing a sbc file to restrain atoms during a minimization with ASL2.

   # Write com file instructions for a simple geometry optimization.
   # The ComUtil instance is configured such that it will write the
   # SUBS opcode in the com file.
   import schrodinger.application.macromodel.utils as mmodutils
   mcu = mmodutils.ComUtil(subs=True)
   com_file = mcu.mini("example_1.mae")
   # MacroModel requires that the sbc file name match the input
   # structure file, not the com file.
   sbc_file = 'example_1.sbc' 

   # Write sbc file that will modify the geometry optimization such that
   # all atoms are harmonically restrained about their starting coordinates.
   sbu = mmodutils.SbcUtil()
   sbu.ASL2[1] = 200 # force constant for Cartesian restraints.
   sbu.ASL2[2] = 'mol.n 1' # ASL identifying the restrained atoms.
   sbu_args = [sbc_file, 'ASL2']
   sbu.writeSbcFile(sbu_args)


   # Example 2 ############################################################
   # Writing a sbc file to perform a conformation search on part of a
   # structure with ASL1/ASL2.

   # Write com file instructions for a simple conformation search.
   # The ComUtil instance is configured such that it will write the
   # SUBS opcode in the com file.
   import schrodinger.application.macromodel.utils as mmodutils
   mcu = mmodutils.ComUtil(subs=True)
   mcu.MCMM[1] = 100 # Short test search.
   com_file = mcu.mcmm("example_2.mae")
   # MacroModel requires that the sbc file name match the input
   # structure file, not the com file.
   sbc_file = "example_2.sbc" 

   # Write an sbc file that will modify the search such that
   # only sidechain atoms are assigned search parameters and sampled.
   sbu = mmodutils.SbcUtil()
   sbu.ASL1[1] = 0 # Add the substructure atoms (set up for search).
   sbu.ASL1[2] = 'sidechain' # Substructure atoms (set up for search).

   sbu.ASL2[1] = 250 # Restraint's harmonic force constant.
   sbu.ASL2[2] = 'not sidechain' # The restrained atoms. 
   sbu_args = [sbc_file, 'ASL1', 'ASL2']
   sbu.writeSbcFile(sbu_args)


   # Example 3 ############################################################
   # Writing a sbc file to restrain/constrain part of the structure
   # with SUBS/FXAT during a simple minimization. Here, the input
   # structure is a ligand-receptor complex where the ligand has
   # residue name MTW. The ligand will be freely optimized within the
   # context of the receptor. The side-chain atoms will be fixed
   # (restrained with a flat-bottom potential, 0.1 angstrom half-width)
   # and a ~3 angstrom shell of nearby atoms will be frozen
   # (constrained). All other atoms are ignored.

   # Write com file instructions for a simple geometry optimization.
   # The ComUtil instance is configured such that it will write the
   # SUBS opcode in the com file.
   import schrodinger.application.macromodel.utils as mmodutils
   import schrodinger.structure as structure
   import schrodinger.structutils.analyze as analyze
   mcu = mmodutils.ComUtil(subs=True)
   com_file = mcu.mini("example_3.mae")
   sbc_file = "example_3.sbc" 

   # Identify the atoms to optimize, restrain and constrain. All other
   # atoms are ignored.
   st = structure.StructureReader("example_3.mae").next()
   ligand_atoms = analyze.evaluate_asl(st, 'res.pt MTW')
   binding_site_atoms = analyze.evaluate_asl(
       st,
       'fillres (sidechain and within 5 res.pt MTW)'
   )
   nearby_atoms = analyze.evaluate_asl(
       st,
       'not (res.pt MTW or fillres (sidechain and within 5 res.pt MTW)) and within 10 res.pt MTW'
   )

   # Assign the atoms to SUBS and FXAT commands.
   sbu = mmodutils.SbcUtil()
   sbu_args = [sbc_file]
   sbu_args.extend(sbu.setSubs(ligand_atoms))
   sbu_args.extend(
       sbu.setFixed(
           binding_site_atoms,
           force_constant=500,
           half_width=1
       )
   )
   sbu_args.extend(sbu.setFrozen(nearby_atoms))
   sbu.writeSbcFile(sbu_args)


   # Example 4 ############################################################
   # Writing a sbc file to restrain/constrain part of the structure
   # with ASL1/ASL2, where the input is a series of non-conformers.
   # Here, the structure file contains a series of non-conformer
   # polypeptides. The side-chains will be freely optimized and the
   # backbone will be restrained. Note well, READ arg1=-1 tells
   # MacroModel to evaluate the sbc for each input structure; a
   # requirement since the input are non-conformers.

   # Write com file instructions for a geometry optimization on a
   # series of structures. The ComUtil instance is configured such
   # that it will write the SUBS opcode in the com file.
   import schrodinger.application.macromodel.utils as mmodutils
   mcu = mmodutils.ComUtil(subs=True)
   mcu.READ[1] = -1 # re-evaluate substructure information.
   com_file = mcu.mini("example_4.mae")
   sbc_file = "example_4.sbc"

   # Assign the ASL1/2 commands and write the file.
   sbu = mmodutils.SbcUtil()
   sbu.ASL1[1] = 0 # Add the substructure atoms (set up for search).
   sbu.ASL1[2] = 'sidechain' # Substructure atoms (set up for search).
   sbu.ASL2[1] = 200 # Restraint's harmonic force constant.
   sbu.ASL2[2] = 'not sidechain' # The restrained atoms. 
   sbu_args = [sbc_file, 'ASL1', 'ASL2']
   sbu.writeSbcFile(sbu_args)


   # Example 5 ############################################################
   # Writing a sbc file to restrain part of the structure with
   # ASL1/ASL2 and flat-bottom restraints. Here, the structure file
   # contains a series of non-conformer polypeptides. The side-chains
   # will be freely optimized and the backbone will be restrained.
   # Note well, READ arg1=-1 which tells MacroModel to evaluate the sbc
   # for each input structure; a requirement since the input are
   # non-conformers.

   # Write com file instructions for a geometry optimization on a
   # series of structures. The ComUtil instance is configured such
   # that it will write the SUBS opcode in the com file.
   import schrodinger.application.macromodel.utils as mmodutils
   mcu = mmodutils.ComUtil(subs=True)
   mcu.READ[1] = -1 # re-evaluate substructure information.
   com_file = mcu.mini("example_5.mae")
   sbc_file = "example_5.sbc"

   # Assign the ASL1/2 commands and write the file.
   sbu = mmodutils.SbcUtil(use_flat_bottom_asl2=True)
   sbu.ASL1[1] = 0 # Add the substructure atoms (set up for search).
   sbu.ASL1[2] = 'sidechain' # Substructure atoms (set up for search).
   sbu.ASL2[1] = 5 # half-width, 0.5 angstroms. 
   sbu.ASL2[2] = 200.0 # restrain 200 kJ/mol*A^2.
   sbu.ASL2[3] = 'not sidechain' # The restrained atoms. 
   sbu_args = [sbc_file, 'ASL1', 'ASL2']
   sbu.writeSbcFile(sbu_args)


   # Example 6 ############################################################
   # Writing a sbc file to restrain atoms during a minimization
   # with ASL2, confirming backwards compatible support for
   # determining a suitable sbc file name.

   # Write com file instructions for a simple geometry optimization.
   # The ComUtil instance is configured such that it will write the
   # SUBS opcode in the com file.
   import schrodinger.application.macromodel.utils as mmodutils
   mcu = mmodutils.ComUtil(subs=True)
   com_file = mcu.mini("example_6.mae", "example_6_test.com")

   # Write sbc file that will modify the geometry optimization such that
   # all atoms are harmonically restrained about their starting coordinates.
   sbu = mmodutils.SbcUtil()
   sbu.ASL2[1] = 200 # force constant for Cartesian restraints.
   sbu.ASL2[2] = 'mol.n 1' # ASL identifying the restrained atoms.
   sbu_args = [com_file, 'ASL2']

   # MacroModel requires that the sbc file name match the input
   # structure file, not the com file.  The method expects a
   # sbc file name as the first argument, but for backwards
   # compatibility, supports .com extensions. 
   sbc_file = sbu.writeSbcFile(sbu_args)

Writes a sbc file for the list of opcodes, and returns the name
of the written sbc file.

@param sbc_args:
    List of arguments to serialize.  The first element should be
    the file name to write, e.g. 'jobname.sbc', where the sbc
    file name corresponds to the input structure file name not
    the input com file name.  The second and subsequent elements
    should be OPCD strings.
@type sbc_args:
    list

@raises:
    ValueError if the first element doesn't end with .sbc and
    an appropriate sbc file name can't be determined.

The arguments for the OPCDs are looked up in turn, evaluating
the next eight list elements for the specific OPCD argument
list, each time the OPCD is encountered.  See getOpcdArgs()
and __init__() for more information about default arguments.
For backwards compatibility, the first argument may also be a
'.com', which will write basename.sbc if the com file can't
be read, but will otherwise inspect the com file for the input
structure file name and construct a suitable sbc file name.