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 inputs:

• if crit = NoReconnections(), then reconnections are disabled and this returns a NullReconnectionCache;
• otherwise, it returns a ReconnectionCache.

In the second case, the detection of reconnection pairs can follow two different strategies:

• if the domain is infinite (default), a naive iteration across all filament segment pairs

is performed;

• if the domain is periodic, an efficient cell lists algorithm is used (see the CellLists module).

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 default option use_velocity = true.

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.

NoReconnections <: ReconnectionCriterion

Used to disable filament reconnections.

ReconnectBasedOnDistance <: ReconnectionCriterion
ReconnectBasedOnDistance(d_crit; use_velocity = true, 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.

• 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.

should_reconnect(
    c::ReconnectionCriterion,
    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.