Geodesic elliptic material vortices

ellipticLCS(T::AbstractMatrix, xspan, yspan, p; kwargs...)

Computes elliptic LCSs as null-geodesics of the Lorentzian metric tensor field given by shifted versions of T on the 2D computational grid spanned by xspan and yspan. p is a LCSParameters-type container of computational parameters. Returns a list of EllipticBarrier-type objects.

Keyword arguments

• outermost=true: only the outermost barriers, i.e., the vortex boundaries are returned, otherwise all detected transport barrieres;
• verbose=true: show intermediate computational information;
• unique_vortices=true: filter out vortices enclosed by other vortices;
• suggested_centers=[]: suggest vortex centers (of type Singularity);
• debug=false: whether to use the debug mode, which avoids parallelization for more precise error messages;
• singularity_predicate = nothing: provide an optional callback to reject certain singularity candidates.

constrainedLCS(T::AbstractMatrix, xspan, yspan, p; kwargs...)
constrainedLCS(T::AxisArray, p; kwargs...)

Computes constrained transport barriers as closed orbits of the transport vector field on the 2D computational grid spanned by xspan and yspan. p is an LCSParameters-type container of computational parameters. Returns a list of EllipticBarrier-type objects.

The keyword arguments and their default values are:

• outermost=true: only the outermost barriers, i.e., the vortex boundaries are returned, otherwise all detected transport barrieres;
• verbose=true: show intermediate computational information
• debug=false: whether to use the debug mode, which avoids parallelization for more precise error messages.

materialbarriers(odefun, xspan, yspan, tspan, lcsp;
    on_torus=false, δ=1e-6, tolerance=1e-6, p=SciMLBase.NullParameters(), kwargs...)

Calculate material barriers to diffusive and stochastic transport on the material domain spanned by xspan and yspan, where the averaged weighted CG tensor is computed at the time instance contained in tspan. The argument lcsp must be of type LCSParameters, and contains parameters used for the elliptic vortex detection.

Container for parameters used in elliptic LCS computations.

Fields

• boxradius: "radius" of localization square for closed orbit detection
• indexradius=1e-1boxradius: radius for singularity type detection
• merge_heuristics: a list of MergeHeuristics for combining singularities
• n_seeds=100: number of seed points on the Poincaré section
• pmin=0.7: lower bound on the parameter in the $\eta$-field
• pmax=2.0: upper bound on the parameter in the $\eta$-field
• rdist=1e-4boxradius: required return distances for closed orbits
• tolerance_ode=1e-8boxradius: absolute and relative tolerance in orbit integration
• maxiters_ode::Int=2000: maximum number of integration steps
• max_orbit_length=8boxradius: maximum length of orbit length
• maxiters_bisection::Int=20: maximum steps in bisection procedure
• only_enclosing::Bool=true: whether the orbit must enclose the starting point of the Poincaré section
• only_smooth::Bool=true: whether or not to reject orbits with "corners".
• only_uniform::Bool=true: whether or not to reject orbits that are not uniform

Example

p = LCSParameters(2.5)
LCSParameters(2.5, 0.25, true, 100, 0.7, 2.0, 0.00025, 2.5e-8, 1000, 20.0, 30)

This is a container for coherent vortex boundaries. An object barrier of type EllipticBarrier can be easily plotted by plot(barrier.curve), or plot!([figure, ]barrier.curve) if it is to be overlaid over an existing plot.

Fields

• curve: a vector of tuples, contains the coordinates of coherent vortex boundary points;
• core: location of the vortex core;
• p: contains the parameter value of the direction field $\eta_{\lambda}^{\pm}$, for which the curve is a closed orbit;
• s: a Bool value, which encodes the sign in the formula of the direction field $\eta_{\lambda}^{\pm}$ via the formula $(-1)^s$.

This is a container for an elliptic vortex, as represented by the vortex's center and a list barriers of all computed EllipticBarriers.

Fields

• center: location of the vortex center;
• barriers: vector of EllipticBarriers.

abstract type MergeHeuristic

Abstract supertype for merge heuristics, which currently include Combine, Combine20, Combine20Aggressive, Combine31.

Container type for critical points of vector fields or singularities of line fields.

Fields

• coords::SVector{2}: coordinates of the singularity
• index::Rational: index of the singularity

getcoords(singularities)

Extracts the coordinates of singularities, a vector of Singularitys. Returns a vector of SVectors.

getindices(singularities)

Extracts the indices of singularities, a vector of Singularitys.

singularity_detection(T, xspan, yspan, combine_distance; merge_heuristics=(Combine20(),)) -> Vector{Singularity}
singularity_detection(T::AxisArray, combine_distance; merge_heuristics=(Combine20(),)) -> Vector{Singularity}

Calculate line-field singularities of the first eigenvector of T by taking a discrete differential-geometric approach. Singularities are calculated on each cell. Singularities with distance less or equal to combine_distance are combined by averaging the coordinates and adding the respective indices. The heuristics listed in merge_heuristics are used to merge singularities, cf. LCSParameters.

Return a vector of Singularitys.

critical_point_detection(vs, xspan, yspan, combine_distance, dist=S1Dist();
    merge_heuristics=(combine_20,)) -> Vector{Singularity}
critical_point_detection(vs::AxisArray, combine_distance, dist=S1Dist();
    merge_heuristics=(combine_20,)) -> Vector{Singularity}

