CASSBEAM(1)

📦 version 1.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🛰️ CASSBEAM(1) — User Commands 🛰️

okay so this is the manual for cassbeam, aka the Cassegrain antenna ray tracer. It's giving very serious science bestie energy, but I got you. 💅

✨ NAME ✨

  • cassbeam — Cassbeam is a Cassegrain antenna ray tracer.

🎀 SYNOPSIS 🎀

cassbeam input_file [key=value ...]

💫 DESCRIPTION 💫

okay so 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. No cap.

Cassbeam is a non-interactive command line program that takes all of its input from the command line. And note that this does not preclude someone at a later date from making a graphical or web front end. So like, CLI-only for now, but the future is open. 🌈

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

📝 INPUT FILE 📝

okay bestie so the main input file? it's literally just a bunch of lines that look like key=value. that's it. that's the whole vibe. one entry per line, no multitasking — and the equal sign is optional, so you can be a little chaotic if you want. 💅

the file also lets you leave comments! every comment starts with %, and the % plus everything after it on that line gets ignored by cassbeam. so go ahead, annotate your heart out. 💖

depending on the key, the value can be one of five types: string, integer, double, vector, or none.

  • a string is a sequence of non-whitespace characters not surrounded by quotes of any kind — so no sneaky " or ', bestie
  • a double is a number that can have a fractional part
  • a vector is a comma-separated list of doubles
  • the none type expects no value at all

below is the full list of allowed keys and what type of value each one wants. if the range of legal values is restricted, that legal range shows up inside brackets. ⚠️ and heads up: legal values do not imply a physical system that will generate meaningful results! like, the code will accept it. the universe might not. 🙈

for the vector type, if a certain number of values is needed, that count is in parentheses. and a required parameter gets marked with a *.

🚨 the thing you NEED to internalize: the secondary optical surface (aka the subreflector) is defined based on the input geometry. so changing where the feed sits changes the geometry of the subreflector! if you want to poke at telescope parameters without messing with the subreflector's shape, that's what the pathology parameters are for. also, the order of the parameters doesn't matter. ✨

📡 Antenna geometry parameters 📡

  • feed_x — the x value of the phase center of the feed. if you don't give a value, 0 is assumed. [double]
  • feed_y — the y value of the phase center of the feed. no value? 0 is assumed. [double]
  • feed_z — the z value of the phase center of the feed. no value? again, 0 is assumed. [double]
  • geom — this string points to a disk file holding the primary optical surface geometry. the file is a three-column ascii text file, each column holding space-separated values for r, z, and dz/dr for the antenna. there's no limit to how many lines it can have (other than your computer's memory, obviously 😭). it's 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 you omit it, no hole gets made. [double, > 0]
  • legapex — the z value where the legs (struts) intersect each other. note that the legs might terminate before reaching this point. default is 1.2*sub_h. [double, > 0]
  • legfoot — the r value where the legs (struts) intersect the primary surface. default is half the antenna radius. [double, > 0]
  • legwidth — the effective width of the legs, used to compute blockage. note that currently a positive value means 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 get rotated 45°. if this parameter isn't set, or if it's set to 0, then no legs get generated at all. [double]
  • name — an optional name for the antenna. and if the name is ``VLBA'', then the true strut geometry for the VLBA antennas is used instead of equispaced struts. 👑 [string]
  • roughness — the RSS surface roughness in meters. this number represents the combined surface error for the primary and secondary. if you don't provide a roughness, the default 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 you have to provide either both feedtaper and feedangle or feedpattern. pick a lane, bestie.
  • 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 holds 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 🩹

so here's the tea: none of the following operations change the shape of the subreflector — its geometry is calculated before they get applied. 🫶

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

and for composited rotations (i.e., when 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, and y rotation before x rotation — regardless of the order the parameters were received in. so no, you can't reorder your way out of it. 💀

  • 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 how many elements you provide: 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 telling cassbeam what output to produce. it 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 you don't provide one, an internal algorithm that is not very good gets 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 it's odd, the next even number gets 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. default value is 0.2. [double, >= 0, <= 1]
  • misceff — a factor of the efficiency calculation that contains "everything else". you are responsible for choosing a realistic value for this one. a default of 1 (i.e., 100%) is assumed if this parameter isn't provided. [double, >= 0, <= 1]
  • out — the prefix for all output files. 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 makes the grid on the primary fine enough to accommodate 4*oversamp*R/lambda points. default is 1. note that vastly "undersampling" is fine, since the field is never calculated anywhere between the feed and the aperture plane. normally blockage calculations and constancy of the illumination 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. default value is 290. [double, > 0]
  • Trec — the equivalent temperature of the receiver. this adds into the system temperature. default value is 50. [double, > 0]
  • Tsky — the temperature in Kelvin of the sky. default value is 3 for frequencies over 1 GHz, and 3 * 10^-2.5 nu for frequencies below 1 GHz. [double, > 0]

✨ OUTPUT FILES ✨

okay bestie so depending on which compute options you picked at run time, you get up to 12 output files 💖. The letter in brackets in the section headings tells you which option turns that file on. And every single one of these output files starts with whatever value you gave to the input parameter out. Also FYI, right now all the output images are in PGM format, which is a super simple greyscale image format that basically every unix-based image viewer supports. iconic of it honestly. 🎀

🌸 Aperture images [a]

Three images get generated so you can vibe-check the aperture field qualitatively. If you need actual quantitative numbers though, you'd have to go modify the source code to export the illumination parameters. so, yk. 🫶

  • out.illumamp.pgm — a 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 — a raster image showing the net phase (that's pathlength multiplied by wave vector) at each point on the primary. A phase gradient is removed. Any portions of the image that correspond to zero flux have an arbitrary phase, so like, don't read too much into those. 🙈
  • out.illumblock.pgm — a raster image showing the blocked portion of the aperture. White means that part of the dish experiences either plane wave blockage from the sky or spherical wave blockage from the feed, and therefore does not contribute to the gain of the antenna. blocked bestie, no notes. 💀

💜 Jones matrix file [j]

The Jones matrix file, out.jones.dat, contains the Jones matrix (peep Hamaker et al. 1996 for the details, iykyk) 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 the 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 they were given on the command line) as well as many output values. Here they are, in order, no skips: 👑

  • 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 info is derived from the Jones matrices which get saved in out.jones.dat. These images are meant for qualitative inspection — the Jones matrices are the ones holding the formal output, bestie. 💅

  • 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. shoutout to him fr fr 🫶

👑 SEE ALSO 👑

See the complete manual in /usr/share/doc/cassbeam/ for more information. go read it, it's giving lore 💖

and that's a wrap, bestie!! ✨ this whole thing is version 1.0, dated 18 Aug 2003, which is honestly vintage in the most iconic way 🦋💅 go beam some radio waves, you got this 💖🌸

📦 where this page comes from