Release 3 x

.readthedocs.yaml

@@ -1,31 +1,24 @@
 # .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
 # Required
 version: 2
-
 # Set the version of Python and other tools you might need
 build:
-    os: ubuntu-22.04
-    tools:
-        python: "3.10"
-        # You can also specify other tool versions:
-        # nodejs: "19"
-        # rust: "1.64"
-        # golang: "1.19"
-
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync
+    install:
+      - "true"
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-    configuration: docs/source/conf.py
-
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
-
-# Optionally declare the Python requirements required to build your docs
-python:
-    install:
-        - requirements: requirements.txt
-        - method: pip
-          path: .
+  configuration: docs/source/conf.py
+# Optionally build your docs in additional formats such as PDF
+#formats:
+#  - pdf

CHANGES.md

@@ -1,5 +1,58 @@
 ## Change Log
 
+### Release 3.0.1
+
+#### _Models_
+
+- New models for the Small Magellanic Cloud (z=0.2) including alternate view angles i=0 (face-on) to i=75.
+
+- Previous 2006 SMC models are now deprecated.
+
+
+#### _Measurement_
+
+- *Measurement.to()* method added to convert units
+- small bug fixes, dead code removal
+
+#### _LineRatioFit_
+
+- Significant performance improvement for map data, ~10x via addition of `joint_fit` keyword and parallel workers
+- Allow users to limit the model space used during the fit with `radiation_field_range` and `density_range` keywords
+
+#### _Excitation Tool_
+
+
+- Added C18O, 13C18O, CH+ to provided molecules
+- Robust piecewise initialization for first fit guess instead of quick and dirty which could sometimes fail.
+- Parallel workers for ~2x performance improvement
+
+#### _Notebooks_
+
+- `Image Radiation Field and Density` notebook updated to use new SMC models and to demonstrate use of  `radiation_field_range` and `density_range` keywords `
+- `H2 Excitation` notebook split into two notebooks for single pixel and map fitting, respectively.  Map fitting now uses observational data from JWST instead of simulated data.
+
+#### _Code cleanup, refactoring, etc._
+
+- `pdrutils.py` split into individual modules *utils.fits*, *utils.helpers*, *utils.paths*, *utils.units*, *utils.wcs*. Done in a backwards compatiable way so *import pdrutils as utils* still works.
+- `pdrtpy.plot` module refactored and new tests added
+- `excitation.py` - refactored to remove dead code, dedupe, vectorize
+- All documentation changed to `numpydoc` format
+- Benchmark code for performance improvements
+- Update scripts for verifying and adding new models
+
+#### _Issues_
+
+- Reorganized `pdrutils.py` into `utils` submodules while preserving backward compatibility ([#204](https://github.com/mpound/pdrtpy/issues/204))
+- Added option to use wavelength on the X-axis of H<sub>2</sub> excitation diagrams ([#176](https://github.com/mpound/pdrtpy/issues/176))
+- Documented FIR wavelength range ([#181](https://github.com/mpound/pdrtpy/issues/181))
+- Converted all code documentation to numpydoc format ([#103](https://github.com/mpound/pdrtpy/issues/103))
+- Verified test suite parallelization across platforms ([#70](https://github.com/mpound/pdrtpy/issues/70))
+- Added `Measurement.to()` method for unit conversion ([#62](https://github.com/mpound/pdrtpy/issues/62))
+- Fixed weird colorbar spacing in `LineRatioPlot.ratios_on_models` ([#35](https://github.com/mpound/pdrtpy/issues/35))
+- Fixed missing centerlines in `overlay_all_ratios` plot when exported to PDF ([#23](https://github.com/mpound/pdrtpy/issues/23))
+
+
+
 ### Release 2.6.4
 
 #### _Models_

README.rst

@@ -14,16 +14,12 @@ PhotoDissociation Region Toolbox --- Python
  :target: http://www.repostatus.org/#active
  :alt: Project Status: Active - The project has reached a stable, usable state and is being actively developed.
 
-.. image:: https://img.shields.io/pypi/pyversions/pdrtpy.svg?style=plastic
- :target: https://img.shields.io/pypi/pyversions/pdrtpy.svg?style=plastic
- :alt: Python version
-
 .. image:: https://img.shields.io/badge/License-GPLv3-blue.svg?style=plastic
  :target: https://www.gnu.org/licenses/gpl-3.0
  :alt: GNU GPL v3 License
 
-.. image:: https://readthedocs.org/projects/pdrtpy/badge/?version=latest&style=plastic
- :target: https://pdrtpy.readthedocs.io/en/latest/?badge=latest
+.. image:: https://readthedocs.org/projects/pdrtpy/badge/?version=stable&style=plastic
+ :target: https://pdrtpy.readthedocs.io/en/stable/
  :alt: Documentation status
 
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=plastic
@@ -38,7 +34,7 @@ PhotoDissociation Region Toolbox --- Python
    :target: https://results.pre-commit.ci/latest/github/mpound/pdrtpy/master
    :alt: pre-commit.ci status
 
-``pdrtpy`` is the Python `PhotoDissociation Region Toolbox <http://dustem.astro.umd.edu/>`_.  The current stable version is 2.6.4
+``pdrtpy`` is the Python `PhotoDissociation Region Toolbox <http://dustem.astro.umd.edu/>`_.  The current stable version is 3.0.1
 
 The PDR Toolbox is a science-enabling tool for the community, designed to
 help astronomers determine the physical parameters of photodissociation
