Restraints and Steering Forces

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 MDFFMgr (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

restraints.restrain_torsions_to_template(template_residues, restrained_residues, restrain_backbone=True, restrain_sidechains=True, kappa=5, alpha=0.2, spring_constant=100, identical_sidechains_only=True, adjust_for_confidence=False, confidence_type='plddt')

Restrain all phi, psi, omega and/or chi dihedrals in restrained_residues to match their counterparts (if present) in template_residues.

Args:
  • template_residues:
    • a chimerax.atomic.Residues instance. All residues must be from a single model, but need no be contiguous

  • restrained_residues:
    • a chimerax.atomic.Residues instance. All residues must be from a single model (which may or may not be the same model as for template_residues). May be the same array as template_residues (which will just restrain all torsions to their current angles).

  • restrain_backbone:
    • if True, all phi, psi and omega dihedrals in restrained_residues hat exist in both restrained_residues and template_residues will be restrained to the angles in template_residues

  • restrain_sidechains:
    • if True, all chi dihedrals in restrained_residues that exist in both restrained_residues and template_residues will be restrained to the angles in template_residues

  • kappa:
    • can be thought of as (approximately) the inverse variance of the well within which the restraint will be felt. For example, kappa=10 corresponds to a standard deviation of \sqrt{\frac{1}{10}} = 0.316 radians or about 18 degrees. A torsion restrained with this kappa will begin to “feel” the steepest part of the restraint once it comes within about two standard deviations of the target angle.

  • alpha:
    • sets the rate of fall-off of the potential outside the restraint well. For alpha==0, the potential quickly falls to a constant (zero force). Increasing alpha increases the force felt outside the core well region.

  • spring_constant:
    • strength of each restraint, in kJ mol^{-1} rad^{-2}

  • identical_sidechains_only:
    • if True, restraints will only be applied to a sidechain if it is the same amino acid as the template.

  • adjust_for_confidence:
    • for use when the reference model is a predicted structure. If True, the parameters of each individual restraint will be adjusted according to the predicted confidence in local conformation (less confident restraints will be both weaker and “fuzzier”)

  • confidence_type:
    • the confidence metric used in the prediction. Currently only “plddt” (predicted local distance difference test) is supported, and is expected to be provided in the B-factor column of the reference model as for models fetched from the AlphaFold2-EBI database. Scores should be on either a 0-100 or 0-1 scale.

restraints.restrain_atom_distances_to_template(template_residues, restrained_residues, protein=True, nucleic=True, custom_atom_names=[], per_chain=False, distance_cutoff=8, alignment_cutoff=5, well_half_width=0.1, kappa=10, tolerance=0.025, fall_off=2, display_threshold=None, adjust_for_confidence=False, use_coordinate_alignment=True, confidence_type='pae', pae_matrix=None, group_name=None)

Creates a “web” of adaptive distance restraints between nearby atoms, restraining one set of residues to the same spatial organisation as another.

Args:
  • template_residues:
    • a list of chimerax.atomic.Residues instances. If restrained_residues is not identical to template_residues, then each Residues should be from a single chain. Residues need not be contiguous.

  • restrained_residues:
    • a list of chimerax.atomic.Residues instances. Must be the same length as template_residues, with a 1:1 correspondence between chains. Chains will be aligned individually to get the subset of matching residues, but original coordinates will be used for the purposes of assigning restraints.

  • protein (default = True):
    • Restrain protein conformation? If True, a pre-defined set of useful “control” atoms (CA plus the first two heavy atoms along each sidechain) will be added to the restraint network.

  • nucleic (default = True):
    • Restrain nucleic acid conformation? If True, key atoms defining the nucleic acid backbone and base pairing will be added to the restraint network.

  • custom_atom_names(default = empty list):
    • Provide the names of any other atoms you wish to restrain (e.g. ligand atoms) here.

  • per_chain(default = False):
    • If False, distance restraints will be added between as well as within chains. If Talse, only intra-chain distances will be restrained.

  • distance_cutoff (default = 8):
    • for each CA atom in restrained_residues, a distance restraint will be created between it and every other CA atom where the equivalent atom in template_residues is within distance_cutoff of its template equivalent.

  • alignment_cutoff (default = 5):
    • distance cutoff (in Angstroms) for rigid-body alignment of model against template. Residues with a CA RMSD greater than this value after alignment will not be restrained. Ignored if use_coordinate_alignment is False.

  • well_half_width (default = 0.1):
    • distance range (as a fraction of the square root of target distance) within which the restraint will behave like a normal harmonic restraint. The applied force will gradually taper off for any restraint deviating from (target + tolerance) by more than this amount.

  • kappa (default = 10):
    • defines the strength of each restraint when the current distance is within well_half_width of the target +/- tolerance. The effective spring constant is k=\frac{\kappa}{(\text{well\_half\_width}*\text{target distance})^2} in kJ mol^{-1} nm^{-2}.

  • tolerance (default = 0.025):
    • half-width (as a fraction of the target distance) of the “flat bottom” of the restraint profile. If abs(distance-target) < tolerance * target, no restraining force will be applied.

  • fall_off (default = 2):
    • Sets the rate at which the energy function will fall off when the distance deviates strongly from the target, as a function of the target distance. The exponent on the energy term at large deviations from the target distance will be set as \alpha = -\text{fall\_off} ln(\text{target}). In other words, long-distance restraints are treated as less confident than short-distance ones.

  • display_threshold (default = 0):
    • deviation from (target +- tolerance) as a fraction of well_half_width below which restraints will be hidden.

  • use_coordinate_alignment (default = True):
    • if True, reference and template residues will be matched by progressively breaking down the models into groups that approximately align as rigid bodies. This is usually the preferable approach, but fails in cases where the working model is badly wrong (e.g. has large register errors). If False, residues will be matched strictly by sequence alignment. This may be preferable when restraining against an AlphaFold model.

  • adjust_for_confidence (default = False):
    • if true, interpret B-factors of the template atoms as a confidence score, the definition of which is controlled by confidence_type, and adjust kappa, tolerance and fall_off according to the mean confidence for each restrained atom pair.

  • confidence_type (default = “pae”):
    • the type of confidence score used. Current options are “pae” (predicted aligned error) and “plddt” (predicted local distance difference test). For the “pae” option, multi-chain template models are NOT currently supported.

  • pae_matrix (default = None):
    • used if adjust_for_confidence is True and confidence_type is “pae”. If the reference model was downloaded from the AlphaFold database, leave this argument as None and the relevant PAE matrix will be automatically fetched. Otherwise, the matrix should be a 2D Numpy array with entry (i,j) equal to the PAE of residue number i relative to residue number j.

  • group_name (default = “Reference Distance Restraints”):
    • allows for the generation of multiple independent groups of restraints. Each unique name will create a new group.

restraints.restrain_small_ligands(distance_cutoff=4, heavy_atom_limit=3, spring_constant=5000, bond_to_carbon=False)

Residues with a small number of heavy atoms can be problematic in MDFF if unrestrained, since if knocked out of density they tend to simply keep going. It is best to restrain them with distance restraints to suitable surrounding atoms or, failing that, to their starting positions.

Args:
  • model:
    • a chimerax.atomic.AtomicStructure instance

  • distance_cutoff (default = 3.5):
    • radius in Angstroms to look for candidate heavy atoms for distance restraints. If no candidates are found, a position restraint will be applied instead.

  • heavy_atom_limit (default = 3):
    • Only residues with a number of heavy atoms less than or equal to heavy_atom_limit will be restrained

  • spring_constant (default = 500):
    • strength of each restraint, in kJ mol^{-1} nm^{-2}

  • bond_to_carbon (default = False):
    • if True, only non-carbon heavy atoms will be restrained using distance restraints.

restraints.restrain_secondary_structure(residues, target)

Restrain all amino acid residues in a selection to a target secondary structure. Secondary structure restraints consist of dihedral restraints on phi and psi, distance restraints on (CA(n)-CA(n+2)) and (O(n)-O(n+4)), and H-bonds between adjacent beta-strands.

Args:
  • atoms:
    • a chimerax.Atoms instance defining the selection. Any

      residue with at least one atom in the selection will be restrained. No distance restraints involving residues outside the selection will be applied.

  • target:
    • ‘helix’ or ‘strand’

Target distances/angles for each secondary structure definition are stored in constants.py.

restraints.restrain_ca_distances_to_template(restrained_residues, distance_cutoff=8, spring_constant=500)

(Deprecated - for most purposes restrain_atom_distances_to_template() should be used.) Creates a “web” of distance restraints between nearby CA atoms, restraining one set of residues to the same spatial organisation as another.

Args:
  • template_residues:
    • a chimerax.atomic.Residues instance. All residues must be from a single model, but need no be contiguous

  • restrained_residues:
    • a chimerax.atomic.Residues instance. All residues must be from a single model (which may or may not be the same model as for template_residues). May be the same array as template_residues (which will just restrain all distances to their current values).

  • distance_cutoff (default = 8):
    • for each CA atom in restrained_residues, a distance restraint will be created between it and every other CA atom where the equivalent atom in template_residues is within distance_cutoff of its template equivalent.

  • spring_constant (default = 500):
    • the strength of each restraint, in kJ mol^{-1} nm^{-2}

Change Tracking

RestraintChangeTracker

class chimerax.isolde.restraints.RestraintChangeTracker(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 _RestraintMgr subclass instance has its own TriggerSet, and RestraintChangeTracker 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 RestraintChangeTracker at the C++ level.

__init__(session, c_pointer=None)
property cpp_pointer

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

property deleted

Has the C++ side been deleted?

Map Steering Forces

MDFFMgr

class chimerax.isolde.restraints.MDFFMgr(model, volume, c_pointer=None, guess_global_k=True, auto_add_to_session=True)

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)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, volume, c_pointer=None, guess_global_k=True, auto_add_to_session=True)
accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_mdff_atoms(atoms, hydrogens=False)

