Ubuntu Manpage: cassbeam - Cassbeam is a Cassegrain antenna ray tracer

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