Merge pull request #33 from open-AIMS/RME-version-updates

Changes to support RME v1.0.42

Author: ConnectedSystems

.JuliaFormatter

@@ -0,0 +1,21 @@
+style = "blue"
+indent = 4
+margin = 92
+always_for_in = "nothing"
+for_in_replacement = "∈"
+whitespace_typedefs = false
+import_to_using = true
+whitespace_in_kwargs = false
+align_struct_field = true
+align_assignment = false
+align_conditional = true
+align_pair_arrow = false
+normalize_line_endings = "unix"
+align_matrix = true
+join_lines_based_on_source = true
+indent_submodule = true
+surround_whereop_typeparameters = false
+yas_style_nesting = true
+trailing_comma = false
+short_to_long_function_def = false
+conditional_to_if = false

Project.toml

@@ -1,7 +1,7 @@
 name = "ReefModEngine"
 uuid = "f4ffb74a-bba7-4ac3-ad08-f8621d7c6d1d"
 authors = ["Takuya Iwanaga", "Daniel Tan", "Pedro Ribeiro de Almeida"]
-version = "1.4.1"
+version = "1.5.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
@@ -13,12 +13,18 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 YAXArrays = "c21b50f5-aa40-41ea-b809-c0f5e47bfa5c"
 
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]
+
 [compat]
 CSV = "0.10"
 DataFrames = "1"
 JSON = "0.21.4"
 NetCDF = "0.11.8"
-Statistics = "1.10.0"
+Statistics = "1"
 StatsBase = "0.33, 0.34"
 YAXArrays = "0.5.5"
 julia = "1"

docs/src/.vitepress/config.mts

