gridap · JordiManyer · Aug 30, 2024 · Aug 30, 2024 · Sep 2, 2024 · Sep 6, 2024
diff --git a/.gitignore b/.gitignore
@@ -2,13 +2,20 @@
 *.jl.cov
 *.jl.mem
 .DS_Store
-/Manifest.toml
-/LocalPreferences.toml
+
+Manifest.toml
+LocalPreferences.toml
+
 /dev/
 /docs/build/
 /docs/site/
-/docs/Manifest.toml
+
 /tmp/
+
 *.vtu
 *.pvtu
 *.pvd
+
+CLAUDE.md
+AGENTS.md
+
diff --git a/Project.toml b/Project.toml
@@ -24,7 +24,7 @@ ForwardDiff = "0.10, 1"
 Gridap = "0.20.6"
 LinearAlgebra = "1"
 MPI = "0.16, 0.17, 0.18, 0.19, 0.20"
-PartitionedArrays = "0.3.3"
+PartitionedArrays = "0.5"
 SparseArrays = "1.3"
 SparseMatricesCSR = "0.6.6"
 WriteVTK = "1.12.0"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,3 +1,4 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Gridap = "56d4f2e9-7ea1-5844-9cf6-b9c51ca7ce8e"
 GridapDistributed = "f9701e48-63b3-45aa-9a63-9bc6c271f355"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,17 +1,15 @@
