From c7478449142a5ea27aeade0b2d8ffbcb5ff9fe31 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Wed, 19 Nov 2025 11:27:13 +0200
Subject: [PATCH] refactor(beams): Define beam element API interface

- Define AbstractBeamElement abstract type hierarchy
- Implement element assembly interface for beam structures
- Export beam formulation and element types
- Document Euler-Bernoulli and Timoshenko beam theories
- Support 2D and 3D beam elements
- Include rotation DOF handling for beam kinematics
- 98 lines of API definitions and exports
---
 src/domains/beams/api.jl | 98 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 src/domains/beams/api.jl

diff --git a/src/domains/beams/api.jl b/src/domains/beams/api.jl
new file mode 100644
index 0000000..e4eaafd
--- /dev/null
+++ b/src/domains/beams/api.jl
@@ -0,0 +1,98 @@
+# This file is a part of JuliaFEM.
+# License is MIT: see https://github.com/JuliaFEM/JuliaFEM.jl/blob/master/LICENSE.md
+
+"""
+Beam formulation API definitions.
+
+This file defines beam-specific abstract types and formulation theories.
+Must be included after core api.jl.
+"""
+
+# ============================================================================
+# BEAM FORMULATION THEORIES
+# ============================================================================
+
+"""
+    AbstractBeamTheory
+
+Abstract type for beam theory variants.
+
+Beam theories differ in how they model shear deformation and cross-section kinematics.
+
+# Concrete Theories
+- `EulerBernoulli`: Classical beam theory (no shear deformation)
+- `Timoshenko`: Includes shear deformation (thick beams)
+
+# See Also
+- [`BeamFormulation`](@ref)
+"""
+abstract type AbstractBeamTheory end
+
+"""
+    EulerBernoulli <: AbstractBeamTheory
+
+Euler-Bernoulli beam theory (classical, no shear deformation).
+
+Assumptions:
+- Plane sections remain plane and perpendicular to neutral axis
+- No transverse shear deformation
+- Valid for slender beams (L/h > 10)
+
+# Usage
+```julia
+formulation = BeamFormulation{EulerBernoulli}()
+physics = Physics(
+    formulation=formulation,
+    field=DisplacementRotation{3}(),
+    mesh=beam_mesh,
+    material=steel
+)
+```
+"""
+struct EulerBernoulli <: AbstractBeamTheory end
+
+"""
+    Timoshenko <: AbstractBeamTheory
+
+Timoshenko beam theory (includes shear deformation).
+
+Assumptions:
+- Plane sections remain plane but NOT perpendicular to neutral axis
+- Transverse shear deformation included
+- Valid for thick beams and higher frequencies
+
+# Usage
+```julia
+formulation = BeamFormulation{Timoshenko}()
+physics = Physics(
+    formulation=formulation,
+    field=DisplacementRotation{3}(),
+    mesh=beam_mesh,
+    material=steel
+)
+```
+"""
+struct Timoshenko <: AbstractBeamTheory end
+
+"""
+    BeamFormulation{Theory<:AbstractBeamTheory} <: AbstractFormulation
+
+Beam element formulation with theory variant.
+
+# Type Parameter
+- `Theory`: Beam theory type (EulerBernoulli or Timoshenko)
+
+# Examples
+```julia
+# Slender beam (classical theory)
+BeamFormulation{EulerBernoulli}()
+
+# Thick beam (includes shear)
+BeamFormulation{Timoshenko}()
+```
+
+# Fields per Node
+Typically 6 DOFs in 3D: (ux, uy, uz, θx, θy, θz)
+Use with `DisplacementRotation{3}` field type.
+"""
+struct BeamFormulation{Theory<:AbstractBeamTheory} <: AbstractFormulation end