Birli

Birli 是一个 Rust 库，用于在位于澳大利亚西部 Murchison Shire Wajarri Yamatji 土地上的 Murchison Widefield Array (MWA) 的数据处理流程中执行常见的预处理任务。

Birli 使用 mwalib 读取 MWA 相关器可见性，该库支持现有的 "遗产" MWA 相关器，以及正在开发的 "MWAX" 相关器。

Birli 是 Wajarri 词汇中表示闪电的单词，闪电是 MWA 常见的故障原因，也是本库预期提供的速度的一个很好的描述。

安装

先决条件

• Rust 编译器，版本 >= 1.64.0 - https://www.rust-lang.net.cn/tools/install
• AOFlagger >= 3.0 (Ubuntu > 21.04: apt install aoflagger-dev)
• CFitsIO >= 3.49 (Ubuntu > 20.10: apt install libcfitsio-dev)

有关特定于操作系统的说明，请查看 linux CI 脚本；Makefile.toml；以及 Dockerfile，因为这些文件会定期进行测试。下面的说明可能不会那么频繁地更新，但更详细。

(Debian/Ubuntu) Linux 设置

# Prerequisites for rustup, cargo and cargo-make
sudo apt install -y gcc libssl-dev pkg-config curl unzip wget
# Run the Rustup install script, profile=default, toolchain=stable
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -sSf | sh -s -- -y
# Cargo make uses Makefile.toml to automate development tasks
cargo install --force cargo-make
# Use multiple cores when compiling C/C++ libraries
export MAKEFLAGS="-j $MAKEFLAGS"
# Install prerequisite C/C++ libraries
cargo make install_deps
# Ensure that rust can find the C/C++ libraries.
# AOFlagger and CFitsIO default to /usr/local/lib
export LD_LIBRARY_PATH="/usr/local/lib/"

macOS

之前支持 macOS，但由于 casacore 和 aoflagger 的稳定性问题，这一支持已被取消。

以下内容可能或可能不起作用。

brew tap mwatelescope/tap
brew install mwatelescope/tap/aoflagger
AOFLAGGER_INCLUDE_DIR=/opt/homebrew/include/ cargo install --path .
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib/
birli

其他操作系统

不幸的是，大多数先决条件在 Windows 上不可用。然而，WSL 很好，并且有一个 docker 镜像！您可以使用 VSCode remote for WSL 或 Docker。您最好的选择是 Ubuntu LTS

安装二进制文件

cargo install --path .

这将在 $HOME/.cargo/bin 创建一个 birli 二进制文件。

故障排除

测试套件

如果您在 Birli 上遇到问题，请运行测试套件以缩小问题范围。

cargo test

依赖关系

遇到段错误？我可以保证这是由于 C 库依赖之一造成的。确保您有所有库的正确版本。这些在 先决条件 中指定。

在 Linux 上使用以下命令获取库版本

pkg-config --modversion cfitsio
aoflagger --version

如果您使用 apt 安装了 CASA 等软件，它将在 /usr/lib/x86_64-linux-gnu/ 中放置一个古老的 cfitsio 库版本。为了解决这个问题，您必须在 shell 中导出 LD_LIBRARY_PATH=/usr/local/lib/，以便 Birli 可以找到正确的库版本。

日志记录

您可以通过设置环境变量 RUST_LOG 来为单个 Rust 模块启用额外的日志记录。例如

RUST_LOG=trace birli ... # set log level to trace for all module (including dependencies)
RUST_LOG=birli=debug birli ... # set log level to debug for birli only
RUST_LOG=birli::io=error birli ... # only show warnings for birli's io module

有关更多示例，请参阅 env_logger 文档

info 的默认日志级别

Docker

在您的环境中无法工作？您始终可以在 Docker 中运行 Birli

docker run mwatelescope/birli:latest -h

想要在完全配置的 Birli 开发环境中打开 shell？很简单！

docker run -it --entrypoint /bin/bash --volume $PWD:/app mwatelescope/birli:latest

注意：这将当前目录挂载到 Docker 镜像中的 /app，这意味着这两个系统共享相同的 target 文件夹。因此，如果您的宿主系统架构与 Docker 不同，您可能需要在切换这些环境之间每次都运行 cargo clean。您还可能想要暂时禁用任何使用

