diff --git a/api/README.md b/api/README.md new file mode 100644 index 0000000000..d89267d694 --- /dev/null +++ b/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. diff --git a/api/t8_fortran_interface/README.md b/api/t8_fortran_interface/README.md new file mode 100644 index 0000000000..d89267d694 --- /dev/null +++ b/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. diff --git a/benchmarks/README.md b/benchmarks/README.md new file mode 100644 index 0000000000..4d30bbca32 --- /dev/null +++ b/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. diff --git a/example/IO/README.md b/example/IO/README.md new file mode 100644 index 0000000000..c850fc1179 --- /dev/null +++ b/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. diff --git a/example/IO/cmesh/README.md b/example/IO/cmesh/README.md new file mode 100644 index 0000000000..47508932c9 --- /dev/null +++ b/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. diff --git a/example/IO/cmesh/gmsh/README.md b/example/IO/cmesh/gmsh/README.md new file mode 100644 index 0000000000..cf3769ed49 --- /dev/null +++ b/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 + +# Run the load-and-refine example +./t8_load_and_refine_square_w_hole +``` diff --git a/example/IO/cmesh/netcdf/README.md b/example/IO/cmesh/netcdf/README.md new file mode 100644 index 0000000000..3e82abcc82 --- /dev/null +++ b/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`. diff --git a/example/IO/cmesh/tetgen/README.md b/example/IO/cmesh/tetgen/README.md new file mode 100644 index 0000000000..dc1e754355 --- /dev/null +++ b/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 +``` +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. diff --git a/example/IO/cmesh/triangle/README.md b/example/IO/cmesh/triangle/README.md new file mode 100644 index 0000000000..725cf41482 --- /dev/null +++ b/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 +``` diff --git a/example/IO/cmesh/vtk/README.md b/example/IO/cmesh/vtk/README.md new file mode 100644 index 0000000000..d4611dc6f2 --- /dev/null +++ b/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 +``` diff --git a/example/IO/forest/README.md b/example/IO/forest/README.md new file mode 100644 index 0000000000..3cbc65b4fc --- /dev/null +++ b/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. diff --git a/example/IO/forest/gmsh/README.md b/example/IO/forest/gmsh/README.md new file mode 100644 index 0000000000..93c28488e6 --- /dev/null +++ b/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 +``` + +This will produce a VTK file (e.g., `output.vtk`) in the execution directory. diff --git a/example/IO/forest/netcdf/README.md b/example/IO/forest/netcdf/README.md new file mode 100644 index 0000000000..752b961d5e --- /dev/null +++ b/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`. diff --git a/example/advect/README.md b/example/advect/README.md new file mode 100644 index 0000000000..ce0189e47a --- /dev/null +++ b/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. diff --git a/example/cmesh/README.md b/example/cmesh/README.md new file mode 100644 index 0000000000..6bdc4ba157 --- /dev/null +++ b/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 +``` diff --git a/example/common/README.md b/example/common/README.md new file mode 100644 index 0000000000..b7527368c6 --- /dev/null +++ b/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. diff --git a/example/forest/README.md b/example/forest/README.md new file mode 100644 index 0000000000..7f429a0926 --- /dev/null +++ b/example/forest/README.md @@ -0,0 +1,25 @@ +# Forest Examples + +This folder contains examples that demonstrate advanced usage of the `t8_forest` object. The `t8_forest` is the main data structure in `t8code` that manages the adaptively refined mesh. + +## Files + +- `t8_test_face_iterate.cxx`: This example demonstrates how to iterate over the faces of elements in a `t8_forest`. This is a common requirement for numerical methods like Discontinuous Galerkin (DG) or Finite Volume (FV) methods, where fluxes across faces need to be computed. +- `t8_test_ghost.cxx`: A key example that shows how to use the ghost layer functionality. It demonstrates the process of creating a layer of "ghost" elements around the boundary of each MPI process's local domain and then exchanging data with the real owner of those elements. This is fundamental for parallel computations. +- `t8_test_ghost_large_level_diff.cxx`: This is a more specific and advanced version of the ghost test. It sets up a scenario where neighboring elements have a large difference in their refinement levels and then tests the ghost exchange. This ensures that the ghost communication is robust even in cases of extreme mesh adaptation. + +## Main Purpose + +These examples are crucial for developers who are implementing parallel numerical solvers with `t8code`. They provide clear demonstrations of how to perform two of the most important operations on a `t8_forest`: iterating over faces and communicating data between processes using the ghost layer. + +## How to Run + +After building the examples, the executables can be run. The ghost examples are intended to be run with MPI. + +```bash +# Run the face iteration example +./t8_test_face_iterate + +# Run the ghost test with multiple processes +mpirun -n 4 ./t8_test_ghost +``` diff --git a/example/geometry/README.md b/example/geometry/README.md new file mode 100644 index 0000000000..5a9801d019 --- /dev/null +++ b/example/geometry/README.md @@ -0,0 +1,26 @@ +# Geometry Examples + +This folder contains examples that demonstrate how to use different geometry representations within `t8code`. Associating a geometry with a mesh is essential for simulations on domains that are not simple cubes. + +## Files + +- `t8_example_geometries.cxx`: This program showcases how to create and use various types of geometries. It likely includes examples of: + - **Analytical Geometries:** Geometries defined by mathematical formulas, such as a sphere or a cylinder. + - **CAD Geometries:** Geometries loaded from a CAD file (e.g., via OpenCASCADE), which allows for arbitrarily complex shapes. + - **Linear Geometries:** The default, where all boundaries are treated as flat polygons. + +The example probably demonstrates how `t8code` can use this geometric information to correctly handle mesh-to-geometry conformity, which is crucial for accurate boundary conditions and simulations. + +## Main Purpose + +This example is a guide for users who need to run simulations on complex domains. It shows how to set up the geometry object and associate it with the `t8_cmesh`, which is a prerequisite for creating a geometry-conforming adaptive mesh. + +## How to Run + +After building the examples, you can run the executable. Note that to run the CAD-based examples, you must have compiled `t8code` with support for a CAD kernel like OpenCASCADE. + +```bash +./t8_example_geometries +``` + +The program will likely print information to the console about the geometries it creates and the operations it performs. diff --git a/example/remove/README.md b/example/remove/README.md new file mode 100644 index 0000000000..097168de74 --- /dev/null +++ b/example/remove/README.md @@ -0,0 +1,24 @@ +# Element Removal Examples + +This folder contains examples that demonstrate how to dynamically remove elements from a `t8_forest`. This functionality can be used to implement features like moving domains, derefining large areas of the mesh, or handling complex geometries where parts of the domain are "carved out." + +## Files + +- `t8_example_empty_trees.cxx`: This example likely shows how to completely empty one or more trees of the coarse mesh, effectively removing all elements within a certain region of the domain. +- `t8_example_gauss_blob.cxx`: This program probably creates a `t8_forest` and then removes elements based on the value of a Gaussian blob function. For instance, it might remove all elements where the function's value is below a certain threshold, leading to a mesh that only exists where the blob is significant. +- `t8_example_spheres.cxx`: This example likely demonstrates removing elements that are inside or outside of one or more spherical regions, showcasing how to modify the mesh based on geometric criteria. + +## Main Purpose + +These examples are for advanced users who need more than just standard refinement and coarsening. The ability to dynamically remove elements from the mesh is powerful for certain classes of problems, such as fluid-structure interaction or simulations with changing domain boundaries. + +## How to Run + +After building the examples, you can run the individual executables. They may be intended to be run with MPI. + +```bash +# Run the spheres example with multiple processes +mpirun -n 4 ./t8_example_spheres +``` + +The output will likely be a set of VTK files that you can visualize in ParaView or VisIt to see the resulting mesh with elements removed. diff --git a/example/version/README.md b/example/version/README.md new file mode 100644 index 0000000000..6dda3d6675 --- /dev/null +++ b/example/version/README.md @@ -0,0 +1,24 @@ +# Version Example + +This folder contains a simple example that demonstrates how to query the version information of the `t8code` library that your application is linked against. + +## Files + +- `t8_version.cxx`: This program calls the `t8code` version functions and prints the library's version number, git commit hash, and other relevant information to the console. + +## Main Purpose + +This example showcases a simple but important piece of functionality. Being able to programmatically access the library version is crucial for: +- **Reproducibility:** Logging the exact version of `t8code` used in a simulation is essential for ensuring that results can be reproduced later. +- **Debugging:** When reporting bugs, knowing the precise version of the library is vital for developers to understand the context of the issue. +- **Feature Checking:** An application could potentially check the `t8code` version to ensure that a required feature is available. + +## How to Run + +After building the examples, you can simply run the executable: + +```bash +./t8_version +``` + +It will print the `t8code` version details to standard output. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000000..18cd07c931 --- /dev/null +++ b/src/README.md @@ -0,0 +1,34 @@ +# t8code Source + +This directory contains the core source code of the `t8code` library. The code is organized into modules, each corresponding to a specific functionality. + +## Subfolders (Modules) + +- [**t8_cmesh/**](t8_cmesh/README.md): The coarse mesh module. It is responsible for storing and managing the initial, unadapted mesh. +- [**t8_data/**](t8_data/README.md): Data management module, including the `t8_data_handler` for user-defined data on elements. +- [**t8_forest/**](t8_forest/README.md): The core module of `t8code`. It implements the adaptive forest of trees, handling mesh refinement, coarsening, partitioning, and ghost element exchange. +- [**t8_geometry/**](t8_geometry/README.md): The geometry module, which provides an interface for handling various geometric representations of the domain. +- [**t8_schemes/**](t8_schemes/README.md): This module defines the refinement and connectivity rules for different element types (e.g., tetrahedra, hexahedra). +- [**t8_types/**](t8_types/README.md): Contains definitions for custom data types and structures used throughout `t8code`. +- [**t8_vector_helper/**](t8_vector_helper/README.md): Provides helper functions for vector manipulations. +- [**t8_vtk/**](t8_vtk/README.md): Contains code for writing data in the VTK format for visualization. + +## Main Files + +In addition to the modules in the subfolders, this directory contains some of the main header files and source files for the library: + +- `t8.h`: The main public header file for the `t8code` C API. This is the primary entry point for users of the library. +- `t8.c`: Implementation of some of the general functions declared in `t8.h`. +- `t8_cmesh.h`, `t8_forest.h`, etc.: Public header files for the specific modules. +- `t8_eclass.h`, `t8_element.h`: Header files defining the element classes and element data structures. + +## Developer Entry Points + +For developers looking to understand the library, the main entry points are: +- `t8.h`: To understand the public API. +- `t8_forest.h`: To understand the main `t8_forest` data structure and its functions. +- The `README.md` file in each subdirectory for a detailed description of that module. + +## Related Wiki Articles + +For a higher-level overview of the architecture and concepts, please refer to the [t8code wiki](https://github.com/DLR-AMR/t8code/wiki). diff --git a/src/t8_cmesh/README.md b/src/t8_cmesh/README.md new file mode 100644 index 0000000000..6e135e9265 --- /dev/null +++ b/src/t8_cmesh/README.md @@ -0,0 +1,47 @@ +# t8_cmesh Module + +The `t8_cmesh` module is responsible for managing the coarse mesh, which is the initial, unadapted, and partitioned representation of the simulation domain. The `t8_cmesh_t` data structure, defined here, stores the geometry and connectivity of the coarse elements (e.g., tetrahedra, hexahedra) and how they are distributed among MPI processes. + +The `t8_cmesh` serves as the foundation upon which the adaptive `t8_forest` is built. + +## Subfolders +- [**t8_cmesh_vertex_connectivity/**](t8_cmesh_vertex_connectivity/README.md): Contains the implementation for building and querying vertex-based connectivity information for the coarse mesh. + +## Key Files and Functionalities + +The functionality of the `t8_cmesh` module is split across several files: + +- **Core Cmesh Object:** + - `t8_cmesh_types.h`: Defines the `t8_cmesh_t` struct and other related data types. + - `t8_cmesh.cxx`: Implements the core functions for creating, querying, and destroying a `t8_cmesh`. + +- **I/O and Mesh Generation:** + - `t8_cmesh_readmshfile.cxx`: Handles reading coarse meshes from Gmsh `.msh` files. + - `t8_cmesh_triangle.cxx`: Contains functionality for reading 2D meshes from the Triangle mesh generator. + - `t8_cmesh_netcdf.c`: Implements reading/writing of cmesh data from/to NetCDF files. + - `t8_cmesh_examples.cxx`/`.h`: Provides functions to generate various example cmeshes programmatically. + - `t8_cmesh_save.cxx`/`.h`: Implements functionality for saving a `t8_cmesh` to a file. + +- **Partitioning and Distribution:** + - `t8_cmesh_partition.cxx`/`.h`: Implements the logic for partitioning a serial cmesh and distributing it across MPI processes. + - `t8_cmesh_offset.c`/`.h`: Manages the offsets used to describe data distribution in parallel. + +- **Geometry and CAD Interface:** + - `t8_cmesh_geometry.cxx`/`.hxx`: Contains the logic for associating a `t8_geometry` object with the cmesh. + - `t8_cmesh_cad.cxx`/`.hxx`: Implements the specific interface for handling geometries from CAD kernels. + +- **Internal Operations:** + - `t8_cmesh_commit.cxx`: Implements the `t8_cmesh_commit` function, which finalizes the cmesh after it has been created and partitioned. + - `t8_cmesh_copy.c`/`.h`: Provides functions to create a copy of a `t8_cmesh`. + - `t8_cmesh_trees.cxx`/`.h`: Manages the trees of the cmesh. Each tree corresponds to a single element in the original, unpartitioned mesh. + - `t8_cmesh_helpers.cxx`/`.h`: A collection of utility and helper functions for internal use. + - `t8_cmesh_stash.c`/`.h`: Implements a "stash" data structure, likely used for temporarily storing and communicating mesh data during construction. + +## Main Entry Points for Developers + +A developer working with the `t8_cmesh` would typically start by: +1. Creating a `t8_cmesh` instance, either from a file (`t8_cmesh_from_msh_file`) or programmatically (`t8_cmesh_new_...`). +2. Finalizing the mesh with `t8_cmesh_commit`. +3. Using the committed `t8_cmesh` to build a `t8_forest`. + +The public API for these operations is primarily found in `src/t8_cmesh.h`. Internal implementation details are in the files listed above. diff --git a/src/t8_cmesh/t8_cmesh_vertex_connectivity/README.md b/src/t8_cmesh/t8_cmesh_vertex_connectivity/README.md new file mode 100644 index 0000000000..0f5a024061 --- /dev/null +++ b/src/t8_cmesh/t8_cmesh_vertex_connectivity/README.md @@ -0,0 +1,30 @@ +# cmesh Vertex Connectivity + +This sub-module of `t8_cmesh` is responsible for building and querying explicit connectivity information based on the vertices of the coarse mesh. This information is not always needed by default, but it is crucial for certain algorithms that require knowledge about which elements share a common vertex. + +## Key Data Structures and Functionality + +The core of this module is the `t8_cmesh_vertex_connectivity_t` data structure, which stores the relationships between vertices and the coarse mesh trees (elements). + +- `t8_cmesh_vertex_connectivity_types.hxx`: Defines the `t8_cmesh_vertex_connectivity_t` struct and other related types. +- `t8_cmesh_vertex_connectivity.cxx`/`.h`/`.hxx`: Contains the main functions to build, query, and destroy the vertex connectivity data structure. The `t8_cmesh_vertex_connectivity_new` function is the main entry point, which takes a `t8_cmesh` and constructs the full connectivity information. + +The connectivity information is stored in two primary forms: + +1. **Tree-to-Vertex Mapping:** This allows for quickly finding the global vertex indices that make up a given coarse mesh tree. + - `t8_cmesh_vertex_conn_tree_to_vertex.cxx`/`.hxx`: Implements the logic to build and access this part of the connectivity data. + +2. **Vertex-to-Tree Mapping:** This is the inverse mapping, which allows for finding all coarse mesh trees that share a specific vertex. This is often the more complex and useful part of the data structure. + - `t8_cmesh_vertex_conn_vertex_to_tree.cxx`/`.hxx`: Implements the logic to build and access this inverse mapping. + +## Main Purpose + +The main purpose of this module is to provide answers to questions like: +- "Which elements are neighbors of element X around vertex Y?" +- "Which elements share this specific vertex?" + +This information is vital for some numerical schemes, mesh quality checks, and advanced partitioning algorithms that operate on the coarse mesh. Since building this data structure has a computational cost, it is handled in a separate module and only computed when explicitly requested by the user or another algorithm. + +## Developer Entry Points + +A developer would typically call `t8_cmesh_vertex_connectivity_new` to build the connectivity data for a given `t8_cmesh`. They could then use the query functions provided in `t8_cmesh_vertex_connectivity.h` to access the connectivity information. Finally, they would call `t8_cmesh_vertex_connectivity_destroy` to free the associated memory. diff --git a/src/t8_data/README.md b/src/t8_data/README.md new file mode 100644 index 0000000000..8c20cd026b --- /dev/null +++ b/src/t8_data/README.md @@ -0,0 +1,33 @@ +# t8_data Module + +The `t8_data` module provides a collection of tools and data structures for managing data within `t8code`. Its most important component is the `t8_data_handler`, which provides the mechanism for users to attach their own application-specific data (e.g., solution variables, material properties) to the elements of a `t8_forest`. + +## Key Files and Functionalities + +- **User Data Management:** + - `t8_data_handler.hxx`: This header-only file defines the `t8_data_handler_t`, a templated class that manages a block of memory for user data, with one entry per local element in the `t8_forest`. It handles allocation, resizing (during mesh adaptation), and provides easy access to the data for a given element. + - `t8_vector_handler.hxx`: A specialized version of a data handler for when the user data is a vector. + +- **General Data Structures:** + - `t8_containers.c`/`.h`: Implements general-purpose data containers, such as dynamic arrays, that are used throughout `t8code`. + - `t8_element_array_iterator.hxx`: Provides a convenient iterator for traversing arrays of elements. + +- **Parallel Data Utilities:** + - `t8_shmem.c`/`.h`: Implements utilities for using shared memory (`shmem`). This allows for more efficient data sharing between MPI processes that are running on the same physical node, avoiding unnecessary memory copies. + +- **CAD Data Handling:** + - `t8_cad.cxx`/`.hxx`: Contains functions for handling data associated with CAD geometries. While the main geometry logic is in the `t8_geometry` module, this part likely deals with storing and managing auxiliary data related to CAD entities. + +## Main Purpose + +The primary purpose of this module is to abstract away the complexities of managing data on a dynamic, distributed mesh. When the mesh is adapted (elements are created or destroyed) or re-partitioned, the `t8_data_handler` automatically ensures that the user's data arrays are correctly resized and that the data remains associated with the correct logical element. + +## Developer Entry Points + +A developer wanting to store data on the forest would: +1. Include `t8_data_handler.hxx`. +2. Instantiate a `t8_data_handler_t` for their specific data type, providing it with a `t8_forest` pointer. +3. Access the data for a specific element `i` using the `[]` operator on the data handler instance. +4. The data handler will automatically be updated when the forest is adapted or partitioned. + +The public interfaces for the data structures and utilities are found in their respective header files (`.h` or `.hxx`). diff --git a/src/t8_forest/README.md b/src/t8_forest/README.md new file mode 100644 index 0000000000..5d77bdc2b5 --- /dev/null +++ b/src/t8_forest/README.md @@ -0,0 +1,52 @@ +# t8_forest Module + +The `t8_forest` module is the heart of `t8code`. It implements the core data structure, `t8_forest_t`, which represents a collection (a "forest") of adaptive refinement trees. Each tree is built upon a coarse element from the `t8_cmesh`. This module contains the logic for all the fundamental operations of a dynamic, parallel adaptive mesh refinement (AMR) framework. + +## Subfolders +- [**t8_forest_search/**](t8_forest_search/README.md): Contains the implementation of algorithms for searching within the forest, such as finding the process that owns a specific point in space. + +## Key Files and Functionalities + +The `t8_forest` is a complex module whose functionality is broken down into several logical components: + +- **Core Forest Management:** + - `t8_forest_types.h`: Defines the `t8_forest_t` struct, the central data structure that manages the entire adaptive mesh. + - `t8_forest.h`: The main public C-API header for the forest. It contains the primary functions for creating, querying, and managing a `t8_forest`. + - `t8_forest.cxx`: Implementation of the core forest management functions. + - `t8_forest_private.h`/`.cxx`: Contains internal functions and data structures that are not part of the public API but are used by other forest components. + +- **Dynamic Adaptation:** + - `t8_forest_adapt.h`/`.cxx`: Implements the functions for mesh adaptation. This includes refining a set of elements (dividing them into children) and coarsening them (replacing children with their parent). This is where the `t8_forest_adapt` and `t8_forest_coarsen` functions are implemented. + - `t8_forest_balance.h`/`.cxx`: Implements the 2:1 balancing algorithm. After adaptation, the forest must be "balanced" to ensure that no leaf element is adjacent to a non-parent element that is more than twice its size. This is essential for the validity of many numerical schemes. + +- **Parallelism and Communication:** + - `t8_forest_partition.h`/`.cxx`: Implements functions to re-partition the forest. When the mesh is adapted, the workload may become unbalanced across MPI processes. These functions redistribute the elements of the forest to re-balance the load. + - `t8_forest_ghost.h`/`.cxx`: Implements the ghost layer functionality. It provides functions to build a layer of ghost elements along the boundaries of each process's subdomain and to exchange data stored on those elements. This is the primary mechanism for inter-process communication. + +- **Iteration and Traversal:** + - `t8_forest_iterate.h`/`.cxx`: Provides powerful and flexible iterators for traversing the elements and faces of the forest. These iterators are the main tool for developers implementing numerical solvers, as they provide access to the mesh entities and their neighborhood information. + +- **I/O:** + - `t8_forest_io.h`: Header file for I/O operations related to the forest. + - `t8_forest_netcdf.cxx`: Implementation for saving a `t8_forest` to a NetCDF file. + +- **Helper Headers:** + - `t8_forest_general.h`: A collection of general-purpose forest functions. + - `t8_forest_geometrical.h`: A collection of functions related to the geometry of the forest elements (e.g., computing volumes, face normals). + - `t8_forest_profiling.h`: Contains tools for profiling the performance of forest operations. + +## Developer Workflow + +A typical developer workflow using the `t8_forest` module looks like this: + +1. **Initialization:** Create a `t8_forest` from a `t8_cmesh` using `t8_forest_new_from_cmesh`. +2. **Adaptation Loop:** + a. **Solve:** Use the iterators (`t8_forest_iterate_...`) to perform calculations on the current mesh. + b. **Mark:** Decide which elements need to be refined or coarsened based on the solution. + c. **Adapt:** Call `t8_forest_adapt` and/or `t8_forest_coarsen` to modify the mesh. + d. **Balance:** Call `t8_forest_balance` to ensure the mesh is valid. + e. **Partition (Optional):** Call `t8_forest_partition` to re-balance the workload. + f. **Update Ghosts:** Re-build the ghost layer and exchange data for the new mesh configuration. +3. **Finalization:** Destroy the forest using `t8_forest_unref`. + +The main public API functions are declared in `t8_forest.h` and the other public header files in this directory. diff --git a/src/t8_forest/t8_forest_search/README.md b/src/t8_forest/t8_forest_search/README.md new file mode 100644 index 0000000000..de3e79b079 --- /dev/null +++ b/src/t8_forest/t8_forest_search/README.md @@ -0,0 +1,35 @@ +# t8_forest_search Module + +This module provides the implementation for search algorithms within a `t8_forest`. The primary and most critical functionality is the parallel point location search, which is the process of finding which element in the distributed forest contains a given point in space. + +This capability is essential for many applications, such as: +- Particle-in-cell methods, to determine which mesh element a particle is in. +- Probing simulation results at arbitrary coordinates. +- Interpolating solution data from the mesh nodes to off-mesh locations. + +## Key Files and Functionality + +The implementation is contained within three main files: + +- `t8_forest_search.h`: The public C-API header file. This is the main entry point for developers, declaring the functions needed to initiate a search, such as `t8_forest_search_points`. +- `t8_forest_search.cxx`: The C++ implementation of the parallel search algorithm. +- `t8_forest_search.hxx`: An internal C++ header file, likely containing helper classes and functions used by the main implementation. + +## The Parallel Search Algorithm + +Finding a point in a distributed, adaptively refined forest is a non-trivial task. The algorithm implemented here is a sophisticated parallel procedure that typically involves these steps: + +1. **Initiation:** One or more processes initiate a search for a set of points. +2. **Local Search:** Each process first searches for the points within its own local domain. +3. **Parallel Routing:** For points that are not found locally, the algorithm must determine which other process owns them. This is often done by a routing process, where a query for a point is forwarded between processes based on their geometric domains until the owner is found. +4. **Tree-based Search:** Once a query arrives at the correct process, the search within that process's local elements is accelerated by leveraging the tree-based structure of the `t8_forest`. + +The implementation is designed to be efficient and scalable, minimizing communication overhead. + +## Developer Entry Points + +A developer would use this module's functionality by calling the functions defined in `t8_forest_search.h`. The typical workflow is: + +1. Prepare an array of points to be located. +2. Call `t8_forest_search_points`, passing in the `t8_forest`, the array of points, and arrays to be filled with the results. +3. The function will return the process rank and the local element ID for each point found. It will also indicate if a point was not found within the domain. diff --git a/src/t8_geometry/README.md b/src/t8_geometry/README.md new file mode 100644 index 0000000000..bd8b5a218d --- /dev/null +++ b/src/t8_geometry/README.md @@ -0,0 +1,35 @@ +# t8_geometry Module + +The `t8_geometry` module provides the framework for representing and interacting with the geometric description of the simulation domain. `t8code` is designed to work with domains that are more complex than simple cubes, including those with curved boundaries. This module provides a flexible, abstract interface that allows the core mesh algorithms to query geometric information without being tied to a specific geometry representation. + +The central concept is the `t8_geometry_t` object, which is an abstract representation of a geometry. Concrete implementations (e.g., for an analytical sphere, or a complex shape from a CAD file) inherit from a common base class and implement a standard set of geometric queries. + +## Subfolders +- [**t8_geometry_implementations/**](t8_geometry_implementations/README.md): Contains the source code for various concrete implementations of the `t8_geometry` interface. + +## Key Files and Functionalities + +- **Abstract Geometry Interface:** + - `t8_geometry.h`: The main public C-API header for the geometry module. It defines the `t8_geometry_t` type and the functions that users can call to interact with a geometry object. + - `t8_geometry.cxx`: The implementation of the public API functions. These functions typically delegate their work to the virtual functions defined in the base class. + - `t8_geometry_base.h`/`.cxx`/`.hxx`: Defines the abstract base class for all geometry implementations. It specifies the virtual function table (vtable) that each concrete geometry must provide. This includes functions for evaluating surface parameterizations, checking if a point is inside the domain, and other geometric queries. + +- **Geometry Management:** + - `t8_geometry_handler.cxx`/`.hxx`: Implements a handler class that is responsible for managing the lifecycle of geometry objects. + - `t8_geometry_hash.hxx`: Provides hashing functions for geometries, which can be used to efficiently compare or store them. + +- **Specific Geometry Types:** + - `t8_geometry_with_vertices.h`/`.cxx`/`.hxx`: A specialized geometry implementation that is defined explicitly by a set of vertices. This is often used to represent piecewise linear geometries. + +- **Utilities:** + - `t8_geometry_helpers.c`/`.h`: A collection of helper and utility functions for geometric calculations. + - `t8_geometry_extended.hxx`: Contains declarations for more advanced or extended geometry functionalities, often for internal C++ usage. + +## Developer Workflow + +A developer using this module would typically: +1. Create an instance of a concrete geometry (e.g., `t8_geometry_new_analytic` or `t8_geometry_new_occ`). The functions to do this are found in the `t8_geometry_implementations` module. +2. Associate this `t8_geometry_t` object with a `t8_cmesh`. +3. The `t8_forest` will then use this geometry information during adaptation and other operations to ensure that the mesh conforms to the domain boundaries. For example, when a new child element is created on a curved boundary, its nodes will be projected onto the true surface representation provided by the `t8_geometry` object. + +The public API is defined in `t8_geometry.h`. The interface that new geometry implementations must satisfy is defined in `t8_geometry_base.h`. diff --git a/src/t8_geometry/t8_geometry_implementations/README.md b/src/t8_geometry/t8_geometry_implementations/README.md new file mode 100644 index 0000000000..dbc2ca38f1 --- /dev/null +++ b/src/t8_geometry/t8_geometry_implementations/README.md @@ -0,0 +1,36 @@ +# Concrete Geometry Implementations + +This folder contains the source code for several concrete implementations of the `t8_geometry` abstract base class. Each implementation represents a different way to define a geometric domain. Users can choose the implementation that best suits their needs. + +The public functions to create instances of these geometries (e.g., `t8_geometry_new_analytic`) are declared in the `.h` files in this directory. + +## Geometry Implementations + +- **`t8_geometry_analytic`**: + - `t8_geometry_analytic.h`/`.cxx`/`.hxx` + - This implementation is for geometries that can be described by a mathematical formula. The user provides function pointers that define the geometry, such as a level-set function (`phi(x,y,z) = 0` for the surface) and its gradient. This is useful for simple, well-defined shapes like spheres, cylinders, or tori. + +- **`t8_geometry_cad`**: + - `t8_geometry_cad.h`/`.cxx`/`.hxx` + - This is a powerful implementation that interfaces with a CAD (Computer-Aided Design) kernel, such as OpenCASCADE. It allows `t8code` to use complex, industry-standard CAD models as the simulation domain. This is the preferred method for complex, real-world geometries. Note that this requires `t8code` to be compiled with CAD support. + +- **`t8_geometry_lagrange`**: + - `t8_geometry_lagrange.h`/`.cxx`/`.hxx` + - This implementation represents the geometry using high-order Lagrange polynomials. This is used to represent curved surfaces with high fidelity and is often used in high-order numerical methods. + +- **`t8_geometry_linear`**: + - `t8_geometry_linear.h`/`.cxx`/`.hxx` + - This represents the geometry as a collection of flat, linear facets. It is a piecewise linear representation of the domain. + - `t8_geometry_linear_axis_aligned.h`/`.cxx`/`.hxx`: A specialized and optimized version for linear geometries that are aligned with the coordinate axes. + +- **`t8_geometry_zero`**: + - `t8_geometry_zero.h`/`.cxx`/`.hxx` + - This is a "null" or "do-nothing" geometry implementation. It essentially provides no geometric information. This is used as a default when no other geometry is specified, and it effectively means the domain is defined purely by the straight-edged elements of the coarse mesh. + +- **`t8_geometry_examples`**: + - `t8_geometry_examples.h`/`.cxx`/`.hxx` + - This file does not provide a new geometry implementation itself, but rather contains functions that create instances of various example geometries (like a brick, sphere, etc.) using the other implementations. This is used by the example programs and for testing. + +## Developer Entry Points + +To use one of these geometries, a developer would include the relevant header file (e.g., `t8_geometry_analytic.h`) and call its constructor function (e.g., `t8_geometry_new_analytic(...)`), passing the required parameters. The resulting `t8_geometry_t*` can then be passed to `t8_cmesh_set_geometry`. diff --git a/src/t8_schemes/README.md b/src/t8_schemes/README.md new file mode 100644 index 0000000000..00629af141 --- /dev/null +++ b/src/t8_schemes/README.md @@ -0,0 +1,33 @@ +# t8_schemes Module + +The `t8_schemes` module is a fundamental part of `t8code`'s combinatorial engine. A "scheme" defines the rules for how an element of a certain shape is refined and how its descendants (children, faces, etc.) are numbered and related to each other. For example, the scheme for a tetrahedron defines that it is refined into 8 child tetrahedra and describes the orientation and connectivity of those children. + +`t8code` uses this information for all its tree-based navigation and neighborhood queries. By abstracting these rules into a scheme, the core algorithms in `t8_forest` can be written in a generic way that is independent of any specific element shape. + +## Subfolders + +- [**t8_default/**](t8_default/README.md): Contains the source code for the default, built-in refinement schemes used by `t8code` for standard element shapes like tetrahedra, hexahedra, prisms, and pyramids. +- [**t8_standalone/**](t8_standalone/README.md): Contains a standalone implementation of the schemes that can be compiled and used independently of the rest of `t8code`. This is useful for testing, debugging, and potentially for other tools that need to work with `t8code`'s refinement patterns. + +## Key Files and Functionality + +- **Scheme Interface:** + - `t8_scheme.h`: The public C-API header. It defines the `t8_scheme_cxx_t` object and provides functions to query properties of a scheme, such as the number of children an element has, the number of faces, etc. + - `t8_scheme.hxx`: The internal C++ header that defines the `t8_scheme_cxx` class, which is the C++ interface for a refinement scheme. + - `t8_scheme.cxx`: The implementation of the C-API functions, which wrap the C++ class methods. + +- **Scheme Construction:** + - `t8_scheme_builder.hxx`: A header file containing a builder class used to construct a `t8_scheme_cxx` object from its raw connectivity data. This is an internal tool used when defining a new scheme. + +## Main Purpose + +The main purpose of this module is to provide a lookup-table-based mechanism for all combinatorial queries related to mesh refinement. Instead of having complex geometric logic scattered throughout the code, `t8code` can simply ask the scheme: "If I refine this face, what are the child faces?" or "What is the parent of child number 5?". This makes the core algorithms clean, fast, and extensible to new element types. + +## Developer Entry Points + +Most developers will not need to interact with this module directly. The `t8_forest` module uses the schemes internally. The only time a developer would work with this module is if they wanted to add support for a completely new element type with a custom refinement pattern. In that case, they would need to: +1. Define the connectivity tables for their new element type. +2. Use the `t8_scheme_builder` to construct a new `t8_scheme_cxx` instance. +3. Register this new scheme with `t8code`. + +The public query interface is in `t8_scheme.h`. diff --git a/src/t8_schemes/t8_default/README.md b/src/t8_schemes/t8_default/README.md new file mode 100644 index 0000000000..7b88fb7f8d --- /dev/null +++ b/src/t8_schemes/t8_default/README.md @@ -0,0 +1,31 @@ +# Default Schemes + +This directory provides the concrete implementations for `t8code`'s standard, built-in refinement schemes. Each supported element shape (tetrahedron, hexahedron, etc.) has its own subdirectory containing the raw, hard-coded connectivity data that defines its refinement pattern. + +These schemes are initialized once when `t8code` is set up and are then made available to the rest of the library. + +## Subfolders + +Each subfolder contains the raw connectivity data (in the form of static C arrays) for a specific element shape, known in `t8code` as an `eclass`. + +- [**t8_default_common/**](t8_default_common/README.md): Common data and definitions shared by all default schemes. +- [**t8_default_line/**](t8_default_line/README.md): Connectivity data for a 1D Line element. +- [**t8_default_quad/**](t8_default_quad/README.md): Connectivity data for a 2D Quadrangle element. +- [**t8_default_tri/**](t8_default_tri/README.md): Connectivity data for a 2D Triangle element. +- [**t8_default_hex/**](t8_default_hex/README.md): Connectivity data for a 3D Hexahedron element. +- [**t8_default_prism/**](t8_default_prism/README.md): Connectivity data for a 3D Prism element. +- [**t8_default_pyramid/**](t8_default_pyramid/README.md): Connectivity data for a 3D Pyramid element. +- [**t8_default_tet/**](t8_default_tet/README.md): Connectivity data for a 3D Tetrahedron element. +- [**t8_default_vertex/**](t8_default_vertex/README.md): Connectivity data for a 0D Vertex element. + +## Key Files + +- `t8_default_c_interface.h`: The public C-API header that provides access to the default schemes. It contains functions like `t8_scheme_new_default_tet()` which return a `t8_scheme_cxx_t` object for a given element type. +- `t8_default.hxx`: The internal C++ header that orchestrates the creation of the default scheme objects from the raw data in the subdirectories. +- `t8_default.cxx`: The C++ implementation file for creating the default schemes. + +## Main Purpose + +This directory is the ultimate source of truth for the combinatorial topology of `t8code`. The static arrays in the subdirectories are the lookup tables that the `t8_forest` module consults for all its operations. For example, when a hexahedron is refined, `t8_forest` queries the `t8_default_hex` scheme to find out the coordinates and face connectivity of the 8 child hexahedra. + +A deep understanding of these files is only necessary for developers who are debugging the lowest levels of the refinement logic or who are interested in the mathematical details of the space-filling curve and refinement patterns. diff --git a/src/t8_schemes/t8_default/t8_default_common/README.md b/src/t8_schemes/t8_default/t8_default_common/README.md new file mode 100644 index 0000000000..349054a879 --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_common/README.md @@ -0,0 +1,11 @@ +# Default Scheme Common Data + +This folder contains common data and definitions that are shared across all the default refinement schemes. + +## Files + +- `t8_default_common.hxx`: This header file likely contains C++ templates, macros, or other helper constructs that are used to build the static connectivity tables in the other `t8_default_*` directories. By factoring out the common code, it reduces duplication and makes the scheme definitions more concise and maintainable. + +## Main Purpose + +The purpose of this file is to provide a common foundation for the definition of the various default schemes. It is an internal implementation detail and is not intended for direct use by developers outside of the `t8_schemes` module. diff --git a/src/t8_schemes/t8_default/t8_default_hex/README.md b/src/t8_schemes/t8_default/t8_default_hex/README.md new file mode 100644 index 0000000000..d51d0df755 --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_hex/README.md @@ -0,0 +1,24 @@ +# Hexahedron Default Scheme + +This directory contains the implementation of the default refinement scheme for a **hexahedron**. + +## Functionality + +The files in this directory define the precise combinatorial rules for the refinement of a hexahedral element. Specifically, they encode the following information: + +- A hexahedron is refined into 8 child hexahedra. +- The orientation, position, and numbering of these 8 children relative to their parent. +- The relationship between the parent's faces and the children's faces. +- The connectivity between the child elements themselves. + +This information is stored in a series of static lookup tables. + +## Files + +- `t8_default_hex.cxx`/`.hxx`: These files contain the primary static arrays that define the hexahedron scheme. They use the `t8_scheme_builder` to construct the final scheme object from these arrays. +- `t8_dhex.h`: Public header for the default hexahedron scheme, providing access to its specific properties. +- `t8_dhex_bits.c`/`.h`: These files contain low-level, bitwise manipulation functions. The refinement pattern for a hexahedron is isomorphic to a 3D Morton (or Z-order) curve, which can be implemented very efficiently using bitwise operations. These files encapsulate that logic. + +## Main Purpose + +This is a low-level, internal component of `t8code`. The `t8_forest` module consults these lookup tables whenever it needs to perform a topological operation (like finding a neighbor or a child) on a hexahedral element. The use of pre-computed tables and efficient bitwise logic makes these operations extremely fast. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_line/README.md b/src/t8_schemes/t8_default/t8_default_line/README.md new file mode 100644 index 0000000000..e724706b36 --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_line/README.md @@ -0,0 +1,19 @@ +# Line Default Scheme + +This directory contains the implementation of the default refinement scheme for a **1D Line** element. + +## Functionality + +The files in this directory define the combinatorial rules for the refinement of a line segment. Specifically, they encode that a line is refined into 2 child lines and describe the numbering and connectivity of those children. + +This information is stored in static lookup tables. + +## Files + +- `t8_default_line.cxx`/`.hxx`: These files contain the static arrays that define the line scheme and use the `t8_scheme_builder` to construct the final scheme object. +- `t8_dline.h`: Public header for the default line scheme. +- `t8_dline_bits.c`/`.h`: These files contain low-level, bitwise manipulation functions for the 1D space-filling curve (which is trivial in 1D but follows the same pattern as the other schemes). + +## Main Purpose + +This is a low-level, internal component of `t8code`. The `t8_forest` module consults these lookup tables for topological operations on 1D elements. This is primarily used for testing or for applications involving 1D domains. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_prism/README.md b/src/t8_schemes/t8_default/t8_default_prism/README.md new file mode 100644 index 0000000000..281d765062 --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_prism/README.md @@ -0,0 +1,24 @@ +# Prism Default Scheme + +This directory contains the implementation of the default refinement scheme for a **prism** element. + +## Functionality + +The files in this directory define the precise combinatorial rules for the refinement of a prism-shaped element. Specifically, they encode the following information: + +- A prism is refined into 8 child prisms. +- The orientation, position, and numbering of these 8 children relative to their parent. +- The relationship between the parent's faces and the children's faces. +- The connectivity between the child elements themselves. + +This information is stored in a series of static lookup tables. + +## Files + +- `t8_default_prism.cxx`/`.hxx`: These files contain the primary static arrays that define the prism scheme. They use the `t8_scheme_builder` to construct the final scheme object from these arrays. +- `t8_dprism.h`: Public header for the default prism scheme, providing access to its specific properties. +- `t8_dprism_bits.c`/`.h`: These files contain low-level, bitwise manipulation functions that implement the logic of the space-filling curve for the prism's unique topology (a product of a triangle and a line). + +## Main Purpose + +This is a low-level, internal component of `t8code`, essential for supporting hybrid meshes containing prisms. The `t8_forest` module consults these lookup tables whenever it needs to perform a topological operation on a prism element. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_pyramid/README.md b/src/t8_schemes/t8_default/t8_default_pyramid/README.md new file mode 100644 index 0000000000..22476cdd8b --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_pyramid/README.md @@ -0,0 +1,25 @@ +# Pyramid Default Scheme + +This directory contains the implementation of the default refinement scheme for a **pyramid** element. The refinement of a pyramid is particularly complex compared to other element types. + +## Functionality + +The files in this directory define the precise combinatorial rules for the refinement of a pyramid-shaped element. Unlike other element types which refine into children of the same shape, the `t8code` pyramid scheme refines a parent pyramid into a collection of **10 child elements: 6 tetrahedra and 4 pyramids**. + +This directory encodes all the information about this complex refinement, including: +- The type, orientation, position, and numbering of the 10 children relative to their parent. +- The relationship between the parent's faces and the children's faces. +- The connectivity between the child elements themselves. + +This information is stored in a series of static lookup tables. + +## Files + +- `t8_default_pyramid.cxx`/`.hxx`: These files contain the primary logic that uses the `t8_scheme_builder` to construct the final scheme object from the raw connectivity data. +- `t8_dpyramid.h`: Public header for the default pyramid scheme, providing access to its specific properties. +- `t8_dpyramid_connectivity.c`/`.h`: These files contain the large, explicit, hard-coded lookup tables that define the complex connectivity of the 10-child refinement pattern. +- `t8_dpyramid_bits.c`/`.h`: These files contain low-level, bitwise manipulation functions that implement the logic of the space-filling curve adapted for the pyramid's topology. + +## Main Purpose + +This is a low-level, internal component of `t8code`, essential for supporting hybrid meshes containing pyramids. The complexity of the files reflects the inherent difficulty in conformally refining a pyramid. The `t8_forest` module consults these lookup tables whenever it needs to perform a topological operation on a pyramid element. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_quad/README.md b/src/t8_schemes/t8_default/t8_default_quad/README.md new file mode 100644 index 0000000000..d6948993ca --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_quad/README.md @@ -0,0 +1,24 @@ +# Quadrangle Default Scheme + +This directory contains the implementation of the default refinement scheme for a **quadrangle (quad)** element. + +## Functionality + +The files in this directory define the precise combinatorial rules for the refinement of a quadrilateral element. Specifically, they encode the following information: + +- A quad is refined into 4 child quads. +- The orientation, position, and numbering of these 4 children relative to their parent. +- The relationship between the parent's edges and the children's edges. +- The connectivity between the child elements themselves. + +This information is stored in a series of static lookup tables. + +## Files + +- `t8_default_quad.cxx`/`.hxx`: These files contain the primary static arrays that define the quad scheme and use the `t8_scheme_builder` to construct the final scheme object. +- `t8_dquad.h`: Public header for the default quad scheme, providing access to its specific properties. +- `t8_default_quad_bits.cxx`/`.hxx`: These files contain low-level, bitwise manipulation functions. The refinement pattern for a quad is isomorphic to a 2D Morton (or Z-order) curve, which is implemented here with efficient bitwise operations. + +## Main Purpose + +This is a low-level, internal component of `t8code`. The `t8_forest` module consults these lookup tables whenever it needs to perform a topological operation (like finding a neighbor or a child) on a quad element. This is essential for 2D simulations or for handling quad faces in 3D. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_tet/README.md b/src/t8_schemes/t8_default/t8_default_tet/README.md new file mode 100644 index 0000000000..dc7d0be4e5 --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_tet/README.md @@ -0,0 +1,26 @@ +# Tetrahedron Default Scheme + +This directory contains the implementation of the default refinement scheme for a **tetrahedron**. This is one of the most important schemes for 3D simulations. + +## Functionality + +The files in this directory define the precise combinatorial rules for the refinement of a tetrahedral element. Specifically, they encode the following information: + +- A tetrahedron is refined into 8 child tetrahedra. +- The orientation, position, and numbering of these 8 children relative to their parent. +- The relationship between the parent's triangular faces and the children's faces. +- The connectivity between the child elements themselves. + +This information is stored in a series of static lookup tables. + +## Files + +- `t8_default_tet.cxx`/`.hxx`: These files contain the primary logic that uses the `t8_scheme_builder` to construct the final scheme object from the raw connectivity data. +- `t8_dtet.h`: Public header for the default tetrahedron scheme, providing access to its specific properties. +- `t8_dtet_connectivity.c`/`.h`: These files contain the large, explicit, hard-coded lookup tables that define the connectivity of the 8-child refinement pattern. +- `t8_dtet_bits.c`/`.h`: These files contain low-level, bitwise manipulation functions that implement the logic of the space-filling curve for the tetrahedron's topology. +- `t8_dtri_to_dtet.h`: A helper header that defines the mapping from the 2D triangle scheme (used for faces) to the 3D tetrahedron scheme. This is crucial for correctly handling face-neighbor relationships. + +## Main Purpose + +This is a low-level, internal component of `t8code`. The `t8_forest` module consults these lookup tables whenever it needs to perform a topological operation (like finding a neighbor or a child) on a tetrahedral element. The use of pre-computed tables makes these operations extremely fast. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_tri/README.md b/src/t8_schemes/t8_default/t8_default_tri/README.md new file mode 100644 index 0000000000..a8360aa55e --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_tri/README.md @@ -0,0 +1,25 @@ +# Triangle Default Scheme + +This directory contains the implementation of the default refinement scheme for a **triangle**. This scheme is fundamental for 2D simulations and for representing the faces of 3D elements like tetrahedra and prisms. + +## Functionality + +The files in this directory define the precise combinatorial rules for the refinement of a triangular element. Specifically, they encode the following information: + +- A triangle is refined into 4 child triangles. +- The orientation, position, and numbering of these 4 children relative to their parent. +- The relationship between the parent's edges and the children's edges. +- The connectivity between the child elements themselves. + +This information is stored in a series of static lookup tables. + +## Files + +- `t8_default_tri.cxx`/`.hxx`: These files contain the primary logic that uses the `t8_scheme_builder` to construct the final scheme object from the raw connectivity data. +- `t8_dtri.h`: Public header for the default triangle scheme, providing access to its specific properties. +- `t8_dtri_connectivity.c`/`.h`: These files contain the explicit, hard-coded lookup tables that define the connectivity of the 4-child refinement pattern. +- `t8_dtri_bits.c`/`.h`: These files contain low-level, bitwise manipulation functions that implement the logic of the space-filling curve for the triangle's topology. + +## Main Purpose + +This is a low-level, internal component of `t8code`. The `t8_forest` module consults these lookup tables whenever it needs to perform a topological operation on a triangular element or face. The use of pre-computed tables makes these operations extremely fast. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_default/t8_default_vertex/README.md b/src/t8_schemes/t8_default/t8_default_vertex/README.md new file mode 100644 index 0000000000..7f162ac432 --- /dev/null +++ b/src/t8_schemes/t8_default/t8_default_vertex/README.md @@ -0,0 +1,21 @@ +# Vertex Default Scheme + +This directory contains the implementation of the default refinement scheme for a **0D Vertex** element. + +## Functionality + +This is the simplest possible scheme. A vertex represents a point in space and has no dimension. The files in this directory define the combinatorial rules for a vertex, which are trivial: + +- A vertex is refined into a single child vertex (itself). +- It has no faces or edges. + +This scheme is necessary for the completeness and consistency of the `t8_schemes` framework, providing a base case for recursive algorithms. + +## Files + +- `t8_default_vertex.cxx`/`.hxx`: These files contain the minimal data and logic required to build the vertex scheme object. +- `t8_dvertex.h`: Public header for the default vertex scheme. + +## Main Purpose + +This is a low-level, internal component of `t8code` that handles the topological properties of a 0D element. It is primarily used to represent the corners of 1D, 2D, and 3D elements. Developers typically do not need to interact with these files directly. diff --git a/src/t8_schemes/t8_standalone/README.md b/src/t8_schemes/t8_standalone/README.md new file mode 100644 index 0000000000..8b9479c0a4 --- /dev/null +++ b/src/t8_schemes/t8_standalone/README.md @@ -0,0 +1,23 @@ +# Standalone Schemes + +This directory contains a "standalone" implementation of the `t8code` refinement schemes. This version is designed to be compiled and used independently of the main `t8code` library, with minimal dependencies. + +## Main Purpose + +The primary purpose of this standalone version is to allow external tools, testing frameworks, or other applications to access the combinatorial information of `t8code`'s refinement patterns without needing to link against the full library (which includes MPI, `p4est`, etc.). + +Potential use cases include: +- **Unit Testing:** The schemes' logic can be tested in a lightweight, isolated environment. +- **External Tools:** A post-processor or a mesh converter could use this to understand the structure of a `t8code` mesh. +- **Visualization and Debugging:** A simple program can be built using this module to visualize the refinement of a single element, which is useful for debugging and educational purposes. + +## Files + +- `t8_standalone.hxx`: The main public header for the standalone schemes. It provides the interface to access the scheme information. +- `t8_standalone.cxx`: The implementation file for the standalone scheme interface. +- `t8_standalone_elements.hxx`: Defines the element types (`eclass`) in a context that is independent of the main `t8code` library. +- `t8_standalone_implementation.hxx`: This header contains the actual implementation. It likely includes the raw connectivity data from the `t8_default` schemes and uses the `t8_scheme_builder` to construct the scheme objects, but without any of the other `t8code` components. + +## How to Use + +A developer would include `t8_standalone.hxx` in their application and link against the object file compiled from `t8_standalone.cxx`. They could then get a scheme object (e.g., for a tetrahedron) and query it for its properties, just as one would with the full `t8_schemes` module. diff --git a/src/t8_types/README.md b/src/t8_types/README.md new file mode 100644 index 0000000000..e2212d7daf --- /dev/null +++ b/src/t8_types/README.md @@ -0,0 +1,27 @@ +# t8_types Module + +The `t8_types` module provides a collection of fundamental, low-level data types and utilities that are used throughout the `t8code` library. These types form the basic building blocks for more complex data structures. + +## Key Files and Functionalities + +- **Basic Type Definitions:** + - `t8_type.hxx`: This header likely defines fundamental type aliases and traits used across the library. This could include standardizing integer types (e.g., `t8_global_id_t` for globally unique IDs) or defining compile-time properties of types. + +- **3D Vector Class (`t8_vec`)**: + - `t8_vec.h`: The public C-API header for a 3D vector type. + - `t8_vec.hxx`: The C++ header defining the `t8_vec_t` class, which is a simple 3-component vector used extensively for representing coordinates, velocities, etc. + - `t8_vec.cxx`: The C++ implementation file for the `t8_vec_t` class methods. + +- **Operator Overloading:** + - `t8_operators.hxx`: This header provides overloaded operators (e.g., `+`, `-`, `*`, `/`) for the custom types defined in this module, particularly for `t8_vec_t`. This allows for clean, readable, and intuitive mathematical expressions involving these types (e.g., `t8_vec_t c = a + b;`). + +- **Data Handler Types:** + - `t8_data_handler_type.hxx`: This file likely contains type definitions or traits related to the `t8_data_handler` (defined in the `t8_data` module). It might specify properties or concepts that data types must fulfill to be used with the data handler. + +## Main Purpose + +The main purpose of this module is to provide a consistent and efficient set of basic data types for the rest of the library. By defining its own vector class and standardizing types, `t8code` ensures that these fundamental operations are performed correctly and efficiently across different platforms and compilers. + +## Developer Entry Points + +Developers using `t8code` will frequently encounter `t8_vec_t` and the associated vector operations. The main C++ interface is in `t8_vec.hxx` and `t8_operators.hxx`. The C-API is in `t8_vec.h`. The other files are mostly internal implementation details. diff --git a/src/t8_vector_helper/README.md b/src/t8_vector_helper/README.md new file mode 100644 index 0000000000..1a4caab286 --- /dev/null +++ b/src/t8_vector_helper/README.md @@ -0,0 +1,19 @@ +# t8_vector_helper Module + +The `t8_vector_helper` module provides a collection of utility functions and algorithms for working with standard library vectors (`std::vector`) and other vector-like containers. + +## Files + +- `t8_vector_algorithms.hxx`: This header-only file contains a suite of generic algorithms that operate on vectors. These are likely helper functions that are not provided by the standard library but are frequently needed within `t8code`. Examples of such functions might include: + - Splitting a vector into multiple sub-vectors. + - Searching for a sub-sequence within a vector. + - Performing a parallel prefix sum on a vector's elements. + - Custom sorting or partitioning algorithms. + +## Main Purpose + +The main purpose of this module is to provide a centralized location for common, reusable vector operations. By implementing these as generic, templated functions, they can be applied to vectors of different data types, reducing code duplication and improving maintainability. These helpers simplify the implementation of more complex algorithms in other parts of the `t8code` library. + +## Developer Entry Points + +A developer would use this module by including the `t8_vector_algorithms.hxx` header file and then calling the desired function on their `std::vector` or other compatible container. The module is entirely self-contained within the header file. diff --git a/src/t8_vtk/README.md b/src/t8_vtk/README.md new file mode 100644 index 0000000000..4266ee17dd --- /dev/null +++ b/src/t8_vtk/README.md @@ -0,0 +1,35 @@ +# t8_vtk Module + +The `t8_vtk` module is responsible for writing `t8code` data, particularly the `t8_forest` and associated user data, into the Visualization Toolkit (VTK) file format. This enables users to visualize their adapted meshes and simulation results using popular visualization tools like [ParaView](https://www.paraview.org/) and [VisIt](https://visit-dav.github.io/visit-website/). + +The module can write both serial (`.vtu`) and parallel (`.pvtu` + multiple `.vtu`) files. + +## Subfolders + +- [**t8_with_vtk/**](t8_with_vtk/README.md): Contains code that is only compiled when `t8code` is configured with VTK support. This code likely handles the direct interaction with the VTK library API. + +## Key Files and Functionality + +- **Main Writer Interface:** + - `t8_vtk_writer.h`: The main public C-API header for the VTK writer. It declares the functions that a user calls to initiate the writing process, such as `t8_vtk_write_forest`. + - `t8_vtk_writer.hxx`: The internal C++ header for the writer class. + - `t8_vtk_writer.cxx`: The main implementation of the VTK writer logic. It orchestrates the process of gathering the mesh geometry and data and writing it to files. + +- **ASCII Format Implementation:** + - `t8_vtk_write_ASCII.hxx`/`.cxx`: These files contain the specific implementation for writing VTK files in the human-readable ASCII format. The VTK standard also supports a binary format, which would be implemented separately. + +- **Helper Functions:** + - `t8_vtk_writer_helper.hxx`/`.cxx`: These files contain helper functions that assist the main writer. This could include functions for triangulating non-tetrahedral elements (as VTK's unstructured grid format is based on simple cell types), collecting data from ghost elements, or managing parallel file information. + +- **Type Definitions:** + - `t8_vtk_types.h`: Defines data types and structures specific to the VTK writing process. + +## Developer Workflow + +A developer wanting to visualize their `t8_forest` and data would typically: +1. Include `t8_vtk_writer.h`. +2. After their simulation step, call `t8_vtk_write_forest`, passing in the `t8_forest` object. +3. They can also provide pointers to their user data (managed by a `t8_data_handler`) to be included in the output file. The function allows specifying names for these data arrays. +4. The module will then generate the appropriate `.vtu` or `.pvtu` files on disk. + +This provides a straightforward way to get simulation data out of `t8code` and into a standard format for visualization and analysis. diff --git a/src/t8_vtk/t8_with_vtk/README.md b/src/t8_vtk/t8_with_vtk/README.md new file mode 100644 index 0000000000..621f8d6c6d --- /dev/null +++ b/src/t8_vtk/t8_with_vtk/README.md @@ -0,0 +1,23 @@ +# VTK Library Interaction + +This directory contains the source code that directly interacts with the third-party [VTK library](https://vtk.org/). The code in this folder is only compiled if `t8code` is configured with VTK support enabled (`-DT8_WITH_VTK=ON`). + +The separation of this code allows the rest of the `t8_vtk` module to have a generic structure, while the files here handle the specific details of calling VTK API functions to create and populate VTK data structures. + +## Key Files and Functionality + +- **Unstructured Grid Handling:** + - `t8_vtk_unstructured.cxx`/`.hxx`: This is a crucial component for visualization. It contains the code that takes the `t8_forest` data (points and element connectivity) and populates a `vtkUnstructuredGrid` object. This VTK data structure is capable of representing the mix of element types (tets, hexes, etc.) found in a `t8_forest`. + +- **PolyData Handling:** + - `t8_vtk_polydata.cxx`/`.hxx`: This contains code to create `vtkPolyData` objects. `vtkPolyData` is typically used for representing surface meshes (vertices and polygons). This might be used in `t8code` to visualize the boundary of a 3D domain or to represent a 2D mesh. + +- **Parallel I/O:** + - `t8_vtk_parallel.cxx`/`.hxx`: This component handles the specifics of writing parallel VTK files. It likely uses the VTK `vtkXMLPUnstructuredGridWriter` (for `.pvtu` files) or similar classes to coordinate the writing process across multiple MPI ranks, where each rank writes its own piece of the data. + +- **VTK File Reading:** + - `t8_vtk_reader.cxx`/`.hxx`: This contains the implementation for reading mesh data *from* a VTK file. It uses the VTK library's reader classes (e.g., `vtkXMLUnstructuredGridReader`) to parse a `.vtu` file and extract the mesh information, which can then be used to initialize a `t8_cmesh`. + +## Main Purpose + +The main purpose of this module is to encapsulate all direct dependencies on the VTK library API. By doing so, the rest of `t8code` remains independent of VTK, and `t8code` can be successfully compiled even if the VTK library is not installed on a user's system (albeit without visualization capabilities). When VTK support is enabled, these files provide the "bridge" between `t8code`'s internal data structures and the corresponding VTK data structures. diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000000..c718a23535 --- /dev/null +++ b/test/README.md @@ -0,0 +1,30 @@ +# Test Folder + +This folder contains all tests for the t8code library. The tests are written using the Google Test framework. + +## Subfolders + +The tests are organized into subfolders, each corresponding to a specific module or functionality of t8code. + +- [api/](api/README.md): Tests for the public C-API of t8code. +- [t8_IO/](t8_IO/README.md): Tests for input/output operations. +- [t8_cmesh/](t8_cmesh/README.md): Tests for the cmesh module, which handles the coarse mesh. +- [t8_cmesh_generator/](t8_cmesh_generator/README.md): Tests for the generation of cmeshes. +- [t8_data/](t8_data/README.md): Tests for data handling and management. +- [t8_forest/](t8_forest/README.md): Tests for the adaptive forest of octrees. +- [t8_forest_incomplete/](t8_forest_incomplete/README.md): Tests for incomplete forest operations. +- [t8_geometry/](t8_geometry/README.md): Tests for geometry handling. +- [t8_schemes/](t8_schemes/README.md): Tests for different numerical schemes. +- [t8_types/](t8_types/README.md): Tests for custom data types used in t8code. +- [t8_vector_helper/](t8_vector_helper/README.md): Tests for vector helper functions. +- [testfiles/](testfiles/README.md): Contains files used by the tests, such as mesh files. + +## Main Entry Points + +The main entry point for running the tests is `t8_gtest_main.cxx`. The tests are built and run using CMake. To build the tests, enable the `T8_ENABLE_TESTING` option in your CMake configuration. + +Individual tests are defined in `_test.cxx` files within the subfolders. The `t8_gtest_...` files in this directory provide the basic setup and custom assertions for the tests. + +## Related Wiki Articles + +For more information on how to build and run the tests, please refer to the [t8code wiki](https://github.com/DLR-AMR/t8code/wiki). diff --git a/test/api/README.md b/test/api/README.md new file mode 100644 index 0000000000..93adf75244 --- /dev/null +++ b/test/api/README.md @@ -0,0 +1,15 @@ +# Test API Folder + +This folder contains tests for the public APIs of t8code. + +## Subfolders + +- [t8_fortran_interface/](t8_fortran_interface/README.md): Tests for the Fortran interface. + +## Main Features + +The tests in this folder verify the correctness and stability of the t8code APIs, ensuring that they can be reliably used by external applications. + +## Main Entry Points + +The tests are integrated into the main test suite and can be run using the `t8_gtest_main` executable after building the tests with CMake. diff --git a/test/api/t8_fortran_interface/README.md b/test/api/t8_fortran_interface/README.md new file mode 100644 index 0000000000..ab614cc8bc --- /dev/null +++ b/test/api/t8_fortran_interface/README.md @@ -0,0 +1,15 @@ +# Fortran Interface Tests + +This folder contains tests for the Fortran interface of t8code. + +## Files + +- `t8_test_mpi_init.f90`: This test checks the initialization of MPI from the Fortran interface. + +## Main Features + +The tests in this folder ensure that the Fortran API of t8code is working correctly and can be used to interact with the library from Fortran applications. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. You need to have a Fortran compiler and MPI enabled to build and run these tests. diff --git a/test/t8_IO/README.md b/test/t8_IO/README.md new file mode 100644 index 0000000000..8e2aae43ea --- /dev/null +++ b/test/t8_IO/README.md @@ -0,0 +1,16 @@ +# t8_IO Tests + +This folder contains tests for the input/output functionalities of t8code, specifically focusing on VTK file operations. + +## Files + +- `t8_gtest_vtk_reader.cxx`: Contains tests for reading VTK files. It verifies that t8code can correctly parse and load data from VTK file formats. +- `t8_gtest_vtk_writer.cxx`: Contains tests for writing VTK files. It ensures that t8code can correctly export data into various VTK file formats. + +## Main Features + +The tests in this directory ensure the reliability of t8code's I/O operations, which are crucial for data import/export and interoperability with other tools that use the VTK format, such as ParaView or VisIt. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. Ensure that VTK support is enabled in the CMake configuration to build and run these tests. diff --git a/test/t8_cmesh/README.md b/test/t8_cmesh/README.md new file mode 100644 index 0000000000..a8219f68a7 --- /dev/null +++ b/test/t8_cmesh/README.md @@ -0,0 +1,33 @@ +# t8_cmesh Tests + +This folder contains tests for the `t8_cmesh` module, which is responsible for handling the coarse mesh in `t8code`. The coarse mesh is the initial, non-adapted representation of the simulation domain. + +## Files + +The test files in this directory cover a wide range of `t8_cmesh` functionalities: + +- `t8_gtest_attribute_gloidx_array.cxx`: Tests the handling of global index attributes on the coarse mesh. +- `t8_gtest_bcast.cxx`: Tests the broadcasting of cmesh data across MPI processes. +- `t8_gtest_cmesh_add_attributes_when_derive.cxx`: Verifies that attributes are correctly handled when a new cmesh is derived. +- `t8_gtest_cmesh_bounding_box.cxx`: Tests the computation of the cmesh's bounding box. +- `t8_gtest_cmesh_copy.cxx`: Tests the functionality for copying a cmesh. +- `t8_gtest_cmesh_face_is_boundary.cxx`: Tests the identification of boundary faces on the cmesh. +- `t8_gtest_cmesh_partition.cxx`: Verifies the partitioning of the cmesh across multiple processes. +- `t8_gtest_cmesh_readmshfile.cxx`: Tests reading a cmesh from a `.msh` file. +- `t8_gtest_cmesh_set_join_by_vertices.cxx`: Tests the logic for joining mesh entities by vertices. +- `t8_gtest_cmesh_set_partition_offsets.cxx`: Tests the setting of partition offsets. +- `t8_gtest_cmesh_tree_vertices_negative_volume.cxx`: A specific test to check for negative volume elements, which can indicate errors in mesh generation or adaptation. +- `t8_gtest_cmesh_vertex_conn.cxx`: Tests the vertex connectivity data structures. +- `t8_gtest_cmesh_vertex_conn_tree_to_vertex.cxx`: Tests the connectivity from trees to vertices. +- `t8_gtest_cmesh_vertex_conn_vertex_to_tree.cxx`: Tests the connectivity from vertices to trees. +- `t8_gtest_compute_first_element.cxx`: Tests the computation of the first element on a process. +- `t8_gtest_hypercube.cxx`: Contains tests specifically for hypercube-shaped cmeshes. +- `t8_gtest_multiple_attributes.cxx`: Tests the handling of multiple attributes on a cmesh. + +## Main Features + +These tests are crucial for ensuring the correctness of the coarse mesh representation and its manipulation, which forms the foundation for the adaptive forest of octrees in `t8code`. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_cmesh_generator/README.md b/test/t8_cmesh_generator/README.md new file mode 100644 index 0000000000..5e5c94d2cc --- /dev/null +++ b/test/t8_cmesh_generator/README.md @@ -0,0 +1,22 @@ +# t8_cmesh_generator Tests + +This folder contains tests for the `t8_cmesh_generator` module, which is responsible for programmatically generating various types of coarse meshes. + +## Subfolders + +- [t8_cmesh_parameterized_examples/](t8_cmesh_parameterized_examples/README.md): Contains parameterized examples of cmeshes used for testing. + +## Files + +- `t8_gtest_cmesh_generator_test.cxx`: This is the main test file for the cmesh generator. It verifies that the generator can create valid and correct coarse meshes based on different input parameters and configurations. +- `t8_cmesh_example_sets.hxx`: A header file defining sets of example cmeshes that are used as a basis for the generator tests. +- `t8_gtest_cmesh_cartestian_product.hxx`: A header file providing utilities to test the generation of cmeshes from Cartesian products of simpler meshes. +- `t8_gtest_cmesh_sum_of_sets.hxx`: A header file providing utilities to test the generation of cmeshes by combining different mesh sets. + +## Main Features + +The tests in this directory ensure that `t8code` can reliably generate a variety of coarse meshes, which is a fundamental capability for setting up different simulation scenarios without relying on externally created mesh files. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_cmesh_generator/t8_cmesh_parameterized_examples/README.md b/test/t8_cmesh_generator/t8_cmesh_parameterized_examples/README.md new file mode 100644 index 0000000000..1aae546534 --- /dev/null +++ b/test/t8_cmesh_generator/t8_cmesh_parameterized_examples/README.md @@ -0,0 +1,20 @@ +# Parameterized cmesh Test Examples + +This directory contains header files that define parameterized examples for the `t8_cmesh_generator` tests. Each file provides a set of parameters or configurations for generating a specific type of coarse mesh, allowing the tests to cover a wide variety of scenarios. + +## Files + +- **`t8_cmesh_new_bigmesh_param.hxx`**: Defines parameters for generating a very large coarse mesh, which is useful for performance and scalability testing. +- **`t8_cmesh_new_comm.hxx`**: Provides different MPI communicator setups to test the generation of cmeshes in various parallel configurations. +- **`t8_cmesh_new_disjoint_bricks_param.hxx`**: Defines parameters for creating a cmesh composed of multiple, non-connected brick elements. +- **`t8_cmesh_new_empty.hxx`**: Contains parameters to test the creation and handling of an empty cmesh. +- **`t8_cmesh_new_from_class_param.hxx`**: Defines parameters for generating a cmesh based on a predefined class of shapes. +- **`t8_cmesh_new_hypercube_pad.hxx`**: Defines parameters for creating a hypercube-shaped mesh with padding. +- **`t8_cmesh_new_hypercube_param.hxx`**: Defines parameters for generating standard hypercube cmeshes. +- **`t8_cmesh_new_periodic.hxx`**: Contains parameters for creating cmeshes with periodic boundary conditions. +- **`t8_cmesh_new_prism_cake_param.hxx`**: Defines parameters for generating a "prism cake" geometry, which is a stack of prisms. +- **`t8_cmesh_params.hxx`**: A helper file that contains a collection of common and shared parameters used across different cmesh generation tests. + +## Main Purpose + +The primary purpose of these files is to provide a systematic and reusable way to test the `t8_cmesh_generator`. By parameterizing the mesh examples, the tests can easily and thoroughly cover a wide range of scenarios, ensuring the robustness and correctness of `t8code`'s mesh generation capabilities. diff --git a/test/t8_data/README.md b/test/t8_data/README.md new file mode 100644 index 0000000000..acc4e53f50 --- /dev/null +++ b/test/t8_data/README.md @@ -0,0 +1,19 @@ +# t8_data Tests + +This folder contains tests for data handling and management within t8code. This includes tests for the data handler, which is responsible for managing user-defined data attached to mesh elements, as well as tests for shared memory operations. + +## Files + +- `t8_gtest_data_handler.cxx`: The main test file for the `t8_data_handler`. It verifies that user data can be correctly allocated, stored, and accessed on a per-element basis. +- `t8_gtest_shmem.cxx`: Contains tests for shared memory (`shmem`) functionalities, ensuring that data can be efficiently shared between processes on the same node. +- `t8_data_handler_specs.cxx` and `t8_data_handler_specs.hxx`: These files define specifications and configurations for the data handler tests, allowing for a variety of test scenarios. +- `t8_pseudo_trees.hxx`: A header file defining "pseudo-trees," which are simplified tree structures used for testing data management without needing a full forest. +- `t8_enlarged_stdtypes.hxx`: A header file providing enlarged standard data types, likely used to test data handling with non-standard data sizes. + +## Main Features + +The tests in this directory are crucial for verifying the correctness and efficiency of how `t8code` manages user data. This is a core feature for any simulation code, as it allows users to attach their application-specific data (like physical quantities) to the mesh. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_forest/README.md b/test/t8_forest/README.md new file mode 100644 index 0000000000..9c2beedea1 --- /dev/null +++ b/test/t8_forest/README.md @@ -0,0 +1,28 @@ +# t8_forest Tests + +This folder contains tests for the `t8_forest` module, which implements the core functionality of `t8code`: the adaptive forest of octrees (or other element types). This includes mesh adaptation (refinement and coarsening), load balancing, ghost element exchange, and search operations. + +## Files + +- `t8_gtest_balance.cxx`: Tests the 2:1 balancing of the forest, which is a crucial step after adaptation to ensure a valid mesh. +- `t8_gtest_element_is_leaf.cxx`: Tests the function that determines if an element is a leaf (i.e., not refined further). +- `t8_gtest_element_volume.cxx`: Verifies the calculation of element volumes. +- `t8_gtest_find_owner.cxx`: Tests the logic for finding the MPI process that owns a given element. +- `t8_gtest_forest_commit.cxx`: Tests the `t8_forest_commit` function, which finalizes changes to the forest after adaptation or partitioning. +- `t8_gtest_forest_face_normal.cxx`: Tests the computation of face normals for elements in the forest. +- `t8_gtest_ghost_and_owner.cxx`: Tests the identification of ghost elements and their owners. +- `t8_gtest_ghost_delete.cxx`: Verifies the correct deletion of ghost elements. +- `t8_gtest_ghost_exchange.cxx`: Tests the exchange of ghost element data between processes, which is essential for parallel computations. +- `t8_gtest_half_neighbors.cxx`: Tests the retrieval of "half" neighbors, which are neighbors of the same size. +- `t8_gtest_partition_data.cxx`: Tests the partitioning of the forest data for load balancing. +- `t8_gtest_search.cxx`: Tests the functions for searching for elements within the forest (e.g., finding which element contains a given point). +- `t8_gtest_transform.cxx`: Tests coordinate transformations between the reference element and the physical element. +- `t8_gtest_user_data.cxx`: Tests the attachment and management of user data on forest elements. + +## Main Features + +These tests ensure the correctness and robustness of the dynamic mesh adaptation and parallel data management capabilities of `t8code`, which are fundamental to its use in AMR simulations. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_forest_incomplete/README.md b/test/t8_forest_incomplete/README.md new file mode 100644 index 0000000000..acb44825e9 --- /dev/null +++ b/test/t8_forest_incomplete/README.md @@ -0,0 +1,19 @@ +# t8_forest_incomplete Tests + +This folder contains tests for handling "incomplete" forests. In `t8code`, an incomplete forest is one that may have unusual or non-standard properties, such as containing empty trees or having "holes" in its structure. These tests are designed to ensure the robustness of forest algorithms when faced with these edge cases. + +## Files + +- `t8_gtest_empty_global_tree.cxx`: Tests how the forest handles a cmesh tree that is globally empty (i.e., has no elements on any process). +- `t8_gtest_empty_local_tree.cxx`: Tests how the forest handles a cmesh tree that is locally empty (i.e., has no elements on the current process, but may have elements on other processes). +- `t8_gtest_iterate_replace.cxx`: Tests the iteration over a forest while simultaneously replacing elements, a complex scenario that can arise during adaptation. +- `t8_gtest_permute_hole.cxx`: Tests the handling of a "permuted hole," which likely refers to a scenario where a gap or missing element is created in the forest due to permutation or reordering operations. +- `t8_gtest_recursive.cxx`: Contains recursive tests, likely to probe deep adaptation scenarios or complex tree structures. + +## Main Features + +The tests in this directory are crucial for ensuring the stability and correctness of `t8code`'s core forest algorithms. By specifically targeting edge cases and unusual configurations, these tests help prevent bugs that might not be caught by standard adaptation and partitioning tests. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_geometry/README.md b/test/t8_geometry/README.md new file mode 100644 index 0000000000..0f36b163a0 --- /dev/null +++ b/test/t8_geometry/README.md @@ -0,0 +1,21 @@ +# t8_geometry Tests + +This folder contains tests for the geometry handling capabilities of `t8code`. These tests ensure that the mesh can correctly interact with and conform to various geometric representations, which is essential for simulating problems on complex domains. + +## Subfolders + +- [t8_geometry_implementations/](t8_geometry_implementations/README.md): Contains tests for specific geometry implementations, such as analytic geometries or those based on CAD kernels. + +## Files + +- `t8_gtest_geometry_handling.cxx`: Provides general tests for geometry handling, verifying the core functionalities of the geometry module. +- `t8_gtest_geometry_triangular_interpolation.cxx`: Tests the triangular interpolation functions, which are often used to represent and evaluate curved surfaces. +- `t8_gtest_point_inside.cxx`: Tests the crucial "point inside element" check, which determines if a given point lies within a mesh element, taking into account the underlying geometry. + +## Main Features + +The tests in this directory verify the accuracy of geometric queries and transformations. This includes ensuring that mesh elements correctly represent the underlying geometry and that operations like point location and interpolation are performed correctly. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. Some tests may require specific geometry kernels (like OpenCASCADE) to be enabled in the CMake configuration. diff --git a/test/t8_geometry/t8_geometry_implementations/README.md b/test/t8_geometry/t8_geometry_implementations/README.md new file mode 100644 index 0000000000..c9d19aec55 --- /dev/null +++ b/test/t8_geometry/t8_geometry_implementations/README.md @@ -0,0 +1,17 @@ +# Specific Geometry Implementation Tests + +This folder contains tests for different, specific implementations of the `t8_geometry` interface. Each file tests a particular way of representing and interacting with the domain geometry. + +## Files + +- `t8_gtest_geometry_cad.cxx`: Contains tests for geometries defined by a CAD kernel, such as OpenCASCADE. These tests verify that `t8code` can correctly interact with complex, industry-standard CAD models. Running these tests requires `t8code` to be compiled with support for a CAD library. +- `t8_gtest_geometry_lagrange.cxx`: Tests the implementation of high-order geometries using Lagrange polynomials. This is used for simulations that require a very accurate, curved representation of the domain boundary. +- `t8_gtest_geometry_linear.cxx`: Tests the simplest geometry implementation, where all surfaces are represented as flat, linear patches. This serves as a baseline and is used for many standard test cases. + +## Main Purpose + +These tests ensure that each supported geometry backend is working correctly. This is crucial for allowing users to choose the most appropriate geometry representation for their specific application, from simple analytical shapes to complex CAD models. + +## How to Run + +These tests are part of the main test suite. Note that some tests, particularly `t8_gtest_geometry_cad.cxx`, will only be built and executed if the corresponding optional dependencies (e.g., OpenCASCADE) are enabled in the CMake configuration. diff --git a/test/t8_schemes/README.md b/test/t8_schemes/README.md new file mode 100644 index 0000000000..4d2ee96793 --- /dev/null +++ b/test/t8_schemes/README.md @@ -0,0 +1,51 @@ +# t8_schemes Tests + +This folder contains tests for the `t8_schemes` module. In `t8code`, a "scheme" defines the connectivity and refinement rules for a specific element shape (e.g., tetrahedrons, prisms, pyramids). These tests verify the correctness of these complex, low-level algorithms that form the combinatorial backbone of `t8code`. + +## Files + +The tests in this directory cover various aspects of the refinement schemes: + +### Tree Traversal and Relationships + +- `t8_gtest_ancestor.cxx`: Tests finding the ancestor of an element. +- `t8_gtest_ancestor_id.cxx`: Tests finding the ancestor of an element by its ID. +- `t8_gtest_descendant.cxx`: Tests finding descendants of an element. +- `t8_gtest_face_descendant.cxx`: Tests finding descendants of a face. +- `t8_gtest_find_parent.cxx`: Tests finding the direct parent of an element. +- `t8_gtest_nca.cxx`: Tests finding the nearest common ancestor of two elements. +- `t8_gtest_root.cxx`: Tests identifying the root element of a tree. +- `t8_gtest_elements_are_family.cxx`: Verifies the logic to determine if elements share a direct lineage. +- `t8_gtest_successor.cxx`: Tests finding the successor element in a traversal. +- `t8_gtest_dfs_base.hxx` & `t8_gtest_bfs_base.hxx`: Base headers for Depth-First Search and Breadth-First Search traversal tests. + +### Connectivity and Neighborhood + +- `t8_gtest_child_parent_face.cxx`: Tests the relationship between a child element's face and its parent's face. +- `t8_gtest_face_corner.cxx`: Tests the mapping between faces and corners of an element. +- `t8_gtest_face_neigh.cxx`: Tests finding face-neighbors of an element. +- `t8_gtest_pyra_connectivity.cxx`: Specific connectivity tests for pyramid elements. + +### Scheme Properties and Consistency + +- `t8_gtest_scheme_consistency.cxx`: A crucial test that checks the internal consistency of the refinement schemes. +- `t8_gtest_default.cxx`: Tests the default scheme. +- `t8_gtest_equal.cxx`: Tests the equality comparison for scheme elements. +- `t8_gtest_pack_unpack.cxx`: Verifies the serialization (packing) and deserialization (unpacking) of scheme data. +- `t8_gtest_input_equal_output.cxx`: Checks that certain operations are idempotent or reversible. +- `t8_gtest_boundary_extrude.cxx`: Tests extrusion of boundary faces. + +### Element Identification and Properties + +- `t8_gtest_get_linear_id.cxx`: Tests retrieving the linear ID of an element. +- `t8_gtest_set_linear_id.cxx`: Tests setting the linear ID of an element. +- `t8_gtest_element_count_leaves.cxx`: Tests counting the number of leaf elements. +- `t8_gtest_element_ref_coords.cxx`: Tests getting the reference coordinates of an element. + +## Main Purpose + +These tests are fundamental to the reliability of `t8code`. They ensure that the rules for how elements are created, related, and subdivided are mathematically correct and consistently applied, which is essential for the integrity of the adaptive mesh. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_types/README.md b/test/t8_types/README.md new file mode 100644 index 0000000000..8581912d26 --- /dev/null +++ b/test/t8_types/README.md @@ -0,0 +1,16 @@ +# t8_types Tests + +This folder contains tests for the custom data types and data structures defined in `t8code`. These tests ensure that the fundamental building blocks for data storage and access are working correctly. + +## Files + +- `t8_gtest_type.cxx`: This file tests the basic custom data types used throughout `t8code`. This might include tests for their size, alignment, and basic operations to ensure platform-independent and consistent behavior. +- `t8_gtest_random_accessible.cxx`: This file tests data structures that are designed to provide random access to their elements. It likely verifies that elements can be accessed correctly and efficiently by their index. + +## Main Purpose + +The tests in this directory are fundamental to the stability of the entire `t8code` library. They verify the correctness of the low-level data types and structures upon which all the higher-level modules (like `t8_cmesh` and `t8_forest`) are built. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/t8_vector_helper/README.md b/test/t8_vector_helper/README.md new file mode 100644 index 0000000000..32d880f119 --- /dev/null +++ b/test/t8_vector_helper/README.md @@ -0,0 +1,15 @@ +# t8_vector_helper Tests + +This folder contains tests for vector helper functions. These functions likely provide utility operations for working with standard vectors or custom vector-like data structures in `t8code`. + +## Files + +- `t8_gtest_vector_split.cxx`: This test verifies the functionality of a `vector_split` function. This function is probably used to partition or divide a vector into multiple sub-vectors, a common operation in parallel processing and data distribution. + +## Main Purpose + +The tests in this directory ensure that the helper functions for vector manipulations are correct. These utilities can help simplify code and improve performance in other parts of the library. + +## How to Run + +These tests are part of the main test suite and are executed when you run the `t8_gtest_main` executable. diff --git a/test/testfiles/README.md b/test/testfiles/README.md new file mode 100644 index 0000000000..820bf88fcb --- /dev/null +++ b/test/testfiles/README.md @@ -0,0 +1,33 @@ +# Test Files + +This folder contains various data files that are used as input for the tests in the `t8code` test suite. These files provide a consistent basis for testing functionalities like file I/O and mesh generation. + +## Files + +The files in this directory are examples of different mesh and data formats that `t8code` can interact with. + +### MSH Files (`.msh`) + +These are mesh files in the Gmsh `.msh` format. They are used to test the `t8_cmesh_readmshfile` functionality. +- `test_msh_file_vers2_ascii.msh`: An ASCII-formatted Gmsh version 2 file. +- `test_msh_file_vers2_bin.msh`: A binary-formatted Gmsh version 2 file. +- `test_msh_file_vers4_ascii.msh`: An ASCII-formatted Gmsh version 4 file. +- `test_msh_file_vers4_bin.msh`: A binary-formatted Gmsh version 4 file. + +### VTK Files (`.vtu`, `.vtp`, `.pvtu`, `.pvtp`) + +These are files in the Visualization Toolkit (VTK) format. They are used to test `t8code`'s VTK reader and writer. +- `test_vtk_cube.vtp`: A single VTK PolyData file representing a cube. +- `test_vtk_tri.vtu`: A single VTK UnstructuredGrid file. +- `test_parallel_file.pvtu`: A parallel VTK UnstructuredGrid file, which points to the individual partition files. +- `test_parallel_file_0.vtu`, `test_parallel_file_1.vtu`: The individual data files for the parallel unstructured grid. +- `test_polydata.pvtp`: A parallel VTK PolyData file. +- `test_polydata_0.vtp`, `test_polydata_1.vtp`: The individual data files for the parallel PolyData. + +### Other Input Files (`.inp`) + +- `test_cube_unstructured_1.inp`, `test_cube_unstructured_2.inp`: These appear to be input files for generating unstructured cube meshes, possibly in a different format. + +## Main Purpose + +Having a dedicated set of test files ensures that the tests are reproducible and can be run without external dependencies on specific mesh generation tools. They are essential for verifying the I/O capabilities of `t8code`. diff --git a/tutorials/features/README.md b/tutorials/features/README.md new file mode 100644 index 0000000000..b55ebc97ac --- /dev/null +++ b/tutorials/features/README.md @@ -0,0 +1,38 @@ +# Feature Tutorials + +This directory contains tutorials that focus on specific, advanced features of `t8code`. Unlike the general tutorials, these are not necessarily meant to be followed in a specific order. Instead, they serve as deep dives into particular topics. + +--- + +### [Feature: Curved Meshes](https://github.com/DLR-AMR/t8code/wiki/Feature---Curved-meshes) + +This tutorial demonstrates one of `t8code`'s most powerful features: the ability to create and manage adaptive meshes that conform to curved domain boundaries. + +- **File:** `t8_features_curved_meshes.cxx` +- **Goal:** To show how to: + 1. Create a `t8_geometry` object that describes a curved domain (in this case, a sphere). + 2. Associate this geometry with a `t8_cmesh`. + 3. Create a `t8_forest` from this geometry-aware cmesh. + 4. Observe how `t8code` automatically projects the nodes of refined elements onto the true curved surface, resulting in a mesh that accurately represents the geometry, rather than being a coarse, blocky approximation. + +#### Input Geometry Files + +The tutorial can be run with different coarse meshes to show its flexibility. This directory includes several Gmsh geometry (`.geo`) files that can be used to generate suitable input meshes. + +- `t8_features_curved_meshes_generate_cmesh_hex.geo`: A 3D coarse mesh of hexahedra. +- `t8_features_curved_meshes_generate_cmesh_tet.geo`: A 3D coarse mesh of tetrahedra. +- `t8_features_curved_meshes_generate_cmesh_quad.geo`: A 2D coarse mesh of quadrilaterals. +- `t8_features_curved_meshes_generate_cmesh_tri.geo`: A 2D coarse mesh of triangles. + +#### How to Run + +1. **Generate a mesh:** Use Gmsh to create a `.msh` file from one of the `.geo` files. + ```bash + gmsh t8_features_curved_meshes_generate_cmesh_tet.geo -3 -o tet_mesh.msh + ``` +2. **Run the tutorial:** Execute the tutorial program, passing the path to the generated mesh file. + ```bash + ./t8_features_curved_meshes --mesh-file tet_mesh.msh + ``` + +The program will output a VTK file (e.g., `t8_features_curved_mesh.vtu`) which you can open in ParaView or VisIt to see the resulting curved, adaptive mesh. diff --git a/tutorials/general/README.md b/tutorials/general/README.md new file mode 100644 index 0000000000..6678ee76ee --- /dev/null +++ b/tutorials/general/README.md @@ -0,0 +1,57 @@ +# General Tutorials + +This directory contains the general, step-by-step tutorials for learning `t8code`. They are designed to be followed in order, as each step builds upon the concepts introduced in the previous one. + +For a detailed walkthrough of each tutorial, please see the corresponding article on the [t8code Wiki](https://github.com/DLR-AMR/t8code/wiki/Tutorial---Overview). + +**Note on File Structure:** Many tutorials are split into multiple files. Typically, there is a `_main.cxx` file that contains the main function and entry point, and other `.cxx` and `.h` files that contain the core logic for the tutorial. This is done to keep the code organized and focused. + +--- + +### [Step 0: Hello World](https://github.com/DLR-AMR/t8code/wiki/Step-0---Hello-World) +- **File:** `t8_step0_helloworld.cxx` +- **Goal:** The absolute basics: how to initialize and finalize the `t8code` library and its dependency, `p4est`. + +### [Step 1: Creating a Coarse Mesh](https://github.com/DLR-AMR/t8code/wiki/Step-1---Creating-a-coarse-mesh) +- **File:** `t8_step1_coarsemesh.cxx` +- **Goal:** Learn how to create a `t8_cmesh_t` object, the coarse mesh that serves as the basis for the adaptive forest. This tutorial creates a cmesh from a built-in example and writes it to a VTK file. + +### [Step 2: Creating a Uniform Forest](https://github.com/DLR-AMR/t8code/wiki/Step-2---Creating-a-uniform-forest) +- **File:** `t8_step2_uniform_forest.cxx` +- **Goal:** Learn how to create a `t8_forest_t` from a `t8_cmesh`. This tutorial creates a uniformly refined forest where all elements have the same refinement level. + +### [Step 3: Adapting a Forest](https://github.com/DLR-AMR/t8code/wiki/Step-3---Adapting-a-forest) +- **Files:** `t8_step3_main.cxx`, `t8_step3_adapt_forest.cxx`, `t8_step3.h` +- **Goal:** Introduce adaptive mesh refinement (AMR). This tutorial shows how to provide a callback function to `t8_forest_adapt` to selectively refine elements based on a user-defined criterion. + +### [Step 4: Partition, Balance, Ghost](https://github.com/DLR-AMR/t8code/wiki/Step-4---Partition,-Balance,-Ghost) +- **Files:** `t8_step4_main.cxx`, `t8_step4_partition_balance_ghost.cxx`, `t8_step4.h` +- **Goal:** Explain the key concepts for parallel execution. This tutorial covers partitioning the forest for load balancing, balancing the forest to maintain the 2:1 constraint, and creating the ghost layer for communication. + +### [Step 5: Storing Element Data](https://github.com/DLR-AMR/t8code/wiki/Step-5---Store-element-data) +- **Files:** `t8_step5_main.cxx`, `t8_step5_element_data.cxx`, `t8_step5.h`, `t8_step5_element_data_c_interface.c` +- **Goal:** Show how to associate application-specific data with mesh elements using the `t8_data_handler`. It also demonstrates how to exchange this data between processes using the ghost layer. + +### [Step 6: Computing Stencils](https://github.com/DLR-AMR/t8code/wiki/Step-6-Computing-stencils) +- **Files:** `t8_step6_main.cxx`, `t8_step6_stencil.cxx`, `t8_step6.h` +- **Goal:** Demonstrate how to use the `t8_forest` iterators to traverse the mesh and access data from face-neighbors. This is a fundamental operation for implementing numerical schemes like finite volume or finite difference methods. + +### [Step 7: Interpolation](https://github.com/DLR-AMR/t8code/wiki/Tutorial-Step-7---Interpolation) +- **Files:** `t8_step7_main.cxx`, `t8_step7_interpolation.cxx`, `t8_step7.h` +- **Goal:** Show how to handle data after the mesh has been adapted. This tutorial demonstrates how to define an interpolation operator to transfer data from parent elements to their new children after refinement. + +--- + +## Other General Tutorials + +### [Building a Custom cmesh](https://github.com/DLR-AMR/t8code/wiki/Build-Cmesh) +- **Files:** `t8_tutorial_build_cmesh_main.cxx`, `t8_tutorial_build_cmesh.cxx`, `t8_tutorial_build_cmesh.h` +- **Goal:** Learn how to programmatically create your own `t8_cmesh` from scratch by defining the vertices and element connectivity manually. + +### [Building a Custom Scheme](https://github.com/DLR-AMR/t8code/wiki/Tutorial:-Build-Scheme) +- **File:** `t8_tutorial_build_scheme.cxx` +- **Goal:** An advanced tutorial that shows how to define a new refinement scheme for a custom element type. + +### [Search](https://github.com/DLR-AMR/t8code/wiki/Tutorial:-Search) +- **File:** `t8_tutorial_search.cxx` +- **Goal:** Demonstrate how to use the `t8_forest_search` functions to find which elements in the forest contain a given set of points.