Doxygen annotations of header files.

Also more politically corrent file name.
2020-06-29 09:14:19 +03:00 · 2020-06-29 09:14:19 +03:00 · e0861a7d40
parent 87c2b08701
commit e0861a7d40
9 changed files with 86 additions and 31 deletions
--- a/notes/old_scattering_notes.lyx
+++ b/notes/old_scattering_notes.lyx
@ -1,7 +1,9 @@
-#LyX 2.1 created this file. For more info see http://www.lyx.org/
-\lyxformat 474
+#LyX 2.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 544
 \begin_document
 \begin_header
+\save_transient_properties true
+\origin unavailable
 \textclass report
 \begin_preamble
 %\renewcommand*{\chapterheadstartvskip}{\vspace*{1cm}}
@ -13,16 +15,18 @@
 \language_package default
 \inputencoding auto
 \fontencoding global
-\font_roman TeX Gyre Pagella
-\font_sans default
-\font_typewriter default
-\font_math auto
+\font_roman "default" "TeX Gyre Pagella"
+\font_sans "default" "default"
+\font_typewriter "default" "default"
+\font_math "auto" "auto"
 \font_default_family default
 \use_non_tex_fonts true
 \font_sc false
 \font_osf true
-\font_sf_scale 100
-\font_tt_scale 100
+\font_sf_scale 100 100
+\font_tt_scale 100 100
+\use_microtype false
+\use_dash_ligatures false
 \graphics default
 \default_output_format pdf4
 \output_sync 0
@ -63,6 +67,7 @@
 \suppress_date false
 \justification true
 \use_refstyle 1
+\use_minted 0
 \index Index
 \shortcut idx
 \color #008000
@ -75,7 +80,10 @@
 \tocdepth 3
 \paragraph_separation indent
 \paragraph_indentation default
-\quotes_language swedish
+\is_math_indent 0
+\math_numbering_side default
+\quotes_style swedish
+\dynamic_quotes 0
 \papercolumns 1
 \papersides 1
 \paperpagestyle default
@ -102,7 +110,7 @@
 \end_layout

 \begin_layout Title
-Electromagnetic multiple scattering, spherical waves and ****
+Electromagnetic multiple scattering, spherical waves and conventions
 \end_layout

 \begin_layout Author
@ -244,7 +252,7 @@ Pi and tau
 Xu
 \begin_inset CommandInset label
 LatexCommand label
-name "sub:Xu pitau"
+name "subsec:Xu pitau"

 \end_inset

@ -373,7 +381,7 @@ The limiting expressions are obtained simply by multiplying the expressions
 
 \begin_inset CommandInset ref
 LatexCommand ref
-reference "sub:Xu pitau"
+reference "subsec:Xu pitau"

 \end_inset

@ -462,6 +470,7 @@ Jackson
 LatexCommand cite
 after "(9.101)"
 key "jackson_classical_1998"
+literal "true"

 \end_inset

@ -478,6 +487,7 @@ where
 LatexCommand cite
 after "(9.119)"
 key "jackson_classical_1998"
+literal "true"

 \end_inset

@ -499,6 +509,7 @@ Normalisation
 LatexCommand cite
 after "(9.120)"
 key "jackson_classical_1998"
+literal "true"

 \end_inset

@ -519,6 +530,7 @@ Local sum rule
 LatexCommand cite
 after "(9.153)"
 key "jackson_classical_1998"
+literal "true"

 \end_inset

@ -793,6 +805,7 @@ As in
 LatexCommand cite
 after "eq. (36)"
 key "xu_calculation_1996"
+literal "true"

 \end_inset

@ -816,6 +829,7 @@ where CS is
 LatexCommand cite
 after "eq. (81)"
 key "xu_calculation_1996"
+literal "true"

 \end_inset

@ -826,7 +840,7 @@ key "xu_calculation_1996"
 Relation between Kristensson and Taylor
 \begin_inset CommandInset label
 LatexCommand label
-name "sub:Kristensson-v-Taylor"
+name "subsec:Kristensson-v-Taylor"

 \end_inset

