utu 0.1.0__tar.gz

utu-0.1.0/.github/workflows/black.yml

@@ -0,0 +1,17 @@
+name: Black
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  black:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: psf/black@stable
+        with:
+          options: "--check --verbose --diff"
+          src: "./utu"

utu-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    if: startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+      - name: Install pypa/build
+        run: >-
+          python -m
+          pip install
+          build
+          --user
+      - name: Build a binary wheel and a source tarball
+        run: >-
+          python -m
+          build
+          --sdist
+          --wheel
+          --outdir dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

utu-0.1.0/.github/workflows/ruff.yml

@@ -0,0 +1,14 @@
+name: Ruff
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chartboost/ruff-action@v1

utu-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,117 @@
+
+name: tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [
+          ubuntu-latest,
+          windows-latest,
+          macOS-latest,
+        ]
+        python-version: ["3.12", "3.13"]
+    name: ${{ matrix.os }}, Python ${{ matrix.python-version }} tests
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel
+          pip install -e .[test]
+      # Coverage is measured in the `chianti` job below and nowhere else.
+      # These jobs skip every test which reads the atomic database, so their
+      # coverage is a subset of that one's, and Codecov decides a pull request
+      # on whichever reports have arrived when it is asked: the subset lands
+      # first and the answer is wrong until the superset catches up, which is
+      # too late to be reported. One report cannot race itself.
+      - name: Test with pytest
+        env:
+          MPLBACKEND: "agg"
+        run: pytest --doctest-modules --junitxml=junit/test-results.xml
+
+  # The tests which read the CHIANTI database, which is too large to fetch on
+  # every job of the matrix, so it is fetched once here and cached. Without
+  # this the whole of `utu.spectrum` skips, and CI reports success on code it
+  # never ran.
+  chianti:
+    runs-on: ubuntu-latest
+    name: ubuntu-latest, Python 3.13, CHIANTI tests
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test]
+          pip install pytest-cov
+      - name: Ask fiasco which database it wants
+        id: chianti
+        run: |
+          python -c "
+          from fiasco.util.setup_db import LATEST_VERSION
+          print(f'version={LATEST_VERSION}')
+          " >> $GITHUB_OUTPUT
+      - name: Restore the CHIANTI database
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.fiasco
+          key: chianti-${{ steps.chianti.outputs.version }}
+      - name: Download and build the CHIANTI database
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          python -c "
+          import fiasco
+          from fiasco.util import check_database
+          check_database(
+              hdf5_dbase_root=fiasco.defaults['hdf5_dbase_root'],
+              ascii_dbase_root=fiasco.defaults['ascii_dbase_root'],
+              ask_before=False,
+          )
+          "
+      - name: Test with pytest
+        env:
+          MPLBACKEND: "agg"
+        run: pytest --cov=. --cov-report=xml
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          name: codecov-umbrella
+
+  # A single check for the whole matrix to report through, so that the branch
+  # ruleset never has to name an operating system or a version of Python.
+  # Naming them means that changing the matrix silently blocks every pull
+  # request: a required check which no longer runs is one which never reports,
+  # and a pull request waits on it forever.
+  tests:
+    if: always()
+    needs: [build, chianti]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check whether every job in the matrix succeeded
+        run: |
+          for result in "${{ needs.build.result }}" "${{ needs.chianti.result }}"; do
+            if [ "$result" != "success" ]; then
+              echo "a job reported '$result'"
+              exit 1
+            fi
+          done
+          echo "every job in the matrix succeeded"

utu-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+docs/_build/
+docs/_autosummary/
+docs/jupyter_execute/
+.coverage
+coverage.xml

utu-0.1.0/.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "3.12"
+  apt_packages:
+    - graphviz
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc

utu-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,21 @@
+# 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/docs/_templates/module_custom.rst

