Restructure documentation

docs/src/.vitepress/config.mts

@@ -37,7 +37,7 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Getting Started', link: '/getting_started' },
-      { text: 'API', link: '/api' }
+      { text: 'API', link: '/api' },
       // {
       //   text: 'Examples',
       //   items: [
@@ -52,7 +52,10 @@ export default defineConfig({
         //   { text: 'Link text', link: '/url_path' },
         // ]
       },
-      {text: 'Results Store', link: '/result_store'}
+      {text: 'Results Store', link: '/results_store'},
+      {text: 'RME Options', link: '/options'},
+      {text: 'Parallelisation', link: '/parallelisation'},
+      {text: 'API', link: '/api'},
     ],
     editLink: {
       pattern: 'https://github.com/open-AIMS/ReefModEngine.jl/edit/main/docs/src/:path'
@@ -65,4 +68,4 @@ export default defineConfig({
       copyright: `© Copyright ${new Date().getUTCFullYear()}. Released under the MIT License.`
     }
   }
-})
+})

docs/src/getting_started.md

@@ -68,27 +68,24 @@ AIMS/ADRIA/GBRMPA.
 
 :::
 
-## Setting RME options
+### RME Documentation
 
-RME is able to run multiple simulations at the same time via multi-threading.
-The recommended value according to the RME documentation is a number equal to or less than
-the number of available CPU cores.
+The full api interface is documented in the documentation provided with the binaries. The
+file `rme_matlab_api_guide.pdf` find in `documents` subdirectory of the ReefModEngine files.
+The documentation provides information on how runs are setup and how functions should be
+used.
 
-```julia
-# Set to use two threads
-set_option("thread_count", 2)
-```
-
-::: tip
-
-Do remember, however, that each process requires memory as well, so the total number of
-threads should not exceed `ceil([available memory] / [memory required per thread])`.
+::: info
 
-The required memory depends on a number of factors including the represented grid size.
-As a general indication, RME's memory use is ~4-5GB for a single run with a 10x10 grid.
+The Matlab API uses the same or similar names with different capitalisation/formatting
+conventions. For example matlab may invoke `rme_init` where as the c++ api function name is
+`rmeInit`. For complete clarity on function names and types consult the c++ header file
+`rme_ml.h` in the `lib` subdirectory.
 
 :::
 
+## Interface
+
 ReefModEngine.jl provides a few convenience functions to interact with RME.
 All other RME functions are available for direct use via the `@RME` macro.
 Care needs to be taken to call RME functions. Specifically:
@@ -99,7 +96,7 @@ Care needs to be taken to call RME functions. Specifically:
 A full list of ReefModEngine.jl functions is provided in [API](@ref API).
 
 ## Short list of RME interface functions
