CutElementIntegration

Description This repo provides benchmark tests for routines that integrate over elements cut by an arbitrary interface. The interface may be defined implicitly by a level set function or parametrically by a NURBS curve. The included codes for integrating over cut elements are either provided as a static version in a folder or as a submodule. A list of provided codes can be seen in the corresponding README*.md file in the codes/ folder. Publications This framework is described in the following publications: T. Toprak, M. Loibl, G. H. Teixeira, I. Shiskina, C. Miao, J. Kiendl, B. Marussig, and F. Kummer, "Employing Continuous Integration inspired workflows for benchmarking of scientific software - A use case on numerical cut element quadrature," Advances in Engineering Software, vol. 213, 2026, doi: 10.1016/j.advengsoft.2025.104087. M. Loibl, G. H. Teixeira, T. Toprak, I. Shishkina, C. Miao, J. Kiendl, F. Kummer, and B. Marussig, "Comparative study of different quadrature methods for cut elements," Archives of Computational Methods in Engineering, 2026, doi: 10.1007/s11831-026-10619-2. Getting started Two ways to obtain the code are distinguished in the following: Clone with git from GitHub Download .zip from GitHub or Zenodo .zip If the code is obtained as a .zip, the open-source git repositories linked as submodules are not available. Please use the git version if you want to use the submodules. MATLAB Requirements Required MATLAB Toolboxes: Symbolic Math Toolbox - Required for reference solution computation in certain test cases These toolboxes can be installed via MATLAB's Add-On Explorer (Home > Add-Ons > Get Add-Ons). Note: StartUpCall will check for required toolboxes and warn if any are missing. Setup Within MATLAB: Navigate to the CutElementIntegration folder Run StartUpCall to add all mandatory paths and check the accessibility of the different integrators (provided in the codes/ folder) StartUpCall Note on Integrator Availability: Not all integrators may be accessible on your system. StartUpCall will report which integrators are available based on: Installed dependencies (Python packages, Julia, .NET, etc.) Platform compatibility (some integrators are Windows or Linux-only) Initialized git submodules (see Git setup above) Individual access restrictions Having only a subset of integrators available is normal and expected. The framework will work with any accessible integrators. Check individual README files in codes/[integrator]/ for specific setup requirements. Note on Python compatibility: Some integrators run with Python which has to be called from MATLAB. In case you encounter problems with the MATLAB-Python interaction, try running the following command in MATLAB upon start: pyenv("ExecutionMode","OutOfProcess"); Exploring Examples To interactively explore all available test case examples, use: queryExampleDetails() % Show all examples queryExampleDetails('circle') % Quick search queryExampleDetails('Category', 'AreaComputation2D') % Filter by category This tool provides detailed information about each example including test case IDs, interface IDs, categories, and source code line numbers. Integrator testing The framework includes regression tests that verify integrator outputs remain consistent with reference solutions. Important: These tests only compare current runs with previously obtained results. They cannot assess the quality of the results - quality validation is the responsibility of the user. Running regression tests Run all example regression tests: runExampleTests Run a specific test for all integrators: testsuite = testExampleChanges_AreaComputation2D; run(testsuite,"checkForChanges_example_circle_1"); Run a specific test for a specific integrator: testsuite = testExampleChanges_AreaComputation2D; testsuite.integrator_names={'Fcmlab'}; run(testsuite,"checkForChanges_example_circle_1"); Test structure Every examples subfolder has a testExampleChanges_*.m class that provides: the runTestCoverage function that ensures every example in the subfolder has a corresponding test file, and checkForChanges_* functions that run a test execution of the given example. The reference solutions are stored in the corresponding subfolders results_ref/. Per test case and integrator there shall be only one reference solution within these folders. The runExampleTests.m script is the main function that runs all testExampleChanges_*.m classes. Framework development Framework unit tests To run framework infrastructure tests (validates utility functions, project structure, and test case configurations): runtests('utilities/framework-unittests') Or use the comprehensive test runner with coverage report: runAllFrameworkTests Include an additional code This section outlines the procedure to include an additional integrator: Add a new folder new_code in codes/ Add a git submodule if the code should be linked as a git repository Add an Integrator class in codes/ that inherits from AbstractIntegrator Write a README in codes/new_code/ Register the Integrator with its name in utilities/integrator-management/getAccessibleIntegrators.m Codes included The included codes for integrating over cut elements are collected in the codes/ folder. They are either provided as a static version in a folder or as a submodule. Please check the README files in the corresponding subfolders for integrator-specific details. License The test environment uses the 3-Clause BSD License. Further, the test environment relies on the Octave NURBS package under the GNU General Public License. For the licenses of the integration codes, see the license files in the corresponding subfolders. Acknowledgments The work is supported by the joint DFG/FWF Collaborative Research Centre CREATOR (DFG: Project-ID 492661287/TRR 361; FWF: 10.55776/F90) at TU Darmstadt, TU Graz and JKU Linz.