Metadata-Version: 2.4
Name: solarc-eclipse
Version: 0.7.0
Summary: ECLIPSE: Emission Calculation and Line Prediction for SOLAR-C EUVST
Home-page: https://github.com/jamesmckevitt/eclipse
Author: James McKevitt
Author-email: James McKevitt <jm2@mssl.ucl.ac.uk>
License: Contact for permission
Project-URL: Homepage, https://github.com/jamesmckevitt/eclipse
Project-URL: Repository, https://github.com/jamesmckevitt/eclipse
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.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.10
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[all]
Requires-Dist: dask
Requires-Dist: psutil
Requires-Dist: mendeleev
Requires-Dist: h5py
Requires-Dist: fiasco
Provides-Extra: mpi
Requires-Dist: mpi4py; extra == "mpi"
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

# ECLIPSE: Emission Calculation and Line Prediction for SOLAR-C EUVST

The ECLIPSE code (Emission Calculation and Line Prediction for SOLAR-C EUVST) is used to forward model the performance of the EUV spectrograph EUVST onboard the SOLAR-C spacecraft.

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.

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17543844.svg)](https://doi.org/10.5281/zenodo.17543844)

## Installation

### From PyPI (recommended)

```bash
pip install solarc-eclipse
```

### From source

```bash
pip install git+https://github.com/jamesmckevitt/eclipse.git
```

## Quick Start

### Command Line Interface

After installation, you can run ECLIPSE from the command line:

```bash
# Run synthesis script (convert 3D MHD data to synthetic spectra)
synthesise-spectra --data-dir ./data/atmosphere --lines Fe12_195.1190 --output-dir ./run/input

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

# Help can be accessed with
synthesise-spectra --help
eclipse --help
```

### Python API

You can also use ECLIPSE as a Python library:

```python
import astropy.units as u
import euvst_response
from euvst_response import AluminiumFilter, Detector_SWC, Telescope_EUVST

telescope = Telescope_EUVST()
detector = Detector_SWC()

print(f"Telescope collecting area: {telescope.collecting_area:.4f}")
print(f"Detector QE (EUV): {detector.qe_euv:.2f}")

# Calculate effective area at Fe XII 195.119 Angstrom
fe12_wl = 195.119 * u.AA
effective_area = telescope.collecting_area * telescope.throughput(fe12_wl) * detector.qe_euv

# Get breakdown of throughput by component
pm_eff = telescope.primary_mirror_efficiency(fe12_wl)
grating_eff = telescope.grating_efficiency(fe12_wl)
micro_eff = telescope.microroughness_efficiency(fe12_wl)
filter_eff = telescope.filter.total_throughput(fe12_wl)
```

### 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 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
)

# Load results
results = load_instrument_response_results("run/result/my_run.pkl")

# Print a summary table (auto-discovers all parameters and shows git commit)
summary_table(results)

# Retrieve a specific combination using full section.attribute names
combo = get_results_for_combination(results, **{"simulation.expos": 40*u.s, "simulation.psf": True})
```

## Detailed instructions

### 1. Run the line synthesis

The synthesis script converts 3D MHD simulation data into synthetic solar spectra. Contribution functions G(T, n_e) are computed on-the-fly using [fiasco](https://fiasco.readthedocs.io/) (a Python interface to the CHIANTI atomic database).

#### Basic Usage

```bash
# Example using all available command line options
synthesise-spectra \
  --data-dir ./data/atmosphere \
  --lines Fe12_195.1190 Fe12_195.1790 \
  --abundance sun_coronal_2021_chianti \
  --n-workers 4 \
  --output-dir ./run/input \
  --output-name synthesised_spectra.pkl \
  --temp-file temp/eosT.0270000 \
  --rho-file rho/result_prim_0.0270000 \
  --vx-file vx/result_prim_1.0270000 \
  --vy-file vy/result_prim_3.0270000 \
  --vz-file vz/result_prim_2.0270000 \
  --cube-shape 512 768 256 \
  --voxel-dx "0.192 Mm" \
  --voxel-dy "0.192 Mm" \
  --voxel-dz "0.064 Mm" \
  --vel-res "5.0 km/s" \
  --vel-lim "300.0 km/s" \
  --integration-axis z \
  --crop-x "-50 Mm" "50 Mm" \
  --crop-y "-50 Mm" "50 Mm" \
  --crop-z "0 Mm" "20 Mm" \
  --downsample 1 \
  --precision float64 \
  --mean-mol-wt 1.29

