# Semi-StructMG

**Repository Path**: zongy17/semi-struct-mg

## Basic Information

- **Project Name**: Semi-StructMG
- **Description**: Algebraic Multigrid for Semi-Structured Grids
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-07-07
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Semi-StructMG: A Fast and Scalable Semi-Structured Algebraic Multigrid

Semi-StructMG is tailored for solving linear system $Ax=b$ on semi-structured grid problems.
As a sophisticated preconditioner, Semi-StructMG also provides various Krylov iterative solvers (CG, GMRES, GCR) in the library to be called directly.

A semi-structured grid usually consists of multiple structured blocks that can be distorted, stretched, rotated, etc., and can have arbitrary connections between them.
The detailed definition and some illustrated examples refer to *hypre*'s documentation (https://hypre.readthedocs.io/en/latest/ch-sstruct.html) or Semi-StructMG's User Guide (in the doc folder of this repository).


## Third-party Library
Semi-StructMG uses jsoncpp (https://github.com/open-source-parsers/jsoncpp), a JSON library, to handle the configuration files for multigrid parameters.
We recommend users to download the 1.9.5 version of jsoncpp (https://github.com/open-source-parsers/jsoncpp/tree/1.9.5), and the following commands can compile and install:
```bash
# clone or download the repository
cd build/debug
cmake -DCMAKE_CXX_COMPILER=${YOUR_CXX_COMPILER} -DCMAKE_BUILD_TYPE=debug -DBUILD_STATIC_LIBS=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_INCLUDEDIR=include/jsoncpp -DARCHIVE_INSTALL_DIR=. -G "Unix Makefiles" ../..
make
```
When compiling and generating the executables of testing programs or user applications, this library needs to be linked together with Semi-StructMG.

## Dynamic Library of Semi-StructMG
**Semi-StructMG is currently not open source.**
It may become partially open source in the future, depending on our assessment of its development prospects.
We provide **precompiled dynamic libraries** for several platforms with different compilers and MPI.
The available versions are listed in the following table (to be updated).
**Users can choose suitable version according to their platforms' configurations.**
If none of the available versions meet your needs, please contact us, and we will compile a dynamic library for your required platform.

## x86_64 
These libraries are compiled with the `-ax` flag (https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2023-0/ax-qax.html) of Intel compilers.
The flag tells the compiler to generate multiple, feature-specific auto-dispatch code paths for Intel processors if there is a performance benefit.
In addition to Intel processors, AMD processors can also be used.

### Intel Compiler + IntelMPI 
Available at `lib/x86_64-IntelMPI-2021.5/libSstructmg.so`.

This library is compiled by icpc (ICC) 2021.5.0 and IntelMPI 2021.5 with `-axCORE-AVX2` flag.

The following table lists the different platforms with various configurations that we have tested our dynamic library successfully.
The compiler and MPI in the table are used to compile the testing programs and user applications that invoke the precompiled Semi-StructMG. 

| Processor  | Compiler    |   MPI  |
| ---------- | ----------- | ------ |
| Intel Xeon Platinum 8358 | icpc (ICC) 19.0.5.281      | IntelMPI 2019.5 |
| AMD EPYC 7H12            | icpc (ICC) 2021.5.0        | IntelMPI 2021.5 |
| Intel Xeon Gold 6342     | icpc (ICC) 2021.7.1        | IntelMPI 2021.7 |
| Intel Xeon Gold 6342     | OneAPI DPC++/C++ 2022.2.1  | IntelMPI 2021.7 |
| Intel Xeon Gold 6132     | icpc (ICC) 19.0.5.281      | IntelMPI 2019.5 |
| Intel Xeon Gold 6254     | icpc (ICC) 19.1.3.304      | IntelMPI 2019.9 |


### Intel Compiler + OpenMPI
Available at `lib/x86_64-OpenMPI-4.0.4/libSstructmg.so`.

This library is compiled by icpc (ICC) 2021.5.0 and OpenMPI 4.0.4 with `-axCORE-AVX2` flag.
The following table lists the platforms with their configurations that we have tested our dynamic library successfully.
The compiler and MPI in the table are used to compile the testing programs and user applications that invoke the precompiled Semi-StructMG. 

| Processor  | Compiler    |   MPI  |
| ---------- | ----------- | ------ |
| Intel Xeon Platinum 8358 | icpc (ICC) 2021.5.0        | OpenMPI 4.0.4 |
| AMD EPYC 7H12            | icpc (ICC) 2021.5.0        | OpenMPI 4.0.4 |
| Intel Xeon Gold 6342     | icpc (ICC) 2021.7.1        | OpenMPI 4.1.4 |
| Intel Xeon Gold 6342     | OneAPI DPC++/C++ 2022.2.1  | OpenMPI 4.1.4 |
| Intel Xeon Gold 6132     | icpc (ICC) 19.0.5.281      | OpenMPI 4.0.2 |
| Intel Xeon Gold 6254     | icpc (ICC) 19.1.3.304      | OpenMPI 4.1.2 |

## aarch64
### Kunpeng series specific

Available at `lib/aarch64-OpenMPI-4.0.2/libSstructmg.so`.

This library is compiled by g++ 9.3.1 (kunpeng gcc 1.3.1) and OpenMPI 4.0.3.
**We must emphasize that this library can probably only run on the Kunpeng series processors because the compilers on ARM do not support a feature similar to Intel's `-ax` option.**
The following table lists the platforms with their configurations that we have tested our dynamic library successfully.
The compiler and MPI in the table are used to compile the testing programs and user applications that invoke the precompiled Semi-StructMG. 

| Processor  | Compiler    |   MPI  |
| ---------- | ----------- | ------ |
| Kunpeng 920  | g++  9.3.1 (kunpeng gcc 1.3.1) | OpenMPI 4.0.4 |
| Kunpeng 920B | g++ 10.3.1                     | OpenMPI 4.1.2 |

## Evaluation and Examples

The repository for performance comparison of Semi-StructMG against *hypre*'s SSAMG, Split, and BoomerAMG refers to https://gitee.com/zongy17/baseline-recmat

By reading these test files, users can quickly understand how Semi-StructMG works and recognize its similarities with the interfaces provided by *hypre*.