# Class SpeciesList¶

## Class Documentation¶

class SpeciesList

Contains a list of the species that exist at one location. The Row object, list, contains the active reference number, for looking up the lineage in a Row of Datapoint objects. Also contains the functions for correctly generating coalescence probabilities and list management.

Note that the maximum size of the list is constrained by the maximum size of unsigned long. Any simulation requiring more individuals per cell than this will unlikely finish in any reasonable time anyway.

Public Functions

SpeciesList()

Default constructor.

~SpeciesList()

Default destructor.

void initialise(unsigned long maxsizein)

Initialises the list to the specified size.

Parameters
• maxsizein: the maximum list size.

void setMaxsize(unsigned long maxsizein)

Sets the maxsize without altering the actual size of list.

Parameters
• maxsizein: The new maximum size to set.

void setSpecies(unsigned long index, unsigned long new_val)

Set specific entry to a particular species reference number.

This version throws an error if the space is empty.

Parameters
• index: the location in list of the species.
• new_val: the new species reference to set list[index] to.

void setSpeciesEmpty(unsigned long index, unsigned long new_val)

Set specific entry to a particular species reference number.

Note this version will throw a runtime_error if the space is not empty

Parameters
• index: the location in list of the species
• new_val: the new species reference to set list[index] to

void setNext(unsigned long n)

Set the next active lineage (for wrapping purposes).

Parameters
• n: the lineage to set as the first wrapped lineage.

void setNwrap(unsigned long nr)

Set the number of wrapping lineages.

Parameters
• nr: the number of wrapped lineages.

unsigned long addSpecies(const unsigned long &new_spec)

Add a new species to the first empty place and return the position of the lineage.

Return
the location the species has been added to.
Parameters
• new_spec: the new species reference to place in the first empty space.

void deleteSpecies(unsigned long index)

Removes the species at the specified index. The species number will be replaced with 0, indicating no species present.

Older versions of this function re-shuffled the list so that all species came at the top.

Parameters
• index: the index of the species to remove from the list.

void decreaseNwrap()

Decreases the nwrap by one.

Indicates the number of species wrapped at the location of this SpeciesList object has decreased by one.

void increaseListSize()

Increases the list size by one.

void increaseNwrap()

Increases the nwrap by one.

Indicates the number of species wrapped at the location of this SpeciesList object has increased by one.

void changePercentCover(unsigned long newmaxsize)

Changes the maximum size of the SpeciesList. Currently identical to setMaxsize.

Parameters
• newmaxsize: the new maximum size to be applied.

unsigned long getRandLineage(const shared_ptr<RNGController> &rand_no)

Get a random species reference number from all the potential entries. Updated alternative version returns any entry, including empty cells, giving the probability of coalescence as well.

Return
the reference of the random lineage. 0 indicates an empty space.
Parameters
• rand_no: the random number object to pass (for maintaining the same seed throughout simulations).

unsigned long getLineageIndex(unsigned long index) const

Get the species reference number from a particular entry.

Return
the species reference at the specified location.
Parameters
• index: the location of the species to reference.

unsigned long getNext() const

Get the next_active variable.

Return

unsigned long getNwrap() const

Getter for the nwrap.

Return
the number of wrapped lineages currently at this grid cell.

unsigned long getListSize() const

Getter for the list size.

Return
the number of lineages currently directly within the SpeciesList.

unsigned long getMaxSize() const

Getter for the maximum size of the SpeciesList object.

Return
the maximum number of lineages that can exist currently.

unsigned long getListLength() const

Gets the length of the list object.

Return
the length of the list object

void wipeList()

Empties the list of any data and fills the list with zeros.

double getCoalescenceProbability() const

Gets the probability of coalescence within this object in a single time step.

Return
the probability of coalescence

Friends

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

Outputs the SpeciesList object to an output stream. Allows for piping to the terminal or writing the object to a file.

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

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

Inputs the SpeciesList object from an input stream. Allows for reading data from a file or string stream.

Parameters
• is: the input stream.
• r: the SpeciesList object to input to.