Concepts

These pages explain Ginkgo’s design and architecture. Pick them when you want to understand — for “how do I do X”, see the How-To guides; for “walk me through a worked example”, see the Tutorials.

Foundation

• The Executor model
  • What is an executor?
  • Execution backends
  • The master/host hierarchy
  • Memory and synchronization
  • Allocators
  • Memory accessibility between executors
  • Selecting an executor at runtime
  • When to use the Reference executor
  • Per-executor pages
• LinOp and composition
  • Everything is a LinOp
  • The LinOp interface
  • Polymorphism via EnableLinOp (CRTP)
  • The factory pattern
  • Composing operators
  • The LinOp inheritance tree
  • Publications
• Memory ownership and gko::array
  • What gko::array stores
  • Construction
  • Accessing the data
  • Copy and move semantics
  • Cross-executor transfers
  • Const-correctness
  • Resizing and filling
  • What array does not do
  • Wrapping memory you do not own

Matrix data and formats

• Matrix data and assembly
  • matrix_data — the format-agnostic representation
  • Reading from Matrix Market
  • Writing to Matrix Market
  • Constructing matrices from matrix_data
  • device_matrix_data — assembly on the device
  • When to assemble on host vs device
• Matrix formats — an overview
  • The format zoo
  • Trade-off axes
  • The conversion graph
  • Selection guidance
  • Per-format pages
  • Publications
• Accessors
  • The range wrapper
  • Plain layouts
  • Precision-decoupled storage
  • Writing accessor-generic kernels
  • When to reach for accessors

Reordering and permutations

• Reordering and permutations
  • What a reordering produces
  • Permutation modes
  • The available algorithms
  • Why reorder before a direct solver
  • When to reorder for iterative solvers
  • Per-algorithm pages

Solvers, preconditioners, criteria

• Solvers — taxonomy
  • The three families
  • The Krylov family
  • Direct solvers
  • Multigrid
  • The factory pattern recap
  • Selection guidance
  • Per-solver pages
• Preconditioners — taxonomy
  • The role of a preconditioner
  • Left, right, and split preconditioning
  • The catalog
  • Jacobi
  • ILU and variants
  • IC (Incomplete Cholesky)
  • ISAI (Incomplete Sparse Approximate Inverse)
  • AMG (Algebraic Multigrid) as a preconditioner
  • Plugging a preconditioner into a Krylov solver
  • Selection guidance
  • Per-preconditioner pages
  • Publications
• Stopping criteria
  • The abstraction
  • Built-in criteria
  • Composition with Combined
  • Plugging into a solver
  • Inspecting why a solver stopped
  • Implicit vs explicit residual norms
• Logging and observability
  • The Logger interface
  • Built-in loggers
  • Convergence — the most common use case
  • Stream logger — tracing
  • ProfilerHook — integrating with external profilers
  • Performance logger
  • Batched: BatchConvergence
  • Custom loggers
  • Publications
• Configuration from JSON files
  • When to use file-based config
  • The pnode representation
  • The registry
  • The expected JSON format
  • End-to-end example
  • Limitations
• Mixed-precision design
  • Why mixed precision
  • AdaptivePrecisionJacobi
  • Iterative refinement with a low-precision inner solver
  • LinOp and precision conversion
  • When mixed precision pays off
  • When it doesn’t
  • Publications

Distributed

• Distributed computing — overview
  • When to go distributed
  • The distributed types
  • The host-first assembly pattern
  • The communicator
  • Block-structured view across ranks
  • Forward links
  • Distributed sub-pages

Batched

• Batched solvers — overview
  • When to use batched
  • The uniform-batch constraint
  • Storage layout
  • The fused-kernel design
  • What’s available
  • Construction example
  • What batched is not
  • Batched sub-pages
  • Publications

Extensions

• Extensions — taxonomy
  • What lives in extensions/
  • Build-time enablement
  • Per-extension pages