utu 0.1.0__py3-none-any.whl

utu/__init__.py

@@ -0,0 +1,9 @@
+"""Solar physics utilities built on named arrays."""
+
+from . import spectrum
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "spectrum",
+]

utu/_tests/test_utu.py

@@ -0,0 +1,7 @@
+import utu
+
+
+def test_version():
+    """The package reports the version setuptools-scm gave it."""
+    assert isinstance(utu.__version__, str)
+    assert utu.__version__

utu/_version.py

@@ -0,0 +1,8 @@
+import importlib.metadata
+
+__all__ = [
+    "__version__",
+]
+
+__version__ = importlib.metadata.version("utu")
+"""The version of this package, taken from the tag it was built from."""

utu/spectrum/__init__.py

@@ -0,0 +1,17 @@
+"""The spectrum of an optically thin plasma, from the CHIANTI atomic database."""
+
+from ._lines import (
+    contribution_function,
+    ions,
+    lines,
+)
+from ._names import spectroscopic
+from ._plots import stem
+
+__all__ = [
+    "contribution_function",
+    "ions",
+    "lines",
+    "spectroscopic",
+    "stem",
+]

utu/spectrum/_lines.py

@@ -0,0 +1,404 @@
+"""The emission lines of an optically thin plasma."""
+
+import functools
+
+import astropy.units as u
+import fiasco
+import named_arrays as na
+import numpy as np
+
+__all__ = [
+    "contribution_function",
+    "ions",
+    "lines",
+]
+
+
+def ions(
+    wavelength_min: None | u.Quantity | na.AbstractScalar = None,
+    wavelength_max: None | u.Quantity | na.AbstractScalar = None,
+    abundance_min: float = 1e-5,
+    **kwargs: object,
+) -> list[str]:
+    r"""
+    Find the ions worth computing over a range of wavelengths.
+
+    An ion is worth computing if its element is abundant enough to contribute
+    and if it has a line in the range at all. Reading the line list of an ion
+    is cheap; solving its level populations is not, and this is how the
+    second is avoided for ions which cannot matter.
+
+    Parameters
+    ----------
+    wavelength_min
+        The shortest wavelength worth looking at.
+        If :obj:`None` (the default), there is no lower bound.
+    wavelength_max
+        The longest wavelength worth looking at.
+        If :obj:`None` (the default), there is no upper bound.
+    abundance_min
+        The abundance, relative to hydrogen, below which an element is not
+        worth including.
+    kwargs
+        Additional arguments passed to :class:`fiasco.Ion`.
+
+    Notes
+    -----
+    Which ions come back is a statement about the database as much as about
+    the wavelengths: an ion the database does not describe cannot be
+    returned, and the databases built for a documentation page or a test
+    suite describe only a few.
+
+    The database is read on the first call and remembered afterwards, so the
+    first call takes a few seconds and the rest take none. What is
+    remembered is the wavelengths of the lines of the ions abundant enough
+    to pass ``abundance_min``, a few megabytes.
+
+    Examples
+    --------
+    The line ESIS was built to observe is a line of :math:`\mathrm{O\,V}`.
+
+    .. jupyter-execute::
+
+        import astropy.units as u
+        import utu
+
+        "O 5" in utu.spectrum.ions(
+            wavelength_min=629 * u.AA,
+            wavelength_max=630 * u.AA,
+        )
+    """
+    wavelength_min = _quantity(wavelength_min)
+    wavelength_max = _quantity(wavelength_max)
+
+    result = []
+
+    for name, w in _catalog(abundance_min, **kwargs).items():
+        where = np.ones(w.shape, dtype=bool)
+        if wavelength_min is not None:
+            where = where & (w > wavelength_min)
+        if wavelength_max is not None:
+            where = where & (w < wavelength_max)
+        if not np.any(where):
+            continue
+        result.append(name)
+
+    return result
+
+
+def _quantity(
+    value: None | u.Quantity | na.AbstractScalar,
+) -> None | u.Quantity:
+    """
+    A value as a plain quantity, however it was given.
+
+    :mod:`fiasco` is not a named-arrays library, and neither are the line
+    lists it returns, so anything handed to it or compared against it has to
+    shed its axes on the way.
+    """
+    if isinstance(value, na.AbstractArray):
+        return value.ndarray
+    return value
+
+
+@functools.cache
+def _catalog(
+    abundance_min: float,
+    **kwargs: object,
+) -> dict[str, u.Quantity]:
+    """
+    The wavelengths of every line of every ion abundant enough to matter.
+
+    Read once and remembered afterwards. The database does not change while
+    a program runs, and reading it is where nearly all the time of
+    :func:`ions` goes: five hundred ions at about thirty milliseconds each,
+    almost none of it spent on the file.
+    """
+    result = {}
+
+    for name in fiasco.list_ions():
+        try:
+            ion = fiasco.Ion(name, 1 * u.MK, **kwargs)
+
+            if ion.abundance is None or ion.abundance < abundance_min:
+                continue
+
+            transitions = ion.transitions
+            if transitions is None:  # pragma: nocover
+                continue
+
+            wavelength = transitions.wavelength
+
+        except Exception:
+            # an ion the database cannot describe is an ion which cannot
+            # contribute, and there are a handful of them
+            continue
+
+        result[str(name)] = wavelength
+
+    return result
+
+
+_ions = ions
+"""
+A private alias for :func:`ions`, so that :func:`lines` can take a parameter
+of that name without hiding the function it falls back on.
+"""
+
+
+def contribution_function(
+    ion: fiasco.Ion,
+    density: u.Quantity | na.AbstractScalar,
+    axis_temperature: str,
+    axis: str = "line",
+    proton_electron_ratio: None | u.Quantity | na.AbstractScalar = None,
+) -> na.FunctionArray:
+    """
+    Compute the contribution function of every line of an ion.
+
+    Returned as a function of wavelength, so that a line and its strength
+    cannot come apart. They are separate arrays underneath, of different
+    lengths whenever an ion has a two-photon transition, and pairing them by
+    hand is a way to label every line with its neighbor's wavelength.
+
+    Whether the temperatures and the densities are taken in pairs or as a
+    grid is decided by their axes. A density which shares the axis of the
+    temperature describes one density per temperature, an isobaric
+    atmosphere for instance, and is computed as such. A density on an axis of
+    its own describes every density at every temperature, and costs as many
+    times more.
+
+    Parameters
+    ----------
+    ion
+        The ion to compute the contribution function of.
+    density
+        The number density of electrons.
+    axis_temperature
+        The name of the axis of the temperature of ``ion``.
+    axis
+        The name to give the axis along the lines of the result.
+    proton_electron_ratio
+        The ratio of protons to electrons at each temperature of ``ion``.
+        If :obj:`None` (the default), :mod:`fiasco` computes it, which walks
+        the whole database and takes an order of magnitude longer than the
+        rest of this function put together. It depends on the temperature
+        and on nothing else, so a caller with more than one ion should
+        compute it once with :func:`fiasco.proton_electron_ratio` and pass
+        it here. Doing so primes the cache of ``ion`` with the value it
+        would otherwise have computed for itself.
+
+    Examples
+    --------
+    The contribution function of the line ESIS was built to observe, which
+    peaks at the temperature the line is formed at.
+
+    .. jupyter-execute::
+
+        import astropy.units as u
+        import fiasco
+        import matplotlib.pyplot as plt
+        import named_arrays as na
+        import numpy as np
+        import utu
+
+        axis = "temperature"
+        temperature = na.geomspace(1e4, 1e7, axis=axis, num=61) * u.K
+
+        ion = fiasco.Ion("O 5", temperature.ndarray)
+
+        result = utu.spectrum.contribution_function(
+            ion=ion,
+            density=1e15 * u.K / u.cm ** 3 / temperature,
+            axis_temperature=axis,
+        )
+
+        # the strongest line of the ion, at 629.7 angstroms
+        index = np.argmax(result.outputs.max(axis), axis="line")
+
+        fig, ax = plt.subplots(constrained_layout=True)
+        na.plt.plot(
+            temperature,
+            result.outputs[index],
+            ax=ax,
+            axis=axis,
+        )
+        ax.set_xscale("log")
+        ax.set_xlabel(f"temperature ({temperature.unit:latex_inline})")
+        ax.set_ylabel(f"$G(T)$ ({result.outputs.unit:latex_inline})")
+    """
+    if proton_electron_ratio is not None:
+        ion.__dict__["proton_electron_ratio"] = _quantity(proton_electron_ratio)
+
+    axis_density = tuple(na.shape(density))
+
+    coupled = tuple(axis_density) == (axis_temperature,)
+
+    result = ion.contribution_function(
+        na.as_named_array(density).ndarray,
+        couple_density_to_temperature=coupled,
+    )
+
+    # the last axis of the result runs over the bound-bound transitions, so
+    # that is the wavelength which belongs to it
+    transitions = ion.transitions
+    wavelength = transitions.wavelength[transitions.is_bound_bound]
+
+    axes = (axis_temperature, "_density", axis)
+    result = na.ScalarArray(result, axes=axes)
+    if coupled:
+        result = result[{"_density": 0}]
+
+    return na.FunctionArray(
+        inputs=na.ScalarArray(wavelength, axes=(axis,)),
+        outputs=result,
+    )
+
+
+def lines(
+    temperature: na.AbstractScalar,
+    density: u.Quantity | na.AbstractScalar,
+    emission_measure: u.Quantity | na.AbstractScalar,
+    wavelength_min: None | u.Quantity | na.AbstractScalar = None,
+    wavelength_max: None | u.Quantity | na.AbstractScalar = None,
+    ions: None | list[str] = None,
+    proton_electron_ratio: None | u.Quantity | na.AbstractScalar = None,
+    axis_temperature: str = "temperature",
+    axis: str = "line",
+    **kwargs: object,
+) -> na.FunctionArray:
+    """
+    Compute the emission lines of an optically thin plasma, brightest first.
+
+    Every line of every ion abundant enough to contribute, with the intensity
+    it would have from a plasma with the given emission measure.
+
+    The wavelength and the ion of a line are components of the inputs of the
+    result, and its intensity is the output, so that sorting or selecting
+    lines carries all three together.
+
+    Parameters
+    ----------
+    temperature
+        The temperatures of the plasma.
+    density
+        The number density of electrons. A density which shares the axis of
+        the temperature is one density per temperature, an isobaric
+        atmosphere for instance; a density on its own axis is every density
+        at every temperature.
+    emission_measure
+        How much plasma there is at each temperature.
+    wavelength_min
+        The shortest wavelength worth computing.
+        If :obj:`None` (the default), there is no lower bound.
+    wavelength_max
+        The longest wavelength worth computing.
+        If :obj:`None` (the default), there is no upper bound.
+    ions
+        The ions to compute the lines of, named as :mod:`fiasco` names them.
+        If :obj:`None` (the default), they are found with :func:`ions`, which
+        is every ion the database describes with a line in ``wavelength``.
+        Naming them is how a result is made to depend on the ions rather
+        than on which of them the database at hand happens to hold.
+    proton_electron_ratio
+        The ratio of protons to electrons at each temperature.
+        If :obj:`None` (the default), it is computed here, once, and given
+        to every ion. Pass it to compute more than one spectrum over one
+        grid of temperatures without paying for it again.
+    axis_temperature
+        The name of the axis of ``temperature``.
+    axis
+        The name to give the axis along the lines of the result.
+    kwargs
+        Additional arguments passed to :class:`fiasco.Ion`.
+
+    Examples
+    --------
+    The brightest lines of two ions, from a plasma spread evenly over a
+    decade of temperature.
+
+    .. jupyter-execute::
+
+        import astropy.units as u
+        import named_arrays as na
+        import utu
+
+        temperature = na.geomspace(1e5, 1e6, axis="temperature", num=11) * u.K
+
+        result = utu.spectrum.lines(
+            temperature=temperature,
+            density=1e15 * u.K / u.cm ** 3 / temperature,
+            emission_measure=1e27 / u.cm ** 5,
+            wavelength_min=550 * u.AA,
+            wavelength_max=680 * u.AA,
+            ions=["O 5", "Mg 10"],
+        )
+
+        result[{"line": slice(4)}]
+    """
+    t = na.as_named_array(temperature).ndarray
+
+    # The ratio of protons to electrons depends on the temperature and on
+    # nothing else, and computing it walks the entire database. Computed
+    # once here and handed to every ion, which is most of what makes this
+    # bearable.
+    if proton_electron_ratio is None:
+        proton_electron_ratio = fiasco.proton_electron_ratio(t, **kwargs)
+
+    wavelength_all = []
+    intensity_all = []
+    ion_all = []
+
+    if ions is None:
+        ions = _ions(
+            wavelength_min=wavelength_min,
+            wavelength_max=wavelength_max,
+            **kwargs,
+        )
+
+    for name in ions:
+        try:
+            g = contribution_function(
+                ion=fiasco.Ion(name, t, **kwargs),
+                density=density,
+                axis_temperature=axis_temperature,
+                axis=axis,
+                proton_electron_ratio=proton_electron_ratio,
+            )
+        except Exception:  # pragma: nocover
+            # an ion whose atomic model the database cannot complete
+            continue
+
+        intensity = (g.outputs * emission_measure).sum(axis_temperature)
+
+        w = g.inputs
+        where = None
+        if wavelength_min is not None:
+            where = w > wavelength_min
+        if wavelength_max is not None:
+            below = w < wavelength_max
+            where = below if where is None else where & below
+        if where is not None:
+            w, intensity = w[where], intensity[where]
+
+        wavelength_all.append(w)
+        intensity_all.append(intensity)
+        ion_all.append(na.ScalarArray(np.array([name] * w.size), axes=(axis,)))
+
+    result = na.FunctionArray(
+        inputs=na.CartesianNdVectorArray(
+            components={
+                "wavelength": na.concatenate(wavelength_all, axis=axis),
+                "ion": na.concatenate(ion_all, axis=axis),
+            },
+        ),
+        outputs=na.concatenate(intensity_all, axis=axis),
+    )
+
+    # Brightest first, carrying the wavelength and the ion of each line along
+    # with its intensity. `argsort` gives back the index of each axis by
+    # name, which is what `__getitem__` takes.
+    order = np.argsort(result.outputs, axis=axis)
+    result = result[order]
+
+    return result[{axis: slice(None, None, -1)}]

