Spatially-explicit neutral community simulation with convergence checks — spesim_simulate_neutral

Simulates a spatially-explicit neutral or hybrid community model, running until the community composition converges or a maximum number of steps is reached. This is an internal function called by generate_heterogeneous_distribution when the model family is set to "neutral_hubbell_like" or "hybrid".

Usage

spesim_simulate_neutral_recruitment(poly, P)

Arguments

poly: An sf polygon defining the sampling domain.
P: A fully materialized parameter list from load_config(). It must also contain convergence parameters: NEUTRAL_MAX_STEPS, NEUTRAL_CONVERGENCE_INTERVAL, NEUTRAL_CONVERGENCE_THRESHOLD, NEUTRAL_CONVERGENCE_PATIENCE.

Value

An sf POINT layer with species and environmental data.

Details

The simulation follows a Moran-style process of death, followed by recruitment. Recruitment can be from a local parent (with dispersal limitation) or from an external metacommunity.

Convergence: Instead of running for a fixed number of steps, this implementation checks for convergence. At intervals specified by NEUTRAL_CONVERGENCE_INTERVAL, it calculates the Bray-Curtis dissimilarity between the current community's species abundance vector and the vector from the previous check. If this dissimilarity is below NEUTRAL_CONVERGENCE_THRESHOLD for a number of consecutive checks equal to NEUTRAL_CONVERGENCE_PATIENCE, the community is considered to have reached a stationary state, and the simulation stops. A NEUTRAL_MAX_STEPS parameter prevents infinite loops.

Performance: All polygon domain checks use a compiled C++ ray-casting point-in-polygon test (see pip_cpp), with the polygon ring coordinates extracted once and cached for the duration of the simulation. The initial community placement is performed with a single vectorised rejection-sample call rather than J individual calls, and the same pre-built tester is threaded through every candidate-location filter in the main loop.