The UFZ services GitLab and Mattermost will be unavailable on Monday, October 25 from 06:00 AM to 08:00 AM due to maintenance work.

Commit c37f8654 authored by Johannes Leins's avatar Johannes Leins
Browse files

Merge branch 'no_singleton' into 'develop'

Merging features since last model version into develop branch

See merge request !9
parents 068452ea d13ef071
Pipeline #28882 passed with stage
in 26 seconds
......@@ -11,9 +11,11 @@ build_linux:
- cd build
- cmake -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo ../
- ninja
- cp "../stages.csv" "../grasslandCells.csv" "../initialDens.csv" "../influences.csv" "../disturbances.csv" "../distScheme.csv" .
artifacts:
paths:
- build/hileg
- build/*.csv
build_windows:
script:
......@@ -21,11 +23,12 @@ build_windows:
- cd build
- CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ cmake -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DNETCDF_PREFIX=$NETCDF_PREFIX ../
- ninja
- cp "$NETCDF_PREFIX/bin/netcdf.dll" "$NETCDF_PREFIX/bin/hdf5.dll" "$NETCDF_PREFIX/bin/hdf5_hl.dll" "$NETCDF_PREFIX/bin/zlib1.dll" "/usr/lib/gcc/x86_64-w64-mingw32/8.3-win32/libstdc++-6.dll" "/usr/lib/gcc/x86_64-w64-mingw32/8.3-win32/libgcc_s_seh-1.dll" .
- cp "../stages.csv" "../grasslandCells.csv" "../initialDens.csv" "../influences.csv" "../disturbances.csv" "../distScheme.csv" "$NETCDF_PREFIX/bin/netcdf.dll" "$NETCDF_PREFIX/bin/hdf5.dll" "$NETCDF_PREFIX/bin/hdf5_hl.dll" "$NETCDF_PREFIX/bin/zlib1.dll" "/usr/lib/gcc/x86_64-w64-mingw32/8.3-win32/libstdc++-6.dll" "/usr/lib/gcc/x86_64-w64-mingw32/8.3-win32/libgcc_s_seh-1.dll" .
artifacts:
paths:
- build/hileg.exe
- build/*.dll
- build/*.csv
builder:
when: manual
......
......@@ -8,6 +8,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED True)
add_executable(
hileg
src/main.cpp
src/Cell.cpp
src/Climate.cpp
src/ClimateScenario.cpp
src/Cohort.cpp
......@@ -26,7 +27,7 @@ add_executable(
src/MowingPattern.cpp
src/Point.cpp
src/Population.cpp
src/PopulationStats.cpp
src/PopulationAtts.cpp
src/StrategyClimate.cpp
)
......
......@@ -17,46 +17,88 @@ The most recent binaries pre-built by GitLab's CI/CD processor are located here:
## Run
To run HiLEG using external climate conditions (input file [influences.csv](influences.csv)), it requires specific NetCDF input files located in subfolder ./climate.
Request the climate data for download at the UFZ data investigation portal: [Full data][CLIMATE_FULL] (~28 GB) or the [data subset][CLIMATE_PART] (~1.5 GB) as used for publication [Leins et al. 2020][LEINSETAL2020].
Request the climate data for download at the UFZ data investigation portal: [Full data][CLIMATE_FULL] (~28 GB) or the [data subset][CLIMATE_PART] (~1.5 GB) as used for publication [Leins et al. 2021][LEINSETAL2021].
### Parameterization
One mandatory and three optional CSV input files must/can be supplied in the root folder to set up the simulation run.
Two mandatory and four optional CSV input files must/can be supplied in the root folder to set up the simulation run.
Refer to the header of these files in the repository for usage instructions.
| file | mandatory | description |
|---------------------------------------|-----------|------------------------------------------------------------------------------------|
| [stages.csv](stages.csv) | YES | defines the life cycle of the target species using the definition of life stages |
| [influences.csv](influences.csv) | NO | influence of external drivers (climate/disturbance) on life cycle processes |
| [disturbances.csv](disturbances.csv) | NO | timing and location of disturbances |
| [climateCells.csv](climateCells.csv) | NO | locations (climate grid cells) used for simulating populations |
| file | mandatory | description |
|-------------------------------------------|-----------|-----------------------------------------------------------------------------------------|
| [stages.csv](stages.csv) | YES | defines the life cycle of the target species using the definition of life stages |
| [grasslandCells.csv](grasslandCells.csv) | YES | locations (grassland cells) of simulated populations and their associated climate cells |
| [initialDens.csv](initialDens.csv ) | NO | initial density per stage and location used instead of value defined in stages.csv |
| [influences.csv](influences.csv) | NO | influence of external drivers (climate/disturbance) on life cycle processes |
| [disturbances.csv](disturbances.csv) | NO | potential timing and location of disturbances |
| [distScheme.csv](distScheme.csv) | NO | applied timing and location of disturbances |
Additionally, the following command line arguments can be used to parameterize the simulation run.
Without command line arguments the simulation runs from 1/Jan/1970 to 30/Dec/2080 using the full grid and creating 10 replicates.
| parameter | default | description |
|--------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| -cCap | 25 | carrying capacity per square meter. Floating point values > 0 are valid |
| -iClim | 0 | index of initial climate change scenario to use. Values between 0 and 11 are valid |
| -nClim | 12 | number of consecutive climate change scenario to use. Valid if > 0 AND (iClim + nClim - 1) < 12 |
| -iTime | 0 | initial time step (day) of simulation run. Values between 0 (1/Jan/1970) and 40404 (31/Dec/2080) are valid |
| -nTime | 40404 | duration of a simulation run in time steps (days). NOTE: by definition, a year has 364 days |
| -dTime | 0 | delta time steps (days) to additional simulation runs. Repeated n times as long as (iTime + n * dTime + nTime) < 40404 (30/Dec/2080) |
| -nSeeds | 10 | number of replicates (random seeds) to create per climate change scenario and (timely) additional simulation runs |
| -limShfl | 10 | number of years before (iTime) and after (iTime + nTime) simulation period to include in reshuffling the order of years |
| -fnameCoords | climateCells.csv | filename of specific file containing applied climate cells coordinates |
| -fnameDist | disturbances.csv | filename of specific file containing applied disturbance schedule |
| --climOnly | | execute simulation runs with climate coditions as only external driver |
| --distOnly | | only execute simulation runs including disturbance scenarios (defined in disturbances.csv) |
| --noDens | | do not create output file of daily density values (has large file size) |
| --listClim | | list available climate change scenarios and their index |
| --help | | prints help page |
| parameter | default | description |
|--------------|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| -cCap | 25 | carrying capacity per square meter. Floating point values > 0 are valid |
| -iClim | 0 | index of initial climate change scenario to use. Values between 0 and 11 are valid |
| -nClim | 1 | number of consecutive climate change scenario to use. Valid if > 0 AND (iClim + nClim - 1) < 12 |
| -iYear | 1970 | initial year of simulation run. Values from 1970 to 2080 are valid |
| -nYear | 111 | duration of a simulation run in years. |
| -dYear | 0 | delta years to additional simulation runs. Repeated n times as long as (iYear + n * dYear + nYear) <= 2081 |
| -iFrame | iYear | initial year of first time frame used to randomly draw years from. Defaults to initial year of simulation run |
| -nFrame | nYear | length in years of first time frame used to randomly draw years from. Defaults to duration of of simulation run |
| -nSeeds | 10 | number of replicates (random seeds) to create per climate change scenario and (timely) additional simulation runs |
| -seed | | run simulation without replicates using the given explicit integer number for the random seed |
| -limShfl | 0 | number of years before (iTime) and after (iTime + nTime) simulation period to include in reshuffling the order of years |
| -runID | timestamp | use the given (unique) integer number to name output files associated with this simulation run. Uses current timestamp as default |
| -dispersal | 2 | applied dispersal type: 0 = none, 1 = base immigration, 2 = migration between neighboring cells, 3 = both (1 and 2) |
| -fnameCells | grasslandCells.csv | filename of specific file containing locations (grassland cells) of simulated populations and their associated climate cells |
| -fnameDens | initialDens.csv | filename of specific file containing initial density per stage and location |
| -fnameDist | disturbances.csv | filename of specific file containing the potential timing and location of disturbances |
| -fnameScheme | distScheme.csv | filename of specific file containing the applied timing and location of disturbances |
| --climOnly | | execute simulation runs with climate conditions as only external driver |
| --distOnly | | only apply additional disturbance schemes using potential disturbances defined in disturbances.csv |
| --dens | | create output file of daily density values (has large file size) |
| --uniformDist| | apply disturbances uniformly in all grassland cells and create a scheme for each defined disturbance. Ignore file distScheme.csv |
| --prognosis | | create one disturbance scheme for each unique disturbance in disturbances.csv and each grassland cell flagged fixed=0 in distScheme.csv |
| --memSave | | save memory by preloading climate data for the current simulation year only (instead of whole time frame) |
| --listClim | | list available climate change scenarios and their index |
| --help | | prints help page |
### Output
A simulation run creates three types of output files in subfolder _./output/run_<runID>/_ depending command line arguments **--prognosis**:
| filename | creation | description |
|-------------------------------------------------------------------------------------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| finalDens/<runID>_finalDens_seed<#seed>_<distSchemeName>_<climateModel>_<RCPscenario>_<finalYear>.csv | without --prognosis | final density per grassland cell and life stage at the end of a simulation time slice (one file per seed, time slice, disturbance scheme, climate model and RCP scenario) |
| <runID>_stats_<climateModel>_<RCPscenario>_<iYear>_<iYear+nYear>.csv | always | population statistics per grassland cell and replicate at the end of a single simulation time slice (one file per time slice, disturbance scheme, climate model and RCP scenario) |
| <runID>_stats_mean_<distSchemeName>_<climateModel>_<RCPscenario>_<iYear>_<iYear+nYear>.csv | with --prognosis | mean population statistics per grassland cell of all replicates at the end of a single simulation time slice (one file per time slice, disturbance scheme, climate model and RCP scenario) |
The files containing the _final density_ are of the same format as the file **initialDens.csv** and thus can be used as simulation input for _initial density_
Both file types for _(mean) population statistics_ contain the same columns except that the mean statistics do not have the column _seed_:
| column name | description |
|-------------------------|-----------------------------------------------------------------------------------------------------------|
| xCoord | X Coordinate of grassland cell / population |
| yCoord | Y Coordinate of grassland cell / population |
| seed | Number of the seed used in the random generator for this replicate (misses in stats_mean) |
| disturbance | Name of the disturbance scenario applied at the coordinate |
| lifetime | Number of the days the population's density was >= minimum density |
| finalDensity | Population density at the end of the current simulation run time slice |
| nExtinction | Number of times the population density dropped below the minimum density |
| nQuasiExtinction | Number of times the population density dropped below the threshold defining quasi extinction (stages.csv) |
| meanDensity | Daily mean population density with respect to the full runtime |
| lifetime_<stageName> | Number of the days a life stage's density was >= minimum density (active) |
| meanDensity_<stageName> | Daily mean life stage density with respect to its lifetime |
| lastPeak_<stageName> | maximum life stage density during the whole last period it was active |
| meanPeak_<stageName> | mean maximum life stage density with respect to the number of periods it was active |
## Publication
With the CSV files supplied in the repository, HiLEG is parameterized for the large marsh grasshopper (LMG) as used for publication [Leins et al. 2020][LEINSETAL2020].
With the CSV files supplied in the repository, HiLEG is parameterized for the large marsh grasshopper (LMG) as used for publication [Leins et al. 2021][LEINSETAL2021].
The output for this publication was generated using [HiLEG version v1.0][HILEGV10] with the following command line arguments.
......@@ -70,15 +112,6 @@ hileg[.exe] -c0 4 -cn 1 -t0 10920 -td 7280 -tn 7280 -nseeds 50 -nodens -luonly -
hileg[.exe] -c0 5 -cn 1 -t0 10920 -td 7280 -tn 7280 -nseeds 50 -nodens -luonly -limS 5
```
To generate similar output with the present [HiLEG version v1.1.1][HiLEGV111], use the following command line arguments together with the provided CSV files.
```sh
hileg[.exe] -cCap 25 -iClim 3 -nClim 3 -iTime 10920 -nTime 7280 -dTime 7280 -nSeeds 50 -limShfl 5 --noDens --climOnly
hileg[.exe] -cCap 25 -iClim 3 -nClim 3 -iTime 10920 -nTime 7280 -dTime 7280 -nSeeds 50 -limShfl 5 --noDens --distOnly
hileg[.exe] -cCap 25 -iClim 5 -nClim 1 -iTime 32760 -nTime 7280 -nSeeds 50 -limShfl 5
```
## Documents and folders
| file / folder | description |
......@@ -86,7 +119,7 @@ hileg[.exe] -cCap 25 -iClim 5 -nClim 1 -iTime 32760 -nTime 7280 -nSeeds 50 -limS
| [ODD.pdf](documents/ODD.pdf) | Overview, design concepts and details (model description) |
| [HiLEG_er.pdf](documents/HiLEG_er.pdf) | Visualization of HiLEG model entities, relations and processes |
| [HiLEG_er_caption.txt](documents/HiLEG_er_caption.txt) | Explanatory caption for file [HiLEG_er.pdf](documents/HiLEG_er.pdf) |
| `climate` | Not in repository. Required for simulation runs with external climate conditions. Request the data for download at the UFZ data investigation portal: [Full data][CLIMATE_FULL] (~28 GB) or the [data subset][CLIMATE_PART] (~1.5 GB) as used for publication [Leins et al. 2020][LEINSETAL2020]. |
| `climate` | Not in repository. Required for simulation runs with external climate conditions. Request the data for download at the UFZ data investigation portal: [Full data][CLIMATE_FULL] (~28 GB) or the [data subset][CLIMATE_PART] (~1.5 GB) as used for publication [Leins et al. 2020][LEINSETAL2021]. |
| `documents` | Model documentation files |
| `lib` | Additional libraries required to build model |
| `output` | Not in repository. Will be created during simulation run as location for output files |
......@@ -94,10 +127,9 @@ hileg[.exe] -cCap 25 -iClim 5 -nClim 1 -iTime 32760 -nTime 7280 -nSeeds 50 -limS
[ECOCLIMB]: https://www.b-tu.de/en/ecoclimb
[LEINSETAL2020]: https://
[LEINSETAL2021]: https://doi.org/10.1016/j.ecolmodel.2020.109355
[BUILD_LINUX]: https://git.ufz.de/leins/hileg/-/jobs/artifacts/master/download?job=build_linux
[BUILD_WIN]: https://git.ufz.de/leins/hileg/-/jobs/artifacts/master/download?job=build_windows
[CLIMATE_FULL]: https://www.ufz.de/record/dmp/archive/8665/en/
[CLIMATE_PART]: https://www.ufz.de/record/dmp/archive/8852/en/
[HILEGV10]: https://git.ufz.de/leins/hileg/-/tree/v1.0
[HILEGV111]: https://git.ufz.de/leins/hileg/-/tree/v1.1.1
# Coordinates of all terrestrial climate cells included in
# the climate data used for publication Leins et al. 2020.
#
# Column climCellID has informative character only and
# is not needed during simulation runs.
#
# Coordinates used for characteristically different climate categories:
# dry: iLon=10, iLat=8
# wet & warm: iLon=11, iLat=7
# cold: iLon=14, iLat=4
#
climCellID,iLon,iLat
1,1,1
2,2,1
3,3,1
4,4,1
5,5,1
6,6,1
7,7,1
8,8,1
9,9,1
10,10,1
11,11,1
12,12,1
13,13,1
14,14,1
15,15,1
16,16,1
17,17,1
18,18,1
19,19,1
20,20,1
21,21,1
22,22,1
23,23,1
24,24,1
25,25,1
26,26,1
27,27,1
28,28,1
29,29,1
30,30,1
31,31,1
32,32,1
33,33,1
34,34,1
35,35,1
36,36,1
37,1,2
38,2,2
39,3,2
40,4,2
41,5,2
42,6,2
43,7,2
44,8,2
45,9,2
46,10,2
47,11,2
48,12,2
49,13,2
50,14,2
51,15,2
52,16,2
53,17,2
54,18,2
55,19,2
56,20,2
57,21,2
58,22,2
59,23,2
60,24,2
61,25,2
62,26,2
63,27,2
64,28,2
65,29,2
66,30,2
67,31,2
68,32,2
69,33,2
70,34,2
71,35,2
72,36,2
73,1,3
74,2,3
75,3,3
76,4,3
77,5,3
78,6,3
79,7,3
80,8,3
81,9,3
82,10,3
83,11,3
84,12,3
85,13,3
86,14,3
87,15,3
88,16,3
89,17,3
90,18,3
91,19,3
92,20,3
93,21,3
94,22,3
95,23,3
96,24,3
97,25,3
98,26,3
99,27,3
100,28,3
101,29,3
102,30,3
103,31,3
104,32,3
105,33,3
106,34,3
107,35,3
108,36,3
109,1,4
110,2,4
111,3,4
112,4,4
113,5,4
114,6,4
115,7,4
116,8,4
117,9,4
118,10,4
119,11,4
120,12,4
121,13,4
122,14,4
123,15,4
124,16,4
125,17,4
126,18,4
127,19,4
128,20,4
129,21,4
130,22,4
131,23,4
132,24,4
133,25,4
134,26,4
135,27,4
136,28,4
137,29,4
138,30,4
139,31,4
140,32,4
141,33,4
142,34,4
143,35,4
144,36,4
145,1,5
146,2,5
147,3,5
148,4,5
149,5,5
150,6,5
151,7,5
152,8,5
153,9,5
154,10,5
155,11,5
156,12,5
157,13,5
158,14,5
159,15,5
160,16,5
161,17,5
162,18,5
163,19,5
164,20,5
165,21,5
166,22,5
167,23,5
168,24,5
169,25,5
170,26,5
171,27,5
172,28,5
173,29,5
174,30,5
175,31,5
176,32,5
177,33,5
178,34,5
179,35,5
180,36,5
181,1,6
182,2,6
183,3,6
184,4,6
185,5,6
186,6,6
187,7,6
188,8,6
189,9,6
190,10,6
191,11,6
192,12,6
193,13,6
194,14,6
195,15,6
196,16,6
197,17,6
198,18,6
199,19,6
200,20,6
201,21,6
202,22,6
203,23,6
204,24,6
205,25,6
206,26,6
207,27,6
208,28,6
209,29,6
210,30,6
211,31,6
212,32,6
213,33,6
214,34,6
215,35,6
216,36,6
217,1,7
218,2,7
219,3,7
220,4,7
221,5,7
222,6,7
223,7,7
224,8,7
225,9,7
226,10,7
227,11,7
228,12,7
229,13,7
230,14,7
231,15,7
232,16,7
233,17,7
234,18,7
235,19,7
236,20,7
237,21,7
238,22,7
239,23,7
240,24,7
241,25,7
242,26,7
243,27,7
244,28,7
245,29,7
246,30,7
247,31,7
248,32,7
249,33,7
250,34,7
251,35,7
252,36,7
253,1,8
254,2,8
255,3,8
256,4,8
257,5,8
258,6,8
259,7,8
260,8,8
261,9,8
262,10,8
263,11,8
264,12,8
265,13,8
266,14,8
267,15,8
268,16,8
269,17,8
270,18,8
271,19,8
272,20,8
273,21,8
274,22,8
275,23,8
276,24,8
277,25,8
278,26,8
279,27,8
280,28,8
281,29,8
282,30,8
283,31,8
284,32,8
285,33,8
286,34,8
287,35,8
288,36,8
289,1,9
290,2,9
291,3,9
292,4,9
293,5,9
294,6,9
295,7,9
296,8,9
297,9,9
298,10,9
299,11,9
300,12,9
301,13,9
302,14,9
303,15,9
304,16,9
305,17,9
306,18,9
307,19,9
308,20,9
309,21,9
310,22,9
311,23,9
312,24,9
313,25,9
314,26,9
315,27,9
316,28,9
317,29,9
318,30,9
319,31,9
320,32,9
321,33,9
322,34,9
323,35,9
324,36,9
325,1,10
326,2,10
327,3,10
328,4,10
329,5,10
330,6,10
331,7,10
332,8,10
333,9,10
334,10,10
335,11,10
336,12,10
337,13,10
338,14,10
339,15,10
340,16,10
341,17,10
342,18,10
343,19,10
344,20,10
345,21,10
346,22,10
347,23,10
348,24,10
349,25,10
350,26,10
351,27,10
352,28,10
353,29,10
354,30,10
355,31,10
356,32,10
357,33,10
358,34,10
359,35,10
360,36,10
361,1,11
362,2,11
363,3,11
364,4,11
365,5,11
366,6,11
367,7,11
368,8,11
369,9,11
370,10,11
371,11,11
372,12,11
373,13,11
374,14,11
375,15,11
376,16,11
377,17,11
378,18,11
379,19,11
380,20,11
381,21,11
382,22,11
383,23,11
384,24,11
385,25,11
386,26,11
387,27,11
388,28,11
389,29,11
390,30,11
391,31,11
392,32,11
393,33,11
394,34,11
395,35,11
396,36,11
397,1,12
398,2,12
399,3,12
400,4,12
401,5,12
402,6,12
403,7,12
404,8,12
405,9,12
406,10,12
407,11,12
408,12,12
409,13,12
410,14,12
411,15,12
412,16,12
413,17,12
414,18,12
415,19,12
416,20,12
417,21,12
418,22,12
419,23,12
420,24,12
421,25,12
422,26,12
423,27,12
424,28,12
425,29,12
426,30,12
427,31,12
428,32,12
429,33,12
430,34,12
431,35,12
432,36,12
433,1,13
434,2,13
435,3,13
436,4,13
437,5,13
438,6,13
439,7,13
440,8,13
441,9,13
442,10,13
443,11,13