diff --git a/.github/workflows/correctness-linux.yaml b/.github/workflows/correctness-linux.yaml index f613c2f65..9d13b9704 100644 --- a/.github/workflows/correctness-linux.yaml +++ b/.github/workflows/correctness-linux.yaml @@ -1,6 +1,10 @@ name: OpenTurbine-CI -on: push +on: + push: + paths-ignore: + - 'docs/**' + - '.github/workflows/deploy_docs.yaml' jobs: Correctness-Linux: diff --git a/.github/workflows/correctness-macos.yaml b/.github/workflows/correctness-macos.yaml index 594fd280f..f5177d3d5 100644 --- a/.github/workflows/correctness-macos.yaml +++ b/.github/workflows/correctness-macos.yaml @@ -1,6 +1,10 @@ name: OpenTurbine-CI -on: push +on: + push: + paths-ignore: + - 'docs/**' + - '.github/workflows/deploy_docs.yaml' jobs: Correctness-MacOS: diff --git a/.github/workflows/deploy_docs.yaml b/.github/workflows/deploy_docs.yaml new file mode 100644 index 000000000..05604bd5b --- /dev/null +++ b/.github/workflows/deploy_docs.yaml @@ -0,0 +1,62 @@ +name: Deploy OpenTurbine Documentation + +on: + push: + branches: [main] + pull_request: + branches: [main] + +concurrency: + group: ${{github.ref}}-${{github.head_ref}}-docs + cancel-in-progress: true + +jobs: + Deploy-Docs: + runs-on: ubuntu-latest + steps: + - name: Cache install source dependencies + id: cache-dependencies + uses: actions/cache@v3 + with: + path: ${{ github.workspace }}/spack + key: linux-spack + - name: Install source dependencies + if: steps.cache-dependencies.outputs.cache-hit != 'true' + run: | + git clone https://github.com/spack/spack.git + source spack/share/spack/setup-env.sh + spack compiler find + spack install yaml-cpp + spack install trilinos@master~epetra ^kokkos-kernels+blas+lapack + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: Clone repository + uses: actions/checkout@v4 + with: + path: openturbine + - name: Install documentation dependencies + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends graphviz libenchant-2-dev doxygen + python3 -m pip install --upgrade pip + pip install -r openturbine/docs/requirements.txt + - name: Build OpenTurbine with documentation + run: | + source spack/share/spack/setup-env.sh + spack load trilinos yaml-cpp + cd openturbine + mkdir build + cd build + cmake .. \ + -DOpenTurbine_ENABLE_TESTS=OFF \ + -DOpenTurbine_ENABLE_DOCUMENTATION=ON \ + -DCMAKE_BUILD_TYPE=Release + cmake --build . + - name: Deploy documentation + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ${{ github.workspace }}/openturbine/build/docs/sphinx/html diff --git a/.github/workflows/formatting.yaml b/.github/workflows/formatting.yaml index 8dc1f52ab..369a1e20c 100644 --- a/.github/workflows/formatting.yaml +++ b/.github/workflows/formatting.yaml @@ -1,20 +1,21 @@ name: OpenTurbine-CI -on: push +on: + push: + paths-ignore: + - 'docs/**' + - '.github/workflows/deploy_docs.yaml' jobs: clang-format: runs-on: ubuntu-24.04 - steps: - name: Checkout repository uses: actions/checkout@v4 - - name: Run clang-format run: | clang-format --version find . -regex '.*\.\(cpp\|hpp\|c\|h\)' -exec clang-format-18 -i {} \; - - name: Check for formatting changes run: | if [[ `git status --porcelain` ]]; then @@ -24,4 +25,3 @@ jobs: else echo "Code is properly formatted." fi - diff --git a/CMakeLists.txt b/CMakeLists.txt index 3fa559064..a11e7b7b7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,9 @@ +# ----------------------------------------------------------------------------- +# Basic project setup +# ----------------------------------------------------------------------------- cmake_minimum_required(VERSION 3.21 FATAL_ERROR) -# Set C++ standard, prefer 17, no extensions +# Set C++ standard requirements -- prefer 17, no extensions set(CMAKE_CXX_STANDARD 17 CACHE STRING "C++ standard to be used") set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) @@ -13,7 +16,11 @@ project( LANGUAGES CXX ) +# ----------------------------------------------------------------------------- +# Project configuration and options +# ----------------------------------------------------------------------------- # Include custom CMake modules +list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake") include(cmake/PreventInSourceBuilds.cmake) include(cmake/OpenTurbineOptions.cmake) @@ -28,15 +35,21 @@ openturbine_setup_dependencies() # Setup local project options openturbine_local_options() +# ----------------------------------------------------------------------------- +# Version information +# ----------------------------------------------------------------------------- # Generate a shortened Git SHA for versioning set(GIT_SHA "Unknown" CACHE STRING "SHA this build was generated from") string(SUBSTRING "${GIT_SHA}" 0 8 GIT_SHORT_SHA) -# Set Openturbine Version +# Set OpenTurbine Version set(OPENTURBINE_VERSION_MAJOR 0 CACHE STRING "major version" FORCE) set(OPENTURBINE_VERSION_MINOR 1 CACHE STRING "minor version" FORCE) set(OPENTURBINE_VERSION ${OPENTURBINE_VERSION_MAJOR}.${OPENTURBINE_VERSION_MINOR} CACHE STRING "version" FORCE) +# ----------------------------------------------------------------------------- +# Library targets +# ----------------------------------------------------------------------------- # Alias libraries for ease of use in targets add_library(OpenTurbine::openturbine_options ALIAS openturbine_options) add_library(OpenTurbine::openturbine_warnings ALIAS openturbine_warnings) @@ -44,10 +57,14 @@ add_library(OpenTurbine::openturbine_warnings ALIAS openturbine_warnings) # Add the main source directory add_subdirectory(src) +# ----------------------------------------------------------------------------- +# Installation configuration +# ----------------------------------------------------------------------------- include(CMakePackageConfigHelpers) -configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/OpenTurbineConfig.cmake.in - "${CMAKE_CURRENT_BINARY_DIR}/OpenTurbineConfig.cmake" - INSTALL_DESTINATION lib/cmake/OpenTurbine +configure_package_config_file( + ${CMAKE_CURRENT_SOURCE_DIR}/cmake/OpenTurbineConfig.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/OpenTurbineConfig.cmake" + INSTALL_DESTINATION lib/cmake/OpenTurbine ) write_basic_package_version_file( @@ -57,13 +74,21 @@ write_basic_package_version_file( ) install(FILES - "${CMAKE_CURRENT_BINARY_DIR}/OpenTurbineConfig.cmake" - "${CMAKE_CURRENT_BINARY_DIR}/OpenTurbineConfigVersion.cmake" - DESTINATION lib/cmake/OpenTurbine + "${CMAKE_CURRENT_BINARY_DIR}/OpenTurbineConfig.cmake" + "${CMAKE_CURRENT_BINARY_DIR}/OpenTurbineConfigVersion.cmake" + DESTINATION lib/cmake/OpenTurbine ) -# Enable testing if requested +# ----------------------------------------------------------------------------- +# Optional components +# ----------------------------------------------------------------------------- +# Build tests include(CTest) if(OpenTurbine_ENABLE_TESTS) add_subdirectory(tests) endif() + +# Build documentation +if(OpenTurbine_ENABLE_DOCUMENTATION) + add_subdirectory(docs) +endif() diff --git a/cmake/FindDoxysphinx.cmake b/cmake/FindDoxysphinx.cmake new file mode 100644 index 000000000..bd11e2956 --- /dev/null +++ b/cmake/FindDoxysphinx.cmake @@ -0,0 +1,26 @@ +#---------------------------------------------------------------------------------------- +# Finds the Doxysphinx executable and version required for generating Sphinx-compatible +# documentation from Doxygen outputs +#---------------------------------------------------------------------------------------- +find_program(DOXYSPHINX_EXECUTABLE NAMES doxysphinx + DOC "Doxysphinx Documentation Builder" +) + +if(DOXYSPHINX_EXECUTABLE) + execute_process( + COMMAND ${DOXYSPHINX_EXECUTABLE} --version + OUTPUT_VARIABLE DOXYSPHINX_VERSION_OUTPUT + OUTPUT_STRIP_TRAILING_WHITESPACE + ) + if("${DOXYSPHINX_VERSION_OUTPUT}" MATCHES "version ([0-9]+\\.[0-9]+\\.[0-9]+)") + set(DOXYSPHINX_VERSION "${CMAKE_MATCH_1}") + endif() +endif() + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Doxysphinx + REQUIRED_VARS DOXYSPHINX_EXECUTABLE + VERSION_VAR DOXYSPHINX_VERSION +) + +mark_as_advanced(DOXYSPHINX_EXECUTABLE) \ No newline at end of file diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake new file mode 100644 index 000000000..9b171369d --- /dev/null +++ b/cmake/FindSphinx.cmake @@ -0,0 +1,25 @@ +#---------------------------------------------------------------------------------------- +# Finds the Sphinx documentation builder and its version +#---------------------------------------------------------------------------------------- +find_program(SPHINX_EXECUTABLE NAMES sphinx-build + DOC "Sphinx Documentation Builder (sphinx-doc.org)" +) + +if(SPHINX_EXECUTABLE) + execute_process( + COMMAND ${SPHINX_EXECUTABLE} --version + OUTPUT_VARIABLE SPHINX_VERSION_OUTPUT + OUTPUT_STRIP_TRAILING_WHITESPACE + ) + if("${SPHINX_VERSION_OUTPUT}" MATCHES ".* ([^\n]+)\n") + set(SPHINX_VERSION "${CMAKE_MATCH_1}") + endif() +endif() + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Sphinx + REQUIRED_VARS SPHINX_EXECUTABLE + VERSION_VAR SPHINX_VERSION +) + +mark_as_advanced(SPHINX_EXECUTABLE) \ No newline at end of file diff --git a/cmake/OpenTurbineOptions.cmake b/cmake/OpenTurbineOptions.cmake index 366b726c9..a7e088231 100644 --- a/cmake/OpenTurbineOptions.cmake +++ b/cmake/OpenTurbineOptions.cmake @@ -1,25 +1,50 @@ include(cmake/SystemLink.cmake) +#-------------------------------------------------------------------------- +# OpenTurbine Build Options +#-------------------------------------------------------------------------- macro(openturbine_setup_options) - # Define project options with default values + #---------------------------------------- + # Core build options + #---------------------------------------- option(OpenTurbine_ENABLE_TESTS "Build Tests" ON) + option(OpenTurbine_ENABLE_DOCUMENTATION "Build Documentation" OFF) option(OpenTurbine_ENABLE_COVERAGE "Enable coverage reporting" OFF) option(OpenTurbine_ENABLE_IPO "Enable IPO/LTO (Interprocedural Optimization/Link Time Optimization)" OFF) option(OpenTurbine_WARNINGS_AS_ERRORS "Treat warnings as errors" OFF) + + #---------------------------------------- + # Sanitizer options + #---------------------------------------- option(OpenTurbine_ENABLE_SANITIZER_ADDRESS "Enable address sanitizer" OFF) option(OpenTurbine_ENABLE_SANITIZER_LEAK "Enable leak sanitizer" OFF) option(OpenTurbine_ENABLE_SANITIZER_UNDEFINED "Enable undefined behavior sanitizer" OFF) option(OpenTurbine_ENABLE_SANITIZER_THREAD "Enable thread sanitizer" OFF) option(OpenTurbine_ENABLE_SANITIZER_MEMORY "Enable memory sanitizer" OFF) + + #---------------------------------------- + # Build optimization options + #---------------------------------------- option(OpenTurbine_ENABLE_UNITY_BUILD "Enable unity builds" OFF) + option(OpenTurbine_ENABLE_PCH "Enable precompiled headers" OFF) + + #---------------------------------------- + # Static analysis options + #---------------------------------------- option(OpenTurbine_ENABLE_CLANG_TIDY "Enable clang-tidy" OFF) option(OpenTurbine_ENABLE_CPPCHECK "Enable CppCheck analysis" OFF) - option(OpenTurbine_ENABLE_PCH "Enable precompiled headers" OFF) + + #---------------------------------------- + # External dependencies + #---------------------------------------- option(OpenTurbine_ENABLE_VTK "Use VTK for visualization" OFF) option(OpenTurbine_BUILD_OPENFAST_ADI "Build the OpenFAST ADI external project" OFF) option(OpenTurbine_BUILD_ROSCO_CONTROLLER "Build the ROSCO controller external project" OFF) endmacro() +#-------------------------------------------------------------------------- +# OpenTurbine Global Options +#-------------------------------------------------------------------------- macro(openturbine_global_options) # Enable IPO/LTO if the option is set if(OpenTurbine_ENABLE_IPO) @@ -28,13 +53,21 @@ macro(openturbine_global_options) endif() endmacro() +#-------------------------------------------------------------------------- +# Project-Wide Configuration Options +#-------------------------------------------------------------------------- macro(openturbine_local_options) + #---------------------------------------- + # Core setup + #---------------------------------------- # Include standard project settings and create interface libraries include(cmake/StandardProjectSettings.cmake) add_library(openturbine_warnings INTERFACE) add_library(openturbine_options INTERFACE) - # Set compiler warnings + #---------------------------------------- + # Compiler warnings + #---------------------------------------- include(cmake/CompilerWarnings.cmake) openturbine_set_project_warnings( openturbine_warnings @@ -44,7 +77,9 @@ macro(openturbine_local_options) "" ) - # Enable sanitizers if specified + #---------------------------------------- + # Sanitizers configuration + #---------------------------------------- include(cmake/Sanitizers.cmake) openturbine_enable_sanitizers( openturbine_options @@ -55,22 +90,30 @@ macro(openturbine_local_options) ${OpenTurbine_ENABLE_SANITIZER_MEMORY} ) - # Set unity build i.e. compile multiple source files into one - set_target_properties(openturbine_options PROPERTIES UNITY_BUILD ${OpenTurbine_ENABLE_UNITY_BUILD}) + #---------------------------------------- + # Build optimizations + #---------------------------------------- + # Configure unity build + set_target_properties(openturbine_options + PROPERTIES UNITY_BUILD ${OpenTurbine_ENABLE_UNITY_BUILD} + ) - # Enable precompiled headers if specified + # Configure precompiled headers if(OpenTurbine_ENABLE_PCH) target_precompile_headers( openturbine_options INTERFACE - - - + + + ) endif() - # Enable static analysis tools if specified + #---------------------------------------- + # Static analysis tools + #---------------------------------------- include(cmake/StaticAnalyzers.cmake) + if(OpenTurbine_ENABLE_CLANG_TIDY) openturbine_enable_clang_tidy(openturbine_options ${OpenTurbine_WARNINGS_AS_ERRORS}) endif() @@ -79,7 +122,9 @@ macro(openturbine_local_options) openturbine_enable_cppcheck(${OpenTurbine_WARNINGS_AS_ERRORS} "") endif() - # Enable coverage reporting if specified + #---------------------------------------- + # Coverage configuration + #---------------------------------------- if(OpenTurbine_ENABLE_COVERAGE) include(cmake/Tests.cmake) openturbine_enable_coverage(openturbine_options) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 000000000..00bb8ab62 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,88 @@ +#-------------------------------------------------------------------------- +# Directory Setup +#-------------------------------------------------------------------------- +set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/sphinx) +set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx) +set(DOXYGEN_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/doxygen) +set(DOXYGEN_INPUT_DIR ${CMAKE_SOURCE_DIR}/src) +set(DOXYGEN_OUTPUT_DIR ${SPHINX_SOURCE}/doxygen) +set(DOXYGEN_HTML_OUTPUT_DIR ${DOXYGEN_OUTPUT_DIR}/html) + +# Create output directory if it doesn't exist +file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) + +#-------------------------------------------------------------------------- +# Doxygen Configuration +#-------------------------------------------------------------------------- +find_package(Doxygen REQUIRED) + +# Collect source files and set up Doxygen paths +file(GLOB_RECURSE OPENTURBINE_PUBLIC_SOURCE + ${DOXYGEN_INPUT_DIR}/*.hpp + ${DOXYGEN_INPUT_DIR}/*.cpp +) +set(DOXYGEN_INDEX_FILE ${DOXYGEN_HTML_OUTPUT_DIR}/index.html) +set(DOXYGEN_TAG_FILE ${DOXYGEN_HTML_OUTPUT_DIR}/tagfile.xml) +set(DOXYGEN_AWESOME_STYLE_FILE ${CMAKE_SOURCE_DIR}/submods/doxygen-awesome-css/doxygen-awesome.css) +set(DOXYFILE_IN ${DOXYGEN_SOURCE_DIR}/Doxyfile) +set(DOXYFILE_OUT ${DOXYGEN_OUTPUT_DIR}/Doxyfile_output) + +# Configure Doxyfile +configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) + +# Doxygen build command +add_custom_command( + OUTPUT ${DOXYGEN_INDEX_FILE} + DEPENDS ${OPENTURBINE_PUBLIC_SOURCE} + DEPENDS ${DOXYGEN_SOURCE_DIR}/mainpage.md + COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} + MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN} + COMMENT "Generating API documentation with Doxygen" +) + +add_custom_target(doxygen + DEPENDS ${DOXYGEN_INDEX_FILE} + COMMENT "Generating API documentation with Doxygen" +) + +#-------------------------------------------------------------------------- +# Doxysphinx Configuration +#-------------------------------------------------------------------------- +find_package(Doxysphinx REQUIRED) + +add_custom_target(doxysphinx + COMMAND ${DOXYSPHINX_EXECUTABLE} build + ${SPHINX_SOURCE} ${SPHINX_BUILD}/html ${DOXYGEN_HTML_OUTPUT_DIR} + COMMENT "Converting Doxygen documentation to Sphinx format" +) +add_dependencies(doxysphinx doxygen) + +#-------------------------------------------------------------------------- +# Sphinx Configuration +#-------------------------------------------------------------------------- +find_package(Sphinx REQUIRED) + +# Spell checking target +# Spell check target is disabled +# add_custom_target(sphinx-spelling +# COMMAND ${SPHINX_EXECUTABLE} -b spelling +# ${SPHINX_SOURCE} ${SPHINX_BUILD}/spelling +# COMMENT "Running spell check on documentation" +# ) +# add_dependencies(sphinx-spelling doxysphinx) + +# Main Sphinx documentation build +add_custom_target(sphinx + COMMAND ${SPHINX_EXECUTABLE} -M html + ${SPHINX_SOURCE} ${SPHINX_BUILD} + -c ${SPHINX_SOURCE} -W --keep-going -n + COMMENT "Generating HTML documentation with Sphinx" +) +# add_dependencies(sphinx sphinx-spelling) +add_dependencies(sphinx doxysphinx) + +#-------------------------------------------------------------------------- +# Main Documentation Target +#-------------------------------------------------------------------------- +add_custom_target(docs ALL) +add_dependencies(docs sphinx) diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 4c707164c..000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,46 +0,0 @@ -# Book settings -# Learn more at https://jupyterbook.org/customize/config.html - -title: OpenTurbine -author: National Renewable Energy Laboratory -# logo: logo.png -copyright: '2023' -only_build_toc_files: true - -# Force re-execution of notebooks on each build. -# See https://jupyterbook.org/content/execute.html -execute: - execute_notebooks: auto - -# Define the name of the latex output file for PDF builds -# latex: -# latex_documents: -# targetname: book.tex - -# Add a bibtex file so that we can create citations -# bibtex_bibfiles: -# - references.bib - -# Information about where the book exists on the web -repository: - url: https://github.com/exawind/openturbine - path_to_book: docs - branch: main - -# Add GitHub buttons to your book -# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository -html: - use_issues_button: true - use_repository_button: true - use_edit_page_button: true - # google_analytics_id: G-L8RGXZCW3F - -sphinx: - mermaid_version: 8.13.3 - extra_extensions: - - 'sphinxcontrib.mermaid' -# - 'sphinx.ext.autodoc' -# - 'sphinx.ext.autosummary' -# - 'sphinx.ext.viewcode' -# config: -# html_theme: sphinx_book_theme diff --git a/docs/_toc.yml b/docs/_toc.yml deleted file mode 100644 index edea69ed2..000000000 --- a/docs/_toc.yml +++ /dev/null @@ -1,17 +0,0 @@ -# Table of contents -# Learn more at https://jupyterbook.org/customize/toc.html - -format: jb-book -root: intro -chapters: -- file: getting_started -- file: tutorials -- file: input_file -- file: reference -- file: dev_guide - sections: - - file: dev_plan - - file: compiling - - file: documentation - - file: tools - - file: api_docs diff --git a/docs/api_docs.md b/docs/api_docs.md deleted file mode 100644 index a3e412544..000000000 --- a/docs/api_docs.md +++ /dev/null @@ -1,6 +0,0 @@ -# API Documentation - -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: diff --git a/docs/compiling.md b/docs/compiling.md deleted file mode 100644 index 34edf4bd8..000000000 --- a/docs/compiling.md +++ /dev/null @@ -1,198 +0,0 @@ -# Compiling - -OpenTurbine is written in C++17 and should be buildable on all systems with a compliant compiler. -Because it leverages Kokkos and Trilinos for performance portability, OpenTurbine is expected to run anywhere that those projects support. -Every effort is made to test on a variety of platforms, including both Linux and MacOS, but it is unlikely that we routinely cover all possibilities. -This page documents the build proceedure as known to work on Linux (RHEL8). -Please reach out to the developers if additional guidance is needed for your particular situation. - -## Spack Installation - -The easiest way to use OpenTurbine is through the [Spack](https://spack.io/) package manager. -Once you have downloaded and set up Spack for your environment, simply run -```bash -spack install openturbine -``` -To see the latest list of supported configuration options, check out the package file or run -```bash -spack info openturbine -``` -Once it is installed, you can load the OpenTurbine library and its dependencies into your environment using -```bash -spack load openturbine -``` - -## Development using Spack Developer Workflow - -One easy way to set up a development environment for OpenTurbine is to use Spack's Developer Workflow. -To setup an environment for working on OpenTurbine, setup Spack and then run the following commands: -```bash -mkdir openturbine -cd openturbine -spack env create -d . -spack env activate . -spack add openturbine+tests -spack install -spack develop openturbine@main -spack concretize -f -spack install -``` -OpenTurbine's source code will now be located in the openturbine folder, but can be accessed from anywhere by -```bash -spack cd -c openturbine -``` -After editing the code here, it can be rebuilt by running -```bash -spack install -``` -To run the tests, first access the build folder through the spack command -```bash -spack cd -b openturbine -``` -Next, the tests can be run either through ctest or directly from the unit test or regression test executables -```bash -ctest -./tests/unit_tests/openturbine_unit_tests -./tests/regression_tests/openturbine_regression_tests -``` -You can also build OpenTurbine from this folder using standard make commands. - -For more information, please see Spack's documentation: https://spack-tutorial.readthedocs.io/en/latest/tutorial_developer_workflows.html - -## Building and Developing in OpenTurbine Directly - -The following sections outline how to build and develop OpenTurbine without Spack's Developer Workflows. -The main complication here is that developers will have to manage their environment and dependicies manually, which may be an unnecessary complication or a freeing feature, depending on your perspective. - -## Dependencies - -Before building OpenTurbine, you'll need the following: - -- C++ compiler that supports the C++17 standard -- [CMake]() the default build system for C++ projects, version 3.21+ -- [Kokkos](https://github.com/kokkos/kokkos) core programming model for performance portability -- [KokkosKernels](https://github.com/kokkos/kokkoskernels) performance portable linear algebra library -- [Trilinos](https://github.com/trilinos/Trilinos) primarily for the Amesos2 sparse direct linear solver package -- [GoogleTest](https://github.com/google/googletest) unit testing package - -## Installing Third Party Librariess - -While there are many ways to get the required Third Party Libraries (TPLs) for building, the easiest is the use the [spack](https://github.com/spack/spack) package manager. -Spack provides a rich featureset for development and dependency management. -The following should be considered a quick-start guide for installing and loading the TPLs you'll need for building OpenTurbine. - -### Clone the spack repository, load the spack environment, and let spack learn about your system -```bash -git clone git@github.com:spack/spack.git -source spack/share/spack/setup-env.sh -spack compiler find -spack external find -``` - -### Install GoogleTest -```bash -spack install googletest -``` - -### Install Trilinos. - -For building OpenTurbine, Kokkos Kernels must be configured to use the LAPACK and BLAS TPLs. -When building for GPU, the Trilinos must be build with support for the Basker linear solver -We also commonly disable EPetra explicitly to prevent deprication warnings. -At the time of this writing, OpenTurbine is known to work with Trilinos version 16.0.0 - the latest and default version in spack - -For a simple serial build -```bash -spack install trilinos~epetra ^kokkos-kernels+blas+lapack -``` - -Trilinos can also be compiled with OpenMP support for parallelism on CPU based machines -```bash -spack install trilinos~epetra+openmp ^kokkos-kernels+blas+lapack -``` - -If building for CUDA platforms, Trilinos must be configured with CUDA support -```bash -spack install trilinos~epetra+basker+cuda ^kokkos-kernels+blas+lapack -``` - -If building for ROCm platforms, Trilinos must be configured with ROCm support -```bash -spack install trilinos~epetra+basker+rocm ^kokkos-kernels+blas+lapack -``` - -Trilinos can be built with or without mpi support. - -### Load the TPLs into your environment -```bash -spack load googletest -spack load trilinos -``` - -Trilinos can also be compiled with support for other platforms. -It is assumed that OpenTurbine will inherit compatibility with them, but they have not been tested at the time of writing. - -For those that choose not to use spack, you must build all of the dependencies manually. -You will have to ensure the the `Amesos2_DIR`, `GTest_DIR`, and `KokkosKernels_DIR` environment variables are properly set for those packages, or otherwise make sure that cmake's `find_package` utility will be able to find them. - -## Building OpenTurbine - -The following is written assuming the TPLs in hand and the environment configured as described above. - -### Clone OpenTurbine and setup a build directory -```bash -git clone git@github.com:Exawind/openturbine.git -cd openturbine -mkdir build -cd build -``` - -### Configure cmake - -For a CPU-based build which includes building unit tests, use -```bash -cmake ../ -``` - -If Trilinos was built with CUDA support, you will need to use the nvcc_wrapper for compilation -```bash -cmake ../ -DCMAKE_CXX_COMPILER=nvcc_wrapper -``` - -If Trilinos was built with ROCm support, you will need to use the hipcc program for compilation -```bash -cmake ../ -DCMAKE_CXX_COMPILER=hipcc -``` - -### Build and Test -At this time, OpenTurbine builds several shared libraries by default. -In order for thier unit tests to pass, they will have to be copied into the directory where your tests are run. -```bash -make -j -cp src/*.dll tests/unit_tests/ -ctest --output-on-failure -``` - -Once built, the unit test executable can also be run directly from the build directory -```bash -./tests/unit_tests/openturbine_unit_tests -``` - -### Build Options - -OpenTurbine has several build options which can be set either when running cmake from the commandline or through a GUI such as ccmake. - -- [OpenTurbine_ENABLE_CLANG_TIDY] enables the Clang-Tidy static analysis tool -- [OpenTurbine_ENABLE_COVERAGE] enables code coverage analysis using gcov -- [OpenTurbine_ENABLE_CPPCHECK] enables the CppCheck static analysis tool -- [OpenTurbine_ENABLE_IPO] enables link time optimization -- [OpenTurbine_ENABLE_PCH] builds precompiled headers to potentially decrease compilation time -- [OpenTurbine_ENABLE_SANITIZER_ADDRESS] enables the address sanitizer runtime analysis tool -- [OpenTurbine_ENABLE_SANITIZER_LEAK] enables the leak sanitizer runtime analysis tool -- [OpenTurbine_ENABLE_SANITIZER_MEMORY] enables the memory sanitizer runtime analysis tool -- [OpenTurbine_ENABLE_SANITIZER_THREAD] enables the thread sanitizer runtime analysis tool -- [OpenTurbine_ENABLE_SANITIZER_UNDEFINED] enables the undefined behavior sanitizer runtime analysis tool -- [OpenTurbine_ENABLE_TESTS] builds OpenTurbine's test suite -- [OpenTurbine_ENABLE_UNITY_BUILD] uses unity builds to potentially decrease compilation time -- [OpenTurbine_ENABLE_VTK] builds OpenTurbine with VTK support for visualization in tests. Will need the VTK TPL to be properly configured -- [OpenTurbine_WARNINGS_AS_ERRORS] treats warnings as errors, including warnings from static analysis tools diff --git a/docs/documentation.md b/docs/documentation.md deleted file mode 100644 index 7dc2c2b09..000000000 --- a/docs/documentation.md +++ /dev/null @@ -1,42 +0,0 @@ -# The Docs - -The documentation is constructed using -[Jupyter-Book](https://jupyterbook.org/en/stable/intro.html), -a framework built on tyop of Sphinx that supports communication -about software as a first priority. Markdown and restructured -test files are both supported as documentation content. -Additional markdown features through MyST are supported and -Jupyter-Book integrates with all Sphinx extensions plus additional -extensions specific to this framework. The config file is at -`docs/_config.yml`. The `sphinx:` section allows for using any -configuration parameters used directly in Sphinx. - -The online documentation is hosted through GitHub Pages and -built and deployed automatically when any file in `docs/` is -modified. See the workflow at `.github/workflows/deploy-pages.yaml` -for reference. - - -## Building locally - -The documentation can be compiled locally using -Jupyter-Book and a few other packages. All dependencies are listed -at `docs/requirements.txt` and can be installed with `pip`. -The commands below describe installing and building the docs. - -```bash -# Move into docs/ directory -cd docs/ - -# Install all depdencies including jupyter-book -pip install -r requirements.txt - -# Build the docs -jupyter-book build . -``` - -Upon successfully compiling, a html file will be available -at `_build/html/index.html`. This can be opened and navigated -with any web browser. - - diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index ad6802461..1f9b99997 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -1,7 +1,7 @@ -# Doxyfile 1.9.6 +# Doxyfile 1.13.2 # This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project. +# Doxygen (www.doxygen.org) for a project. # # All text after a double hash (##) is considered a comment and is placed in # front of the TAG it is preceding. @@ -15,10 +15,10 @@ # # Note: # -# Use doxygen to compare the used configuration file with the template +# Use Doxygen to compare the used configuration file with the template # configuration file: # doxygen -x [configFile] -# Use doxygen to compare the used configuration file with the template +# Use Doxygen to compare the used configuration file with the template # configuration file without replacing the environment variables or CMake type # replacement variables: # doxygen -x_noenv [configFile] @@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "OpenTurbine" +PROJECT_NAME = "OpenTurbine API" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -51,7 +51,7 @@ PROJECT_NAME = "OpenTurbine" PROJECT_NUMBER = # Using the PROJECT_BRIEF tag one can provide an optional one line description -# for a project that appears at the top of each page and should give viewer a +# for a project that appears at the top of each page and should give viewers a # quick idea about the purpose of the project. Keep the description short. PROJECT_BRIEF = "A flexible multibody structural dynamics code for wind turbines" @@ -63,18 +63,24 @@ PROJECT_BRIEF = "A flexible multibody structural dynamics code for wind PROJECT_LOGO = +# With the PROJECT_ICON tag one can specify an icon that is included in the tabs +# when the HTML document is shown. Doxygen will copy the logo to the output +# directory. + +PROJECT_ICON = + # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is -# entered, it will be relative to the location where doxygen was started. If +# entered, it will be relative to the location where Doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ./docs/doxygen +OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@" -# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 +# If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format # and will distribute the generated files over these directories. Enabling this -# option can be useful when feeding doxygen a huge amount of source files, where -# putting all generated files in the same directory would otherwise causes +# option can be useful when feeding Doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise cause # performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to # control the number of sub-directories. # The default value is: NO. @@ -92,7 +98,7 @@ CREATE_SUBDIRS = NO CREATE_SUBDIRS_LEVEL = 8 -# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# If the ALLOW_UNICODE_NAMES tag is set to YES, Doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode # U+3044. @@ -101,7 +107,7 @@ CREATE_SUBDIRS_LEVEL = 8 ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this +# documentation generated by Doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. # Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian, # Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English @@ -115,14 +121,14 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# If the BRIEF_MEMBER_DESC tag is set to YES, Doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# If the REPEAT_BRIEF tag is set to YES, Doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the @@ -153,13 +159,13 @@ ABBREVIATE_BRIEF = "The $name class" \ the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# doxygen will generate a detailed section even if there is only a brief +# Doxygen will generate a detailed section even if there is only a brief # description. # The default value is: NO. ALWAYS_DETAILED_SEC = NO -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# If the INLINE_INHERITED_MEMB tag is set to YES, Doxygen will show all # inherited members of a class in the documentation of that class as if those # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. @@ -167,7 +173,7 @@ ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# If the FULL_PATH_NAMES tag is set to YES, Doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. @@ -177,11 +183,11 @@ FULL_PATH_NAMES = YES # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand # part of the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the path to +# If left blank the directory from which Doxygen is run is used as the path to # strip. # # Note that you can specify absolute paths here, but also relative paths, which -# will be relative from the directory where doxygen is started. +# will be relative from the directory where Doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = @@ -195,41 +201,42 @@ STRIP_FROM_PATH = STRIP_FROM_INC_PATH = -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but -# less readable) file names. This can be useful is your file systems doesn't +# If the SHORT_NAMES tag is set to YES, Doxygen will generate much shorter (but +# less readable) file names. This can be useful if your file system doesn't # support long names like on DOS, Mac, or CD-ROM. # The default value is: NO. SHORT_NAMES = NO -# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the -# first line (until the first dot) of a Javadoc-style comment as the brief -# description. If set to NO, the Javadoc-style will behave just like regular Qt- -# style comments (thus requiring an explicit @brief command for a brief -# description.) +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen will interpret the +# first line (until the first dot, question mark or exclamation mark) of a +# Javadoc-style comment as the brief description. If set to NO, the Javadoc- +# style will behave just like regular Qt-style comments (thus requiring an +# explicit @brief command for a brief description.) # The default value is: NO. JAVADOC_AUTOBRIEF = NO -# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# If the JAVADOC_BANNER tag is set to YES then Doxygen will interpret a line # such as # /*************** # as being the beginning of a Javadoc-style comment "banner". If set to NO, the # Javadoc-style will behave just like regular comments and it will not be -# interpreted by doxygen. +# interpreted by Doxygen. # The default value is: NO. -JAVADOC_BANNER = NO +JAVADOC_BANNER = YES -# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first -# line (until the first dot) of a Qt-style comment as the brief description. If -# set to NO, the Qt-style will behave just like regular Qt-style comments (thus -# requiring an explicit \brief command for a brief description.) +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will interpret the first +# line (until the first dot, question mark or exclamation mark) of a Qt-style +# comment as the brief description. If set to NO, the Qt-style will behave just +# like regular Qt-style comments (thus requiring an explicit \brief command for +# a brief description.) # The default value is: NO. -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen treat a # multi-line C++ special comment block (i.e. a block of //! or /// comments) as # a brief description. This used to be the default behavior. The new default is # to treat a multi-line C++ comment block as a detailed description. Set this @@ -241,10 +248,10 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO -# By default Python docstrings are displayed as preformatted text and doxygen's +# By default Python docstrings are displayed as preformatted text and Doxygen's # special commands cannot be used. By setting PYTHON_DOCSTRING to NO the -# doxygen's special commands can be used and the contents of the docstring -# documentation blocks is shown as doxygen documentation. +# Doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as Doxygen documentation. # The default value is: YES. PYTHON_DOCSTRING = YES @@ -255,7 +262,7 @@ PYTHON_DOCSTRING = YES INHERIT_DOCS = YES -# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# If the SEPARATE_MEMBER_PAGES tag is set to YES then Doxygen will produce a new # page for each member. If set to NO, the documentation of a member will be part # of the file/class/namespace that contains it. # The default value is: NO. @@ -325,30 +332,30 @@ OPTIMIZE_OUTPUT_SLICE = NO # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# language is one of the parsers supported by Doxygen: IDL, Java, JavaScript, # Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, # VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser # tries to guess whether the code is fixed or free formatted code, this is the -# default for Fortran type files). For instance to make doxygen treat .inc files +# default for Fortran type files). For instance to make Doxygen treat .inc files # as Fortran files (default is PHP), and .f files as C (default is Fortran), # use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. When specifying no_extension you should add +# the files are not read by Doxygen. When specifying no_extension you should add # * to the FILE_PATTERNS. # # Note see also the list of default file extension mappings. EXTENSION_MAPPING = -# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# If the MARKDOWN_SUPPORT tag is enabled then Doxygen pre-processes all comments # according to the Markdown format, which allows for more readable # documentation. See https://daringfireball.net/projects/markdown/ for details. -# The output of markdown processing is further processed by doxygen, so you can -# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# The output of markdown processing is further processed by Doxygen, so you can +# mix Doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. # The default value is: YES. @@ -358,25 +365,45 @@ MARKDOWN_SUPPORT = YES # to that level are automatically included in the table of contents, even if # they do not have an id attribute. # Note: This feature currently applies only to Markdown headings. -# Minimum value: 0, maximum value: 99, default value: 5. +# Minimum value: 0, maximum value: 99, default value: 6. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 0 + +# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to +# generate identifiers for the Markdown headings. Note: Every identifier is +# unique. +# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a +# sequence number starting at 0 and GITHUB use the lower case version of title +# with any whitespace replaced by '-' and punctuation characters removed. +# The default value is: DOXYGEN. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 5 +MARKDOWN_ID_STYLE = DOXYGEN -# When enabled doxygen tries to link words that correspond to documented +# When enabled Doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or -# globally by setting AUTOLINK_SUPPORT to NO. +# globally by setting AUTOLINK_SUPPORT to NO. Words listed in the +# AUTOLINK_IGNORE_WORDS tag are excluded from automatic linking. # The default value is: YES. AUTOLINK_SUPPORT = YES +# This tag specifies a list of words that, when matching the start of a word in +# the documentation, will suppress auto links generation, if it is enabled via +# AUTOLINK_SUPPORT. This list does not affect affect links explicitly created +# using \# or the \link or commands. +# This tag requires that the tag AUTOLINK_SUPPORT is set to YES. + +AUTOLINK_IGNORE_WORDS = + # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should set this -# tag to YES in order to let doxygen match functions declarations and +# tag to YES in order to let Doxygen match functions declarations and # definitions whose arguments contain STL classes (e.g. func(std::string); -# versus func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. +# versus func(std::string) {}). This also makes the inheritance and +# collaboration diagrams that involve STL classes more complete and accurate. # The default value is: NO. BUILTIN_STL_SUPPORT = NO @@ -388,16 +415,16 @@ BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen -# will parse them like normal C++ but will assume all classes use public instead -# of private inheritance when no explicit protection keyword is present. +# https://www.riverbankcomputing.com/software) sources only. Doxygen will parse +# them like normal C++ but will assume all classes use public instead of private +# inheritance when no explicit protection keyword is present. # The default value is: NO. SIP_SUPPORT = NO # For Microsoft's IDL there are propget and propput attributes to indicate # getter and setter methods for a property. Setting this option to YES will make -# doxygen to replace the get and set methods by a property in the documentation. +# Doxygen to replace the get and set methods by a property in the documentation. # This will only work if the methods are indeed getting or setting a simple # type. If this is not the case, or you want to show the methods anyway, you # should set this option to NO. @@ -406,7 +433,7 @@ SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES then doxygen will reuse the documentation of the first +# tag is set to YES then Doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. @@ -464,18 +491,18 @@ TYPEDEF_HIDES_STRUCT = NO # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This # cache is used to resolve symbols given their name and scope. Since this can be # an expensive process and often the same symbol appears multiple times in the -# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small -# doxygen will become slower. If the cache is too large, memory is wasted. The +# code, Doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# Doxygen will become slower. If the cache is too large, memory is wasted. The # cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range # is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 -# symbols. At the end of a run doxygen will report the cache usage and suggest +# symbols. At the end of a run Doxygen will report the cache usage and suggest # the optimal cache size from a speed point of view. # Minimum value: 0, maximum value: 9, default value: 0. LOOKUP_CACHE_SIZE = 0 -# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use -# during processing. When set to 0 doxygen will based this on the number of +# The NUM_PROC_THREADS specifies the number of threads Doxygen is allowed to use +# during processing. When set to 0 Doxygen will based this on the number of # cores available in the system. You can set it explicitly to a value larger # than 0 to get more control over the balance between CPU load and processing # speed. At this moment only the input processing can be done using multiple @@ -487,11 +514,19 @@ LOOKUP_CACHE_SIZE = 0 NUM_PROC_THREADS = 1 +# If the TIMESTAMP tag is set different from NO then each generated page will +# contain the date or date and time when the page was generated. Setting this to +# NO can help when comparing the output of multiple runs. +# Possible values are: YES, NO, DATETIME and DATE. +# The default value is: NO. + +TIMESTAMP = NO + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# If the EXTRACT_ALL tag is set to YES, Doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. @@ -557,7 +592,7 @@ EXTRACT_ANON_NSPACES = NO RESOLVE_UNNAMED_PARAMS = YES -# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation # section is generated. This option has no effect if EXTRACT_ALL is enabled. @@ -565,7 +600,7 @@ RESOLVE_UNNAMED_PARAMS = YES HIDE_UNDOC_MEMBERS = NO -# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option # will also hide undocumented C++ concepts if enabled. This option has no effect @@ -574,14 +609,22 @@ HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# If the HIDE_UNDOC_NAMESPACES tag is set to YES, Doxygen will hide all +# undocumented namespaces that are normally visible in the namespace hierarchy. +# If set to NO, these namespaces will be included in the various overviews. This +# option has no effect if EXTRACT_ALL is enabled. +# The default value is: YES. + +HIDE_UNDOC_NAMESPACES = YES + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all friend # declarations. If set to NO, these declarations will be included in the # documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO -# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any # documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. @@ -595,7 +638,7 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO -# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# With the correct setting of option CASE_SENSE_NAMES Doxygen will better be # able to match the capabilities of the underlying filesystem. In case the # filesystem is case sensitive (i.e. it supports files in the same directory # whose names only differ in casing), the option must be set to YES to properly @@ -604,7 +647,7 @@ INTERNAL_DOCS = NO # output files written for symbols that only differ in casing, such as for two # classes, one named CLASS and the other named Class, and to also support # references to files without having to specify the exact matching casing. On -# Windows (including Cygwin) and MacOS, users should typically set this option +# Windows (including Cygwin) and macOS, users should typically set this option # to NO, whereas on Linux or other Unix flavors it should typically be set to # YES. # Possible values are: SYSTEM, NO and YES. @@ -612,14 +655,14 @@ INTERNAL_DOCS = NO CASE_SENSE_NAMES = SYSTEM -# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. HIDE_SCOPE_NAMES = NO -# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then Doxygen will # append additional text to a page's title, such as Class Reference. If set to # YES the compound reference will be hidden. # The default value is: NO. @@ -632,7 +675,7 @@ HIDE_COMPOUND_REFERENCE= NO SHOW_HEADERFILE = YES -# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# If the SHOW_INCLUDE_FILES tag is set to YES then Doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. @@ -645,7 +688,7 @@ SHOW_INCLUDE_FILES = YES SHOW_GROUPED_MEMB_INC = NO -# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen will list include # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. @@ -657,14 +700,14 @@ FORCE_LOCAL_INCLUDES = NO INLINE_INFO = YES -# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# If the SORT_MEMBER_DOCS tag is set to YES then Doxygen will sort the # (detailed) documentation of file and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = YES -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# If the SORT_BRIEF_DOCS tag is set to YES then Doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. Note that # this will also influence the order of the classes in the class list. @@ -672,7 +715,7 @@ SORT_MEMBER_DOCS = YES SORT_BRIEF_DOCS = NO -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then Doxygen will sort the # (brief and detailed) documentation of class members so that constructors and # destructors are listed first. If set to NO the constructors will appear in the # respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. @@ -684,7 +727,7 @@ SORT_BRIEF_DOCS = NO SORT_MEMBERS_CTORS_1ST = NO -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# If the SORT_GROUP_NAMES tag is set to YES then Doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will # appear in their defined order. # The default value is: NO. @@ -701,11 +744,11 @@ SORT_GROUP_NAMES = NO SORT_BY_SCOPE_NAME = NO -# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# If the STRICT_PROTO_MATCHING option is enabled and Doxygen fails to do proper # type resolution of all parameters of a function it will reject a match between # the prototype and the implementation of a member function even if there is # only one candidate or it is obvious which candidate to choose by doing a -# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# simple string match. By disabling STRICT_PROTO_MATCHING Doxygen will still # accept a match between prototype and implementation in such cases. # The default value is: NO. @@ -775,25 +818,25 @@ SHOW_FILES = YES SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from +# Doxygen should invoke to get the current version for each file (typically from # the version control system). Doxygen will invoke the program by executing (via # popen()) the command command input-file, where command is the value of the # FILE_VERSION_FILTER tag, and input-file is the name of an input file provided -# by doxygen. Whatever the program writes to standard output is used as the file +# by Doxygen. Whatever the program writes to standard output is used as the file # version. For an example see the documentation. FILE_VERSION_FILTER = # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed -# by doxygen. The layout file controls the global structure of the generated +# by Doxygen. The layout file controls the global structure of the generated # output files in an output format independent way. To create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. You can +# that represents Doxygen's defaults, run Doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml # will be used as the name of the layout file. See also section "Changing the # layout of pages" for information. # -# Note that if you run doxygen from a directory containing a file called -# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# Note that if you run Doxygen from a directory containing a file called +# DoxygenLayout.xml, Doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. LAYOUT_FILE = @@ -808,19 +851,35 @@ LAYOUT_FILE = CITE_BIB_FILES = +# The EXTERNAL_TOOL_PATH tag can be used to extend the search path (PATH +# environment variable) so that external tools such as latex and gs can be +# found. +# Note: Directories specified with EXTERNAL_TOOL_PATH are added in front of the +# path already specified by the PATH variable, and are added in the order +# specified. +# Note: This option is particularly useful for macOS version 14 (Sonoma) and +# higher, when running Doxygen from Doxywizard, because in this case any user- +# defined changes to the PATH are ignored. A typical example on macOS is to set +# EXTERNAL_TOOL_PATH = /Library/TeX/texbin /usr/local/bin +# together with the standard path, the full search path used by doxygen when +# launching external tools will then become +# PATH=/Library/TeX/texbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin + +EXTERNAL_TOOL_PATH = + #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages #--------------------------------------------------------------------------- # The QUIET tag can be used to turn on/off the messages that are generated to -# standard output by doxygen. If QUIET is set to YES this implies that the +# standard output by Doxygen. If QUIET is set to YES this implies that the # messages are off. # The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# generated to standard error (stderr) by Doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. @@ -828,14 +887,14 @@ QUIET = NO WARNINGS = YES -# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# If the WARN_IF_UNDOCUMENTED tag is set to YES then Doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. WARN_IF_UNDOCUMENTED = YES -# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# If the WARN_IF_DOC_ERROR tag is set to YES, Doxygen will generate warnings for # potential errors in the documentation, such as documenting some parameters in # a documented function twice, or documenting parameters that don't exist or # using markup commands wrongly. @@ -843,8 +902,8 @@ WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES -# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete -# function parameter documentation. If set to NO, doxygen will accept that some +# If WARN_IF_INCOMPLETE_DOC is set to YES, Doxygen will warn about incomplete +# function parameter documentation. If set to NO, Doxygen will accept that some # parameters have no documentation without warning. # The default value is: YES. @@ -852,7 +911,7 @@ WARN_IF_INCOMPLETE_DOC = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return -# value. If set to NO, doxygen will only warn about wrong parameter +# value. If set to NO, Doxygen will only warn about wrong parameter # documentation, but not about the absence of documentation. If EXTRACT_ALL is # set to YES then this flag will automatically be disabled. See also # WARN_IF_INCOMPLETE_DOC @@ -860,24 +919,39 @@ WARN_IF_INCOMPLETE_DOC = YES WARN_NO_PARAMDOC = NO -# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about -# undocumented enumeration values. If set to NO, doxygen will accept +# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, Doxygen will warn about +# undocumented enumeration values. If set to NO, Doxygen will accept # undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: NO. WARN_IF_UNDOC_ENUM_VAL = NO -# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# If WARN_LAYOUT_FILE option is set to YES, Doxygen will warn about issues found +# while parsing the user defined layout file, such as missing or wrong elements. +# See also LAYOUT_FILE for details. If set to NO, problems with the layout file +# will be suppressed. +# The default value is: YES. + +WARN_LAYOUT_FILE = YES + +# If the WARN_AS_ERROR tag is set to YES then Doxygen will immediately stop when # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS -# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but -# at the end of the doxygen process doxygen will return with a non-zero status. -# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# then Doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the Doxygen process Doxygen will return with a non-zero status. +# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then Doxygen behaves +# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined Doxygen will not +# write the warning messages in between other messages but write them at the end +# of a run, in case a WARN_LOGFILE is defined the warning messages will be +# besides being in the defined file also be shown at the end of a run, unless +# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case +# the behavior will remain as with the setting FAIL_ON_WARNINGS. +# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. WARN_AS_ERROR = NO -# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# The WARN_FORMAT tag determines the format of the warning messages that Doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated # and the warning text. Optionally the format may contain $version, which will @@ -890,7 +964,7 @@ WARN_FORMAT = "$file:$line: $text" # In the $text part of the WARN_FORMAT command it is possible that a reference # to a more specific place is given. To make it easier to jump to this place -# (outside of doxygen) the user can define a custom "cut" / "paste" string. +# (outside of Doxygen) the user can define a custom "cut" / "paste" string. # Example: # WARN_LINE_FORMAT = "'vi $file +$line'" # See also: WARN_FORMAT @@ -917,10 +991,11 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ./docs/doxygen/mainpage.txt ./src +INPUT = @CMAKE_SOURCE_DIR@/docs/doxygen/mainpage.md \ + "@DOXYGEN_INPUT_DIR@" # This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv # documentation (see: # https://www.gnu.org/software/libiconv/) for the list of possible encodings. @@ -930,12 +1005,12 @@ INPUT = ./docs/doxygen/mainpage.txt ./src INPUT_ENCODING = UTF-8 # This tag can be used to specify the character encoding of the source files -# that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify +# that Doxygen parses. The INPUT_FILE_ENCODING tag can be used to specify # character encoding on a per file pattern basis. Doxygen will compare the file # name with each pattern and apply the encoding instead of the default -# INPUT_ENCODING) if there is a match. The character encodings are a list of the -# form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding -# "INPUT_ENCODING" for further information on supported encodings. +# INPUT_ENCODING if there is a match. The character encodings are a list of the +# form: pattern=encoding (like *.php=ISO-8859-1). +# See also: INPUT_ENCODING for further information on supported encodings. INPUT_FILE_ENCODING = @@ -945,17 +1020,17 @@ INPUT_FILE_ENCODING = # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not -# read by doxygen. +# read by Doxygen. # # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # -# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, -# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, -# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C -# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, -# *.vhdl, *.ucf, *.qsf and *.ice. +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, +# *.cpp, *.cppm, *.ccm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, +# *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, +# *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to +# be provided as Doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ *.cc \ @@ -1014,7 +1089,7 @@ RECURSIVE = YES # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. # -# Note that relative paths are relative to the directory from which doxygen is +# Note that relative paths are relative to the directory from which Doxygen is # run. EXCLUDE = @@ -1040,9 +1115,6 @@ EXCLUDE_PATTERNS = # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = @@ -1072,7 +1144,7 @@ EXAMPLE_RECURSIVE = NO IMAGE_PATH = -# The INPUT_FILTER tag can be used to specify a program that doxygen should +# The INPUT_FILTER tag can be used to specify a program that Doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command: # @@ -1087,14 +1159,14 @@ IMAGE_PATH = # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. # -# Note that doxygen will use the data processed and written to standard output +# Note that Doxygen will use the data processed and written to standard output # for further processing, therefore nothing else, like debug statements or used # commands (so in case of a Windows batch file always use @echo OFF), should be # written to standard output. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not -# properly processed by doxygen. +# properly processed by Doxygen. INPUT_FILTER = @@ -1107,7 +1179,7 @@ INPUT_FILTER = # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not -# properly processed by doxygen. +# properly processed by Doxygen. FILTER_PATTERNS = @@ -1129,10 +1201,19 @@ FILTER_SOURCE_PATTERNS = # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page # (index.html). This can be useful if you have a project on for instance GitHub -# and want to reuse the introduction page also for the doxygen output. +# and want to reuse the introduction page also for the Doxygen output. USE_MDFILE_AS_MAINPAGE = +# If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub- +# directories of the project's root, is used as the documentation for that sub- +# directory, except when the README.md starts with a \dir, \page or \mainpage +# command. If set to NO, the README.md file needs to start with an explicit \dir +# command in order to be used as directory documentation. +# The default value is: YES. + +IMPLICIT_DIR_DOCS = YES + # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common # extension is to allow longer lines before the automatic comment starts. The @@ -1156,12 +1237,13 @@ FORTRAN_COMMENT_AFTER = 72 SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, -# classes and enums directly into the documentation. +# multi-line macros, enums or list initialized variables directly into the +# documentation. # The default value is: NO. INLINE_SOURCES = NO -# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct Doxygen to hide any # special comment blocks from generated source code fragments. Normal C, C++ and # Fortran comments will always remain visible. # The default value is: YES. @@ -1199,7 +1281,7 @@ REFERENCES_LINK_SOURCE = YES SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will -# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# point to the HTML generated by the htags(1) tool instead of Doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system # (see https://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. @@ -1213,14 +1295,14 @@ SOURCE_TOOLTIPS = YES # Doxygen will invoke htags (and that will in turn invoke gtags), so these # tools must be available from the command line (i.e. in the search path). # -# The result: instead of the source browser generated by doxygen, the links to +# The result: instead of the source browser generated by Doxygen, the links to # source code will now point to the output of htags. # The default value is: NO. # This tag requires that the tag SOURCE_BROWSER is set to YES. USE_HTAGS = NO -# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# If the VERBATIM_HEADERS tag is set the YES then Doxygen will generate a # verbatim copy of the header file for each class for which an include is # specified. Set to NO to disable this. # See also: Section \class. @@ -1252,7 +1334,7 @@ IGNORE_PREFIX = # Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# If the GENERATE_HTML tag is set to YES, Doxygen will generate HTML output # The default value is: YES. GENERATE_HTML = YES @@ -1273,40 +1355,40 @@ HTML_OUTPUT = html HTML_FILE_EXTENSION = .html # The HTML_HEADER tag can be used to specify a user-defined HTML header file for -# each generated HTML page. If the tag is left blank doxygen will generate a +# each generated HTML page. If the tag is left blank Doxygen will generate a # standard header. # # To get valid HTML the header file that includes any scripts and style sheets -# that doxygen needs, which is dependent on the configuration options used (e.g. +# that Doxygen needs, which is dependent on the configuration options used (e.g. # the setting GENERATE_TREEVIEW). It is highly recommended to start with a # default header using # doxygen -w html new_header.html new_footer.html new_stylesheet.css # YourConfigFile # and then modify the file new_header.html. See also section "Doxygen usage" -# for information on how to generate the default header that doxygen normally +# for information on how to generate the default header that Doxygen normally # uses. # Note: The header is subject to change so you typically have to regenerate the -# default header when upgrading to a newer version of doxygen. For a description +# default header when upgrading to a newer version of Doxygen. For a description # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each -# generated HTML page. If the tag is left blank doxygen will generate a standard +# generated HTML page. If the tag is left blank Doxygen will generate a standard # footer. See HTML_HEADER for more information on how to generate a default # footer and what special commands can be used inside the footer. See also # section "Doxygen usage" for information on how to generate the default footer -# that doxygen normally uses. +# that Doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of -# the HTML output. If left blank doxygen will generate a default style sheet. +# the HTML output. If left blank Doxygen will generate a default style sheet. # See also section "Doxygen usage" for information on how to generate the style -# sheet that doxygen normally uses. +# sheet that Doxygen normally uses. # Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as # it is more robust and this tag (HTML_STYLESHEET) will in the future become # obsolete. @@ -1316,7 +1398,7 @@ HTML_STYLESHEET = # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined # cascading style sheets that are included after the standard style sheets -# created by doxygen. Using this option one can overrule certain style aspects. +# created by Doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the # standard style sheet and is therefore more robust against future updates. # Doxygen will copy the style sheet files to the output directory. @@ -1344,11 +1426,11 @@ HTML_EXTRA_FILES = # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output # should be rendered with a dark or light theme. -# Possible values are: LIGHT always generate light mode output, DARK always -# generate dark mode output, AUTO_LIGHT automatically set the mode according to -# the user preference, use light mode if no preference is set (the default), -# AUTO_DARK automatically set the mode according to the user preference, use -# dark mode if no preference is set and TOGGLE allow to user to switch between +# Possible values are: LIGHT always generates light mode output, DARK always +# generates dark mode output, AUTO_LIGHT automatically sets the mode according +# to the user preference, uses light mode if no preference is set (the default), +# AUTO_DARK automatically sets the mode according to the user preference, uses +# dark mode if no preference is set and TOGGLE allows a user to switch between # light and dark mode via a button. # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1385,15 +1467,6 @@ HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via JavaScript. If disabled, the navigation index will @@ -1413,6 +1486,33 @@ HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +# If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be +# dynamically folded and expanded in the generated HTML source code. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_CODE_FOLDING = YES + +# If the HTML_COPY_CLIPBOARD tag is set to YES then Doxygen will show an icon in +# the top right corner of code and text fragments that allows the user to copy +# its content to the clipboard. Note this only works if supported by the browser +# and the web page is served via a secure context (see: +# https://www.w3.org/TR/secure-contexts/), i.e. using the https: or file: +# protocol. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COPY_CLIPBOARD = YES + +# Doxygen stores a couple of settings persistently in the browser (via e.g. +# cookies). By default these settings apply to all HTML pages generated by +# Doxygen across all projects. The HTML_PROJECT_COOKIE tag can be used to store +# the settings under a project specific key, such that the user preferences will +# be stored separately. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_PROJECT_COOKIE = + # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to @@ -1430,7 +1530,7 @@ HTML_INDEX_NUM_ENTRIES = 100 # generated that can be used as input for Apple's Xcode 3 integrated development # environment (see: # https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To -# create a documentation set, doxygen will generate a Makefile in the HTML +# create a documentation set, Doxygen will generate a Makefile in the HTML # output directory. Running make will produce the docset in that directory and # running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at @@ -1478,18 +1578,18 @@ DOCSET_PUBLISHER_ID = org.doxygen.Publisher DOCSET_PUBLISHER_NAME = Publisher -# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# If the GENERATE_HTMLHELP tag is set to YES then Doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop # on Windows. In the beginning of 2021 Microsoft took the original page, with -# a.o. the download links, offline the HTML help workshop was already many years -# in maintenance mode). You can download the HTML help workshop from the web -# archives at Installation executable (see: +# a.o. the download links, offline (the HTML help workshop was already many +# years in maintenance mode). You can download the HTML help workshop from the +# web archives at Installation executable (see: # http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo # ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). # # The HTML Help Workshop contains a compiler that can convert all HTML output -# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# generated by Doxygen into a single compiled HTML file (.chm). Compiled HTML # files are now used as the Windows 98 help format, and will replace the old # Windows help format (.hlp) on all Windows platforms in the future. Compressed # HTML files also contain an index, a table of contents, and you can search for @@ -1509,7 +1609,7 @@ CHM_FILE = # The HHC_LOCATION tag can be used to specify the location (absolute path # including file name) of the HTML help compiler (hhc.exe). If non-empty, -# doxygen will try to run the HTML help compiler on the generated index.hhp. +# Doxygen will try to run the HTML help compiler on the generated index.hhp. # The file has to be specified with full path. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1543,6 +1643,16 @@ BINARY_TOC = NO TOC_EXPAND = NO +# The SITEMAP_URL tag is used to specify the full URL of the place where the +# generated documentation will be placed on the server by the user during the +# deployment of the documentation. The generated sitemap is called sitemap.xml +# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL +# is specified no sitemap is generated. For information about the sitemap +# protocol see https://www.sitemaps.org +# This tag requires that the tag GENERATE_HTML is set to YES. + +SITEMAP_URL = + # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help @@ -1601,7 +1711,7 @@ QHP_CUST_FILTER_ATTRS = QHP_SECT_FILTER_ATTRS = # The QHG_LOCATION tag can be used to specify the location (absolute path -# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# including file name) of Qt's qhelpgenerator. If non-empty Doxygen will try to # run qhelpgenerator on the generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1633,7 +1743,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # of each HTML page. A value of NO enables the index and the value YES disables # it. Since the tabs in the index contain the same information as the navigation # tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. -# The default value is: NO. +# The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO @@ -1646,11 +1756,11 @@ DISABLE_INDEX = NO # (i.e. any modern browser). Windows users are probably better off using the # HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can # further fine tune the look of the index (see "Fine-tuning the output"). As an -# example, the default style sheet generated by doxygen has an example that +# example, the default style sheet generated by Doxygen has an example that # shows how to put an image at the root of the tree instead of the PROJECT_NAME. # Since the tree basically has the same information as the tab index, you could # consider setting DISABLE_INDEX to YES when enabling this option. -# The default value is: NO. +# The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = NO @@ -1668,7 +1778,7 @@ GENERATE_TREEVIEW = NO FULL_SIDEBAR = NO # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that -# doxygen will group on one line in the generated HTML documentation. +# Doxygen will group on one line in the generated HTML documentation. # # Note that a value of 0 will completely suppress the enum values from appearing # in the overview section. @@ -1677,6 +1787,12 @@ FULL_SIDEBAR = NO ENUM_VALUES_PER_LINE = 4 +# When the SHOW_ENUM_VALUES tag is set doxygen will show the specified +# enumeration values besides the enumeration mnemonics. +# The default value is: NO. + +SHOW_ENUM_VALUES = NO + # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. # Minimum value: 0, maximum value: 1500, default value: 250. @@ -1684,21 +1800,21 @@ ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 -# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# If the EXT_LINKS_IN_WINDOW option is set to YES, Doxygen will open links to # external symbols imported via tag files in a separate window. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. EXT_LINKS_IN_WINDOW = NO -# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email +# If the OBFUSCATE_EMAILS tag is set to YES, Doxygen will obfuscate email # addresses. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. OBFUSCATE_EMAILS = YES -# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# If the HTML_FORMULA_FORMAT option is set to svg, Doxygen will use the pdf2svg # tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see # https://inkscape.org) to generate formulas as SVG images instead of PNGs for # the HTML output. These images will generally look nicer at scaled resolutions. @@ -1711,7 +1827,7 @@ HTML_FORMULA_FORMAT = png # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful -# doxygen run you need to manually remove any form_*.png images from the HTML +# Doxygen run you need to manually remove any form_*.png images from the HTML # output directory to force them to be regenerated. # Minimum value: 8, maximum value: 50, default value: 10. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1733,7 +1849,7 @@ FORMULA_MACROFILE = # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -USE_MATHJAX = NO +USE_MATHJAX = YES # With MATHJAX_VERSION it is possible to specify the MathJax version to be used. # Note that the different versions of MathJax have different requirements with @@ -1755,7 +1871,7 @@ MATHJAX_VERSION = MathJax_2 # Possible values are: HTML-CSS (which is slower, but has the best # compatibility. This is the name for Mathjax version 2, for MathJax version 3 # this will be translated into chtml), NativeMML (i.e. MathML. Only supported -# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This +# for MathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This # is the name for Mathjax version 3, for MathJax version 2 this will be # translated into HTML-CSS) and SVG. # The default value is: HTML-CSS. @@ -1775,7 +1891,7 @@ MATHJAX_FORMAT = HTML-CSS # - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = +MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/ # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example @@ -1789,7 +1905,7 @@ MATHJAX_RELPATH = MATHJAX_EXTENSIONS = -# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# The MATHJAX_CODEFILE tag can be used to specify a file with JavaScript pieces # of code that will be used on startup of the MathJax code. See the MathJax site # (see: # http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an @@ -1798,12 +1914,12 @@ MATHJAX_EXTENSIONS = MATHJAX_CODEFILE = -# When the SEARCHENGINE tag is enabled doxygen will generate a search box for -# the HTML output. The underlying search engine uses javascript and DHTML and +# When the SEARCHENGINE tag is enabled Doxygen will generate a search box for +# the HTML output. The underlying search engine uses JavaScript and DHTML and # should work on any modern browser. Note that when using HTML help # (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) # there is already a search function so this one should typically be disabled. -# For large projects the javascript based search engine can be slow, then +# For large projects the JavaScript based search engine can be slow, then # enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to # search using the keyboard; to jump to the search box use + S # (what the is depends on the OS and browser, but it is typically @@ -1822,7 +1938,7 @@ SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be # implemented using a web server instead of a web client using JavaScript. There # are two flavors of web server based searching depending on the EXTERNAL_SEARCH -# setting. When disabled, doxygen will generate a PHP script for searching and +# setting. When disabled, Doxygen will generate a PHP script for searching and # an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing # and searching needs to be provided by external tools. See the section # "External Indexing and Searching" for details. @@ -1831,7 +1947,7 @@ SEARCHENGINE = YES SERVER_BASED_SEARCH = NO -# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# When EXTERNAL_SEARCH tag is enabled Doxygen will no longer generate the PHP # script for searching. Instead the search results are written to an XML file # which needs to be processed by an external indexer. Doxygen will invoke an # external search engine pointed to by the SEARCHENGINE_URL option to obtain the @@ -1876,7 +1992,7 @@ SEARCHDATA_FILE = searchdata.xml EXTERNAL_SEARCH_ID = -# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through Doxygen # projects other than the one defined by this configuration file, but that are # all added to the same external search index. Each project needs to have a # unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of @@ -1890,7 +2006,7 @@ EXTRA_SEARCH_MAPPINGS = # Configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. +# If the GENERATE_LATEX tag is set to YES, Doxygen will generate LaTeX output. # The default value is: YES. GENERATE_LATEX = NO @@ -1935,7 +2051,7 @@ MAKEINDEX_CMD_NAME = makeindex LATEX_MAKEINDEX_CMD = makeindex -# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX +# If the COMPACT_LATEX tag is set to YES, Doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -1966,15 +2082,15 @@ EXTRA_PACKAGES = # The LATEX_HEADER tag can be used to specify a user-defined LaTeX header for # the generated LaTeX document. The header should contain everything until the -# first chapter. If it is left blank doxygen will generate a standard header. It +# first chapter. If it is left blank Doxygen will generate a standard header. It # is highly recommended to start with a default header using # doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty # and then modify the file new_header.tex. See also section "Doxygen usage" for -# information on how to generate the default header that doxygen normally uses. +# information on how to generate the default header that Doxygen normally uses. # # Note: Only use a user-defined header if you know what you are doing! # Note: The header is subject to change so you typically have to regenerate the -# default header when upgrading to a newer version of doxygen. The following +# default header when upgrading to a newer version of Doxygen. The following # commands have a special meaning inside the header (and footer): For a # description of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1983,10 +2099,10 @@ LATEX_HEADER = # The LATEX_FOOTER tag can be used to specify a user-defined LaTeX footer for # the generated LaTeX document. The footer should contain everything after the -# last chapter. If it is left blank doxygen will generate a standard footer. See +# last chapter. If it is left blank Doxygen will generate a standard footer. See # LATEX_HEADER for more information on how to generate a default footer and what # special commands can be used inside the footer. See also section "Doxygen -# usage" for information on how to generate the default footer that doxygen +# usage" for information on how to generate the default footer that Doxygen # normally uses. Note: Only use a user-defined footer if you know what you are # doing! # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1995,7 +2111,7 @@ LATEX_FOOTER = # The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined # LaTeX style sheets that are included after the standard style sheets created -# by doxygen. Using this option one can overrule certain style aspects. Doxygen +# by Doxygen. Using this option one can overrule certain style aspects. Doxygen # will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the @@ -2021,7 +2137,7 @@ LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# If the USE_PDFLATEX tag is set to YES, Doxygen will use the engine as # specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX # files. Set this option to YES, to get a higher quality PDF documentation. # @@ -2031,15 +2147,22 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode -# command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. +# The LATEX_BATCHMODE tag signals the behavior of LaTeX in case of an error. +# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch +# mode nothing is printed on the terminal, errors are scrolled as if is +# hit at every error; missing files that TeX tries to input or request from +# keyboard input (\read on a not open input stream) cause the job to abort, +# NON_STOP In nonstop mode the diagnostic message will appear on the terminal, +# but there is no possibility of user interaction just like in batch mode, +# SCROLL In scroll mode, TeX will stop only for missing files to input or if +# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at +# each error, asking for user intervention. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_BATCHMODE = NO -# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# If the LATEX_HIDE_INDICES tag is set to YES then Doxygen will not include the # index chapters (such as File Index, Compound Index, etc.) in the output. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2049,19 +2172,11 @@ LATEX_HIDE_INDICES = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # https://en.wikipedia.org/wiki/BibTeX and \cite for more info. -# The default value is: plain. +# The default value is: plainnat. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, # it will be relative to the LATEX_OUTPUT directory. If left blank the @@ -2074,7 +2189,7 @@ LATEX_EMOJI_DIRECTORY = # Configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The +# If the GENERATE_RTF tag is set to YES, Doxygen will generate RTF output. The # RTF output is optimized for Word 97 and may not look too pretty with other RTF # readers/editors. # The default value is: NO. @@ -2089,7 +2204,7 @@ GENERATE_RTF = NO RTF_OUTPUT = rtf -# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF +# If the COMPACT_RTF tag is set to YES, Doxygen generates more compact RTF # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -2109,28 +2224,36 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's +# Load stylesheet definitions from file. Syntax is similar to Doxygen's # configuration file, i.e. a series of assignments. You only have to provide # replacements, missing definitions are set to their default value. # # See also section "Doxygen usage" for information on how to generate the -# default style sheet that doxygen normally uses. +# default style sheet that Doxygen normally uses. # This tag requires that the tag GENERATE_RTF is set to YES. RTF_STYLESHEET_FILE = # Set optional variables used in the generation of an RTF document. Syntax is -# similar to doxygen's configuration file. A template extensions file can be +# similar to Doxygen's configuration file. A template extensions file can be # generated using doxygen -e rtf extensionFile. # This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = +# The RTF_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the RTF_OUTPUT output directory. +# Note that the files will be copied as-is; there are no commands or markers +# available. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_EXTRA_FILES = + #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for +# If the GENERATE_MAN tag is set to YES, Doxygen will generate man pages for # classes and files. # The default value is: NO. @@ -2161,7 +2284,7 @@ MAN_EXTENSION = .3 MAN_SUBDIR = -# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, then it # will generate one additional man file for each entity documented in the real # man page(s). These additional files only source the real man page, but without # them the man command would be unable to find the correct page. @@ -2174,7 +2297,7 @@ MAN_LINKS = NO # Configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that +# If the GENERATE_XML tag is set to YES, Doxygen will generate an XML file that # captures the structure of the code including all documentation. # The default value is: NO. @@ -2188,7 +2311,7 @@ GENERATE_XML = NO XML_OUTPUT = xml -# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program +# If the XML_PROGRAMLISTING tag is set to YES, Doxygen will dump the program # listings (including syntax highlighting and cross-referencing information) to # the XML output. Note that enabling this will significantly increase the size # of the XML output. @@ -2197,7 +2320,7 @@ XML_OUTPUT = xml XML_PROGRAMLISTING = YES -# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, Doxygen will include # namespace members in file scope as well, matching the HTML output. # The default value is: NO. # This tag requires that the tag GENERATE_XML is set to YES. @@ -2208,7 +2331,7 @@ XML_NS_MEMB_FILE_SCOPE = NO # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- -# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files +# If the GENERATE_DOCBOOK tag is set to YES, Doxygen will generate Docbook files # that can be used to generate PDF. # The default value is: NO. @@ -2226,19 +2349,45 @@ DOCBOOK_OUTPUT = docbook # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# If the GENERATE_AUTOGEN_DEF tag is set to YES, Doxygen will generate an +# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures # the structure of the code including all documentation. Note that this feature # is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to Sqlite3 output +#--------------------------------------------------------------------------- + +# If the GENERATE_SQLITE3 tag is set to YES Doxygen will generate a Sqlite3 +# database with symbols found by Doxygen stored in tables. +# The default value is: NO. + +GENERATE_SQLITE3 = NO + +# The SQLITE3_OUTPUT tag is used to specify where the Sqlite3 database will be +# put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put +# in front of it. +# The default directory is: sqlite3. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_OUTPUT = sqlite3 + +# The SQLITE3_RECREATE_DB tag is set to YES, the existing doxygen_sqlite3.db +# database file will be recreated with each Doxygen run. If set to NO, Doxygen +# will warn if a database file is already found and not modify it. +# The default value is: YES. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_RECREATE_DB = YES + #--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module +# If the GENERATE_PERLMOD tag is set to YES, Doxygen will generate a Perl module # file that captures the structure of the code including all documentation. # # Note that this feature is still experimental and incomplete at the moment. @@ -2246,7 +2395,7 @@ GENERATE_AUTOGEN_DEF = NO GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary +# If the PERLMOD_LATEX tag is set to YES, Doxygen will generate the necessary # Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI # output from the Perl module output. # The default value is: NO. @@ -2276,13 +2425,13 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all +# If the ENABLE_PREPROCESSING tag is set to YES, Doxygen will evaluate all # C-preprocessor directives found in the sources and include files. # The default value is: YES. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# If the MACRO_EXPANSION tag is set to YES, Doxygen will expand all macro names # in the source code. If set to NO, only conditional compilation will be # performed. Macro expansion can be done in a controlled way by setting # EXPAND_ONLY_PREDEF to YES. @@ -2341,7 +2490,7 @@ PREDEFINED = EXPAND_AS_DEFINED = -# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# If the SKIP_FUNCTION_MACROS tag is set to YES then Doxygen's preprocessor will # remove all references to function-like macros that are alone on a line, have # an all uppercase name, and do not end with a semicolon. Such function macros # are typically used for boiler-plate code, and will confuse the parser if not @@ -2365,26 +2514,26 @@ SKIP_FUNCTION_MACROS = YES # section "Linking to external documentation" for more information about the use # of tag files. # Note: Each tag file must have a unique name (where the name does NOT include -# the path). If a tag file is not located in the directory in which doxygen is +# the path). If a tag file is not located in the directory in which Doxygen is # run, you must also specify the path to the tagfile here. TAGFILES = -# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# When a file name is specified after GENERATE_TAGFILE, Doxygen will create a # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = +GENERATE_TAGFILE = "@DOXYGEN_TAG_FILE@" -# If the ALLEXTERNALS tag is set to YES, all external class will be listed in -# the class index. If set to NO, only the inherited external classes will be -# listed. +# If the ALLEXTERNALS tag is set to YES, all external classes and namespaces +# will be listed in the class and namespace index. If set to NO, only the +# inherited external classes will be listed. # The default value is: NO. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will be +# in the topic index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. @@ -2398,33 +2547,26 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -# You can include diagrams made with dia in doxygen documentation. Doxygen will -# then run dia to produce the diagram and insert it in the documentation. The -# DIA_PATH tag allows you to specify the directory where the dia binary resides. -# If left empty dia is assumed to be found in the default search path. - -DIA_PATH = - # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. HIDE_UNDOC_RELATIONS = YES -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# If you set the HAVE_DOT tag to YES then Doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: -# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO # The default value is: NO. HAVE_DOT = NO -# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed -# to run in parallel. When set to 0 doxygen will base this on the number of +# The DOT_NUM_THREADS specifies the number of dot invocations Doxygen is allowed +# to run in parallel. When set to 0 Doxygen will base this on the number of # processors available in the system. You can set it explicitly to a value # larger than 0 to get control over the balance between CPU load and processing # speed. @@ -2435,7 +2577,7 @@ DOT_NUM_THREADS = 0 # DOT_COMMON_ATTR is common attributes for nodes, edges and labels of # subgraphs. When you want a differently looking font in the dot files that -# doxygen generates you can specify fontname, fontcolor and fontsize attributes. +# Doxygen generates you can specify fontname, fontcolor and fontsize attributes. # For details please see Node, # Edge and Graph Attributes specification You need to make sure dot is able # to find the font, which can be done by putting it in a standard location or by @@ -2469,35 +2611,47 @@ DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" DOT_FONTPATH = -# If the CLASS_GRAPH tag is set to YES (or GRAPH) then doxygen will generate a -# graph for each documented class showing the direct and indirect inheritance -# relations. In case HAVE_DOT is set as well dot will be used to draw the graph, -# otherwise the built-in generator will be used. If the CLASS_GRAPH tag is set -# to TEXT the direct and indirect inheritance relations will be shown as texts / -# links. -# Possible values are: NO, YES, TEXT and GRAPH. +# If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then Doxygen will +# generate a graph for each documented class showing the direct and indirect +# inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and +# HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case +# the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the +# CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used. +# If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance +# relations will be shown as texts / links. Explicit enabling an inheritance +# graph or choosing a different representation for an inheritance graph of a +# specific class, can be accomplished by means of the command \inheritancegraph. +# Disabling an inheritance graph can be accomplished by means of the command +# \hideinheritancegraph. +# Possible values are: NO, YES, TEXT, GRAPH and BUILTIN. # The default value is: YES. CLASS_GRAPH = YES -# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# If the COLLABORATION_GRAPH tag is set to YES then Doxygen will generate a # graph for each documented class showing the direct and indirect implementation # dependencies (inheritance, containment, and class references variables) of the -# class with other documented classes. +# class with other documented classes. Explicit enabling a collaboration graph, +# when COLLABORATION_GRAPH is set to NO, can be accomplished by means of the +# command \collaborationgraph. Disabling a collaboration graph can be +# accomplished by means of the command \hidecollaborationgraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES -# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for -# groups, showing the direct groups dependencies. See also the chapter Grouping -# in the manual. +# If the GROUP_GRAPHS tag is set to YES then Doxygen will generate a graph for +# groups, showing the direct groups dependencies. Explicit enabling a group +# dependency graph, when GROUP_GRAPHS is set to NO, can be accomplished by means +# of the command \groupgraph. Disabling a directory graph can be accomplished by +# means of the command \hidegroupgraph. See also the chapter Grouping in the +# manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. GROUP_GRAPHS = YES -# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and +# If the UML_LOOK tag is set to YES, Doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. # The default value is: NO. @@ -2518,10 +2672,10 @@ UML_LOOK = NO UML_LIMIT_NUM_FIELDS = 10 -# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# If the DOT_UML_DETAILS tag is set to NO, Doxygen will show attributes and # methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS -# tag is set to YES, doxygen will add type and arguments for attributes and -# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# tag is set to YES, Doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, Doxygen # will not generate fields with class member information in the UML graphs. The # class diagrams will look similar to the default class diagrams but using UML # notation for the relationships. @@ -2533,8 +2687,8 @@ DOT_UML_DETAILS = NO # The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters # to display on a single line. If the actual line length exceeds this threshold -# significantly it will wrapped across multiple lines. Some heuristics are apply -# to avoid ugly line breaks. +# significantly it will be wrapped across multiple lines. Some heuristics are +# applied to avoid ugly line breaks. # Minimum value: 0, maximum value: 1000, default value: 17. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2549,24 +2703,29 @@ DOT_WRAP_THRESHOLD = 17 TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to -# YES then doxygen will generate a graph for each documented file showing the +# YES then Doxygen will generate a graph for each documented file showing the # direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an include graph, when INCLUDE_GRAPH is is set to NO, +# can be accomplished by means of the command \includegraph. Disabling an +# include graph can be accomplished by means of the command \hideincludegraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are -# set to YES then doxygen will generate a graph for each documented file showing +# set to YES then Doxygen will generate a graph for each documented file showing # the direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an included by graph, when INCLUDED_BY_GRAPH is set +# to NO, can be accomplished by means of the command \includedbygraph. Disabling +# an included by graph can be accomplished by means of the command +# \hideincludedbygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. INCLUDED_BY_GRAPH = YES -# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# If the CALL_GRAPH tag is set to YES then Doxygen will generate a call # dependency graph for every global function or class method. # # Note that enabling this option will significantly increase the time of a run. @@ -2578,7 +2737,7 @@ INCLUDED_BY_GRAPH = YES CALL_GRAPH = NO -# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# If the CALLER_GRAPH tag is set to YES then Doxygen will generate a caller # dependency graph for every global function or class method. # # Note that enabling this option will significantly increase the time of a run. @@ -2590,17 +2749,20 @@ CALL_GRAPH = NO CALLER_GRAPH = NO -# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# If the GRAPHICAL_HIERARCHY tag is set to YES then Doxygen will graphical # hierarchy of all classes instead of a textual one. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. GRAPHICAL_HIERARCHY = YES -# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# If the DIRECTORY_GRAPH tag is set to YES then Doxygen will show the # dependencies a directory has on other directories in a graphical way. The # dependency relations are determined by the #include relations between the -# files in the directories. +# files in the directories. Explicit enabling a directory graph, when +# DIRECTORY_GRAPH is set to NO, can be accomplished by means of the command +# \directorygraph. Disabling a directory graph can be accomplished by means of +# the command \hidedirectorygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2616,25 +2778,30 @@ DIR_GRAPH_MAX_DEPTH = 1 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: -# http://www.graphviz.org/)). -# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order -# to make the SVG files visible in IE 9+ (other browsers do not have this -# requirement). +# https://www.graphviz.org/)). +# +# Note the formats svg:cairo and svg:cairo:cairo cannot be used in combination +# with INTERACTIVE_SVG (the INTERACTIVE_SVG will be set to NO). # Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, -# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and -# png:gdiplus:gdiplus. +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus, +# png:gdiplus:gdiplus, svg:cairo, svg:cairo:cairo, svg:svg, svg:svg:core, +# gif:cairo, gif:cairo:gd, gif:cairo:gdiplus, gif:gdiplus, gif:gdiplus:gdiplus, +# gif:gd, gif:gd:gd, jpg:cairo, jpg:cairo:gd, jpg:cairo:gdiplus, jpg:gd, +# jpg:gd:gd, jpg:gdiplus and jpg:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. DOT_IMAGE_FORMAT = png -# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to -# enable generation of interactive SVG images that allow zooming and panning. +# If DOT_IMAGE_FORMAT is set to svg or svg:svg or svg:svg:core, then this option +# can be set to YES to enable generation of interactive SVG images that allow +# zooming and panning. # # Note that this requires a modern browser other than Internet Explorer. Tested # and working are Firefox, Chrome, Safari, and Opera. -# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make -# the SVG files visible. Older versions of IE do not have SVG support. +# +# Note This option will be automatically disabled when DOT_IMAGE_FORMAT is set +# to svg:cairo or svg:cairo:cairo. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2653,11 +2820,12 @@ DOT_PATH = DOTFILE_DIRS = -# The MSCFILE_DIRS tag can be used to specify one or more directories that -# contain msc files that are included in the documentation (see the \mscfile -# command). +# You can include diagrams made with dia in Doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. -MSCFILE_DIRS = +DIA_PATH = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile @@ -2665,7 +2833,7 @@ MSCFILE_DIRS = DIAFILE_DIRS = -# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# When using PlantUML, the PLANTUML_JAR_PATH tag should be used to specify the # path where java can find the plantuml.jar file or to the filename of jar file # to be used. If left blank, it is assumed PlantUML is not used or called during # a preprocessing step. Doxygen will generate a warning when it encounters a @@ -2673,20 +2841,26 @@ DIAFILE_DIRS = PLANTUML_JAR_PATH = -# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a -# configuration file for plantuml. +# When using PlantUML, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for PlantUML. PLANTUML_CFG_FILE = -# When using plantuml, the specified paths are searched for files specified by -# the !include statement in a plantuml block. +# When using PlantUML, the specified paths are searched for files specified by +# the !include statement in a PlantUML block. PLANTUML_INCLUDE_PATH = +# The PLANTUMLFILE_DIRS tag can be used to specify one or more directories that +# contain PlantUml files that are included in the documentation (see the +# \plantumlfile command). + +PLANTUMLFILE_DIRS = + # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes -# larger than this value, doxygen will truncate the graph, which is visualized -# by representing a node as a red box. Note that doxygen if the number of direct +# larger than this value, Doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that if the number of direct # children of the root node in a graph is already larger than # DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that # the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. @@ -2716,17 +2890,17 @@ MAX_DOT_GRAPH_DEPTH = 0 DOT_MULTI_TARGETS = NO -# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# If the GENERATE_LEGEND tag is set to YES Doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. -# Note: This tag requires that UML_LOOK isn't set, i.e. the doxygen internal +# Note: This tag requires that UML_LOOK isn't set, i.e. the Doxygen internal # graphical representation for inheritance and collaboration diagrams is used. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate +# If the DOT_CLEANUP tag is set to YES, Doxygen will remove the intermediate # files that are used to generate the various graphs. # # Note: This setting is not only used for dot files but also for msc temporary @@ -2734,3 +2908,19 @@ GENERATE_LEGEND = YES # The default value is: YES. DOT_CLEANUP = YES + +# You can define message sequence charts within Doxygen comments using the \msc +# command. If the MSCGEN_TOOL tag is left empty (the default), then Doxygen will +# use a built-in version of mscgen tool to produce the charts. Alternatively, +# the MSCGEN_TOOL tag can also specify the name an external tool. For instance, +# specifying prog as the value, Doxygen will call the tool as prog -T +# -o . The external tool should support +# output file formats "png", "eps", "svg", and "ismap". + +MSCGEN_TOOL = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = diff --git a/docs/doxygen/mainpage.md b/docs/doxygen/mainpage.md new file mode 100644 index 000000000..033696514 --- /dev/null +++ b/docs/doxygen/mainpage.md @@ -0,0 +1,42 @@ +# OpenTurbine API documentation {#mainpage} + +This document is intended for developers who want to understand the C++ code +structure and modify the codebase and, therefore, assumes that the reader is +familiar with the installation, compilation, and execution steps. If you are new to +OpenTurbine and haven't installed/used OpenTurbine previously, we recommend starting +with the [user manual](https://exawind.github.io/openturbine/) that provides a detailed +overview of the installation process as well as general usage. + +## How to use this API guide? + +TODO + +### Source code organization + +Upon successful download/clone, the base repository (`openturbine`) has source code +organized in subdirectories described below: + +- `cmake` -- Functions and utilities used during CMake configuration phase +- `docs` -- User manual (Sphinx-based) and Doxygen files +- `src` -- C++ source files. All code is located within this directory and is + organized into sub-directories that represent the different parts of the codebase. +- `test` -- Divided into unit-tests and regression tests, contains test files for + the codebase + +When developing new features, we strongly recommend creating a unit-test and +develop features incrementally and testing as you add capabilities. Unit-tests +are also a good way to explore the usage of individual components of the code. + +## Contributing + +OpenTurbine is an open-source code and we welcome contributions from the community. +Please consult the [developer +documentation](https://exawind.github.io/openturbine/developer/index.html) section +of the user manual to learn about the process of submitting code enhancements, +bug-fixes, documentation updates, etc. + +## License + +OpenTurbine is licensed under MIT license. Please see the +[LICENSE](https://github.com/Exawind/openturbine/blob/main/LICENSE) included in +the source code repository for more details. diff --git a/docs/doxygen/mainpage.txt b/docs/doxygen/mainpage.txt deleted file mode 100644 index e21bf9cbd..000000000 --- a/docs/doxygen/mainpage.txt +++ /dev/null @@ -1,32 +0,0 @@ -/*! @mainpage - * - * @section intro_sec Introduction - * - * `OpenTurbine` is a new, open-source wind turbine structural dynamics simulation - * code designed to meet the research needs of Wind Energy Technologies Office (WETO) - * and the broader wind energy community for land-based and offshore wind turbines. - * `OpenTurbine` will provide high-fidelity, highly performant structural dynamics - * models that can couple with low-fidelity aerodynamic/hydrodynamic models like those - * in [OpenFAST](https://github.com/OpenFAST/openfast), as well as high-fidelity - * computational fluid dynamics (CFD) models like those in the WETO and Office - * of Science supported [ExaWind](https://github.com/Exawind) code suite. - * - * Following describes the salient features conceived for OpenTurbine: - * - `OpenTurbine` will follow modern software development best practices. The - * development process will require test-driven development (TDD), version control, - * hierarchical automated testing, and continuous integration leading to a - * robust development environment. - * - The core data structures will be memory efficient and will enable vectorization - * and parallelization at multiple levels. - * - They will be data-oriented to exploit methods for accelerated computing including - * high utilization of chip resources (e.g., single instruction multiple data i.e. SIMD), - * parallelization through GP-GPUs or other hardware, and support for memory-efficient - * architectures. - * - The computational algorithms will incorporate robust open-source libraries for - * mathematical operations, resource allocation, and data management. - * - The API design will consider multiple stakeholder needs and ensure - * integration with existing and future ecosystems for data science, machine learning, - * and AI. - * - `OpenTurbine` will be written in modern C++ and leverage [Kokkos](https://github.com/kokkos/kokkos) - * as its performance-portability library with inspiration from the ExaWind stack. - */ diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index a14aadfd3..000000000 --- a/docs/getting_started.md +++ /dev/null @@ -1,18 +0,0 @@ -# Getting Started - -This page describes the procedure for installing OpenTurbine -and performing basic tasks. For in-depth guides and explanations, -see {ref}`tutorials` and {ref}`reference`. - -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: - - -## Installation - -OpenTurbine is not currently distributed, so it is required to -compile the code in order to install it. See {ref}`compiling` -for details. In the future, OpenTurbine will be distributed -through typical package managers like Spack or Conda. diff --git a/docs/input_file.md b/docs/input_file.md deleted file mode 100644 index 4de7c05ce..000000000 --- a/docs/input_file.md +++ /dev/null @@ -1,10 +0,0 @@ -(input-file)= - -# Input File - -This page describes the input file. - -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index d557c69f0..000000000 --- a/docs/intro.md +++ /dev/null @@ -1,38 +0,0 @@ -# OpenTurbine: A flexible multibody structural dynamics code for wind turbines - -:::{note} -This page is under construction. Please check back here throughout FY23 -for updates, and see development activity at https://github.com/exawind/openturbine. -::: - -OpenTurbine is a new, open-source wind turbine structural dynamics simulation -code designed to meet the research needs of Wind Energy Technologies Office (WETO) -and the broader wind energy community for land-based and offshore wind turbines. -OpenTurbine will provide high-fidelity, highly performant structural dynamics -models that can couple with low-fidelity aerodynamic/hydrodynamic models like those -in [OpenFAST](https://github.com/OpenFAST/openfast), as well as high-fidelity -computational fluid dynamics (CFD) models like those in the WETO and Office -of Science supported [ExaWind](https://github.com/Exawind) code suite. - -Following describes the high-level development objectives conceived for OpenTurbine: -- OpenTurbine will follow modern software development best practices. The -development process will require test-driven development (TDD), version control, -hierarchical automated testing, and continuous integration leading to a -robust development environment. -- The core data structures will be memory efficient and will enable vectorization -and parallelization at multiple levels. -- They will be data-oriented to exploit methods for accelerated computing including -high utilization of chip resources (e.g., single instruction multiple data i.e. SIMD), -parallelization through GPGPUs or other hardware, and support for memory-efficient -architectures. -- The computational algorithms will incorporate robust open-source libraries for -mathematical operations, resource allocation, and data management. -- The API design will consider multiple stakeholder needs and ensure -integration with existing and future ecosystems for data science, machine learning, -and AI. -- OpenTurbine will be written in modern C++ and will leverage [Kokkos](https://github.com/kokkos/kokkos) -as its performance-portability library with inspiration from the ExaWind stack. - - -```{tableofcontents} -``` diff --git a/docs/reference.md b/docs/reference.md deleted file mode 100644 index 0226db8ed..000000000 --- a/docs/reference.md +++ /dev/null @@ -1,8 +0,0 @@ -(reference)= - -# Reference - -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: diff --git a/docs/requirements.txt b/docs/requirements.txt index 5db4a429e..cffd76b60 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,14 @@ -jupyter-book -matplotlib -numpy -sphinxcontrib.mermaid \ No newline at end of file +breathe>=4.4 +docutils==0.16 +Pygments>=2.2 +pyparsing>=2.1 +Sphinx>=1.8.5 +sphinxcontrib-bibtex>=2.0.0 +sphinxcontrib-mermaid>=0.6 +sphinx_rtd_theme>=0.3 +sphinx_toolbox +sphinx_copybutton +pyenchant +sphinxcontrib-spelling +doxysphinx +sphinxcontrib-doxylink \ No newline at end of file diff --git a/docs/sphinx/_static/oturb_logo_v1.jpeg b/docs/sphinx/_static/oturb_logo_v1.jpeg new file mode 100644 index 000000000..1b81f7930 Binary files /dev/null and b/docs/sphinx/_static/oturb_logo_v1.jpeg differ diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py new file mode 100644 index 000000000..69efb71b7 --- /dev/null +++ b/docs/sphinx/conf.py @@ -0,0 +1,109 @@ +import sys + +#-------------------------------------------------------------------------- +# General configuration +#-------------------------------------------------------------------------- +extensions = [ + 'sphinx.ext.mathjax', # MathJax for mathematical expressions + 'sphinx_copybutton', # Copy button for code blocks + 'sphinx_rtd_theme', # ReadTheDocs theme + 'sphinx_toolbox.collapse', # Collapse sections in the documentation + 'sphinxcontrib.bibtex', # BibTeX bibliography + 'sphinxcontrib.doxylink', # Doxygen links + 'sphinxcontrib.mermaid', # Mermaid diagrams + 'sphinxcontrib.spelling' # Spelling checker +] + +bibtex_bibfiles = [] + +#-------------------------------------------------------------------------- +# Project information +#-------------------------------------------------------------------------- +templates_path = ['_templates'] # path relative to conf.py +source_suffix = ['.rst'] # options ['.rst', '.md'] +main_doc = 'index' # top-level toctree document +project = 'OpenTurbine' +title = 'OpenTurbine Documentation' +copyright = '2023 - Present, MIT License' +author = 'National Renewable Energy Laboratory (NREL) and Sandia National Laboratories (SNL)' + +# Version info +version = '0.0' # The short X.Y version +release = '0.0.1' # The full version, including alpha/beta/rc tags + +#-------------------------------------------------------------------------- +# Spelling configuration +#-------------------------------------------------------------------------- +spelling_word_list_filename = "spelling_wordlist.txt" +spelling_exclude_patterns = ["doxygen/html/*"] +spelling_show_suggestions = False +spelling_warning = False +spelling_ignore_contributor_names = False + +#-------------------------------------------------------------------------- +# Build configuration +#-------------------------------------------------------------------------- +# Patterns to ignore when looking for source files +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# Pygments i.e. syntax highlighting style to use +pygments_style = 'sphinx' + +# Include todos in the output? +todo_include_todos = False + +# Figure, table, and code-block numbering +numfig = True +numfig_format = {'figure': '%s', 'table': '%s', 'code-block': '%s'} + +#-------------------------------------------------------------------------- +# HTML output configuration +#-------------------------------------------------------------------------- +html_theme = 'sphinx_rtd_theme' +html_logo = '_static/oturb_logo_v1.jpeg' +html_static_path = ['_static'] # Path to static files +html_show_copyright = True # Show copyright in the footer +htmlhelp_basename = 'openturbine_doc' # Output file base name for HTML help builder + +#-------------------------------------------------------------------------- +# LaTeX output configuration +#-------------------------------------------------------------------------- +# Group the document tree into LaTeX files +latex_documents = [( + main_doc, # source start file + 'openturbine.tex', # target name + title, # title + author, # author + 'manual' # documentclass [howto, manual, or own class] +)] + +#-------------------------------------------------------------------------- +# Manual page output configuration +#-------------------------------------------------------------------------- +# One entry per manual page +man_pages = [( + main_doc, # source start file + 'openturbine', # name + title, # description + [author], # authors + 1 # manual section +)] + +#-------------------------------------------------------------------------- +# Texinfo output configuration +#-------------------------------------------------------------------------- +# Grouping the document tree into Texinfo files +texinfo_documents = [( + main_doc, # source start file + 'openturbine', # name + title, # description + author, # author + project, # project + 'Flexible Multibody Dynamics of Wind Turbines', # description + 'Miscellaneous'), # category +] + +def setup(app): + app.add_object_type("input_param", "input_param", + objname="OpenTurbine input parameter", + indextemplate="pair: %s; OpenTurbine input parameter") diff --git a/docs/images/AoS_SoA.pdf b/docs/sphinx/developer/AoS_SoA.pdf similarity index 100% rename from docs/images/AoS_SoA.pdf rename to docs/sphinx/developer/AoS_SoA.pdf diff --git a/docs/dev_plan.md b/docs/sphinx/developer/dev_plan.rst similarity index 73% rename from docs/dev_plan.md rename to docs/sphinx/developer/dev_plan.rst index 68bddb469..43ae64e03 100644 --- a/docs/dev_plan.md +++ b/docs/sphinx/developer/dev_plan.rst @@ -1,13 +1,10 @@ -(dev-plan)= +.. _dev-plan: -# OpenTurbine Development Plan +OpenTurbine Development Plan +############################ -:::{warning} -This page is under construction. Please check back here throughout FY23 -for updates, and see development activity at https://github.com/exawind/openturbine. -::: - -## Background and overview +Background and overview +*********************** OpenTurbine development started in early 2023 with primary funding from the U.S. Department of Energy (DOE) Wind Energy Technologies Office (WETO) and with @@ -20,15 +17,16 @@ simulation code designed to meet the research needs of WETO and the broader wind energy community for land-based and offshore wind turbines. OpenTurbine will provide high-fidelity, highly performant structural dynamics models that can couple with low-fidelity aerodynamic/hydrodynamic models like those in -[OpenFAST](https://github.com/OpenFAST/openfast), and high-fidelity computational +`OpenFAST `_, and high-fidelity computational fluid dynamics (CFD) models like those in the WETO and Office of Science supported -[ExaWind](https://github.com/Exawind) code suite. OpenTurbine will be designed +`ExaWind `_ code suite. OpenTurbine will be designed deliberately to address shortcomings of wind turbine structural models and codes that are critical to the success of WETO modeling efforts. -## Development priorities and use cases +Development priorities and use cases +************************************ -*Development priorities:* Considering lessons learned from nearly a decade of +**Development priorities:** Considering lessons learned from nearly a decade of OpenFAST development, OpenTurbine will follow modern software development best practices. The development process will require test-driven development, version control, hierarchical automated testing, and continuous integration @@ -40,9 +38,11 @@ instruction multiple data [SIMD]), parallelization through GPU or other hardware, and support for memory-efficient architectures such as the ARM-based Apple M-series chips. -*Use-case priority:* Time-domain simulation of land-based wind turbine dynamics coupled to computational fluid dynamics for fluid-structure-interaction. +**Use-case priority:** Time-domain simulation of land-based wind turbine dynamics +coupled to computational fluid dynamics for fluid-structure-interaction. -## Design drivers and considerations +Design drivers and considerations +********************************* OpenTurbine is a relatively small, narrowly scoped software project. Organizationally, it is very lean with a minimal and focused development @@ -55,7 +55,8 @@ with a consideration for how new developers, current developers in the future, and external stakeholders will be able to understand the nuances of the code. In short, **don't be clever** and **keep it simple**. -### Lean software +Lean software +============= The scope of this software should be defined early in the development process, and any expansion of the scope should be critically evaluated before accepting. @@ -71,7 +72,8 @@ are other areas where the ecosystem of open source scientific software should be leveraged, and preference should be given to software internal to NREL or funded by WETO. -### Modular architecture +Modular architecture +==================== The code architecture should be structured such that each portion of code is responsible for a minimal unit of work. Low-level units can be combined @@ -88,44 +90,44 @@ changing a solver type without modifying the modules around it. The flow of data should be considered in discrete steps in a pipeline rather than a monolithic system working on the data. -```{mermaid} -flowchart LR +.. mermaid:: + + flowchart LR - Start(( )) + Start(( )) - subgraph I/O - direction LR - io1{{YAML}} - io2{{JSON}} - end + subgraph I/O + direction LR + io1{{YAML}} + io2{{JSON}} + end - DataModel[[Data Model]] + DataModel[[Data Model]] - subgraph Solver - direction LR - solver1{{Type 1}} - solver2{{Type 2}} - solver3{{Type 3}} - end + subgraph Solver + direction LR + solver1{{Type 1}} + solver2{{Type 2}} + solver3{{Type 3}} + end - Output[[Output Model]] + Output[[Output Model]] - subgraph Export - direction LR - export1{{Visualization}} - export2{{ASCII}} - export3{{Commercial}} - end + subgraph Export + direction LR + export1{{Visualization}} + export2{{ASCII}} + export3{{Commercial}} + end - Finish(( )) + Finish(( )) - Start --- I/O - I/O --- DataModel - DataModel --- Solver - Solver --- Output - Output --- Export - Export --- Finish -``` + Start --- I/O + I/O --- DataModel + DataModel --- Solver + Solver --- Output + Output --- Export + Export --- Finish It is critical to the sustainability and stability of OpenTurbine to maintain independence from external software even though there @@ -135,7 +137,8 @@ to support integration of third party libraries as well as the ability to change any library for another that accomplishes a similar task even if by alternative methods. -### Performance first +Performance first +================= A key design consideration of OpenTurbine is computational efficiency or performance. Both the quantity of work and the efficiency of data should @@ -154,12 +157,14 @@ algorithms. Additionally, it follows the modular architecture design described above in that it supports swapping accelerators or parallelization methods. - -#### Data-oriented design +Data-oriented design +-------------------- OpenTurbine developers designing new algorithms and data structures -should become familiar with the concepts of [data-oriented design](https://en.wikipedia.org/wiki/Data-oriented_design), -particularly [structures of arrays vs. arrays of structures](https://stackoverflow.com/questions/17924705/structure-of-arrays-vs-array-of-structures). +should become familiar with the concepts of +`data-oriented design `_, +particularly `structures of arrays vs. arrays of structures +`_. The key concept of this paradigm is to structure data so that it maps closely to the form it will be represented and used within the relevant algorithms and processing units. Specifically, developers should choose between @@ -169,14 +174,13 @@ readability, it is important to consider the computational efficiency. A balance must be found, and documentation for any design decision is an important tool to resolve this tension. The graphic below illustrates the difference between structures of arrays and arrays of structures for a data -type consisting of three components of a location and a magnitude such as +type consisting of three components of a location and a magnitude such as a point in 3D space (i.e., voxel or point in a fluid domain). -```{image} images/AoS_SoA.pdf -:alt: aos_soa -:width: 400px -:align: center -``` +.. image:: AoS_SoA.pdf + :alt: aos_soa + :width: 400px + :align: center For operations involving vector math or accessing the same attribute of many objects, the SoA pattern typically ensures that arrays are byte-aligned @@ -186,7 +190,8 @@ alignment. In operations that access all attributes of a particular object for a computation, the AoS pattern structures the memory in a contiguous form. -### Accessible software +Accessible software +=================== Access to the software is an important consideration for the longevity and relevance of OpenTurbine. In short, if the software is @@ -210,12 +215,16 @@ The high level user interface should be expressive and easily accessible through common computational tools. For example, it is typical to include a Python interface to compiled code for easier data generation and scripting. -## Programming language and models +Programming language and models +******************************* -OpenTurbine is envisioned with a core written in C++ and leveraging [Kokkos](https://github.com/kokkos/kokkos) as its performance-portability library with inspiration from the ExaWind -stack including [Nalu-Wind](https://github.com/Exawind/nalu-wind). +OpenTurbine is envisioned with a core written in C++ and leveraging +`Kokkos `_ as its performance-portability +library with inspiration from the ExaWind +stack including `Nalu-Wind `_. -## Application Programming Interface (API) +Application Programming Interface (API) +*************************************** The primary goal of the API is to provide data structures and interfaces necessary for coupling OpenTurbine to the ExaWind CFD codes for @@ -231,7 +240,8 @@ as a point-mass. For geometry-resolved floating-platform offshore simulations, the API will be expanded to handle mapping from the structure surface mesh (if solid/shell elements are used) to the CFD mesh. -## Key numerical algorithms +Key numerical algorithms +************************ The models necessary for mid- to high-fidelity simulation of wind turbine structural dynamics include linear and nonlinear finite-element models coupled @@ -240,11 +250,12 @@ nonlinear beam finite elements, wherein the blade roots are constrained to rotate with the hub. These models together constitute a set of differential-algebraic equations (DAEs) in the time domain. We will build on the experiences gained with OpenFAST, particularly its nonlinear beam-dynamics module, -[BeamDyn](https://github.com/OpenFAST/openfast/tree/main/modules/beamdyn). +`BeamDyn `_. For time integration of the index-3 DAEs, we will leverage the generalized-alpha algorithm now established in BeamDyn which allows for user-controlled numerical -damping. See [Arnold and Brüls (2007)](https://link.springer.com/article/10.1007/s11044-007-9084-0) for details. +damping. See `Arnold and Brüls (2007) `_ +for details. The primary model for the turbine blades and the tower, which are slender and flexible structures, will be nonlinear finite elements based on the geometrically exact beam @@ -256,51 +267,64 @@ finite elements (a special case of LSFEs). The choice of rotation representation is being determined. BeamDyn relies on the Wiener-Milenkovic vectorial rotation parameterization (three rotational degrees of freedom), which contains singularities. The team is currently investigating the -use of [quaternions](https://en.wikipedia.org/wiki/Quaternion), which are +use of `quaternions `_, which are singularity free but require four parameters to represent rotation, i.e., they do not form a minimum set. -## Verification and validation cases +Verification and validation cases +********************************* The list of verification and validation cases is a work in progress. By way of semantics, verification cases are those for which an analytical solution exists and -formal accuracy studies can be examined. Validation cases are those for which +formal accuracy studies can be examined. Validation cases are those for which we have solutions that are deemed to be better representations of reality. For example, validation results might be from experiments or from higher-fidelity numerical simulations such as shell or solid finite element models. **Verification cases** -- Rigid-body dynamics: three-dimensional pendulum -- Cantilever-beam nonlinear static roll up + +* Rigid-body dynamics: three-dimensional pendulum +* Cantilever-beam nonlinear static roll up **Validation cases** -- Princeton beam experiment -- Twisted and curved beams where the benchmarks are highly resolved solid-element Ansys models -- IEA 15-megawatt turbine where benchmark is a highly resolved shell-element Ansys model -## Target baseline turbines +* Princeton beam experiment +* Twisted and curved beams where the benchmarks are highly resolved solid-element Ansys models +* IEA 15-megawatt turbine where benchmark is a highly resolved shell-element Ansys model + +Target baseline turbines +************************ -- [NREL 5-megawatt reference turbine](https://www.nrel.gov/docs/fy09osti/38060.pdf) -- [IEA 15-megawatt reference turbine](https://github.com/IEAWindTask37/IEA-15-240-RWT) +* `NREL 5-megawatt reference turbine `_ +* `IEA 15-megawatt reference turbine `_ -## High-level development timeline +High-level development timeline +******************************* CY = calendar year, FY = fiscal year **CY23 Q2**: The OpenTurbine team will implement a rigid-body dynamics solver following the concepts described above, i.e., DAE-3 coupling, quaternion-based rotation representation, and a generalized-alpha time integrator. This proof-of-concept implementation will be made available -in the `main` branch of OpenTurbine repository and will inform the next steps in OpenTurbine +in the ``main`` branch of OpenTurbine repository and will inform the next steps in OpenTurbine development. **CY23 Q3**: Implement a general GEBT-based beam element that is appropriate for constrained multi-body simulations of a wind turbine. Enable variable order finite elements and user-defined material property definition (appropriate for modern turbine blades). Demonstrate performance for a dynamic cantilever beam -problem and compare against [BeamDyn](https://github.com/OpenFAST/openfast/tree/main/modules/beamdyn). - -**CY24 Q1**: Demonstrate a wind turbine rotor simulation under prescribed loading and include code verification results and automated testing results. Include control system (e.g., [ROSCO](https://github.com/NREL/ROSCO/tree/main/ROSCO)) and pitch control of blades. Compare simulation time against an equivalent model simulated with [OpenFAST](https://github.com/OpenFAST/openfast). - -**CY24 Q3**: Demonstrate a rotor simulation with fluid-structure interaction (FSI) and a pitch control system. Fluid will be represented in two ways. First, through a simple Blade Element Momentum Theory (BEMT) solver and second, where the blades are represented as actuator lines in the fluid domain (solved with the ExaWind CFD code). - -**CY25 Q1**: Release a robust, well-documented, well-tested version of OpenTurbine for land-based wind turbine simulations. Demonstrate whole turbine simulation (tower, nacelle, drivetrain) capabilities with FSI coupling to ExaWind. - +problem and compare against `BeamDyn `_. + +**CY24 Q1**: Demonstrate a wind turbine rotor simulation under prescribed loading and include code +verification results and automated testing results. Include control system +(e.g., `ROSCO `_) and pitch control of blades. +Compare simulation time against an equivalent model simulated with +`OpenFAST `_. + +**CY24 Q3**: Demonstrate a rotor simulation with fluid-structure interaction (FSI) and a pitch control +system. Fluid will be represented in two ways. First, through a simple Blade Element Momentum Theory +(BEMT) solver and second, where the blades are represented as actuator lines in the fluid domain +(solved with the ExaWind CFD code). + +**CY25 Q1**: Release a robust, well-documented, well-tested version of OpenTurbine for land-based +turbine simulations. Demonstrate whole turbine simulation (tower, nacelle, drivetrain) capabilities +with FSI coupling to ExaWind. diff --git a/docs/sphinx/developer/documentation.rst b/docs/sphinx/developer/documentation.rst new file mode 100644 index 000000000..ef6320465 --- /dev/null +++ b/docs/sphinx/developer/documentation.rst @@ -0,0 +1,111 @@ +.. _dev-documenting: + +Documentation +============= + +OpenTurbine comes with two different types of documentation: + +- The manual, i.e., the document you are reading now, that is + written using `Sphinx `_, and + +- Inline documentation within C++ source code that are written in a format that can be + processed automatically by `Doxygen `_ + +Manual +------ + +The OpenTurbine manual is written using a special format called +ReStructured Text (ReST) and is converted into HTML and PDF formats +using a python package Sphinx. Since the manuals are written in simple +text files, they can be version controlled alongside the source +code. Documentation is automatically generated with new updates to the +GitHub repository and deployed at `OpenTurbine documentation site +`_. + +Writing documentation +````````````````````` + +As mentioned previously, documentation is written using a special text format +called reStructuredText. Sphinx user manual provides a `reST Primer +`_ that +provides an overview of this format and how to write documentation using this format. + +Source code documentation +------------------------- + +Source code (C++ files) are commented using a special format that +allows Doxygen to extract the annotated comments and create source +code documentation as well as inheritance diagrams. The +documentation for the latest snapshot of +the codebase can be browsed in this manual. The `Doxygen manual +`_ provides an overview of +the syntax that must be used. Please follow the Doxygen style of +commenting code when commenting OpenTurbine sources. + +When commenting code, try to use self-documenting code, i.e., descriptive names +for variables and functions that eliminate the need to describe what is going on +in comments. In general, comments should address *why* something is being coded +in a particular way, rather than how the code does things. Try to write the code +in a clear manner so that it is obvious from reading the code instead of having +to rely on comments to follow the code structure. + +Building documentation +---------------------- + +Documentation Dependencies +``````````````````````````` + +To generate the OpenTurbine documentation locally, several dependencies are required: + +* ``doxygen`` - For generating source code documentation +* ``graphviz`` - For creating inheritance diagrams +* ``sphinx`` - For building the manual +* ``enchant`` - For spell checking +* ``doxysphinx`` - For integrating Doxygen with Sphinx + +Installation +``````````````````````````` + +System Dependencies +``````````````````````````` + +For Ubuntu/Debian Linux: + +.. code-block:: bash + + $ sudo apt-get install -y --no-install-recommends graphviz libenchant-2-dev + +For macOS using Homebrew: + +.. code-block:: bash + + $ brew install doxygen graphviz enchant + +Python Dependencies +``````````````````````````` + +Install required Python packages using pip: + +.. code-block:: bash + + $ pip install sphinx sphinx_rtd_theme sphinx_toolbox sphinx_copybutton pyenchant sphinxcontrib-spelling doxysphinx + +Building Documentation +``````````````````````````` + +To build the documentation: + +.. code-block:: bash + + $ cd build && cmake -DOPENTURBINE_ENABLE_DOCUMENTATION:BOOL=ON .. && cmake --build . -t docs + +.. note:: + + macOS users may need to set the enchant library path: + + .. code-block:: bash + + $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib + +The built documentation will be available in the ``docs/sphinx/html`` directory. For other output formats, +see the `Sphinx documentation `_. diff --git a/docs/sphinx/developer/index.rst b/docs/sphinx/developer/index.rst new file mode 100644 index 000000000..43a927191 --- /dev/null +++ b/docs/sphinx/developer/index.rst @@ -0,0 +1,16 @@ +.. _dev-docs: + +Developer Documentation +======================= + +This section is meant for potential developers who are interested in modifying +and extending the ``openturbine`` source code for their own use cases. + +.. toctree:: + :maxdepth: 3 + + overview + dev_plan + documentation + ../doxygen/html/index + tools diff --git a/docs/dev_guide.md b/docs/sphinx/developer/overview.rst similarity index 84% rename from docs/dev_guide.md rename to docs/sphinx/developer/overview.rst index dcc06e31d..a10f15714 100644 --- a/docs/dev_guide.md +++ b/docs/sphinx/developer/overview.rst @@ -1,6 +1,7 @@ -(dev-guide)= +.. _overview: -# Developer's Guide +Overview +======== Developers of OpenTurbine should understand the workflows described here. Adherence to these processes ensures high quality code with minimal maintenance. @@ -9,23 +10,18 @@ and people so that work is not duplicated or conflicting. The primary objective of these processes is communication and signaling to other developers and ourselves now and in the future. -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: +.. contents:: -```{contents} -``` +Version control +--------------- -## Version control - -OpenTurbine uses git with a basic version of git-flow. The `main` branch is +OpenTurbine uses git with a basic version of git-flow. The ``main`` branch is stable, contains release-ready code, and is updated least frequently. The -`develop` branch contains tested and well developed code. It is the staging +``develop`` branch contains tested and well developed code. It is the staging branch for the next release. New work happens on feature branches prefixed -with `feature/` or `f/`, and these are merged into `develop`. Bug fixes are -on branches prefixed with `bug/` or `b/`, and these can be merged into -`develop` or `main` depending on the severity of the bug. +with ``feature/`` or ``f/``, and these are merged into ``develop``. Bug fixes are +on branches prefixed with ``bug/`` or ``b/``, and these can be merged into +``develop`` or ``main`` depending on the severity of the bug. The commit history should serve as a record of changes and include good contextual information. When staging changes and writing a commit message, @@ -36,6 +32,7 @@ what you were thinking right now. Do your future self the favor of authoring a long lasting commit message with a well-scoped set of changes. Some tips: + - Each commit should encompass one well-scoped change. A smell test is whether you've used the word "and" in the commit message. For example, a commit message of "Add a new CLI flag for XYZ and improve speed via @@ -46,9 +43,10 @@ Some tips: commit in a series and understand why and how the changes were made in sequence. - Practice editing a branch's commit history with interactive - rebase: `git rebase -i`. + rebase: ``git rebase -i``. -## Pull requests +Pull requests +------------- The driving question for each pull request should be "How can I convince reviewers that this pull request should be merged?" @@ -67,7 +65,8 @@ is a question, it should be asked without hesitation. This builds a searchable body of information that can ultimately be compiled into more formal documentation or serve as an informal reference on GitHub itself. -## Developer workflow +Developer workflow +------------------ Prior to starting work on a new project, a Discussion should be created to describe the scope of work and design the implementation. The original @@ -86,7 +85,8 @@ as link issues to other issues to understand dependencies. Finally, when the work is complete, a pull request should be created and reviewers assigned. -## Adding unit tests +Adding unit tests +----------------- All pull requests should be maximally tested in the unit test suite. This includes new code as well as existing code that is modified. To add a new @@ -94,11 +94,11 @@ unit test, first decide if the tests will consist of a new group of tests or whether it logically fits into an existing group. GTest groups tests into "test suites" during test declaration: -```c++ -TEST(TestSuiteName, TestName) { - test body -} -``` +.. code-block:: cpp + + TEST(TestSuiteName, TestName) { + test body + } A test suite contains multiple tests and the unit test runner can filter by test suite or test name. New tests should be organized so that @@ -111,17 +111,18 @@ the test and any relevant background. A new test suite requires registering with CMake. First, create a new C++ file to contain the test suite. Then, add it to the list -of sources for `${oturb_unit_test_exe_name}` in -`tests/unit_tests/CMakeLists.txt`. +of sources for ``${oturb_unit_test_exe_name}`` in +``tests/unit_tests/CMakeLists.txt``. The test suite can be listed from the runner with the following command: -```bash -./openturbine_unit_tests --gtest_list_tests -``` +.. code-block:: bash -## Checklist for code contributions + ./openturbine_unit_tests --gtest_list_tests + +Checklist for code contributions +-------------------------------- Ensure that all of these steps are complete prior to submitting a pull request as ready for review. @@ -135,4 +136,3 @@ as ready for review. - Documentation for changes - Documentation for high level references that are impacted; for example, installation instructions, API reference, or user guides - diff --git a/docs/sphinx/developer/tools.rst b/docs/sphinx/developer/tools.rst new file mode 100644 index 000000000..29a60502c --- /dev/null +++ b/docs/sphinx/developer/tools.rst @@ -0,0 +1,30 @@ +Developer Tools +=============== + +This page describes tools used in the development of OpenTurbine. These should +generally be adopted by all developers so that expectations and systems are +aligned. + +clang-format +------------ + +`ClangFormat `_ is used for +linting to enforce a consistent code style. It can be installed with most package +managers. The syntax to run the linter is given below. + +.. code-block:: bash + + # Lint in place all .cpp files in the src directory + clang-format -i src/*.cpp + + # Show changes in stdout for all header files in the utilities directory + clang-format -i src/utilities/*.H + +ClangFormat is configured by the ``.clang-format``. If the tool is run from the +top directory, it will automatically detect and load the settings in the +configuration file. + +.. note:: + + The CI system runs this linter and any required changes will cause the system + to fail. diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst new file mode 100644 index 000000000..bdf60519f --- /dev/null +++ b/docs/sphinx/index.rst @@ -0,0 +1,49 @@ +=========== +OpenTurbine +=========== + +`OpenTurbine `_ is an open-source wind +turbine structural dynamics simulation code designed to meet the research needs of +the Wind Energy Technologies Office (WETO) and the broader wind energy community +for both land-based and offshore wind turbines. OpenTurbine offers high-fidelity, +high-performance structural dynamics models that can integrate with low-fidelity +aerodynamic/hydrodynamic models, such as those in +`OpenFAST `_, as well as high-fidelity +computational fluid dynamics (CFD) models, like those in the WETO and Office of +Science-supported `ExaWind `_ code suite. + +Following are the high-level development objectives of OpenTurbine: + +- OpenTurbine adheres to modern software development best practices. The + development process emphasizes test-driven development (TDD), version control, + hierarchical automated testing, and continuous integration, leading to a robust + development environment. +- OpenTurbine is being developed in modern C++ and leverages + `Kokkos `_ as its performance-portability + library, drawing inspiration from the ExaWind stack. +- The core data structures are crafted to be memory efficient, enabling + vectorization and parallelization at multiple levels. +- These structures are data-oriented to leverage accelerated computing methods, + including high utilization of chip resources (e.g., single instruction multiple + data, SIMD), parallelization through GPGPUs or other hardware, and support for + memory-efficient architectures. +- The computational algorithms incorporate robust open-source libraries for + mathematical operations, resource allocation, and data management. +- The API design considers the needs of multiple stakeholders, ensuring + integration with existing and future ecosystems for data science, machine + learning, and AI. + +.. toctree:: + :maxdepth: 2 + + walkthrough/index + user/user + theory/index + developer/index + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/sphinx/spelling_wordlist.txt b/docs/sphinx/spelling_wordlist.txt new file mode 100644 index 000000000..67e040993 --- /dev/null +++ b/docs/sphinx/spelling_wordlist.txt @@ -0,0 +1,98 @@ +AeroDyn +API +APIs +CFD +CMake +CTest +Exascale +Fortran +GPU +GPUs +Jupyter +Kokkos +Kokkos-Kernels +Kokkos-kernels +MPI +Nalu +Navier +Neumann +OpenFAST +OpenTurbine +Raphson +SIMD +amr +amrex +anisotropic +bool +cartesian +centerline +cmake +codebase +conda +cpp +cuda +dat +datafile +dimensionalize +discretization +discretized +discretizes +doxygen +dropdown +dt +exawind +executables +fidelities +frontend +homebrew +hydrostatic +hypre +initializer +initializers +inline +iteratively +mesoscale +microscale +multibody +multigrid +multiphase +namespace +namespaces +netcdf +normals +ok +openfast +openturbine +paraview +performant +piecewise +plotfile +plotfiles +plt +postprocessing +pre +priori +proj +reStructuredText +repo +roadmap +rosco +runtime +solvability +spack +spacings +spanwise +src +struct +structs +submodule +submodules +teardown +timestep +timestepping +timesteps +vectorization +vectorized +walkthrough +yaml +yaml-cpp diff --git a/docs/sphinx/theory/flexible_beam.rst b/docs/sphinx/theory/flexible_beam.rst new file mode 100644 index 000000000..734bf739c --- /dev/null +++ b/docs/sphinx/theory/flexible_beam.rst @@ -0,0 +1,599 @@ +SO(3)-based GEBT Beam +===================== + +This document's purpose is to document the equations needed for a spectral-finite element implementation of Geometrically Exact Beam Theory (GEBT), where rotations are modeled in SO(3), rather than as Wiener-Milenkovicz parameters like in BeamDyn. The derivation is based on that described in Bauchau (2011). + +Useful Equations +---------------- + +.. math:: + + \underline{\psi} = \log \left(\underline{\underline{R}}\right) + + \underline{\delta \psi} = \mathrm{axial}\left(\delta \underline{\underline{R}}\,\underline{\underline{R}}^T\right) + + \underline{\omega} = \mathrm{axial}\left(\dot{\underline{\underline{R}}}\,\underline{\underline{R}}^T\right) + + \underline{\kappa} = \mathrm{axial}\left(\underline{\underline{R}}'\,\underline{\underline{R}}^T\right) + +which are the Cartesian rotation vector, the virtual rotation vector, the angular velocity (:math:`\in \mathbb{R}^3`), and the curvature (:math:`\in \mathbb{R}^3`), respectively, for rotation tensor :math:`\underline{\underline{R}} \in SO(3)`, and where a overdot denotes a time derivative and a prime denotes spatial derivative along the beam's reference line. + +Also useful: For any :math:`\underline{a} \in \mathbb{R}^3` and :math:`\underline{\underline{A}} \in \mathbb{R}^{3\times 3}`, + +.. math:: + + \tilde{a} = + \begin{bmatrix} + 0 & -a_3 & a_2 \\ + a_3 & 0 & -a_1 \\ + -a_2 & a_1 & 0 + \end{bmatrix} + +.. math:: + + \mathrm{axial}\left(\underline{\underline{A}}\right) = + \frac{1}{2} + \begin{bmatrix} + a_{32}-a_{23} \\ + a_{13}-a_{31} \\ + a_{21}-a_{12} + \end{bmatrix} + +If :math:`\underline{\underline{R}}` is represented by an Euler parameter, i.e., unit quaternion, :math:`\hat{q}^T= (q_0,q_1,q_2,q_3)`, + +.. math:: + + \underline{\omega} = 2 F(\hat{q}) \dot{\hat{q}} + + \underline{\kappa} = 2 F(\hat{q}) \hat{q}' + +where + +.. math:: + + F = + \begin{bmatrix} + -q_1 & +q_0 & -q_3 & +q_2 \\ + -q_2 & +q_3 & +q_0 & -q_1 \\ + -q_3 & -q_2 & +q_1 & +q_0 \\ + \end{bmatrix} + +For any :math:`\underline{a},\underline{b} \in \mathbb{R}^3`, + +.. math:: + + \widetilde{a}\underline{b} = -\widetilde{b}\underline{a} + + \widetilde{a}^T = -\widetilde{a} + + \widetilde{ \widetilde{a} \underline{b} } - \widetilde{a} \widetilde{b} = - \widetilde{b} \widetilde{a} + +Define: + +.. math:: + + \underline{\underline{\mathcal{RR}^0}} = + \begin{bmatrix} + \underline{\underline{R}}~\underline{\underline{R}}^0 & \underline{\underline{0}} \\ + \underline{\underline{0}} & \underline{\underline{R}}~\underline{\underline{R}}^0 + \end{bmatrix} + +for :math:`\underline{\underline{\mathcal{RR}^0}} \in \mathbb{R}^{6\times6}` + +Sectional stiffness and mass matrices (see B, p. 688): + +.. math:: + + \underline{\underline{\mathcal{C}}} = \underline{\underline{\mathcal{RR}^0}}\, \underline{\underline{\mathcal{C}}}^*\, \underline{\underline{\mathcal{RR}^0}}^T + + \underline{\underline{\mathcal{M}}} = \underline{\underline{\mathcal{RR}^0}}\, \underline{\underline{\mathcal{M}}}^*\, \underline{\underline{\mathcal{RR}^0}}^T + +for user-provided property-matrices :math:`\underline{\underline{\mathcal{C}}}^*, \underline{\underline{\mathcal{M}}}^* \in \mathbb{R}^{6\times6}`. + +Reference beam line in :math:`0 \le \zeta \le L`: + +.. math:: + + \underline{\mathcal{Q}}^0 = + \begin{Bmatrix} + \underline{x}^0(\zeta) \\ + \underline{\underline{R}}^0(\zeta) + \end{Bmatrix} + +where :math:`\underline{\mathcal{Q}}^0 \in G = \mathbb{R}^3 \times SO(3)` + +Generalized displacements (intertal basis) of beam line in :math:`0 \le \zeta \le L`: + +.. math:: + + \underline{\mathcal{Q}} = + \begin{Bmatrix} + \underline{u}(\zeta) \\ + \underline{\underline{R}}(\zeta) + \end{Bmatrix} + +where :math:`\underline{\mathcal{Q}} \in G = \mathbb{R}^3 \times SO(3)` + +Generalized velocities (intertal basis) of beam line in :math:`0 \le \zeta \le L`: + +.. math:: + + \underline{\mathcal{V}} = + \begin{Bmatrix} + \dot{\underline{u}}(\zeta) \\ + \underline{\omega}(\zeta) + \end{Bmatrix} + +Generalized velocities (material basis) of beam line in :math:`0 \le \zeta \le L`: + +.. math:: + + \underline{\mathcal{V}}^* = \underline{\underline{\mathcal{RR}^0}}^T \mathcal{V} + +Sectional strain measure for a beam in the inertial basis (B 16.45): + +.. math:: + + \underline{e}= + \begin{Bmatrix} + \underline{\epsilon} \\ \underline{\kappa} + \end{Bmatrix} + = \begin{Bmatrix} + \underline{x}{^0}'+\underline{u}'-\left(\underline{\underline{R}}~\underline{\underline{R}}^0 \right) \overline{i}_1 \\ + \mathrm{axial}\left(\underline{\underline{R}}'\underline{\underline{R}}^T\right) + \end{Bmatrix} + +Sectional strain measure for a beam in the material basis: + +.. math:: + + \underline{e}^*= + \begin{Bmatrix} + \underline{\epsilon}^* \\ \underline{\kappa}^* + \end{Bmatrix} + = \begin{Bmatrix} + \left( \underline{\underline{R}}~\underline{\underline{R}}^0 \right)^T \left(\underline{x}^{0\prime}+\underline{u}'\right)-\overline{i}_1 \\ + \left( \underline{\underline{R}}~\underline{\underline{R}}^0 \right)^T \mathrm{axial}\left(\underline{\underline{R}}'\underline{\underline{R}}^T\right) + \end{Bmatrix} + +Sectional elastic forces and moments in material/inertial systems (B 16.47): + +.. math:: + + \begin{Bmatrix} + \underline{N}^* \\ \underline{M}^* + \end{Bmatrix} + =\underline{\underline{\mathcal{C}}}^* \underline{e}^* \qquad + \begin{Bmatrix} + \underline{N} \\ \underline{M} + \end{Bmatrix} + =\underline{\underline{\mathcal{C}}}\, \underline{e} + +for :math:`\underline{\underline{\mathcal{C}}}^*, \underline{\underline{\mathcal{C}}} \in \mathbb{R}^{6\times6}`, where :math:`\underline{\underline{\mathcal{C}}} = \underline{\underline{\mathcal{RR}^0}}\, \underline{\underline{\mathcal{C}}}^*\, \underline{\underline{\mathcal{RR}^0}}^T`. + +Through principle of virtual work, one can show (B 16.50): + +.. math:: + + \underline{N}' = -\underline{f} + + \underline{M}'+ \left(\tilde{x}^{0\prime}+\tilde{u}'\right) \underline{N} = -\underline{m} + +Sectional linear and angular momenta in material/inertial system (B 16.60): + +.. math:: + + \underline{\mathcal{P}}^* = + \begin{Bmatrix} + \underline{h}^* \\ \underline{g}^* + \end{Bmatrix} + =\underline{\underline{\mathcal{M}}}^* \underline{\mathcal{V}}^* + + \underline{\mathcal{P}} = + \begin{Bmatrix} + \underline{h} \\ \underline{g} + \end{Bmatrix} + =\underline{\underline{\mathcal{M}}}\, \underline{\mathcal{V}} + +for :math:`\underline{\underline{\mathcal{M}}} \in \mathbb{R}^{6\times6}`, + +Through Hamilton's principle, one can show (B 16.63): + +.. math:: + + \dot{\underline{h}} - \underline{N}' = \underline{f} + + \dot{g} + \dot{\tilde{u}} \underline{h} - \underline{M}'- \left(\tilde{x}'^0+\tilde{u}'\right) \underline{N} = \underline{m} + +Finite Element Formulation +-------------------------- + +The inertial forces are (B 17.106): + +.. math:: + + \underline{\mathcal{F}}^I = \dot{\underline{\mathcal{P}}} + + \begin{bmatrix} \underline{\underline{0}} & \underline{\underline{0}} \\ \underline{\underline{0}} & \dot{\tilde{u}} \end{bmatrix} + \underline{\mathcal{P}} + + \underline{\mathcal{F}}^I \in \mathbb{R}^6 + +which can be written (B 17.110) (note the term :math:`m \dot{\tilde{u}}\dot{\underline{u}}`, which arises in chain rule, is identically zero): + +.. math:: + + \underline{\mathcal{F}}^I = \begin{bmatrix} + m \ddot{\underline{u}} + + \left( \dot{\tilde{\omega}}+ \tilde{\omega} \tilde{\omega} \right) m \underline{\eta}\\ + m \tilde{\eta} \ddot{\underline{u}} + \underline{\underline{\rho}} \dot{\underline{\omega}} + + \tilde{\omega} \underline{\underline{\rho}} \underline{\omega} + \end{bmatrix} + +where :math:`m`, :math:`\underline{\eta}`, and :math:`\underline{\underline{\rho}}` are readily extracted from the section mass matrix in inertial coordinates: + +.. math:: + + \underline{\underline{\mathcal{M}}} = \underline{\underline{\mathcal{RR}^0}}\, \underline{\underline{\mathcal{M}}}^*\, \underline{\underline{\mathcal{RR}^0}}^T = + \begin{bmatrix} + m \underline{\underline{I}}_3 & m \tilde{\eta}^T\\ + m \tilde{\eta} & \underline{\underline{\rho}} + \end{bmatrix} + +The elastic forces are (B 17.118): + +.. math:: + + \underline{\mathcal{F}}^C = + \begin{Bmatrix} \underline{\mathcal{F}}^C_1 \\ \underline{\mathcal{F}}^C_2 \end{Bmatrix}= + \begin{Bmatrix} \underline{N} \\ \underline{M} \end{Bmatrix} = \underline{\underline{\mathcal{C}}}\, \underline{e} + + \underline{\mathcal{F}}^D = + \begin{Bmatrix} \underline{0} \\ \left(\tilde{x}'^0+\tilde{u}'\right)^T\underline{\mathcal{F}}^C_1 \end{Bmatrix} = + \begin{Bmatrix} \underline{0} \\ \left(\tilde{x}'^0+\tilde{u}'\right)^T\underline{N} \end{Bmatrix} + + \underline{\mathcal{F}}^C, \underline{\mathcal{F}}^D \in \mathbb{R}^6 + +.. math:: + + \underline{\underline{\mathcal{C}}} = \begin{bmatrix} + \underline{\underline{\mathcal{C}}}_{11} & \underline{\underline{\mathcal{C}}}_{12} \\ + \underline{\underline{\mathcal{C}}}_{21} & \underline{\underline{\mathcal{C}}}_{22} \end{bmatrix} + +.. math:: + + \underline{e} = \begin{Bmatrix} \underline{e}_1 \\ \underline{e}_2 \end{Bmatrix} + + \underline{e}_1 = \underline{x}^{0\prime}+\underline{u}'-\left(\underline{\underline{R}}\,\underline{\underline{R}}^0\right) \overline{i}_1 + + \underline{e}_2 = \underline{\kappa} = \mathrm{axial}\left( \underline{\underline{R}}' \underline{\underline{R}}^T \right) + = 2 F(\hat{q}) \hat{q}^\prime + +In the above for :math:`\underline{e}_1` there is a potential problem at non-node quadrature points. The tangent, :math:`\underline{x}^{0 \prime}`, is unlikely to match :math:`\underline{\underline{R}}^0 \overline{i}_1`; that mismatch would cause incorrect strain. We will use the following equivalent definition for :math:`\underline{e}_1`: + +.. math:: + + \underline{e}_1 = \underline{x}^{0 \prime} +\underline{u}'-\underline{\underline{R}}\, \underline{x}^{0 \prime} + +which will guarantee no strain in reference configuration (i.e., :math:`\underline{e}_1 = 0` when :math:`\underline{u}^\prime=0` and :math:`\underline{\underline{R}}=\underline{\underline{I}}`). + +Linearization +------------- + +Inertial terms (see B 17.111) + +.. math:: + + \Delta \underline{\mathcal{F}}^I = + \underline{\underline{\mathcal{M}}} \Delta \ddot{\underline{q}} + + \underline{\underline{\mathcal{G}}} \Delta \dot{\underline{q}} + + \underline{\underline{\mathcal{K}}} \Delta \underline{q} + +where + +.. math:: + + \underline{\underline{\mathcal{G}}} = + \begin{bmatrix} + \underline{\underline{0}} & \widetilde{ \widetilde{\omega} m \underline{\eta} }^T + + \widetilde{\omega} m \widetilde{\eta}^T\\ + \underline{\underline{0}} & \widetilde{\omega} \underline{\underline{\rho}} - \widetilde{\underline{\underline{\rho}} \underline{\omega}} + \end{bmatrix} + +.. math:: + + \underline{\underline{\mathcal{K}}} = + \begin{bmatrix} + \underline{\underline{0}} & \left( \dot{\widetilde{\omega}} + \tilde{\omega}\tilde{\omega} + \right) m \widetilde{\eta}^T\\ + \underline{\underline{0}} & \ddot{\widetilde{u}} m \widetilde{\eta} + + \left(\underline{\underline{\rho}}\dot{\widetilde{\omega}} + -\widetilde{\underline{\underline{\rho}} \dot{\underline{\omega}}} \right) + + \widetilde{\omega} \left( \underline{\underline{\rho}} \widetilde{\omega} + - \widetilde{ \underline{\underline{\rho}}\underline{\omega}} \right) + \end{bmatrix} + +.. math:: + + \Delta \underline{\mathcal{F}}^C = + \underline{\underline{\mathcal{C}}} \Delta \underline{q}' + \underline{\underline{\mathcal{O}}} \Delta \underline{q} + +.. math:: + + \underline{\underline{\mathcal{O}}} = + \begin{bmatrix} + \underline{\underline{0}} & -\widetilde{N} + \underline{\underline{\mathcal{C}}}_{11}\left( \tilde{x}^{0 \prime}+ \tilde{u}' \right) \\ + \underline{\underline{0}} & -\widetilde{M} + \underline{\underline{\mathcal{C}}}_{21}\left( \tilde{x}^{0 \prime} + \tilde{u}' \right) + \end{bmatrix} + +.. math:: + + \Delta \underline{q} = \begin{Bmatrix} \Delta \underline{u} \\ \underline{\Delta \psi} \end{Bmatrix} + + \Delta \underline{q}' = \begin{Bmatrix} \Delta \underline{u}' \\ \underline{\Delta \psi}' \end{Bmatrix} + +.. math:: + + \Delta \underline{\mathcal{F}}^D = + \underline{\underline{\mathcal{P}}} \Delta \underline{q}' + \underline{\underline{\mathcal{Q}}} \Delta \underline{q} + +.. math:: + + \underline{\underline{\mathcal{P}}} = + \begin{bmatrix} + \underline{\underline{0}} & \underline{\underline{0}} \\ + \widetilde{N} + \left( \tilde{x}^{0 \prime}+ \tilde{u}' \right)^T + \underline{\underline{\mathcal{C}}}_{11} & + \left( \tilde{x}^{0 \prime} + \tilde{u}' \right)^T + \underline{\underline{\mathcal{C}}}_{12} + \end{bmatrix} + +.. math:: + + \underline{\underline{\mathcal{Q}}} = + \begin{bmatrix} + \underline{\underline{0}} & \underline{\underline{0}} \\ + \underline{\underline{0}} & + \left( \tilde{x}^{0 \prime} + \tilde{u}' \right)^T + \left[-\widetilde{N} + \underline{C}_{11} \left( \tilde{x}^{0 \prime} + \tilde{u}' \right) \right] + \end{bmatrix} + +Finite-element representation: + +.. math:: + + \underline{q}(s) = \sum_{j=0}^{N} \phi_j(s) \widehat{\underline{q}}_j, \qquad \underline{q}, \widehat{\underline{q}}_j \in \mathbb{R}^7 + +Strong Form: + +.. math:: + + {\underline{\mathcal{F}}^{I}} + -{\underline{\mathcal{F}}^{C}}'+\underline{\mathcal{F}}^D-\underline{\mathcal{F}}^G + -\underline{\mathcal{F}}^{\mathrm{ext}} = \underline{0} + +Weak Form (Residual): + +.. math:: + + \int_{-1}^{1} \phi_i \left( + {\underline{\mathcal{F}}^{I}} + -{\underline{\mathcal{F}}^{C}}' + +\underline{\mathcal{F}}^D-\underline{\mathcal{F}}^G + -\underline{\mathcal{F}}^{\mathrm{ext}}\right) J(s) dx = \underline{0} + +.. math:: + + \int_{-1}^{1} \left( + J(s) \phi_i \underline{\mathcal{F}}^I + + \phi'_i{\underline{\mathcal{F}}^{C}}+ J(s) \phi_i \underline{\mathcal{F}}^D\right)ds + -\int_{-1}^{1} \phi_i\left(\underline{\mathcal{F}}^G + +\underline{\mathcal{F}}^{\mathrm{ext}}\right) J(s) dx = \underline{0}, \quad \forall i\in\{0,1,\ldots,N\} + +Elastic nodal force vector: + +.. math:: + + \underline{F}_i^E = + \sum_{\ell=0}^{n^Q} + \left[ \phi'_i(s_\ell) + {\underline{\mathcal{F}}^{C}}(s_\ell)+ J(s_\ell) \phi_i(s_\ell) \underline{\mathcal{F}}^D(s_\ell) \right] w_\ell\, \quad + \forall i\in\{0,1,\ldots,N\}\,, \\ + \underline{F}_i^E \in \mathbb{R}^6 + +Inertial nodal force vector: + +.. math:: + + \underline{F}_i^{I} = + \sum_{\ell=0}^{n^Q} + J(s_\ell) \phi_i(s_\ell) \underline{\mathcal{F}}^I(s_\ell) w_\ell\, \quad + \forall i\in\{0,1,\ldots,N\}\,, \\ + \underline{F}_i^I \in \mathbb{R}^6 + +External nodal force vector: + +.. math:: + + \underline{F}_i^{ext} = + \sum_{\ell=0}^{n^Q} \phi_i (s_\ell) + \underline{F}^{ext}(s_\ell) J(s_\ell) w_\ell \,, + \quad \forall i\in\{0,1,\ldots,N\}\,,\\ + \underline{F}_i^{ext} \in \mathbb{R}^6 + +Gravity nodal force vector: + +.. math:: + + \underline{F}_i^g = + \sum_{\ell=0}^{n^Q} \phi_i (s_\ell) \underline{\mathcal{F}}^G(s_\ell) + J(s_\ell) w_\ell, \, + \quad \forall i\in\{0,1,\ldots,N\}\,,\\ + \underline{F}_i^g \in \mathbb{R}^6 + +Spectral finite-element portion of the residual vector: + +.. math:: + + \underline{R}^{FE} = + \begin{bmatrix} + \underline{{F}}_{0}^I + \underline{{F}}_{0}^{E} - + \underline{{F}}_{0}^{ext} - \underline{{F}}_{0}^{g}\\ + \underline{{F}}_{1}^I + \underline{{F}}_{1}^{E} - + \underline{{F}}_{1}^{ext} - \underline{{F}}_{1}^{g}\\ + \vdots \\ + \underline{{F}}_{N}^I + \underline{{F}}_{N}^{E} - + \underline{{F}}_{N}^{ext} - \underline{{F}}_{N}^{g}\\ + \end{bmatrix}\,, \quad + \underline{R}^{FE} \in \mathbb{R}^{6(N+1)} + +Linearized form for finite-element (FE) portion of iteration matrix (inertial contributions): + +.. math:: + + \underline{\underline{M}}_{ij} = + \sum_{\ell=0}^{n^Q} & + \phi_i(s_\ell) \underline{\underline{\mathcal{M}}}(s_\ell) \phi_j(s_\ell) J(s_\ell) w_\ell \\ + &\forall i,j\in\{0,1,\ldots,N\} + , \quad \underline{\underline{M}}_{ij} \in \mathbb{R}^{6\times 6} + +.. math:: + + \underline{\underline{G}}_{ij} = + \sum_{\ell=0}^{n^Q} & + \phi_i(s_\ell) \underline{\underline{\mathcal{G}}}(s_\ell) \phi_j(s_\ell) J(s_\ell) w_\ell \\ + &\forall i,j\in\{0,1,\ldots,N\} + , \quad \underline{\underline{G}}_{ij} \in \mathbb{R}^{6\times 6} + +.. math:: + + \underline{\underline{K}}_{ij}^I = + \sum_{\ell=0}^{n^Q} & + \phi_i(s_\ell) \underline{\underline{\mathcal{K}}}(s_\ell) \phi_j(s_\ell) J(s_\ell) w_\ell \\ + &\forall i,j\in\{0,1,\ldots,N\} + , \quad \underline{\underline{K}}_{ij}^I \in \mathbb{R}^{6\times 6} + +Linearized form for finite-element (FE) portion of iteration matrix (elastic contribution): + +.. math:: + + \underline{\underline{K}}_{ij}^E = + \sum_{\ell=0}^{n^Q} \big[& + \phi_i(s_\ell) \underline{\underline{\mathcal{P}}}(s_\ell) \phi'_j(s_\ell) + + \phi_i(s_\ell) \underline{\underline{\mathcal{Q}}}(s_\ell) \phi_j(s_\ell) J(s_\ell)+ \\ + & + \phi'_i(s_\ell) \underline{\underline{\mathcal{C}}}(s_\ell) \phi'_j(s_\ell) \frac{1}{J(s_\ell)}+ + \phi'_i(s_\ell) \underline{\underline{\mathcal{O}}}(s_\ell) \phi_j(s_\ell) + \big] w_\ell \\ + &\forall i,j\in\{0,1,\ldots,N\} + , \quad \underline{\underline{K}}_{ij}^E \in \mathbb{R}^{6\times 6} + +Spectral finite-element portion of the iteration matrix: + +.. math:: + + \underline{\underline{K}}^{FE} = + \begin{bmatrix} + \underline{\underline{K}}_{00}^I + \underline{\underline{K}}_{00}^E& + \underline{\underline{K}}_{01}^I + \underline{\underline{K}}_{01}^E& \ldots & + \underline{\underline{K}}_{0N}^I + \underline{\underline{K}}_{0N}^E\\ + \underline{\underline{K}}_{10}^I + \underline{\underline{K}}_{10}^E & + \underline{\underline{K}}_{11}^I + \underline{\underline{K}}_{11}^E& + \ldots & + \underline{\underline{K}}_{1N}^I + \underline{\underline{K}}_{1N}^E\\ + \vdots & \vdots & \vdots & \vdots \\ + \underline{\underline{K}}_{N0}^I + \underline{\underline{K}}_{N0}^E& + \underline{\underline{K}}_{N1}^I + \underline{\underline{K}}_{N1}^E& \ldots & + \underline{\underline{K}}_{NN}^I + \underline{\underline{K}}_{NN}^E\\ + \end{bmatrix}, \, + \underline{\underline{K}}^{FE} \in \mathbb{R}^{6 (N+1) \times 6 (N+1)} + +.. math:: + + \underline{\underline{M}}^{FE} = + \begin{bmatrix} + \underline{\underline{M}}_{00}& + \underline{\underline{M}}_{01}& \ldots & + \underline{\underline{M}}_{0N}\\ + \underline{\underline{M}}_{10} & + \underline{\underline{M}}_{11}& + \ldots & + \underline{\underline{M}}_{1N}\\ + \vdots & \vdots & \vdots & \vdots \\ + \underline{\underline{M}}_{N0}& + \underline{\underline{M}}_{N1}& \ldots & + \underline{\underline{M}}_{NN}\\ + \end{bmatrix},\, + \underline{\underline{M}}^{FE} \in \mathbb{R}^{6 (N+1) \times 6 (N+1)} + +.. math:: + + \underline{\underline{G}}^{FE} = + \begin{bmatrix} + \underline{\underline{G}}_{00}& + \underline{\underline{G}}_{01}& \ldots & + \underline{\underline{G}}_{0N}\\ + \underline{\underline{G}}_{10} & + \underline{\underline{G}}_{11}& + \ldots & + \underline{\underline{G}}_{1N}\\ + \vdots & \vdots & \vdots & \vdots \\ + \underline{\underline{G}}_{N0}& + \underline{\underline{G}}_{N1}& \ldots & + \underline{\underline{G}}_{NN}\\ + \end{bmatrix},\, + \underline{\underline{G}}^{FE} \in \mathbb{R}^{6 (N+1) \times 6 (N+1)} + +Constraints (zero subscripts denote the zeroth/root nodal value): + +.. math:: + + \underline{\Phi} = + \begin{Bmatrix} + \underline{u}_0- \underline{u}_\mathrm{BC} \\ \underline{\psi}_0-\underline{\psi}_\mathrm{BC} + \end{Bmatrix}, \quad \underline{\Phi} \in \mathbb{R}^6 + +.. math:: + + \underline{F}^C = \underline{\underline{B}}^T \underline{\lambda} + \,, \quad \underline{F}^C \in \mathbb{R}^{6 (N+1)}, \quad \underline{\lambda} \in \mathbb{R}^6 + +.. math:: + + \underline{\underline{B}} = + \begin{bmatrix} + \underline{\underline{I}} & \underline{\underline{0}} & \underline{\underline{0}} &\ldots & \underline{\underline{0}} \\ + \underline{\underline{0}} & \underline{\underline{I}} & \underline{\underline{0}} &\ldots & \underline{\underline{0}} + \end{bmatrix}\,, \quad \underline{\underline{B}} \in \mathbb{R}^{6\times 6 (N+1)} + +.. math:: + + \underline{\underline{K}}^C = + \begin{bmatrix} + \underline{\underline{0}} & \underline{\underline{0}} & \ldots & \underline{\underline{0}} \\ + \vdots & \vdots & \ldots & \vdots \\ + \underline{\underline{0}} & \underline{\underline{0}} & \ldots & \underline{\underline{0}} + \end{bmatrix} \,, \quad \underline{\underline{K}}^C + \in \mathbb{R}^{\{6 (N+1)\}\times \{6 (N+1)\}} + +Full residual: + +.. math:: + + \underline{\underline{R}} = + \begin{Bmatrix} + \underline{R}^{FE} + \underline{F}^C \\ + \underline{\Phi} + \end{Bmatrix} + , \quad \underline{R}_{t} \in \mathbb{R}^{6(N+1)+6} + +Iteration matrix: + +.. math:: + + \underline{\underline{S}}_t = + \begin{bmatrix} + \underline{\underline{M}}^{FE} \beta'+\underline{\underline{G}}^{FE} \gamma' + \left(\underline{\underline{K}}^{FE} + \underline{\underline{K}}^C\right) + \underline{\underline{T}}(h \Delta q) & \underline{\underline{B}}^T \\ + \underline{\underline{B}}\,\underline{\underline{T}}(h \Delta q) & \underline{\underline{0}} + \end{bmatrix} + , \quad \underline{\underline{S}}_{t} \in \mathbb{R}^{\{6(N+1)+6\} \times \{6(N+1)+6\}} diff --git a/docs/sphinx/theory/index.rst b/docs/sphinx/theory/index.rst new file mode 100644 index 000000000..2d88e4a7f --- /dev/null +++ b/docs/sphinx/theory/index.rst @@ -0,0 +1,13 @@ +Theory Manual +============= + +This section describes the theoretical background of OpenTurbine such as formulation of +elements, constraints, and other relevant topics. + +.. toctree:: + :glob: + :maxdepth: 2 + + flexible_beam + rigid_body + nonlinear_spring diff --git a/docs/sphinx/theory/nonlinear_spring.rst b/docs/sphinx/theory/nonlinear_spring.rst new file mode 100644 index 000000000..ac475c878 --- /dev/null +++ b/docs/sphinx/theory/nonlinear_spring.rst @@ -0,0 +1,62 @@ +R3-based geometrically nonlinear, constitutively linear spring +============================================================== + +**Overview:** Geometrically nonlinear and constitutively linear spring defined in :math:`\underline{\underline{R}}^3` + +**Spring Model Input at Initialization:** + +- :math:`\underline{x}_1^0 \in \mathbb{R}^3`: node 1 reference position; inertial CS +- :math:`\underline{x}_2^0 \in \mathbb{R}^3`: node 2 reference position; inertial CS +- :math:`\underline{u}_1^i \in \mathbb{R}^3`: node 1 initial displacement +- :math:`\underline{u}_2^i \in \mathbb{R}^3`: node 2 initial displacement +- :math:`k` constitutively linear spring stiffness +- :math:`\ell^\mathrm{us}` unstretched reference length + +**Degrees of Freedom:** + +- :math:`\underline{u}_1 \in \mathbb{R}^3`: node 1 displacement at time :math:`t` +- :math:`\underline{u}_2 \in \mathbb{R}^3`: node 2 displacement at time :math:`t` + +**Force:** + +.. math:: + + \underline{F} = \begin{bmatrix} + \underline{f} \\ + -\underline{f} + \end{bmatrix} + \,, \mathrm{where}\, \underline{F} \in \mathbb{R}^6 + +and + +.. math:: + + \underline{f} = -k \frac{\underline{r} }{| \underline{r} |} \left( | \underline{r} | - \ell^\mathrm{us} \right) + \,, \mathrm{where}\, \underline{r} = \underline{x}_2^0 + \underline{u}_2 - \underline{x}_1^0 - \underline{u}_1 + +.. math:: + + \delta \underline{f} = \underline{\underline{K}}_t + \begin{bmatrix} + \delta \underline{u}_1\\ + \delta \underline{u}_2 + \end{bmatrix} + +.. math:: + + \underline{\underline{K}}_t = \begin{bmatrix} + \underline{\underline{A}} & -\underline{\underline{A}} \\ + - \underline{\underline{A}} & \underline{\underline{A}} + \end{bmatrix} + +and + +.. math:: + + \underline{\underline{A}} = k \left( \frac{\ell^\mathrm{us} }{|\underline{r} |} - 1\right) \underline{\underline{I}} + - \frac{k \ell^\mathrm{us}}{|\underline{r}|^3}\left( \widetilde{r} \widetilde{r} + \underline{\underline{I}} (\underline{r}^T \underline{r} ) \right) + +Aside: For :math:`\underline{a},\underline{r}\in \mathbb{R}^3`, +:math:`\underline{r} (\underline{a}^T \underline{r}) = +\left[ \widetilde{r} \widetilde{r} + \underline{\underline{I}} \left( \underline{r}^T \underline{r} \right) +\right] \underline{a}` diff --git a/docs/sphinx/theory/rigid_body.rst b/docs/sphinx/theory/rigid_body.rst new file mode 100644 index 000000000..1e143eec1 --- /dev/null +++ b/docs/sphinx/theory/rigid_body.rst @@ -0,0 +1,144 @@ +R3xSO(3)-based Rigid Body +========================== + +Overview +-------- + +Details for a rigid-body solver. Unlike Bruls et al (2012), this is formulated in inertial coordinates. + +Rigid-Body Model Input at Initialization +---------------------------------------- + +- **M**\* ∈ ℝ\ :sup:`6×6`: Rigid body mass matrix in material coordinate system (CS) +- **x**\ :sup:`0` ∈ ℝ\ :sup:`3`: Rigid body reference position; inertial CS +- **R**\ :sup:`0` ∈ ℝ\ :sup:`3×3`: Rigid body reference orientation +- **u**\ :sup:`i` ∈ ℝ\ :sup:`3`: Rigid body initial displacement +- **R**\ :sup:`i` ∈ ℝ\ :sup:`3×3`: Rigid body initial orientation +- **u̇**\ :sup:`i` ∈ ℝ\ :sup:`3`: Rigid body initial velocity +- **ω**\ :sup:`i` ∈ ℝ\ :sup:`3`: Rigid body initial angular velocity + +Degrees of Freedom +------------------ + +- **u** ∈ ℝ\ :sup:`3`: Rigid body displacement at time *t* +- **R** ∈ ℝ\ :sup:`3×3`: Rigid-body orientation at time *t* (represented as **q̂** ∈ ℝ\ :sup:`4` quaternion) +- **ω** ∈ ℝ\ :sup:`3`: Rigid body angular velocity at time *t* +- Generalized coordinates: + +.. math:: + + q = \begin{bmatrix} + u \\ + R \\ + \end{bmatrix} + , \quad + \dot{q} = \begin{bmatrix} + \dot{u} \\ + \omega \\ + \end{bmatrix} + , \quad + \ddot{q} = \begin{bmatrix} + \ddot{u} \\ + \dot{\omega} \\ + \end{bmatrix} + +Residual +-------- + +.. math:: + + R^{\mathrm{rb}} = + \begin{bmatrix} + M^{\mathrm{rb}}\, \ddot{q} + g^{\mathrm{rb}} - F^{\mathrm{rb}} + B^T\lambda \\ + \Phi + \end{bmatrix} + \in \mathbb{R}^{6+nc} + +where + +.. math:: + + B \in \mathbb{R}^{nc \times 6}\,, \quad + \lambda \in \mathbb{R}^{nc}\,, \quad + \Phi \in \mathbb{R}^{nc}\,, \quad + F^{\mathrm{rb}} + = + \begin{bmatrix} + f\\ + m\\ + \end{bmatrix} + \in \mathbb{R}^{6} + +.. math:: + + M^{\mathrm{rb}} + = \begin{bmatrix} + m I_3 & m \tilde{\eta}^T \\ + m \tilde{\eta} & \rho + \end{bmatrix} + = \mathcal{RR}^0\, M^* {\mathcal{RR}^0}^T + % + \in \mathbb{R}^{6\times 6} + \,,\quad + g^{\mathrm{rb}} = \begin{bmatrix} + m \tilde{\omega} \tilde{\omega} \eta \\ + \tilde{\omega} \rho \omega + \end{bmatrix} + +and where + +.. math:: + + \mathcal{RR}^0 = + \begin{bmatrix} + R^0 & 0 \\ + 0 & R^0 + \end{bmatrix} + \quad \text{for } \mathcal{RR}^0 \in \mathbb{R}^{6\times6} + +Time Integration +---------------- + +Iteration matrix: + +.. math:: + + S_t = + \begin{bmatrix} + M_t \beta'+C_t \gamma' + K_t + T(h \Delta q) & B^T \\ + B\,T(h \Delta q) & 0 + \end{bmatrix} + , \quad S_{t} \in \mathbb{R}^{(6+nc) \times (6+nc)} + +where + +.. math:: + + M_t = M^{\mathrm{rb}}\in \mathbb{R}^{6\times 6} \,, \quad + C_t = \mathcal{G}^{\mathrm{rb}}\in \mathbb{R}^{6\times 6} \,, \quad + K_t = \mathcal{K}^{\mathrm{rb}} \in \mathbb{R}^{6\times 6} + +and where + +.. math:: + + \mathcal{G}^{\mathrm{rb}} = + \begin{bmatrix} + 0 & \widetilde{ \widetilde{\omega} m \eta }^T + + \widetilde{\omega} m \widetilde{\eta}^T\\ + 0 & \widetilde{\omega} \rho - \widetilde{\rho \omega} + \end{bmatrix} + +.. math:: + + \mathcal{K}^{\mathrm{rb}} = + \begin{bmatrix} + 0 & \left( \dot{\widetilde{\omega}} + \tilde{\omega}\tilde{\omega} + \right) m \widetilde{\eta}^T\\ + 0 & \ddot{\widetilde{u}} m \widetilde{\eta} + + \left(\rho\dot{\widetilde{\omega}} + -\widetilde{\rho \dot{\omega}} \right) + + \widetilde{\omega} \left( \rho \widetilde{\omega} + - \widetilde{ \rho\omega} \right) + \end{bmatrix} diff --git a/docs/sphinx/user/features.rst b/docs/sphinx/user/features.rst new file mode 100644 index 000000000..dfcb61959 --- /dev/null +++ b/docs/sphinx/user/features.rst @@ -0,0 +1,29 @@ +.. _capabilities: + + +Capabilities and Roadmap +======================== + +This section documents a non-exhaustive list of current OpenTurbine +capabilities and roadmap for future capabilities. + +.. tip:: + + If your project relies on a capability that is not yet present in + OpenTurbine, please create an issue on the code project page. + + Please acknowledge as a publication co-author any developer that + has significantly contributed to implementing or improving specific + capability that was used for that publication. + + +Capabilities +------------ + +.. tip:: + + The capabilities are linked to the relevant input file references + (keyword `inp`) and documentation (keyword `doc`). Searching for + those keywords in the `test/test_files` directory will give + concrete examples of the feature usage. + diff --git a/docs/sphinx/user/user.rst b/docs/sphinx/user/user.rst new file mode 100644 index 000000000..679f91192 --- /dev/null +++ b/docs/sphinx/user/user.rst @@ -0,0 +1,8 @@ +User Manual +============= + +.. toctree:: + :glob: + :maxdepth: 2 + + features.rst diff --git a/docs/sphinx/walkthrough/compiling.rst b/docs/sphinx/walkthrough/compiling.rst new file mode 100644 index 000000000..fcf47cf7e --- /dev/null +++ b/docs/sphinx/walkthrough/compiling.rst @@ -0,0 +1,284 @@ +Compiling +========= + +OpenTurbine is developed in C++17 and is designed to be buildable on any +system with a compliant compiler. It utilizes +`Kokkos `_ and +`Trilinos `_ to ensure performance +portability, allowing it to run on any platform supported by these projects. +We strive to test OpenTurbine on a wide range of platforms, including Linux +and macOS, although it is not feasible to cover every possible configuration. +This document outlines the build procedure verified to work on Linux (RHEL8). +For additional assistance tailored to your specific setup, please contact the +developers. + +Spack Installation +------------------ + +The easiest way to use OpenTurbine is through the `Spack `_ +package manager. Once you have downloaded and set up Spack for your +environment, simply run + +.. code-block:: bash + + spack install openturbine + +To see the latest list of supported configuration options, check out the +package file or run + +.. code-block:: bash + + spack info openturbine + +Once it is installed, you can load the OpenTurbine library and its +dependencies into your environment using + +.. code-block:: bash + + spack load openturbine + +Development using Spack Developer Workflow +------------------------------------------ + +One easy way to set up a development environment for OpenTurbine is to use +Spack's Developer Workflow. To setup an environment for working on +OpenTurbine, setup Spack and then run the following commands: + +.. code-block:: bash + + mkdir openturbine + cd openturbine + spack env create -d . + spack env activate . + spack add openturbine+tests + spack install + spack develop openturbine@main + spack concretize -f + spack install + +OpenTurbine's source code will now be located in the openturbine folder, but +can be accessed from anywhere by + +.. code-block:: bash + + spack cd -c openturbine + +After editing the code here, it can be rebuilt by running + +.. code-block:: bash + + spack install + +To run the tests, first access the build folder through the spack command + +.. code-block:: bash + + spack cd -b openturbine + +Next, the tests can be run either through ctest or directly from the unit +test or regression test executables + +.. code-block:: bash + + ctest + ./tests/unit_tests/openturbine_unit_tests + ./tests/regression_tests/openturbine_regression_tests + +You can also build OpenTurbine from this folder using standard make +commands. + +For more information, please see Spack's documentation: +https://spack-tutorial.readthedocs.io/en/latest/tutorial_developer_workflows.html + +Building and Developing in OpenTurbine Directly +----------------------------------------------- + +The following sections outline how to build and develop OpenTurbine without +Spack's Developer Workflows. The main complication here is that developers +will have to manage their environment and dependencies manually, which may +be an unnecessary complication or a freeing feature, depending on your +perspective. + +Dependencies +------------ + +Before building OpenTurbine, you'll need the following: + +- C++ compiler that supports the C++17 standard +- `CMake `_: the default build system for C++ projects, + version 3.21 or later +- `Kokkos `_: core programming model for + performance portability +- `KokkosKernels `_: performance + portable linear algebra library +- `Trilinos `_: primarily for the + Amesos2 sparse direct linear solver package +- `GoogleTest `_: unit testing package + +Installing Third Party Libraries +-------------------------------- + +There are several methods to obtain the necessary Third Party Libraries +(TPLs) for building OpenTurbine, however the simplest is to use the +`spack `_ package manager. Spack offers a +comprehensive set of features for development and dependency management. The +following is a quick-start guide for installing and loading the TPLs required +to build OpenTurbine. + +Clone the spack repository, load the spack environment, and let spack learn about your system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + git clone git@github.com:spack/spack.git + source spack/share/spack/setup-env.sh + spack compiler find + spack external find + +Install GoogleTest +~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + spack install googletest + +Install Trilinos +~~~~~~~~~~~~~~~~ + +To build OpenTurbine, Kokkos Kernels must be configured to use the LAPACK +and BLAS TPLs. For GPU builds, Trilinos should be compiled with support for +the Basker linear solver. Additionally, we typically disable EPetra to avoid +deprecation warnings. As of this writing, OpenTurbine is compatible with +Trilinos version 16.0.0, which is the latest and default version in spack. + +For a simple serial build + +.. code-block:: bash + + spack install trilinos~epetra ^kokkos-kernels+blas+lapack + +Trilinos can also be compiled with OpenMP support for parallelism on CPU based machines + +.. code-block:: bash + + spack install trilinos~epetra+openmp ^kokkos-kernels+blas+lapack + +If building for CUDA platforms, Trilinos must be configured with CUDA support + +.. code-block:: bash + + spack install trilinos~epetra+basker+cuda ^kokkos-kernels+blas+lapack + +If building for ROCm platforms, Trilinos must be configured with ROCm support + +.. code-block:: bash + + spack install trilinos~epetra+basker+rocm ^kokkos-kernels+blas+lapack + +Trilinos can be built with or without MPI support. + +Load the TPLs into your environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + spack load googletest + spack load trilinos + +Trilinos can be compiled with support for various platforms. While it is +assumed that OpenTurbine will inherit compatibility with these platforms, +they have not been tested at the time of writing. + +If you choose not to use Spack, you must manually build all dependencies. +Please ensure that the ``Amesos2_DIR``, ``GTest_DIR``, and ``KokkosKernels_DIR`` +environment variables are correctly set for these packages. Alternatively, +make sure that CMake's ``find_package`` utility can locate them. + +Building OpenTurbine +-------------------- + +The following is written assuming the TPLs in hand and the environment +configured as described above. + +Clone OpenTurbine and setup a build directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + git clone git@github.com:Exawind/openturbine.git + cd openturbine + mkdir build + cd build + +Configure cmake +~~~~~~~~~~~~~~~ + +For a CPU-based build which includes building unit tests, use + +.. code-block:: bash + + cmake ../ + +If Trilinos was built with CUDA support, you will need to use the nvcc_wrapper +for compilation + +.. code-block:: bash + + cmake ../ -DCMAKE_CXX_COMPILER=nvcc_wrapper + +If Trilinos was built with ROCm support, you will need to use the hipcc program +for compilation + +.. code-block:: bash + + cmake ../ -DCMAKE_CXX_COMPILER=hipcc + +Build and Test +~~~~~~~~~~~~~~ + +Currently, OpenTurbine builds several shared libraries by default. To ensure +that their unit tests pass, these libraries must be copied into the directory +where the tests are executed. + +.. code-block:: bash + + make -j + cp src/*.dll tests/unit_tests/ + ctest --output-on-failure + +Once built, the unit test executable can also be run directly from the build +directory + +.. code-block:: bash + + ./tests/unit_tests/openturbine_unit_tests + +Build Options +------------- + +OpenTurbine has several build options which can be set either when running +CMake from the command line or through a GUI such as ccmake. + +- ``OpenTurbine_ENABLE_CLANG_TIDY`` enables the Clang-Tidy static analysis tool +- ``OpenTurbine_ENABLE_COVERAGE`` enables code coverage analysis using gcov +- ``OpenTurbine_ENABLE_CPPCHECK`` enables the CppCheck static analysis tool +- ``OpenTurbine_ENABLE_IPO`` enables link time optimization +- ``OpenTurbine_ENABLE_PCH`` builds precompiled headers to potentially decrease + compilation time +- ``OpenTurbine_ENABLE_SANITIZER_ADDRESS`` enables the address sanitizer runtime + analysis tool +- ``OpenTurbine_ENABLE_SANITIZER_LEAK`` enables the leak sanitizer runtime + analysis tool +- ``OpenTurbine_ENABLE_SANITIZER_MEMORY`` enables the memory sanitizer runtime + analysis tool +- ``OpenTurbine_ENABLE_SANITIZER_THREAD`` enables the thread sanitizer runtime + analysis tool +- ``OpenTurbine_ENABLE_SANITIZER_UNDEFINED`` enables the undefined behavior + sanitizer runtime analysis tool +- ``OpenTurbine_ENABLE_TESTS`` builds OpenTurbine's test suite +- ``OpenTurbine_ENABLE_UNITY_BUILD`` uses unity builds to potentially decrease + compilation time +- ``OpenTurbine_ENABLE_VTK`` builds OpenTurbine with VTK support for + visualization in tests. Will need the VTK TPL to be properly configured +- ``OpenTurbine_WARNINGS_AS_ERRORS`` treats warnings as errors, including + warnings from static analysis tools diff --git a/docs/sphinx/walkthrough/index.rst b/docs/sphinx/walkthrough/index.rst new file mode 100644 index 000000000..ef4d0941a --- /dev/null +++ b/docs/sphinx/walkthrough/index.rst @@ -0,0 +1,21 @@ +Walkthrough +=========== + +This section demonstrates a typical OpenTurbine workflow, walking through the steps +required to analyze wind turbine components and systems. The compilation instructions +outline how to build OpenTurbine and its dependencies. OpenTurbine is part of the +ExaWind software suite, which provides a comprehensive set of tools for wind energy +modeling and simulation. + +.. note:: + + This tutorial is intended to provide an example of how OpenTurbine is often used, + but there are many variations and alternative workflows that OpenTurbine + provides. Please consult the :doc:`../user/user` for additional details on + other OpenTurbine features and options. + +.. toctree:: + :glob: + :maxdepth: 2 + + compiling.rst diff --git a/docs/tools.md b/docs/tools.md deleted file mode 100644 index ed537fb4a..000000000 --- a/docs/tools.md +++ /dev/null @@ -1,32 +0,0 @@ -# Developer Tools - -This page describes tools used in the development of OpenTurbine. -These should generally be adopted by all developers so that -expectations and systems are aligned. - -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: - -## clang-format - -[ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) is used -for linting to enforce a consistent code style. It can be installed -with most package managers. The syntax to run the linter is given -below. - -```bash -# Lint in place all .cpp files in the src directory -clang-format -i src/*.cpp - -# Show changes in stdout for all header files in the utilities directory -clang-format -i src/utilities/*.H -``` - -ClangFormat is configured by the `.clang-format`. If the tool -is run from the top directory, it will automatically detect and load -the settings in the configuration file. - -**NOTE** The CI system runs this linter and any required changes will -cause the system to fail. diff --git a/docs/tutorials.md b/docs/tutorials.md deleted file mode 100644 index 09ce8c4ff..000000000 --- a/docs/tutorials.md +++ /dev/null @@ -1,7 +0,0 @@ -(tutorials)= -# Tutorials / How-To - -:::{warning} -This page is under construction. Check back here throughout FY23 -for updates, and see activity at https://github.com/exawind/openturbine. -::: diff --git a/src/elements/beams/CMakeLists.txt b/src/elements/beams/CMakeLists.txt index 321835c1e..1031f77fd 100644 --- a/src/elements/beams/CMakeLists.txt +++ b/src/elements/beams/CMakeLists.txt @@ -2,6 +2,7 @@ target_sources(openturbine_library PRIVATE) install(FILES beam_element.hpp + beam_quadrature.hpp beam_section.hpp beams.hpp beams_input.hpp diff --git a/src/elements/beams/populate_element_views.hpp b/src/elements/beams/populate_element_views.hpp index 1c3d420fb..57a89bca4 100644 --- a/src/elements/beams/populate_element_views.hpp +++ b/src/elements/beams/populate_element_views.hpp @@ -7,17 +7,19 @@ namespace openturbine { +/// @brief Populate the node initial position and orientation inline void PopulateNodeX0( const BeamElement& elem, const std::vector& nodes, const Kokkos::View& node_x0 ) { for (size_t j = 0; j < elem.node_ids.size(); ++j) { - for (size_t k = 0U; k < kLieGroupComponents; ++k) { + for (size_t k = 0U; k < 7U; ++k) { node_x0(j, k) = nodes[elem.node_ids[j]].x[k]; } } } +/// @brief Populate the integration weights at each quadrature point inline void PopulateQPWeight( const BeamElement& elem, const Kokkos::View& qp_weight @@ -27,14 +29,23 @@ inline void PopulateQPWeight( } } -inline void PopulateShapeFunctionValues( - const BeamElement& elem, const std::vector& nodes, - const Kokkos::View& shape_interp +/// @brief Map node positions from [0,1] to [-1,1] +inline std::vector MapNodePositions( + const BeamElement& elem, const std::vector& nodes ) { std::vector node_xi(elem.node_ids.size()); for (size_t i = 0; i < elem.node_ids.size(); ++i) { node_xi[i] = 2 * nodes[elem.node_ids[i]].s - 1; } + return node_xi; +} + +/// @brief Populate shape function values at each quadrature point +inline void PopulateShapeFunctionValues( + const BeamElement& elem, const std::vector& nodes, + const Kokkos::View& shape_interp +) { + const auto node_xi = MapNodePositions(elem, nodes); std::vector weights; for (size_t j = 0; j < elem.quadrature.size(); ++j) { @@ -47,14 +58,12 @@ inline void PopulateShapeFunctionValues( } } +/// @brief Populate shape function derivatives at each quadrature point inline void PopulateShapeFunctionDerivatives( const BeamElement& elem, const std::vector& nodes, const Kokkos::View& shape_deriv ) { - std::vector node_xi(elem.node_ids.size()); - for (size_t i = 0; i < elem.node_ids.size(); ++i) { - node_xi[i] = 2 * nodes[elem.node_ids[i]].s - 1; - } + const auto node_xi = MapNodePositions(elem, nodes); std::vector weights; for (size_t j = 0; j < elem.quadrature.size(); ++j) { @@ -67,15 +76,22 @@ inline void PopulateShapeFunctionDerivatives( } } +/// @brief Map section positions from [0,1] to [-1,1] +inline std::vector MapSectionPositions(const BeamElement& elem) { + std::vector section_xi(elem.sections.size()); + for (size_t i = 0; i < elem.sections.size(); ++i) { + section_xi[i] = 2 * elem.sections[i].position - 1; + } + return section_xi; +} + +/// @brief Populate mass matrix values at each quadrature point inline void PopulateQPMstar( const BeamElement& elem, const Kokkos::View& qp_Mstar ) { + const auto section_xi = MapSectionPositions(elem); std::vector weights(elem.sections.size()); - std::vector section_xi(elem.sections.size()); - for (size_t i = 0; i < elem.sections.size(); ++i) { - section_xi[i] = 2 * elem.sections[i].position - 1; - } for (size_t i = 0; i < elem.quadrature.size(); ++i) { auto qp_xi = elem.quadrature[i][0]; @@ -95,15 +111,13 @@ inline void PopulateQPMstar( } } +/// @brief Populate stiffness matrix values at each quadrature point inline void PopulateQPCstar( const BeamElement& elem, const Kokkos::View& qp_Cstar ) { + const auto section_xi = MapSectionPositions(elem); std::vector weights(elem.sections.size()); - std::vector section_xi(elem.sections.size()); - for (size_t i = 0; i < elem.sections.size(); ++i) { - section_xi[i] = 2 * elem.sections[i].position - 1; - } for (size_t i = 0; i < elem.quadrature.size(); ++i) { auto qp_xi = elem.quadrature[i][0]; diff --git a/tests/unit_tests/system/masses/test_calculate_gravity_force.cpp b/tests/unit_tests/system/masses/test_calculate_gravity_force.cpp index 31fe0323c..7fd947acc 100644 --- a/tests/unit_tests/system/masses/test_calculate_gravity_force.cpp +++ b/tests/unit_tests/system/masses/test_calculate_gravity_force.cpp @@ -17,7 +17,7 @@ struct ExecuteCalculateGravityForce { }; TEST(CalculateGravityForceTestsMasses, OneNode) { - constexpr double mass = 1.; + constexpr auto mass = 1.; const auto eta_tilde = Kokkos::View("eta_tilde"); constexpr auto eta_tilde_data = std::array{37., 38., 39., 40., 41., 42., 43., 44., 45.}; diff --git a/tests/unit_tests/system/masses/test_calculate_inertial_forces.cpp b/tests/unit_tests/system/masses/test_calculate_inertial_forces.cpp index 155be6fac..5ebcc8426 100644 --- a/tests/unit_tests/system/masses/test_calculate_inertial_forces.cpp +++ b/tests/unit_tests/system/masses/test_calculate_inertial_forces.cpp @@ -27,7 +27,7 @@ struct ExecuteCalculateInertialForces { }; TEST(CalculateInertialForcesTestsMasses, OneNode) { - constexpr double mass = 1.; + constexpr auto mass = 1.; const auto u_ddot = Kokkos::View("u_ddot"); constexpr auto u_ddot_data = std::array{37., 38., 39.};