How hel-astro-lab/runko works
Project Type and Purpose
• Runko is a multi-physics simulation framework for astrophysical plasmas. It is designed to run on both CPUs and GPUs and is written in modern C++ with Python bindings. It supports several physics modules (Particle-In-Cell (PIC), FDTD electromagnetics (EMF), Force-Free Electrodynamics (FFE), Vlasov (VLV), and Radiation/QED) and integrates with the grid infrastructure library (corgi) for parallel domain decomposition and high-performance simulations.
• The README further highlights the separation between low-level performance-critical kernels (C++) and high-level drivers/prototyping (Python). It also emphasizes simulation aspects such as parallelism, load-balancing, and the ability to test on a laptop and scale to supercomputer platforms.
Analyzing the File Structure
• The top-level file tree contains directories like core, bindings, projects, prototypes, docs, external, tests, and tools.
• The core directory is subdivided into submodules for the different physics components (emf, ffe, pic, qed, vlv), each implemented in C++.
• The bindings directory provides the C++/Python interface code; this is key to the hybrid design.
• The projects/ directory holds example simulation setups (which might be used to illustrate usage and configuration).
• The prototypes directory contains experimental implementations and interface prototypes – useful for understanding extensibility and modularity.
• External libraries (e.g., corgi, ezh5, cppitertools) and build/configuration files (CMakeLists.txt, Travis, clang-format) also appear, showing that compilation, testing, and documentation are well supported.
• The presence of documentation, tests, and tools directories further suggests that the codebase is designed for high performance, modularity, and ease of scaling/testing.
Main Components
a. Core Computing Kernels:
• Segment these into the physics modules:
• EMF module (FDTD propagators, filters, boundaries)
• PIC module (particle pushers, depositers, interpolators)
• FFE module (currents, tile management)
• VLV module (Vlasov-specific solvers, AMR, momentum and spatial solvers)
• QED module (radiation interaction, pairing, photon management)
• Common infrastructure such as the “tile” abstractions and grid tasking.
b. Python Bindings Layer:
• Binding files (bindings/, pytools/) that ‘expose’ the C++ kernels to Python. This is the interface layer where high-level simulation scripts invoke the performance-critical routines.
c. External Dependencies and Infrastructure:
• Use of third-party libraries like corgi for domain decomposition and parallelization.
• External libraries listed in the file tree (e.g., external/corgi, external/fmt) to show how lower-level tasks and performance abstractions are augmented by external packages.
d. Projects and Prototypes:
• Projects directory as an example “simulation driver” area, where users design specific simulation setups to utilize the kernel and interface layers.
• A component for prototypes (including coupling, dispersion-solver, high-order methods, etc.) to signify experimental and extensible parts of the framework.
e. Supporting Infrastructure:
• Build, configuration, and testing components: CMake, Travis, documentation (docs), tests.
• Tools (for code quality, performance profiling, and debugging) should be included as auxiliary services.
Relationships and Interactions
• Simulation projects (Python scripts) call into the Python Bindings layer.
• Bindings invoke the corresponding high-performance C++ kernels in the core.
• C++ kernels use the tile-decomposition and load-balancing provided by the external grid library (corgi).
• Data input/output and snapshot functionality (contained under the io/ directory) acts as an interface to external storage facilities.
• Testing and prototypes loop back into both the Python interfaces and the core functionalities to validate design choices.
Important Architectural Patterns and Design Principles
• Modular Design: Each physics domain is separated in its own module within core (emf, pic, ffe, vlv, qed).
• Hybrid Layering: The separation between performance-critical C++ code (kernels) and high-level Python control (rapid prototyping and simulation setup).
• Domain Decomposition: Use of the corgi library for parallelism via grid tiling and load-balancing.
• Extensibility: Clear boundaries and interfaces between modules support independent development and coupling of different physical models.