From 9c8445655231c46b36d6f5b7a2bc923543d3bbb0 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 1 Dec 2024 21:58:42 +0000 Subject: [PATCH] build based on ee460f5 --- dev/.documenter-siteinfo.json | 2 +- dev/Adaptivity/index.html | 6 +++--- dev/Algebra/index.html | 4 ++-- dev/CellData/index.html | 2 +- dev/FESpaces/index.html | 2 +- dev/Geometry/index.html | 2 +- dev/GridapDistributed/index.html | 2 +- dev/MultiField/index.html | 2 +- dev/Visualization/index.html | 2 +- dev/getting-started/index.html | 2 +- dev/index.html | 2 +- 11 files changed, 14 insertions(+), 14 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index b59063c..e912e7e 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.8.5","generation_timestamp":"2024-11-15T05:09:52","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.8.5","generation_timestamp":"2024-12-01T21:58:38","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/Adaptivity/index.html b/dev/Adaptivity/index.html index c7f4eda..2466475 100644 --- a/dev/Adaptivity/index.html +++ b/dev/Adaptivity/index.html @@ -1,6 +1,6 @@ -Adaptivity · GridapDistributed.jl

Adaptivity

GridapDistributed.RedistributeGlue — Type

RedistributeGlue

Glue linking two distributions of the same mesh.

  • new_parts: Array with the new part IDs (and comms)
  • old_parts: Array with the old part IDs (and comms)
  • parts_rcv: Array with the part IDs from which each part receives
  • parts_snd: Array with the part IDs to which each part sends
  • lids_rcv : Local IDs of the entries that are received from each part
  • lids_snd : Local IDs of the entries that are sent to each part
  • old2new : Mapping of local IDs from the old to the new mesh
  • new2old : Mapping of local IDs from the new to the old mesh
source
GridapDistributed.redistribute — Method

Redistributes an DistributedDiscreteModel to optimally rebalance the loads between the processors. Returns the rebalanced model and a RedistributeGlue instance.

source
GridapDistributed.redistribute_cartesian — Method
redistribute_cartesian(old_model,new_ranks,new_parts)
-redistribute_cartesian(old_model,pdesc::DistributedCartesianDescriptor)

Redistributes a DistributedCartesianDiscreteModel to a new set of ranks and parts. Only redistributes into a superset of the old_model ranks (i.e. towards more processors).

source
GridapDistributed.refine_cell_gids — Method
refine_cell_gids(
+Adaptivity · GridapDistributed.jl
Adaptivity
GridapDistributed.RedistributeGlue — Type
RedistributeGlue
Glue linking two distributions of the same mesh.
  • new_parts: Array with the new part IDs (and comms)
  • old_parts: Array with the old part IDs (and comms)
  • parts_rcv: Array with the part IDs from which each part receives
  • parts_snd: Array with the part IDs to which each part sends
  • lids_rcv : Local IDs of the entries that are received from each part
  • lids_snd : Local IDs of the entries that are sent to each part
  • old2new  : Mapping of local IDs from the old to the new mesh
  • new2old  : Mapping of local IDs from the new to the old mesh
source
GridapDistributed.redistribute — Method
Redistributes an DistributedDiscreteModel to optimally    rebalance the loads between the processors.    Returns the rebalanced model and a RedistributeGlue instance. 
source
GridapDistributed.redistribute_cartesian — Method
redistribute_cartesian(old_model,new_ranks,new_parts)
+redistribute_cartesian(old_model,pdesc::DistributedCartesianDescriptor)
Redistributes a DistributedCartesianDiscreteModel to a new set of ranks and parts.   Only redistributes into a superset of the old_model ranks (i.e. towards more processors).
source
GridapDistributed.refine_cell_gids — Method
refine_cell_gids(
   cmodel::DistributedDiscreteModel{Dc},
   fmodels::AbstractArray{<:DiscreteModel{Dc}}
-) where Dc
Given a coarse model and it's local refined models, returns the gids of the fine model. The gids are computed as follows: 
  • First, we create a global numbering for the owned cells by adding an owner-based offset to the local  cell ids (such that cells belonging to the first processor are numbered first). This is  quite standard.
  • The complicated part is making this numeration consistent, i.e communicating gids of the  ghost cells. To do so, each processor selects it's ghost fine cells, and requests their  global ids by sending two keys:
    1. The global id of the coarse parent
    2. The child id of the fine cell
source
GridapDistributed.refine_local_models — Method
refine_local_models(cmodel::DistributedDiscreteModel{Dc},args...;kwargs...) where Dc
Given a coarse model, returns the locally refined models. This is done by 
  • refining the local models serially
  • filtering out the extra fine layers of ghosts
We also return the ids of the owned fine cells.
To find the fine cells we want to keep, we have the following criteria: 
  • Given a fine cell, it is owned iff  A) It's parent cell is owned
  • Given a fine cell, it is a ghost iff not(A) and  B) It has at least one neighbor with a non-ghost parent
