# Class Landscape¶

## Class Documentation¶

class Landscape

Contains all maps and provides the functions for accessing a grid cell in the correct temporal and spacial location.

The function runDispersal() also provides the move routine, provided two alternative methods for moving individuals. Contains routines for easy setting up and switching between the different coordinate systems required. Set the map parameters with setDims(), import the map files with calcFineMap(), calcCoarseMap() etc, then set up the landscape type using setLandscape() and sethistorical(). Usage is then by runDispersal() for running a dispersal kernel on the landscape, and then getVal() to obtain the density at the desired coordinates. All coordinates should be given in reference to the simulation grid, and offsets for the fine and coarse map are calculated automatically.

Public Functions

Landscape()

The default constructor.

unsigned long getHabitatMax()

Gets the maximum habitat value from any map.

Return
the maximum habitat value

bool hasHistorical()

Returns if the simulation is using historical maps.

Return
true if using historical maps

Map<uint32_t> &getFineMap()

Gets the fine map object.

Return
reference to the fine map

Map<uint32_t> &getCoarseMap()

Gets the coarse map object.

Return
reference to the coarse map

const Map<uint32_t> &getFineMap() const

Gets the fine map object.

Return
reference to the fine map

const Map<uint32_t> &getCoarseMap() const

Gets the coarse map object.

Return
reference to the coarse map

void setDims(shared_ptr<SimParameters> mapvarsin)

Sets the dimensions of the grid, the area where the species are initially sampled from. This function must be run before any of the calc map functions to allow for the correct deme allocation.

Parameters
• mapvarsin: the SimParameters object containing the map variables to import

bool checkMapExists()

Checks that the map files exist (or are none/null).

Return
true if all the paths exist in configs

void calcFineMap()

Imports the fine map object from file and calculates the correct values at each point. Without a map to input, the fine map will simply be a matrix of 1s.

void calcHistoricalFineMap()

Imports the historical fine map object from file and calculates the correct values at each point. Without a map to input, the historical fine map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.

void calcCoarseMap()

Imports the coarse map object from file and calculates the correct values at each point. Without a map to input, the coarse map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.

void calcHistoricalCoarseMap()

Imports the historical coarse map object from file and calculates the correct values at each point. Without a map to input, the historical coarse map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.

void setTimeVars(double gen_since_historical_in, double habitat_change_rate_in)

Sets the time variables.

Parameters
• gen_since_historical_in: the time (in generations) since a historical habitat state was achieved.
• habitat_change_rate_in: the rate of transform of the habitat up until the historical time. A value of 0.2 would mean 20% of the change occurs linearlly up until the historical time and the remaining 80% occurs in a jump to the historical state.

void calcOffset()

Calculates the offset and extremeties of the fine map.

Note that setting dispersal_relative_cost to a value other than 1 can massively increase simulation time.

bool checkAllDimensionsZero()

Checks that all dimensions for all maps are zero.

If this is true, then it means we can calculate actual offsets and dimensions from the maps, otherwise the values from the parameters will be used.

Return
true if all map offsets are zero

void calculateOffsetsFromMaps()

Calculates the offsets from the map files directly.

Assumes that all required maps have been imported.

void calculateOffsetsFromParameters()

Uses the inputted parameters to set the offsets for the map files.

void validateMaps()

Checks that the map file sizes are correct and that each value on the fragmented maps is less than the historical maps. This should be disabled in simulations where habitat sizes are expected to shrink as well as grow.

bool updateMap(double generation)

Checks if an update needs to be performed to the map configuration, and if it does, performs the update.

Return
true if the map has been updated
Parameters
• generation: the current generation timer

bool requiresUpdate()

Checks if the map will require another update.

Return
true if another update will be performed

void doUpdate()

void resetHistorical()

Resets the historical variables to recalculate historical maps.

Required for rcoalescence compatability.

bool isHistorical()

Gets the historical boolean.

Return
the historical map state.

void setHistorical(const bool &historical_in)

Sets the historical state of the system.

Parameters
• historical_in: the historical state.

double getHistorical()

Get the historical map time.

Return
double the historical map time

string getLandscapeType()
void checkHistorical(double generation)

Checks if the historical state has been reached.

If there are no historical maps, this function will do nothing.

Parameters
• generation: the time to check at.

