Merge pull request #31 from Quetzal-framework/develop

doc: updating kernels

.clang-format

@@ -0,0 +1,3 @@
+BasedOnStyle: Microsoft
+IndentWidth: 4
+ColumnLimit: 120

.devcontainer/Dockerfile-ubuntu

@@ -1,13 +1,14 @@
-FROM ubuntu:22.04
+FROM ubuntu:23.04
 
 ARG DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update -y
 RUN apt-get install -y --no-install-recommends\
                     vim \
                     git \
-                    gcc-12 \
-                    g++-12 \
+                    gcc-13 \
+                    g++-13 \
+                    clangd \
                     build-essential \
                     libboost-all-dev \
                     cmake \
@@ -16,6 +17,6 @@ RUN apt-get install -y --no-install-recommends\
                     ca-certificates \
                     doxygen \
                     graphviz \ 
-                    python3-pip
+                    pipx
 
-RUN pip install conan==2.0.13
+RUN pipx ensurepath && pipx install conan==2.0.13

.devcontainer/devcontainer.json

@@ -13,24 +13,38 @@
 	"remoteUser": "root",
 	// Features to add to the dev container, see https://containers.dev/feature
 	"features": {},
-
 	// Configure tool-specific properties.
 	"customizations": {
-		// Configure properties specific to VS Code.
+		// Configure properties specific to VS Code to be installed in the devcontainer
 		"vscode": {
-			"settings": {},
 			"extensions": [
-				"streetsidesoftware.code-spell-checker"
-			]
+				// Clangd: code complete, compile error, clang-format etc
+				"llvm-vs-code-extensions.vscode-clangd",
+				// Format all files in the workspace
+				"jbockle.jbockle-format-files",
+				// Cmake syntax highlighting
+				"twxs.cmake",
+				// Check grammar in text and Markdown
+				"znck.grammarly",
+				// Spelling check in code
+				"streetsidesoftware.code-spell-checker",
+			],
+			"settings": {
+				"clangd.path": "/usr/bin/clangd",
+				"clangd.arguments": [
+					"--compile-commands-dir=${workspaceFolder}",
+					"-std=c++23"
+				],
+				"clang-format.executable": "clang-format",
+				"clang-format.style": "file",
+				"clang-format.fallbackStyle": "Microsoft",
+				"clang-format.formatOnSave": true,
+				"clang-format.formatOnType": true,
+				"clang-format.arguments": [
+					"-assume-filename=${workspaceFolder}/.clang-format"
+				],
+				"formatFiles.excludePattern": "**/.vscode/**,**/.git/**,**/build/**,**/.cache/**"
+			}
 		}
 	}
-
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
-
-	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "gcc -v",
-
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-	// "remoteUser": "root"
 }

.devcontainer/onCreateCommand.sh

@@ -1,2 +1,11 @@
-conan install conanfile.py --profile:build=conan/profiles/linux-armv8-gcc12-release --profile:host=conan/profiles/linux-armv8-gcc12-release --build=missing --output-folder=build
-conan install conanfile.py --profile:build=conan/profiles/linux-armv8-gcc12-debug --profile:host=conan/profiles/linux-armv8-gcc12-debug --build=missing --output-folder=build
+conan install conanfile.py \
+    --profile:build=conan/profiles/linux-armv8-gcc12-release \
+    --profile:host=conan/profiles/linux-armv8-gcc12-release \
+    --build=missing \
+    --output-folder=build
+
+conan install conanfile.py \
+    --profile:build=conan/profiles/linux-armv8-gcc12-debug \
+    --profile:host=conan/profiles/linux-armv8-gcc12-debug \
+    --build=missing \
+    --output-folder=build

.gitignore

@@ -1,4 +1,5 @@
 build/
 .DS_Store
 CMakeUserPresets.json
-conaninfo.txt
+conaninfo.txt
+.cache

.vscode/extensions.json

@@ -1,9 +1,21 @@
 {
     "recommendations": [
+        // Dev Containers
         "ms-vscode-remote.remote-containers",
-        "ms-vscode.cpptools-themes",
-        "ms-vscode.cpptools",
-        "ms-vscode.cpptools-extension-pack",
-        "twxs.cmake"
+        // Docker Explorer view to VS Code
+        "ms-azuretools.vscode-docker",
+        // Understanding of complex code
+        // "lvm-vs-code-extensions.vscode-clangd"
+        // Bundle the 4 next extensions
+        // "ms-vscode.cpptools-extension-pack",        
+        // 1. Semantic colorization
+        // "ms-vscode.cpptools-themes",
+        // 2. Intellisense
+        // "ms-vscode.cpptools",
+        // 3. CMake syntax
+        // "twxs.cmake",
+        // 4. Cmake workflow
+        // "ms-vscode.cmake-tool",
+
     ]
 }

