From 647d3cb20ffdb503361a721d333cbcc16daebd94 Mon Sep 17 00:00:00 2001 From: Greg Sleap Date: Sun, 28 Mar 2021 19:45:22 +0800 Subject: [PATCH] Updated README and install instructions and fixed many markdown issues --- CHANGELOG.md | 19 +++++++---- Cargo.toml | 2 +- README.md | 74 +++++++++++++++++++++++++++++-------------- tools/make_release.sh | 30 ------------------ 4 files changed, 63 insertions(+), 62 deletions(-) delete mode 100755 tools/make_release.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index ca7ae9c..4acaaa1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,16 +2,21 @@ Changes in each release are listed below. +## 0.6.3 28-Mar-2021 (Pre-release) + +* Refactored github actions for a more complete CI workflow with automated releases. +* Updated README and install instructions and fixed many markdown issues. + ## 0.6.2 25-Mar-2021 (Pre-release) * Modified MWA Legacy read code to produce cotter-compatible visibilities: - * mwalib differs from cotter: cotter produces 0+0j for XY on auto's, mwalib provides the values. - * mwalib and cotter differ from pyuvdata: mwalib/cotter visibilities are conjugated with respect to pyuvdata for cross correlations. + * mwalib differs from cotter: cotter produces 0+0j for XY on auto's, mwalib provides the values. + * mwalib and cotter differ from pyuvdata: mwalib/cotter visibilities are conjugated with respect to pyuvdata for cross correlations. * Added cotter validation data and test to ensure conversion code produces cotter equivalent visibilities (with the above exception). -* Provide rust-fitsio's cfitsio-static feature. +* Provide rust-fitsio's cfitsio-static feature. * Bumped fitsio dependency to 0.17.* and changed fitsio-sys to ^0 to ensure fitsio and mwalib use the same fitsio-sys version always. * Updated CI pipeline: bumped install of cfitsio to v3.49. -* Made error handling code a little lighter. +* Made error handling code a little lighter. ## 0.6.1 08-Mar-2021 (Pre-release) @@ -29,9 +34,9 @@ Changes in each release are listed below. * Major refactoring- this will break compatibility with previous mwalib versions. * mwalibContext top level object now split into: - * MetafitsContext (when you only provide a metafits file) - * CorrelatorContext (when you provide a metafits and 1 or more gpubox files) - * VoltageContext (when you provide a metafits and 1 or more voltage files) + * MetafitsContext (when you only provide a metafits file) + * CorrelatorContext (when you provide a metafits and 1 or more gpubox files) + * VoltageContext (when you provide a metafits and 1 or more voltage files) * FFI interfaces standardised, with struct based functions returning arrays of structs e.g. mwalib_antennas_get returns an array of antennas rather than a single instance. * Souce code is broken out into seperate folders with their own test.rs unit tests. * TimeStep struct now has GPS time as well as UNIX time. diff --git a/Cargo.toml b/Cargo.toml index 0ec8a19..9861e8b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "mwalib" -version = "0.6.2" +version = "0.6.3" homepage = "https://github.com/MWATelescope/mwalib" repository = "https://github.com/MWATelescope/mwalib" readme = "README.md" diff --git a/README.md b/README.md index 4928a33..4b7256b 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,21 @@ # mwalib + ![Run Tests](https://github.com/MWATelescope/mwalib/workflows/Run%20Tests/badge.svg) [![codecov](https://codecov.io/gh/MWATelescope/mwalib/branch/master/graph/badge.svg)](https://codecov.io/gh/MWATelescope/mwalib) -
-MWA library to read raw visibilities, voltages and metadata into a common structure. + +MWA library to read raw visibilities, voltages and metadata into a common structure. mwalib supports the existing "legacy" MWA correlator, as well as the in-development -"MWAX" correlator. This library strives to provide a single interface to work with -all incarnations of MWA metadatam correlator and voltage formats and abstract away +"MWAX" correlator. This library strives to provide a single interface to work with +all incarnations of MWA metadatam correlator and voltage formats and abstract away the nitty gritty details about reading MWA data. ## Usage via C + In the `examples` directory, see `build_c_examples.sh`, `mwalib-print-obs-context.c`, and `mwalib-sum-all-hdus.c` for examples of usage. ## Usage via Python + The primary Python interface to `mwalib` is [`pymwalib`](https://github.com/MWATelescope/pymwalib). @@ -20,21 +23,23 @@ There are also a couple of simple examples Python scripts here that use mwalib's `examples/mwalib-print-obs-context.py`, and `examples/mwalib-sum-all-hdus.py`. ## Usage in Rust + In the `examples` directory, see `mwalib-print-obs-context.rs` and `mwalib-print-obs-context.rs` for examples. Also run `cargo doc --open` to see the rendered documentation. ## Usage approach + - Populate a Context struct (`MetafitsContext`, `CorrelatorContext` or `VoltageContext`) `CorrelatorContext` - Use this when you have a metafits file and one or more gpubox files. This struct provides information about the correlator observation and provides access to a `MetafitsContext` for metadata, as well as methods for reading raw visibility data. - - `MetafitsContext` - an efficient way to get access to most of the observation metadata. Only requires that you pass a valid MWA metafits file. + + `MetafitsContext` - an efficient way to get access to most of the observation metadata. Only requires that you pass a valid MWA metafits file. `VoltageContext` - Use this when you have a metafits file and one or more recombined (or MWAX) voltage files. This struct provides information about the VCS observation and provides access to a `MetafitsContext` for metadata, and in an upcoming release- methods for reading raw voltage data. During creation of a `CorrelatorContext` or `MetafitsContext`, a number of checks are - performed on the metadata and gpubox/voltage files to ensure consistency. + performed on the metadata and gpubox/voltage files to ensure consistency. Once created, the context is primed for reading data. - Read raw data @@ -48,6 +53,7 @@ the rendered documentation. data in [fine_channel][baseline][polarisation][r][i] order. ## Concepts + - gpubox "batches" gpubox batches refers to the different gpubox outputs for the same @@ -68,7 +74,9 @@ the rendered documentation. number of antennas). ## Building From Source + You can build mwalib from source: + - Install rust `https://www.rust-lang.org/tools/install` @@ -76,7 +84,8 @@ You can build mwalib from source: - Install cfitsio If using a package manager install the `cfitsio-dev` package. If building from source ensure you build it with with `--enable-reentrant` option. - See: https://heasarc.gsfc.nasa.gov/fitsio/ + See: [FITSIO Homepage](https://heasarc.gsfc.nasa.gov/fitsio/) + Alternatively get the fitsio-sys crate to compile cfitsio for you by adding `--features cfitsio-static` to your cargo build command (below). - Compile the source @@ -98,33 +107,50 @@ You can build mwalib from source: - (Optional) If modifying the ffi functions, a `cargo build` will automatically regenerate mwalib.h ## Installation + As an alternative to building from source, we produce github releases whenever features or bug fixes are completed as tarballs. In the release you will find everything you need to use mwalib from C/C++/Python or any other language that can utilise shared libraries: -* lib/libmwalib.a (Statically compiled library) -* lib/libmwalib.so (Dynamic library) -* include/mwalib.h (C Header file) -* CHANGELOG.md (Change log for this and previous relases) -* LICENSE (License for using mwalib in your projects) -* LICENSE-cfitsio (Since libcfitsio is statically compiled into our static and dynamic libraries, we also include it's license) -NOTE: from release 0.3.2 onwards, libcfitsio is statically linked to mwalib in order to reduce issues with conflicting/incompatible versions of cfitsio. Therefore, there is no need for you to have cfitsio installed on your machine. +- lib/libmwalib.a (Statically compiled library) +- lib/libmwalib.so (Dynamic library for Linux) +- lib/libmwalib.dylib (Dynamic library for MacOS) +- include/mwalib.h (C Header file) +- CHANGELOG.md (Change log for this and previous relases) +- LICENSE (License for using mwalib in your projects) +- LICENSE-cfitsio (Since libcfitsio is statically compiled into our static and dynamic libraries, we also include it's license) + +NOTE: from release 0.3.2 onwards, libcfitsio is statically linked to mwalib in order to reduce issues with conflicting/incompatible versions of cfitsio. Therefore, there is no need for you to have cfitsio installed on your machine unless you are compiling from source. + +To install on most Linux x86/64 distributions, the following would be all that is needed: + +- Download release from mwalib [github releases](https://github.com/MWATelescope/mwalib/releases). (Where X.Y.Z is the current release version) -To install on a regular linux x86/64 distribution, the following would be all that is needed: -- Download release from mwalib [github releases](https://github.com/MWATelescope/mwalib/releases). - `wget "https://github.com/MWATelescope/mwalib/releases/download/v0.3.1/libmwalib-0.3.1-linux_x86_64.tar.gz" -O mwalib.tar.gz` + ```bash + wget "https://github.com/MWATelescope/mwalib/releases/download/vX.Y.Z/libmwalib-X.Y.Z-linux_x86_64.tar.gz" -O mwalib.tar.gz + ``` - Untar the tarball - `mkdir mwalib; tar xvf mwalib.tar.gz -C mwalib` + + ```bash + mkdir mwalib + tar xvf mwalib.tar.gz -C mwalib + ``` - Install - `sudo cp mwalib/lib/libmwalib.* /usr/local/lib` - `sudo cp mwalib/include/libmwalib.h /usr/local/include` + + ```bash + sudo cp mwalib/lib/libmwalib.* /usr/local/lib + sudo cp mwalib/include/libmwalib.h /usr/local/include + ``` - Register the library with ldconfig - `sudo ldconfig` + + ```bash + sudo ldconfig + ``` ## Example test output -``` -CorrelatorContext ( + +```CorrelatorContext ( Correlator version: v1 Legacy, MWA latitude: -26.703319405555554 degrees, diff --git a/tools/make_release.sh b/tools/make_release.sh deleted file mode 100755 index 252d60b..0000000 --- a/tools/make_release.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env bash - -# Must be run with the version number as the only param. e.g. -# ./make_release.sh 0.6.0 -if [[ $# -eq 0 ]] ; then - echo 'You must provide the release version number. E.g. ./make_release.sh 0.6.0' - exit 1 -fi - -echo "Making release... $1" -echo "Cleaning up previous release files..." -rm -rf ../target -rm -rf release -echo "Building mwalib..." -export MWALIB_LINK_STATIC_CFITSIO=1 -cargo build --release -echo "Packaging up mwalib..." -mkdir -p release -mkdir -p release/lib -mkdir -p release/include -cp ../target/release/libmwalib.a release/lib/. -cp ../target/release/libmwalib.so release/lib/. -cp ../LICENSE release/. -cp ../LICENSE-cfitsio release/. -cp ../CHANGELOG.md release/. -cp ../include/mwalib.h release/include/. -cd release -echo "Taring files..." -tar -czvf libmwalib-$1-linux_x86_64.tar.gz lib/libmwalib.a lib/libmwalib.so include/mwalib.h LICENSE LICENSE-cfitsio CHANGELOG.md -echo "Release complete!"