Add area and flowgrow functionality (#54)

Author: dkarrasch

Project.toml

@@ -1,6 +1,6 @@
 name = "CoherentStructures"
 uuid = "0c1513b4-3a13-56f1-9cd2-8312eaec88c4"
-version = "0.3.4"
+version = "0.3.5"
 
 [deps]
 Arpack = "7d9fca2a-8960-54d3-9f78-7d1dccf2cb97"
@@ -31,15 +31,15 @@ Arpack = "0.3, 0.4"
 AxisArrays = "0.3.3, 0.4"
 ColorTypes = "0.10"
 DiffEqBase = "6"
-Distances = "0.9"
+Distances = "0.9, 0.10"
 GeometricalPredicates = "0.3, 0.4"
-Interpolations = "0.11, 0.12"
+Interpolations = "0.11, 0.12, 0.13"
 IterativeSolvers = "0.7, 0.8"
 LinearMaps = "2"
 NearestNeighbors = "0.4.4"
 OrdinaryDiffEq = "5.18"
 ProgressMeter = "1"
-RecipesBase = "0.7, 0.8, 1.0"
+RecipesBase = "0.7, 0.8, 1"
 StaticArrays = "0.10, 0.11, 0.12"
 Tensors = "1.0.1"
 VoronoiDelaunay = "0.4"

docs/src/Laplace.md

@@ -7,14 +7,17 @@ CurrentModule = CoherentStructures
 The LCS approaches implemented and described in this section are strongly influenced
 by ideas developed in the spectral clustering/diffusion maps communities. The
 general references include:
-   * [Shi & Malik, Normalized cuts and image segmentation, 2000](https://doi.org/10.1109/34.868688)
-   * [Coifman & Lafon, Diffusion maps, 2006](https://doi.org/10.1016/j.acha.2006.04.006)
-   * [Marshall & Hirn, Time coupled diffusion maps, 2018](https://doi.org/10.1016/j.acha.2017.11.003)
+
+* [Shi & Malik, Normalized cuts and image segmentation, 2000](https://doi.org/10.1109/34.868688)
+* [Coifman & Lafon, Diffusion maps, 2006](https://doi.org/10.1016/j.acha.2006.04.006)
+* [Marshall & Hirn, Time coupled diffusion maps, 2018](https://doi.org/10.1016/j.acha.2017.11.003)
+
 In the LCS context, these ideas have been adopted in the following works:
-   * somewhat related [Froyland & Padberg-Gehle, 2015](https://doi.org/10.1063/1.4926372)
-   * [Hadjighasem et al., 2016](https://doi.org/10.1103/PhysRevE.93.063107)
-   * [Banisch & Koltai, 2017](https://doi.org/10.1063/1.4971788)
-   * [Rypina et al., 2017](https://doi.org/10.5194/npg-24-189-2017)/[Padberg-Gehle & Schneide, 2018](https://doi.org/10.5194/npg-24-661-2017)
+
+* somewhat related [Froyland & Padberg-Gehle, 2015](https://doi.org/10.1063/1.4926372)
+* [Hadjighasem et al., 2016](https://doi.org/10.1103/PhysRevE.93.063107)
+* [Banisch & Koltai, 2017](https://doi.org/10.1063/1.4971788)
+* [Rypina et al., 2017](https://doi.org/10.5194/npg-24-189-2017)/[Padberg-Gehle & Schneide, 2018](https://doi.org/10.5194/npg-24-661-2017)
 
 For demonstrations on example cases, please consult the page on
 [Working with trajectories](@ref).
@@ -25,6 +28,7 @@ For demonstrations on example cases, please consult the page on
 
 Three commonly used sparsification methods are implemented for use with various
 graph Laplacian methods.
+
 ```@docs
 KNN
 MutualKNN
@@ -38,16 +42,21 @@ Other sparsification methods can be implemented by defining a
 
 Since the Euclidean heat kernel is ubiquitous in diffusion maps-based computations,
 we provide it for convenience.
+
 ```@docs
 gaussian
 gaussiancutoff
 ```
+
 To compute a sparse distance matrix (or adjacency matrix, depending on the
 [sparsification method](@ref sparsification_methods)), use [`spdist`](@ref).
+
 ```@docs
 spdist
 ```
+
 The main high-level functions for the above-listed methods are the following.
+
 ```@docs
 sparse_diff_op_family
 sparse_diff_op
@@ -56,9 +65,11 @@ sparse_diff_op
 ### Normalization functions
 
 In the diffusion maps framework, there are two commonly used normalization steps:
+
 1. kernel-density estimate normalization ([`kde_normalize!`](@ref)), and
 2. row normalization ([`row_normalize!`](@ref)), to obtain a diffusion/Markov
    operator (w.r.t. right- and left-action, respectively).
+
 ```@docs
 kde_normalize!
 row_normalize!

docs/src/basics.md

@@ -3,27 +3,32 @@
 ```@meta
 CurrentModule = CoherentStructures
 ```
+
 ## Definition of vector fields
 
 `CoherentStructures.jl` is set up for handling two- and three-dimensional dynamical
 systems only. For such low-dimensional flows it is advantageous (for top
 performance) to obey the following syntax:
-```
+
+```julia
 function vectorfield2d(u, p, t)
     du1 = ... # equation for $\dot{x}$
     du2 = ... # equation for $\dot{y}$
     return StaticArrays.SVector{2}(du1, du2)
 end
 ```
+
 and correspondingly for three-dimensional ODEs:
-```
+
+```julia
 function vectorfield3d(u, p, t)
     du1 = ... # equation for $\dot{x}$
     du2 = ... # equation for $\dot{y}$
     du3 = ... # equation for $\dot{z}$
     return StaticArrays.SVector{3}(du1, du2, du3)
 end
 ```
+
 In a companion package [`StreamMacros.jl`](https://github.com/CoherentStructures/StreamMacros.jl), there are convenience macros to define two-dimensional velocity
 and vorticity fields from stream functions.
 
@@ -70,25 +75,31 @@ tensor_invariants
 For computing distances w.r.t. standard metrics, there exists the excellent
 [`Distances.jl`](https://github.com/JuliaStats/Distances.jl) package. For example,
 the Euclidean distance between two points is computed by any of the last two lines:
-```
+
+```julia
 using Distances
 x, y = rand(3), rand(3)
 Euclidean()(x, y)
 euclidean(x, y)
 ```
+
 Other metrics of potential interest include `Haversine(r)`, the geodesic
 distance of two points on the sphere with radius `r`, and `PeriodicEuclidean(L)`,
 the distance on a torus or cylinder. Here, `L` is a vector containing the period
 of each dimension, `Inf` for non-periodic dimensions.
+
 ```@docs
 Distances.Euclidean
 Distances.Haversine
 Distances.PeriodicEuclidean
 ```
+
 In `CoherentStructures.jl`, there is one more metric type implemented:
+
 ```@docs
 STmetric
 ```
+
 This is a spatiotemporal metric that operates on trajectories in the format of
 vectors of static vectors, i.e., `Vector{<:SVector}`. Each vector element
 corresponds to the state vector. The `STmetric` then computes the

docs/src/elliptic.md

@@ -7,16 +7,20 @@ CurrentModule = CoherentStructures
 ## Background
 
 The following functions implement an LCS methodology developed in the following papers:
-   * [Haller & Beron-Vera, 2012](https://doi.org/10.1016/j.physd.2012.06.012)
-   * [Haller & Beron-Vera, 2013](https://doi.org/10.1017/jfm.2013.391)
-   * [Karrasch, Huhn, and Haller, 2015](https://doi.org/10.1098/rspa.2014.0639)
+
+* [Haller & Beron-Vera, 2012](https://doi.org/10.1016/j.physd.2012.06.012)
+* [Haller & Beron-Vera, 2013](https://doi.org/10.1017/jfm.2013.391)
+* [Karrasch, Huhn, and Haller, 2015](https://doi.org/10.1098/rspa.2014.0639)
+
 Our implementation here follows conceptually [Karrasch, Huhn, and Haller, 2015](https://doi.org/10.1098/rspa.2014.0639),
 and is described in detail in the preprint TBD.
 Depending on the indefinite metric tensor field used, the functions below yield
 the following types of coherent structures:
-   * black-hole/Lagrangian coherent vortices ([Haller & Beron-Vera, 2012](https://doi.org/10.1017/jfm.2013.391))
-   * elliptic objective Eulerian coherent structures (OECSs) ([Serra & Haller, 2016](https://doi.org/10.1063/1.4951720))
-   * material diffusive transport barriers ([Haller, Karrasch, and Kogelbauer, 2018](https://doi.org/10.1073/pnas.1720177115))
+
+* black-hole/Lagrangian coherent vortices ([Haller & Beron-Vera, 2012](https://doi.org/10.1017/jfm.2013.391))
+* elliptic objective Eulerian coherent structures (OECSs) ([Serra & Haller, 2016](https://doi.org/10.1063/1.4951720))
+* material diffusive transport barriers ([Haller, Karrasch, and Kogelbauer, 2018](https://doi.org/10.1073/pnas.1720177115))
+
 The general procedure is the following. Assume $T$ is the symmetric tensor field
 of interest, say, (i) the Cauchy-Green strain tensor field $C$, (ii) the
 rate-of-strain tensor field $S$, or (iii) the averaged diffusion-weighted
@@ -38,26 +42,29 @@ rather computes the index for each grid cell and then combines nearby
 singularities, i.e., adds non-vanishing indices of nearby grid cells.
 
 In summary, the implementation consists of the following steps:
+
    1. compute the index for each grid cell and combine nearby singular grid cells
       to "singularity candidates";
-   3. look for elliptic singularity candidates (and potentially isolated wedge
+   2. look for elliptic singularity candidates (and potentially isolated wedge
       pairs);
-   4. place an eastwards oriented Poincaré section at the pair center;
-   5. for each point on the discretized Poincaré section, scan through the given
+   3. place an eastwards oriented Poincaré section at the pair center;
+   4. for each point on the discretized Poincaré section, scan through the given
       parameter interval such that the corresponding η-orbit closes at that point;
-   6. if desired: for each Poincaré section, take the outermost closed orbit as
+   5. if desired: for each Poincaré section, take the outermost closed orbit as
       the coherent vortex barrier (if there exist any).
 
 ## Function documentation
 
 ### The meta-functions `ellipticLCS` and `constrainedLCS`
 
 The fully automated high-level functions are:
+
 ```@docs
 ellipticLCS
 constrainedLCS
 materialbarriers
 ```
+
 One of their arguments is a list of parameters used in the LCS detection. This
 list is combined in a data type called `LCSParameters`. The output is a list of `EllipticBarrier`s and a list of `Singularity`s.
 There is an option to retrieve all closed barriers (`outermost=false`), in
@@ -71,12 +78,15 @@ closed orbit computation, cf. [Closed orbit detection](@ref).
 ### Specific types
 
 These are the specifically introduced types for elliptic LCS computations.
+
 ```@docs
 LCSParameters
 EllipticBarrier
 EllipticVortex
 ```
+
 Another one is `Singularity`, which comes along with some convenience functions.
+
 ```@docs
 Singularity
 getcoords
@@ -88,29 +98,37 @@ getindices
 This is performed by [`singularity_detection`](@ref) for line fields
 (such as eigenvector fields of symmetric positive-definite tensor fields) and by
 [`critical_point_detection`](@ref) for classic vector fields.
+
 ```@docs
 singularity_detection
 critical_point_detection
 ```
+
 This function takes three steps. The first two are:
+
 ```@docs
 compute_singularities
 combine_singularities
 ```
+
 The third step is a postprocessing step, in which detected singularities are
 merged according to different heuristics.
+
 ```@docs
 combine_20
 combine_20_aggressive
 combine_31
 ```
+
 The function [`compute_singularities`](@ref) requires one of two signed distance
 functions for angles. These are [`s1dist`](@ref) for vector fields, and
 [`p1dist`](@ref) for line fields.
+
 ```@docs
 s1dist
 p1dist
 ```
+
 From all virtual/merged singularities those with a suitable index are selected.
 Around each elliptic singularity the tensor field is localized and passed on for
 closed orbit detection.
@@ -121,3 +139,16 @@ closed orbit detection.
 compute_returning_orbit
 compute_closed_orbits
 ```
+
+### Convenience functions
+
+First of all, [`Singularity`](@ref), [`EllipticBarrier`](@ref) and [`EllipticVortex`](@ref)
+objects can be passed as initial conditions to the [`flow`](@ref) function, which returns
+a (time-resolved) vector of corresponding objects. Moreover, we have advection with
+adaptive point insertion (known in oceanography as "Dritschel advection") and an function
+to compute the area of [`EllipticBarrier`](@ref) and [`EllipticVortex`](@ref) objects.
+
+```@docs
+flowgrow
+area
+```