Document more C++ functions and classes

Makefile

@@ -1,6 +1,7 @@
 pretty:
-	clang-format --verbose -i include/compas/*/*.h src/*/*.cu src/*/*.cpp src/*/*.cuh tests/*cpp benchmarks/*cpp
-	clang-format --verbose -i julia-bindings/src/*cpp
+	clang-format --verbose -i src/*/*.cpp src/*/*.cu
+	clang-format --verbose -i include/compas/*/*.cuh include/compas/*/*.h
+	clang-format --verbose -i julia-bindings/src/*cpp tests/*cpp benchmarks/*cpp
 
 all: pretty
 

docs/build_api.py

@@ -67,9 +67,32 @@ def build_index_page(groups):
 
 
 groups = {
-    "Cartesian trajectories": ["CartesianTrajectory", "CartesianTrajectoryView", "make_cartesian_trajectory", "rewind", "prephaser", "phase_encoding", "SimulateSignalMethod", "magnetization_to_signal"],
-    "Spiral trajectories": ["SpiralTrajectory", "make_spiral_trajectory"],
-    "utils": ["compute_residual"]
+    "Data structures": [
+        "CudaContext",
+        "TissueParameterField",
+        "TissueParameters",
+    ],
+    "Jacobian computation": [
+        "compute_jacobian",
+        "compute_jacobian_hermitian",
+    ],
+    "Trajectories": [
+        "Trajectory",
+        "CartesianTrajectory",
+        "SpiralTrajectory",
+        "SimulateSignalMethod",
+        "magnetization_to_signal",
+        "phase_encoding",
+    ],
+    "Sequences": [
+        "FISPSequence",
+        "pSSFPSequence",
+        "simulate_magnetization",
+        "simulate_magnetization_derivative",
+    ],
+    "Utilities": [
+        "compute_residual",
+    ],
 }
 
 

include/compas/jacobian/hermitian.h

@@ -5,6 +5,19 @@
 
 namespace compas {
 
+/**
+ * Computes the product of the Hermitian transpose of the Jacobian matrix with the given vector.
+ *
+ * @param ctx
+ * @param echos The magnetization at echo time. Size: [nreadouts, nvoxels]
+ * @param delta_echos_T1 The partial derivatives of `echo` with respect to T1.
+ * @param delta_echos_T2 The partial derivatives of `echo` with respect to T2.
+ * @param parameters The tissue parameters (T1, T2, etc.)
+ * @param trajectory Cartesian k-space sampling trajectory.
+ * @param coil_sensitivities The sensitivities of the receiver coils. Size: [ncoils, nvoxels]
+ * @param vector The input vector. Size: [ncoils, nreadouts, nsamples_per_readout]
+ * @return The result of `Jᴴv`. Size: [nfields, nvoxels]. There are 4 fields: T1, T2, and rho<sub>x</sub>/rho<sub>y</sub>.
+ */
 Array<cfloat, 2> compute_jacobian_hermitian(
     const CudaContext& ctx,
     Array<cfloat, 2> echos,
@@ -14,4 +27,4 @@ Array<cfloat, 2> compute_jacobian_hermitian(
     CartesianTrajectory trajectory,
     Array<float, 2> coil_sensitivities,
     Array<cfloat, 3> vector);
-}
+}  // namespace compas

include/compas/jacobian/product.h

