The package VQM`ArgColorPlot

Bernd Thaller
Institute of Mathematics
University of Graz
Austria
04-10-2004

Abstract

The package VQM`ArgColorPlot provides methods to visualize complex-valued functions of one real variable. This package is part of the VQM packages which can be obtained here:  http://www.uni-graz.at/imawww/vqm/software.html (free download). The VQM packages are part of the Visual Quantum Mechanics project, see http://www.uni-graz.at/imawww/vqm/. In particular, these packages are distributed with the book Advanced Visual Quantum Mechanics, Springer-Verlag New York, 2004.

Introduction and implementation

Here we describe theoretical background and the practical implementation of the main function in the package VQM`ArgColorPlot`.

FilledPlot

Special packages enhance the capabilities of Mathematica. For example, the package Graphics`FilledPlot` allows to plot a function such that the space between the graph of the function and the horizontal axis is filled with a color

<<Graphics`FilledPlot`

FilledPlot[Exp[-x^2/2], {x,-3,3}, PlotRange->All]

In that way one can produce neat looking graphs. See the package documentation for details.

FilledPlot[{x^2/18, Cos[x], Sin[x]},
 {x, 0, 2 Pi},
 Fills -> {{{1, Axis}, GrayLevel[.7]},
 {{2, 3}, GrayLevel[.3]}},
 Curves -> Front]

Again, it is only possible to print real-valued functions.

Filling with an x-dependent color

In order to visualize a complex-valued function f[x] of one real variable, we use the following idea. We plot the curve Abs[f[x]] and fill the space between the curve and the horizontal axis with a color determined by Arg[f[x]]. Since the argument of a complex number is a real number modulo 2π, it appears natural to choose Hue[Arg[f[x]]/(2π)].

Unfortunately, there is no built-in Mathematica routine for performing this task. The command FilledPlot does not allow to fill the space between the curve and the x-axis with a color that depends on x. Therefore we have to define an appropriate command by ourselves.

In order to be specific, we define a sample function

f[x_] := Exp[-x^2 + 2 I x]

We proceed as follows. First, we define a set of positions on the x-axis and calculate a table of function values at these positions.

xvalues = Table[x,{x,-3.,3.,.1}];

(The semicolon serves to suppress the lengthy output). Observe that the boundary values and the increment are given as real numbers. This guarantees that all generated values are real numbers. and when we calculate the value of f for one of these x-values, then Mathematica will return a numeric expression. The function values at these points can be calculated just by applying the function f to the list xvalues:

yvalues = f[xvalues];

As long as we know what we are doing, we can ignore the warning concerning a possible spelling error. One can also turn these messages off by invoking the command Off[General::spell1].

The variable yvalues now contains a one-dimensional array of complex numbers. With the command Short we can look at an abbreviated form of this expression (The parameter in the command Short describes the desired length of the abbreviated expression). :

Short[yvalues,2]

Next we generate a table of absolute values

absvals = Abs[yvalues];

and a table of arguments

args = Arg[yvalues];

From this we want to determine a table of color values. We could try to apply Hue to the list args, but this does not work because Hue is not "listable"

Hue[args/(2 Pi)]    //Short

We have to use the command Map in order to apply Hue to each of the values in the list. Map has the shortcut /@

Hue /@ (args/(2 Pi))    //Short

We can achieve this in one step by writing

