Summary | Source files | Compilation | Precompiled | Gallery | References
Poincare
A program for the visualization of trajectories of Stokes parameters on the Poincaré sphere. The program generates MetaPost code as output.
Summary of the program
The Poincare computer program creates topographic maps of Stokes parameters [1], visualized as trajectories on the Poincare sphere [2]. The Poincare program generates MetaPost source code as output, to be compiled into PostScript or Encapsulated PostScript [3], using John Hobby's MetaPost compiler or anything that understands the MetaPost syntax. I have used the Poincare program extensively in my research career, and the program has been continuously updated for almost nine years by now, in fact the oldest program I keep active in my stock. This program was used in the generation of the image that made it to the front page of issue 4 of J. Opt. A: Pure Appl. Opt., Vol. 2 (July 2000).
Current revision
Revision 1.23, as of 24/01/2014. Copyright © Fredrik Jonsson 1997-2014, under GPL.
Source files
poincare.c
[140 kB]
ANSI-C (ISO C90) conforming source code for the Poincare program. Compile
by 'make' and run 'poincare --help' to get a listing of the available
switches and options in the terminal window.
[ download |
view source ]
Makefile
[10 kB]
The Makefile for compilation of the executable file, and for generation
of the examples, simply by executing 'make examples'.
To compile the executable and documentation, simply run 'make' in the
directory containing the source files and this Makefile.
View the contents of the Makefile to get an idea of how typical applications
of the Poincare program are implemented.
[ download |
view source ]
poincare.tar.gz
[33 kB]
Gzip:ed
tape archive of
the entire Poincare program directory, including the ANSI C source code and
Makefile needed to rebuild the program and example images from scratch.
[ download ]
Compilation
Compile the source code 'poincare.c' using the enclosed Makefile, or simply by executing
gcc -O2 -g -Wall -pedantic -ansi ./poincare.c -o ./poincare -lm
Precompiled executables
poincare [78 kB] Executable program compiled for Mac OS X 10.7 (Lion) using the GNU C Compiler (GCC). [Compiled Thursday 23 Jan, 2014]
Example gallery
Application example 1

Figure 1.
This is an example of a Poincare map of a spiraling helicoidal trajectory of
Stokes parameters (artificially generated by an AWK script).
The hidden parts of the trajectory is drawn as solid gray, and labels for
the components of the Stokes vector
(s1(t),s2(t),s3(t)) are displayed at the corresponding axes.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(689 kB) ]
Extract of Makefile for the generation of Fig. 1:
# # example-a: # # This is simply an example of a Poincare map of a spiraling # helicoidal trajectory of Stokes parameters. The hidden parts # of the trajectory is drawn as solid gray, and labels for the # components of the Stokes vector (s_1(t),s_2(t),s_3(t)) are # displayed at the corresponding axes. # example-a: make poincare @echo 1|$(AWK) 'BEGIN {n=440; pi=3.1415926535;}{\ printf("p\n");\ for (k=0;k<=n;k++) {\ t=k/n; phi=t*16*pi; theta=t*pi;\ x=cos(phi)*sin(theta); \ y=sin(phi)*sin(theta); \ z=cos(theta);\ printf("%-6.4f %-6.4f %-6.4f\n",x,y,z);\ }\ printf("q\n");\ }END{}' > example-a.dat @./poincare --verbose --normalize \ --inputfile example-a.dat --outputfile example-a.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" rt \ --rotatephi 15.3 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 @$(METAPOST) example-a.mp @$(TEX) -jobname=example-a '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-a.1}}\bye' @$(DVIPS) $(DVIPSOPTS) example-a -o example-a.eps
Application example 2

