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. 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: :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: Homonuclear=1.

: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.

: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. 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.

  • | adds the css class border to the figure

    :drop:`|I1p` -> I1p

  • ^A ^B ^C ^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.

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

    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

    I1p :drop:`|^B I1p`

    I1p :drop:`|^Bp50 I1p`

    I1p :drop:`|^Bp100 I1p`

    I1p :drop:`|^Bp150 I1p`

    Different values of p, q, or r

    I1p :drop:`|^B I1p`

    I1p :drop:`|^Bp50 I1p`

    I1p :drop:`|^Bq50 I1p`

    I1p :drop:`|^Br50 I1p`

  • { enables Separation Based on Coherence Order p 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