# Show all available options
synthesise-spectra --help
```

#### Command Line Options

**Input/Output Paths:**
- `--data-dir`: Directory containing simulation data (default: `data/atmosphere`)
- `--output-dir`: Output directory for results (default: `./run/input`)
- `--output-name`: Output filename (default: `synthesised_spectra.pkl`)

**Line and Abundance Selection:**
- `--lines`: Emission lines to synthesise, e.g., `--lines Fe12_195.1190 Fe12_195.1790` (required)
- `--abundance`: CHIANTI abundance dataset name (default: `sun_coronal_2021_chianti`)
- `--n-workers`: Number of parallel workers for the fiasco G(T, n_e) computation. Each distinct ion is computed in a separate process. `0` uses all available CPUs (default: `0`). Set to `1` for serial execution.

**Simulation Files:**
- `--temp-file`: Temperature file relative to data-dir (default: `temp/eosT.0270000`)
- `--rho-file`: Density file relative to data-dir (default: `rho/result_prim_0.0270000`)
- `--vx-file`: X-velocity file (required if `--integration-axis x`)
- `--vy-file`: Y-velocity file (required if `--integration-axis y`)
- `--vz-file`: Z-velocity file (required if `--integration-axis z`)

**Grid Parameters:**
- `--cube-shape`: Cube dimensions as three integers (default: `512 768 256`)
- `--voxel-dx`, `--voxel-dy`, `--voxel-dz`: Voxel sizes with units (default: `"0.192 Mm"`, `"0.192 Mm"`, `"0.064 Mm"`)

**Velocity Grid:**
- `--vel-res`: Velocity resolution with units (default: `"5.0 km/s"`)
- `--vel-lim`: Velocity limit +-km/s with units (default: `"300.0 km/s"`)

**Integration and Viewing:**
- `--integration-axis`: Integration axis: `x`, `y`, or `z` (default: `z`)
  - `z`: Standard top-down view (integrates through height)
  - `x`: Side view from the left (integrates left-to-right)
  - `y`: Side view from the front (integrates front-to-back)

**Spatial Cropping (Heliocentric coordinates with units):**
- `--crop-x`: X-range to crop with units, e.g., `--crop-x "-50 Mm" "50 Mm"` (optional)
- `--crop-y`: Y-range to crop with units, e.g., `--crop-y "-50 Mm" "50 Mm"` (optional)
- `--crop-z`: Z-range to crop with units, e.g., `--crop-z "0 Mm" "20 Mm"` (optional)
- Omit any crop option to use the full range in that dimension

**Processing Options:**
- `--downsample`: Downsampling factor (default: `1` = no downsampling)
- `--precision`: Numerical precision `float32` or `float64` (default: `float64`)
- `--mean-mol-wt`: Mean molecular weight (default: `1.29`)

#### Dynamic Mode (Time-varying Atmospheres)

For simulating raster scans over evolving atmospheres, use dynamic mode which combines MHD timesteps based on instrument scanning:

```bash
synthesise-spectra \
  --data-dir ./data/atmosphere \
  --lines Fe12_195.1190 \
  --abundance sun_coronal_2021_chianti \
  --output-dir ./run/input \
  --slit-rest-time "40 s" \
  --slit-width "0.2 arcsec" \
  --temp-dir temp \
  --temp-filename eosT \
  --rho-dir rho \
  --rho-filename result_prim_0 \
  --vz-dir vz \
  --vz-filename result_prim_2 \
  --time-dir time \
  --time-filename tau_slice_0.100 \
  --cube-shape 512 768 256 \
  --voxel-dx "0.192 Mm" \
  --voxel-dy "0.192 Mm" \
  --voxel-dz "0.064 Mm" \
  --vel-res "5.0 km/s" \
  --vel-lim "300.0 km/s" \
  --integration-axis z