@ -961,7 +975,7 @@ In this section I summarize the formulae for power
 Kristensson
 \begin_inset CommandInset label
 LatexCommand label
-name "sub:Radiated enenergy-Kristensson"
+name "subsec:Radiated enenergy-Kristensson"

 \end_inset

@ -1022,7 +1036,7 @@ Here I derive the radiated power in Taylor's convention by applying the
 relations from subsection 
 \begin_inset CommandInset ref
 LatexCommand ref
-reference "sub:Kristensson-v-Taylor"
+reference "subsec:Kristensson-v-Taylor"

 \end_inset

@ -1030,7 +1044,7 @@ reference "sub:Kristensson-v-Taylor"
 
 \begin_inset CommandInset ref
 LatexCommand ref
-reference "sub:Radiated enenergy-Kristensson"
+reference "subsec:Radiated enenergy-Kristensson"

 \end_inset

@ -1110,6 +1124,7 @@ Jackson
 LatexCommand cite
 after "(9.155)"
 key "jackson_classical_1998"
+literal "true"

 \end_inset

@ -1138,6 +1153,7 @@ TODO start from
 LatexCommand cite
 after "(A7)"
 key "pustovit_plasmon-mediated_2010"
+literal "true"

 \end_inset

@ -1317,6 +1333,7 @@ TODO start from
 LatexCommand cite
 after "(A11)"
 key "pustovit_plasmon-mediated_2010"
+literal "true"

 \end_inset

@ -1479,6 +1496,7 @@ Cruzan's formulation, Xu's normalisation
 LatexCommand cite
 after "(59)"
 key "xu_efficient_1998"
+literal "true"

 \end_inset

@ -1495,6 +1513,7 @@ where
 LatexCommand cite
 after "(28,5,60,61)"
 key "xu_efficient_1998"
+literal "true"

 \end_inset

--- a/qpms/drudeparam_data.c
+++ b/qpms/drudeparam_data.c
@ -1,8 +1,15 @@
+/*! \file drudeparam_data.c
+ * \brief Lorentz-Drude model parameters for various materials permittivity.
+ *
+ * Data taken from drudelorentz.com, originally apparently from
+ * Rakić & al., Appl. Opt. 22 (1198), pp. 5271–5283,
+ * Optical Properties of Metallic Films for Vertical-Cavity Optoelectronic Device
+ * https://dx.doi.org/10.1364/AO.37.005271
+ */
+
 #include "materials.h"
 #include <gsl/gsl_const_mksa.h>

