Merge pull request #43 from JuliaGeodynamics/bk-update-docs

Update documentation

.github/workflows/CI.yml

@@ -6,6 +6,12 @@ on:
     branches:
       - main
     tags: '*'
+
+# Cancel redundant CI tests automatically
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   run_tests:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
@@ -41,18 +47,18 @@ jobs:
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest  
-  build_docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: julia-actions/setup-julia@latest
-        with:
-          version: '1.10'
-      - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
-      - name: Build and deploy
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+#  build_docs:
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: actions/checkout@v4
+#      - uses: julia-actions/setup-julia@latest
+#        with:
+#          version: '1.10'
+#      - name: Install dependencies
+#        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+#      - name: Build and deploy
+#        env:
+#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+#          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+#        run: julia --project=docs --color=yes docs/make.jl
 

.github/workflows/Documenter.yml

@@ -0,0 +1,48 @@
+# Note: this workflow is copied from the Trixi.jl package
+name: Documentation
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+    paths-ignore:
+      - '.zenodo.json'
+      - '.github/workflows/benchmark.yml'
+      - '.github/workflows/CI.yml'
+      - '.github/workflows/CompatHelper.yml'
+  pull_request:
+    paths-ignore:
+      - '.zenodo.json'
+      - '.github/workflows/CI.yml'
+      - '.github/workflows/CompatHelper.yml'
+      - '.github/workflows/TagBot.yml'
+      - 'benchmark/**'
+      - 'utils/**'
+  workflow_dispatch:
+
+# Cancel redundant CI tests automatically
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.9'
+          show-versioninfo: true
+      - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-buildpkg@v1
+        env:
+          PYTHON: ""
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        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 # To make GitHub Action work, disable showing a plot window with the GR backend of the Plots package
+        run: julia --project=docs --color=yes docs/make.jl

.gitignore

