Fix clippy lints and add a little more docs.

We don't mind that "FEEBeam" has multiple consecutive capital letters.
Link an MWA wiki page that details the M&C order and change the
module-level documentation syntax to the recommended format (i.e. //!).

Also hide the fee error module; this just makes things slightly simpler.
Finally don't push some directories to crates.io.

Cargo.toml

@@ -10,6 +10,7 @@ readme = "README.md"
 description = "Primary beam code for the Murchison Widefield Array (MWA) radio telescope."
 repository = "https://github.com/MWATelescope/mwa_hyperbeam"
 homepage = "https://github.com/MWATelescope/mwa_hyperbeam"
+exclude = [".github/*"]
 
 # Make a rust library, as well as static and C-compatible dynamic libraries
 # available as "libmwa_hyperbeam.a" and "libmwa_hyperbeam.so".

README.md

@@ -107,7 +107,7 @@ the `hdf5-static` feature:
 
 ## Comparing with other FEE beam codes
 Below is a table comparing other implementations of the FEE beam code. All
-benchmarks were done with unique azimuth and zenith angle directionss, and all
+benchmarks were done with unique azimuth and zenith angle directions, and all
 on the same system. The CPU is a Ryzen 9 3900X, which has 12 cores and SMT (24
 threads). All benchmarks were done in serial, unless indicated by "parallel".
 Python times were taken by running `time.time()` before and after the

benches/bench.rs

@@ -2,10 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Benchmarks. FEE beam code benchmarks rely on the HDF5 file being present in the
-project's root directory.
- */
+//! Benchmarks. FEE beam code benchmarks rely on the HDF5 file being present in
+//! the project's root directory.
 
 use criterion::*;
 use rayon::prelude::*;

examples/beam_calcs.c

@@ -24,6 +24,9 @@ int main(int argc, char *argv[]) {
     // Set up the direction and pointing to test.
     double az = 45.0 * M_PI / 180.0;
     double za = 80.0 * M_PI / 180.0;
+    // Delays and amps correspond to dipoles in the "M&C order". See
+    // https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139) for
+    // more info.
     unsigned delays[16] = {3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0};
     double amps[16] = {1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1};
     int freq_hz = 51200000;

examples/beam_calcs.py

@@ -21,6 +21,9 @@
 az = np.linspace(0, 0.9 * np.pi, n)
 za = np.linspace(0.1, 0.9 * np.pi / 2, n)
 freq = 167000000
+# Delays and amps correspond to dipoles in the "M&C order". See
+# https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139) for more
+# info.
 delays = [0] * 16
 amps = [1.0] * 16
 norm_to_zenith = True

examples/beam_calcs.rs

@@ -2,17 +2,15 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Example code using hyperbeam with Rust.
-
-Build and run with something like:
-cargo run --release --example beam_calcs -- mwa_full_embedded_element_pattern.h5 10000
-
-If you want to use hyperbeam in your own Rust crate, then check out the latest
-version on crates.io:
-
-https://crates.io/crates/mwa_hyperbeam
- */
+//! Example code using hyperbeam with Rust.
+//!
+//! Build and run with something like:
+//! `cargo run --release --example beam_calcs -- mwa_full_embedded_element_pattern.h5 10000`
+//!
+//! If you want to use hyperbeam in your own Rust crate, then check out the latest
+//! version on crates.io:
+//!
+//! https://crates.io/crates/mwa_hyperbeam
 
 use mwa_hyperbeam::fee::FEEBeam;
 use structopt::*;
@@ -48,6 +46,9 @@ fn main() -> Result<(), anyhow::Error> {
         za.push(0.1 + 0.9 * std::f64::consts::PI / 2.0 * i as f64 / opts.num_directions as f64);
     }
     let freq_hz = 51200000;
+    // Delays and amps correspond to dipoles in the "M&C order". See
+    // https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139) for
+    // more info.
     let delays = vec![0; 16];
     let amps = vec![1.0; 16];
     let norm_to_zenith = false;

examples/beam_calcs_many.c

@@ -29,6 +29,9 @@ int main(int argc, char *argv[]) {
         az[i] = 45.0 * M_PI / 180.0;
         za[i] = 10.0 * M_PI / 180.0;
     }
+    // Delays and amps correspond to dipoles in the "M&C order". See
+    // https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139) for
+    // more info.
     unsigned delays[16] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
     double amps[16] = {1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1};
     int freq_hz = 51200000;

examples/beam_calcs_many_omp.c

@@ -31,6 +31,9 @@ int main(int argc, char *argv[]) {
         az[i] = coord_rad;
         za[i] = coord_rad;
     }
+    // Delays and amps correspond to dipoles in the "M&C order". See
+    // https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139) for
+    // more info.
     unsigned delays[16] = {3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0};
     double amps[16] = {1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1};
     int freq_hz = 51200000;

src/constants.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Useful constants.
- */
+//! Useful constants.
 
 use crate::types::{c64, Jones};
 

src/factorial.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Pre-calculated factorials from boost.
- */
+//! Pre-calculated factorials from boost.
 
 /* The following C++ program gives the values:
 

src/fee/error.rs

@@ -2,13 +2,12 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Errors associated with the FEE beam.
- */
+//! Errors associated with the FEE beam.
 
 use thiserror::Error;
 
 #[derive(Error, Debug)]
+#[allow(clippy::upper_case_acronyms)]
 pub enum InitFEEBeamError {
     #[error("One of HDF5 datasets started with 'X_'; what's wrong with your file?")]
     MissingDipole,
@@ -37,6 +36,7 @@ pub enum InitFEEBeamError {
 }
 
 #[derive(Error, Debug)]
+#[allow(clippy::upper_case_acronyms)]
 pub enum FEEBeamError {
     #[error("Expected {expected} dipole coefficients, but got {got}")]
     S1S2CountMismatch { expected: usize, got: usize },

src/fee/mod.rs

@@ -2,12 +2,10 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Code to implement the MWA Fully Embedded Element (FEE) beam, a.k.a. "the 2016
-beam".
- */
+//! Code to implement the MWA Fully Embedded Element (FEE) beam, a.k.a. "the
+//! 2016 beam".
 
-pub mod error;
+mod error;
 mod types;
 
 use std::f64::consts::{FRAC_PI_2, TAU};
@@ -24,6 +22,7 @@ pub use error::{FEEBeamError, InitFEEBeamError};
 use types::*;
 
 /// The main struct to be used for calculating Jones matrices.
+#[allow(clippy::upper_case_acronyms)]
 pub struct FEEBeam {
     /// The `hdf5::File` struct associated with the opened HDF5 file. It is
     /// behind a `Mutex` to prevent parallel usage of the file.
@@ -363,9 +362,11 @@ impl FEEBeam {
 
     /// Calculate the Jones matrix for a given direction and pointing.
     ///
-    /// `delays` and `amps` apply to each dipole in a given MWA tile (in the M&C
-    /// order), and *must* have 16 elements. `amps` being dipole gains (usually
-    /// 1 or 0), not digital gains.
+    /// `delays` and `amps` apply to each dipole in a given MWA tile, and *must*
+    /// have 16 elements (each corresponds to an MWA dipole in a tile, in the
+    /// M&C order; see
+    /// <https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139>.
+    /// `amps` being dipole gains (usually 1 or 0), not digital gains.
     pub fn calc_jones(
         &self,
         az_rad: f64,
@@ -407,7 +408,9 @@ impl FEEBeam {
     ///
     /// This is basically a wrapper around `calc_jones`; this function
     /// calculates the Jones matrices in parallel. `delays` and `amps` *must*
-    /// have 16 elements.
+    /// have 16 elements (each corresponds to an MWA dipole in a tile, in the
+    /// M&C order; see
+    /// <https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139>.
     pub fn calc_jones_array(
         &self,
         az_rad: &[f64],

src/fee/types.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Helper types for the FEE beam.
- */
+//! Helper types for the FEE beam.
 
 use dashmap::DashMap;
 

src/ffi.rs

@@ -2,10 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Code for allowing other languages to talk to this Rust library. See the examples
-directory for usage.
- */
+//! Code for allowing other languages to talk to this Rust library. See the
+//! examples directory for usage.
 
 // TODO: Error handling.
 
@@ -47,10 +45,16 @@ pub unsafe extern "C" fn new_fee_beam_from_env() -> *mut FEEBeam {
 
 /// Get the beam response Jones matrix for the given direction and pointing.
 ///
+/// `delays` and `amps` apply to each dipole in a given MWA tile, and *must*
+/// have 16 elements (each corresponds to an MWA dipole in a tile, in the M&C
+/// order; see
+/// https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139). `amps`
+/// being dipole gains (usually 1 or 0), not digital gains.
+///
 /// Note the return type (*double); we can't pass complex numbers across the FFI
-/// boundary, so the real and imaginary components are unpacked into
-/// doubles. The output contains 8 doubles, where the j00 is the first pair, j01
-/// is the second pair, etc.
+/// boundary, so the real and imaginary components are unpacked into doubles.
+/// The output contains 8 doubles, where the j00 is the first pair, j01 is the
+/// second pair, etc.
 ///
 /// # Arguments
 ///
@@ -59,15 +63,15 @@ pub unsafe extern "C" fn new_fee_beam_from_env() -> *mut FEEBeam {
 /// `az_rad` - The azimuth coordinate of the beam in radians
 /// `za_rad` - The zenith angle coordinate of the beam in radians
 /// `freq_hz` - The frequency used for the beam response in Hertz
-/// `delays` - A pointer to a 16-element array of dipole delays for an MWA tile.
-/// `amps` - A pointer to a 16-element array of dipole gains for an MWA tile.
+/// `delays` - A pointer to a 16-element array of dipole delays for an MWA tile
+/// `amps` - A pointer to a 16-element array of dipole gains for an MWA tile
 /// `norm_to_zenith` - A boolean indicating whether the beam response should be
 /// normalised with respect to zenith.
 ///
 /// # Returns
 ///
 /// * A pointer to an 8-element Jones matrix array on the heap. This array may
-/// be freed by the caller.
+///   be freed by the caller.
 ///
 #[no_mangle]
 pub unsafe extern "C" fn calc_jones(
@@ -103,9 +107,17 @@ pub unsafe extern "C" fn calc_jones(
 
 /// Get the beam response Jones matrix for several az/za directions for the
 /// given pointing. The Jones matrix elements for each direction are put into a
-/// single array. As there are 8 floats per Jones matrix, there are 8 *
-/// `num_azza` floats in the array. Rust will calculate the Jones matrices
-/// in parallel. See the documentation for `calc_jones` for more info.
+/// single array.
+///
+/// `delays` and `amps` apply to each dipole in a given MWA tile, and *must*
+/// have 16 elements (each corresponds to an MWA dipole in a tile, in the M&C
+/// order; see
+/// https://wiki.mwatelescope.org/pages/viewpage.action?pageId=48005139). `amps`
+/// being dipole gains (usually 1 or 0), not digital gains.
+///
+/// As there are 8 floats per Jones matrix, there are 8 * `num_azza` floats in
+/// the array. Rust will calculate the Jones matrices in parallel. See the
+/// documentation for `calc_jones` for more info.
 #[no_mangle]
 pub unsafe extern "C" fn calc_jones_array(
     fee_beam: *mut FEEBeam,

src/legendre.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Code for Legendre polynomials.
- */
+//! Code for Legendre polynomials.
 
 /// Evaluates the Legendre polynomial Pm(n,m) at x. x must satisfy |x| <= 1.
 ///

src/lib.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Primary beam code for the Murchison Widefield Array.
- */
+//! Primary beam code for the Murchison Widefield Array.
 
 mod constants;
 mod factorial;

src/python/fee.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Python interface to hyperbeam FEE code.
- */
+//! Python interface to hyperbeam FEE code.
 
 use numpy::*;
 use pyo3::create_exception;
@@ -28,6 +26,7 @@ impl std::convert::From<InitFEEBeamError> for PyErr {
 /// A Python class interfacing with the hyperbeam code written in Rust.
 #[pyclass]
 #[text_signature = "(hdf5_file)"]
+#[allow(clippy::upper_case_acronyms)]
 struct FEEBeam {
     beam: FEEBeamRust,
 }

src/python/mod.rs

@@ -2,8 +2,6 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Python interface to hyperbeam.
- */
+//! Python interface to hyperbeam.
 
 mod fee;

src/types.rs

@@ -2,9 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-/*!
-Generic types.
- */
+//! Generic types.
 
 use std::collections::hash_map::DefaultHasher;
 use std::hash::{Hash, Hasher};