@@ -49,25 +45,31 @@ Spitzer, STO, and Herschel. Given a set of observations of spectral line or
 continuum intensities, PDR Toolbox can compute best-fit FUV incident
 intensity and cloud density based on our models of PDR emission.
 
-The PDR Toolbox will cover a wide range of spectral lines and metallicities
+The PDR Toolbox covers a wide range of spectral lines and metallicities
 and allows map-based analysis so users can quickly compute spatial
 images of density and radiation field from map data.  We provide Jupyter
 `Example Notebooks`_ for data analysis.  It also can support models from
-other PDR codes enabling comparison of derived properties between codes.
-
-The underlying PDR model code has improved physics and chemistry. Critical updates include those discussed in
-`Neufeld & Wolfire 2016 <https://ui.adsabs.harvard.edu/abs/2016ApJ...826..183N/abstract>`_, plus photo rates from
-`Heays et al. 2017 <https://ui.adsabs.harvard.edu/abs/2017A%26A...602A.105H/abstract>`_, oxygen chemistry rates from
-`Kovalenko et al. 2018 <https://ui.adsabs.harvard.edu/abs/2018ApJ...856..100K/abstract>`_ and
-`Tran et al. 2018 <https://ui.adsabs.harvard.edu/abs/2018ApJ...854...25T/abstract>`_,
-and carbon chemistry rates from
-`Dagdigian 2019 <https://ui.adsabs.harvard.edu/abs/2019MNRAS.487.3427D/abstract>`_. We have also implemented new collisional
-excitation rates for |OI| from
-`Lique et al. 2018 <https://ui.adsabs.harvard.edu/abs/2018MNRAS.474.2313L/abstract>`_ (and Lique private
-communication) and have included |13C| chemistry along with the
-emitted line intensities for  |13CII| and |13CO|.
-
-We also support fitting of temperatures and column densities of excitation diagrams of |H2|, CO, and |13CO| excitation diagrams.  Users can fit other molecules by providing appropriate transition data.
+other PDR codes enabling comparison of derived properties between codes. It supports models from
+multiple PDR codes enabling comparison of derived properties between codes.
+
+
+We suppoort PDR models from:
+
+* The Wolfire-Kaufman PDR  code which has physics and chemistry updates such as those discussed in
+    `Neufeld & Wolfire 2016 <https://ui.adsabs.harvard.edu/abs/2016ApJ...826..183N/abstract>`_, plus photo rates from
+    `Heays et al. 2017 <https://ui.adsabs.harvard.edu/abs/2017A%26A...602A.105H/abstract>`_, oxygen chemistry rates from
+    `Kovalenko et al. 2018 <https://ui.adsabs.harvard.edu/abs/2018ApJ...856..100K/abstract>`_ and
+    `Tran et al. 2018 <https://ui.adsabs.harvard.edu/abs/2018ApJ...854...25T/abstract>`_,
+    and carbon chemistry rates from
+    `Dagdigian 2019 <https://ui.adsabs.harvard.edu/abs/2019MNRAS.487.3427D/abstract>`_. We have also implemented new collisional
+    excitation rates for |OI| from
+    `Lique et al. 2018 <https://ui.adsabs.harvard.edu/abs/2018MNRAS.474.2313L/abstract>`_ (and Lique private
+    communication) and have included |13C| chemistry along with the
+    emitted line intensities for  |13CII| and |13CO|.
+
+* The `KOSMA-tau code <https://markusroellig.github.io/research/KOSMA-tau/>`_, which supports spherical geometry.
+
+We also support fitting of temperatures and column densities of excitation diagrams of |H2|, CO, |13CO|. |C18O|, and |CH+|, in both single pixels and maps.  Users can fit other molecules by providing appropriate transition data.
 
 Up to date documentation can be found at `pdrtpy.readthedocs.io <http://pdrtpy.readthedocs.io/>`_.
 