@@ -0,0 +1,69 @@
+{{ name | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+    {% block attributes %}
+    {% if attributes %}
+    .. rubric:: Module Attributes
+
+    .. autosummary::
+      :toctree:
+    {% for item in attributes %}
+      {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
+
+    .. autosummary::
+      :toctree:
+      :template: function_custom.rst
+    {% for item in functions %}
+      {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block classes %}
+    {% if classes %}
+    .. rubric:: {{ _('Classes') }}
+
+    .. autosummary::
+      :toctree:
+      :template: class_custom.rst
+    {% for item in classes %}
+      {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block exceptions %}
+    {% if exceptions %}
+    .. rubric:: {{ _('Exceptions') }}
+
+    .. autosummary::
+      :toctree:
+    {% for item in exceptions %}
+      {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Modules
+
+    .. autosummary::
+       :toctree:
+       :template: module_custom.rst
+       :recursive:
+    {% for item in modules %}
+       {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+

utu-0.1.0/docs/conf.py

@@ -0,0 +1,139 @@
+"""Configuration for the Sphinx documentation builder."""
+
+import os
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path("..").resolve()))
+
+project = "utu"
+copyright = "2026, Roy T. Smart"
+author = "Roy T. Smart"
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "jupyter_sphinx",
+    "sphinx_codeautolink",
+    "sphinx_favicon",
+]
+
+autosummary_generate = True
+autosummary_imported_members = True
+autosummary_ignore_module_all = False
+autodoc_typehints = "description"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/sun-data/utu",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/utu/",
+            "icon": "fa-brands fa-python",
+        },
+    ],
+}
+
+# https://github.com/readthedocs/readthedocs.org/issues/2569
+master_doc = "index"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "astropy": ("https://docs.astropy.org/en/stable", None),
+    "named_arrays": ("https://named-arrays.readthedocs.io/en/stable", None),
+    "fiasco": ("https://fiasco.readthedocs.io/en/stable", None),
+}
+
+codeautolink_custom_blocks = {"jupyter-execute": None}
+
+
+# -- The atomic database ----------------------------------------------------
+
+ions = [
+    "he_1",
+    "o_3",
+    "o_4",
+    "o_5",
+    "ne_7",
+    "mg_10",
+    "si_11",
+]
+"""
+The ions the examples on these pages compute with.
+
+Every page which reads the CHIANTI database is written against these ions,
+and the database built below describes only these, so that a page can be
+built in a minute rather than in twenty. The whole database is 1.6 GB of
+text, almost all of it the collision strengths of iron, and turning it into
+the form :mod:`fiasco` reads takes about as long as Read the Docs allows a
+build to run in total.
+"""
+
+extension = [
+    "auto",
+    "cilvl",
+    "diparams",
+    "drparams",
+    "easplom",
+    "easplups",
+    "elvlc",
+    "fblvl",
+    "psplups",
+    "reclvl",
+    "rrlvl",
+    "rrparams",
+    "scups",
+    "trparams",
+    "wgfa",
+]
+"""
+The kinds of file an ion can have.
+
+Not every ion has every one of them; the ones an ion does not have are
+skipped as the database is built.
+"""
+
+if os.environ.get("READTHEDOCS") == "True":  # pragma: no cover
+    import fiasco
+    from fiasco.util import get_chianti_catalog
+    from fiasco.util.setup_db import (
+        _get_chianti_dbase_url,
+        build_hdf5_dbase,
+        download_dbase,
+    )
+
+    ascii_dbase_root = pathlib.Path(fiasco.defaults["ascii_dbase_root"])
+    hdf5_dbase_root = pathlib.Path(fiasco.defaults["hdf5_dbase_root"])
+
+    if not (ascii_dbase_root / "VERSION").is_file():
+        # which version to fetch is asked of `fiasco` rather than written
+        # down here, since the two are not the same question: the URL of a
+        # version is not something one can guess from its number
+        download_dbase(_get_chianti_dbase_url(), ascii_dbase_root)
+
+    if not hdf5_dbase_root.is_file():
+        catalog = get_chianti_catalog(ascii_dbase_root)
+        files = [f"{ion}.{ext}" for ion in ions for ext in extension]
+        files += catalog["abundance_files"]
+        files += catalog["ioneq_files"]
+        files += catalog["ip_files"]
+        build_hdf5_dbase(
+            ascii_dbase_root,
+            hdf5_dbase_root,
+            files=files,
+            show_progress=False,
+        )

utu-0.1.0/docs/index.rst

@@ -0,0 +1,38 @@
+utu
+===
+
+:mod:`utu` is a library of solar physics utilities built on
+:mod:`named_arrays`, named for the Sumerian god of the sun.
+
+Installation
+============
+
+:mod:`utu` is available on PyPI and can be installed using pip::
+
+    pip install utu
+
+Tutorials
+=========
+
+.. toctree::
+    :maxdepth: 1
+
+    tutorials/spectrum
+
+
+API Reference
+=============
+
+.. autosummary::
+    :toctree: _autosummary
+    :template: module_custom.rst
+    :recursive:
+
+    utu
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`