Figure 2.
This example is similar to the one in the previous figure, but now with
labels added at the beginning and end points of the trajectory (LCP and
RCP, indicating the poles of left and right circular polarization states,
respctivelty). These labels are added with the '--axislabels' option in
the listed block of the Makefile.
In addition, the appearance of hidden parts of the trajectory has been
changed to dashed black, using the '--draw_hidden_dashed' option.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(693 kB) ]
Extract of Makefile for the generation of Fig. 2:
# example-b: # # This example figure is similar to example-a, but with labels # added to the beginning and end points of the trajectory (LCP # and RCP, respectively). In addition, the appearance of hidden # parts of the trajectory has been changed to dashed black. # example-b: make poincare @echo 1|$(AWK) 'BEGIN {n=440; pi=3.1415926535;}{\ printf("p b urgt \"LCP\"\n");\ for (k=0;k<=n;k++) {\ t=k/n; phi=t*16*pi; theta=t*pi;\ x=cos(phi)*sin(theta); \ y=sin(phi)*sin(theta); \ z=cos(theta);\ printf("%-6.4f %-6.4f %-6.4f\n",x,y,z);\ }\ printf("q e lrgt \"RCP\"\n");\ }END{}' > example-b.dat @./poincare --verbose --normalize --draw_hidden_dashed \ --inputfile example-b.dat --outputfile example-b.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" rt \ --rotatephi 15.0 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 @$(METAPOST) example-b.mp @$(TEX) -jobname=example-b '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-b.1}}\bye' @$(DVIPS) $(DVIPSOPTS) example-b -o example-b.eps
Application example 3
In this example, several trajectories are mapped onto the same sphere. This is something useful for illustrating, for example, wave propagation in isotropic media, in which case the form of the Stokes trajectory is invariant under rotation around the s3-axis of the coordinate system (s1,s2,s3).
Extract of Makefile for the generation of the data files for Figs. 3:
example-c: make example-c-data-solid make example-c-data-chopped make example-c-solid make example-c-chopped make example-c-chopped-reversed make example-c-chopped-dash example-c-data-solid: make poincare echo 1|$(AWK) 'BEGIN {jj=10; kk=90; pi=3.1415926535; \ ta=0.1; tb=0.9;}{\ for (j=1;j<=jj;j++) {\ phia=(j/jj)*2*pi;\ printf("p\n");\ for (k=1;k<=kk;k++) {\ t=ta+(k/kk)*(tb-ta); \ phi=phia+t*1.2*pi; \ theta=t*pi;\ x=cos(phi)*sin(theta); \ y=sin(phi)*sin(theta); \ z=-cos(theta);\ printf("%-6.4f %-6.4f %-6.4f\n",x,y,z);\ }\ printf("q\n");\ }\ }END{}' > example-cs.dat example-c-data-chopped: make poincare @echo 1|$(AWK) 'BEGIN {jj=10; kk=90; mm=4; pi=3.1415926535; \ ta=0.1; tb=0.9;}{\ for (j=1;j<=jj;j++) {\ phia=(j/jj)*2*pi;\ dkk=kk/mm;\ for (m=1;m<=mm;m++) {\ printf("p\n");\ for (k=1+(m-1)*dkk;k<=1+m*dkk;k++) {\ t=ta+(k/kk)*(tb-ta); \ phi=phia+t*1.2*pi; \ theta=t*pi;\ x=cos(phi)*sin(theta); \ y=sin(phi)*sin(theta); \ z=-cos(theta);\ printf("%-6.4f %-6.4f %-6.4f\n",x,y,z);\ }\ printf("q\n");\ }\ }\ }END{}' > example-cc.dat

Figure 3(a). Multiple paths of trajectories mapped on the same sphere.
In the basic configuration, each path will be draw by a single arrow
indicating the directionality in traversing each path of the Stokes vector.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(738 kB) ]
Extract of Makefile for the generation of Fig. 3(a):
example-c-solid: @./poincare --verbose --normalize --bezier \ --inputfile example-cs.dat --outputfile example-cs.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" urt \ --rotatephi 15.0 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 \ --arrowheadangle 20.0 --draw_paths_as_arrows $(METAPOST) example-cs.mp $(TEX) -jobname=example-cs '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-cs.1}}\bye' $(DVIPS) $(DVIPSOPTS) example-cs -o example-cs.eps

Figure 3(b). Same map as in previous figure, but now with the path
arrows chopped up into several segments.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(755 kB) ]
Extract of Makefile for the generation of Fig. 3(b):
example-c-chopped: @./poincare --verbose --normalize --bezier \ --inputfile example-cc.dat --outputfile example-cc.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" rt \ --rotatephi 15.0 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 \ --arrowheadangle 20.0 --draw_paths_as_arrows $(METAPOST) example-cc.mp $(TEX) -jobname=example-cc '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-cc.1}}\bye' $(DVIPS) $(DVIPSOPTS) example-cc -o example-cc.eps

Figure 3(c). Same as previous figure, but now with the arrows reversed,
using the '--reverse_arrow_paths' option.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(773 kB) ]
Extract of Makefile for the generation of Fig. 3(c):
example-c-chopped-reversed: @./poincare --verbose --normalize --bezier \ --inputfile example-cc.dat --outputfile example-ccr.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" rt \ --rotatephi 15.0 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 \ --arrowheadangle 20.0 --draw_paths_as_arrows \ --reverse_arrow_paths $(METAPOST) example-ccr.mp $(TEX) -jobname=example-ccr '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-ccr.1}}\bye' $(DVIPS) $(DVIPSOPTS) example-ccr -o example-ccr.eps

Figure 3(d).The effect of using the '--draw_hidden_dashed' option.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(756 kB) ]
Extract of Makefile for the generation of Fig. 3(d):
example-c-chopped-dash: @./poincare --verbose --normalize --bezier --draw_hidden_dashed \ --inputfile example-cc.dat --outputfile example-cd.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" rt \ --rotatephi 15.0 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 \ --arrowheadangle 20.0 --draw_paths_as_arrows $(METAPOST) example-cd.mp $(TEX) -jobname=example-cd '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-cd.1}}\bye' $(DVIPS) $(DVIPSOPTS) example-cd -o example-cd.eps
Application example 4