Instead of checking A and B, we do the following: 
  • We mark fine owned cells by checking A 
  • If a cell is owned, we set it's fine neighbors as owned or ghost
source

+) where Dc

Given a coarse model and it's local refined models, returns the gids of the fine model. The gids are computed as follows:

  • First, we create a global numbering for the owned cells by adding an owner-based offset to the local cell ids (such that cells belonging to the first processor are numbered first). This is quite standard.
  • The complicated part is making this numeration consistent, i.e communicating gids of the ghost cells. To do so, each processor selects it's ghost fine cells, and requests their global ids by sending two keys:
    1. The global id of the coarse parent
    2. The child id of the fine cell
source
GridapDistributed.refine_local_models — Method
refine_local_models(cmodel::DistributedDiscreteModel{Dc},args...;kwargs...) where Dc

Given a coarse model, returns the locally refined models. This is done by

  • refining the local models serially
  • filtering out the extra fine layers of ghosts

We also return the ids of the owned fine cells.

To find the fine cells we want to keep, we have the following criteria:

  • Given a fine cell, it is owned iff A) It's parent cell is owned
  • Given a fine cell, it is a ghost iff not(A) and B) It has at least one neighbor with a non-ghost parent

Instead of checking A and B, we do the following:

  • We mark fine owned cells by checking A
  • If a cell is owned, we set it's fine neighbors as owned or ghost
source
diff --git a/dev/Algebra/index.html b/dev/Algebra/index.html index 88a8c59..1ad7771 100644 --- a/dev/Algebra/index.html +++ b/dev/Algebra/index.html @@ -1,3 +1,3 @@ -Algebra · GridapDistributed.jl
+Algebra · GridapDistributed.jl
diff --git a/dev/CellData/index.html b/dev/CellData/index.html index e74f71b..53a2507 100644 --- a/dev/CellData/index.html +++ b/dev/CellData/index.html @@ -1,2 +1,2 @@ -CellData · GridapDistributed.jl
+CellData · GridapDistributed.jl
diff --git a/dev/FESpaces/index.html b/dev/FESpaces/index.html index b98fdce..f6ece7d 100644 --- a/dev/FESpaces/index.html +++ b/dev/FESpaces/index.html @@ -3,4 +3,4 @@ model::DistributedDiscreteModel; constraint_type=:global, kwargs... -)

Distributed equivalent to ConstantFESpace(model;kwargs...).

With constraint_type=:global, a single dof is shared by all processors. This creates a global constraint, which is NOT scalable in parallel. Use at your own peril.

With constraint_type=:local, a single dof is owned by each processor and shared with no one else. This space is locally-constant in each processor, and therefore scalable (but not equivalent to its serial counterpart).

source
GridapDistributed.DistributedFEFunctionData — Type
source
GridapDistributed.DistributedSingleFieldFEFunction — Type
source
GridapDistributed.DistributedSingleFieldFESpace — Type
source
GridapDistributed.DistributedSparseMatrixAssembler — Type
source
+)

