Beams2D Patch 1 - Documentation

engibench/problems/beams2d/v0.py

@@ -55,13 +55,41 @@ class Beams2D(Problem[npt.NDArray]):
     r"""Beam 2D topology optimization problem.
 
     ## Problem Description
-    Beams2D is a structural topology optimization (TO) problem that optimizes a 2D Messerschmitt-Bölkow-Blohm (MBB) beam under bending. The beam is symmetric about the central vertical axis, with a force applied at the top; only the right half is modeled in our case. Problems are formulated using density-based TO, drawing from an existing Python [implementation](https://github.com/arjendeetman/TopOpt-MMA-Python).
+    Beams2D is a structural topology optimization (TO) problem that optimizes a 2D Messerschmitt-Bölkow-Blohm
+    (MBB) beam under bending. The beam is symmetric about the central vertical axis, with a force applied
+    at the top; only the right half is modeled in our case. Problems are formulated using density-based TO,
+    drawing from an existing Python [implementation](https://github.com/arjendeetman/TopOpt-MMA-Python).
+
+    ## Motivation
+    The optimization of beam cross-sections is one of a fundamental problem in engineering, aiming to
+    maximize the structural stiffness under some applied force. This objective is usually formulated as
+    minimizing the compliance, which is the inverse of stiffness. In particular, TO frames the problem as
+    one of optimal material distribution, defining a grid of elements for which the material densities must
+    be determined on a scale from 0 to 1, where 1 represents the presence of material. After applying the
+    beam loads and other boundary conditions, designs are typically optimized using a gradient-based
+    approach with the help of the finite element method (FEM). While this is one of the simplest
+    TO applications, it is still a computationally expensive process requiring many iterations, opening the
+    door for faster approximation methods such as generative inverse design.
+    One of the most common beam types in TO is the Messerschmitt-Bölkow-Blohm (MBB) beam,
+    which is supported at the bottom-right and bottom-left corners, with a downward force applied
+    on the top-center. Given this symmetric configuration, one half of the design may be optimized
+    while representing the entire structure. We implement the MBB beam in ENGIBENCH for the most
+    accessible comparison to previous works in this domain.
 
     ## Design Space
-    The design space is an array of solid densities in `[0., 1.]` with default image shape `(100, 50)`, where `nelx = 100` and `nely = 50`. Internally, this is represented as a flattened `(5000,)` array. Alternative shapes include `(50, 25)` for faster computation and `(200, 100)` for higher-resolution results. Corresponding datasets for these three resolutions are provided.
+    This problem simulates the right half-section of a MBB beam under bending. This half-beam is
+    subjected to a force at its top-left corner (corresponding to the top-center of the entire design) which
+    may also be shifted to the right to simulate different loading conditions. A roller support at the
+    bottom-right corner prevents vertical movement, and a symmetric boundary condition is enforced on
+    the left edge. The design space is an array of solid densities in `[0., 1.]` with a default size of
+    `(100, 50)` used by default, where `nelx = 100` and `nely = 50`. Internally, this is represented as
+    a flattened `(5000,)` array. Alternative shapes include `(50, 25)` for faster computation and `(200, 100)`
+    for higher-resolution results. Corresponding datasets for these three resolutions are provided.
 
     ## Objectives
-    The goal is to optimize the distribution of solid material to minimize compliance (equivalently, maximize stiffness) while satisfying constraints on material usage and minimum feature size.
+    The goal is to optimize the distribution of solid material to minimize compliance
+    (equivalently, maximize stiffness) while satisfying constraints on material usage and minimum feature size.
+    Compliance is calculated as the sum of strain energy over the structure.
 
     The objectives are defined and indexed as follows:
 
@@ -75,15 +103,31 @@ class Beams2D(Problem[npt.NDArray]):
     - `overhang_constraint`: Boolean flag to enable a 45-degree overhang constraint for manufacturability.
 
     ## Simulator
+    Our simulation code is based on a Python adaptation of the popular 88-line topology optimization
+    code. It uses the more versatile density filtering approach in combination with a standard
+    Optimality Criteria (OC) optimization method. Two primary sensitivity matrices, one with respect
+    to compliance (`dc`) and the other with respect to volume fraction (`dv`), are continuously updated
+    and used to calculate a given design's compliance value. We have also ensured that during the
+    required Lagrange multiplier search within OC, the inner optimization loop terminates if the absolute
+    difference upper and lower bounds diminishes to a value smaller than machine precision. This
+    prevents the code from becoming stuck at this point, which we observed in some warm-starting
+    instances with noisy initial designs.
+
     Compliance `c` is calculated using:
     ```python
     c = ((Emin + xPrint**penal * (Emax - Emin)) * ce).sum()
     ```
 
-    where `xPrint` is the current true density field, `penal` is the penalization factor (e.g., 3.0), and `ce` is the element-wise strain energy density.
+    where `xPrint` is the current true density field, `penal` is the penalization factor (e.g., 3.0),
+    and `ce` is the element-wise strain energy density.
 
     ## Dataset
-    Three datasets, each corresponding to a different resolution, are available on the [Hugging Face Datasets Hub](https://huggingface.co/datasets/IDEALLab/beams_2d).
+    This problem offers multiple datasets for various sizes of `nelx` and `nely`. Each dataset includes
+    columns for the optimal design, all conditions listed above, and the corresponding objective values.
+    For advanced usage, we also provide a column containing the optimization history. The datasets have
+    been generated by sampling conditions over a structured grid for various problem sizes.
+    Three datasets are available on the [Hugging Face Datasets Hub](https://huggingface.co/datasets/IDEALLab/beams_2d).
+    They correspond to resolutions of $50 \times 25$, $100 \times 50$ (default), and $200 \times 100$.
 
     ### v0
 
@@ -102,9 +146,21 @@ class Beams2D(Problem[npt.NDArray]):
 
     A more comprehensive description of the creation method can be found in the [README](https://github.com/IDEALLab/EngiBench/tree/main/engibench/problems/beams2d).
 
-    ## References
+    ## Citation
     If you use this problem in your research, please cite the following paper:
-    E. Andreassen, A. Clausen, M. Schevenels, B. S. Lazarov, and O. Sigmund, "Efficient topology optimization in MATLAB using 88 lines of code," in Structural and Multidisciplinary Optimization, vol. 43, pp. 1-16, 2011.
+    ```
+    @article{andreassen2011efficient,
+        title={Efficient topology optimization in MATLAB using 88 lines of code},
+        author={Andreassen, Erik and Clausen, Anders and Schevenels, Mattias and Lazarov, Boyan S and Sigmund, Ole},
+        journal={Structural and Multidisciplinary Optimization},
+        volume={43},
+        number={1},
+        pages={1--16},
+        year={2011},
+        publisher={Springer}
+    }
+    ```
+
 
     ## Lead
     Arthur Drake @arthurdrake1