From 9ef1c8aaa298675975db4a7c0bb13cac6708b3a8 Mon Sep 17 00:00:00 2001
From: "Joachim Wuttke (h)" <j.wuttke@fz-juelich.de>
Date: Wed, 9 Dec 2020 15:25:26 +0100
Subject: [PATCH] Units: doxy explanation
---
Base/Const/Units.h | 16 +++++++++++++---
1 file changed, 13 insertions(+), 3 deletions(-)
diff --git a/Base/Const/Units.h b/Base/Const/Units.h
index 3ec10b3fdb0..0a755bf3b6b 100644
--- a/Base/Const/Units.h
+++ b/Base/Const/Units.h
@@ -16,11 +16,21 @@
#define BORNAGAIN_BASE_CONST_UNITS_H
//! Constants and functions for physical unit conversions.
+//!
+//! In user code, quantities that have a physical dimension should always
+//! be given in the form _value * unit_, e.g. 0.529 * angstrom for a length,
+//! or 45 * deg for an angle.
+//!
+//! Internally, BornAgain has length, angle, magnetic field units of nanometer,
+//! radians, Tesla. Therefore, in principle, the multipliers nm, rad, tesla could
+//! be ommited from code. However, to make code more readable, and to prevent
+//! misunderstandings, we recommend that physical dimension be always made clear
+//! by multiplying values with an appropriate constant, even if this expands to 1.
namespace Units {
// Length
-static constexpr double nanometer = 1.;
+static constexpr double nanometer = 1.; //!< Internal unit for lengths
static constexpr double angstrom = 1.e-1 * nanometer;
static constexpr double micrometer = 1.e+3 * nanometer;
static constexpr double millimeter = 1.e+6 * nanometer;
@@ -32,11 +42,11 @@ static constexpr double nm = nanometer;
static constexpr double nm2 = nanometer * nanometer;
// Angle
-static constexpr double rad = 1.;
+static constexpr double rad = 1.; //!< Radian, internal unit for angles
static constexpr double deg = (3.1415926535897932 / 180.0) * rad;
// Magnetic field
-static constexpr double tesla = 1.;
+static constexpr double tesla = 1.; //!< Internal unit for magnetic fields
static constexpr double gauss = 1e-4;
// Converters
--
GitLab