Moment based reffes

.github/workflows/Downgrade.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.9' # Needs to be lowest supported version
+          - '1.10' # Needs to be lowest supported version
         os:
           - ubuntu-latest
         arch:

.github/workflows/ci.yml

@@ -15,7 +15,6 @@ jobs:
       fail-fast: false
       matrix: # Main tests for linux
         version:
-          - '1.9'
           - '1.10'
           - '1.11'
         os:

NEWS.md

@@ -5,6 +5,73 @@ 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).
 
+## Moment-based changes
+
+### Added
+
+- Documentation and refactoring of `Gridap.Polynomials`. Since PR[#1072](https://github.com/gridap/Gridap.jl/pull/#1072).
+- Two new families of polynomial bases in addition to `Monomial`, `Legendre` (former `Jacobi`) and `ModalC0`: `Chebyshev` and `Bernstein`
+- `MonomialBasis` and `Q[Curl]GradMonomialBasis` have been generalized to `Legendre`, `Chebyshev` and `Bernstein` using the new `CartProdPolyBasis` and `CompWiseTensorPolyBasis` respectively.
+- `PCurlGradMonomialBasis` has been generalized to `Legendre` and `Chebyshev` using the new `RaviartThomasPolyBasis`.
+- New aliases and high level constructor for `CartProdPolyBasis` (former MonomialBasis): `MonomialBasis`, `LegendreBasis`, `ChebyshevBasis` and `BernsteinBasis`.
+- New high level factory `FEEC_poly_basis` for the bases for the scalar Lagrange, Nedelec, Raviart-Thomas, BDM spaces, and all other spaces of the Periodic Table of the Finite Elements. (for Serendipity, only scalar is supported). For example:
+  - Nedelec on simplex `FEEC_poly_basis(Val(D),Float64,order+1,  1,:P⁻)`
+  - Nedelec on n-cubes `FEEC_poly_basis(Val(D),Float64,order+1,  1,:Q⁻)`
+  - Raviart on simplex `FEEC_poly_basis(Val(D),Float64,order+1,D-1,:P⁻; rotate_90=(D==2))`
+  - Raviart on n-cubes `FEEC_poly_basis(Val(D),Float64,order+1,D-1,:Q⁻; rotate_90=(D==2))`
+  - BDM     on simplex `FEEC_poly_basis(Val(D),Float64,order+1,D-1,:P ; rotate_90=(D==2))`
+- Added `BernsteinBasisOnSimplex` that implements Bernstein polynomials in barycentric coordinates, since PR[#1104](https://github.com/gridap/Gridap.jl/pull/#1104).
+- More documentation of `Gridap.ReferenceFEs`. Since PR[#1109](https://github.com/gridap/Gridap.jl/pull/#1109).
+
+- Some refactoring of `Gridap.TensorValues` to simplify maintenance and new implementations. Since PR[#1115](https://github.com/gridap/Gridap.jl/pull/#1115).
+  - Added `SkewSymTensorValue`: a new `<:MultiValue` 2nd order tensor type such that `transpose(s)==-s`.
+  - `congruent_prod`: new operation for 2nd order tensors: `a,b -> bᵀ⋅a⋅b` preserving symmetry of `a`.
+  - `component_basis` and `representatives_of_componentbasis_dual`: new APIs for `::MultiValue`s yielding bases of the vector space spanned by the independent components of a tensor type (1st method) and its dual space (2nd method).
+
+- Refactoring of moment-based ReferenceFEs, those using face-integral linear forms for DoFs, including `RaviartThomas`, `Nedelec`, `BDM` and `CrouzeixRaviart`. Since PR[#1048](https://github.com/gridap/Gridap.jl/pull/#1048).
+  - The mid-level `MomentBasedRefFE` factory function creates moment based refFEs
+  - The low-level `FaceMeasure` implements the numerical integration of a bilinear integrand over the faces of a polytope.
+  - The low-level `MomentBasedDofBasis` implements a discretized basis of moment DoF
+- Implemented moment-based scalar (`H1` conform) elements for scalar elements `lagrangian` and `serendipity` under the names `modal_lagrangian` and `modal_serendipity`. They are the default elements when calling for `k`=0-forms in the generic FEEC reference FE constructor (`P⁻`/`:P`/`:Q⁻` => `lagrangian`, `:S`=> `serendipity`), use the keyword `nodal=true` to opt-in nodal DOF based counterpart. Since PR[#1173](https://github.com/gridap/Gridap.jl/pull/1173).
+- Unified the high-level constructors of ReferenceFEs
+- New high level `ReferenceFE`s constructor using Arnold et al FEEC notations (Periodic Table of the Finite Elements): `ReferenceFE(F::Symbol, r, k, [, T::Type]; kwargs...)` with `F` the element family, `r` polynomial order and `k` the form order.
+- Added `poly_type`, `mom_poly_type` and `change_dof` keyword arguments to many low and high-level reference FE constructors, they enable to control the polynomial (pre-)bases choice for the approximation space and moment test-spaces of the reference elements (See `ReferenceFEs` doc. page). Since PR[#1173](https://github.com/gridap/Gridap.jl/pull/1173).
+- Documented the implemented ReferenceFEs with available order and other information in the `ReferenceFEs` section of the doc.
+- Implemented the Nedelec reference elements of the second kind `nedelec2`.
+- API for Geometric decomposition of polynomial bases, implemented for simplices and n-cubes. Since PR[#1144](https://github.com/gridap/Gridap.jl/pull/1144).
+  The geometric decomposition API consist in the methods `has_geometric_decomposition`, `get_face_own_funs` and `get_facet_flux_sign_flip`.
+
+### Fixed
+
+- Fixed evaluation of `LinearCombinationDofVector` on vector of `<:Field`s (only impacts ModalC0 FEs and future moment based reffes)., since PR[#1105](https://github.com/gridap/Gridap.jl/pull/#1105).
+- Minor `MuliValue` bugfixes for `isless` and `<=` with scalars.
+
+### Changed
+
+- Existing Jacobi polynomial bases/spaces were renamed to Legendre (which they were).
+- `Monomial` is now subtype of the new abstract type`Polynomial <: Field`
+- `MonomialBasis` is now an alias for `CartProdPolyBasis{...,Monomial}`
+- All polynomial bases are now subtypes of the new abstract type `PolynomialBasis <: AbstractVector{<:Polynomial}`
+- `get_order`, now always returns the maximum order of the basis, the correspondence with `ReferenceFEs` constructors is summarized in the documentation of the module.
+- `NedelecPreBasisOnSimplex` is renamed `NedelecPolyBasisOnSimplex`
+- `JacobiPolynomial` is renamed `Legendre` and subtypes `Polynomial`
+- `JacobiPolynomialBasis` is renamed `LegendreBasis`
+- `ModalC0BasisFunction` is renamed `ModalC0` and subtypes `Polynomial`
+- On simplices, the default polynomial bases of BDM, Nédélec and Raviart-Thomas RefFEs have changed for barycentric polynomial bases which lead to better conditioned systems for higher order.
+- Similarly, on n-cubes, the default polynomial bases of BDM, Nédélec and Raviart-Thomas RefFEs have changed for Legendre (tensor-product) polynomial bases instead of Monomials.
+- Changed `Base.==` for `ReferenceFE`s, and implemented it for `LinearCombinationFieldVector` and `LinearCombinationDofVector`. The implementation now uses AutoHashEquals.jl, so RefFEs are now only equal if they have the same prebasis, shapefun and dofs.
+- Monomial (pre)bases have been replaced with Bernstein / Barycentric bases for non-scalar finite elements on simplices.
+
+### Deprecated
+
+- `num_terms(f::AbstractVector{<:Field})` in favor of `length(f::PolynomialBasis)`
+- `MonomialBasis{D}(args...)` in favor of `MonomialBasis(Val(D), args...)`
+- `[P/Q][Curl]GradMonomialBasis{D}(args...)` in favor of `FEEC_poly_basis`
+- `NedelecPreBasisOnSimplex{D}(order)` in favor of `NedelecPolyBasisOnSimplex(Val(D), Float64, order)`
+- `JacobiPolynomialBasis{D}(args...)` in favor of `LegendreBasis(Val(D), args...)`
+
+### Removed
+
 ## [0.19.5] - 2025-09-19
 
 ### Added

Project.toml

@@ -5,6 +5,7 @@ version = "0.19.5"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+AutoHashEquals = "15f4f7f2-30c1-5605-9d31-71845cf9641f"
 BSON = "fbb218c0-5317-5bc6-957e-2ee96dd4b1f0"
 BlockArrays = "8e7c35d0-a365-5155-bbbb-fb81a777f24e"
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
@@ -40,6 +41,7 @@ TikzPicturesExt = "TikzPictures"
 [compat]
 AbstractTrees = "0.3.3, 0.4"
 Aqua = "0.8"
+AutoHashEquals = "2.2.0"
 BSON = "0.3.4"
 BlockArrays = "1"
 Combinatorics = "1"
@@ -66,7 +68,7 @@ Statistics = "1"
 Test = "1"
 TikzPictures = "3"
 WriteVTK = "1.21.1"
-julia = "1.9"
+julia = "1.10"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Gridap = "56d4f2e9-7ea1-5844-9cf6-b9c51ca7ce8e"
+Kroki = "b3565e16-c1f2-4fe9-b4ab-221c88942068"
+TikzPictures = "37f6aa50-8035-52d0-81c2-5a1d08754b2d"
 
 [compat]
 Documenter = "1.0"

docs/generate_diagrams.jl

@@ -0,0 +1,102 @@
+using Kroki
+
+macro export_kroki(name, str)
+  return quote
+    write("src/assets/"*string($name)*".svg", render($str, "svg"))
+  end
+end
+
+# Plantuml uml diagrams syntax: https://plantuml.com/class-diagram#49b7759afaffc066
+
+@export_kroki :poly_1 plantuml"""
+  @startuml
+  skinparam groupInheritance 2
+  hide empty members
+
+  together {
+    abstract Field
+    abstract Polynomial {
+      +isHierarchical
+    }
+  }
+  Field <|-left- Polynomial
+
+  together {
+    struct Monomial
+    struct Legendre
+    struct Chebyshev
+    struct ModalC0
+    struct Bernstein
+  }
+
+  Polynomial <|.. Monomial
+  Polynomial <|.. Legendre
+  Polynomial <|.. Chebyshev
+  Polynomial <|.. ModalC0
+  Polynomial <|.. Bernstein
+
+  @enduml
+  """
+
+@export_kroki :poly_2 plantuml"""
+  @startuml
+  skinparam groupInheritance 2
+  hide empty members
+
+  together {
+    abstract "AbstractArray{<:Polynomial}" as a1
+    abstract PolynomialBasis {
+      +get_order
+      +return_type
+    }
+  }
+  a1 <|-left- PolynomialBasis
+
+  together {
+    struct CartProdPolyBasis {
+      +get_exponents
+      +get_orders
+    }
+    struct CompWiseTensorPolyBasis
+    struct RaviartThomasPolyBasis
+    struct NedelecPolyBasisOnSimplex
+    struct BernsteinBasisOnSimplex {
+      +get_orders
+    }
+    struct ModalC0Basis {
+      +get_orders
+    }
+  }
+
+  struct BarycentricPΛBasis {
+    +print_indices
+  }
+  struct BarycentricPmΛBasis {
+    +print_indices
+  }
+
+  PolynomialBasis <|.. CartProdPolyBasis
+  PolynomialBasis <|.. CompWiseTensorPolyBasis
+  PolynomialBasis <|.. RaviartThomasPolyBasis
+  PolynomialBasis <|.. NedelecPolyBasisOnSimplex
+  PolynomialBasis <|.. BernsteinBasisOnSimplex
+  PolynomialBasis <|.. ModalC0Basis
+  PolynomialBasis <|.. BarycentricPmΛBasis
+  PolynomialBasis <|.. BarycentricPΛBasis
+
+  object "(<:Polynomial)Basis" as m1
+  object "FEEC_poly_basis" as m2
+
+  CartProdPolyBasis <-- m1
+  BarycentricPmΛBasis o-- BernsteinBasisOnSimplex
+  BarycentricPΛBasis o-- BernsteinBasisOnSimplex
+  CartProdPolyBasis <-- m2
+  CompWiseTensorPolyBasis <-- m2
+  RaviartThomasPolyBasis <-- m2
+  NedelecPolyBasisOnSimplex <-- m2
+  BarycentricPmΛBasis <-- m2
+  BarycentricPΛBasis <-- m2
+
+  @enduml
+  """
+

docs/generate_tikz.jl

@@ -0,0 +1,28 @@
+
+using Gridap
+using TikzPictures
+
+using Gridap.ReferenceFEs, Gridap.Adaptivity
+
+function export_tikz_poly(name, p, d, label_offset)
+  options = "background rectangle/.style={draw=white,fill=white,rounded corners=1ex}, show background rectangle, color=black, scale=2"
+  preamble = "\\usetikzlibrary {backgrounds}"
+  tp = TikzPicture(p;options,preamble,label_dim=d,label_offset)
+  TikzPictures.save(SVG(joinpath("src/assets/polytopes/",name)), tp)
+end
+
+export_tikz_poly("SEGMENT_0", Polygon([Point(0.0,0.0),Point(1.0,0.0)]), 0, Point(0.0,0.1))
+
+for d in 0:1
+  offset = iszero(d) ? 0.1 : 0.0
+  export_tikz_poly("QUAD_$d", QUAD, d, offset)
+  export_tikz_poly("TRI_$d" , TRI, d, offset)
+end
+
+for d in 0:2
+  offset = iszero(d) ? 0.1 : 0.0
+  export_tikz_poly("HEX_$d", HEX, d, offset)
+  export_tikz_poly("TET_$d" , TET, d, offset)
+  export_tikz_poly("PYRAMID_$d", PYRAMID, d, offset)
+  export_tikz_poly("WEDGE_$d", WEDGE, d, offset)
+end

docs/make.jl

@@ -1,41 +1,51 @@
 
 using Documenter
 using Gridap
+using TikzPictures
 
 pages = [
   "Home" => "index.md",
   "Getting Started" => "getting-started.md",
-  "Gridap" => "Gridap.md",
-  "Gridap.Helpers" => "Helpers.md",
-  "Gridap.Io" => "Io.md",
-  "Gridap.Algebra" => "Algebra.md",
-  "Gridap.Arrays" => "Arrays.md",
-  "Gridap.TensorValues" => "TensorValues.md",
-  "Gridap.Fields" => "Fields.md",
-  "Gridap.Polynomials" => "Polynomials.md",
-  "Gridap.ReferenceFEs" => "ReferenceFEs.md",
-  "Gridap.Geometry" => "Geometry.md",
-  "Gridap.CellData" => "CellData.md",
-  "Gridap.Visualization" => "Visualization.md",
-  "Gridap.FESpaces" => "FESpaces.md",
-  "Gridap.MultiField" => "MultiField.md",
-  "Gridap.ODEs" => "ODEs.md",
-  "Gridap.Adaptivity" => "Adaptivity.md",
+  "Gridap at a glance" => "overview.md",
+  "Ecosystem" => "ecosystem.md",
+  "Modules" => [
+    "Helpers" => "modules/Helpers.md",
+    "Io" => "modules/Io.md",
+    "Algebra" => "modules/Algebra.md",
+    "Arrays" => "modules/Arrays.md",
+    "TensorValues" => "modules/TensorValues.md",
+    "Fields" => "modules/Fields.md",
+    "Polynomials" => "modules/Polynomials.md",
+    "ReferenceFEs" => "modules/ReferenceFEs.md",
+    "Geometry" => "modules/Geometry.md",
+    "CellData" => "modules/CellData.md",
+    "Visualization" => "modules/Visualization.md",
+    "FESpaces" => "modules/FESpaces.md",
+    "MultiField" => "modules/MultiField.md",
+    "ODEs" => "modules/ODEs.md",
+    "Adaptivity" => "modules/Adaptivity.md",
+  ],
+  "Extensions" => [
+    "TikzPictures" => "extensions/TikzPictures.md",
+  ],
   "Developper notes" => Any[
     "dev-notes/block-assemblers.md",
+    "dev-notes/pullbacks.md",
+    "dev-notes/bernstein.md",
     "dev-notes/autodiff.md",
   ],
 ]
 
 makedocs(
   sitename = "Gridap.jl",
   format = Documenter.HTML(
-    size_threshold=nothing
+    size_threshold=nothing,
+    size_threshold_warn=300 * 2^10 # 300KiB
   ),
   modules = [Gridap],
   pages = pages,
   doctest = false,
-  warnonly = [:cross_references,:missing_docs],
+  warnonly = [:missing_docs,:cross_references], # ,:cross_references
   checkdocs = :exports,
 )