Returns a MDFFAtoms instance covering the atoms in the input. Only one MDFFAtom 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

property enabled

Turns this potential on/off in simulations

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 MDFFAtoms instance covering the atoms in the input. Unlike add_mdff_atoms(), no new MDFFAtom 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?

property global_k

Global coupling constant applied to all atoms (scales the individual atom coupling constants). Effective units are kJ mol^{-1} (\text{map density unit})^{-1} nm^3

guess_global_k(distance_cutoff=3, percentile=90, scaling_constant=2)

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. Each heavy atom coordinate is randomly perturbed by up to 0.25 A along each axis, and the gradient at that point 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 value * global_k = scaling_constant.

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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property selected

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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.

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property volume

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

was_deleted

Indicates whether this Drawing has been deleted.

MDFFAtom

class chimerax.isolde.restraints.MDFFAtom(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)
property atom

Returns the ChimeraX Atom. Read only.

property 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.

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property enabled

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

property mgr

MDFFMgr for this atom and map. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property 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.

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.

MDFFAtoms

class chimerax.isolde.restraints.MDFFAtoms(c_pointers=None)
__init__(c_pointers=None)
property atoms

Returns the chimerax.Atom. Read only.

clear_sim_indices()

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

property 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.

property enableds

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

static restore_snapshot(session, data)

