# Restraints and Steering Forces

- General Principles
- General Utilities
- Change Tracking
  - Restraint_Change_Tracker
- Map Steering Forces
  - MDFF_Mgr
  - MDFF_Atom
  - MDFF_Atoms
- Position Restraints
  - Position_Restraint_Mgr
  - Position_Restraint
  - Position_Restraints
- Interactive Tugging Forces
  - Tuggable_Atoms_Mgr
  - Tuggable_Atom
  - Tuggable_Atoms
- Distance Restraints
  - Distance_Restraint_Mgr
  - Distance_Restraint
  - Distance_Restraints
- Adaptive Distance Restraints
  - Adaptive_Distance_Restraint_Mgr
  - Adaptive_Distance_Restraint
  - Adaptive_Distance_Restraints
- Proper Dihedral Restraints
  - Proper_Dihedral_Restraint_Mgr
  - Proper_Dihedral_Restraint
  - Proper_Dihedral_Restraints
- Chirality Restraints
  - Chiral_Restraint_Mgr
  - Chiral_Restraint
  - Chiral_Restraints
- Rotamer Restraints
  - Rotamer_Restraint_Mgr
  - Rotamer_Restraint
  - Rotamer_Restraints

## General Principles

Virtually all manipulations of the model in ISOLDE are achieved via the use of custom forces implemented in the OpenMM API. Most of these need to be visualised in some way - it is generally a bad idea to have a custom restraint imposed if it’s easy to forget it’s there!

While not all of the manager classes described below, each is implemented as a `chimerax.Model` subclass for simplicity and easy housekeeping. With the exception of `MDFF_Mgr` (which is placed below the `chimerax.Volume` holding the map it manages), each manager will appear as a child model to the main `chimerax.AtomicStructure`.

## General Utilities

> ..automethod:: restrain_torsions_to_template

> ..automethod:: restrain_ca_distances_to_template

> ..automethod:: restrain_small_ligands

## Change Tracking

### Restraint_Change_Tracker

> class `chimerax.isolde.restraints.``Restraint_Change_Tracker`(session, c_pointer=None)

>   A per-session singleton tracking changes in ISOLDE restraints, and firing triggers as necessary. It should very rarely be necessary to work with this class directly. Each individual `_Restraint_Mgr` subclass instance has its own `TriggerSet`, and `Restraint_Change_Tracker` will fire the ‘changes’ trigger in the appropriate instances whenever necessary. If you wish to create a new type of restraint class, it will need to register itself with the `Restraint_Change_Tracker` at the C++ level.

