==========
Color Code
==========

Color Code for Droplets
-----------------------

Each droplet represents a complex function on a sphere (for more
details, see :ref:`Mathematical Background`).  A complex number
:math:`c` can be expressed in the form :math:`c=r \cdot exp(iφ)`,
where :math:`r` is the absolute value (represented by the distance
from the origin), :math:`φ` is the phase, and :math:`exp(iφ)` is the
phase factor of the complex number (represented by :ref:`the color
wheel shown below <Color Wheel>`). The examples here show the colors
of a spherical droplet (:math:`r=1`) with phase factors
(:math:`exp(iφ)`) of :math:`1` (red), :math:`i` (yellow), :math:`-1`
(green) and :math:`-i` (blue).

.. list-table:: Droplet Colors
   :header-rows: 1

   * - φ [deg]
     - φ [rad]
     - exp(iφ)
     - Color
     - Droplet Example
   * - 0°
     - 0
     - :math:`1`
     - Red
     - :drop:`@[Show Axes=false;Show Droplet Labels=false] 1*Id`
   * - 90°
     - :math:`\pi/2`
     - :math:`i`
     - Yellow
     - :drop:`@[Show Axes=false;Show Droplet Labels=false] i*Id`
   * - 180°
     - :math:`\pi`
     - :math:`-1`
     - Green
     - :drop:`@[Show Axes=false;Show Droplet Labels=false] -1*Id`
   * - 270°
     - :math:`3\pi/2`
     - :math:`-i`
     - Blue
     - :drop:`@[Show Axes=false;Show Droplet Labels=false] -i*Id`


Color Wheel
===========

The standard color wheel used to represent the phase factor :math:`exp(iφ)`:

.. figure:: _images/color_wheel_med.png
   :align: center


.. note::

   This color wheel is slightly different from the one used in
   [GARON2015]_, where :math:`φ=π` is cyan, rather than green.
   Opposing colors are used for phase factors with opposite signs: Red
   and green correspond to phase factors of :math:`1` and :math:`-1`,
   whereas yellow and blue correspond to the phase factors :math:`i`
   and :math:`-i`, respectively.

.. note::

   We are aware of the relatively high prevalence of red-green color
   blindness and have already experimented with some alternative color
   wheels, but alas our team lacks the wetware necessary to evaluate
   them. Please contact us at help@spindrops.org if you are interested
   in helping us evaluate alternatives.


Color Code for Vectors
----------------------

.. _figure_color_code_ccv:

.. drops:: I1p
   :width: 40%
   :align: right
   :prefs: Magnetization Droplets=false;
   :view: A

Linear Cartesian spin operators, such as :pton:`I1x`, :pton:`I1y` or
:pton:`I1z` are Hermitian and can always be represented as
three-dimensional real vectors.  If linear Cartesian spin operators
are multiplied by :math:`i`, the resulting operators :pton:`i I1x`,
:pton:`i I1y` or :pton:`i I1z` are skew-Hermitian, which can be
represented by three-dimensional imaginary vectors.

`Real` vectors are represented by `red` arrows and imaginary vectors
are represented by `yellow` arrows.  This is illustrated in
:numref:`figure_color_code_ccv` for the example of the raising
operator :pton:`I1p = I1x + i I1y`: the term :pton:`I1x` is
represented by a real vector pointing along the x axis (red arrow),
and the term :pton:`i I1y` is represented by an imaginary vector
pointing along the y axis (yellow arrow).  Next to the arrows, the
axes indicator is also drawn, the X and Y axis indicators are drawn
using their color as relative to their positional orientation around
the Z axis.  The axis coloring is different from the coloring of the
Bloch vectors.  The color of the Bloch vectors indicates the phase of
the underlying function, which in full generality can only be a linear
combination of a real and imaginary vector, whereas the colors of the
Axes indicator correspond to their 3D phase orientation in the x-y
plane.

Color Code for Pulses
---------------------

The same :ref:`color code <Color Wheel>` is used to represent the
phase of pulses in the graphical representation of a pulse sequence:

.. todo:: pulse examples

=========== ===== ============== =============== =============
        Pulse Phase              Pulse Color     Pulse Example
-------------------------------- --------------- -------------
[Cartesian] [deg] [rad]
----------- ----- -------------- -----------------------------
x           0°    0              Red             
y           90°   π/2            Yellow          
-x          180°  π              Green           
-y          270°  3π/2           Blue            
=========== ===== ============== =============== =============

Rotations around the z-axis and periods of isotropic mixing are
indicated by gray rectangles:

.. drops:: I1p
   :sequence: Standard/IM12
   :nspin: 2
   :time: 0.2
   :caption: Isotropic Mixing Sequence

.. comment: :prefs: Show Details=true