```

**Dynamic Mode Options:**
- `--slit-rest-time`: Slit rest time per position - enables dynamic mode
- `--slit-width`: Slit width
- `--temp-dir`, `--rho-dir`, `--vx-dir`, `--vy-dir`, `--vz-dir`, `--time-dir`: Directories containing timestep files
- `--temp-filename`, `--rho-filename`, `--vx-filename`, `--vy-filename`, `--vz-filename`, `--time-filename`: Filename prefix before timestep suffix

#### Output

The synthesis produces a pickle file containing:
- `line_cubes`: Individual NDCube objects for each spectral line with proper WCS
- `config`: Runtime configuration for reproducibility
- Additional technical data for internal use

#### Performance Tips

- Use `--downsample 2` or `--downsample 4` for initial testing
- Use `--precision float32` to reduce memory usage (may affect accuracy)
- Use spatial cropping to focus on regions of interest and reduce computation time
- Monitor memory usage - full resolution synthesis can require 50+ GB RAM
- Side views (`--integration-axis x` or `y`) may require different velocity files

#### Working with Synthesis Results

The synthesis results can be loaded and analyzed using the package API:

```python
import euvst_response

# Load synthesis results - this sums all line cubes into a single cube
# By default uses Fe XII 195.119 Angstrom as reference for wavelength grid
cube = euvst_response.load_atmosphere("./run/input/synthesised_spectra.pkl")
print(f"Combined cube shape: {cube.data.shape}")

# Access individual line cubes if needed
import pickle
with open("./run/input/synthesised_spectra.pkl", "rb") as f:
    data = pickle.load(f)

# Access individual line cubes
fe12_195 = data["line_cubes"]["Fe12_195.1190"]
print(f"Fe XII 195.119 cube shape: {fe12_195.data.shape}")
print(f"Rest wavelength: {fe12_195.meta['rest_wav']}")

# List all available lines
print(f"Available spectral lines: {list(data['line_cubes'].keys())}")
```

### 2. Simulate the instrument response

#### Configuration File

ECLIPSE uses YAML configuration files to specify simulation parameters.
Parameters are organised into four sections - `simulation`, `detector`, `telescope`, and `filter` - each corresponding directly to a configuration class in `config.py`.
Any field of those classes can be set here.
**Any parameter that is given as a list is automatically swept over** and the
simulation runs every combination (cartesian product).

**Top-level keys** (not sections):
- `instrument`: `SWC` (EUVST Short Wavelength) or `EIS` (Hinode/EIS)
- `synthesis_file`: path to the synthesised spectra pickle file
- `reference_line`: spectral line used as the wavelength-grid reference (default `Fe12_195.1190`)
- `n_iter`: number of Monte Carlo iterations
- `ncpu`: CPU cores to use (`-1` = all available)
- `offchip_bin_slit`: off-chip slit binning factor (default `1`)
- `pinhole_sizes`, `pinhole_positions`: fixed paired lists for pinhole diffraction tests (SWC only)
- `uniform_intensity`, `rest_wavelength`, `thermal_width`: uniform-intensity mode (alternative to synthesis file)

Here's a complete example configuration file:

```yaml
# Input
instrument: SWC
synthesis_file: ./run/input/synthesised_spectra.pkl
reference_line: Fe12_195.1190

# Global settings (apply to all combinations)
n_iter: 500
ncpu: -1
offchip_bin_slit: [1, 2]  # sweep no-binning and 2-pixel off-chip binning

