Merge branch 'master' into feature-gmt

.github/workflows/ci.yml

@@ -138,8 +138,8 @@ jobs:
       run: |
         cd sc
         git fetch --tags
-        # git checkout v2.8.5
-        git checkout -b test-branch c467b80334f48ceaf1c7c724155ed9f9a4cc6106
+        git checkout v2.8.6
+        # git checkout -b test-branch 2c1496904c485d4ca6f844c396b32f608b72438c
 
     - name: Run bootstrap script
       run: ./bootstrap

.github/workflows/ci_cmake.yml

@@ -99,7 +99,9 @@ jobs:
           ./build/Testing/Temporary/LastTest.log
 
   mac:
-    runs-on: macos-latest
+    # macos-14 is to use Apple Silicon hardware
+    # https://github.blog/changelog/2024-01-30-github-actions-introducing-the-new-m1-macos-runner-available-to-open-source/
+    runs-on: macos-14
     name: CMake build on MacOS
     timeout-minutes: 60
 
@@ -179,6 +181,15 @@ jobs:
       CMAKE_GENERATOR: "MinGW Makefiles"
 
     steps:
+    - uses: msys2/setup-msys2@v2
+      with:
+        update: true
+        install: >-
+          mingw-w64-x86_64-zlib
+
+    - name: Put MSYS2_MinGW64 on PATH
+      run: echo "${{ runner.temp }}/msys64/mingw64/bin/" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
     - uses: actions/checkout@v4
       name: Checkout source code
 
@@ -189,6 +200,7 @@ jobs:
         -Dmpi:BOOL=no
         --install-prefix=${{ runner.temp }}
         -DBUILD_SHARED_LIBS:BOOL=${{ matrix.shared }}
+        -DZLIB_ROOT:PATH=${{ runner.temp }}/msys64/mingw64/
 
     - name: CMake build
       run: cmake --build --preset default
@@ -204,6 +216,7 @@ jobs:
         cmake -B example/build -S example
         -DCMAKE_PREFIX_PATH:PATH=${{ runner.temp }}
         -DBUILD_SHARED_LIBS:BOOL=${{ matrix.shared }}
+        -DZLIB_ROOT:PATH=${{ runner.temp }}/msys64/mingw64/
 
     - name: CMake build examples
       run: cmake --build example/build

AUTHORS

@@ -38,7 +38,7 @@
   Ethan Alan Hereth <e.a.hereth@gmail.com>
   Alex Fikl <alexfikl@gmail.com>
   Hannes Frank <frank@iag.uni-stuttgart.de>
-  Michael Lahnert <michael.lahnert@ipvs.uni-stuttgart.de>
+  Michael Lahnert <michael.lahnert@gmail.com>
   Olivier Iffrig <olivier.iffrig@cea.fr>
 */
 

config/p4est_soversion.in

@@ -4,4 +4,4 @@
 
 # This file is included by src/Makefile.am and parsed by cmake/config.cmake.
 
-P4EST_SOVERSION = 2:0:0
+P4EST_SOVERSION = 3:0:0

doc/author_lahnert.txt

@@ -1 +1 @@
-I place my contributions to p4est under the FreeBSD license. Michael Lahnert (michael.lahnert@ipvs.uni-stuttgart.de)
+I place my contributions to p4est under the FreeBSD license. Michael Lahnert (michael.lahnert@gmail.com)

doc/doxygen/installation.dox

