Provided by: cassbeam_1.1-4build2_amd64 bug

NAME

       cassbeam - Cassbeam is a Cassegrain antenna ray tracer

SYNOPSIS

       cassbeam input_file [key=value ...]

DESCRIPTION

       cassbeam is a program for Cassegrain antenna modelling.  It computes several properties of
       the antenna including gain, zenith system temperature, and the beam, in full polarization.
       All  calculations  are  done  in  the  transmit sense and use reciprocity to relate to the
       equivalent receiving system.

       Cassbeam is a non-interactive command line program that takes all of its  input  from  the
       command  line.   Note  that  this  does not preclude someone at a later date from making a
       graphical or web front end.  There is one required argument when running  cassbeam  -  the
       input  filename.   Additional  arguments  can supplement the parameters of the input file.
       These arguments are passed in the same key=value as required  in  the  input  file  except
       whitespace is not allowed around the equal sign.  If a parameter appears both in the input
       file and the command line, then the value on the command line supercedes the value on  the
       input file.

INPUT FILE

       The  main  input  file consists of a series of lines of the form key=value.  Only one such
       entry is allowed per line.  The equal sign is optional.  The input files allow comments to
       be placed within the file.  All comments begin with %.  This character and any that follow
       it on a given line are ignored by cassbeam.  Depending on key, the value  may  be  one  of
       five  types:  string,  integer,  double,  vector,  none.   A  string is a sequence of non-
       whitespace characters not surrounded by quotes of any kind.  A double value  is  a  number
       that  can  have  a  fractional  part.  A vector is a comma-separated list of doubles.  The
       `none' type expects no value.  Below is a list of the allowed keys and the type  of  value
       expected.   If  the range of legal values is restricted, the legal range will be contained
       within brackets.  Note that legal values do not imply a physical system that will generate
       meaningful  results!   For the vector type, if a certain number of values are needed, they
       will be indicated in parentheses.  A required parameter will be indicated with a `*'.   It
       is  important  to  realize  that the secondary optical surface (i.e., the subreflector) is
       defined based on the input geometry.  Thus changing the feed  placement  will  change  the
       geometry of the subreflector!  To change parameters of the telescope without affecting the
       shape of the subreflector, set the pathology parameters.   Note  that  the  order  of  the
       parameters does not matter.

   Antenna geometry parameters
       feed_x The  x  value  of  the  phase  center  of  the feed.  If no value is provided, 0 is
              assumed. [double]

       feed_y The y value of the phase center of the  feed.   If  no  value  is  provided,  0  is
              assumed. [double]

       feed_z The  z  value  of  the  phase  center  of  the feed.  If no value is provided, 0 is
              assumed. [double]

       geom   This string points to a disk file containing the primary optical surface  geometry.
              This file is a three column ascii text file, each containing space separated values
              for r, z, and dz/dr for the antenna.  There is no limit (other than your computer's
              memory) to the number of lines in this file.  It is assumed (but not checked!) that
              the values of r start at 0 and are equally spaced.  The radius, R, of  the  primary
              is  given  by  the  value of r in the last row.  Columns 1 and 2 are in meters, and
              column 3 is dimensionless.  [string]

       hole_radius
              The radius (in meters) of an unpanelled area at the  center  of  the  primary.   If
              omitted, no hole will be made. [double, > 0]

       legapex
              The z value where the legs (struts) intersect each other.  Note that the legs might
              terminate before reaching this point.  The default value is 1.2*sub_h.  [double,  >
              0]

       legfoot
              The  r  value  where  the legs (struts) intersect the primary surface.  The default
              value is half the antenna radius. [double, > 0]

       legwidth
              The effective width of the legs, used to compute blockage.  Note that  currently  a
              positive  value  indicates  four equally spaced legs with one leg along the x axis.
              If the value is negative, its absolute value is used in the blockage  calculations,
              but  the legs are rotated 45°.  If this parameter is not set, or if it is set to 0,
              then no legs will be generated. [double]

       name   An optional name given to the antenna.  If the name  is  ``VLBA'',  then  the  true
              strut  geometry  for  the  VLBA  antennas  is  used  rather than equispaced struts.
              [string]

       roughness
              The RSS surface roughness in meters.  This number represents the  combined  surface
              error  for  the  primary  and  secondary.  If no roughness is provided, the default
              value of 0 is used. [double, >= 0]

       sub_h  This value is the z value of the intersection of the subreflector with the z  axis.
              [double, > 0]

   Feed pattern parameters
       Note that either both feedtaper and feedangle or feedpattern must be provided.

       feedangle
              Sets the reference angle for the feed taper. [double, > 0]

       feedpattern
              The  name  of  the file containing the pattern of the feed.  This file contains two
              space-separated columns of numbers: the angle in degrees and the taper in dB.   The
              first angle must equal 0, and the angles must be uniformly spaced. [string]

       feedpatternscale
              The factor by which to scale the pattern defined in feedpattern.  [double, > 0]

       feedtaper
              This  parameter  sets  the taper (in dB) of the feed at an angle feedangle from the
              feed axis to 10^-feedtaper/10. [double, > 0]

   Pathology parameters
       None of the following operations change the shape of the subreflector -  its  geometry  is
       calculated  before  their  application.  Note that displacements of either the feed or the
       subreflector result in a rotation of the feed that corrects for the mispointing caused  by
       the  translations.   Rotations of the feed act in addition to this correction.  Composited
       rotations (i.e., setting rsub_x and rsub_y are  both  provided),  the  operations  on  the
       object  being rotated proceed in reverse alphabetical order (z rotation before y rotation;
       y rotation before x rotation) regardless of the order that the parameters are received.

       dfeed_x
              Displacement of the feed along the x axis. [double]

       dfeed_y
              Displacement of the feed along the y axis. [double]

       dfeed_z
              Displacement of the feed along the z axis. [double]

       dsub_x Displacement of the subreflector along the x axis. [double]

       dsub_y Displacement of the subreflector along the y axis. [double]

       dsub_z Displacement of the subreflector along the z axis. [double]

       focus  Displacement of the feed along the feed axis.  A  positive  value  moves  the  feed
              closer to the subreflector. [double]

       rfeed_x
              Rotation  of  the  feed  in degrees about the x axis.  A positive value will rotate
              from the z axis through the y axis. [double]

       rfeed_y
              Rotation of the feed in degrees about the y axis.  A  positive  value  will  rotate
              from the x axis through the z axis. [double]

       rfeed_z
              Rotation  of  the  feed  in degrees about the z axis.  A positive value will rotate
              from the y axis through the x axis. [double]

       rsub_x Rotation of the subreflector in degrees about the x axis.  A  positive  value  will
              rotate from the z axis through the y axis. [double]

       rsub_y Rotation  of  the  subreflector in degrees about the y axis.  A positive value will
              rotate from the x axis through the z axis. [double]

       rsub_z Rotation of the subreflector in degrees about the z axis.  A  positive  value  will
              rotate from the y axis through the x axis. [double]

       subrotpoint
              Defines  the  point about which the rotation of the subreflector is performed.  The
              contents of the vector depend on the number of elements are provided:  either  only
              the  z  value, or the x and y values, or the x, y, and z values. [vector (1 or 2 or
              3)]

   Operating condition parameters
       compute
              A string to tell what output to produce.  The string can be  `all',  `none',  or  a
              string containing flag characters.  The default value is `all', meaning produce all
              possible output.  `none' will produce only messages on the  screen  and  no  output
              files.  The characters of the general string mean the following:

              a Save the aperture images;

              j Save the Jones matrices in a table;

              p Save the parameters;

              s Save the polarized beams.

              Note that the string is case insensitive. [string]

       diffeff
              A user supplied diffraction efficiency.  If none is provided, an internal algorithm
              that is not very good is used.  This needs to be upgraded! [double]

       freq   The frequency in GHz at which the calculation will be run. [double, > 0]

       gridsize
              Specifies a fixed grid size.  If odd, the next even  number  will  be  used.   This
              option overrides any setting of oversamp and is the preferred method of setting the
              grid size.  Setting it to a value less than 32 will result in a grid  size  of  32.
              [integer, >= 32]

       leggroundscatter
              The  fraction of power that scatters off the struts toward the ground.  The default
              value is 0.2. [double, >= 0, <= 1]

       misceff
              A factor of the efficiency calculation that contains ``everything else''.  The user
              is  responsible  for  choosing  a  realistic value for this.  A default of 1 (i.e.,
              100%) is assumed if this parameter is not provided.  [double, >= 0, <= 1]

       out    The prefix for all output files.  The default  is  cassbeam.   A  dot  will  always
              separate the prefix from any trailing characters. [string]

       oversamp
              One way of specifying the grid size.  This option will make the grid on the primary
              fine enough to accommodate 4*oversamp*R/lambda points.  The  default  is  1.   Note
              that  vastly  ``undersampling''  is  fine as the field is never calculated anywhere
              between the feed and  the  aperture  plane.   Normally  blockage  calculations  and
              constancy of the illumination will dictate the required sampling.  See gridsize for
              an alternate way of specifying the grid.  This parameter is ignored if gridsize  is
              set. [double, > 0]

       pixelsperbeam
              This  is  the approximate number of pixels that the core of the beam will occupy in
              the output images. [int, > 0]

       Tground
              The temperature in Kelvin of the ground.  The default value is 290. [double, > 0]

       Trec   The equivalent temperature of the receiver.  This adds into the system temperature.
              The default value is 50. [double, > 0]

       Tsky   The  temperature in Kelvin of the sky.  The default value is 3 for frequencies over
              1 GHz, and 3 * 10^-2.5 nu for frequencies below 1 GHz. [double, > 0]