Create object using snapshot data.

property 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.

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.

Position Restraints

PositionRestraintMgr

class chimerax.isolde.restraints.PositionRestraintMgr(model, c_pointer=None, auto_add_to_session=True)

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)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, auto_add_to_session=True)
accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_restraint(atom)

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

Args:
  • atom:
    • a chimerax.Atom instance

add_restraints(atoms)

Returns a PositionRestraints 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 PositionRestraint 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 PositionRestraint instance (or None if no restraint exists for this atom).

Args:
  • atom:
    • a chimerax.Atom instance

get_restraints(atoms)

Returns a PositionRestraints instance covering the atoms in the input. Unlike add_restraints(), no new PositionRestraint 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property normals

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

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property 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, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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_visibility=False)

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

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property visible_restraints

Returns a PositionRestraints 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.

was_deleted

Indicates whether this Drawing has been deleted.

PositionRestraint

class chimerax.isolde.restraints.PositionRestraint(c_pointer)

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

__init__(c_pointer)
property atom

Returns the restrained chimerax.Atom. Read-only.

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property enabled

Enable/disable this position restraint.

property mgr

PositionRestraintMgr that owns this restraint. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property 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.

property spring_constant

Restraint spring constant in kJ mol^{-1} nm^{-2}. Can be written

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.

property target

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

property target_vector

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

property visible

Check whether this restraint is currently visible. Read only.

PositionRestraints

class chimerax.isolde.restraints.PositionRestraints(c_pointers=None, single_type=None, poly_type=None)
__init__(c_pointers=None, single_type=None, poly_type=None)
property atoms

Returns the restrained chimerax.Atoms. Read-only.

clear_sim_indices()

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

property enableds

Enable/disable position restraints with a Numpy boolean array.

static restore_snapshot(session, data)

Create object using snapshot data.

property 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.

property spring_constants

Restraint spring constants in kJ mol^{-1} nm^{-2}. Can be written

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.

property target_vectors

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

property targets

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

property visibles

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

Interactive Tugging Forces

NOTE: The classes TuggableAtom and TuggableAtoms are simply wrappers over PositionRestraint and PositionRestraints respectively, with no API changes.

TuggableAtomsMgr

class chimerax.isolde.restraints.TuggableAtomsMgr(model, c_pointer=None, allow_hydrogens='polar only')

Manages creation, deletion and mapping of PositionRestraint 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)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, allow_hydrogens='polar only')
accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_tuggable(atom)

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

Args:
  • atom:
    • a chimerax.Atom instance

add_tuggables(atoms)

Returns a TuggableAtoms 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 PositionRestraint 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 TuggableAtoms instance covering the atoms in the input. Unlike add_tuggables(), no new PositionRestraint 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property normals

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

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Since the “restraints” in TuggbleAtomsMgr are designed to be transient for user interaction, checkpoints are not saved. Instead, the restore_checkpoint() method simply clears all tugging forces.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property 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, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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_visibility=False)

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

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property visibles

Returns a TuggableAtoms 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.

was_deleted

Indicates whether this Drawing has been deleted.

TuggableAtom

See Position_Restraint

TuggableAtoms

Distance Restraints

DistanceRestraintMgr

class chimerax.isolde.restraints.DistanceRestraintMgr(model, c_pointer=None, auto_add_to_session=True)

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)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, auto_add_to_session=True)

Prepare a distance restraint manager for a given atomic model.

accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_restraint(atom1, atom2)

