chhavi 1.0.0__tar.gz

chhavi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemangi C. Varkal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chhavi-1.0.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: chhavi
+Version: 1.0.0
+Summary: RAMSES to VTKHDF conversion tool for AMR datasets
+Author-email: Hemangi Varkal <hemangivarkal1612@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Hemangi C. Varkal
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: h5py>=3.6
+Requires-Dist: osyris>=1.6
+Requires-Dist: vtk>=9.2
+Requires-Dist: tqdm>=4.60
+Dynamic: license-file
+
+# Chhavi: A Python tool for converting RAMSES outputs to VTKHDF
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)  
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-brightgreen)]()  
+[![Build Status](https://img.shields.io/badge/tests-passing-brightgreen)]()
+
+
+## Overview
+
+**Chhavi** is a Python package that converts **[RAMSES](https://ramses-organisation.readthedocs.io/en/latest/)** simulation outputs into **[VTKHDF](https://vtk.org/documentation/)** **OverlappingAMR** format.
+
+It provides both a **command-line interface (CLI)** and a **Python API**, making it easy to visualize and analyze data in **[ParaView](https://docs.paraview.org/en/latest/)** and other compatible tools.
+
+The package also includes test coverage, example scripts, profile analysis suite for **[Osyris](https://osyris.readthedocs.io/en/stable/)** vs **VTKHDF** validation and clear documentation, ensuring it is reproducible and accessible for scientific use.
+
+---
+
+## 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
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/HemangiVarkal/Chhavi.git
+cd Chhavi
+pip install -r requirements.txt
+```
+
+---
+
+## Usage
+
+### Command-Line Interface (CLI)
+
+Example:
+
+```bash
+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
+
+```python
+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:
+```python
+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] <br>
+    `vtk_profile_00002.csv` [radius, mean, std, min, max]
+2. Computes **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`:
+
+```bash
+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
+
+```lua
+<output-prefix>_00001.vtkhdf
+<output-prefix>_00002.vtkhdf
+...
+```
+
+---
+
+## Tests
+
+Run the test suite with:
+
+```bash
+pytest tests/
+```
+
+---
+
+## Repository Structure
+
+```
+Chhavi/
+├── chhavi/              # Core Python package
+│ ├── __init__.py
+│ ├── cli.py
+│ ├── converter.py
+│ └── parallel.py
+│
+├── tests/               # Unit tests
+│ ├── __init__.py
+│ ├── test_cli.py
+│ ├── test_converter.py
+│ ├── test_import.py
+│ ├── test_parallel.py
+│ ├── test_parser.py
+│ └── test_profile_analysis.py
+│
+├── examples/            # Example usage scripts
+│ └── example_usage.py
+│
+├── profiles/            #  Profile analysis suite
+│ ├── compute_osyris_profile.py
+│ ├── compute_vtk_profile.py
+│ ├── analyzing_profiles.py
+│
+├── papers/              # JOSS submission papers
+│ ├── paper.md
+│ └── paper.bib
+│
+├── ramses_outputs/      # Sample real RAMSES outputs
+│ └── sedov_3d/
+│ ├── output_00001/
+│ ├── output_00002/
+│ ├── output_00003/
+│ ├── output_00004/
+│ └── output_00005/
+│
+├── LICENSE
+├── README.md
+├── 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](LICENSE) file for details.
+
+---
+
+## Authors
+
+- **[Hemangi C. Varkal](https://github.com/HemangiVarkal)** — 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](https://github.com/HemangiVarkal/Chhavi)

chhavi-1.0.0/chhavi/__init__.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+
+"""
+
+Chhavi: RAMSES → VTKHDF (Overlapping AMR) Converter
+===================================================
+
+──────────────────────────────────────────────────────────────────────────────
+Description
+──────────────────────────────────────────────────────────────────────────────
+Chhavi converts RAMSES simulation outputs into the VTKHDF format that
+ParaView and other VTK-based visualization tools can read.
+
+──────────────────────────────────────────────────────────────────────────────
+WHY THIS EXISTS
+──────────────────────────────────────────────────────────────────────────────
+- RAMSES uses an Adaptive Mesh Refinement (AMR) grid suitable for HPC, but not
+  directly compatible with most visualization pipelines.
+- VTKHDF’s OverlappingAMR format stores data by refinement level, with
+  cell-centered fields and AMR indexing metadata, ideal for ParaView.
+
+"""
+
+from .converter import (
+    ChhaviConverter,
+    parse_output_numbers,
+    parse_norm_range,
+    parse_fields_arg,
+    list_fields_for_snapshot,
+)
+
+from .parallel import (
+    process_single_output,
+    run_parallel_conversion,
+)
+
+__version__ = "1.0.0"

chhavi-1.0.0/chhavi/cli.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+──────────────────────────────────────────────────────────────────────────────
+CLI QUICK START (copy–paste, then tweak)
+──────────────────────────────────────────────────────────────────────────────
+Example run (filters a subvolume, includes extra fields):
+
+    python3 cli.py \
+        --base-dir ./simulations \
+        --folder-name output_dir \
+        --numbers 1,3,5-7 \
+        --output-prefix overlapping_amr \
+        --level-start 2 --level-end 5 \
+        --x-range 0.0:1.0 --y-range 0.0:1.0 --z-range 0.0:1.0 \
+        --fields density,pressure \
+        --verbose \
+        --nproc 4 \
+        --output-dir ./vtk_outputs
+
+Exploration mode :
+
+    # Lists fields Osyris sees in the mesh (no conversion happens)
+    python3 cli.py --base-dir ./simulations --folder-name output_dir \
+        -n 5 --list-fields
+
+    # Dry-run: show counts after filters, but don’t write .vtkhdf
+    python3 cli.py --base-dir ./simulations --folder-name output_dir \
+        -n 5 --level-start 1 --dry-run --verbose
+
+Required args:
+
+    --base-dir         Path to your RAMSES run root directory.
+    --folder-name      Subfolder inside base-dir containing outputs.
+    -n / --numbers     Output numbers to process. Formats:
+                       "7" or "3,5,9" or "10-15"
+
+Optional args:
+
+    --output-prefix / -o   Prefix for output files (default: overlapping_amr)
+    --level-start / --level-end     AMR level filter (inclusive)
+    --x-range / --y-range / --z-range   Normalized ranges [0,1] over box length
+    --fields           Physical fields to be included (default: density, pressure, velocity)
+    --verbose          step-by-step narration
+    --list-fields      Only list available mesh fields and exit
+    --dry-run          Run everything except the actual write step
+    --nproc            Number of CPU cores to use for parallel conversion (default: 1)
+    --output-dir       Directory to store .vtkhdf output files (default: input directory)
+──────────────────────────────────────────────────────────────────────────────
+Tip on “normalized ranges”:
+    RAMSES coordinates are in code/physical units. We divide by the simulation
+    box length (from metadata) so [0,1] always spans the full domain, regardless
+    of units.
+──────────────────────────────────────────────────────────────────────────────
+"""
+
+import os
+import argparse
+import logging
+
+from .converter import (
+    parse_output_numbers,
+    parse_norm_range,
+    parse_fields_arg,
+    list_fields_for_snapshot,
+)
+from .parallel import run_parallel_conversion, setup_logging
+
+logger = logging.getLogger("chhavi")
+
+
+def main() -> None:
+    """
+    Parse CLI args and run the conversion pipeline.
+    """
+
+    parser = argparse.ArgumentParser(
+        description="VTKHDF AMR Generator from RAMSES Data (refactored)"
+    )
+
+    # Required inputs
+    parser.add_argument(
+        "--base-dir",
+        type=str,
+        required=True,
+        help="Base directory containing simulation folders (REQUIRED)",
+    )
+    parser.add_argument(
+        "--folder-name",
+        type=str,
+        required=True,
+        help="Folder inside base_dir to process (REQUIRED)",
+    )
+    parser.add_argument(
+        "-n",
+        "--numbers",
+        type=parse_output_numbers,
+        required=True,
+        help="Output numbers like '1', '1,3,5' or '2-7' (REQUIRED)",
+    )
+
+    # Output and level selection
+    parser.add_argument(
+        "-o",
+        "--output-prefix",
+        dest="output_prefix",
+        default="overlapping_amr",
+        help="Output file prefix (default: overlapping_amr)",
+    )
+    parser.add_argument(
+        "--level-start",
+        type=int,
+        default=None,
+        help="Minimum AMR level to include (inclusive). Optional.",
+    )
+    parser.add_argument(
+        "--level-end",
+        type=int,
+        default=None,
+        help="Maximum AMR level to include (inclusive). Optional.",
+    )
+
+    # Normalized ranges (single arg per axis)
+    parser.add_argument(
+        "--x-range",
+        type=parse_norm_range,
+        default=None,
+        help="Normalized x range 'min:max' (e.g., 0.2:0.8, :0.7, 0.1:, :).",
+    )
+    parser.add_argument(
+        "--y-range", type=parse_norm_range, default=None, help="Normalized y range 'min:max'."
+    )
+    parser.add_argument(
+        "--z-range", type=parse_norm_range, default=None, help="Normalized z range 'min:max'."
+    )
+
+    # Field selection (replace per-field enable flags with a single argument)
+    parser.add_argument(
+        "--fields",
+        type=parse_fields_arg,
+        default=None,
+        help="Comma-separated list of fields to include (e.g. density,velocity,magnetic_field). If omitted, sensible defaults are used.",
+    )
+
+    parser.add_argument(
+        "--list-fields",
+        action="store_true",
+        help="List available fields in the first requested snapshot and exit.",
+    )
+
+    # Utility flags
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Print plan without writing files."
+    )
+    parser.add_argument("--verbose", action="store_true", help="Verbose logging.")
+    parser.add_argument(
+        "--nproc",
+        type=int,
+        default=None,
+        help="Number of CPU cores to use for parallel conversion (default: 1)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=str,
+        default=None,
+        help="Directory to store .vtkhdf output files (default: input directory)",
+    )
+
+    args = parser.parse_args()
+
+    # Configure logging early
+    setup_logging(args.verbose)
+
+    # Build absolute input folder path and validate
+    input_folder = os.path.join(os.path.abspath(args.base_dir), args.folder_name)
+
+    if not os.path.exists(input_folder):
+        logger.error("Input folder not found: %s", input_folder)
+        raise FileNotFoundError(f"Input folder not found: {input_folder}")
+
+    # Validate nproc argument (positive integer if provided)
+    if args.nproc is not None and args.nproc <= 0:
+        parser.error(f"Invalid --nproc value: {args.nproc}. Must be a positive integer.")
+
+    # Validate output directory existence or create it
+    output_dir = args.output_dir if args.output_dir is not None else input_folder
+    if not os.path.exists(output_dir):
+        try:
+            os.makedirs(output_dir, exist_ok=True)
+            logger.info("Created output directory: %s", output_dir)
+        except Exception as e:
+            parser.error(f"Failed to create output directory '{output_dir}': {e}")
+
+    # Check level ranges
+    if args.level_start is not None and args.level_end is not None:
+        if args.level_end < args.level_start:
+            parser.error(
+                f"Invalid level range: end ({args.level_end}) < start ({args.level_start})."
+            )
+
+    # Normalize default ranges: None -> (None,None)
+    def norm_default(r):
+        return (None, None) if r is None else r
+
+    x_range = norm_default(args.x_range)
+    y_range = norm_default(args.y_range)
+    z_range = norm_default(args.z_range)
+
+    # If user requested to list fields, inspect the first snapshot in args.numbers
+    if args.list_fields:
+        first_num = args.numbers[0]
+        logger.info("Listing fields for snapshot %s in folder '%s'...", first_num, input_folder)
+        fields = list_fields_for_snapshot(input_folder, first_num)
+
+        if fields:
+            print("Available fields (best-effort):")
+            for f in fields:
+                print(" -", f)
+        else:
+            print("No fields discovered (see logs for details).")
+        return
+
+    # Run conversion (fields argument may be None meaning use defaults+auto-detect)
+    try:
+        run_parallel_conversion(
+            output_numbers=args.numbers,
+            input_folder=input_folder,
+            output_prefix=args.output_prefix,
+            fields=args.fields,
+            level_start=args.level_start,
+            level_end=args.level_end,
+            x_range_norm=x_range,
+            y_range_norm=y_range,
+            z_range_norm=z_range,
+            dry_run=args.dry_run,
+            verbose=args.verbose,
+            nproc=args.nproc,
+            output_directory=output_dir,
+        )
+    except Exception as e:
+        logger.exception("FATAL: Unexpected error: %s", e)
+        raise
+
+
+if __name__ == "__main__":
+    main()