Implement interactive demo with wrapping noise habitat + normal dispersal + species visualisation (#22)

* Initial implementation of wrapping noise scenario

* Implemented proof-of-concept demo notebook

* Cleaned up wrapping noise scenario and added docs

* Vendored https://github.com/Mapet13/opensimplex_noise_rust to defer to MathsCore::floor

Author: juntyr

Cargo.toml

@@ -44,6 +44,9 @@ default-members = [
     "necsim/plugins/tskit",
 ]
 
+[profile.dev]
+debug = false
+
 [profile.release]
 opt-level = 3
 lto = "fat"

docs/simulate.ron

@@ -241,13 +241,49 @@
             migration: (0.0 < f64 <= 1.0),
         )
         /* (almost) infinite spatially-explicit scenario with Gaussian distributed dispersal
-         *  the entire infinite landscape is habitat but, without loss of generality, has deme 1 */
+         * the entire infinite landscape is habitat but, without loss of generality, has deme 1
+         * the landscape is on a (wrapping) torus with 0 <= x < 2^32 and 0 <= y < 2^32 */
       | AlmostInfinite(
             /* radius of a circle from which individuals are sampled */
             radius: (u16),
             /* sigma for the Gaussian dispersal kernel N(0, sigma^2) */
             sigma: (0.0 <= f64),
         )
+        /* (almost) infinite spatially-explicit scenario with (approximate) Gaussian distributed dispersal
+           each location (x, y) in the landscape has either habitat for exactly one individual,
+            or is inhabitable, depending on a sample from an OpenSimplexNoise
+           the landscape is on a (wrapping) torus with 0 <= x < 2^32 and 0 <= y < 2^32 */
+      | WrappingNoise(
+            /* random seed for the noise */
+            seed: (i64),
+            /* percentage of the habitat that will be habitable */
+            coverage: (0.0 <= f64 <= 1.0),
+            /* scale of the noise, is doubled on each octave
+             * choose 0.025 for a reasonable default */
+            scale: (0.0 < f64 <= 1.0),
+            /* geometric persistence factor for noise amplitude across octaves
+             * choose 0.5 for a reasonable default */
+            persistence: (0.0 < f64 <= 1.0),
+            /* number of noise octaves that are accumulated for each sample
+             * a larger number of octaves provides finer-grained habitat boundaries
+                but is less efficient to simulate
+             * choose 1 for only one noise sample per location and maximum efficiency */
+            octaves: (0 < usize),
+            /* rectangular sample area, individuals living in here are simulated
+             * the sample area can wrap around the torus */
+            sample: Extent(
+                /* lower-left origin x of the sample area */
+                x: (u32),
+                /* lower-left origin y of the sample area */
+                y: (u32),
+                /* width of the sample area */
+                width: (1 <= u64 <= 2^32),
+                /* height of the sample area */
+                height: (1 <= u64 <= 2^32),
+            ),
+            /* sigma for the Gaussian dispersal kernel N(0, sigma^2) */
+            sigma: (0.0 <= f64),
+        )
     ),
 
     /* selection of the coalescence algorithm which is used */

necsim/core/bond/src/closed_unit_f64.rs

@@ -88,6 +88,11 @@ impl ClosedUnitF64 {
         Self(0.0_f64)
     }
 
