GeoEco.Connectivity.LarvalDispersal.LarvalDispersal.RunSimulation2012

classmethod LarvalDispersal.RunSimulation2012(simulationDirectory, resultsDirectory, startDate, duration, simulationTimeStep=1.0, summarizationPeriod=24, a=None, b=None, settlementRate=0.8, useSensoryZone=False, sourcePatchIDs=None, destPatchIDs=None, excludePatchIDs=None, diffusivity=50.0, overwriteExisting=False)

Executes a larval dispersal simulation using the Treml et al. (2012) algorithm.

This tool simulates larval dispersal for the date, duration, and settlement parameters you specify using the hydrodynamic dispersal approach described by Treml et. al (2012). The tool works by by simulating dispersal from each patch, one at at time. For the focal patch, the simulator releases 1.0 units of larvae at each cell that is fully occupied by suitable habitat (i.e. cells where the patch cover raster is 1.0) and proportionally less at partially occupied cells (e.g. 0.5 units at cells where the patch cover raster is 0.5). It then circulates larvae around the study area by applying the Multidimensional Positive Definite Advection Transport Algorithm (MPDATA) (Smolarkiewicz and Margolin 1998) to the ocean currents. Larvae settle according to the settlement parameters as they drift over patches (including the source patch, if it is eligible for settlement).

Default values are provided for most parameters but you should carefully review the documentation for each and configure them according to your species and region of interest. You should also carefully examine any warning messages reported in the ArcGIS geoprocessing output window and adjust parameter values as needed to resolve potential problems.

It is often the case that the default Time Step parameter must be adjusted based on the spatial resolution of your analysis and the ocean currents present in your region of interest. We recommend that you first simulate dispersal from a single patch for a short period to test that the Time Step and other parameters are configured appropriately. To do this, set the Duration parameter to a small value such as 5 or 10 days and specify a single patch ID for the Patches That Disperse Larvae parameter. After carefully reviewing the output and adjusting parameters, increase the Duration to the final desired value and verify that it runs successfully for the single patch. Then adjust the Patches That Disperse Larvae parameter to conduct the simulation for all patches. Depending the size of the study area, the duration, the time step, the number of patches, and other factors, the full simulation can take minutes to hours to complete.

The algorithm implemented by this tool provides several important improvements over the Treml et al. (2008) algorithm, such as mass-balanced larval settlement and a more accurate numerical approach for the advection step. The 2008 algorithm is obsolete and we recommend it no longer be used.

References:

Smolarkiewicz PK, Margolin LG (1998) MPDATA: A Finite-Difference Solver for Geophysical Flows. Journal of Computational Physics 140: 459-480.

Treml EA, Roberts J, Chao Y, Halpin P, Possingham HP, Riginos C (2012) Reproductive output and duration of the pelagic larval stage determine seascape-wide connectivity of marine populations. Integrative and Comparative Biology 52(4): 525-537.

Treml EA, Halpin PN, Urban DL, Pratson LF (2008) Modeling population connectivity by ocean currents, a graph-theoretic approach for marine conservation. Landscape Ecology 23: 19-36.

