From 127b400fbd026333449f53e215369dc03499dc2a Mon Sep 17 00:00:00 2001 From: Xavier Robin <xavier.robin@unibas.ch> Date: Wed, 10 Jul 2024 11:07:20 +0200 Subject: [PATCH] doc: add EditMode and example code --- modules/mol/base/doc/editors.rst | 69 ++++++++++++++++++++++++++------ 1 file changed, 56 insertions(+), 13 deletions(-) diff --git a/modules/mol/base/doc/editors.rst b/modules/mol/base/doc/editors.rst index b07b939b1..1469b2a8f 100644 --- a/modules/mol/base/doc/editors.rst +++ b/modules/mol/base/doc/editors.rst @@ -11,16 +11,30 @@ atoms. There are two flavors of editors, one for the internal coordinate system Edit Modes -------------------------------------------------------------------------------- -Editors support two modes: An unbuffered edit mode and a buffered edit mode. In -the unbuffered edit mode, dependent information such as the spatial organizer -and the internal coordinate system (in case of the XCSEditor) are updated after -every change. In buffered edit mode, the updates are delayed until one of the -following happens: +.. class:: EditMode - * The last editor goes out of scope. - * :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` is called - explicitly. + Editors support two modes: An unbuffered edit mode and a buffered edit mode. + .. attribute:: UNBUFFERED_EDIT + + This is the default edit mode in editors. In unbuffered edit mode, + dependent information such as the spatial organizer and the internal + coordinate system (in case of the :class:`XCSEditor`) are updated after + every change. + + .. warning:: + + The unbuffered edit mode can be extremely inefficient as every operation + can trigger expensive calculations. + + .. attribute:: BUFFERED_EDIT + + In buffered edit mode, the updates are delayed until one of the following + happens: + + * The last editor goes out of scope. + * :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` is called + explicitly. The editors follow the RIAA (resource allocation is initialization) principle: Whenever an editor is requested an internal reference counter is incremented. In @@ -31,6 +45,39 @@ In Python, one can not rely on the destructors being called. It is advised to always put a call to :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` when the editing is finished. +Here is a short example of how to use the editors to correctly create a +methionine residue: + +.. code-block:: python + + entity = ost.mol.CreateEntity() + + # A buffered external coordinate system editor covers most use cases + editor = entity.EditXCS(ost.mol.EditMode.BUFFERED_EDIT) + + # Insert a new protein chain + chain = editor.InsertChain("A"); + editor.SetChainType(chain, ost.mol.ChainType.CHAINTYPE_POLY_PEPTIDE_L) + + # Insert a residue + res1 = editor.AppendResidue(chain, "MET"); + res1.SetChemClass(ost.mol.L_PEPTIDE_LINKING) + res1.SetChemType(ost.mol.ChemType.AMINOACIDS) + + # Insert atoms + editor.InsertAtom(res1, "N", ost.geom.Vec3(21.609, 35.384, 56.705)) + editor.InsertAtom(res1, "CA", ost.geom.Vec3(20.601, 35.494, 57.793)) + editor.InsertAtom(res1, "C", ost.geom.Vec3(19.654, 34.300, 57.789)) + editor.InsertAtom(res1, "O", ost.geom.Vec3(18.447, 34.456, 57.595)) + + # Connect them + editor.Connect(res1.FindAtom("N"), res1.FindAtom("CA")) + editor.Connect(res1.FindAtom("CA"), res1.FindAtom("C")) + editor.Connect(res1.FindAtom("C"), res1.FindAtom("O")) + + # Finalize + editor.UpdateICS() + Basic Editing Operations -------------------------------------------------------------------------------- @@ -41,11 +88,7 @@ The basic functionality of editors is implemented in the EditorBase class. To use the editing functions available in :class:`EditorBase`, it is recommended to use the external coordinate system :class:`XCSEditor` with - buffering for performance reasons: - - .. code-block:: python - - editor = entity.EditXCS(ost.mol.EditMode.BUFFERED_EDIT) + buffering for performance reasons. .. class:: EditorBase -- GitLab