Geometrical derivatives

.gitignore

@@ -6,5 +6,6 @@
 /docs/build/
 /docs/site/
 Manifest.toml
+LocalPreferences.toml
 .vscode/
 *.swp

NEWS.md

@@ -4,12 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.6] - 2025-04-19
 
 ### Added
 
 - Added support for distributed level-set geometries. Since PR[#99](https://github.com/gridap/GridapEmbedded.jl/pull/99).
 - Refactored the distributed code to allow for ghosted/unghosted geometries and triangulations. Since PR[#100](https://github.com/gridap/GridapEmbedded.jl/pull/100).
+- Implemented geometrical derivatives. Since PR[#109](https://github.com/gridap/GridapEmbedded.jl/pull/109).
+- Added a proper documentation. Since PR[#109](https://github.com/gridap/GridapEmbedded.jl/pull/109).
 
 ### Changed
 

Project.toml

@@ -1,14 +1,31 @@
+authors = ["Francesc Verdugo <[email protected]>", "Eric Neiva <[email protected]>", "Pere Antoni Martorell <[email protected]>", "Santiago Badia <[email protected]>"]
 name = "GridapEmbedded"
 uuid = "8838a6a3-0006-4405-b874-385995508d5d"
-authors = ["Francesc Verdugo <[email protected]>", "Eric Neiva <[email protected]>", "Pere Antoni Martorell <[email protected]>", "Santiago Badia <[email protected]>"]
-version = "0.9.5"
+version = "0.9.6"
+
+[compat]
+AbstractTrees = "0.3.3, 0.4"
+Algoim = "0.2.2"
+Combinatorics = "1"
+CxxWrap = "0.16"
+FillArrays = "0.10, 0.11, 0.12, 0.13, 1"
+FiniteDiff = "2.27.0"
+ForwardDiff = "0.10.38, 1"
+Graphs = "1.12.0"
+Gridap = "0.18.12"
+GridapDistributed = "0.3, 0.4"
+MPI = "0.20"
+MiniQhull = "0.1.0, 0.2, 0.3, 0.4"
+PartitionedArrays = "0.3.4"
+julia = "1.3"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 Algoim = "0eb9048c-21de-4c7a-bfac-056de1940b74"
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 CxxWrap = "1f15a43c-97ca-5a2a-ae31-89f07a497df4"
 FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
+ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 Gridap = "56d4f2e9-7ea1-5844-9cf6-b9c51ca7ce8e"
 GridapDistributed = "f9701e48-63b3-45aa-9a63-9bc6c271f355"
@@ -20,22 +37,10 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 algoimWrapper_jll = "3c43aa7b-5398-51f3-8d75-8f051e6faa4d"
 
-[compat]
-AbstractTrees = "0.3.3, 0.4"
-Algoim = "0.2.2"
-Combinatorics = "1"
-CxxWrap = "0.16"
-FillArrays = "0.10, 0.11, 0.12, 0.13, 1"
-Graphs = "1.12.0"
-Gridap = "0.17, 0.18"
-GridapDistributed = "0.3, 0.4"
-MPI = "0.20"
-MiniQhull = "0.1.0, 0.2, 0.3, 0.4"
-PartitionedArrays = "0.3.4"
-julia = "1.3"
-
 [extras]
+FiniteDiff = "6a86dc24-6348-571c-b903-95158fe2bd41"
+MPIPreferences = "3da0fdf6-3ccc-4f1b-acd9-58baa6c99267"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Test", "FiniteDiff"]

README.md

@@ -2,6 +2,7 @@
 
 Embedded finite element methods, level set surface descriptions and constructive solid geometry.
 
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://gridap.github.io/GridapEmbedded.jl/stable)
 [![Build Status](https://github.com/gridap/GridapEmbedded.jl/workflows/CI/badge.svg?branch=master)](https://github.com/gridap/GridapEmbedded.jl/actions?query=workflow%3ACI)
 [![Codecov](https://codecov.io/gh/gridap/GridapEmbedded.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/gridap/GridapEmbedded.jl)
 
@@ -40,4 +41,3 @@ julia> BimaterialLinElastCutFEM.main(n=4,outputfile="results3")
 ```
 
 <img src="https://raw.githubusercontent.com/gridap/GridapEmbedded.jl/master/examples/BimaterialLinElastCutFEM/BimaterialLinElastCutFEM_solution.png" width="400">
-

docs/Project.toml

@@ -1,2 +1,3 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GridapEmbedded = "8838a6a3-0006-4405-b874-385995508d5d"

docs/make.jl

@@ -1,14 +1,25 @@
 using Documenter, GridapEmbedded
 
+pages = [
+    "Home" => "index.md",
+    "Constructive Solid Geometry (CSG)" => "CSG.md",
+    "Embedded Interfaces" => "Interfaces.md",
+    "Level Set Cutters" => "LevelSetCutters.md",
+    "Aggregated FEM" => "AggregatedFEM.md",
+    "Moment-Fitted Quadratures" => "MomentFittedQuadratures.md",
+    "Geometrical Derivatives" => "GeometricalDerivatives.md",
+    "Distributed computing" => "Distributed.md",
+]
+
 makedocs(;
-    modules=[GridapEmbedded],
-    format=Documenter.HTML(),
-    pages=[
-        "Home" => "index.md",
-    ],
-    repo="https://github.com/gridap/GridapEmbedded.jl/blob/{commit}{path}#L{line}",
-    sitename="GridapEmbedded.jl",
-    authors="Francesc Verdugo <[email protected]>, Eric Neiva <[email protected]> and Santiago Badia <[email protected]>",
+    modules = [GridapEmbedded],
+    format = Documenter.HTML(
+        size_threshold=nothing
+    ),
+    sitename = "GridapEmbedded.jl",
+    authors = "Francesc Verdugo <[email protected]>, Eric Neiva <[email protected]> and Santiago Badia <[email protected]>",
+    pages = pages,
+    warnonly = false,
 )
 
 deploydocs(;

docs/src/AggregatedFEM.md

@@ -0,0 +1,16 @@
+
+# Aggregated FEM
+
+```@meta
+CurrentModule = GridapEmbedded.AgFEM
+```
+
+```@autodocs
+Modules = [AgFEM,]
+Order   = [:type, :constant, :macro, :function]
+Pages   = [
+  "/AgFEM.jl", 
+  "/AgFEMSpaces.jl",
+  "CellAggregation.jl" 
+]
+```

docs/src/CSG.md

@@ -0,0 +1,15 @@
+
+# Constructive Solid Geometry (CSG)
+
+```@meta
+CurrentModule = GridapEmbedded.CSG
+```
+
+```@autodocs
+Modules = [CSG,]
+Order   = [:type, :constant, :macro, :function]
+Pages   = [
+  "/Nodes.jl", 
+  "/Geometries.jl", 
+]
+```

docs/src/Distributed.md

@@ -0,0 +1,23 @@
+
+# Distributed computing
+
+```@meta
+CurrentModule = GridapEmbedded.Distributed
+```
+
+We support distributed computing through [GridapDistributed.jl](https://github.com/gridap/GridapDistributed.jl). As per usual, we design our libraries so that the high-level API is unchanged when using distributed computing. This means that for most users, the changes to your driver will be minimal.
+
+The following features are currently supported:
+
+- Level-Set Cutters
+- STL Cutters
+
+The folowing features are not yet supported:
+
+- Aggregated FEM
+- Moment-Fitted Quadratures
+
+```@autodocs
+Modules = [Distributed,]
+Order   = [:type, :constant, :macro, :function]
+```

docs/src/GeometricalDerivatives.md

@@ -0,0 +1,33 @@
+# Geometrical Derivatives
+
+```@meta
+CurrentModule = GridapEmbedded
+```
+
+The geometrical differentiation capabilities are based on the following work:
+
+!!! note "Reference"
+    "Level-set topology optimisation with unfitted finite elements and automatic shape differentiation",
+    by Z. J. Wegert, J. Manyer, C. Mallon, S. Badia, V. J. Challis (2025)
+
+To see examples of usage, please refer to the tests in `test/LevelSetCuttersTests/GeometricalDifferentiationTests.jl`.
+
+## Discretize then differentiate
+
+```@autodocs
+Modules = [GridapEmbedded.Interfaces]
+Order   = [:type, :constant, :macro, :function]
+Pages   = [
+  "/CutFaceBoundaryTriangulations.jl", 
+]
+```
+
+## Autodiff
+
+```@autodocs
+Modules = [GridapEmbedded.LevelSetCutters]
+Order   = [:type, :constant, :macro, :function]
+Pages   = [
+  "/DifferentiableTriangulations.jl", 
+]
+```

docs/src/Interfaces.md

@@ -0,0 +1,87 @@
+
+# Embedded Interfaces
+
+```@meta
+CurrentModule = GridapEmbedded.Interfaces
+```
+
+## Domain Nomenclature
+
+Throughout this documentation, many methods accept arguments that select different parts of the cut domain. We split the domain into the following parts:
+
+**The background mesh entities** (cells, facets, nodes) are classified as `IN`, `OUT` or `CUT`. The `IN` and `OUT` background cells are uncut, i.e completely inside or outside the geometry, respectively. These states are internally defined as constants:
+
+```julia
+  const IN = -1
+  const OUT = 1
+  const CUT = 0
+```
+
+**The `CUT` background cells** are cut by the embedded boundary, and split into subcells/subfacets. The subcells/subfacets are classified as `IN` or `OUT` depending on whether they are inside or outside the geometry. `CUT_IN` and `CUT_OUT` subentities can be accessed using the `CutInOrOut` objects:
+
+```julia
+  struct CutInOrOut
+    in_or_out::Int
+  end
+  const CUT_IN = CutInOrOut(IN)
+  const CUT_OUT = CutInOrOut(OUT)
+```
+
+For FEM, we generally want to get sets of uncut and cut cells together, for a given state `IN/OUT`. These are referred as `PHYSICAL` parts of the domain. Moreover, FE spaces are generally defined over the background mesh and need to span both `IN/OUT` and `CUT` background cells. These are referred as `ACTIVE` parts of the domain. You can extract the `PHYSICAL` and `ACTIVE` parts of the domain using the following constants:
+
+```julia
+const PHYSICAL_IN = (CUT_IN,IN)
+const PHYSICAL_OUT = (CUT_OUT,OUT)
+const PHYSICAL = PHYSICAL_IN
+```
+
+```julia
+struct ActiveInOrOut
+  in_or_out::Int
+end
+const ACTIVE_IN = ActiveInOrOut(IN)
+const ACTIVE_OUT = ActiveInOrOut(OUT)
+const ACTIVE = ACTIVE_IN
+```
+
+## Cutters
+
+Cutters are used to cut the background mesh according to a provided geometry.
+
+```@autodocs
+Modules = [Interfaces,]
+Order   = [:type, :constant, :macro, :function]
+Pages   = [
+  "/Cutters.jl", 
+]
+```
+
+We provide several types of cutters, including:
+
+- **Level-Set Cutters**: Cutters for Level-Set and function-defined geometries. See [Level-Set Cutters](@ref).
+- **STL Cutters**: Cutters for STL based geometries. Provided by [STLCutters.jl](https://github.com/gridap/STLCutters.jl).
+
+## Embedded Discretizations
+
+After cutting the background mesh, you will be returned an `EmbeddedDiscretization` object. These contain all the information you need to generate the integration meshes for embedded methods.
+
+```@docs
+AbstractEmbeddedDiscretization
+EmbeddedDiscretization
+EmbeddedFacetDiscretization
+```
+
+## Embedded Triangulations
+
+From `EmbeddedDiscretization` objects, you can extract all the triangulations you need to perform integration for embedded methods. We currently provide the following methods:
+
+```@docs
+Gridap.Geometry.Triangulation(::EmbeddedDiscretization,::Any)
+EmbeddedBoundary(::EmbeddedDiscretization)
+GhostSkeleton(::EmbeddedDiscretization)
+Gridap.Geometry.BoundaryTriangulation(::EmbeddedFacetDiscretization,::Any)
+Gridap.Geometry.SkeletonTriangulation(::EmbeddedFacetDiscretization,::Any)
+SubCellTriangulation
+SubFacetTriangulation
+SubFacetBoundaryTriangulation
+```

docs/src/LevelSetCutters.md

@@ -0,0 +1,16 @@
+
+# Level-Set Cutters
+
+```@meta
+CurrentModule = GridapEmbedded.LevelSetCutters
+```
+
+```@autodocs
+Modules = [LevelSetCutters,]
+Order   = [:type, :constant, :macro, :function]
+Pages   = [
+  "/AnalyticalGeometries.jl",
+  "/DiscreteGeometries.jl",
+  "LevelSetCutters.jl", 
+]
+```

docs/src/MomentFittedQuadratures.md

@@ -0,0 +1,11 @@
+
+# Moment-Fitted Quadratures
+
+```@meta
+CurrentModule = GridapEmbedded.MomentFittedQuadratures
+```
+
+```@autodocs
+Modules = [MomentFittedQuadratures,]
+Order   = [:type, :constant, :macro, :function]
+```

docs/src/index.md

@@ -1,8 +1,19 @@
 # GridapEmbedded.jl
 
-```@index
-```
+## Introduction
+
+GridapEmbedded.jl is a package for the simulation of PDEs on embedded domains within the Gridap.jl ecosystem. Please refer to the [Gridap.jl documentation](https://gridap.github.io/Gridap.jl/stable/) for information on the core capabilities of the Gridap.jl library.
+
+## Manual
 
-```@autodocs
-Modules = [GridapEmbedded]
+```@contents
+Pages = [
+  "CSG.md",
+  "Interfaces.md",
+  "LevelSetCutters.md",
+  "AggregatedFEM.md",
+  "MomentFittedQuadratures.md",
+  "GeometricalDerivatives.md",
+  "Distributed.md",
+]
 ```