Complete redefinition of qpms_normalisation_t

Former-commit-id: 4e14e1430d9dda96e5c023941ea3fadebd895676

notes/Electrodynamics.bib

@@ -353,6 +353,7 @@ Cross-referenced as UMIACS-TR-2001-44},
   abstract = {This thesis addresses optical binding - a new area of interest within the field of optical micromanipulation. It presents, for the first time, a rigorous numerical simulation of some of the key results, along with new experimental findings and also physical interpretations of the results. In an optical trap particles are attracted close to areas of high optical intensities and intensity gradients. So, for example, if two lasers are pointed towards each other (a counter propagating trap) then a single particle is trapped in the centre of the two beams \textendash{} the system is analogous to a particle being held by two springs in a potential well. If one increases the number of particles in the trap then naively one would expect all the particles to collect in the centre of the well. However, the effect of optical binding means that the presence of one particle affects the distribution of light experienced by another particle, resulting in extremely complex interactions that can lead to unusual 1D and 2D structures to form within the trap. Optical binding is not only of theoretical interest but also has applications in micromanipulation and assembly.},
   language = {en},
   publisher = {{Springer Science \& Business Media}},
+  url = {http://gen.lib.rus.ec/book/index.php?md5=3B222192BB23C6D062BAABB76696D0E4},
   author = {Taylor, Jonathan M.},
   month = jul,
   year = {2011},
@@ -1817,6 +1818,7 @@ The anapole is an intriguing example of a nonradiating source useful in the stud
   abstract = {This book is an introduction to some of the most important properties of electromagnetic waves and their interaction with passive materials and scatterers. The main purpose of the book is to give a theoretical treatment of these scattering phenomena, and to illustrate numerical computations of some canonical scattering problems for different geometries and materials. The scattering theory is also important in the theory of passive antennas, and this book gives several examples on this topic. Topics covered include an introduction to the basic equations used in scattering; the Green functions and dyadics; integral representation of fields; introductory scattering theory; scattering in the time domain; approximations and applications; spherical vector waves; scattering by spherical objects; the null-field approach; and propagation in stratified media. The book is organised along two tracks, which can be studied separately or together. Track 1 material is appropriate for a first reading of the textbook, while Track 2 contains more advanced material suited for the second reading and for reference. Exercises are included for each chapter.},
   language = {English},
   publisher = {{Scitech Publishing}},
+  url = {http://gen.lib.rus.ec/book/index.php?md5=00CCB3E221E741ADDB2E236FD4A9F002},
   author = {Kristensson, Gerhard},
   month = jul,
   year = {2016},

notes/conventions.md

@@ -1,5 +1,5 @@
-VSWF conventions
+VSWF conventions {#vswf_conventions}
-================
+====================================
 
 In general, the (transversal) VSWFs can be defined using (some) vector spherical harmonics
 as follows: \f[
@@ -141,7 +141,7 @@ Literature convention tables
 	\vect E = \sum_\alpha \pr{ \wcrreg_\alpha \wfrreg_\alpha + \wcrout_\alpha \wfrout_\alpha }, \\
 	\vect H = \frac{1}{Z_0Z^r} \sum_\alpha \pr{ \wcrreg_\alpha \sigma_\alpha\wfrreg_\overline{\alpha} +
 		 \wcrout_\alpha \sigma_\alpha\wfrout_\overline{\alpha}},
-\f] where \f$ \sigma_{lmM} = +1, \sigma_{lmN}=-1, \overline{lmM}=lmM, \overline{lmN}=lmM, \f$  cf. eq. (6). The notation is not extremely consistent throughout Reid's memo.	| 	| 	|
+\f] where \f$ \sigma_{lmM} = +1, \sigma_{lmN}=-1, \overline{lmM}=lmN, \overline{lmN}=lmM, \f$  cf. eq. (6). The notation is not extremely consistent throughout Reid's memo.	| 	| 	|
 | Taylor \cite taylor_optical_2011	| \f[
 	\wfet_{mn}^{(j)}	=	\frac{n(n+1)}{kr}\sqrt{\frac{2n+1}{4\pi}\frac{\left(n-m\right)!}{\left(n+m\right)!}}\Fer[Taylor]{n}{m}\left(\cos\theta\right)e^{im\phi}z_{n}^{j}\left(kr\right)\uvec{r} \\
 		+\left[\tilde{\tau}_{mn}\left(\cos\theta\right)\uvec{\theta}+i\tilde{\pi}_{mn}\left(\cos\theta\right)\uvec{\phi}\right]e^{im\phi}\frac{1}{kr}\frac{\ud\left(kr\,z_{n}^{j}\left(kr\right)\right)}{\ud(kr)}, \\ 

qpms/normalisation.h

@@ -0,0 +1,149 @@
+/*! \file normalisation.h
+ * \brief Convention-dependent coefficients for VSWFs.
+ *
+ * See also @ref qpms_normalisation_t and @ref vswf_conventions.
+ */
+#ifndef NORMALISATION_H
+#define NORMALISATION_H
+
+#include "qpms_types.h"
+#include <math.h>
+#include <complex.h>
+
+
+/// Returns the (real positive) common norm factor of a given normalisation compared to the reference convention.
+/** Does NOT perform the inversion if QPMS_NORMALISATION_INVERSE is set. */
+static inline double qpms_normalisation_normfactor(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	switch (norm & QPMS_NORMALISATION_NORM_BITS) {
+		case QPMS_NORMALISATION_NORM_POWER:
+			return 1;
+		case QPMS_NORMALISATION_NORM_SPHARM:
+			return sqrt(l*(l+1));
+		case QPMS_NORMALISATION_NORM_NONE: // TODO more precision
+			return sqrt(l*(l+1) * 4*M_PI / (2*l+1)) *
+			       	exp(0.5*(lgamma(l+m+1) - lgamma(l-m+1)));
+		default:
+			QPMS_WTF;
+	}
+}
+
+
+/// Returns the factors of a magnetic VSWF of a given convention compared to the reference convention.
+/**
+ * This version ignores the Condon-Shortley phase bit (perhaps because the Condon-Shortley
+ * phase is already taken into account in a `gsl_sf_legendre_*_e()` call.)
+ */
+static inline complex double qpms_normalisation_factor_M_noCS(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	complex double fac = qpms_normalisation_normfactor(norm, l, m);
+	if (norm & QPMS_NORMALISATION_M_MINUS) fac *= -1;
+	if (norm & QPMS_NORMALISATION_M_I) fac *= I;
+	if (norm & QPMS_NORMALISATION_INVERSE) fac = 1/fac;
+	return fac;
+}
+
+
+/// Returns the factors of a magnetic VSWF of a given convention compared to the reference convention.
+/**
+ * This version takes into account the Condon-Shortley phase bit. 
+ * Do not use if the C.-S. has already been taken into account e.g. in
+ * a `gsl_sf_legendre_*_e()` call.
+ */
+static inline complex double qpms_normalisation_factor_M(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	complex double fac = qn;
+	return ((norm & QPMS_NORMALISATION_CSPHASE) && (m % 2)) ? -fac : fac;
+}
+
+
+/// Returns the factors of a electric VSWF of a given convention compared to the reference convention.
+/**
+ * This version ignores the Condon-Shortley phase bit (perhaps because the Condon-Shortley
+ * phase is already taken into account in a `gsl_sf_legendre_*_e()` call.)
+ */
+static inline complex double qpms_normalisation_factor_N_noCS(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	complex double fac = qpms_normalisation_normfactor(norm, l, m);
+	if (norm & QPMS_NORMALISATION_N_MINUS) fac *= -1;
+	if (norm & QPMS_NORMALISATION_N_I) fac *= I;
+	if (norm & QPMS_NORMALISATION_INVERSE) fac = 1/fac;
+	return fac;
+}
+
+
+/// Returns the factors of a electric VSWF of a given convention compared to the reference convention.
+/**
+ * This version takes into account the Condon-Shortley phase bit. 
+ * Do not use if the C.-S. has already been taken into account e.g. in
+ * a `gsl_sf_legendre_*_e()` call.
+ */
+static inline complex double qpms_normalisation_factor_N(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	complex double fac = qn;
+	return ((norm & QPMS_NORMALISATION_CSPHASE) && (m % 2)) ? -fac : fac;
+}
+
+
+#if 0
+/// Returns the factors of a longitudinal VSWF of a given convention compared to the reference convention.
+/**
+ * This version ignores the Condon-Shortley phase bit (perhaps because the Condon-Shortley
+ * phase is already taken into account in a `gsl_sf_legendre_*_e()` call.)
+ */
+static inline complex double qpms_normalisation_factor_L_noCS(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	complex double fac = qpms_normalisation_normfactor(norm, l, m);
+	if (norm & QPMS_NORMALISATION_L_MINUS) fac *= -1;
+	if (norm & QPMS_NORMALISATION_L_I) fac *= I;
+	if (norm & QPMS_NORMALISATION_INVERSE) fac = 1/fac;
+	return fac;
+}
+
+/// Returns the factors of a longitudinal VSWF of a given convention compared to the reference convention.
+/**
+ * This version takes into account the Condon-Shortley phase bit. 
+ * Do not use if the C.-S. has already been taken into account e.g. in
+ * a `gsl_sf_legendre_*_e()` call.
+ */
+static inline complex double qpms_normalisation_factor_L(qpms_normalisation_t norm, qpms_l_t l, qpms_m_t m) {
+	complex double fac = qn;
+	return ((norm & QPMS_NORMALISATION_CSPHASE) && (m % 2)) ? -fac : fac;
+}
+#endif
+
+/// Returns normalisation flags corresponding to the dual spherical harmonics / waves.
+/**
+ * This reverses the normalisation factors returned by qpms_normalisation_factor_*
+ * and conjugates the asimuthal part for complex spherical harmonics, 
+ * \f$ e^{\pm im\phi} \leftrightarrow e^{\mp im\phi} \f$.
+ */
+static inline qpms_normalisation_t qpms_normalisation_dual(qpms_normalisation_t norm) {
+	norm ^= QPMS_NORMALISATION_INVERSE;
+	if (!(norm & QPMS_NORMALISATION_SPHARM_REAL))
+		norm ^= QPMS_NORMALISATION_REVERSE_AZIMUTHAL_PHASE;
+	return norm;
+}
+
+/// Returns the asimuthal part of a spherical harmonic.
+/** Returns \f[ e^{im\phi} \f] for standard complex spherical harmonics,
+ * \f[ e^{-im\phi \f] for complex spherical harmonics 
+ * and QPMS_NORMALISATION_REVERSE_ASIMUTHAL_PHASE set.
+ *
+ * For real spherical harmonics, this gives
+ * \f[ 
+ * 	\sqrt{2}\cos{m \phi} \quad \mbox{if } m>0, \\
+ * 	\sqrt{2}\sin{m \phi} \quad \mbox{if } m<0, \\
+ * 	1 \quad \mbox{if } m>0. \\
+ * \f]
+ */
+static inline complex double qpms_spharm_azimuthal_part(qpms_normalisation_t norm, qpms_m_t m, double phi) {
+	switch(norm & (QPMS_NORMALISATION_REVERSE_ASIMUTHAL_PHASE | QPMS_NORMALISATION_SPHARM_REAL)) {
+		case 0:
+			return cexp(I*m*phi);
+		case QPMS_NORMALISATION_REVERSE_ASIMUTHAL_PHASE:
+			return cexp(-I*m*phi);
+		case QPMS_NORMALISATION_SPHARM_REAL:
+			if (m > 0) return M_SQRT2 * cos(m*phi);
+			else if (m < 0) return M_SQRT2 * sin(m*phi);
+			else return 1.;
+		default:
+			QPMS_WTF;
+	}
+}
+
+#endif //NORMALISATION_H

qpms/qpms_types.h

@@ -86,48 +86,86 @@ typedef enum {
 
 
 
-/// Vector spherical wavefuction normalisation (and sign) convention codes.
+/// Vector spherical wavefuction normalisation and phase convention codes.
-/** Throughout the literature, various conventions for VSWF bases are used.
+/**
- *  The meaningful ones are the "power" and "spherical harmonic" normalisation
+ *  Throughout the literature, various conventions for VSWF bases are used.
- *  conventions, as the (\a l, \a m) and (\a l, \a −m) waves of the same type have the same
+ *  These bit flags are used by the functions declared in normalisation.h
- *  intensities.
+ *  that return the appropriate convention-dependent factors.
- *  One might also encounter a very inconvenient and messy "antinormalisation"
- *  used in Xu (TODO reference).
  *
- *  Moreover, VSWFs might use various sign convention. Usually they either
+ *  See @ref vswf_conventions for comparison of the various conventions used.
- *  carry the Condon-Shortley phase \f$ (-1)^m \f$ or not, which is also saved here.
- *
- *  TODO references and exact definitions.
  */
 typedef enum {
+	QPMS_NORMALISATION_UNDEF = 0, ///< Convention undefined. This should not happen.
+       	/// Flag indicating that qpms_normalisition_factor_* should actually return values inverse to the default.
+	QPMS_NORMALISATION_INVERSE = 1, 
+	/** Flag indicating inversion of the asimuthal phase for complex spherical harmonics (i.e. \f$ e^{-im\phi} \f$
+	 * instead of \f$ e^{im\phi} \f$.
+	 */
+	QPMS_NORMALISATION_REVERSE_AZIMUTHAL_PHASE = 2,
+	/// Flag indicating use of the real spherical harmonics.
+	/** If QPMS_NORMALISATION_REVERSE_AZIMUTHAL_PHASE is unset, negative \a m
+	 * correspond to sine in the asimuthal factor; if set, undefined behaviour.
+	 */
+	QPMS_NORMALISATION_SPHARM_REAL = 4,
+	/// Flag indicating usage of Condon-Shortley phase.
+	/** If set, the Ferrers functions and everything derived from them 
+	 * (spherical harmonics, VSWFs) will include a \f$ (-1)^m \f$ factor.
+	 *
+	 * On implementation level, this means that the relevant `gsl_sf_legendre_*_e()`
+	 * functions will be called with argument `csphase = -1.` instead of `+1.`.
+	 */
+	QPMS_NORMALISATION_CSPHASE = 8,
+	QPMS_NORMALISATION_M_I = 16, ///< Include an additional \a i -factor into the magnetic waves.
+	QPMS_NORMALISATION_M_MINUS = 32, ///< Include an additional \f$-1\f$ -factor into the magnetic waves.
+	QPMS_NORMALISATION_N_I = 64, ///< Include an additional \a i -factor into the electric waves.
+	QPMS_NORMALISATION_N_MINUS = 128, ///< Include an additional \f$-1\f$ -factor into the magnetic waves.
+#if 0
+	QPMS_NORMALISATION_L_I = 256, ///< Include an additional \a i -factor into the longitudinal waves.
+	QPMS_NORMALISATION_L_MINUS = 512, ///< Include an additional \f$-1\f$ -factor into the longitudinal waves.
+#endif 
+	QPMS_NORMALISATION_NORM_BITSTART = 65536, 
+	/// The VSWFs shall be power-normalised. This is the "default".
+	/**
+	 * Power normalisation is used e.g. in \cite kristensson_spherical_2014 (complex spherical
+	 * harmonics with Condon-Shortley phase) or \cite kristensson_scattering_2016 (real
+	 * spherical harmonics). This is also the reference for all the other normalisation conventions,
+	 * meaning that qpms_normalisation_factor_M() and qpms_normalisation_factor_N() shall
+	 * always return `1. + 0.*I` if `norm == QPMS_NORMALISATION_NORM_POWER`.
+	 */
+	QPMS_NORMALISATION_NORM_POWER = QPMS_NORMALISATION_NORM_BITSTART * 1,
+	/// The VSWFs shall be normalised as in \cite taylor_optical_2011 .
+	/** This includes a \f$ \sqrt{l(l+1)} \f$ factor compared to the power normalisation. */
+	QPMS_NORMALISATION_NORM_SPHARM = QPMS_NORMALISATION_NORM_BITSTART * 3,
+	/// The VSWFs shall be created using spherical harmonics without any normalisation. Do not use.
+	/** This includes a \f[ 
+	 * 	\sqrt{l(l+1)} \left(\frac{(2l+1)}{4\pi}\frac{(l-m)!}{(l+m)!}\right)^{-\frac{1}{2}}
+	 * \f] factor compared to the power normalisation.
+	 *
+	 * Note that this has no sense whatsoever for real spherical harmonics.
+	 * Again, do not use this.
+	 */
+	QPMS_NORMALISATION_NORM_NONE = QPMS_NORMALISATION_NORM_BITSTART * 2,
+	QPMS_NORMALISATION_NORM_BITS = QPMS_NORMALISATION_NORM_POWER 
+		| QPMS_NORMALISATION_NORM_NONE | QPMS_NORMALISATION_NORM_SPHARM,
 
-#define QPMS_NORMALISATION_T_CSBIT 128 ///< A flag used in qpms_normalisation_t indicating the Condon-Shortley phase.
+	/// VSWF convention used in \cite kristensson_scattering_2016
-
+	QPMS_NORMALISATION_CONVENTION_KRISTENSSON_REAL = QPMS_NORMALISATION_NORM_POWER
-#ifdef USE_XU_ANTINORMALISATION
+		| QPMS_NORMALISATION_SPHARM_REAL,
-	// As in TODO
+	/// VSWF convention used in \cite kristensson_spherical_2014
-	QPMS_NORMALISATION_XU = 4, ///< such that the numerical values in Xu's tables match, not recommended to use otherwise
+	QPMS_NORMALISATION_CONVENTION_KRISTENSSON = QPMS_NORMALISATION_NORM_POWER
-	QPMS_NORMALISATION_XU_CS = QPMS_NORMALISATION_XU | QPMS_NORMALISATION_T_CSBIT, 
+		| QPMS_NORMALISATION_CSPHASE,
-#endif
+	/// VSWF convention used in SCUFF-EM \cite reid_electromagnetism_2016
-	QPMS_NORMALISATION_NONE = 3, ///< genuine unnormalised waves (with unnormalised Legendre polynomials)
+	QPMS_NORMALISATION_CONVENTION_SCUFF = QPMS_NORMALISATION_NORM_POWER
-	QPMS_NORMALISATION_KRISTENSSON = 2, ///< As in http://www.eit.lth.se/fileadmin/eit/courses/eit080f/Literature/book.pdf, power-normalised
+		| QPMS_NORMALISATION_CSPHASE | QPMS_NORMALISATION_M_I
-	QPMS_NORMALISATION_POWER = QPMS_NORMALISATION_KRISTENSSON, 
+		| QPMS_NORMALISATION_N_MINUS
-	// as in TODO
-	QPMS_NORMALISATION_TAYLOR = 1,
-	QPMS_NORMALISATION_SPHARM = QPMS_NORMALISATION_TAYLOR,
-	// Variants with Condon-Shortley phase
-	QPMS_NORMALISATION_NONE_CS = QPMS_NORMALISATION_NONE | QPMS_NORMALISATION_T_CSBIT,
-	QPMS_NORMALISATION_KRISTENSSON_CS = QPMS_NORMALISATION_KRISTENSSON | QPMS_NORMALISATION_T_CSBIT, 
-	QPMS_NORMALISATION_POWER_CS = QPMS_NORMALISATION_KRISTENSSON_CS,
-	QPMS_NORMALISATION_TAYLOR_CS = QPMS_NORMALISATION_TAYLOR | QPMS_NORMALISATION_T_CSBIT,
-	QPMS_NORMALISATION_SPHARM_CS = QPMS_NORMALISATION_TAYLOR_CS,
-	QPMS_NORMALISATION_UNDEF = 0
 } qpms_normalisation_t;
 
 /// Determine whether the convention includes Condon-Shortley phase (-1) or not (+1).
 static inline int qpms_normalisation_t_csphase(qpms_normalisation_t norm) {
-	return (norm & QPMS_NORMALISATION_T_CSBIT)? -1 : 1;
+	return (norm & QPMS_NORMALISATION_CSPHASE)? -1 : 1;
 }
 
+#if 0
 /// Returns the normalisation convention code without the Condon-Shortley phase.
 static inline int qpms_normalisation_t_normonly(qpms_normalisation_t norm) {
 	return norm & (~QPMS_NORMALISATION_T_CSBIT);
@@ -198,6 +236,7 @@ static inline double qpms_normalisation_t_factor_abssquare(qpms_normalisation_t
 			return NAN;
 	}
 }
+#endif
 
 
 /// Bessel function kinds.