Initial docs setup

.github/workflows/Documenter.yml

@@ -0,0 +1,49 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Documenter
+
+on:
+  push:
+    branches:
+      - main
+    tags: ['*']
+  pull_request:
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+  statuses: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Julia
+        uses: julia-actions/setup-julia@v1
+      - name: Pull Julia cache
+        uses: julia-actions/cache@v1
+      - name: Install documentation dependencies
+        run: julia --project=docs -e 'using Pkg; pkg"dev ."; Pkg.instantiate(); Pkg.precompile(); Pkg.status()'
+      #- name: Creating new mds from src
+      - name: Build and deploy docs
+        uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          GKSwstype: "100" # for Plots.jl plots (if you have them)
+          JULIA_DEBUG: "Documenter"
+          DATADEPS_ALWAYS_ACCEPT: true

.github/workflows/TagBot.yml

@@ -0,0 +1,31 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+    inputs:
+      lookback:
+        default: 3
+permissions:
+  actions: read
+  checks: read
+  contents: write
+  deployments: read
+  issues: read
+  discussions: read
+  packages: read
+  pages: read
+  pull-requests: read
+  repository-projects: read
+  security-events: read
+  statuses: read
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
+ReefModEngine = "f4ffb74a-bba7-4ac3-ad08-f8621d7c6d1d"

docs/make.jl

@@ -0,0 +1,34 @@
+using Documenter, DocumenterVitepress
+using ReefModEngine
+using Logging
+
+Logging.disable_logging(Logging.Warn)
+
+makedocs(;
+    sitename="ReefModEngine.jl",
+    modules=[ReefModEngine],
+    clean=true,
+    doctest=true,
+    authors="Iwanaga et al.",
+    checkdocs=:all,
+    format=DocumenterVitepress.MarkdownVitepress(
+        repo = "github.com/open-AIMS/ReefModEngine.jl", # this must be the full URL!
+        devbranch="main",
+        devurl="dev";
+    ),
+    draft=false,
+    source="src",
+    build="build",
+    warnonly=true,
+)
+
+# Enable logging to console again
+Logging.disable_logging(Logging.BelowMinLevel)
+
+deploydocs(;
+    repo="github.com/open-AIMS/ReefModEngine.jl.git",
+    target="build", # this is where Vitepress stores its output
+    branch = "gh-pages",
+    devbranch="main",
+    push_preview = true
+)

docs/package.json

@@ -0,0 +1,16 @@
+{
+    "scripts": {
+        "docs:dev": "vitepress dev build/.documenter",
+        "docs:build": "vitepress build build/.documenter",
+        "docs:preview": "vitepress preview build/.documenter"
+    },
+    "dependencies": {
+        "@shikijs/transformers": "^1.1.7",
+        "markdown-it": "^14.0.0",
+        "markdown-it-footnote": "^4.0.0",
+        "markdown-it-mathjax3": "^4.3.2",
+        "vitepress": "^1.0.0-rc.43",
+        "vitepress-plugin-tabs": "^0.5.0",
+        "vitest": "^1.3.0"
+    }
+}

docs/src/index.md

@@ -0,0 +1,116 @@
+# ReefModEngine.jl
+
+A Julia interface to the ReefMod Engine (RME) C++ API.
+
+Targets RME v1.0, and provides some convenience functions for outplanting interventions.
+All other functions are accessible via the `@RME` macro.
+
+The RME library, accompanying dataset, and RME documentation has to be requested from RME developers.
+
+## Usage example
+
+```julia
+using ReefModEngine
+using CSV, DataFrames, MAT
+
+# Initialize RME (may take a minute or two)
+init_rme("path to RME directory")
+# [ Info: Loaded RME 1.0.28
+
+# Set to use two threads
+set_option("thread_count", 2)
+
+# Load target intervention locations determined somehow (e.g., by ADRIA)
+# The first column is simply the row number.
+# The second column is a list of target reef ids matching the format as found in
+# the id list file (the file is found under `data_files/id` of the RME data set)
+deploy_loc_details = CSV.read("target_locations.csv", DataFrame, header=["index_id", "reef_id"])
+
+name = "Example"
+start_year = 2022
+end_year = 2099
+RCP_scen = "SSP 2.45"
+gcm = "CNRM_ESM2_1"
+reps = 2
+n_reefs = 3806
+
+# Get list of reef ids as specified by ReefMod Engine
+reef_id_list = reef_ids()
+
+# Reef indices and IDs
+target_reef_idx = deploy_loc_details.index_id
+target_reef_ids = deploy_loc_details.reef_id
+n_target_reefs = length(target_reef_idx)
+
+# Get reef areas from RME
+reef_areas = zeros(n_reefs)
+@RME reefAreasKm2(reef_areas::Ptr{Cdouble}, n_reefs::Cint)::Cint
+
+# Get list of areas for the target reefs
+target_reef_areas_km² = reef_areas[target_reef_idx]
+d_density_m² = 6.8  # coral seeding density (per m²)
+
+# Initialize result store
+result_store = ResultStore(start_year, end_year, n_reefs, reps)
+# 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"
+@RME ivRemoveAll()::Cvoid
+@RME reefSetRemoveAll()::Cint
+
+# Note: if the Julia runtime crashes, check that the specified data file location is correct
+@RME runCreate(name::Cstring, start_year::Cint, end_year::Cint, RCP_scen::Cstring, gcm::Cstring, reps::Cint)::Cint
+
+# Add 3 DHW enhancement to outplanted corals
+set_option("restoration_dhw_tolerance_outplants", 3)
+
+# Create a reef set using the target reefs
+@RME reefSetAddFromIdList("iv_moore"::Cstring, target_reef_ids::Ptr{Cstring}, length(target_reef_ids)::Cint)::Cint
+
+# Deployments occur between 2025 2030
+# Year 1: 100,000 outplants; Year 2: 500,000; Year 3: 1,1M; Year 4: 1,1M; Year 5: 1,1M and Year 6: 1,1M.
+set_outplant_deployment!("outplant_iv_2026", "iv_moore", 100_000, 2026, target_reef_areas_km², d_density_m²)
+set_outplant_deployment!("outplant_iv_2027", "iv_moore", 500_000, 2027, target_reef_areas_km², d_density_m²)
+set_outplant_deployment!("outplant_iv_2028_2031", "iv_moore", Int64(1.1 * 1e6), Int64(1.1 * 1e6)*3, 2028, 2031, 1, target_reef_areas_km², d_density_m²)
+
+@RME runInit()::Cint
+
+# Run all years and all reps
+@time @RME runProcess()::Cint
+
+# Collect and store results
+collect_all_results!(result_store, start_year, end_year, reps)
+
+# Save results to matfile with entries (matching ReefMod Engine standard names)
+# 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
+save_to_mat(result_store)
+```