OUTPUT FILES

       Up to 12 output files are generated depending on which compute options  were  selected  at
       run  time.   These files are listed below.  The letter in brackets in the section headings
       indicate which option is used to enable this file to be written.  All output  files  begin
       with the value of the input parameter out.  Currently all output images are in PGM format,
       which is a very simple greyscale image format supported by most unix-based image viewers.

   Aperture images [a]
       Three images are generated that allow the aperture field to be examined qualitatively.  If
       quantitative  numbers  are  needed,  the  source  code  should  be  modified to export the
       illumination parameters.

       out.illumamp.pgm
              Raster image showing the amplitude of the illumination pattern of the primary.   No
              blockage is done at this point.  The scale is linear in flux.

       out.illumphase.pgm
              Raster  image  showing the net phase (pathlength multiplied by wave vector) at each
              point on the primary.  A phase gradient is removed.  Portions  of  the  image  that
              correspond to zero flux have an arbitrary phase.

       out.illumblock.pgm
              Raster  image  showing  the blocked portion of the aperture.  White means that this
              part of the dish is  experiences  either  plane  wave  blockage  from  the  sky  or
              spherical  wave blockage from the feed, and thus does not contribute to the gain of
              the antenna.

   Jones matrix file [j]
       The Jones matrix file, out.jones.dat contains the Jones matrix (see Hamaker  et  al.  1996
       for  details)  corresponding  to  the effect of the antenna on the incoming radiation as a
       function of position on the sky.  The file is organized as an  eight  column  ascii.   The
       first row corresponds to the point on the image with smallest l and m.  The rastering then
       proceeds first with increasing l, and then with increasing m.  There are a  total  of  n^2
       rows,  where n is the smallest odd number greater than or equal to the gridsize used.  The
       matrices are rastered on a sine-projected coordinate system tangent to the sky at the beam
       center,  which corresponds to row number (n^2+1)/2.  At the beam center the pixel scale is
       given by the  output  parameter  beampixelscale,  which  is  stored  in  the  output  file
       out.params described below.

   Parameter file [p]
       The  parameter  file,  out.params  is an output file in the same format as the input file,
       containing all of the input parameters that were specified (even if on the  command  line)
       as well as many output values.  They are:

       Aeff   The effective area of the antenna [m^2]. [double]

       Aeff_Tsys
              The  effective  area  of  the  antenna  divided  by the system temperature [m^2/K].
              [double]

       ampeff The amplitude efficiency. [double]

       beampixelscale
              The scale of the generated beam images [deg/pixel]. [double]

       blockeff
              The blockage efficiency. [double]

       diffeff
              The diffraction efficiency. [double]

       fwhm_l The full width at half max of the beam in the l direction. [double]

       fwhm_m The full width at half max of the beam in the m direction. [double]

       gain   The gain G of the antenna. [double]

       illumeff
              The illumination efficiency. [double]

       peaksidelobe
              The directivity of the greatest sidelobe relative to the peak  directivity  of  the
              beam. [double]

       phaseeff
              The phase efficiency. [double]

       point_l
              The l component of the pointing offset from the z axis measured in the image plane.
              [double]

       point_m
              The m component of the pointing offset from the z axis measured in the image plane.
              [double]

       prispilleff
              The primary spillover efficiency. [double]

       program
              The name of the program run, which is cassbeam. [string]

       misceff
              The miscellaneous efficiency. [double]

       spilleff
              The spillover efficiency. [double]

       subspilleff
              The subreflector spillover efficiency. [double]

       surfeff
              The surface efficiency. [double]

       totaleff
              The total efficiency calculated for the antenna. [double]

       Tsys   The system temperature. [double]

       version
              The software version number. [string]

   Polarized beam images [s]
       With  the  s option, cassbeam will produce 7 images of the beam showing in the four Stokes
       parameters the response to an unpolarized source as a function  of  the  position  of  the
       source on the sky.  This information is derived from the Jones matrices which are saved in
       out.jones.dat. These images are meant for  qualitative  inspection.   The  Jones  matrices
       contain the formal output.

       out.I.pgm
              Stokes I - total intensity;

       out.Q.pgm
              Stokes Q - excess linear polarization e_1 over e_2;

       out.U.pgm
              Stokes U - excess linear polarization in e'_1 over e'_2

       out.V.pgm
              Stokes V - excess right circular polarzation over left circular polarization;

       out.QI.pgm
              The ratio of the Stokes Q image to the Stokes I image;

       out.UI.pgm
              The ratio of the Sytokes U image to the Stokes I image;

       out.VI.pgm
              The ratio of the Stokes V image to the Stokes I image;

AUTHOR

       Cassbeam is written by  Walter Brisken, National Radio Astronomy Observatory. This manpage
       is extracted from his cassbeam manual.

SEE ALSO

       See the complete manual in /usr/share/doc/cassbeam/ for more information.