eclipse 0.13.0__py3-none-any.whl

eclipse/synthesis_file.py

@@ -0,0 +1,882 @@
+"""
+Synthesis files: the spectra the instrument simulation observes, as HDF5.
+
+The layout is described on the Files page of the docs. The view is
+`integration_axis`, `"x"`, `"y"` or `"z"` seen from +x, -y or above, or
+`"-x"`, `"+y"` or `"-z"` from the other side, where the image is mirrored
+left to right and `x_edges` change sign. A file without it is taken as
+seen along z.
+"""
+
+from __future__ import annotations
+
+import json
+import numbers
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Mapping, Optional
+
+import astropy.units as u
+import h5py
+import numpy as np
+
+from .atmosphere import (_check_format, _open_to_read, _read_dataset, _replacing,
+                         _text_attribute, _write_dataset)
+from .utils import (_bin_edges, _unpickle, angle_to_distance, onto_wavelength_bins, require_uniform_grid,
+                    view_axis_and_side, view_name)
+
+__all__ = [
+    "FORMAT_NAME",
+    "FORMAT_VERSION",
+    "RADIANCE_UNIT",
+    "SpectralLine",
+    "Synthesis",
+    "read_synthesis",
+    "read_synthesis_layout",
+    "write_synthesis",
+    "read_synthesis_products",
+    "load_synthesis",
+    "write_line_cubes",
+    "convert_synthesis_pickle",
+    "is_synthesis_file",
+    "synthesis_line_names",
+]
+
+FORMAT_NAME = "eclipse-synthesis"
+FORMAT_VERSION = 1
+
+# Spectral radiance unit of the instrument simulation and ECLIPSE's synthesis.
+RADIANCE_UNIT = u.erg / (u.s * u.cm**2 * u.sr * u.cm)
+
+# A spectral radiance without the steradian: a flux density per wavelength or
+# per frequency, in energy or in photons.
+_SPECTRAL_FLUX_DENSITIES = (u.erg / (u.s * u.cm**2 * u.cm), u.erg / (u.s * u.cm**2 * u.Hz),
+                            u.ph / (u.s * u.cm**2 * u.cm), u.ph / (u.s * u.cm**2 * u.Hz))
+
+AXES = ("x", "y")
+EDGES = {axis: f"{axis}_edges" for axis in AXES}
+# Example unit for each dataset, for error messages that ask for one.
+UNITS = {"intensity": u.erg / (u.s * u.cm**2 * u.sr * u.AA), "wavelength": u.AA,
+         "rest_wavelength": u.AA, "x_edges": u.Mm, "y_edges": u.Mm, "time": u.s}
+# Attributes naming the ion that emits a line, as in ECLIPSE's line cubes.
+IDENTITY = ("atom", "ion")
+# Image axes for a view along each simulation axis, from either side, as
+# named in ECLIPSE's line cubes.
+_VIEW_CTYPES = {"z": ("SOLX", "SOLY"), "x": ("SOLY", "SOLZ"), "y": ("SOLX", "SOLZ")}
+
+
+def to_radiance(intensity: u.Quantity, wavelength: u.Quantity) -> u.Quantity:
+    """
+    Convert `intensity` from any unit of spectral radiance to erg / (s cm2 sr cm).
+
+    A radiance per frequency or in photons is converted at each value of
+    `wavelength`, which runs along the last axis of `intensity`.
+    """
+    # spectral_density converts flux densities per wavelength or frequency,
+    # in energy or photons, but knows nothing of solid angle, so the
+    # steradian is removed and put back. It would also convert lambda
+    # F_lambda (the unit of an intensity summed over a line), so the flux
+    # density is first checked to be one of the four kinds.
+    flux = intensity * u.sr
+    if not any(flux.unit.is_equivalent(kind) for kind in _SPECTRAL_FLUX_DENSITIES):
+        raise u.UnitConversionError(
+            f"The intensity must be a spectral radiance, per wavelength or per "
+            f"frequency, such as erg / (s cm2 sr Angstrom) or W / (m2 sr Hz); "
+            f"got {intensity.unit}.")
+    return flux.to(RADIANCE_UNIT * u.sr, equivalencies=u.spectral_density(wavelength)) / u.sr
+
+
+def _checked(value, name: str, ndim: int, kinds: Optional[tuple] = None) -> u.Quantity:
+    """
+    Validate and return `value`.
+
+    It must be a finite Quantity with `ndim` axes and, if `kinds` is given,
+    a unit of one of those physical types.
+    """
+    if not isinstance(value, u.Quantity):
+        raise TypeError(f"{name} must be an astropy Quantity, got "
+                        f"{type(value).__name__}.")
+    if kinds is not None and value.unit.physical_type not in kinds:
+        raise u.UnitConversionError(
+            f"{name} must be in a unit of {' or '.join(kinds)}, got {value.unit}.")
+    if value.ndim != ndim:
+        raise ValueError(f"{name} must have {ndim} dimensions, got {value.ndim}.")
+    if not np.all(np.isfinite(value.value)):
+        raise ValueError(f"{name} contains NaN or infinite values.")
+    return value
+
+
+def _to_length(value: u.Quantity) -> u.Quantity:
+    """Position or size on the Sun in Mm, from a length or an angle seen from 1 AU."""
+    if value.unit.physical_type == "angle":
+        return angle_to_distance(value).to(u.Mm)
+    return value.to(u.Mm)
+
+
+# Relative tolerance for two grids that should be the same, allowing only for
+# rounding, e.g. from converting between Angstrom and nm or from edges
+# computed from two WCSs.
+_SAME_GRID = 1e-12
+
+
+def _same_grid(found: u.Quantity, expected: u.Quantity) -> bool:
+    """Whether `found` is the same grid as `expected`, up to rounding."""
+    if found.shape != expected.shape:
+        return False
+    values = found.to_value(expected.unit)
+    return bool(np.all(np.abs(values - expected.value)
+                       <= _SAME_GRID * np.abs(expected.value).max()))
+
+
+def _check_wavelength(wavelength) -> u.Quantity:
+    """
+    Validate and return `wavelength`.
+
+    It must be a finite, increasing 1D Quantity of lengths with at least 2
+    values.
+    """
+    wavelength = _checked(wavelength, "wavelength", ndim=1, kinds=("length",))
+    if wavelength.size < 2:
+        raise ValueError(f"wavelength must have at least 2 values, got {wavelength.size}.")
+    if np.any(np.diff(wavelength.value) <= 0):
+        raise ValueError("wavelength must increase; a grid that decreases, as "
+                         "one converted from increasing frequencies does, "
+                         "needs it and the intensity reversed along it.")
+    return wavelength
+
+
+@dataclass(frozen=True)
+class SpectralLine:
+    """
+    Spectra of one line, or of one spectral window, over the image.
+
+    Parameters
+    ----------
+    intensity : u.Quantity
+        Spectral radiance at each pixel and wavelength,
+        `(ny, nx, n_wavelength)`, in any unit of spectral radiance.
+    wavelength : u.Quantity
+        Wavelength of each plane of `intensity`, increasing, not necessarily
+        evenly spaced.
+    rest_wavelength : u.Quantity
+        Wavelength the line's Doppler shifts are measured from, within the
+        range of `wavelength`.
+    atom, ion : int, optional
+        Atomic number and ionisation stage of the emitting ion, e.g. 26 and
+        12 for Fe XII. Carried into the results.
+    """
+
+    intensity: u.Quantity
+    wavelength: u.Quantity
+    rest_wavelength: u.Quantity
+    atom: Optional[int] = None
+    ion: Optional[int] = None
+
+    def __post_init__(self):
+        wavelength = _check_wavelength(self.wavelength)
+        for name in IDENTITY:
+            value = getattr(self, name)
+            if value is not None and (isinstance(value, bool)
+                                      or not isinstance(value, numbers.Integral) or value < 1):
+                raise ValueError(f"{name} must be a whole number from 1, got {value!r}.")
+        if self.atom is not None and self.ion is not None and self.ion > self.atom + 1:
+            raise ValueError(f"ion {self.ion} is beyond the last stage of atom {self.atom}, "
+                             f"{self.atom + 1}.")
+        rest = _checked(self.rest_wavelength, "rest_wavelength", ndim=0, kinds=("length",))
+        if not wavelength[0] <= rest <= wavelength[-1]:
+            raise ValueError(f"rest_wavelength {rest} is outside the wavelengths, "
+                             f"which run from {wavelength[0]} to {wavelength[-1]}.")
+        intensity = _checked(self.intensity, "intensity", ndim=3)
+        # A trial conversion rejects any unit that is not a spectral radiance.
+        to_radiance(1.0 * intensity.unit, wavelength[0])
+        if intensity.shape[-1] != wavelength.size:
+            raise ValueError(
+                f"intensity has {intensity.shape[-1]} wavelengths along its last "
+                f"axis but there are {wavelength.size}. The intensity is "
+                f"(y, x, wavelength): y along the slit first.")
+        if np.any(intensity.value < 0):
+            raise ValueError("intensity has negative values, which no spectral "
+                             "radiance can have.")
+
+    def radiance(self) -> u.Quantity:
+        """Intensity in erg / (s cm2 sr cm), the unit of ECLIPSE's own synthesis."""
+        return to_radiance(self.intensity, self.wavelength)
+
+
+@dataclass(frozen=True)
+class Synthesis:
+    """
+    Spectra over an image, line by line, for the instrument simulation.
+
+    Parameters
+    ----------
+    lines : mapping of str to SpectralLine
+        Lines keyed by the names `reference_line` uses in the instrument
+        configuration. All share the image.
+    x_edges, y_edges : u.Quantity
+        Pixel boundaries, evenly spaced, as lengths on the Sun or angles seen
+        from 1 AU. x runs across the slit and y along it.
+    source : str, optional
+        Free text naming the code and the model, kept in the file.
+    time : u.Quantity, optional
+        Time of the snapshot, needed to place it in a time series of
+        synthesis files.
+    integration_axis : str, optional
+        View: the simulation axis the image was seen along, `"x"`, `"y"` or
+        `"z"`, which names the image axes of the cubes made from it. A sign,
+        such as `"-x"`, gives the side of the box it was seen from. None
+        means seen along z.
+    """
+
+    lines: Mapping[str, SpectralLine]
+    x_edges: u.Quantity
+    y_edges: u.Quantity
+    source: str = ""
+    time: Optional[u.Quantity] = None
+    integration_axis: Optional[str] = None
+
+    def __post_init__(self):
+        if self.time is not None:
+            _checked(self.time, "time", ndim=0, kinds=("time",))
+        if self.integration_axis is not None:
+            try:
+                view = view_name(self.integration_axis)
+            except ValueError:
+                raise ValueError(f"integration_axis must be one of 'x', 'y', 'z', '+x', '-x', "
+                                 f"'+y', '-y', '+z', '-z' or None, got "
+                                 f"{self.integration_axis!r}.") from None
+            # Normalise the name, so "+x" and "x" are the same view.
+            object.__setattr__(self, "integration_axis", view)
+        for axis in AXES:
+            name = EDGES[axis]
+            edges = _checked(getattr(self, name), name, ndim=1, kinds=("length", "angle"))
+            # The instrument grid uses one pixel size per axis, so the edges
+            # must be evenly spaced.
+            require_uniform_grid(edges.value, name)
+        if not isinstance(self.lines, Mapping) or not self.lines:
+            raise ValueError("A synthesis needs at least one line, as a mapping "
+                             "from its name to a SpectralLine.")
+        for name, line in self.lines.items():
+            if not isinstance(name, str) or not name or "/" in name:
+                raise ValueError(f"A line's name must be a string without '/', "
+                                 f"got {name!r}.")
+            if not isinstance(line, SpectralLine):
+                raise TypeError(f"Line {name!r} must be a SpectralLine, got "
+                                f"{type(line).__name__}.")
+            if line.intensity.shape[:2] != self.shape:
+                raise ValueError(
+                    f"Line {name!r} has an image of {line.intensity.shape[:2]} pixels "
+                    f"but the edges give (ny, nx) = {self.shape}. The intensity is "
+                    f"(y, x, wavelength): y along the slit first.")
+        if not isinstance(self.source, str):
+            raise TypeError(f"source must be a string, got "
+                            f"{type(self.source).__name__}.")
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Image shape, `(ny, nx)`."""
+        return (self.y_edges.size - 1, self.x_edges.size - 1)
+
+    def pixel_size(self, axis: str) -> u.Quantity:
+        """Pixel size along `axis` on the Sun, in Mm."""
+        edges = getattr(self, EDGES[_check_axis(axis)])
+        return _to_length(require_uniform_grid(edges.value, EDGES[axis]) * edges.unit)
+
+    def centre(self, axis: str) -> u.Quantity:
+        """Centre of the image along `axis` on the Sun, in Mm."""
+        edges = getattr(self, EDGES[_check_axis(axis)])
+        return _to_length(0.5 * (edges[0] + edges[-1]))
+
+    def summed(self, reference: str) -> u.Quantity:
+        """
+        Sum of all lines' radiance on the wavelengths of line `reference`.
+
+        This is what the instrument observes when it measures `reference`.
+        Each line is averaged onto the reference wavelength bins, conserving
+        flux, and is zero outside its own wavelength range. Lines reaching
+        the reference window add to it as blends; the others add nothing.
+        """
+        if reference not in self.lines:
+            raise ValueError(f"No line is named {reference!r}; the lines are "
+                             f"{list(self.lines)}.")
+        wavelength = self.lines[reference].wavelength
+        total = np.zeros(self.shape + (wavelength.size,))
+        for line in self.lines.values():
+            total += onto_wavelength_bins(line.radiance().to_value(RADIANCE_UNIT),
+                                          line.wavelength.to_value(wavelength.unit),
+                                          wavelength.value)
+        return total * RADIANCE_UNIT
+
+    def evenly_spaced(self, name: str) -> bool:
+        """Whether line `name` has evenly spaced wavelengths, as a WCS needs."""
+        try:
+            require_uniform_grid(self.lines[name].wavelength.value, "wavelength")
+        except ValueError:
+            return False
+        return True
+
+    def line_meta(self, name: str) -> dict:
+        """Metadata of line `name`, as in ECLIPSE's line cubes."""
+        from .utils import VELOCITY_CONVENTION
+
+        line = self.lines[name]
+        return {"line_name": name, "rest_wav": line.rest_wavelength,
+                "integration_axis": self.integration_axis or "z", "source": self.source,
+                "velocity_convention": VELOCITY_CONVENTION,
+                **{key: getattr(line, key) for key in IDENTITY
+                   if getattr(line, key) is not None}}
+
+    def summed_meta(self, reference: str) -> dict:
+        """
+        Metadata for `summed`: that of `reference` plus the names of the summed lines.
+        """
+        return {**self.line_meta(reference), "combined_lines": list(self.lines),
+                "n_lines": len(self.lines), "metadata_source": reference,
+                "summed_intensity": True}
+
+    def line_cube(self, name: str):
+        """
+        Line `name` as an NDCube, indexed `[y, x, wavelength]`, in erg / (s cm2 sr cm).
+
+        The wavelengths must be evenly spaced for the cube's WCS to describe
+        them.
+        """
+        return self._cube(self.lines[name].radiance(), name, self.line_meta(name))
+
+    def summed_cube(self, reference: str, summed: Optional[u.Quantity] = None,
+                    meta: Optional[Mapping] = None):
+        """
+        `summed` as an NDCube on the wavelengths of `reference`.
+
+        The reference wavelengths must be evenly spaced. The `summed`
+        argument, if given, is the result of `summed` already computed.
+        `meta` is added to `summed_meta`.
+        """
+        return self._cube(self.summed(reference) if summed is None else summed, reference,
+                          {**self.summed_meta(reference), **(meta or {})})
+
+    def _cube(self, data: u.Quantity, name: str, meta: dict):
+        from astropy.wcs import WCS
+        from ndcube import NDCube
+
+        line = self.lines[name]
+        step = require_uniform_grid(line.wavelength.to_value(u.cm), f"the wavelengths of {name}")
+        ny, nx = self.shape
+        n_wavelength = line.wavelength.size
+        wcs = WCS(naxis=3)
+        axis, _ = view_axis_and_side(self.integration_axis or "z")
+        wcs.wcs.ctype = ["WAVE", *_VIEW_CTYPES[axis]]
+        wcs.wcs.cunit = ["cm", "Mm", "Mm"]
+        wcs.wcs.crpix = [(n_wavelength + 1) / 2, (nx + 1) / 2, (ny + 1) / 2]
+        middle = 0.5 * (line.wavelength[0] + line.wavelength[-1])
+        wcs.wcs.crval = [middle.to_value(u.cm), self.centre("x").to_value(u.Mm),
+                         self.centre("y").to_value(u.Mm)]
+        wcs.wcs.cdelt = [step, self.pixel_size("x").to_value(u.Mm),
+                         self.pixel_size("y").to_value(u.Mm)]
+        return NDCube(data.value, wcs=wcs, unit=data.unit, meta=meta)
+
+
+def _check_axis(axis: str) -> str:
+    if axis not in AXES:
+        raise ValueError(f"axis must be one of {AXES}, got {axis!r}.")
+    return axis
+
+
+# ----------------------------------------------------------------------
+# HDF5
+# ----------------------------------------------------------------------
+def is_synthesis_file(path: str | Path) -> bool:
+    """Whether `path` is HDF5, as synthesis files are, rather than an older pickle."""
+    return h5py.is_hdf5(str(path))
+
+
+def synthesis_line_names(path: str | Path) -> list:
+    """Names of the lines in a synthesis file, in file order, without reading the spectra."""
+    path = Path(path)
+    with _open_to_read(path, "synthesis") as f:
+        _check_format(f, path, kind="synthesis", format_name=FORMAT_NAME,
+                      format_version=FORMAT_VERSION)
+        return list(f["lines"]) if "lines" in f else []
+
+
+def write_synthesis(synthesis: Synthesis, path: str | Path,
+                    products: Optional[Mapping] = None,
+                    compression: Optional[str] = None) -> Path:
+    """
+    Write a synthesis file.
+
+    The file is written to a new file beside it and then moved into place,
+    so a run stopped part way leaves any existing file unchanged.
+
+    Parameters
+    ----------
+    synthesis : Synthesis
+        Spectra to write.
+    path : str or Path
+        File to write. An existing file is replaced.
+    products : mapping, optional
+        Intermediate products of the synthesis, stored in the file's
+        `synthesis` group and read back by `read_synthesis_products`.
+    compression : str, optional
+        HDF5 compression filter for the spectra, such as `"gzip"`. Default
+        None (uncompressed), which reads fastest.
+
+    Returns
+    -------
+    Path
+        Path of the written file.
+    """
+    path = Path(path)
+    with _replacing(path) as partial, h5py.File(partial, "w") as f:
+        f.attrs["format"] = FORMAT_NAME
+        f.attrs["version"] = FORMAT_VERSION
+        f.attrs["source"] = synthesis.source
+        if synthesis.integration_axis is not None:
+            f.attrs["integration_axis"] = synthesis.integration_axis
+        for axis in AXES:
+            _write_dataset(f, EDGES[axis], getattr(synthesis, EDGES[axis]))
+        if synthesis.time is not None:
+            _write_dataset(f, "time", synthesis.time)
+        # Keep the given line order, which HDF5 would otherwise sort by name.
+        group = f.create_group("lines", track_order=True)
+        for name, line in synthesis.lines.items():
+            entry = group.create_group(name)
+            _write_dataset(entry, "intensity", line.intensity, compression=compression)
+            _write_dataset(entry, "wavelength", line.wavelength)
+            _write_dataset(entry, "rest_wavelength", line.rest_wavelength)
+            for key in IDENTITY:
+                if getattr(line, key) is not None:
+                    entry.attrs[key] = int(getattr(line, key))
+        if products:
+            _write_tree(f.create_group("synthesis", track_order=True), products)
+    return path
+
+
+def read_synthesis(path: str | Path, reference_line: Optional[str] = None,
+                   columns: Optional[slice] = None) -> Synthesis:
+    """
+    Read the spectra of a synthesis file, on their original wavelengths.
+
+    Parameters
+    ----------
+    path : str or Path
+        Synthesis file.
+    reference_line : str, optional
+        Read only the lines that reach this line's spectral window. Default
+        None reads every line.
+    columns : slice, optional
+        Contiguous slice of pixels along x to read. Default None reads the
+        whole image.
+
+    Returns
+    -------
+    Synthesis
+        Spectra in the file.
+    """
+    path = Path(path)
+    with _open_to_read(path, "synthesis") as f:
+        _check_format(f, path, kind="synthesis", format_name=FORMAT_NAME,
+                      format_version=FORMAT_VERSION)
+        edges = {EDGES[axis]: _read_dataset(f, EDGES[axis], units=UNITS) for axis in AXES}
+        if columns is not None:
+            nx = edges["x_edges"].size - 1
+            first = 0 if columns.start is None else columns.start
+            last = nx if columns.stop is None else columns.stop
+            if columns.step not in (None, 1) or not 0 <= first < last <= nx:
+                raise ValueError(f"columns must be a slice of neighbouring pixels among the "
+                                 f"{nx} along x, got {columns}.")
+            edges["x_edges"] = edges["x_edges"][first:last + 1]
+            columns = slice(first, last)
+        group, names = _lines_reaching(f, path, reference_line)
+        lines = {}
+        for name in names:
+            entry = group[name]
+            fields = {"intensity": _read_dataset(entry, "intensity", columns, units=UNITS, axis=1),
+                      "wavelength": _read_dataset(entry, "wavelength", units=UNITS),
+                      "rest_wavelength": _read_dataset(entry, "rest_wavelength", units=UNITS),
+                      **_identity(entry)}
+            try:
+                lines[name] = SpectralLine(**fields)
+            except (TypeError, ValueError) as error:
+                raise type(error)(f"{path}, line {name!r}: {error}") from None
+        source, integration_axis = _source(f), _integration_axis(f)
+        time = _read_dataset(f, "time", units=UNITS) if "time" in f else None
+    try:
+        return Synthesis(lines=lines, source=source, time=time,
+                         integration_axis=integration_axis, **edges)
+    except (TypeError, ValueError) as error:
+        raise type(error)(f"{path}: {error}") from None
+
+
+def read_synthesis_layout(path: str | Path, reference_line: Optional[str] = None) -> dict:
+    """
+    Contents of a synthesis file, without reading the spectra.
+
+    Returns a dict of `x_edges`, `y_edges`, `time` (None if absent),
+    `source`, `integration_axis` (None if absent) and `lines`. `lines` maps
+    each line, or each one reaching the window of `reference_line` if
+    given, to its `wavelength`, `rest_wavelength`, `identity` (its `atom`
+    and `ion`, where the file gives them) and the `shape` of its intensity.
+    A time series uses it to check its files before reading any spectra.
+    """
+    path = Path(path)
+    with _open_to_read(path, "synthesis") as f:
+        _check_format(f, path, kind="synthesis", format_name=FORMAT_NAME,
+                      format_version=FORMAT_VERSION)
+        layout = {EDGES[axis]: _read_dataset(f, EDGES[axis], units=UNITS) for axis in AXES}
+        layout["time"] = None
+        if "time" in f:
+            try:
+                layout["time"] = _checked(_read_dataset(f, "time", units=UNITS), "time",
+                                          ndim=0, kinds=("time",))
+            except (TypeError, ValueError) as error:
+                raise type(error)(f"{path}: {error}") from None
+        layout["source"] = _source(f)
+        layout["integration_axis"] = _integration_axis(f)
+        group, names = _lines_reaching(f, path, reference_line)
+        layout["lines"] = {}
+        for name in names:
+            entry = group[name]
+            if "intensity" not in entry:
+                raise ValueError(f"{path}, line {name!r} has no 'intensity' dataset.")
+            layout["lines"][name] = {
+                "wavelength": _read_dataset(entry, "wavelength", units=UNITS),
+                "rest_wavelength": _read_dataset(entry, "rest_wavelength", units=UNITS),
+                "identity": _identity(entry), "shape": entry["intensity"].shape}
+    return layout
+
+
+def _lines_reaching(f: h5py.File, path: Path, reference_line: Optional[str]):
+    """
+    The file's `lines` group and the names of its lines.
+
+    Only the lines reaching the window of `reference_line` are named, or all
+    of them if it is None.
+    """
+    group = f.get("lines")
+    if group is None or len(group) == 0:
+        raise ValueError(f"{path} holds no lines.")
+    names = list(group)
+    if reference_line is not None:
+        if reference_line not in group:
+            raise ValueError(f"'reference_line' {reference_line!r} is not in {path}; "
+                             f"its lines are {names}.")
+        window = _line_wavelength(group, reference_line, path)
+        names = [name for name in names
+                 if _reaches(_line_wavelength(group, name, path), window)]
+    return group, names
+
+
+def _line_wavelength(group: h5py.Group, name: str, path: Path) -> u.Quantity:
+    """
+    Wavelengths of line `name`, checked as when the line is read.
+
+    They decide whether the line reaches the window, so a line with
+    unreadable wavelengths raises an error rather than being skipped.
+    """
+    wavelength = _read_dataset(group[name], "wavelength", units=UNITS)
+    try:
+        return _check_wavelength(wavelength)
+    except (TypeError, ValueError) as error:
+        raise type(error)(f"{path}, line {name!r}: {error}") from None
+
+
+def _source(f: h5py.File) -> str:
+    return str(_text_attribute(f.attrs, "source", ""))
+
+
+def _identity(entry: h5py.Group) -> dict:
+    """A line's atom and ion, where its group gives them."""
+    return {key: int(entry.attrs[key]) for key in IDENTITY if key in entry.attrs}
+
+
+def _integration_axis(f: h5py.File) -> Optional[str]:
+    axis = _text_attribute(f.attrs, "integration_axis")
+    return None if axis is None else str(axis)
+
+
+def _reaches(wavelength: u.Quantity, window: u.Quantity) -> bool:
+    """
+    Whether a line sampled at `wavelength` has any part inside `window`.
+
+    Each wavelength covers the bin halfway to its neighbours, as in the sum
+    of the lines, so a line reaches the window if its outermost bin
+    overlaps the window's, even when all its wavelengths lie outside.
+    """
+    own, window = wavelength.to_value(window.unit), window.value
+    if own.size < 2 or window.size < 2:
+        # Too few values to form bins; the line is rejected when it is read.
+        return own.max() >= window.min() and own.min() <= window.max()
+    own, window = _bin_edges(own), _bin_edges(window)
+    return own[-1] > window[0] and own[0] < window[-1]
+
+
+def read_synthesis_products(path: str | Path, keys: Optional[Iterable[str]] = None) -> dict:
+    """
+    Intermediate products of ECLIPSE's synthesis.
+
+    For a file from `synthesise-spectra` these are:
+
+    - `dem_map`: DEM in each pixel, on the temperatures `logT_grid`.
+    - `em_tv`: emission measure in each pixel by temperature and velocity,
+      on the velocities `vel_grid`.
+    - `electron_density`: electron density in cm^-3 at which the
+      contribution functions were evaluated, at each temperature of each
+      pixel, same shape as `dem_map`. It is the mean over the cells,
+      weighted by their emission measure.
+    - `goft`: each line's contribution function, on the temperatures and
+      the densities `logN_grid`.
+    - `voxel_sizes`, `atmosphere`, `dynamic_mode` and `config`: the
+      atmosphere and the settings of the synthesis.
+
+    A file from another code has none of these and gives an empty dict.
+    Tuples are returned as lists, and dictionary keys as strings.
+
+    Parameters
+    ----------
+    path : str or Path
+        Synthesis file.
+    keys : iterable of str, optional
+        Products to read. Leaving out `em_tv`, often the largest part of the
+        file, saves time. Default None reads everything.
+
+    Returns
+    -------
+    dict
+        Products keyed by name.
+    """
+    path = Path(path)
+    with _open_to_read(path, "synthesis") as f:
+        _check_format(f, path, kind="synthesis", format_name=FORMAT_NAME,
+                      format_version=FORMAT_VERSION)
+        if "synthesis" not in f:
+            return {}
+        if isinstance(keys, str):
+            keys = [keys]
+        return _read_tree(f["synthesis"], None if keys is None else set(keys))
+
+
+def load_synthesis(path: str | Path) -> dict:
+    """
+    Everything in a synthesis file: line cubes and synthesis products.
+
+    The line cubes need evenly spaced wavelengths, as ECLIPSE's own synthesis
+    writes them. For a file with uneven wavelengths, use `read_synthesis`.
+
+    Parameters
+    ----------
+    path : str or Path
+        Synthesis file.
+
+    Returns
+    -------
+    dict
+        `line_cubes`, an NDCube per line indexed `[y, x, wavelength]` in
+        erg / (s cm2 sr cm), plus the products from
+        `read_synthesis_products`.
+    """
+    synthesis = read_synthesis(path)
+    uneven = [name for name in synthesis.lines if not synthesis.evenly_spaced(name)]
+    if uneven:
+        raise ValueError(
+            f"{path}: the wavelengths of {', '.join(uneven)} are not evenly spaced, which "
+            f"the WCS of an NDCube cannot describe. Read the file with read_synthesis, "
+            f"which keeps each line's wavelengths as they are.")
+    line_cubes = {name: synthesis.line_cube(name) for name in synthesis.lines}
+    return {"line_cubes": line_cubes, **read_synthesis_products(path)}
+
+
+# The products are nested dicts of arrays and plain values. Arrays and
+# non-scalar Quantities become datasets. Everything else becomes a JSON
+# attribute, with Quantities stored as value and unit so they read back as
+# Quantities.
+def _write_tree(group: h5py.Group, tree: Mapping) -> None:
+    for key, value in tree.items():
+        key = str(key)
+        if _is_array(value):
+            data = value.value if isinstance(value, u.Quantity) else np.asarray(value)
+            dataset = group.create_dataset(key, data=data, compression="gzip",
+                                           compression_opts=1)
+            if isinstance(value, u.Quantity):
+                dataset.attrs["unit"] = value.unit.to_string()
+        elif isinstance(value, Mapping) and any(_holds_array(v) for v in value.values()):
+            _write_tree(group.create_group(key, track_order=True), value)
+        else:
+            group.attrs[key] = json.dumps(_jsonable(value))
+
+
+def _read_tree(group: h5py.Group, keys: Optional[set]) -> dict:
+    tree = {}
+    for key, value in group.attrs.items():
+        if keys is None or key in keys:
+            tree[key] = json.loads(value, object_hook=_unjson)
+    for key, item in group.items():
+        if keys is not None and key not in keys:
+            continue
+        if isinstance(item, h5py.Group):
+            tree[key] = _read_tree(item, None)
+        else:
+            data = item[()]
+            unit = item.attrs.get("unit")
+            tree[key] = data if unit is None else u.Quantity(data, u.Unit(
+                unit.decode() if isinstance(unit, bytes) else unit))
+    return tree
+
+
+def _is_array(value) -> bool:
+    return (isinstance(value, np.ndarray) and value.ndim > 0) or (
+        isinstance(value, u.Quantity) and value.ndim > 0)
+
+
+def _holds_array(value) -> bool:
+    if _is_array(value):
+        return True
+    return isinstance(value, Mapping) and any(_holds_array(v) for v in value.values())
+
+
+def _jsonable(value):
+    if isinstance(value, u.Quantity):
+        return {"__quantity__": _jsonable(value.value), "unit": value.unit.to_string()}
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, Mapping):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    if isinstance(value, Path):
+        return str(value)
+    return value
+
+
+def _unjson(value: dict):
+    if "__quantity__" in value:
+        return u.Quantity(value["__quantity__"], u.Unit(value["unit"]))
+    return value
+
+
+# ----------------------------------------------------------------------
+# From ECLIPSE's line cubes
+# ----------------------------------------------------------------------
+def write_line_cubes(line_cubes: Mapping, path: str | Path, source: str = "",
+                     products: Optional[Mapping] = None,
+                     time: Optional[u.Quantity] = None) -> Path:
+    """
+    Write ECLIPSE line cubes as a synthesis file.
+
+    Each cube keeps its values, wavelengths, rest wavelength, atom and ion.
+    The cubes must share one image, which is taken from the first cube's
+    coordinates.
+
+    Parameters
+    ----------
+    line_cubes : mapping of str to NDCube
+        Cubes keyed by line name, indexed `[y, x, wavelength]`, with
+        `rest_wav` in their metadata, as made by `create_line_cube`.
+    path : str or Path
+        File to write. An existing file is replaced.
+    source : str, optional
+        Free text naming the simulation.
+    products : mapping, optional
+        Intermediate products of the synthesis; see `write_synthesis`.
+    time : u.Quantity, optional
+        Time of the snapshot.
+
+    Returns
+    -------
+    Path
+        Path of the written file.
+    """
+    cubes = dict(line_cubes)
+    if not cubes:
+        raise ValueError("There are no line cubes to write.")
+    first_name, first = next(iter(cubes.items()))
+    edges = {"x_edges": _pixel_edges(first, 1), "y_edges": _pixel_edges(first, 2)}
+    lines = {}
+    for name, cube in cubes.items():
+        if cube.data.shape[:2] != first.data.shape[:2]:
+            raise ValueError(f"Line {name!r} has an image of {cube.data.shape[:2]} "
+                             f"pixels, not {first.data.shape[:2]} as the others.")
+        # All lines share one image, so a cube of the same shape but at another
+        # position or with other pixel sizes would land on the wrong pixels.
+        for axis, wcs_axis in (("x", 1), ("y", 2)):
+            if not _same_grid(_pixel_edges(cube, wcs_axis), edges[f"{axis}_edges"]):
+                raise ValueError(f"Line {name!r} has other pixel positions along {axis} "
+                                 f"than {first_name!r}; the lines of a synthesis file "
+                                 f"share one image.")
+        meta = cube.meta or {}
+        lines[name] = SpectralLine(intensity=np.asarray(cube.data) * cube.unit,
+                                   wavelength=cube.axis_world_coords_values(-1)[0],
+                                   rest_wavelength=meta["rest_wav"],
+                                   **{key: int(meta[key]) for key in IDENTITY
+                                      if meta.get(key) is not None})
+    # Store the view, which names the image axes, so the cubes read back as
+    # written. A cube without one is taken as seen along z.
+    views = {(cube.meta or {}).get("integration_axis") or "z" for cube in cubes.values()}
+    if len(views) > 1:
+        raise ValueError(f"The line cubes were seen along different axes, {sorted(views)}; "
+                         f"the lines of a synthesis file share one image.")
+    synthesis = Synthesis(lines=lines, source=source, time=time,
+                          integration_axis=views.pop(), **edges)
+    return write_synthesis(synthesis, path, products=products)
+
+
+def _pixel_edges(cube, wcs_axis: int) -> u.Quantity:
+    """Pixel boundaries along one image axis of `cube`, from its WCS, in Mm."""
+    wcs = getattr(cube.wcs, "low_level_wcs", cube.wcs)
+    n = cube.data.shape[::-1][wcs_axis]
+    points = np.zeros((n + 1, wcs.pixel_n_dim))
+    points[:, wcs_axis] = np.arange(n + 1) - 0.5
+    world = wcs.pixel_to_world_values(*points.T)
+    return (np.asarray(world[wcs_axis]) * u.Unit(wcs.world_axis_units[wcs_axis])).to(u.Mm)
+
+
+def convert_synthesis_pickle(pickle_path: str | Path, path: str | Path) -> Path:
+    """
+    Convert a synthesis pickle from ECLIPSE 0.11.0 or earlier to a synthesis file.
+
+    Everything in the pickle is kept: the line cubes as the spectra and the
+    rest as the synthesis products. A pickle made before the axis order or
+    the velocity convention changed is rejected, as `eclipse` rejects it.
+    Loading a pickle runs any code it contains, so only convert pickles you
+    trust.
+
+    Parameters
+    ----------
+    pickle_path : str or Path
+        Pickle to convert.
+    path : str or Path
+        Synthesis file to write. Must not be the pickle itself.
+
+    Returns
+    -------
+    Path
+        Path of the written file.
+    """
+    # Only duplicates of kept data are dropped: each line's spectra (si) and
+    # wavelengths (wl_grid) in goft, and the atmosphere metadata each line
+    # cube carried as spatial_reference.
+    from .data_processing import check_old_line_cubes
+
+    # Writing over the pickle would destroy the only copy of its synthesis.
+    if Path(path).expanduser().resolve() == Path(pickle_path).expanduser().resolve():
+        raise ValueError(f"{path} is the pickle being converted; give the synthesis file "
+                         f"another name, such as {Path(pickle_path).with_suffix('.h5').name}.")
+    with open(pickle_path, "rb") as f:
+        saved = _unpickle(f)
+    if "line_cubes" not in saved or not saved["line_cubes"]:
+        raise ValueError(f"{pickle_path} holds no line cubes.")
+    check_old_line_cubes(saved["line_cubes"], pickle_path)
+    products = {key: value for key, value in saved.items() if key != "line_cubes"}
+    goft = products.get("goft")
+    if isinstance(goft, Mapping):
+        # si and wl_grid repeat the spectra and wavelengths of the line cubes.
+        products["goft"] = {name: {key: value for key, value in info.items()
+                                   if key not in ("si", "wl_grid")}
+                            for name, info in goft.items()}
+    atmosphere = products.get("atmosphere") or {}
+    time = atmosphere.get("time")
+    return write_line_cubes(saved["line_cubes"], path, source=str(atmosphere.get("source") or ""),
+                            products=products,
+                            time=time if isinstance(time, u.Quantity) else None)