# Class ProtractedTree¶

## Class Documentation¶

class ProtractedTree : public virtual necsim::Tree

Contains the protracted tree class, for running simulations with procated speciation.

Subclassed by necsim::ProtractedSpatialTree

Public Functions

ProtractedTree()
bool calcSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.

Return
if true, speciation has occured
Parameters
• random_number: the generated random number from 0-1
• speciation_rate: the speciation rate to be applied
• no_generations: the number of generations a lineage has existed for

void speciateLineage(const unsigned long &data_position)

Performs the actual speciation. Includes handling of speciated lineages under protracted conditions.

Parameters
• data_position: the position in the array of TreeNodes for this lineage

bool getProtracted()

Gets the protractedness of the simulation. Overridden by protracted child classes.

Return

void setProtractedVariables(double speciation_gen_min, double speciation_gen_max)

Sets the protracted variables.

Parameters
• speciation_gen_min: the minimum number of generations to have passed before speciation is allowed
• speciation_gen_max: the maximum number of generations a lineage can exist for before it is speciated.

string getProtractedVariables()

Gets the protracted variables and returns them as a single, newline separated string.

Return
string containing the protracted variables, separated by newlines.

double getProtractedGenerationMin()

Gets the minimum number of generations a lineage must exist.

Return
double the number of generations a lineage must exist

double getProtractedGenerationMax()

Gets the maximum number of generations a lineage can exist.

Return
double the number of generations a lineage must exist

string protractedVarsToString()

Outputs the protracted variables to a string.

This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.

Return
string containing a list of the protracted speciation variables.

void applySpecRate(double sr, double t)

Applies the given speciation rate to the tree.

Note
Currently this just copies code from the version in tree, which is not ideal, but this avoids creating an extra function.
Parameters
• sr: the required speciation rate

void importSimulationVariables(const string &configfile)

Import the simulation variables from the command line structure.

This function parses the simulation variables, imports them from the config file, checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSimulation() can be run immediately afterwards.

Parameters
• configfile: the path to the config file containing parameters to parse.

void importSimulationVariables(ConfigParser config)

Import the simulation variables from a ConfigOption.

This function parses the simulation variables, imports them (from either the command line or a config file), checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSim() can be run immediately afterwards.

Parameters
• config: the set of config parameters to import

void runFileChecks()

Runs the basic file existence checks. Checks for paused simulations and file existence.

void wipeSimulationVariables()

Resets all the simulation variables.

void internalSetup(shared_ptr<SimParameters> sim_parameters_in)

Sets up the simulation parameters from the one provided.

Intended for usage with metacommunity application. No output directory is expected.

Parameters
• sim_parameters_in: the simulation parameters to set up the simulation with

bool checkOutputDirectory()

Asserts that the output directory is not null and exists. If it doesn’t exist, it attempts to create it.

Return
true if output creates successfully
Exceptions
• Fatal_Exception: if the output directory creation fails

void checkSims()

Checks for existing paused simulations to resume from Sets bPaused if there are.

This version uses the default values read from the config file.

void checkSims(string output_dir, long seed, long job_type)

Checks for existing paused simulations to resume from.

Sets bPaused if there are.

This version uses the values supplied to the function directly

Parameters
• output_dir: the output directory to check for
• seed: the seed for paused sims
• job_type: the job_type for paused sims

void setParameters()

Move the parameters from the sim_parameters object to their relevant parameters.

bool hasPaused()

Gets the has_paused variable for resuming sims.

Return
if the simulation has paused

vector<double> getTemporalSampling()

Gets the map autocorrel times.

long long getSeed()

Getter for the simulation seed.

Return
Returns the seed

long long getJobType()

Gets the job type for the simulation. This is a reference number for the jobs.

Return
Returns the job type

void setSeed(long long seed_in)

Sets the simulation seed for the random number generator.

This function should only be called once.

The seed is set within the NR object. This will be fixed for the simulation and is only performed once.

Parameters
• seed_in: the desired seed to set for the simulation

double getGeneration() const

Gets the generation timer for the simulation.

Return
the number of generations that have passed

unsigned long getInitialCount()

Gets the initial number of individuals.

Return
the number of initial individuals to simulate

unsigned long setObjectSizes()

Sets the sizes of grid, active and data, based on the number of individuals counted from the samplemask.

Return
a count of the number of individuals that exist in the simulation

void setup()

The setup function for generating the simulation objects.

The simulation parameters are set from comargs using setParameters(). Generates and fills the active and grid objects as well as importing all the maps from the supplied files.

void setInitialValues()

Sets the starting values for required parameters.