Distributed equivalent to ConstantFESpace(model;kwargs...).

With constraint_type=:global, a single dof is shared by all processors. This creates a global constraint, which is NOT scalable in parallel. Use at your own peril.

With constraint_type=:local, a single dof is owned by each processor and shared with no one else. This space is locally-constant in each processor, and therefore scalable (but not equivalent to its serial counterpart).

source
GridapDistributed.DistributedFEFunctionData — Type
source
GridapDistributed.DistributedSingleFieldFEFunction — Type
source
GridapDistributed.DistributedSingleFieldFESpace — Type
source
GridapDistributed.DistributedSparseMatrixAssembler — Type
source
diff --git a/dev/Geometry/index.html b/dev/Geometry/index.html index 7074192..8343779 100644 --- a/dev/Geometry/index.html +++ b/dev/Geometry/index.html @@ -1,2 +1,2 @@ -Geometry · GridapDistributed.jl
+Geometry · GridapDistributed.jl
diff --git a/dev/GridapDistributed/index.html b/dev/GridapDistributed/index.html index f4e41ef..4df5c49 100644 --- a/dev/GridapDistributed/index.html +++ b/dev/GridapDistributed/index.html @@ -1,2 +1,2 @@ -GridapDistributed · GridapDistributed.jl
+GridapDistributed · GridapDistributed.jl
diff --git a/dev/MultiField/index.html b/dev/MultiField/index.html index 4572653..5e2c3e2 100644 --- a/dev/MultiField/index.html +++ b/dev/MultiField/index.html @@ -1,2 +1,2 @@ -MultiField · GridapDistributed.jl
+MultiField · GridapDistributed.jl
diff --git a/dev/Visualization/index.html b/dev/Visualization/index.html index 2fa6917..e826ec0 100644 --- a/dev/Visualization/index.html +++ b/dev/Visualization/index.html @@ -1,2 +1,2 @@ -Visualization · GridapDistributed.jl
+Visualization · GridapDistributed.jl
diff --git a/dev/getting-started/index.html b/dev/getting-started/index.html index 26468c3..4293acd 100644 --- a/dev/getting-started/index.html +++ b/dev/getting-started/index.html @@ -1,2 +1,2 @@ -Getting Started · GridapDistributed.jl

Getting Started

Installation requirements

GridapDistributed is tested on Linux, but it should be also possible to use it on Mac OS and Windows since it is written exclusively in Julia and it only depends on registered Julia packages.

Installation

GridapDistributed is a registered package. Thus, the installation should be straight forward using the Julia's package manager Pkg. To this end, open the Julia REPL (i.e., execute the julia binary), type ] to enter package mode, and install GridapDistributed as follows

pkg> add GridapDistributed

You will also need the PartitionedArrays package. 

pkg> add PartitionedArrays

If you want to leverage the satellite packages of GridapDistributed.jl, i.e., GridapPETSc.jl, GridapP4est.jl, and/or GridapGmsh.jl, you have to install them separately as 

pkg> add GridapPETSc
pkg> add GridapGmsh
pkg> add GridapP4est

Please note that these three packages depend on binary builds of the corresponding libraries they wrap (i.e., PETSc, Gmsh, and P4est). By default, they will leverage binary builds available at the Julia package registry. However, one may also use custom installations of these libraries. See the documentation of the corresponding package for more details

For further information about how to install and manage Julia packages, see the Pkg documentation.

Further steps

If you are new to the Gridap ecosystem of packages, we recommend that you first follow the Gridap Tutorials step by step in order to get familiar with the Gridap.jl library. GridapDistributed.jl and Gridap.jl share almost the same high-level API. Therefore, some familiarity with Gridap.jl is highly recommended (if not essential) before starting with GridapDistributed.jl.

If you are already familiarized with Gridap.jl, we recommend you to start straight away with the following tutorial.

+Getting Started · GridapDistributed.jl

Getting Started

Installation requirements

