Merge pull request #31 from gridap/documentation

Adding documentations

.github/workflows/.ci.yml

@@ -26,3 +26,20 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.8'
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

docs/Project.toml

@@ -1,3 +1,5 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GridapEmbedded = "8838a6a3-0006-4405-b874-385995508d5d"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 STLCutters = "284f087d-c8bb-44c4-af3c-39d0e1f330a5"

docs/make.jl

@@ -1,17 +1,19 @@
-using Documenter, STLCutters
+using Documenter
+using Literate
+using STLCutters
 
 makedocs(;
     modules=[STLCutters],
     format=Documenter.HTML(),
     pages=[
-        "Home" => "index.md",
+        "Introduction" => "index.md",
+        "Usage" => "usage.md",
+        "Distributed" => "distributed.md",
+        "Reference" => ["public_api.md","types.md","functions.md"]
     ],
-    repo="https://github.com/pmartorell/STLCutters.jl/blob/{commit}{path}#L{line}",
     sitename="STLCutters.jl",
-    authors="Pere Antoni Martorell, Large Scale Scientific Computing",
-    assets=String[],
 )
 
-# deploydocs(;
-#     repo="github.com/pmartorell/STLCutters.jl",
-# )
+deploydocs(
+  repo = "github.com/gridap/STLCutters.jl.git",
+)

docs/src/distributed.md

