From 2c544bf0e81dd8727e4227535807cd6f2b73f2cf Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Mon, 20 Jan 2025 16:32:12 +0100
Subject: [PATCH] Add doxygen inline documentation
---
src/include/Commons.h | 4 ++++
src/include/Configuration.h | 28 +++++++++--------------
src/include/clu_subs.h | 2 +-
src/include/file_io.h | 45 +++++++++++++++++++------------------
src/include/logging.h | 4 ++--
src/scripts/pydynrange.py | 25 ++++++++++++++++++---
6 files changed, 63 insertions(+), 45 deletions(-)
diff --git a/src/include/Commons.h b/src/include/Commons.h
index 68881585..12f85a32 100644
--- a/src/include/Commons.h
+++ b/src/include/Commons.h
@@ -127,9 +127,13 @@ public:
//! \brief Wave number.
double wn;
double xip;
+ //! \brief Number of scales (wavelengths) to be computed.
int number_of_scales;
+ //! \brief Size of the block of scales handled by the current process.
int xiblock;
+ //! \brief Index of the first scale handled by the current process.
int firstxi;
+ //! \brief Index of the last scale handled by the current process.
int lastxi;
//! \brief ID of the GPU used by one MPI process.
int proc_device;
diff --git a/src/include/Configuration.h b/src/include/Configuration.h
index 36eae2ff..81477ab6 100644
--- a/src/include/Configuration.h
+++ b/src/include/Configuration.h
@@ -67,17 +67,17 @@ protected:
int _le;
//! \brief Maximum dimension of allocated matrix allowance (deprecated).
np_int _mxndm;
- //! \brief QUESTION: definition?
+ //! \brief Flag for intensity.
int _iavm;
//! \brief Incident field polarization status (0 - linear, 1 - circular).
int _in_pol;
- //! \brief Number of transition points. QUESTION: correct?
+ //! \brief Number of points for transition layer integration.
int _npnt;
- //! \brief Transition smoothness. QUESTION: correct?
+ //! \brief Number of points for non-transition layer integration.
int _npntts;
//! \brief Type of meridional plane definition.
int _isam;
- //! \brief Transition matrix layer ID. QUESTION: correct?
+ //! \brief Scale index of the T-matrix output.
int _jwtm;
//! \brief Incident field initial azimuth.
double _in_theta_start;
@@ -121,17 +121,17 @@ public:
const int& le = _le;
//! \brief Read only view on maximum dimension of allocated matrix allowance (deprecated).
const np_int& mxndm = _mxndm;
- //! \brief QUESTION: definition?
+ //! \brief Read only view on the intensity mode flag.
const int& iavm = _iavm;
//! \brief Read only view on incident field polarization status (0 - linear, 1 - circular).
const int& in_pol = _in_pol;
- //! \brief Read only view on number of transition points. QUESTION: correct?
+ //! \brief Read only view on number of points for transition layer integration.
const int& npnt = _npnt;
- //! \brief Read only view on transition smoothness. QUESTION: correct?
+ //! \brief Read only view on number of points for non-transition layer integration.
const int& npntts = _npntts;
//! \brief Read only view on type of meridional plane definition.
const int& isam = _isam;
- //! \brief Read only view on transition matrix layer ID. QUESTION: correct?
+ //! \brief Read only view on scale index for T-matrix output.
const int& jwtm = _jwtm;
//! \brief Read only view on incident field initial azimuth.
const double& in_theta_start = _in_theta_start;
@@ -157,14 +157,6 @@ public:
const double& sc_phi_step = _sc_phi_step;
//! \brief Read only view on scattered field final elevation.
const double& sc_phi_end = _sc_phi_end;
- /*
- //! \brief Read only view on vector of spherical components X coordinates.
- const double *sph_x = _sph_x;
- //! \brief Read only view on vector of spherical components Y coordinates.
- const double *sph_y = _sph_y;
- //! \brief Read only view on vector of spherical components Z coordinates.
- const double *sph_z = _sph_z;
- */
/*! \brief Build a scattering geometry configuration structure.
*
@@ -394,6 +386,7 @@ public:
* memory structures.
*
* \param nsph: `int` The number of spheres in the simulation.
+ * \param configs: `int` Number of spherical monometer configuration types.
* \param scale_vector: `double*` The radiation-particle scale vector.
* \param nxi: `int` The number of radiation-particle scalings.
* \param variable_name: `string` The name of the radiation-particle scaling type.
@@ -539,7 +532,8 @@ public:
* This is a specialized function to access a scale (generally a wavelength),
* through its index.
*
- * \param index: `int` Index of the scale to be retrieved.
+ * \param row: `int` Row index of the element to be retrieved.
+ * \param column: `int` Column index of the element to be retrieved.
* \return scale: `double` The desired scale.
*/
double get_rcf(int row, int column) { return _rcf[row][column]; }
diff --git a/src/include/clu_subs.h b/src/include/clu_subs.h
index 38dfcba5..9c5feffe 100644
--- a/src/include/clu_subs.h
+++ b/src/include/clu_subs.h
@@ -131,7 +131,7 @@ void crsm1(double vk, double exri, ParticleDescriptor *c1);
*/
dcomplex ghit_d(
int ihi, int ipamo, int nbl, int l1, int m1, int l2, int m2,
- ParticleDescriptor *c1, dcomplex *rac3j
+ ParticleDescriptor *c1, double *rac3j
);
/*! \brief Compute the transfer vector from N2 to N1.
diff --git a/src/include/file_io.h b/src/include/file_io.h
index df475bf7..250acd33 100644
--- a/src/include/file_io.h
+++ b/src/include/file_io.h
@@ -228,7 +228,6 @@ public:
* \param rhs: `const VirtualAsciiFile&` The refence to the VirtualAsciiFile to be inserted.
* \param start: `int32_t` The first line to be inserted (optional, default is 0).
* \param end: `int32_t` The last line to be inserted (optional, default is 0 to read all).
- * \param line: `const string&` Reference to a string representing the line.
* \return result: `int` A result code (0 if successful).
*/
int insert(int32_t position, VirtualAsciiFile& rhs, int32_t start = 0, int32_t end = 0);
@@ -275,18 +274,37 @@ public:
//! \brief Read only view of `_data_size`.
const size_t & data_size = _data_size;
- /*! \brief VirtualBinaryLine instance constructor.
+ /*! \brief VirtualBinaryLine instance constructor for `int` data.
*
- * \param mydata: `int, double, long, float, complex, or dcomplex`piece of data to put in the line.
+ * \param mydata: `int` The piece of data to put in the line.
*/
VirtualBinaryLine(int mydata);
+
+ /*! \brief VirtualBinaryLine instance constructor for `long` data.
+ *
+ * \param mydata: `long` The piece of data to put in the line.
+ */
VirtualBinaryLine(long mydata);
+
+ /*! \brief VirtualBinaryLine instance constructor for single-precision floating point data.
+ *
+ * \param mydata: `float` The piece of data to put in the line.
+ */
VirtualBinaryLine(float mydata);
+
+ /*! \brief VirtualBinaryLine instance constructor for double-precision floating point data.
+ *
+ * \param mydata: `double` The piece of data to put in the line.
+ */
VirtualBinaryLine(double mydata);
- // VirtualBinaryLine(complex mydata);
+
+ /*! \brief VirtualBinaryLine instance constructor for `dcomplex` data.
+ *
+ * \param mydata: `dcomplex` The piece of data to put in the line.
+ */
VirtualBinaryLine(dcomplex mydata);
- /*! \brief VirtualBinaryLine copy constructor.
+ /*! \brief VirtualBinaryLine copy constructor.
*
* \param rhs: `const VirtualBinaryLine&` Reference to a VirtualBinaryLine instance.
*/
@@ -367,23 +385,6 @@ public:
*/
int append_to_disk(const std::string& file_name);
- // /*! \brief Insert another VirtualBinaryFile at a given position.
- // *
- // * This function inserts a target VirtualBinaryFile in the current one at the given
- // * position. Optionally, a range of lines to be inserted can be specified, otherwise
- // * the full content of the target file is inserted. This function DOES NOT increase
- // * the size of the inner storage and it can only be used if the inner storage has
- // * already been adjusted to contain the insertion target.
- // *
- // * \param position: `int32_t` The position at which the other file is inserted in this one.
- // * \param rhs: `const VirtualBinaryFile&` The refence to the VirtualBinaryFile to be inserted.
- // * \param start: `int32_t` The first line to be inserted (optional, default is 0).
- // * \param end: `int32_t` The last line to be inserted (optional, default is 0 to read all).
- // * \param line: `const string&` Reference to a string representing the line.
- // * \return result: `int` A result code (0 if successful).
- // */
- // int insert(int32_t position, VirtualBinaryFile& rhs, int32_t start = 0, int32_t end = 0);
-
/*! \brief Get the number of lines in the current instance.
*
* \return size: `int32_t` The number of lines in the VirtualBinaryFile instance.
diff --git a/src/include/logging.h b/src/include/logging.h
index e58522a1..f5fc0615 100644
--- a/src/include/logging.h
+++ b/src/include/logging.h
@@ -65,13 +65,13 @@ class Logger {
* \param threshold: `int` Threshold of the messages to be included in log. Can
* be `LOG_DEBG` (log everything), `LOG_INFO` (give detailed information),
* `LOG_WARN` (log odd looking effects), or `LOG_ERRO` (print error messages,
- * `always active). The default behaviour is `LOG_WARN`.
+ * always active). The default behaviour is `LOG_WARN`.
* \param logging_output: `FILE *` Pointer to an open output file for common messages
* (optional, default is `stdout`).
* \param error_output: `FILE *` Pointer to an open output file for error messages
* (optional, default is `stderr`).
*/
- Logger(int threshold, FILE *logging_output=stdout, FILE *error_output=stderr);
+ Logger(int threshold, FILE *logging_output = stdout, FILE *error_output = stderr);
/*! \brief Logger instance destroyer.
*/
diff --git a/src/scripts/pydynrange.py b/src/scripts/pydynrange.py
index b9c74ca8..491f68f8 100755
--- a/src/scripts/pydynrange.py
+++ b/src/scripts/pydynrange.py
@@ -37,27 +37,44 @@ from sys import argv, stdout
#
# \returns exit_code: `int` 0 on successful completion.
class PlotData:
- # \brief PlotData instance constructor.
+ ## \brief PlotData instance constructor.
def __init__(self):
+ ## \brief Maximum real part value.
self.max_real = -1.0
+ ## \brief Maximum imaginary part value.
self.max_imag = -1.0
+ ## \brief Maximum absolute value.
self.max_absl = -1.0
+ ## \brief Minimum (most negative) real part value.
self.min_real = 1.0
+ ## \brief Minimum (most negative) imaginary part value.
self.min_imag = 1.0
+ ## \brief Smallest absolute value.
self.sml_absl = 1.0
+ ## \brief Smallest absolute real part value.
self.sml_real = 1.0
+ ## \brief Smallest absolute imaginary part value.
self.sml_imag = 1.0
+ ## \brief Histogram of absolute values.
self.absl_hist = [0 for i in range(-99, 100)]
+ ## \brief Histogram of real values.
self.real_hist = [0 for i in range(-99, 100)]
+ ## \brief Histogram of imaginary values.
self.imag_hist = [0 for i in range(-99, 100)]
+ ## \brief Maximum real order of magnitude.
self.max_real_mag = -100
+ ## \brief Minimum real order of magnitude.
self.min_real_mag = 100
+ ## \brief Maximum imaginary order of magnitude.
self.max_imag_mag = -100
+ ## \brief Minimum imaginary order of magnitude.
self.min_imag_mag = 100
+ ## \brief Maximum absolute order of magnitude.
self.max_absl_mag = -100
+ ## \brief Minimum absolute order of magnitude.
self.min_absl_mag = 100
- # \brief Print a text log of the dynamic range.
+ ## \brief Print a text log of the dynamic range.
def log_dynamic_range(self):
print(" MAX( ABS[AM] ) = %14.7e"%self.max_absl)
print(" MIN( ABS[AM] ) = %14.7e"%self.sml_absl)
@@ -69,7 +86,9 @@ class PlotData:
print("MIN( ABS( IMAG[AM] ) ) = %14.7e"%self.sml_imag)
return
- # \brief Make histograms of dynamic range with matplotlib.
+ ## \brief Make histograms of dynamic range with matplotlib.
+ #
+ # \param config: `dict` Dictionary of configuration options.
def plot_dynamic_range(self, config):
import matplotlib.pyplot as plt
import numpy as np
--
GitLab