utu/spectrum/_names.py

@@ -0,0 +1,90 @@
+"""The names of ions, written the way spectroscopists write them."""
+
+import numpy as np
+
+import named_arrays as na
+
+__all__ = [
+    "spectroscopic",
+]
+
+_numeral = (
+    (1000, "M"),
+    (900, "CM"),
+    (500, "D"),
+    (400, "CD"),
+    (100, "C"),
+    (90, "XC"),
+    (50, "L"),
+    (40, "XL"),
+    (10, "X"),
+    (9, "IX"),
+    (5, "V"),
+    (4, "IV"),
+    (1, "I"),
+)
+
+
+def _roman(number: int) -> str:
+    """Write a positive integer as a Roman numeral."""
+    result = ""
+    for value, numeral in _numeral:
+        count, number = divmod(number, value)
+        result += numeral * count
+    return result
+
+
+def _spectroscopic(name: str, latex: bool) -> str:
+    element, _, stage = str(name).partition(" ")
+    element = element.capitalize()
+    numeral = _roman(int(stage))
+    if latex:
+        return rf"{element}\,\textsc{{{numeral.lower()}}}"
+    return f"{element} {numeral}"
+
+
+def spectroscopic(
+    ion: str | na.AbstractScalar,
+    latex: bool = False,
+) -> str | na.AbstractScalar:
+    r"""
+    Write the name of an ion the way a spectroscopist writes it.
+
+    The charge state is a Roman numeral, one greater than the charge, so
+    that the neutral atom is ``I``. This is how :mod:`fiasco` numbers its
+    ions as well, only in Arabic numerals, so ``O 5`` becomes ``O V``.
+
+    Parameters
+    ----------
+    ion
+        The name of an ion, or an array of them, as :mod:`fiasco` writes it.
+    latex
+        Whether to write the numeral as LaTeX small capitals, which is how
+        it is set in print.
+
+    Examples
+    --------
+    The ion ESIS was built to observe.
+
+    .. jupyter-execute::
+
+        import utu
+
+        utu.spectrum.spectroscopic("O 5")
+
+    And as it would be set in a journal.
+
+    .. jupyter-execute::
+
+        utu.spectrum.spectroscopic("O 5", latex=True)
+    """
+    if isinstance(ion, str):
+        return _spectroscopic(ion, latex=latex)
+
+    ion = na.as_named_array(ion)
+    result = np.array([_spectroscopic(i, latex=latex) for i in ion.ndarray.flat])
+
+    return na.ScalarArray(
+        ndarray=result.reshape(ion.ndarray.shape),
+        axes=ion.axes,
+    )