@@ -0,0 +1,198 @@
+/**
+ * \page installing_p4est Installation
+ *
+ * We collect helpful hints to build the p4est software library and examples.
+ *
+ * \tableofcontents
+ *
+ * \section debian Using a Debian package
+ * Installing `p4est` on Debian-based systems via a package manager is the most
+ * straightforward method to get started. This method is beneficial for users who
+ * prefer a managed installation and do not require the latest version or
+ * customization of the build process. This provides a frozen and stable version
+ * of the code with minimal hassle. However, contributions back to the software
+ * aren't possible in this manner.
+ *
+ * Before proceeding, ensure your package lists are up to date.
+ * Open a terminal and update your system's package list with the following command:
+ *
+ * > `sudo apt-get update`
+ *
+ * Once the package lists are updated, you can install `p4est` using `apt-get`.
+ *
+ * > `sudo apt-get install libp4est-<VERSION>`
+ *
+ * The available version can be found in the
+ * [debian package tracker](https://packages.qa.debian.org/p/p4est.html),
+ * or by running
+ *
+ * > `apt-cache search p4est`
+ *
+ * \section tarbuild Installing p4est from a .tar.gz archive
+ *
+ * No special tools are needed to build from a tarball obtained for example from
+ * [the release directory](https://github.com/p4est/p4est.github.io/tree/master/release/).
+ *
+ * After unpacking the tar file, we recommend to change into an empty build directory.
+ * The `configure` script from the toplevel directory of the unpacked tar file
+ * can be executed as is.
+ * We recommend to create an empty build directory.
+ *
+ * \subsection steps1 Step-by-step guide
+ *
+ * \subsubsection unpack_tarball 1. Unpack the tarball
+ *
+ * > `tar -xzf p4est-<VERSION>.tar.gz`
+ *
+ * \subsubsection create_dir 2. Create and change into a build directory
+ *
+ * > `mkdir p4est_build`
+ *
+ * > `cd p4est_build`
+ *
+ * \subsubsection run_script 3. Run the configure script
+ *
+ * > `../p4est-<VERSION>/configure --help`
+ *
+ * > `../p4est-<VERSION>/configure --enable-mpi --etc...`
+ *
+ * You may also set environment variables like `CFLAGS="-Wall -g"`.
+ *
+ * \subsubsection complile_software 4. Compile the software
+ *
+ * > `make -j V=0`
+ *
+ * The environment variable `V=0` suppresses most of `make`'s console output.
+ *
+ * \subsubsection install_software 5. Install the software (optional)
+ *
+ * > `make install V=0`
+ *
+ * The software is installed by default into the prefix `./local`.
+ * This can be changed by setting `configure --prefix=<PATH>`.
+ *
+ * \section install Building from source on Unix-like systems
+ *
+ * For a more hands-on approach, consider cloning the
+ * p4est GitHub repository. You'll need familiarity with the revision control
+ * tool `git` or its GUI frontends. The branch `develop` is recommended
+ * as it has minimized dependencies and houses the latest algorithms. To
+ * generate the configure script, call the `./bootstrap` script in the p4est
+ * top-level source directory. This requires a working installation of GNU
+ * autoconf, automake, and libtool.
+ *
+ * \subsection prerequisites Prerequisites
+ * - For the installation from source, we still prefer the autotools
+ *   over the CMake system (which has recently been added).
+ *   Ensure you have:
+ *   - \c automake
+ *   - \c autoconf
+ *   - \c libtool
+ *   - \c make
+ *
+ * \subsection optional Optional components
+ * - For enhancing parallel processing, having \c MPI is advisable
+ *   and configuring `--enable-mpi`.
+ *
+ * \subsection steps2 Step-by-step guide
+ *
+ * \subsubsection source_retrieval 1. Source retrieval
+ *
+ * > `git clone https://github.com/cburstedde/p4est.git`
+ *
+ * \subsubsection bootstrap 2. Bootstrap execution
+ *
+ * Navigate to the \c p4est directory and initiate the bootstrap script,
+ * especially if you've cloned it from GitHub:
+ *
+ * > `cd p4est`
+ *
+ * > `./bootstrap`
+ *
+ * \subsubsection setup 3. Setting up p4est
+ *
+ * Decide on a compilation directory. For this guide, `~/p4est_build` is used,
+ * presuming the source is in `~/p4est`:
+ *
+ * > `mkdir ~/p4est_build`
+ *
+ * > `cd ~/p4est_build`
+ *
+ * > `../p4est/configure [OPTIONS]`
+ *
+ * The \c configure script is quite versatile and has multiple options, among
+ * them:
+ *
+ * - `--enable-debug`: Activates debugging mode, increasing verbosity and turns
+ *   on `P4EST_ASSERT` for checks.
+ * - `--enable-mpi`: This integrates the `mpi.h` header and triggers MPI compiler
+ *   wrappers. Without this option, MPI routine wrappers are employed for serial
+ *   compilation.
+ * - `--disable-mpiio`: This avoids using `MPI_File` based calls.
+ *
+ * Additionally, the command:
+ *
+ * > `../p4est/configure --help`
+ *
+ * prints a list of currently available options to configure.
+ *
+ * A common developer-oriented configuration might resemble:
+ *
+ * > `relative/path/to/configure CFLAGS="-Wall -Wuninitialized -O0 -g" --enable-mpi --enable-debug`
+ *
+ * While a production-oriented configuration could be:
+ *
+ * > `relative/path/to/configure CFLAGS="-Wall -Wno-unused-but-set-variable -O2" --enable-mpi`
+ *
+ * \subsubsection compile 4. Compiling p4est
+ *
+ * After configuration, the next step is the compilation of \c p4est:
+ *
+ * > `make -j V=0`
+ *
+ * > `make install -j V=0`
+ *
+ * \subsubsection verification 5. Verification Step
+ *
+ * It's recommended to execute the \c p4est test programs post-installation
+ * to ensure everything is in order:
+ *
+ * > `make -j4 check V=0`
+ *
+ * Where the `-j` option limits parallel make to at most four targets at the same time.
+ *
+ * \subsubsection api_docs 6. Autogenerated API documentation
+ *
+ * The Doxygen output for p4est and libsc can be recreated with the following
+ * command after the configuration process:
+ *
+ * > `make doxygen`
+ *
+ * This requires the doxygen program and produces html, latex and man format
+ * documentation under `doc`.
+ *
+ * \subsubsection integration 7. Integrating with p4est
+ *
+ * For projects aiming to incorporate \c p4est as an external library
+ *
+ * > `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/p4est_install/lib`
+ *
+ * to be able to run built executables that dynamically link to p4est.
+ * Append to the compile command:
+ *
+ * > `-I$HOME/p4est_install/include -L$HOME/p4est_install/lib -lp4est -lsc -lz -lm`
+ *
+ * For full functionality, we expect a zlib that provides the function
+ * `adler32_combine`.
+ *
+ * \section further Further information and links
+ *
+ * You may find further documentation for installation on both
+ * [Linux](https://github.com/cburstedde/p4est/blob/develop/INSTALL) and
+ * [Windows](https://github.com/cburstedde/p4est/blob/develop/INSTALL_WINDOWS)
+ * in the source folder.
+ *
+ * For users with Windows 10 version 2004 and higher, you may also try
+ * [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) as p4est works
+ * well in the subsystem.
+ */