HPC 上的 Singularity

# - load the singularity module
module load singularity
# - cd into your preferred sif file location, e.g. /pawsey/mwa/singularity/birli
# - create a .sif file from the latest mwatelescope/birli docker image
singularity pull --dir . docker://mwatelescope/birli:latest
# - run birli within the singularity image
singularity exec  /pawsey/mwa/singularity/birli/birli_latest.sif /app/target/release/birli ${YOUR_BIRLI_ARGS}

查看此 gist 了解使用 Birli 的 Garrawarla SLURM 作业的示例

HPC 上的 Singularity（调试模式）

这将为您提供有关您在 Birli 上遇到任何问题的更多信息，但是调试构建未经优化，速度较慢。

# - request an interactive HPC session
salloc --partition workq --time 1:00:00 --nodes 1 -c 38 --mem=350G
# - load the singularity module
module load singularity
# - cd into your preferred sif file location, e.g. /pawsey/mwa/singularity/birli
# - create a .sif file from the latest mwatelescope/birli docker image
singularity pull --dir . docker://mwatelescope/birli:debug
# - run birli within the singularity image
singularity exec  /pawsey/mwa/singularity/birli/birli_debug.sif /bin/bash

在下面的 shell 中

# - enable lots of logs
export RUST_LOG=trace
# - run birli in debug mode with GDB
gdb --args /app/target/debug/birli ${YOUR_BIRLI_ARGS}
# > run

用法

birli-h

USAGE:
    birli [OPTIONS] --metafits <PATH> <PATHS>...

OPTIONS:
        --apply-di-cal <PATH>        Apply DI calibration solutions before averaging
        --dry-run                    Just print the summary and exit
        --emulate-cotter             Use Cotter's array position, not MWAlib's
    -h, --help                       Print help information
        --no-draw-progress           do not show progress bars
        --phase-centre <RA> <DEC>    Override Phase centre from metafits (degrees)
        --pointing-centre            Use pointing instead phase centre
    -V, --version                    Print version information

INPUT:
    -m, --metafits <PATH>    Metadata file for the observation
    <PATHS>...           GPUBox files to process

SELECTION:
        --no-sel-autos                [WIP] Deselect autocorrelations
        --no-sel-flagged-ants         [WIP] Deselect flagged antennas
        --sel-ants <ANTS>...          [WIP] Antenna to select
        --sel-chan-ranges <RANGES>    Select separate channel ranges
        --sel-time <MIN> <MAX>        Timestep index range (inclusive) to select

RESOURCE LIMITS:
        --max-memory <GIBIBYTES>    Estimate --time-chunk with <GIBIBYTES> GiB each chunk.
        --time-chunk <STEPS>        Process observation in chunks of <STEPS> timesteps.

FLAGGING:
        --flag-antennas <ANTS>...         Flag antenna indices
        --flag-autos                      Flag auto correlations
        --flag-coarse-chans <CHANS>...    Flag additional coarse chan indices
        --flag-dc                         Force flagging of DC centre chans
        --flag-edge-chans <COUNT>         Flag <COUNT> fine chans on the ends of each coarse
        --flag-edge-width <KHZ>           Flag bandwidth [kHz] at the ends of each coarse chan
        --flag-end <SECONDS>              Flag seconds before the last provided time
        --flag-end-steps <COUNT>          Flag <COUNT> steps before the last provided
        --flag-fine-chans <CHANS>...      Flag fine chan indices in each coarse chan
        --flag-init <SECONDS>             Flag <SECONDS> after first common time (quack time)
        --flag-init-steps <COUNT>         Flag <COUNT> steps after first common time
        --flag-times <STEPS>...           Flag additional time steps
        --no-flag-dc                      Do not flag DC centre chans
        --no-flag-metafits                Ignore antenna flags in metafits

CORRECTION:
        --no-cable-delay           Do not perform cable length corrections
        --no-digital-gains         Do not perform digital gains corrections
        --no-geometric-delay       Do not perform geometric corrections
        --passband-gains <TYPE>    Type of PFB passband filter gains correction to apply [default:
                                   auto] [possible values: none, cotter, jake, auto]

