Merge pull request #41 from maltezfaria/doc-review

Doc review

Author: maltezfaria

.all-contributorsrc

@@ -20,5 +20,7 @@ MakieExt = "Makie"
 [compat]
 julia = "1.9"
 LinearAlgebra = "1"
+Makie = "0.21"
 MarchingCubes = "0.1.10"
 StaticArrays = "1"
+MMG_jll = "5"

Project.toml

@@ -7,28 +7,11 @@
 [![Lint workflow Status](https://github.com/maltezfaria/LevelSetMethods.jl/actions/workflows/Lint.yml/badge.svg?branch=main)](https://github.com/maltezfaria/LevelSetMethods.jl/actions/workflows/Lint.yml?query=branch%3Amain)
 [![Docs workflow Status](https://github.com/maltezfaria/LevelSetMethods.jl/actions/workflows/Docs.yml/badge.svg?branch=main)](https://github.com/maltezfaria/LevelSetMethods.jl/actions/workflows/Docs.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/maltezfaria/LevelSetMethods.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/maltezfaria/LevelSetMethods.jl)
-[![DOI](https://zenodo.org/badge/DOI/FIXME)](https://doi.org/FIXME)
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
-[![All Contributors](https://img.shields.io/github/all-contributors/maltezfaria/LevelSetMethods.jl?labelColor=5e1ec7&color=c0ffee&style=flat-square)](#contributors)
 [![BestieTemplate](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/JuliaBesties/BestieTemplate.jl/main/docs/src/assets/badge.json)](https://github.com/JuliaBesties/BestieTemplate.jl)
 
-## How to Cite
+This package provides tools to solve level-set equations on cartesian meshes. It closely
+follows the book [Level Set Methods and Dynamic Implicit
+Surfaces](https://link.springer.com/book/10.1007/b98879) by Stanley Osher and Ronald Fedkiw.
 
-If you use LevelSetMethods.jl in your work, please cite using the reference given in [CITATION.cff](https://github.com/maltezfaria/LevelSetMethods.jl/blob/main/CITATION.cff).
-
-## Contributing
-
-If you want to make contributions of any kind, please first that a look into our [contributing guide directly on GitHub](docs/src/90-contributing.md) or the [contributing page on the website](https://maltezfaria.github.io/LevelSetMethods.jl/dev/90-contributing/)
-
----
-
-### Contributors
-
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-
-<!-- ALL-CONTRIBUTORS-LIST:END -->
+For more details, see the [stable](https://maltezfaria.github.io/LevelSetMethods.jl/stable)
+or [development](https://maltezfaria.github.io/LevelSetMethods.jl/dev) documentations.

README.md

@@ -42,8 +42,8 @@ makedocs(;
         "terms.md",
         "time-integrators.md",
         "boundary-conditions.md",
-        hide("Extensions" => "extensions.md", ["extension-makie.md", "extension-mmg.md"]),
-        hide("Examples" => "examples.md", ["example-zalesak.md", "example-shape-optim.md"]),
+        "Extensions" => ["extension-makie.md", "extension-mmg.md"],
+        "Examples" => ["example-zalesak.md", "example-shape-optim.md"],
         numbered_pages,
     ),
     pagesonly = true, # ignore .md files not in the pages list

docs/make.jl

@@ -4,14 +4,19 @@
 
 We consider in this example the *isoperimetric inequality* which states that among all closed surfaces enclosing a fixed area with volume $V_0 > 0$, the sphere is the one with minimal perimeter.
 We show here how to demonstrate this result through numerical optimization.
-To do this, we first define the problem mathematically (1):
+
+!!! warning
+    This example is purely illustrative. The optimization method used here has not been extensively tested.
+    Coupling the [LevelSetMethods](https://github.com/maltezfaria/LevelSetMethods.jl) toolbox to any simulation package makes it possible to solve PDE-constrained optimization problems (see for instance [allaire2004structural](@cite)).
+
+To do this, we first define the problem mathematically:
 
 ```math
     \begin{array}{rl}
-        \displaystyle\min_{\Omega \subset \mathbb{R}^N} & P(\Omega)
+        \displaystyle\min_{\Omega \subset \mathbb{R}^d} & P(\Omega)
         \\
         \text{u.c.} & V(\Omega) = V_0
-    \end{array},
+    \end{array},\qquad\text{(1)}
 ```
 
 where $P(\Omega), V(\Omega)$ are the perimeter and volume of $\Omega$ defined by
@@ -23,16 +28,17 @@ where $P(\Omega), V(\Omega)$ are the perimeter and volume of $\Omega$ defined by
     .
 ```
 
-The optimization problem (1) can be solved using the augmented Lagrangian approach by minimizing iteratively the following functional (2):
+The optimization problem $\text{(1)}$ can be solved using the augmented Lagrangian approach by minimizing iteratively the following functional:
 
 ```math
     f(\Omega) = P(\Omega) + \lambda (V(\Omega) - V_0) + \frac{\mu}{2} (V(\Omega) - V_0)^2
+    \qquad\text{(2)}
 ```
 
 where $\mu$ is a parameter updated during the course of the optimization.
-To minimize (2), we will use a gradient-based algorithm.
+To minimize $\text{(2)}$, we use a gradient-based algorithm.
 For this, we need to define what a *small variation* of $\Omega$ is.
-As such, we define for any shape $\Omega \subset \mathbb{R}^N$ its deformed configuration $\Omega_{\boldsymbol{\theta}}$ by a small vector field $\boldsymbol{\theta} \in W^{1,\infty}(\mathbb{R}^N, \mathbb{R}^N)$ as:
+As such, for any shape $\Omega \subset \mathbb{R}^d$ we define (following Hadamard method) its deformation $\Omega_{\boldsymbol{\theta}}$ by a small vector field $\boldsymbol{\theta} \in W^{1,\infty}(\mathbb{R}^d, \mathbb{R}^d)$ as:
 
 ```math
     \Omega_{\boldsymbol{\theta}}
@@ -60,7 +66,7 @@ In other words, using $\boldsymbol{\theta} = - (\kappa + (\lambda + \mu (V(\Omeg
 
 ## Numerical solution using the level-set method
 
-If $\Omega$ is given by the level-set function $\phi_0 : \R^N \to \R$ then one associated with $\Omega_{\tau\boldsymbol{\theta}}$ is given by $\phi(\cdot, \tau)$ solution of
+If $\Omega$ is given by the level-set function $\phi_0 : \R^d \to \R$ then one associated with $\Omega_{\tau\boldsymbol{\theta}}$ is given by $\phi(\cdot, \tau)$ solution of
 
 ```math
     \partial_t \phi - \kappa |\nabla \phi| - (\lambda + \mu (V(\Omega) - V_0)) |\nabla \phi| = 0
@@ -127,3 +133,6 @@ end
 ```
 
 ![Optimization](optimization.gif)
+
+Different values and updates for the $\lambda$ and $\mu$ coefficients can be used to control the extent to which the optimization focuses on minimizing the objective or satisfying the constraint.
+Taking a smaller time step can also limit the oscillations observed at the end of optimization.