Updates to docs and readme

README.md

@@ -1,3 +1,12 @@
-# LevelSetTopOpt.jl
+# LevelSetTopOpt
 
-...
+| **badges** |
+
+LevelSetTopOpt is computational toolbox for level set-based topology optimisation implemented in Julia and the [Gridap](https://github.com/gridap/Gridap.jl) package ecosystem. See the documentation and following publication for further details:
+
+> Zachary J. Wegert, Jordi M. Fuertes, Connor Mallon, Santiago Badia, and Vivien J. Challis (2024). "LevelSetTopOpt.jl: A scalable computational toolbox for level set-based topology optimisation". In preparation.
+
+## Documentation
+
+- [**STABLE**](...) — **Documentation for the most recently tagged version.**
+- [**LATEST**](...) — *Documentation for the in-development version.*

docs/make.jl

@@ -1,27 +1,31 @@
+cd("./docs/")
+using Pkg; Pkg.activate(".")
+
 using Documenter
 using LevelSetTopOpt
 
 makedocs(
     sitename = "LevelSetTopOpt.jl",
     format = Documenter.HTML(
       prettyurls = false,
-      collapselevel = 1,
+      # collapselevel = 1,
     ),
     modules = [LevelSetTopOpt],
     pages = [
       "Home" => "index.md",
-      "Usage" => [
-        "usage/getting-started.md",
-        "usage/ad.md",
-        "usage/petsc.md",
-        "usage/mpi-mode.md",
-      ],
-      "Tutorials" => [
-        "tutorials/minimum_thermal_compliance.md",
-        "tutorials/minimum_elastic_compliance.md",
-        "tutorials/inverter_mechanism.md",
-        "tutorials/inverse_homogenisation.md",
-      ],
+      "Getting Started" => "getting-started.md",
+      # "Usage" => [
+      #   "usage/getting-started.md",
+      #   "usage/ad.md",
+      #   "usage/petsc.md",
+      #   "usage/mpi-mode.md",
+      # ],
+      # "Tutorials" => [
+      #   "tutorials/minimum_thermal_compliance.md",
+      #   "tutorials/minimum_elastic_compliance.md",
+      #   "tutorials/inverter_mechanism.md",
+      #   "tutorials/inverse_homogenisation.md",
+      # ],
       "Reference" => [
         "reference/optimisers.md",
         "reference/chainrules.md",
@@ -31,9 +35,9 @@ makedocs(
         "reference/utilities.md",
         "reference/benchmarking.md"
       ],
-      "Developer Notes" => [
-        "dev/shape_der.md",
-      ]
+      # "Developer Notes" => [
+      #   "dev/shape_der.md",
+      # ]
     ],
 )
 

docs/src/getting-started.md

@@ -0,0 +1,39 @@
+# Getting started
+
+## Installation
+
+`LevelSetTopOpt.jl` and additional dependencies can be installed in an existing Julia environment using the package manager. This can be accessed in the Julia REPL (read-eval–print loop) by pressing `]`. We then add the required packages via:
+```
+pkg> add LevelSetTopOpt, Gridap, GridapDistributed, GridapPETSc, GridapSolvers, PartitionedArrays, SparseMatricesCSR
+```
+Once installed, serial driver scripts can be run immediately, whereas parallel problems also require an MPI installation. 
+
+### MPI
+For basic users, [`MPI.jl`](https://github.com/JuliaParallel/MPI.jl) provides such an implementation and a Julia wrapper for `mpiexec` - the MPI executor. This is installed via:
+```
+pkg> add MPI
+julia> using MPI
+julia> MPI.install_mpiexecjl()
+```
+Once the `mpiexecjl` wrapper has been added to the system `PATH`, MPI scripts can be executed in a terminal via
+```
+mpiexecjl -n P julia  main.jl
+```
+where `main` is a driver script, `P` denotes the number of processors. 
+
+### PETSc
+In `LevelSetTopOpt.jl` we rely on the [`GridapPETSc.jl`](https://github.com/gridap/GridapPETSc.jl) satellite package to interface with the linear and nonlinear solvers provided by the PETSc (Portable, Extensible Toolkit for Scientific Computation) library. For basic users these solvers are provided by `GridapPETSc.jl` with no additional work. 
+
+### Advanced installation
+For more advanced installations, such as use of a custom MPI/PETSc installation on a HPC cluster, we refer the reader to the [discussion](https://github.com/gridap/GridapPETSc.jl) for `GridapPETSc.jl` and the [configuration page](https://juliaparallel.org/MPI.jl/stable/configuration/) for `MPI.jl`.
+
+## Usage and tutorials
+In order to get familiar with the library we recommend following the numerical examples described in: 
+
+> Zachary J. Wegert, Jordi M. Fuertes, Connor Mallon, Santiago Badia, and Vivien J. Challis (2024). "LevelSetTopOpt.jl: A scalable computational toolbox for level set-based topology optimisation". In preparation.
+
+More general tutorials for familiarising ones self with Gridap are available via the [Gridap Tutorials](https://gridap.github.io/Tutorials/dev/).
+
+## Known issues
+- PETSc's GAMG preconditioner breaks for split Dirichlet DoFs (e.g., x constrained while y free for a single node). There is no simple fix for this. We recommend instead using MUMPS or another preconditioner for this case.
+- Currently, our implementation of automatic differentiation does not support multiplication and division of optimisation functionals. We plan to add this in a future release of `LevelSetTopOpt.jl`. 

docs/src/index.md

@@ -1,6 +1,24 @@
 # LevelSetTopOpt.jl
-Welcome to the documentation for LevelSetTopOpt.jl!
+Welcome to the documentation for `LevelSetTopOpt.jl`!
 
-# What
+## Introduction
+`LevelSetTopOpt.jl` is computational toolbox for level set-based topology optimisation implemented in Julia and the Gridap package ecosystem. The core design principle of `LevelSetTopOpt.jl` is to provide an extendable framework for solving optimisation problems in serial or parallel with a high-level programming interface and automatic differentiation. See the following publication for further details:
 
-# Why
+> Zachary J. Wegert, Jordi M. Fuertes, Connor Mallon, Santiago Badia, and Vivien J. Challis (2024). "LevelSetTopOpt.jl: A scalable computational toolbox for level set-based topology optimisation". In preparation.
+
+## How to use this documentation
+
+* The first step for new users is to visit the [Getting Started](getting-started.md) page.
+
+* A set of tutorials are available as part of the above paper.
+
+* The detailed documentation is in the Reference section.
+
+## Julia educational resources
+
+A basic knowledge of the Julia programming language is needed to use the `LevelSetTopOpt.jl` package.
+Here, one can find a list of resources to get started with this programming language.
+
+* First steps to learn Julia form the [Gridap wiki](https://github.com/gridap/Gridap.jl/wiki/Start-learning-Julia) page.
+* Official webpage [docs.julialang.org](https://docs.julialang.org/)
+* Official list of learning resources [julialang.org/learning](https://julialang.org/learning/)

docs/src/reference/benchmarking.md

@@ -7,6 +7,7 @@ LevelSetTopOpt.benchmark
 ## Existing benchmark methods
 ```@docs
 LevelSetTopOpt.benchmark_optimizer
+LevelSetTopOpt.benchmark_single_iteration
 LevelSetTopOpt.benchmark_forward_problem
 LevelSetTopOpt.benchmark_advection
 LevelSetTopOpt.benchmark_reinitialisation