.vscode/settings.json

@@ -1,5 +1,6 @@
 // Workspace settings are stored in the workspace .vscode folder and only apply when the workspace is opened.
 {
+    "C_Cpp.default.cppStandard": "c++23",
     "cmake.configureOnOpen": false,
     "files.associations": {
         "cwchar": "cpp",
@@ -77,6 +78,11 @@
         "typeindex": "cpp",
         "typeinfo": "cpp",
         "valarray": "cpp",
-        "variant": "cpp"
-    }
+        "variant": "cpp",
+        "*.ipp": "cpp"
+    },
+    "cSpell.words": [
+        "clangd",
+        "devcontainer"
+    ]
 }

CMakeLists.txt

@@ -11,6 +11,9 @@ project(quetzal-coatl-dev LANGUAGES CXX)
 
 list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 
+# Support for clangd
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
 # add project code
 add_subdirectory(src)
 

docs/4-tutorials.md

@@ -816,33 +816,50 @@ There a different modeling approaches to look at these demographic histories, pr
 @page dispersal_kernels Dispersal Kernels
 @tableofcontents
 
+@note 
+The objective of this section is to define the modality of dispersal of a species across a discrete landscape. Because dispersal is so tightly related to graph connectivity and performance, this will require to:
+1. transform a `quetzal::geography::landscape` into a `quetzal::geography::graph` selecting the desired level of connectivity
+2. update the edges information of the graph to reflect the desired rate of movement.
+
 # Background
 
-# Neighborhood-based Dispersal
+The challenge of replicating a demographic process within a discrete landscape can be framed as a process on a spatial graph. In this graph, the vertices represent the cells of the landscape grid, while the edges link the areas where migration occurs.
 
-# Distance-based Dispersal
+The quantity of edges in this graph significantly influences both complexity and performance. For instance, in a landscape containing \f$n\f$ cells, considering migration between any two arbitrary locations would result in a complete graph with \f$\frac{n(n-1)}{2}\f$ edges, which could pose computational difficulties.
 
-# Resistance-based Dispersal
+For this reason, constructing a spatial graph first requires to account for the modality of dispersal between the vertices (locations) of the graph. We distinguish at least 3 modalities:
 
-@note 
-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.
+* 4-neighbors: each cell of the landscape grid is connected only to its cardinal neighbors (N, E, S, W). 
+* 8-neighbors: each cell of the landscape grid is connected only to its cardinal and intercardinal (NE, SE, SW, NW) neighbors.
+* complete graph: each cell of the landscape grid is connected to all others: the rate of migration between two cells will be a function of the distance or path of least resistance.
 
-## Background 
+# 4-neighbors graph
+
+# 8-neighbors graph
+
+# Complete graph
+
+## Distance-based kernel
+
+A straightforward approach to determine the dispersal mode across a complete spatial graph involves correlating the geographic distance between two locations with the likelihood of dispersal 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>). Additionally, we will calculate essential metrics, such as the distance between two coordinates, the dispersal probability between them, and the average dispersal distance anticipated under this distribution.
 
 The dispersal location kernel represents the statistical pattern of dispersal distances within a population. In this context, it essentially serves as the probability density function (pdf) that outlines the distribution of locations after dispersal in relation to the original location. The expressions have been adjusted to incorporate a scale parameter, 
 \f$a\f$, which is consistent with a distance unit, and a shape parameter, 
 \f$b\f$, that dictates the curvature of the distribution curve, emphasizing the influence of long-distance events.
 
 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 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. 
+Quetzal incorporates various kernel types available in the `quetzal::demography::dispersal_kernel` namespace, and streamlines compile-time dimensional analysis and units conversion using the `mp-units` library. 
 
 **Input**
 
-@include{lineno} dispersal_kernel.cpp
+@include{lineno} demography_dispersal_kernel.cpp
 
 **Output**
 
-@include{lineno} dispersal_kernel.txt
+@include{lineno} demography_dispersal_kernel.txt
 
 ---
+
+## Resistance-based Dispersal
+

docs/github-corner-css/css/corner.css

@@ -36,4 +36,4 @@
     .github-corner .octo-arm {
         animation: octocat-wave 560ms ease-in-out;
     }
-}
+}

docs/github-corner-css/css/styles.css

@@ -9,7 +9,8 @@
     box-sizing: border-box;
 }
 
-html, body {
+html,
+body {
     font-family: Helvetica, Arial, sans-serif;
     background: #fff;
     margin: 0px;
@@ -129,4 +130,4 @@ footer span {
     .twitter-share-button {
         margin-bottom: -8px;
     }
-}
+}