utu/spectrum/_plots.py

@@ -0,0 +1,180 @@
+"""Drawing the emission lines of a spectrum."""
+
+import adjustText
+import matplotlib.axes
+import matplotlib.pyplot as plt
+import matplotlib.text
+import named_arrays as na
+import numpy as np
+
+from ._names import spectroscopic
+
+__all__ = [
+    "stem",
+]
+
+
+def stem(
+    spectrum: na.FunctionArray,
+    ax: None | matplotlib.axes.Axes = None,
+    num_label: None | int = None,
+    latex: bool = False,
+    headroom: float = 1.45,
+    axis: str = "line",
+    kwargs_line: None | dict = None,
+    kwargs_text: None | dict = None,
+    kwargs_adjust: None | dict = None,
+) -> list[matplotlib.text.Text]:
+    """
+    Draw a spectrum as a stem from zero for each line, and label the
+    brightest of them with the ion which emitted them.
+
+    A spectrum of lines is mostly empty, and what matters about it is which
+    line is where and how much brighter it is than its neighbours. Drawn
+    this way it is the picture an instrument is designed against.
+
+    The labels are moved apart so that none covers another or crosses a line
+    it does not belong to. Each line is handed to the solver as points along
+    its length rather than as a point at its tip, more of them for a
+    brighter line, which is what keeps a label from being pushed across one.
+
+    Parameters
+    ----------
+    spectrum
+        The lines to draw, as :func:`~utu.spectrum.lines` returns them: a
+        wavelength and an ion for each line, and its intensity. Every line
+        given is drawn, so slice it first to draw fewer.
+    ax
+        The axes to draw on. If :obj:`None` (the default), the current axes.
+    num_label
+        How many of the brightest lines to label.
+        If :obj:`None` (the default), all of them are labelled.
+    latex
+        Whether to set the name of each ion in LaTeX, which needs the axes
+        to be rendering text through LaTeX to come out right.
+    headroom
+        How much taller than the brightest line to make the axes, so that
+        the labels have somewhere to be pushed into.
+    axis
+        The name of the axis along the lines of ``spectrum``.
+    kwargs_line
+        Additional arguments passed to :meth:`matplotlib.axes.Axes.vlines`.
+    kwargs_text
+        Additional arguments passed to :meth:`matplotlib.axes.Axes.text`.
+    kwargs_adjust
+        Additional arguments passed to :func:`adjustText.adjust_text`.
+
+    Returns
+    -------
+    The label of each line that was labelled, in the order they were drawn.
+
+    Examples
+    --------
+    The brightest lines of two ions, from a plasma spread evenly over a
+    decade of temperature.
+
+    .. jupyter-execute::
+
+        import astropy.units as u
+        import matplotlib.pyplot as plt
+        import named_arrays as na
+        import utu
+
+        temperature = na.geomspace(1e5, 1e6, axis="temperature", num=11) * u.K
+
+        result = utu.spectrum.lines(
+            temperature=temperature,
+            density=1e15 * u.K / u.cm ** 3 / temperature,
+            emission_measure=1e27 / u.cm ** 5,
+            wavelength_min=550 * u.AA,
+            wavelength_max=680 * u.AA,
+            ions=["O 5", "Mg 10"],
+        )
+
+        fig, ax = plt.subplots(figsize=(6, 3), constrained_layout=True)
+        utu.spectrum.stem(result[{"line": slice(6)}], ax=ax)
+        ax.set_xlabel(f"wavelength ({u.AA:latex_inline})")
+        ax.set_ylabel(f"intensity ({result.outputs.unit:latex_inline})");
+    """
+    if ax is None:  # pragma: nocover
+        ax = plt.gca()
+
+    kwargs_line = kwargs_line if kwargs_line is not None else {}
+    kwargs_text = kwargs_text if kwargs_text is not None else {}
+    kwargs_adjust = kwargs_adjust if kwargs_adjust is not None else {}
+
+    wavelength = na.value(spectrum.inputs.wavelength).ndarray
+    intensity = na.value(spectrum.outputs).ndarray
+
+    ax.vlines(
+        x=wavelength,
+        ymin=0,
+        ymax=intensity,
+        **{"color": "black", "linewidth": 1} | kwargs_line,
+    )
+
+    # room above the tallest line for the labels to be pushed into
+    ax.set_ylim(0, intensity.max() * headroom)
+
+    # Every line is given to the solver as points along its length, more of
+    # them for a brighter line, so that a label is pushed away from a line
+    # it would otherwise cross rather than only from the tip of it.
+    x_static = []
+    y_static = []
+    for i in range(intensity.size):
+        num = max(int(100 * intensity[i] / intensity.max()), 3)
+        y = np.linspace(0, intensity[i], num=num)
+        y_static.append(y)
+        x_static.append(np.broadcast_to(wavelength[i], y.shape))
+
+    # brightest first, so that taking the first few takes the brightest few
+    order = np.argsort(spectrum.outputs, axis=axis)
+    brightest = spectrum[order][{axis: slice(None, None, -1)}]
+    brightest = brightest[{axis: slice(num_label)}]
+
+    x_label = na.value(brightest.inputs.wavelength).ndarray
+    y_label = na.value(brightest.outputs).ndarray
+    name = spectroscopic(brightest.inputs.ion, latex=latex).ndarray
+
+    text = [
+        ax.text(
+            x=x_label[i],
+            y=y_label[i],
+            s=f"{name[i]} {x_label[i]:.1f}",
+            **{
+                "ha": "center",
+                "va": "bottom",
+                "bbox": {
+                    "facecolor": "white",
+                    "edgecolor": "none",
+                    "alpha": 0.75,
+                    "pad": 0.8,
+                },
+            }
+            | kwargs_text,
+        )
+        for i in range(x_label.size)
+    ]
+
+    adjustText.adjust_text(
+        texts=text,
+        x=np.concatenate(x_static),
+        y=np.concatenate(y_static),
+        ax=ax,
+        **{
+            "arrowprops": {
+                "arrowstyle": "-",
+                "connectionstyle": "arc3",
+                "alpha": 0.5,
+                "linewidth": 0.5,
+            },
+            "force_static": (0.4, 0.6),
+            "force_text": (0.4, 0.6),
+            "expand": (1.15, 1.4),
+            "max_move": (30, 30),
+            "time_lim": 10,
+        }
+        | kwargs_adjust,
+    )
+
+    return text

