Merge pull request #210 from mdienst/dev-documentaion

kaipartmann · web-flow · commit f4b9adafe1c7 · 2025-07-17T15:03:32.000+02:00
Developer documentation
diff --git a/docs/make.jl b/docs/make.jl
@@ -84,6 +84,12 @@ makedocs(;
             joinpath("generated", "tutorial_cylinder.md"),
             joinpath("generated", "tutorial_brazilian_test.md"),
         ],
+        "Development" => [
+            "dev_systems.md",
+            "dev_materials.md",
+            "dev_solvers.md",
+            "dev_multithreading_mpi.md",
+        ],
         "API Reference" => [
             "public_api_reference.md",
             "private_api_reference.md",
diff --git a/docs/src/dev_materials.md b/docs/src/dev_materials.md
@@ -0,0 +1,27 @@
+# Materials
+
+!!! warning "Draft & Work in Progress"
+    This documentation is a draft and work in progress. It will be extended and improved in the future.
+
+The selected material specifies, which peridynamic formulation is employed in calculations.
+
+## Implemented material models
+
+- [`BBMaterial`](@ref): Bond-based peridynamics.
+- [`DHBBMaterial`](@ref): Dual-horizon bond-based peridynamics.
+- [`OSBMaterial`](@ref): Ordinary state-based peridynamics, also called linear peridynamic solid (LPS).
+- [`CMaterial`](@ref): Correspondence formulation.
+- [`CRMaterial`](@ref): Correspondence formulation with stress rotation for objectivity enforcement.
+- [`RKCMaterial`](@ref): Reproducing kernel peridynamics with bond-associated higher-order integration.
+- [`RKCRMaterial`](@ref): Reproducing kernel peridynamics with bond-associated higher-order integration with stress rotation for objectivity enforcement.
+- [`BACMaterial`](@ref): Bond-associated correspondence formulation of Chen and Spencer.
+- [`CKIMaterial`](@ref): Continuum-kinematics-inspired peridynamics.
+
+## Custom materials
+
+Custom materials can be defined for existing systems.
+Therefore the `<XYZ>Material` type has to be a subtype of an `Abstract<SystemName>Material`, which automatically sets methods for this type.
+Further it is necessary to: 
+- link a point parameter type with `@params`.
+- link and create a storage with `@storage`.
+- define the `force_density_point!` function.
diff --git a/docs/src/dev_multithreading_mpi.md b/docs/src/dev_multithreading_mpi.md
@@ -0,0 +1,45 @@
+# Multithreading & MPI  
+
+!!! warning "Draft & Work in Progress"
+    This documentation is a draft and work in progress. It will be extended and improved in the future.
+
+Multithreading and MPI are implemented based on a similar approach. The body is split into several chunks, that each have their own process.
+```@raw html
+<img src="https://github.com/user-attachments/assets/86caad93-8a56-495b-822a-ffccc5c43c9e" width="650"/>
+```
+There are two types of points. Each chunk consists of the local points, which lay inside the specific body chunk, as well as halo points, which lay on the surface of neighboring chunks and interact with local points of the considered chunk, because they lay inside their horizons. 
+
+This means that every point of a body exists locally in the body chunk that it originally lies in. Additionally one or more copies of the point can exist as halo points in other chunks.
+```@raw html
+<img src="https://github.com/user-attachments/assets/79340f51-cb62-42b2-8f1b-fd474f7fe8fb" width="350"/>
+```
+Since there are points that exist in multiple chunks (in one chunk as local points and possibly in one or more chunks as halo points) information has to be exchanged between these copies of specific points.  
+Two types of exchanges are of importance for both methods:
+- local-to-halo exchange: Data from calculations in the chunk where the point is local is transferred to the halo versions of this point which exist in other chunks.
+```@raw html
+<img src="https://github.com/user-attachments/assets/34434920-a758-438a-a463-a259397f1bba" width="350"/>
+```
+- halo-to-local exchange: Data from calculations of the one or multiple halo versions of a point is transferred to the local version of the point.
+```@raw html
+<img src="https://github.com/user-attachments/assets/6265e5b8-bff5-4aa3-83b7-62a385578f37" width="350"/>
+```
+
+A body chunk contains all information that is necessary for the simulation:
+
+```@raw html
+<img src="https://github.com/user-attachments/assets/c2cd75de-065e-4568-abde-e753216f3e85" width="650"/>
+```
+
+## Multithreading
+
+To manage the body chunks that compose a body in multithreading a `ThreadsDataHandler` is employed. It combines information about all the body chunks of the system and all halo exchanges between them.
+```@raw html
+<img src="https://github.com/user-attachments/assets/48e61d30-cfd5-424c-bc36-c52485a00dc2" width="250"/>
+```
+
+## MPI
+
+For MPI simulations an `MPIDataHandler` is used for each body chunk, processing its halo exchanges and further MPI-related information.
+```@raw html
+<img src="https://github.com/user-attachments/assets/ab389e50-05f7-4d6e-8b0d-992fb6c79a75" width="250"/>
+```
diff --git a/docs/src/dev_solvers.md b/docs/src/dev_solvers.md
@@ -0,0 +1,19 @@
+# Time solvers
+
+!!! warning "Draft & Work in Progress"
+    This documentation is a draft and work in progress. It will be extended and improved in the future.
+
+## VelocityVerlet
+
+A time integration solver for the Velocity Verlet algorithm used for dynamic simulations.
+
+## DynamicRelaxation
+
+A time integration solver for the adaptive dynamic relaxation algorithm used for quasi-static simulations.
+
+## Custom solvers
+
+To create a custom time solver, the following steps are required:
+- define a type `MySolver<:AbstractTimeSolver`. It has to be a subtype of the type `AbstractTimeSolver`.
+- define the function `init_time_solver!(vv::MySolver, dh::AbstractDataHandler)`.
+- define the function `solve!(dh::AbstractDataHandler, vv::VelocityVerlet, options::AbstractJobOptions)`.
diff --git a/docs/src/dev_systems.md b/docs/src/dev_systems.md
@@ -0,0 +1,30 @@
+# Systems
+
+!!! warning "Draft & Work in Progress"
+    This documentation is a draft and work in progress. It will be extended and improved in the future.
+
+Systems are the backbone of the simulations.
+They contain all the required pre-defined data structures (e.g. bonds, point-families, interactions, ...).
+
+## BondSystem
+
+The standard system for bond-based ([`BBMaterial`](@ref)), ordinary state-based ([`OSBMaterial`](@ref)) and non-ordinary state-based correspondence formulation ([`CMaterial`](@ref)) material models. Used material models have to be subtypes of `AbstractBondSystemMaterial` or `AbstractCorrespondenceMaterial`.
+
+## InteractionSystem
+
+The system utilizing one-, two- and three-neighbor-interactions for the continuum-kinematics-inspired material model ([`CKIMaterial`](@ref)).
+Used material models have to be subtypes of  `AbstractInteractionSystemMaterial`.
+
+## BondAssociatedSystem
+
+A system for the bond-associated correspondence model by Chen and Spencer ([`BACMaterial`](@ref)).
+Used material models have to be subtypes of  `AbstractBondAssociatedSystemMaterial`.
+
+## Custom systems
+
+Custom systems are relatively free in how they are defined, only these things are required:
+- define an abstract type `Abstract<SystemName>Material` that all materials using this system have to be a subtype of.
+- define the `get_system(body::AbstractBody{Material}, pd::PointDecomposition, chunk_id::Int) where {Material<:Abstract<SystemName>Material}` function.
+- define the `system_type(mat::Abstract<SystemName>Material)` function that returns the system type.
+- define the `calc_timestep_point(system::<SystemType>, params::AbstractPointParameters, point_id::Int)` function.
+- define the `calc_force_density!(chunk::AbstractBodyChunk{<:<SystemType>}, t, Δt)` function.
diff --git a/src/discretization/body.jl b/src/discretization/body.jl
@@ -12,8 +12,12 @@ Construct a `Body` for a peridynamics simulation.
     - [`OSBMaterial`](@ref): Ordinary state-based peridynamics, also called linear
         peridynamic solid (LPS).
     - [`CMaterial`](@ref): Correspondence formulation.
-    - [`CRMaterial`](@ref): Correspondence formulation stress rotation for objectivity
+    - [`CRMaterial`](@ref): Correspondence formulation with stress rotation for objectivity
         enforcement.
+    - [`RKCMaterial`](@ref): Reproducing kernel peridynamics with bond-associated
+        higher-order integration.
+    - [`RKCRMaterial`](@ref): Reproducing kernel peridynamics with bond-associated
+        higher-order integration with stress rotation for objectivity enforcement.
     - [`BACMaterial`](@ref): Bond-associated correspondence formulation of Chen and Spencer.
     - [`CKIMaterial`](@ref): Continuum-kinematics-inspired peridynamics.
 - `position::AbstractMatrix`: A `3×n` matrix with the point position of the `n` points.