Creates and returns a DistanceRestraint 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 DistanceRestraints 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.

property all_restraints

Returns a DistanceRestraints instance encompassing all restraints owned by this manager.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

atom_restraints(atom)

Returns a DistanceRestraints 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 DistanceRestraints 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.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 DistanceRestraint 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_restraints(atoms1, atoms2)

Returns the DistanceRestraints 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

intra_restraints(atoms)

Returns a DistanceRestraints 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.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property 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, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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_visibility=False)

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

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property visible_restraints

Returns a DistanceRestraints 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.

was_deleted

Indicates whether this Drawing has been deleted.

DistanceRestraint

class chimerax.isolde.restraints.DistanceRestraint(c_pointer)

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

__init__(c_pointer)
property atoms

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

property center

Returns the mid-point between the two restrained atoms. Read only.

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property distance

Current distance between restrained atoms in Angstroms. Read only.

property enabled

Enable/disable this restraint or get its current state.

property mgr

DistanceRestraintMgr for this restraint. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property satisfied

Returns true if deviation from target distance is less than satisfied_limit. Read only.

property satisfied_limit

Deviation from target distance (in Angstroms) beyond which this restraint will be considered unsatisfied.

property 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.

property spring_constant

Restraint spring constant in kJ mol^{-1} nm^{-2}

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.

property target

Target distance in Angstroms

property unsatisfied

Returns true if deviation from target distance is greater than or equal to satisfied_limit. Read only.

property visible

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

DistanceRestraints

class chimerax.isolde.restraints.DistanceRestraints(c_pointers=None)

Adaptive Distance Restraints

AdaptiveDistanceRestraintMgr

class chimerax.isolde.restraints.AdaptiveDistanceRestraintMgr(model, c_pointer=None, name='Adaptive Distance Restraints', auto_add_to_session=True)

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)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, name='Adaptive Distance Restraints', auto_add_to_session=True)

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

accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_restraint(atom1, atom2)

Creates and returns a DistanceRestraint 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.

property all_restraints

Returns a DistanceRestraints instance encompassing all restraints owned by this manager.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

atom_restraints(atom)

Returns a DistanceRestraints 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 DistanceRestraints 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.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
property 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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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_colormap()

Get the current color scale (as min_color, mid_color, max_color) used for the restraint pseudobonds.

get_restraint(atom1, atom2)

Returns the DistanceRestraint 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_restraints(atoms1, atoms2)

Returns the DistanceRestraints 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

intra_restraints(atoms)

Returns a DistanceRestraints 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.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property 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, update_graphics=True)

Set the color scale for automatically coloring 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, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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_visibility=True)

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

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property visible_restraints

Returns a DistanceRestraints 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.

was_deleted

Indicates whether this Drawing has been deleted.

AdaptiveDistanceRestraint

class chimerax.isolde.restraints.AdaptiveDistanceRestraint(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 k=\frac{\kappa}{c^2}. 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)
property alpha

Parameter setting rate of energy growth/flattening outside well

property applied_force

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

property atoms

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

property c

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

property center

Returns the mid-point between the two restrained atoms. Read only.

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property distance

Current distance between restrained atoms in Angstroms. Read only.

property effective_spring_constant

Effective harmonic spring constant when distance < c, in kJ mol^{-1} nm^{-2}. The effective spring constant is k=\kappa/c^2. Setting this parameter adjusts \kappa for the current c.

property enabled

Enable/disable this restraint or get its current state.

property kappa

Parameter setting depth of energy well, in kJ/mol

property mgr

AdaptiveDistanceRestraintMgr for this restraint. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property satisfied

Returns true if deviation from target distance is less than satisfied_limit. Read only.

property satisfied_limit

Deviation from target distance (in Angstroms) beyond which this restraint will be considered unsatisfied.

property 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.

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.

property target

Target distance in Angstroms

property tolerance

Half-width of potential well flat bottom in Angstroms

property unsatisfied

Returns true if deviation from target distance is greater than or equal to satisfied_limit. Read only.

property visible

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

AdaptiveDistanceRestraints

class chimerax.isolde.restraints.AdaptiveDistanceRestraints(c_pointers=None)
__init__(c_pointers=None)
property alphas

Parameter setting rate of energy growth/flattening outside well

property applied_forces

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

property atoms

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

property centers

Returns the mid-point between the two restrained atoms for each restraint. Read only.

clear_sim_indices()

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

property colors

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

property cs

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

property distances

Current distances between restrained atoms in Angstroms. Read only.

property effective_spring_constants

Effective harmonic spring constants when distance < c, in kJ mol^{-1} nm^{-2}. The effective spring constant is k=\kappa/c^2. Setting this parameter adjusts \kappa for the current c.

property enableds

Enable/disable these restraints or get their current states.

property kappas

Parameter setting depth of energy well, in kJ/mol

static restore_snapshot(session, data)

Create object using snapshot data.

property satisfied_limits