utu/spectrum/_tests/test_lines.py

@@ -0,0 +1,181 @@
+import astropy.units as u
+import fiasco
+import named_arrays as na
+import numpy as np
+import pytest
+
+import utu
+
+
+def _database() -> bool:
+    """Whether the CHIANTI database has been downloaded on this machine."""
+    try:
+        return len(fiasco.list_ions()) > 0
+    except Exception:  # pragma: nocover
+        return False
+
+
+needs_database = pytest.mark.skipif(
+    not _database(),
+    reason="the CHIANTI database is not available",
+)
+
+# A window around the O V line, narrow enough that only a handful of ions
+# qualify. Every ion which does costs a level population solve, and six of
+# them prove as much about sorting and filtering as twenty five do.
+# Given as named scalars rather than as plain quantities, since both are
+# allowed and only one of them would otherwise be tried.
+wavelength_min = na.ScalarArray(629.72 * u.AA)
+wavelength_max = na.ScalarArray(629.75 * u.AA)
+
+temperature = na.ScalarArray(
+    ndarray=10 ** np.arange(4.0, 7.0, 0.5) * u.K,
+    axes=("temperature",),
+)
+
+density = na.ScalarArray(
+    ndarray=1e15 * u.K / u.cm**3 / temperature.ndarray,
+    axes=("temperature",),
+)
+
+emission_measure = na.ScalarArray(
+    ndarray=1e27 / u.cm**5 * np.ones(temperature.shape["temperature"]),
+    axes=("temperature",),
+)
+
+
+# Each of the fixtures below walks the whole database, which takes an order
+# of magnitude longer than anything the tests do with the result. They are
+# scoped to the session so that the suite pays for each walk once.
+
+
+@pytest.fixture(scope="session")
+def ions_all() -> list[str]:
+    """Every ion the database describes."""
+    return utu.spectrum.ions()
+
+
+@pytest.fixture(scope="session")
+def ions_window() -> list[str]:
+    """Every ion with a line in the window above."""
+    return utu.spectrum.ions(
+        wavelength_min=wavelength_min,
+        wavelength_max=wavelength_max,
+    )
+
+
+@pytest.fixture(scope="session")
+def proton_electron_ratio() -> u.Quantity:
+    """The ratio of protons to electrons at each temperature above."""
+    return fiasco.proton_electron_ratio(temperature.ndarray)
+
+
+@needs_database
+def test_ions(ions_window: list[str], ions_all: list[str]):
+    assert ions_window
+    for name in ions_window:
+        assert isinstance(name, str)
+
+    # the line this window was chosen for
+    assert "O 5" in ions_window
+
+    # and asking for every ion gives more of them
+    assert len(ions_window) < len(ions_all)
+
+
+@needs_database
+def test_contribution_function(proton_electron_ratio: u.Quantity):
+    ion = fiasco.Ion("O 5", temperature.ndarray)
+
+    result = utu.spectrum.contribution_function(
+        ion=ion,
+        density=density,
+        axis_temperature="temperature",
+        proton_electron_ratio=proton_electron_ratio,
+    )
+
+    assert isinstance(result, na.FunctionArray)
+    assert na.unit(result.inputs).is_equivalent(u.AA)
+    assert "temperature" in na.shape(result.outputs)
+    assert "line" in na.shape(result.outputs)
+
+    # a density which shares the axis of the temperature is one density per
+    # temperature, so the result carries no axis of its own for it
+    assert "_density" not in na.shape(result.outputs)
+
+
+@needs_database
+def test_contribution_function_grid(proton_electron_ratio: u.Quantity):
+    """A density on its own axis is every density at every temperature."""
+    ion = fiasco.Ion("O 5", temperature.ndarray)
+
+    density_grid = na.ScalarArray(
+        ndarray=np.array([1e9, 1e10]) / u.cm**3,
+        axes=("density",),
+    )
+
+    result = utu.spectrum.contribution_function(
+        ion=ion,
+        density=density_grid,
+        axis_temperature="temperature",
+        proton_electron_ratio=proton_electron_ratio,
+    )
+
+    shape = na.shape(result.outputs)
+    assert shape["temperature"] == temperature.shape["temperature"]
+    assert shape["_density"] == 2
+
+
+@needs_database
+def test_lines():
+    """The whole of it, with nothing given that can be worked out."""
+    result = utu.spectrum.lines(
+        temperature=temperature,
+        density=density,
+        emission_measure=emission_measure,
+        wavelength_min=wavelength_min,
+        wavelength_max=wavelength_max,
+    )
+
+    assert isinstance(result, na.FunctionArray)
+
+    w = result.inputs.wavelength
+    ion = result.inputs.ion
+    intensity = result.outputs
+
+    # the wavelength, the ion, and the intensity of a line are one array
+    assert na.shape(w) == na.shape(ion) == na.shape(intensity)
+
+    assert np.all(w > wavelength_min)
+    assert np.all(w < wavelength_max)
+
+    # brightest first
+    d = np.diff(na.value(intensity).ndarray)
+    assert np.all(d <= 0)
+
+    # and the brightest line in this window is the one it was chosen for
+    brightest = {"line": 0}
+    assert str(ion[brightest].ndarray) == "O 5"
+    assert np.isclose(w[brightest].ndarray.to_value(u.AA), 629.733, atol=1e-2)
+
+
+@needs_database
+def test_lines_ions(
+    ions_window: list[str],
+    proton_electron_ratio: u.Quantity,
+):
+    """Naming the ions is what keeps a result from depending on the database."""
+    result = utu.spectrum.lines(
+        temperature=temperature,
+        density=density,
+        emission_measure=emission_measure,
+        wavelength_min=wavelength_min,
+        wavelength_max=wavelength_max,
+        ions=["O 5"],
+        proton_electron_ratio=proton_electron_ratio,
+    )
+
+    assert np.all(result.inputs.ion == "O 5")
+
+    # and there were other ions to be had in this window
+    assert len(ions_window) > 1

