 |
PolyDiM
C++ library for POLYtopal DIscretization Methods
|
| |
PolyDiM
C++ library for POLYtopal DIscretization Methods
|
This guide explains how to set up PolyDiM and GeDiM on your local machine.
In particular, it includes instructions for:
Before performing the following steps, make sure that an SSH key is already configured on your local machine. For more information, see the documentation.
Follow the instructions below to install the C++ library on your local machine so that it can be connected by other applications.
Note: all the following actions can be found in the build_and_run_example_cpp.sh
Installation is based on CMake. Minimum CMake 3.12 version is required.
To build the library we require C++20 standard.
We develop and test with gcc compiler. Minimum version required is gcc-10. See compiler support for more information.
Clone the repository from the GitHub repository into a local directory on your computer. In the following instructions, this directory is referred to as ${BASE_FOLDER}.
Navigate to the cloned repository and initialize and update all Git submodules:
PolyDiM interfaces external libraries.
The installation requires the external dependencies already compiled and installed. Set the CMake variable CMAKE_PREFIX_PATH to give PolyDiM the path where the external libraries are installed.
PolyDiM linear algebra operations are based on
PolyDiM geometrical operations are based on:
Moreover, PolyDiM currently interfaces and exploits the following optional libraries:
To activate/deactivate them can use the CMake variables:
| Option | Default |
|---|---|
ENABLE_TRIANGLE | OFF |
ENABLE_TETGEN | OFF |
ENABLE_VORO | OFF |
ENABLE_SUITESPARSE | OFF |
ENABLE_PETSC | OFF |
ENABLE_METIS | OFF |
ENABLE_VTK | OFF |
The directory /${BASE_FOLDER}/PolyDiM/gedim/3rd_party_libraries contains a CMake configuration that simplifies the local installation of several third-party dependencies.
The following libraries can be installed automatically:
You can enable or disable the installation of each dependency using the following CMake options:
| Option | Default |
|---|---|
INSTALL_EIGEN3 | ON |
INSTALL_GOOGLETEST | ON |
INSTALL_TRIANGLE | ON |
INSTALL_TETGEN | ON |
INSTALL_VORO | ON |
INSTALL_LAPACK | ON |
INSTALL_METIS | OFF |
INSTALL_VTK | OFF |
The following example installs the third-party dependencies into ${BASE_FOLDER}, enabling METIS while disabling TetGen:
If the build completes successfully, the selected third-party libraries will be installed under:
These installations can then be added to the CMake prefix path. For example:
This final section provides an example of how to build and install the PolyDiM and GeDiM libraries.
The build will be performed in the directory /${BASE_FOLDER}/PolyDiM/build. Unless otherwise specified, the Release build configuration is used.
To build and install the PolyDiM and GeDiM libraries locally, run the following commands:
Note: The example below builds PolyDiM using 4 parallel jobs and enables the optional components introduced in the previous example.
After the build process completes successfully, the libraries are installed in the directory specified by CMAKE_INSTALL_PREFIX.
By default, CMAKE_INSTALL_PREFIX is set to the PolyDiM subdirectory within the build directory. For the example above, the installation path is:
To install the libraries in a custom location, set the CMAKE_INSTALL_PREFIX variable when configuring the project with CMake.
After installation, the libraries can be used from any CMake-based application by importing the GeDiM::GeDiM and PolyDiM::PolyDiM targets. For example:
Unit tests for PolyDiM and GeDiM are available to verify that the libraries have been compiled correctly. Running the unit tests is optional and is not required to use the libraries.
The unit tests are based on the GoogleTest framework. The GTest and GMock libraries must already be installed on your system in order to build and run the tests.
To enable the unit tests, set the CMake options ENABLE_POLYDIM_UNIT_TESTS and/or ENABLE_GEDIM_UNIT_TESTS to ON. Both options are disabled (OFF) by default.
Tutorials for the use of PolyDiM are available in the folder /${BASE_FOLDER}/PolyDiM/build/PolyDiM/examples.
To enable the unit tests, set the CMake options ENABLE_POLYDIM_EXAMPLES to ON. The option is disabled (OFF) by default.
More details in the Examples page.
In the following, we build and run the 2D elliptic problem example, Elliptic_PCC_2D.
When executed for the first time, the program generates a Parameters.ini file containing the default settings for the tutorial example.
The parameters can be modified either by editing the file or by specifying them on the command line. For example, running
executes the same example using a finite element method of polynomial order (k = 2).
Along with examples, integration tests, such as convergence test, are available for each methods and orders that can be exploited to solve the related PDE problems. These test are provided as Python scripts.
Starting from v2.0.0, PolyDiM is also available for Python.
Note: all the following actions can be found in the build_and_run_example_python.sh
Installation is based on python3. Minimum python3.11 version is required.
You can install it using pip:
Before installing the package, make sure that all required dependencies are available in your environment. PyPolyDiM relies on several standard scientific Python packages, including:
The complete list of dependencies can be found in the requirements.txt file located in the GitHub repository.
The GitHub repository contains examples and tutorials to help you get started with the library.
For instance, the file main_elliptic_pcc_2d.py contains the Python implementation of the C++ example presented in the previous section.
For more information and documentation, visit the project page on PyPI.
Starting from v3.0.0, PolyDiM is also available for MATLAB users.
Information for setup and use can be found in MATLAB file exchange and on the official GitHub repository.
1.9.8 