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 conf.py file by adding it to the extensions list:

extensions = ['drops']

ReST Directive

.. drops:: PTON

The drops directive inserts a DROPS image representing the Plain Text Operator Notation into the docuemnt. It takes a number of options:

: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
:align:
Causes the image to float and align itself on the page in this direcion, valid values are “right” and “left”.
:sequence: <sequence name>
Select the sequence to be loaded in the simulation.
:window: <window name>
Open the Window named <window name> in SpinDrops, ie List Basis Elems or Preferences.

:prefs:

Set preference values in SpinDrops. This can be a ‘;’-separated list of name=value pairs, where the values are json-parseable values, ie Current Layout=1;Current Separation=0;Show Axes=true
:nspin:
Set the number of spins in the simulation, can also be accomplished with the prefs options and setting the “Current Layout” appropriately.
:time:
Set the simulation time.
:height:
The height of the image, either as a px value, or a percentage of the width.
:width:
Set the width of the image, either as a px value, or a percentage of the nominal layout width.
:aspect:
Sets the aspect ratio (width/height) as a percentage.
:view:
Sets the viewpoint to one of a number of pre-defined positions: A,B,C,D.
:class:
Set the html/css classes of the image, ie, ‘border’ will add a border to the image.

ReST Text Roles

:pton:

This text role converts a PTON string into a math element with the PTON replaced by the standard operator notation rendered in LaTeX. For example: :pton:`I1x` produces \(I_{1x}\)

: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 image will be created, whereas if the :drop: is in a table or at the top level of the document, a figure with the corresponding PTON set as the figure’s caption will be produced.

The role :drop:`I1x` produces an inline image: I1x .

Some flags are available to modify the DROPS image:

  • .scheme selects the preference scheme in SpinDrops, from the loaded settings, the scheme name must be followed by a whitespace character.

  • | adds the css class border to the figure

    :drop:`|I1p` -> I1p

  • ^A ^B ^C ^D changes the viewpoint to one of the preset views: A, B, C, or D.

    :drop:`|^AI1p` -> I1p :drop:`|^BI1p` -> I1p :drop:`|^CI1p` -> I1p :drop:`|^DI1p` -> I1p

  • { enables Separation Based on Coherence Order in the display.

    :drop:`|^C{I1p` -> I1p

  • /n changes the image width to (100/n)% of the page, n must be followed by a space or non-digit character. For example, /3 I1x creates an image that is 1/3 of the page width. The default image width is 200 px.

    :drop:`|/4I1p` -> I1p :drop:`|/6I1p` -> I1p

  • #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.

    :drop:`|#2I1p` -> I1p :drop:`|#3I1p` -> I1p

  • "caption" sets the figure caption to the quoted string. Example :drop:`"neato"I1x`

  • [...] sets a prefs string, as in the :prefs: option.

    :drop:`|[Show Axes=false]I1p` -> I1p