huevals = Hue[Arg[#]/(2 Pi)]& /@ yvalues;

Next, we are going to plot a graph of the function f. Let us first plot the graph of the absolute value, which is represented by the list absvals. We shall convert this into a list of points which can then be joined to form a line. The coordinates of these points can be obtained from the lists xvalues and absvals. We just apply the command Transpose in order to obtain the list of (x.y) pairs.

graphline = Line[{xvalues,absvals}//Transpose];

We can look at this by converting the graphics primitive graphline into a graphics object and by applying the command Show:

Show[Graphics[graphline]]

In fact, this line is a polygonal curve, but the corners are too close to be visible at this magnification.

The colors will be obtained by generating polygons which are filled with the appropriate color. Assume that we are given n+1 function values f[(Subscript[x, 0])], f[(Subscript[x, 1])],   ...  f[(Subscript[x, n])] .  From these n+1 values we can generate n polygons, where the k-th polygon is given by the points (Subscript[x, k]), f[(Subscript[x, k])], f[(Subscript[x, k + 1])], and (Subscript[x, k + 1])(k=0,..n-1). In a conventional programming language, one would think to generate the list of polygons with a sort of do-loop. In Mathematica it is much more effective to apply list operations. We first generate an auxiliary list of zero values

nullv = Table[0,{Length[xvalues]}];

The n-1 points ((Subscript[x, k]),0) for k=0 .. n on the x-axis are obtained by

xpoints = {xvalues, nullv}//Transpose;

Next we form the list of points with coordinates ((Subscript[x, k]),f[(Subscript[x, k])])

ypoints = {xvalues, absvals}//Transpose;

Now, this is a list of corner points for the polygons. The command Drop[list,±1] removes either the first or the last element of a list.

cornerpoints = {Drop[xpoints,-1], Drop[ypoints,-1], Drop[ypoints,1], Drop[xpoints,1]}//Transpose;

Short[cornerpoints,3]

The list of polygons is formed by mapping the command Polygon on the list of corner points.

polylist = Map[Polygon, cornerpoints];

Finally, we combine the color directives from the list hue with each polygon

coloredpolys = {Drop[huevals,-1],polylist}//Transpose;

Lets have a look at this:

Show[Graphics[coloredpolys]]

We can combine this with the line of the curve:

Show[Graphics[{coloredpolys,graphline}]]

We combine everything into a single command. This can be done using a Module.

\(\(\(fillit[xvars_, hues_, 
        values_]\  := 
\ \ \ Module[{nullv, xpts, valpts, lines, 
          fills}, 
\ \ \ \ \ \ nullv\  = \ 
          Table[0, {Length[xvars]}]; 
		xpts\  = \ {xvars, nullv} // 
            Transpose; 
\ \ \ \ \ \ valpts\  = \ {xvars, values} // 
            Transpose; 
		lines\  = \ 
          Line[valpts]; 
\ \ \ \ \ \ fills\  = 
\ \ \ \ \ \ \ \ \ {Drop[
                hues, \(-1\)], 
\ \ \ \ \ \ \ \ \ \ \ \ \ Map[
                Polygon, 
					\ \ \ \ {\ Drop[xpts, \(-1\)], \ 
                    Drop[valpts, \(-1\)], \ Drop[valpts, \ 1], 
                    Drop[xpts, \ 
                      1]
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ } // Transpose
\ \ \ \ \ \ \ \ \ \ \ \ \ ]
\ \ \ \ \ \ \ \ \ } // 
            Transpose; 
\ \ \ \ \ \ Show[
          Graphics[\ {fills, lines}\ ]]
\ \ \ ]\)\(
\)
    \)\)

Let us test this command with a small list:

fillit[{1,2,3,4,5}, Hue/@{0,.25,.5,.75,1}, {0,1,2,1,0}]

Phase-colored plot

We can easily use the command fillit to define a useful plot command for a list of complex numbers:

ListArgColorPlot[list_List] :=
   Module[{xvars,hues,values},
         xvars	= Range[Length[list]];
         hues	= Hue[Arg[#]/(2 Pi)]& /@ list;
         values	= Abs[list];
         fillit[xvars,hues,values]
         ]

f[x_] := Tan[x + 0.3 I]

yvalues = Table[f[x],{x,-5.,5.,0.1}];

ListArgColorPlot[yvalues]//Timing

The package VQM`ArgColorPlot

The (non-standard) package VQM`ArgColorPlot provides additional functionality

<<VQM`ArgColorPlot`

All symbols defined by the VQM packages start with the letter "Q". In particular, the package implements QListArgColorPlot which corresponds to the command ListArgColorPlot defined above. But the command defined in the package accepts the standard options:

yvalues = Table[Tan[x + 0.3 I],{x,-5.,5.,0.1}];

QListArgColorPlot[yvalues, Frame->True, Axes->{True,False},
PlotRange->{-.5,4}]

There is a variant which corresponds to Plot

QArgColorPlot[Tan[x + 0.3 I], {x,-5,5}, Frame->True, Axes->{True,False},
PlotRange->{-.5,4}]

Further documemtation is available via Mathematica's Help Browser, provided the VQM packages are properly installed.

Moreover, you can get help in the usual way:

?QArgColorPlot

Options[QArgColorPlot]

?QSaturation

Examples for using the ArgColorPlot package

We turn off error messages that occur whenever one of the complex values to be plotted is zero (because the argument of that number is not defined):

Off[Arg::"indet"];

This example shows a complex-valued Gaussian function.

QArgColorPlot[(E^(-I 6 x - ((x^2)/2))), {x, -4, 4}]

Most of the options for Plot can be used also for QArgColorPlot. In addition, we can influence the Saturation and the Brightness of the colors for the complex phase:

QArgColorPlot[(E^(-I 6 x - ((x^2)/2))), {x, -4, 4}, PlotStyle -> {Thickness[0.025], GrayLevel[0.5]}, 
      QSaturation -> 0.5, QBrightness -> 0.7, 
      PlotRange -> {-0.2, 1.2}, Frame -> True, 
      Axes -> {True, False}]

Next, we illustrate the usage of QListArgColorPlot. First, we create a list of complex numbers.

mytab = 
        Table[Sin[π x] (E^(2 I π x)), {x, -2, 2, 0.1}];

QListArgColorPlot[mytab]

If, like here, the complex values come from the discretization of a function of a real variable x, we want to have x-values on the horizontal axis, and not the index of the complex list. This can be done with the option QHorizontalRange which specifies the range of x-values on the horizontal axis:

QListArgColorPlot[mytab, Axes -> True, 
      QHorizontalRange -> {-2, 2}]

Here is another method to achieve a similar result:

QListArgColorPlot[mytab, Axes->True, Ticks->{QNiceTicks[-2.,2.,0.1],Automatic}]

We can also plot a part of the list, corresponding, for example, to the values in the sub-interval {-1,0} of the horizontal range {-2,2}:

QListArgColorPlot[mytab, Axes -> True, 
        QHorizontalRange -> {{-2, 2}, {-1, 0}}];

If the "sub-interval" is larger than the horizontal range, the list will be padded with zeros:

QListArgColorPlot[mytab, Axes -> True, 
        QHorizontalRange -> {{-2, 2}, {-4, 4}}];

If you want to combine a phase-colored plot with an ordinary plot of another function, you can use QCombinedPlot:

QCombinedPlot[{Exp[-x^2/2], x^2/2 - 1/2}, {x, -4, 
          4}];

There is also a "ListPlot"-version of QCombinedPlot, where a list of complex values is plotted together with an ordinary function:

mytab = Table[Exp[-x^2/2], {x, -4, 4, 0.1}];
QListCombinedPlot[{mytab, x^2/2 - 1/2}, {x, -4, 
          4}];

QListCombinedPlot[{mytab, x^2/2 - 1/2}, {x, 0, 2}];

QListCombinedPlot[{mytab, x^2/2 - 1/2}, {x, 0, 2}, 
        QHorizontalRange -> {-4, 4}];

QListCombinedPlot[{mytab, x^2/2 - 1/2}, {x, 0, 2}, 
        QHorizontalRange -> {{-4, 4}, {-1/2, 
              3/2}}];

Normally, in QArgColorPlot, the range between the x-axis and the graph of the function is filled with a color corresponding to the phase. But we can also use another horizontal line at height y=y0 by using the option QBottomLine->y0:

QArgColorPlot[Exp[I x - x^2],{x,-3,3}, QBottomLine->1/3]

This is useful, if we want to combine several ArgColorPlots in the same graphics:

Show[
      QArgColorPlot[Sin[x + I], {x, -3, 3}, 
        QBottomLine -> 1, Epilog -> Line[{{-3, 1}, {3, 1}}], 
        DisplayFunction -> Identity], 
      QArgColorPlot[
        Cos[x + I] - (E^(I Arg[Cos[x + I]])), {x, -3, 3}, DisplayFunction -> Identity], 
      PlotRange -> {-0.2, 1.7}, Frame -> True, 
      DisplayFunction -> $DisplayFunction]

Some more options for use with QArgColorPlot:

QSquared->True plots the square of the curve instead of the absolute value:

QArgColorPlot[Sin[x],{x,-2Pi,Pi}, QSquared->True]

QShiftPlot->number performs a vertical shift of the whole plot by number.

QArgColorPlot[Sin[x],{x,-2Pi,Pi}, QShiftPlot->1, PlotRange->{0,2}]

QPlotDown->True lets the whole plot appear uside down.

QArgColorPlot[Sin[x],{x,-2Pi,Pi}, QPlotDown->True]

In quantum mechanics, a (ℂ^2)-valued functions is called a spinor function. The ArgColorPlot has a method to plot such functions by combining QArgColorPlots of the two component-functions. By default, the second component is plotted upside down and with less saturation:

spinorfunction[
          x_] := {Cos[
              3 x] (E^(-(1/3) (((x - (1/4)))^2) + I x)), 
          Sin[4 x] (E^(-(1/2) (((x + (1/4)))^2) + 2 I x))};
QSpinorPlot[Evaluate[spinorfunction[x]], {x, -3. , 3. }, 
      PlotRange -> All, Frame -> True, 
      Axes -> {True, False}]

Like the other commands, this command accepts options and allows a combination with an ordinary plot

spinorlist = 
        Table[{x, spinorfunction[x]}, {x, -3, 3, 0.1}];
QListSpinorCombinedPlot[{spinorlist, Sin[4 x]}, {x, -2, 3}, 
      PlotRange -> All, 
      QCurveStyle -> {RGBColor[0, 0.7, 0.9], Thickness[0.03]}, 
      PlotStyle -> {RGBColor[0.2, 0.2, 0.5], 
          Thickness[0.02]}]