1## Copyright (C) 2013 Martin Vogel <octave@martin-vogel.info>
2##
3## This program is free software; you can redistribute it and/or modify it
4## under the terms of the GNU General Public License as published by the
5## Free Software Foundation; either version 3 of the License, or (at your
6## option) any later version.
7##
8## This program is distributed in the hope that it will be useful, but WITHOUT
9## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10## FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
11## for more details.
12##
13## You should have received a copy of the GNU General Public License
14## along with this program; see the file COPYING.  If not, see
15## <http://www.gnu.org/licenses/>.
16
17## -*- texinfo -*-
18## @deftypefn  {Function File} {@var{JM} =} jones_linretarder()
19## @deftypefnx {Function File} {@var{JM} =} jones_linretarder(@var{p})
20## @deftypefnx {Function File} {@var{JM} =} jones_linretarder(..., @var{mode})
21## Return the Jones matrix for a linear retarder with long axis
22## rotation of 0 degrees.
23##
24## @itemize @minus
25## @item @var{p} is the phase delay in radiant units, i.e. @var{p} is
26## ranging between 0 and 2*pi(). If not given or set to [] the default
27## value 0 is used.
28## @item @var{mode} is a string defining the units for the phase
29## delay: 'radiant' (default), 'degree' (0..360) or 'wavelength'
30## (0..1).
31## @end itemize
32##
33## Argument @var{p} can be passed as a scalar or as a matrix or as a
34## cell array. In the two latter cases, a cell array @var{JM} of
35## Jones matrices of the same size is returned.
36##
37## References:
38##
39## @enumerate
40## @item E. Collett, Field Guide to Polarization,
41##       SPIE Field Guides vol. FG05, SPIE (2005). ISBN 0-8194-5868-6.
42## @item R. A. Chipman, "Polarimetry," chapter 22 in Handbook of Optics II,
43##       2nd Ed, M. Bass, editor in chief (McGraw-Hill, New York, 1995)
44## @item @url{http://en.wikipedia.org/wiki/Jones_calculus, "Jones calculus"},
45##       last retrieved on Jan 13, 2014.
46## @end enumerate
47##
48## @seealso{Jones_waveplate}
49## @end deftypefn
50
51function JM = jones_linretarder(varargin)
52
53  phase_defv = 0;
54
55  if nargin<1
56    phase = phase_defv;
57  else
58    phase = varargin{1};
59  end
60
61  [phase, was_cell] = __c2n__(phase, phase_defv);
62
63  if nargin>=2 && ischar(varargin{end})
64    if strncmpi(varargin{end},'deg',3)
65      phase = phase*pi()/180.0;
66    elseif strncmpi(varargin{end},'wav',3)
67      phase = phase*2*pi();
68    end
69  end
70
71  if (numel(phase) > 1) || was_cell
72
73    JM = cell(size(phase));
74    JM_subs = cell(1,ndims(JM));
75    for jmi=1:numel(JM)
76      [JM_subs{:}] = ind2sub(size(JM),jmi);
77      JM{JM_subs{:}} = s_linretarder(phase(JM_subs{:}));
78    end
79
80  else
81
82    JM = s_linretarder(phase);
83
84  end
85
86end
87
88% helper function
89function JM = s_linretarder(phase_in_pi_units)
90
91  JM = zeros(2,2);
92  JM(1,1) = 1;
93  JM(2,2) = exp(-1i*phase_in_pi_units);
94
95end
96
97%!test
98%! % test default return value
99%! A = jones_linretarder();
100%! R = A*A-A;
101%! assert(norm(R,inf), 0, 1e-9);
102%!
103%!test
104%! % test serial application of linear retarder elements
105%! phase = rand(1, 1);
106%! A1 = jones_linretarder(phase);
107%! A2 = jones_linretarder(phase*2);
108%! R = A1*A1-A2;
109%! assert(norm(R,inf), 0, 1e-9);
110%!
111%!test
112%! % another test of serial application of retarder elements
113%! phase1 = rand(1, 1);
114%! phase2 = rand(1, 1);
115%! A1 = jones_linretarder(phase1);
116%! A2 = jones_linretarder(phase2);
117%! A12 = jones_linretarder(phase1+phase2);
118%! R = A1*A2-A12;
119%! assert(norm(R,inf), 0, 1e-9);
120%!
121%!test
122%! % test mode
123%! phase = rand(1, 1);
124%! A1 = jones_linretarder(phase);
125%! A2 = jones_linretarder(phase*180/pi(), 'deg');
126%! A3 = jones_linretarder(phase/(2*pi()), 'wav');
127%! R1 = A1-A2;
128%! R2 = A1-A3;
129%! assert(norm(R1,inf)+norm(R2,inf), 0, 1e-9);
130%!
131%!test
132%! % test correct size of return values
133%! for dim = 1:5
134%!   asize = randi([1 4], 1, dim);
135%!   R = rand(asize);
136%!   if numel(R) == 1
137%!     R = {R};
138%!   end
139%!   rsize = size(R);
140%!   C = jones_linretarder(R);
141%!   csize = size(C);
142%!   assert(rsize == csize);
143%! end
144