Deviations from target distances (in Angstroms) beyond which restraints will be considered unsatisfied.

property satisfieds

Returns true for restraints whose deviations from their target distances are less than satisfied_limit. Read only.

property 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.

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.

property targets

Target distances in Angstroms

property tolerances

Half-widths of potential well flat bottoms in Angstroms

property unsatisfieds

Returns true for restraints whose deviations from their target distances are greater than or equal to satisfied_limit. Read only.

property visibles

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

Proper Dihedral Restraints

ProperDihedralRestraintMgr

class chimerax.isolde.restraints.ProperDihedralRestraintMgr(model, c_pointer=None, auto_add_to_session=True, display_name='Proper Dihedral Restraints')

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)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, auto_add_to_session=True, display_name='Proper Dihedral Restraints')
accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

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 ProperDihedralRestraints instance.

Args:
  • residues:
    • a chimerax.Residues instance

add_drawing(d)

Add a child drawing.

add_restraint(dihedral)

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

Args:
  • dihedral:
    • a ProperDihedral instance

add_restraint_by_residue_and_name(residue, name)

Singular form of add_restraints_by_residues_and_name(). Returns a ProperDihedralRestraint 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 ProperDihedralRestraints instance covering the dihedrals in the input. Only one ProperDihedralRestraint 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 ProperDihedrals instance.

add_restraints_by_residues_and_name(residues, name)

Convenience function wrapping add_restraints(). Returns a ProperDihedralRestraints 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

disable_mutually_exclusive_restraints(restraints, enabled_only=True)

ProperDihedralRestraints and AdaptiveDihedralRestraints are mutually exclusive by design - the last thing we want is two different restraints fighting over the same dihedral!

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 ProperDihedralRestraints 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 ProperDihedralRestraint instance (or None if no restraint exists for this dihedral).

Args:
  • dihedral:
    • a ProperDihedral instance

get_restraint_by_residue_and_name(residue, name)

Singular form of get_restraints_by_residues_and_name(). Returns a ProperDihedralRestraint 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 ProperDihedralRestraints instance covering the dihedrals in the input. Unlike add_restraints(), no new ProperDihedralRestraint 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 ProperDihedrals instance.

get_restraints_by_residues_and_name(residues, name)

Convenience function wrapping get_restraints(). Returns a ProperDihedralRestraints 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property normals

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

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property 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, update_graphics=True)

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(update_graphics=True)

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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_visibility=False)

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

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property visible_restraints

Returns a ProperDihedralRestraints instance containing all currently visible restraints. A restraint is visible if it is enabled, at least the axial bond of its ProperDihedral 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.

was_deleted

Indicates whether this Drawing has been deleted.

ProperDihedralRestraint

class chimerax.isolde.restraints.ProperDihedralRestraint(c_pointer)
property annotation_color

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

property cutoff

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

property dihedral

The restrained ProperDihedralRestraint. Read only.

property display

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

property enabled

Enable/disable this restraint or get its current state.

property mgr

ProperDihedralRestraintMgr for this restraint. Read only.

property offset

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

property satisfied

Returns True if the current deviation from the target angle is less than satisfied_limit.

property satisfied_limit

Deviation from target angle beyond which restraint will be considered unsatisfied.

property 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.

property spring_constant

Get/set the spring constant for this restraint in kJ mol^{-1} rad^{-2}

property target

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

property unsatisfied

Returns True if the current deviation from the target angle is greater than or equal to satisfied_limit.

property visible

Is this restraint currently visible? Read-only.

ProperDihedralRestraints

class chimerax.isolde.restraints.ProperDihedralRestraints(c_pointers=None)
__init__(c_pointers=None)
property annotation_colors

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

property cutoffs

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

property dihedrals

The restrained {ProperDihedrals}. Read only.

property displays

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

property enableds

Enable/disable each restraint or get their current states.

property offsets

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

property satisfied_limits

Deviations from target angle beyond which restraint will be considered unsatisfied.

property satisfieds

Returns True for restraints where the current deviation from the target angle is less than satisfied_limit.

property sim_indices

Index of each restraint in the relevant 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.

property spring_constants

Get/set the spring constant for each restraint in kJ mol^{-1} rad^{-2}

property targets

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

property unsatisfieds

Returns True for restraints where the current deviation from the target angle is greater than or equal to satisfied_limit.

property visibles

Is each restraint currently visible? Read-only.

Adaptive Dihedral Restraints

AdaptiveDihedralRestraintMgr

class chimerax.isolde.restraints.AdaptiveDihedralRestraintMgr(model, c_pointer=None, auto_add_to_session=True)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, auto_add_to_session=True)
accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

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 ProperDihedralRestraints instance.

Args:
  • residues:
    • a chimerax.Residues instance

add_drawing(d)

Add a child drawing.

add_restraint(dihedral)

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

Args:
  • dihedral:
    • a ProperDihedral instance

add_restraint_by_residue_and_name(residue, name)