utu/spectrum/_tests/test_names.py

@@ -0,0 +1,34 @@
+import numpy as np
+import pytest
+
+import named_arrays as na
+import utu
+
+
+@pytest.mark.parametrize(
+    argnames="ion,expected,expected_latex",
+    argvalues=[
+        ("He 1", "He I", r"He\,\textsc{i}"),
+        ("O 5", "O V", r"O\,\textsc{v}"),
+        ("Mg 10", "Mg X", r"Mg\,\textsc{x}"),
+        ("S 4", "S IV", r"S\,\textsc{iv}"),
+        ("Fe 24", "Fe XXIV", r"Fe\,\textsc{xxiv}"),
+    ],
+)
+def test_spectroscopic(ion: str, expected: str, expected_latex: str):
+    assert utu.spectrum.spectroscopic(ion) == expected
+    assert utu.spectrum.spectroscopic(ion, latex=True) == expected_latex
+
+
+def test_spectroscopic_array():
+    """An array of names keeps its shape and its axes."""
+    ion = na.ScalarArray(
+        ndarray=np.array([["O 5", "Mg 10"], ["He 1", "S 4"]]),
+        axes=("x", "y"),
+    )
+
+    result = utu.spectrum.spectroscopic(ion)
+
+    assert na.shape(result) == na.shape(ion)
+    assert result[{"x": 0, "y": 0}].ndarray == "O V"
+    assert result[{"x": 1, "y": 1}].ndarray == "S IV"

