---
orphan: true
---

# xengine_metadata_v2.yml

```yaml
# The purpose of this "X-engine metadata" file is to document the file format.
# It will be used in two contexts:
#
#  1. Every X-engine node sends this file to every FRB node, at the beginning
#    of the TCP stream.
#
#  2. As a configuration file for the "fake correlator" used for testing.
#
# This is a minimal "version 0", and will be extended later.

version: 2

# Frequency channels. The observed frequency band is divided into "zones".
# Within each zone, all frequency channels have the same width, but the
# channel width may differ between zones.
#   zone_nfreq: number of frequency channels in each zone.
#   zone_freq_edges: frequency band edges in MHz.
# For example:
#   zone_nfreq: [N]      zone_freq_edges: [400,800]      one zone, channel width (400/N) MHz
#   zone_nfreq: [2*N,N]  zone_freq_edges: [400,600,800]  width (100/N), (200/N) MHz in lower/upper band
#
# In this config, we have:
#  Total frequency channels: 28160
#  Channel widths (MHz): [ 0.00610352, 0.012207, 0.0244141, 0.0976562, 0.195312 ]

zone_nfreq: [8192, 8192, 6144, 2048, 3584]
zone_freq_edges: [300, 350, 450, 600, 800, 1500]

# Optional: which frequency channels are present?
# A list of distinct integers 0 <= (channel_id) < (total frequency channels).
# Only makes sense in "context 1" (see above), to indicate which frequency channels
# are sent by a particular X-engine node.

freq_channels: [ 0, 10000, 20000, 28159 ]

# Data for each beam recieved by this node, all fields required. An opaque id and sky coordinates,
# given as direction cosines in the grid frame.  The grid frame is defined by x & y unit vectors
# which are orthogonal and lie along (or close to) the axes of the telescope grid. Each
# beam has a skywards-directed unit vector b.  The grid_x and grid_y values are the x & y direction
# cosines: b.x and b.y.
beams: [
  {id: 100, grid_x: 0.0, grid_y: 0.0},
  {id: 200, grid_x: 0.1, grid_y: 0.0},
  {id: 300, grid_x: 0.0, grid_y: 0.1},
]

#############
# Timekeeping
#############


# Each frame from the X-engine will come with the fpga sequence number (seq) at the beginning of the frame.
# To keep time in pirate, we need to know:
# - unix_ns_at_seq_0: the epoch (the UNIX time at seq = 0, in nanoseconds).
# - dt_ns_per_seq: the rate at which seqs tick, number of nanoseconds per seq tick.
# - seq_per_frame: the number of seq ticks covered by a data frame.
#
# In Kotekan language:
# unix_nx_at_seq_0 = time0_ns
# dt_ns_per_seq = fengine_fft_length / ADC_sampling_rate_GHz
# seq_per_frame = 256 * frb_downsampling_factor (not sure if this exists)
#
# The sifter will need Earth Orientation Parameters (EOP) (which change in time and Kotekan has) and
# a precession/nutation model (which Kotekan does *not* have) to compute RA/DEC for the beams.
# Since the sifter has to do this calculation anyways, I propose we *don't* sent UT1 or EOP data
# from Kotekan to Pirate, and instead rely on the sifter to make the astropy calls itself.
#
# This means the sifter may infer a *slightly* different UT1 for the same seq number compared to 
# the X-engine (if it has more up-to-date EOP data).  The difference will be sub-ms, which I think is
# acceptable?
#
# unix_ns_at_seq_0 will change whenever the F-engine reboots, which will also require a reboot of
# the X-engine.

unix_ns_at_seq_0: 1772483060000000000
dt_ns_per_seq: 5120
seq_per_frame: 256

###########
# Telescope alignment and localization parameters.
###########

# Coordinate Systems
#
# Topocentric: origin at the given lat/lon. x-axis is directed exactly East (increasing Longitude),
#   y-axis is directed exactly North (increasing Latitude), z-axis is directed exactly "up" (increasing
#   altitude). orthogonal, Z = X x Y.
#
# Grid: origin at SW corner of Dish Array, aligned with Dish Array.  x-axis directed "east-ish"
#   parallel to dish "e/w" separatation vector.  y-axis directed "north-ish" parallel to "n/s"
#   separation vector.  Z = X x Y points normal to grid plane.  Dish grid lives in x-y plane at a
#   constant Z. Orthogonal. Rotated by O(1) degrees from "Topocentric"
#
# Dish Elevation Axis: The axis around which the dishes pivot. positive is in the east direction.
#   *Not* parallel to the dish grid "e/w" separation. "Coelevation" pointing measures an angle around
#   this axis.
#
# Dish Vertical Axis: Local "up/zenith" for the dishes. The direction which has coelevation = 0.0.
#   Orthogonal to the Dish Elevation axis.

# Position on the Earth in degrees
tel_origin_itrs_lat_deg: 49.32075144444
tel_origin_itrs_lon_deg: -119.62081125

# Unit vectors in the x & y grid directions, in topocentric coordinates.
tel_grid_x_axis: [ 0.999974342398359362,
                -0.000037539331442772,
                -0.007163318767675494]
tel_grid_y_axis: [0.000065403387739210,
                0.999992433220348809,
                0.003889630373557614]

# Unit vectors for the dish frame, the elevation axis and vertical axis, in
# topocentric coordinates.
tel_dish_elev_axis: [0.99999999838132391,
                -0.000056897733584327,
                0.0]
tel_dish_vert_axis: [0.0, 0.0, 1.0]

# The dish pointing angle, co-elevation in degrees: angle away from vertical,
# north is positive
tel_dish_coelev_deg: 0.0

# Values of dish separation in x and y directions in meters.
tel_dish_separation_x_m: 6.300156854906823
tel_dish_separation_y_m: 8.500057809796308
```