Metadata-Version: 2.4
Name: m-eclipses
Version: 0.3.1
Summary: MSSL Emission Calculation and Line Intensity Prediction for SOLAR-C EUVST-SW
Home-page: https://github.com/jamesmckevitt/solc_euvst_sw_response
Author: James McKevitt
Author-email: James McKevitt <jm2@mssl.ucl.ac.uk>
License: Contact for permission
Project-URL: Homepage, https://github.com/jamesmckevitt/solc_euvst_sw_response
Project-URL: Repository, https://github.com/jamesmckevitt/solc_euvst_sw_response
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: astropy
Requires-Dist: ndcube
Requires-Dist: specutils
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: joblib
Requires-Dist: tqdm
Requires-Dist: dill
Requires-Dist: pyyaml
Requires-Dist: reproject
Requires-Dist: sunpy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# M-ECLIPSES: MSSL Emission Calculation and Line Intensity Prediction for SOLAR-C EUVST-SW

The M-ECLIPSES code (MSSL Emission Calculation and Line Intensity Prediction for SOLAR-C EUVST-SW) is used to forward model the performance of the ESA/MSSL short wavelength camera, part of the EUV spectrograph EUVST, on SOLAR-C.

Contact: James McKevitt (jm2@mssl.ucl.ac.uk). License: Contact for permission to use.

The instrument response generated by this code will be updated during instrument development, testing, and commissioning.

## Installation

### From PyPI (recommended)

```bash
pip install m-eclipses
```

### From source

```bash
git clone https://github.com/jamesmckevitt/solc_euvst_sw_response.git
cd solc_euvst_sw_response
pip install -e .
```

## Usage Instructions

### Command Line Interface

After installation, you can run M-ECLIPSES from the command line:

```bash
# Show logo and basic usage
m-eclipses

# Run instrument response simulation
m-eclipses --config ./run/input/config.yaml

# Alternative short command
meclipses --config ./run/input/config.yaml
```

### Python API

You can also use M-ECLIPSES as a Python library:

```python
import euvst_response
from euvst_response import AluminiumFilter, Detector_SWC, Telescope_EUVST
```

### Analysis Tutorial

For analyzing simulation results, see the included Jupyter notebook `analysis_tutorial.ipynb` which demonstrates how to:

- Load simulation results
- Explore parameter combinations
- Analyze fit statistics and compute velocity/line width errors
- Create SunPy maps for visualization

The analysis functions are now available directly from the package:

```python
from euvst_response import (
    load_instrument_response_results,
    get_results_for_combination,
    analyse_fit_statistics,
    create_sunpy_maps_from_combo,
    summary_table
)
```

### 1. Generate contribution functions for the desired emission lines

Edit `make_gofnt.pro` to specify the desired emission lines and the location of the CHIANTI files. You can use CHIANTI to identify the required lines.

Run the following command:
```bash
idl -e "make_goft"
```

### 2. Run the line synthesis

Run the line synthesis using:
```bash
python synthesise_spectra.py
```

This step can require a lot of memory at full resolution. A fully synthesised atmosphere using the Cheung et al. (2018) atmosphere (doi:10.1038/s41550-018-0629-3) for the Fe XII 195.119 and 195.179 lines, including 5 background lines from each side, can be downloaded here: https://liveuclac-my.sharepoint.com/:f:/g/personal/ucasjem_ucl_ac_uk/Es-ts6rwXIlInAweGI7hmdMB5BoGqv9uSpIXOvMkzhS3cw?e=54si7R

### 3. Simulate the instrument response

#### Configuration File

M-ECLIPSES uses YAML configuration files to specify simulation parameters. You can specify single values or lists of values for parameter sweeps.

Here's a complete example configuration file:

```yaml
# Instrument selection
instrument: SWC  # Options: SWC (EUVST Short Wavelength) or EIS (Hinode/EIS)

# Point Spread Function
psf: False  # Enable PSF convolution (currently only planned for SWC)
# Or test with and without PSF:
# psf: [True, False]  # Run simulations both with and without PSF

# Exposure times - can be single value or list
expos: [0.5 s, 1 s, 2 s, 5 s, 10 s, 20 s, 40 s, 80 s]

# Monte Carlo simulation parameters
n_iter: 25      # Number of Monte Carlo iterations (more = better statistics)
ncpu: -1        # Number of CPU cores (-1 = use all available)

# Parameter sweeps - you can specify single values or lists for any parameter
# The simulation will run all combinations of parameters

# Slit width - affects spatial resolution
slit_width: 0.2 arcsec  # Narrowest slit on EUVST
# Or sweep multiple values:
# slit_width: [0.1 arcsec, 0.2 arcsec, 0.5 arcsec]

# Filter parameters (SWC only)
# Thickness of aluminum oxide layer on entrance filter
oxide_thickness: 95 angstrom  # Default
# Or sweep multiple values:
# oxide_thickness: [50 angstrom, 95 angstrom, 150 angstrom]

# Carbon contamination thickness on filter
c_thickness: 0 angstrom  # Start with no contamination
# Or model contamination buildup:
# c_thickness: [0 angstrom, 25 angstrom, 50 angstrom, 100 angstrom]

# Aluminum filter thickness
aluminium_thickness: 1485 angstrom  # Default thickness
# Or test different thicknesses:
# aluminium_thickness: [1000 angstrom, 1485 angstrom, 2000 angstrom]

# CCD temperature for dark current calculation
ccd_temperature: -60  # Temperature in Celsius (typical operating temperature)
# Or test different temperatures:
# ccd_temperature: [-60, -40, -20]  # Range of possible CCD temperatures

# Visible stray light level
vis_sl: 0 photon / (s * pixel)  # Ideal case (no stray light)
# Or model stray light:
# vis_sl: [0, 1e3, 1e4] photon / (s * pixel)
```

For guidence on recommended values, see McKevitt et al. (2025) (in prep.).

#### Running Simulations

Run the instrument response function using:
```bash
m-eclipses --config ./run/input/config.yaml
```

This can be looped in bash using:
```bash
for config in ./run/input/*.yaml; do
  m-eclipses --config "$config"
done
```

#### Output

Results are saved as pickle files in the `scratch/` directory with descriptive filenames based on the parameter ranges, and copied to `run/result/`. The output includes:
- Simulated detector signals (DN and photon counts)
- Fitted spectral line parameters (intensity, velocity, width)
- Statistical analysis of velocity precision vs. exposure time
- Ground truth comparisons

## Acknowledgements

The SOLAR-C/EUVST-SW instrument is an ESA-funded contribution to the JAXA-led SOLAR-C mission. The EUVST-LW (long wavelength) instrument is contributed by NASA. The M-ECLIPSES code is developed and maintained at Mullard Space Science Laboratory (UCL).