# Simulation parameters
# Any field listed as a list is swept over; all combinations are run.
simulation:
  slit_width: [0.2 arcsec, 0.4 arcsec]  # sweep over two slit widths
  expos: [5 s, 10 s, 20 s, 40 s, 80 s]  # sweep over five exposure times
  psf: True
  vis_sl: 0 photon / (s * cm^2)
  enable_pinholes: False

# Detector parameters
detector:
  ccd_temperature: -60 Celsius  # used to compute dark current via the CCD model

# Telescope parameters
telescope:
  microroughness_sigma: 0.3 nm  # RMS surface roughness

# Aluminium filter parameters (SWC only)
filter:
  al_thickness: 1485 angstrom
  oxide_thickness: 95 angstrom
  c_thickness: 40 angstrom
  mesh_throughput: 0.8
```

Any parameter from the `Detector_SWC`, `Telescope_EUVST`, or `AluminiumFilter`
dataclasses in `config.py` can be added to the corresponding section. For
example, to sweep over detector quantum efficiency:

```yaml
detector:
  ccd_temperature: -60 Celsius
  qe_euv: [0.5, 0.65, 0.76]   # sweep over three QE values
```

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

By default, both the DN and photon signals are fitted at every Monte Carlo iteration. To speed up the simulation when only one is needed, use the `fit_signals` option:

```yaml
fit_signals: dn       # Fit only the DN signal
fit_signals: photon   # Fit only the photon signal
fit_signals: both     # Fit both (default)
```

To fit blended spectral lines with multiple Gaussian components, add a `fitting` block:

```yaml
fitting:
  primary_component: 0           # index of the component whose velocity is reported
  constrain_positive_intensity: true  # reject fits with negative amplitudes
  backend: scipy                 # optimiser: "scipy" (default) or "mpfit"
  components:
    - wavelength: 195.119 angstrom     # component 0: free centre, width, amplitude
    - wavelength: 195.179 angstrom     # component 1: centre & width tied to component 0
      tie_center: 0
      tie_width: 0
```

Each component requires a `wavelength` field giving its rest wavelength.

Each entry in `components` corresponds to one Gaussian. Optional per-component keys:
- `tie_center: <i>`: constrain this component's centre to match component *i*
- `tie_width: <i>`: constrain this component's line width to match component *i*
- `amplitude_greater_than: <i>`: constrain amplitude to exceed that of component *i*

Omitting the `fitting` block fits a single Gaussian (default behaviour).

If you synthesised data in dynamic mode, your configuration must specify:
- Exactly one slit width matching the synthesis slit width
- Exactly one exposure time matching the synthesis exposure time

#### Running Simulations

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

**Command-line options:**
- `--config`: Path to YAML configuration file (required)
- `--debug`: Enable debug mode with IPython breakpoints on errors (optional)

#### Multi-node MPI parallelisation

When launched with multiple MPI ranks on a SLURM cluster (via `srun` or `mpirun`, and setting `--ntasks-per-node`), ECLIPSE automatically distributes Monte Carlo iterations across ranks and gathers results on rank 0. No code or configuration changes are needed - MPI is auto-detected at runtime. If `mpi4py` is not installed or only one rank is present, the code falls back to single-process mode.

Requirements: `mpi4py` and `intel-mpi` (load with `module load intel-mpi` before launching).

#### Output

Results are saved as pickle files in the `run/result/` directory with the same base name as the configuration file. 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
- Full config objects (`Detector`, `Telescope`, `Simulation`) for each parameter combination
- The git commit ID and software version used to produce the results

Use `summary_table(results)` after loading to see all parameter combinations and the run metadata.

## 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 ECLIPSE code is developed and maintained at Mullard Space Science Laboratory (UCL), and was made using Austrian Super Computing (ASC) infrastructure in collaboration with the University of Vienna.
