<filename>modules/pymol/editing.py
#A* -------------------------------------------------------------------
#B* This file contains source code for the PyMOL computer program
#C* Copyright (c) Schrodinger, LLC. 
#D* -------------------------------------------------------------------
#E* It is unlawful to modify or remove this copyright notice.
#F* -------------------------------------------------------------------
#G* Please see the accompanying LICENSE file for further information. 
#H* -------------------------------------------------------------------
#I* Additional authors of this source file include:
#-* 
#-* 
#-*
#Z* -------------------------------------------------------------------

from __future__ import print_function

if __name__=='pymol.editing':

    import pymol
    import math
    from . import selector
    cmd = __import__("sys").modules["pymol.cmd"]
    from .cmd import _cmd,lock,unlock,Shortcut,is_string, \
          boolean_sc,boolean_dict,safe_list_eval, is_sequence, \
          DEFAULT_ERROR, DEFAULT_SUCCESS, _raising, is_ok, is_error              
    from chempy import cpv
    
    ref_action_dict = {
        'store'     : 1,
        'recall'    : 2,
        'validate'  : 3,
        'swap'      : 4,
    }

    ref_action_sc = Shortcut(ref_action_dict.keys())
    
    def reference(action='validate', selection='(all)',
                  state=0, quiet=1, _self=cmd):
        r = DEFAULT_ERROR
        if is_string(action):
            action = ref_action_sc.auto_err(action,"action")
            action = ref_action_dict[action]
        else:
            action = int(action)
        selection = selector.process(selection)           
        try:
            _self.lock(_self)
            r = _cmd.reference( _self._COb, int(action), str(selection),
                               int(state)-1, int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r
    
    def sculpt_purge(_self=cmd):
        '''
DESCRIPTION

    "sculpt_purge" is an unsupported feature.
    
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.sculpt_purge(_self._COb)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def sculpt_deactivate(object, _self=cmd):
        '''
DESCRIPTION

    "sculpt_deactivate" deactivates sculpting for the given object and
    clears the stored restraints.

ARGUMENTS

    object = str: name of a single object or "all"

SEE ALSO

    sculpt_activate
    '''
        r = 0
        try:
            _self.lock(_self)
            r = _cmd.sculpt_deactivate(_self._COb,str(object))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def sculpt_activate(object, state=0, match_state=-1, 
                        match_by_segment=0, _self=cmd):
        '''
DESCRIPTION

    "sculpt_activate" enables sculpting for the given object. The current
    geometry (bond lengths, angles, etc.) of the given state is remembered as
    the reference geometry.

ARGUMENTS

    object = str: name of a single object or "all"

    state = int: object state or 0 for current state {default: 0}

SEE ALSO

    sculpt_iterate, sculpt_deactivate
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.sculpt_activate(_self._COb,str(object),
                                     int(state)-1,
                                     int(match_state)-1,
                                     int(match_by_segment))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def split_states(object, first=1, last=0, prefix=None, _self=cmd):
        '''
DESCRIPTION

    "split_states" separates a multi-state molecular object into a set
    of single-state molecular objects.

USAGE

    split_states object [, first [, last [, prefix ]]]
    
EXAMPLE

    load docking_hits.sdf
    split_states docking_hits, prefix=hit
    delete docking_hits
    
SEE ALSO

    join_states
        '''
        r = DEFAULT_SUCCESS
        prefix_set = bool(prefix)
        first=int(first)
        last=int(last)
        prefix_a = first - 1

        # support selections, not only objects
        sele = _self.get_unused_name('_sele_Abnqh5s5VS')
        _self.select(sele, object, 0)

        # all names to check for name conflicts
        names = set(_self.get_names('all'))

        # iterate over objects
        for object in _self.get_object_list(sele):
            olast = _self.count_states('%' + object)

            if 0 < last < olast:
                olast = last

            for a in range(first, olast + 1):
                name = None
                if prefix_set:
                    prefix_a += 1
                else:
                    prefix_a = a
                    prefix = object + "_"
                    name = _self.get_title(object,a)

                if not name:
                    name = prefix + "%04d" % prefix_a
                elif name in names:
                    name = _self.get_unused_name(name)
                names.add(name)

                r = _self.create(name, "?%s & ?%s" % (sele, object), a, 1)

                if is_error(r): 
                    break

        _self.delete(sele)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r
     
    def sculpt_iterate(object, state=0, cycles=10, _self=cmd):
        '''
DESCRIPTION

    "sculpt_iterate" performs a simple energy minimization of atomic
    coordinates based on the geometry restraints which were defined with
    the "sculpt_activate" invocation and which are selected in the
    "sculpt_field_mask" setting. Sculpting currently supports local
    geometry restraints and vdw repulsion, but no solvation or
    electrostatic effects.

ARGUMENTS

    object = str: name of a single object or "all"

    state = int: object state or 0 for current state {default: 0}

    cycles = int: number of iterations {default: 10}

SEE ALSO

    commands: sculpt_activate, sculpt_deactivate
    settings: "sculpting" setting, all "sculpt_*" settings
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.sculpt_iterate(_self._COb,str(object),int(state)-1,int(cycles))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def smooth(selection="all", passes=1, window=5, first=1,
               last=0, ends=0, quiet=1, _self=cmd):

        '''
DESCRIPTION

    "smooth" performs a window average of coordinate states.  

USAGE

    smooth [ selection [, passes [, window [, first [, last [, ends]]]]]]

ARGUMENTS

    ends = 0 or 1: controls whether or not the end states are also smoothed
    using a weighted asymmetric window

NOTES

    This type of averaging is often used to suppress high-frequency
    vibrations in a molecular dynamics trajectory.

    This function is not memory efficient.  For reasons of
    flexibility, it uses two additional copies of every atomic
    coordinate for the calculation.  If you are memory-constrained in
    visualizing MD trajectories, then you may want to use an external
    tool such as ptraj to perform smoothing before loading coordinates
    into PyMOL.

SEE ALSO

    load_traj

    '''
        
        r = DEFAULT_ERROR
        selection = selector.process(selection)   
        try:
            _self.lock(_self)
            r = _cmd.smooth(_self._COb,str(selection),int(passes),int(window),
                                 int(first)-1,int(last)-1,int(ends),int(quiet))

        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def set_state_order(name, order, quiet=1, _self=cmd):
        '''
DESCRIPTION

    API only. Set the order of states for an object.

ARGUMENTS

    name = str: object name

    order = list of int: index array (1-based state indices)

EXAMPLE

    # reverse the order of a 20 model object
    cmd.set_state_order('1nmr', range(20, 0, -1))
        '''
        with _self.lockcm:
            return _cmd.set_state_order(_self._COb, name, [i - 1 for i in order])

    def set_discrete(name, discrete=1, quiet=1, _self=cmd):
        '''
DESCRIPTION

    Convert discrete to non-discrete object or vice versa.
        '''
        with _self.lockcm:
            return _cmd.set_discrete(_self._COb, name, int(discrete))

    def set_symmetry(selection, a, b, c, alpha, beta, gamma, spacegroup="P1", state=-1, _self=cmd):

        '''
DESCRIPTION

    "set_symmetry" defines or redefines the crystal and spacegroup
    parameters for a molecule or map object.

USAGE

    set_symmetry selection, a, b, c, alpha, beta, gamma, spacegroup

NOTES

    The new symmetry will be defined for every object referenced
    by the selection.

PYMOL API

    cmd.set_symmetry(string selection, float a, float b, float c,
          float alpha, float beta, float gamma, string spacegroup)

        '''
        r = DEFAULT_ERROR
        selection = selector.process(selection)
        try:
            _self.lock(_self)
            r = _cmd.set_symmetry(_self._COb,str(selection), int(state) - 1,
                                         float(a),float(b),float(c),
                                         float(alpha),float(beta),float(gamma),
                                         str(spacegroup))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def symmetry_copy(source_name='', target_name='', source_state=1, target_state=1, target_undo=1, log=0, quiet=1, _self=cmd):
        """
DESCRIPTION

    "symmetry_copy" copies symmetry information from one object to another.

USAGE

    symmetry_copy source_name, target_name, source_state, target_state

NOTES

    Maps support accessing and setting states other than the first,
    but molecular objects do not.

    New in PyMOL v1.5.

PYMOL API

    cmd.symmetry_copy(source_name, target_name, source_state, target_state,
        target_undo, log, quiet)

        """

        r = DEFAULT_ERROR

        suspend_undo = _self.get("suspend_undo")
        fin = 1
        push_undo(target_name, just_coordinates=0, finish_undo=0, _self=_self)
        _self.set("suspend_undo", 1, updates=0)

        if source_name == None:
            source_name = ''

        target_name = str(target_name).strip()
        source_name = str(source_name).strip()

        # ignored for now
        source_mode = 1
        target_mode = 1
        
        try:
            _self.lock(_self)
            
            r = _cmd.symmetry_copy(_self._COb,str(source_name),
                                   str(target_name),
                                   int(source_mode),
                                   int(target_mode),
                                   int(source_state)-1,
                                   int(target_state)-1,
                                   int(target_undo),
                                   int(log),
                                   int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self):
            _self.set("suspend_undo", suspend_undo, updates=0)
            fin = -1
            push_undo("", just_coordinates=0, finish_undo=fin, _self=_self)
            raise pymol.CmdException            

            _self.set("suspend_undo", suspend_undo, updates=0)
            push_undo("", just_coordinates=0, finish_undo=fin, _self=_self)

        return r


    def set_name(old_name, new_name,_self=cmd):
        '''
DESCRIPTION

    "set_name" changes the name of an object or selection.
    
USAGE

    set_name old_name, new_name
    
PYMOL API

    cmd.set_name(string old_name, string new_name)

        '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.set_name(_self._COb,str(old_name),
                                    str(new_name))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def set_geometry(selection, geometry, valence, _self=cmd):
        '''
DESCRIPTION

    "set_geometry" changes PyMOL\'s assumptions about the proper valence
    and geometry of atoms in the selection.

USAGE

    set_geometry selection, geometry, valence

NOTES

    Immature functionality. See code for details.

PYMOL API

    cmd.set_geometry(string selection, int geometry, int valence)

SEE ALSO

    remove, attach, fuse, bond, unbond
    '''
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        try:
            _self.lock(_self)
            r = _cmd.set_geometry(_self._COb,str(selection),int(geometry),int(valence))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def undo(_self=cmd):
        '''
DESCRIPTION

    "undo" restores the previous conformation of the object currently
    being edited.

USAGE

    undo

SEE ALSO

    redo, push_undo
    '''
        r = DEFAULT_ERROR      
        try:
            _self.lock(_self)
            r = _cmd.undo(_self._COb,-1)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def push_undo(selection, just_coordinates=1, finish_undo=0, add_objects=0, delete_objects=0, state=0, _self=cmd):
        '''
DESCRIPTION

    "push_undo" stores the current conformations of objects in the
    selection onto their individual undo rings.

    Notice: This command is only partly implemented in open-source PyMOL.

USAGE

    push_undo (all)

SEE ALSO

    undo, redo
    '''
        # preprocess selections
        selection = selector.process(selection)
        #
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.push_undo(_self._COb,"("+str(selection)+")",int(state)-1)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def redo(_self=cmd):
        '''
DESCRIPTION

    "redo" reapplies the conformational change of the object currently
    being edited.

USAGE

    redo

SEE ALSO

    undo, push_undo
    '''
        r = DEFAULT_ERROR      
        try:
            _self.lock(_self)
            r = _cmd.undo(_self._COb,1)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException                     
        return r

    order_dict = {
    # simulation 
        '0'         : 0,
        '1'         : 1,
        '2'         : 2,
        '3'         : 3,
        '4'         : 4,
        'aromatic'  : 4,
        'guess'     : -1,
        'copy'      : -2
    }

    order_sc = Shortcut(order_dict.keys())

    def valence(order, selection1=None, selection2=None, source='',
                target_state=0, source_state=0, reset=1,
                quiet=1, _self=cmd):
        '''
DESCRIPTION

    "valence" modifies the valences of all existing bonds formed
    between two atom selections.
    
USAGE

    valence 2, (name C), (name O)

PYMOL API

    cmd.valence(string selection1, selection2)

SEE ALSO

    unbond, fuse, attach, replace, remove_picked
    '''
        if is_string(order):
            order = order_sc.auto_err(order,"order")
            order = order_dict[order]
        else:
            order = int(order)
        r = DEFAULT_ERROR
        # preprocess selections
        if selection1 == None:
            selection1="(pk1)"
            if selection2 == None:
                selection2="(pk2)"
        if selection2 == None:
            selection2 = selection1
        selection1 = selector.process(selection1)
        selection2 = selector.process(selection2)
        if source!='':
            source = selector.process(source)
        try:
            _self.lock(_self)
            if order>=0:
                r = _cmd.bond(_self._COb, "("+selection1+")", "("+selection2+")", int(order), 2, int(quiet))
            else:
                r = _cmd.revalence(_self._COb,
                                   "("+selection1+")",
                                   "("+selection2+")",
                                   str(source), 
                                   int(target_state)-1, int(source_state)-1,
                                   int(reset), int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def bond(atom1="(pk1)", atom2="(pk2)", order=1, edit=1, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "bond" creates a new bond between two selections, each of which
    should contain one atom.

USAGE

    bond [atom1, atom2 [,order]]

NOTES

    The atoms must both be within the same object.

    The default behavior is to create a bond between the (lb) and (rb)
    selections.

PYMOL API

    cmd.bond(string atom1, string atom2)

SEE ALSO

    unbond, fuse, attach, replace, remove_picked
    '''
        r = DEFAULT_ERROR
        # preprocess selections
        atom1 = selector.process(atom1)
        atom2 = selector.process(atom2)
        try:
            _self.lock(_self)
            r = _cmd.bond(_self._COb,
                          atom1, atom2,
                          int(order),1,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def invert(quiet=1, _self=cmd):
        '''
DESCRIPTION

    "invert" inverts the stereo-chemistry of atom (pk1), holding attached atoms
    (pk2) and (pk3) immobile.

USAGE

    invert 

NOTES

    The invert function is usually bound to CTRL-E in Editing Mode.

PYMOL API

    cmd.invert( )

    '''
        r = DEFAULT_ERROR
        # preprocess selections
        #
        try:
            _self.lock(_self)
            r = _cmd.invert(_self._COb,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise cmd.QuietException
        return r

    def unbond(atom1="(pk1)", atom2="(pk2)", quiet=1, _self=cmd):
        '''
DESCRIPTION

    "unbond" removes all bonds between two selections.

USAGE

    unbond atom1,atom2

ARGUMENTS

    atom1 = string {default: (pk1)}

    atom2 = string {default: (pk2)}

PYMOL API

    cmd.unbond(selection atom1, selection atom2)

SEE ALSO

    bond, fuse, remove_picked, attach, detach, replace

    '''
        r = DEFAULT_ERROR
        # preprocess selections
        atom1 = selector.process(atom1)
        atom2 = selector.process(atom2)   
        try:
            _self.lock(_self)
            r = _cmd.bond(_self._COb,
                          atom1, atom2,
                          0,0,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def remove(selection, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "remove" eleminates the atoms in a selection from their respective
    molecular objects.

USAGE

    remove selection

EXAMPLES

    remove resi 124 

PYMOL API

    cmd.remove( string selection )

SEE ALSO

    delete
    '''
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        #   
        r = 1
        try:
            _self.lock(_self)   
            r = _cmd.remove(_self._COb,"("+selection+")",int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def remove_picked(hydrogens=1,quiet=1,_self=cmd):
        '''
DESCRIPTION

    "remove_picked" removes the atom or bond currently picked for
    editing.

USAGE

    remove_picked [ hydrogens ]

NOTES

    This function is usually connected to the
    DELETE key and "CTRL-D".

    By default, attached hydrogens will also be deleted unless
    hydrogen-flag is zero.

PYMOL API

    cmd.remove_picked(integer hydrogens)

SEE ALSO

    attach, replace
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.remove_picked(_self._COb,int(hydrogens),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def cycle_valence(h_fill=1, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "cycle_valence" cycles the valence on the currently selected bond.

USAGE

    cycle_valence [ h_fill ]

ARGUMENTS

    h_fill = 0 or 1: updated hydrogens too? {default: 1 (yes)}
    
EXAMPLE

    cycle_valence

NOTES

    If the h_fill flag is true, hydrogens will be added or removed to
    satisfy valence requirements.

    This function is usually connected to the DELETE key and "CTRL-W".

PYMOL API

    cmd.cycle_valence(int h_fill)

SEE ALSO

    remove_picked, attach, replace, fuse, h_fill
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.cycle_valence(_self._COb,quiet)
        finally:
            _self.unlock(r,_self)
        if h_fill:
            globals()['h_fill'](quiet)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def attach(element,geometry,valence,name='',quiet=1,_self=cmd):
        '''
DESCRIPTION

    "attach" adds a single atom on to the picked atom.

USAGE

    attach element, geometry, valence

PYMOL API

    cmd.attach( element, geometry, valence )

    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.attach(_self._COb,str(element),int(geometry),int(valence),str(name))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def fuse(selection1="(pk1)", selection2="(pk2)", 
             mode=0, recolor=1, move=1, _self=cmd):
        '''
DESCRIPTION

    "fuse" joins two objects into one by forming a bond.  A copy of
    the object containing the first atom is moved so as to form an
    approximately resonable bond with the second, and that copy is
    then merged with the first object.

USAGE

    fuse [ selection1 [, selection2 [, mode [, recolor [, move ]]]]]

ARGUMENTS

    selection1 = str: single atom selection (will be copied to object 2)

    selection2 = str: single atom selection

    mode = int: {default: 0}
      3: don't move and don't create a bond, just combine into single object

    recolor = bool: recolor C atoms to match target {default: 1}

    move = bool: {default: 1}

NOTES

    Each selection must include a single atom in each object.
    The atoms can both be hydrogens, in which case they are
    eliminated, or they can both be non-hydrogens, in which
    case a bond is formed between the two atoms.

SEE ALSO

    bond, unbond, attach, replace, fuse, remove_picked
    '''
        r = DEFAULT_ERROR
        # preprocess selections
        selection1 = selector.process(selection1)
        selection2 = selector.process(selection2)
        #   
        try:
            _self.lock(_self)
            r = _cmd.fuse(_self._COb,str(selection1),str(selection2),
                              int(mode),int(recolor),int(move))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def unpick(_self=cmd):
        '''
DESCRIPTION

    "unpick" deletes the special "pk" atom selections (pk1, pk2, etc.)
    used in atom picking and molecular editing.

USAGE

    unpick

PYMOL API

    cmd.unpick()

SEE ALSO

    edit
        '''
        
        r = DEFAULT_ERROR      
        try:
            _self.lock(_self)   
            r = _cmd.unpick(_self._COb)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def drag(selection=None, wizard=1, edit=1, quiet=1, mode=-1, _self=cmd):
        '''
DESCRIPTION

    "drag" activates dragging for a selection, enabling the user to
    manipulate the atom coordinates of the atoms using mouse controls
    similar to those for controlling the camera.

USAGE

    drag [ selection ]

ARGUMENTS
  
    selection = string: atoms to drag.  If not provided, and dragging
    is active, then dragging is instead deactivated.

NOTES

    Currently, the selection of atom to drag must all reside in a
    single molecular object.

'''
        quiet = int(quiet)
        if (selection!=None) and (selection!=""):
            selection = selector.process(selection)
            if is_string(edit):
                edit=boolean_dict[boolean_sc.auto_err(edit,'boolean')]
            if is_string(wizard):
                wizard=boolean_dict[boolean_sc.auto_err(wizard,'boolean')]
            edit = int(edit)
            wizard = int(wizard)
            old_button_mode = _self.get('button_mode')
        else:
            wizard = 0
            edit = 0
            selection = ""
        #
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.drag(_self._COb,str(selection),int(quiet),int(mode))
        finally:
            _self.unlock(r,_self)
        if not is_error(r):
            if edit:
                _self.edit_mode(edit)
            if wizard:
                wiz = _self.get_wizard()
                if (wiz == None):
                    _self.wizard("dragging",old_button_mode)
                elif wiz.__class__ != 'pymol.wizard.dragging.Dragging':
                    _self.wizard("dragging",old_button_mode)
                else:
                    wiz.recount()
        if _self._raising(r,_self): raise pymol.CmdException
        return r
        
    def edit(selection1='', selection2='none', selection3='none',
             selection4='none', pkresi=0, pkbond=1, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "edit" picks atoms or a bond for editing.

USAGE

    edit selection1 [, selection2 [, selection3 [, selection4 [, pkresi [, pkbond ]]]]] 

NOTES

    If only one selection is provided, an atom is picked.

    If two selections are provided, the bond between them
    is picked (by default, if one exists).

PYMOL API

    cmd.edit(string selection1, string selection2,
             string selection3, string selection4,
             int pkresi, int pkbond, int quiet)

SEE ALSO

    unpick, remove_picked, cycle_valence, torsion
    '''
        # preprocess selections
        selection1 = selector.process(selection1)
        selection2 = selector.process(selection2)
        selection3 = selector.process(selection3)
        selection4 = selector.process(selection4)
        #
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.edit(_self._COb,str(selection1),str(selection2),
                              str(selection3),str(selection4),
                              int(pkresi),int(pkbond),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException
        return r

    def get_editor_scheme(_self=cmd):
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.get_editor_scheme(_self._COb)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def torsion(angle,_self=cmd):
        '''
DESCRIPTION

    "torsion" rotates the torsion on the bond currently
    picked for editing.  The rotated fragment will correspond
    to the first atom specified when picking the bond (or the
    nearest atom, if picked using the mouse).

USAGE

    torsion angle

PYMOL API

    cmd.torsion( float angle )

SEE ALSO

    edit, unpick, remove_picked, cycle_valence
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.torsion(_self._COb,float(angle))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def h_fill(quiet=1, _self=cmd):
        '''
DESCRIPTION

    "h_fill" removes and replaces hydrogens on the atom or bond picked
    for editing.

USAGE

    h_fill

NOTES

    This is useful for fixing hydrogens after changing bond valences.

PYMOL API

    cmd.h_fill()

SEE ALSO

    edit, cycle_valence, h_add
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.h_fill(_self._COb,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def h_fix(selection="",quiet=1,_self=cmd):
        '''
DESCRIPTION

    "h_fix" is an unsupported command that may have something to do
    with repositioning hydrogen atoms.
    
    '''
        # preprocess selection
        selection = selector.process(selection)

        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.h_fix(_self._COb,str(selection),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def h_add(selection="(all)",quiet=1,_self=cmd):
        '''
DESCRIPTION

    "h_add" uses a rudimentary algorithm to add hydrogens onto a
    molecule based on current valences.

USAGE

    h_add selection

ARGUMENTS

    selection = string {default: (all)}

NOTES

    Because PDB files do not normally contain bond valences for
    ligands and other nonstandard components, it may be necessary to
    manually correct ligand conformations before adding hydrogens.

PYMOL API

    cmd.h_add( string selection="(all)" )

SEE ALSO

    h_fill
    '''
        # preprocess selection
        selection = selector.process(selection)
        #   
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)   
            r = _cmd.h_add(_self._COb,selection,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r



    def sort(object="",_self=cmd):
        '''
DESCRIPTION

    "sort" reorders atoms in the structure.  It usually only necessary
    to run this routine after an "alter" command which has modified the
    names of atom properties.  Without an argument, sort will resort
    all atoms in all objects.

USAGE

    sort [object]

PYMOL API

    cmd.sort(string object)

SEE ALSO

    alter
    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.sort(_self._COb,str(object))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def replace(element, geometry, valence, h_fill=1, name="", 
		quiet=1, _self=cmd):
        '''
DESCRIPTION

    "replace" replaces the picked atom with a new atom.

USAGE

    replace element, geometry, valence [, h_fill [, name ]]

NOTES

    Immature functionality. See code for details.

PYMOL API

    cmd.replace(string element, int geometry, int valence, int h_fill,
                string name)

SEE ALSO

    remove, attach, fuse, bond, unbond
    '''
        r = DEFAULT_ERROR      
        if not "pk1" in _self.get_names("selections"):
            print(" Error: you must first pick an atom to replace.")
            raise pymol.CmdException
        try:
            if h_fill: # strip off existing hydrogens
                remove("((neighbor pk1) and elem H)",quiet=quiet)
            _self.lock(_self)
            r = _cmd.replace(_self._COb,str(element),int(geometry),int(valence),str(name),quiet)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def rename(selection="all", force=0, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "rename" creates new atom names which are unique within residues.

USAGE

    rename selection [, force ]

PYMOL API

    cmd.rename(string selection, int force )

SEE ALSO

    alter
    '''
        r = DEFAULT_ERROR   
        selection = "("+selector.process(selection)+")"
        try:
            _self.lock(_self)   
            r = _cmd.rename(_self._COb,str(selection),int(force),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def dss(selection="(all)", state=0, context=None, preserve=0,
            quiet=1, _self=cmd):

        '''
DESCRIPTION

    "dss" defines secondary structure based on backbone geometry
    and hydrogen bonding patterns.
    
USAGE

    dss selection, state

ARGUMENT

    selection = string: {default: (all)}

    state = integer: {default: 0 -- all states}
    
EXAMPLE

    dss

NOTES

    With PyMOL, heavy emphasis is placed on cartoon aesthetics, and so
    both hydrogen bonding patterns and backbone geometry are used in
    the assignment process.  Depending upon the local context, helix
    and strand assignments are made based on geometry, hydrogen
    bonding, or both.

    This command will generate results which differ slightly from DSSP
    and other programs.  Most deviations occur in borderline or
    transition regions.  Generally speaking, PyMOL is more strict, thus
    assigning fewer helix/sheet residues, except for partially
    distorted helices, which PyMOL tends to tolerate.
    
    WARNING: This algorithm has not yet been rigorously validated.

    If you dislike one or more of the assignments made by dss, you can
    use the alter command to make changes (followed by "rebuild").
    For example:
    
        alter 123-125/, ss=\'L\'
        alter pk1, ss=\'S\'
        alter 90/, ss=\'H\'
        rebuild

PYMOL API

    cmd.dss(string selection, int state)
        
        '''
        # preprocess selections
        selection = selector.process(selection)
        r = DEFAULT_ERROR
        if context==None:
            context = ""
        else:
            context = selector.process(context)
        #
        try:
            _self.lock(_self)
            r = _cmd.dss(_self._COb,str(selection),int(state)-1,str(context),
                            int(preserve),int(quiet))
        finally:
            _self.unlock(r,_self)   
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def alter(selection, expression, quiet=1, space=None, _self=cmd):

        '''
DESCRIPTION

    "alter" changes atomic properties using an expression evaluated
    within a temporary namespace for each atom.

USAGE

    alter selection, expression

EXAMPLES

    alter chain A, chain='B'
    alter all, resi=str(int(resi)+100)
    sort

NOTES

    Symbols defined (* = read only):

    name, resn, resi, resv, chain, segi, elem, alt, q, b, vdw, type,
    partial_charge, formal_charge, elec_radius, text_type, label, 
    numeric_type, model*, state*, index*, ID, rank, color, ss,
    cartoon, flags

    All strings must be explicitly quoted.  This operation typically
    takes several seconds per thousand atoms altered.  

    You may need to issue a "rebuild" in order to update associated
    representations.
    
    WARNING: You should always issue a "sort" command on an object
    after modifying any property which might affect canonical atom
    ordering (names, chains, etc.).  Failure to do so will confound
    subsequent "create" and "byres" operations.  

SEE ALSO

    alter_state, iterate, iterate_state, sort
        '''
        if not expression:
            raise pymol.CmdException('missing expression')

        if space == None:
            space = _self._pymol.__dict__
        r = DEFAULT_ERROR
        # preprocess selections
        selection = selector.process(selection)
        #
        try:
            _self.lock(_self)
            r = _cmd.alter(_self._COb,"("+str(selection)+")",str(expression),0,int(quiet),dict(space))
        finally:
            _self.unlock(r,_self)   
        if _self._raising(r,_self): raise pymol.CmdException
        return r

    def alter_list(object, expr_list, quiet=1, space=None, _self=cmd):
        '''
DESCRIPTION

    "alter_list" is an unsupported feature.
    
        '''
        #
        if space == None:
            space = _self._pymol.__dict__
        try:
            _self.lock(_self)
            r = _cmd.alter_list(_self._COb,str(object),list(expr_list),int(quiet),dict(space))
        finally:
            _self.unlock(r,_self)   
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def iterate(selection, expression, quiet=1, space=None, _self=cmd):

        '''
DESCRIPTION

    "iterate" iterates over an expression within a temporary namespace
    for each atom.

USAGE

    iterate selection, expression

EXAMPLES

    stored.net_charge = 0
    iterate all, stored.net_charge = stored.net_charge + partial_charge
    print stored.net_charge
    
    stored.names = []
    iterate all, stored.names.append(name)
    print stored.names
    
NOTES

    Unlike with the "alter" command, atomic properties cannot be
    altered.  For this reason, "iterate" is more efficient than
    "alter".

SEE ALSO

    iterate_state, alter, alter_state
        '''
        if not expression:
            raise pymol.CmdException('missing expression')

        if space == None:
            space = _self._pymol.__dict__
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        #
        try:
            _self.lock(_self)
            r = _cmd.alter(_self._COb,"("+str(selection)+")",str(expression),1,int(quiet),dict(space))
        finally:
            _self.unlock(r,_self)   
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def alter_state(state, selection, expression, quiet=1,
                    space=None, atomic=1, _self=cmd):

        '''
DESCRIPTION

    "alter_state" changes atom coordinates and flags over a particular
    state and selection using the Python evaluator with a temporary
    namespace for each atomic coordinate.

USAGE

    alter_state state, selection, expression

EXAMPLES

    alter_state 1, all, x=x+5
    rebuild
    
NOTES

    By default, most of the symbols from "alter" are available for use
    on a read-only basis.  

    It is usually necessary to "rebuild" representations once your
    alterations are complete.
    
SEE ALSO

    iterate_state, alter, iterate
        '''
        if not expression:
            raise pymol.CmdException('missing expression')

        if space == None:
            space = _self._pymol.__dict__
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        #
        state = int(state)
        try:
            _self.lock(_self)
            r = _cmd.alter_state(_self._COb,
                                 int(state)-1,"("+str(selection)+")",
                                 str(expression),
                                 0,int(atomic),int(quiet),dict(space))
        finally:
            _self.unlock(r,_self)   
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def iterate_state(state, selection, expression, quiet=1, 
                      space=None, atomic=1, _self=cmd):

        '''
DESCRIPTION

    "iterate_state" is to "alter_state" as "iterate" is to "alter"

USAGE

    iterate_state state, selection, expression

EXAMPLES

    stored.sum_x = 0.0
    iterate_state 1, all, stored.sum_x = stored.sum_x + x
    print stored.sum_x
    
SEE ALSO

    iterate, alter, alter_state
        '''
        if not expression:
            raise pymol.CmdException('missing expression')

        r = DEFAULT_ERROR
        if space == None:
            space = _self._pymol.__dict__
        # preprocess selection
        selection = selector.process(selection)
        state = int(state)
        #
        try:
            _self.lock(_self)
            r = _cmd.alter_state(_self._COb,int(state)-1,"("+str(selection)+")",
                                        str(expression),1,int(atomic),
                                        int(quiet),dict(space))
        finally:
            _self.unlock(r,_self)   
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def translate(vector=[0.0,0.0,0.0], selection="all", state=-1, 
                  camera=1, object=None, object_mode=0, _self=cmd):

        '''
DESCRIPTION

    "translate" translates the atomic coordinates of atoms in a
    selection.  Alternatively, is modifies the matrix associated with
    a particular object or object-state.

USAGE

    translate vector [, selection [, state [, camera [, object ]]]]

ARGUMENTS

    vector = float vector: translation vector

    selection = string: atoms whose coordinates should be modified {default: all}

    state > 0: only the indicated state is modified

    state = 0: all states are modified

    state = -1: only current state is modified {default}

    camera = 0 or 1: is the vector in camera coordinates? {default: 1 (yes)}

    object = string: object name (only if rotating object matrix) {default: None}


PYMOL API

    cmd.translate(list vector, string selection, int state, int
                  camera, string object)

EXAMPLES

    translate [1,0,0], name CA

NOTES

    "translate" can be used to translate the atomic coordinates of a
    molecular object.  Behavior differs depending on whether or not
    the "object" parameter is specified.

    If object is None, then translate translates atomic coordinates
    according to the vector provided for the selection and in the state
    provided.  All representation geometries will need to be
    regenerated to reflect the new atomic coordinates.

    If object is set to an object name, then selection is ignored and
    instead of translating the atomic coordinates, the object\'s
    overall representation display matrix is modified.  This option is
    for use in animations only.

    The "camera" option controls whether the camera or the model\'s
    axes are used to interpret the translation vector.

        '''
        r = DEFAULT_ERROR
        object_mode = int(object_mode)
        if _self.is_string(vector):
            vector = safe_list_eval(vector)
        if not _self.is_sequence(vector):
            print("Error: bad vector.")
            raise pymol.CmdException
        else:
            vector = [float(vector[0]),float(vector[1]),float(vector[2])]
            selection = selector.process(selection)
            camera=int(camera)
            view = _self.get_view(0)
            if camera:
                mat = [ view[0:3],view[3:6],view[6:9] ]
                shift = cpv.transform(mat,vector)
            else:
                shift = vector
            if object==None:
                ttt = [1.0,0.0,0.0,shift[0],
                         0.0,1.0,0.0,shift[1],
                         0.0,0.0,1.0,shift[2],
                         0.0,0.0,0.0,1.0]
                r=_self.transform_selection(selection,ttt,state=state)
            elif object_mode==0: # update the TTT display matrix
                try:
                    _self.lock(_self)
                    r=_cmd.translate_object_ttt(_self._COb,str(object),shift)
                finally:
                    _self.unlock(r,_self)
            elif object_mode==1: # either updates TTT or coordinates & history
                     # depending on the current matrix mode
                matrix = [1.0, 0.0, 0.0, shift[0],
                          0.0, 1.0, 0.0, shift[1],
                          0.0, 0.0, 1.0, shift[2],
                          0.0, 0.0, 0.0, 1.0]
                try:
                    _self.lock(_self)
                    r = _cmd.transform_object(_self._COb,str(object),int(state)-1,
                                                      list(matrix),0,'',1)
                finally:
                    _self.unlock(r,_self)
            else:
                print(" Error: translate: unrecognized object_mode")
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def rotate(axis='x', angle=0.0, selection="all", state=-1, camera=1, 
               object=None, origin=None, object_mode=0, _self=cmd):
        
        '''
DESCRIPTION

    "rotate" rotates the atomic coordinates of atoms in a selection
    about an axis.  Alternatively, it modifies the matrix associated
    with a particular object or object state.

USAGE

    rotate axis, angle [, selection [, state [, camera [, object 
        [, origin ]]]]]

ARGUMENTS

    axis = x, y, z, or float vector: axis about which to rotate

    angle = float: degrees of rotation

    selection = string: atoms whose coordinates should be modified {default: all}
    
    state > 0: only the indicated state is modified

    state = 0: all states are modified

    state = -1: only the current state is modified {default}

    camera = 0 or 1: is the axis specific in camera coordinates? {default: 1}

    object = string: object name (only if rotating object matrix) {default: None}

    origin = float vector: origin of rotateion {default: None}
        
EXAMPLES

    rotate x, 45, pept

    rotate [1,1,1], 10, chain A

NOTES

    Behavior differs depending on whether or not the "object"
    parameter is specified.

    If object is None, then the atomic coordinates are modified
    directly, and all representation geometries will need to be
    regenerated to reflect the new atomic coordinates.

    If object is set to an object name, then the selection field is
    ignored and instead of translating the atomic coordinates, the
    object matrix is modified.  This option is only intended for use
    in animations and is not yet fully supported.

PYMOL API

    cmd.rotate(list-or-string axis, float angle, string selection, 
               int state, int camera, string object)

        '''
        r = DEFAULT_ERROR
        object_mode = int(object_mode)
        have_origin = 0
        if axis in ['x','X']:
            axis = [1.0,0.0,0.0]
        elif axis in ['y','Y']:
            axis = [0.0,1.0,0.0]
        elif axis in ['z','Z']:
            axis = [0.0,0.0,1.0]
        else:
            axis = safe_list_eval(str(axis))
        if not _self.is_list(axis):
            print("Error: bad axis.")
            raise pymol.CmdException
        else:
            axis = [float(axis[0]),float(axis[1]),float(axis[2])]
            angle = math.pi*float(angle)/180.0
            view = _self.get_view(0)
            if origin!=None:
                have_origin = 1
                if _self.is_string(origin):
                    if ',' in origin:
                        origin = safe_list_eval(origin) # should be a sequence of floats
                    else:
                        _self.lock(_self)
                        try:
                            origin = _cmd.get_origin(_self._COb,str(origin))
                        finally:
                            unlock(-1)
                origin = [float(origin[0]),float(origin[1]),float(origin[2])]
            else:
                origin = [view[12],view[13],view[14]]
            camera=int(camera)
            if camera:
                vmat = [ view[0:3],view[3:6],view[6:9] ]
                axis = cpv.transform(vmat,axis)
            mat = cpv.rotation_matrix(angle,axis)
            if object==None:
                ttt = [mat[0][0],mat[0][1],mat[0][2],origin[0],                   
                       mat[1][0],mat[1][1],mat[1][2],origin[1],
                       mat[2][0],mat[2][1],mat[2][2],origin[2],
                       -origin[0],-origin[1],-origin[2], 1.0]
                r=_self.transform_selection(selection,ttt,state=state)
            elif object_mode==0:
                _self.lock(_self)
                try:
                    if not have_origin:
                        origin = _cmd.get_origin(_self._COb,str(object))
                    if is_sequence(origin):
                        ttt = [mat[0][0],mat[0][1],mat[0][2], origin[0],
                               mat[1][0],mat[1][1],mat[1][2], origin[1],
                               mat[2][0],mat[2][1],mat[2][2], origin[2],
                               -origin[0], -origin[1], -origin[2], 1.0]
                        r=_cmd.combine_object_ttt(_self._COb,str(object),ttt)
                finally:
                    _self.unlock(r,_self)
                if not is_sequence(origin):
                    print(" Error: rotate: unknown object '%s'."%object)
                    if _self._raising(r,_self):
                        raise pymol.CmdException                                
            elif object_mode==1:
                
                matrix = [mat[0][0],mat[0][1],mat[0][2], origin[0],     
                          mat[1][0],mat[1][1],mat[1][2], origin[1],
                          mat[2][0],mat[2][1],mat[2][2], origin[2],
                          -origin[0],-origin[1],-origin[2], 1.0]
                try:
                    _self.lock(_self)
                    r = _cmd.transform_object(_self._COb,str(object),int(state)-1,
                                                      list(matrix),0,'',0)
                finally:
                    _self.unlock(r,_self)
                
            else:
                print(" Error: rotate: unrecognized object_mode")
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def set_title(object, state, text, _self=cmd):
        '''
DESCRIPTION

    "set_title" attaches a text string to the state of a particular
    object which can be displayed next to the object name when that
    state is active.  This is useful for display the energies of a set
    of conformers.

USAGE

    set_title object, state, text

PYMOL API

    cmd.set_title(string object, int state, string text)

    '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.set_title(_self._COb,str(object),int(state)-1,str(text))
        finally:
            _self.unlock(r,_self)

    def set_object_ttt(object, ttt, state=0, quiet=1, homogenous=0, 
                       _self=cmd):
        '''
DESCRIPTION

    "set_object_ttt" is an API-only function which sets the TTT matrix
    (view transformation) for an object.

    When a movie is defined and the object has key frames for object
    motions, then the key frames take priority and update the TTT matrix
    while the movie is playing.

    Unlike a homogenous matrix where the last row is always [0,0,0,1],
    a TTT matrix may have a pre-translation vector in the last row.

ARGUMENTS

    object = str: object name

    ttt = list of 16 floats: TTT matrix

    state = int: UNUSED, TTT matrices are not state specific

    homogenous = 0/1: NAME IS MISLEADING AND IMPLEMENTATION
    POSSIBLY WRONG! If 1, then transpose the input matrix and
    set the last column (post-translation) to [0,0,0,1].

SEE ALSO

    cmd.transform_object, cmd.matrix_reset
        '''
        r = None
        if _self.is_string(ttt):
            ttt = safe_list_eval(str(ttt))
        if homogenous: # passed a homogenous matrix, so do the best we can
            ttt = [ # NOTE: this appears to be incorrect...
                ttt[ 0], ttt[ 4], ttt[ 8], 0.0,
                ttt[ 1], ttt[ 5], ttt[ 9], 0.0,
                ttt[ 2], ttt[ 6], ttt[10], 0.0,
                ttt[ 3], ttt[ 7], ttt[11], 1.0]
        try:
            _self.lock(_self)
            r = _cmd.set_object_ttt(_self._COb,str(object),
				    (float(ttt[ 0]),
				     float(ttt[ 1]),
				     float(ttt[ 2]),
				     float(ttt[ 3]),            
				     float(ttt[ 4]),
				     float(ttt[ 5]),
				     float(ttt[ 6]),
				     float(ttt[ 7]),            
				     float(ttt[ 8]),
				     float(ttt[ 9]),
				     float(ttt[10]),
				     float(ttt[11]),            
				     float(ttt[12]),
				     float(ttt[13]),
				     float(ttt[14]),
				     float(ttt[15])),
				    int(state)-1,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def transform_selection(selection, matrix, state=-1, log=0, 
                            homogenous=0, transpose=0, _self=cmd):
        '''

DESCRIPTION

    "transform_selection" transforms the atomic coordinates of a
    selection.

PYMOL API
   
    cmd.transform_selection(string selection, list matrix, int state,
                            int log, int homogenous, int transpose):

NOTES

    Note that when homogenous is zero, the input matrix is NOT a
    standard homogenous 4x4 transformation matrix.  Instead it is
    something PyMOL-specific which consists of the following:

    1) a 3x3 matrix containing the rotation in the upper-left quadrant

    2) a 1x3 translation to be applied *before* rotation in the bottom row
        (matrix[12],matrix[13],matrix[14]).

    3) a 3x1 translation to be applied *after* rotation in the right-hand
        column (matrix[3],matrix[7],matrix[11])

    In other words, if the matrix is:

    [  m0  m1  m2  m3 \\
       m4  m5  m6  m7 \\
       m8  m9 m10 m11 \\
      m12 m13 m14 m15 ] 

    Atoms will be transformed as follows

    Y = M X

    y0 = m0*(x0+m12) + m1*(x1+m13) +  m2*(x2+m14) + m3 \\
    y1 = m4*(x0+m12) + m5*(x1+m13) +  m6*(x2+m14) + m7 \\
    y2 = m8*(x0+m12) + m9*(x1+m13) + m10*(x2+m14) + m11 

        '''
        r = DEFAULT_ERROR
        selection = selector.process(selection)
        if int(transpose):
            matrix = [ matrix[0], matrix[4], matrix[8 ], matrix[12],
                       matrix[1], matrix[5], matrix[9 ], matrix[13],
                       matrix[2], matrix[6], matrix[10], matrix[14],
                       matrix[3], matrix[7], matrix[11], matrix[15]]
        try:
            _self.lock(_self)
            r = _cmd.transform_selection(_self._COb,str(selection),int(state)-1,
                                                  list(matrix),int(log),int(homogenous))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def transform_object(name, matrix, state=-1, log=0, selection='',
                         homogenous=0, transpose=0, _self=cmd):
        '''
DESCRIPTION

    "transform_object" in an API-only function which applies a
    transformation matrix to an object.

    If setting "matrix_mode" > 0 and selection is empty, then this
    function operates on the TTT (movie) matrix.

ARGUMENTS

    name = str: object name

    matrix = list of 16 floats: transformation matrix

    state = int: object state {default: -1}

    log = 0/1: write action to log file (only applies if object is a
    molecular object) {default: 0}

    selection = str: atom selection (only applies to molecular objects,
    if empty then the whole object state is transformed).

    homogenous = 0/1: if 0, then matrix[12:15] may contain a pre-translation,
    otherwise those values must be zeros (see also cmd.transform_selection)
    {default: 0}

    transpose = 0/1: matrix is 0=row-major, 1=column-major {default: 0}

SEE ALSO

    cmd.transform_selection, cmd.set_object_ttt, cmd.matrix_reset
        '''
        r = DEFAULT_ERROR
        if int(transpose):
            matrix = [ matrix[0], matrix[4], matrix[8 ], matrix[12],
                          matrix[1], matrix[5], matrix[9 ], matrix[13],
                          matrix[2], matrix[6], matrix[10], matrix[14],
                          matrix[3], matrix[7], matrix[11], matrix[15]]
        try:
            _self.lock(_self)
            r = _cmd.transform_object(_self._COb,str(name),int(state)-1,
                                              list(matrix),int(log),
                                              str(selection),
                                              int(homogenous))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def matrix_copy(source_name='', target_name='',
                    source_mode=-1, target_mode=-1,
                    source_state=1, target_state=1,
                    target_undo=1, log=0, quiet=1,
                    _self=cmd):
        '''

DESCRIPTION
        
    "matrix_copy" copies a transformation matrix from one object to
    another.

USAGE

    matrix_copy source_name, target_name

NOTES

    This command is often used after a protein structure alignment to
    bring other related objects into the same frame of reference.

SEE ALSO

    matrix_reset, align, fit, pair_fit
'''
        
        r = DEFAULT_ERROR
        if source_name == None:
            source_name = ''
        target_name = str(target_name).strip()
        source_name = str(source_name).strip()
        if (target_name == '' and source_name != ''): # tentative -- create a new command instead?
            mat = cmd.get_object_matrix(source_name,source_state)
            view = cmd.get_view()
            new_view = (
                mat[ 0]*view[ 0] + mat[ 4]*view[ 3] + mat[ 8]*view[ 6],
                mat[ 0]*view[ 1] + mat[ 4]*view[ 4] + mat[ 8]*view[ 7],  
                mat[ 0]*view[ 2] + mat[ 4]*view[ 5] + mat[ 8]*view[ 8],
                mat[ 1]*view[ 0] + mat[ 5]*view[ 3] + mat[ 9]*view[ 6],
                mat[ 1]*view[ 1] + mat[ 5]*view[ 4] + mat[ 9]*view[ 7],  
                mat[ 1]*view[ 2] + mat[ 5]*view[ 5] + mat[ 9]*view[ 8],
                mat[ 2]*view[ 0] + mat[ 6]*view[ 3] + mat[10]*view[ 6],
                mat[ 2]*view[ 1] + mat[ 6]*view[ 4] + mat[10]*view[ 7],  
                mat[ 2]*view[ 2] + mat[ 6]*view[ 5] + mat[10]*view[ 8],
                view[ 9] ,         view[10] ,         view[11],
                mat[ 0]*view[12] + mat[ 1]*view[13] + mat[ 2]*view[14] -
                mat[ 0]* mat[ 3] - mat[ 4]* mat[ 7] - mat[ 8]* mat[11], 
                mat[ 4]*view[12] + mat[ 5]*view[13] + mat[ 6]*view[14] -
                mat[ 1]* mat[ 3] - mat[ 5]* mat[ 7] - mat[ 9]* mat[11],
                mat[ 8]*view[12] + mat[ 9]*view[13] + mat[10]*view[14] -
                mat[ 2]* mat[ 3] - mat[ 6]* mat[ 7] - mat[10]* mat[11],
                view[15] ,         view[16] ,         view[17] )
            r = cmd.set_view(new_view)
        else:
            try:
                _self.lock(_self)
                r = _cmd.matrix_copy(_self._COb,str(source_name),
                                                 str(target_name),
                                                 int(source_mode),
                                                 int(target_mode),
                                                 int(source_state)-1,
                                                 int(target_state)-1,
                                                 int(target_undo),
                                                 int(log),
                                                 int(quiet))
            finally:
                _self.unlock(r,_self)
            if _self._raising(r,_self):
                raise pymol.CmdException            
        return r

    def matrix_reset(name, state=1, mode=-1, log=0, quiet=1,_self=cmd):
        '''

DESCRIPTION
        
    "matrix_reset" resets the transformation for an object.

USAGE

    matrix_reset name [, state [, mode ]]

ARGUMENTS

    name = str: object name

    state = int: object state {default: 1}

    mode = int: {defualt: -1 = matrix_mode or 0}
      0: transformation was applied to coordinates
      1: reset TTT matrix (movie transformation)
      2: reset state matrix

SEE ALSO

    matrix_copy, align, super, fit, pair_fit
    
'''
        
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.reset_matrix(_self._COb,str(name),
                                         int(mode),
                                         int(state)-1,
                                         int(log),
                                         int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self):
            raise pymol.CmdException            
        return r

        
    def translate_atom(sele1, v0, v1, v2, state=0, mode=0,
                       log=0, _self=cmd):

        r = DEFAULT_ERROR
        sele1 = selector.process(sele1)
        try:
            _self.lock(_self)
            r = _cmd.translate_atom(_self._COb,str(sele1),float(v0),float(v1),
                                            float(v2),int(state)-1,int(mode),int(log))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def update(target, source, target_state=0, source_state=0, 
               matchmaker=1, quiet=1, _self=cmd):

        '''
DESCRIPTION

    "update" transfers coordinates from one selection to another.
USAGE

    update (target-selection),(source-selection)

EXAMPLES

    update target,(variant)

NOTES

    Currently, this applies across all pairs of states.  Fine
    control will be added later.

SEE ALSO

    load
    '''
        r = DEFAULT_ERROR
        a=target
        b=source
        # preprocess selections
        a = selector.process(a)
        b = selector.process(b)
        #
        if a[0]!='(': a="("+str(a)+")"
        if b[0]!='(': b="("+str(b)+")"   
        try:
            _self.lock(_self)   
            r = _cmd.update(_self._COb,str(a),str(b),int(target_state)-1,
                                 int(source_state)-1,int(matchmaker),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r


    def set_dihedral(atom1, atom2, atom3, atom4, angle, state=1, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "set_dihedral" changes the dihedral angle formed between the four
    bonded atoms provided.  The atoms must be acyclic.
    
USAGE

    set_dihedral atom1, atom2, atom3, atom4, angle [, state [, quiet ]]

NOTES

    Because set_dihedral uses the molecular editing capability,
    numbered "pk" atom selections (if any) will be redefined by this
    operation.
    
PYMOL API

    cmd.set_dihedral(string atom1, string atom2, string atom3, string atom4,
                     float angle, int state, int quiet)

    '''
        # preprocess selections
        atom1 = selector.process(atom1)
        atom2 = selector.process(atom2)
        atom3 = selector.process(atom3)
        atom4 = selector.process(atom4)
        #   
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.set_dihe(_self._COb,atom1,atom2,atom3,atom4,
                                    float(angle),int(state)-1,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    map_op_dict = {
        'minimum'       : 0,
        'maximum'       : 1,
        'sum'           : 2,
        'average'       : 3,
        'difference'    : 4,
        'copy'          : 5,
        'unique'        : 6,
        }
    
    map_op_sc = Shortcut(map_op_dict.keys())

    def map_set(name, operator, operands='', target_state=0, 
                source_state=0, zoom=0, quiet=1, _self=cmd):

        '''
DESCRIPTION

    "map_set" provides a number of common operations on and between maps.

USAGE

    map_set name, operator, operands, target_state, source_state

    operator may be "minimum, maximum, average, sum, or difference"

EXAMPLES

    map my_sum, add, map1 map2 map3
    map my_avg, average, map1 map2 map3
    
NOTES

    source_state = 0 means all states
    target_state = -1 means current state
    
    experimental
    
SEE ALSO

    map_new
        '''
        r = DEFAULT_ERROR
        operator_index = map_op_dict[map_op_sc.auto_err(operator,'operator')]
        try:
            _self.lock(_self)
            r = _cmd.map_set(_self._COb,str(name), int(operator_index), str(operands),
                         int(target_state)-1, int(source_state)-1, int(zoom), int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r
            
    def map_set_border(name, level=0.0, state=0, _self=cmd):

        '''
DESCRIPTION

    "map_set_border" is a function (reqd by PDA) which allows you to set the
    level on the edge points of a map

USAGE

    map_set_border name, level

NOTES

    unsupported.
    
SEE ALSO

    load
        '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.map_set_border(_self._COb,str(name),float(level),int(state))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def map_double(name, state=0, _self=cmd):
        '''
DESCRIPTION

    "map_double" resamples a map at twice the current resolution.

NOTES

     The amount of memory required to store the map will increase
     eight-fold.

USAGE

    map_double map_name, state
        '''
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.map_double(_self._COb,str(name),int(state)-1)
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def map_halve(name, state=0, smooth=1, _self=cmd):

        '''
DESCRIPTION

    "map_halve" resamples a map at half the current resolution.  

USAGE

    map_halve map_name, state
    
NOTES

    The amount of memory required to store the map will decrease
    eight-fold.

SEE ALSO

    map_double
        '''

        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.map_halve(_self._COb,str(name),int(state)-1,int(smooth))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def map_trim(name, selection, buffer=0.0, map_state=0, sele_state=0, quiet=1, _self=cmd):
        '''
DESCRIPTION

    "map_trim" is an unsupported command that may have something to do with
    reducing the extent of a map to cover just a single selection of atoms.

    '''
        
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        #   
        try:
            _self.lock(_self)
            r = _cmd.map_trim(_self._COb,str(name),str(selection),
                                  float(buffer),int(map_state)-1,
                                  int(sele_state)-1,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    
    def protect(selection="(all)", quiet=1, _self=cmd):
        '''
DESCRIPTION

    "protect" protects a set of atoms from tranformations performed
    using the editing features.  This is most useful when you are
    modifying an internal portion of a chain or cycle and do not wish
    to affect the rest of the molecule.

USAGE

    protect (selection)

PYMOL API

    cmd.protect(string selection)

SEE ALSO

    deprotect, mask, unmask, mouse, editing
    '''
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        #   
        try:
            _self.lock(_self)   
            r = _cmd.protect(_self._COb,"("+str(selection)+")",1,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def deprotect(selection="(all)", quiet=1, _self=cmd):
        '''
DESCRIPTION

    "deprotect" reverses the effect of the "protect" command.

USAGE

    deprotect (selection)

PYMOL API

    cmd.deprotect(string selection)

SEE ALSO

    protect, mask, unmask, mouse, editing
    '''
        r = DEFAULT_ERROR
        # preprocess selection
        selection = selector.process(selection)
        #   
        try:
            _self.lock(_self)   
            r = _cmd.protect(_self._COb,"("+str(selection)+")",0,int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    flag_dict = {
    # simulation 
        'focus'         : 0,
        'free'          : 1,
        'restrain'      : 2,
        'fix'           : 3,
        'exclude'       : 4,
        'study'         : 5,
        
    # rendering
        'exfoliate'     : 24,
        'ignore'        : 25,
        'no_smooth'     : 26,
    }

    flag_sc = Shortcut(flag_dict.keys())

    flag_action_dict = {
        'reset' : 0,
        'set'   : 1,
        'clear' : 2,
        }

    flag_action_sc = Shortcut(flag_action_dict.keys())

    def fix_chemistry(selection1="all", selection2="all",
		      invalidate=1, quiet=1, _self=cmd):
        '''
DESCRIPTION
   
    "fix chemistry" is an unsupported feature.

'''
        r = DEFAULT_ERROR
        selection1 = selector.process(selection1)
        selection2 = selector.process(selection2)
        try:
            _self.lock(_self)   
            r = _cmd.fix_chemistry(_self._COb,"("+str(selection1)+")",
				   "("+str(selection2)+")",int(invalidate),
				   int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def set_object_color(name, color, quiet=1, _self=cmd):
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.set_object_color(_self._COb,str(name),str(color),int(quiet))
        finally:
            _self.unlock(r,_self)      
        if _raising(r,_self): raise pymol.CmdException
        return r
    
    def flag(flag, selection, action="reset", quiet=1, _self=cmd):
        '''
DESCRIPTION

    "flag" sets the indicated flag for atoms in the selection and
     clears the indicated flag for atoms not in the selection.  

USAGE

    flag flag, selection [, action ]

ARGUMENTS

    action = reset: {default} set flag for atoms in selection and clear it for all others

    action = set: set the flag for atoms in selection, leaving other atoms unchanged

    action = clear: clear the flag for selected atoms, leaving other atoms unchanged

EXAMPLES  

    flag free, (resi 45 x; 6)

NOTES

    This is primarily useful for passing selection information into
    Chempy models, which have a 32 bit attribute "flag" which holds
    this information.

    If the 'auto_indicate_flags' setting is true, then PyMOL will automatically
    create a selection called "indicate" which contains all atoms with that flag
    after applying the command.

    SPECIAL FLAGS

    * Flags 0-7 are reserved for molecular modeling 

        focus      0 = Atoms of Interest (i.e. a ligand in an active site) \\
        free       1 = Free Atoms (free to move subject to a force-field) \\
        restrain   2 = Restrained Atoms (typically harmonically contrained) \\
        fix        3 = Fixed Atoms (no movement allowed) \\
        exclude    4 = Atoms which should not be part of any simulation

    * Flags 8-15 are free for end users to manipulate

    * Flags 16-23 are reserved for external GUIs and linked applications

    * Flags 24-30 are reserved for PyMOL internal usage

        exfoliate 24 = Remove surface from atoms when surfacing \\
        ignore    25 = Ignore atoms altogether when surfacing \\
        no_smooth 26 = Do not smooth atom position

    * Flag 31 is reserved for coverage tracking when assigning parameters, etc.

PYMOL API

    cmd.flag(int flag, string selection, string action="reset",
             int indicate=0)

        '''
        r = DEFAULT_ERROR
        # preprocess selection
        new_flag = flag_sc.interpret(str(flag))
        if new_flag:
            if _self.is_string(new_flag):
                flag = flag_dict[new_flag]
            else:
                flag_sc.auto_err(flag,'flag')
        # preprocess selection
        selection = selector.process(selection)
        action = flag_action_dict[flag_action_sc.auto_err(action,'action')]
        #      
        try:
            _self.lock(_self)
            r = _cmd.flag(_self._COb,int(flag),"("+str(selection)+")",
                              int(action),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException            
        return r

    def vdw_fit(selection1, selection2, state1=1,state2=1,buffer=0.24,quiet=1,_self=cmd):
        '''
DESCRIPTION

    "vdw_fit" is an unsupported feature.
    
    '''
        # preprocess selections
        selection1 = selector.process(selection1)
        selection2 = selector.process(selection2)
        #
        r = DEFAULT_ERROR
        try:
            _self.lock(_self)
            r = _cmd.vdw_fit(_self._COb,str(selection1),int(state1)-1,
                             str(selection2),int(state2)-1,
                             float(buffer),int(quiet))
        finally:
            _self.unlock(r,_self)
        if _self._raising(r,_self): raise pymol.CmdException
        return r

    def split_chains(selection='(all)', prefix=None, group=None, quiet=1, _self=cmd):
        '''
DESCRIPTION

    Create a single object for each chain in selection

SEE ALSO

    split_states
        '''
        count = 0
        models = _self.get_object_list('(' + selection + ')')
        names_list = []
        for model in models:
            for chain in _self.get_chains('(%s) and model %s' % (selection, model)):
                count += 1
                if not prefix:
                    name = '%s_%s' % (model, chain)
                else:
                    name = '%s%04d' % (prefix, count)
                _self.create(name, '(%s) and model %s and chain "%s"' %
                        (selection, model, chain), zoom=0)
                names_list.append(name)
            _self.disable(model)

        if group:
            cmd.group(group, ' '.join(names_list), 'add')

    def alphatoall(selection='polymer', properties='b', operator='byca',
            quiet=1, _self=cmd):
        '''
DESCRIPTION

    Expand any given property of the CA atoms to all atoms in the residue

ARGUMENTS

    selection = string: atom selection {default: polymer}

    properties = string: space separated list of atom properties {default: b}
        '''
        properties = '(' + ','.join(properties.split()) + ')'
        space = {'props': {}}
        _self.iterate('%s (%s)' % (operator, selection),
                'props[model,segi,chain,resi] = ' + properties,
                space=space)
        _self.alter(selection,
                properties + ' = props.get((model,segi,chain,resi), ' + properties + ')',
                space=space)
        if not int(quiet):
            print(' Modified %d residues' % (len(space['props'])))

    def mse2met(selection='all', quiet=1, _self=cmd):
        '''
DESCRIPTION

    Mutate selenomethionine to methionine
        '''
        x = _self.alter('(%s) and MSE/SE' % selection, 'name="SD";elem="S"')
        _self.flag('ignore', '(%s) and resn MSE' % (selection), 'clear')
        _self.alter('(%s) and resn MSE' % selection, 'resn="MET";type="ATOM"')
        if not int(quiet):
            print(' Altered %d MSE residues to MET' % (x))


    def _base(i, numerals, _emptyzero=False):
        if i == 0:
            return '' if _emptyzero else numerals[0]

        b = len(numerals)
        return _base(i // b, numerals, True) + numerals[i % b]


    def uniquify(identifier, selection, reference='', quiet=1, _self=cmd):
        '''
DESCRIPTION

    Make `identifier` unique with respect to reference selection.

ARGUMENTS

    identifier = str: atom identifier (chain, segi, etc.)

    selection = str: atom selection to modify

    reference = str: atom selection whose identifiers must not be
    present in the first selection {default: !selection}

EXAMPLE

    fetch 1a00 1hbb, async=0
    uniquify chain, 1hbb
    # 1hbb now has chains E,F,G,H
        '''
        import itertools
        import string

        if not reference:
            reference = '!(' + selection + ')'

        p = identifier

        set_ref = set()
        set_sel = set()
        mapping = {}
        space = {'set_ref': set_ref, 'set_sel': set_sel, 'mapping': mapping}

        _self.iterate(reference, 'set_ref.add(' + p + ')', space=space)
        _self.iterate(selection, 'set_sel.add(' + p + ')', space=space)

        set_union = set_ref | set_sel
        set_inter = set_ref & set_sel

        if not set_inter:
            return

        baseargs = ()
        i_iter = itertools.count(1)

        if isinstance(next(iter(set_inter)), int):
            basefunc = int
        elif p in ('resi',):
            basefunc = str
        else:
            basefunc = _base
            baseargs = (string.ascii_uppercase + '123456789',)
            i_iter = itertools.count(0)

        for name in set_inter:
            for i in i_iter:
                newname = basefunc(i, *baseargs)
                if newname not in set_union:
                    mapping[name] = newname
                    set_union.add(newname)
                    break

        _self.alter(selection, '%s = mapping.get(%s, %s)' % (p, p, p),
                space=space)

        if not int(quiet):
            print(' Uniquify: renamed %d %s identifier(s)' % (len(mapping), p))


    def copy_to(name, selection, rename='chain segi ID', zoom=-1, quiet=1, _self=cmd):
        '''
DESCRIPTION

    Copies selection to object `name` (all states) and by default
    renames chain, segi and ID identifiers to avoid naming conflicts.

ARGUMENTS

    name = str: object name to modify

    selection = str: atom selection (will be copied to `name`)

    rename = str: space separated list of identifiers to rename
    {default: chain segi ID}

SEE ALSO

    create, fuse
        '''
        temp = _self.get_unused_name('_tmp')

        try:
            _self.create(temp, selection, zoom=0)
            _self.disable(' '.join(_self.get_object_list(selection)))

            for prop in rename.split():
                if prop.upper() == 'ID':
                    _self.alter(temp, 'ID = -1')
                else:
                    uniquify(prop, temp, '?' + name, quiet=quiet)

            _self.create(name, '?' + name + ' ' + temp, zoom=zoom)
            _self.unpick()

            if not int(quiet):
                n = _self.count_atoms(temp)
                print(' Copied %d atoms to object %s' % (n, name))
        finally:
            _self.delete(temp)