@@ -93,29 +95,14 @@ Installation
 Requirements
 ^^^^^^^^^^^^
 
-``pdrtpy`` requires Python 3 and recent versions of  `astropy <https://astropy.org>`_, `numpy <https://numpy.org>`_, `scipy <https://scipy.org>`_, `lmfit <https://lmfit.github.io/lmfit-py/>`_, and `matplotlib <https://matplotlib.org/>`_. If you want to run the `Example Notebooks`_, you also need `jupyter <https://jupyter.org>`_.
-
-First make sure you are using Python 3.10 or higher:
-
-.. code-block:: sh
-
-   python --version
-
-should show e.g., *3.11.7*.
+``pdrtpy`` requires Python 3.11+ and recent versions of  `astropy <https://astropy.org>`_, `numpy <https://numpy.org>`_, `scipy <https://scipy.org>`_, `lmfit <https://lmfit.github.io/lmfit-py/>`_, and `matplotlib <https://matplotlib.org/>`_. If you want to run the `Example Notebooks`_, you also need `jupyter <https://jupyter.org>`_.
 
 
-.. Also, make sure *setuptools* is up to date:
-
-.. .. code-block:: sh
-
-..   pip install -U setuptools
-
 Install the package
 ^^^^^^^^^^^^^^^^^^^
 
 With pip
 --------
-Python has numerous ways to install packages; the easiest is with *pip*.
 The code is hosted at the `Python Packaging Index <https://pypi.org/project/pdrtpy/>`_, so you can type:
 
 .. code-block:: sh
@@ -128,7 +115,15 @@ If you do not have permission to install into your Python system package area, y
 
    pip install --user pdrtpy
 
-* For installation from github, see `For Developers`_ below.
+From github
+-----------
+
+.. code-block:: sh
+
+   git clone https://github.com/mpound/pdrtpy
+   cd pdrtpy
+   uv sync
+   uv run ipython
 
 Then go ahead and install the `Example Notebooks`_.
 
@@ -154,7 +149,8 @@ To familiarize yourself with the capabilities of ``pdrtpy``, we suggest you do t
 - `Determining Radiation Field and Intensity <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_Find_n_G0_Single_Pixel.ipynb>`_
 - `Image Radiation Field and Intensity for Maps <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_Make_n_G0_maps.ipynb>`_
 - `Using Alternate Viewing Angle PDR Models to fit emission maps of the Horsehead. <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_EdgeOnModelHorsehead.ipynb>`_
-- `Fitting |H2| Excitation Diagrams <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_H2_Excitation.ipynb>`_
+- `Fitting H2 Excitation Diagrams <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_H2_Excitation.ipynb>`_
+-  `Fitting H2 Excitation on Spatial Maps <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_H2_Excitation_Maps.ipynb>`_
 - `Adding Custom Models <https://github.com/mpound/pdrtpy-nb/blob/master/notebooks/PDRT_Example_Adding_Models.ipynb>`_
 
 Getting Help & Giving Feedback
@@ -178,27 +174,18 @@ to see the main new features we want to build.  You can help out with those or s
 
 For Developers
 --------------
-If you plan to tinker with the code, you should fork the repo and work on your own fork.  Point your browser to
-`https://github.com/mpound/pdrtpy <https://github.com/mpound/pdrtpy>`_
-and click on *fork* in the upper right corner.   After you have made your changes, create a pull request to merge them into the master branch.
-
-You may want to use a virtual environment to protect from polluting your daily working environment (especially if you have a stable version of `pdrtpy` installed).
+For developing pdrtpy code, we recommend the use of a python virtual environment. The example above uses `uv <https://docs.astral.sh/uv/>`_. Before installing pdrtpy, developers should install uv following `one of the methods in the uv docs <https://docs.astral.sh/uv/getting-started/installation/>`_. uv is the only tool that can sync the environment to the lockfile, so to install the known working development environment, uv is needed.  If you plan to tinker with the code, you should fork the repo and work on your own fork.     After you have made your changes, create a pull request to merge them into the master branch.
 
-.. code-block:: sh
-
-   sudo apt-get install python3-venv
-   python -m venv ~/pdrtpy_venv
-   source ~/pdrtpy_venv/bin/activate[.csh]
-   cd pdrtpy
-   pip install -r requirements.txt
-   pip install -e .
 