utu/spectrum/_tests/test_plots.py

@@ -0,0 +1,83 @@
+import astropy.units as u
+import matplotlib
+import matplotlib.pyplot as plt
+import named_arrays as na
+import numpy as np
+import pytest
+
+import utu
+
+matplotlib.use("agg")
+
+# A spectrum written down rather than computed, so that these tests say
+# nothing about the atomic database and do not need it to run.
+spectrum = na.FunctionArray(
+    inputs=na.CartesianNdVectorArray(
+        components={
+            "wavelength": na.ScalarArray(
+                ndarray=np.array([584.3, 609.8, 629.7]) * u.AA,
+                axes=("line",),
+            ),
+            "ion": na.ScalarArray(
+                ndarray=np.array(["He 1", "Mg 10", "O 5"]),
+                axes=("line",),
+            ),
+        },
+    ),
+    outputs=na.ScalarArray(
+        ndarray=np.array([10.0, 30.0, 100.0]) * u.erg / u.s / u.cm**2,
+        axes=("line",),
+    ),
+)
+
+
+@pytest.mark.parametrize("num_label", [None, 1, 2])
+def test_stem(num_label: None | int):
+    fig, ax = plt.subplots()
+
+    result = utu.spectrum.stem(spectrum, ax=ax, num_label=num_label)
+
+    expected = num_label if num_label is not None else spectrum.shape["line"]
+    assert len(result) == expected
+
+    # the brightest line is labelled first, whichever order it was given in
+    assert result[0].get_text().startswith("O V")
+
+    # every line is drawn, whether or not it is labelled
+    segments = [s for c in ax.collections for s in c.get_segments()]
+    assert len(segments) == spectrum.shape["line"]
+
+    # and there is room above the tallest of them for the labels
+    assert ax.get_ylim()[1] > 100
+
+    plt.close(fig)
+
+
+def test_stem_latex():
+    """The name of an ion, as it would be set in a journal."""
+    fig, ax = plt.subplots()
+
+    result = utu.spectrum.stem(spectrum, ax=ax, num_label=1, latex=True)
+
+    assert result[0].get_text().startswith(r"O\,\textsc{v}")
+
+    plt.close(fig)
+
+
+def test_stem_kwargs():
+    """Every default the caller might disagree with can be replaced."""
+    fig, ax = plt.subplots()
+
+    result = utu.spectrum.stem(
+        spectrum,
+        ax=ax,
+        num_label=1,
+        kwargs_line={"color": "red"},
+        kwargs_text={"fontsize": 5},
+        kwargs_adjust={"time_lim": 1},
+    )
+
+    assert result[0].get_fontsize() == 5
+    assert np.all(ax.collections[0].get_color() == np.array([[1, 0, 0, 1]]))
+
+    plt.close(fig)

