Changed voltage data format from [u8] to [i8]. Added python docstrings

MWATelescope · Sep 15, 2023 · 35fabdf · 35fabdf
1 parent 93a91c3
commit 35fabdf
Show file tree

Hide file tree

Showing 17 changed files with 795 additions and 553 deletions.
diff --git a/.gitignore b/.gitignore
@@ -18,3 +18,4 @@ ccov.zip
 /test_files/1101503312_vcs/*.dat
 /test_files/1370755832_mwax_vcs_os/*.sub
 .python-version
+__pycache__
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 Changes in each release are listed below.
 
+## 1.1.0 13-Sep-2023
+
+* BREAKING CHANGE: `VoltageContext::read_second` and `read_file` now return signed bytes (`i8`) instead of unsigned (`u8`). This is a very breaking change for existing clients using these functions, but it is necessary to return the correct interpretation of the bytes to the client.
+* Python classes and methods now have docstrings. 
+
 ## 1.0.1 12-Sep-2023
 
 * Fixed various uncaught clippy lints.

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mwalib"
-version = "1.0.1"
+version = "1.1.0"
 homepage = "https://github.com/MWATelescope/mwalib"
 repository = "https://github.com/MWATelescope/mwalib"
 readme = "README.md"

diff --git a/README.md b/README.md
@@ -31,11 +31,11 @@ mwalib provides the following binaries and implementations with releases startin
 | Filename  | Purpose  |
 |-----------|----------|
 |mwalib-vX.X.X-linux-x86-64.tar.gz | Linux "C"/"C++" compatible library - includes ".h" and "libmwalib.a" and "libmwalib.so" library files. |
-|mwalib-vX.X.X-linux-python-x86-64.tar.gz | Linux compatible Python wheel. |
+|mwalib-vX.X.X-linux-python-x86-64.tar.gz | Linux compatible Python wheels. |
 |mwalib-vX.X.X-macosx-x86-64.tar.gz | MacOSX "C"/"C++" compatible library - includes ".h" and "libmwalib.a" and "libmwalib.so" library files. |
-|mwalib-vX.X.X-macosx-python-x86-64.tar.gz | MacOSX compatible Python wheel. |
+|mwalib-vX.X.X-macosx-python-x86-64.tar.gz | MacOSX compatible Python wheels. |
 
-NOTE: for both Linux, more optimised builds are named with a v2 and v3 after the "x86-64". These suffixes denote that the compilation was optimised for the specified [CPU microarchitecture levels](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels), with "x86-64" being the most compatible with the very oldest CPUs. If you have a CPU which was manufactured after 2008 you are safe with x86-64-v2, and if it is newer than 2015 then you are safe using x86-64-v3.
+NOTE: for Linux, more optimised builds are named with a v2 and v3 after the "x86-64". These suffixes denote that the compilation was optimised for the specified [CPU microarchitecture levels](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels), with "x86-64" being the most compatible with the very oldest CPUs. If you have a CPU which was manufactured after 2008 you are probably safe with x86-64-v2, and if it is newer than 2015 then you are safe using x86-64-v3.
 
 ----
 For installation instructions, concepts and usage info, please see the [`mwalib GitHub Wiki`](https://github.com/MWATelescope/mwalib/wiki).

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,5 @@
 [project]
 name = "mwalib"
-version = "1.0.1"
 description = "A library to work with raw data and metadata from the Murchison Widefield Array (MWA)"
 readme = "README.md"
 requires-python = ">=3.7"

diff --git a/src/correlator_context/mod.rs b/src/correlator_context/mod.rs
@@ -16,11 +16,14 @@ use crate::metafits_context::*;
 use crate::timestep::*;
 use crate::*;
 
+#[cfg(feature = "python")]
+mod python;
+
 #[cfg(test)]
 mod test;
 
 ///
-/// `mwalib` correlator observation context. This represents the basic metadata for a correlator observation.
+/// This represents the basic metadata and methods for an MWA correlator observation.
 ///
 #[derive(Debug)]
 #[cfg_attr(feature = "python", pyo3::pyclass(get_all))]
@@ -134,7 +137,7 @@ impl CorrelatorContext {
     ///
     /// * Result containing a populated CorrelatorContext object if Ok.
     ///
-    ///
+    ///    
     pub fn new<P: AsRef<Path>, P2: AsRef<Path>>(
         metafits_filename: P,
         gpubox_filenames: &[P2],
@@ -418,10 +421,10 @@ impl CorrelatorContext {
     /// # Arguments
     ///
     /// * `corr_timestep_index` - index within the CorrelatorContext timestep array for the desired timestep. This corresponds
-    ///                      to the element within mwalibContext.timesteps.
+    ///                      to the element within CorrelatorContext.timesteps.
     ///
     /// * `corr_coarse_chan_index` - index within the CorrelatorContext coarse_chan array for the desired coarse channel. This corresponds
-    ///                      to the element within mwalibContext.coarse_chans.
+    ///                      to the element within CorrelatorContext.coarse_chans.
     ///
     ///
     /// # Returns
@@ -452,10 +455,10 @@ impl CorrelatorContext {
     /// # Arguments
     ///
     /// * `corr_timestep_index` - index within the CorrelatorContext timestep array for the desired timestep. This corresponds
-    ///                      to the element within mwalibContext.timesteps.
+    ///                      to the element within CorrelatorContext.timesteps.
     ///
     /// * `corr_coarse_chan_index` - index within the CorrelatorContext coarse_chan array for the desired coarse channel. This corresponds
-    ///                      to the element within mwalibContext.coarse_chans.
+    ///                      to the element within CorrelatorContext.coarse_chans.
     ///
     ///
     /// # Returns
@@ -486,10 +489,10 @@ impl CorrelatorContext {
     /// # Arguments
     ///
     /// * `corr_timestep_index` - index within the CorrelatorContext timestep array for the desired timestep. This corresponds
-    ///                      to the element within mwalibContext.timesteps.
+    ///                      to the element within CorrelatorContext.timesteps.
     ///
     /// * `corr_coarse_chan_index` - index within the CorrelatorContext coarse_chan array for the desired coarse channel. This corresponds
-    ///                      to the element within mwalibContext.coarse_chans.
+    ///                      to the element within CorrelatorContext.coarse_chans.
     ///
     ///
     /// # Returns
@@ -987,116 +990,3 @@ impl fmt::Display for CorrelatorContext {
         )
     }
 }
-
-#[cfg(feature = "python")]
-use ndarray::Array2;
-#[cfg(feature = "python")]
-use ndarray::Array3;
-#[cfg(feature = "python")]
-use numpy::PyArray2;
-#[cfg(feature = "python")]
-use numpy::PyArray3;
-#[cfg(feature = "python")]
-use pyo3::prelude::*;
-
-#[cfg(feature = "python")]
-#[pymethods]
-impl CorrelatorContext {
-    #[new]
-    fn pyo3_new(metafits_filename: PyObject, gpubox_filenames: Vec<PyObject>) -> PyResult<Self> {
-        // Convert the gpubox filenames.
-        let gpubox_filenames: Vec<String> = gpubox_filenames
-            .into_iter()
-            .map(|g| g.to_string())
-            .collect();
-        let c = CorrelatorContext::new(metafits_filename.to_string(), &gpubox_filenames)?;
-        Ok(c)
-    }
-
-    #[pyo3(name = "get_fine_chan_freqs_hz_array")]
-    fn pyo3_get_fine_chan_freqs_hz_array(&self, corr_coarse_chan_indices: Vec<usize>) -> Vec<f64> {
-        self.get_fine_chan_freqs_hz_array(&corr_coarse_chan_indices)
-    }
-
-    #[pyo3(name = "read_by_baseline")]
-    fn pyo3_read_by_baseline<'py>(
-        &self,
-        py: Python<'py>,
-        corr_timestep_index: usize,
-        corr_coarse_chan_index: usize,
-    ) -> PyResult<&'py PyArray3<f32>> {
-        // Use the existing Rust method.
-        let data = self.read_by_baseline(corr_timestep_index, corr_coarse_chan_index)?;
-        // Convert the vector to a 3D array (this is free).
-        let data = Array3::from_shape_vec(
-            (
-                self.metafits_context.num_baselines,
-                self.metafits_context.num_corr_fine_chans_per_coarse,
-                8,
-            ),
-            data,
-        )
-        .expect("shape of data should match expected dimensions (num_baselines, num_corr_fine_chans_per_coarse, visibility_pols * 2)");
-        // Convert to a numpy array.
-        let data = PyArray3::from_owned_array(py, data);
-        Ok(data)
-    }
-
-    #[pyo3(name = "read_by_frequency")]
-    fn pyo3_read_by_frequency<'py>(
-        &self,
-        py: Python<'py>,
-        corr_timestep_index: usize,
-        corr_coarse_chan_index: usize,
-    ) -> PyResult<&'py PyArray3<f32>> {
-        // Use the existing Rust method.
-        let data = self.read_by_frequency(corr_timestep_index, corr_coarse_chan_index)?;
-        // Convert the vector to a 3D array (this is free).
-        let data = Array3::from_shape_vec(
-            (
-                self.metafits_context.num_corr_fine_chans_per_coarse,
-                self.metafits_context.num_baselines,
-                8,
-            ),
-            data,
-        )
-        .expect("shape of data should match expected dimensions (num_corr_fine_chans_per_coarse, num_baselines, visibility_pols * 2)");
-        // Convert to a numpy array.
-        let data = PyArray3::from_owned_array(py, data);
-        Ok(data)
-    }
-
-    #[pyo3(name = "read_weights_by_baseline")]
-    fn pyo3_read_weights_by_baseline<'py>(
-        &self,
-        py: Python<'py>,
-        corr_timestep_index: usize,
-        corr_coarse_chan_index: usize,
-    ) -> PyResult<&'py PyArray2<f32>> {
-        // Use the existing Rust method.
-        let data = self.read_weights_by_baseline(corr_timestep_index, corr_coarse_chan_index)?;
-        // Convert the vector to a 3D array (this is free).
-        let data = Array2::from_shape_vec(
-            (
-                self.metafits_context.num_baselines,
-                self.metafits_context.num_visibility_pols,
-            ),
-            data,
-        )
-        .expect("shape of data should match expected dimensions (num_baselines, visibility_pols)");
-        // Convert to a numpy array.
-        let data = PyArray2::from_owned_array(py, data);
-        Ok(data)
-    }
-
-    // https://pyo3.rs/v0.17.3/class/object.html#string-representations
-    fn __repr__(&self) -> String {
-        format!("{}", self)
-    }
-
-    fn __enter__(slf: Py<Self>) -> Py<Self> {
-        slf
-    }
-
-    fn __exit__(&mut self, _exc_type: &PyAny, _exc_value: &PyAny, _traceback: &PyAny) {}
-}