GridapDistributed is tested on Linux, but it should be also possible to use it on Mac OS and Windows since it is written exclusively in Julia and it only depends on registered Julia packages.

Installation

GridapDistributed is a registered package. Thus, the installation should be straight forward using the Julia's package manager Pkg. To this end, open the Julia REPL (i.e., execute the julia binary), type ] to enter package mode, and install GridapDistributed as follows

pkg> add GridapDistributed

You will also need the PartitionedArrays package. 

pkg> add PartitionedArrays

If you want to leverage the satellite packages of GridapDistributed.jl, i.e., GridapPETSc.jl, GridapP4est.jl, and/or GridapGmsh.jl, you have to install them separately as 

pkg> add GridapPETSc
pkg> add GridapGmsh
pkg> add GridapP4est

Please note that these three packages depend on binary builds of the corresponding libraries they wrap (i.e., PETSc, Gmsh, and P4est). By default, they will leverage binary builds available at the Julia package registry. However, one may also use custom installations of these libraries. See the documentation of the corresponding package for more details

For further information about how to install and manage Julia packages, see the Pkg documentation.

Further steps

If you are new to the Gridap ecosystem of packages, we recommend that you first follow the Gridap Tutorials step by step in order to get familiar with the Gridap.jl library. GridapDistributed.jl and Gridap.jl share almost the same high-level API. Therefore, some familiarity with Gridap.jl is highly recommended (if not essential) before starting with GridapDistributed.jl.

If you are already familiarized with Gridap.jl, we recommend you to start straight away with the following tutorial.

diff --git a/dev/index.html b/dev/index.html index 6247664..8cdd6fb 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · GridapDistributed.jl

GridapDistributed.jl

Documentation of the GridapDistributed.jl library.

Note

These documentation pages are under construction.

Introduction

The ever-increasing demand for resolution and accuracy in mathematical models of physical processes governed by systems of Partial Differential Equations (PDEs) can only be addressed using fully-parallel advanced numerical discretization methods and scalable solution methods, thus able to exploit the vast amount of computational resources in state-of-the-art supercomputers. To this end, GridapDistributed.jl is a registered software package which provides fully-parallel distributed memory data structures and associated methods for the Finite Element (FE) numerical solution of PDEs on parallel computers. Thus, it can be run on multi-core CPU desktop computers at small scales, as well as on HPC clusters and supercomputers at medium/large scales. The data structures in GridapDistributed.jl are designed to mirror as far as possible their counterparts in the Gridap.jl Julia software package, while implementing/leveraging most of their abstract interfaces. As a result, sequential Julia scripts written in the high-level Application Programming Interface (API) of Gridap.jl can be used verbatim up to minor adjustments in a parallel distributed memory context using GridapDistributed.jl. This equips end-users with a tool for the development of simulation codes able to solve real-world application problems on massively parallel supercomputers while using a highly expressive, compact syntax, that resembles mathematical notation. This is indeed one of the main advantages of GridapDistributed.jl and a major design goal that we pursue.

In order to scale FE simulations to large core counts, the mesh used to discretize the computational domain on which the PDE is posed must be partitioned (distributed) among the parallel tasks such that each of these only holds a local portion of the global mesh. The same requirement applies to the rest of data structures in the FE simulation pipeline, i.e., FE space, linear system, solvers, data output, etc. The local portion of each task is composed by a set of cells that it owns, i.e., the local cells of the task, and a set of off-processor cells (owned by remote processors) which are in touch with its local cells, i.e., the ghost cells of the task. This overlapped mesh partition is used by GridapDistributed.jl, among others, to exchange data among nearest neighbors, and to glue together global Degrees of Freedom (DoFs) which are sitting on the interface among subdomains. Following this design principle, GridapDistributed.jl provides scalable parallel data structures and associated methods for simple grid handling (in particular, Cartesian-like meshes of arbitrary-dimensional, topologically n-cube domains), FE spaces setup, and distributed linear system assembly. It is in our future plans to provide highly scalable linear and nonlinear solvers tailored for the FE discretization of PDEs (e.g., linear and nonlinear matrix-free geometric multigrid and domain decomposition preconditioners). In the meantime, however, GridapDistributed.jl can be combined with other Julia packages in order to realize the full potential required in real-world applications. These packages and their relation with GridapDistributed.jl are overviewed in the next section.