-using Documenter, GridapDistributed
+using Documenter, GridapDistributed, Gridap
 
 pages = [
-  "Home" => "index.md",
-  "Getting Started" => "getting-started.md",
-  "GridapDistributed" => "GridapDistributed.md",
-  "Algebra" => "Algebra.md",
-  "CellData" => "CellData.md",
-  "FESpaces" => "FESpaces.md",
-  "Geometry" => "Geometry.md",
-  "MultiField" => "MultiField.md",
-  "Visualization" => "Visualization.md",
-  "Adaptivity" => "Adaptivity.md",
- ]
+  "Home"          => "index.md",
+  "Backends"      => "backends.md",
+  "Algebra"       => "algebra.md",
+  "Geometry"      => "geometry.md",
+  "FESpaces"      => "fespaces.md",
+  "Assembly"      => "assembly.md",
+  "Adaptivity"    => "adaptivity.md",
+  "Visualization" => "visualization.md",
+]
 
 makedocs(;
     modules=[GridapDistributed],
@@ -20,7 +18,7 @@ makedocs(;
     repo="https://github.com/gridap/GridapDistributed.jl/blob/{commit}{path}#L{line}",
     sitename="GridapDistributed.jl",
     authors="S. Badia <santiago.badia@monash.edu>, A. F. Martin <alberto.f.martin@anu.edu.au>, F. Verdugo <fverdugo@cimne.upc.edu>",
-    # warnonly=true, # for debugging
+    warnonly=true,
 )
 
 deploydocs(;

diff --git a/docs/src/Adaptivity.md b/docs/src/Adaptivity.md
diff --git a/docs/src/Algebra.md b/docs/src/Algebra.md
diff --git a/docs/src/CellData.md b/docs/src/CellData.md
diff --git a/docs/src/FESpaces.md b/docs/src/FESpaces.md
diff --git a/docs/src/Geometry.md b/docs/src/Geometry.md
diff --git a/docs/src/GridapDistributed.md b/docs/src/GridapDistributed.md
diff --git a/docs/src/MultiField.md b/docs/src/MultiField.md
diff --git a/docs/src/Visualization.md b/docs/src/Visualization.md
diff --git a/docs/src/adaptivity.md b/docs/src/adaptivity.md
@@ -0,0 +1,91 @@
+# [Adaptivity](@id adaptivity)
+
+`GridapDistributed.jl` provides an interface for the adaptive mesh refinement (AMR)
+abstractions defined in `Gridap.jl`. The framework works out of the box for Gridap's
+built-in refinement routines. For scalable AMR on unstructured meshes with full MPI
+performance, see [`GridapP4est.jl`](https://github.com/gridap/GridapP4est.jl), which
+integrates the p4est library with `GridapDistributed.jl`.
+
+## Adapted discrete models
+
+`DistributedAdaptedDiscreteModel` represents a distributed mesh obtained by refining a
+parent mesh. It wraps both the fine (child) mesh, the coarse (parent) mesh, and a
+distributed array of `AdaptivityGlue` objects that record the parent-child cell
+relationship.
+
+### Uniform Cartesian refinement
+
+```julia
+using Gridap, GridapDistributed, PartitionedArrays
+
+function main(distribute)
+  ranks  = distribute(LinearIndices((4,)))
+  coarse = CartesianDiscreteModel(ranks, (2,2), (0,1,0,1), (4,4))
+
+  # Refine uniformly by a factor of 2 in every direction
+  fine = refine(coarse, 2)   # returns a DistributedAdaptedDiscreteModel
+
+  parent     = get_parent(fine)
+  glue_array = get_adaptivity_glue(fine)
+
+  # The fine mesh is used like any other DistributedDiscreteModel
+  reffe = ReferenceFE(lagrangian, Float64, 1)
+  V     = TestFESpace(fine, reffe)
+  uh    = interpolate(x -> sum(x), V)
+end
+
+with_debug(main)
+```
+
+`refine(model, r)` accepts an integer or a tuple refinement factor; `refine(model, 2)`
+halves the cell size in every direction.
+
+## Sub-communicators
+
+AMR workflows sometimes involve different sets of ranks at different stages (e.g. a coarse
+mesh on 2 ranks that is refined onto 8). Use `generate_subparts` to carve out a
+sub-communicator of `n` ranks from the full set:
+
+```julia
+fine_ranks   = distribute(LinearIndices((8,)))
+coarse_ranks = generate_subparts(fine_ranks, 2)  # ranks 1–2 only
+
+if i_am_in(coarse_ranks)
+  # only executed on ranks 1 and 2
+end
+```
+
+Ranks outside the sub-communicator receive an inert placeholder and skip the guarded block.
+
+## API
+
+### Adapted models
+
+```@docs
+GridapDistributed.DistributedAdaptedDiscreteModel
+```
+
+### Sub-communicators
+
+```@docs
+GridapDistributed.generate_subparts
+GridapDistributed.i_am_in
+```
+
+### Refinement internals
+
+```@docs
+GridapDistributed.refine_local_models
+GridapDistributed.refine_cell_gids
+```
+
+### Redistribution
+
+```@docs
+GridapDistributed.RedistributeGlue
+GridapDistributed.redistribute
+GridapDistributed.redistribute_cartesian
+GridapDistributed.redistribute_array_by_cells
+GridapDistributed.redistribution_local_indices
+GridapDistributed.redistribute_indices
+```
diff --git a/docs/src/algebra.md b/docs/src/algebra.md
@@ -0,0 +1,75 @@
+# [Algebra](@id algebra)
+
+`GridapDistributed.jl` relies on [`PartitionedArrays.jl`](https://github.com/fverdugo/PartitionedArrays.jl) for all distributed linear algebra. Users interacting with the assembled system — for example, to inspect residuals or feed vectors into a custom solver — will work directly with PartitionedArrays types. This page gives a brief conceptual overview; the [PartitionedArrays documentation](https://fverdugo.github.io/PartitionedArrays.jl/stable/) is the authoritative reference.
+
+## Distributed index ranges: `PRange`
+
+A `PRange` is a distributed range of integers. It is the backbone of every distributed array: it records, for each local index on each rank, its global ID and which rank owns it.
+
+Each rank's slice of a `PRange` is an `AbstractLocalIndices` object that exposes the local index layout:
+
+| Function | Returns |
+|---|---|
+| `local_to_global(idx)` | Global ID for each local index (owned + ghost) |
+| `own_to_global(idx)` | Global IDs of owned (non-ghost) indices |
+| `ghost_to_global(idx)` | Global IDs of ghost indices |
+| `own_to_local(idx)` | Local positions of owned indices |
+| `ghost_to_local(idx)` | Local positions of ghost indices |
+| `local_to_owner(idx)` | Owner rank for each local index |
+
+Access the local indices on each rank via `partition`:
+
+```julia
+map(partition(prange)) do indices
+  lid_to_gid = local_to_global(indices)
+end
+```
+
+`PRanges` will be used as axes for distributed vectors and matrices, and to define the communication pattern for synchronizing ghost values.
+
+## Distributed vectors: `PVector`
+
+A `PVector` is a distributed dense vector. Each rank stores a local segment that includes both **owned** entries (for which this rank is authoritative) and **ghost** entries (copies of entries owned by neighboring ranks).
+
+Two operations synchronize the distributed state:
+
+- `consistent!(x)` — broadcasts owned values to ghost copies on neighboring ranks. Call
+  this after a solve to ensure ghost entries reflect the current solution.
+- `assemble!(x)` — accumulates ghost contributions into the owning rank's entry. Used
+  during assembly to collect off-rank contributions.
+
+Both return a task; wait for completion with `|> wait` or `fetch`.
+
+A normal workflow would be:
+
+```julia
+  map(partition(x)) do x
+    # Do something locally with the values of x
+    # NO communication is allowed here!
+  end
+  consistent!(x) |> wait # Synchronize ghost values after local updates
+```
+
+## Distributed sparse matrices: `PSparseMatrix`
+
+A `PSparseMatrix` is a distributed sparse matrix stored in compressed form. Each rank owns a block of rows. Non-zero entries in off-rank columns are stored locally and communicated as needed during matrix-vector products (`mul!`).
+
+## GridapDistributed additions
+
+`GridapDistributed.jl` adds a small set of utilities on top of PartitionedArrays to support the FE assembly pipeline.
+
+### API
+
+```@docs
+GridapDistributed.permuted_variable_partition
+GridapDistributed.unpermute
+GridapDistributed.locally_repartition
+GridapDistributed.filter_and_replace_ghost
+```
+
+### Block arrays
+
+```@docs
+GridapDistributed.BlockPRange
+GridapDistributed.BlockPArray
+```