Edit README.md

# SNR Hadronic Synthesis

`SNR Hadronic Synthesis` is a Python pipeline to synthesise **hadronic gamma-ray emission** from 3D (M)HD simulations of supernova remnants (SNRs).  

The code is **generic** and not hard-coded to any particular object: it takes PLUTO-like simulation outputs and builds gamma-ray maps and SEDs in a fully reproducible way.

The code is **generic**, fully modular, and not tied to any specific remnant or simulation. It processes PLUTO-like outputs in `.flt` format to produce gamma-ray maps and global spectral energy distributions (SEDs) in a reproducible framework.

---

## Project and context

This software has been developed by **Anna Marretta** within the research activities of the **PNRR–CATMAD** project (CUP: C53C22000350006), carried out at the **University of Palermo (UNIPA)** and the **INAF – Palermo Astronomical Observatory (OAPA)**.

The **CATMAD** project was supported by **Fondazione ICSC, Spoke 3 — Astrophysics and Cosmos Observations**, within the **National Recovery and Resilience Plan (PNRR)**, Project ID **CN_00000013** *“Italian Research Center on High-Performance Computing, Big Data and Quantum Computing”*, funded by **MUR Mission 4, Component 2, Investment 1.4 (M4C2-19)**, **Next Generation EU (NGEU)**.

The CATMAD project is led by **Prof. Marco Miceli** and involves a research group including  

This software has been developed by **Anna Marretta** within the research activities of the **PNRR–CATMAD** project (CUP: C53C22000350006), carried out at the **University of Palermo (UNIPA)** and the **INAF — Palermo Astronomical Observatory (OAPA)**.

The CATMAD project is led by **Prof. Marco Miceli** and involves the research team:  

**Sabina Ustamujic, Antonio Tutone, Fabio Reale, Salvatore Orlando,  

Costanza Argiroffi, Paolo Pagano, Marco Barbera, and Oleh Petruk.**

Although developed in the CATMAD framework, this repository represents an **independent and original software effort** by the author. It provides a **modular and general pipeline** for synthesizing hadronic gamma-ray emission from 3D (M)HD simulations of supernova remnants.

Although developed in the CATMAD framework, this repository represents an **independent and original research software product** authored by the developer. It implements a general pipeline for modelling cosmic-ray proton distributions and their resulting adronic gamma-ray emission from 3D (M)HD SNR simulations.

---

## Physical description (what the code does)

The pipeline assumes a SNR expanding in an intercloud medium with uniform density \(n_0\), interacting with different interstellar clouds.

## Core physical pipeline

You provide 3D PLUTO-like outputs (`rho`, `tr*`, etc.) in `.flt` format, and the physical parameters of the simulation (explosion energy, ambient density, distance to the source, …).  

The code then:

Given simulation outputs (`rho`, `tr1–tr4`, etc.) and key physical parameters (e.g. explosion energy, ambient density, source distance, remnant age), the pipeline performs:

1. Builds a geometrical/physical **mask** around the shock.

2. Computes the **distance** from the explosion centre for each cell (`r_pc.flt`).

3. Computes a **Sedov-like acceleration time** (`t_s_mask.flt`) and a **Bell-like amplified magnetic field** (`B_sat.flt`).

4. Derives the maximum proton energy **E_max** using one of two models:

   - `first-model`: piecewise-in-time + particle escape  

     **Reference:** Vink (2020), *Physics Reports*.

   - `second-model`: global \( t^{-\delta} \) scaling  

     **Reference:** Celli et al. (2019), *MNRAS, 490, 4317*.

5. Builds **density 3D distributions** for shocked material (`rho_masked`) and for gamma-emitting material after cooling (`rho_cooling`).

6. Computes a **global scaling factor** for the proton spectra so that the total proton energy \(W_p\) matches a target value.

7. Builds a voxel-wise **amplitude map** \( A(\mathbf{x}) \propto d/d_{\max} \).

8. Computes the **gamma-ray map** and the **total SED** using Naima’s hadronic `PionDecay` model.

9. Provides utilities to **plot the gamma-ray map** (rotation + integration) and the **SED**.

1. Construction of a **user-defined shock mask**.

2. Computation of cell-wise **radial distance** from the explosion centre (`r_pc.flt`).

3. Derivation of a **Sedov-like acceleration time map** (`t_s_mask.flt`).

4. Computation of a **Bell-type amplified magnetic field map** (`B_sat.flt`), and extraction of the characteristic **T_threshold** when \(B < B_{\text{threshold}}\).

5. Estimate of the maximum proton energy **E_max** via:

   - `first-model` — piecewise acceleration + particle escape (Vink 2020).

   - `second-model` — global \(t^{-\delta}\) scaling (Celli et al. 2019).

6. Generation of shocked (`rho_masked`) and **cooling-filtered density cubes** (`rho_cooling`) for emission synthesis.

7. **Global scaling factor** computation for proton spectra to match a target proton energy \(W_p\).

8. Construction of a voxel-wise **proton spectral amplitude map** \(A(\mathbf{x}) \propto d/d_{\max}\).

9. Synthesis of the **3D gamma-ray flux cube** and **total SED** using Naima (`PionDecay` model).

10. Optional visualisation utilities for the 2D gamma-ray map (with user-defined rotations and axis integration) and SED plotting.

---

## Code structure and CLI

All functionality is exposed through a **Typer-based CLI** via `main.py`.

## Installation

There are two main usage modes:

### Requirements

- Python **≥ 3.10**

### 1. Interactive wizard (recommended)

Install dependencies via:

```bash

python main.py wizard

pip install numpy matplotlib astropy typer[all] naima scipy