AVERAGING:
        --avg-freq-factor <FACTOR>    Average <FACTOR> channels per averaged channel
        --avg-freq-res <KHZ>          Frequency resolution of averaged data
        --avg-time-factor <FACTOR>    Average <FACTOR> timesteps per averaged timestep
        --avg-time-res <SECONDS>      Time resolution of averaged data

OUTPUT:
    -f, --flag-template <TEMPLATE>    The template used to name flag files. Percents are substituted
                                      for the zero-prefixed GPUBox ID, which can be up to 3
                                      characters long. Example: FlagFile%%%.mwaf
    -M, --ms-out <PATH>               Path for measurement set output
    -u, --uvfits-out <PATH>           Path for uvfits output

AOFLAGGER:
        --aoflagger-strategy <PATH>    Strategy to use for RFI Flagging
        --no-rfi                       Do not perform RFI Flagging with aoflagger

注意：aoflagged 选项仅在启用 aoflagger 功能时可用。

操作按以下各节所述的顺序执行。

电缆延迟校正

电缆延迟校正涉及调整可见性相位，以校正每个 tile 与其接收器之间电缆电气长度的差异。

Legacy MWA 相关器观测通常不会应用电缆延迟，但是 MWAX 观测可以。metafits 中的 CABLEDEL 键描述了应用了哪些几何延迟。

默认情况下，Birli 将应用电缆长度校正。您可以使用 --no-cable-delay 来禁用此操作。

基线的电缆长度由基线的 rfInput 电气长度之差确定，如 metafits 的 TILEDATA HDU 中指定。复杂数据的可见性通过一个角度进行相移，该角度由电气长度和通道频率确定。

let angle = -2.0 * PI * electrical_length_m * freq_hz / SPEED_OF_LIGHT_IN_VACUUM_M_PER_S;

数字增益校正

原始数据中的每个输入都按每个粗通道的因子进行缩放。这在 metafits 主要 HDU 的 Gains 列中定义。默认情况下，Birli 会校正这些数字增益，您可以使用 --no-digital-gains 来禁用此操作。

粗 PFB 带通校正

对粗通道多相滤波器组（PFB）通带滤波器增益进行校正有四种选项。对于传统的相关器观测，最好使用cotter，而对于MWAX相关器观测，最好使用jake。使用auto会根据metafits文件中的信息选择最合适的选项，而使用none将禁用这种校正。

尽管PFB通带滤波器形状是接收器中使用的滤波器系数的函数，但它也受到所使用的细通道化技术的影响，这两个相关器之间略有不同。

MWAX通道化器只是一个具有矩形窗口的FFT，其中的超细通道随后聚合到你的频率分辨率；而传统的相关器则有一个最小bin宽度为10kHz的二级细-PFB。这两种不同的方法在细通道之间有不同的泄漏量，这会影响粗通道的频谱形状。更多的泄漏导致频谱形状在频率上变得平滑。

cotter增益来源于Cotter的_sb128ChannelSubbandValue2014FromMemo，在subbandpassband.cpp中。这些有时被称为Levine增益。由于这些增益是在基础传统相关器分辨率10KHz下计算的，因此它们不适用于不是10kHz的倍数的分辨率。

jake增益（归功于Jake Jones）在这篇维基文章中描述。

当将PFB增益应用于与增益分辨率不同的观测时，需要对这些增益进行平均以适应数据，而这一平均的确切细节取决于相关器类型。有关更多详细信息，请参阅mwa维基上的平均细通道。

RFI标记

默认情况下，Birli会使用AOFlagger中的默认MWA策略来标记数据。您可以使用--no-rfi选项来禁用此功能，或使用--aoflagger-strategy选项提供您自己的策略文件。

几何延迟校正（又称相位跟踪）

几何校正涉及调整可见度相位，以纠正来自相位中心的光到达每个面板的距离差异。

传统的MWA相关器观测通常不进行相位跟踪，然而MWAX观测可以应用相位跟踪。metafits中的GEODEL卡描述了已应用哪些几何延迟。