@@ -0,0 +1,104 @@
+# Distributed
+
+## Introduction
+
+When dealing with large-scale problems, this package can be accelerated through two types of parallelization. The first one is multi-threading, which uses [Julia Threads](https://docs.julialang.org/en/v1/base/multi-threading/) for shared memory parallelization (e.g., `julia -t 4`). This method, adds some speed-up. However, it is only efficient for a reduced number of threads.
+
+The second one is a distributed memory computing. For such parallelization, we use MPI (`mpiexec -np 4 julia input.jl`) through [`PartitionedArrays`](https://www.francescverdugo.com/PartitionedArrays.jl/stable) and [`GridapDistributed`](https://gridap.github.io/GridapDistributed.jl/dev/). With MPI expect to efficiently compute large-scale problems, up to thousands of cores.
+
+Additionally, the distributed memory implementation is built on top of [GridapEmbedded](https://github.com/gridap/GridapEmbedded.jl). GridapEmbedded provides parallelization tools since [v0.9.2](https://github.com/gridap/GridapEmbedded.jl/releases/tag/v0.9.2).
+
+
+## Underlying distributed algorithms
+
+The implementation of multi-threading is straightforwardly applied to the embarrassingly parallel loops. However, the distributed memory implementation requires more involved algorithms for the global computations, e.g., the classification of the background cells as inside or outside. These algorithms are described in Chapter 4 of the following PhD thesis.
+
+> Pere A. Martorell. "Unfitted finite element methods for explicit boundary representations". PhD Thesis. Universitat Politècnica de Catalunya. 2024. [hdl.handle.net/10803/690625](https://www.tdx.cat/handle/10803/690625)
+
+## Multi-threading usage
+
+The usage of this package with multi-threading is the same as for the serial case (see [Serial example](@ref)). The user only needs to set the number of threads when initializing Julia. E.g.,
+
+```bash
+julia -threads 4 
+```
+
+## Distributed memory usage
+
+The distributed usage needs to be set up at the driver level. The user needs to install and load `MPI.jl`, `PartitionedArrays.jl`, and `GridapDistributed.jl`. 
+
+Here, we provide a basic example of solving the Poisson equation with distributed STLCutters with 8 MPI tasks. Run the following command.
+
+```bash
+mpiexec -np 8 julia poisson.jl
+```
+
+Where `poisson.jl` is the following code.
+
+```julia
+using STLCutters
+using GridapEmbedded
+using GridapDistributed
+using PartitionedArrays
+using MPI
+
+parts = (2,2,2)
+cells = (10,10,10)
+filename = "stl_file_path.stl"
+
+with_mpi() do distribute
+  ranks = distribute(LinearIndices((prod(parts))))
+  # Domain and discretization
+  geo = STLGeometry(filename)
+  pmin,pmax = get_bounding_box(geo)
+  model = CartesianDiscreteModel(ranks,parts,pmin,pmax,cells)
+  cutgeo = cut(model,geo)
+  # Cell aggregation
+  model,cutgeo,aggregates = aggregate(AggregateAllCutCells(),cutgeo)
+  # Triangulations
+  Ω_act = Triangulation(cutgeo,ACTIVE)
+  Ω = Triangulation(cutgeo)
+  Γ = EmbeddedBoundary(cutgeo)
+  nΓ = get_normal_vector(Γ)   
+  dΩ = Measure(Ω,2)
+  dΓ = Measure(Γ,2)
+  # FE spaces
+  Vstd = TestFESpace(Ω_act,ReferenceFE(lagrangian,Float64,1))
+  V = AgFEMSpace(Vstd)
+  U = TrialFESpace(V)
+  # Weak form
+  γ = 10.0
+  h = (pmax - pmin)[1] / cells[1]
+  ud(x) = x[1] - x[2]
+  f = 0
+  a(u,v) =
+    ∫( ∇(v)⋅∇(u) )dΩ +
+    ∫( (γ/h)*v*u  - v*(nΓ⋅∇(u)) - (nΓ⋅∇(v))*u )dΓ
+  l(v) =
+    ∫( v*f )dΩ +
+    ∫( (γ/h)*v*ud - (nΓ⋅∇(v))*ud )dΓ
+  # Solve
+  op = AffineFEOperator(a,l,U,V)
+  uh = solve(op)
+  writevtk(Ω,"results",cellfields=["uh"=>uh])
+end
+```
+!!! note
+    The STL file can be downloaded using [`download_thingi10k`](@ref).
+
+!!! note
+    It is recommended to use `with_debug()` instead of `with_mpi()` for debugging in serialized execution, see more details in [`PartitionedArrays`](https://www.francescverdugo.com/PartitionedArrays.jl/stable).
+
+!!! note
+    One can consider a different stabilization of the small cut-cell problem instead of AgFEM. Then, the `aggregate` and `AgFEMSpace` need to be removed.
+    See more examples in [`GridapEmbedded`](https://github.com/gridap/GridapEmbedded.jl)
+
+
+!!! warning
+    Even though the distributed algorithms are proven to be efficient for large-scale weak scaling tests [Martorell, 2024](https://www.tdx.cat/handle/10803/690625). The performance of this implementation is not tested.
+
+
+
+
+
+

docs/src/functions.md

@@ -0,0 +1,11 @@
+# Private functions
+
+```@index
+Pages = ["functions.md"] 
+```
+
+```@autodocs
+Modules = [STLCutters]
+Public = false
+Order   = [:function]
+```

docs/src/index.md

@@ -1,8 +1,24 @@
 # STLCutter.jl
 
-```@index
-```
+Welcome to the documentation for STLCutters.
 
-```@autodocs
-Modules = [STLCutters]
-```
+
+!!! note
+
+    These documentation pages are under construction.
+
+
+## What
+
+This package provides the tools for solving partial differential equations (PDEs) on domains bounded by [STL](https://en.wikipedia.org/wiki/STL_(file_format)) surfaces. STLCutters is an extension of [GridapEmbedded](https://github.com/gridap/GridapEmbedded.jl). GridapEmbedded is a package for solving 
+PDEs on embedded domains, e.g., using embedded, unfitted or immersed finite element methods. Both, GridapEmbedded and STLCutters build on top of [Gridap](https://github.com/gridap/GridapEmbedded.jl).
+
+In the following work, you can find the research related with STLCutters:
+
+> Santiago Badia, Pere A. Martorell, Francesc Verdugo. "Geometrical discretisations for unfitted finite elements on explicit boundary representations." Journal of Computational Physics 460 (2022): 111162. doi: [10.1016/j.jcp.2022.111162](https://doi.org/10.1016/j.jcp.2022.111162)
+
+## Why
+
+The simulation of industrial and scientific problems involves solving PDEs on complex geometries. The generation of body-fitted unstructured meshes requires extensive human intervention. Additionaly, mesh partitioners are inherently serial and represent a botleneck (or a limitation) in the parallelization. Embedded methods (e.g., [GridapEmbedded](https://github.com/gridap/GridapEmbedded.jl)) address this limitation by using simple (e.g., structured) meshes for the functional discretization.. However, these methods define the domain through implicit functions (i.e., level sets) which represents a significant limitation.
+
+This package addresses explicit boundary representations with embedded methods. Specifically, we provide algorithmic tools for the discretizations of embedded methods on STL surfaces. The implementations are designed to be efficient in large-scale distributed memory environments.

docs/src/public_api.md

@@ -0,0 +1,19 @@
+# Public API
+
+```@index
+Pages = ["public_api.md"]
+```
+
+
+```@meta
+CurrentModule = STLCutters
+```
+
+```@docs
+STLCutters.cut
+subtriangulate
+STLCutter
+STLGeometry
+download_thingi10k
+check_requisites
+```

docs/src/reference.md

@@ -0,0 +1,2 @@
+# Reference
+

docs/src/types.md

@@ -0,0 +1,11 @@
+# Private types
+
+```@index
+Pages = ["types.md"]
+```
+
+```@autodocs
+Modules = [STLCutters]
+Public = false
+Order   = [:type]
+```

docs/src/usage.md

@@ -0,0 +1,117 @@
+# Usage
+
+## Installation
+
+STLCutters is a registered package. You can install it by running:
+
+```julia
+# Use ] to enter the Pkg REPL mode
+pkg> add STLCutters
+```
+
+## Load package
+
+Load the package normally with
+
+```
+using STLCutters
+```
+
+## Downloading STL files
+
+The STLCutters package works with STL files. Therefore, first, you need to create or download an STL file. The [Thingi10k](https://ten-thousand-models.appspot.com/) dataset is one of the options for testing. You can download any indexed geometry with [`download_thingi10k`](@ref). E.g.,
+
+```
+filename = download_thingi10k(293137)
+```
+
+## Discretization
+
+Since STLCutters is an extension of [GridapEmbedded](https://github/gridap/GridapEmbedded.jl) it utilizes the same workflow to solve PDEs on embedded domains. In particular, STLCutters extends the [`cut`](@ref STLCutters.cut) function from GridapEmbedded.
+
+We load the STL file with an [`STLGeometry`](@ref) object. E.g.,
+
+```
+filename = download_thingi10k(293137)
+geo = STLGeometry(filename)
+```
+
+Then, we define a `DiscreteModel` around, e.g., a `CartesianDiscreteModel`.
+
+```julia
+pmin,pmax = get_bounding_box(geo)
+model = CartesianDiscreteModel(pmin,pmax,())
+```
+
+Now, we can [`cut`](@ref STLCutters.cut) the `model` with the `STLGeometry`.
+
+```julia
+cutgeo = cut(model,geo)
+```
+
+!!! note
+    Some STL files may not be properly defined. It is recommended to check the requisites before proceeding with [`check_requisites`](@ref). In particular, one checks if the STL is a closed surface, a manifold and has a bounded density of faces.
+
+## Usage with Gridap
+
+Once, the geometry is discretized one can generate the embedded triangulations to solve PDEs with [Gridap](https://github.com/gridap/Gridap.jl), see also [Gridap Tutorials](https://gridap.github.io/Tutorials/stable).
+
+Like in GridapEmbedded, we extract the embedded triangulations as follows.
+
+```julia
+Ωact = Triangulation(cutgeo,ACTIVE)
+Ω = Triangulation(cutgeo)
+Γ = EmbeddedBoundary(cutgeo)
+Λ = SkeletonTriangulation(cutgeo)
+```
+
+## Serial example
+
+Now, we provide an example of the solution of a Poisson problem on the embedded domain.
+
+```julia
+using STLCutters
+using GridapEmbedded
+cells = (10,10,10)
+filename = "stl_file_path.stl"
+# Domain and discretization
+geo = STLGeometry(filename)
+pmin,pmax = get_bounding_box(geo)
+model = CartesianDiscreteModel(pmin,pmax,cells)
+cutgeo = cut(model,geo)
+# Cell aggregation
+aggregates = aggregate(AggregateAllCutCells(),cutgeo)
+# Triangulations
+Ω_act = Triangulation(cutgeo,ACTIVE)
+Ω = Triangulation(cutgeo)
+Γ = EmbeddedBoundary(cutgeo)
+nΓ = get_normal_vector(Γ)   
+dΩ = Measure(Ω,2)
+dΓ = Measure(Γ,2)
+# FE spaces
+Vstd = TestFESpace(Ω_act,ReferenceFE(lagrangian,Float64,1))
+V = AgFEMSpace(Vstd)
+U = TrialFESpace(V)
+# Weak form
+γ = 10.0
+h = (pmax - pmin)[1] / cells[1]
+ud(x) = x[1] - x[2]
+f = 0
+a(u,v) =
+    ∫( ∇(v)⋅∇(u) )dΩ +
+    ∫( (γ/h)*v*u  - v*(nΓ⋅∇(u)) - (nΓ⋅∇(v))*u )dΓ
+l(v) =
+    ∫( v*f )dΩ +
+    ∫( (γ/h)*v*ud - (nΓ⋅∇(v))*ud )dΓ
+# Solve
+op = AffineFEOperator(a,l,U,V)
+uh = solve(op)
+writevtk(Ω,"results",cellfields=["uh"=>uh])
+```
+
+!!! note
+    The STL file can be downloaded using [`download_thingi10k`](@ref).
+
+!!! note
+    One can consider a different stabilization of the small cut-cell problem instead of AgFEM. Then, the `aggregate` and `AgFEMSpace` need to be removed.
+    See more examples in [`GridapEmbedded`](https://github.com/gridap/GridapEmbedded.jl)