solarc-eclipse 0.7.0__tar.gz → 0.8.0__tar.gz

solarc_eclipse-0.8.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) James McKevitt
+
+Publishing any results produced by this software, or any work derived from it, requires permission from the author. Contact James McKevitt (jm2@mssl.ucl.ac.uk) before publication.
+
+The SOLAR-C SWG are also required to approve the publication of forward modelling results for SOLAR-C/EUVST. Contact James McKevitt (jm2@mssl.ucl.ac.uk) for more information.

solarc_eclipse-0.8.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: solarc-eclipse
+Version: 0.8.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: Copyright (c) James McKevitt
+        
+        Publishing any results produced by this software, or any work derived from it, requires permission from the author. Contact James McKevitt (jm2@mssl.ucl.ac.uk) before publication.
+        
+        The SOLAR-C SWG are also required to approve the publication of forward modelling results for SOLAR-C/EUVST. Contact James McKevitt (jm2@mssl.ucl.ac.uk) for more information.
+Project-URL: Homepage, https://github.com/jamesmckevitt/eclipse
+Project-URL: Repository, https://github.com/jamesmckevitt/eclipse
+Project-URL: Documentation, https://solarc-eclipse.readthedocs.io
+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"
+Requires-Dist: ipywidgets; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+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). See [LICENSE](LICENSE) for usage terms.
+
+The instrument response generated by this code will be updated during instrument development, testing, and commissioning.
+
+[![Documentation Status](https://readthedocs.org/projects/solarc-eclipse/badge/?version=latest)](https://solarc-eclipse.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/solarc-eclipse.svg)](https://pypi.org/project/solarc-eclipse/)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.17543844-blue.svg)](https://doi.org/10.5281/zenodo.17543844)
+
+Full documentation - installation, quick start, the synthesis and instrument response guides, and the analysis tutorial - is at **[solarc-eclipse.readthedocs.io](https://solarc-eclipse.readthedocs.io)**.
+
+## 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.

solarc_eclipse-0.8.0/README.md

@@ -0,0 +1,17 @@
+# 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). See [LICENSE](LICENSE) for usage terms.
+
+The instrument response generated by this code will be updated during instrument development, testing, and commissioning.
+
+[![Documentation Status](https://readthedocs.org/projects/solarc-eclipse/badge/?version=latest)](https://solarc-eclipse.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/solarc-eclipse.svg)](https://pypi.org/project/solarc-eclipse/)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.17543844-blue.svg)](https://doi.org/10.5281/zenodo.17543844)
+
+Full documentation - installation, quick start, the synthesis and instrument response guides, and the analysis tutorial - is at **[solarc-eclipse.readthedocs.io](https://solarc-eclipse.readthedocs.io)**.
+
+## 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.

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/euvst_response/__init__.py

@@ -4,7 +4,7 @@ ECLIPSE: Emission Calculation and Line Prediction for SOLAR-C EUVST
 This package provides tools for modeling the performance of the EUV spectrograph EUVST, on SOLAR-C.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 __author__ = "James McKevitt"
 __email__ = "jm2@mssl.ucl.ac.uk"
 

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/euvst_response/data_processing.py

@@ -14,7 +14,7 @@ from specutils import Spectrum
 from specutils.manipulation import FluxConservingResampler
 from joblib import Parallel, delayed
 from tqdm import tqdm
-from .utils import tqdm_joblib, distance_to_angle
+from .utils import tqdm_joblib, distance_to_angle, _fwhm_to_sigma
 
 
 def _resample_batch(flat_chunk, unit, spectral_world, new_spec_grid, n_spec):
@@ -331,9 +331,11 @@ def create_uniform_intensity_cube(
     det,
     sim,
     n_sigma_extent: float = 8.0,
+    n_slit_pixels: int = 1,
+    tel=None,
 ) -> NDCube:
     """
-    Create a 1x1 pixel NDCube containing a Gaussian emission line.
+    Create a 1 x ``n_slit_pixels`` pixel NDCube containing a Gaussian emission line.
 
     The cube is built directly at the detector's spectral resolution and
     assigned a helioprojective WCS consistent with the output of
@@ -354,14 +356,30 @@ def create_uniform_intensity_cube(
         Simulation configuration (provides ``slit_width``).
     n_sigma_extent : float, optional
         Number of sigma either side of line centre to include in the
-        wavelength grid (default: 8).
+        wavelength grid (default: 8).  Measured on the width the line will have
+        once the spectral PSF has been applied, if *tel* is given.
+    n_slit_pixels : int, optional
+        Number of (uniform) slit pixels to generate.  Set to the
+        ``offchip_bin_slit`` value so that subsequent ``rebin_slit_offchip``
+        sums ``n_slit_pixels`` independent noise realisations into a single
+        binned pixel (default: 1).
+    tel : Telescope_EUVST or Telescope_EIS, optional
+        Telescope configuration.  When given, the grid is widened to hold the
+        line after spectral PSF broadening, adding the PSF width to the thermal
+        width in quadrature.  Without this a narrow line gets a grid only a
+        couple of pixels wide, and convolving it with a PSF wider than the line
+        pushes flux off the ends of the grid.  Default None, which sizes the
+        grid on the thermal width alone.
 
     Returns
     -------
     NDCube
-        Shape ``(1, 1, n_lambda)`` with unit ``erg / (s cm2 sr cm)`` and a
+        Shape ``(1, n_slit_pixels, n_lambda)`` with unit ``erg / (s cm2 sr cm)`` and a
         helioprojective + wavelength WCS.
     """
+    if n_slit_pixels < 1:
+        raise ValueError(f"n_slit_pixels must be >= 1, got {n_slit_pixels}")
+
     # --- Spectral grid --------------------------------------------------
     lam0 = rest_wavelength.to(u.cm)
 
@@ -371,7 +389,19 @@ def create_uniform_intensity_cube(
     # Detector pixel pitch in cm
     dlam = det.wvl_res.to(u.cm / u.pix) * u.pix  # strip per-pixel to cm
 
-    half_range = n_sigma_extent * sigma_lam
+    # The grid has to hold the line as it will be *measured*, not as it leaves
+    # the Sun, so add the spectral PSF to the thermal width in quadrature.
+    # Widths add that way for Gaussians, and the PSF is often the broader of
+    # the two: at the default 20 km/s the line is 0.77 pixels against a PSF of
+    # 1.08.  Always widening, rather than only when psf is set, keeps the grid
+    # independent of a value that is swept and is not known when the cube is
+    # built and cached.
+    sigma_total = sigma_lam
+    if tel is not None:
+        sigma_psf = _fwhm_to_sigma(tel.psf_params[1].to(u.pixel).value) * dlam
+        sigma_total = np.sqrt(sigma_lam**2 + sigma_psf**2)
+
+    half_range = n_sigma_extent * sigma_total
     n_pix_half = int(np.ceil((half_range / dlam).decompose().value))
     n_lam = 2 * n_pix_half + 1  # always odd, centred on rest wavelength
 
@@ -384,14 +414,17 @@ def create_uniform_intensity_cube(
         u.erg / (u.s * u.cm**2 * u.sr * u.cm)
     )
     profile = A * np.exp(-0.5 * ((lam_grid - lam0) / sigma_lam) ** 2)
-    data = profile.value[np.newaxis, np.newaxis, :]  # shape (1, 1, n_lam)
+    # Tile the profile along the slit axis.  Every slit pixel holds the same
+    # intensity, but each is noised independently downstream, which is what
+    # rebin_slit_offchip needs in order to sum them.
+    data = np.tile(profile.value, (1, n_slit_pixels, 1))  # shape (1, n_slit_pixels, n_lam)
 
     # --- WCS (matches reproject_ndcube output format) --------------------
     # Axes: WAVE (cm), HPLT-TAN (arcsec), HPLN-TAN (arcsec)
     wcs = WCS(naxis=3)
     wcs.wcs.ctype = ["WAVE", "HPLT-TAN", "HPLN-TAN"]
     wcs.wcs.cunit = ["cm", "arcsec", "arcsec"]
-    wcs.wcs.crpix = [(n_lam + 1) / 2, 1.0, 1.0]
+    wcs.wcs.crpix = [(n_lam + 1) / 2, (n_slit_pixels + 1) / 2, 1.0]
     wcs.wcs.crval = [lam0.value, 0.0, 0.0]
     wcs.wcs.cdelt = [
         dlam.to_value(u.cm),

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/euvst_response/main.py

@@ -432,14 +432,18 @@ def main() -> None:
             DET = Detector_EIS(**all_det) if all_det else Detector_EIS()
 
         # Two-level rebinning cache: rebin_atmosphere does not depend on offchip_bin_slit,
-        # so cube_reb_cache is keyed by the 3-tuple to avoid redundant rebin calls when
-        # sweeping multiple binning values at fixed spatial/spectral sampling.
-        cube_reb_key = (
+        # so cube_reb_cache is keyed by the sampling alone to avoid redundant rebin calls
+        # when sweeping multiple binning values at fixed spatial/spectral sampling.
+        sampling_key = (
             slit_width.to_value(u.arcsec),
             DET.plate_scale_angle.to_value(u.arcsec / u.pixel),
             DET.wvl_res.to_value(u.cm / u.pixel),
         )
-        rebin_cache_key = (*cube_reb_key, offchip_bin_slit)
+        # In uniform-intensity mode the cube is built with one slit pixel per binning
+        # factor, so that rebin_slit_offchip has independent noise realisations to sum.
+        # The cube therefore does depend on offchip_bin_slit, and the key must say so.
+        cube_reb_key = (*sampling_key, offchip_bin_slit) if uniform_intensity_mode else sampling_key
+        rebin_cache_key = (*sampling_key, offchip_bin_slit)
 
         if cube_reb_key not in cube_reb_cache:
             print(
@@ -463,6 +467,8 @@ def main() -> None:
                     thermal_width=uniform_thermal_width,
                     det=DET,
                     sim=SIM_rebin,
+                    n_slit_pixels=offchip_bin_slit,
+                    tel=TEL,
                 )
             else:
                 cube_reb_cache[cube_reb_key] = rebin_atmosphere(cube_sim, DET, SIM_rebin)
@@ -479,7 +485,7 @@ def main() -> None:
             # Key by (slit_width_arcsec, offchip_bin_slit) so that sweeps over
             # multiple binning factors at fixed slit width all retain their cubes
             # (a single-key dict would silently keep only the first one).
-            cube_reb_dict.setdefault((cube_reb_key[0], offchip_bin_slit), cube_reb_binned)
+            cube_reb_dict.setdefault((sampling_key[0], offchip_bin_slit), cube_reb_binned)
 
         cube_reb_binned, fit_truth_data, fit_truth_units = rebin_cache[rebin_cache_key]
 

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/euvst_response/monte_carlo.py

@@ -18,7 +18,17 @@ from .fitting import fit_cube_gauss
 from .utils import angle_to_distance, rebin_slit_offchip, _get_mpi_info
 
 
-def simulate_once(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim) -> Tuple[NDCube, ...]:
+def simulate_once(
+    I_cube: NDCube,
+    t_exp: u.Quantity,
+    det,
+    tel,
+    sim,
+    *,
+    uniform_mode: bool = False,
+    photon_shot_inverse_transform: bool = False,
+    dark_current_inverse_transform: bool = False,
+) -> Tuple[NDCube, ...]:
     """
     Run a single Monte Carlo simulation of the instrument response.
     
@@ -34,6 +44,18 @@ def simulate_once(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim) -> Tuple[NDC
         Telescope configuration
     sim : Simulation
         Simulation configuration
+    uniform_mode : bool, optional
+        If True the input cube is uniform along the slit, so the PSF is
+        convolved in the spectral direction only.  See
+        :func:`~euvst_response.radiometric.apply_focusing_optics_psf`.
+        Default False.
+    photon_shot_inverse_transform : bool, optional
+        Use inverse-transform Poisson sampling for photon shot noise, so that
+        common random numbers survive a change in photon flux.  Default False.
+    dark_current_inverse_transform : bool, optional
+        Use inverse-transform Poisson sampling for dark-current shot noise, so
+        that common random numbers survive a change in dark-current level.
+        Default False.
         
     Returns
     -------
@@ -57,7 +79,9 @@ def simulate_once(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim) -> Tuple[NDC
 
     # Apply focusing optics PSF (primary mirror + diffraction grating)
     if sim.psf:
-        photons_focused = apply_focusing_optics_psf(photons_pixels, tel)
+        photons_focused = apply_focusing_optics_psf(
+            photons_pixels, tel, convolve_spatial=not uniform_mode
+        )
     else:
         photons_focused = photons_pixels
     
@@ -68,10 +92,16 @@ def simulate_once(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim) -> Tuple[NDC
         photons_euv_pinholes = photons_focused
 
     # Sample discrete photon arrivals (photon shot noise)
-    photon_arrivals = sample_photon_arrivals(photons_euv_pinholes)
+    photon_arrivals = sample_photon_arrivals(
+        photons_euv_pinholes,
+        photon_shot_inverse_transform=photon_shot_inverse_transform,
+    )
 
     # Convert to electrons (detector response: QE, Fano noise, dark current, read noise)
-    electrons = to_electrons(photon_arrivals, t_exp, det)
+    electrons = to_electrons(
+        photon_arrivals, t_exp, det,
+        dark_current_inverse_transform=dark_current_inverse_transform,
+    )
     
     # Add visible stray light (with filter throughput)
     electrons_stray = add_visible_stray_light(electrons, t_exp, det, sim, tel)
@@ -92,7 +122,10 @@ def simulate_once(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim) -> Tuple[NDC
 
 def monte_carlo(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim, n_iter: int = 5,
                 fit_config=None, offchip_bin_slit: int = 1,
-                fit_signals: str = "both", uniform_mode: bool = False) -> Tuple[NDCube, dict | None, NDCube, dict | None]:
+                fit_signals: str = "both", uniform_mode: bool = False,
+                *,
+                photon_shot_inverse_transform: bool = False,
+                dark_current_inverse_transform: bool = False) -> Tuple[NDCube, dict | None, NDCube, dict | None]:
     """
     Run Monte Carlo simulations and fit results.
     
@@ -121,11 +154,19 @@ def monte_carlo(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim, n_iter: int =
         ``"photon"``.  Fitting is the most expensive step, so
         selecting only the signal of interest roughly halves runtime.
     uniform_mode : bool, optional
-        If True the input cube is assumed to be a single 1x1 spatial pixel
-        (uniform-intensity mode).  All MC simulations are run first and
-        the resulting spectra are stacked so that fitting is parallelised
-        over the n_iter iterations rather than over the spatial dimension.
-        Default: False.
+        If True the input cube is taken to be uniform-intensity mode: one scan
+        position and ``offchip_bin_slit`` identical slit pixels, which
+        *offchip_bin_slit* then sums back down to a single spatial pixel.  All
+        MC simulations are run first and the resulting spectra are stacked so
+        that fitting is parallelised over the n_iter iterations rather than
+        over the spatial dimension.  Default: False.
+    photon_shot_inverse_transform : bool, optional
+        Use inverse-transform Poisson sampling for photon shot noise, so that
+        common random numbers survive a change in photon flux.  Default False.
+    dark_current_inverse_transform : bool, optional
+        Use inverse-transform Poisson sampling for dark-current shot noise, so
+        that common random numbers survive a change in dark-current level.
+        Default False.
         
     Returns
     -------
@@ -165,7 +206,12 @@ def monte_carlo(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim, n_iter: int =
                       disable=not show_progress):
             (intensity_exp, photons_total, photons_throughput, photons_pixels,
              photons_focused, photon_arrivals, electrons, electrons_stray,
-             electrons_pinholes, dn) = simulate_once(I_cube, t_exp, det, tel, sim)
+             electrons_pinholes, dn) = simulate_once(
+                I_cube, t_exp, det, tel, sim,
+                uniform_mode=uniform_mode,
+                photon_shot_inverse_transform=photon_shot_inverse_transform,
+                dark_current_inverse_transform=dark_current_inverse_transform,
+            )
 
             if i == 0 and rank == 0:
                 first_dn_signal = rebin_slit_offchip(dn, offchip_bin_slit)
@@ -244,7 +290,12 @@ def monte_carlo(I_cube: NDCube, t_exp: u.Quantity, det, tel, sim, n_iter: int =
             # Simulate one run
             (intensity_exp, photons_total, photons_throughput, photons_pixels,
              photons_focused, photon_arrivals, electrons, electrons_stray,
-             electrons_pinholes, dn) = simulate_once(I_cube, t_exp, det, tel, sim)
+             electrons_pinholes, dn) = simulate_once(
+                I_cube, t_exp, det, tel, sim,
+                uniform_mode=uniform_mode,
+                photon_shot_inverse_transform=photon_shot_inverse_transform,
+                dark_current_inverse_transform=dark_current_inverse_transform,
+            )
 
             # Store first iteration signals only on rank 0 (binned, to match fit shapes)
             if i == 0 and rank == 0:

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/euvst_response/radiometric.py

@@ -7,8 +7,46 @@ import numpy as np
 import astropy.units as u
 import astropy.constants as const
 from ndcube import NDCube
+from scipy.ndimage import convolve1d
 from scipy.signal import convolve2d
-from .utils import wl_to_vel, vel_to_wl, debug_break
+from scipy.stats import poisson
+from .utils import wl_to_vel, vel_to_wl, debug_break, _fwhm_to_sigma
+
+
+def _poisson_inverse_transform(mean_counts, size=None) -> np.ndarray:
+    """
+    Draw Poisson counts by inverse-transform (quantile) sampling.
+
+    One uniform draw per element is passed through the Poisson inverse-CDF.
+    The marginal distribution is identical to ``np.random.poisson``, but this
+    consumes a fixed number of RNG draws per element, where the rejection
+    sampling in ``np.random.poisson`` consumes a variable number.  That keeps
+    the random stream synchronised across runs whose only difference is the
+    Poisson mean, which is what makes common-random-number variance reduction
+    possible.
+
+    Parameters
+    ----------
+    mean_counts : float or np.ndarray
+        Poisson mean, either scalar or per element.
+    size : tuple of int, optional
+        Shape to draw.  Defaults to the shape of *mean_counts*.
+
+    Returns
+    -------
+    np.ndarray
+        Sampled counts as int64.
+    """
+    if size is None:
+        size = np.shape(mean_counts)
+
+    u_draw = np.random.random(size=size)
+    # np.random.random() draws from [0, 1) and scipy's ppf returns -1 at
+    # exactly 0, which would give a negative count.  Clamp to the smallest
+    # positive double, which leaves the CRN property intact.
+    np.maximum(u_draw, np.nextafter(0.0, 1.0), out=u_draw)
+
+    return poisson.ppf(u_draw, mean_counts).astype(np.int64)
 
 
 def _vectorized_fano_noise(photon_counts: np.ndarray, rest_wavelength: u.Quantity, det) -> np.ndarray:
@@ -126,12 +164,12 @@ def photons_to_pixel_counts(ph_flux: NDCube, wl_pitch: u.Quantity, plate_scale:
     )
 
 
-def _fwhm_to_sigma(fwhm: float) -> float:
-    """Convert FWHM to Gaussian sigma: sigma = FWHM / (2 * sqrt(2 * ln2))."""
-    return fwhm / (2.0 * np.sqrt(2.0 * np.log(2.0)))
-
-
-def apply_focusing_optics_psf(signal: NDCube, tel) -> NDCube:
+def apply_focusing_optics_psf(
+    signal: NDCube,
+    tel,
+    *,
+    convolve_spatial: bool = True,
+) -> NDCube:
     """
     Convolve each detector frame (n_slit, n_lambda) of an NDCube with an
     anisotropic 2-D PSF from the focusing optics.
@@ -147,6 +185,14 @@ def apply_focusing_optics_psf(signal: NDCube, tel) -> NDCube:
     tel : Telescope_EUVST or Telescope_EIS
         Telescope configuration containing PSF parameters.
         psf_params = [spatial_fwhm, spectral_fwhm] in pixel units.
+    convolve_spatial : bool, optional
+        When False, convolve the spectral axis only and leave the slit axis
+        alone.  This is for a field that is uniform along the slit, where
+        convolving a constant with a normalised kernel returns the same
+        constant and the spatial pass is an identity operation.  Doing it
+        anyway would not be harmless: the convolution treats everything
+        outside the array as dark, so a uniform field would lose flux off the
+        ends of the slit that it really does have.  Default True.
 
     Returns
     -------
@@ -160,6 +206,11 @@ def apply_focusing_optics_psf(signal: NDCube, tel) -> NDCube:
     psf_type = tel.psf_type.lower()
     psf_params = tel.psf_params
 
+    if psf_type != "gaussian":
+        raise ValueError(
+            f"Unsupported PSF type: {psf_type}. Supported: 'gaussian'."
+        )
+
     if len(psf_params) < 2:
         raise ValueError(
             "psf_params must contain two elements: "
@@ -182,6 +233,20 @@ def apply_focusing_optics_psf(signal: NDCube, tel) -> NDCube:
     if kx % 2 == 0:
         kx += 1
 
+    if not convolve_spatial:
+        # Spectral axis only.  Zero padding is correct here: the wavelength
+        # grid extends several sigma past the line, so there is no flux at its
+        # edges to lose.
+        x_1d = np.arange(kx) - kx // 2
+        psf_1d = np.exp(-0.5 * (x_1d / sigma_spectral) ** 2)
+        psf_1d /= psf_1d.sum()
+        return NDCube(
+            data=convolve1d(data_in, psf_1d, axis=2, mode="constant", cval=0.0),
+            wcs=signal.wcs.deepcopy(),
+            unit=unit,
+            meta=signal.meta,
+        )
+
     # Coordinate grids centred at zero
     cy, cx = ky // 2, kx // 2
     y, x = np.mgrid[:ky, :kx]
@@ -189,13 +254,8 @@ def apply_focusing_optics_psf(signal: NDCube, tel) -> NDCube:
     x = (x - cx).astype(float)
 
     # Build PSF
-    if psf_type == "gaussian":
-        psf = np.exp(-0.5 * ((y / sigma_spatial) ** 2
-                             + (x / sigma_spectral) ** 2))
-    else:
-        raise ValueError(
-            f"Unsupported PSF type: {psf_type}. Supported: 'gaussian'."
-        )
+    psf = np.exp(-0.5 * ((y / sigma_spatial) ** 2
+                         + (x / sigma_spectral) ** 2))
 
     # Normalise
     psf /= psf.sum()
@@ -213,7 +273,13 @@ def apply_focusing_optics_psf(signal: NDCube, tel) -> NDCube:
     )
 
 
-def to_electrons(photon_counts: NDCube, t_exp: u.Quantity, det) -> NDCube:
+def to_electrons(
+    photon_counts: NDCube,
+    t_exp: u.Quantity,
+    det,
+    *,
+    dark_current_inverse_transform: bool = False,
+) -> NDCube:
     """
     Convert a photon-count NDCube to an electron-count NDCube.
 
@@ -225,6 +291,12 @@ def to_electrons(photon_counts: NDCube, t_exp: u.Quantity, det) -> NDCube:
         Exposure time (used for dark current and read noise).
     det : Detector_SWC or Detector_EIS
         Detector description.
+    dark_current_inverse_transform : bool, optional
+        When True, draw dark-current shot noise with
+        :func:`_poisson_inverse_transform` rather than ``np.random.poisson``.
+        The distribution is unchanged, but the random stream stays synchronised
+        across runs that differ only in dark-current level, which is what
+        common-random-number variance reduction needs.  Default False.
 
     Returns
     -------
@@ -242,10 +314,16 @@ def to_electrons(photon_counts: NDCube, t_exp: u.Quantity, det) -> NDCube:
 
     e = electron_counts * (u.electron / u.pixel)
 
-    # Add dark current with Poisson noise (per pixel)
+    # Add dark current with Poisson shot noise (per pixel)
     dark_current_mean = (det.dark_current * t_exp).to(u.electron / u.pixel).value
-    dark_current_poisson = np.random.poisson(dark_current_mean, size=photon_counts.data.shape) * (u.electron / u.pixel)
-    e += dark_current_poisson
+    if dark_current_inverse_transform:
+        dark_current_counts = _poisson_inverse_transform(
+            dark_current_mean, size=photon_counts.data.shape
+        )
+    else:
+        dark_current_counts = np.random.poisson(dark_current_mean, size=photon_counts.data.shape)
+    dark_current_signal = dark_current_counts * (u.electron / u.pixel)
+    e += dark_current_signal
     
     # Add read noise
     e += np.random.normal(0, det.read_noise_rms.value,
@@ -317,7 +395,11 @@ def add_poisson(cube: NDCube) -> NDCube:
     )
 
 
-def sample_photon_arrivals(photon_counts: NDCube) -> NDCube:
+def sample_photon_arrivals(
+    photon_counts: NDCube,
+    *,
+    photon_shot_inverse_transform: bool = False,
+) -> NDCube:
     """
     Sample a discrete Poisson realisation of photon arrivals per pixel.
 
@@ -331,6 +413,12 @@ def sample_photon_arrivals(photon_counts: NDCube) -> NDCube:
     ----------
     photon_counts : NDCube
         Expected (mean) photon counts per pixel.
+    photon_shot_inverse_transform : bool, optional
+        When True, draw photon shot noise with
+        :func:`_poisson_inverse_transform` rather than ``np.random.poisson``.
+        The distribution is unchanged, but the random stream stays synchronised
+        across runs that differ only in photon flux, which is what
+        common-random-number variance reduction needs.  Default False.
 
     Returns
     -------
@@ -344,7 +432,10 @@ def sample_photon_arrivals(photon_counts: NDCube) -> NDCube:
     mean_counts = q.to(canonical_units).value
     mean_counts = np.maximum(mean_counts, 0)
 
-    sampled = np.random.poisson(mean_counts)
+    if photon_shot_inverse_transform:
+        sampled = _poisson_inverse_transform(mean_counts)
+    else:
+        sampled = np.random.poisson(mean_counts)
 
     return NDCube(
         data=sampled.astype(np.int64),

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/euvst_response/utils.py

@@ -457,3 +457,8 @@ def tqdm_joblib(tqdm_object):
     finally:
         joblib.parallel.BatchCompletionCallBack = old_callback
         tqdm_object.close()
+
+
+def _fwhm_to_sigma(fwhm: float) -> float:
+    """Convert FWHM to Gaussian sigma: sigma = FWHM / (2 * sqrt(2 * ln2))."""
+    return fwhm / (2.0 * np.sqrt(2.0 * np.log(2.0)))

{solarc_eclipse-0.7.0 → solarc_eclipse-0.8.0}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
 ]
 description = "ECLIPSE: Emission Calculation and Line Prediction for SOLAR-C EUVST"
 readme = "README.md"
-license = {text = "Contact for permission"}
+license = {file = "LICENSE"}
 requires-python = ">=3.10"
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -49,6 +49,16 @@ dev = [
     "black",
     "flake8",
     "mypy",
+    # Needed when re-running the tutorial notebook, not when building the docs
+    # (mkdocs-jupyter renders the stored outputs without executing anything).
+    # Without it tqdm emits a TqdmWarning, which gets saved into the notebook
+    # outputs and then shows up as an error block on the docs site.
+    "ipywidgets",
+]
+docs = [
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "mkdocs-jupyter",
 ]
 
 [project.scripts]
@@ -60,6 +70,7 @@ synthesise_spectra = "euvst_response.synthesis_cli:main"
 [project.urls]
 Homepage = "https://github.com/jamesmckevitt/eclipse"
 Repository = "https://github.com/jamesmckevitt/eclipse"
+Documentation = "https://solarc-eclipse.readthedocs.io"
 
 [tool.setuptools.packages.find]
 include = ["euvst_response*"]