dust-compendium 0.1.0__py3-none-any.whl

dust_compendium-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: dust-compendium
+Version: 0.1.0
+Summary: Dust attenuation tables for simple galactic geometries, computed with Hyperion
+Project-URL: Homepage, https://github.com/galacticusorg/dust-compendium
+Project-URL: Documentation, https://dust-compendium.readthedocs.io
+Project-URL: Issues, https://github.com/galacticusorg/dust-compendium/issues
+Author-email: Andrew Benson <abenson@carnegiescience.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astronomy,dust,galacticus,galaxies,radiative transfer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Requires-Dist: h5py>=3.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff==0.16.7; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
+Requires-Dist: sphinx-book-theme; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.7; extra == 'plots'
+Description-Content-Type: text/markdown
+
+# Dust Compendium
+
+[![CI](https://github.com/galacticusorg/dust-compendium/actions/workflows/ci.yml/badge.svg)](https://github.com/galacticusorg/dust-compendium/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/dust-compendium/badge/?version=latest)](https://dust-compendium.readthedocs.io)
+
+Dust attenuation tables for simple galactic geometries, computed by running the
+[Hyperion](http://www.hyperion-rt.org) Monte Carlo radiative transfer code over
+a grid of galaxy models.
+
+A tabulation gives the fraction of starlight escaping a galaxy as a function of
+wavelength, inclination, the optical depth of each dusty component, and the
+sizes of the components themselves. [Galacticus](https://github.com/galacticusorg/galacticus)
+reads them through its `dustAttenuationAtlasCompendium` class. The method is
+described in [Benson (2018)](https://ui.adsabs.harvard.edu/abs/2018RNAAS...2..188B).
+
+Full documentation is at [dust-compendium.readthedocs.io](https://dust-compendium.readthedocs.io).
+
+## Installation
+
+```bash
+pip install dust-compendium
+```
+
+That gives the library and the command line tool. Computing *new* tabulations
+additionally needs Hyperion, in two parts, neither of which is a dependency of
+this package:
+
+- its **Python front-end**, which has to come from source for now — the current
+  PyPI release calls `np.string_` when writing a model, which NumPy 2 removed;
+- its **Fortran solvers**, which `pip` does not install at all.
+
+See [the installation notes](https://dust-compendium.readthedocs.io/en/latest/installation.html).
+
+## Using it
+
+```bash
+dust-compendium validate configs/compendium-d03-rv3.1.yaml   # what would this run?
+dust-compendium build    configs/compendium-d03-rv3.1.yaml   # write the model inputs
+dust-compendium run      configs/compendium-d03-rv3.1.yaml   # solve them, here or on Slurm
+dust-compendium collect  configs/compendium-d03-rv3.1.yaml   # assemble the tabulation
+dust-compendium plot     attenuations.hdf5 -q curve -c opticalDepth
+dust-compendium compare  attenuations.hdf5 --atlas /path/to/atlas.hdf5
+```
+
+A campaign is described by a YAML file. Any value written as a range becomes an
+axis of the tabulation; a galaxy is a set of named components, each of which may
+carry stars, dust, both or neither. Each step reads what the one before it left
+on disk, so any of them can be interrupted and resumed.
+
+`configs/` holds the configuration for the published Draine R_V=3.1 tabulation,
+one adding dust to the spheroid, and one matched to Ferrara et al. (1999) for
+validation.
+
+## Validation
+
+Reproducing Ferrara et al. (1999) with matched grains, geometry and grids gives
+a median absolute difference from their published atlas of **0.0034** in disk
+transmission, with 99.9% of entries within 0.02 — as close as the original
+scripts got, and near the 0.005 floor set by the atlas being published to two
+decimal places.
+
+## Provenance
+
+This replaces the Perl and Python 2 scripts written for the 2018 paper, which
+are preserved verbatim in the first commit of this repository. Rewriting them
+turned up several defects, two of which reached published data; those are
+described under
+[Published datasets](https://dust-compendium.readthedocs.io/en/latest/datasets.html).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

dust_compendium-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+dustcompendium/__init__.py,sha256=7rA1LA0SktQZR215XSlteRjjNxDvzPsWhxRg2iOBSqA,479
+dustcompendium/campaign.py,sha256=UJoTc_t6UmDrc4lKVbQuVbvuMbopXTctpPRCuu6bv-c,10878
+dustcompendium/cli.py,sha256=wB0x8cJ2RMU5DYWq52X_v35Fg55CI4xQ4o6X3cLR-C4,18736
+dustcompendium/config.py,sha256=ds6u3hVxrd5IBMKqRJzbUQCNqCPwU1Sg9kfxUE7DMXY,9433
+dustcompendium/galaxy.py,sha256=af_02zpCKdQNxcIQ6o0CgaIZGTAhTaCKEx1VjLScaEk,5672
+dustcompendium/grid.py,sha256=skfpvX2aEp6wuhsaK0BPyIUfiKyc2LdmaA8cxH4FoYo,9302
+dustcompendium/hyperion_model.py,sha256=gKc_-s_pkX6eXRFOnnpz4lWp3SVrkewczYUpAh0O_z8,5418
+dustcompendium/model.py,sha256=0DyM2cB0YoNNrVMrB_GgQ4i44KVqLYTHMp7eWpyOU54,9969
+dustcompendium/plots.py,sha256=lGG7Ms7gBzGttr3BI3WwWsbP-kxnYqJrRXc3r7YLai4,12710
+dustcompendium/postprocess.py,sha256=VOW7lNt9V_Uvcs97i7oLJNdDdS8-Si8PLdmaCO0xqzk,12469
+dustcompendium/tabulation.py,sha256=YlyWFKTFvY5IUdfY-RvfZA6jyjo4yZ8wrcC10hS3Cis,12159
+dustcompendium/validation.py,sha256=tlo7ZSgM3gVLCTEFtlRcpuYTSE6XYuTpUUcB9lvIViA,5822
+dustcompendium/dust/__init__.py,sha256=yWcio7isC6u3AavSXuRPKy1Gw6LLLKtn3FXujasvYYk,316
+dustcompendium/dust/ferrara.py,sha256=KkNPgTT8hf38MjjBpNLkqQQLhyBZzWWQHAkABLnSSDw,5286
+dustcompendium/dust/properties.py,sha256=RNPPbpTp7J77Ja1XWmPzNYaS0HnpV5jlgLYQXCAJYak,2707
+dustcompendium/dust/data/gordon1997.csv,sha256=v7r1Sk7kzfsxx6hiR-8IYOW4gY6IJCLENMR47DC7L5U,1325
+dustcompendium/geometry/__init__.py,sha256=VjSuSP2OdoFKMaWnkIUMKAq5LOO8u2Sx4bzCft4SFTU,2342
+dustcompendium/geometry/base.py,sha256=TkSR68lnX9jgG1od6Z0YQ11BDb-1FnqVPyCTPqckDpU,5867
+dustcompendium/geometry/disk.py,sha256=SXsgKZtmmcXL6mQxMtov-gZmqThnoL_vc5g45uR8NHw,6150
+dustcompendium/geometry/spheroid.py,sha256=emyUi8n_PE0-Wq-Er6uMPVBfd9S1d5oVhtUVa0TLj4E,17987
+dustcompendium/runner/__init__.py,sha256=lJ4INQBG_XywZZbe6asJrPRppZEPMR05cU3mLtVYG58,1132
+dustcompendium/runner/base.py,sha256=NJUYjAR83hBxNZSlsT_RLHvst5IyvsuAcAFs8P0KxSc,4037
+dustcompendium/runner/local.py,sha256=gXXUzcWivrmCROuD75py-I86FlLH5-l2O4X-h4M9DBA,2104
+dustcompendium/runner/slurm.py,sha256=GLieuIVAgD92VChxTmE7ERRIs7PEgbp_DiPVuKERG08,7155
+dustcompendium/runner/solver.py,sha256=AnGX7widY1v3YpxCWIHR503pN5gIod8YVGNPR7YaCKM,3695
+dust_compendium-0.1.0.dist-info/METADATA,sha256=AjrtzjNWX2GmWGpwsS2ebRQnlc1mrmLqbPIVqEgSQdM,4735
+dust_compendium-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+dust_compendium-0.1.0.dist-info/entry_points.txt,sha256=I1I2b9Ss3aSvG_jZyOiXnNK7Gh5ERwoqDKLCVDUj960,59
+dust_compendium-0.1.0.dist-info/licenses/LICENSE,sha256=Dg5aovcCb-1jZaq8wyx5dK6xzuTA-RmIzbhF4-cBYy0,1075
+dust_compendium-0.1.0.dist-info/RECORD,,

dust_compendium-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dust_compendium-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dust-compendium = dustcompendium.cli:app

dust_compendium-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2026 Andrew Benson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dustcompendium/__init__.py

@@ -0,0 +1,14 @@
+"""Dust attenuation tables for simple galactic geometries.
+
+Computes the fraction of starlight escaping a galaxy as a function of
+wavelength, inclination, dust optical depth and component size, by running the
+Hyperion Monte Carlo radiative transfer code over a grid of simple galactic
+geometries, and tabulates the result.
+
+The method is described in `Benson (2018)
+<https://ui.adsabs.harvard.edu/abs/2018RNAAS...2..188B>`_.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

dustcompendium/campaign.py

@@ -0,0 +1,259 @@
+r"""Expanding a configuration into the individual models that have to be run.
+
+A campaign tabulates attenuation over a grid of parameters. Every parameter
+written as a range in the configuration becomes an *axis*: the optical depth of
+each dust-bearing component, and any geometric scale that varies. One model is
+run for each point on that grid and for each component with stars, since the
+attenuation of each is tabulated separately.
+
+The published compendium is 60 optical depths by 51 spheroid sizes by two
+emitting components, which is 6,120 models -- why this wants a cluster.
+"""
+
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from itertools import product
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .config import CampaignConfig, ProfileConfig, values_of
+from .galaxy import Component, Galaxy
+from .model import ModelSpec
+
+__all__ = ["Axis", "Campaign", "Run"]
+
+#: Geometric parameters which may vary, and so become axes.
+GEOMETRIC = ("scale_radial", "scale_height")
+
+
+@dataclass(frozen=True)
+class Axis:
+    """One tabulated parameter, and the values it takes."""
+
+    kind: str
+    """``opticalDepth``, ``scaleRadial`` or ``scaleHeight``."""
+    component: str
+    """Which component it belongs to."""
+    roles: frozenset[str]
+    """Which of ``stellar`` and ``dust`` this axis sets.
+
+    A component's stars and its dust may have different scale lengths -- the
+    original already gave the disk separate stellar and dust scale heights -- so
+    the two are separate parameters. When they are configured over the same
+    values they are one axis, driving both, rather than a square grid of a scale
+    against itself.
+    """
+    values: NDArray[np.float64]
+    qualified: bool = False
+    """Whether the name needs a role to tell it from another axis of the same parameter."""
+
+    @property
+    def name(self) -> str:
+        """A stable name, used for labels and for output dataset names."""
+        if self.qualified:
+            return f"{self.kind}:{self.component}:{sorted(self.roles)[0]}"
+        return f"{self.kind}:{self.component}"
+
+    def affects(self, emitter: str) -> bool:
+        """Whether this axis can change what the given emitter's light looks like.
+
+        Attenuation depends on every dust distribution, but only on the stellar
+        distribution of the component being observed. So a geometric axis
+        belonging to another component's *stars* changes nothing, and tabulating
+        against it would repeat the same model. The original arranged this by
+        hand, pinning the spheroid scale to a single value when the disk was
+        emitting, which is why ``attenuationDisk`` carries no spheroid axis.
+        """
+        return "dust" in self.roles or self.component == emitter
+
+    def __len__(self) -> int:
+        return int(self.values.size)
+
+
+@dataclass(frozen=True)
+class Run:
+    """One model: a point on the parameter grid, seen from one emitting component."""
+
+    emitter: str
+    indices: tuple[int, ...]
+    """Index into each of :attr:`Campaign.axes`, in order."""
+    spec: ModelSpec
+    label: str
+
+    @property
+    def file_stem(self) -> str:
+        """A file name stem, with the characters a path would rather not carry."""
+        return self.label.replace(":", "_").replace("/", "_").replace(" ", "_")
+
+
+class Campaign:
+    """The set of models a configuration describes.
+
+    Parameters
+    ----------
+    config
+        The parsed configuration.
+    """
+
+    def __init__(self, config: CampaignConfig) -> None:
+        self.config = config
+        self.axes = tuple(self._axes())
+        self.wavelengths = values_of(config.tabulation.wavelengths)
+        self.inclinations = values_of(config.tabulation.inclinations)
+
+    def _axes(self) -> Iterator[Axis]:
+        for name, component in self.config.geometry.components.items():
+            roles = (("stellar", component.stellar), ("dust", component.dust))
+            for role, profile in roles:
+                if profile is None or role != "dust":
+                    continue
+                if profile.optical_depth is not None:
+                    yield Axis("opticalDepth", name, frozenset({role}), values_of(profile.optical_depth))
+            for parameter in GEOMETRIC:
+                kind = parameter.replace("_r", "R").replace("_h", "H")
+                # Group the roles which vary this parameter over identical
+                # values; each distinct set of values is one axis.
+                groups: list[tuple[NDArray[np.float64], set[str]]] = []
+                for role, profile in roles:
+                    if profile is None or getattr(profile, parameter, None) is None:
+                        continue
+                    values = values_of(getattr(profile, parameter))
+                    if values.size <= 1:
+                        continue
+                    for existing, members in groups:
+                        if existing.shape == values.shape and np.array_equal(existing, values):
+                            members.add(role)
+                            break
+                    else:
+                        groups.append((values, {role}))
+                for values, members in groups:
+                    yield Axis(kind, name, frozenset(members), values, qualified=len(groups) > 1)
+
+    @property
+    def emitters(self) -> tuple[str, ...]:
+        """Components with stars, each of which is tabulated separately."""
+        return tuple(
+            name
+            for name, component in self.config.geometry.components.items()
+            if component.stellar is not None
+        )
+
+    def axes_for(self, emitter: str) -> tuple[Axis, ...]:
+        """The axes the given emitter is actually tabulated against."""
+        return tuple(axis for axis in self.axes if axis.affects(emitter))
+
+    def shape_for(self, emitter: str) -> tuple[int, ...]:
+        """Length of each axis the given emitter is tabulated against."""
+        return tuple(len(axis) for axis in self.axes_for(emitter))
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """Length of each axis, in order."""
+        return tuple(len(axis) for axis in self.axes)
+
+    def __len__(self) -> int:
+        """How many models the campaign contains."""
+        return sum(int(np.prod(self.shape_for(emitter), dtype=int)) for emitter in self.emitters)
+
+    def _chosen(
+        self, indices: Sequence[int], axes: Sequence[Axis] | None = None
+    ) -> dict[tuple[str, str, str], float]:
+        """The value each axis takes at a point, keyed by component, role and parameter."""
+        chosen = {}
+        for axis, index in zip(axes if axes is not None else self.axes, indices, strict=True):
+            parameter = {"scaleRadial": "scale_radial", "scaleHeight": "scale_height"}.get(
+                axis.kind, "optical_depth"
+            )
+            for role in axis.roles:
+                chosen[(axis.component, role, parameter)] = float(axis.values[index])
+        return chosen
+
+    def galaxy(
+        self, indices: Sequence[int], axes: Sequence[Axis] | None = None, emitter: str | None = None
+    ) -> Galaxy:
+        """The galaxy at a point on the parameter grid, as one emitter sees it.
+
+        A component which neither emits for this run nor carries dust cannot
+        change the answer, and is left out. That is not merely an economy: a
+        component included needlessly still sizes the grid, and a large spheroid
+        sizing the grid for a disk-only model is what leaves the disk
+        unresolved. The original arranged the same thing by hand, pinning the
+        spheroid scale to zero whenever the disk was emitting.
+        """
+        chosen = self._chosen(indices, axes)
+
+        def build(name: str, role: str, profile: ProfileConfig | None):
+            if profile is None:
+                return None
+            overrides = {
+                parameter: value
+                for (component, kind, parameter), value in chosen.items()
+                if component == name and kind == role and parameter in GEOMETRIC
+            }
+            return profile.build(**overrides)
+
+        components = []
+        for name, component in self.config.geometry.components.items():
+            emits = emitter is None or name == emitter
+            if not emits and component.dust is None:
+                continue
+            components.append(
+                Component(
+                    name,
+                    stellar=build(name, "stellar", component.stellar) if emits else None,
+                    dust=build(name, "dust", component.dust),
+                )
+            )
+        return Galaxy(components)
+
+    def optical_depths(self, indices: Sequence[int], axes: Sequence[Axis] | None = None) -> dict[str, float]:
+        """The optical depth of each dust-bearing component at a point."""
+        chosen = self._chosen(indices, axes)
+        return {
+            component: value
+            for (component, _role, parameter), value in chosen.items()
+            if parameter == "optical_depth"
+        }
+
+    def runs(self) -> Iterator[Run]:
+        """Every model in the campaign, in a stable order.
+
+        The seed is decremented per model, as the original did, so that each gets
+        its own realization rather than repeating one.
+        """
+        tabulation = self.config.tabulation
+        seed = tabulation.seed
+        for emitter in self.emitters:
+            axes = self.axes_for(emitter)
+            for indices in product(*(range(len(axis)) for axis in axes)):
+                seed -= 1
+                suffix = "_".join(str(index) for index in indices)
+                yield Run(
+                    emitter=emitter,
+                    indices=indices,
+                    label=f"{self.config.label}_{emitter}" + (f"_{suffix}" if suffix else ""),
+                    spec=ModelSpec(
+                        galaxy=self.galaxy(indices, axes, emitter),
+                        emitter=emitter,
+                        optical_depths=self.optical_depths(indices, axes),
+                        wavelengths=self.wavelengths,
+                        inclinations=self.inclinations,
+                        cut_off=self.config.geometry.cut_off,
+                        photons=tabulation.photons,
+                        seed=seed,
+                    ),
+                )
+
+    def grid_options(self) -> Mapping[str, object]:
+        """Grid options from the configuration, to pass when building a model."""
+        geometry = self.config.geometry
+        return {
+            "spacing": geometry.spacing,
+            "radial_cells": geometry.radial_cells,
+            "vertical_cells": geometry.vertical_cells,
+        }
+
+    def __repr__(self) -> str:
+        axes = ", ".join(f"{axis.name}[{len(axis)}]" for axis in self.axes)
+        return f"Campaign({self.config.label!r}, {len(self)} models, axes: {axes})"