Commit cb308b85 authored by Giovanni La Mura's avatar Giovanni La Mura
Browse files

Added doxygen inline documentation expansion

parent 3cdb591f

src/include/tfrfme.h

+18 −18
Original line number Diff line number Diff line
@@ -28,7 +28,7 @@ class Swap1 { 
protected:

  //! Index of the last element to be filled.

  int _last_index;

  //! Number of vector coordinates. QUESTION: correct?

  //! Number of beam description wave-numbers.

  int _nkv;

  //! NLMMT = 2 * LM * (LM + 2)

  int _nlmmt;
@@ -69,7 +69,7 @@ public: 
  /*! \brief Swap1 instance constructor.

   *

   * \param lm: `int` Maximum field expansion order.

   * \param _nkv: `int` Number of vector coordinates. QUESTION: correct?

   * \param nkv: `int` Number of beam description wave numbers.

   */

  Swap1(int lm, int nkv);
@@ -130,7 +130,7 @@ protected: 
  int _last_vector;

  //! Index of the last matrix element to be filled.

  int _last_matrix;

  //! Number of vector coordinates. QUESTION: correct?

  //! Number of beam description wave numbers.

  int _nkv;

  //! Contiguous vector of VKZM matrix.

  double *vec_vkzm;
@@ -152,13 +152,13 @@ protected: 
  double _delxyz;

  //! QUESTION: definition?

  double _vknmx;

  //! QUESTION: definition?

  //! Wave number grid spacing.

  double _delk;

  //! QUESTION: definition?

  //! Square of wave number grid spacing.

  double _delks;

  //! NLMMT = LM * (LM + 2) * 2

  int _nlmmt;

  //! Number of radial vector coordinates. QUESTION: correct?

  //! Number of radial vector coordinates.

  int _nrvc;



  /*! \brief Load a Swap2 instance from a HDF5 binary file.
@@ -192,7 +192,7 @@ public: 
  const int &last_vector = _last_vector;

  //! Read-only view on the index of the last matrix element to be filled.

  const int &last_matrix = _last_matrix;

  //! Read-only view on the number of vector coordinates. QUESTION: correct?

  //! Read-only view on the number of beam description wave numbers.

  const int &nkv = _nkv;

  //! QUESTION: definition?

  double *vkv;
@@ -222,12 +222,12 @@ public: 
  const double &delks = _delks;

  //! NLMMT = LM * (LM + 2) * 2

  const int &nlmmt = _nlmmt;

  //! Number of radial vector coordinates. QUESTION: correct?

  //! Read-only view on the number of radial vector coordinates.

  const int &nrvc = _nrvc;



  /*! \brief Swap2 instance constructor.

   *

   * \param nkv: `int` Number of vector coordinates. QUESTION: correct?

   * \param nkv: `int` Number of beam description wave numbers.

   */

  Swap2(int nkv);
@@ -252,7 +252,7 @@ public: 


  /*! \brief Calculate the necessary amount of memory to create a new instance.

   *

   * \param nkv: `int` Number of radial vector coordinates. QUESTION: correct?

   * \param nkv: `int` Number of beam description wave numbers.

   * \return size: `long` The necessary memory size in bytes.

   */

  static long get_size(int nkv);
@@ -316,11 +316,11 @@ protected: 
  int _nlmmt;

  //! NRVC = NXV * NYV * NZV

  int _nrvc;

  //! Field expansion mode identifier.

  //! Beam description mode.

  int _lmode;

  //! Maximum field expansion order.

  int _lm;

  //! QUESTION: definition?

  //! Number of beam description wave numbers.

  int _nkv;

  //! Number of computed X coordinates.

  int _nxv;
@@ -332,11 +332,11 @@ protected: 
  double _vk;

  //! External medium refractive index

  double _exri;

  //! QUESTION: definition?

  //! Numerical aperture.

  double _an;

  //! QUESTION: definition?

  //! Filling factor.

  double _ff;

  //! QUESTION: definition?

  //! Lens transmission.

  double _tra;

  //! QUESTION: definition?

  double _spd;
@@ -402,11 +402,11 @@ public: 
  const double& vk = _vk;

  //! Read-only view on external medium refractive index

  const double& exri = _exri;

  //! QUESTION: definition?

  //! Read-only view on numeric aperture.

  const double& an = _an;

  //! QUESTION: definition?

  //! Read-only view on filling factor.

  const double& ff = _ff;

  //! QUESTION: definition?

  //! Read-only view on lens transmission.

  const double& tra = _tra;

  //! QUESTION: definition?

  const double& spd = _spd;

src/trapping/cfrfme.cpp

+91 −0
Original line number Diff line number Diff line
@@ -66,6 +66,35 @@ 
#endif



#ifdef USE_TARGET_OFFLOAD

/*! \brief Specialized function to map data on the device.

 *

 * This function prepares a target device to perform the trapping calulation

 * loop by allocating the device memory and copying the input data. The

 * operation has been separated from the main loop execution for performance

 * evaluation purposes and in order to grant data data communication occurs

 * only when strictly necessary.

 *

 * \param vec_wsum: `dcomplex *` Vector of weight sums to be computed.

 * \param size_vec_wsum: `int` Size of the vector of weight sums to be computed.

 * \param global_vec_w: `dcomplex *` Global space for weight vectors visible to

 * all threads.

 * \param int size_global_vec_w: `int` Size of the global weight vector space.

 * \param vec_tt1_wk: `dcomplex *` Vector of swap object weights.

 * \param int size_vec_tt1_wk: `int` Size of the swap object weights vector.

 * \param vkv: `double *` Vector of beam fields wave numbers (with size = NLMMT).

 * \param _xv: `double *` Vector of x-coordinate calculation spacing.

 * \param nxv: `int` Number of x-coordinates used in the calculation.

 * \param _yv: `double *` Vector of y-coordinate calculation spacing.

 * \param nyv: `int` Number of y-coordinates used in the calculation.

 * \param _zv: `double *` Vector of z-coordinate calculation spacing.

 * \param nzv: `int` Number of z-coordinates used in the calculation.

 * \param vec_vkzm: `double *` Vectorized VKZM matrix (size = NLMMT x NLMMT)

 * \param jlmf: `int` First order of the calculation.

 * \param jlml: `int` Last order of the calculation.

 * \param nkv: `int` Number of beam vector wave-numbers.

 * \param nlmmt: `int` NLMMT = 2 x LM x (LM + 2), with LM as maximum field

 * expansion order.

 */

void map_data(

  dcomplex *vec_wsum, int size_vec_wsum, dcomplex *global_vec_w, int size_global_vec_w,

  const dcomplex *vec_tt1_wk, int size_vec_tt1_wk, double *vkv, double *_xv, int nxv,
@@ -73,6 +102,40 @@ void map_data( 
  int nkv, int nlmmt

);



/*! \brief Specialized function to perform GPU-offloaded trapping loop.

 *

 * The offload of GPU operations through interface layers, such as OpenMP,

 * can become implementation dependent, especially when attempting to target

 * generic hardware. In this case, not all the compilers are able to obtain

 * a correct solution, especially when loop optimization is requested. In

 * order to preserve the work-flow integrity when compiling in high optimization,

 * therefore, it is useful to encapsulate the GPU oflloaded loop in a separate

 * function, which takes care of bracketing the target code region allowing

 * for the loop execution on a generic target device.

 *

 * \param vec_wsum: `dcomplex *` Vector of weight sums to be computed.

 * \param size_vec_wsum: `int` Size of the vector of weight sums to be computed.

 * \param global_vec_w: `dcomplex *` Global space for weight vectors visible to

 * all threads.

 * \param int size_global_vec_w: `int` Size of the global weight vector space.

 * \param vec_tt1_wk: `dcomplex *` Vector of swap object weights.

 * \param int size_vec_tt1_wk: `int` Size of the swap object weights vector.

 * \param vkv: `double *` Vector of beam fields wave numbers (with size = NLMMT).

 * \param _xv: `double *` Vector of x-coordinate calculation spacing.

 * \param nxv: `int` Number of x-coordinates used in the calculation.

 * \param _yv: `double *` Vector of y-coordinate calculation spacing.

 * \param nyv: `int` Number of y-coordinates used in the calculation.

 * \param _zv: `double *` Vector of z-coordinate calculation spacing.

 * \param nzv: `int` Number of z-coordinates used in the calculation.

 * \param vec_vkzm: `double *` Vectorized VKZM matrix (size = NLMMT x NLMMT)

 * \param jlmf: `int` First order of the calculation.

 * \param jlml: `int` Last order of the calculation.

 * \param nkv: `int` Number of beam vector wave-numbers.

 * \param nlmmt: `int` NLMMT = 2 x LM x (LM + 2), with LM as maximum field

 * expansion order.

 * \param delks: `double` Square of the wave-number grid spacing.

 * \param frsh: `double` Instrumental offset along beam z-axis.

 */

void offload_loop(

  dcomplex *vec_wsum, int size_vec_wsum, dcomplex *global_vec_w, int size_global_vec_w,

  const dcomplex *vec_tt1_wk, int size_vec_tt1_wk, double *vkv, double *_xv, int nxv,
@@ -80,6 +143,34 @@ void offload_loop( 
  int nkv, int nlmmt, double delks, double frsh

);



/*! \brief Specialized function to clean memory on the device.

 *

 * This function cleans the device memory after the calculation loop and

 * copies the result back to the host system. The operation has been separated

 * from the main loop execution for performance evaluation purposes and in

 * order to grant data data communication occurs only when strictly necessary.

 *

 * \param vec_wsum: `dcomplex *` Vector of weight sums to be computed.

 * \param size_vec_wsum: `int` Size of the vector of weight sums to be computed.

 * \param global_vec_w: `dcomplex *` Global space for weight vectors visible to

 * all threads.

 * \param int size_global_vec_w: `int` Size of the global weight vector space.

 * \param vec_tt1_wk: `dcomplex *` Vector of swap object weights.

 * \param int size_vec_tt1_wk: `int` Size of the swap object weights vector.

 * \param vkv: `double *` Vector of beam fields wave numbers (with size = NLMMT).

 * \param _xv: `double *` Vector of x-coordinate calculation spacing.

 * \param nxv: `int` Number of x-coordinates used in the calculation.

 * \param _yv: `double *` Vector of y-coordinate calculation spacing.

 * \param nyv: `int` Number of y-coordinates used in the calculation.

 * \param _zv: `double *` Vector of z-coordinate calculation spacing.

 * \param nzv: `int` Number of z-coordinates used in the calculation.

 * \param vec_vkzm: `double *` Vectorized VKZM matrix (size = NLMMT x NLMMT)

 * \param jlmf: `int` First order of the calculation.

 * \param jlml: `int` Last order of the calculation.

 * \param nkv: `int` Number of beam vector wave-numbers.

 * \param nlmmt: `int` NLMMT = 2 x LM x (LM + 2), with LM as maximum field

 * expansion order.

 */

void unmap_data(

  dcomplex *vec_wsum, int size_vec_wsum, dcomplex *global_vec_w, int size_global_vec_w,

  const dcomplex *vec_tt1_wk, int size_vec_tt1_wk, double *vkv, double *_xv, int nxv,