Readmes for all benchmarks,examples,src,test

api/README.md

@@ -0,0 +1,11 @@
+# t8code APIs
+
+This directory contains Application Programming Interfaces (APIs) for using `t8code` from languages other than C/C++.
+
+## Subfolders
+
+- [**t8_fortran_interface/**](t8_fortran_interface/README.md): Contains the source code for the Fortran interface to `t8code`.
+
+## Main Purpose
+
+The APIs in this folder provide language-specific bindings that allow developers to call `t8code`'s core functionalities from different programming environments. This broadens the library's usability and allows it to be integrated into a wider range of scientific computing applications.

api/t8_fortran_interface/README.md

@@ -0,0 +1,11 @@
+# t8code APIs
+
+This directory contains Application Programming Interfaces (APIs) for using `t8code` from languages other than C/C++.
+
+## Subfolders
+
+- [**t8_fortran_interface/**](t8_fortran_interface/README.md): Contains the source code for the Fortran interface to `t8code`.
+
+## Main Purpose
+
+The APIs in this folder provide language-specific bindings that allow developers to call `t8code`'s core functionalities from different programming environments. This broadens the library's usability and allows it to be integrated into a wider range of scientific computing applications.

benchmarks/README.md

@@ -0,0 +1,34 @@
+# t8code Benchmarks
+
+This directory contains a collection of benchmark programs designed to measure the performance and scalability of various components within the `t8code` library. These benchmarks are crucial for performance regression testing, identifying bottlenecks, and demonstrating the efficiency of `t8code`'s core algorithms.
+
+## Building the Benchmarks
+
+To build the benchmarks, you need to enable the `T8_ENABLE_BENCHMARKS` option in your CMake configuration.
+
+## Benchmark Programs
+
+Each file is a standalone program that times a specific operation or workflow.
+
+- **`t8_time_forest_partition.cxx`**: This benchmark measures the time it takes to partition a `t8_forest`. It  creates a forest, possibly adapts it to create a load imbalance, and then times the `t8_forest_partition` call. This is a key benchmark for assessing parallel scalability.
+
+- **`t8_time_fractal.cxx`**: This program benchmarks the creation of a "fractal" mesh. This typically involves recursively adapting the mesh based on a geometric criterion, which heavily exercises the `t8_forest_adapt` and `t8_forest_balance` functions. It's a good measure of the raw speed of mesh adaptation.
+
+- **`t8_time_new_refine.c`**: A C-based benchmark that specifically times the refinement process (`t8_forest_adapt`).
+
+- **`t8_time_partition.cxx`**: This is another benchmark for partitioning to time the partition. It might test a different scenario or a different aspect of partitioning compared to `t8_time_forest_partition.cxx`.
+
+- **`t8_time_prism_adapt.cxx`**: This benchmark specifically measures the performance of adaptation on a mesh composed of prisms. This is important for ensuring that the performance of hybrid mesh elements is also tracked.
+
+- **`t8_time_set_join_by_vertices.cxx`**: This benchmark times the `t8_cmesh_set_join_by_vertices` function. This function is part of setting up the coarse mesh connectivity and can have a performance impact, especially for very large coarse meshes.
+
+## How to Run
+
+After building the benchmarks, you can run the individual executables. Most of them are intended to be run with MPI to test parallel performance.
+
+```bash
+# Example of running a benchmark with multiple processes
+mpirun -n 16 ./t8_time_forest_partition
+```
+
+The programs will typically print timing information and other performance metrics to the console. The exact parameters (e.g., initial mesh size, refinement levels) can often be controlled via command-line arguments. Run a benchmark with the `-h` flag to see its available options.

example/IO/README.md

@@ -0,0 +1,12 @@
+# I/O Examples
+
+This folder contains examples related to Input/Output operations in `t8code`. These examples demonstrate how to read and write `t8code`'s main data structures, such as the `t8_cmesh` and `t8_forest`, to and from disk.
+
+## Subfolders
+
+- [**cmesh/**](cmesh/README.md): Examples showing how to read a coarse mesh from a file and write it back out.
+- [**forest/**](forest/README.md): Examples showing how to save an adapted forest to a file and load it back. This is useful for checkpointing and restarting simulations.
+
+## Main Purpose
+
+These examples are essential for understanding how to manage data persistence in `t8code`. They provide a starting point for integrating `t8code` into workflows that involve pre-existing mesh files or require saving simulation states.

example/IO/cmesh/README.md

@@ -0,0 +1,21 @@
+# cmesh I/O Examples
+
+This folder provides examples on how to perform Input/Output operations with the `t8_cmesh` object. The main example demonstrates a general load-and-save capability.
+
+## Files
+
+- `t8_cmesh_load_save.cxx`: This program shows how to load a `t8_cmesh` from a file, and then save it back to another file. This is a useful pattern for converting between mesh formats or for inspecting a mesh.
+
+## Subfolders
+
+The subfolders contain examples that are specific to different mesh file formats or mesh generators that `t8code` can interface with.
+
+- [**gmsh/**](gmsh/README.md): Examples for reading `.msh` files from Gmsh.
+- [**netcdf/**](netcdf/README.md): Examples for reading meshes stored in the NetCDF format.
+- [**tetgen/**](tetgen/README.md): Examples for reading meshes from TetGen.
+- [**triangle/**](triangle/README.md): Examples for reading 2D meshes from Triangle.
+- [**vtk/**](vtk/README.md): Examples for writing `t8_cmesh` data to VTK files for visualization.
+
+## Main Purpose
+
+These examples are designed to help developers understand how to get coarse mesh data into and out of `t8code`, which is a fundamental first step for many simulation workflows.

example/IO/cmesh/gmsh/README.md

@@ -0,0 +1,25 @@
+# Gmsh I/O Examples
+
+This folder contains examples that demonstrate how to read `.msh` files, the native format of the open-source mesh generator [Gmsh](https://gmsh.info/).
+
+## Files
+
+- `t8_read_msh_file.cxx`: A straightforward example that shows the basic process of reading a `.msh` file and initializing a `t8_cmesh` from it.
+- `t8_load_and_refine_square_w_hole.cxx`: A more complex example that loads a hybrid 2D mesh (containing both quads and triangles) of a square with a circular hole. After loading, it uniformly refines the resulting forest to demonstrate a complete workflow.
+- `circlesquare_hybrid_hole.msh`: The Gmsh mesh file used as input for the `t8_load_and_refine_square_w_hole` example.
+
+## Main Purpose
+
+These examples provide a practical guide for users who want to use `t8code` to process meshes created with Gmsh. This is a very common use case, as Gmsh is a powerful and widely used tool for generating unstructured meshes.
+
+## How to Run
+
+After building the examples, you can run the executables from the build directory. For example:
+
+```bash
+# Run the basic reader example
+./t8_read_msh_file <path_to_your_mesh.msh>
+
+# Run the load-and-refine example
+./t8_load_and_refine_square_w_hole <path_to_circlesquare_hybrid_hole.msh>
+```

example/IO/cmesh/netcdf/README.md

@@ -0,0 +1,21 @@
+# NetCDF I/O Example
+
+This folder contains an example for writing `t8_cmesh` data to a file using the [NetCDF](https://www.unidata.ucar.edu/software/netcdf/) (Network Common Data Form) format.
+
+## Files
+
+- `t8_write_cmesh_netcdf.cxx`: This program demonstrates how to take a `t8_cmesh` (in this case, one generated programmatically) and write its contents to a `.nc` file.
+
+## Main Purpose
+
+This example is relevant for users who need to interface `t8code` with other scientific computing applications that use NetCDF for data storage. It shows how to export the coarse mesh data in this standard format.
+
+## How to Run
+
+To build and run this example, `t8code` must be configured with NetCDF support enabled. After building, you can simply execute the program:
+
+```bash
+./t8_write_cmesh_netcdf
+```
+
+This will generate an output file (e.g., `cmesh.nc`) in the execution directory. You can then inspect this file with NetCDF tools like `ncdump` or `ncview`.

example/IO/cmesh/tetgen/README.md

@@ -0,0 +1,23 @@
+# TetGen I/O Examples
+
+This folder contains examples that demonstrate how to read mesh files generated by [TetGen](http.www.tetgen.org/), a quality tetrahedral mesh generator and 3D Delaunay triangulator.
+
+## Files
+
+- `t8_read_tetgen_file.cxx`: A basic example that shows how to read TetGen's output files (`.node`, `.ele`) and construct a `t8_cmesh` from them.
+- `t8_forest_from_tetgen.cxx`: A more advanced example that not only reads a TetGen mesh but also creates a `t8_forest` from it, demonstrating a more complete workflow from external mesh to a `t8code` forest.
+- `t8_time_tetgen_file.cxx`: A utility program to measure the time it takes to read a TetGen file. This can be useful for performance analysis and benchmarking `t8code`'s I/O capabilities.
+
+## Main Purpose
+
+These examples are for users who use TetGen to create their 3D tetrahedral meshes and want to use them as input for `t8code`. They show the necessary steps to import such meshes into `t8code`'s data structures.
+
+## How to Run
+
+To run these examples, you will need a mesh generated by TetGen. The executables take the base name of the TetGen files as an argument.
+
+```bash
+# Example usage:
+./t8_read_tetgen_file <path_to_your_mesh_basename>
+```
+For a mesh described by `mymesh.node` and `mymesh.ele`, the command would be `./t8_read_tetgen_file mymesh`. You will need to have TetGen support enabled in the `t8code` build configuration.

example/IO/cmesh/triangle/README.md

@@ -0,0 +1,20 @@
+# Triangle I/O Example
+
+This folder contains an example that demonstrates how to read mesh files generated by [Triangle](https://www.cs.cmu.edu/~quake/triangle.html), a high-quality 2D mesh generator and Delaunay triangulator.
+
+## Files
+
+- `t8_read_triangle_file.cxx`: This program shows how to read Triangle's output files (`.node`, `.ele`) and initialize a 2D `t8_cmesh` from them.
+
+## Main Purpose
+
+This example is intended for users who use Triangle to generate their 2D unstructured meshes and want to import them into `t8code` for simulation or other processing.
+
+## How to Run
+
+To build and run this example, `t8code` must be configured with Triangle support enabled. The executable takes the base name of the Triangle files as a command-line argument.
+
+```bash
+# If your mesh is defined by mymesh.node and mymesh.ele:
+./t8_read_triangle_file mymesh
+```

example/IO/cmesh/vtk/README.md

@@ -0,0 +1,20 @@
+# VTK I/O Example
+
+This folder contains an example for reading a coarse mesh from a VTK file.
+
+## Files
+
+- `t8_cmesh_read_from_vtk.cxx`: This program demonstrates how to read a mesh from a VTK file (`.vtu` or `.vtp`) and create a `t8_cmesh` from it. While `t8code` is often used to *write* VTK files for visualization, this shows it can also ingest them as a cmesh source.
+
+## Main Purpose
+
+This example is useful for workflows where the input mesh is provided in the VTK format. It allows users to leverage `t8code`'s capabilities on meshes generated by other tools that can export to VTK.
+
+## How to Run
+
+To build and run this example, `t8code` must be configured with VTK support enabled. The executable takes the path to the VTK file as a command-line argument.
+
+```bash
+# Example usage:
+./t8_cmesh_read_from_vtk <path_to_your_mesh.vtu>
+```

example/IO/forest/README.md

@@ -0,0 +1,12 @@
+# Forest I/O Examples
+
+This folder contains examples related to Input/Output operations for the `t8_forest` object. These examples demonstrate how to save and load the state of an adaptive forest, which is a key feature for checkpointing and restarting simulations.
+
+## Subfolders
+
+- [**gmsh/**](gmsh/README.md): An example of how to save a `t8_forest` into the Gmsh `.msh` format.
+- [**netcdf/**](netcdf/README.md): An example of how to save a `t8_forest` into the NetCDF format.
+
+## Main Purpose
+
+These examples are crucial for users who need to save the results of a simulation or checkpoint its state. Being able to save the adapted forest allows a simulation to be restarted exactly where it left off, or for the final adapted mesh to be analyzed or used in subsequent computations.

example/IO/forest/gmsh/README.md

@@ -0,0 +1,21 @@
+# Gmsh Forest I/O Example
+
+This folder contains an example of a workflow involving a `t8_forest` and the Gmsh `.msh` file format.
+
+## Files
+
+- `t8_gmsh_to_vtk.cxx`: This program demonstrates a common use case: loading a mesh from a Gmsh file, creating a `t8_forest` from it, and then writing the resulting forest data to a VTK file for visualization. While the primary action is writing a VTK file, the initial step involves reading a `.msh` file, showcasing `t8code`'s ability to ingest Gmsh files as a starting point for forest creation.
+
+## Main Purpose
+
+This example is useful for users who have meshes in the Gmsh format and want to use them in `t8code` and then visualize the results. It bridges the gap between mesh generation with Gmsh and analysis/visualization with tools that support the VTK format (like ParaView or VisIt).
+
+## How to Run
+
+After building the examples, you can run this program by providing a path to a Gmsh `.msh` file.
+
+```bash
+./t8_gmsh_to_vtk <path_to_your_mesh.msh>
+```
+
+This will produce a VTK file (e.g., `output.vtk`) in the execution directory.

example/IO/forest/netcdf/README.md

@@ -0,0 +1,21 @@
+# NetCDF Forest I/O Example
+
+This folder contains an example for writing `t8_forest` data to a file using the [NetCDF](https://www.unidata.ucar.edu/software/netcdf/) format.
+
+## Files
+
+- `t8_write_forest_netcdf.cxx`: This program demonstrates how to take a `t8_forest` (in this case, one that is created programmatically and refined) and write its contents, including the adaptive structure and any associated data, to a `.nc` file.
+
+## Main Purpose
+
+This example is important for users who need to save the complete state of an adapted mesh for checkpointing, restarting, or post-processing with tools that support the NetCDF format. It shows how to persist the complex data structures of an adapted `t8_forest`.
+
+## How to Run
+
+To build and run this example, `t8code` must be configured with NetCDF support enabled. After building, you can simply execute the program:
+
+```bash
+./t8_write_forest_netcdf
+```
+
+This will generate an output file (e.g., `forest.nc`) in the execution directory, which contains the serialized `t8_forest`. You can inspect this file with NetCDF tools like `ncdump`.

example/advect/README.md

@@ -0,0 +1,45 @@
+# Advection Solver Example
+
+This folder contains a complete, stand-alone finite volume advection solver. It is one of the most comprehensive examples in `t8code` and serves as an excellent case study for how to build a real application on top of the library.
+
+The solver advects a scalar quantity through a domain, demonstrating many of `t8code`'s key features in a practical context.
+
+## Files
+
+- `t8_advection.cxx`: The main source code for the advection solver. This file shows how to:
+    - Initialize `t8code` and a `t8_cmesh`.
+    - Create a `t8_forest` and adapt it based on a given feature (in this case, the advected scalar field).
+    - Attach user data (the scalar quantity) to the mesh elements.
+    - Use the `t8_ghost` mechanism to exchange data between MPI processes.
+    - Implement a numerical scheme (finite volume) using the `t8_forest` iterators.
+    - Write out visualization files (VTK) at regular intervals.
+- `t8_advection_generate_channel.geo`: A Gmsh geometry file for generating a 3D channel mesh. This can be used as input to the advection solver.
+- `t8_advection_generate_channel_2d.geo`: A Gmsh geometry file for generating a 2D channel mesh.
+
+## Main Features Demonstrated
+
+- **Adaptive Mesh Refinement (AMR):** The solver adaptively refines the mesh to better resolve the features of the advected scalar field.
+- **Parallel Execution:** The example is fully parallelized with MPI and uses `t8code`'s ghost layer functionality for communication.
+- **Hybrid Meshes:** It can run on meshes with different element types (tetrahedra, hexahedra, prisms, etc.).
+- **User Data Management:** It shows how to associate application-specific data with each element in the forest.
+- **File I/O:** It can take a mesh file as input and writes out VTK files for visualization.
+
+## How to Run
+
+After building the examples, the `t8_advection` executable will be available. You can run it with the `-h` flag to see all available command-line options.
+
+```bash
+./t8_advection -h
+```
+
+A typical use case is to run it on a mesh file. You can generate a mesh using the provided `.geo` files with Gmsh.
+
+```bash
+# First, generate a mesh with Gmsh
+gmsh t8_advection_generate_channel.geo -3 -o channel.msh
+
+# Then, run the advection solver on that mesh
+mpirun -n 4 ./t8_advection --mesh-file channel.msh
+```
+
+The solver will produce a series of `.pvtu` and `.vtu` files that can be opened in ParaView or VisIt to visualize the advection process.

example/cmesh/README.md

@@ -0,0 +1,27 @@
+# Coarse Mesh (cmesh) Examples
+
+This folder contains examples that demonstrate how to create, manipulate, and query the `t8_cmesh` object. The `t8_cmesh` is the coarse, unadapted representation of the domain and serves as the basis for the adaptive `t8_forest`.
+
+## Files
+
+- `t8_cmesh_create_partitioned.cxx`: This example shows how to create a `t8_cmesh` that is already partitioned across multiple MPI processes. This is an advanced use case for situations where the coarse mesh itself is too large to fit on a single node.
+- `t8_cmesh_geometry_examples.cxx`: Demonstrates how to associate different types of geometries with a `t8_cmesh`. This is key to running simulations on non-trivial, curved domains.
+- `t8_cmesh_hypercube_pad.cxx`: An example of how to create a hypercube-shaped cmesh with padding, which can be useful for certain boundary condition treatments.
+- `t8_cmesh_partition.cxx`: This program shows the standard workflow for partitioning a `t8_cmesh` that is initially loaded on a single process and then distributed across all available MPI processes.
+- `t8_cmesh_set_join_by_vertices.cxx`: An example that demonstrates how to control the connectivity of the coarse mesh by defining how faces are joined based on their shared vertices.
+
+## Main Purpose
+
+These examples provide a guide to the various ways a `t8_cmesh` can be constructed and configured. Understanding these concepts is fundamental to setting up a simulation in `t8code`, as the `t8_cmesh` is the first major object that needs to be created.
+
+## How to Run
+
+After building the examples, you can run the individual executables. Some may be intended to be run with MPI.
+
+```bash
+# Run a simple example on a single process
+./t8_cmesh_hypercube_pad
+
+# Run a partitioning example with multiple processes
+mpirun -n 4 ./t8_cmesh_partition
+```

example/common/README.md

@@ -0,0 +1,13 @@
+# Common Code for Examples
+
+This folder does not contain a standalone example. Instead, it holds common code, utility functions, and data structures that are shared among the various examples in the `example` directory.
+
+## Files
+
+- `t8_example_common.hxx`: The main header file for the common example code. It likely defines shared data structures, constants, and function prototypes.
+- `t8_example_common.cxx`: The implementation file for the common code. It might contain functions for parsing command-line arguments, setting up MPI, or other boilerplate tasks that are repeated in multiple examples.
+- `t8_example_common_functions.cxx`: This file likely contains more specific utility functions that are used by the examples, for instance, functions to set up specific test cases or analytical solutions.
+
+## Main Purpose
+
+The purpose of this folder is to reduce code duplication across the examples and to keep the individual example files focused on the specific `t8code` feature they are intended to demonstrate. By centralizing common functionality, the examples become cleaner and easier to understand. Developers looking to build their own applications can also find useful utility code here.