From b73a5900c6385a3f5a49f5af547736114c981b47 Mon Sep 17 00:00:00 2001 From: Nicola Giuliani Date: Tue, 19 Jul 2016 14:47:26 +0200 Subject: [PATCH 1/4] working on readme --- README.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2091ea9c..f641c4e5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,30 @@ -Parallel BEM Solver for deal.II -=============================== +#Parallel BEM Solver for deal.II [![Build Status](https://travis-ci.org/mathLab/pi-BEM.svg?branch=master)](https://travis-ci.org/mathLab/pi-BEM) +The library represents a parallel solver for the Laplace equation through Boundary Element Methods. We have developed the software on top of the deal.II library. + +## Provided features + +We provide the following capabilities + +- Read of the grid through an external file in one of the following formats (.prm, .msh, .vtk), the files specifies the kind of boundary condition to be applied on the nodes. +- Possibility of solving mixed Dirichlet Neumann boundary value problem. +- Automatic treatment of sharp edges via the double nodes technique. +- Usage of Lagrangian Finite Elements of arbitrary order. We also provide interfaces with discontinuous elements. +- Distributed memory (MPI) parallelisation of the standard collocation BEM for the Laplace equation. +- Coupling with a FMM to get a performance improvement. +- Hybrid Distributed (MPI) - Shared (TBB) memory parallelisation for the BEM-FMM code + +## Code Structure + +## Install Procedure +In order to successfully compile the code you need + +- to install the [deal.II](https://github.com/dealii/dealii) library allowing both for multiprocessors and multithreaded environment. +- to install the Trilinos and Metis wrappers of the library, see the official [instructions](https://www.dealii.org/developer/readme.html) +- to install the pi-BEM library. + After you have compiled your application, you can run make test @@ -17,8 +39,7 @@ Take a look at https://www.dealii.org/developer/developers/testsuite.html for more information on how to create tests and add categories of tests. -Notice to developers -==================== +#Notice to developers Before making a pull request, please make sure you run the script @@ -30,10 +51,9 @@ white space changes are inserted in the repository. The script requires Artistic Style Version 2.04 (astyle) to work properly. -Licence -======= +#Licence -Please see the file ./LICENSE for details +Please see the file [./LICENSE](https://github.com/mathLab/pi-BEM/blob/master/LICENSE) for details From 0fcc8fcbd887f44cddab2ce7529a6aaedaa11a95 Mon Sep 17 00:00:00 2001 From: Nicola Giuliani Date: Tue, 19 Jul 2016 15:35:16 +0200 Subject: [PATCH 2/4] done readme --- README.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f641c4e5..bee0b0dc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Build Status](https://travis-ci.org/mathLab/pi-BEM.svg?branch=master)](https://travis-ci.org/mathLab/pi-BEM) -The library represents a parallel solver for the Laplace equation through Boundary Element Methods. We have developed the software on top of the deal.II library. +The library represents a parallel solver for the Laplace equation through Boundary Element Methods. We have developed the software in C++ on top of the [deal.II](https://github.com/dealii/dealii) library. ## Provided features @@ -15,15 +15,46 @@ We provide the following capabilities - Distributed memory (MPI) parallelisation of the standard collocation BEM for the Laplace equation. - Coupling with a FMM to get a performance improvement. - Hybrid Distributed (MPI) - Shared (TBB) memory parallelisation for the BEM-FMM code +- Recovery of both primal (potential) and dual (potential normal derivative) unknowns. +- L2 projection of the full 3D potential gradient for post processing. +- Extensive tuning via parameter file using the [deal2lkit](https://github.com/mathLab/deal2lkit) library + ## Code Structure +We have subdivided the code in main classes to handle the many different aspects of a complete BEM simulation. + +- Driver. This class is in charge of organising the overall BEM simulation. It has interfaces with all the other classes in order to have a complete simulation. +- ComputationalDomain. This class handles, and provides to the other classes, ONLY the geometry of the problem. In particular + - it handles the domain decomposition using a graph partitioning tool (METIS); + - it reads the domain from an external file. +- BoundaryCondition. The class handling the boundary conditions. In particular + - it reads the boundary conditions for the potential and its normal derivative; + - given the peculiarities of the BEM the boundary conditions represent the actual unknowns, thus it creates the vector containing the variables and fills them with the proper data; + - it performs the error analysis on both unknowns. + +- BEMProblem. This class is the core of the BEM simulation + - it receives the variables vector filled in with the proper boundary condition; + - it creates the codimension 1 functional space setting up the BEM; + - it solves the system using a preconditioned parallel GMRES solver; + - it eventually interacts with the FMM accelerator. +- BEMFMA. This class handles the accelerator, in particular + - it sets up an hierarchical 3D space subdivision (octree); + - it receives two distributed vectors representinf the unknowns and performs a full FMM matrix vector product. ## Install Procedure In order to successfully compile the code you need - to install the [deal.II](https://github.com/dealii/dealii) library allowing both for multiprocessors and multithreaded environment. - to install the Trilinos and Metis wrappers of the library, see the official [instructions](https://www.dealii.org/developer/readme.html) -- to install the pi-BEM library. + +Then you can clone the repository and compile it + + git clone https://github.com/mathLab/pi-BEM.git + cd pi-BEM + mkdir build + cd build + cmake ../ + make -j4 After you have compiled your application, you can run From a6560eb13a11572de4a0a4984f84c01071f2d138 Mon Sep 17 00:00:00 2001 From: Nicola Giuliani Date: Tue, 19 Jul 2016 17:28:41 +0200 Subject: [PATCH 3/4] added some documentation for the classes --- Doxyfile.in | 2 +- include/bem_fma.h | 7 +++++++ include/bem_problem.h | 7 +++++++ include/boundary_conditions.h | 6 ++++++ include/computational_domain.h | 5 +++++ include/driver.h | 4 +++- 6 files changed, 29 insertions(+), 2 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index 1b7ee0ef..394aac41 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "Parallel BEM Solver for deal.II" +PROJECT_NAME = "pi-BEM: a parallel BEM solver for deal.II" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version diff --git a/include/bem_fma.h b/include/bem_fma.h index 6d37353b..4b6f8df9 100644 --- a/include/bem_fma.h +++ b/include/bem_fma.h @@ -40,6 +40,13 @@ namespace Operator using namespace dealii; using namespace deal2lkit; +/** +* A class for the handling of the Fast Multiple Method coupled with the Bundary Element Method. +* It is derived from ParameterAcceptor to have a common interface with parameter files. In +* particular this class performs the matrix vector products approximating long range interactions +* via Multipole and Local Expansions that are contained in dedicated classes. + +*/ template //, Type V> class BEMFMA : public ParameterAcceptor { diff --git a/include/bem_problem.h b/include/bem_problem.h index da11d401..9725d03d 100644 --- a/include/bem_problem.h +++ b/include/bem_problem.h @@ -101,6 +101,13 @@ using namespace deal2lkit; //using namespace TrilinosWrappers; //using namespace TrilinosWrappers::MPI; +/** +* - BEMProblem. This class is the core of the BEM simulation +* - it receives the variables vector filled in with the proper boundary condition; +* - it creates the codimension 1 functional space setting up the BEM; +* - it solves the system using a preconditioned parallel GMRES solver; +* - it eventually interacts with the FMM accelerator. +*/ template class BEMProblem : public ParameterAcceptor { diff --git a/include/boundary_conditions.h b/include/boundary_conditions.h index 9c4294a7..fa380044 100644 --- a/include/boundary_conditions.h +++ b/include/boundary_conditions.h @@ -76,6 +76,12 @@ #include #include +/** +* - BoundaryCondition. The class handling the boundary conditions. In particular +* - it reads the boundary conditions for the potential and its normal derivative; +* - given the peculiarities of the BEM the boundary conditions represent the actual unknowns, thus it creates the vector containing the variables and fills them with the proper data; +* - it performs the error analysis on both unknowns. +*/ template class BoundaryConditions : public ParameterAcceptor { diff --git a/include/computational_domain.h b/include/computational_domain.h index 442f06fa..47470580 100644 --- a/include/computational_domain.h +++ b/include/computational_domain.h @@ -67,6 +67,11 @@ using namespace dealii; using namespace deal2lkit; +/** +* - ComputationalDomain. This class handles, and provides to the other classes, ONLY the geometry of the problem. In particular +* - it handles the domain decomposition using a graph partitioning tool (METIS); +* - it reads the domain from an external file. +*/ template class ComputationalDomain : public ParameterAcceptor { diff --git a/include/driver.h b/include/driver.h index f0d45f90..bab494b1 100644 --- a/include/driver.h +++ b/include/driver.h @@ -69,7 +69,9 @@ using namespace dealii; //using namespace TrilinosWrappers::MPI::Vector; //using namespace TrilinosWrappers::MPI::SparseMatrix; - +/** +* This class is in charge of organising the overall BEM simulation. It has interfaces with all the other classes in order to have a complete simulation. +*/ template class Driver : public ParameterAcceptor { From 926e22aa9217b115b327bd8ed20b90411c647962 Mon Sep 17 00:00:00 2001 From: Nicola Giuliani Date: Wed, 20 Jul 2016 11:50:46 +0200 Subject: [PATCH 4/4] added comments by alberto --- README.md | 18 ++++++++++-------- include/boundary_conditions.h | 4 ++-- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index bee0b0dc..1a85e9dd 100644 --- a/README.md +++ b/README.md @@ -13,23 +13,23 @@ We provide the following capabilities - Automatic treatment of sharp edges via the double nodes technique. - Usage of Lagrangian Finite Elements of arbitrary order. We also provide interfaces with discontinuous elements. - Distributed memory (MPI) parallelisation of the standard collocation BEM for the Laplace equation. -- Coupling with a FMM to get a performance improvement. -- Hybrid Distributed (MPI) - Shared (TBB) memory parallelisation for the BEM-FMM code +- Coupling with a Fast Multiple Method (FMM) to get a performance improvement. +- Hybrid Distributed (MPI) - Shared (Intel Threaded Building Block) memory parallelisation for the BEM-FMM code - Recovery of both primal (potential) and dual (potential normal derivative) unknowns. -- L2 projection of the full 3D potential gradient for post processing. +- L2 projection of the full 3D potential gradient for post processing. - Extensive tuning via parameter file using the [deal2lkit](https://github.com/mathLab/deal2lkit) library ## Code Structure We have subdivided the code in main classes to handle the many different aspects of a complete BEM simulation. -- Driver. This class is in charge of organising the overall BEM simulation. It has interfaces with all the other classes in order to have a complete simulation. +- Driver. This class is in charge of organising the overall BEM simulation. It has interfaces with all the other classes in order to perform a complete simulation. - ComputationalDomain. This class handles, and provides to the other classes, ONLY the geometry of the problem. In particular - it handles the domain decomposition using a graph partitioning tool (METIS); - it reads the domain from an external file. -- BoundaryCondition. The class handling the boundary conditions. In particular +- BoundaryCondition. The class handles the boundary conditions. In particular - it reads the boundary conditions for the potential and its normal derivative; - - given the peculiarities of the BEM the boundary conditions represent the actual unknowns, thus it creates the vector containing the variables and fills them with the proper data; + - given the peculiarities of the BEM, the boundary conditions represent the actual unknowns, thus it creates the vectors containing the two variables and fills them with the proper data; - it performs the error analysis on both unknowns. - BEMProblem. This class is the core of the BEM simulation @@ -39,13 +39,15 @@ We have subdivided the code in main classes to handle the many different aspects - it eventually interacts with the FMM accelerator. - BEMFMA. This class handles the accelerator, in particular - it sets up an hierarchical 3D space subdivision (octree); - - it receives two distributed vectors representinf the unknowns and performs a full FMM matrix vector product. + - it receives two distributed vectors representing the unknowns and performs a full FMM matrix vector product. ## Install Procedure In order to successfully compile the code you need -- to install the [deal.II](https://github.com/dealii/dealii) library allowing both for multiprocessors and multithreaded environment. - to install the Trilinos and Metis wrappers of the library, see the official [instructions](https://www.dealii.org/developer/readme.html) +- to install the [deal.II](https://github.com/dealii/dealii) library allowing both for multiprocessors and multithreaded environment. +- to install the [deal2lkit](https://github.com/mathLab/deal2lkit) library allowing both for multiprocessors and multithreaded environment. + Then you can clone the repository and compile it diff --git a/include/boundary_conditions.h b/include/boundary_conditions.h index fa380044..ba912151 100644 --- a/include/boundary_conditions.h +++ b/include/boundary_conditions.h @@ -77,9 +77,9 @@ #include /** -* - BoundaryCondition. The class handling the boundary conditions. In particular +* - BoundaryCondition. The class handles the boundary conditions. In particular * - it reads the boundary conditions for the potential and its normal derivative; -* - given the peculiarities of the BEM the boundary conditions represent the actual unknowns, thus it creates the vector containing the variables and fills them with the proper data; +* - given the peculiarities of the BEM, the boundary conditions represent the actual unknowns, thus it creates the vectors containing the variables and fills them with the proper data; * - it performs the error analysis on both unknowns. */ template