Code quality improvements.

Author: cgranade

src/Simulation/qdk_sim_rs/Cargo.toml

@@ -12,6 +12,9 @@ homepage = "https://github.com/microsoft/qsharp-runtime"
 repository = "https://github.com/microsoft/qsharp-runtime"
 readme = "README.md"
 
+# Verified with cargo-msrv.
+rust-version = "1.51.0"
+
 exclude = [
     # Exclude files specific to QDK build pipelines.
     "*.template", "*.csx", "*.ps1", "NuGet.Config", "drop",
@@ -86,6 +89,8 @@ built = "0.5.0"
 [dev-dependencies]
 assert-json-diff = "2.0.1"
 criterion = { version = "0.3", features = ['html_reports', 'csv_output'] }
+approx = { version = "0.5.1", features = ["num-complex"] }
+ndarray = { version = "0.15.4", features = ["approx"] }
 
 [[bench]]
 name = "c_api_benchmark"

src/Simulation/qdk_sim_rs/src/c_api.rs

@@ -1,12 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-// The following two attributes include the README.md for this module when
-// building docs (requires +nightly).
-// See https://github.com/rust-lang/rust/issues/82768#issuecomment-803935643
-// for discussion.
-#![cfg_attr(doc, feature(extended_key_value_attributes))]
-#![cfg_attr(doc, cfg_attr(doc, doc = include_str!("../docs/c-api.md")))]
+#![cfg_attr(all(), doc = include_str!("../docs/c-api.md"))]
 
 use crate::error::{QdkSimError, QdkSimError::*};
 use crate::{built_info, NoiseModel, Process, State};

src/Simulation/qdk_sim_rs/src/error.rs

@@ -27,14 +27,22 @@ pub enum QdkSimError {
     /// process.
     #[error("Channel acts on {expected} qubits, but was applied to an {actual}-qubit state.")]
     #[diagnostic(code(qdk_sim::process::wrong_n_qubits))]
-    WrongNumberOfQubits { expected: usize, actual: usize },
+    WrongNumberOfQubits {
+        /// The number of qubits that was expected, as given by the size of the
+        /// channel to be applied.
+        expected: usize,
+        /// The actual number of qubits for the given state.
+        actual: usize,
+    },
 
     /// Raised when a channel cannot be applied to a given state due to a
     /// mismatch between channel and state kinds.
     #[error("Unsupported quantum process variant {channel_variant} for applying to state variant {state_variant}.")]
     #[diagnostic(code(qdk_sim::process::unsupported_apply))]
     UnsupportedApply {
+        /// The enum variant of the channel to be applied.
         channel_variant: &'static str,
+        /// The enum variant of the state that the channel is to be applied to.
         state_variant: &'static str,
     },
 
@@ -77,7 +85,9 @@ pub enum QdkSimError {
     #[error("C API error: No simulator with ID {invalid_id} exists. Expected: {expected:?}.")]
     #[diagnostic(code(qdk_sim::c_api::invalid_sim))]
     NoSuchSimulator {
+        /// The invalid simulator id which caused this error.
         invalid_id: usize,
+        /// A list of valid simulator ids at the point when this error occured.
         expected: Vec<usize>,
     },
 
@@ -86,7 +96,10 @@ pub enum QdkSimError {
     #[error("C API error: UTF-8 error decoding {arg_name} argument: {source}")]
     #[diagnostic(code(qdk_sim::c_api::utf8))]
     InvalidUtf8InArgument {
+        /// The name of the argument containing invalid UTF-8 data.
         arg_name: String,
+
+        /// The underlying UTF-8 error that caused this error.
         #[source]
         source: Utf8Error,
     },

src/Simulation/qdk_sim_rs/src/lib.rs

@@ -1,12 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-// The following two attributes include the README.md for this crate when
-// building docs (requires +nightly).
-// See https://github.com/rust-lang/rust/issues/82768#issuecomment-803935643
-// for discussion.
-#![cfg_attr(doc, feature(extended_key_value_attributes))]
-#![cfg_attr(doc, cfg_attr(doc, doc = include_str!("../README.md")))]
+#![cfg_attr(all(), doc = include_str!("../README.md"))]
 // Set linting rules for documentation. We will stop the build on missing docs,
 // or docs with known broken links. We only enable this when all relevant
 // features are enabled, otherwise the docs build will fail on links to
@@ -17,7 +12,7 @@
 // that are missing an `# Example` section. Currently, that raises a lot of
 // warnings when building docs, but ideally we should make sure to address
 // warnings going forward by adding relevant examples.
-#![cfg_attr(doc, warn(missing_doc_code_examples))]
+#![cfg_attr(doc, warn(rustdoc::missing_doc_code_examples))]
 
 #[macro_use(array, s)]
 extern crate ndarray;

src/Simulation/qdk_sim_rs/src/linalg/decompositions/lu.rs

@@ -12,6 +12,7 @@ use crate::{
     linalg::array_ext::{RemoveAxisExt, ShapeExt},
 };
 
+/// Represents the output of an LU decomposition acting on a matrix.
 #[derive(Debug)]
 pub struct LU<A, S>
 where
@@ -22,13 +23,22 @@ where
     pub(self) pivots: Array1<usize>,
 }
 
+/// Represents types that represent matrices that are decomposable into lower-
+/// and upper-triangular parts.
 pub trait LUDecomposable {
+    /// The element type for the output matrices.
     type Elem: Scalar;
-    type Repr: Data<Elem = Self::Elem>;
+
+    /// Type of owned data in the output matrices.
     type OwnedRepr: Data + RawData<Elem = Self::Elem>;
+
+    /// The output type for LU decompositions on this type.
     type Output: LUDecomposition<Self::Elem, Self::OwnedRepr>;
+
+    /// The type used to represent errors in the decomposition.
     type Error;
 
+    /// Performs an LU decomposition on the given type.
     fn lu(&self) -> Result<Self::Output, Self::Error>;
 }
 
@@ -38,7 +48,6 @@ where
     A: Scalar,
 {
     type Elem = A;
-    type Repr = S;
     type OwnedRepr = OwnedRepr<A>;
     type Error = QdkSimError;
     type Output = LU<A, OwnedRepr<A>>;
@@ -51,7 +60,7 @@ where
             QdkSimError::CannotConvertElement("f64".to_string(), type_name::<A::Real>().to_string())
         })?;
 
-        let mut factors = &mut (*self).to_owned();
+        let factors = &mut (*self).to_owned();
         let mut pivots: Array1<_> = (0..n_rows).collect::<Vec<_>>().into();
 
         for j in 0..n_rows {
@@ -178,16 +187,84 @@ where
 
 #[cfg(test)]
 mod tests {
-    use ndarray::array;
+    use approx::assert_abs_diff_eq;
+    use cauchy::c64;
+    use ndarray::{array, Array2, OwnedRepr};
 
-    use crate::{error::QdkSimError, linalg::decompositions::LUDecomposable};
+    use crate::{
+        error::QdkSimError,
+        linalg::decompositions::{LUDecomposable, LU},
+    };
 
     #[test]
     fn lu_decomposition_works_f64() -> Result<(), QdkSimError> {
         let mtx = array![[6.0, 18.0, 3.0], [2.0, 12.0, 1.0], [4.0, 15.0, 3.0]];
-        // TODO: Actually write the test!
-        let lu = mtx.lu()?;
-        println!("{:?}", lu);
+        let lu: LU<f64, OwnedRepr<f64>> = mtx.lu()?;
+
+        // NB: This tests the internal structure of the LU decomposition, and
+        //     may validly fail if the algorithm above is modified.
+        let expected_factors = array![
+            [6.0, 18.0, 3.0],
+            [0.3333333333333333, 6.0, 0.0],
+            [0.6666666666666666, 0.5, 1.0],
+        ];
+        for (actual, expected) in lu.factors.iter().zip(expected_factors.iter()) {
+            assert_abs_diff_eq!(actual, expected, epsilon = 1e-6);
+        }
+
+        let expected_pivots = vec![0, 1, 2];
+        assert_eq!(lu.pivots.to_vec(), expected_pivots);
+        Ok(())
+    }
+
+    #[test]
+    fn lu_decomposition_works_c64() -> Result<(), QdkSimError> {
+        // In [1]: import scipy.linalg as la
+        // In [2]: la.lu([
+        //    ...:     [-1, 1j, -2],
+        //    ...:     [3, 0, -4j],
+        //    ...:     [-1, 5, -1]
+        //    ...: ])
+        // Out[2]: (array([[0., 0., 1.],
+        //                 [1., 0., 0.],
+        //                 [0., 1., 0.]]),
+        //          array([[ 1.        +0.j ,  0.        +0.j ,  0.        +0.j ],
+        //                 [-0.33333333+0.j ,  1.        +0.j ,  0.        +0.j ],
+        //                 [-0.33333333+0.j ,  0.        +0.2j,  1.        +0.j ]]),
+        //          array([[ 3.        +0.j        ,  0.        +0.j        ,
+        //                  -0.        -4.j        ],
+        //                 [ 0.        +0.j        ,  5.        +0.j        ,
+        //                  -1.        -1.33333333j],
+        //                 [ 0.        +0.j        ,  0.        +0.j        ,
+        //                  -2.26666667-1.13333333j]]))
+        let mtx: Array2<c64> = array![
+            [c64::new(-1.0, 0.0), c64::new(0.0, 1.0), c64::new(-2.0, 0.0)],
+            [c64::new(3.0, 0.0), c64::new(0.0, 0.0), c64::new(0.0, -4.0)],
+            [c64::new(-1.0, 0.0), c64::new(5.0, 0.0), c64::new(-1.0, 0.0)]
+        ];
+        let lu: LU<c64, OwnedRepr<c64>> = mtx.lu()?;
+
+        // NB: This tests the internal structure of the LU decomposition, and
+        //     may validly fail if the algorithm above is modified.
+        let expected_factors = array![
+            [c64::new(3.0, 0.0), c64::new(0.0, 0.0), c64::new(0.0, -4.0)],
+            [
+                c64::new(-0.3333333333333333, 0.0),
+                c64::new(5.0, 0.0),
+                c64::new(-1.0, -1.3333333333333333)
+            ],
+            [
+                c64::new(-0.3333333333333333, 0.0),
+                c64::new(0.0, 0.2),
+                c64::new(-2.26666667, -1.13333333)
+            ],
+        ];
+        for (actual, expected) in lu.factors.iter().zip(expected_factors.iter()) {
+            assert_abs_diff_eq!(actual, expected, epsilon = 1e-6);
+        }
+
+        let expected_pivots = vec![1, 2, 2];
+        assert_eq!(lu.pivots.to_vec(), expected_pivots);
         Ok(())
     }
 }

src/Simulation/qdk_sim_rs/src/linalg/decompositions/mod.rs

@@ -1,2 +1,4 @@
+//! Support for various decompositions used in linear algebra.
+
 mod lu;
 pub use lu::*;

src/Simulation/qdk_sim_rs/src/linalg/inv.rs

@@ -0,0 +1,90 @@
+use cauchy::Scalar;
+use ndarray::{Array1, Array2, Data, OwnedRepr, RawData};
+
+use crate::linalg::decompositions::{LUDecomposable, LUDecomposition};
+
+/// Types that support the matrix inverse $A^{-1}$.
+pub trait Inv {
+    /// Errors that can result from the [`inv`] method.
+    ///
+    /// [`inv`]: Inv::inv
+    type Error;
+    /// Type used to represent $A^{-1}$ when calling [`inv`].
+    ///
+    /// [`inv`]: Inv::inv
+    type Output;
+
+    /// Computes the inverse of a given matrix.
+    fn inv(&self) -> Result<Self::Output, Self::Error>;
+}
+
+impl<M, A, E> Inv for M
+where
+    M: LUDecomposable<Elem = A, OwnedRepr = OwnedRepr<A>, Error = E>,
+    A: Scalar,
+    // TODO: Allow decomposables and decompositions to have different errors.
+    <M as LUDecomposable>::Output: LUDecomposition<A, OwnedRepr<A>, Error = E>,
+{
+    type Error = M::Error;
+    type Output =
+        <<M as LUDecomposable>::Output as LUDecomposition<A, OwnedRepr<A>>>::MatrixSolution;
+
+    fn inv(&self) -> Result<Self::Output, Self::Error> {
+        // TODO: Check determinant here.
+        let lu = self.lu()?;
+        // TODO: Change to use Identity trait.
+        let id_mtx = Array2::from_diag(&Array1::ones(lu.order()));
+        lu.solve_matrix(&id_mtx)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use approx::assert_abs_diff_eq;
+    use cauchy::c64;
+    use ndarray::array;
+    use num_traits::Zero;
+
+    use crate::{error::QdkSimError, linalg::Inv};
+
+    #[test]
+    fn inv_works_f64() -> Result<(), QdkSimError> {
+        let mtx = array![[6.0, 18.0, 3.0], [2.0, 12.0, 1.0], [4.0, 15.0, 3.0]];
+        // TODO: Actually write the test!
+        let inv = mtx.inv()?;
+        println!("{:?}", inv);
+        Ok(())
+    }
+
+    #[test]
+    fn inv_works_c64() -> Result<(), QdkSimError> {
+        let mtx = array![
+            [c64::zero(), c64::new(0.0, 1.0), c64::new(2.0, 0.0)],
+            [c64::new(0.0, 3.0), c64::new(4.0, 0.0), c64::new(0.0, 5.0)],
+            [c64::new(6.0, 0.0), c64::new(0.0, 7.0), c64::new(8.0, 0.0)]
+        ];
+        let inv = mtx.inv()?;
+        let expected_inv = array![
+            [
+                c64::new(-0.69791667, 0.),
+                c64::new(0., -0.0625),
+                c64::new(0.13541667, 0.)
+            ],
+            [
+                c64::new(0., -0.0625),
+                c64::new(0.125, 0.),
+                c64::new(0., -0.0625)
+            ],
+            [
+                c64::new(0.46875, 0.),
+                c64::new(0., -0.0625),
+                c64::new(-0.03125, 0.)
+            ],
+        ];
+
+        for (actual, expected) in inv.iter().zip(expected_inv.iter()) {
+            assert_abs_diff_eq!(actual, expected, epsilon = 1e-6);
+        }
+        Ok(())
+    }
+}

src/Simulation/qdk_sim_rs/src/linalg/mod.rs

@@ -14,6 +14,9 @@ use crate::{common_matrices::nq_eye, C64};
 mod tensor;
 pub use tensor::*;
 
+mod inv;
+pub use inv::*;
+
 pub mod decompositions;
 
 // Define private modules as well.

src/Simulation/qdk_sim_rs/src/tableau.rs

@@ -3,7 +3,10 @@
 
 use std::fmt::Display;
 
-use crate::utils::{set_row_to_row_sum, set_vec_to_row_sum, swap_columns};
+use crate::{
+    error::QdkSimError,
+    utils::{set_row_to_row_sum, set_vec_to_row_sum, swap_columns},
+};
 use ndarray::{s, Array, Array1, Array2};
 use serde::{Deserialize, Serialize};
 
@@ -91,16 +94,18 @@ impl Tableau {
     ///
     /// If the assertion would pass, `Ok(())` is returned, otherwise an [`Err`]
     /// describing the assertion failure is returned.
-    pub fn assert_meas(&self, idx_target: usize, expected: bool) -> Result<(), String> {
-        let actual = self.determinstic_result(idx_target).ok_or(format!(
-            "Expected {}, but measurement result would be random.",
-            expected
-        ))?;
+    pub fn assert_meas(&self, idx_target: usize, expected: bool) -> Result<(), QdkSimError> {
+        let actual = self
+            .determinstic_result(idx_target)
+            .ok_or(QdkSimError::MiscError(format!(
+                "Expected {}, but measurement result would be random.",
+                expected
+            )))?;
         if actual != expected {
-            Err(format!(
+            Err(QdkSimError::MiscError(format!(
                 "Expected {}, but measurement result would actually be {}.",
                 expected, actual
-            ))
+            )))
         } else {
             Ok(())
         }

src/Simulation/qdk_sim_rs/tests/chp_simulation_tests.rs

@@ -1,10 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-use qdk_sim::{Pauli, Process, State, Tableau};
+use qdk_sim::{error::QdkSimError, Pauli, Process, State, Tableau};
 
 #[test]
-fn pauli_channel_applies_correctly() -> Result<(), String> {
+fn pauli_channel_applies_correctly() -> Result<(), QdkSimError> {
     let x = Process::new_pauli_channel(Pauli::X);
     let state = State::new_stabilizer(1);
     let output_state = x.apply(&state)?;