|
pops-core
0.9
PoPS (Pest or Pathogen Spread) Model Core C++ library
|
PoPS Core is the core C++ library for the PoPS Model.
PoPS (Pest or Pathogen Spread) is a stochastic spread model of pests and pathogens in forest and agricultural landscapes. It is used for various pest, pathogens, and hosts. It was originally developed for Phytophthora ramorum and the original version of the model was written in R, later with Rcpp, and was based on Meentemeyer (2011) paper.
PoPS Core is a header-only C++ library. It is using templates for the main spatial data structures, i.e., rasters, to be universal and it makes use of C++11 features, so C++11 is the minimal required version.
If you use this software or code, please cite the following papers:
In case you are using the automatic management feature in rpops or the steering version of r.pops.spread (from the branch steering), please cite also:
In addition to citing the above paper, we also encourage you to reference, link, and/or acknowledge specific version of the software you are using for example:
This section is designed to clarify the branch structure and versioning of this repository (and interface repositories) and general naming of new features and bug fix branches, especially those that are take longer to develop.
Most bugs/issues will be found in the master branch as it is the branch being used in the R package and Grass module. Thus bug fixes should be merged into master once tested on both R and Grass. Bug fixes should be released as minor versions (e.g. if major release is 1.0 then the first bug fix would be released as version 1.1 and both R and Grass would be updated to 1.1.0). If a bug is found in one of the interfaces (R package or Grass module) that doesn't require a change to PoPS Core then these repositories should be updated indepentantly and maintain a patch release 1.0.x. For example, if the current version of the R package is 1.1.0 and Grass module is 1.1.0 and a bug is found in the R package then the R package version becomes 1.1.1 while the Grass version is 1.1.0. However, the version number is still shared for all the projects, so when a new version of the GRASS module is needed, it will be 1.1.2.
When creating new features create a branch from master using the following syntax new_feature. For example, we want to add a transportation network model for human assisted dispersal, the branch created would be named transportation_network_model (or similar). New features will be merged into master once tested based on the priorities of our stakeholders first. Once new features are tested in R and Grass with the latest bug fixes and any other new features being included in the next major release we will merge them into master and create an official major release version (e.g. update from version 1.1 to version 2.0 and the R package and Grass module are updated to 2.0.0). When you are creating branches in your fork, we still recommend choosing informative names such as the one suggested above.
If you are interested in contributing to PoPS and are not a core developer on the model, please take a look at following documents to make the process as seamless as possible.
The stable API to be used in other projects includes the pops::Model and pops::Config classes and classes used in their API (for example, pops::SpreadRate). This API is changed only beween major versions or, if really needed, to fix serious issues in the released major version.
Other classes and functions are part of the internal API and although you can use them in your project, you will need to follow the changes in the library more closely and update your code more often.
If you are using the C++ API, we invite you to open an issue in this repository to tell us about it and we can both acknowledge you in this repo or elsewhere and discuss planned changes with you.
If you are interested in reviewing the code, you may want to focus at the following core functions rather than the API.
simulation.remove : removes the pest or pathogen from the infested hosts based on some environmental threshold (currently only temperature is accounted for).
simulation.generate : generates dispersing indivduls from all infested cells based as a function of local infected hosts and weather.
simulation.disperse : creates dispersal locations for the dispersing individuals from the generate function.
simulation.mortality : causes mortality in infested/infected hosts based on mortality rate
The custom date class is used to easily manage different time steps within the model and account for differences in the way frequently used weather data sets treat leap years (DAYMET drops December 31st from leap years, PRISM keeps all days even for leap years)
The PoPS Core library can be used directly in a C++ program or through other programs. It is used in R package called rpops and a GRASS GIS module called r.pops.spread.
This is a convenient way, if you are using Git and you can use the C++ header files directly.
Git supports inclusion of other repositories into your own code using a mechanism called submodules. In your repository, run:
If you want a specific branch of PoPS Core, after adding the PoPS submodule, run the following commands (with branch-name being the branch of the PoPS library you want to use):
The will create a directory called pops-core in your repository which will now contain all the files from this repository. You can use the two following commands to see the changes to your repository:
Git added a file called .gitmodules with the link to this repository and linked a specific commit in this repository. The commit linked is the currently latest commit to PoPS library.
You can now commit and push changes to your repository.
When someone else clones our project, they need to run the two following commands to get the content of the pops-core directory:
Alternatively, the pops-core directory can be populated during cloning when git clone is used with the --recurse-submodules parameter.
If you want to update the specific PoPS commit your repository is using to the latest one, you the following command:
Here we are assuming that you use Linux command line or equivalent and you have CMake and C++ compiler installed. We are testing with GNU GCC with (g++) and GNU make (make), but many of other tools supported by CMake should work too. See CMake documentation for different ways of compiling.
First download the source code (as a ZIP file and unpack it or use Git to get it from the Git repository).
Configure the project and use directory called build for configure and build outputs:
Build the project:
The library itself does not need compilation since it is header only (it is compiled later with your project), but this compiled several test programs.
To run these tests:
If something is wrong, this will generate error messages. Note that not all tests are not fully automatic, so in couple cases this only testing if the code is running and not crashing (you will need to examine the source code to see the details).
Additionally, create documentation using the following (Doxygen required):
The HTML documentation will appear in the html subdirectory of build directory. Open the file called index.html to access it in a web browser.
Optionally, to remove the build directory when you are done, use:
Note that if you are not using CMake, you can just add the headers to your project since this a header-only library. However, if you are using CMake, you probably want to use the following approach.
Assuming you added the directory as a submodule or a plain subdirectory called pops-core add these two following lines to your CMakeLists.txt file (assuming you already have target called your_target):
_(alphabetical order)_
_(alphabetical order)_
See Git commit history, GitHub insights, or CHANGELOG.md file (if present) for details about contributions.
Permission to use, copy, modify, and distribute this software and its documentation under the terms of the GNU General Public License is hereby granted. No representations are made about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. See the GNU General Public License for more details.
1.8.17