Doxygen, TODO list.

Former-commit-id: 72381c6157319efecf6c62f98851df6194e2a972

Doxyfile

@@ -753,7 +753,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = qpms finite_systems.md README.md README.Triton.md finite_systems.md lattices.md
+INPUT                  = qpms finite_systems.md README.md README.Triton.md finite_systems.md lattices.md TODO.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

TODO.md

@@ -0,0 +1,29 @@
+TODO list before public release
+===============================
+
+- Tests!
+- Docs!
+- Cross section calculations.
+- Field calculations.
+- Complex frequencies, n's, k's.
+- Transforming point (meta)generators.
+- Ewald summations of all types of lattices (dimensionality-wise).
+- Split lattices.h into separate point generator and lattice vector manipulation parts.
+  * Maybe move something from the .h to .c file.
+- Check exact normalisation convention of scuff-tmatrix output.
+- Check whether the Condon-Shortley phase affects the form of Wigner matrices.
+- The xflip, yflip and possible i-factor problem.
+- General 3D point group symmetries.
+  * Instead the current hard-coded limited set.
+  * The generation, finding subgroups etc. should be "easy" with
+    quaternions and stuff, as the  set is quite limited, 
+    see [Wikipedia](https://en.wikipedia.org/wiki/Point_groups_in_three_dimensions).
+  * Not sure about the representations, though.
+  * As a description of a T-matrix / particle metadata.
+- Nice CLI for all general enough utilities.
+- Remove legacy code.
+- Prefix all identifiers. Maybe think about a different prefix than qpms?
+- Consistent indentation and style overall.
+
+
+

TODOs.rst

@@ -1,20 +0,0 @@
-URGENT
-======
-
-- Check exact normalisation convention of scuff-tmatrix output.
-- Check whether the Condon-Shortley phase affects the form of Wigner matrices.
-- The xflip, yflip and possible i-factor problem.
-
-
-TODO label description (obsolete!)
-==================================
-
-LMAXVAR - besides to int, the function should support an iterable for the lMax argument or similar, and
-          in such case the output should have the according additional dimension. In the end, I want
-          to support systems where different nanoparticles have different lMax.
-
-VECTORIZE - add support to process more than one element at once, in general.
-
-TRUEVECTORIZE - remove inner python loops to speed things up
-
-FEATURE - non-urgent general feature to implement

qpms/ewald.c

@@ -48,7 +48,7 @@ static inline double factorial(const int n) {
 static inline complex double csq(complex double x) { return x * x; }
 static inline double sq(double x) { return x * x; }
 
-
+/// Metadata describing the normalisation conventions used in ewald32_constants_t.
 typedef enum {
   EWALD32_CONSTANTS_ORIG, // As in [1, (4,5)], NOT USED right now.
   EWALD32_CONSTANTS_AGNOSTIC /* Not depending on the spherical harmonic sign/normalisation

qpms/ewald.h

@@ -1,3 +1,29 @@
+/*! \file ewald.h
+ * \brief Lattice sums of spherical waves.
+ *
+ * Implementation of two-dimensional lattice sum in three dimensions
+ * according to:
+ * - [1] C.M. Linton, I. Thompson
+ *     Journal of Computational Physics 228 (2009) 1815–1829
+ * - [2] C.M.Linton
+ *     SIAM Review Vol 52, No. 4, pp. 630–674
+ *
+ * N.B.!!! currently, the long-range parts are calculated 
+ * not according to [1,(4.5)], but rather
+ * according to the spherical-harmonic-normalisation-independent 
+ * formulation in my notes notes/ewald.lyx.
+ * Both parts of lattice sums are then calculated with 
+ * the \f$ P_n^{|m|} e^{im\phi} \f$
+ * (N.B. or \f$ P_n^{|m|} e^{imf} (-1)^m \f$ for negative m) 
+ * substituted in place  of  \f$ Y_n^m \f$ 
+ * (this is quite a weird normalisation especially 
+ * for negative \f$ |m| \f$, but it is consistent
+ * with the current implementation of the translation coefficients in
+ * @ref translations.c;
+ * in the long run, it might make more sense to replace it everywhere with normalised
+ * Legendre polynomials).
+ */
+
 #ifndef EWALD_H
 #define EWALD_H
 #include <gsl/gsl_sf_result.h>
@@ -9,28 +35,6 @@
 #include "qpms_types.h"
 #include "lattices.h"
 
-/* 
- * Implementation of two-dimensional lattice sum in three dimensions
- * according to:
- * [1] C.M. Linton, I. Thompson
- *     Journal of Computational Physics 228 (2009) 1815–1829
- * [2] C.M.Linton
- *     SIAM Review Vol 52, No. 4, pp. 630–674
- */
-
-/*
- * N.B.!!! currently, the long-range parts are calculated not according to [1,(4.5)], but rather
- * according to the spherical-harmonic-normalisation-independent formulation in my notes
- * notes/ewald.lyx.
- * Both parts of lattice sums are then calculated with the P_n^|m| e^imf substituted in place
- *                                             // (N.B. or P_n^|m| e^imf (-1)^m for negative m) 
- * of Y_n^m (this is quite a weird normalisation especially for negative |m|, but it is consistent
- * with the current implementation of the translation coefficients in translations.c;
- * in the long run, it might make more sense to replace it everywhere with normalised
- * Legendre polynomials).
- */
-
-
 // Use this handler to ignore underflows of incomplete gamma.
 gsl_error_handler_t IgnoreUnderflowsGSLErrorHandler;
 
@@ -117,20 +121,20 @@ static inline complex double clilgamma(complex double z) {
  
 
 
-// Incomplete Gamma function as series
-// DLMF 8.7.3 (latter expression) for complex second argument
+/// Incomplete Gamma function as series.
+/** DLMF 8.7.3 (latter expression) for complex second argument */
 int cx_gamma_inc_series_e(double a, complex z, qpms_csf_result * result);
 
-// Incomplete gamma for complex second argument
-// if x is (almost) real, it just uses gsl_sf_gamma_inc_e
+/// Incomplete gamma for complex second argument.
+/** if x is (almost) real, it just uses gsl_sf_gamma_inc_e(). */
 int complex_gamma_inc_e(double a, complex double x, qpms_csf_result *result);
 
-// Exponential integral for complex second argument
-// If x is (almost) positive real, it just uses gsl_sf_expint_En_e
+/// Exponential integral for complex second argument.
+/** If x is (almost) positive real, it just uses gsl_sf_expint_En_e(). */
 int complex_expint_n_e(int n, complex double x, qpms_csf_result *result);
 
 
-// hypergeometric 2F2, used to calculate some errors
+/// Hypergeometric 2F2, used to calculate some errors.
 int hyperg_2F2_series(const double a, const double b, const double c, const double d,
     const double x, gsl_sf_result *result);