>   `__init__`(session, c_pointer=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `deleted`

>     Has the C++ side been deleted?

## Map Steering Forces

### MDFF_Mgr

> class `chimerax.isolde.restraints.``MDFF_Mgr`(model, volume, c_pointer=None)

>   Manages the molecular dynamics flexible fitting (MDFF) steering forces for one map. Appears as a Model to provide a consistent API to all the other restraint manager classes, but doesn’t actually draw anything. Unlike other restraint manager classes, it lives as a child to the `chimerax.Volume` holding the map it manages.

>   The preferred way to create/retrieve the MDFF manager for a given `AtomicStructure` instance m and `Volume` instance is:

>       from chimerax.isolde import session_extensions as sx
>       mdff_mgr = sx.get_mdff_mgr(m, v)

>   `__init__`(model, volume, c_pointer=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_mdff_atoms`(atoms, hydrogens=False)

>     Returns a `MDFF_Atoms` instance covering the atoms in the input. Only one `MDFF_Atom` will ever be created for a given atom, so it is safe to use this repeatedly on the same set of atoms. Use this method when you want to ensure that all atoms in the input will be properly coupled to the map in simulations.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>       - hydrogens:
>           - should hydrogens be coupled to the map? Setting this to True will substantially increase the amount of computation required and empirically seems to make little difference to the result.
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `enabled`

>     Turns this potential on/off in simulations

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_mdff_atoms`(atoms)

>     Returns a `MDFF_Atoms` instance covering the atoms in the input. Unlike `add_mdff_atoms()`, no new `MDFF_Atom` will be created. Use this method when you’ve already coupled all the atoms you want to this map, and don’t want to accidentally add more.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `global_k`

>     Global coupling constant applied to all atoms (scales the individual atom coupling constants). Effective units are

>   `guess_global_k`(distance_cutoff=3, percentile=80, scaling_constant=5)

>     Guesses a reasonable value for the global coupling constant defining how strongly the map “pulls” on atoms, based on the steepness of the map gradients in the vicinity of the model. The map is first masked down to voxels within distance_cutoff of the model, and the gradient at each voxel is calculated based on linear interpolation of surrounding voxels. The gradients are ranked in increasing order of value, and the the value at the given percentile is selected. The final global_k is selected such that .

>     Args:
>       - distance_cutoff:
>           - mask radius in Angstroms
>       - percentile:
>           - defines the gradient value to be selected for the weighting calculation
>       - scaling constant:
>           - Defines the final strength of the map forces (larger value = stronger pull)
>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Should be overridden in derived classes.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `volume`

>     The Volume object providing the MDFF potential for the managed atoms.

### MDFF_Atom

> class `chimerax.isolde.restraints.``MDFF_Atom`(c_pointer)

>   A thin wrapper around a `chimerax.Atom` to handle its coupling to a molecular dynamics flexible fitting potential derived from a volumetric map.

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `atom`

>     Returns the ChimeraX Atom. Read only.

>   `coupling_constant`

>     Per-atom MDFF coupling constant. This is multiplied by the global coupling constant for the map when calculating the MDFF potential. Can be set.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `deleted`

>     Has the C++ side been deleted?

>   `enabled`

>     Enable/disable MDFF tugging on this atom or get its current state.

>   `sim_index`

>     Index of this atom in the relevant MDFF Force in a running simulation. Returns -1 if the atom is not currently in a simulation. Can be set, but only if you know what you are doing.

### MDFF_Atoms

> class `chimerax.isolde.restraints.``MDFF_Atoms`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `atoms`

>     Returns the `chimerax.Atom`. Read only.

>   `clear_sim_indices`()

>     Run at the end of a simulation to reset `sim_indices` to -1.

>   `coupling_constants`

>     Per-atom MDFF coupling constants. These are multiplied by the global coupling constant for the map when calculating the MDFF potentials. Can be set.

>   `enableds`

>     Enable/disable MDFF tugging on each atom or get the current states.

>   `sim_indices`

>     Index of each atom in the relevant MDFF Force in a running simulation. Atoms which are not currently in a simulation have indices equal to -1. Can be set, but only if you know what you are doing.

## Position Restraints

### Position_Restraint_Mgr

> class `chimerax.isolde.restraints.``Position_Restraint_Mgr`(model, c_pointer=None)

>   Manages creation, deletion, mapping and drawing of position restraints for a single atomic structure. Appears as a child `chimeraX.Model` under the `chimerax.AtomicStructure` it manages.

>   The preferred way to create/retrieve the position restraint manager for a given `AtomicStructure` instance m is:

>       from chimerax.isolde import session_extensions as sx
>       pr_mgr = sx.get_position_restraint_mgr(m)

>   `__init__`(model, c_pointer=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_restraint`(atom)

>     Singular form of `add_restraints()`, returning a `Position_Restraint` instance (or None if the atom is not restrainable).

>     Args:
>       - atom:
>           - a `chimerax.Atom` instance
>   `add_restraints`(atoms)

>     Returns a `Position_Restraints` instance covering the non-hydrogen atoms in the input. Hydrogen atoms are unrestrainable by design, since their low mass can easily cause instability with strong restraints. Only one `Position_Restraint` will ever be created for a given atom, so it is safe to use this repeatedly on the same set of atoms. Use this method when you want to ensure that all atoms in the input will be restrainable in simulations.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_restraint`(atom)

>     Singular form of `get_restraints()`, returning a `Position_Restraint` instance (or None if no restraint exists for this atom).

>     Args:
>       - atom:
>           - a `chimerax.Atom` instance
>   `get_restraints`(atoms)

>     Returns a `Position_Restraints` instance covering the atoms in the input. Unlike `add_restraints()`, no new `Position_Restraint` will be created. Use this method when you’ve already defined all the restraints you need, and don’t want to accidentally add more.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `num_restraints`

>     Number of restraints currently managed by this manager.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_bond_color`(color)

>     Set the colour of the dashed bond connecting each restrained atom to its target pin.

>     Args:
>       - color:
>           - an iterable of four integers (0..255) representing the (r,g,b,a) colour values
>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_pin_color`(color)

>     Set the colour of the pins used to represent position restraints.

>     Args:
>       - color:
>           - an iterable of four integers (0..255) representing the (r,g,b,a) colour values
>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`(update_bonds=True, update_targets=True)

>     Update the restraints drawing. Happens automatically every time restraints or coordinates change. It should rarely/never be necessary to call this manually.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `visible_restraints`

>     Returns a `Position_Restraints` instance containing only the currently visible restraints. A restraint will be visible if it is enabled and its atom is visible. Note that it is not possible to hide an enabled restraint independent of its atom, other than by hiding the entire restraint manager. This is by design: hiding of individual restraints will lead to trouble if the user subsequently forgets they are there.

### Position_Restraint

> class `chimerax.isolde.restraints.``Position_Restraint`(c_pointer)

>   Defines a user-adjustable and -switchable harmonic spring connecting an atom to a fixed point in space.

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `atom`

>     Returns the restrained `chimerax.Atom`. Read-only.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `deleted`

>     Has the C++ side been deleted?

>   `enabled`

>     Enable/disable this position restraint.

>   `sim_index`

>     Index of this restraint in the associated force object in a running simulation. Returns -1 if the restraint is not part of any simulation. Can be set, but only if you know what you are doing.

>   `spring_constant`

>     Restraint spring constant in . Can be written

>   `target`

>     Target (x,y,z) position in Angstroms. Can be written.

>   `target_vector`

>     Returns the vector (“bond”) connecting the atom to its target. Read only.

>   `visible`

>     Check whether this restraint is currently visible. Read only.

### Position_Restraints

> class `chimerax.isolde.restraints.``Position_Restraints`(c_pointers=None, single_type=None, poly_type=None)
>   `__init__`(c_pointers=None, single_type=None, poly_type=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `atoms`

>     Returns the restrained `chimerax.Atoms`. Read-only.

>   `clear_sim_indices`()

>     Run at the end of a simulation to reset `sim_indices` to -1.

>   `enableds`

>     Enable/disable position restraints with a Numpy boolean array.

>   `sim_indices`

>     Index of each restraint in the associated force object in a running simulation. Restraints tha are not part of a simulation have indices of -1. Can be set, but only if you know what you are doing.

>   `spring_constants`

>     Restraint spring constants in . Can be written

>   `target_vectors`

>     Returns the vectors (“bonds”) connecting each atom to its target. Read only.

>   `targets`

>     Target (x,y,z) positions in Angstroms. Can be written.

>   `visibles`

>     Returns a boolean mask giving the currently visible restraints. Read only.

## Interactive Tugging Forces

NOTE: The classes `Tuggable_Atom` and `Tuggable_Atoms` are simply wrappers over `Position_Restraint` and `Position_Restraints` respectively, with no API changes.

### Tuggable_Atoms_Mgr

> class `chimerax.isolde.restraints.``Tuggable_Atoms_Mgr`(model, c_pointer=None)

>   Manages creation, deletion and mapping of `Position_Restraint` objects to act as interactive tugging forces, and drawing of the applied force vectors. Appears as a child `chimeraX.Model` under the `chimerax.AtomicStructure` it manages.

>   The preferred way to create/retrieve the tuggable atoms manager for a given `AtomicStructure` instance m is:

>       from chimerax.isolde import session_extensions as sx
>       ta_mgr = sx.get_tuggable_atoms_mgr(m)

>   `__init__`(model, c_pointer=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_tuggable`(atom)

>     Singular form of `get_tuggable()`, returning a `Tuggable_Atom` instance (or None if the atom is not tuggable).

>     Args:
>       - atom:
>           - a `chimerax.Atom` instance
>   `add_tuggables`(atoms)

>     Returns a `Tuggable_Atoms` instance covering the non-hydrogen atoms in the input. Hydrogen atoms cannot be tugged by design, since their low mass can easily cause instability with strong forces. Only one `Position_Restraint` will ever be created for a given atom, so it is safe to use this repeatedly on the same set of atoms. Use this method when you want to ensure that all atoms in the input will be tuggable in simulations.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `get_tuggables`(atoms)

>     Returns a `Tuggable_Atoms` instance covering the atoms in the input. Unlike `add_tuggables()`, no new `Position_Restraint` will be created.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `num_tuggables`

>     Number of tuggable atoms currently managed by this manager.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_arrow_color`(color)

>     Set the colour applied to the arrows used to represent the tugging force vector(s).

>     Args:
>       - color:
>           - an (r,g,b,a) iterable of 4 integers in the range (0..255)
>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Update the force vector drawing. Happens automatically every time restraints or coordinates change. It should rarely/never be necessary to call this manually.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `visibles`

>     Returns a `Tuggable_Atoms` instance containing only those tuggables with currently-visible force vectors. A vector will be visible if and only if the its associated atom is both visible and currently being tugged.

### Tuggable_Atom

> See `Positon_Restraint`

### Tuggable_Atoms

> See `Position_Restraints`

## Distance Restraints

### Distance_Restraint_Mgr

> class `chimerax.isolde.restraints.``Distance_Restraint_Mgr`(model, c_pointer=None)

>   Manages distance restraints (Atom pairs with distances and spring constants) and their visualisations for a single atomic structure. Appears as a child `chimerax.Model` under the `chimerax.AtomicStructure` it manages.

>   The preferred way to create/retrieve the distance restraint manager for a given `AtomicStructure` instance m is:

>       from chimerax.isolde import session_extensions as sx
>       dr_mgr = sx.get_distance_restraint_mgr(m)

>   `__init__`(model, c_pointer=None)

>     Prepare a distance restraint manager for a given atomic model.

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_restraint`(atom1, atom2)

>     Creates and returns a `Distance_Restraint` between the given atoms if possible, or returns the existing one if it already exists. Note that distance restraints can be added to a running simulation, but will trigger an expensive (a few seconds) reinitialisation of the simulation context.

>     Args:
>       - atom1, atom2:
>           - `chimerax.Atom` instances. Both atoms must be in the `chimerax.AtomicStructure` belonging to this manager, must not be the same atom or directly bonded to each other, and should not be hydrogens.
>   `add_ss_restraints`(residues)

>     Creates and returns a tuple of two `Distance_Restraints` instances containing restraints suitable for restraining secondary structure. The first, O(n) - N(n+4) defines the classic alpha helical H-bonds. The second, CA(n) - CA^(n+2) is useful for “stretching out” beta strands as well as cross-bracing helices. Useful target differences for restraining specific secondary structures can be retrieved from restraints.constants.ss_restraints.

>     Args:
>       - residues:
>           - a `chimerax.Residues` instance. All residues must be in the model belonging to this manager.
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `all_restraints`

>     Returns a `Distance_Restraints` instance encompassing all restraints owned by this manager.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `atom_restraints`(atom)

>     Returns a `Distance_Restraints` instance encompassing all distance restraints involving the given atom.

>     Args:
>       - atom:
>           - a `chimerax.Atom` instance from the `chimerax.AtomicStructure` belonging to this manager.
>   `atoms_restraints`(atoms)

>     Returns a `Distance_Restraints` instance encompassing all distance restraints involving at least one of the atoms. If you want only restraints where both atoms are in the set, use `intra_restraints()` instead.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance. All atoms must be part of the `chimerax.AtomicStructure` belonging to this manager.
>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_restraint`(atom1, atom2)

>     Returns the `Distance_Restraint` between the given atoms if it exists, otherwise None.

>     Args:
>       - atom1, atom2:
>           - `chimerax.Atom` instances. Both atoms must be in the `chimerax.AtomicStructure` belonging to this manager.
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `get_ss_restraints`(residues)

>     Identical to `add_ss_restraints()`, but does not add any new restraints.

>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `intra_restraints`(atoms)

>     Returns a `Distance_Restraints` instance encompassing all distance restraints for which both atoms are in the input set.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance. All atoms must be part of the `chimerax.AtomicStructure` belonging to this manager.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_bond_color`(color)

>     Set the colour of the cylinder representing the distance restraint.

>     Args:
>       - color:
>           - an iterable of four integers (0..255) representing the (r,g,b,a) colour values
>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_target_color`(color)

>     Set the colour of the cylinder representing the target distance.

>     Args:
>       - color:
>           - an iterable of four integers (0..255) representing the (r,g,b,a) colour values
>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Update the restraints drawing. Happens automatically every time restraints or coordinates change. It should rarely/never be necessary to call this manually.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `visible_restraints`

>     Returns a `Distance_Restraints` instance encompassing all currently visible restraints owned by this manager. A restraint will be visible if it is enabled and both its atoms are visible.

### Distance_Restraint

> class `chimerax.isolde.restraints.``Distance_Restraint`(c_pointer)

>   Defines a harmonic spring restraining the distance between a pair of atoms.

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `atoms`

>     Returns a tuple of `chimerax.Atoms` pointing to the pair of restrained atoms. Read only.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `deleted`

>     Has the C++ side been deleted?

>   `distance`

>     Current distance between restrained atoms in Angstroms. Read only.

>   `enabled`

>     Enable/disable this restraint or get its current state.

>   `sim_index`

>     Index of this restraint in the relevant MDFF Force in a running simulation. Returns -1 if the restraint is not currently in a simulation. Can be set, but only if you know what you are doing.

>   `spring_constant`

>     Restraint spring constant in

>   `target`

>     Target distance in Angstroms

>   `visible`

>     Restraint will be visible if it is enabled and both atoms are visible.

### Distance_Restraints

> class `chimerax.isolde.restraints.``Distance_Restraints`(c_pointers=None)

## Adaptive Distance Restraints

### Adaptive_Distance_Restraint_Mgr

> class `chimerax.isolde.restraints.``Adaptive_Distance_Restraint_Mgr`(model, c_pointer=None)

>   Manages “adaptive” distance restraints between atoms and their visualisations for a single atomic structure. Appears as a child `chimerax.Model` under the `chimerax.AtomicStructure` it manages.

>   The preferred way to create/retrieve the adaptive distance restraint manager for a given `AtomicStructure` instance m is:

>       from chimerax.isolde import session_extensions as sx
>       adr_mgr = sx.get_adaptive_distance_restraint_mgr(m)

>   `__init__`(model, c_pointer=None)

>     Prepare an adaptive distance restraint manager for a given atomic model.

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_restraint`(atom1, atom2)

>     Creates and returns a `Distance_Restraint` between the given atoms if possible, or returns the existing one if it already exists. Note that distance restraints can be added to a running simulation, but will trigger an expensive (a few seconds) reinitialisation of the simulation context.

>     Args:
>       - atom1, atom2:
>           - `chimerax.Atom` instances. Both atoms must be in the `chimerax.AtomicStructure` belonging to this manager, must not be the same atom or directly bonded to each other, and should not be hydrogens.
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `all_restraints`

>     Returns a `Distance_Restraints` instance encompassing all restraints owned by this manager.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `atom_restraints`(atom)

>     Returns a `Distance_Restraints` instance encompassing all distance restraints involving the given atom.

>     Args:
>       - atom:
>           - a `chimerax.Atom` instance from the `chimerax.AtomicStructure` belonging to this manager.
>   `atoms_restraints`(atoms)

>     Returns a `Distance_Restraints` instance encompassing all distance restraints involving at least one of the atoms. If you want only restraints where both atoms are in the set, use `intra_restraints()` instead.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance. All atoms must be part of the `chimerax.AtomicStructure` belonging to this manager.
>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `display_threshold`

>     Cutoff deviation from (target +/- tolerance) as a fraction of `c` below which distance restraints will be hidden. If `display_threshold` == 0 (default), all active restraints will be shown.

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_restraint`(atom1, atom2)

>     Returns the `Distance_Restraint` between the given atoms if it exists, otherwise None.

>     Args:
>       - atom1, atom2:
>           - `chimerax.Atom` instances. Both atoms must be in the `chimerax.AtomicStructure` belonging to this manager.
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `intra_restraints`(atoms)

>     Returns a `Distance_Restraints` instance encompassing all distance restraints for which both atoms are in the input set.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance. All atoms must be part of the `chimerax.AtomicStructure` belonging to this manager.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_bond_color`(color)

>     Set the colour of the cylinder representing the distance restraint.

>     Args:
>       - color:
>           - an iterable of four integers (0..255) representing the (r,g,b,a) colour values
>   `set_colormap`(min_color, mid_color, max_color)

>     Set the color scale for automatically colouring the restraint pseudobonds. Colors will be interpolated from min_color to mid_color when (r0-tolerance-3*c) < r < (r0-tolerance), and from mid_color to max_color when (r0+tolerance < r < r0+tolerance+3*c).

>     Args:
>       - min_color:
>           - an [rgba] array of four integers in the range 0-255
>       - mid_color:
>           - an [rgba] array of four integers in the range 0-255
>       - max_color:
>           - an [rgba] array of four integers in the range 0-255
>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_target_color`(color)

>     Set the colour of the cylinder representing the target distance.

>     Args:
>       - color:
>           - an iterable of four integers (0..255) representing the (r,g,b,a) colour values
>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Update the restraints drawing. Happens automatically every time restraints or coordinates change. It should rarely/never be necessary to call this manually.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `visible_restraints`

>     Returns a `Distance_Restraints` instance encompassing all currently visible restraints owned by this manager. A restraint will be visible if it is enabled and both its atoms are visible.

### Adaptive_Distance_Restraint

> class `chimerax.isolde.restraints.``Adaptive_Distance_Restraint`(c_pointer)

>   Defines an “adaptive robustness” distance restraint especially suited to large collections of fuzzy/unsure restraints (e.g. homology-based reference model restraints, evolutionary couplings, NMR NOESY spectra etc.). It differs from a simple harmonic restraint in two ways:

>   > 1. Provides an optional flat bottom (that is, a tolerance either side of the target within which no biasing force will be applied); and
>   > 2. Outside of the central energy “well” (the width of which is controlled by `c`) the potential can be tuned to “flatten out” (or, indeed, increase even faster than quadratic) with a rate controlled by `alpha`

>   If `tolerance` = 0 and `alpha` = 2, the restraint will behave identically to a traditional harmonic restraint with spring constant . Increasing `alpha` makes the “walls” of the well steeper than quadratic (not generally recommended); `alpha` = 1 makes them linear, and smaller/negative values cause the energy to flatten at increasing rates. The value of `alpha` is open-ended, but values below about -50 yield essentially no further changes to the energy profile.

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `alpha`

>     Parameter setting rate of energy growth/flattening outside well

>   `applied_force`

>     Total force currently being applied to this restraint. Read only.

>   `atoms`

>     Returns a tuple of `chimerax.Atoms` pointing to the pair of restrained atoms. Read only.

>   `c`

>     Parameter setting width of quadratic portion of energy well, in Angstroms

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `deleted`

>     Has the C++ side been deleted?

>   `distance`

>     Current distance between restrained atoms in Angstroms. Read only.

>   `effective_spring_constant`

>     Effective harmonic spring constant when `distance` < `c`, in . The effective spring constant is . Setting this parameter adjusts for the current `c`.

>   `enabled`

>     Enable/disable this restraint or get its current state.

>   `kappa`

>     Parameter setting depth of energy well, in kJ/mol

>   `sim_index`

>     Index of this restraint in the relevant MDFF Force in a running simulation. Returns -1 if the restraint is not currently in a simulation. Can be set, but only if you know what you are doing.

>   `target`

>     Target distance in Angstroms

>   `tolerance`

>     Half-width of potential well flat bottom in Angstroms

>   `visible`

>     Restraint will be visible if it is enabled and both atoms are visible.

### Adaptive_Distance_Restraints

> class `chimerax.isolde.restraints.``Adaptive_Distance_Restraints`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `alphas`

>     Parameter setting rate of energy growth/flattening outside well

>   `applied_forces`

>     Total force currently being applied to each restraint. Read only.

>   `atoms`

>     Returns a 2-tuple of `Atoms` containing the restrained atoms. Read only.

>   `clear_sim_indices`()

>     Run at the end of a simulation to reset sim indices to -1

>   `colors`

>     Color of each restraint. Automatically set based on ratio of current distance to target. Read only.

>   `cs`

>     Parameter setting width of quadratic portion of energy well, in Angstroms

>   `distances`

>     Current distances between restrained atoms in Angstroms. Read only.

>   `effective_spring_constants`

>     Effective harmonic spring constants when `distance` < `c`, in . The effective spring constant is . Setting this parameter adjusts for the current `c`.

>   `enableds`

>     Enable/disable these restraints or get their current states.

>   `kappas`

>     Parameter setting depth of energy well, in kJ/mol

>   `sim_indices`

>     Index of each restraint in the relevant MDFF Force in a running simulation. Restraints which are not currently in a simulation have indices equal to -1. Can be set, but only if you know what you are doing.

>   `targets`

>     Target distances in Angstroms

>   `tolerances`

>     Half-widths of potential well flat bottoms in Angstroms

>   `visibles`

>     Each restraint will be visible if it is enabled and both atoms are visible.

## Proper Dihedral Restraints

### Proper_Dihedral_Restraint_Mgr

> class `chimerax.isolde.restraints.``Proper_Dihedral_Restraint_Mgr`(model, c_pointer=None, defer_add=False)

>   Manages creation, deletion, mapping and drawing of proper dihedral restraints for a single atomic structure. Appears as a child `chimerax.Model` under the `chimerax.AtomicStructure` it manages.

>   The preferred way to create/retrieve the proper dihedral restraint manager for a given `AtomicStructure` instance m is:

>       from chimerax.isolde import session_extensions as sx
>       pdr_mgr = sx.get_proper_dihedral_restraint_mgr(m)

>   `__init__`(model, c_pointer=None, defer_add=False)

>     Initialize self. See help(type(self)) for accurate signature.

>   `add`(models)

>     Add child models to this model.

>   `add_all_defined_restraints_for_residues`(residues)

>     Creates and returns all possible dihedral restraints for all named proper dihedrals in the given residues as a `Proper_Dihedral_Restraints` instance.

>     Args:
>       - residues:
>           - a `chimerax.Residues` instance
>   `add_drawing`(d)

>     Add a child drawing.

>   `add_restraint`(dihedral)

>     Singular form of `add_restraints()`, returning a `Proper_Dihedral_Restraint` instance (or None if things go wrong).

>     Args:
>       - dihedral:
>           - a `Proper_Dihedral` instance
>   `add_restraint_by_residue_and_name`(residue, name)

>     Singular form of `add_restraints_by_residues_and_name()`. Returns a `Proper_Dihedral_Restraint` instance for the dihedral with the given name in the given residue if it exists or can be created, else None.

>     Args:
>       - residue:
>           - A `chimerax.Residue` instance
>       - name:
>           - Lowercase name of a known dihedral definition (e.g. ‘phi’)
>   `add_restraints`(dihedrals)

>     Returns a `Proper_Dihedral_Restraints` instance covering the dihedrals in the input. Only one `Proper_Dihedral_Restraint` will ever be created for a given dihedral, so it is safe to use this repeatedly on the same set of dihedrals. Use this method when you want to ensure that all dihedrals in the input will be restrainable in simulations.

>     Args:
>       - dihedrals:
>           - a `Proper_Dihedrals` instance.
>   `add_restraints_by_residues_and_name`(residues, name)

>     Convenience function wrapping `add_restraints()`. Returns a `Proper_Dihedral_Restraints` instance covering all dihedrals with the given name in residues.

>     Args:
>       - residues:
>           - A `chimerax.Residues` instance
>       - name:
>           - Lowercase name of a known dihedral definition (e.g. ‘phi’)
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_all_restraints_for_residues`(residues)

>     Returns a `Proper_Dihedral_Restraints` containing all existing dihedral restraints belonging to the given residues.

>     Args:
>       - residues:
>           - a `chimerax.Residues` instance
>   `get_restraint`(dihedral)

>     Singular form of `get_restraints()`, returning a `Proper_Dihedral_Restraint` instance (or None if no restraint exists for this dihedral).

>     Args:
>       - dihedral:
>           - a `Proper_Dihedral` instance
>   `get_restraint_by_residue_and_name`(residue, name)

>     Singular form of `get_restraints_by_residues_and_name()`. Returns a `Proper_Dihedral_Restraint` instance for the dihedral with the given name in the given residue if it exists, else None.

>     Args:
>       - residue:
>           - A `chimerax.Residue` instance
>       - name:
>           - Lowercase name of a known dihedral definition (e.g. ‘phi’)
>   `get_restraints`(dihedrals)

>     Returns a `Proper_Dihedral_Restraints` instance covering the dihedrals in the input. Unlike `add_restraints()`, no new `Proper_Dihedral_Restraint` will be created. Use this method when you’ve already defined all the restraints you need, and don’t want to accidentally add more.

>     Args:
>       - dihedrals:
>           - a `Proper_Dihedrals` instance.
>   `get_restraints_by_residues_and_name`(residues, name)

>     Convenience function wrapping `get_restraints()`. Returns a `Proper_Dihedral_Restraints` instance containing all existing restraints for the dihedrals with the given name in residues.

>     Args:
>       - residues:
>           - A `chimerax.Residues` instance
>       - name:
>           - Lowercase name of a known dihedral definition (e.g. ‘phi’)
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `num_restraints`

>     Number of dihedral restrains currently owned by this manager.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_color_scale`(max_c, mid_c, min_c)

>     Set a custom colour scale for the validation indicators.

>     Args:
>       - max_c:
>           - The colour applied to the most-favoured rotamers, as an integer (r,g,b,a) array in the range (0..255)
>       - mid_c:
>           - The colour applied to rotamers at the border between favoured and allowed, as an integer (r,g,b,a) array in the range (0..255)
>       - min_c:
>           - The colour applied to outlier rotamers, as an integer (r,g,b,a) array in the range (0..255)
>   `set_default_colors`()

>     Set the colour scale for validation indicators back to their defaults.

>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Update the restraints drawing. Happens automatically every time restraints or coordinates change. It should rarely/never be necessary to call this manually.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `visible_restraints`

>     Returns a `Proper_Dihedral_Restraints` instance containing all currently visible restraints. A restraint is visible if it is enabled, at least the axial bond of its `Proper_Dihedral` is visible, and its `display` propery is True. Unlike other restraint classes the visibility of active restraints is controllable, primarily because certain restraints (particularly the peptide omega dihedral) are best left always on and would become distracting if visible.

### Proper_Dihedral_Restraint

> class `chimerax.isolde.restraints.``Proper_Dihedral_Restraint`(c_pointer)
>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `annotation_color`

>     Get the color of the annotation for this restraint according to the current colormap. Read only.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `cutoff`

>     Cutoff angle offset below which no restraint will be applied. Can be set.

>   `deleted`

>     Has the C++ side been deleted?

>   `dihedral`

>     The restrained `Proper_Dihedral`. Read only.

>   `display`

>     Set whether you want this restraint to be displayed when active.

>   `enabled`

>     Enable/disable this restraint or get its current state.

>   `offset`

>     Difference between current and target angle in radians. Read only.

>   `sim_index`

>     Index of this restraint in the relevant Force in a running simulation. Returns -1 if the restraint is not currently in a simulation. Can be set, but only if you know what you are doing.

>   `spring_constant`

>     Get/set the spring constant for this restraint in

>   `target`

>     Target angle for this restraint in radians. Can be written.

>   `visible`

>     Is this restraint currently visible? Read-only.

### Proper_Dihedral_Restraints

> class `chimerax.isolde.restraints.``Proper_Dihedral_Restraints`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `annotation_colors`

>     Get the annotation color for each restraint according to the current colormap. Read only.

>   `cutoffs`

>     Cutoff angle offsets below which no restraint will be applied. Can be set.

>   `dihedrals`

>     The restrained `Proper_Dihedrals`. Read only.

>   `displays`

>     Set whether you want each restraint to be displayed when active.

>   `enableds`

>     Enable/disable each restraint or get their current states.

>   `offsets`

>     Difference between current and target angles in radians. Read only.

>   `restrict_to_sel`(atoms)

>     Returns a new `Proper_Dihedral_Restraints` containing only the restraints for which every atom is in the given selection.

>   `sim_indices`

>     Index of each restraint in the relevant MDFF Force in a running simulation. Restraints which are not currently in a simulation have indices equal to -1. Can be set, but only if you know what you are doing.

>   `spring_constants`

>     Get/set the spring constant for each restraint in

>   `targets`

>     Target angles for each restraint in radians. Can be written.

>   `visibles`

>     Is each restraint currently visible? Read-only.

## Chirality Restraints

### Chiral_Restraint_Mgr

> class `chimerax.isolde.restraints.``Chiral_Restraint_Mgr`(model, c_pointer=None)

>   Manages creation, deletion and mapping of chiral restraints for a single atomic structure. Appears as a `chimerax.Model` under the `chimerax.AtomicStructure` it manages.

>   Chirality restraints are always on by default, and are not drawn. The restraint targets are likewise fixed quantities - if you want to switch chirality, you should replace/rename the residue in question to your desired isomer.

>   The preferred way to create/retrieve the chirality restraint manager for a given `AtomicStructure` instance m is:

>       from chimerax.isolde import session_extensions as sx
>       chir_mgr = sx.get_chir_restraint_mgr(m)

>   `__init__`(model, c_pointer=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_restraint`(chiral)

>     Singular form of `add_restraints()`, returning a `Chiral_Restraint` instance (or None if things go wrong).

>     Args:
>       - dihedral:
>           - a `Chiral_Center` instance
>   `add_restraints`(chirals)

>     Returns a `Chiral_Restraints` instance covering the `Chiral_Centres` in the input. Only one `Chiral_Restraint` will ever be created for a given chiral centre, so it is safe to use this repeatedly on the same set of centres. Use this method when you want to ensure that all chiral centres in the input will be restrainable in simulations.

>     Args:
>       - chirals:
>           - a `Chiral_Centers` instance.
>   `add_restraints_by_atoms`(atoms)

>     Returns a `Chiral_Restraints` covering all chiral centers in the given atoms.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_restraint`(chiral)

>     Singular form of `get_restraints()`, returning a `Chiral_Restraint` instance (or None if no restraint exists for this chiral centre).

>     Args:
>       - chiral:
>           - a `Chiral_Center` instance
>   `get_restraints`(chirals)

>     Returns a `Chiral_Restraints` instance covering the `Chiral_Centers` in the input. Unlike `add_restraints()`, no new `Chiral_Restraint` will be created. Use this method when you’ve already defined all the restraints you need, and don’t want to accidentally add more.

>     Args:
>       - chirals:
>           - a `Chiral_Centers` instance.
>   `get_restraints_by_atoms`(atoms)

>     Returns a `Chiral_Restraints` covering only those chiral centers in the given atoms for which a restraint has already been defined.

>     Args:
>       - atoms:
>           - a `chimerax.Atoms` instance
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `num_restraints`

>     Number of chirality restrains currently owned by this manager.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Should be overridden in derived classes.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

### Chiral_Restraint

> class `chimerax.isolde.restraints.``Chiral_Restraint`(c_pointer)

>   Handles the restraint of a single chiral centre in simulations. Unlike other restraints, `Chiral_Restraint` instances are enabled by default. In addition, `target` is immutable, and set to the equilibrium angle of the chiral improper dihedral (defined in dictionaries/chirals.json and viewable via `Chiral_Mgr.chiral_center_dict`).

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `cutoff`

>     Cutoff angle offset below which no restraint will be applied. Can be set.

>   `deleted`

>     Has the C++ side been deleted?

>   `dihedral`

>     The restrained `Chiral_Center`. Read only.

>   `enabled`

>     Enable/disable this restraint or get its current state.

>   `offset`

>     Difference between current and target angle in radians. Read only.

>   `sim_index`

>     Index of this restraint in the relevant Force in a running simulation. Returns -1 if the restraint is not currently in a simulation. Can be set, but only if you know what you are doing.

>   `spring_constant`

>     Get/set the spring constant for this restraint in

>   `target`

>     Target angle for this restraint in radians. Read only.

### Chiral_Restraints

> class `chimerax.isolde.restraints.``Chiral_Restraints`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `cutoffs`

>     Cutoff angle offsets below which no restraint will be applied. Can be set.

>   `dihedrals`

>     Returns the restrained `Chiral_Centers`. Read only.

>   `enableds`

>     Enable/disable each restraint or get their current states.

>   `offsets`

>     Differences between current and target angles in radians. Read only.

>   `restrict_to_sel`(atoms)

>     Returns a new `Chiral_Restraints` containing only the restraints for which every atom is in the given selection.

>   `sim_indices`

>     Index of each restraint in the relevant Force in a running simulation. Returns -1 for restraints not currently in a simulation. Can be set, but only if you know what you are doing.

>   `spring_constants`

>     Get/set the spring constants for each restraint in

>   `targets`

>     Target angles for each restraint in radians. Read only.

## Rotamer Restraints

### Rotamer_Restraint_Mgr

> class `chimerax.isolde.restraints.``Rotamer_Restraint_Mgr`(model, c_pointer=None)

>   Rotamer restraints are a little special in that they primarily exist as convenience wrappers around sets of dihedral restraints. As such, `Rotamer_Restraint_Mgr` does not handle drawing of restraints, but it does handle drawing of previews when scrolling through alternate target rotamer conformations for a given sidechain.

>   `__init__`(model, c_pointer=None)

>     Manages rotamer restraints for a single model

>   `add`(models)

>     Add child models to this model.

>   `add_drawing`(d)

>     Add a child drawing.

>   `add_restraint`(rotamer_or_residue)

>     Returns a `Rotamer_Restraint` instance for the given rotamer or residue, attempting to create it if it doesn’t already exist. If creation is impossible (e.g. the residue is non-rotameric or incomplete), returns None.

>     Args:
>       - rotamer_or_residue:
>           - a `Rotamer` or `chimerax.Residue` belonging to the same molecule as this manager
>   `add_restraints`(rotamers_or_residues)

>     Returns a `Rotamer_Restraints` instance covering all rotamers in the input, creating those that don’t yet exist.

>     Args:
>       - rotamers_or_residues:
>           - a `Rotamers` or `chimerax.Residues` with all elements belonging to the same molecule as this manager
>   `all_drawings`(displayed_only=False)

>     Return all drawings including self and children at all levels.

>   `all_models`()

>     Return all models including self and children at all levels.

>   `any_part_highlighted`()

>     Is any part of this Drawing or its children highlighted.

>   `bounds`()

>     The bounds of all displayed parts of a drawing and its children and all descendants, including instance positions, in scene coordinates. Drawings with an attribute skip_bounds = True are not included.

>   `bounds_intercept_copies`(bounds, mxyz1, mxyz2)

>     Return indices of positions where line segment intercepts displayed bounds. This is to optimize picking so that positions where no intercept occurs do not need to be checked to see what is picked.

>   `child_drawings`()

>     Return the list of surface pieces.

>   `child_models`()

>     Return child models.

>   `clear_highlight`(include_children=True)

>     Unhighlight this drawing and child drawings in if include_children is True.

>   `commit_preview`(rotamer)

>     Directly set the coordinates of the associated residue to match the current preview. NOTE: if a simulation is running this change will be ignored unless you immediately run `Sim_Handler.push_coords_to_sim()`!

>     Args:
>       - rotamer:
>           - a `Rotamer` instance
>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `custom_x3d`(stream, x3d_scene, indent, place)

>     Override this function for custom X3D

>     This is a generic version and assumes that positions are orthogonal.

>   `delete`()

>     Delete this model.

>   `deleted`

>     Has the C++ side been deleted?

>   `draw`(renderer, draw_pass)

>     Draw this drawing using the given draw pass. Does not draw child drawings

>   `draw_self`(renderer, draw_pass)

>     Draw this drawing without children using the given draw pass.

>   `drawing_lineage`

>     Return a sequence of drawings from the root down to the current drawing.

>   `empty_drawing`()

>     Does this drawing have no geometry? Does not consider child drawings.

>   `first_intercept`(mxyz1, mxyz2, exclude=None)

>     Find the first intercept of a line segment with the displayed part of this drawing and its children. The end points are in the parent drawing coordinates and do not take account of this Drawings positions. If the exclude option is given it is a function that takes a drawing and returns true if this drawing and its children should be excluded. Return a Pick object for the intercepted item. The Pick object has a distance attribute giving the fraction (0-1) along the segment where the intersection occurs. For no intersection None is returned. This routine is used for highlighting objects, for identifying objects during mouse-over, and to determine the front-most point in the center of view to be used as the interactive center of rotation.

>   `first_intercept_children`(child_drawings, mxyz1, mxyz2, exclude=None)

>     Like first_intercept() but check for intercepts with just the specified children.

>   `geometry_bounds`()

>     Return the bounds of this drawing’s geometry not including positions and not including children. Bounds are in this drawing’s coordinate system. These bounds are cached for speed.

>   `get_restraint`(rotamer_or_residue)

>     Returns a `Rotamer_Restraint` instance for the given rotamer or residue if the restraint has previously been created, otherwise None.

>     Args:
>       - rotamer_or_residue:
>           - a `Rotamer` or `chimerax.Residue` belonging to the same molecule as this manager
>   `get_restraints`(rotamers_or_residues)

>     Returns a `Rotamer_Restraints` instance containing all previously-created restraints in the input.

>     Args:
>       - rotamers_or_residues:
>           - a `Rotamers` or `chimerax.Residues` with all elements belonging to the same molecule as this manager
>   `get_selected`(include_children=False, fully=False)

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `has_formatted_metadata`(session)

>     Can override both this and ‘get_formatted_metadata’ if lazy evaluation desired

>   `highlighted_displayed_triangles_mask`

>     Mask of highlighted and displayed triangles.

>   `id_string`

>     Return the dot-separated identifier for this model. A top-level model (one that is not a child of another model) will have no dots in its identifier. A child model identifier consists of its parent model identifier, followed by a dot (period), followed by its (undotted) identifier within the parent model.

>     Returns:
>       A string. If the model has not been assigned an identifier, an empty string is returned.
>   `new_drawing`(name, *, subclass=None)

>     Create a new empty child drawing.

>   `next_preview`(rotamer)

>     Returns the target definition (a dict providing name, expected frequency, chi angles and estimated standard deviations) for the conformation next in order of decreasing favourability for this rotamer, and draws a preview overlaying the residue. If the current preview is the least favoured conformation, wraps back to the most favoured. Only one preview may be displayed at a time.

>     Args:
>       - rotamer:
>           - a `Rotamer` instance
>   `normals`

>     Normal vectors of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

>   `num_restraints`

>     Number of `Rotamer_Restraint` objects maintained by this manager.

>   `number_of_positions`(displayed_only=False)

>     Number of positions the Drawing is placed at.

>   `number_of_triangles`(displayed_only=False)

>     Return the number of triangles including all child drawings and all positions.

>   `planes_pick`(planes, exclude=None)

>     Find the displayed drawing instances bounded by the specified planes for this drawing and its children. Each plane is a 4-vector v with points in the pick region v0*x + v1*y + v2*z + v3 >= 0 using coordinate system of the parent drawing. If a drawing has instances then only the center of each instance is considered and the whole instance is picked if the center is within the planes. If a drawing has only one instance (self.positions has length 1) then the pick lists the individual triangles which have at least one vertex within all of the planes. If exclude is not None then it is a function called with a Drawing argument that returns true if this drawing and its children should be excluded from the pick. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

>   `prev_preview`(rotamer)

>     Returns the target definition (a dict providing name, expected frequency, chi angles and estimated standard deviations) for the conformation next in order of increasing favourability for this rotamer, and draws a preview overlaying the residue. If the current preview is the most favoured conformation, wraps back to the least favoured. Only one preview may be displayed at a time.

>     Args:
>       - rotamer:
>           - a `Rotamer` instance
>   `redraw_needed`(**kw)

>     Function called when the drawing has been changed to indicate that the graphics needs to be redrawn.

>   `remove_all_drawings`(delete=True)

>     Remove all child drawings.

>   `remove_drawing`(d, delete=True)

>     Remove a specified child drawing.

>   `remove_drawings`(drawings, delete=True)

>     Remove specified child drawings.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `selected`

>     Is this model selected? If fully is true then are all parts of this model selected?

>   `set_geometry`(vertices, normals, triangles)

>     Set vertices, normals and triangles defining the shape to be drawn.

>   `set_targets`(rotamer, target_index=None)

>     Set chi dihedral restraints on the rotamer to match the target definition. If no preview is currently active, then the index of the target definition must be provided. As well as setting the target chi angles, the cutoff angle on each restraint will be set to twice the estimated standard deviation.

>     Args:
>       - rotamer:
>           - a `Rotamer` instance
>       - target_index:
>           - Mandatory if no preview is current. The index of the target in the list of available target conformations (see `Rotamer.num_targets` and `Rotamer.get_target()`)
>   `set_transparency`(alpha)

>     Set transparency to alpha (0-255). Applies to per-vertex colors if currently showing per-vertex colors otherwise single color. Does not effect child drawings.

>   `show_metadata`(session, *, verbose=False, log=None, **kw)

>     called by ‘log metadata’ command.

>   `showing_transparent`()

>     Are any transparent objects being displayed. Includes all children.

>   `take_snapshot`(session, flags)

>     Return snapshot of current state of instance.

>     The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

>   `triangles`

>     Vertex indices for the corners of each triangle making up the rendered geometry, a numpy M by 3 array of int32 values. Read-only. Set using set_geometry() method.

>   `update_graphics`()

>     Should be overridden in derived classes.

>   `vertices`

>     Vertices of the rendered geometry, a numpy N by 3 array of float32 values. Read-only. Set using set_geometry() method.

### Rotamer_Restraint

> class `chimerax.isolde.restraints.``Rotamer_Restraint`(c_pointer)

>   Rotamer restraints are special in that they only exist as wrappers around combinations of `Proper_Dihedral_Restraint` objects. As such, they have no independent presence in simulations. The chi dihedral restraints may still be addressed and controlled independently if necessary.

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `chi_restraints`

>     Returns a `Proper_Dihedral_Restraints` covering the chi dihedrals in this rotamer.

>   `cpp_pointer`

>     Value that can be passed to C++ layer to be used as pointer (Python int)

>   `deleted`

>     Has the C++ side been deleted?

>   `enabled`

>     Enable/disable chi dihedral restraints. Returns False if any chi restraint is disabled.

>   `residue`

>     `chimerax.Residue` to be restrained. Read only.

>   `rotamer`

>     `Rotamer` to be restrained. Read only.

>   `set_spring_constant`(k)

>     Sets the spring constants for all chi dihedrals in the rotamer to k. Write-only. To retrieve the current spring constants, use `chi_restraints.spring_constants`

>   `target_index`

>     Get/set the index of the rotamer target definition giving target angles and cutoffs. If no restraint is currently applied, returns the last restraint that was applied to this rotamer. If no restraint has ever been applied, returns -1. Setting the index automatically apples the target and cutoff angles for each chi dihedral restraint, according to the chosen target. Cutoffs angles are set to twice the estimated standard deviations for the target.

### Rotamer_Restraints

> class `chimerax.isolde.restraints.``Rotamer_Restraints`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `enableds`

>     Enable/disable chi dihedral restraints. Returns False for any rotamer where at least one chi restraint is disabled.

>   `residues`

>     `chimerax.Residues` to be restrained. Read only.

>   `rotamers`

>     `Rotamers` to be restrained. Read only.

>   `set_spring_constant`(k)

>     Sets the spring constants for all chi dihedrals in all rotamers to k. Write-only. To retrieve the current spring constants, use `Rotamer.chi_restraints.spring_constants` (note: this is only possible for one rotamer at a time).

>   `target_index`

>     Get/set the index of the rotamer target definition giving target angles and cutoffs. If no restraint is currently applied, returns the last restraint that was applied to this rotamer. If no restraint has ever been applied, returns -1.