Singular form of add_restraints_by_residues_and_name(). Returns a ProperDihedralRestraint 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 ProperDihedralRestraints instance covering the dihedrals in the input. Only one ProperDihedralRestraint 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 ProperDihedrals instance.

add_restraints_by_residues_and_name(residues, name)

Convenience function wrapping add_restraints(). Returns a ProperDihedralRestraints 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

static angle_range_to_kappa(angle_range)

Returns the kappa value that will limit the restraining force to approximately target +/- angle_range.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

disable_mutually_exclusive_restraints(restraints, enabled_only=True)

ProperDihedralRestraints and AdaptiveDihedralRestraints are mutually exclusive by design - the last thing we want is two different restraints fighting over the same dihedral!

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 ProperDihedralRestraints 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 ProperDihedralRestraint instance (or None if no restraint exists for this dihedral).

Args:
  • dihedral:
    • a ProperDihedral instance

get_restraint_by_residue_and_name(residue, name)

Singular form of get_restraints_by_residues_and_name(). Returns a ProperDihedralRestraint 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 ProperDihedralRestraints instance covering the dihedrals in the input. Unlike add_restraints(), no new ProperDihedralRestraint 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 ProperDihedrals instance.

get_restraints_by_residues_and_name(residues, name)

Convenience function wrapping get_restraints(). Returns a ProperDihedralRestraints 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property normals

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

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property 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, update_graphics=True)

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(update_graphics=True)

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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_visibility=False)

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

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

property visible_restraints

Returns a ProperDihedralRestraints instance containing all currently visible restraints. A restraint is visible if it is enabled, at least the axial bond of its ProperDihedral 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.

was_deleted

Indicates whether this Drawing has been deleted.

AdaptiveDihedralRestraint

class chimerax.isolde.restraints.AdaptiveDihedralRestraint(c_pointer)
property alpha

Sets the rate at which the restraining potential flattens out (in other words, how fast the force drops to zero) outside of the well region set by kappa. If alpha is zero, the force outside the well is essentially zero. Increasing alpha increases the applied force. While values between -1 and 2 are allowed, in general it is advisable to stick to values between 0 and 1. For values larger than 1, the force outside the well will grow more steeply than inside; for values less than zero the force outside the well will become repulsive.

property annotation_color

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

property applied_moment

Current moment (or torque) around the axis of this dihedral, in kJ/mol

property dihedral

The restrained AdaptiveDihedralRestraint. Read only.

property display

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

property enabled

Enable/disable this restraint or get its current state.

property kappa

