miriad 4.1.0.0

data/lib/miriad.rb

@@ -0,0 +1,564 @@
+# The MIRIAD-Ruby package...
+#
+# 1. makes MIRIAD datasets accessible from Ruby by wrapping the MIRIAD UVIO
+#    routines.
+#
+# 2. makes Ruby usable with MIRIAD datasets by adding convenience, utility, and
+#    astronomy related methods to Ruby classes.
+#
+#--
+#$Id: miriad.rb 901 2008-04-17 22:44:07Z davidm $
+#++
+
+require 'rbconfig'
+require 'rubygems'
+require 'date'
+require 'narray'
+miriad_shared_lib = 'miriad.' + Config::CONFIG['DLEXT']
+require miriad_shared_lib
+require 'miriad_ruby_shared_library' if false # Fake out RDoc
+#require 'fftw3'
+
+# Add CKMS constant to Math module
+Math::const_set :CKMS, 299792.458 unless Math::const_defined? :CKMS
+
+# The MIRIAD package adds angle conversion methods to the Math module
+module Math
+  # Convert possibly non-integer degrees +fr+ to [degrees, minutes, seconds]
+  # where degrees and minutes are integers.
+  def self.d_to_dms(fr)
+    sign = fr <=> 0
+    fr *= sign
+    d = fr.to_i; fr %= 1; fr *= 60
+    m = fr.to_i; fr %= 1; fr *= 60
+    return d*sign, m, fr
+  end
+
+  # Convert possibly non-integer hours +fr+ to [hours, minutes, seconds]
+  # where hours and minutes are integers.
+  def self.h_to_hms(fr); d_to_dms(fr); end
+
+  # Convert degrees, minutes, seconds to possibly non-integer degrees.
+  # Missing arguments are assumed to be 0.
+  def self.dms_to_d(*args)
+    d = 0.to_r
+    d += args.shift unless args.empty?
+    sign = d <=> 0
+    d += args.shift * Rational(sign,60) unless args.empty?
+    d += args.shift * Rational(sign,3600) unless args.empty?
+    return d
+  end
+
+  # Convert hours, minutes, seconds to possibly non-integer hours.
+  # Missing arguments are assumed to be 0.
+  def self.hms_to_h(*args); dms_to_d(*args); end
+
+  # Convert degrees to radians
+  def self.d2r(d) d*PI/180; end
+  # Convert radians to degrees
+  def self.r2d(r) r*180/PI; end
+  # Convert hours to radians
+  def self.h2r(h) h*PI/12; end
+  # Convert radians to hours
+  def self.r2h(r) r*12/PI; end
+  # Convert degrees to hours
+  def self.d2h(d) d/15.0; end
+  # Convert hours to degrees
+  def self.h2d(h) h*15.0; end
+end
+
+# Th MIRIAD package adds angle conversion and angle formatting methods to
+# Numeric class.
+class Numeric
+  # Convert +self+ to [degrees, minutes, seconds] where degrees and minutes are
+  # integers.
+  def to_dms() Math.d_to_dms(self); end
+  # Convert +self+ to [hours, minutes, seconds] where hours and minutes are
+  # integers.
+  alias :to_hms :to_dms
+  # Convert +self+ to "##d##m##.###s" format with +prec+ fractional places.
+  def to_dmsstr(prec=3)
+    width = prec == 0 ? 2 : prec+3
+    "%02dd%02dm%0#{width}.#{prec}fs" % to_dms
+  end
+  # Convert +self+ to "##:##:##.###" format with +prec+ fractional places.
+  def to_hmsstr(prec=3)
+    width = prec == 0 ? 2 : prec+3
+    "%02d:%02d:%0#{width}.#{prec}f" % to_dms
+  end
+  # Convert +self+ from degrees to radians (i.e. <tt>Math.d2r(self)</tt>).
+  def d2r() Math.d2r(self); end
+  # Convert +self+ from radians to degrees (i.e. <tt>Math.r2d(self)</tt>).
+  def r2d() Math.r2d(self); end
+  # Convert +self+ from hours to radians (i.e. <tt>Math.h2r(self)</tt>).
+  def h2r() Math.h2r(self); end
+  # Convert +self+ from radians to hours (i.e. <tt>Math.r2h(self)</tt>).
+  def r2h() Math.r2h(self); end
+  # Convert +self+ from degrees to hours (i.e. <tt>Math.d2h(self)</tt>).
+  def d2h() Math.d2h(self); end
+  # Convert +self+ from hours to degrees (i.e. <tt>Math.h2d(self)</tt>).
+  def h2d() Math.h2d(self); end
+end
+
+# The MIRIAD package adds angle conversion methods to Array class.
+class Array
+  # Convert +self+ from [degrees, minutes, seconds] to degrees.
+  # Missing arguments are assumed to be 0.
+  def dms_to_d; Math::dms_to_d(*self); end
+  # Convert +self+ from [hours, minutes, seconds] to hours.
+  # Missing arguments are assumed to be 0.
+  alias :hms_to_h :dms_to_d
+end
+
+# The MIRIAD package adds angle parsing methods to String class.
+class String
+  # Parse a "dd:mm:ss.sss" String to Float degrees.
+  # <b>NOT</b> the inverse of Numeric#to_dmsstr (but may become so).
+  def dms_to_d; Math::dms_to_d(*split(':').map{|s| s.to_f}); end
+  # Parse a "hh:mm:ss.sss" String to Float hours.
+  alias :hms_to_h :dms_to_d
+end
+
+# The MIRIAD package adds astronomy-related and other utilty methods to
+# the +DateTime+ class.
+class DateTime
+
+  # The J2000 epoch
+  J2000 = civil(2000,1,1,12)
+
+  # Create a +DateTime+ object from a numeric Astronomical Julian Date.
+  def self.ajd(d)
+    J2000 + d - J2000.ajd
+  end
+
+  # Besselian year at the time represented by +self+.
+  #
+  # Adapted from http://hpiers.obspm.fr/eop-pc/models/constants.html
+  def by
+    2000+(amjd-51544.5)/365.242189813
+  end
+
+  def ut2_ut1
+    # Taken from
+    # http://www.iers.org/products/6/11136/orig/bulletina-xx-042.txt
+    pi2t=Math::PI*2*(by%1)
+    ENV['UT2_UT1'] || 0.022 * Math::sin(pi2t) \
+    - 0.012 * Math::cos(pi2t) \
+    - 0.006 * Math::sin(2*pi2t) \
+    + 0.007 * Math::cos(2*pi2t)
+  end
+
+  # UT1-UTC (unit is seconds) at the time represented by +self+
+  #
+  # This is an increasingly out-of-date approximation only.  Taken from
+  # http://www.iers.org/products/6/11136/orig/bulletina-xx-042.txt
+  def ut1_utc
+    # TODO Get more accurate measurement of this value from usno
+    ENV.has_key?('UT1_UTC') ?
+      ENV['UT1_UTC'].to_f : -0.2221 - 0.00092 * (amjd - 54399) - ut2_ut1
+  end
+
+  # A +DateTime+ object corresponding to the same time as +self+, but
+  # with an offset of 0.  Returns +self+ if <tt>self.offset == 0</tt>.
+  def to_utc
+    (offset == 0) ? self : new_offset(0)
+  end
+
+  # Create a +DateTime+ object from a numeric Astronomical Julian Date.
+  def self.utc
+    now.to_utc
+  end
+
+  # UT1 (expressed in hours) at the time represented by +self+
+  def ut1
+    ((amjd % 1) * 24 + ut1_utc/(60*60)) % 24
+  end
+
+  # UT1 (expressed in hours) at the current time.
+  def self.ut1
+    now.ut1
+  end
+
+  # Greenwich Mean Sidereal Time at the time represented by +self+.
+  #
+  # Adapted from http://aa.usno.navy.mil/faq/docs/GAST.php
+  def gmst
+    # The local variables here have been slightly renamed from the reference to
+    # be more ruby-esque.  Here is the mapping...
+    # 
+    # Local  Reference
+    # jdut1  JD
+    # jd0    JD0
+    # h      H
+    # d      D
+    # d0     D0
+    # t      T
+
+    # The UT Julian date of the time of interest
+    jdut1 = ajd + ut1_utc/(24*60*60)
+    # Julian date of the previous midnight (0h) UT
+    jd0 = (jdut1-0.5).floor + 0.5
+    # Hours of UT elapsed since jd0
+    h = (jdut1 - jd0) * 24.0
+    # Days and fraction of day since J2000 epoch
+    d = jdut1 - J2000.ajd
+    # Integer days (and a half) since epoch
+    d0 = jd0 - J2000.ajd
+    # Fractional centuries since epoch
+    t = d/36525.0
+    # gmst
+    (6.697374558 + 0.06570982441908 * d0 + 1.00273790935 * h + 0.000026 * t**2) % 24.0
+  end
+
+  # Equation of the Equinoxes at the time represented by +self+.
+  #
+  # Adapted from http://aa.usno.navy.mil/faq/docs/GAST.php
+  def eqeq
+    # The local variables here have been slightly renamed from the reference to
+    # be more ruby-esque.  Here is the mapping...
+    # 
+    # Local  Reference
+    # jdut1  JD
+    # d      D
+    # omega  Omega (Greek letter)
+    # dpsi   Delta Psi (Greek letters)
+    # eps    epsilon (Greek letter)
+
+    # The UT Julian date of the time of interest
+    jdut1 = ajd + ut1_utc/(24*60*60)
+    # Days and fraction of day since J2000 epoch
+    d = jdut1 - J2000.ajd
+    # Longitude of the ascending node of the Moon
+    omega = 125.04 - 0.052954 * d
+    # Mean Longitude of the Sun
+    l = 280.47 + 0.98565 * d
+    # Delta psi
+    dpsi = -0.000319 * Math.sin(omega.d2r) \
+           -0.000024 * Math.sin(2*l.d2r)
+    # Obliquity
+    eps = 23.4393 - 0.0000004 * d
+    # eqeq
+    dpsi * Math.cos(eps.d2r)
+  end
+
+  # Greenwich Apparent Sidereal Time at the time represented by +self+.
+  def gast
+    (gmst + eqeq) % 24.0
+  end
+
+  # Local Mean Sidereal Time in hours at the time represented by
+  # +self+.  +longitude+ is in degrees.
+  def lmst(longitude=0.0)
+    (gmst + longitude.d2h) % 24.0
+  end
+
+  # Local Apparent Sidereal Time in hours at the time represented by
+  # +self+.  +longitude+ is in degrees.
+  def last(longitude=0.0)
+    (gast + longitude.d2h) % 24.0
+  end
+end
+
+# A subclass of StandardError raised by wrapped MIRIAD code.
+class MirlibError < StandardError
+end
+
+# In addition to the Uvio and Visibility classes, the Miriad module also
+# provides some utility methods.
+module Miriad
+
+  # The version of mirlib on which this package is based.
+  MIRLIB_VERSION = "4.1.0"
+
+  # Contains Polarization code constants.  The values follow the AIPS/FITS
+  # conventions.
+  module Pol
+    # Stokes I
+    I = 1
+    # Stokes Q
+    Q = 2
+    # Stokes U
+    U = 3
+    # Stokes V
+    V = 4
+    # Circular RR
+    RR = -1
+    # Circular LL
+    LL = -2
+    # Circular RL
+    RL = -3
+    # Circular LR
+    LR = -4
+    # Linear XX
+    XX = -5
+    # Linear YY
+    YY = -6
+    # Linear XY
+    XY = -7
+    # Linear YX
+    YX = -8
+  end
+
+  # Compute the [u,v,w] projection of a baseline with endpoints <tt>xyz1</tt>
+  # and <tt>xyz2</tt> in the direction of +obsra+, +obsdec+ (i.e. right
+  # ascension and declination in the current epoch) at the local apparent
+  # sidereal time +lst+.  <tt>xyz1</tt> and <tt>xyz2</tt> are three element
+  # arrays containing geocentric coordinates of the baseline endpoints, and
+  # +obsra+, +obsdec+, and +lst+ are all in radians
+  #
+  # The body of this method was transcribed from the MIRIAD source file
+  # <tt>uvcal.for</tt>.
+  def self.xyz2uvw(xyz1,xyz2,obsra,obsdec,lst)
+    x1,y1,z1 = xyz1
+    x2,y2,z2 = xyz2
+
+    ha = lst - obsra
+    sinha = Math.sin(ha)
+    cosha = Math.cos(ha)
+    sind = Math.sin(obsdec)
+    cosd = Math.cos(obsdec)
+
+    bxx = x2 - x1
+    byy = y2 - y1
+    bzz = z2 - z1
+
+    u =   bxx * sinha + byy * cosha
+    v = -(bxx * cosha - byy * sinha)*sind + bzz*cosd
+    w =  (bxx * cosha - byy * sinha)*cosd + bzz*sind
+
+    [u,v,w]
+  end
+
+  # Precess from one mean RA,DEC to another.
+  #
+  # A simple precession routine, to precess from one set of mean
+  # equatorial coordinates (RA,DEC), to another at a different epoch.
+  # This is accurate to order 0.3 arcsec over 50 years.
+  #
+  # Reference:
+  #   Explanatory Supplement to the Astronomical Almanac, 1993. p 105-106.
+  #
+  # NOTE: This does not take account of atmospheric refraction,
+  # nutation, aberration nor gravitational deflection.
+  #
+  # Input:
+  #   ra,dec   RA,DEC at the from_jd epoch (radians).
+  #   to_jd    Julian day of the new epoch. (defaults to current time)
+  #   from_jd  Julian day of the known epoch. (defaults to J2000)
+  #
+  # Output:
+  #   [ra+,dec] Precessed coordinates (radians).
+  #
+  # The body of this method was transcribed from the miriad source file
+  # <tt>ephem.for</tt> originally created by Bob Sault.
+  def self.precess(ra, dec, to_jd=DateTime.now.ajd, from_jd=DateTime::J2000.ajd)
+    t = (from_jd - 2451545)/36525
+    m = Math::PI/180 * (1.2812323 + (0.0003879 + 0.0000101*t)*t)*t
+    n = Math::PI/180 * (0.5567530 - (0.0001185 + 0.0000116*t)*t)*t
+    rm = ra - 0.5*(m + n*Math.sin(ra)*Math.tan(dec))
+    dm = dec - 0.5*n*Math.cos(rm)
+    #
+    #  J2000 coordinates.
+    #
+    r0 = ra - m - n*Math.sin(rm)*Math.tan(dm)
+    d0 = dec - n*Math.cos(rm)
+    #
+    #  Coordinates of the other epoch.
+    #
+    t = (to_jd - 2451545)/36525
+    m = Math::PI/180 * (1.2812323 + (0.0003879 + 0.0000101*t)*t)*t
+    n = Math::PI/180 * (0.5567530 - (0.0001185 + 0.0000116*t)*t)*t
+    rm = r0 + 0.5*(m + n*Math.sin(r0)*Math.tan(d0))
+    dm = d0 - 0.5*n*Math.cos(rm)
+
+    ra = r0 + m + n*Math.sin(rm)*Math.tan(dm)
+    dec = d0 + n*Math.cos(rm)
+
+    [ra, dec]
+  end
+
+  # Format a MIRIAD baseline number as "A1-A2".
+  def self.basstr(baseline)
+    baseline = baseline.to_i
+    "%d-%d" % basant(baseline)
+  end
+
+  # Convert a MIRIAD baseline number into two antenna numbers.
+  def self.basant(baseline)
+    baseline = baseline.to_i
+    [baseline/256, baseline%256]
+  end
+
+  # Convert two antenna numbers into a MIRIAD baseline number
+  def self.antbas(a1,a2)
+    a1, a2 = a2, a1 if a2 < a1
+    a1.to_i*256 + a2.to_i
+  end
+
+  # Convert two antenna numbers, <tt>a1</tt> and <tt>a2</tt>, into a baseline
+  # index (NOT a MIRIAD baseline number) using +n+ as the maximum antenna
+  # number.
+  def self.basidx(a1,a2,n)
+    a1, a2 = a2, a1 if a2 < a1
+    return a1 + ((2*n+1)*(a2-a1) - (a2-a1)**2) / 2
+  end
+
+  # Convert a baseline index (NOT a MIRIAD baseline number) +i+ into two
+  # antenna numbers using +n+ as the maximum antenna number.
+  def self.idxbas(i,n)
+    b = -(2*n+1)
+    ac = 2*i
+    r = Math.sqrt(b**2-4*ac)
+    d = (-b-r.floor)/2
+    d -= 1 while (a1 = i + (b*d + d**2)/2) < 0
+    a2 = a1 + d
+    [a1, a2]
+  end
+
+  # The Visibility class holds preamble, visdata, and flags for one integration
+  # on one baseline.  It also provides convenience methods to query and access
+  # these attributes and their sub-attributes.
+  class Visibility
+    # The MIRIAD preamble
+    attr_accessor :preamble
+    # The MIRIAD visdata
+    attr_accessor :data
+    # The MIRIAD flags
+    attr_accessor :flags
+    # Constructs a new Visibility object containing the given +preamble+,
+    # +data+, and +flags+ objects.  Not used often.  Usually Visibility objects
+    # are obtained from Uvio#read.
+    def initialize(preamble, data, flags)
+      @preamble = preamble
+      @data = data
+      @flags = flags
+    end
+    # call-seq: Visibility[preamble, data, flags]
+    #
+    # Alternate way to contruct a Visibility object.
+    def self.[](preamble, data, flags)
+      self.new(preamble, data, flags)
+    end
+    # Returns the [u,v,w] coordinates from the preamble.
+    def coord() preamble[0..2]; end
+    # Returns the Julian date from the preamble.
+    def jd() preamble[3]; end
+    # Returns the baseline number from the preamble.
+    def baseline() preamble[4].to_i; end
+    # Returns a DateTime object corresponding to the Julian date from the
+    # preamble.
+    def time() DateTime.ajd(jd); end
+    # Returns the two antenna numbers corresponding to the baseline number
+    # from the preamble.
+    def ants() Miriad.basant(baseline); end
+    # True if the baseline is an autocorrelation.
+    def auto?() a1,a2=Miriad.basant(baseline); a1 == a2; end
+    # True if the baseline is a cross correlation.
+    def cross?() a1,a2=Miriad.basant(baseline); a1 != a2; end
+    ## TODO Make this more robust (i.e. less hard-coded)
+    #def lags()
+    #  i = NArray.int(1024).indgen!(512) % 1024
+    #  d = data[i]
+    #  d[0] = 0 # Zero-out the DC channel
+    #  d -= d.mean # Remove the mean
+    #  FFTW3.dft(d,1)/1024
+    #end
+  end
+
+  # The Uvio class is mostly a SWIG wrapper around the UVIO C routines from
+  # MIRIAD.  Some convenience methods are added in
+  # miriad.rb[link:files/miriad_rb.html].
+  class Uvio
+    # Calls <tt>putvr(var, data, ?a)</tt>
+    def putvra(var,data) putvr(var, data, ?a); end
+    # Calls <tt>putvr(var, data, ?i)</tt>
+    def putvri(var,data) putvr(var, data, ?i); end
+    # Calls <tt>putvr(var, data, ?r)</tt>
+    def putvrr(var,data) putvr(var, data, ?r); end
+    # Calls <tt>putvr(var, data, ?d)</tt>
+    def putvrd(var,data) putvr(var, data, ?d); end
+
+    # Convenience wrapper around self.new.  Self.new may become private, so use
+    # this method instead.
+    def self.open(name,mode='r')
+      raise 'invalid dataset name' if name.nil? or name.empty?
+      case mode[0]
+      when ?r then
+        raise 'invalid dataset given' unless test ?d, name
+      when ?w then
+        raise 'dataset exists' if test ?d, name
+      when ?a then
+        raise 'invalid dataset given' unless test ?d, name
+      end
+
+      self.new(name,mode)
+    end
+
+    # call-seq:
+    #   read() -> uvread(5, nchan, nchan) -> Visibility
+    #   read(nil) -> uvread(5, nchan, nchan) -> Visibility
+    #   read(vis) -> uvread(vis.preamble, vis.data, vis.flags) -> Visibility
+    #   read(*args) -> uvread(*args) -> Visibility
+    #
+    # Convenience wrapper around uvread.  Shortens data and flags if they were
+    # passed in longer than necessary.  Always returns a Visibility, except at
+    # end of file in which case it returns +nil+.
+    #
+    # See uvread for details.
+    #
+    # <b>This method should be preferred over uvread.  uvread may disappear in
+    # future versions!</b>
+    def read(*args)
+      if args.length == 0 || args[0].nil?
+        n, p, d, f = uvread(5,nchan,nchan)
+      elsif args.length == 1 && Visibility === args[0]
+        n, p, d, f = uvread(args[0].preamble,args[0].data,args[0].flags)
+      else
+        n, p, d, f = uvread(*args)
+      end
+
+      # Return nil on EOF
+      return nil if n == 0
+
+      # FIXME for Array inputs
+      # If nread is different than what was passed in
+      if n != d.length
+        # Shorten data and flags
+        d = d[0...n]
+        f = f[0...n]
+      end
+
+      # Return Visibility
+      return args[0] if Visibility === args[0]
+      Visibility[p,d,f]
+    end
+
+    # call-seq: baseline -> [ant1, ant2]
+    #
+    # Decodes the value of the +baseline+ uv variable and returns a two element
+    # array containing the two antenna numbers.
+    def baseline
+      bl = getvr('baseline')
+      bl = [bl.to_i/256, bl.to_i%256] if bl
+    end
+
+    # Uvio.foo, if foo is not a predefined attribute or method, will return the
+    # current value of the MIRIAD UV variable +foo+ or +nil+ if it doesn't
+    # (yet) exist.
+    #
+    # Uvio.foo=bar, if foo= is not a predefined attribute or method, will set
+    # the value of the MIRIAD UV variable +foo+ to +bar+.  Only valid for
+    # datasets opened in write mode.  [SETTER FUNCTIONALITY NOT YET
+    # IMPLEMENTED!]
+    def method_missing(sym,*args)
+      val = nil
+      var = sym.to_s
+      case var
+      when /=$/: break
+      else val = getvr(var)
+      end
+      val
+    end
+  end
+
+end