# Accessing ISOLDE GUI functions from Python

class `chimerax.isolde.isolde.``IsoldeParams`(**kw)

  Contains the basic settings for defining and displaying the atoms and maps involved in an interactive simulation. Changes to parameter values will affect all future simulations in the ISOLDE session. At present, permanent changes can only be made by editing the corresponding entry in constants.py.

class `chimerax.isolde.isolde.``Isolde`(gui=None)

  The master ISOLDE class, primarily designed to be used by the ISOLDE GUI as the front-end interface for starting, controlling and analysing interactive simulations. Should only be used as a session-level singleton.

  `__init__`(gui=None)

    Initialises the ISOLDE object and adds it to the ChimeraX session as `session.isolde`.

    Args:
      - gui (default=None):
          - Used by the ISOLDE BundleAPI to prepare the ISOLDE GUI interface (i.e. when running from Tools/General/ISOLDE in the ChimeraX GUI menu).
  `add_checkpoint_block`(obj, reason)

    Some processes are incompatible with checkpointing. We need to know when these are running and disable checkpointing until they’re done.

    Args:
      - obj:
          - The Python object blocking checkpointing
      - reason:
          - A text string.
  `add_distance_restraint`(atom1, atom2, target, spring_constant)

    Adds a distance restraint between two atoms with the given target distance and spring constant. If the restraint already exists, just changes the target/spring constant and enables it.

    Args:
      - atom1, atom2:
          - `chimerax.Atom` instances pointing to the pair of atoms to be restrained.
      - target:
          - The target distance in Angstroms
      - spring_constant:
          - The restraint spring constant in kJ mol-1 nm-2
  `add_real_space_map`(existing_volume=None, filename=None, to_model=None)

    Associate a real-space map with the given model. The input map will be “slaved” to the target model to behave similarly to a crystallographic map. Exactly one of existing_volume or filename should be given.

    Args:
      - existing_volume (default None):
          - A `chimerax.Volume` object or None. If not None, the chosen `Volume` will be removed from the model tree, and replaced with a `clipper.maps.NXmapHandler` object.
      - filename (default None):
          - A map file of any format recognised by ChimeraX.
      - to_model (default None):
          - A `chimerax.AtomicStructure` or None. If None, the model currently selected by ISOLDE will be used as the target.
  `add_xtal_data`(filename, model=None)

    Add a set of maps derived from a crystal dataset (in MTZ format) to the target model. Cell dimensions and space group must match. If the file contains experimental measurements (F/sigF), a set of “live” maps will be generated and will be recalculated whenever the model coordinates change. If it contains precalculated map data (F/phi), one static map will be generated for each F/phi pair found.

    Args:
      - filename:
          - a file in .mtz format
      - model (default None):
          - A `chimerax.AtomicStructure` or None. If None, the model currently selected by ISOLDE will be used as the target.
  `can_checkpoint`

    Is checkpoint save/revert currently allowed?

  `change_selected_model`(model)

    Change the model upon which ISOLDE is focused (that is, upon which simulations will be run). This performs some basic preparations, including preparing any maps associated with the model for simulation. While ISOLDE is running, only atoms from the selected model will be selectable using the mouse.

    Args:
      - model:
          - a `chimerax.AtomicStructure` instance.
  `checkpoint`(*_)

    Save the current state of the simulation (coordinates and all restraints).

  `checkpoint_disabled_reasons`

    A `IsoldeParams` instance containing basic parameters controlling how the interactive simulation selection is defined and displayed.

  `clear_secondary_structure_restraints_for_selection`(*_, atoms=None, residues=None)

    Clear all secondary structure restraints in the selection. If no atoms or residues are provided, restraints will be cleared for any atoms selected in the main window.

    Args:
      - atoms (default: None):
          - A `chimerax.Atoms` instance or None
      - residues (default: None):
          - A `chimerax.Residues` instance or None

    atoms and residues arguments should not both be given in the same call. If neither is given, then all currently-selected atoms in the model will be released.

  `commit_sim`()

    Stop the simulation and keep the current coordinates.

  `discard_sim`(revert_to='checkpoint', warn=True)

    Stop the simulation and revert to either the starting state or the last saved checkpoint.

    Args:
      - revert_to (default: ‘checkpoint’):
          - Either ‘checkpoint’ or ‘start’
      - warn (default: True):
          - if warn is True and checkpoint==’start’, a warning dialog will be raised allowing the user to back out before discarding the simulation coordinates.
  `equilibrate`()

    Switch the imulation to equilibration mode

  `flip_peptide_bond`(res)

    Flip the peptide bond N-terminal to the given residue by the addition of temporary phi/psi restraints. Requires a simulation to be running.

    Args:
      - res:
          - A ChimeraX `Residue` instance
  `flip_peptide_omega`(res)

    Flip the peptide bond N-terminal to this residue from cis to trans or vice versa. Only usable when a simulation is running.

    Args:
      - res:
          - A `chimerax.Residue` instance pointing to a non-N-terminal amino acid residue.
  `ignored_residues`

    A `chimerax.Residues` object defining residues to be ignored for simulation purposes. Residues in this list will be retained in the model and used for map calculations, but will not be included in simulations. In most cases, this should only be populated with residues that have not been parameterised for MD.

  `load_demo_data`()

    Load a small protein model with crystallographic maps to explore.

  `load_model_and_data`(model_file, mtzfile)

    Load a model and MTZ file ready for simulation

    Args:
      - model_file:
          - a PDB or mmCIF file
      - mtzfile:
          - a MTZ file containing experimental F/sigF and/or precalculated F/phi columns.
  `minimize`()

    Switch the simulation to energy minimisation mode

  `params`

    Parameters controlling the initialisation and behaviour of the simulation.

  `pause_sim_toggle`()

    Pause/resume the simulation

  `release_rotamer`(rotamer_or_residue)

    Release all chi dihedral restraints on a single rotamer.

    Args:
      - rotamer_or_residue:
          - A `Rotamer` or a `chimerax.Residue` instance
  `release_rotamers`(rotamers_or_residues)

    Release all chi dihedral restraints on a set of rotamers.

    Args:
      - rotamers_or_residues:
          - Either a `Rotamers` or a `chimerax.Residues` instance
  `release_xyz_restraints_on_selected_atoms`(*_, sel=None)

    Release current position restraints on a set of atoms.

    Args:
      - sel (default: None):
          - A `chimerax.Atoms` instance giving the atoms to release, or None. If None, all currently-selected atoms from the current model will be released.
  `remove_checkpoint_block`(obj)

    Release a block on checkpointing. When all blocks are removed, checkpointing will be re-enabled.

    Args:
      - obj:
          - the Python object no longer blocking checkpointing
  `reset_sim_params`()

    Reset all the simulation parameters back to the defaults found in constants.py.

  `restrain_atom_to_xyz`(atom, target, spring_constant)

    Restrain the given atom to a (x,y,z) position.

    Args:
      - atom:
          - A `chimerax.Atom` instance pointing to an atom in the currently selected model. By default hydrogen atoms are not restrainable.
      - target:
          - An iterable giving the target (x,y,z) position in Angstroms
      - spring_constant:
          - The desired spring constant in kJ mol-1 nm-2
  `restrain_secondary_structure`(atoms, 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, and distance restraints on (CA(n)-CA(n+2)) and (O(n)-O(n+4)).

    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:
          - a string selected from the following:
              . ‘Helix’ . ‘Parallel Beta’ . ‘Antiparallel Beta’

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

  `revert_to_checkpoint`(*_)

    Return the simulation to the last saved checkpoint. Note: a checkpoint is automatically saved at the beginning of each simulation.

  `save_cif_file`(model, filename)

    Save a model in mmCIF format.

    Args:
      - model:
          - an `AtomicStructure`
      - filename:
          - a text string providing a valid filename (must end with .cif).
  `selected_model`

    Returns the atomic model on which ISOLDE is currently operating. Can be set.

  `selected_model_has_maps`

    Returns True if the selected model has at least one map associated with it, otherwise False. Read only.

  `show_master_help_in_browser`(*_)

    Open the ISOLDE help documentation.

  `sim_handler`

    Returns the `isolde.openmm.Sim_Handler` instance controlling the currently running simulation, or None if no simulation is running. Read only.

  `sim_manager`

    Returns the `isolde.openmm.Sim_Manager` instance providing high-level control over the current simulation. If no simulation is currently defined, returns None. Read only.

  `sim_paused`

    Returns True if the simulation is paused or no simulation is running, otherwise False.

  `simulation_mode`

    Returns ‘equil’ or ‘min’ depending on the state of the simulation, or None if no simulation is defined. Read only. To switch modes, use `isolde.minimize()` and :func@`isolde.equilibrate`.

  `simulation_running`

    Returns True if a simulation is running, otherwise False. Read only.

  `smoothing`

    Turn smoothing of the simulation trajectory visualisation on or off.

  `smoothing_alpha`

    Get/set the value of the constant defining how heavily smoothed the trajectory visualisation is. Value must be greater than zero and less than or equal to one. A value of 1 indicates no smoothing, while a value of 0.01 indicates that a given frame contributes only 1% to the displayed moving average.

  `start_sim`()

    Start an interactive simulation based around the currently-selected atoms.

  `stop_tugging`(atom_or_atoms)

    Release one or more atoms from the tugging force.

    Args:
      - atom_or_atoms:
          - A `chimerax.Atom` or `Atoms` instance
  `tug_atom_to`(atom, target, spring_constant=None)

    Tug an atom towards the given target coordinates in the context of a running simulation. If no spring constant is given, a default value will be used. NOTE: the tugging effect will remain in place until updated with a new call to tug_atom_to() or removed with stop_tugging(atom).

    Args:
      - atom:
          - The atom to be tugged. Must be a heavy atom that is mobile in the current simulation
      - target:
          - An iterable giving the (x,y,z) target in Angstroms
      - spring constant (default None):
          - An optional spring constant (in kJ mol-1 A-2). If none is provided, the default in sim_params.mouse_tug_spring_constant will be used.