void setSimStartVariables()

Sets the variables at the start of a simulation for temporary data.

This is not the main set-up routine, which creates the permanent data structures including maps, the coalescence tree and active lineage listings.

void printSetup()

Prints the statement for the setup initiation.

This is stored in a separate function so that it can be called in isolation by child classes.

void setTimes()

Sets the temporal sampling points from the time config file.

void determineSpeciationRates()

Determines the speciation rates to apply and then applies them to the coalescence tree post-simulation.

Detects speciation rates from the config files supplied.

void addSpeciationRates(vector<long double> spec_rates_in)

Adds the speciation rates to those to be applied.

void generateObjects()

Assigns the objects sizes in memory and fills with the starting lineages.

unsigned long fillObjects(const unsigned long &initial_count)

Fills the active and data objects with the starting lineages.

Parameters
• initial_count: the number of individuals expected to exist

void runSingleLoop()

Runs a single loop of the simulation.

bool runSimulation()

Run the entire simulation given the start conditions already defined by setup().

Setup is assumed to have been run already. This function is the main function containing the main loop of the simulation. At the end of the simulation, returns true if the simulation is complete, false otherwise.

Return
true if the simulation has completed

bool runSimulationNoGillespie()

Runs the simulation using the standard coalescence algorithm.

Return
true if the simulation has completed

void writeSimStartToConsole()

Writes to the console that the simulation is beginning.

void writeStepToConsole()

Write the step counter to console. This function should only be called in debugging mode.

void incrementGeneration()

Increments the generation counter and step references.

void chooseRandomLineage()

Chooses a random lineage from active.

The index of the random lineage is stored in this_step, as chosen. Also records the required variables for the step process, like x, y position.

void updateStepCoalescenceVariables()

Updates the coalescence variables in the step object.

void speciation(const unsigned long &chosen)

Speciation to supplied lineage.

Also calls the removeOldPos() and switchPositions() functions for removing the lineage out of active reference.

Parameters
• chosen:

void removeOldPosition(const unsigned long &chosen)

Removes the old position within active.

Parameters
• chosen: the desired active reference to remove from the grid.

void switchPositions(const unsigned long &chosen)

Switches the chosen position with the endactive position.

Parameters
• chosen: the chosen lineage to switch with endactive.

void calcNextStep()

Calculates the next step for the simulation.

void coalescenceEvent(const unsigned long &chosen, unsigned long &coalchosen)

Perform the coalescence between lineages. Once coalesced, lineages are removed from the active scope.

Parameters
• chosen: the chosen lineage for coalescence
• coalchosen: the target lineage for coalscence

void checkTimeUpdate()

Checks if the number of lineages should be expanded at another sample point.

void addLineages(double generation_in)

Adds the required lineages at the generation time.

Parameters
• generation_in: the generation to add lineages at

bool checkProportionAdded(const double &proportion_added)

Randomly checks if a lineage should be added, based on the proportion added.

Return
true if the lineage should be added, false otherwise
Parameters
• proportion_added: the proportion of lineages that should be added

void checkSimSize(unsigned long req_data, unsigned long req_active)

Checks the size of the main active and data objects is large enough.

Parameters
• req_data: the required data object size
• req_active: the required active object size

void makeTip(const unsigned long &tmp_active, const double &generation_in, vector<TreeNode> &data_added)

Sets the active reference to a tip, if it isn’t one already. Otherwise, creates a new tip for the new generation time.

Parameters
• tmp_active: the reference in active
• generation_in: the generation to set for the new lineage
• data_added: vector of lineages to add to data

void convertTip(unsigned long i, double generationin, vector<TreeNode> &data_added)

Creates a new reference in data containing the tip with a new generation counter.

Parameters
• i: the reference in active of the lineage to make a tip
• generationin: the generation to make the lineage a tip at
• data_added: vector of lineages to add to the data object

bool stopSimulation()

Finalises the simulation, and performs the correct tasks depending if the sim has been paused or finished.

Return

void applySpecRate(long double sr, double t)

Applies the given speciation rate to the tree.

Parameters
• sr: the required speciation rate
• t: the required time of speciation

void applySpecRate(long double sr)

Overloaded version of applySpecRates for the default generation (0.0).

Parameters
• sr: the speciation rate to apply to the tree

void applySpecRateInternal(long double sr, double t)

Applies the given speciation rate to the tree, but does not output to a file. Instead returns a pointer to the nodes object.

Parameters
• sr: the required speciation rate
• t: the required time of speciation

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Gets the sorted cumulative species abundances from the contained TreeList.

