Central class to construct and own megafauna habitats and populations. More...

#include <world.h>

Classes
struct	InsfileContent
	All simulation instructions from the TOML instruction file. More...

struct	SimDayOptions
	Options passed to simulate_day() More...

Public Member Functions
	World (const std::string instruction_filename, const SimMode mode=SimMode::Simulate)
	Constructor: Read parameters and HFTs from instruction file. More...

	World (const std::shared_ptr< const Parameters > params, const std::shared_ptr< const HftList > hftlist)
	Constructor for unit tests. More...

	World ()
	Constructor: Create deactivated `World` object. More...

	~World ()
	Default destructor. More...

void	create_simulation_unit (std::shared_ptr< Habitat > habitat)
	Compose a new simulation from an external habitat and new populations. More...

const Parameters &	get_params () const
	Get global simulation parameters. More...

const std::list< SimulationUnit > &	get_sim_units () const
	List of all the simulation units in the world. More...

const bool	is_activated () const
	Whether this World object is in SimMode::Simulate mode. More...

void	simulate_day (const Date &date, const SimDayOptions &opts=SimDayOptions())
	Iterate through all simulation units and perform simulation for this day. More...

void	simulate_day (const Date &date, const bool do_herbivores)
	Iterate through all simulation units and perform simulation for this day. More...

Private Member Functions
int	get_habitat_count_per_agg_unit () const
	Get the number of habitats per aggregation unit. More...

const HftList &	get_hfts () const
	Get the immutable list of herbivore functional types. More...

Output::WriterInterface *	construct_output_writer () const
	Create Output::WriterInterface implementation according to params. More...

Static Private Member Functions
static InsfileContent	read_instruction_file (const std::string &filename)
	Helper function to initialize World::InsfileContent object. More...

Private Attributes
const SimMode	mode = SimMode::Simulate
	Whether this object is going to simulate or just lint an instruction file. More...

bool	simulation_units_checked = false
	Whether the habitat counts per aggregation unit have been checked. More...

struct Fauna::World::InsfileContent	insfile

int	days_since_last_establishment
	Number of days since extinct populations were re-established. More...

std::unique_ptr< Fauna::Date >	last_date
	The date from the last call to simulate_day() More...

const std::unique_ptr< Output::Aggregator >	output_aggregator
	Collects output data per time interval and aggregation unit. More...

std::unique_ptr< Output::WriterInterface >	output_writer
	Output writer as selected by Parameters::output_format. More...

std::list< SimulationUnit >	sim_units
	List of all the simulation units in the world. More...

const std::unique_ptr< WorldConstructor >	world_constructor
	Helper class to construct various elements of the megafauna world. More...

Detailed Description

Central class to construct and own megafauna habitats and populations.

Constructor & Destructor Documentation

◆ World() [1/3]

World::World	(	const std::string	instruction_filename,
		const SimMode	mode = `SimMode::Simulate`
	)

Constructor: Read parameters and HFTs from instruction file.

Parameters

instruction_filename	Path to the instruction file for the megafauna model. It contains global settings and herbivore parameters.
mode	Whether we are only checking the instruction file or running a simulation. If set to SimMode::Lint, no files will be created.

Exceptions

std::logic_error If a selected instruction file parameter is not implemented.

◆ World() [2/3]

World::World	(	const std::shared_ptr< const Parameters >	params,
		const std::shared_ptr< const HftList >	hftlist
	)

Constructor for unit tests.

Warning: This function may be changed in the future depending on the needs of unit tests.

Parameters

params	Global simulation parameters that would normally be parsed from the instruction file.
hftlist	HFT parameters that would normally be parsed from the instruction file.

Exceptions

std::invalid_argument If either of the shared pointers is NULL.

◆ World() [3/3]

World::World ( )

Constructor: Create deactivated World object.

Even if the megafauna model should be completely deactivated, there might be a need to create a "dummy" World instance. An object created with this constructor will not simulate anything.

Deprecated:: Rather don’t create a Fauna::World object at all instead of a “dummy” one. For example, use std::shared_ptr<Fauna::World> and leave the pointer NULL if you don’t need it.

◆ ~World()

World::~World ( )

default

Default destructor.

Member Function Documentation

◆ construct_output_writer()

Output::WriterInterface * World::construct_output_writer ( ) const

private

Create Output::WriterInterface implementation according to params.

Exceptions

std::logic_error If Parameters::output_format is not implemented.

See also: output_writer

◆ create_simulation_unit()

void World::create_simulation_unit ( std::shared_ptr< Habitat > habitat )

Compose a new simulation from an external habitat and new populations.

The new simulation unit will be owned by World and released as soon as the Habitat instance is marked as to be deleted from extern.

If the World class was constructed without an instruction file, this function will do nothing, but will still throw an error if the parameter is NULL.

Parameters

habitat Pointer to an instance of a class that implements Habitat, given externally by the vegetation model. The World object will release it after it has been marked as dead (Habitat::kill()) externally.

Exceptions

std::invalid_argument If habitat is NULL.

◆ get_habitat_count_per_agg_unit()

int World::get_habitat_count_per_agg_unit ( ) const

private

Get the number of habitats per aggregation unit.

Exceptions

std::logic_error If the number of habitats differs between aggregation units.

See also: Parameters::one_hft_per_habitat

◆ get_hfts()

const HftList & World::get_hfts ( ) const

private

Get the immutable list of herbivore functional types.

◆ get_params()

const Parameters & World::get_params ( ) const

Get global simulation parameters.

The global megafauna parameters are public because they might be required by the calling vegetation model to check back against vegetation-specific settings.

Exceptions

std::logic_error If the member variable hasn’t been set (if the World class was created without an instruction file).

◆ get_sim_units()

const std::list< SimulationUnit > & Fauna::World::get_sim_units ( ) const

inline

List of all the simulation units in the world.

This is read-only. Unit tests can use it to check if create_simulation_unit() works.

◆ is_activated()

const bool Fauna::World::is_activated ( ) const

inline

Whether this World object is in SimMode::Simulate mode.

◆ read_instruction_file()

World::InsfileContent World::read_instruction_file ( const std::string & filename )

staticprivate

Helper function to initialize World::InsfileContent object.

◆ simulate_day() [1/2]

void Fauna::World::simulate_day	(	const Date &	date,
		const bool	do_herbivores
	)

inline

Iterate through all simulation units and perform simulation for this day.

Parameters

date	The current simulation day.
do_herbivores	see SimDayOptions::do_herbivores

Deprecated:: Use simulate_day(const Date&, const SimDayOptions&)

◆ simulate_day() [2/2]

void World::simulate_day	(	const Date &	date,
		const SimDayOptions &	opts = `SimDayOptions()`
	)

Iterate through all simulation units and perform simulation for this day.

This is the central access point to start the perform the herbivore simulations.

If a Habitat instance is marked as dead (Habitat::is_dead()), the corresponding simulation unit will be released from memory.

If the World class was constructed without parameters, this function will do nothing.

Parameters

date	The current simulation day.
opts	Options for today’s simulation.

Exceptions

std::invalid_argument	If `date` has not been correctly incremented by one day since the last call. However, no exception will be thrown if SimDayOptions::reset_date is `true`.
logic_error	If Parameters::one_hft_per_habitat, but for at least one aggregation unit (Habitat::get_aggregation_unit()) the number of associated habitats is not an integer multiple of the number of HFTs.
logic_error	If the aggregation units (Habitat::get_aggregation_unit()) created with create_simulation_unit() do not all have the same number of habitats each. It would bias the output if the means for each aggregation unit would have different “sample counts.”

Member Data Documentation

◆ days_since_last_establishment

int Fauna::World::days_since_last_establishment

private

Number of days since extinct populations were re-established.

◆ insfile

struct Fauna::World::InsfileContent Fauna::World::insfile

private

◆ last_date

std::unique_ptr<Fauna::Date> Fauna::World::last_date

private

The date from the last call to simulate_day()

This is to check that the simulation days are coming in correctly from the vegetation/host model.

◆ mode

const SimMode Fauna::World::mode = SimMode::Simulate

private

Whether this object is going to simulate or just lint an instruction file.

◆ output_aggregator

const std::unique_ptr<Output::Aggregator> Fauna::World::output_aggregator

private

Collects output data per time interval and aggregation unit.

◆ output_writer

std::unique_ptr<Output::WriterInterface> Fauna::World::output_writer

private

Output writer as selected by Parameters::output_format.

◆ sim_units

std::list<SimulationUnit> Fauna::World::sim_units

private

List of all the simulation units in the world.

All objects are owned by World.

◆ simulation_units_checked

bool Fauna::World::simulation_units_checked = false

private

Whether the habitat counts per aggregation unit have been checked.

By setting this variable, we don’t need to check on every call of simulate_day(), which might save some calculations. Instead, habitat counts are only checked when they have changed through create_simulation_unit().

See also: get_habitat_count_per_agg_unit()

◆ world_constructor

const std::unique_ptr<WorldConstructor> Fauna::World::world_constructor

private

Helper class to construct various elements of the megafauna world.

The documentation for this class was generated from the following files:

/home/docs/checkouts/readthedocs.org/user_builds/modular-megafauna-model/checkouts/latest/include/Fauna/world.h
/home/docs/checkouts/readthedocs.org/user_builds/modular-megafauna-model/checkouts/latest/src/Fauna/world.cpp

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ World() [1/3]

◆ World() [2/3]

◆ World() [3/3]

◆ ~World()

Member Function Documentation

◆ construct_output_writer()

◆ create_simulation_unit()

◆ get_habitat_count_per_agg_unit()

◆ get_hfts()

◆ get_params()

◆ get_sim_units()

◆ is_activated()

◆ read_instruction_file()

◆ simulate_day() [1/2]

◆ simulate_day() [2/2]

Member Data Documentation

◆ days_since_last_establishment

◆ insfile

◆ last_date

◆ mode

◆ output_aggregator

◆ output_writer

◆ sim_units

◆ simulation_units_checked

◆ world_constructor