@@ -1,3 +1,4 @@
 test/*.pvd
 test/Timestep_*
-.CondaPkg
+.CondaPkg
+/.vscode

.zenodo.json

@@ -0,0 +1,14 @@
+{
+    "description": "Julia interface for the parallel Lithosphere and Mantle Evolution Model (LaMEM)",
+    "license": "MIT",
+    "title": "LaMEM.jl",
+    "upload_type": "software",
+    "creators": [
+        {
+            "affiliation": "Institute of Geosciences, Johannes Gutenberg University Mainz, Germany",
+            "name": "Kaus, Boris",
+            "orcid": "0000-0002-0247-8660"
+        },
+    ],
+    "access_right": "open"
+}

Project.toml

@@ -6,8 +6,8 @@ version = "0.2.12"
 [deps]
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
-GeophysicalModelGenerator = "3700c31b-fa53-48a6-808a-ef22d5a84742"
 GeoParams = "e018b62d-d9de-4a26-8697-af89c310ae38"
+GeophysicalModelGenerator = "3700c31b-fa53-48a6-808a-ef22d5a84742"
 Glob = "c27321d9-0574-5035-807b-f59d2c89b15c"
 LaMEM_jll = "15d6fa20-f789-5486-b71b-22b4ac8eb1c1"
 LightXML = "9c8b4983-aa76-5018-a973-4c85ecc9e179"
@@ -29,12 +29,13 @@ GeoParams = "0.4, 0.5"
 GeophysicalModelGenerator = "0.4 - 0.6"
 Glob = "1"
 LightXML = "0.9"
+MPICH_jll = "4.1 - 4.1.2"
 Plots = "1"
 ReadVTK = "0.1, 0.2"
 Statistics = "1.0"
 WriteVTK = "1"
 julia = "1.9"
-MPICH_jll = "4.1 - 4.1.2"
+
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

docs/.gitignore

@@ -0,0 +1 @@
+/build

docs/Project.toml

@@ -1,5 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
 
 [compat]
-Documenter = "0.27"
+Documenter = "1"
+Test = "1"

docs/make.jl

@@ -1,6 +1,8 @@
-using Documenter, LaMEM
+using Documenter
 push!(LOAD_PATH, "../src/")
 
+using LaMEM
+
 @info "Making documentation..."
 makedocs(;
     sitename="LaMEM.jl",
@@ -9,18 +11,21 @@ makedocs(;
     format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true"), # easier local build
     pages=[
         "Home" => "index.md",
-        "Installation" => ["General instructions" => "man/installation.md",
-                            "Installation on HPC systems" => "man/installation_HPC.md"],
-        "Create & run LaMEM models from julia" => ["Overview" => "man/juliasetups.md",
-                                                    "Example 1: Sphere" => "man/juliasetup_example_sphere.md",
-                                                    "Example 2: Volcano" => "man/juliasetup_LaPalma.md",
-                                                    "Example 3: Subduction" => "man/juliasetup_TMSubduction.md",
-                                                    "Notebooks" => "man/juliasetup_pluto.md",
-                                                    "Available functions" => "man/LaMEM_ModelFunctions.md"],
-        "Run LaMEM" => "man/runlamem.md",
-        "Reading timesteps" => "man/readtimesteps.md",
-        "List of functions" => "man/listfunctions.md",
+        "Installation" => ["General instructions" => "installation.md",
+                            "Installation on HPC systems" => "installation_HPC.md"],
+        "Create & run LaMEM models from julia" => ["Overview" => "juliasetups.md",
+                                                    "Example 1: Sphere" => "juliasetup_example_sphere.md",
+                                                    "Example 2: Volcano" => "juliasetup_LaPalma.md",
+                                                    "Example 3: 2D Subduction" => "juliasetup_TMSubduction.md",
+                                                    "Notebooks" => "juliasetup_pluto.md",
+                                                    "Available functions" => "LaMEM_ModelFunctions.md",
+                                                  ],
+        "Run LaMEM" => "runlamem.md",
+        "Reading timesteps" => "readtimesteps.md",
+        "List of functions" => "listfunctions.md",
     ],
+    pagesonly=true,
+    warnonly=true
 )
 
 deploydocs(; repo="github.com/JuliaGeodynamics/LaMEM.jl.git", devbranch="main")

docs/src/assets/LaMEM_ModelFunctions.md

@@ -0,0 +1,7 @@
+# List functions
+These are all the functions that are provided for the LaMEM Julia Setup interface 
+```@autodocs
+Modules = [LaMEM.LaMEM_Model]
+```
+
+

docs/src/index.md

@@ -3,5 +3,8 @@
 This is the julia interface to LaMEM, which does a number of handy things:
 
 - It will automatically download a binary installation of LaMEM, along with the correct version of PETSc and mpiexec for your system. You can also use these binaries directly from your terminal, so you are not limited to julia. Gone are the days where you had to first spend hours or days to install PETSc on your system!
-- We provide a simple function to run LaMEM from julia (also in parallel).
-- We provide functions to read timesteps back into julia. 
+- It provides the functionality to setup a model, run it and plot the results with a few lines of julia.
+- We provide many default options
+- You can do this with Jupyter or Pluto notebooks
+- We provide a simple function to run LaMEM from julia (also in parallel), using classical LaMEM `*.dat` files
+- We provide functions to read timesteps back into julia and compress out 

docs/src/installation.md

@@ -0,0 +1,27 @@
+# Installation
+
+Installing LaMEM can simply be done through the package manager:
+```julia
+julia>]
+pkg>add LaMEM
+```
+which will download the binaries along with PETSc and mpiexec for your system.
+
+You can test if it works on your machine with
+```julia
+pkg> test LaMEM
+```
+
+### Running LaMEM from the julia REPL
+Running LaMEM from within julia can be done with the `run_lamem` function:
+
+```@docs
+run_lamem
+```
+
+### Running LaMEM from outside julia
+If you, for some reason, do not want to run LaMEM through julia but instead directly from the terminal or powershell, you will have to add the required dynamic libraries and executables.
+Do this with:
+```@docs
+show_paths_LaMEM
+```

docs/src/installation_HPC.md

@@ -0,0 +1,67 @@
+# Installation on HPC systems
+
+Installing LaMEM on high performance computer (HPC) systems can be complicated, because you will have to compile PETSc with the correct dependencies for that system. 
+The reason is that HPC systems use MPI versions that are specifically tailored/compiled for that system. 
+
+> Warning: the explanation below is still somewhat experimental and may not work on your system
+> The best approach of running LaMEM on large HPC systems remains to install the correct version of PETSc using the locally recommended MPI libraries and install the correct version of LaMEM with that. You can still save the input setup to file, for the correct number or processors using LaMEM.jl. The locally generated `*.dat` file will still work.
+
+Luckily there is a solution thanks to the great work of `@eschnett` and colleagues, who developed [MPITrampoline](https://github.com/eschnett/MPItrampoline) which is an intermediate layer between the HPC-system-specific MPI libraries and the precompiled `LaMEM` binaries. 
+
+It essentially consists of two steps: 
+    1) compile a small package ([MPIwrapper](https://github.com/eschnett/MPIwrapper)) 
+    2) make sure that you download the version of `MAGEMin` that was compiled versus `MPItrampoline`.
+
+Here step-by-step instructions (for Linux, as that is what essentially all HPC systems use):
+
+
+* Download [MPIwrapper](https://github.com/eschnett/MPIwrapper): 
+```bash
+$git clone https://github.com/eschnett/MPIwrapper.git 
+$cd MPIwrapper
+```
+
+* Install it after making sure that `mpiexec` points to the one you want (you may have to load some modules, depending on your system):
+```bash
+$cmake -S . -B build -DMPIEXEC_EXECUTABLE=mpiexec -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=$HOME/mpiwrapper
+$cmake --build build
+$cmake --install build
+```
+At this stage, `MPItrampoline` is installed in `$HOME/mpiwrapper`
+
+* Set the correct wrapper:
+```
+$export MPITRAMPOLINE_LIB=$HOME/mpiwrapper/lib64/libmpiwrapper.so
+```
+Depending on the system it may be called `lib` instead of `lib64` (check!).
+
+* Start julia and install the `MPI` and `MPIPreferences` packages:
+```julia
+$julia
+julia> ]
+pkg>add MPI, MPIPreferences
+```
+
+* Set the preference to use `MPItrampoline`
+```julia
+julia> using MPIPreferences; MPIPreferences.use_jll_binary("MPItrampoline_jll")
+┌ Info: MPIPreferences unchanged
+└   binary = "MPItrampoline_jll"
+```
+
+* Load `MPI` and verify it is the correct one
+```julia
+julia> using MPI
+julia> MPI.Get_library_version()
+"MPIwrapper 2.10.3, using MPIABI 2.9.0, wrapping:\nOpen MPI v4.1.4, package: Open MPI boris@Pluton Distribution, ident: 4.1.4, repo rev: v4.1.4, May 26, 2022"
+```
+After this, restart julia (this only needs to be done once, next time all is fine).
+
+* Now load `LaMEM` and check that it uses the `mpitrampoline` version:
+```julia
+julia> using MPI,LaMEM
+julia> LaMEM.LaMEM_jll.host_platform
+Linux x86_64 {cxxstring_abi=cxx11, julia_version=1.8.1, libc=glibc, libgfortran_version=5.0.0, mpi=mpitrampoline}
+```
+
+At this stage the precompiled version of `LaMEM` should be useable on that system.