Chhavi: A Python Tool for Converting RAMSES Outputs to VTKHDF for High-Fidelity AMR Visualization

Abstract: RAMSES is an adaptive mesh refinement (AMR) astrophysical simulation code that generates high-resolution multiscale data. However, its native binary output format is not directly compatible with standard visualization tools, making efficient analysis challenging. We present Chhavi, an open-source Python tool that converts RAMSES outputs into the VTKHDF format for direct use in visualization platforms such as ParaView. The tool reconstructs the AMR hierarchy, preserves key physical fields including density, pressure and velocity, and organizes them into a structured representation suitable for multi-resolution visualization. The conversion is validated using the three-dimensional Sedov blast wave test case. Quantitative evaluation through radial profile comparison and Lin's concordance correlation coefficient demonstrates strong agreement between the original and converted datasets, confirming both physical and structural fidelity. Chhavi provides a scalable bridge between RAMSES simulation outputs and modern visualization workflows, supporting efficient and reproducible analysis in computational astrophysics.

• The paper presents a Python tool, Chhavi, that converts RAMSES simulation outputs to VTKHDF, preserving the AMR structure needed for high-fidelity visualization.
• It employs a modular pipeline with stages for data extraction, AMR hierarchy reconstruction, field mapping, and efficient parallel processing to maintain dataset integrity.
• Empirical validation using the Sedov blast wave test shows near-perfect overlap in physical parameters, ensuring reproducibility and minimal deviation between native and converted data.

Chhavi: Enabling High-Fidelity AMR Visualization from RAMSES Simulation Outputs

Motivation and Context

RAMSES is a widely-adopted AMR code for large-scale astrophysical simulations, but its native output format poses significant barriers to direct integration with contemporary visualization pipelines. Unlike more standardized data representations (e.g., VTK, HDF5-based formats), RAMSES outputs require customized pre-processing and domain-specific scripts to achieve compatibility with platforms such as ParaView. Existing Python-based analysis frameworks (yt, Osyris) facilitate in-memory analysis but do not provide an efficient, standardized, and reproducible pathway for preparing RAMSES datasets for visualization workflows.

The Chhavi tool specifically addresses this gap by enabling robust conversion from RAMSES outputs to the VTKHDF format, preserving both the AMR structure and key simulation fields required for high-fidelity, multi-resolution visualization.

Figure 1: Overview of the Chhavi pipeline, delineating the modular stages from RAMSES data extraction through AMR hierarchy reconstruction and field mapping to VTKHDF file generation for ParaView.

Methodology

Chhavi employs a modular pipeline with four discrete processing stages: data extraction, AMR hierarchy reconstruction, field mapping, and VTKHDF output generation. The initial phase extracts grid-based simulation data, including cell-level coordinates, refinement levels, and physical observables (density, pressure, velocity). The AMR hierarchy is explicitly reconstructed by associating each data point with the correct refinement level and enforcing the nested multilevel structure inherent to RAMSES outputs.

Field mapping does not perform interpolation or transformation, maintaining direct correspondence between source and target fields. In the final stage, the pipeline writes the output in the VTKHDF format, utilizing the hierarchical structure of HDF5 for both scalability and seamless integration with multiresolution-aware visualization platforms. This design ensures that the physical and topological features central to astrophysical simulations are preserved across the conversion process.

Implementation Details

Chhavi is implemented in Python and provides both command-line and programmatic interfaces. It supports batch processing of simulation snapshots and parallel conversion using user-configurable worker pools. The modular pipeline architecture allows users to customize field selection, output file naming, and parallelization strategy.

By minimizing disk I/O and maintaining data in memory across pipeline stages, Chhavi optimizes for large-scale AMR simulations. The tool is open-sourced, with distribution via both GitHub and PyPI, facilitating adoption and extensibility by the community.

Validation and Empirical Analysis

Chhavi’s fidelity is validated using the canonical three-dimensional Sedov blast wave, a stringent test for both hydrodynamic solvers and data post-processing pipelines. Visualizations of the resulting VTKHDF data in ParaView confirm the accurate preservation of the spherical shock front and retention of multilevel AMR features, enabling detailed structural exploration without visible artefacts or discontinuities between refinement levels.

Figure 2: Visualization in ParaView of the Sedov blast wave using Chhavi-converted VTKHDF data, clearly resolving the spherical shock and AMR structure.

Quantitative validation is provided by computing radial profiles of essential fields (e.g., density, pressure) and comparing these profiles between native RAMSES outputs and the VTKHDF representations. The profiles show near-perfect overlap, and Lin’s concordance correlation coefficient approaches unity ($\sim$1.0), demonstrating that Chhavi maintains both physical and structural equivalence during conversion.

Figure 3: Radial profile comparison between original RAMSES and VTKHDF data for the Sedov test, demonstrating negligible deviation in key physical parameters.

Implications and Future Perspectives

By systematically bridging RAMSES output with VTKHDF, Chhavi enables the integration of advanced AMR simulation data into scientific visualization frameworks, removing friction for analyses involving complex, multiscale physical phenomena. The tool’s modular, extensible design positions it as an adaptable solution for the broader computational astrophysics community, with clear opportunities for extension to more complex simulation datasets, additional physical fields, and more nuanced AMR topologies.

The strong quantitative and qualitative agreement between native and converted datasets establishes Chhavi as a reliable, reproducible element within scientific workflows. As high-resolution AMR simulations become more prevalent—and memory and GPU resource challenges escalate—further optimization of Chhavi for large-scale deployment (e.g., more aggressive parallelization, memory-mapped workflows) will likely be critical.

Additionally, embedding more extensive benchmarking, integrating support for advanced physical diagnostics, and expanding compatibility to other astrophysical codes represent promising directions for future development.

Conclusion

Chhavi introduces a robust, scalable, and validated methodology for converting RAMSES simulation outputs to the VTKHDF format, explicitly preserving AMR structure and physical field fidelity. The tool enables direct, high-fidelity visualization using platforms like ParaView, streamlining the integration between simulation and analysis. This capability strengthens reproducible research practices, supports rigorous validation, and enhances collaborative workflows in computational astrophysics.