@@ -5,6 +5,19 @@
 
 namespace compas {
 
+/**
+ * Computes the product of the Jacobian matrix with the given vector.
+ *
+ * @param ctx The CUDA context.
+ * @param echos The magnetization at echo time. Size: [nreadouts, nvoxels]
+ * @param delta_echos_T1 The partial derivatives of `echo` with respect to T1.
+ * @param delta_echos_T2 The partial derivatives of `echo` with respect to T2.
+ * @param parameters The tissue parameters (T1, T2, etc.)
+ * @param trajectory Cartesian k-space sampling trajectory.
+ * @param coil_sensitivities The sensitivities of the receiver coils. Size: [ncoils, nvoxels]
+ * @param vector The input vector. Size: [nfields, nvoxels]. There are 4 fields: T1, T2, and rho<sub>x</sub>/rho<sub>y</sub>.
+ * @return The result of `Jv`. Size: [ncoils, nreadouts, nsamples_per_readout].
+ */
 Array<cfloat, 3> compute_jacobian(
     const CudaContext& ctx,
     Array<cfloat, 2> echos,

include/compas/parameters/tissue.h

@@ -7,8 +7,13 @@
 
 namespace compas {
 
+/**
+ * Stores the tissue parameters for each voxel. Note that, instead of having seperate 1D arrays for each field, data
+ * is instead stored in a single 2D matrix where each row is different field (see `TissueParameterField`) and each
+ * column is a voxel.
+ */
 struct TissueParameters: public Object {
-    Array<float, 2> parameters;
+    Array<float, 2> parameters;  // Size: [TissueParameterField::NUM_FIELDS, nvoxels]
     int nvoxels;
     bool has_z = true;
     bool has_b0 = true;

include/compas/parameters/tissue_view.cuh

@@ -5,6 +5,10 @@
 
 namespace compas {
 
+/**
+ * The fields that are stored in `TissueParameters` represented as integers. For example, `TissueParameterField::T1`
+ * is `0`, thus the first row of `TissueParameters` are the T1 values of the voxels.
+ */
 namespace TissueParameterField {
 enum {
     T1 = 0,
@@ -31,13 +35,19 @@ struct TissueVoxel {
     float z;
 };
 
+/**
+ * Device-side representation of `TissueParameters`
+ */
 struct TissueParametersView {
     cuda_view<float, 2> parameters;
     int nvoxels;
     bool has_z;
     bool has_b0;
     bool has_b1;
 
+    /**
+     * Returns the parameters for the voxel at location `i`.
+     */
     COMPAS_DEVICE TissueVoxel get(index_t i) const {
         TissueVoxel voxel;
 

include/compas/simulate/derivative.h

@@ -6,6 +6,18 @@ namespace compas {
 
 static constexpr float DEFAULT_FINITE_DIFFERENCE_DELTA = 1e-4F;
 
+/**
+ * Calculate the derivative of the magnetization at echo times given by `simulate_magnetization`.
+ *
+ * @param context The context.
+ * @param field One of the fields given by `TissueParameterField`.
+ * @param echos The echos calculated by `simulate_magnetization`.
+ * @param parameters The tissue parameters.
+ * @param sequence The pSSFP sequence
+ * @param delta The Δ used for calculating the finite difference method.
+ * @return An array of dimensions `[nreadouts, nvoxels]` giving the derivative over the given field of the magnetization
+ *         at each voxel for each readout.
+ */
 Array<cfloat, 2> simulate_magnetization_derivative(
     const CudaContext& context,
     int field,
@@ -14,6 +26,18 @@ Array<cfloat, 2> simulate_magnetization_derivative(
     pSSFPSequence sequence,
     float delta = DEFAULT_FINITE_DIFFERENCE_DELTA);
 
+/**
+ * Calculate the derivative of the magnetization at echo times given by `simulate_magnetization`.
+ *
+ * @param context The context.
+ * @param field One of the fields given by `TissueParameterField`.
+ * @param echos The echos calculated by `simulate_magnetization`.
+ * @param parameters The tissue parameters.
+ * @param sequence The FISP sequence
+ * @param delta The Δ used for calculating the finite difference method.
+ * @return An array of dimensions `[nreadouts, nvoxels]` giving the derivative over the given field of the magnetization
+ *         at each voxel for each readout.
+ */
 Array<cfloat, 2> simulate_magnetization_derivative(
     const CudaContext& context,
     int field,

include/compas/simulate/fisp.h

@@ -4,6 +4,16 @@
 
 namespace compas {
 
+/**
+ * Simulate the magnetization at echo times for the tissue parameters given by `parameters` for the given FISP sequence
+ * parameters.
+ *
+ * @param context The Context.
+ * @param parameters The tissue parameters.
+ * @param sequence The FISP sequence.
+ * @return An array of dimensions `[nreadouts, nvoxels]` giving the magnetization at each voxel for each readout at
+ *         echo times.
+ */
 Array<cfloat, 2> simulate_magnetization(
     const CudaContext& context,
     TissueParameters parameters,

include/compas/simulate/pssfp.h

@@ -3,6 +3,17 @@
 #include "compas/sequences/pssfp_view.h"
 
 namespace compas {
+
+/**
+ * Simulate the magnetization at echo times for the tissue parameters given by `parameters` for the given pSSFP sequence
+ * parameters.
+ *
+ * @param context The Context.
+ * @param parameters The tissue parameters.
+ * @param sequence The pSSFP sequence.
+ * @return An array of dimensions `[nreadouts, nvoxels]` giving the magnetization at each voxel for each readout at
+ *         echo times.
+ */
 Array<cfloat, 2> simulate_magnetization(
     const CudaContext& context,
     TissueParameters parameters,

include/compas/trajectories/cartesian.h

@@ -9,11 +9,14 @@
 namespace compas {
 
 /**
- * Object representing a Cartesian trajectory.
+ *  Describes a Cartesian gradient trajectory. This is represented by storing the starting position in `k-space` for
+ *  each readout and the step (`delta_k`) per sample point. It is assumed that the step is the same for all readouts.
+ *  Note that the cartesian trajectory is a special case of the spiral trajectory, having the same step size for each
+ *  readout (meaning it can be represented using a single value instead of an array of values).
  */
 struct CartesianTrajectory: public Trajectory {
-    Array<cfloat> k_start;
-    cfloat delta_k;
+    Array<cfloat> k_start;  // Size: nreadouts
+    cfloat delta_k;  // Size: nreadouts
 
     CartesianTrajectory(
         int nreadouts,
@@ -27,7 +30,6 @@ struct CartesianTrajectory: public Trajectory {
 };
 
 /**
- *
  * Create a Cartesian trajectory object.
  *
  * @param context

include/compas/trajectories/phase_encoding.h

@@ -8,7 +8,13 @@
 namespace compas {
 
 /**
- * Compute the phase encoding of a signal.
+ * Apply phase encoding to the given magnetization.
+ *
+ * @param ctx Compas context.
+ * @param echos The magnetization at echo times. Size: `[nreadouts, nvoxels]`.
+ * @param parameters The tissue parameters.
+ * @param trajectory The `Trajectory`.
+ * @return The phase encoded magnetization at echo times.
  */
 Array<cfloat, 2> phase_encoding(
     const CudaContext& ctx,

include/compas/trajectories/signal.h

@@ -8,25 +8,46 @@
 namespace compas {
 
 /**
- * Object to represent the kind of signal.
+ * Compute method used for `magnetization_to_signal`. Some method yield better performance, but at the cost of less
+ * accurate results.
  */
 enum struct SimulateSignalMethod {
+    /**
+     * Direct simulation without optimization or approximations. This is the most reliable method, but is also slow.
+     */
     Direct,
-    MatmulPedantic,
+
+    /**
+     * Use matrix multiplication method. This ensure reasonable accuracy with reasonable performance.
+     */
     Matmul,
+
+    /**
+     * Use high precision matrix multiplication method. This ensure high accuracy with reasonable performance.
+     */
+    MatmulPedantic,
+
+    /**
+     * Use low precision matrix multiplication method using TF32 floats. This gives low accuracy with high performance.
+     */
     MatmulTF32,
+
+    /**
+     * Use low precision matrix multiplication method using BF16 floats. This gives low accuracy with high performance.
+     */
     MatmulBF16,
 };
 
 /**
+ * Compute the MR signal given the magnetization at echo times in all voxels.
  *
- * @param context
- * @param echos
- * @param parameters
- * @param trajectory
- * @param coil_sensitivities
- * @param method
- * @return
+ * @param context Compas Context.
+ * @param echos Magnetization at echo times. Size: [nreadouts, nvoxels].
+ * @param parameters The tissue parameters.
+ * @param trajectory The trajectory.
+ * @param coil_sensitivities The coil sensitivities. Size: [ncoils, nvoxels].
+ * @param method Method used for calculating. See `SimulateSignalMethod`.
+ * @return The MR signal. Size: [ncoils, nreadouts, nsamples_per_readout].
  */
 Array<cfloat, 3> magnetization_to_signal(
     const CudaContext& context,

include/compas/trajectories/spiral.h

@@ -8,11 +8,12 @@
 namespace compas {
 
 /**
- * Object representing a Spiral trajectory.
+ *  Describes a Spiral gradient trajectory. This is represented by storing the starting position in `k-space` for
+ *  each readout and the step (`delta_k`) per sample point. The step can be different for each readout.
  */
 struct SpiralTrajectory: public Trajectory {
-    Array<cfloat> k_start;
-    Array<cfloat> delta_k;
+    Array<cfloat> k_start;  // Size: nreadouts
+    Array<cfloat> delta_k;  // Size: nreadouts
 
     SpiralTrajectory(
         int nreadouts,

include/compas/trajectories/spiral_view.cuh

@@ -1,9 +1,9 @@
 #pragma once
 
-#include "compas/trajectories/cartesian_view.cuh"
 #include "compas/core/complex_type.h"
 #include "compas/core/view.h"
 #include "compas/parameters/tissue_view.cuh"
+#include "compas/trajectories/cartesian_view.cuh"
 
 namespace compas {
 

include/compas/trajectories/trajectory.h

@@ -4,8 +4,8 @@
 
 namespace compas {
 
-/**
- * Generic class to represent a trajectory object.
+/***
+ * The base class for the `CartesianTrajectory` and `SpiralTrajectory`.
  */
 struct Trajectory: public Object {
     int nreadouts;