API Reference

calculate_encirclement_number(D_values, omega_values; n_power_max=0)

Calculates the number of encirclements of the origin for a given list of complex values D_values corresponding to a list of frequencies omega_values.

calculate_encirclement_number(D_func, omega_values, p; n_power_max=0, σ=0.0)

Calculates the number of encirclements by evaluating a characteristic equation D_func(λ, p) where λ = σ + 1im * ω.

argument_principle_with_MDBM(D_func, mdbm, omega_coars; σ=0.0)

Enriches a coarse grid evaluation of the argument principle with MDBM results. Assumes the last axis of the MDBM problem is ω. n_power_max is calculated internally.

triangulation_of_MDBM_results(mdbm, p_uniq, color_values)

Triangulates the MDBM results for visualization using color_values for the mesh.

argument_principle_solver_with_MDBM(D_func, axlist, ω_coars; σ=0.0)

Complete workflow for MDBM enrichment using brute-force evaluation for background.

sensitivity_mapping_with_MDBM(D_func, axlist; σ=0.0, ω_max=1e6, Niter=4)

HIGH-LEVEL: Uses the integration-based sensitivity metric (estimated σ) as the MDBM objective. This provides the most robust and informative stability map.

calculate_unstable_roots_direct(D_func, p, σ=0.0; ...)

Calculates the number of unstable roots using direct integration of the phase. Use n_roots_to_track to optimize:

• 0: Max speed, only Z calculation.
• 1: Track the closest root (default).
• N: Track up to N local minima.

calculate_unstable_roots_p_vec(D_func, params_vec::AbstractVector; ...)

Vectorized stability sweep using multi-threading.

calculate_unstable_roots_quadgk(D_func, p, σ=0.0; ω_max=1e6, reltol=1e-5, abstol=1e-5, n_power_max=nothing)

Calculates the number of unstable roots using QuadGK.jl (adaptive 1D quadrature).

calculate_unstable_roots_quadgk_p_vec(D_func, params_vec::AbstractVector; ...)

Vectorized stability sweep using QuadGK and multi-threading.

calculate_unstable_roots_fixed_step(D_func, p, σ=0.0; ω_max=1e6, steps=1000, n_power_max=nothing)

ULTRA-FAST: Fixed-step trapezoidal integration. Zero overhead, perfect for real-time sweeps.

calculate_unstable_roots_fixed_step_p_vec(D_func, params_vec::AbstractVector; ...)

Vectorized stability sweep using ultra-fast fixed-step integration.

get_n_power_max(D_func, p, σ=0.0; ω_large=1e6)

Estimates the highest power of the polynomial (npowermax).

get_D_from_model(bc_model, λ::Complex, p, ::Val{N}; u_eq = zeros(SVector{N, Float64}), verbosity::Int = 0) where {N}

Extracts the characteristic equation value D(λ) from a black-box DDE model. Uses ForwardDiff to extract the Jacobian matrix and calculates its determinant.

find_largest_circle(S::BitMatrix, Xvector::AbstractVector, Yvector::AbstractVector; 
                    N::Int=0, sub_pixel_depth::Int=5, scale_x::Float64=1.0, scale_y::Float64=1.0)
find_largest_circle(S::BitMatrix; N::Int=0, sub_pixel_depth::Int=5, scale_x::Float64=1.0, scale_y::Float64=1.0)

Finds the largest physical circle containing only true values within a boolean matrix S. Incorporates anisotropic scaling to correctly map ellipses in physical space.

Keyword Arguments

• N::Int: Number of coarse subsampling iterations for speed. Default is 0.
• sub_pixel_depth::Int: Number of fractional refinement steps. Default is 5.
• scale_x, scale_y: Scaling factors to normalize the physical axes to a 1:1 aspect ratio.

Returns

A NamedTuple: (R_scaled, x, y, i, j) where R_scaled is the radius in the scaled mathematical space, and x, y are the unscaled physical coordinates of the center.

find_largest_circle(true_pts, false_pts, boundary_pts; N=0, scale_x=1.0, scale_y=1.0)

Finds the largest inscribed ellipse using unordered 2D point clouds, incorporating anisotropic scaling to normalize the search space.

Arguments

• true_pts: Array of valid 2D coordinates (e.g., [(x1, y1), (x2, y2), ...]).
• false_pts: Array of invalid 2D coordinates (obstacles).
• boundary_pts: Array of precise 2D boundary points separating true and false regions.
• N::Int: Number of coarse subsampling iterations for speed. Default is 0.
• scale_x, scale_y: Scaling factors to normalize physical axes to a 1:1 aspect ratio.

Returns

A NamedTuple: (R_scaled, x, y) representing the exact scaled radius and the unscaled physical coordinates of the center.

find_largest_circle(mdbm; N=0, scale_x=1.0, scale_y=1.0, kwargs...)

Automatically extracts Stable (S), Unstable (U), and Boundary (B) point clouds from an MDBM_Problem object. It then performs a two-step optimization:

1. A fast, scaled grid search for an initial guess.
2. A robust, omnidirectional pattern search for mathematically exact sub-pixel refinement.

Keyword Arguments

• N::Int: Number of subsampling steps for the initial guess. Default is 0.
• scale_x, scale_y: Normalization scales to prevent anisotropic "pipe" traps.
• max_iters, tol, decay_rate, num_angles: Advanced tuning parameters passed directly to the refine_circle_robust step.

Returns

A NamedTuple: (R_scaled, x, y, valid) containing the exact scaled radius, the unscaled physical center coordinates, and a validation flag.

find_largest_circle_transposed(true_pts, false_pts, boundary_pts; N::Int=0, scale_x=1.0, scale_y=1.0)

A wrapper for find_largest_circle that accepts transposed 2D point cloud data. Automatically parses 2xN Matrices or [X_vector, Y_vector] Vectors into the correct format.

generate_ellipse_points(x_center, y_center, R_scaled; scale_x=1.0, scale_y=1.0, Nellips=360)

Generates the [X_points, Y_points] arrays required to plot the resulting scaled circle as an ellipse in the original physical space.

refine_circle_robust(x_init, y_init, boundary_pts; U=[], scale_x=1.0, scale_y=1.0, 
                     max_iters=2000, tol=1e-6, decay_rate=0.9, num_angles=16)

An advanced radial pattern search with adaptive step sizing. It navigates narrow, angled corridors by searching in a full circle and smoothly shrinking/growing its step size to prevent getting trapped in local bottlenecks.

_to_tuples(pts)

Internal helper function to convert various 2D point cloud formats (2xN Matrix, Vector of Vectors [X, Y]) into a standard Vector of (x, y) tuples.