Chhavi: A Python tool for converting RAMSES outputs to VTKHDF

Overview

Chhavi is a Python tool for converting RAMSES simulation outputs into VTKHDF format for visualization and analysis in ParaView and related tools.

It provides both a command-line interface (CLI) and a Python API.

The package also includes test coverage, example scripts, profile analysis suite for Osyris vs VTKHDF validation and clear documentation, ensuring it is reproducible and accessible for scientific use.

---

Quick Start

pip install chhavi
chhavi --help

---

Features

• Convert RAMSES AMR outputs into VTKHDF OverlappingAMR files
• Uses Osyris for data analysis and extraction
• Support for both scalar fields (density, pressure, grav_potential) and vector fields (velocity, magnetic_field, grav_acceleration)
• Dry-run mode to preview what would be written without creating files
• CLI and Python API for flexible use
• Parallel conversion support with configurable number of workers (--nproc)
• Customizable output directory through --output-dir option
• Profile Analysis - Osyris vs VTKHDF validation (CCC > 0.99)
• Fully tested with pytest

---

Installation

Install from PyPI (recommended)

pip install chhavi

Install from source (development)

git clone https://github.com/HemangiVarkal/Chhavi.git
cd Chhavi
pip install .

---

Usage

Command-Line Interface (CLI)

Example:

chhavi --base-dir ramses_outputs/ \
       --folder-name sedov_3d/ -n 1 \
       --output-prefix sedov_test \
       --fields density,velocity,pressure \
       --dry-run \
       --output-dir ./vtk_outputs \
       --nproc 1

Alternatively:

python -m chhavi.cli --base-dir ramses_outputs/ \
       --folder-name sedov_3d/ -n 1 \
       --output-prefix sedov_test \
       --fields density,velocity,pressure \ 
       --dry-run \
       --output-dir ./vtk_outputs \
       --nproc 1

Key options:

• --base-dir → Parent folder
• --folder-name → Folder containing RAMSES outputs
• -n → Snapshot number(s)
• --output-prefix → Prefix for generated .vtkhdf files
• --fields → Comma-separated list of fields (scalars/vectors)
• --dry-run → Run without writing files
• --output-dir → Directory to store .vtkhdf output files. Defaults to --base-dir/--folder-name.
• --nproc → Number of CPU cores to use for parallel conversion (default: 1). Falls back to serial if unavailable.

Python API

from chhavi.converter import ChhaviConverter

    converter = ChhaviConverter(
    input_folder="ramses_outputs/sedov_3d",
    output_prefix="sedov_test",
    fields=["density", "velocity"],
    dry_run=True,
    output_directory="./vtk_outputs"
)

converter.process_output(1)

---

Profile Analysis Workflow

Profile analysis tools are provided in profiles/ directory:

cd profiles/
python compute_osyris_profile.py --base-dir ..\ramses_outputs --folder-name sedov_3d --numbers 4
python compute_vtk_profile.py --base-dir ..\vtk_outputs --folder-name sedov_3d --numbers 4
python analyzing_profiles.py -n 4

This suite:

1. Generates radial density profiles from Osyris (RAMSES native) and VTKHDF outputs, saved as CSV files in profile_outputs/ folder: osyris_profile_00002.csv [radius, mean, std, min, max]
   vtk_profile_00002.csv [radius, mean, std, min, max]
2. Computes Concordance Correlation Coefficient (CCC) validation metric between CSV profiles (CCC > 0.99 confirms equivalence)
3. Creates publication-quality comparison plots profile_comparison_00002.png with error bands
4. test_profile_analysis.py in tests/ validates snapshot output_00004 with 7 automated tests

---

Example Script

An example is provided in examples/example_usage.py:

python -m examples.example_usage

This script:

1. Lists available fields in snapshots
2. Prints dataset info
3. Performs a dry-run conversion
4. Displays scalar/vector fields to be written

You can specify an output directory in the example usage by setting OUTPUT_DIR='your/path'.

---

Output File Structure

<output-prefix>_00001.vtkhdf
<output-prefix>_00002.vtkhdf
...

---

Tests

Run the test suite with:

pytest tests/

---

Repository Structure

Chhavi/
├── chhavi/              # Core Python package
│ ├── __init__.py
│ ├── cli.py
│ ├── converter.py
│ └── parallel.py
│
├── examples/            # Example usage scripts
│ └── example_usage.py
│
├── profiles/            #  Profile analysis suite
│ ├── compute_osyris_profile.py
│ ├── compute_vtk_profile.py
│ ├── analyzing_profiles.py
│
├── ramses_outputs/      # Sample real RAMSES outputs
│ └── sedov_3d/
│ ├── output_00001/
│ ├── output_00002/
│ ├── output_00003/
│ ├── output_00004/
│ └── output_00005/
│
├── tests/               # Unit tests
│ ├── __init__.py
│ ├── test_cli.py
│ ├── test_converter.py
│ ├── test_import.py
│ ├── test_parallel.py
│ ├── test_parser.py
│ └── test_profile_analysis.py
│
├── LICENSE
├── pyproject.toml
├── README.md
├── requirements-dev.txt
├── requirements.txt
└── .gitignore

---

Notes & Best Practices

• Default fields if --fields is not specified: density, pressure, velocity
• Profile validation confirms Osyris and VTKHDF produce equivalent results
• Verbose mode --verbose provides step-by-step information, including the number of cells retained per level.
• Parallel execution automatically uses specified CPU cores (--nproc); falls back to serial execution if needed
• Output directory is auto-created if it does not exist — no manual setup required
• If no cells survive filtering or fields are missing, the output file is skipped, with warnings logged

---

License

This project is licensed under the terms of the MIT License.
See the LICENSE file for details.

---

Authors

• Hemangi C. Varkal — Developer
• Shubhankar R. Gharote — Space Applications Centre (SAC), ISRO
• Dr. Munn Vinayak Shukla — Space Applications Centre (SAC), ISRO
• Dr. Mehul Pandya — Space Applications Centre (SAC), ISRO

---

Acknowledgements

• This work was carried out at the Space Applications Centre (SAC), Indian Space Research Organisation (ISRO), Ahmedabad, India.
• The author expresses sincere appreciation to Dr. Rashmi Sharma (DD, EPSA) for continuous encouragement and institutional support.
• Special thanks are due to Dr. Mehul Pandya (Group Director, SESG/EPSA), Dr. Munn Vinayak Shukla (Head, SSD/SESG/EPSA) and Shubhankar R. Gharote (Scientist, SSD/SESG/EPSA) for their invaluable guidance, technical insights, and collaboration throughout the development of this work.
• Computations were performed using the SAGAR High Performance Computing (HPC) Facility of SAC.
• Implementation follows ParaView VTKHDF OverlappingAMR conventions.

---

Citation

If you use Chhavi in your work, please cite it as:

Varkal, H. (2026). Chhavi: A Python tool for converting RAMSES outputs to VTKHDF.
GitHub repository: https://github.com/HemangiVarkal/Chhavi