doc: conn and forest doc and examples

Makefile.am

@@ -77,6 +77,7 @@ include example/tetgen/Makefile.am
 include example/timings/Makefile.am
 include example/balance/Makefile.am
 include example/search/Makefile.am
+include example/tutorials/Makefile.am
 
 ## This was only used for our lint code, which needs to be replaced.
 ##

doc/DoxygenLayout.xml

@@ -8,6 +8,10 @@
       <tab type="user" visible="yes" url="@ref example_simple2" title="Example 2D" intro=""/>
       <tab type="user" visible="yes" url="@ref example_simple3" title="Example 3D" intro=""/>
       <tab type="examples" visible="yes" title="Example Related Files" intro=""/>
+      <tab type="usergroup" visible="yes" url="@ref tutorials" title="Tutorials" intro="">
+      <tab type="user" visible="yes" url="@ref new_example" title="New Example" intro=""/>
+      <tab type="user" visible="yes" url="@ref connectivity" title="Connectivity" intro=""/>
+      <tab type="user" visible="yes" url="@ref forest" title="Forest" intro=""/>
     </tab>
     <tab type="modules" visible="yes" title="" intro=""/>
     <tab type="namespaces" visible="yes" title="">

example/tutorials/Makefile.am

@@ -0,0 +1,14 @@
+
+# This file is part of p4est.
+# Makefile.am in example/tutorials/
+# included non-recursively from toplevel directory
+
+bin_PROGRAMS += example/tutorials/p4est_tutorials_t0_new
+bin_PROGRAMS += example/tutorials/p4est_tutorials_t1_conn_tree
+bin_PROGRAMS += example/tutorials/p4est_tutorials_t1_conn_fileio
+bin_PROGRAMS += example/tutorials/p4est_tutorials_t2_forest
+
+example_tutorials_p4est_tutorials_t0_new_SOURCES = example/tutorials/t0_new.c
+example_tutorials_p4est_tutorials_t1_conn_tree_SOURCES = example/tutorials/t1_conn_tree.c
+example_tutorials_p4est_tutorials_t1_conn_fileio_SOURCES = example/tutorials/t1_conn_fileio.c
+example_tutorials_p4est_tutorials_t2_forest_SOURCES = example/tutorials/t2_forest.c

example/tutorials/t0_new.c

@@ -0,0 +1,33 @@
+#include <p4est.h>   /* Include the p4est library header for parallel adaptive mesh refinement. */
+
+int main (int argc, char ** argv) {
+  /* Initialize the MPI communicator to the default world communicator, which includes all MPI processes. */
+  sc_MPI_Comm mpicomm = sc_MPI_COMM_WORLD;
+
+  /* Initialize the MPI environment with arguments from the command line. */
+  int mpiret = sc_MPI_Init (&argc, &argv);
+
+  /* Check the return status of MPI initialization and abort if it failed. */
+  SC_CHECK_MPI (mpiret);
+
+  /* Initialize the SC library. */
+  sc_init (mpicomm, 1, 1, NULL, SC_LP_DEFAULT);
+
+  /* Initialize the p4est library with default logging priority. */
+  p4est_init (NULL, SC_LP_DEFAULT);
+
+  /* Print a global production-level message saying "Hello World!". */
+  P4EST_GLOBAL_PRODUCTION ("Hello World!\n");
+
+  /* Print a production-level message from the current MPI process. */
+  P4EST_PRODUCTION ("Hello World from the parallel process!\n");
+
+  /* Finalize the MPI environment and clean up all MPI resources. */
+  mpiret = sc_MPI_Finalize ();
+
+  /* Check the return status of MPI finalization and abort if an error occurred. */
+  SC_CHECK_MPI (mpiret);
+
+  /* Return 0 from main to indicate that the program has finished successfully. */
+  return 0;
+}

example/tutorials/t1_conn_fileio.c

