READMEs for api, benchmarks and examples

Author: Prasanna-Ponnusamy

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>
+```