Requires: MATLAB Runtime R2026a (which can be freely downloaded from https://www.mathworks.com/products/compiler/matlab-runtime.html) or the full version of MATLAB R2026a, ArcGIS Pro 3.6.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.6.0 or later, ArcGIS ‘spatial’ extension, Python numpy module, Python matplotlib module.

Parameters:

• simulationDirectory (str) –

  Existing larval dispersal simulation directory that has been loaded with ocean currents.

  The directory must have been created using the Create Larval Dispersal Simulation tool and then loaded with ocean currents using one of the tools provided for this purpose.

  Minimum length꞉ 1. Must exist.

• resultsDirectory (str) –

  Existing directory to receive files containing the results of the simulation. To create GIS-compatible visualizations from the files, run the Visualize Larval Dispersal Simulation Results (2012 Algorithm) tool.

  The files written to the results directory are:

  Parameters.ini - a text file in Microsoft Windows .INI format that lists the parameters used to execute the simulation.

  CompetencyCurve.png - a plot showing the proportion of larvae that are competent to settle at each time step. The x axis units are days. The y axis ranges from 0 (no larvae are competent) to 1 (all larvae are competent). The competency curve is configured by the Competency Gamma a and Competency Gamma b parameters.

  Results.pickle - a file in Python pickle format that contains the following matrices.

  • competencyCurve - a 1D numpy array, data type float32, of the values used to produce CompetencyCurve.png.

  • dispersalMatrix - a 3D numpy array, data type float32, that shows the cumulative quantity of larvae dispersed from every source patch to every destination patch, at each time the simulation is summarized. The matrix is indexed [from, to, t] where from represents the patch that is the source of larvae, to represents the patch that larvae have settled upon, and t represents the summarization period. from and to are 0-based indices into metadata['sourceIDs'] and metadata['destIDs']. For example, if metadata['sourceIDs'] and metadata['destIDs'] are both [3, 6, 8], dispersalMatrix[1, 2, :] is the larvae released from patch 6 that settled on patch 8. t=0 corresponds to the start of the simulation when no time steps have executed. At t=0, the entire matrix will be zero because no larvae will have settled yet. t=1 tallies the cumulative number of larvae that have settled after one summarization period has elapsed. t=2 tallies the cumulative quantity of larvae that have settled after two summarization periods, and so on. The units of the matrix are arbitrary units of larvae, where the value 1.0 corresponds to the quantity of larvae released at the start of the simulation in one cell that is fully covered by suitable habitat (i.e. the Patch Cover Raster has the value 1.0 in that cell).

  • settledDensityMatrix - a 3D numpy array, data type float32, that shows the cumulative quantity of larvae that have settled throughout the study area at each summarization step. The matrix indices are [x,y,t]. t=0 corresponds to the start of the simulation when no time steps have executed. At t=0, no larvae will have settled yet, so all cells of the matrix will be zero. t=1 tallies the cumulative quantity of larvae that have settled after one summarization period has elapsed. t=2 tallies the cumulative quantity of larvae that have settled after two summarization periods, and so on. The units of this matrix are the same as the dispersalMatrix.

  • suspendedDensityMatrix - a 3D numpy array, data type float32, that shows the instantaneous quantity of larvae suspended in the water column (i.e. those that have not settled or drifted off the edge of the map yet). The indexing and units of this matrix work the same as the settledDensityMatrix. At t=0, all larvae will be suspended in the water column over their source patches. At t>1, some larvae will have drifted into other cells.

  • metadata - a dictionary of the contents of the Parameters.ini file.

  Minimum length꞉ 1. Must exist.

• startDate (datetime) – Start date of the simulation. The larvae are released from the patches on this date. The simulation must contain currents that include this date.

• duration (float) –

  Duration of the simulation, in days. Typically this will be the pelagic larval duration (PLD) of the species you are studying.

  The simulation must contain currents that span the entire time range of the simulation.

  The simulation’s run time and memory requirements scale linearly with the duration and the number of patches from which larvae are released. We recommend you first try a short simulation such as 5 days for a single patch to quickly validate that the parameters produce reasonable results without running out of memory. Then increase the duration and number of patches to the desired values.

  Must be greater than 0.0.

• simulationTimeStep (float, optional) –

  Time step of the simulation, in hours.

  The time step defines the period at which larvae density is recalculated using the numerical advection-diffusion model. Smaller time steps increase the stability of the model and accuracy of the results but also the run time and computer memory requirements of the simulation.

  To check the model stability, this tool calculates a stability condition from the simulation time step, grid cell size, and maximum current velocity. If the stability condition is less than 2^(-1/2), approximately 0.7071, the simulation should be numerically stable. If the stability condition is greater than this value, the simulator will issue a warning but proceed with the simulation. To avoid anomalous results, you are strongly advised to reduce the time step until the stability condition is less than 0.7071.

  If the stability condition is substantially less than 0.7071, you can increase the simulation time step to reduce the execution time of the tool without sacrificing model stability (providing that you ensure the stability condition is less than 0.7071).

  Must be greater than 0.0.

• summarizationPeriod (int, optional) –

  The period, expressed as a number of simulation time steps, at which the simulation results should be summarized. The first summarization will occur at the start of the simulation, and subsequent summarizations will occur every time the period elapses. For example, if the time step is 1 hour and the summarization period is 24, summarizations will occur every 24 hours.

  The summarization period determines two time-related processes of the simulation:

  1. The temporal frequency at which mortality will be applied. Mortality is an optional biological process implemented by the Visualize Larval Dispersal Simulation Results tool. If you intend to apply mortality, we recommend that you choose a summarization period small enough that summarizations occur at least once per day. Because mortality is applied before settlement, if summarizations occur too infrequently, an unrealistically large number of larvae may be killed by mortality before they have a chance to settle. Please see the documentation for the Mortality Rate parameter of the Visualize Larval Dispersal Simulation Results tool for more information.

  2. The temporal frequency of rasters produced by the Visualize Larval Dispersal Simulation Results tool that show the density of larvae throughout the study area as the simulation progresses. Here, the summarization period is mainly an aesthetic choice, e.g. do you want density rasters to be produced at, say, a daily time step or something else? Your choice may depend on whether you intend to examine just a few time slices, in which case a long period is OK, or want to build a smooth animation, in which case a short period is better, resulting in many rasters each showing small changes.

  Whether you choose a short summarization period or a long one depends on your preferences for these processes. Both are implemented by the Visualize Larval Dispersal Simulation Results tool, which you execute after the simulation is complete.

  Visualization concerns aside, the main drawback to choosing a low summarization period is that the tool will require more memory to execute and utilize more disk space for the results. So long you as you have sufficient memory and disk space, there is no harm in setting a low summarization period.

  Minimum value꞉ 1.

• a (float, optional) –

  Shape parameter (often known as alpha or a) of the gamma cumulative distribution function used to represent the onset of larval settlement competency. If this parameter is omitted (the default) or set to zero, the larvae will be immediately competent (i.e. as soon as they are released).

  The Gamma Competency a and b parameters control the shape of the cumulative distribution function. The function is computed from these parameters using days as the units. At a*b days, approximately half the larvae will be competent. The b parameter controls the rate at which the larvae become competent, centered on this a*b value, with smaller values of b producing a faster rate. For example, with a=20 and b=0.1, about half will be competent at 2 days; they will start to become competent at about 1 day and nearly all be competent at 3.5 days. With a=200 and b=0.01, about 50% will be component at 2 days, as before, but they will not start to become competent until about 1.7 days and nearly all will be competent by 2.3 days.

  To help you visualize the competency function, the tool creates a plot of it in the results directory.

  For more about the gamma cumulative distribution function, see Wikipedia.

  Minimum value꞉ 0.0.

• b (float, optional) – Scale parameter (often known as theta or b) of the gamma cumulative distribution function used to represent the onset of larval settlement competency. Please see the documentation for the Competency Gamma a parameter for more information. Must be greater than 0.0.

• settlementRate (float, optional) –

  Rate at which competent larvae will settle when suspended over a patch, expressed as the proportion of larvae that will settle per day. For example, the default value 0.8 indicates that 80% of the larvae suspended over the patch for a day will settle.

  This parameter must be greater than 0 and less than or equal to 1.

  Only competent larvae may settle; incompetent larvae continue drifting. Larvae may only settle on patches that are eligible for settlement. If you specify values for the Patches Larvae Can Settle On parameter, only those patches will be eligible. (If you do not specify any values for that parameter, all patches are will be eligible.)

  Must be greater than 0.0. Maximum value꞉ 1.0.

• useSensoryZone (bool, optional) –

  Specifies whether the larvae will settle using a sensory zone.

  If True, all larvae suspended over a patch cell will be candidates for settling, regardless of the proportion of that cell that is occupied by suitable habitat. Under this scheme, it is assumed that the larvae employ a sensory zone that allows them to detect and move to any suitable habitat that occurs within the cell they occupy.

  If False, the default, the number of candidate larvae will be proportional to the proportion of cell that is occupied by suitable habitat. Under this scheme, it is assumed that larvae are evenly distributed across the cell they occupy and that they do not employ a sensory zone, allowing only the larvae that are over the fraction of the cell occupied by suitable habitat to settle.

  Only competent larvae may settle; incompetent larvae continue drifting. Larvae may only settle on patches that are eligible for settlement. If you specify values for the Patches Larvae Can Settle On parameter, only those patches will be eligible. (If you do not specify any values for that parameter, all patches are will be eligible.)

• sourcePatchIDs (list of int, optional) – List of IDs of patches from which larvae should be dispersed. If the list is empty, larvae will be dispersed from all patches except those listed for the Excluded Patches parameter. Minimum length꞉ 1.

• destPatchIDs (list of int, optional) – List of IDs of patches upon which larvae can settle. If the list is empty, larvae can settle on all patches except those listed for the Excluded Patches parameter. Minimum length꞉ 1.

• excludePatchIDs (list of int, optional) –

  List of IDs of patches to exclude from the simulation.

  This parameter is ignored if the two previous parameters are both provided, in which case those parameters specify which patches are included in the simulation.

  Minimum length꞉ 1.

• diffusivity (float, optional) –

  The horizontal diffusivity coefficient, in meters squared per second, to use in the simulation.

  It is recommended that you consult an oceanographer to determine this value. The original study from which this tool was developed (Treml et al. 2012) used the value 50. If you specify zero or omit this value, diffusion will not be performed, which will greatly reduce the simulation run time.

  Minimum value꞉ 0.0.

• overwriteExisting (bool, optional) – If True, the contents of the results directory will be overwritten, if it exists. If False, a ValueError will be raised if the contents already exist.

Returns:

Updated results directory.

Return type:

str