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
  • Implementing a LinOp
  • Cloning
  • 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: overview
  • The format zoo
  • Trade-off axes
  • The conversion graph
  • Validation and device views
  • Selection guidance
  • Per-format pages
• 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

• Solver taxonomy
  • The three families
  • The Krylov family
  • Direct solvers
  • Multigrid
  • The factory pattern recap
  • Selection guidance
• Preconditioner taxonomy
  • The role of a preconditioner
  • Left, right, and split preconditioning
  • The catalog
  • Plugging a preconditioner into a Krylov solver
  • Selection guidance
  • Per-preconditioner pages
• 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
  • Adaptive-precision block Jacobi
  • 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
  • Block-structured view across ranks
  • Multiplying distributed matrices
  • Transposing
  • Writing the local entries

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

• Extension taxonomy
  • What lives in extensions/
  • Using the extensions
  • Per-extension pages