BFieldMesh add comments

BFieldMesh add comments

ping @schaffer

MagneticField/MagFieldElements/MagFieldElements/BFieldMesh.h

 /*
-  Copyright (C) 2002-2020 CERN for the benefit of the ATLAS collaboration
+  Copyright (C) 2002-2021 CERN for the benefit of the ATLAS collaboration
 */
 
-/*
- * BFieldMesh.h
- * Generic 3-d mesh representing a simple field map.
- * The field type is templated - it may be short (for the toroid) or double (for
- * the solenoid)
+/**
+ *
+ * @class BFieldMesh
+ *
+ * A 3-d mesh (axes z,r,phi) representing a simple field map.
+ * 
+ * The mesh is made up from 'cells'
+ * We hold numz, numr , numphi positions defining
+ * the corners of the cells.
+ *
+ * Then we have
+ * numz X numr X numphi field values at these corners
+ *
+ * The field type is templated - it may be short (for the toroid)
+ * or double (for the solenoid)
  *
  * Masahiro Morii, Harvard University
  *
@@ -16,9 +26,9 @@
 #ifndef BFIELDMESH_H
 #define BFIELDMESH_H
 
+#include "CxxUtils/restrict.h"
 #include "MagFieldElements/BFieldCache.h"
 #include "MagFieldElements/BFieldVector.h"
-#include "CxxUtils/restrict.h"
 #include <array>
 #include <cmath>
 #include <vector>
@@ -33,7 +43,7 @@ public:
   BFieldMesh& operator=(const BFieldMesh&) = default;
   BFieldMesh& operator=(BFieldMesh&&) = default;
   ~BFieldMesh() = default;
-  // constructor
+  /** @brief constructor with mesh dimensions and scale*/
   BFieldMesh(double zmin,
              double zmax,
              double rmin,
@@ -41,51 +51,68 @@ public:
              double phimin,
              double phimax,
              double bscale);
-  // set ranges
+
+  /** @brief set mesh range/dimensions */
   void setRange(double zmin,
                 double zmax,
                 double rmin,
                 double rmax,
                 double phimin,
                 double phimax);
-  // set bscale
+
+  /** @brief set B scale */
   void setBscale(double bscale);
-  // scale bscale by a factor
+  /**  @brief scale B scale by a factor*/
   void scaleBscale(double factor);
-  // allocate space to vectors
+  /**  @brief allocate space to vectors */
   void reserve(int nz, int nr, int nphi, int nfield);
+  /**  @brief allocate space to vectors */
   void reserve(int nz, int nr, int nphi);
-  // add elements to vectors
-  void appendMesh(int i, double mesh);
+  /** @brief add a position for a cell corner for an  axis  */
+  void appendMesh(int axis, double value);
+  /** @brief append a filed vector  */
   void appendField(const BFieldVector<T>& field);
-  // build Look Up Table
+  /** @brief  build Look Up Table*/
   void buildLUT();
-  // test if a point is inside this zone
+  /* @brief test if a point is inside this mesh*/
   bool inside(double z, double r, double phi) const;
-  // find the bin
+  /* @brief get the cache corresponding to a particular cell*/
   void getCache(double z,
                 double r,
                 double phi,
                 BFieldCache& cache,
                 double scaleFactor = 1.0) const;
-  // get the B field
+  /* @brief get the bfield given a point in xyz*/
   void getB(const double* ATH_RESTRICT xyz,
             double* ATH_RESTRICT B,
             double* ATH_RESTRICT deriv = nullptr) const;
-  // accessors
-  double min(size_t i) const;
-  double max(size_t i) const;
+  /* @brief minimum in axis*/
+  double min(size_t axis) const;
+  /* @brief maximum in axis*/
+  double max(size_t axis) const;
+  /* @brief minimum in z*/
   double zmin() const;
+  /* @brief maximum in z*/
   double zmax() const;
+  /* @brief minimun in r*/
   double rmin() const;
+  /* @brief maximum in r*/
   double rmax() const;
+  /* @brief minimun in phi*/
   double phimin() const;
+  /* @brief maximum in phi*/
   double phimax() const;
-  unsigned nmesh(size_t i) const;
-  double mesh(size_t i, size_t j) const;
+  /* @brief number of corner cell coordinates for axis*/
+  unsigned nmesh(size_t axis) const;
+  /* @brief coordinate at axis of cell corner */
+  double mesh(size_t axis, size_t index) const;
+  /* @brief field entries in mesh*/
   unsigned nfield() const;
-  const BFieldVector<T>& field(size_t i) const;
+  /* @brief field vector at cell corner at index*/
+  const BFieldVector<T>& field(size_t index) const;
+  /* @brief scale*/
   double bscale() const;
+  /* @brief memory size*/
   int memSize() const;
 
 protected: