Tutor

Table of Contents

• Herbivores Tutorials
  • How to add a new herbivore class
  • How to add a new energy expenditure component
  • How to add a new foraging limit
  • How to add a new digestive limit
  • How to add a new reproduction model
  • How to add a new diet composer
  • How to add a new mortality factor
• Forage Tutorials
  • How to add a new forage type
  • How to change forage net energy content
  • How to add a new forage distribution algorithm
• Parameters Tutorials
  • How to add a new global parameter
  • How to add a new HFT parameter
• Output Tutorials
  • How to add a new output variable
  • How to write output to another format

Instructions how expand the code base for your own needs.

Herbivores Tutorials

How to add a new herbivore class

The model design allows a complete substitution of the herbivore class. If you want to implement a completely new model behaviour, you can derive your new class from Fauna::HerbivoreInterface and write it from scratch. If you want to build upon the base functionality, derive it from Fauna::HerbivoreBase.

Then, derive a new class from Fauna::PopulationInterface to manage and construct your object instances. In Fauna::WorldConstructor::create_populations(), create all instances of that population class for one habitat.

Relationships for a new herbivore type.

How to add a new energy expenditure component

• Add a new enum entry in Fauna::ExpenditureComponent.
• TOML instruction file: Add new possible string value for the HFT parameter expenditure.components in Fauna::InsfileReader::read_hft(); include it in the error message.
• Implement your algorithm as a free function or a class. See expenditure_components.h for examples.
• Call your model in Fauna::HerbivoreBase::get_todays_expenditure().
• Update the UML diagram in Section HerbivoreBase.

How to add a new foraging limit

A foraging limit constrains the daily uptake of forage mass by a herbivore individual. Foraging limits are implemented as functors (without using the strategy design pattern, though). Which ones are activated is defined by foraging.limits in Fauna::Hft. They are called in Fauna::GetForageDemands::get_max_foraging().

• Add a new enum entry in Fauna::ForagingLimit.
• TOML instruction file: Add a new possible string value for the HFT parameter foraging.limits in Fauna::InsfileReader::read_hft()
• Implement your foraging limit (preferably as a function object in the file foraging_limits.h, but you can do as you wish). Make sure that an exception is thrown if it is called with an unknown forage type.
• Call your implementation in Fauna::GetForageDemands::get_max_foraging().
• Update the UML diagram in HerbivoreBase.

How to add a new digestive limit

On top of foraging limitations, the daily forage uptake can be constrained by maximum digestive throughput. The implementation is almost parallel to a foraging limit.

• Add a new enum entry in Fauna::DigestiveLimit.
• Read the new value for digestion.limit from the TOML instruction file in Fauna::InsfileReader::read_hft().
• Implement your digestive limit algorithm as a free function or an object. If it is not much code, put it in foraging_limits.h, otherwise create a new file for it. Make sure that an exception is thrown if it is called with an unknown forage type.
• Call your implementation in Fauna::GetForageDemands::get_max_digestion().
• Update the UML diagram in HerbivoreBase.

How to add a new reproduction model

A reproduction model defines the offspring per female individual for each simulation day.

• Create a new enum entry in Fauna::ReproductionModel.
• Read the new value for reproduction.model from the instruction file in Fauna::InsfileReader::read_hft().
• Create your class or function in reproduction_models.h or in a separate file.
• Call your model in Fauna::HerbivoreBase::get_todays_offspring_proportion().
• Update the UML diagram in HerbivoreBase.

How to add a new diet composer

In a scenario with multiple forage types, the herbivore decides what to include in its diet. This decision is modelled by an implementation of a so called “diet composer model”: Fauna::DietComposer. You can implement your own model as a new class or a simple function; just call it in Fauna::GetForageDemands::get_diet_composition().

• Create a new enum entry in Fauna::DietComposer.
• Read the new value for foraging.diet_composer in Fauna::InsfileReader::read_hft().
• Call your model in Fauna::GetForageDemands::get_diet_composition().
• Update the UML diagram in HerbivoreBase.

How to add a new mortality factor

Any death event of an herbivore is modelled by a mortality factor. Whether you want to have herbivores die by for instance disease, drought, or predators, you should create a new mortality factor.

• Create a new enum entry in Fauna::MortalityFactor.
• Parse the new possible value for the set mortality.factors in Fauna::InsfileReader::read_hft().
• Implement your mortality model as a function or class in mortality_factors.h or in a separate file (if it’s more complex).
• Call the mortality factor in Fauna::HerbivoreBase::apply_mortality_factors_today().
• Update the UML diagram in HerbivoreBase.

Forage Tutorials

How to add a new forage type

• Create new enum entry in Fauna::ForageType and add it to Fauna::FORAGE_TYPES by expanding the initializing function get_all_forage_types(), which is declared in local namespace in forage_types.cpp.
• Add a short name without blanks in Fauna::get_forage_type_name().
• Derive new class from Fauna::ForageBase.
  • Implement a merge() method, like Fauna::GrassForage::merge().
• Add a new member variable in Fauna::HabitatForage of that class.
  • Add it in Fauna::HabitatForage::operator[]().
  • Call your merge() function in Fauna::HabitatForage::merge().
• Adjust the implementation of Fauna::Habitat::get_available_forage() and Fauna::Habitat::remove_eaten_forage() in your vegetation model.
• For Fauna::NetEnergyModel::GrossEnergyFraction you will need to define a value for the parameter forage.gross_energy.new_forage_type in the TOML file.
• Herbivores
  • Check all foraging and digestion limits (foraging_limits.h) whether they need to be expanded.
  • Probably you will need to implement a new diet composer or adjust existing ones.
• Test Simulations
  • If you want to use your forage type in the demo simulations, expand Fauna::Demo::SimpleHabitat by a new growth model (analoguous to Fauna::Demo::LogisticGrass). Also update the UML diagram in the class documentation of SimpleHabitat.

Relationships for a new forage type.

How to change forage net energy content

• Implement your model in a function or class in the file net_energy_models.h.
• Add a new enum item in Fauna::NetEnergyModel.
• Parse that value for the HFT parameter digestion.net_energy_model in Fauna::InsfileReader::read_hft().
• Execute your function or class in Fauna::HerbivoreBase::get_net_energy_content().
• Update the UML diagram in HerbivoreBase.

How to add a new forage distribution algorithm

• Derive a new class from Fauna::DistributeForage and implement your algorithm. If the algorithm is not too big, put it in forage_distribution_algorithms.h, otherwise create a new set of files.
• Return a reference to an object of your class in Fauna::WorldConstructor::create_distribute_forage() if it is selected in the parameters.
• Add a new enum entry in Fauna::ForageDistributionAlgorithm.
• Parse your new value from the parameter simulation.forage_distribution in Fauna::InsfileReader::read_hft().

Parameters Tutorials

How to add a new global parameter

• Declare your parameter as a member variable in Fauna::Parameters and initialize it with a valid default value. The enum class type for Enum parameters should be declared in parameters.h.
• Write a validity check in Fauna::Parameters::is_valid().
• Parse the parameter from the TOML instruction file in Fauna::InsfileReader. General parameters are parsed in Fauna::InsfileReader::read_table_simulation().
  • If you are creating a whole new set of parameters, it might make sense to group them in a TOML table. Existing tables are output and simulation. You should then write a new private member function similar to Fauna::InsfileReader::read_table_simulation().

How to add a new HFT parameter

• Declare a new member variable in Fauna::Hft and initialize it with a valid default value. The enum class type for Enum parameters should be declared in hft.h.
• Write a validity check in Fauna::Hft::is_valid().

See also

Parameters

Output Tutorials

How to add a new output variable

After separating the megafauna model from LPJ-GUESS into its own library only a minimal set of variables are made available for output. If your variable of interest is already present in Fauna::Output::HabitatData or Fauna::Output::HerbivoreData, then you can skip the first step in the following tutorial.

• Extend the appropriate container: Fauna::Output::HabitatData or Fauna::Output::HerbivoreData by a new member variable and initialize it with zero.
  • Add it in the reset() function.
  • Implement average building in the appropriate merge() function.
  • For herbivore data, you need to add it to Fauna::Output::HerbivoreData::create_datapoint(). If your value is per individual, you will need to weight the value by individual density; if it is per area or per habitat, you can calculate the sum.
  • Assign a value to the variable somewhere in daily simulation.
• Write the variable in Fauna::Output::TextTableWriter.
  • Add a selector for your new output file as a boolean member variable in Fauna::Output::TextTableWriterOptions. Pay attention to place it in the right Doxygen group.
  • Parse the name of the selector in Fauna::InsfileReader::read_table_output_text_tables() and add it there to the valid options in the error message.
  • Optional: Consider adding it in the example output in the file examples/megafauna.toml and plotting it in tools/demo_simulator/demo_results.Rmd. In that case the output file needs to be listed as an artifact in .gitlab-ci.yml under the job “demo_simulation”.
  • Add an output file stream (std::ofstream) for your variable as a private member variable in Fauna::Output::TextTableWriter.
  • In the constructor Fauna::Output::TextTableWriter::TextTableWriter(), add your new output file to the list of file streams if it is selected in the options.
  • Initialize the column captions of your new file in Fauna::Output::TextTableWriter::write_captions().
  • Write the data to the file in Fauna::Output::TextTableWriter::write_datapoint().

Note

If you want to add a variable that is not per herbivore mass, you would have to use mass density as weight.

How to write output to another format

The default output format are very simple tab-separated plaintext tables. The class Fauna::Output::TextTableWriter is responsible for this format. However, you can also replace that output format with another one, for instance writing to a NetCDF file or forwarding it to another program or library.

• Derive a new class from Fauna::Output::WriterInterface.
• Add a new enum entry to Fauna::OutputFormat.
• Parse the new option in Fauna::InsfileReader::read_table_output().
• Create a new instance of your writer class in the constructor Fauna::World::World() if your enum entry is selected.

See also

Output design

---

Copyright

This software documentation is licensed under a Creative Commons Attribution 4.0 International License.

Author

Wolfgang Traylor, Senckenberg BiK-F

Date

2019