---
title: BEAMDATA.txt
section: 5
---

# NAME
beamdata.txt --- beam launcher data for **gray**(1)

# FORMAT
The beam launcher data can be provided in three ways, each with a corresponding
file format.

## 0D format
The beam parameters are given as fixed numbers, independent of the values of
the launch angles α, β. In this case the format is as follows:

    f  ! comment
    x₀ y₀ z₀
    w₀₁ w₀₂ d₀₁ d₀₂ φ
where:

  - *f* is the frequency (GHz)
- *x₀, y₀, z₀* are the launcher position (cm)
- *w₀₁, w₀₂* are the beam waists in the two principal directions (cm)
- *d₀₁, d₀₂* are the distances of the beam waists from the launch point (cm)
- *φ* is the rotation angle from the horizontal direction to the first
  principal direction (deg)

Note: this case implies simple astigmatism, i.e. the amplitude and phase
ellipses in the beam transverse plane are aligned.

## 1D format
The beam parameters, including the launch position and angles, are given as a
function of the launcher steering angle *θ* in tabular format. The data will be
interpolated by GRAY to obtain the actual beam parameters at a given pair of
launch angles.

The format is as follows:

    f  ! comment
    nrows
    θ α β x₀ y₀ z₀ w₁ w₂ k₁ k₂ φ_w φ_R
    θ α β x₀ y₀ z₀ w₁ w₂ k₁ k₂ φ_w φ_R
    ...
The first two lines contain the frequency (GHz) and the number of table rows.
The rest of the file contains the whitespace-separated records, one row per
line, where:

- *θ* is the mechanical steering angle (unused)
- *α, β* are the poloidal and toroidal launch angles (deg)
- *x₀, y₀, z₀* are the launcher position (mm)
- *w₁, w₂* are the beam widths in the two principal directions (mm)
- *k₁, k₂* are the wavefront curvatures in the two principal directions (mm⁻¹)
- *φ_w, φ_R* are the rotation angles of the amplitude and phase
  ellipses in the transverse plane at the launch point (deg)

## 2D format
The beam parameters, including the launch position, are given as a
function of the two launch angles α, β. The format is as follows:

    nbeams
    id mode f na nb
    α β x₀ y₀ z₀ w₁ w₂ k₁ k₂ φ_w φ_R
    α β x₀ y₀ z₀ w₁ w₂ k₁ k₂ φ_w φ_R
    ...
    id mode f na nb
    α β x₀ y₀ z₀ w₁ w₂ k₁ k₂ φ_w φ_R
    α β x₀ y₀ z₀ w₁ w₂ k₁ k₂ φ_w φ_R
    ...

The first line specifies the number of beams described by the file.
The rest of the files consists of *nbeams* 2D tables preceded by a header where:

- *id* is a string identifier of the beam
- *mode* indicates where the beam has O-mode (*1*) or X-mode (*2*)
  polarisation
- *f* is the frequency (GHz)
- *nα, nβ* are the numbers of rows and columns of the table

The 2D table is stored in row-major order over *nα×nβ* lines, that is, the
*i,j*-th record is stored on the l-th line, with *l = i + nα×j*.
The poloidal angle *α(i,j)* must be monotonic along *i* and the toroidal angle
*β(i, j)* must be monotonic along *j*.
Each line stores one record with the same fields as in the 1D format.

Note: even if this format allows to define multiple independent beams in the
same file, this feature is not used by **gray**(1), which always load the first
table.

# EXAMPLES

1. A valid 0D beamdata.txt file

       170                      ! f
       950.0 0.0 62.0           ! x₀  y₉ z₀
       2.1 2.1 162.0 162.0 0.0  ! w₀₁ w₀₂ d₀₁ d₀₂ φ

2. A valid 1D beamdata.txt file

       170  ! f
       27   ! nrows
       -7.5  25.93  19.75  7067.6  -41.45  4233.6  42.70  43.99  -5.899E-4  -5.363E-4  -3.15  -3.15
       -5.0  31.23  19.99  7067.8  -41.48  4233.6  42.70  43.99  -5.899E-4  -5.364E-4  -2.32  -2.32
       -2.0  37.61  20.09  7068.1  -41.51  4233.5  42.69  43.98  -5.900E-4  -5.364E-4  -1.09  -1.09
        3.5  49.29  19.77  7068.7  -41.58  4233.2  42.67  43.97  -5.902E-4  -5.366E-4  -2.11  -2.11

3. A valid 2D beamdata.txt file

       1                    ! nbeams
       example 1 137.6 6 2  ! id mode f nα nβ
       -7.96  -12.99  4352  -161.2   907  16.46  28.67  -2.48E-05  -2.36E-03  -21.79   5.61
        4.82  -13.18  4392  -149.4   976  15.80  26.29  -4.71E-05  -2.56E-03  -17.88   8.85
       14.52  -13.40  4416  -138.6  1031  15.30  24.50  -1.72E-04  -2.80E-03  -14.87  11.95
       24.86  -13.70  4438  -125.4  1091  14.92  22.66  -4.36E-04  -3.19E-03  -11.63  15.84
       36.12  -14.12  4455  -109.2  1159  14.90  20.80  -8.64E-04  -3.81E-03   -8.29  20.21
       48.76  -14.72  4466   -89.0  1235  15.74  18.91  -1.38E-03  -4.80E-03   -7.66  23.62
       -9.80   -6.93  4353  -132.0   904  16.71  29.36  -1.71E-04  -2.28E-03  -10.02   8.52
        2.84   -7.14  4392  -123.8   972  16.03  26.82  -1.85E-04  -2.46E-03   -7.62  10.46
       12.39   -7.38  4416  -116.4  1025  15.53  24.95  -3.05E-04  -2.67E-03   -5.78  12.41
       22.50   -7.72  4437  -107.4  1084  15.13  23.06  -5.55E-04  -2.99E-03   -3.79  14.90
       33.42   -8.18  4454   -96.5  1149  14.57  21.17  -9.75E-04  -3.51E-03  -10.43  14.82
       45.51   -8.80  4465   -83.0  1222  15.65  19.32  -1.48E-03  -4.35E-03    0.41  20.57