=============== DROPS in Sphinx =============== The `sphinx `_ `drops` extension adds two roles and one directive to ReST processing. It was used to create most of the SpinDrops example images on this website. To enable the extensions, install the drops.py extension, and enable it in your sphinx :code:`conf.py` file by adding it to the extensions list:: extensions = ['drops'] ReST Directive ============== .. rst:directive:: .. drops:: PTON The `drops` directive inserts a DROPS image representing the :ref:`PTON` into the docuemnt. It takes a number of options: :code:`:caption:` This options can be blank to disable the generation of a caption. Otherwise, it contains text (potentially :pton:) to serve as the figure's caption :code:`:align:` Causes the image to float and align itself on the page in this direcion, valid values are "right" and "left". :code:`:sequence: ` Select the sequence to be loaded in the simulation. :code:`:window: ` Open the Window named `` in SpinDrops, ie List Basis Elems or Preferences. .. _sphinx_prefs: :code:`:prefs:` Set preference values in SpinDrops. This can be a ';'-separated list of name=value pairs, where the values are json-parseable values, ie :code:`Current Layout=1;Current Separation=0;Show Axes=true` :code:`:nspin:` Set the number of spins in the simulation, can also be accomplished with the :code:`prefs` options and setting the `"Current Layout"` appropriately. Additional parameters for the spin offsets, and J-couplings can be provided after a `;`. Such an example, for a two spin system with the spins having offsets of 1 and 2, respectively, and a J-coupling of 2.2: :code:`:nspin: 2; v1=1; v2=2; J12=2.2`. Furthermore, a flag can be added to signify that the system should be presented to the simulator as a Homonuclear system thusly: :code:`Homonuclear=1`. :code:`:pdir:` Override default preferences directory. By default, the pdir is chosen based on the ``nspin`` parameter, but this can be overridden by setting this explicitly. The built-in available pdirs are ``doc1``, ``doc2``, ``doc3``, and ``doc3c``. :code:`:time:` Set the simulation time. :code:`:height:` The height of the image, either as a px value, or a percentage of the width. :code:`:width:` Set the width of the image, either as a px value, or a percentage of the nominal layout width. :code:`:aspect:` Sets the aspect ratio (width/height) as a percentage. :code:`:view:` Sets the viewpoint. See :ref:`drops_view_reference` for the full list of view, world, and zoom values. :code:`:class:` Set the html/css classes of the image, ie, 'border' will add a border to the image. .. _drops_view_reference: Visual Reference: ``:view:`` Option =================================== The ``:view:`` value combines an optional **world** letter (``A``-``D``), an optional **view shift** letter (``p``, ``q``, or ``r``), and an optional **scale percentage**. Format: :code:`[ABCD][pqr][NN]` (any element can be omitted). World Orientation (A, B, C, D) ------------------------------ The world letter sets the orientation of the spin system relative to the camera (it rotates the scene around the X axis): .. list-table:: World orientations :class: no-cap-num :widths: 25 25 25 25 * - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: A :caption: ``A`` — looking down −Z (xy plane) - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: B :caption: ``B`` — tilted ≈25° forward - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: C :caption: ``C`` — tilted ≈75° forward (default) - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: D :caption: ``D`` — top-down (xz plane) If no world letter is given the previously-set world is used (or the preset default ``C`` if the directive sets the view explicitly). View Shift (p, q, r) -------------------- The view shift letter selects how the camera is positioned relative to the spin system. Each shift has a different base distance and offset: .. list-table:: View shifts (3-spin system) :class: no-cap-num :widths: 33 33 33 * - .. drops:: 4I1xI2yI3z :nspin: 3 :width: 90% :view: Cp :caption: ``Cp`` — centered, base distance 20 - .. drops:: 4I1xI2yI3z :nspin: 3 :width: 90% :view: Cq :caption: ``Cq`` — shifted up, closer (base 12) - .. drops:: 4I1xI2yI3z :nspin: 3 :width: 90% :view: Cr :caption: ``Cr`` — shifted left, base distance 20 Zoom Scale (percentages) ------------------------ The optional integer after ``p``/``q``/``r`` is a zoom percentage. Higher numbers zoom in (closer camera). Below, the same operator under increasing zoom: .. list-table:: Zoom scaling with ``p`` :class: no-cap-num :widths: 25 25 25 25 * - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: Cp80 :caption: ``Cp80`` — far - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: Cp120 :caption: ``Cp120`` - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: Cp170 :caption: ``Cp170`` - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: Cp250 :caption: ``Cp250`` — close If only the world letter is given (e.g. ``:view: C``) the ``drops`` extension uses a built-in **default view** tuned for the ``:nspin:`` of the directive. These defaults are reasonable for 4:3 images; for wide-aspect images use an explicit ``pNNN``, ``qNNN``, or ``rNNN`` value. .. _drops_aspect_reference: Visual Reference: ``:aspect:`` and ``:width:`` ============================================== ``:width:`` is the rendered width of the image (a CSS percentage of the page width or an absolute pixel count). ``:aspect:`` is the width-to-height ratio expressed as a percentage (so ``:aspect: 200%`` means width = 2× height). Without ``:aspect:`` the default is 4:3 (133%). .. list-table:: Aspect ratios with ``:view: Cp170`` :class: no-cap-num :widths: 33 33 33 * - .. drops:: 2I1xI2y :nspin: 2 :width: 99% :aspect: 100% :view: Cp170 :caption: ``aspect: 100%`` - .. drops:: 2I1xI2y :nspin: 2 :width: 99% :aspect: 200% :view: Cp170 :caption: ``aspect: 200%`` - .. drops:: 2I1xI2y :nspin: 2 :width: 99% :aspect: 250% :view: Cp170 :caption: ``aspect: 250%`` For wide aspects (>150%) you generally want a tighter zoom (e.g. ``Cp200`` or ``Cp250``) so the drops fill the frame. .. _drops_nspin_reference: Visual Reference: ``:nspin:`` ============================= ``:nspin:`` selects the spin layout in which the operator is rendered. Without it, the directive auto-detects the layout from the spin labels in the operator (``I1`` → 1-spin, ``I1...I2`` → 2-spin, ``I1...I2...I3`` → 3-spin). .. list-table:: nspin variations :class: no-cap-num :widths: 33 33 33 * - .. drops:: I1x :nspin: 1 :width: 90% :view: Cp200 :caption: ``nspin: 1`` - .. drops:: I1x :nspin: 2 :width: 90% :view: Cp170 :caption: ``nspin: 2`` (same operator) - .. drops:: I1x :nspin: 3 :width: 90% :view: Cp130 :caption: ``nspin: 3`` (same operator) Optional spin-system parameters can be appended after a ``;``. For example ``:nspin: 2; v1=1; v2=2; J12=2.2`` sets the offsets and the J-coupling. ``Homonuclear=1`` makes all spins share one channel. .. _drops_prefs_reference: Visual Reference: ``:prefs:`` ============================= ``:prefs:`` sets one or more preference values before the simulation runs. Multiple settings are separated by ``;``. Common knobs: .. list-table:: Common prefs :class: no-cap-num :widths: 50 50 * - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: Cp170 :prefs: Show Axes=true;Show Droplet Labels=true :caption: Axes + droplet labels - .. drops:: 2I1xI2y :nspin: 2 :width: 80% :view: Cp170 :prefs: Show Axes=false;Show Droplet Labels=false :caption: No axes, no labels Other useful prefs include ``Current Layout`` (``1``=1-spin, ``2``=2-spin, ``3``=3-spin chain, ``4``=3-spin triangle), ``Current Separation``, ``Magnetization Vectors``, ``Magnetization Droplets``, and ``Foreground``. .. _drops_window_reference: Visual Reference: ``:window:`` ============================== ``:window:`` opens a SpinDrops window inside the rendered image. Multiple windows can be opened by separating names with ``;``. Available windows include: * ``SequenceEditTable`` — pulse sequence editor * ``SysParamWindow`` — system parameters / ensemble editor * ``OperatorEditWindow`` — initial state editor * ``List Basis Elems`` — basis element list * ``Density Op.`` — density operator inspector * ``Operator Inspector`` — generic operator inspector * ``Preferences`` — preferences window * ``OptimWindow`` — pulse optimization window * ``SequenceExplWindow`` — sequence-element explainer * ``PulseExplWindow`` — pulse explainer * ``Elem. Propagator`` — elementary propagator inspector * ``EditProdOpWindow`` — product operator editor Combining ``:sequence:`` with ``:window:`` runs the simulation in the full ``MainFrame`` view (rather than the bare ``SingleFrame`` operator-only view). .. _drops_class_reference: Visual Reference: ``:class:`` ============================= ``:class:`` adds CSS classes to the rendered ``
``. The extension recognises ``border`` (adds a thin border) and ``no-cap-num`` (suppresses the figure number prefix in the caption). .. list-table:: Class examples :class: no-cap-num :widths: 50 50 * - .. drops:: I1x :nspin: 1 :width: 80% :view: Cp200 :class: border :caption: ``:class: border`` - .. drops:: I1x :nspin: 1 :width: 80% :view: Cp200 :caption: (no class) ReST Text Roles =============== .. rst:role:: pton This text role converts a :term:`PTON` string into a :rst:role:`math` element with the PTON replaced by the standard operator notation rendered in LaTeX. For example: ``:pton:`I1x``` produces :pton:`I1x` .. rst:role:: drop This directive can be used to create an inline DROPS image from a PTON string using SpinDrops. The text in the string can optionally contain a number of flags to control the image produced. If the :drop: occurs inline in text, a simple :rst:role:`image` will be created, whereas if the :drop: is in a table or at the top level of the document, a :rst:dir:`figure` with the corresponding PTON set as the figure's caption will be produced. The role :code:`:drop:`I1x`` produces an inline image: :drop:`@I1x`. Some flags are available to modify the DROPS image: .. + :code:`@` causes the DROPS to be rendered without a figure .. caption. + :code:`.scheme` selects the preference ``scheme`` in SpinDrops, from the loaded settings, the scheme name must be followed by a whitespace character. The default schemes are ``doc1``, ``doc2``, ``doc3``, and ``doc3c``: these are mostly base viewports for viewing different sized spin systems. This is the same setting as the drops directive's ``:pdir:`` option. + :code:`|` adds the css class ``border`` to the figure :code:`:drop:`|I1p`` -> :drop:`|I1p` + :code:`^A` :code:`^B` :code:`^C` :code:`^D` changes the viewpoint to one of the preset worlds: A, B, C, or D. This is equivalent to the ``:view:`` option to the `ReST Directive`_. :code:`:drop:`|^AI1p`` -> :drop:`|^AI1p` :code:`:drop:`|^BI1p`` -> :drop:`|^BI1p` :code:`:drop:`|^CI1p`` -> :drop:`|^CI1p` :code:`:drop:`|^DI1p`` -> :drop:`|^DI1p` It can be followed by an optional ``p``, ``q``, or ``r`` view scaler flag which is then followed by a percent-based integer scale: Different values of N in ``pN`` :drop:`|^B I1p` :code:`:drop:`|^B I1p`` :drop:`|^Bp50 I1p` :code:`:drop:`|^Bp50 I1p`` :drop:`|^Bp100 I1p` :code:`:drop:`|^Bp100 I1p`` :drop:`|^Bp150 I1p` :code:`:drop:`|^Bp150 I1p`` Different values of ``p``, ``q``, or ``r`` :drop:`|^B I1p` :code:`:drop:`|^B I1p`` :drop:`|^Bp50 I1p` :code:`:drop:`|^Bp50 I1p`` :drop:`|^Bq50 I1p` :code:`:drop:`|^Bq50 I1p`` :drop:`|^Br50 I1p` :code:`:drop:`|^Br50 I1p`` + :code:`{` enables :ref:`sep-p` in the display. :code:`:drop:`|^C{I1p`` -> :drop:`|^C{I1p` + :code:`/n` changes the image width to (100/n)% of the page, `n` must be followed by a space or non-digit character. For example, :code:`/3 I1x` creates an image that is 1/3 of the page width. The default image width is 200 px. :code:`:drop:`|/4I1p`` -> :drop:`|/4I1p` :code:`:drop:`|/6I1p`` -> :drop:`|/6I1p` + :code:`#n` causes the PTON to be rendered in the context of an `n`-spin system. The value for `n` must be followed by a non-digit character character. for example ``:drop:`#2 I1y``` or ``:drop:`#2I1x``` If this is unset, the default is to use the maximum spin number of the PTON to decide how big the spin system should be. :code:`:drop:`|#2I1p`` -> :drop:`|#2I1p` :code:`:drop:`|#3I1p`` -> :drop:`|#3I1p` + :code:`"caption"` sets the figure caption to the quoted string. Example ``:drop:`"neato"I1x``` .. this one appears to be broken at the moment! TODO: fix! .. :code:`:drop:`|"mary had a little lamb"I1p`` -> :drop:`|"mary had a little lamb"I1p` + :code:`[...]` sets a prefs string, as in the :ref:`:prefs:` option. :code:`:drop:`|[Show Axes=false]I1p`` -> :drop:`|[Show Axes=false]I1p`