默认情况下，如果尚未应用，Birli将应用相位中心的几何校正。它从metafits中的RAPHASE和DECPHASE卡确定观测的相位中心。如果这些不可用，则使用metafits中的指向中心卡（RA和DEC）。您可以使用--no-geometric-delay禁用几何校正，以及使用--phase-centre和--pointing-centre选项来覆盖相位中心。

基线几何长度由其UVW傅里叶空间向量的w分量确定，在将其面板位置和相位中心应用于J2000历元之前，应用摄动和章动，并考虑星体折射。复相干度通过由w分量和通道的频率确定的角位移。

let angle = -2.0 * PI * uvw.w * freq_hz / SPEED_OF_LIGHT_IN_VACUUM_M_PER_S;

校准

Birli可以使用--apply-di-cal标志应用方向无关的校准解决方案。这些解决方案在平均之前应用。未平均可见性中的通道数必须是校准解决方案文件中通道数的整数倍。与Cotter不同，Birli将处理存在NaN值的校准解决方案，通过标记任何存在NaN的可见性来处理。

目前，仅支持MWA aocal格式（.bin），该格式由mwa-reduce包中的calibrate二进制程序生成。该格式在此处进行了描述，然而由于startTime和endTime字段定义不明确，它们的值被忽略，因此只能应用单个时间段的解决方案。

Cotter仿真

--emulate-cotter标志确保输出尽可能与Cotter匹配。只有在你需要直接与Cotter进行比较时才应使用此标志。

默认情况下，Birli将使用MWALib中的MWA阵列位置来计算UVWs和几何校正，这比Cotter使用的更准确，也是直接比较时误差的主要来源。

此标志作为src/main.rs测试的一部分使用，以验证Birli的输出与Cotter在可接受范围内匹配。

平均

要按给定的整数因子对时间或频率数据进行平均，你可以提供--avg-time-factor或--avg-freq-factor选项。这也可以通过使用--avg-time-res和--avg-freq-res选项来实现，这些选项分别接受[秒]的持续时间或[千赫兹]的带宽。第二组选项将根据输入数据的分辨率选择最接近的整数平均因子。

输出

Birli可以将可见性数据输出到uvfits或测量集，使用--ms-out（-M）或--uvfits-out（-u）。它还可以使用--flag-template（-f）以.mwaf格式输出每个粗通道的标志，其中模板参数中的%字符将被用于标识从GPUBox文件中获取粗通道数据的相同零前缀粗通道标识符所替换。对于旧数据，使用两个百分号字符，因为粗通道标识符是GPUBox编号。然而，对于MWAX数据，粗通道标识符是通道号，需要三位数字。

示例：自动确定标志模板

export flag_template='Flagfile%%.mwaf'
if [ ${obsid} -gt 1300000000 ]; then
    flag_template='Flagfile_ch%%%.mwaf'
fi
birli \
  -f $flag_template \
  ...

当处理一组接收机通道号不连续的粗通道时，将在测量集和uvfits文件名中添加后缀，以指示该文件中的粗通道或粗通道范围。

Cotter比较

以下表格显示了Birli选项如何映射到Cotter选项

