[doc] add doc-strings and setup doc-pages

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,15 @@
-using Documenter, STLCutters
+using Revise
+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",
     ],
-    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",
-# )

docs/src/index.md

@@ -1,8 +1,45 @@
 # STLCutter.jl
 
+Welcome to the documentation for 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.
+
+
+
 ```@index
 ```
 
+
+
 ```@autodocs
 Modules = [STLCutters]
+Order   = [:type, :function]
 ```
+
+```@meta
+CurrentModule = STLCutters
+```
+
+```@docs
+subtriangulate
+```
+

docs/src/usage.md

@@ -0,0 +1,11 @@
+# Usage
+
+## Installation
+
+STLCutters is a registered package. You can install it by running:
+
+```julia
+julia> ] add STLCutters
+```
+
+# Downloading STL files

src/STLs.jl

@@ -1,4 +1,12 @@
 
+
+"""
+    struct STLTopology{Dc,Dp,T} <: GridTopology{Dc,D}
+
+  [`STLTopology`](@ref) is a `Gridap.GridTopology` without lazy arrays.
+  It reduces computations when accessing their properties. It is used to
+  save the STL geometries. It is alliased as [`STL`](@ref).
+"""
 struct STLTopology{Dc,Dp,T} <: GridTopology{Dc,Dp}
   vertex_to_coordinates::Vector{Point{Dp,T}}
   n_m_to_nface_to_mfaces::Matrix{Table{Int32,Vector{Int32},Vector{Int32}}}
@@ -7,6 +15,11 @@ struct STLTopology{Dc,Dp,T} <: GridTopology{Dc,Dp}
   offsets::Vector{Int32}
 end
 
+"""
+    const STL = STLTopology
+
+  Alias [`STLTopology`](@ref) as `STL`.
+"""
 const STL = STLTopology
 
 function STL(model::DiscreteModel)
@@ -76,26 +89,52 @@ function get_face_vertices(stl::STL{D}) where D
   f_to_v
 end
 
+"""
+    get_cell!(cache,stl::STL,i::Integer)
+
+  Get a cell as a [`Face`](@ref).
+  It requires [`get_cell_cache`](@ref) to be allocate the cache.
+"""
 function get_cell!(c,stl::STL{Dc},i::Integer) where Dc
   get_dface!(c,stl,i,Val{Dc}())
 end
 
+"""
+    get_dface!(cache,stl::STL,i::Integer,::Val{d})
+
+  Get a face as a [`Face`](@ref)
+"""
 function get_dface!(c,stl::STL,i::Integer,::Val{d}) where d
   T = get_face_vertices(stl,d)
   X = get_vertex_coordinates(stl)
   p = get_polytope(stl)
   get_dface!(c,X,T,p,i,Val{d}())
 end
 
+"""
+    get_cell(stl::STL,i::Integer)
+
+  Get a cell as a [`Face`](@ref).
+"""
 function get_cell(stl::STL,i::Integer)
   c = get_cell_cache(stl)
   get_cell!(c,stl,i)
 end
 
+"""
+    get_cell_cache(stl::STL)
+
+  Allocate cache for [`get_cell!`](@ref).
+"""
 function get_cell_cache(stl::STL{Dc}) where Dc
   get_dface_cache(stl,Dc)
 end
 
+"""
+    get_dface_cache(stl::STL,d::Integer)
+
+  Allocate cache for [`get_dface!`](@ref).
+"""
 function get_dface_cache(stl::STL,d::Integer)
   T = get_face_vertices(stl,d)
   array_cache(T)
@@ -116,6 +155,11 @@ function get_simplex_dface!(cache,X,T,i::Integer,::Val{d}) where d
   simplex_face( vertices )
 end
 
+"""
+    is_open_surface(topo::GridTopology)
+
+  Predicate to check if a surface is water tight.
+"""
 function is_open_surface(stl::GridTopology)
   Dc = num_dims(stl)
   e_to_f = get_faces(stl,Dc-1,Dc)
@@ -124,8 +168,14 @@ function is_open_surface(stl::GridTopology)
   true
 end
 
-# Read STL from file
+"""
+    read_stl(filename)
 
+  Read STL file with `MeshIO.jl` and `Gridap.jl` arrays:
+  - `vertex_to_coordinates` is a vector of `Point{3,Float64}`
+  - `facet_to_vertices` is a `Gridap.Table` of `Int`
+  - `facet_to_normals` is a vector of `VectorValue{3,Float64}`
+"""
 function read_stl(filename::String)
   mesh = _load(filename)
   vertex_to_coordinates = MeshIO.decompose(MeshIO.Point3,mesh)
@@ -174,7 +224,11 @@ function Base.convert(::Type{Vector{T}},x::MeshIO.TriangleFace) where T
 end
 
 # Save STL to file
+"""
+    save_as_stl(stl::DiscreteModel,filename)
 
+  Save `DiscreteModel{2,3}` into a STL file.
+"""
 function save_as_stl(stl::DiscreteModel{Dc,Dp},filename) where {Dc,Dp}
   (Dc == 2 && Dp == 3 ) || error("Geometry incompatible with STL format")
   filename *= ".stl"
