{"id":23224163,"url":"https://github.com/jppelteret/dealii-weak_forms","last_synced_at":"2025-08-02T22:05:04.156Z","repository":{"id":37997779,"uuid":"340746669","full_name":"jppelteret/dealii-weak_forms","owner":"jppelteret","description":"An implementation of a symbolic weak form interface for deal.II, using expression templates as well as automatic and symbolic differentiation.","archived":false,"fork":false,"pushed_at":"2023-03-04T17:17:00.000Z","size":14046,"stargazers_count":5,"open_issues_count":9,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T00:26:08.370Z","etag":null,"topics":["cpp","dealii","finite-element-method","weak-forms"],"latest_commit_sha":null,"homepage":"https://jppelteret.github.io/dealii-weak_forms/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jppelteret.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING.LESSER","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-20T20:26:53.000Z","updated_at":"2024-05-29T16:54:36.000Z","dependencies_parsed_at":"2024-12-18T23:33:04.227Z","dependency_job_id":"e7e0ebfe-ad59-4cb2-acbc-1635b770b7e0","html_url":"https://github.com/jppelteret/dealii-weak_forms","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jppelteret/dealii-weak_forms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jppelteret%2Fdealii-weak_forms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jppelteret%2Fdealii-weak_forms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jppelteret%2Fdealii-weak_forms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jppelteret%2Fdealii-weak_forms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jppelteret","download_url":"https://codeload.github.com/jppelteret/dealii-weak_forms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jppelteret%2Fdealii-weak_forms/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268464789,"owners_count":24254196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","dealii","finite-element-method","weak-forms"],"created_at":"2024-12-18T23:32:51.550Z","updated_at":"2025-08-02T22:05:04.070Z","avatar_url":"https://github.com/jppelteret.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Linux CI](https://github.com/jppelteret/dealii-weak_forms/actions/workflows/ci.yml/badge.svg)\n![Doxygen documentation](https://github.com/jppelteret/dealii-weak_forms/actions/workflows/doxygen.yml/badge.svg)\n![Source indentation](https://github.com/jppelteret/dealii-weak_forms/actions/workflows/indentation.yml/badge.svg)\n\n# Weak forms for deal.II\n------------------------\nAn implementation of a symbolic weak form interface for `deal.II`, using \nexpression templates as well as automatic and symbolic differentiation. \n\nAuthor: Jean-Paul Pelteret, 2020 - 2022\n\n# Table of Contents\n\n- [Concept](#concept)\n- [Features](#features)\n   - [Highlights](#highlights)\n   - [Wishlist and work in progress](#wishlist-and-work-in-progress)\n- [Class documentation](#class-documentation)\n- [Examples](#examples)\n- [Benchmarks](#benchmarks)\n- [Building the library](#building-the-library)\n- [Citing the library](#citing-the-library)\n- [Docker images](#docker-images)\n   - [Building the image](#building-the-image) \n   - [Running the image](#running-the-image) \n- [Similar projects that inspired this work](#similar-projects-that-inspired-this-work)\n- [Acknowledgements](#acknowledgements)\n- [Contributing](#contributing)\n- [License](#license)\n\n# Concept\n---------\nThe idea for this library is to offer an abstraction for the discretisation\nof finite element weak forms using the `deal.II` open source finite element\nlibrary. It, effectively, allows one to express the assembly of discretised\nlinear system by the weak form alone, the components of which can be reused\nas they are lazily evaluated.\n\nTo summarise what this library offers the user: by providing an intuitive\nmethod to compose and re-use operations, the user is able to focus more on\n*what* they are doing (i.e. the algorithm or discretisation that they are\nwanting to implement) rather than *how* they are doing it (i.e. the\nprogrammatic implementation itself). This way you need not be distracted\nthe minutia of the implementation -- all of the calculation loops are now\nhidden details, as are the data storage and value extraction processes.\nPermitting the storing and reusing intermediate values (or composite\noperations) means that if you want to change that definition, then you only\nneed to do it in one place -- in the case of a composite operation, all of\nthe updates to the underlying value composition follow seemlessly, and without\nany further intervention. On top of that, by leveraging automatic or symbolic\ndifferentiation, the number of hand-calculations required to implement\ncomplex constitutive laws *correctly* diminishes significantly.\n\nDetails as to exactly what the abstraction level is, and how it differs to the\n\"native\" functionality that is already provided in `deal.II` can be found\n[here](doc/readme/concept.md).\n\n\n# Features\n----------\n\n## Highlights\n- Easy to read and interpret expression of weak forms\n- Output of forms in ASCII and LaTeX formats\n- Any and all quantities can be retained as intermediate calculations\n- Wrappers for many of the commonly used `deal.II` functions and classes\n- Operator and function overloading for many `deal.II` dense linear algebra\n  classes\n- Support for scalar, vector and tensor-valued finite elements\n- Support for multi-field forms, thereby supporting the implementation of \n  (coupled) multi-physics problems\n- The use of `std::function`s as input to user-definable class value definitions\n- Self-linearising forms with specified parameterisations that leverage\n  automatic and symbolic differentiation frameworks. This allows for problems\n  to be implemented as a (scalar) energy functional or the expression of\n  residuals alone. The AD/SD frameworks permit efficient derivative computations\n  derived from provided quantities.\n- The datatype for calculations (`float`, `double`, `std::complex\u003c...\u003e`) is\n  chosen only at assembly time and is, in principle, generic. This permits the\n  implementation of complex-valued forms.\n- Volume, boundary and interface integration\n  - Assembly loops, assembling cell or face matrix and/or vector contributions\n    into a global linear system\n  - Summation of quantities (like the integral of a field value)\n- Supports the hp finite element method\n- Supports MPI and serial computing concepts\n- Automatically implements multi-threading along with `SIMD` vectorisation\n  (when available)\n\n## Wishlist and work in progress\n- Performance improvements for the self-linearising forms is an ongoing area of\n  interest and research. \n- A matrix-free implementation will be investigated in the future.\n- Python bindings, to be usable in Jupyter Notebooks, will be investigated.\n\n# Class documentation\n---------------------\nThe source code documentation for this project can be found at https://jppelteret.github.io/dealii-weak_forms/index.html. \n\nAs the Doxygen documentation is incomplete, some more informative documentation for the user-interactive classes and some details\nof how they can be used are found [here](doc/readme/classes.md).\n\n\n# Examples\n----------\nSome examples and output can be found [here](doc/readme/examples.md).\n\n\n# Benchmarks\n------------\nThe results of some preliminary benchmarks can be found [here](doc/readme/benchmarks.md).\n\nTo summarise, for matrix-based methods the convenience that might be found in\nusing such a library does come at some overhead. The overheads may be mitigated\nwhen higher order finite element methods are used (i.e. when using higher order \nFEs, a \"typical\" hand-written assembly loop (meaning, the canonical approach used\nin the `deal.II` tutorials) *may* be evaluated slower than the assembly loop \ngenerated by this library and when all the appropriate settings permitting\noptimisations have been chosen). However, there are many factors that might\ninfluence the performance of a code so this comment, guided by the observations\nmade in the (limited) benchmarking study, should not be considered general truth.\nIt might be prudent to conduct some examinations of your own before accepting\nthe analysis done here and following any guidance given by the author.\n\n\n# Building the library\n----------------------\nThis library requires `deal.II` version `9.4.0` (at the time of writing, this\nmeans the developer version), and a `C++14` compliant compiler (the minimum\nrequirement to build `deal.II`). \n\nIn order to use the automatic or symbolic differentiation facilities, it is\nrequired that `deal.II` is built with the one or more of the following optional\ndependencies:\n-  ADOL-C\n-  Trilinos (with Sacado)\n-  SymEngine\n\nThis project uses `CMake` as a build generator. The code block below encapsulates\nthe various options that can be passed on `CMake` to configure the project before\ncompilation.\n\n```bash\ncmake \\\n-DCMAKE_BUILD_TYPE=[Debug/Release] \\\n-DCMAKE_INSTALL_PREFIX=\u003cpath_to_installation_location\u003e \\\n-DBUILD_BENCHMARKS=[ON/OFF] \\\n-DBUILD_DOCUMENTATION=[ON/OFF] \\\n-DBUILD_TESTS=[ON/OFF] \\\n-DDEAL_II_DIR=\u003cpath\u003e \\\n-DDEAL_II_SOURCE_DIR=\u003cpath\u003e \\ # Only required when tests or benchmarks are enabled\n-DDOXYGEN_EXECUTABLE=\u003cpath_to_doxygen\u003e \\ # Only required when documentation is built\n-DCLANGFORMAT=[ON/OFF] \\\n-DCLANGFORMAT_EXECUTABLE=\u003cpath_to_clang-format\u003e \\ # Only required when code formatting is quired\n\u003cpath_to_weak_forms_source\u003e\n```\n\nThis library has only been built and tested on `MacOS` with the `Clang`\ncompiler, as well as the `GCC` compiler on a `Linux` operating system.\n`Windows` and/or `MSVC` are not explicitly supported.\n\n## Dependency recommendations\n-----------------------------\n- If you plan on using multi-threading and the `SD` framework provided by one of\n  the self-linearising functors, then SymEngine (a `deal.II` dependency) should\n  be built with the option `-DWITH_SYMENGINE_THREAD_SAFE:BOOL=ON`.\n\n\n# Citing the library\n--------------------\nThis library has been created for the author's enjoyment, so no direct citation\nis necessary, thanks. Since this library acts as a convenience wrapper around\ndata structures and algorithms implemented in the `deal.II` library, a citation\nof the latest release paper, as well as the design paper, would be appreciated.\n```bibtex\n@article{dealII93,\n  title     = {The \\texttt{deal.II} Library, Version 9.3},\n  author    = {Daniel Arndt and Wolfgang Bangerth and Bruno Blais and\n               Marc Fehling and Rene Gassm{\\\"o}ller and Timo Heister\n               and Luca Heltai and Uwe K{\\\"o}cher and Martin\n               Kronbichler and Matthias Maier and Peter Munch and\n               Jean-Paul Pelteret and Sebastian Proell and Konrad\n               Simon and Bruno Turcksin and David Wells and Jiaqi\n               Zhang},\n  journal   = {Journal of Numerical Mathematics},\n  year      = {2021, accepted for publication},\n  url       = {https://dealii.org/deal93-preprint.pdf},\n  doi       = {10.1515/jnma-2021-0081},\n  volume    = {29},\n  number    = {3},\n  pages     = {171--186}\n}\n\n@article{dealII2019design,\n  title   = {The {deal.II} finite element library: Design, features,\n             and insights},\n  author  = {Daniel Arndt and Wolfgang Bangerth and Denis Davydov and\n             Timo Heister and Luca Heltai and Martin Kronbichler and\n             Matthias Maier and Jean-Paul Pelteret and Bruno Turcksin and\n             David Wells},\n  journal = {Computers \\\u0026 Mathematics with Applications},\n  year    = {2021},\n  DOI     = {10.1016/j.camwa.2020.02.022},\n  pages   = {407-422},\n  volume  = {81},\n  issn    = {0898-1221},\n  url     = {https://arxiv.org/abs/1910.13247}\n}\n```\nAs the matrix-based implementation leverages some awesome concepts and data\nstructures in the `deal.II` library, it would be appropriate to cite the\nauthors of those specific areas of work.\n- `MeshWorker::mesh_loop()`, built on top of the `WorkStream` pattern, for\n  efficient multithreading\n  ```bibtex\n  @article{Turcksin2016,\n    author    = {B. Turcksin and M. Kronbichler and W. Bangerth},\n    title     = {WorkStream -- a design pattern for multicore-enabled finite\n                 element computations},\n    journal   = {ACM Transactions on Mathematical Software, pp. 2/1-29},\n    year      = {2016},\n    volume    = {43}\n  }\n  ```\n- `VectorizedArray` and `AlignedVector` for `SIMD` vectorisation\n  ```bibtex\n  @article{Kronbichler2012,\n    author = {Martin Kronbichler and Katharina Kormann},\n    title = {A generic interface for parallel cell-based finite element\n             operator application},\n    journal = {Computers {\\\u0026} Fluids},\n    doi = {10.1016/j.compfluid.2012.04.012},\n    url = {https://doi.org/10.1016/j.compfluid.2012.04.012},\n    year = {2012},\n    month = jun,\n    publisher = {Elsevier {BV}},\n    volume = {63},\n    pages = {135--147}\n  }\n  ```\n- `MeshWorker::ScratchData` and `GeneralDataStorage` for generic finite element\n   operations and data storage / extraction.\n  ```bibtex\n  @article{Sartori2018,\n    Author  = {Sartori, Alberto and Giuliani, Nicola and\n               Bardelloni, Mauro and Heltai, Luca},\n    Journal = {SoftwareX},\n    Pages   = {318--327},\n    Title   = {{deal2lkit: A toolkit library for high performance\n              programming in deal.II}},\n    Doi     = {10.1016/j.softx.2018.09.004},\n    Volume  = {7},\n    Year    = {2018}\n  }\n  ```\n\n# Docker images\n---------------\nA [template](./docker/Dockerfile) for creating a docker image can be found in the `docker` folder.\n\n## Building the image\n```sh\n$ docker build . -t dealii-weak_forms-full_ci -f ./Dockerfile\n$ docker run -d dealii-weak_forms-full_ci\n```\n\n## Running the image\n```sh\n$ docker run --rm -t -i -v `pwd`:/home/dealii dealii-weak_forms-full_ci\n```\n\n# Similar projects that inspired this work\n------------------------------------------\n- `deal.II`\n  - [CFL form language for deal.II](https://github.com/masterleinad/CFL) by Daniel Arndt and Guido Kanschat\n- Other finite element and finite volume codes\n  - [FEniCS](https://fenicsproject.org/): [Unified Form Language](https://github.com/FEniCS/ufl)\n  - [NGSolve](https://ngsolve.org/): [Symbolic Integrators](https://docu.ngsolve.org/latest/how_to/symbolic_integrators.html)\n  - [OpenFOAM](https://openfoam.com/): [Equation representation](https://cfd.direct/openfoam/user-guide/v6-programming-language-openfoam/)\n- Other codes that use expression templates\n  - [Sacado](https://trilinos.github.io/sacado.html): [Automatic differentiation using operator overloading](https://github.com/trilinos/Trilinos/tree/master/packages/sacado) \n\n\n# Acknowledgements\n------------------\n- The LaTeX output for the various examples was rendered using the [Interactive LaTeX Editor](https://arachnoid.com/latex/).\n\n\n# Contributing\n--------------\nPlease read the contributing documentation [here](contributing.md).\n\n\n# License\n---------\nThis project is licensed under the GNU Lesser General Public License v3.0.\nFor more information, see the `LICENSE.md` and `COPYING.LESSER` files.\n\n    Weak forms for deal.II: An implementation of a symbolic weak form interface\n    for deal.II, using expression templates as well as automatic and symbolic\n    differentiation. \n\n    Copyright (C) 2021 - 2022  Jean-Paul Pelteret\n\n    This program is free software: you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjppelteret%2Fdealii-weak_forms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjppelteret%2Fdealii-weak_forms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjppelteret%2Fdealii-weak_forms/lists"}