teukolsky_data: fix and extend documentation

1 files changed, 28 insertions, 20 deletions

diff --git a/teukolsky_data.h b/teukolsky_data.h
index 0394260..786554e 100644
--- a/teukolsky_data.h
+++ b/teukolsky_data.h
@@ -153,28 +153,20 @@ void td_context_free(TDContext **td);
 int td_solve(TDContext *td, double *coeffs_init[3]);
 
 /**
- * Evaluate the 3-metric γ_ij at the specified rectangular grid (in cylindrical
- * coordinates { ρ, z, φ }).
+ * Evaluate the conformal factor ψ at the specified points in spherical
+ * coordinates { r, θ, φ } (since the spacetime is axially symmetric, φ is
+ * disregarded).
  *
  * @param td the solver context
- * @param rho the array of ρ coordinates.
- * @param nb_coords_rho the number of elements in rho.
- * @param z   the array of z coordinates.
- * @param nb_coords_z the number of elements in z.
- * @param nb_comp number of needed components of the metric
- * @param comp a nb_comp-sized array specifying the components of the metric to evaluate
- * @param diff_order a nb_comp-sized array specifying the order of the derivatives of the
- *                   metric to evaluate. The first element specifies the derivative wrt ρ,
- *                   the second wrt z. I.e. diff_order[i] = { 0, 0 } evaluates the metric
- *                   itself, diff_order[i] = { 0, 1 } evaluates ∂γ/∂z etc.
- * @param out a nb_comp-sized array of pointers to the arrays into which the values of the
- *            metric will be written. Each requested component is evaluated on the grid
- *            formed by the outer product of the rho and z vectors. I.e.
- *            out[l][j * out_strides[l] + i] = γ_comp[l](rho[i], z[j]). The length of each
- *            array in out must be nb_coords_rho * nb_coords_z.
- * @param out_strides a nb_comp-sized array of distances (in double-sized elements), for each
- *                    array in out, between two elements corresponding to the same ρ but one
- *                    step in z. Each element in out_strides must be at least nb_coords_rho.
+ * @param nb_coords number of elements in the r and theta arrays
+ * @param r values of r coordinates
+ * @param theta values of θ coordinates
+ * @param diff_order order of the derivatives of the metric to evaluate. The
+ *   first element specifies the derivative wrt r, the second
+ *   wrt θ. I.e. diff_order[i] = { 0, 0 } evaluates ψ itself,
+ *   diff_order = { 0, 1 } evaluates ∂ψ/∂θ etc.
+ * @param out a nb_coords-sized array into which the values of the ψ will be
+ *   written. out[i] is the value of ψ at the spacetime point { r[i], θ[i], 0 }
  *
  * @return >= 0 on success, a negative error code on failure.
  */
@@ -182,18 +174,34 @@ int td_eval_psi(const TDContext *td,
                 size_t nb_coords, const double *r, const double *theta,
                 const unsigned int diff_order[2],
                 double *out);
+/**
+ * Same as td_eval_psi(), except K_{r}^r ('rr' component of the mixed-index
+ * extrinsic curvature tensor) is evaluated.
+ */
 int td_eval_krr(const TDContext *td,
                 size_t nb_coords, const double *r, const double *theta,
                 const unsigned int diff_order[2],
                 double *out);
+/**
+ * Same as td_eval_psi(), except K_{φ}^φ ('φφ' component of the mixed-index
+ * extrinsic curvature tensor) is evaluated.
+ */
 int td_eval_kpp(const TDContext *td,
                 size_t nb_coords, const double *r, const double *theta,
                 const unsigned int diff_order[2],
                 double *out);
+/**
+ * Same as td_eval_psi(), except K_{r}^θ ('rθ' component of the mixed-index
+ * extrinsic curvature tensor) is evaluated.
+ */
 int td_eval_krt(const TDContext *td,
                 size_t nb_coords, const double *r, const double *theta,
                 const unsigned int diff_order[2],
                 double *out);
+/**
+ * Compute the values of lapse that would make the spacetime slice maximal.
+ * Parameters are the same as for td_eval_psi().
+ */
 int td_eval_lapse(const TDContext *td,
                   size_t nb_coords, const double *r, const double *theta,
                   const unsigned int diff_order[2],