@@ -0,0 +1,56 @@
+#include <p4est.h>
+#include <p4est_vtk.h>
+
+int main(int argc, char **argv) {
+  p4est_connectivity_t *conn_out, *conn_in; /* Pointers to p4est connectivity structures */
+  p4est_t *p4est;                          /* Pointer to the p4est structure */
+  int save;                                /* Variable to store the status of save operation. 0: a successfull save*/
+  size_t *bytes = NULL;                    /* Pointer to store the size of the connectivity in bytes */
+  const char *filename = P4EST_STRING "_a_unitsquare"; /* File name for saving/loading the connectivity */
+
+  sc_MPI_Comm mpicomm = sc_MPI_COMM_WORLD;
+  int mpiret = sc_MPI_Init(&argc, &argv);
+  SC_CHECK_MPI(mpiret);
+  sc_init(mpicomm, 1, 1, NULL, SC_LP_DEFAULT);
+  p4est_init(NULL, SC_LP_DEFAULT);
+
+  /* Create a new unit square connectivity which describes how the quadrants are connected */
+  conn_out = p4est_connectivity_new_unitsquare();
+
+  /* Create a new p4est (a forest of quadtrees) structure using the unit square connectivity */
+  p4est = p4est_new(mpicomm, conn_out, 0, NULL, NULL);
+
+  /* Print a message indicating the start of the connectivity file writing process */
+  P4EST_PRODUCTION("Writing connectivity file\n");
+  /* Save the connectivity to a file */
+  save = p4est_connectivity_save(filename, conn_out);
+  if (save) {
+    /* Print an error message if saving the connectivity failed */
+    P4EST_PRODUCTION("Error writing connectivity file\n");
+  }
+  /* Destroy the p4est structure to free memory */
+  p4est_destroy(p4est);
+  /* Destroy the output connectivity structure to free memory */
+  p4est_connectivity_destroy(conn_out);
+
+  /* Print a message indicating the start of the connectivity file loading process */
+  P4EST_PRODUCTION("Loading connectivity file\n");
+  /* Load the connectivity from a file */
+  conn_in = p4est_connectivity_load(filename, bytes);
+  if (conn_in == NULL) {
+    /* Print an error message if loading the connectivity failed */
+    P4EST_LERRORF("Could not read file %s\n", filename);
+    return 1;
+  }
+  /* Create a new p4est structure using the loaded connectivity */
+  p4est = p4est_new(mpicomm, conn_in, 0, NULL, NULL);
+  /* Destroy the p4est structure to free memory */
+  p4est_destroy(p4est);
+  /* Destroy the input connectivity structure to free memory */
+  p4est_connectivity_destroy(conn_in);
+
+  /* Finalize the MPI environment */
+  mpiret = sc_MPI_Finalize();
+  SC_CHECK_MPI(mpiret);
+  return 0; /* Return 0 to indicate successful execution */
+}

example/tutorials/t1_conn_tree.c

@@ -0,0 +1,38 @@
+#include <p4est.h>
+#include <p4est_vtk.h>
+
+int main (int argc, char **argv) {
+  /* Declare the MPI communicator and initialize the MPI environment */
+  sc_MPI_Comm mpicomm = sc_MPI_COMM_WORLD;
+  int mpiret = sc_MPI_Init(&argc, &argv);
+  /* Check for successful MPI initialization */
+  SC_CHECK_MPI(mpiret);
+
+  /* Initialize the SC library with 1-byte alignment and default log priority */
+  sc_init(mpicomm, 1, 1, NULL, SC_LP_DEFAULT);
+  /* Initialize the p4est library with default parameters */
+  p4est_init(NULL, SC_LP_DEFAULT);
+
+  /* Create a new connectivity for a unit square domain */
+  p4est_connectivity_t *conn;
+  conn = p4est_connectivity_new_unitsquare();
+
+  /* Create a new p4est structure (forest of quadtrees) with the created connectivity */
+  p4est_t *p4est;
+  p4est = p4est_new(mpicomm, conn, 0, NULL, NULL);
+
+  /* Write the forest structure to a VTK file for visualization purposes */
+  /* The filename will be prefixed with "p4est_a_unitsquare" */
+  p4est_vtk_write_file(p4est, NULL, P4EST_STRING "_a_unitsquare");
+
+  /* Destroy the p4est structure to free memory */
+  p4est_destroy(p4est);
+  /* Destroy the connectivity structure to free memory */
+  p4est_connectivity_destroy(conn);
+
+  /* Finalize the MPI environment and check for errors */
+  mpiret = sc_MPI_Finalize();
+  SC_CHECK_MPI(mpiret);
+
+  return 0;
+}