+.
 
 .. |reg|    unicode:: U+000AE .. REGISTERED SIGN
 .. |13C|    replace:: :sup:`13`\ C
 .. |13CO|   replace:: :sup:`13`\ CO
+.. |C18O| replace:: C\ :sup:`18`\ O
+.. |CH+| replace:: CH\ :sup:`+`
 .. |13CII|  replace:: [\ :sup:`13`\ C II]
 .. |OI|  replace:: [O I]
 .. |CII|  replace:: [C II]
 .. |H2|  replace:: H\ :sub:`2`
-.. |nu|     unicode:: 0x3bd .. greek nu
+.. |nu|   unicode:: 0x3bd .. greek nu

pdrtpy/__init__.py

@@ -1,6 +1,6 @@
 """Top level package for pdrtpy"""
 
-__version__ = "2.7.4"
+__version__ = "3.0.1"
 
 VERSION = __version__
 AUTHORS = "Marc W. Pound, Mark G. Wolfire"

pdrtpy/measurement.py

@@ -357,7 +357,7 @@ def to(self, unit: str | u.Unit, equivalencies: list | None = None):
             equivalencies = []
         return self.convert_unit_to(unit, equivalencies)
 
-    def write(self, filename, **kwd):
+    def write(self, filename, **kwargs):
         """Write this Measurement to a FITS file with value in 1st HDU and error in 2nd HDU.
 
         See :meth:`astropy.nddata.CCDData.write`.
@@ -366,11 +366,11 @@ def write(self, filename, **kwd):
         ----------
         filename : str
             Name of file.
-        **kwd
+        **kwargs
             All additional keywords are passed to :py:mod:`astropy.io.fits`.
         """
         hdu = self.to_hdu()
-        hdu.writeto(filename, **kwd)
+        hdu.writeto(filename, **kwargs)
 
     def _set_up_for_interp(self, kind="linear"):
         # @TODO this will always return nan if there are nan in the data.
@@ -700,7 +700,7 @@ def from_table(filename, format="ipac", array=False):
 
 
 def fits_measurement_reader(
-    filename, hdu=0, unit=None, hdu_mask="MASK", hdu_flags=None, key_uncertainty_type="UTYPE", **kwd
+    filename, hdu=0, unit=None, hdu_mask="MASK", hdu_flags=None, key_uncertainty_type="UTYPE", **kwargs
 ):
     """FITS file reader for Measurement class, called by :meth:`Measurement.read`.
 
@@ -729,7 +729,7 @@ def fits_measurement_reader(
         Currently not implemented. Default: None.
     key_uncertainty_type : str, optional
         Header key name where the uncertainty class name is stored. Default: ``'UTYPE'``.
-    **kwd
+    **kwargs
         Additional keyword parameters passed to the FITS reader in :mod:`astropy.io.fits`.
 
     Raises
@@ -738,14 +738,14 @@ def fits_measurement_reader(
         If the conversion from CCDData to Measurement fails.
     """
 
-    _id = kwd.pop("identifier", "unknown")
-    _title = kwd.pop("title", None)
-    _squeeze = kwd.pop("squeeze", True)
-    _restfreq = kwd.pop("restfreq", None)
+    _id = kwargs.pop("identifier", "unknown")
+    _title = kwargs.pop("title", None)
+    _squeeze = kwargs.pop("squeeze", True)
+    _restfreq = kwargs.pop("restfreq", None)
     # suppress INFO messages about units in FITS file. e.g. useless ones like:
     # "INFO: using the unit erg / (cm2 s sr) passed to the FITS reader instead of the unit erg s-1 cm-2 sr-1 in the FITS file."
     log.setLevel("WARNING")
-    z = CCDData.read(filename, unit=unit)
+    z = CCDData.read(filename, unit=unit, **kwargs)
     if _squeeze:
         z = utils.squeeze(z)
 

pdrtpy/models/dotar

@@ -1,6 +1,6 @@
   /bin/rm -rf *.tgz
   tar cvfz kt2013_models.tgz kosmatau
   tar cvfz wk2020_models.tgz wolfirekaufman/version2020
+  tar cvfz wk_smc_models.tgz ./wolfirekaufman/version2020/constant_density/smc/
   tar cvfz wk2006_models.tgz wolfirekaufman/version2006
   tar cvfz lmc_models.tgz ./wolfirekaufman/version2020/constant_density/lmc
-  tar cvfz smc_models.tgz ./wolfirekaufman/version2006/constant_density/smc/