RangeShifter 3.0 merge (develop into main)

.github/workflows/check.yml

@@ -27,12 +27,9 @@ jobs:
       - name: run
         run: ${{ matrix.path_to_exe }} run_on_gha/rs_test_project/
 
-#      block output checks for now
-#      - name: check_output
-#        if: ${{ matrix.os != 'macos-latest' }} # no check until I get access to a machine with Xcode 15
-#        run: |
-#         cd ./run_on_gha/rs_test_project 
-#          rm Outputs/DebugLog.txt
-#          bash check_output.bash
-        # DebugLog contains addresses, changes every run
-
+      - name: check_output
+        if: ${{ matrix.os != 'macos-latest' }} # no check until I get access to a machine with Xcode 15
+        run: |
+          cd ./run_on_gha/rs_test_project 
+        #  bash check_output.bash # disable until new genetics stable
+

.github/workflows/check_charly.yml

@@ -0,0 +1,28 @@
+name: check_charly
+on: push
+
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        include:
+          - os: windows-latest
+            path_to_exe: ./build/Debug/RangeShifter.exe
+          - os: ubuntu-latest
+            path_to_exe: ./build/RangeShifter
+          - os: macos-latest
+            path_to_exe: ./build/RangeShifter
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: build
+        run: |
+          mkdir build
+          cd build
+          cmake ../
+          cmake --build .
+
+      - name: run
+        run: ${{ matrix.path_to_exe }} run_on_gha/rs_project_charly/

.github/workflows/check_gcc.yml