Sets the width of the region within which the dihedral will be restrained. For values of kappa greater than about 1, the effective standard deviation is approximately equal to sqrt(1/kappa)`. As kappa approaches zero the shape of the energy profile approaches a standard cosine. Values of kappa below zero are not allowed.

property mgr

AdaptiveDihedralRestraintMgr for this restraint. Read only.

property offset

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

property satisfied

Returns True if the current deviation from the target angle is less than satisfied_limit.

property satisfied_limit

Deviation from target angle beyond which restraint will be considered unsatisfied.

property 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.

property spring_constant

Get/set the spring constant for this restraint in kJ mol^{-1} rad^{-2}

property target

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

property unsatisfied

Returns True if the current deviation from the target angle is greater than or equal to satisfied_limit.

property visible

Is this restraint currently visible? Read-only.

AdaptiveDihedralRestraints

class chimerax.isolde.restraints.AdaptiveDihedralRestraints(c_pointers=None)
__init__(c_pointers=None)
property alphas

Sets the rate at which the restraining potential flattens out (in other words, how fast the force drops to zero) outside of the well region set by kappa. If alpha is zero, the force outside the well is essentially zero. Increasing alpha increases the applied force. While values between -1 and 2 are allowed, in general it is advisable to stick to values between 0 and 1. For values larger than 1, the force outside the well will grow more steeply than inside; for values less than zero the force outside the well will become repulsive.

property annotation_colors

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

property applied_moments

Current moment (or torque) around the axis of each dihedral, in kJ/mol

property dihedrals

The restrained {ProperDihedrals}. Read only.

property displays

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

property enableds

Enable/disable each restraint or get their current states.

property kappas

Sets the width of the region within which the dihedral will be restrained. For values of kappa greater than about 1, the effective standard deviation is approximately equal to \sqrt{\frac{1}{\kappa}}. As kappa approaches zero the shape of the energy profile approaches a standard cosine. Values of kappa below zero are not allowed.

property offsets

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

property satisfied_limits

Deviations from target angle beyond which restraint will be considered unsatisfied.

property satisfieds

Returns True for restraints where the current deviation from the target angle is less than satisfied_limit.

property sim_indices

Index of each restraint in the relevant 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.

property spring_constants

Get/set the spring constant for each restraint in kJ mol^{-1} rad^{-2}

property targets

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

property unsatisfieds

Returns True for restraints where the current deviation from the target angle is greater than or equal to satisfied_limit.

property visibles

Is each restraint currently visible? Read-only.

Chirality Restraints

ChiralRestraintMgr

class chimerax.isolde.restraints.ChiralRestraintMgr(model, c_pointer=None, auto_add_to_session=True)

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_chiral_restraint_mgr(m)
ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, auto_add_to_session=True)
accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_restraint(chiral)

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

Args:
  • dihedral:
    • a ChiralCenter instance

add_restraints(chirals)

Returns a ChiralRestraints instance covering the Chiral_Centres in the input. Only one ChiralRestraint 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 ChiralCenters instance.

add_restraints_by_atoms(atoms)

Returns a ChiralRestraints 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 ChiralRestraint instance (or None if no restraint exists for this chiral centre).

Args:
  • chiral:
    • a ChiralCenter instance

get_restraints(chirals)

Returns a ChiralRestraints instance covering the ChiralCenters in the input. Unlike add_restraints(), no new ChiralRestraint 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 ChiralCenters instance.

get_restraints_by_atoms(atoms)

Returns a ChiralRestraints 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
new_drawing(name, *, subclass=None)

Create a new empty child drawing.

property normals

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

property 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Save a snapshot of the state of restraints for all or a subset of atoms (typically the mobile atoms in a running simulation). Override in derived classes.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property selected

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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.

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

was_deleted

Indicates whether this Drawing has been deleted.

ChiralRestraint

class chimerax.isolde.restraints.ChiralRestraint(c_pointer)

Handles the restraint of a single chiral centre in simulations. Unlike other restraints, ChiralRestraint 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 ChiralMgr.chiral_center_dict).

__init__(c_pointer)
property center

Centroid of the atoms defining the restrained chiral center. Read only.

property cpp_pointer

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

property cutoff

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

property deleted

Has the C++ side been deleted?

property dihedral

The restrained ChiralCenter. Read only.

property enabled

Enable/disable this restraint or get its current state.

property mgr

ChiralRestraintMgr for this restraint. Read only.

property offset

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

static restore_snapshot(session, data)

Create object using snapshot data.

property satisfied

Returns True if the current deviation from the target angle is less than satisfied_limit.

property satisfied_limit

Deviation from target angle beyond which restraint will be considered unsatisfied.

property 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.

property spring_constant

Get/set the spring constant for this restraint in kJ mol^{-1} rad^{-2}

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.

property target

Target angle for this restraint in radians. Read only.

property unsatisfied

Returns True if the current deviation from the target angle is greater than or equal to satisfied_limit.

ChiralRestraints

class chimerax.isolde.restraints.ChiralRestraints(c_pointers=None)
__init__(c_pointers=None)
property centers

Centroids of the atoms defining each restrained chiral center. Read only.

property cutoffs

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

property dihedrals

Returns the restrained ChiralCenters. Read only.

property enableds

Enable/disable each restraint or get their current states.

property offsets

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

static restore_snapshot(session, data)

Create object using snapshot data.

restrict_to_sel(atoms)

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

property satisfied_limits

Deviations from target angle beyond which restraint will be considered unsatisfied.

property satisfieds

Returns True for all restraints where the current deviation from the target angle is less than satisfied_limit.

property 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.

property spring_constants

Get/set the spring constants for each restraint in kJ mol^{-1} rad^{-2}

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.

property targets

Target angles for each restraint in radians. Read only.

property unsatisfieds

Returns True for all restraints where the current deviation from the target angle is greater than or equal to satisfied_limit.

Rotamer Restraints

RotamerRestraintMgr

class chimerax.isolde.restraints.RotamerRestraintMgr(model, c_pointer=None, auto_add_to_session=True)

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

ALL_EDGES_DISPLAY_MASK = 7

Edge mask for displaying all three triangle edges (bits 0, 1, 2).

Dot = 'dot'

Display style showing only dots at triangle vertices.

HIGHLIGHT_DRAW_PASS = 'highlight'

Draw pass to render only the highlighted parts of drawings.

INCLUDE_MAPS = 4

state flag

LAST_DRAW_PASS = 'last'

Draw pass to render after everything else for showing labels on top.

Mesh = 'mesh'

Display style showing only edges of triangles.

OPAQUE_DRAW_PASS = 'opaque'

Draw pass to render only opaque drawings.

SCENE = 1

state flag

SESSION = 2

state flag

Solid = 'solid'

Display style showing filled triangles.

TRANSPARENT_DEPTH_DRAW_PASS = 'transparent depth'

Draw pass to render only the depth of transparent drawings.

TRANSPARENT_DRAW_PASS = 'transparent'

Draw pass to render only transparent drawings.

__init__(model, c_pointer=None, auto_add_to_session=True)

Manages rotamer restraints for a single model

accept_multishadow

False means not to show multishadow on this Drawing even if global multishadow is on.

accept_shadow

False means not to show shadow on this Drawing even if global shadow is on.

add(models) None

Add child models to this model.

add_drawing(d)

Add a child drawing.

add_restraint(rotamer_or_residue)

Returns a RotamerRestraint 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 RotamerRestraints 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.

allow_clipping

False means not to clip this Drawing even if global clipping is on.

allow_depth_cue

False means not show depth cue on this Drawing even if global depth cueing is on.

property allow_hydrogens

Choose whether to allow all hydrogens (“all”), only polar hydrogens (“polar”), or no hydrogens (“no”) to be restrained/tugged. For position restraints the default is “no”; for interactive tugging the default is “polar”.

ambient_texture

A 3-dimensional texture that modulates the brightness of surface vertex colors. Used for fast rendering of ambient occlusion lighting.

ambient_texture_transform

Transformation mapping vertex coordinates to ambient_texture coordinates, a geometry.Place object.

any_part_highlighted()

Is any part of this Drawing or its children highlighted.

property atomspec

Return the atom specifier string for this structure.

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.

casts_shadows = True

Whether this drawing creates shadows when shadows are enabled.

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.

property color
colormap

Maps 2D and 3D texture values to colors.

colormap_range

Data value range corresponding to ends of colormap.

property colors
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 SimHandler.push_coords_to_sim()!

Args:
  • rotamer:
    • a Rotamer instance

cpp_del_model()

Called by the C++ layer to request that the model be deleted

property 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()

Supported API. Delete this model.

property deleted

Has the C++ side been deleted?

property display
property display_positions
property display_style
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.

property drawing_lineage

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

property edge_mask
empty_drawing()

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

first_intercept(mxyz1, mxyz2, exclude=None)

So that generic models can be properly picked. Most model classes override this.

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 RotamerRestraint 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 RotamerRestraints 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

property highlighted
property highlighted_displayed_triangles_mask

Mask of highlighted and displayed triangles.

property highlighted_positions
property highlighted_triangles_mask
property 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.

inherit_graphics_exemptions

Whether disabled lighting and clipping in parent will be copied to child when drawing is added.

property model_color
multitexture

List of N textures to use, each applying to 1/N of the triangles. This is used for volumetric rendering by texturing a stack of rectangles. Only 2-dimensional textures are supported. Can be None.

multitexture_reverse_order

Whether to draw multitextured geometry in reverse order for handling transparency. Used by grayscale rendering for depth ordering.

property name
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

property normals

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

property num_restraints

Number of RotamerRestraint 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.

on_top

Whether to draw on top of everything else. Used for text labels.

opaque_texture

Whether the texture for surface coloring is opaque or transparent.

pickable = False

Whether this drawing can be picked by View.picked_object().

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 ‘all’ if this drawing and its children should be excluded from the pick, or true if just this drawing should be excluded. Return a list of Pick objects for the contained items. This routine is used for highlighting objects in a frustum.

property position
property positions
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.

restore_checkpoint(data)

Restore the state of restraints from a checkpoint.

restore_geometry(session, data)

Restore model and drawing state saved with save_geometry().

static restore_snapshot(session, data)

Create object using snapshot data.

save_checkpoint(atoms=None)

Since RotamerRestraintMgr is just a convenience layer over ProperDihedralRestraintMgr, there is no need to save/restore checkpoints.

save_geometry(session, flags)

Return state for saving Model and Drawing geometry that can be restored with restore_geometry().

property scene_position
property selected

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

set_geometry(vertices, normals, triangles, edge_mask=None, triangle_mask=None)

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.

property shape_changed
show_metadata(session, *, verbose=False, log=None, **kw)

called by ‘log metadata’ command.

showing_transparent(include_children=True)

Are any transparent objects being displayed. Includes all children.

skip_bounds = False

Whether this drawing is included in calculation by bounds().

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.

texture

Texture to use in coloring the surface, a graphics.Texture object. Only 2-dimensional textures are supported. Can be None.

texture_coordinates

Texture coordinates, an N by 2 numpy array of float32 values in range 0-1

property triangle_mask
property 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.

use_lighting

Whether to use lighting when rendering. If false then a flat unshaded color will be shown.

property vertex_colors
property vertices

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

was_deleted

Indicates whether this Drawing has been deleted.

RotamerRestraint

class chimerax.isolde.restraints.RotamerRestraint(c_pointer)

Rotamer restraints are special in that they only exist as wrappers around combinations of ProperDihedralRestraint 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)
property chi_restraints

Returns a ProperDihedralRestraints covering the chi dihedrals in this rotamer.

property cpp_pointer

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

property deleted

Has the C++ side been deleted?

property enabled

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

property mgr

RotamerRestraintMgr for this restraint. Read only.

property residue

chimerax.Residue to be restrained. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property 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

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.

property 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.

RotamerRestraints

class chimerax.isolde.restraints.RotamerRestraints(c_pointers=None)
__init__(c_pointers=None)
property enableds

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

property residues

chimerax.Residues to be restrained. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property 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).

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.

property 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.