doc/doxygen/mainpage.dox

@@ -52,6 +52,7 @@
  * [source](http://github.com/cburstedde/p4est) under the
  * [doc/](https://github.com/cburstedde/p4est/tree/master/doc) directory.
  *
+ * We provide installation instructions under \ref installing_p4est.
  * To build the p4est library from a tar distribution, use the standard
  * procedure of the GNU autotools.  The configure script takes the following
  * options:

doc/release_notes.txt

@@ -9,30 +9,38 @@
    the next release version.  Please also note if there have been A*I
    extensions, in which case we'll bump the libtool minor version.
 
-## 2.9
-
-This release will be considered stable and long-time supported.
-
 ## 2.8.6
 
-This is the upcoming release with lots of small additions throughout.
+There have been breaking changes, very strictly speaking.
 
 ### Build system
 
+ - Bump libsc under subdirectory sc/ to v2.8.6.
+ - Bump libtool library version of p4est and libsc to 3:0:0.
+ - Enhance CMake build script in accordance with changes under sc/.
+
 ### Documentation
 
  - Create a page of examples for users to get familiar with the software.
  - Arrange all doxygen pages into a subdirectory doc/doxygen.
  - Fix the warnings while generating documentation for p4est_connectivity.h.
  - Fix the warnings while generating documentation for p8est_connectivity.h.
  - Add more explicit documentation to the p?est_connectivity.h files.
+ - Fix the warnings while generating documentation for p4est_mesh.h.
+ - Fix the warnings while generating documentation for p8est_mesh.h.
+ - Add more explicit documentation to the p?est_mesh.h files.
 
 ### Functionality
 
  - Add two connectivities (2d bowtie and 3d drop) to stress the balance demo.
  - Add a new 3d connectivity (drop) into the simple example.
  - Add three 2d connectivities (circle, drop and bowtie) into simple.
  - Integrate updated MPI I/O wrappers and CMake logic in libsc.
+ - Reset quadrant data size to 0 in p{4,8}est_wrap_new_p4est.
+ - Add search_partition_gfp operating without a gfq array.
+ - Add a parameter struct for the p{4,8}est_wrap_t.
+ - Add a parameter struct for the p{4,8}est_mesh_t.
+ - Add an option to store edge-hanging corner neighbors in the mesh.
  - Begin example/gmt to match geodesic information against mesh.
 
 ## 2.8.5

src/p4est.h

@@ -388,12 +388,12 @@ void                p4est_partition (p4est_t * p4est,
 
 /** Compute the checksum for a forest.
  * Based on quadrant arrays only. It is independent of partition and mpisize.
- * \return  Returns the checksum on processor 0 only. 0 on other processors.
+ * \return  Returns the checksum on all processors.
  */
 unsigned            p4est_checksum (p4est_t * p4est);
 
 /** Compute a partition-dependent checksum for a forest.
- * \return  Returns the checksum on processor 0 only. 0 on other processors.
+ * \return  Returns the checksum on all processors.
  */
 unsigned            p4est_checksum_partition (p4est_t * p4est);
 

src/p4est_communication.c

@@ -942,29 +942,22 @@ p4est_comm_checksum (p4est_t * p4est, unsigned local_crc, size_t local_bytes)
 #ifdef P4EST_ENABLE_MPI
   int                 mpiret;
   int                 p;
-  uint64_t            send[2];
-  uint64_t           *gather;
-
-  send[0] = (uint64_t) local_crc;
-  send[1] = (uint64_t) local_bytes;
-  gather = NULL;
-  if (p4est->mpirank == 0) {
-    gather = P4EST_ALLOC (uint64_t, 2 * p4est->mpisize);
-  }
-  mpiret = sc_MPI_Gather (send, 2, sc_MPI_LONG_LONG_INT,
-                          gather, 2, sc_MPI_LONG_LONG_INT, 0, p4est->mpicomm);
+  long long           send[2];
+  long long          *gather;
+
+  send[0] = (long long) local_crc;
+  send[1] = (long long) local_bytes;
+  gather = P4EST_ALLOC (long long, 2 * p4est->mpisize);
+  mpiret = sc_MPI_Allgather (send, 2, sc_MPI_LONG_LONG_INT,
+                             gather, 2, sc_MPI_LONG_LONG_INT, p4est->mpicomm);
   SC_CHECK_MPI (mpiret);
 
-  if (p4est->mpirank == 0) {
-    for (p = 1; p < p4est->mpisize; ++p) {
-      crc = adler32_combine (crc, (uLong) gather[2 * p + 0],
-                             (z_off_t) gather[2 * p + 1]);
-    }
-    P4EST_FREE (gather);
-  }
-  else {
-    crc = 0;
+  crc = (uLong) gather[0];
+  for (p = 1; p < p4est->mpisize; ++p) {
+    crc = adler32_combine (crc, (uLong) gather[2 * p + 0],
+                           (z_off_t) gather[2 * p + 1]);
   }
+  P4EST_FREE (gather);
 #endif /* P4EST_ENABLE_MPI */
 
   return (unsigned) crc;