Computes critical points of a vector/line field vs, potentially given as an AxisArray. Critical points with distance less or equal to combine_distance are combined by averaging the coordinates and adding the respective indices. The argument dist is a signed distance function for angles: choose S1Dist() for vector fields, and P1Dist() for line fields; cf. compute_singularities. MergeHeuristics listed in merge_heuristics, cf. LCSParameters, are applied to combine singularities.

Returns a vector of Singularitys.

compute_singularities(v, xspan, yspan, dist=S1Dist()) -> Vector{Singularity}    
compute_singularities(v::AxisArray, dist=S1Dist()) -> Vector{Singularity}

Computes critical points and singularities of vector and line fields v, respectively. The argument dist is a signed distance function for angles. Choose s1dist (default) for vector fields, and p1dist for line fields.

Combine(dist)(sing_coordinates) -> Vector{Singularity}

This function does the equivalent of: build a graph where singularities are vertices, and two vertices share an edge iff the coordinates of the corresponding vertices (given by sing_coordinates) have a distance leq dist. Find all connected components of this graph, and return a list of their mean coordinate and sum of sing_indices.

Combine20()(singularities)

Determines singularities which are mutually closest neighbors and combines them as one, while adding their indices.

Combine31()(singularities)

Takes the list of singularities in singularities and combines them so that any -1/2 singularity whose three nearest neighbors are 1/2 singularities becomes an elliptic region, provided that the -1/2 singularity is in the triangle spanned by the wedges. This configuration is common for OECS, applying to material barriers on a large turbulent example yielded only about an additional 1% material barriers.

Combine20Aggressive()(singularities)

A heuristic for combining singularities which is likely to have a lot of false positives.

S1Dist()(α, β)

Computes the signed length of the angle of the shortest circle segment going from angle β to angle α, as computed on the full circle.

Examples

julia> dist = S1Dist();

julia> dist(π/2, 0)
1.5707963267948966

julia> dist(0, π/2)
-1.5707963267948966

P1Dist()(α, β)

Computes the signed length of the angle of the shortest circle segment going from angle β to angle α [± π], as computed on the half circle.

Examples

julia> dist = P1Dist();

julia> dist(π, 0)
0.0

compute_returning_orbit(vf, seed::SVector{2}, save::Bool=false, maxiters=2000, tolerance=1e-8, max_orbit_length=20.0)

Computes returning orbits under the velocity field vf, originating from seed. The optional argument save controls whether intermediate locations of the returning orbit should be saved. Returns a tuple of orbit and statuscode (0 for success, 1 for maxiters reached, 2 for out of bounds error, 3 for other error).

compute_closed_orbits(ps, ηfield, cache; kwargs...)

Compute the (outermost) closed orbit for a given Poincaré section ps, a vector field constructor ηfield, and an LCScache cache.

Keyword arguments

• rev=true: determines whether closed orbits are sought from the outside inwards (true) or from the inside outwards (false);
• p::LCSParameters: an object holding the parameters for the LCS computation; see LCSParameters.

struct FlowGrowParams

Container for parameters used in point-inserting flow computations; see flowgrow.

Fields

• maxcurv=0.3: maximal bound on the absolute value of the discrete curvature;
• mindist=0.1: least acceptable distance between two consecutive points;
• maxdist=1.0: maximal acceptable distance between two consecutive points.

flowgrow(odefun, curve, tspan, params; kwargs...)

Advect curve with point insertion by the ODE with right hand side odefun over the time interval tspan, evaluated at each element of tspan. This method is known in oceanography as Dritschel's method. The point insertion method is controlled by the parameters stored in params::FlowGrowParams; cf. FlowGrowParams. Keyword arguments kwargs are passed to the flow function.

Convenience methods for EllipticBarrier and [EllipticVortex] objects in place of curve exist. In this case, the method returns a vector of length length(tspan) of corresponding objects.

area(polygon)

Compute the enclosed area of polygon, which can be of type Vector{SVector{2}}, EllipticBarrier or EllipticVortex. In the latter case, the enclosed area of the outermost (i.e., the last EllipticBarrier in the barriers field) is computed.

centroid(polygon)

Compute the center (of mass) of polygon, which can be of type Vector{SVector{2}}, EllipticBarrier or EllipticVortex. In the latter case, the center of the outermost (i.e., the last EllipticBarrier in the barriers field) is computed.

clockwise(barrier, velocity, t0; p=nothing) -> Bool
clockwise(vortex, velocity, t0; p=nothing) -> Bool

Determine whether a given vortex or barrier is instantaneously (at t0) rotating clockwise due to the velocity field velocity. The keyword argument p is a parameter passed to velocity, for instance the interpolant of the interpolating velocity field interp_rhs.

Clockwise-rotating vortices correspond to anticyclones in the Northern hemisphere and to cyclones in the Southern hemisphere.

Base.extrema(barrier) -> (LL, UR)
Base.extrema(vortex) -> (LL, UR)

Compute an axis-aligned, rectangular bounding box around an EllipticVortex or an EllipticBarrier. Returns the coordinates of the lower left corner LL and of the upper right corner UR.

isinside(p, polygon)

Determine whether the point p (or Singularity) lies inside polygon, which can be of type Vector{SVector{2}}, EllipticBarrier or EllipticVortex. In the latter case, the outermost (i.e., the last EllipticBarrier in the barriers field) is used.