void setLandscape(const string &is_infinite)

Sets the landscape functions to either infinite or finite.

Parameters
• is_infinite: a string of either closed, infinite, tiled_fine or tiled_coarse, corresponding to the relevant landscape type.

unsigned long getVal(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version involves a call to the function pointer, *getValFunc, so that the correct call to either getValFinite() or getValInfinite is made.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValCoarse(const double &xval, const double &yval, const double &current_generation)

Gets the value from the coarse maps, including linear interpolating between the historical and present maps.

Return
the value of the map at the given coordinates and time
Parameters
• xval: the x coordinate
• yval: the y coordinate
• current_generation: the current generation timer

unsigned long getValFine(const double &xval, const double &yval, const double &current_generation)

Gets the value from the fine maps, including linear interpolating between the historical and present maps.

Return
the value of the map at the given coordinates and time
Parameters
• xval: the x coordinate
• yval: the y coordinate
• current_generation: the current generation timer

unsigned long getValFinite(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes finite landscape.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValInfinite(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValCoarseTiled(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of tiled coarse maps.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValFineTiled(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of tiled fine maps.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValCoarseClamped(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of clamped coarse maps.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValFineClamped(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of clamped fine maps.

Return
the value on the correct map at the correct space.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long convertSampleXToFineX(const unsigned long &x, const long &xwrap) const

Gets the x position on the fine map, given an x and x wrapping.

Note that this function will not check if the value is actually within bounds of the fine map, and an error will likely be thrown by the matrix referencing if this is the case.

Return
the x location on the fine map
Parameters
• x: the x coordinate on the sample mask
• xwrap: the x wrapping of the sample mask.

unsigned long convertSampleYToFineY(const unsigned long &y, const long &ywrap) const

Gets the y position on the fine map, given a y and y wrapping.

Note that this function will not check if the value is actually within bounds of the fine map, and an error will likely be thrown by the matrix referencing if this is the case.

Return
the y location on the fine map
Parameters
• y: the y coordinate on the sample mask
• ywrap: the y wrapping of the sample mask.

void convertFineToSample(long &x, long &xwrap, long &y, long &ywrap)

Converts the fine map coordinates to the sample grid coordinates. Main conversion is in a call to convertCoordinates, but also makes sure the returned types are long integers.

Parameters
• x: the x coordinate to modify
• xwrap: the x wrapping to modify
• y: the y coordinate to modify
• ywrap: the y wrapping to modify

unsigned long getInitialCount(double dSample, DataMask &samplemask)

Counts the number of spaces available in the initial species space. Requires the samplemask to check the sampling area.

Return
the total number of individuals predicted to initially exist on the map.
Parameters
• dSample: the sample proportion (from 0 to 1).
• samplemask: the DataMask object to sample from.

shared_ptr<SimParameters> getSimParameters()

Gets the mapvars object pointer for referencing simulation parameters.

Return

bool checkMap(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &generation)

Checks whether the point is habitat or non-habitat.

Return
a boolean of whether the map is habitat or non-habitat.
Parameters
• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension.
• ywrap: the number of wraps in the y dimension.
• generation: the current generation time.

bool isOnFine(const double &x, const double &y, const long &xwrap, const long &ywrap)

Checks whether the point comes from the fine grid.

Return
a boolean of whether the location is on the fine map
Parameters
• x: the x position
• y: the y position
• xwrap: the number of wraps in the x dimension
• ywrap: the number of wraps in the y dimension

bool isOnCoarse(const double &x, const double &y, const long &xwrap, const long &ywrap)

Checks whether the point comes from the coarse grid.

Return
a boolean of whether the location is on the fine map
Parameters
• x: the x position
• y: the y position
• xwrap: the number of wraps in the x dimension
• ywrap: the number of wraps in the y dimension

bool isOnMap(const double &x, const double &y, const long &xwrap, const long &ywrap)

Checks that the point supplied is within map limits. If the map is inifite, returns true.

Return
a boolean of whether the location is on the fine map
Return
true if the point is within the map limits
Parameters
• x: the x position
• y: the y position
• xwrap: the number of wraps in the x dimension
• ywrap: the number of wraps in the y dimension

void fixGridCoordinates(double &x, double &y, long &xwrap, long &ywrap)

Fixes the coordinates to be correctly within the original grid, altering the xwrap and ywrap consequently.

Parameters
• x: the x position.
• y: the y position.
• xwrap: the number of wraps in the x dimension.
• ywrap: the number of wraps in the y dimension.

unsigned long runDispersal(const double &dist, const double &angle, long &startx, long &starty, long &startxwrap, long &startywrap, bool &disp_comp, const double &generation)

The function that actually performs the dispersal. It is included here for easier programming and efficiency as the function doesn’t need to perform all the checks until the edge of the fine grid.

Return
the density value at the end dispersal point
Parameters
• dist: the distance travelled (or “distance energy” if dispersal_relative_cost is not 1).
• angle: the angle of movement.
• startx: the start x position.
• starty: the start y position.
• startxwrap: the start number of wraps in the x dimension.
• startywrap: the start number of wraps in the y dimension.
• disp_comp: a boolean of whether the dispersal was complete or not. This value is returned false if dispersal is to habitat, false otherwise.
• generation: the time in generations since the start of the simulation.

double distanceToNearestHabitat(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, const double &generation)

Calculates the distance from the start position to the nearest habitat cell.

Return
the distance from the start position to the nearest habitat cell
Parameters
• start_x: the start x coordinate
• start_y: the start y coordinate
• start_x_wrap: the starting x wrapping
• start_y_wrap: the starting y wrapping
• generation: the generation timer

void findNearestHabitatCell(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, double &end_x, double &end_y, const double &generation)

Gets the nearest habitat cells from a particular point, spiraling outwards.

Parameters
• start_x: the start x coordinate
• start_y: the start y coordinate
• start_x_wrap: the starting x wrapping
• start_y_wrap: the starting y wrapping
• end_x: the end x coordinate value to modify
• end_y: the end y coordinate value to modify
• generation: the generation timer

bool findAnyHabitatCell(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, double &end_x, double &end_y, const double &generation)

Finds the nearest habitat cell using a much slower method (scanning the entire map for cells.

Return
true if a habitat cell is found
Parameters
• start_x: the start x coordinate
• start_y: the start y coordinate
• start_x_wrap: the starting x wrapping
• start_y_wrap: the starting y wrapping
• end_x: the end x coordinate value to modify
• end_y: the end y coordinate value to modify
• generation: the generation timer

string printVars()

Prints some selected Map variables to the terminal.

Return
the string containing the map variables to print

void clearMap()

Wipes the map of all variables. Only really useful for testing purposes.

void recalculateHabitatMax()

Recalculates the habitat map maximum by checking the maximums for each of the relevant map files (fine, coarse and historicals).

Protected Types

typedef unsigned long (Landscape::*fptr)(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &dCurrentGen)

Protected Attributes

Map<uint32_t> fine_map
Map<uint32_t> historical_fine_map
Map<uint32_t> coarse_map
Map<uint32_t> historical_coarse_map
shared_ptr<SimParameters> mapvars
long fine_x_min = {}
long fine_y_min = {}
long coarse_x_min = {}
long coarse_y_min = {}
long fine_x_max = {}
long fine_y_max = {}
long coarse_x_max = {}
long coarse_y_max = {}
long fine_x_offset = {}
long fine_y_offset = {}
long coarse_x_offset = {}
long coarse_y_offset = {}
unsigned long scale = {}
long x_dim = {}
long y_dim = {}
double deme = {}
bool check_set_dim
double dispersal_relative_cost = {}
double update_time = {}
double habitat_change_rate = {}
double gen_since_historical = {}
double current_map_time
bool is_historical
bool has_historical
unsigned long habitat_max
unsigned long fine_max
unsigned long coarse_max
unsigned long historical_fine_max
unsigned long historical_coarse_max
string landscape_type
bool infinite_boundaries
string NextMap
bool has_coarse
fptr getValFunc

Friends

ostream &operator<<(ostream &os, const Landscape &r)

Operator for outputting the Map object variables to an output stream. This is used for storing the Map object to file.

Return
the output stream.
Parameters
• os: the output stream.
• r: the Map object to output.

istream &operator>>(istream &is, Landscape &r)

Operator for inputting the Map object variables from an input stream. This is used for reading the Map object from file.

Return
the input stream.
Parameters
• is: the input stream.
• r: the Map object to input to.