For use with metacommunity applications

Return
row of cumulative species abundances

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances from the internal tree.

Return
the species abundances
Parameters
• community_reference: the community reference

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundances from the internal tree.

Return
the species abundances

ProtractedSpeciationParameters setupCommunity()

Sets up Community member to point to the same output database as the simulation.

Return
the protracted speciation parameters to set up

void setupCommunityCalculation(long double sr, double t)

Sets up the generation of the tree object.

Parameters
• sr: the required speciation rate
• t: the required time of speciation

void applyMultipleRates()

Applies multiple speciation rates to the coalescence tree, ignoring repeated speciation rates.

Speciation rates are read from the speciation_rates object, which should have already been calculated.

void sqlOutput()

Copy the in-memory database to file.

This function should not be called if the database is already opened on disc, and won’t do anything if it is.

void createAndOutputData()

Creates the output data objects and outputs important simulation data to a database file.

void outputData()

Outputs the simulation data (including the coalescence tree) to an sql database.

void sortData()

Sort and process the species list so that the useful information can be extracted from it.

void writeTimes()

Writes the times to the terminal for simulation information.

void openSQLDatabase()

Opens a connection to the in-memory database, or the on-disk database, depending on the compilation options.

void sqlCreate()

Generates the SQL database file from the full simulation data. This allows for greater analysis of the data after completion of the simulation.

void setupOutputDirectory()

Creates the output directory, if it doesn’t already exist, and deletes any existing database with the output name.

void sqlCreateSimulationParameters()

Creates the SIMULATION_PARAMETERS table in the SQL database.

string simulationParametersSqlInsertion()

Creates a string containing the SQL insertion statement for the simulation parameters.

Return
string containing the SQL insertion statement

void simPause()

Pause the simulation and dump data from memory.

shared_ptr<ofstream> initiatePause()

Checks the output folder exists and initiates the pause.

Return
the output file stream to save objects to

void dumpMain(shared_ptr<ofstream> out)

Saves the main simulation variables to file.

Parameters
• out: the output file stream to save the object to

void dumpActive(shared_ptr<ofstream> out)

Saves the active object to file.

Parameters
• out: the output file stream to save the object to

void dumpData(shared_ptr<ofstream> out)

Saves the data object to file.

Parameters
• out: the output file stream to save the object to

void completePause(shared_ptr<ofstream> out)

Completes the pause routine and outputs the sql dump.

Parameters
• out: the output stream to close up

void setResumeParameters(string pausedir, string outdir, unsigned long seed, unsigned long job_type, unsigned long new_max_time)

Sets the resume variables so that the simulation can be resumed.

The pause directory can be the same as the output directory if it is desirable to save to the same location.

Parameters
• pausedir: the directory containing the pause folder for resuming the simulation
• outdir: the directory to write simulation output to
• seed: the simulation seed
• job_type: the simulation job reference number
• new_max_time: the maximum simulation time to run for in seconds (0 keeps old simulation max time)

void setResumeParameters()

Sets the resume variables to the defaults.

shared_ptr<ifstream> openSaveFile()
void loadMainSave(shared_ptr<ifstream> in1)

Loads the main simulation parameters from the save file into memory.

void loadDataSave(shared_ptr<ifstream> in1)

Loads the data object from the save file into memory.

void loadActiveSave(shared_ptr<ifstream> in1)

Loads the active object from the save file into memory.

void initiateResume()

Checks for resuming and prints to the terminal.

void simResume()

Resumes the simulation from a previous state.

Reads in the parameters and objects from file and re-starts the simulation.

void addGillespie(const double &g_threshold)
bool runSimulationGillespie()

Protected Attributes

shared_ptr<vector<TreeNode>> data
unsigned long enddata
shared_ptr<SimParameters> sim_parameters
shared_ptr<RNGController> NR
vector<long double> speciation_rates
bool seeded
long long seed
long long job_type
string times_file
vector<double> reference_times
bool uses_temporal_sampling
time_t start
time_t sim_start
time_t sim_end
time_t now
time_t sim_finish
time_t out_finish
time_t time_taken
vector<DataPoint> active
unsigned long endactive
unsigned long startendactive
unsigned long maxsimsize
Community community
long steps
unsigned long maxtime
double generation
double deme
double deme_sample
long double spec
string out_directory
shared_ptr<SQLiteHandler> database
bool sim_complete
bool has_imported_vars
Step this_step
string sql_output_database
bool bFullMode
bool bResume
bool bConfig
bool has_paused
bool has_imported_pause
bool bIsProtracted
string pause_sim_directory
bool using_gillespie