@@ -0,0 +1,25 @@
+name: check_gcc
+on: push
+
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: build
+        run: |
+          shopt -s extglob
+          g++ --std=c++20 -o RangeShifter ./src/*.cpp ./src/RScore/!(Main).cpp -DLINUX_CLUSTER
+
+      - name: run
+        run: ./RangeShifter ./run_on_gha/rs_test_project/
+
+      - name: check_output
+        if: ${{ matrix.os != 'macos-latest' }}
+        run: |
+          cd ./run_on_gha/rs_test_project 
+        #  bash check_output.bash # disable until new genetics stable

.gitignore

@@ -61,8 +61,17 @@ out/
 x64/
 *.json
 
+# Eclipse
+.metadata/
+src/RScore/.cproject
+.cproject
+.settings/
+Model/
+
 # Ignore test project outputs, except anchors
 run_on_gha/rs_test_project/Outputs/*
 !run_on_gha/rs_test_project/Outputs/git_anchor.txt
 run_on_gha/rs_test_project/OutputMaps/*
 !run_on_gha/rs_test_project/OutputMaps/git_anchor.txt
+/run_on_gha/test_scenario_01/Outputs
+/Default/

CMakeLists.txt

@@ -1,30 +1,38 @@
 cmake_minimum_required(VERSION 3.10)
 
 # set the project name and version
-project(RangeShifter VERSION 2.1.0)
+project(RangeShifter VERSION 3.0.0)
 
 # specify the C++ standard
-set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # add RScore to source search path
 set(batchmode ON) # don't config RScore as standalone
+
+if(DEFINED OMP)
+	set(OMP ON)
+endif()
+
 add_subdirectory(src/RScore)
 
 # add the executable
 add_executable(RangeShifter src/Main.cpp src/BatchMode.cpp)
 
-target_compile_definitions(RangeShifter PRIVATE RSWIN64)
-
 # enable LINUX_CLUSTER macro on Linux + macOS
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux" OR CMAKE_SYSTEM_NAME STREQUAL "Darwin")
 	add_compile_definitions(LINUX_CLUSTER)
 endif()
 
-# Debug Mode by default, unless "release" is passed i.e. `cmake -Drelease=`
-if(NOT DEFINED release)
-	add_compile_definitions(RSDEBUG)
+# Enable parallelisation with OpenMP
+# define macro during config: `cmake -DOMP=`
+if(DEFINED OMP)
+	find_package(OpenMP COMPONENTS CXX)
+	if(OpenMP_CXX_FOUND)
+		target_link_libraries(RangeShifter PUBLIC OpenMP::OpenMP_CXX)
+	endif()
 endif()
+
 # link RScore to the executable as a library
 target_link_libraries(RangeShifter PUBLIC RScore)
 

README.md

@@ -1,6 +1,6 @@
-# RangeShifter Batch Mode 
+# RangeShifter Batch Mode
 
-C++ code for the RangeShifter v2 batch mode application 
+C++ code for the RangeShifter 3.0 batch mode application 
 
 <img title="" src="https://github.com/RangeShifter/RangeShifter_batch_dev/blob/main/doc/rs_batch_logo.png" alt="" align="right" height="150">
 
@@ -19,33 +19,93 @@ In Batch Mode, RangeShifter can be run from the command line (e.g., `./rangeshif
 This allows the user to run large batches of simulations with different parameters, which would need to be specified individually in the GUI version.
 The Batch Mode also enables running RangeShifter on machines with a non-interactive interface, for example a high-performance cluster.
 
-## Building RangeShifter
+## Building RangeShifter-batch
 
 The compiled software can be found in the [Software and Documentation](https://github.com/RangeShifter/RangeShifter-software-and-documentation) repo. 
 
 Building RangeShifter from the source code requires CMake. If you haven't done so yet, you will need to [download and install it](https://cmake.org/download/).
 
-RangeShifter can then be configured and built (out-of-source) from `CMakeLists.txt`, with the usual CMake commands:
+RangeShifter can then be configured and built from `CMakeLists.txt`.
+If you are not seeking to develop the code yourself, it is best (=faster) to build RangeShifter in Release mode, whihc requires slightly different command on Unix vs Windows systems:
 
 ```bash
+# Unix
 mkdir build && cd build
-cmake ..
+cmake -DCMAKE_BUILD_TYPE=Release ..
 cmake --build .
 ```
 
+```bash
+# Windows (Visual Studio)
+mkdir build && cd build
+cmake ..
+cmake --build . --config Release
+```
+
 If you use Visual Studio as your IDE, CMake should be recognised automatically when `RangeShifter_batch_dev` is opened as a new folder. 
 Visual Studio will take care of the configuration, and you only need to select target RangeShifter.exe before pressing the build button.
 
-Alternatively, RangeShifter can also be built directly with the GNU C++ compiler, in which case some #define macros must be passed to it:
+Alternatively, RangeShifter can also be built directly with the GNU C++ compiler. 
+In this case, some #define macros must be passed to it, and RScore/Main.cpp must be excluded from source files:
+
+```bash
+shopt -s extglob # enable the !(file) pattern below
+g++ --std=c++20 -o RangeShifter.exe ./src/*.cpp ./src/RScore/!(Main).cpp -DLINUX_CLUSTER -O3 -s -DNDEBUG
+```
+
+### Parallelisation
+
+As of 3.0, parallelisation (using [OpenMP](https://www.openmp.org/)) is available for the reproduction and dispersal modules. 
+This behaviour is turned off by default, and can be turned on by building RangeShifter with the `OMP` macro enabled:
 
 ```bash
-g++ -o RangeShifter.exe ./src/*.cpp ./src/RScore/*.cpp -DRSDEBUG -DRSWIN64 -DLINUX_CLUSTER
+# Unix
+mkdir build && cd build
+cmake -DOMP= -DCMAKE_BUILD_TYPE=Release ..
+cmake --build .
 ```
 
-## Running RangeShifter
+```bash
+# Windows (Visual Studio)
+mkdir build && cd build
+cmake -DOMP= ..
+cmake --build . --config Release
+```
+
+⚠️ Please note that enabling parallelisation will alter random number generation, 
+such that two identical simulations won't produce the same exact numbers, even given the same seed.
+
+### Building with Visual Studio (Windows)
+
+Building RangeShifter-batch with CMake can be done easily within Visual Studio. 
+This requires the CMake and C++ modules to be installed (please refer to the Visual Studio installer for this).
+
+Simply clone this repo, then open it in Visual Studio using the Open Folder option. 
+Visual Studio will then recognise the CMakeLists file and automatically configure the build.
+Once this is done, you should be able to select Rangeshifter.exe in the Startup Item panel ([Screenshot](https://github.com/RangeShifter/RangeShifter_batch_dev/blob/develop/doc/rs_in_vs.png)).
+Hit the button to build and run RangeShifter. The executable should be built in a folder inside `out/build/`. 
+
+## Running RangeShifter-batch
 
 For instructions on how to setup the project directory and input files, please refer to section 3.3 of the [User Manual](https://raw.githubusercontent.com/RangeShifter/RangeShifter-software-and-documentation/master/RangeShifter_v2.0_UserManual.pdf), and to the [documentation repository](https://github.com/RangeShifter/RangeShifter-software-and-documentation) for examples.
 
+## Parallelisation
+
+RangeShifter supports partial parallelisation with OpenMP (thanks @nboullis!).
+
+Parallelisation is turned off by default, but can be enabled by passing macro `OMP` to CMake:
+
+```bash
+cmake -DOMP= ..
+cmake --build .
+```
+
+The number of threads can be controlled with the `OMP_NUM_THREADS` variable:
+
+```bash
+OMP_NUM_THREADS=10 ./RangeShifter.exe ./
+```
+
 ## Contributing
 
 See [CONTRIBUTING](https://github.com/RangeShifter/RangeShifter_batch_dev/blob/main/CONTRIBUTING.md)
@@ -56,9 +116,22 @@ See [CONTRIBUTING](https://github.com/RangeShifter/RangeShifter_batch_dev/blob/m
 - [RScore](https://github.com/RangeShifter/RScore), source for RangeShifter's core code
 - [RangeShiftR-pkg](https://github.com/RangeShifter/RangeShiftR-pkg), source for the R interface
 
-## Maintainer
+## Authors
+
+**Developers:**
+
+- Theo Pannetier ([@TheoPannetier](https://github.com/TheoPannetier))
+- Jette Wolff ([@JetteReeg](https://github.com/JetteReeg))
+- Steve Palmer
+- Roslyn Henry ([@RoslynHenry](https://github.com/RoslynHenry))
+
+Concepts:
 
-- [@TheoPannetier](https://github.com/TheoPannetier)
+- Damaris Zurell ([@damariszurell](https://github.com/damariszurell))
+- Greta Bocedi ([@GretaBocedi](https://github.com/GretaBocedi))
+- Justin Travis
+- Steve Palmer
+- Roslyn Henry ([@RoslynHenry](https://github.com/RoslynHenry))
 
 ## References
 

doc/Manual/Batchmode/CONTROL.txt

@@ -17,14 +17,80 @@ EmigrationFile	EmigrationFile_name.txt
 TransferFile	TransferFile_name.txt
 SettlementFile	SettlementFile_name.txt
 GeneticsFile	GeneticsFile_name.txt
+TraitsFile	TraitsFile_name.txt
+ManagementFile ManagementFile_name.txt
 InitialisationFile	InitialisationFile_name.txt
 
 ANY ADDITIONAL LINES ARE NOT READ, AND CAN THEREFORE BE USED FOR COMMENTS
 
-Example RangeShifter v2.0 Control File for a patch-based model of a stage-structured population dispersing by the kernel transfer option
+Example RangeShifter v3.0 Control File for a patch-based model 
+of a stage-structured population dispersing by the kernel transfer option
 
-Alternatives for non-structutred population / no variable traits:
+DOCUMENTATION
 
-StageStructFile	NULL
-GeneticsFile	NULL
+More detail can be found in Section 3.3 (Batch Mode) of the user manual
+
+Parameter		Values		Description
+
+BatchNum		≥ 0			Batch number, appears in all output file names
+
+PatchModel		0 / 1		0 = cell-based model, 1 = patch-based model
+
+Resolution		> 0			Landscape resolution, i.e. cell size (in m)
+
+LandType		0 / 2 / 9	0 = imported raster map with unique habitat codes
+							2 = imported raster map with habitat quality
+							9 = create an artificial landscape for each replicate
+
+MaxHabitats		> 0			Maximum number of habitats in the landscapes to be used;
+							must be >1 for LandType = 0
+							must be 1 for LandType = 2 or 9
+
+SpeciesDist		0 / 1		Load initial species distribution? 0 = no, 1 = yes
+
+DistResolution	> 0			Resolution of the species distribution map (m)
+							must not be less than the Resolution parameter
+
+Reproduction	0 / 1 / 2	0 = asexual / only female model, 1 = sexual model (simple);
+							2 = sexual model (explicit mating system)
+
+RepSeasons		≥ 1			No. of reproductive seasons per year
+
+StageStruct		0 / 1		0 = no stage structure, 1 = stage-structured model
+
+Stages			> 1			No. of stages (incl. juveniles) if stage-structured
+
+Transfer		0 / 1 / 2	Transfer method: 0 = dispersal kernels,
+							1 = SMS (stochastic movement simulator),
+							2 = CRW (correlated random walk)
+
+ParameterFile		filename			Principal file for model parameters,
+										1 line per simulation, simulations must be numbered sequentially
+										includes habitat-dependent values for K (or 1/b)
+
+LandFile			filename			Identifies the landscape(s) to be used for each simulation in the ParametersFile; format depends on LandType setting
+
+StageStructFile		filename/NULL		NULL if not stage-structured model (StageStruct= 0),
+										must have matching simulation nos. to those in ParametersFile 
+										1 line per simulation
+
+EmigrationFile		filename			Must have matching simulation nos. to those in ParametersFile
+										no. lines per simulation depends on model stage and sex structure
+
+TransferFile		filename			Must have matching simulation nos. to those in ParametersFile
+										no. lines per simulation depends on model stage and sex structure
+
+SettlementFile		filename			Must have matching simulation nos. to those in ParametersFile
+										no. lines per simulation depends on model stage and sex structure
+
+GeneticsFile 		filename/NULL		Required if any dispersal trait is made evolvable (IndVar fields in Emigration/Transfer/Settlement files).
+
+(v3.0) TraitsFile	filename/NULL		Required if any dispersal trait is made evolvable. 1 line per simulation; 
+										1 line per trait type per simulation.
+
+ManagementFile		filename/NULL		NULL if no management options are selected. Otherwise must habe matching simulation nos.
+										to those in ParametersFile;
+
+InitialisationFile	filename			Must have matching simulation nos. to those in ParametersFile.
+										1 line per simulation
 

run_on_gha/expected_output/windows_ubuntu/Batch1_RS_log.csv

@@ -1,7 +1,7 @@
 Event,Number,Reps,Years,Time
 WARNING,***** RSDEBUG mode is active *****,,,
 RANDOM SEED,666,,,
-Landscape,37,,,3
-Simulation,1,1,10,0
+Landscape,37,,,2
+Simulation,1,1,10,1
 
 Batch,,,,3