Building blocks and composability

The figure below depicts the relation among GridapDistributed.jl and other packages in the Julia package ecosystem. The interaction of GridapDistributed.jl and its dependencies is mainly designed with separation of concerns in mind towards high composability and modularity. On the one hand, Gridap.jl provides a rich set of abstract types/interfaces suitable for the FE solution of PDEs. It also provides realizations (implementations) of these abstractions tailored to serial/multi-threaded computing environments. GridapDistributed.jl implements these abstractions for parallel distributed-memory computing environments. To this end, GridapDistributed.jl also leverages (uses) the serial realizations in Gridap.jl and associated methods to handle the local portion on each parallel task. (See arrow labels in the figure below.) On the other hand, GridapDistributed.jl relies on PartitionedArrays.jl in order to handle the parallel execution model (e.g., message-passing via the Message Passing Interface (MPI)), global data distribution layout, and communication among tasks. PartitionedArrays.jl also provides a parallel implementation of partitioned global linear systems (i.e., linear algebra vectors and sparse matrices) as needed in grid-based numerical simulations. While PartitionedArrays.jl is an stand-alone package, segregated from GridapDistributed.jl, it was designed with parallel FE packages such as GridapDistributed.jl in mind. In any case, GridapDistributed.jl is designed so that a different distributed linear algebra library from PartitionedArrays.jl might be used as well, as far as it is able to provide the same functionality.

fig:packages
GridapDistributed.jl and its relation to other packages in the Julia package ecosystem. In this diagram, each rectangle represents a Julia package, while the (directed) arrows represent relations (dependencies) among packages. Both the direction of the arrow and the label attached to the arrows are used to denote the nature of the relation. Thus, e.g., GridapDistributed.jl depends on Gridap.jl and PartitionedArrays.jl , and GridapPETSc depends on Gridap.jl and PartitionedArrays.jl . Note that, in the diagram, the arrow direction is relevant, e.g., GridapP4est depends on GridapDistributed.jl but not conversely.

How to use this documentation

  • The first step for new users is to visit the Getting Started page.

  • A set of tutorials written as Jupyter notebooks and html pages are available here.

  • The detailed documentation is in the rest of sections of the left hand side menu. (WIP)

  • Guidelines for developers of the Gridap project is found in the Gridap wiki page.

Julia educational resources

A basic knowledge of the Julia programming language is needed to use the GridapDistributed package. Here, one can find a list of resources to get started with this programming language.

+Home · GridapDistributed.jl

GridapDistributed.jl

Documentation of the GridapDistributed.jl library.

Note

These documentation pages are under construction.

Introduction

The ever-increasing demand for resolution and accuracy in mathematical models of physical processes governed by systems of Partial Differential Equations (PDEs) can only be addressed using fully-parallel advanced numerical discretization methods and scalable solution methods, thus able to exploit the vast amount of computational resources in state-of-the-art supercomputers. To this end, GridapDistributed.jl is a registered software package which provides fully-parallel distributed memory data structures and associated methods for the Finite Element (FE) numerical solution of PDEs on parallel computers. Thus, it can be run on multi-core CPU desktop computers at small scales, as well as on HPC clusters and supercomputers at medium/large scales. The data structures in GridapDistributed.jl are designed to mirror as far as possible their counterparts in the Gridap.jl Julia software package, while implementing/leveraging most of their abstract interfaces. As a result, sequential Julia scripts written in the high-level Application Programming Interface (API) of Gridap.jl can be used verbatim up to minor adjustments in a parallel distributed memory context using GridapDistributed.jl. This equips end-users with a tool for the development of simulation codes able to solve real-world application problems on massively parallel supercomputers while using a highly expressive, compact syntax, that resembles mathematical notation. This is indeed one of the main advantages of GridapDistributed.jl and a major design goal that we pursue.

