Merge pull request #30 from Quetzal-framework/develop

fix: gaussian naming convention and doc link

docs/4-tutorials.md

@@ -27,7 +27,7 @@
 
 - @subpage demographic_histories_in_quetzal
 - Examples
-  - @subpage dispersal-kernels
+  - @subpage dispersal_kernels
   - @subpage Growth Expressions
   - @subpage Memory Management
 
@@ -814,10 +814,18 @@ There a different modeling approaches to look at these demographic histories, pr
 
 [//]: # (----------------------------------------------------------------------)
 @page dispersal_kernels Dispersal Kernels
+@tableofcontents
+
+# Background
+
+# Neighborhood-based Dispersal
+
+# Distance-based Dispersal
+
+# Resistance-based Dispersal
 
 @note 
-The objective of this section is to parametrize a Dispersal Location Kernel (in the sense of <a href="nathan-et-al-2012.pdf" target="_blank"><b> Nathan et al. 2012</b></a>)
-and to compute useful quantities, such as the distance between two locations, the probability to disperse from one to the other, and the mean dispersal distance expected under the distribution.
+Simulating a demographic process on a spatial graph first requires to account for the modality of dispersal between the vertices (locations) of the graph. A relatively simple way to do so is to link the geographic distance between two locations to the probability to disperse between them. The objective of this section is to highlight this model choice by parametrizing a simple Dispersal Location Kernel (in the sense of <a href="nathan-et-al-2012.pdf" target="_blank"><b> Nathan et al. 2012</b></a>) and to compute useful quantities, such as the distance between two coordinates, the probability to disperse from one to the other, and the mean dispersal distance expected under the distribution.
 
 ## Background 
 
@@ -827,7 +835,7 @@ The dispersal location kernel represents the statistical pattern of dispersal di
 
 For a source \f$(x_0,y_0)\f$, the dispersal location kernel denoted as \f$k_L(r)\f$ provides the density of the probability of the dispersal end point in the 2D space. In this case, \f$k_L(r)dA\f$ is the probability of a dispersal end point to be within a small 2D area \f$dA\f$ around the location \f$(x,y)\f$. Since a probability is unitless and \f$dA\f$ is an area, \f$k_L(r)\f$ is expressed in per unit area in a 2D space.
 
-Quetzal automate dimensional analysis and conversion thanks to the `mp-units` library.
+Quetzal implements several types of kernel available in the `quetzal::demography::dispersal_kernel` namespace, and automates compile-time dimensional analysis and units conversion thanks to the `mp-units` library. 
 
 **Input**
 

example/dispersal_kernel.cpp

@@ -8,7 +8,7 @@ int main()
 {
 	// Shorten notation
 	using namespace mp_units::si::unit_symbols; // SI system: km, m, s 
-	using quetzal::demography::dispersal_kernel::Gaussian;
+	using quetzal::demography::dispersal_kernel::gaussian;
 	using quetzal::geography::lonlat;
 
 	// Dispersal kernels operate on distances between geographic coordinates
@@ -17,11 +17,11 @@ int main()
 	constexpr auto distance = source.great_circle_distance_to(target) * km;
 
 	// Used to parametrize the kernel
-	constexpr auto param = Gaussian<>::param_type {.a=1000.*m};
+	constexpr auto param = gaussian<>::param_type {.a=1000.*m};
 
 	// Compute quantities
-	auto p = Gaussian<>::pdf(distance, param);
-	auto d = Gaussian<>::mean_dispersal_distance(param);
+	auto p = gaussian<>::pdf(distance, param);
+	auto d = gaussian<>::mean_dispersal_distance(param);
 
 	std::cout << "Dispersal from " << source << " to " << target << " :\n"
 			  << "distance is " << distance << "\n"

src/include/quetzal/demography/dispersal_kernel.hpp

@@ -31,7 +31,7 @@ namespace quetzal
       /// @details To be used as a reference against leptokurtic kernels.
       ///          Suitable for diffusion-based dispersal or complete random-walk during a constant time.
       template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
-      struct Gaussian
+      struct gaussian
       {
 
         /// @brief Dispersal location kernel parameter
@@ -65,7 +65,7 @@ namespace quetzal
       /// @brief Logistic dispersal location kernel (fat-tailed, power-law tail)
       /// @ingroup demography
       /// @details Suitable for frequent long-distance dispersal events and weak effect of distance close to the source.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct logistic
       {
 
@@ -113,7 +113,7 @@ namespace quetzal
       /// @details To be used as reference against more fat-tailed kernels. 
       ///          Suitable for representing a travel at constant speed in a random direction with a constant
       ///          stopping rate, or a correlated random walk with settlement.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct negative_exponential
       {
         /// @brief Dispersal location kernel parameter
@@ -149,7 +149,7 @@ namespace quetzal
       /// @brief Exponential Power dispersal location kernel (\f$b > 1\f$ : thin-tailed, \f$b < 1\f$ : fat-tailed. Always thinner than power laws.)
       /// @ingroup demography
       /// @details Suitable for pollen dispersal. Gaussian and Exponential are special cases, making it suitable for shape comparisons.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct exponential_power
       {
         /// @brief Dispersal location kernel parameter
@@ -194,7 +194,7 @@ namespace quetzal
       /// @ingroup demography
       /// @details Suitable for seed dispersal. Obtained as a continuous mixture of Gaussian kernels with variance
       ///          parameters distributed as the inverse of a Gamma distribution.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct two_dt
       {
         /// @brief Dispersal location kernel parameter
@@ -242,7 +242,7 @@ namespace quetzal
       /// @brief Inverse Power Law dispersal location kernel (fat-tailed, power-law tail)
       /// @ingroup demography
       /// @details Suitable for very fat tails.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct inverse_power_law
       {
         /// @brief Dispersal location kernel parameter
@@ -288,7 +288,7 @@ namespace quetzal
       /// @brief Lognormal dispersal location kernel (fat-tailed)
       /// @ingroup demography
       /// @details Suitable for seed dispersal, particularly when the peak of the distribution is not at zero distance from the source.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct lognormal
       {
         /// @brief Dispersal location kernel parameter
@@ -329,7 +329,7 @@ namespace quetzal
       /// @brief Gaussian Mixture dispersal location kernel (leptokurtic, never fat-tailed)
       /// @ingroup demography
       /// @details Used in theoretical studies.
-      template<QuantityOf<isq::length> Distance>
+      template<QuantityOf<isq::length> Distance = mp_units::quantity<mp_units::si::metre>>
       struct gaussian_mixture
       {
         /// @brief Dispersal location kernel parameter