From 45bd1d979c2f1900769170dac44aa4f24c1c4112 Mon Sep 17 00:00:00 2001 From: zjwegert <60646897+zjwegert@users.noreply.github.com> Date: Thu, 4 Apr 2024 12:07:18 +1000 Subject: [PATCH 1/3] Add some more docs --- docs/make.jl | 36 +++++++++++++++------------ docs/src/getting-started.md | 39 ++++++++++++++++++++++++++++++ docs/src/index.md | 24 +++++++++++++++--- docs/src/reference/benchmarking.md | 1 + 4 files changed, 81 insertions(+), 19 deletions(-) create mode 100644 docs/src/getting-started.md diff --git a/docs/make.jl b/docs/make.jl index b9f14f4e..fc289362 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,3 +1,6 @@ +cd("./docs/") +using Pkg; Pkg.activate(".") + using Documenter using LevelSetTopOpt @@ -5,23 +8,24 @@ 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", + # ] ], ) diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md new file mode 100644 index 00000000..5b9eed32 --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index c26e8171..2a9769a0 100644 --- a/docs/src/index.md +++ b/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/) \ No newline at end of file diff --git a/docs/src/reference/benchmarking.md b/docs/src/reference/benchmarking.md index e5e6d42e..617ee276 100644 --- a/docs/src/reference/benchmarking.md +++ b/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 From e766580de3c598eb39b0c07b177214bfff8e40e1 Mon Sep 17 00:00:00 2001 From: zjwegert <60646897+zjwegert@users.noreply.github.com> Date: Thu, 4 Apr 2024 12:13:58 +1000 Subject: [PATCH 2/3] Update readme --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 18d66ae5..4be459bc 100755 --- a/README.md +++ b/README.md @@ -1,3 +1,10 @@ -# LevelSetTopOpt.jl +# LevelSetTopOpt -... \ No newline at end of file +[comment]: 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 for further details. + +## Documentation + +- [**STABLE**](...) — **Documentation for the most recently tagged version.** +- [**LATEST**](...) — *Documentation for the in-development version.* \ No newline at end of file From 93f33fa935eb56ee884c7f798793ff1b89699acd Mon Sep 17 00:00:00 2001 From: zjwegert <60646897+zjwegert@users.noreply.github.com> Date: Thu, 4 Apr 2024 12:15:54 +1000 Subject: [PATCH 3/3] README update 2 --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4be459bc..1ce80170 100755 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # LevelSetTopOpt -[comment]: badges +| **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 for further details. +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