Reconnections

Reconnections

Module for dealing with the reconnection of filaments.

Reconnections.init_cache(
    crit::ReconnectionCriterion,
    fs::AbstractVector{<:AbstractFilament},
    Ls::NTuple{3, Real} = (Infinity(), Infinity(), Infinity()),
) -> AbstractReconnectionCache

Initialise reconnection cache.

Required arguments are a reconnection criterion crit and the domain dimensions (or periods) Ls. The type of cache will vary depending on the chosen reconnection criterion.

reconnect!(
    [callback::Function],
    cache::AbstractReconnectionCache,
    fs::AbstractVector{<:AbstractFilament},
    [vs::AbstractVector{<:AbstractVector}],
) -> NamedTuple

Perform filament reconnections according to chosen criterion.

Note that, when a filament self-reconnects, this creates new filaments, which are appended at the end of fs.

Moreover, this function will remove reconnected filaments if their number of nodes is too small (typically $< 3$, see check_nodes).

Optionally, vs can be a vector containing all instantaneous filament velocities. In this case, this will be used to discard reconnections between filaments which are moving in opposite directions. This is required if the ReconnectBasedOnDistance criterion is used with its option use_velocity = true (default if max_passes = 1).

Returns

This function returns a NamedTuple with fields:

• reconnection_count: number of reconnections;

• reconnection_length_loss: decrease of filament length due to reconnections. This is simply an estimate for the difference in filament length before and after a reconnection. It is unrelated to (and does not include) filament removal (see below). Uses the straight segment approximation;

• filaments_removed_count: number of filaments removed after reconnection. This happens when a filament reconnects with itself, splitting into two new filaments, and one or both of these filaments have an insufficient number of discretisation nodes;

• filaments_removed_length: length of removed filaments. We use a straight segment approximation (no quadratures) to estimate the filament lengths.

Callback function

Optionally, one may pass a callback which will be called whenever the vector of filaments fs is modified. Its signature must be the following:

callback(f::AbstractFilament, i::Int, mode::Symbol)

where f is the modified filament, i is its index in fs, and mode is one of:

• :modified if the filament fs[i] was modified;
• :appended if the filament was appended at the end of fs (at index i);
• :removed if the filament previously located at index i was removed.

ReconnectionCriterion

Abstract type describing a criterion for filament reconnections.

Implemented reconnection criteria include:

• NoReconnections: disables reconnections;

• ReconnectBasedOnDistance: reconnects filament segments which are closer than a critical distance;

• ReconnectFast: considers segments as straight lines, enabling to perform all required reconnections in a single pass.

NoReconnections <: ReconnectionCriterion

Used to disable filament reconnections.

ReconnectBasedOnDistance <: ReconnectionCriterion
ReconnectBasedOnDistance(d_crit; max_passes = 1, use_velocity = (max_passes == 1), decrease_length = true, cos_max = 0.97)

Reconnects filament segments which are at a distance d < d_crit.

Optional keyword arguments

• use_velocity: if true (default), use filament velocity information in reconnections. For now, this is used to discard a reconnection between two points if they are instantaneously getting away from each other. If max_passes > 1, then use_velocity must be set to false.

• max_passes: maximum number of scans through all segment pairs to detect and perform reconnections. In a single pass, a filament can only be reconnected at most once. Therefore, this parameter can be useful to make sure that all required reconnections have been performed. Setting max_passes > 1 also requires use_velocity = false.

• decrease_length: if true (default), a reconnection will only be performed if it will decrease the total filament length. Since, for vortices, the total energy is roughly related to the vortex length, this means that reconnections should always tend to dissipate energy.

• cos_max: allows to disable reconnections of nearly parallel segments. Two segments are considered to be "nearly parallel" if cos(θ) > cos_max. The default value cos_max = 0.97 disables reconnections when the angle between lines is $θ < \arccos(0.97) ≈ 14°$. Note that the angle $θ$ is signed (it takes values in $[-1, 1]$). Negative angles mean that the segments are antiparallel, and in this case reconnections are always performed.

ReconnectFast <: ReconnectionCriterion
ReconnectFast(d_crit; max_passes = 1, nthreads = Threads.nthreads(), use_velocity = false, decrease_length = true, cos_max = 0.97)

Reconnects filament segments which are at a distance d < d_crit.

This criterion is similar to ReconnectBasedOnDistance but with important differences:

• filament segments are considered as straight lines (which may be less accurate);

• each filament can be reconnected multiple times, meaning that fewer passes are needed to perform all required reconnections;

• one can combine use_velocity = true with max_passes > 1.

Moreover, this criterion accepts an nthreads option which allows to manually choose the number of threads to use. In particular, if nthreads = 1, a serial implementation will be used which generally needs a small number of passes (so it can in fact be faster if running with a small number of threads).

This criterion only supports periodic domains.

See ReconnectBasedOnDistance for details on criterion parameters.

should_reconnect(
    c::ReconnectBasedOnDistance,
    fx::AbstractFilament, fy::AbstractFilament, i::Int, j::Int;
    periods,
) -> Union{Nothing, NamedTuple}

Check whether two filaments should reconnect according to the chosen criterion.

Checks for a possible reconnection between filament segments fx[i:i+1] and fy[j:j+1].

If the filament segments should reconnect, this function returns a NamedTuple with reconnection information, which includes in particular all the fields returned by find_min_distance.

Otherwise, returns nothing if the filament segments should not reconnect.