;+
; NAME:
;    vortex
;
; PURPOSE:
;    Returns a phase hologram encoding a helical mode.
;
; CATEGORY:
;    Computer-generated holography
;
; CALLING SEQUENCE:
;    phi = vortex(ell, [dim])
;
; INPUTS:
;    ell : [integer] topological charge for the vortex
;
; KEYWORDS:
;    cal: [xc,yc,xfac] coordinates of optical axis on SLM face
;        and scale factor for x-coordinate.
;        Default: uses calibration constants set by HOLO_INIT.
;    dim: one- or two-component specification of the phase-mask's
;        dimensions.
;        Default: uses calibration constants set by HOLO_INIT.
;
; KEYWORD FLAGS:
;    nomod: If set, then return phi, rather than phi mod 2 pi.
;
; OUTPUTS:
;    phi: vortex-forming phase mask: $\phi(\rho) = \ell \theta$.
;        Result is positive and modded by 2 pi.
;
; PROCEDURE:
;    Calls MAKETHETA to calculate theta.
;
; EXAMPLE:
;    IDL> phi = vortex( 60, 512 ) ; 512 x 512 charge 60 vortex
;    IDL> phi = vortex( -60 )     ; 768 x 768 charge -60 vortex
;    IDL> phi = vortex( 11, [512,768] ) ; 512 x 768 ...
;
; MODIFICATION HISTORY:
; 02/07/2002: David G. Grier, The University of Chicago, Created.
; 02/28/2002: DGG added CENTER keyword to move center of pattern
;      on face of SLM.  Useful for correcting for misaligned optics.
; 09/23/2003: DGG moved DIM to a keyword for consistency with
;      related routines.  Retired CENTER in favor of CAL, which
;      includes rescaling of the x-axis for square projected pixels.
; 10/01/2003: DGG added NOMOD keyword.
; 04/22/2004: DGG modifed to call MAKETHETA.
; 06/10/2010: DGG Documentation fixes.  Added COMPILE_OPT
;
; Copyright 2002-2010 David G. Grier
;
; UPDATES:
;    The most recent version of this program may be obtained from
;    http://physics.nyu.edu/grierlab/software.html
; 
; LICENSE:
;    This program is free software; you can redistribute it and/or
;    modify it under the terms of the GNU General Public License as
;    published by the Free Software Foundation; either version 2 of the
;    License, or (at your option) any later version.
;
;    This program is distributed in the hope that it will be useful,
;    but WITHOUT ANY WARRANTY; without even the implied warranty of
;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;    General Public License for more details.
;
;    You should have received a copy of the GNU General Public License
;    along with this program; if not, write to the Free Software
;    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
;    02111-1307 USA
;
;    If the Internet and WWW are still functional when you are using
;    this, you should be able to access the GPL here: 
;    http://www.gnu.org/copyleft/gpl.html
;-

function vortex, ell, dim = dim, cal = cal, nomod = nomod

COMPILE_OPT IDL2

theta = maketheta(dim = dim, cal = cal)
phi = ell * theta
phi -= min(phi)

if not keyword_set(nomod) then $
  phi = temporary(phi) mod (2.*!dpi)

return, phi
end