Class SimulateDispersal

Class Documentation

class SimulateDispersal

Contains routines for importing a density map file, running a dispersal kernel n times on a landscape and record the dispersal distances.

Public Functions

SimulateDispersal()
necsim::SimulateDispersal::~ SimulateDispersal()
void setSequential(bool bSequential)

Sets the is_sequential flag.

Parameters
  • bSequential: if true, dispersal events are selected using the end point of the last dispersal distance for the start of the next move event

void setSimulationParameters(shared_ptr<SimParameters> sim_parameters, bool print = true)

Sets the pointer to the simulation parameters object.

Parameters
  • sim_parameters: pointer to the simulation parameters to use
  • print: if true, writes the parameters out using writeInfo()

void importMaps()

Import the maps from the simulation parameters.

void setSizes()

Creates the map of steps to parameter references and initialises object sizes.

void setDispersalParameters()

Sets the dispersal parameters in the DispersalCoordinator.

void setSeed(unsigned long s)

Sets the seed for the random number generator.

Parameters
  • s: the seed

void setOutputDatabase(string out_database)

Sets the output database for writing results to.

Parameters
  • out_database: path to the output database

void setNumberRepeats(unsigned long n)

Sets the number of repeats to run the dispersal kernel for.

Parameters
  • n: the number of repeats

void setNumberSteps(const vector<unsigned long> &s)

Sets the number of steps to run each repeat of the dispersal kernel for when recording mean distance travelled.

Parameters
  • s: a vector containing each step variable to record the distance at

void setNumberWorkers(unsigned long n)

Sets the number of threads launched to parallelise the distance simulation.

Parameters
  • n: the number of workers

unsigned long getMaxNumberSteps()

Gets the maximum number of steps that is to be applied.

Return

void storeCellList()

Calculates the list of cells to choose randomly from.

const Cell &getRandomCell()

Gets a random cell from the list of cells.

Return
a Cell object reference containing the x and y positions to choose from

void getEndPoint(Cell &this_cell)

Checks the density a given distance from the start point, calling the relevant landscape function.

This also takes into account the rejection sampling of density based on the maximal density value from the map.

Parameters
  • this_cell: Cell containing the x and y coordinates of the starting position

void getEndPoint(Cell &this_cell, DispersalCoordinator &dispersal_coordinator)

Checks the density a given distance from the start point, calling the relevant landscape function.

This also takes into account the rejection sampling of density based on the maximal density value from the map.

Parameters
  • this_cell: Cell containing the x and y coordinates of the starting position
  • dispersal_coordinator: Reference to the dispersal coordinator to use

template<bool chooseRandomCells = false>
void runDistanceLoop(const unsigned long bidx, const unsigned long eidx, const unsigned long num_repeats, std::mutex &mutex, unsigned long &finished, DispersalCoordinator &dispersal_coordinator, double &generation)

Runs the distance simulation edix-bidx times and reports the progress.

Template Parameters
  • chooseRandomCells: If true random walks will be chosen randomly from the cells vector, otherwise uses cells[bidx:edix]
Parameters
  • bidx: First inclusive index into the cells vector of random walk origins to simulate in this worker
  • eidx: Last exclusive index into the cells vector of random walk origins to simulate in this worker
  • num_repeats: The number of repeats to average over for each cell
  • mutex: The mutex to synchronise progress feedback to the user
  • finished: The total number of cells simulated across all workers
  • dispersal_coordinator: Reference to the dispersal corrdinator to use
  • generation: Reference to the generation variable used byt the dispersal coordinator

template<bool chooseRandomCells = false>
void runDistanceWorker(const unsigned long seed, const unsigned long bidx, const unsigned long eidx, const unsigned long num_repeats, std::mutex &mutex, unsigned long &finished)

Runs the distance simulation eidx-bidx times on a separate worker and reports the progress.

Template Parameters
  • chooseRandomCells: If true random walks will be chosen randomly from the cells vector, otherwise uses cells[bidx:edix]
Parameters
  • seed: Seed to use to initialse the per worker rng and dispersal coordinator
  • bidx: First inclusive index into the cells vector of random walk origins to simulate in this worker
  • eidx: Last exclusive index into the cells vector of random walk origins to simulate in this worker
  • num_repeats: The number of repeats to average over for each cell
  • mutex: The mutex to synchronise progress feedback to the user
  • finished: The total number of cells simulated across all workers

void runMeanDispersalDistance()

Simulates the dispersal kernel for the set parameters, storing the mean dispersal distance.

void runMeanDistanceTravelled()

Simulates the dispersal kernel for the set parameters, storing the mean distance travelled.

void runAllDistanceTravelled()

Simulates the dispersal kernel for the set parameters on all habitable cells, storing the mean distance travelled.

void runSampleDistanceTravelled(const vector<Cell> &samples)

Simulates the dispersal kernel for the set parameters on the given sample cells, storing the mean distance travelled.

Parameters
  • samples: Vector of cells to be sampled during the distance simulation

void writeRepeatInfo(unsigned long i)

Writes the information about this repeat to the logger.

void writeDatabase(string table_name)

Writes out the distances to the SQL database.

Parameters
  • table_name: the name of the table to output to, either ‘DISPERSAL_DISTANCE’ or ‘DISTANCES_TRAVELLED’

void writeParameters(string table_name)

Writes the simulation parameters to the output SQL database.

Parameters
  • table_name: the name of the table to output to, either ‘DISPERSAL_DISTANCE’ or ‘DISTANCES_TRAVELLED’

void clearParameters()

Clears the parameters from the internal objects so that another dispersal simulation can be run, if necessary.

void checkMaxParameterReference()

Gets the maximum parameter reference from the output SQL database and saves val + 1 to parameter_reference Assumes that the database exists.

unsigned long checkMaxIdNumber(string table_name)

Gets the maximum id number from the output SQL database and returns val + 1 Assumes that the database exists.

Note
this function does not check for SQL injection attacks and should not be used with variable function names.
Return
the maximum id + 1 from the given table
Parameters
  • table_name: the name of the table to check for max(id) in

Protected Attributes

shared_ptr<Landscape> density_landscape
DataMask data_mask
DispersalCoordinator dispersal_coordinator = {}
shared_ptr<SimParameters> simParameters
shared_ptr<RNGController> random
unsigned long seed
SQLiteHandler database
vector<tuple<unsigned long, Cell, double>> distances
map<unsigned long, unsigned long> parameter_references
vector<Cell> cells
unsigned long num_repeats
set<unsigned long> num_steps
unsigned long num_workers
double generation
bool is_sequential
unsigned long max_parameter_reference