-
+Setting options. See [RME Options](@ref Setting-RME-options) for more information.
 ```julia
 # Set RME options by its config name
 # See RME documentation for list of available options
@@ -108,6 +105,9 @@ set_option("restoration_dhw_tolerance_outplants", 3)
 set_option("use_fixed_seed", 1)  # turn on use of a fixed seed value
 set_option("fixed_seed", 123)  # set the fixed seed value
 
+```
+Helpers for setting up interventions.
+```julia
 # Get list of reef ids as specified by ReefMod Engine
 reef_id_list = reef_ids()
 
@@ -125,12 +125,19 @@ match_id("10-330")
 # at a given density
 area_needed(100_000, 6.8)
 
+```
+Handling results. See [Results Store](@ref Results) for more information.
+```julia
 # Create a convenient result store to help extract data from RME
 result_store = ResultStore(start_year, end_year)
 
 # Collect and store all results, where `reps` is the total number of expected runs.
 concat_results!(result_store, start_year, end_year, reps)
 
+# Save results to a given location
+save_result_store(result_store, path_to_save_location)
+```
+```julia
 # Initialize RME runs
 run_init()
 
@@ -196,21 +203,6 @@ d_density_m² = 6.8
 
 # Initialize result store
 result_store = ResultStore(start_year, end_year)
-# Outputs:
-# ReefModEngine Result Store
-#
-# Each store holds data for `:ref` and `:iv` across:
-# 2022 to 2099 (78 years)
-# For 2 repeats.
-#
-# cover : (78, 3806, 2)
-# dhw : (78, 3806, 2)
-# dhw_mortality : (78, 3806, 2)
-# cyc_mortality : (78, 3806, 2)
-# cyc_cat : (78, 3806, 2)
-# cots : (78, 3806, 2)
-# cots_mortality : (78, 3806, 2)
-# species : (78, 3806, 6, 2)
 
 @info "Starting runs"
 reset_rme()  # Reset RME to clear any previous runs
@@ -247,26 +239,6 @@ run_init()
 
 # Collect and store results
 concat_results!(result_store, start_year, end_year, reps)
-
-# Save results to matfile with entries (matching ReefMod Engine standard names)
-# Defaults to "RME_outcomes_[today's date].mat"
-# coral_cover_ref
-# coral_cover_iv
-# dhw_ref
-# dhw_iv
-# dhwloss_ref
-# dhwloss_iv
-# cyc_ref
-# cyc_iv
-# cyccat_ref
-# cyccat_iv
-# cots_ref
-# cots_iv
-# cotsloss_ref
-# cotsloss_iv
-# species_ref
-# species_iv
-# TODO: Save to result example
 ```
 
 The RME stores all data in memory, so for larger number of replicates it may be better

docs/src/index.md

@@ -15,7 +15,10 @@ ReefMod has been ported to C++ to address issues and concerns around computation
 efficiency. This port is referred to as the ReefMod Engine (RME).
 
 This package, ReefModEngine.jl, provides a Julia interface to the RME, leveraging Julia's
-first-class language interoperability support.
+first-class language interoperability support. The package does the following
+
+- **Exposes the RME engine c++ API**
+- **Provides a simpler API for setup result collection** (optional)
 
 To avoid confusion, the following naming conventions are used when referring to each.
 
@@ -30,4 +33,4 @@ allow its use in Julia.
 
 A copy of the ReefMod Engine is available on request from its current developers at UQ.
 
-:::
+:::

docs/src/options.md

@@ -0,0 +1,22 @@
+# Setting RME options
+
+RME allows access to a range of options that change the way runs are execited. All of these
+are have defaults so are not required to changed for model runs but many are useful.
+ReefModEngine.jl provides access via the `set_option` function. For example, parallelisation
+can be set via the number of threads to use
+
+```julia
+set_option("thread_count", 2)
+```
+
+The name of all options and expected inputs is provided in the **RME system options**
+section of the documentation provided with the binaries. The documentation lists the option
+name, default value and the effect/meaning of the option.
+
+Some other options are as follows.
+
+```julia
+set_option("restoration_dhw_tolerance_outplants", 3)
+set_option("use_fixed_seed", 1)  # turn on use of a fixed seed value
+set_option("fixed_seed", 123)  # set the fixed seed value
+```

docs/src/parallelisation.md

@@ -0,0 +1,18 @@
+# Running model in parallel
+
+RME provides an option to run repititions in parallel with no additional setup via the
+`thread count` option. This can be set as follows
+
+```julia
+set_option("thread_count", 2)
+```
+
+::: tip
+
+Do remember, however, that each process requires memory as well, so the total number of
+threads should not exceed `ceil([available memory] / [memory required per thread])`.
+
+The required memory depends on a number of factors including the represented grid size.
+As a general indication, RME's memory use is ~4-5GB for a single run with a 10x10 grid.
+
+:::

docs/src/results_store.md

@@ -23,7 +23,7 @@ variables:
  - `cots_mortality`   ~ Mortality caused by COTS (% of population*)
  - `total_taxa_cover` ~ Total Species Cover (% of total reef area)
 
-*\* not formally confirmed*
+*not formally confirmed
 
 ## Usage