%% The phaseplot command
% Nick Trefethen, October 2020
%%
% (Chebfun example complex/PhaseplotCommand.m)
% [Tags: #Conformal]
%%
% To plot a complex phase portrait in Chebfun, it is now
% enough to execute |phaseplot| with a function handle or complex
% chebfun2. For example, here is a phase portrait of the function
% $f(z) = z$ on the default domain $[-1, 1, -1, 1]$:
phaseplot(@(z) z)
%%
% At each point $z$ in the domain, the color shows the complex argument
% of $f(z)$ at that point. For example, if $f(z)$ is positive
% the color is red and if it is negative the color is cyan.
% Notice the sequence of six colors as traces around counterclockwise:
% red, yellow, green, cyan, blue, magenta. One can think
% of this as an interleaving of the two famous color schemes
% used by printers: rgb and cmy.
%%
% Phase portraits reveal a lot about analytic and meromorphic
% functions. For example, $f(z) = (z-1)/(z+1)$ has a zero at
% $z=1$ and a pole at $z=-1$, as revealed by the colors there
% going in the opposite direction:
f = @(z) (z-1)./(z+1);
phaseplot(f, [-2 2 -2 2])
%%
% Multiple poles or zeros show more colors:
f = @(z) z.^3;
phaseplot(f)
%%
% Branch cuts show up as discontinuities:
f = @(z) sqrt(z-1).*sqrt(z+1);
phaseplot(f, [-2 2 -2 2])
%%
% Essential singularities are glorious:
f = @(z) exp(3./z);
phaseplot(f)
%%
% An earlier phase portrait capability was introduced
% in Chebfun in 2013, in which |plot(f)| gives a phase portrait
% if |f| is a chebfun2 that takes complex values. The new
% |phaseplot| command can also take a chebfun2 as argument, but
% is is much more flexible since it can deal with any function
% handle. This broadens the scope greatly since functions with
% poles and other singularities generally cannot be resolved as
% chebfun2 objects.
%%
% If you compare the images produced by |phaseplot| with
% the "classic" ones such as those magnificently discussed in [1],
% you will find a slight difference in coloring.
subplot(121), phaseplot(@(z) z)
axis off, title('default colors')
subplot(122), phaseplot(@(z) z, 'classic')
axis off, title('''classic'' colors')
%%
% The classic color scheme makes cyan, magenta, and yellow much
% narrower than red, green, and blue. This has some
% appeal, since the narrow stripes convey sharper information, but
% on the other hand it seems somewhat artificial to treat three
% arguments of the compass so differently from the other three.
% That is why |phaseplot| introduces a slight transformation
% of the color scheme. In the code it is a one-liner: search
% for "phi" if you are curious.
%%
% To see some amazing things revealed by phase portraits, check
% out [2].
%%
% [1] E. Wegert, _Visual Complex Functions: An Introduction
% with Phase Portraits_, Birkhäuser, 2012.
%
% [2] E. Wegert, |www.visual.wegert.com|.