Birli	Cotter	Cotter描述
--version	-版本	输出版本并退出。
-m<路径>	-m<文件名>	从给定的fits文件名中读取元数据。
-f，-u，-M	-o<文件名>	将输出保存到给定的文件名
--no-rfi	-norfi	禁用射频干扰检测。
--aoflagger-strategy<路径>	-标志-策略<文件>	使用指定的aoflagger策略。
--no-cable-delay	-nocablelength	不要执行电缆长度校正。
--no-geom	-nogeom	禁用几何校正。
--phase-centre<赤经> <赤纬>	-中心<ra> <dec>	设置替代相位中心，例如 -centre 00h00m00.0s 00d00m00.0s。
--pointing-centre	-usepcentre	以指向中心为中心。
--avg-时间-res<秒>	-timeres<s>	在写入测量集之前，将时间步的秒数平均在一起。
--avg-freq-res<千赫兹>	-freqres<kHz>	在写入测量集之前，将通道的 kHz 带宽平均在一起。
--apply-di-cal<路径>	-full-apply<文件>	在平均之前应用解决方案文件。
--no-digital-gains	-nosbgains	不纠正数字增益。
--max-memory (WIP)	-absmem<gb>	使用最多指定的大致内存量，单位为千兆字节。
--flag-edge-width<kHz>	-edgewidth<kHz>	标记每个子带的边缘通道的给定宽度（默认：80 kHz）。
--flag-init<sec>	-initflag<sec>	指定在观测开始时标记的秒数（默认：QUACK）
--flag-end<sec>	-endflag<sec>	指定在观测结束时额外标记的秒数（默认：0s）。
--flag-dc	-flagdcchannels	标记每个子带的中心通道（目前为默认设置）。
--no-flag-dc	-noflagdcchannels	不要标记每个子带的中心通道。
--flag-antennae <ANTS>... (WIP)	-flagantenna<lst>	将逗号分隔的零索引天线列表标记为标记天线。
--flag-coarse-chans <CHANS> (WIP)	-flagsubband<lst>	标记逗号分隔的零索引子带。
--no-sel-autos (WIP)	-noautos	不输出自相关。
(not --flag-autos)	-noflagautos	不要标记自相关（uvfits 文件输出的默认设置）。
(default)	-nostats	禁用收集统计数据（uvfits 文件输出的默认设置）。
(not --no-sel-flagged-ants, WIP)	-noantennapruning	不要移除标记的天线。
(default)	-allowmissing	当不是所有 GPU 盒文件都可用时不要中止（默认是中止）。

Birli 在没有提供标记时执行与 Cotter 相同的所有默认预处理步骤。例外的是，我们尚未实现自动相关的标记，标记天线的修剪。这意味着 birli <in/out args> 等同于

 cotter \
  -allowmissing \
  -noantennapruning \
  -noflagautos \
  -nostats \
  -flag-strategy <mwa default aoflagger strategy>
  <in/out args>

目前没有意图复制以下 Birli 选项，所以如果这些对您很重要，请提出问题

• 粗通道选择 (-sbcount, -sbstart)：这可以通过简单地更改 CLI 参数中给出的粗通道文件来实现)
• Dysco 压缩 (-use-dysco, -dysco-config)
• 手动元数据指定 (-a, -h, -i)：此信息从 metafits 中容易获得。
• -offline-gpubox-格式
• 质量统计（-saveqs，-histograms，-skipwrite，-nostats）
• -noflagmissings：如果缺少一个HDU，则应始终标记。
• -apply：仅支持-full-apply。
• -noalign：gpuboxes始终对齐。
• CPU限制（-j）：Birli使用crossbeam进行并发，智能地使用可用的计算资源。可以使用cgroups实现严格的资源限制。
• 内存百分比限制（-mem）：仅支持-absmem。在HPC系统上确定内存限制不可靠，因此我们建议手动指定内存限制。
• -sbpassband<文件>
• -flagfiles <name>应用现有标记

示例：RFI标记，校正，平均，输出

在这个示例中，我们使用aoflagger子命令来

• 使用MWA默认标记策略执行RFI标记
• 执行几何和电缆长度校正
• 将数据平均到4秒，160kHz
• 将可见性输出到.uvfits（-u）

birli \
  -m tests/data/1254670392_avg/1254670392.metafits \
  -f "/tmp/Flagfile.Birli.MWA.%%.mwaf" \
  -u "/tmp/1254670392.birli.uvfits" \
  --avg-time-res 4 --avg-freq-res 160 \
  tests/data/1254670392_avg/1254670392_*gpubox*.fits

等效的Cotter命令将是

# output uvfits
cotter \
  -m tests/data/1254670392_avg/1254670392.metafits \
  -o "tests/data/1254670392_avg/1254670392.cotter.uvfits" \
  -allowmissing \
  -noantennapruning \
  -noflagautos \
  -nostats \
  -timeres 4 \
  -freqres 160 \
  -flag-strategy /usr/local/share/aoflagger/strategies/mwa-default.lua \
  tests/data/1254670392_avg/1254670392_20191009153257_gpubox*.fits

贡献

欢迎拉取请求！请尽力确保测试覆盖率的高标准得到维持。

在每次提交之前，使用cargo make ci来确保您的代码格式正确。

致谢

这项科学研究使用从Murchison射电天文台获得的数据。我们感谢Wajarri Yamatji人作为天文台场地的传统所有者。

覆盖率

此存储库经...批准