Provided by: cassbeam_1.1-3_amd64

**NAME**

cassbeam - Cassbeam is a Cassegrain antenna ray tracer

**SYNOPSIS**

cassbeaminput_file[key=value...]

**DESCRIPTION**

cassbeamis 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 samekey=valueas 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 formkey=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 onkey, thevaluemay be one of five types: string, integer, double, vector, none. A string is a sequence of non- whitespace charactersnotsurrounded 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 novalue. Below is a list of the allowedkeysand the type ofvalueexpected. 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.Antennageometryparametersfeed_xThe x value of the phase center of the feed. If no value is provided, 0 is assumed. [double]feed_yThe y value of the phase center of the feed. If no value is provided, 0 is assumed. [double]feed_zThe z value of the phase center of the feed. If no value is provided, 0 is assumed. [double]geomThis 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_radiusThe radius (in meters) of an unpanelled area at the center of the primary. If omitted, no hole will be made. [double, > 0]legapexThe 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]legfootThe r value where the legs (struts) intersect the primary surface. The default value is half the antenna radius. [double, > 0]legwidthThe 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]nameAn 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]roughnessThe 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_hThis value is the z value of the intersection of the subreflector with the z axis. [double, > 0]FeedpatternparametersNote that either bothfeedtaperandfeedangleorfeedpatternmust be provided.feedangleSets the reference angle for the feed taper. [double, > 0]feedpatternThe 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]feedpatternscaleThe factor by which to scale the pattern defined infeedpattern. [double, > 0]feedtaperThis parameter sets the taper (in dB) of the feed at an anglefeedanglefrom the feed axis to 10^-feedtaper/10. [double, > 0]PathologyparametersNone 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., settingrsub_xandrsub_yare 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_xDisplacement of the feed along the x axis. [double]dfeed_yDisplacement of the feed along the y axis. [double]dfeed_zDisplacement of the feed along the z axis. [double]dsub_xDisplacement of the subreflector along the x axis. [double]dsub_yDisplacement of the subreflector along the y axis. [double]dsub_zDisplacement of the subreflector along the z axis. [double]focusDisplacement of the feed along the feed axis. A positive value moves the feed closer to the subreflector. [double]rfeed_xRotation of the feed in degrees about the x axis. A positive value will rotate from the z axis through the y axis. [double]rfeed_yRotation of the feed in degrees about the y axis. A positive value will rotate from the x axis through the z axis. [double]rfeed_zRotation of the feed in degrees about the z axis. A positive value will rotate from the y axis through the x axis. [double]rsub_xRotation of the subreflector in degrees about the x axis. A positive value will rotate from the z axis through the y axis. [double]rsub_yRotation of the subreflector in degrees about the y axis. A positive value will rotate from the x axis through the z axis. [double]rsub_zRotation of the subreflector in degrees about the z axis. A positive value will rotate from the y axis through the x axis. [double]subrotpointDefines 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)]OperatingconditionparameterscomputeA 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:aSave the aperture images;jSave the Jones matrices in a table;pSave the parameters;sSave the polarized beams. Note that the string is case insensitive. [string]diffeffA user supplied diffraction efficiency. If none is provided, an internal algorithm that is not very good is used. This needs to be upgraded! [double]freqThe frequency in GHz at which the calculation will be run. [double, > 0]gridsizeSpecifies a fixed grid size. If odd, the next even number will be used. This option overrides any setting ofoversampand 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]leggroundscatterThe fraction of power that scatters off the struts toward the ground. The default value is 0.2. [double, >= 0, <= 1]misceffA 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]outThe prefix for all output files. The default iscassbeam. A dot will always separate the prefix from any trailing characters. [string]oversampOne 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. Seegridsizefor an alternate way of specifying the grid. This parameter is ignored ifgridsizeis set. [double, > 0]pixelsperbeamThis is the approximate number of pixels that the core of the beam will occupy in the output images. [int, > 0]TgroundThe temperature in Kelvin of the ground. The default value is 290. [double, > 0]TrecThe equivalent temperature of the receiver. This adds into the system temperature. The default value is 50. [double, > 0]TskyThe 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 whichcomputeoptions 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 parameterout. Currently all output images are in PGM format, which is a very simple greyscale image format supported by most unix-based image viewers.Apertureimages[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.pgmRaster 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.pgmRaster 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.pgmRaster 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.Jonesmatrixfile[j]The Jones matrix file,out.jones.datcontains 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 thegridsizeused. 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 parameterbeampixelscale, which is stored in the output fileout.paramsdescribed below.Parameterfile[p]The parameter file,out.paramsis 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:AeffThe effective area of the antenna [m^2]. [double]Aeff_TsysThe effective area of the antenna divided by the system temperature [m^2/K]. [double]ampeffThe amplitude efficiency. [double]beampixelscaleThe scale of the generated beam images [deg/pixel]. [double]blockeffThe blockage efficiency. [double]diffeffThe diffraction efficiency. [double]fwhm_lThe full width at half max of the beam in the l direction. [double]fwhm_mThe full width at half max of the beam in the m direction. [double]gainThe gain G of the antenna. [double]illumeffThe illumination efficiency. [double]peaksidelobeThe directivity of the greatest sidelobe relative to the peak directivity of the beam. [double]phaseeffThe phase efficiency. [double]point_lThe l component of the pointing offset from the z axis measured in the image plane. [double]point_mThe m component of the pointing offset from the z axis measured in the image plane. [double]prispilleffThe primary spillover efficiency. [double]programThe name of the program run, which iscassbeam. [string]misceffThe miscellaneous efficiency. [double]spilleffThe spillover efficiency. [double]subspilleffThe subreflector spillover efficiency. [double]surfeffThe surface efficiency. [double]totaleffThe total efficiency calculated for the antenna. [double]TsysThe system temperature. [double]versionThe software version number. [string]Polarizedbeamimages[s]With thesoption, 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 inout.jones.dat. These images are meant for qualitative inspection. The Jones matrices contain the formal output.out.I.pgmStokes I - total intensity;out.Q.pgmStokes Q - excess linear polarization e_1 over e_2;out.U.pgmStokes U - excess linear polarization in e'_1 over e'_2out.V.pgmStokes V - excess right circular polarzation over left circular polarization;out.QI.pgmThe ratio of the Stokes Q image to the Stokes I image;out.UI.pgmThe ratio of the Sytokes U image to the Stokes I image;out.VI.pgmThe ratio of the Stokes V image to the Stokes I image;

**AUTHOR**

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