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.
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.