example/tutorials/t2_forest.c

@@ -0,0 +1,75 @@
+#include <p4est.h>
+#include <p4est_vtk.h>
+#include <p4est_extended.h>
+
+/* refinement level initialization */
+static int          refine_level = 6;
+
+/* refinement function */
+static int
+refine_fn (p4est_t * p4est, p4est_topidx_t which_tree,
+           p4est_quadrant_t * quadrant)
+{
+  double x_center, y_center, radius;
+
+  /* Calculate the center coordinates of the quadrant */
+  x_center = (double)(quadrant->x + (P4EST_QUADRANT_LEN(quadrant->level) / 2)) / P4EST_ROOT_LEN;
+  y_center = (double)(quadrant->y + (P4EST_QUADRANT_LEN(quadrant->level) / 2)) / P4EST_ROOT_LEN;
+
+  /* Define the radius of the circle */
+  radius = 0.4;
+  /* If the refinement level  */
+  if ((int) quadrant->level <= (refine_level)) {
+
+    /* Check if the center of the quadrant lies within the circle of radius 0.1 */
+    if ((x_center - 0.5) * (x_center - 0.5) + (y_center - 0.5) * (y_center - 0.5) < radius * radius) {
+      /* The center is within the circle, so refine this quadrant */
+      return 1;
+    }
+  }
+  return 0;
+}
+
+
+int main (int argc, char **argv) {
+  p4est_connectivity_t *conn;
+  p4est_t *p4est;
+  /* Usage parameters for exercise 3*/
+
+
+  sc_MPI_Comm mpicomm = sc_MPI_COMM_WORLD;
+  int mpiret = sc_MPI_Init(&argc, &argv);
+  SC_CHECK_MPI(mpiret);
+
+  sc_init(mpicomm, 1, 1, NULL, SC_LP_DEFAULT);
+  p4est_init(NULL, SC_LP_DEFAULT);
+
+  /* Exercise 1*/
+  conn = p4est_connectivity_new_unitsquare();
+  p4est = p4est_new(mpicomm, conn, 0, NULL, NULL);
+  p4est_vtk_write_file(p4est, NULL, P4EST_STRING "_unitsquare_new");
+
+  /* Exercise 2*/
+  p4est_refine (p4est, 1, refine_fn, NULL);
+  p4est_vtk_write_file(p4est, NULL, P4EST_STRING "_unitsquare_refine");
+
+  // p4est_partition (p4est, 0, NULL);
+  // p4est_vtk_write_file (p4est, NULL, P4EST_STRING "_unitsquare_partition");
+
+  /* Exercise 3
+  Here there are two options */
+  // p4est_balance (p4est, P4EST_CONNECT_FULL, NULL);
+  // p4est_vtk_write_file (p4est, NULL, P4EST_STRING "_unitsquare_balance");
+
+  p4est_partition_ext(p4est, 1, NULL);
+  p4est_vtk_write_file (p4est, NULL, P4EST_STRING "_unitsquare_partition_ext");
+
+  p4est_destroy(p4est);
+  p4est_connectivity_destroy(conn);
+
+
+  mpiret = sc_MPI_Finalize();
+  SC_CHECK_MPI(mpiret);
+
+  return 0;
+}