QPMS
/
qpms
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

qpms_types.h doxygen update 

Former-commit-id: 79bd4323d54f9f6d751b63d926943a66548e6cbd
This commit is contained in:
Marek Nečada 2019-02-27 13:31:20 +02:00
parent cbb6ee7846
commit c51e7b5851
1 changed files with 42 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
qpms/qpms_types.h
View File

@ -17,14 +17,14 @@
// integer index types // integer index types
typedef int qpms_lm_t; typedef int qpms_lm_t;
/// Type for spherical harmonic degree l. /// Type for spherical harmonic degree \a l.
typedef int qpms_l_t; /* can't be unsigned because of the behaviour under - operator; typedef int qpms_l_t; /* can't be unsigned because of the behaviour under the - operator;
also -1 needed as an invalid value for scalar waves. */ also -1 needed as an invalid value for scalar waves. */
/// Type for spherical harmonic order m. /// Type for spherical harmonic order \a m.
typedef qpms_lm_t qpms_m_t; typedef qpms_lm_t qpms_m_t;
/// Type for the (l,m) multiindex of transversal (M or N-type) VSWFs. /// Type for the (\a l, \a m) multiindex of transversal (\a M or \a N -type) VSWFs.
/** This corresponds to the typical memory layout for various coefficient etc. /** This corresponds to the typical memory layout for various coefficient etc.
* Corresponds to the l-primary, m-secondary ordering, i.e. * Corresponds to the l-primary, m-secondary ordering, i.e.
* \f[ y = 0: l = 1, m = -1, \f] * \f[ y = 0: l = 1, m = -1, \f]
@ -32,39 +32,45 @@ typedef qpms_lm_t qpms_m_t;
* \f[ y = 2: l = 1, m = +1, \f] * \f[ y = 2: l = 1, m = +1, \f]
* \f[ y = 3: l = 2, m = -2, \f] * \f[ y = 3: l = 2, m = -2, \f]
* ... * ...
*
* See also indexing.h.
*/ */
typedef size_t qpms_y_t; typedef size_t qpms_y_t;
/// Type for the (l,m) multiindex of spherical harmonics, including (0,0). /// Type for the (\a l, \a m) multiindex of spherical harmonics, including (0, 0).
/** This differs from qpms_y_t by being shifted by one and including /** This differs from qpms_y_t by being shifted by one and including
* the l = 0 option. Suitable also for scalar and longitudinal waves. * the \a l = 0 option. Suitable also for scalar and longitudinal waves.
* Corresponds to the l-primary, m-secondary ordering, i.e. * Corresponds to the \a l -primary, \a m -secondary ordering, i.e.
* \f[ y = 0: l = 0, m = 0, \f] * \f[ y = 0: l = 0, m = 0, \f]
* \f[ y = 1: l = 1, m = -1, \f] * \f[ y = 1: l = 1, m = -1, \f]
* \f[ y = 2: l = 1, m = 0, \f] * \f[ y = 2: l = 1, m = 0, \f]
* \f[ y = 3: l = 1, m = +1, \f] * \f[ y = 3: l = 1, m = +1, \f]
* \f[ y = 4: l = 2, m = -2, \f] * \f[ y = 4: l = 2, m = -2, \f]
* ... * ...
*
* See also indexing.h.
*/ */
typedef size_t qpms_y_sc_t; typedef size_t qpms_y_sc_t;
/// Codes of the VSWF types (electric/N, magnetic/M, longitudinal/L). /// Codes of the VSWF types (electric/N, magnetic/M, longitudinal/L).
typedef enum { typedef enum {
QPMS_VSWF_ELECTRIC = 2, ///< "Electric" ($N$-type) transversal wave. QPMS_VSWF_ELECTRIC = 2, ///< "Electric" (\a N -type) transversal wave.
QPMS_VSWF_MAGNETIC = 1, ///< "Magnetic" ($M$-type) transversal wave. QPMS_VSWF_MAGNETIC = 1, ///< "Magnetic" (\a M -type) transversal wave.
QPMS_VSWF_LONGITUDINAL = 0 ///< Longitudinal ($L$-type) wave (not relevant for radiation). QPMS_VSWF_LONGITUDINAL = 0 ///< Longitudinal (\a L -type) wave (not relevant for radiation).
} qpms_vswf_type_t; } qpms_vswf_type_t;
// FIXME DOC The references to the functions do not work in doxygen:
/// Exhaustive index type for VSWF basis functions. /// Exhaustive index type for VSWF basis functions.
/** Carries information about the wave being of M/N/L (magnetic, electric, /** Carries information about the wave being of \a M/N/L (magnetic, electric,
* or longitudinal) type, as well as the wave's degree and order (l, m). * or longitudinal) type, as well as the wave's degree and order (\a l, \a m).
* *
* The formula is 4 * (qpms_y_sc_t) y_sc + (qmps_vswf_type_t) type_code, * The formula is 4 * (qpms_y_sc_t) y_sc + (qmps_vswf_type_t) type_code,
* but don't rely on this and use the functions * but don't rely on this and use the functions
* qpms_tmn2uvswfi() and qpms_uvswfi2tmn() * \ref qpms_tmn2uvswfi() and \ref qpms_uvswfi2tmn()
* from qpms_types.h instead * from qpms_types.h instead
* as the formula might change in future versions. * as the formula might change in future versions.
*
* See also indexing.h.
*/ */
typedef unsigned long long qpms_uvswfi_t; typedef unsigned long long qpms_uvswfi_t;
@ -76,22 +82,25 @@ typedef enum {
QPMS_ENOMEM = 8 ///< Out of memory. QPMS_ENOMEM = 8 ///< Out of memory.
} qpms_errno_t; } qpms_errno_t;
/// Vector spherical wavefuction normalisation (and sign) convention codes. /// Vector spherical wavefuction normalisation (and sign) convention codes.
/** Throughout the literature, various conventions for VSWF bases are used. /** Throughout the literature, various conventions for VSWF bases are used.
* The meaningful ones are the "power" and "spherical harmonic" normalisation * The meaningful ones are the "power" and "spherical harmonic" normalisation
* conventions, as the (l,m) and (l,-m) waves of the same type have the same * conventions, as the (\a l, \a m) and (\a l, \a −m) waves of the same type have the same
* intensities. * intensities.
* One might also encounter a very inconvenient and messy "antinormalisation" * One might also encounter a very inconvenient and messy "antinormalisation"
* used in Xu (TODO reference). * used in Xu (TODO reference).
* *
* Moreover, VSWFs might use various sign convention. Usually they either * Moreover, VSWFs might use various sign convention. Usually they either
* carry the Condon-Shortley phase $(-1)^m$ or not, which is also saved here. * carry the Condon-Shortley phase \f$ (-1)^m \f$ or not, which is also saved here.
* *
* TODO references and exact definitions. * TODO references and exact definitions.
*/ */
//const int QPMS_NORMALISATION_T_CSBIT = 128;
#define QPMS_NORMALISATION_T_CSBIT 128
typedef enum { typedef enum {
#define QPMS_NORMALISATION_T_CSBIT 128 ///< A flag used in qpms_normalisation_t indicating the Condon-Shortley phase.
#ifdef USE_XU_ANTINORMALISATION #ifdef USE_XU_ANTINORMALISATION
// As in TODO // As in TODO
QPMS_NORMALISATION_XU = 4, ///< such that the numerical values in Xu's tables match, not recommended to use otherwise QPMS_NORMALISATION_XU = 4, ///< such that the numerical values in Xu's tables match, not recommended to use otherwise
@ -199,45 +208,46 @@ typedef enum {
} qpms_bessel_t; } qpms_bessel_t;
// coordinate system types // coordinate system types
/// 3D cartesian coordinates. /// 3D cartesian coordinates. See also vectors.h.
typedef struct cart3_t { typedef struct cart3_t {
double x, y, z; double x, y, z;
} cart3_t; } cart3_t;
/// 3D complex (actually 6D) coordinates. /// 3D complex (actually 6D) coordinates. See also vectors.h.
typedef struct ccart3_t { typedef struct ccart3_t {
complex double x, y, z; complex double x, y, z;
} ccart3_t; } ccart3_t;
/// 2D cartesian coordinates. /// 2D cartesian coordinates. See also vectors.h.
/** See also vectors.h */
typedef struct cart2_t { typedef struct cart2_t {
double x, y; double x, y;
} cart2_t; } cart2_t;
/// Spherical coordinates. /// Spherical coordinates. See also vectors.h.
typedef struct sph_t { typedef struct sph_t {
double r, theta, phi; double r, theta, phi;
} sph_t; } sph_t;
/// Spherical coordinates with complex radial component. /// Spherical coordinates with complex radial component. See also vectors.h.
typedef struct csph_t { // Do I really need this??? typedef struct csph_t { // Do I really need this???
complex double r; complex double r;
double theta, phi; double theta, phi;
} csph_t; } csph_t;
/// 3D complex vector components in local spherical basis. /// 3D complex vector components in local spherical basis. See also vectors.h.
typedef struct csphvec_t { typedef struct csphvec_t {
complex double rc, thetac, phic; complex double rc, thetac, phic;
} csphvec_t; } csphvec_t;
/// 2D polar coordinates. /// 2D polar coordinates. See also vectors.h.
typedef struct pol_t { typedef struct pol_t {
double r, phi; double r, phi;
} pol_t; } pol_t;
/// Union type capable to contain various 1D, 2D and 3D coordinates. /// Union type capable to contain various 1D, 2D and 3D coordinates.
typedef union anycoord_point_t { typedef union anycoord_point_t {
double z; /// 1D cartesian coordinate. double z; ///< 1D cartesian coordinate.
cart3_t cart3; cart3_t cart3;
cart2_t cart2; cart2_t cart2;
sph_t sph; sph_t sph;
@ -260,21 +270,21 @@ typedef enum {
* Internaly represented as a pair of complex numbers, * Internaly represented as a pair of complex numbers,
* \f$ Q_a = Q_1 + iQ_z, Q_b = Q_y + i Q_x\f$. * \f$ Q_a = Q_1 + iQ_z, Q_b = Q_y + i Q_x\f$.
* *
* Check wigner.h for "methods". * See wigner.h for "methods".
*/ */
typedef struct qpms_quat_t { typedef struct qpms_quat_t {
complex double a, b; complex double a, b;
} qpms_quat_t; } qpms_quat_t;
/// Quaternion type as four doubles. /// Quaternion type as four doubles.
/** Check wigner.h for "methods". /** See wigner.h for "methods".
*/ */
typedef struct qpms_quat4d_t { typedef struct qpms_quat4d_t {
double c1, ci, cj, ck; double c1, ci, cj, ck;
} qpms_quat4d_t; } qpms_quat4d_t;
/// 3D improper rotations represented as a quaternion and a sign of the determinant. /// 3D improper rotations represented as a quaternion and a sign of the determinant.
/** Check wigner.h for "methods". /** See wigner.h for "methods".
*/ */
typedef struct qpms_irot3_t { typedef struct qpms_irot3_t {
qpms_quat_t rot; ///< Quaternion representing the rotation part. qpms_quat_t rot; ///< Quaternion representing the rotation part.
@ -289,7 +299,7 @@ typedef struct qpms_irot3_t {
* A typical use case would be when only even/odd fields wrt. z-plane * A typical use case would be when only even/odd fields wrt. z-plane
* mirror symmetry are considered. * mirror symmetry are considered.
* *
* Check vswf.h for "methods". * See vswf.h for "methods".
*/ */
typedef struct qpms_vswf_set_spec_t { typedef struct qpms_vswf_set_spec_t {
size_t n; ///< Actual number of VSWF indices included in ilist. size_t n; ///< Actual number of VSWF indices included in ilist.
@ -309,10 +319,10 @@ typedef int32_t qpms_ss_tmi_t;
typedef int32_t qpms_ss_pi_t; typedef int32_t qpms_ss_pi_t;
// These types are mainly used in groups.h: // These types are mainly used in groups.h:
/// Finite group member index. /// Finite group member index. See also groups.h.
typedef int qpms_gmi_t; typedef int qpms_gmi_t;
/// Irreducible representation index /// Irreducible representation index. See also groups.h.
typedef int qpms_iri_t; typedef int qpms_iri_t;
/// Permutation representation of a group element. /// Permutation representation of a group element.