libCEED User Manual Release 0.9.0 Ahmad Abdelfattah Valeria Barra Natalie Beams Jed Brown Jean-Sylvain Camier Veselin Dobrev Yohann Dudouit Leila Ghaffari Tzanio Kolev David Medina Will Pazner Thilina Ratnayaka Jeremy L. Thompson Stan Tomov Oct 01, 2021 Contents 1 Introduction 4 2 Getting Started 6 2.1 Building ................................................. 6 2.2 Additional Language Interfaces .................................... 7 2.3 Testing .................................................. 7 2.4 Backends ................................................. 8 2.5 Examples ................................................. 9 2.6 Benchmarks ............................................... 11 2.7 Install ................................................... 11 2.7.1 pkg-config ............................................ 12 2.8 Contact .................................................. 12 2.9 How to Cite ............................................... 12 2.10 Copyright ................................................ 13 3 Interface Concepts 13 3.1 Theoretical Framework ......................................... 13 3.2 Finite Element Operator Decomposition ............................... 14 3.2.1 Terminology and Notation ................................... 15 3.2.2 Partial Assembly ........................................ 19 3.2.3 Parallel Decomposition .................................... 20 1 3.3 API Description ............................................. 20 3.4 Gallery of QFunctions ......................................... 26 3.5 Interface Principles and Evolution .................................. 27 4 Examples 28 4.1 Common notation ............................................ 28 4.2 Standalone libCEED .......................................... 28 4.2.1 Ex1-Volume ........................................... 28 4.2.2 Ex2-Surface ........................................... 29 4.3 CEED Bakeoff Problems ........................................ 29 4.3.1 Mass Operator ......................................... 30 4.3.2 Laplace’s Operator ....................................... 31 4.4 PETSc demos and BPs ......................................... 31 4.4.1 Area ............................................... 31 4.4.1.1 Cube .......................................... 31 4.4.1.2 Sphere ......................................... 32 4.4.2 Bakeoff problems and generalizations ............................ 34 4.4.2.1 Bakeoff problems on the cubed-sphere ...................... 34 4.4.3 Multigrid ............................................ 35 4.5 Compressible Navier-Stokes mini-app ................................ 35 4.5.1 Running the mini-app ..................................... 36 4.5.2 The Navier-Stokes equations ................................. 39 4.5.3 Advection ............................................ 42 4.5.4 Isentropic Vortex ........................................ 43 4.5.5 Density Current ......................................... 43 4.6 Solid mechanics mini-app ....................................... 43 4.6.1 Running the mini-app ..................................... 44 4.6.1.1 On algebraic solvers ................................. 46 4.6.1.2 Nondimensionalization ............................... 47 4.6.1.3 Diagnostic Quantities ................................ 47 4.6.2 Linear Elasticity ......................................... 48 4.6.2.1 Constitutive modeling ............................... 48 4.6.3 Hyperelasticity at Small Strain ................................ 49 4.6.3.1 Newton linearization ................................ 49 4.6.4 Hyperelasticity at Finite Strain ................................ 50 4.6.4.1 Constitutive modeling ............................... 50 4.6.4.2 Weak form ...................................... 52 4.6.4.3 Newton linearization ................................ 53 4.6.5 Hyperelasticity in current configuration ........................... 55 4.6.5.1 Push forward, then linearize ............................ 55 4.6.5.2 Linearize, then push forward ............................ 57 4.6.5.3 Jacobian representation ............................... 58 5 Julia, Python, and Rust Interfaces 58 6 API Documentation 58 6.1 Public API ................................................ 58 6.1.1 Ceed ............................................... 58 6.1.1.1 Base library resources ................................ 58 6.1.2 CeedVector ........................................... 64 6.1.2.1 Basic vector operations ............................... 64 6.1.3 CeedElemRestriction ...................................... 69 6.1.3.1 Expressing element decomposition and degrees of freedom over a mesh .. 69 6.1.4 CeedBasis ............................................ 75 2 6.1.4.1 Discrete element bases and quadrature ...................... 75 6.1.5 CeedQFunction ......................................... 83 6.1.5.1 Resolution/space-independent weak forms and quadrature-based operations 83 6.1.6 CeedOperator .......................................... 90 6.1.6.1 Discrete operators on user vectors ......................... 90 6.2 Backend API ............................................... 99 6.2.1 Ceed ............................................... 99 6.2.2 CeedVector ........................................... 104 6.2.3 CeedElemRestriction ...................................... 105 6.2.4 CeedBasis ............................................ 107 6.2.5 CeedQFunction ......................................... 111 6.2.6 CeedOperator .......................................... 114 6.3 Internal Functions ............................................ 116 6.3.1 Ceed ............................................... 116 6.3.2 CeedVector ........................................... 116 6.3.3 CeedElemRestriction ...................................... 116 6.3.4 CeedBasis ............................................ 116 6.3.5 CeedQFunction ......................................... 118 6.3.6 CeedOperator .......................................... 119 7 Floating Point Precision 123 7.1 Language-specific notes ........................................ 124 8 Developer Notes 124 8.1 Style Guide ................................................ 124 8.2 Clang-tidy ................................................ 124 8.3 Header Files ............................................... 125 8.4 Shape ................................................... 125 8.5 restrict semantics .......................................... 126 8.6 Internal Layouts ............................................. 126 8.7 Backend Inheritance .......................................... 126 9 libCEED: How to Contribute 127 9.1 Developer’s Certificate of Origin 1.1 ................................. 127 9.2 Authorship ................................................ 128 10 libCEED Code of Conduct 128 10.1 Our Pledge ................................................ 128 10.2 Our Standards .............................................. 128 10.3 Enforcement Responsibilities ..................................... 129 10.4 Scope ................................................... 129 10.5 Enforcement ............................................... 129 10.6 Enforcement Guidelines ........................................ 129 10.6.1 1. Correction .......................................... 129 10.6.2 2. Warning ............................................ 130 10.6.3 3. Temporary Ban ........................................ 130 10.6.4 4. Permanent Ban ........................................ 130 10.7 Attribution ................................................ 130 11 Changes/Release Notes 130 11.1 Current main branch .......................................... 131 11.1.1 Interface changes ........................................ 131 11.1.2 New features .......................................... 131 11.1.3 Maintainability ......................................... 131 11.2 v0.9 (Jul 6, 2021) ............................................. 131 3 11.2.1 Interface changes ........................................ 131 11.2.2 New features .......................................... 131 11.2.3 Performance improvements .................................. 132 11.2.4 Examples ............................................ 132 11.2.5 Deprecated backends ...................................... 132 11.3 v0.8 (Mar 31, 2021) ........................................... 132 11.3.1 Interface changes ........................................ 132 11.3.2 New features .......................................... 132 11.3.3 Performance improvements .................................. 132 11.3.4 Examples ............................................ 132 11.4 v0.7 (Sep 29, 2020) ............................................ 133 11.4.1 Interface changes ........................................ 133 11.4.2 New features .......................................... 133 11.4.3 Performance improvements .................................. 134 11.4.4 Examples ............................................ 134 11.4.5 Deprecated backends ...................................... 134 11.5 v0.6 (Mar 29, 2020) ........................................... 134 11.5.1 New features .......................................... 134 11.5.2 Performance Improvements .................................. 135 11.5.3 Interface changes ........................................ 135 11.5.4 Examples ............................................ 135 11.6 v0.5 (Sep 18, 2019) ............................................ 136 11.7 v0.4 (Apr 1, 2019) ............................................ 137