From 9bfba7077bc7e347f0ea4c8798835929222af4c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Ne=C4=8Dada?= Date: Thu, 27 Jun 2019 16:42:35 +0300 Subject: [PATCH] Doxygen, TODO list. Former-commit-id: 72381c6157319efecf6c62f98851df6194e2a972 --- Doxyfile | 2 +- TODO.md | 29 ++++++++++++++++++++++++ TODOs.rst | 20 ----------------- qpms/ewald.c | 2 +- qpms/ewald.h | 62 ++++++++++++++++++++++++++++------------------------ 5 files changed, 64 insertions(+), 51 deletions(-) create mode 100644 TODO.md delete mode 100644 TODOs.rst diff --git a/Doxyfile b/Doxyfile index 49d6842..e59d63a 100644 --- a/Doxyfile +++ b/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 diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..026d624 --- /dev/null +++ b/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. + + + diff --git a/TODOs.rst b/TODOs.rst deleted file mode 100644 index d85be8a..0000000 --- a/TODOs.rst +++ /dev/null @@ -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 diff --git a/qpms/ewald.c b/qpms/ewald.c index ac8ac23..b36f5c4 100644 --- a/qpms/ewald.c +++ b/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 diff --git a/qpms/ewald.h b/qpms/ewald.h index ca794b3..5a2215c 100644 --- a/qpms/ewald.h +++ b/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 @@ -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);