+    #[must_use]
+    pub const fn half() -> Self {
+        Self(0.5_f64)
+    }
+
     #[must_use]
     pub const fn one() -> Self {
         Self(1.0_f64)

necsim/core/bond/src/off_by_one_u64.rs

@@ -7,7 +7,7 @@ use core::{
 
 use serde::{Deserialize, Deserializer, Serialize};
 
-use crate::OffByOneU32;
+use crate::{ClosedUnitF64, OffByOneU32};
 
 #[derive(Debug)]
 #[allow(clippy::module_name_repetitions)]
@@ -150,3 +150,14 @@ impl Mul for OffByOneU64 {
         Self((self.0 + 1) * (other.0 + 1) - 1)
     }
 }
+
+impl Mul<ClosedUnitF64> for OffByOneU64 {
+    type Output = Self;
+
+    fn mul(self, other: ClosedUnitF64) -> Self::Output {
+        #[allow(clippy::cast_possible_truncation)]
+        #[allow(clippy::cast_sign_loss)]
+        #[allow(clippy::cast_precision_loss)]
+        Self(((((self.get() as f64) * other.get()) as u128) - 1) as u64)
+    }
+}

necsim/core/src/cogs/habitat.rs

@@ -15,6 +15,9 @@ pub trait Habitat<M: MathsCore>: crate::cogs::Backup + core::fmt::Debug + Sized
     where
         Self: 'a;
 
+    #[must_use]
+    fn is_finite(&self) -> bool;
+
     #[must_use]
     fn get_extent(&self) -> &LandscapeExtent;
 
@@ -24,7 +27,7 @@ pub trait Habitat<M: MathsCore>: crate::cogs::Backup + core::fmt::Debug + Sized
     }
 
     #[must_use]
-    #[debug_ensures(ret.get() == {
+    #[debug_ensures(!self.is_finite() || ret.get() == {
         self.iter_habitable_locations()
             .map(|location| u128::from(self.get_habitat_at_location(&location)))
             .sum()

necsim/core/src/landscape/extent.rs

@@ -2,8 +2,10 @@ use necsim_core_bond::OffByOneU32;
 
 use super::Location;
 
-#[allow(clippy::module_name_repetitions)]
-#[derive(PartialEq, Eq, Clone, Debug, TypeLayout)]
+#[allow(clippy::module_name_repetitions, clippy::unsafe_derive_deserialize)]
+#[derive(PartialEq, Eq, Clone, Debug, serde::Deserialize, serde::Serialize, TypeLayout)]
+#[serde(rename = "Extent")]
+#[serde(deny_unknown_fields)]
 #[repr(C)]
 pub struct LandscapeExtent {
     x: u32,

necsim/core/src/reporter/filter.rs

@@ -26,7 +26,7 @@ impl<R: Reporter, KeepSpeciation: Boolean, KeepDispersal: Boolean, KeepProgress:
     for FilteredReporter<R, KeepSpeciation, KeepDispersal, KeepProgress>
 {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
-        fmt.debug_struct("FilteredReporter")
+        fmt.debug_struct(stringify!(FilteredReporter))
             .field("reporter", &self.reporter)
             .finish()
     }

necsim/impls/cuda/src/event_buffer.rs

@@ -48,7 +48,7 @@ impl<ReportSpeciation: Boolean, ReportDispersal: Boolean> fmt::Debug
     for EventBuffer<ReportSpeciation, ReportDispersal>
 {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
-        fmt.debug_struct("EventBuffer")
+        fmt.debug_struct(stringify!(EventBuffer))
             .field("max_events", &self.max_events)
             .field("event_counter", &self.event_counter)
             .finish()

necsim/impls/no-std/src/cogs/dispersal_sampler/in_memory/packed_alias/mod.rs

@@ -116,7 +116,7 @@ impl<M: MathsCore, H: Habitat<M>, G: RngCore<M>> core::fmt::Debug
     for InMemoryPackedAliasDispersalSampler<M, H, G>
 {
     fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
-        f.debug_struct("InMemoryPackedAliasDispersalSampler")
+        f.debug_struct(stringify!(InMemoryPackedAliasDispersalSampler))
             .field("alias_dispersal_ranges", &self.alias_dispersal_ranges)
             .field(
                 "alias_dispersal_buffer",

necsim/impls/no-std/src/cogs/dispersal_sampler/mod.rs

@@ -3,3 +3,4 @@ pub mod in_memory;
 pub mod non_spatial;
 pub mod spatially_implicit;
 pub mod trespassing;
+pub mod wrapping_noise;