@@ -201,6 +255,13 @@ function save_as_stl(stl::DiscreteModel{Dc,Dp},filename) where {Dc,Dp}
   filename
 end
 
+
+"""
+    save_as_stl(stl::Vector{<:DiscreteModel},filename)
+
+  Save a list of `DiscreteModel{2,3}` into STL files. It save the files as
+  `filename_1.stl`, `filename_2.stl`,..., `filename_n.stl``.
+"""
 function save_as_stl(stls::Vector{<:DiscreteModel},filename)
   files = []
   for (i,stl) in enumerate(stls)
@@ -1163,12 +1224,11 @@ end
 # Testing helpers
 
 """
-  download_thingi10k(id;path"")
+    download_thingi10k(id;path"")
 
 Dowloads surface model from [thingiverse](https://www.thingiverse.com)
 indexed by FileID at [Thingi10K](https://ten-thousand-models.appspot.com)
 """
-
 function download_thingi10k(id;path="")
   url = "https://www.thingiverse.com/download:$id"
   r = Downloads.request(url)

src/SimplexFaces.jl

@@ -1,4 +1,9 @@
 
+"""
+   abstract type Face{Df,Dp}
+
+  Face type used to compute intersections with multiple dispatching.
+"""
 abstract type Face{Df,Dp} end
 
 struct Segment{D,T}<:Face{1,D}

src/SubTriangulations.jl

@@ -5,6 +5,23 @@ const FACE_CUT = -1
 const FACE_IN = 1
 const FACE_OUT = 2
 
+"""
+    SubtriangulationLabels
+
+  Labels for the sub grids of [`subtriangulate`](@ref).
+
+  It stores the following fields:
+  - `cell_to_bgcell`: subcell to background cell
+  - `cell_to_io`: subcell to IN/OUT
+  - `face_to_stlface`: subface to STL face
+  - `face_to_bgcell`: subface to background cell
+  - `face_to_ios`: subface to surface source (IN,OUT,SKIN)
+  - `bgcell_to_ioc`: background cell to IN/OUT/CUT
+  - `bgface_to_ioc`: background face to IN/OUT/CUT
+  - `bface_to_lbgface`: subface to local background face
+  - `bface_to_bgcell`: subface to background cell
+  - `bface_to_io`: subface to IN/OUT
+"""
 struct SubtriangulationLabels
   cell_to_bgcell::Vector{Int32}
   cell_to_io::Vector{Int8}
@@ -18,6 +35,32 @@ struct SubtriangulationLabels
   bface_to_io::Vector{Int8}
 end
 
+
+"""
+    subtriangulate(bgmodel::DiscreteModel,stl::DiscreteModel;kwargs...)
+
+  Intersection of each background cell in `bgmodel` with domain bounded by the
+  `stl` surface.
+
+  It returns a three grids and set of lables:
+  - `cell_grid`: cell-wise volume grid of the intersection of each background cell and the interior of the domain.
+  - `face_grid`: cell-wise surface grid of the intersection of each background cell and the `stl` surface.
+  - `bface_grid`: facet-wise surface grid of the intersection of each background (d-1)-face and the interior of the domain.
+  - `labels`: [`SubtriangulationLabels`](@ref) label IN/OUT/CUT, background cell, background face or STL face.
+
+
+  # Optional keywords arguments:
+  - `kdtree`: (default `false`) if `true` it uses a kdtree as a first step
+  - `tolfactor`: (default `1e3`) relative tolerance with respect to machine
+     precision (e.g., `1e-16*max_length(bgmodel)`)
+  - `surfacesource`: (default `:skin`) source of the `face_grid`.
+      - `:skin`: the `face_grid` is the intersection of the `stl` surface
+      - `:interior`: the `face_grid` is extracted of the interior `cell_grid`
+      - `:exterior`: the `face_grid` is extracted of the exterior `cell_grid
+      - `:both`: retunrs boths `:interior` and `:exterior` `face_grid`. It must be filtered (only used for debugging purposes).
+  - `showprogress`: (default `true`) show progress bar
+  - `all_defined`: (default `true`) if `true` all cells are defined as `IN`, `OUT` or `CUT`. If `false` undefined cells are allowed (only used for distributed meshes)
+"""
 function subtriangulate(
   bgmodel::DiscreteModel,
   stlmodel::DiscreteModel;
@@ -225,6 +268,17 @@ function propagate_inout!(bgmodel,bgcell_to_ioc,bgnode_to_io;all_defined)
   bgcell_to_ioc
 end
 
+"""
+    propagate_inout!(bgmocel,bgcell_to_inoutcut,bgnode_to_inoutcut,in_or_out)
+
+  Propagates IN or OUT (`in_or_out`) label of each backgroun cell
+  (`bgcell_to_inoutcut`) through the nodes of the background
+  model (`bgnode_to_inoutcut`).
+  It overwrites `bgcell_to_inoutcut``.
+
+
+  It is implemented with a deep-first search algorithm that stops at CUT cells.
+"""
 function propagate_inout!(bgmodel,bgcell_to_ioc,bgnode_to_io,in_or_out)
   D = num_dims(bgmodel)
   grid_topology = get_grid_topology(bgmodel)