Developer Guide

• PyLith design
  • Design overview
    • Boundary between Python and C++
  • PyLith Application Flow
    • Time-Dependent Problem
  • Code Layout
    • Directory Structure
• PyLith implementation
  • Code Structure
    • Legend for class diagrams
    • Application
    • Problem
    • Solution
    • Physics and Finite-Element Objects
    • Materials
    • Boundary Conditions
    • Interior Interfaces (Faults)
    • Mesh Importing
    • Output
  • PETSc Finite-Element Implementation
    • DMPlex
      • Point Depth and Height
    • pylith::topology::Field, PetscSection, and PetscVec
    • Integration
    • Projection
    • Pointwise functions (kernels)
• Rebuilding PETSc and PyLith
  • Rebuilding PETSc
  • Rebuilding PyLith
    • Overview
    • Updating your fork
    • Makefiles
    • Build Targets
• Testing
  • C++ unit tests
    • CppUnit macros
  • Method of Manufactured Solutions
    • Debugging residual errors
    • Debugging Jacobian errors
    • Example
  • Running C++ unit tests and MMS tests
    • Running C++ unit tests
  • Running MMS tests
    • Using the debugger
    • Using valgrind
  • Python unit tests
  • Full-scale tests
    • Command line arguments
    • Using the debugger
    • Using valgrind
    • Example
• Git Workflow
  • Overview
  • Git tasks
    • Setting up your fork
      • Set the upstream repository
    • Creating a new feature branch
    • Staging, Committing, and Pushing Changes
    • Keeping a feature branch in sync with branch main
    • Creating a pull request
    • Adding remotes for accessing other PyLith forks
  • Git Quick Reference
    • Break commit into multiple commits
    • Update from upstream
    • Rebase branch off main
    • Branches
      • Delete branches
      • Rename local branch
      • Show merged/unmerged branches
• Debugging
  • Debugging tools
    • VS Code integration
      • C++ unit test
      • MMS test
      • PyLith simulation
    • Debugger quick reference
    • Valgrind quick reference
  • Viewing fields
    • Viewing differences
  • Running tests in CI Docker containers
• Performance
  • Performance Tools
    • Overview
    • Evaluating Performance
      • Quick View
      • Graphical View
        • Viewing Performance with FlameGraph
  • Logging
• Contributing to PyLith
  • Documentation
    • Building the documentation
      • Prerequisites
      • Generating the documentation
    • MyST Quick reference
      • Style guide
      • Headings
      • Heading 2
        • Heading 3
          • Heading 4
      • Admonitions
      • Lists
        • Itemized lists
        • Definition lists
        • Field lists
      • Code blocks
      • Tables
      • Figures
      • Math
      • Citations
      • Table of contents
    • Contributing to the documentation
  • Workflow
  • Creating a new example
    • Checklist
  • Coding Style
    • General guidelines
    • Formatting source files
    • Error Checking
    • C/C++ style
      • Object Declaration Files
      • Object Implementation Files
    • Python style
  • Adding New Governing Equations and/or Bulk Rheologies
    • Overview
    • Python
    • C++
• PyLith design
  • MMS Test Redesign: Approach C — Detailed Design Specification
    • 1. Overview
      • 1.1 Goals
      • 1.2 Constraints
      • 1.3 Assumptions
    • 2. Class Hierarchy
    • 3. MMSTestCase — The Shared Base Class
      • 3.1 Responsibilities
      • 3.2 Header: tests/src/MMSTestCase.hh
      • 3.3 Implementation: tests/src/MMSTestCase.cc
        • Constructor
        • Destructor
        • checkEnabled
        • _initialize — The Hook Sequence
        • _readMesh
        • _setupFaultTopology (default no-op)
        • _nondimensionalize
        • _setupFaultFields (default no-op)
        • _setupProblem
        • _setExactSolution
        • _registerExactSolution (default)
        • _registerExactSolutionFault (default no-op)
    • 4. Equation Mixins
      • 4.1 ElasticitySetup
      • 4.2 IncompressibleElasticitySetup
      • 4.3 PoroelasticitySetup
      • 4.4 Future Equation Mixins
    • 5. Equation Mixin Implementation Details
      • 5.1 Material Creation Pattern
      • 5.2 Solution Subfield Registration Pattern
    • 6. FaultKinSetup Mixin
      • 6.1 Responsibilities
      • 6.2 Header: tests/src/FaultKinSetup.hh
      • 6.3 Implementation: tests/src/FaultKinSetup.cc
        • _registerFaultExactSolution
      • 6.4 Multiple Kinematic Sources (Future Extension)
    • 7. Concrete Test Case Pattern
      • 7.1 Structure
      • 7.2 Example: No-Fault Linear Elasticity (UniformStrain2D)
      • 7.3 Example: Fault Test Case (TwoBlocksStatic)
      • 7.4 Example: Poroelasticity (PressureGradient)
      • 7.5 Dynamic Formulation Example (PlanePWave2D)
    • 8. TestCases.cc and the MMS_TEST_CASE Macro
      • 8.1 Macro Definition
      • 8.2 Usage in TestCases.cc
    • 9. File Layout
      • 9.1 New Shared Infrastructure (tests/src/)
      • 9.2 Per-Directory Structure (e.g., linearelasticity/nofaults-2d/)
      • 9.3 Updated Makefile.am Pattern
    • 10. Initialization Sequence Diagram
    • 11. Design Decisions and Rationale
      • 11.1 Why Multiple Inheritance Instead of Composition
      • 11.2 Why Virtual Hooks Instead of Template Methods (CRTP)
      • 11.3 Why Test Cases Return by Value
      • 11.4 Why _enabledChecks Bitmask Instead of Separate Booleans
      • 11.5 Diamond Inheritance Prevention
      • 11.6 Ownership Model
    • 12. Migration Plan
      • 12.1 Phase 1: Create Shared Infrastructure
      • 12.2 Phase 2: Migrate Linear Elasticity No-Fault 2D
      • 12.3 Phase 3: Migrate Remaining Directories
      • 12.4 Phase 4: Add New Equation Mixins
      • 12.5 Validation
    • 13. API Reference Summary
      • 13.1 Key External APIs Used
      • 13.2 PETSc Function Signatures
      • 13.3 Discretization Struct Fields
    • 14. Checklist for Adding a New Equation Type
    • 15. Checklist for Adding a New Test Case to an Existing Equation
    • 16. Potential Issues and Mitigations
      • 16.1 Copy/Move Semantics of Test Objects
      • 16.2 Static Data in Analytical Functions
      • 16.3 Thread Safety
      • 16.4 Compile Time
    • 17. Complete Implementation Specification for MMSTestCase
      • Required includes for MMSTestCase.cc:
      • Methods that MUST remain virtual (overridable by concrete classes):
    • 18. Existing Test Cases to Migrate
      • 18.1 linearelasticity/nofaults-2d (6 test cases)
      • 18.2 linearelasticity/nofaults-3d (4 test cases)
      • 18.3 linearelasticity/faults-2d (5 test cases)
      • 18.4 incompressibleelasticity/nofaults-2d (4 test cases)
      • 18.5 poroelasticity/nofaults-2d (1 test case)
    • 19. Summary
• Integrated development environments
  • Visual Studio Code
    • Setting up VS Code
    • Starting VS Code
    • Extensions