Added more docs, ported feature docs to document-features.

Author: cgranade

src/Simulation/qdk_sim_rs/Cargo.toml

@@ -32,15 +32,20 @@ crate-type = ["rlib", "staticlib", "cdylib"]
 # Optional build-time features: we use this to create Python and WASM bindings.
 [features]
 default = []
+
+## Ensures that the crate is compatible with usage from WebAssembly.
 wasm = ["web-sys"]
+
 # When Python bindings are enabled, we also need the pyo3 dependency.
+## Enables Python bindings for this crate.
 python = ["pyo3", "numpy"]
 
 # Enable LaTeX on docs.rs.
 # See https://stackoverflow.com/a/54573800/267841 and
 # https://github.com/rust-num/num/pull/226/files for why this works.
 [package.metadata.docs.rs]
 rustdoc-args = [ "--html-in-header", "docs-includes/header.html", "--html-after-content", "docs-includes/after.html" ]
+features = ["document-features"]
 
 
 [profile.release]
@@ -82,6 +87,10 @@ thiserror = "1.0.30"
 miette = "4.3.0"
 anyhow = "1.0.56"
 
+# We use document-features to automatically generate feature documentation from
+# Cargo.toml, following the example at 
+document-features = { version = "0.2", optional = true }
+
 [build-dependencies]
 built = "0.5.0"
 

src/Simulation/qdk_sim_rs/README.md

@@ -4,7 +4,7 @@
          To generate and view the documentation for this crate locally, please
          run:
 
-         $ cargo +nightly doc --features python --open
+         $ cargo doc --features python,document-features --open
 -->
 
 # Quantum Development Kit Preview Simulators
@@ -28,11 +28,6 @@ The [`c_api`] module allows for using the simulation functionality in this crate
 
 Similarly, the [`python`] module allows exposing data structures in this crate to Python programs.
 
-## Cargo Features
-
-- **`python`**: Enables Python bindings for this crate.
-- **`wasm`**: Ensures that the crate is compatible with usage from WebAssembly.
-
 ## Representing quantum systems
 
 This crate provides several different data structures for representing quantum systems in a variety of different conventions:
@@ -148,3 +143,5 @@ TODO
 - Stabilizer simulation not yet exposed via C API.
 - Test and microbenchmark coverage still incomplete.
 - Too many APIs `panic!` or `unwrap`, and need replaced with `Result` returns instead.
+
+# Crate features

src/Simulation/qdk_sim_rs/src/lib.rs

@@ -2,6 +2,10 @@
 // Licensed under the MIT License.
 
 #![cfg_attr(all(), doc = include_str!("../README.md"))]
+#![cfg_attr(
+    feature = "document-features",
+    cfg_attr(doc, doc = ::document_features::document_features!())
+)]
 // 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

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

@@ -36,7 +36,7 @@ pub trait LUDecomposable {
     type Output: LUDecomposition<Self::Elem, Self::OwnedRepr>;
 
     /// The type used to represent errors in the decomposition.
-    type Error;
+    type Error: std::error::Error;
 
     /// Performs an LU decomposition on the given type.
     fn lu(&self) -> Result<Self::Output, Self::Error>;
@@ -108,19 +108,41 @@ where
     }
 }
 
+/// Represents the result of decomposing a square matrix $A$ into lower- and
+/// upper-triangular components $L$ and $U$, respectively.
 pub trait LUDecomposition<A, S>
 where
     S: Data<Elem = A>,
     A: Scalar,
 {
+    /// The type used to represent errors in using this decomposition to solve
+    /// matrix equations.
     type Error: std::error::Error;
+
+    /// The type resulting from using this decomposition to solve problems
+    /// of the form $A\vec{x} = \vec{y}$.
     type VectorSolution;
+
+    /// The type resulting from using this decomposition to solve problems
+    /// of the form $AX = Y$.
     type MatrixSolution;
 
+    /// The size $n$ of the matrix whose decomposition is represented. In
+    /// particular, $L\Pi U$ is taken to be an $n \times n$ matrix, where $L$
+    /// and $U$ are the lower- and upper-triangular factors, and where $\Pi$
+    /// is a permutation matrix.
     fn order(&self) -> usize;
 
     // TODO: Change signature to be in-place.
+    /// Uses this decomposition to solve an equation of the form
+    /// $A\vec{x} = \vec{y}$ for $\vec{x}$ given $\vec{y}$, where $A$ is
+    /// implicitly represented by this decomposition.
     fn solve_vector(&self, rhs: &ArrayBase<S, Ix1>) -> Result<Self::VectorSolution, Self::Error>;
+
+    // TODO: Change signature to be in-place.
+    /// Uses this decomposition to solve an equation of the form
+    /// $AX = Y$ for $X$ given $Y$, where $A$ is
+    /// implicitly represented by this decomposition.
     fn solve_matrix(&self, rhs: &ArrayBase<S, Ix2>) -> Result<Self::MatrixSolution, Self::Error>;
 }