utu-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: utu
+Version: 0.1.0
+Summary: A Python library of solar physics utilities built on named arrays
+Author-email: "Roy T. Smart" <roytsmart@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/sun-data/utu
+Project-URL: Documentation, https://utu.readthedocs.io
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: astropy
+Requires-Dist: matplotlib
+Requires-Dist: adjustText
+Requires-Dist: named-arrays~=2.8
+Requires-Dist: fiasco~=0.8.2
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-doctestplus; extra == "test"
+Provides-Extra: doc
+Requires-Dist: matplotlib; extra == "doc"
+Requires-Dist: graphviz; extra == "doc"
+Requires-Dist: pydata-sphinx-theme; extra == "doc"
+Requires-Dist: ipykernel; extra == "doc"
+Requires-Dist: jupyter-sphinx; extra == "doc"
+Requires-Dist: sphinx-favicon; extra == "doc"
+Requires-Dist: sphinx-codeautolink; extra == "doc"
+Dynamic: license-file
+
+# utu
+
+[![tests](https://github.com/sun-data/utu/actions/workflows/tests.yml/badge.svg)](https://github.com/sun-data/utu/actions/workflows/tests.yml)
+[![Black](https://github.com/sun-data/utu/actions/workflows/black.yml/badge.svg)](https://github.com/sun-data/utu/actions/workflows/black.yml)
+[![Ruff](https://github.com/sun-data/utu/actions/workflows/ruff.yml/badge.svg)](https://github.com/sun-data/utu/actions/workflows/ruff.yml)
+[![Documentation Status](https://readthedocs.org/projects/utu/badge/?version=latest)](https://utu.readthedocs.io/en/latest/?badge=latest)
+
+A Python library of solar physics utilities built on
+[named arrays](https://github.com/sun-data/named-arrays).
+
+Named for the Sumerian god of the sun.
+
+## Documentation
+
+The documentation is at [utu.readthedocs.io](https://utu.readthedocs.io/en/latest/).
+
+## `utu.spectrum`
+
+The emission lines of an optically thin plasma, computed from the CHIANTI
+atomic database through [fiasco](https://github.com/wtbarnes/fiasco), and
+returned as named arrays.

utu-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+utu/__init__.py,sha256=QIcAyF2Gbk3WN5knkAnXK1MiUo-XW-Vy55S5Rr3xBGU,161
+utu/_version.py,sha256=7JjVb-xSpAQiq4NIZy8IlFzG_wu7BbNsO78dKYqGQBI,182
+utu/_tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utu/_tests/test_utu.py,sha256=QJaQqEqHI3TzrtH34ofzzlqmukw3Ki15xcCDva5Ijl8,170
+utu/spectrum/__init__.py,sha256=_qWFMJ_rLmiAQ-LlrSSRV-jKh2tW3YLvfghPA7j-yeE,316
+utu/spectrum/_lines.py,sha256=SmkBhQ_LJyC_hjZQy_SXD8ZXiR20NxJ33SjkDMI8Z6A,13695
+utu/spectrum/_names.py,sha256=ixlHgaNyPypVqFQkIZYR1RmMqwaPPmoflZkr7WaiZe0,2106
+utu/spectrum/_plots.py,sha256=PlaA4r-2k_X95rJ8POdVgBWM133p9kCNEUzWqrJfIrE,5996
+utu/spectrum/_tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utu/spectrum/_tests/test_lines.py,sha256=qrNd_bb6Cd1-q29gpu5PlWqFBaeUs9nTsBLMglitV4Y,5399
+utu/spectrum/_tests/test_names.py,sha256=oww8IAx7vGMUu1SMUOY6JcN6aV4ddX1A4vasXhHo7GI,1006
+utu/spectrum/_tests/test_plots.py,sha256=mkPVyuLx_-ZTNSh2IYKSXpiQ6yERk7t3oY5Fo3cRIDI,2315
+utu-0.1.0.dist-info/licenses/LICENSE,sha256=7g-UZoXrsIORYtW9htZUtHR85BXqO2pWRCoEQxnGTUY,1488
+utu-0.1.0.dist-info/METADATA,sha256=Vbo3p1_0cMp7rM_o03R5ngSXqBwrDFx9J-HGhR-NS1o,2100
+utu-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+utu-0.1.0.dist-info/top_level.txt,sha256=liQQdfMTlISJzyng_tpRLbcDrPMutG5a1J1njO28Z_c,4
+utu-0.1.0.dist-info/RECORD,,

utu-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

utu-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Roy T. Smart
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

utu-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+utu