-// Data from drudelorentz.com
-
 #define EH (GSL_CONST_MKSA_ELECTRON_VOLT / GSL_CONST_MKSA_PLANCKS_CONSTANT_HBAR)

 static const qpms_ldparams_t LDPARAMS_AU = {
--- a/qpms/gaunt.h
+++ b/qpms/gaunt.h
@ -1,3 +1,6 @@
+/*! \file gaunt.h
+ * \brief Gaunt coefficients (integrals over three spherical harmonics).
+ */
 #ifndef GAUNT_H
 #define GAUNT_H
 #include <stdlib.h>
--- a/qpms/kahansum.h
+++ b/qpms/kahansum.h
@ -1,3 +1,6 @@
+/*! \file kahansum.h
+ * \brief Inline functions providing Kahan summation.
+ */
 #ifndef KAHANSUM_H
 #define KAHANSUM_H

--- a/qpms/materials.h
+++ b/qpms/materials.h
@ -1,4 +1,4 @@
-/* \file materials.h
+/*! \file materials.h
 * \brief Optical properties of materials.
 */
 #ifndef QPMS_MATERIALS_H
@ -73,17 +73,17 @@ typedef struct qpms_ldparams_t {
 	qpms_ldparams_triple_t data[]; ///< "Oscillator" parameters.
 } qpms_ldparams_t;

-extern const qpms_ldparams_t *const QPMS_LDPARAMS_AG; ///< Lorentz-Drude parameters for silver.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_AU; ///< Lorentz-Drude parameters for gold.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_CU; ///< Lorentz-Drude parameters for copper.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_AL; ///< Lorentz-Drude parameters for aluminium.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_CR; ///< Lorentz-Drude parameters for chromium.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_TI; ///< Lorentz-Drude parameters for titanium.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_BE; ///< Lorentz-Drude parameters for beryllium.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_NI; ///< Lorentz-Drude parameters for nickel.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_PD; ///< Lorentz-Drude parameters for polonium.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_PT; ///< Lorentz-Drude parameters for platinum.
-extern const qpms_ldparams_t *const QPMS_LDPARAMS_W ; ///< Lorentz-Drude parameters for tungsten.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_AG; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for silver.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_AU; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for gold.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_CU; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for copper.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_AL; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for aluminium.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_CR; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for chromium.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_TI; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for titanium.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_BE; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for beryllium.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_NI; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for nickel.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_PD; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for polonium.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_PT; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for platinum.
+extern const qpms_ldparams_t *const QPMS_LDPARAMS_W ; ///< Lorentz-Drude parameters from \cite rakic_optical_1998 for tungsten.

 /// Lorentz-Drude permittivity.
 complex double qpms_lorentzdrude_eps(complex double omega, const qpms_ldparams_t *);
--- a/qpms/oshacks.h
+++ b/qpms/oshacks.h
@ -1,3 +1,6 @@
+/*! \file oshacks.h
+ * \brief Some platform-dependent functions.
+ */
 #ifndef _QPMS_OSHACKS_H
 #define _QPMS_OSHACKS_H
 #include <unistd.h>
--- a/qpms/parsing.h
+++ b/qpms/parsing.h
@ -1,3 +1,6 @@
+/*! \file parsing.h
+ * \brief Some custom string conversions.
+ */
 #ifndef QPMS_PARSING_H
 #define QPMS_PARSING_H

--- a/qpms/qpmsblas.h
+++ b/qpms/qpmsblas.h
@ -1,4 +1,17 @@
-// If included together with <cblas.h>, this must be include _afterwards_ because of the typedefs!
+/*! \file qpmsblas.h
+ * \brief Naïve implementation of BLAS functions to workaround OpenBLAS bugs.
+ *
+ * There is a bug in certain versions of OpenBLAS causing crashes if many
+ * BLAS functions are run from different threads in parallel. 
+ * Typically, this happens when one calculates some large matrix (such as the
+ * global translation matrix) in several threads and cblas_zgemm() 
+ * is called on relatively small submatrices. 
+ * Because the submatrices are small, we can use a naïve,
+ * serial implementation of cblas_zgemm() as a workaround without a substantial
+ * impact on performance.
+ *
+ * If included together with <cblas.h>, this must be include _afterwards_ because of the typedefs!
+ */
 #ifndef QPMSBLAS_H
 #define QPMSBLAS_H
 #define QPMS_BLAS_INDEX_T long long int
@ -11,6 +24,7 @@ typedef enum {CblasNonUnit=131, CblasUnit=132} CBLAS_DIAG;
 typedef enum {CblasLeft=141, CblasRight=142} CBLAS_SIDE;
 #endif

+/// Naïve serial reimplementation of cblas_zgemm.
 void qpms_zgemm(CBLAS_LAYOUT Order, CBLAS_TRANSPOSE TransA, CBLAS_TRANSPOSE TransB,
 		const QPMS_BLAS_INDEX_T M, const QPMS_BLAS_INDEX_T N, const QPMS_BLAS_INDEX_T K,
 		const _Complex double *alpha, const _Complex double *A, const QPMS_BLAS_INDEX_T lda,
--- a/qpms/tiny_inlines.h
+++ b/qpms/tiny_inlines.h
@ -1,3 +1,6 @@
+/*! \file tiny_inlines.h
+ * \brief Simple but frequently used inline functions and macros.
+ */
 #ifndef TINY_INLINES_H
 #define TINY_INLINES_H
 #include <stdlib.h>