# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).


## [1.0.0] - in planning

*Aim: 4 species, 2 crop growth models, farm model, GAEC scenarios, experimental analysis*

*Plan: decouple CairoMakie (#81), fix & test ALMaSS, set up first experiments*

*Plan: add more regions*


## [0.7.0] - 14-03-2025

### Added

- Add AquaCrop crop model

- Allow multiple crop models to be used in one simulation.  The
  settings "crop.cropmodel" and "crop.cropdirectory" are now
  comma-separated lists of crop models and their data directories.

- Simple linear crop height estimation for AquaCrop plants from
  biomass (AquaCrop does not model plant height)

- Read soil type map, controlled with the setting "world.soiltypesmap"

- Landscape `Pixel`s store their soil type (`enum SoilType`)

- `FarmPlot`s store the most common soil type of their landscape
  `Pixel`s (AquaCrop needs the soil type as an input parameter).

### Changed

### Deprecated

### Removed

### Fixed


## [0.6.1] - 14-03-2025

### Added

- user manual: documentation is now compiled to PDF (#91)

- added soil maps to region data, but not used yet

- added `mean_cloud_cover` and `potential_evapotranspiration` fields
  to weather data csv files

### Changed

- added soil map section to GIS docs

- Changed weather internal representation to struct-of-arrays
  (previously a dict-of-struct representation).  The `Weather` type
  now stores all weather information for the whole simulation, with a
  function interface, e.g. `sunshine(weather, date)`.

- When reading weather data, we now throw an error when there are
  missing days or any missing values for the fields `min_temperature`,
  `max_temperature`, `mean_temperature`, `precipitation`, and
  `potential_evapotranspiration`.  In the future missing values could
  also be imputed.

- The script for weather data extraction at
  `data/regions/auxiliary/extract_weather_data.R` has been reworked to
  always return an output row for each day in the date range, even if
  the day is missing in the original data source.  It now also accepts
  the stations to download as command-line arguments.  The `renv`
  lockfile for the R environment used to run the script can be found
  at `data/regions/auxiliary/renv.lock`.

### Deprecated

### Removed

### Fixed


## [0.6.0] - 13-01-2025

**This point release re-implements the ALMaSS crop model**


### Added

- `crop.cropdirectory` parameter specifies folder in which all crop data files for the
  selected crop model can be found.

### Changed

- `preprocessparameters()` checks whether the map and crop directories are reachable from the 
  current working directory. If not, it checks whether it can be reached from the package directory. 
  This makes running simulations easier when Persefone has been installed as a package.

- `simulate()` and `initialise()` now take a `params` keyword argument that can be used to
  override parameters from other input sources

- The ALMaSS crop data config file
  `data/crops/almass/crop_data_general.csv` now has extra columns for
  `is_c4_plant`, `sowingdensity`, and `phase_before_harvest`

### Deprecated

### Removed

- `crop.cropfile` and `crop.growthfile` parameters -> user configuration is now done via
  `crop.cropdirectory`, names of ALMaSS input files are specified as constants in `almass.jl`

### Fixed

- The implementation of the ALMaSS vegetation model in Persefone has
  been completely rewritten, hopefully more faithfully reproducing the
  logic in ALMaSS.  The resulting plant heights are now more realistic
  and do not produce the extreme plant heights seen previously (which
  was due to an erroneous interpretation of the ALMaSS growth curves).


---

## [0.5.5] - 09-08-2024

**This point release implements the first basic farm model**

### Added

- basic farm model that assigns a crop rotation to each field, sowing and harvesting when appropriate

- new parameters: `farm.farmmodel`, `farm.setaside`, `farm.fieldoutfreq`

- visualisation of cropped area and crop growth over time

- `farm.setaside` setting to configure what proportion of land farmers let lie fallow

- `isharvestable()` function for `FarmPlot`s

- `@areaof` macro to calculate the area of a given number of landscape pixels

- `data/farm/standard_gross_margins.csv` from KTBL data

### Changed

- expanded & adapted general crop data and crop growth curve tables

### Fixed

- bug fixes in the ALMaSS crop model


## [0.5.4] - 08-08-2024

**Skylark data analysis and new internal utility functions**

### Added

- `AnnualDate` type and associated functions for working with recurring dates (#101)
  - can be constructed from two `Int64`, a `Date`, or a `Tuple{Int64,Int64}`
  - automatic conversion from `Date` or `Tuple{Int64,Int64}`
  - can use operators: `==`, `<`, `+`, `-`, `:`
  - `thisyear()`, `lastyear()`, `nextyear()` functions and macros

- new file `core/utils.jl` for utility functions that fit in no other file

- irregular data logging using `record!()`/`@record()` (#103)

- data outputs & visualisation for the skylark model (#97)

- `randn()` function and macro to sample from a vector using a normal distribution

- `make install` to download and install Julia and package dependencies (on Linux, #67)

- weather file for the Thüringer Becken

### Changed

- moved random number functions and macros from `input.jl` to `utils.jl`

- expanded weather data for Jena to 1990-2023

- Non-breeding skylarks only search for neighbours to follow once (-> huge
  performance improvement!)

### Fixed

- bug fixes in the skylark model


## [0.5.3] - 31-07-2024

**Switchable crop models**

### Added

- Support for switchable crop models (#70), crop models can be set
  with the `cropmodel` setting in the `[crop]` section of
  `parameters.toml`.

- New submodules `ALMaSS` for the ALMaSS crop model, and `SimpleCrop`
  for testing switchable crop models.

### Changed

- All functionality specific to the ALMaSS crop model has been moved
  to the submodule `ALMaSS`.

- Due to switchable crop models, some types are now parametric:
  `AgricultureModel{Tcroptype,Tcropstate}` and `FarmPlot{Tcropstate}`.

- `FarmPlot{Tcropstate}` now only stores basic information about which
  pixels are part of the farm plot, all crop-specific information is
  now stored in the field `cropstate`.  Many functions acting on a
  `FarmPlot` now mostly forward to functions of the same name acting
  on the `cropstate` field of a `FarmPlot`.

- The type of `height` in `ALMaSS.CropState` and
  `ALMaSS.CropCurveParams` is now a unitful number `::Length{Float64}`.

- Both crop models `ALMaSS` and `SimpleCrop` now also support the
  functions `cropcover` and `cropyield` in addition to `croptype`,
  `cropname`, `cropheight`.

- `cropheight` now returns a unitful number `::Length{Float64}`, and
  returns height `0cm` if the landscape at that position is not a
  `FarmPlot`.


## [0.5.2] - 30-07-2024

**Rewrote the skylark model**

### Added

- Skylark model is largely rewritten to follow a new phase structure (#9)

- animals can occupy territories (see `@occupy`, `@isoccupied`, `@vacate` macros/functions) (#94)

- `@cropcover` macro and function

- ODD documentation for Skylark

### Changed

- input files that are now copied to a separate `inputs` directory within the output directory

- `EventType` renamed to `Management` for clarity

- documentation website now has a "Scientific Documentation" section

### Removed

- old skylark model (has been rewritten, see above)

### Fixed

- all skylarks now migrate (#90)

- `insectbiomass()` uses units


## [0.5.1] - 13-06-2024

**Added Unitful.jl**

### Added

- Unitful.jl now used to add units to quantities

- `world.mapdirectory` parameter specifies the path to the directory in which
 `landcovermap`, `farmfieldsmap`, and `weatherfile` are located
 
- `world.mapresolution` parameter specifies the input maps' spatial resolution in meters
 
### Changed

- spatial functions now work with explicit distances (using Unitful.jl) rather than using
  the number of pixels

- all species definitions and tests updated to use units

---

## [0.5.0] - 07-06-2024

**This release doesn't add much new functionality, but represents a major restructuring 
of the code base. Specifically, it removes the Agents.jl dependency and changes the 
way the species definition macros work and are used.**

### Added

- `SimulationModel` type, extended by `AgricultureModel` struct

- `@create` macro defines a special phase function that is called when an individual
  animal is created (at birth or on model initialisation)
  
- functions (and associated macros) to replace Agents.jl functionality:
  - `move!()` and `walk!()` 
  - `nearby_ids()`, `nearby_animals()`, `countanimals()`, `neighbours()`
  - `directionto()`, `distanceto()`, `randomdirection()`
  - `nagents()`, `killallanimals!()`

- `@here` macro to return the pixel currently occupied by the active animal

- `core.logoutput` parameter to define whether logs are printed to screen, file, none, or both

- large logo and model structure diagram

- Changelog

### Changed

- `SimulationModel` replaces `AgentBasedModel`

- Species definition macros revamped:
  - `@species` now only defines parameters and variables and creates a mutable struct
  - `@phase` must now be defined in the top-level code and creates a global function
  - `@initialise` renamed to `@populate`, must also be called in the top-level code
  - `initindividual()` renamed to `create!()`
  
- Skylark, Wolpertinger, and Wyvern updated to match the new macros

- requires Julia 1.10

### Removed

- Agents.jl dependency (including `AgentBasedModel` and functions for adding/moving/removing agents)

---

## [0.4.1] - 2023-11-14

**Initial version of the skylark model**

### Added

- initial version of the Skylark species

- small Jena map

- animal individuals keep track of their parents' IDs

- several new functions and macros for animals

- installation instructions for Windows

### Changed

- graphics output is more configurable


## [0.4.0] - 2023-10-28

**Functions for animal populations**

### Added

- initialisation functions for individuals (not just species)

- migration function / migrant pool for animals that disappear from the landscape during winter

- skylark migration

### Changed

- online documentation was expanded and restructured

- nature macros moved to a separate file


*Started changelog at this point, earlier versions are not included.*

<!-- Template

## [version] - unreleased

<comments>

### *PLANNED*

### Added

### Changed

### Deprecated

### Removed

### Fixed

-->