In order to scale FE simulations to large core counts, the mesh used to discretize the computational domain on which the PDE is posed must be partitioned (distributed) among the parallel tasks such that each of these only holds a local portion of the global mesh. The same requirement applies to the rest of data structures in the FE simulation pipeline, i.e., FE space, linear system, solvers, data output, etc. The local portion of each task is composed by a set of cells that it owns, i.e., the local cells of the task, and a set of off-processor cells (owned by remote processors) which are in touch with its local cells, i.e., the ghost cells of the task. This overlapped mesh partition is used by GridapDistributed.jl, among others, to exchange data among nearest neighbors, and to glue together global Degrees of Freedom (DoFs) which are sitting on the interface among subdomains. Following this design principle, GridapDistributed.jl provides scalable parallel data structures and associated methods for simple grid handling (in particular, Cartesian-like meshes of arbitrary-dimensional, topologically n-cube domains), FE spaces setup, and distributed linear system assembly. It is in our future plans to provide highly scalable linear and nonlinear solvers tailored for the FE discretization of PDEs (e.g., linear and nonlinear matrix-free geometric multigrid and domain decomposition preconditioners). In the meantime, however, GridapDistributed.jl can be combined with other Julia packages in order to realize the full potential required in real-world applications. These packages and their relation with GridapDistributed.jl are overviewed in the next section.

Building blocks and composability

The figure below depicts the relation among GridapDistributed.jl and other packages in the Julia package ecosystem. The interaction of GridapDistributed.jl and its dependencies is mainly designed with separation of concerns in mind towards high composability and modularity. On the one hand, Gridap.jl provides a rich set of abstract types/interfaces suitable for the FE solution of PDEs. It also provides realizations (implementations) of these abstractions tailored to serial/multi-threaded computing environments. GridapDistributed.jl implements these abstractions for parallel distributed-memory computing environments. To this end, GridapDistributed.jl also leverages (uses) the serial realizations in Gridap.jl and associated methods to handle the local portion on each parallel task. (See arrow labels in the figure below.) On the other hand, GridapDistributed.jl relies on PartitionedArrays.jl in order to handle the parallel execution model (e.g., message-passing via the Message Passing Interface (MPI)), global data distribution layout, and communication among tasks. PartitionedArrays.jl also provides a parallel implementation of partitioned global linear systems (i.e., linear algebra vectors and sparse matrices) as needed in grid-based numerical simulations. While PartitionedArrays.jl is an stand-alone package, segregated from GridapDistributed.jl, it was designed with parallel FE packages such as GridapDistributed.jl in mind. In any case, GridapDistributed.jl is designed so that a different distributed linear algebra library from PartitionedArrays.jl might be used as well, as far as it is able to provide the same functionality.

fig:packages
GridapDistributed.jl and its relation to other packages in the Julia package ecosystem. In this diagram, each rectangle represents a Julia package, while the (directed) arrows represent relations (dependencies) among packages. Both the direction of the arrow and the label attached to the arrows are used to denote the nature of the relation. Thus, e.g., GridapDistributed.jl depends on Gridap.jl and PartitionedArrays.jl , and GridapPETSc depends on Gridap.jl and PartitionedArrays.jl . Note that, in the diagram, the arrow direction is relevant, e.g., GridapP4est depends on GridapDistributed.jl but not conversely.

How to use this documentation

  • The first step for new users is to visit the Getting Started page.

  • A set of tutorials written as Jupyter notebooks and html pages are available here.

  • The detailed documentation is in the rest of sections of the left hand side menu. (WIP)

  • Guidelines for developers of the Gridap project is found in the Gridap wiki page.

Julia educational resources

A basic knowledge of the Julia programming language is needed to use the GridapDistributed package. Here, one can find a list of resources to get started with this programming language.