# General Utilities

- Session Extensions
- View
- Ctypes Support
- Threading
- Parameter Management

## Session Extensions

A set of convenience functions to safely get/create any of ISOLDE’s core manager objects.

`chimerax.isolde.session_extensions.``get_adaptive_distance_restraint_mgr`(model)

  Get the `Distance_Restraint_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

`chimerax.isolde.session_extensions.``get_chiral_mgr`(session)

  Get the session-level `Chiral_Mgr` singleton, creating it if it doesn’t yet exist.

  Args;
    - session:
        - the top-level ChimeraX session instance

`chimerax.isolde.session_extensions.``get_chiral_restraint_mgr`(model)

  Get the `Chiral_Restraint_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

`chimerax.isolde.session_extensions.``get_distance_restraint_mgr`(model)

  Get the `Distance_Restraint_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

`chimerax.isolde.session_extensions.``get_mdff_mgr`(model, volume, create=False)

  Get the `MDFF_Mgr` for the given model and volume, optionally creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure` instance
    - volume:
        - a `chimerax.map.Volume` instance. The `MDFF_Mgr` will be added as a submodel to the `Volume`
    - create (default=False):
        - if True, creates and returns a `MDFF_Mgr` if one doesn’t already exist

`chimerax.isolde.session_extensions.``get_position_restraint_mgr`(model)

  Get the `Position_Restraint_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

`chimerax.isolde.session_extensions.``get_proper_dihedral_mgr`(session)

  Get the session-level `Proper_Dihedral_Mgr` singleton, creating it if it doesn’t yet exist.

  Args;
    - session:
        - the top-level ChimeraX session instance

`chimerax.isolde.session_extensions.``get_proper_dihedral_restraint_mgr`(model)

  Get the `Proper_Dihedral_Restraint_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

`chimerax.isolde.session_extensions.``get_rama_annotator`(model, create=True)

  Get the `Rama_Annotator` for the given model, optionally creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure` instance
    - create (default=True):
        - if True and no `Rama_Annotator` already exists for the
        - model, one will be created and returned.

`chimerax.isolde.session_extensions.``get_ramachandran_mgr`(session)

  Get the session-level `Rama_Mgr` singleton, creating it if it doesn’t yet exist.

  Args;
    - session:
        - the top-level ChimeraX session instance

`chimerax.isolde.session_extensions.``get_rota_annotator`(model, create=True)

  Get the `Rotamer_Annotator` for the given model, optionally creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure` instance
    - create (default=True):
        - if True and no `Rotamer_Annotator` already exists for the model, one will be created and returned.

`chimerax.isolde.session_extensions.``get_rotamer_mgr`(session)

  Get the session-level `Rota_Mgr` singleton, creating it if it doesn’t yet exist.

  Args;
    - session:
        - the top-level ChimeraX session instance

`chimerax.isolde.session_extensions.``get_rotamer_restraint_mgr`(model)

  Get the `Rotamer_Restraint_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

`chimerax.isolde.session_extensions.``get_tuggable_atoms_mgr`(model)

  Get the `Tuggable_Atoms_Mgr` for the given model, creating it if it doesn’t yet exist.

  Args;
    - model:
        - a `chimerax.AtomicStructure`

## View

`chimerax.isolde.view.``focus_on_coord`(session, center, radius=1.0, clip=True)

  Focus the main view on a coordinate, maintaining the current center of rotation method and optionally updating the near and far clipping planes.

  Args:
    - session:
        - the top-level ChimeraX session instance
    - center:
        - (x,y,z) coordinates as a Numpy array
    - radius (default=5.0):
        - the zoom level, camera position and (optionally) clipping planes will be adjusted to ensure that everything within at least this distance from the center is shown.
    - clip (default=True):
        - if True, updates the near and far clipping planes.

`chimerax.isolde.view.``focus_on_selection`(session, atoms, pad=1.0, clip=True)

  Focus the main view on a selecton of atoms, maintaining the current center of rotation method and optionally updating the near and far clipping planes.

  Args:
    - session:
        - the top-level ChimeraX session instance
    - atoms:
        - a `chimerax.Atoms` instance
    - pad (default=5.0):
        - the zoom level, camera position and (optionally) clipping planes will be adjusted to ensure that everything within at least this distance from the selection is shown.
    - clip (default=True):
        - if True, updates the near and far clipping planes.

## Ctypes Support

## Threading

`chimerax.isolde.delayed_reaction.``delayed_reaction`(triggerset, trigger_name, initiator_func, initiator_args, ready_test_func, final_func, final_func_args)

  Designed to work together with threaded (Python or C++) objects, to start a long-running threaded task and then automatically apply the result (in a later GUI update) when done. Can also be used to simply conveniently call the desired callback once on the next firing of the trigger, by setting ready_test_func to None.

  Args:

  > - triggerset:
  >     - the `chimerax.core.triggers.TriggerSet` (or other class with similar functionality) providing the trigger (e.g. session.triggers)
  > - trigger_name:
  >     - the name of the trigger (e.g. ‘new frame’)
  > - initiator_func:
  >     - A handle to the function that kicks off the threaded process. Any return value will be ignored.
  > - initiator_args:
  >     - A tuple of arguments to be applied to initiator_func
  > - ready_test_func:
  >     - Should return True when the threaded task is done, False otherwise. Set it to None to just run on the next firing of the trigger.
  > - final_func:
  >     - Task to run once the thread is done.
  > - final_func_args:
  >     - A tuple of arguments to be applied to final_func (e.g. to tell it what to do with the thread result)

  A simple example using the `Delayed_Reaction_Tester` below to print some output to the ChimeraX log after a delay of 100 frames (assuming the code is run from the ChimeraX Shell or some other environment where session is already defined):

      dt = Delayed_Reaction_Tester()
      delayed_reaction(session.triggers, 'new frame', dt.initiator_func,
          (100,), dt.ready_test_func, dt.final_func, ('Finished!,'))

## Parameter Management

class `chimerax.isolde.param_mgr.``Param_Mgr`(**kw)

  A manager for important parameters to keep them all in one place, rather than spread as variables throughout a large class. On object initialisation, the docstring will be automatically generated to list the parameters and their default values (and units where applicable). Addition of new parameters after initialisation is not allowed. Once initialised, parameter values may be changed by either (for example):

  obj.set_param(name, new_value)

  or

  obj.name = new_value

  Values are retrievable either by:

  val = obj.name

  or

  val = obj[name]