# Birli
Birli logo
Linux Tests Crates.io codecov codecov rust-reportcard Crates.io
A Rust library for common preprocessing tasks performed in the data pipeline of the Murchison Widefield Array (MWA), located on the land of the Wajarri Yamatji people in Murchison Shire, Western Australia. Birli reads MWA correlator visibilities in the gpufits file format using [mwalib](https://github.com/MWATelescope/mwalib), which supports the existing "legacy" MWA correlator, as well as the in-development "MWAX" correlator. **Birli** is the Wajarri word for lightning, a common cause of outages at the MWA, and a great descriptor for the speed which this library intends to deliver. ## Installation ### Prerequisites - A Rust compiler with a version >= 1.65.0 - - [AOFlagger](https://gitlab.com/aroffringa/aoflagger) >= 3.0 (Ubuntu > 21.04: apt install aoflagger-dev) - [CFitsIO](https://heasarc.gsfc.nasa.gov/fitsio/) >= 3.49 (Ubuntu > 20.10: apt install libcfitsio-dev) for OS-specific instructions, check out the [linux](https://github.com/MWATelescope/Birli/blob/main/.github/workflows/linux_test.yml) CI Script; the [Makefile.toml](https://github.com/MWATelescope/Birli/blob/main/Makefile.toml); and the [Dockerfile](https://github.com/MWATelescope/Birli/blob/main/Dockerfile) as these are tested regularly. The instructions below may be updated less frequently, but are better documented. ### (Debian/Ubuntu) Linux Setup ```bash # 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 Previously macOS was supported, however this has ben dropped due stability issues with casacore and aoflagger. The following may or may not work. ```bash 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 ``` It is not possible to set the library search path globally . So if you don't set `DYLD_FALLBACK_LIBRARY_PATH` you will see an error like ```txt libc++abi: terminating due to uncaught exception of type std::runtime_error: cannot open : No such file or directory ``` in some cases, macOS will deliberately unset this. ```bash export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib/ echo ${DYLD_FALLBACK_LIBRARY_PATH:-unset} # it's set here bash -c 'echo ${DYLD_FALLBACK_LIBRARY_PATH:-unset}' # but not here ``` ### Other Operating Systems Unfortunately most of the prerequisites aren't available on Windows. However, WSL is great, and there is a docker image! You could use VSCode remote for WSL or Docker. Your best best is Ubuntu LTS ### Installing the binary ```bash cargo install --path . ``` This creates a `birli` binary in `$HOME/.cargo/bin` ## Troubleshooting ### Test suite Having issues with Birli? run the test suite to narrow down your issue. ```bash cargo test ``` ### Dependencies Experiencing segfaults? I can guarantee it's because of one of the C library dependencies. Make sure you have the right versions of all the libraries. These are specified in [Prerequisites](#prerequisites). Get library versions on linux with: ```bash pkg-config --modversion cfitsio aoflagger --version ``` If you have something like CASA installed from apt, it's going to put an ancient cfitsio library version in `/usr/lib/x86_64-linux-gnu/`, to get around this, you must export `LD_LIBRARY_PATH=/usr/local/lib/` in the shell so that Birli can find the correct library version. ### Logging You can enable additional logging on individual Rust modules by setting the `RUST_LOG` environment variable. For example: ```bash 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 ``` For more examples, see the [env_logger docs](https://docs.rs/env_logger/latest/env_logger/) The default log level in `info` ### Docker Couldn't get it working on your environment? You can always run Birli in Docker ```bash docker run mwatelescope/birli:latest -h ``` Want to open a shell within a fully provisioned Birli development environment? Easy! ```bash docker run -it --entrypoint /bin/bash --volume $PWD:/app mwatelescope/birli:latest ``` Note: This mounts the current directory to `/app` in the Docker image, meaning both of these systems share the same `target` folder. so if your host system is a different architecture than Docker, you may need to `cargo clean` each time you switch between these environments. You may also want to temporarily disable any linters or language servers that use ### Singularity on HPC ```bash # - 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} ``` see this gist for an example of [a Garrawarla SLURM job using Birli](https://gist.github.com/d3v-null/9ce233114ebb16dc18072303845257e5) ### Singularity on HPC (debug mode) This will give you much more information about any problem you're having with Birli, however the debug build is not optimised, and is much slower. ```bash # - 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 ``` then within this shell ```bash # - 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 ``` ## Usage `birli -h` ```txt USAGE: birli [OPTIONS] --metafits ... OPTIONS: --apply-di-cal 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 Override Phase centre from metafits (degrees) --pointing-centre Use pointing instead phase centre -V, --version Print version information INPUT: -m, --metafits Metadata file for the observation ... GPUBox files to process SELECTION: --no-sel-autos [WIP] Deselect autocorrelations --no-sel-flagged-ants [WIP] Deselect flagged antennas --provided-chan-ranges Only consider provided channels --sel-ants ... [WIP] Antenna to select --sel-chan-ranges Select separate channel ranges --sel-time Timestep index range (inclusive) to select RESOURCE LIMITS: --max-memory Estimate --time-chunk with GiB each chunk. --time-chunk Process observation in chunks of timesteps. FLAGGING: --flag-antennas ... Flag antenna indices --flag-autos Flag auto correlations --flag-coarse-chans ... Flag additional coarse chan indices --flag-dc Force flagging of DC centre chans --flag-edge-chans Flag fine chans on the ends of each coarse --flag-edge-width Flag bandwidth [kHz] at the ends of each coarse chan --flag-end Flag seconds before the last provided time --flag-end-steps Flag steps before the last provided --flag-fine-chans ... Flag fine chan indices in each coarse chan --flag-init Flag after first common time (quack time) --flag-init-steps Flag steps after first common time --flag-times ... 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 of PFB passband filter gains correction to apply [default: auto] [possible values: none, cotter, jake, auto] --van-vleck Apply Van Vleck corrections AVERAGING: --avg-freq-factor Average channels per averaged channel --avg-freq-res Frequency resolution of averaged data --avg-time-factor Average timesteps per averaged timestep --avg-time-res Time resolution of averaged data OUTPUT: -f, --flag-template