Minor improvements to desriptions and namings

Redmine: #1858
in Material class hierarchy

Core/Material/BaseMaterialImpl.cpp

@@ -13,7 +13,6 @@ constexpr double magnetization_prefactor
     = (gamma_n * r_e / 2.0 / mu_B) * 1e-18;
 
 namespace {
-// Used in experimental calculation of scattering matrix:
 cvector_t OrthogonalToBaseVector(cvector_t base, const kvector_t vector)
 {
     if (base.mag2()==0.0) return cvector_t {};

Core/Material/BaseMaterialImpl.h

@@ -24,7 +24,8 @@
 class Transform3D;
 class WavevectorInfo;
 
-//! A wrapper for homogeneous and wavelength-independent materials
+//! A basic implementation for homogeneous and wavelength-independent materials.
+//! Incorporates data and methods required to handle material magnetization.
 //! @ingroup materials
 
 class BA_CORE_API_ BaseMaterialImpl : public INamed
@@ -56,11 +57,11 @@ public:
     //! Returns underlying material data
     virtual complex_t materialData() const = 0;
 
-    //! Returns \pi/(wl*wl) - sld, with wl being the wavelength
+    //! Returns (\f$ \pi/\lambda^2 \f$ - sld), sld being the scattering length density
     virtual complex_t scalarSubtrSLD(const WavevectorInfo& wavevectors) const = 0;
 
 #ifndef SWIG
-    //! Returns \pi/(wl*wl) - sld matrix with magnetization corrections. wl denotes the wavelength
+    //! Returns (\f$ \pi/\lambda^2 \f$ - sld) matrix with magnetization corrections
     Eigen::Matrix2cd polarizedSubtrSLD(const WavevectorInfo& wavevectors) const;
 #endif
 
@@ -70,7 +71,6 @@ public:
     virtual void print(std::ostream &ostr) const = 0;
 
 private:
-    //! Sets the magnetization (in A/m)
     void setMagnetization(kvector_t magnetization)
     {
         m_magnetization = magnetization;

Core/Material/Material.h

@@ -26,7 +26,7 @@
 class Transform3D;
 class WavevectorInfo;
 
-//! A wrapper for homogeneous and wavelength-independent materials
+//! A wrapper for underlying material implementation
 //! @ingroup materials
 
 class BA_CORE_API_ Material
@@ -46,7 +46,10 @@ public:
     //! Constructs a material with inverted magnetization
     Material inverted() const;
 
+    //! Returns refractive index
     complex_t refractiveIndex(double wavelength) const;
+
+    //! Returns squared refractive index
     complex_t refractiveIndex2(double wavelength) const;
 
     //! Indicates whether the interaction with the material is scalar.
@@ -67,13 +70,14 @@ public:
     //! Returns underlying material data
     complex_t materialData() const;
 
+    //! Returns true if material underlying data is nullptr
     bool isEmpty() {return !m_material_impl;}
 
-    //! Returns \pi/(wl*wl) - sld, with wl being the wavelength
+    //! Returns (\f$ \pi/\lambda^2 \f$ - sld), sld (in \f$nm^{-2}\f$) being the scattering length density
     complex_t scalarSubtrSLD(const WavevectorInfo& wavevectors) const;
 
 #ifndef SWIG
-    //! Returns \pi/(wl*wl) - sld matrix with magnetization corrections. wl denotes the wavelength
+    //! Returns (\f$ \pi/\lambda^2 \f$ - sld) matrix with magnetization corrections
     Eigen::Matrix2cd polarizedSubtrSLD(const WavevectorInfo& wavevectors) const;
 #endif
 

Core/Material/MaterialFactoryFuncs.h

@@ -3,7 +3,7 @@
 //  BornAgain: simulate and fit scattering at grazing incidence
 //
 //! @file      Core/Material/MaterialFactoryFuncs.h
-//! @brief     Defines factory functions for creating different flavors of materials.
+//! @brief     Factory functions used to create material instances.
 //!
 //! @homepage  http://www.bornagainproject.org
 //! @license   GNU General Public License v3 or higher (see COPYING)
@@ -18,15 +18,23 @@
 
 #include "Material.h"
 
+//! @ingroup materials
+
 //! Constructs a material with _name_ and _refractive_index_.
+//! @param magnetization: magnetization (in A/m)
 BA_CORE_API_ Material RefractiveIndexMaterial(const std::string& name, complex_t refractive_index,
                                               kvector_t magnetization = kvector_t());
 
+//! @ingroup materials
+
 //! Constructs a material with _name_ and refractive_index parameters
 //! \f$\delta\f$ and \f$\beta\f$ for refractive index \f$n = 1 - \delta + i \beta\f$.
+//! @param magnetization: magnetization (in A/m)
 BA_CORE_API_ Material RefractiveIndexMaterial(const std::string& name, double delta, double beta,
                                               kvector_t magnetization = kvector_t());
 
+//! @ingroup materials
+
 //! Constructs a wavelength-independent material with given sld and absorptive term
 //! Absorptive term is wavelength-independent (normalized to a wavelength)
 //! and can be considered as inverse of imaginary part of complex scattering length density:
@@ -36,15 +44,19 @@ BA_CORE_API_ Material RefractiveIndexMaterial(const std::string& name, double de
 //! \f$ \sigma_{abs}(\lambda_0) \f$ - absorption cross-section at \f$ \lambda_0 \f$ wavelength
 //! @param sld: scattering length density, \f$ nm^{-2} \f$
 //! @param abs_term: wavelength-independent absorptive term, \f$ nm^{-2} \f$
+//! @param magnetization: magnetization (in A/m)
 BA_CORE_API_ Material MaterialBySLD(const std::string& name, double sld, double abs_term,
                                     kvector_t magnetization = kvector_t());
 
+//! @ingroup materials
+
 //! Constructs a wavelength-independent material with given sld and absorptive term
 //! As opposed to MaterialBySLD, absorptive term is the product of number density and
 //! absorptive cross-section \f$ \sigma_0 \f$ at \f$ \lambda = 1.798197\f$ Angstroms.
 //! The latter corresponds to 2200 m/s neutrons.
 //! @param sld: scattering length density, \f$ nm^{-2} \f$
 //! @param abs_cx: absorptive term at \f$ \lambda = 1.798197\f$ Angstroms, \f$ nm^{-1} \f$
+//! @param magnetization: magnetization (in A/m)
 BA_CORE_API_ Material MaterialByAbsCX(const std::string& name, double sld, double abs_cx,
                                       kvector_t magnetization = kvector_t());
 

Core/Material/RefractiveCoefMaterial.h

@@ -19,14 +19,14 @@
 #include "BaseMaterialImpl.h"
 #include "Material.h"
 
+//! Material implementation based on refractive coefficiencts (valid for one wavelength value only)
+//! @ingroup materials
+
 class BA_CORE_API_ RefractiveCoefMaterial : public BaseMaterialImpl
 {
 public:
-    //! Constructs a material with _name_ and _refractive_index_.
     friend BA_CORE_API_ Material RefractiveIndexMaterial(const std::string&, complex_t, kvector_t);
 
-    //! Constructs a material with _name_ and refractive_index parameters
-    //! \f$\delta\f$ and \f$\beta\f$ for refractive index \f$n = 1 - \delta + i \beta\f$.
     friend BA_CORE_API_ Material RefractiveIndexMaterial(const std::string&, double, double,
                                                          kvector_t);
 
@@ -35,13 +35,23 @@ public:
     //! Returns pointer to a copy of material
     virtual RefractiveCoefMaterial* clone() const override;
 
+    //! Returns refractive index
+    //! For this particular implementation returned value does not depend
+    //! on passed wavelength
     virtual complex_t refractiveIndex(double wavelength) const override;
+
+    //! Returns squared refractive index.
+    //! For this particular implementation returned value does not depend
+    //! on passed wavelength.
     virtual complex_t refractiveIndex2(double wavelength) const override;
 
     //! Returns underlying material data
     virtual complex_t materialData() const override;
 
-    //! Returns \pi/(wl*wl) - sld, with wl being the wavelength
+    //! Returns (\f$ \pi/\lambda^2 \f$ - sld), sld (in \f$nm^{-2}\f$) being the scattering length density.
+    //! If the wavelength associated with passed wavevector is different from the one
+    //! associated with refractive coefficients used during the object construction,
+    //! provided result is inconsistent.
     virtual complex_t scalarSubtrSLD(const WavevectorInfo& wavevectors) const override;
 
     //! Prints object data

Core/Material/WavelengthIndependentMaterial.cpp

@@ -5,9 +5,9 @@ namespace
 {
 // Returns SLD-like complex value, where real part is SLD and imaginary one is
 // wavelength-independent absorptive term
-inline complex_t getSLD(double delta_factor, double beta_factor)
+inline complex_t getSLD(double sld, double abs_term)
 {
-    return complex_t(delta_factor, -beta_factor / 2.0);
+    return complex_t(sld, -abs_term / 2.0);
 }
 
 inline double getWlPrefactor(double wavelength)

Core/Material/WavelengthIndependentMaterial.h

@@ -19,6 +19,9 @@
 #include "BaseMaterialImpl.h"
 #include "Material.h"
 
+//! Material implementation based on wavelength-independent data (valid for a range of wavelengths)
+//! @ingroup materials
+
 class BA_CORE_API_ WavelengthIndependentMaterial : public BaseMaterialImpl
 {
 public:
@@ -31,13 +34,16 @@ public:
     //! Returns pointer to a copy of material
     virtual WavelengthIndependentMaterial* clone() const override;
 
+    //! Returns refractive index
     virtual complex_t refractiveIndex(double wavelength) const override;
+
+    //! Returns squared refractive index
     virtual complex_t refractiveIndex2(double wavelength) const override;
 
     //! Returns underlying material data
     virtual complex_t materialData() const override;
 
-    //! Returns \pi/(wl*wl) - sld, with wl being the wavelength
+    //! Returns (\f$ \pi/\lambda^2 \f$ - sld), sld (in \f$nm^{-2}\f$) being the scattering length density
     virtual complex_t scalarSubtrSLD(const WavevectorInfo& wavevectors) const override;
 
     //! Prints object data

Doc/Doxygen/defgroups.dox

@@ -10,7 +10,7 @@
 @brief Classes to describe experimental sample.
 
 \defgroup materials Materials
-@brief Classes to describe magnetic and non-magnetic materials.
+@brief Classes and functions to describe magnetic and non-magnetic materials.
 
 \defgroup formfactors Available formfactors
 @brief Available form factors.