From a7ccec56b9b787f426dae44b8be78227c501bc8a Mon Sep 17 00:00:00 2001 From: Cassandra Granade Date: Thu, 31 Mar 2022 16:50:23 -0700 Subject: [PATCH] Added more docs, ported feature docs to document-features. --- src/Simulation/qdk_sim_rs/Cargo.toml | 9 +++++++ src/Simulation/qdk_sim_rs/README.md | 9 +++---- src/Simulation/qdk_sim_rs/src/lib.rs | 4 ++++ .../src/linalg/decompositions/lu.rs | 24 ++++++++++++++++++- 4 files changed, 39 insertions(+), 7 deletions(-) diff --git a/src/Simulation/qdk_sim_rs/Cargo.toml b/src/Simulation/qdk_sim_rs/Cargo.toml index d2500e3a97e..54a7e92640d 100644 --- a/src/Simulation/qdk_sim_rs/Cargo.toml +++ b/src/Simulation/qdk_sim_rs/Cargo.toml @@ -32,8 +32,12 @@ 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. @@ -41,6 +45,7 @@ python = ["pyo3", "numpy"] # 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" diff --git a/src/Simulation/qdk_sim_rs/README.md b/src/Simulation/qdk_sim_rs/README.md index 0d88dd46c5a..b18f76ed7a0 100644 --- a/src/Simulation/qdk_sim_rs/README.md +++ b/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 diff --git a/src/Simulation/qdk_sim_rs/src/lib.rs b/src/Simulation/qdk_sim_rs/src/lib.rs index 425286ba802..ae6e721dcc9 100644 --- a/src/Simulation/qdk_sim_rs/src/lib.rs +++ b/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 diff --git a/src/Simulation/qdk_sim_rs/src/linalg/decompositions/lu.rs b/src/Simulation/qdk_sim_rs/src/linalg/decompositions/lu.rs index a79ea531753..92b79ff511f 100644 --- a/src/Simulation/qdk_sim_rs/src/linalg/decompositions/lu.rs +++ b/src/Simulation/qdk_sim_rs/src/linalg/decompositions/lu.rs @@ -36,7 +36,7 @@ pub trait LUDecomposable { type Output: LUDecomposition; /// 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; @@ -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 where S: Data, 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) -> Result; + + // 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) -> Result; }