Figure 4.
This example illustrates a set of closed trajectories, each
being constructed out of concatenated pieces so as to create
a plurality of arrow heads in each cycle. This example also
illustrates how additional indicatory arrows may be included
in the map by using the '--arrow' option repeatedly.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(713 kB) ]
Extract of Makefile for the generation of Fig. 4:
# # example-d: # # This example illustrates a set of closed trajectories, each # being constructed out of concatenated pieces so as to create # a plurality of arrow heads in each cycle. This example also # illustrates how additional indicatory arrows may be included # in the map by using the '--arrow' option repeatedly. # example-d: make example-d-data make example-d-solid example-d-data: make poincare echo 1|$(AWK) 'BEGIN {jj=5; kk=90; pi=3.1415926535; \ ta=0.0; tb=1.0;}{\ for (j=1;j<jj;j++) {\ phia=(j/jj)*pi;\ printf("p b urgt \"$$\(\\vartheta=%1.1f\)$$\"\n",phia);\ for (k=0;k<=kk;k++) {\ t=ta+(k/kk)*(tb-ta);\ phi=t*2*pi+pi/2; \ theta=(j/jj)*pi+(pi/17)*sin(phia)*cos(5*phi);\ x=cos(phi)*sin(theta); \ y=sin(phi)*sin(theta); \ z=-cos(theta);\ printf("%-6.4f %-6.4f %-6.4f\n",x,y,z);\ }\ printf("q\n");\ }\ }END{}' > example-d.dat example-d-solid: @./poincare --verbose --normalize --bezier \ --inputfile example-d.dat --outputfile example-d.mp \ --axislengths 0.3 1.7 0.3 2.4 0.3 1.5 \ --axislabels "s_1(t)" bot "s_2(t)" bot "s_3(t)" rt \ --rotatephi 15.0 --rotatepsi -60.0 --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 20.0 \ --paththickness 0.8 --arrowthickness 0.4 \ --arrowheadangle 30.0 --draw_paths_as_arrows \ --arrow 1.0 0.7 -0.58 1.0 0.7 0.15 0 0.9 \ --arrow 0.28 0.9 0.52 0.3 0.9 1.5 0 0.9 $(METAPOST) example-d.mp $(TEX) -jobname=example-d '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{example-d.1}}\bye' $(DVIPS) $(DVIPSOPTS) example-d -o example-d.eps
Application example 5

Figure 5. The following example of an application of the poincare program is taken from my PhD thesis, and illustrates how to append MetaPost code to the generated Poincare map, in this case an illustration of the interpretation of various parts of the Poincare sphere in terms of the polarization states, illustrated as the paths the point of the electrical field vector describes as one looks into the oncoming wave.
In this particular example, the MetaPost code in the file 'polstate.mp'
contains all illustrations of the polarization state interpretation, and
is appended via the 'input polstate.mp;' statement in the end of the
generated file 'stoke.mp' (by using the '--auxsource' option when invoking
the poincare program from the command line), which serves as a master
source file when compiling the figure.
[ Download MetaPost code |
view source |
Encapsulated PostScript image
(694 kB) ]
Extract of Makefile for the generation of Fig. 5:
example-stoke: make poincare @./poincare --verbose --normalize \ --axislengths 0.3 1.6 0.3 2.7 0.3 1.5 \ --axislabels "S_1" bot "S_2" bot "S_3" rt \ --rotatephi 15.0 --rotatepsi -70.0 \ --shading 0.75 0.99 \ --rhodivisor 50 --phidivisor 80 --scalefactor 25.0 \ --outputfile stoke.mp --auxsource polstate.mp $(METAPOST) stoke.mp $(TEX) -jobname=stoke '\input epsf\nopagenumbers\ \centerline{\epsfxsize=155mm\epsfbox{stoke.1}}\bye' $(DVIPS) $(DVIPSOPTS) stoke -o stoke.eps
References
[1] J. D. Jackson, Classical Electrodynamics, 2nd Edn. (Wiley, New York, 1975).
[2] The Poincaré sphere is classically denoted so after the French mathematician Henri Poincaré who in 1892 introduced it in his Théorie Mathématique de la Lumière, Vol. 2, Chapter 12, Pages 275-306 (Gauthiers-Villars, Paris, 1892).
[3] For information on the PostScript programming language, see for example the PostScript area on the website of Adobe Systems Inc., at http://www.adobe.com/products/postscript/ or the reference book "PostScript Language - Tutorial and Cookbook" (Adison-Wesley, Reading, Massachusetts, 1985), ISBN 0-201-10179-3.