@@ -51,7 +51,8 @@ export default defineConfig({
         // items: [
         //   { text: 'Link text', link: '/url_path' },
         // ]
-      }
+      },
+      {text: 'Results Store', link: '/result_store'}
     ],
     editLink: {
       pattern: 'https://github.com/open-AIMS/ReefModEngine.jl/edit/main/docs/src/:path'

docs/src/getting_started.md

@@ -25,42 +25,29 @@ A copy of the ReefMod Engine is available on request from its current developers
 
 :::
 
-## Pre-initialization setup
-
-Before using RME with ReefModEngine.jl, two changes must be done to the RME data files and
-configuration.
-
-1. A copy of the [Canonical Reefs](https://github.com/gbrrestoration/canonical-reefs)
-   geopackage must be placed inside the `data_files/region` directory with the name
-   `reefmod_gbr.gpkg`.
-
-   This is to aid in aligning the reef ids as used by ReefMod/RME with those used by
-   AIMS/ADRIA/GBRMPA.
-
-2. Inside the `data_files/config` directory, there is a `config.xml` file.
-   Make a backup of this file by making a copy of it.
-   (e.g., naming it `_config.xml` or `original_config.xml`)
-
-   Edit the `config.xml` file by removing all of the leading `../` from directory paths.
-   (a simple "search and replace all" will suffice).
-
-   The reason is that when used in MATLAB (the original intended use case for RME), the
-   assumed initial start location is inside `data_files/config`. The leading `../` moves
-   changes the directory up one level.
-
-   ReefModEngine.jl on the other hand treats `data_files` as the initial library location,
-   and so there is no need to move up one level.
-
 ## Initialization
 
-Before anything can be done, the RME library has to first be initialized.
+Use of RME with ReefModEngine.jl requires the RME library to first be initialized.
 
 ```julia
-# Initialize RME (may take a minute or two)
+# Initialize RME
 init_rme("path to RME directory")
-# [ Info: Loaded RME 1.0.28
+# [ Info: Loaded RME 1.0.42
 ```
 
+::: info
+
+[ADRIA](https://github.com/open-AIMS/ADRIA.jl) is able to run GBR-wide simulations with
+[CoraBlox](https://github.com/open-AIMS/CoralBlox.jl), using RME datasets to represent the
+GBR. Before doing so, however, a copy of the
+[Canonical Reefs](https://github.com/gbrrestoration/canonical-reefs) geopackage must be
+placed inside the `data_files/region` directory with the name `reefmod_gbr.gpkg`.
+
+This is to aid in aligning the reef ids as used by ReefMod/RME with those used by
+AIMS/ADRIA/GBRMPA.
+
+:::
+
 ## Setting RME options
 
 RME is able to run multiple simulations at the same time via multi-threading.
@@ -267,7 +254,7 @@ to run each replicate individually and store results as they complete.
 
 ::: warning
 
-ReefModEngine.jl's result store is currently memory-based as well, so the only advantage
+ReefModEngine.jl's result store is currently memory-based, so the only advantage
 to this approach currently is avoiding storing results when they are no longer necessary.
 Efforts will be made to move to a disk-backed store.
 

src/ReefModEngine.jl

@@ -25,7 +25,7 @@ macro RME(func)
 end
 
 """
-Only for use when RME functions return non-error numeric results.
+Only for use when RME functions return numeric results that are not error codes.
 
 # Examples
 
@@ -38,28 +38,32 @@ macro getRME(func)
 end
 
 """
-    rme_version_info()::@NamedTuple{major::Int64, minor::Int64, patch::Int64}
+    rme_version_info()::VersionNumber
 
-Get RME version
+Get RME version.
 """
-function rme_version_info()::@NamedTuple{major::Int64, minor::Int64, patch::Int64}
+function rme_version_info()::VersionNumber
     rme_ver = @RME version()::Cstring
-    rme_ver = parse.(Int64, split(rme_ver, '.'))
-    return (major=rme_ver[1], minor=rme_ver[2], patch=rme_ver[3])
+    return VersionNumber(rme_ver)
 end
 
 export rme_version_info
 
 include("rme_init.jl")
 include("interface.jl")
 include("deployment.jl")
+include("intervention.jl")
 include("io.jl")
 include("ResultStore.jl")
+include("logging.jl")
 
 # Set up and initialization
 export
     init_rme, reset_rme, @RME, @getRME, set_option, run_init, RME_PATH, RME
 
+# Parameter interface
+export set_iv_param, get_iv_param, get_param, iv_add
+
 # Convenience/utility methods
 export
     reef_ids, deployment_area, set_outplant_deployment!, set_enrichment_deployment!,
@@ -69,4 +73,11 @@ export
 export
     ResultStore, concat_results!, save_result_store
 
+# Logging
+export
+    log_set_all_items_enabled, log_set_item_enabled,
+    log_set_all_reefs_enabled, log_set_reef_enabled,
+    log_get_reef_data_ref, log_get_reef_data_int,
+    log_get_run_data_ref, log_get_run_data_int
+
 end

src/ResultStore.jl

@@ -52,6 +52,7 @@ function save_result_store(dir_name::String, result_store::ResultStore)::Nothing
     open(scenario_info_path, "w") do f
         write(f, si_json_string)
     end
+
     return nothing
 end
 
@@ -71,70 +72,70 @@ function create_dataset(start_year::Int, end_year::Int, n_reefs::Int, reps::Int)
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Number of juvenile corals
     nb_coral_juv = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Percentage rubble cover
     rubble = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Percentage rubble cover
     relative_shelter_volume = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # DHW [degree heating weeks]
     dhw = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # DHW mortality [% of population (to be confirmed)]
     dhw_mortality = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Cyclone mortality [% of population (to be confirmed)]
     cyc_mortality = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Cyclone categories [0 to 5]
     cyc_cat = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Crown-of-Thorn Starfish population [per ha]
     cots = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Mortality caused by Crown-of-Thorn Starfish [% of population (to be confirmed)]
     cots_mortality = DataCube(
         zeros(arr_size...);
         timesteps=start_year:end_year,
         locations=1:n_reefs,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
     # Total Species cover [% of total reef area]
     n_species = 6
@@ -144,7 +145,7 @@ function create_dataset(start_year::Int, end_year::Int, n_reefs::Int, reps::Int)
         timesteps=start_year:end_year,
         locations=1:n_reefs,
         taxa=1:n_species,
-        scenarios=1:(2 * reps)
+        scenarios=1:(2*reps)
     )
 
     return Dataset(;
@@ -223,7 +224,7 @@ function preallocate_concat!(rs, start_year, end_year, reps::Int64)::Nothing
     axlist = (
         Dim{:timesteps}(start_year:end_year),
         Dim{:locations}(1:(rs.n_reefs)),
-        Dim{:scenarios}((prev_reps + 1):new_n_reps)
+        Dim{:scenarios}((prev_reps+1):new_n_reps)
     )
 
     # Concatenate total_taxa_cover cube separately.
@@ -252,7 +253,7 @@ function preallocate_concat!(rs, start_year, end_year, reps::Int64)::Nothing
         Dim{:timesteps}(start_year:end_year),
         Dim{:locations}(1:(rs.n_reefs)),
         Dim{:taxa}(1:n_species),
-        Dim{:scenarios}((prev_reps + 1):new_n_reps)
+        Dim{:scenarios}((prev_reps+1):new_n_reps)
     )
     rs.results.cubes[:total_taxa_cover] = cat(
         rs.results.cubes[:total_taxa_cover],
@@ -277,8 +278,8 @@ function n_corals_calculation(
     return round(
         Int,
         (
-        sum((count_per_year .* target_reef_area_km² .* (1 / m2_TO_km2)))
-    )
+            sum((count_per_year .* target_reef_area_km² .* (1 / m2_TO_km2)))
+        )
     )
 end
 
@@ -341,7 +342,7 @@ function append_scenarios!(rs::ResultStore, reps::Int)::Nothing
         @getRME reefSetGetAsVector(
             reefset_name::Cstring, iv_reef_ids_idx::Ptr{Cint}, length(iv_reef_ids_idx)::Cint
         )::Cint
-        iv_reef_ids = reef_ids()[iv_reef_ids_idx .!== 0]
+        iv_reef_ids = reef_ids()[iv_reef_ids_idx.!==0]
         scenario_dict[reefset_name] = iv_reef_ids
 
         # Get reef areas for intervention reefset