pythonradex 2.0.0__tar.gz → 2.0.1__tar.gz

{pythonradex-2.0.0 → pythonradex-2.0.1}/CITATION.cff

@@ -1,15 +1,17 @@
 cff-version: 1.2.0
 title: "pythonradex"
-version: 2.0.0
 license: "MIT"
 type: software
 repository-code: "https://github.com/gica3618/pythonradex"
 abstract: "pythonradex solves the 1D non-LTE radiative transfer for a homogeneous medium. It is a tool to quickly estimate the radiation from an astrophysical gas. It also provides a convenient function to read data files in the LAMDA format. pythonradex is a python re-implementation of the RADEX code, with additional functionality not included in RADEX (treatment of overlapping lines, treatment of dust continuum, output of spectra, and more)."
-message: "Please cite this software using the metadata from 'preferred-citation'."
+message: "If you use this software, please cite our article in the Journal of Open Source Software."
 authors:
   - given-names: Gianni
     family-names: Cataldi
-    affiliation: National Astronomical Observatory of Japan
+    orcid: "https://orcid.org/0000-0002-2700-9676"
+contact:
+  - family-names: Cataldi
+    given-names: Gianni
     orcid: "https://orcid.org/0000-0002-2700-9676"
 keywords:
   - python
@@ -19,3 +21,21 @@ keywords:
   - non-LTE
   - escape probability
   - line emission
+preferred-citation:
+  authors:
+  - family-names: Cataldi
+    given-names: Gianni
+    orcid: "https://orcid.org/0000-0002-2700-9676"
+  date-published: 2026-02-24
+  doi: 10.21105/joss.09233
+  issn: 2475-9066
+  issue: 118
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 9233
+  title: "pythonradex: a fast Python re-implementation of RADEX with
+    extended functionality"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.09233"
+  volume: 11

{pythonradex-2.0.0 → pythonradex-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonradex
-Version: 2.0.0
+Version: 2.0.1
 Summary: 1D non-LTE radiative transfer
 Project-URL: Documentation, https://pythonradex.readthedocs.io/en/latest/
 Project-URL: Issues, https://github.com/gica3618/pythonradex/issues
@@ -31,12 +31,29 @@ Provides-Extra: notebooks
 Requires-Dist: jupyter; extra == 'notebooks'
 Requires-Dist: matplotlib; extra == 'notebooks'
 Requires-Dist: pandas; extra == 'notebooks'
-Description-Content-Type: text/plain
+Description-Content-Type: text/markdown
 
 pythonradex solves the 1D non-LTE radiative transfer for a homogeneous medium. It is a tool to quickly estimate the radiation from an astrophysical gas. It also provides a convenient function to read data files in the LAMDA format. pythonradex is a python re-implementation of the RADEX code, with additional functionality not included in RADEX (treatment of overlapping lines, treatment of dust continuum, output of spectra, and more).
 
 For more details, please refer to the documentation: http://pythonradex.readthedocs.io/
 
+If you use pythonradex in your research, please cite the following [JOSS article](https://doi.org/10.21105/joss.09233):
+
+```tex
+@article{pythonradex,
+    doi = {10.21105/joss.09233},
+    url = {https://doi.org/10.21105/joss.09233},
+    year = {2026},
+    publisher = {The Open Journal},
+    volume = {11},
+    number = {118},
+    pages = {9233},
+    author = {Cataldi, Gianni},
+    title = {pythonradex: a fast Python re-implementation of RADEX with extended functionality},
+    journal = {Journal of Open Source Software}
+}
+```
+
 For questions, bug reports, or feature suggestions, please open an issue on github.
 
 pythonradex is written and maintained by Gianni Cataldi.

pythonradex-2.0.0/README.txt → pythonradex-2.0.1/README.md

@@ -2,6 +2,23 @@ pythonradex solves the 1D non-LTE radiative transfer for a homogeneous medium. I
 
 For more details, please refer to the documentation: http://pythonradex.readthedocs.io/
 
+If you use pythonradex in your research, please cite the following [JOSS article](https://doi.org/10.21105/joss.09233):
+
+```tex
+@article{pythonradex,
+    doi = {10.21105/joss.09233},
+    url = {https://doi.org/10.21105/joss.09233},
+    year = {2026},
+    publisher = {The Open Journal},
+    volume = {11},
+    number = {118},
+    pages = {9233},
+    author = {Cataldi, Gianni},
+    title = {pythonradex: a fast Python re-implementation of RADEX with extended functionality},
+    journal = {Journal of Open Source Software}
+}
+```
+
 For questions, bug reports, or feature suggestions, please open an issue on github.
 
 pythonradex is written and maintained by Gianni Cataldi.

pythonradex-2.0.1/docs/citation.rst

@@ -0,0 +1,18 @@
+Citation
+===================
+If you use ``pythonradex`` in your research, please cite the following `JOSS article <https://doi.org/10.21105/joss.09233>`__:
+
+.. code-block:: tex
+
+    @article{pythonradex,
+        doi = {10.21105/joss.09233},
+        url = {https://doi.org/10.21105/joss.09233},
+        year = {2026},
+        publisher = {The Open Journal},
+        volume = {11},
+        number = {118},
+        pages = {9233},
+        author = {Cataldi, Gianni},
+        title = {pythonradex: a fast Python re-implementation of RADEX with extended functionality},
+        journal = {Journal of Open Source Software}
+    } 

{pythonradex-2.0.0 → pythonradex-2.0.1}/joss_paper/paper.bib

@@ -21,7 +21,7 @@ author = {{Rybicki}, G.~B. and {Lightman}, A.~P.},
 doi = {10.1002/9783527618170.ch1},
 publisher = {John Wiley & Sons, Ltd},
 isbn = {9783527618170},
-title = {FUNDAMENTALS OF RADIATIVE TRANSFER},
+title = {Fundamentals of radiative transfer},
 booktitle = {Radiative Processes in Astrophysics},
 chapter = {1},
 pages = {1-50},
@@ -88,7 +88,7 @@ archivePrefix = {arXiv},
 
 @ARTICLE{AsensioRamos2018,
        author = {{Asensio Ramos}, Andr{\'e}s and {Elitzur}, Moshe},
-        title = "{MOLPOP-CEP: an exact, fast code for multi-level systems}",
+        title = {{MOLPOP-CEP}: an exact, fast code for multi-level systems},
       journal = {Astronomy and Astrophysics},
      keywords = {radiative transfer, line: formation, ISM: lines and bands, methods: numerical, Astrophysics - Instrumentation and Methods for Astrophysics},
          year = 2018,
@@ -131,7 +131,7 @@ archivePrefix = {arXiv},
 
 @inproceedings{Lam2015,
 author = {Lam, Siu Kwan and Pitrou, Antoine and Seibert, Stanley},
-title = {Numba: a LLVM-based Python JIT compiler},
+title = {Numba: a LLVM-based {Python} JIT compiler},
 year = {2015},
 isbn = {9781450340052},
 publisher = {Association for Computing Machinery},
@@ -172,8 +172,8 @@ series = {LLVM '15}
             Harris, Charles R. and Archibald, Anne M. and
             Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and
             {van Mulbregt}, Paul and {SciPy 1.0 Contributors}},
-  title   = {{{SciPy} 1.0: Fundamental Algorithms for Scientific
-            Computing in Python}},
+  title   = {{SciPy} 1.0: Fundamental Algorithms for Scientific
+            Computing in {Python}},
   journal = {Nature Methods},
   year    = {2020},
   volume  = {17},
@@ -222,7 +222,7 @@ url="https://doi.org/10.1007/978-94-011-2394-5_2"
 @ARTICLE{Schoier2005,
        author = {{Sch{\"o}ier}, F.~L. and {van der Tak}, F.~F.~S. and {van Dishoeck}, E.~F. and {Black}, J.~H.},
         title = "{An atomic and molecular database for analysis of submillimetre line observations}",
-      journal = {\aap},
+      journal = {Astronomy and Astrophysics},
      keywords = {astronomical data bases: miscellaneous, atomic data, molecular data, radiative transfer, ISM: atoms, ISM: molecules, Astrophysics},
          year = 2005,
         month = mar,

{pythonradex-2.0.0 → pythonradex-2.0.1}/joss_paper/paper.md

@@ -1,7 +1,7 @@
 ---
 title: 'pythonradex: a fast Python re-implementation of RADEX with extended functionality'
 tags:
-  - python
+  - Python
   - astronomy
   - astrophysics
   - radiative transfer
@@ -14,7 +14,7 @@ authors:
     orcid: 0000-0002-2700-9676
     affiliation: 1
 affiliations:
- - name: National Astronomical Observatory of Japan
+ - name: National Astronomical Observatory of Japan, 2-21-1 Osawa, Mitaka, Tokyo 181-8588, Japan
    index: 1
    ror: 052rrw050
 
@@ -25,7 +25,7 @@ bibliography: paper.bib
 
 # Summary
 
-A common task in astronomical research is to estimate the physical parameters (temperature, mass, density etc.) of a gas by using observed line emission. This often requires a calculation of how the radiation propagates via emission and absorption ("radiative transfer"). In radio and infrared astronomy, the Fortran code `RADEX` [@vanderTak2007] is a popular tool to solve the non-LTE radiative transfer of a uniform medium in a simplified geometry. I present a python re-implementation of `RADEX`: `pythonradex`. Written in python, it provides an easy and intuitive user interface, improved performance as well as additional functionality not included in `RADEX` (continuum effects and overlapping lines).
+A common task in astronomical research is to estimate the physical parameters (temperature, mass, density etc.) of a gas by using observed line emission. This often requires a calculation of how the radiation propagates via emission and absorption ("radiative transfer"). In radio and infrared astronomy, the Fortran code `RADEX` [@vanderTak2007] is a popular tool to solve the non-LTE radiative transfer of a uniform medium in a simplified geometry. I present a Python re-implementation of `RADEX`: `pythonradex`. Written in Python, it provides an easy and intuitive user interface, improved performance as well as additional functionality not included in `RADEX` (continuum effects and overlapping lines).
 
 # Statement of need
 
@@ -35,13 +35,13 @@ To interpret such data, a radiative transfer calculation is typically used [see
 
 If the medium is dense enough, local thermodynamic equilibrium (LTE) can be assumed. This considerably simplifies the radiative transfer calculation. A non-LTE calculation is considerably more complex and computationally expensive because the fractional population of the molecular energy levels needs to be solved for numerically [e.g. @vanderTak2007]. Typically, an iterative approach is used: from a first guess of the level populations, the radiation field is calculated. This radiation field is then used to solve for updated level populations. The iterations continue until convergence is reached.
 
-Various codes are available to solve the radiative transfer. Codes solving the radiative transfer in 3D are used for detailed calculations of sources with well-known geometries. Examples include `RADMC-3D` [@Dullemond2012] and `LIME` [@Brinch2010]. However, a full 3D calculation is often too computationally expensive if a large parameter space needs to be explored, in particular in non-LTE. 1D codes that quickly provide an approximate solution are a commonly used alternative. In this respect, the 1D non-LTE code `RADEX` [@vanderTak2007] has gained considerable popularity: as of February 10, 2026, the paper presenting `RADEX` [@vanderTak2007] has 1463 citations. The Fortan code `RADEX` solves the radiative transfer of a uniform medium using an escape probability formalism.
+Various codes are available to solve the radiative transfer. Codes solving the radiative transfer in 3D are used for detailed calculations of sources with well-known geometries. Examples include `RADMC-3D` [@Dullemond2012] and `LIME` [@Brinch2010]. However, a full 3D calculation is often too computationally expensive if a large parameter space needs to be explored, in particular in non-LTE. 1D codes that quickly provide an approximate solution are a commonly used alternative. In this respect, the 1D non-LTE code `RADEX` [@vanderTak2007] has gained considerable popularity: as of February 10, 2026, the paper presenting `RADEX` [@vanderTak2007] has 1463 citations. The Fortran code `RADEX` solves the radiative transfer of a uniform medium using an escape probability formalism.
 
-The python programming language is now widely used in astronomy. Still, no python version of `RADEX` is available, although some python wrappers such as `SpectralRadex` [@SpectralRadex] or `ndradex` [@ndradex], and even a Julia version [`Jadex`, @jadex], exist. Furthermore, `RADEX` cannot take into account the effects of an internal continuum field (typically arising from dust that is mixed with the gas), nor cross-excitation effects arising when transitions overlap in frequency. The `pythonradex` code addresses these concerns.
+The Python programming language is now widely used in astronomy. Still, no Python version of `RADEX` is available, although some Python wrappers such as `SpectralRadex` [@SpectralRadex] or `ndradex` [@ndradex], and even a Julia version [`Jadex`, @jadex], exist. Furthermore, `RADEX` cannot take into account the effects of an internal continuum field (typically arising from dust that is mixed with the gas), nor cross-excitation effects arising when transitions overlap in frequency. The `pythonradex` code addresses these concerns.
 
 # Implementation
 
-`pythonradex` is written in python and implements the Accelerated Lambda Iteration (ALI) scheme presented by @Rybicki1992. Like `RADEX`, an escape probability equation is used to calculate the radiation field for a given level population. This allows solving the radiative transfer iteratively. To speed up the convergence, ng-acceleration [@Ng1974] is employed. To improve performance, critical parts of the code are just-in-time compiled using `numba` [@Lam2015].
+`pythonradex` is written in Python and implements the accelerated lambda iteration (ALI) scheme presented by @Rybicki1992. Like `RADEX`, an escape probability equation is used to calculate the radiation field for a given level population. This allows solving the radiative transfer iteratively. To speed up the convergence, Ng acceleration [@Ng1974] is employed. To improve performance, critical parts of the code are just-in-time compiled using Numba [@Lam2015].
 
 `pythonradex` supports four geometries: two static geometries (slab and sphere), and two large-velocity-gradient (LVG) geometries (again slab and sphere). In the LVG approximation, it is assumed that all regions of the source are Doppler shifted with respect to each other due to a velocity gradient. This means that all photons escape the source, unless absorbed locally [i.e. close to the emission location, e.g. @Elitzur1992].
 
@@ -53,32 +53,31 @@ Like `RADEX`, `pythonradex` needs a file in LAMDA-format as input to read the mo
 
 `pythonradex` was benchmarked against `RADEX` for a number of example problems, generally with excellent agreement (see \autoref{fig:pythonradex_vs_radex} for an example). To test the treatment of overlapping lines, `pythonradex` was tested against the `MOLPOP-CEP` code [@AsensioRamos2018], again showing good agreement, as illustrated in \autoref{fig:HCN_spectrum}.
 
-![The ratio of CO 2-1 excitation temperature (left column) and optical depth (right column) computed with `pythonradex` and `RADEX` for a static sphere. Each panel shows a parameter space of H$_2$ density and column density for a fixed kinetic temperature. Values exceeding the colorbar range are shown in black with the corresponding value in white text.\label{fig:pythonradex_vs_radex}](code/pythonradex_vs_radex.pdf)
-
-![Spectrum of HCN around 177.3 GHz computed with `pythonradex` and `MOLPOP-CEP` for a static slab. Good agreement is found when treating line overlap. Interestingly, the spectra differ somewhat when ignoring overlap. The positions and widths of the individual hyperfine components are illustrated by the black dotted lines.\label{fig:HCN_spectrum}](code/HCN_spec.pdf)
-
-
 # Performance advantage
 
 <!-- Numbers in this section are from performance_comparison.py -->
-Both `pythonradex` and `RADEX` are single-threaded. To compare their performance, we consider the calculation of a grid of models over a parameter space spanning 20 values in each of kinetic temperature, column density and H$_2$ density (i.e. a total of 8000 models). We consider a few different molecules: C (small number of levels and transitions), SO (large number of levels and transitions) as well as CO and HCO$^+$ (intermediate). On a laptop with i7-7700HQ cores running on Ubuntu 22.04, `pythonradex` computed the model grid faster than `RADEX` by factors  of approximately 1.5 (C), 6 (SO), 7 (CO) and 3 (HCO$^+$). Running the same test on the Multi-wavelength Data Analysis System (MDAS) operated by the National Astronomical Observatory of Japan (Rocky Linux 8.9 with AMD EPYC 7543 CPUs) resulted in a even larger performance advantage: `pythonradex` calculated the grid faster by factors of 13 (C), 10 (SO), 13 (CO) and 12 (HCO$^+$)[^1].
+Both `pythonradex` and `RADEX` are single-threaded. To compare their performance, we consider the calculation of a grid of models over a parameter space spanning 20 values in each of kinetic temperature, column density and H$_2$ density (i.e. a total of 8000 models). We consider a few different molecules: C (small number of levels and transitions), SO (large number of levels and transitions) as well as CO and HCO$^+$ (intermediate). On a laptop with i7-7700HQ cores running on Ubuntu 22.04, `pythonradex` computed the model grid faster than `RADEX` by factors of approximately 1.5 (C), 6 (SO), 7 (CO) and 3 (HCO$^+$). Running the same test on the Multi-wavelength Data Analysis System (MDAS) operated by the National Astronomical Observatory of Japan (Rocky Linux 8.9 with AMD EPYC 7543 CPUs) resulted in an even larger performance advantage: `pythonradex` calculated the grid faster by factors of 13 (C), 10 (SO), 13 (CO) and 12 (HCO$^+$)[^1].
 
 [^1]: `Jadex` [@jadex] claims a performance advantage of a factor ~110 over `RADEX`.
 
+![The ratio of CO 2-1 excitation temperature (left column) and optical depth (right column) computed with `pythonradex` and `RADEX` for a static sphere. Each panel shows a parameter space of H$_2$ density and column density for a fixed kinetic temperature. Values exceeding the colorbar range are shown in black with the corresponding value in white text.\label{fig:pythonradex_vs_radex}](code/pythonradex_vs_radex.pdf)
+
+![Spectrum of HCN around 177.3 GHz computed with `pythonradex` and `MOLPOP-CEP` for a static slab. Good agreement is found when treating line overlap. Interestingly, the spectra differ somewhat when ignoring overlap. The positions and widths of the individual hyperfine components are illustrated by the black dotted lines.\label{fig:HCN_spectrum}](code/HCN_spec.pdf)
+
 # Additional differences between `RADEX` and `pythonradex`
 
 ## Output flux
 
-`RADEX` computes line fluxes based on a "background subtracted" intensity given by $(B_\nu(T_\mathrm{ex})-I_\mathrm{bg})(1-e^{-\tau})$, where $B_\nu$ is the Planck function, $T_\mathrm{ex}$ the excitation temperature, $I_\mathrm{bg}$ the external background and $\tau$ the (frequency-dependent) optical depth. This may or may not be the right quantity to be compared to observations (for example, it is not appropriate when considering data from interferometers like ALMA). `pythonradex` does not apply any observational correction, giving the user the flexibility to decide how the computed fluxes are compared to observations.
+`RADEX` computes line fluxes based on a "background subtracted" intensity given by $(B_\nu(T_\mathrm{ex})-I_\mathrm{bg})(1-e^{-\tau})$, where $B_\nu$ is the Planck function, $T_\mathrm{ex}$ the excitation temperature, $I_\mathrm{bg}$ the external background and $\tau$ the (frequency-dependent) optical depth. This may or may not be the right quantity to be compared to observations. For example, it is not appropriate when considering data from interferometers like ALMA. `pythonradex` does not apply any observational correction, giving the user the flexibility to decide how to compare the computed fluxes to observations.
 
 ## Flux for spherical geometry
 
 To calculate line fluxes, `pythonradex` uses different formulae depending on the geometry (see the [`pythonradex` documentation](https://pythonradex.readthedocs.io/en/latest/index.html) for more details). On the other hand, `RADEX` always uses the formula for a slab. \autoref{fig:flux_comparison_sphere} illustrates the consequences. For a static sphere, by using the slab formula, the flux is overestimated by a factor 1.5[^2] in the optically thin limit. In the optically thick case, only the surface of the static sphere is visible, so the different formulae give the same result. On the other hand, for the LVG sphere, the difference is always a factor 1.5 regardless of optical depth. This is a consequence of the LVG assumption that photons always escape unless absorbed locally. By computing the optically thin flux directly[^3], it can be confirmed that the formulae used by `pythonradex` are correct.
 
-[^2]: The factor 1.5 simply corresponds to the volume ratio of a "spherical slab" (i.e. a cylinder) to a sphere.
+[^2]: The factor 1.5 corresponds to the volume ratio of a "spherical slab" (i.e. a cylinder) to a sphere.
 [^3]: In units of W/m$^2$, $F_\mathrm{thin} = V_\mathrm{sphere}n_2A_{21}\Delta E \frac{1}{4\pi d^2}$ with $V_\mathrm{sphere}=\frac{4}{3}R^3\pi$ the volume of the sphere, $n$ the number density, $x_2$ the fractional level population of the upper level, $A_{21}$ the Einstein coefficient, $\Delta E$ the energy of the transition and $d$ the distance.
 
-<!-- This figure comes from  manual_test_and_benchmarks/emerging_flux/compare_emerging_flux_formula.py -->
+<!-- This figure comes from manual_test_and_benchmarks/emerging_flux/compare_emerging_flux_formula.py -->
 ![For the two spherical geometries, fluxes using the slab formula (as done by `RADEX`) and formulae appropriate for a sphere (as done by `pythonradex`) were calculated. The figure shows the ratio of the fluxes as function of optical depth.\label{fig:flux_comparison_sphere}](flux_comparison_spherical_geometries.pdf)
 
 
@@ -86,9 +85,9 @@ To calculate line fluxes, `pythonradex` uses different formulae depending on the
 
 `pythonradex` depends on the following packages:
 
-* `numpy` [@Harris2020]
-* `scipy` [@Virtanen2020]
-* `numba` [@Lam2015]
+* NumPy [@Harris2020]
+* SciPy [@Virtanen2020]
+* Numba [@Lam2015]
 
 # Acknowledgements
 

{pythonradex-2.0.0 → pythonradex-2.0.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "pythonradex"
 description = '1D non-LTE radiative transfer'
-readme = "README.txt"
+readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 keywords = ['radiative transfer', 'radex', 'non-LTE']

{pythonradex-2.0.0 → pythonradex-2.0.1}/src/pythonradex/__init__.py

@@ -4,3 +4,6 @@ Python implementation of the RADEX radiative transfer code
 """
 
 from . import helpers, LAMDA_file, radiative_transfer
+from importlib.metadata import version
+
+__version__ = version("pythonradex")

pythonradex-2.0.0/docs/citation.rst

@@ -1,3 +0,0 @@
-Citation
-===================
-A paper describing ``pythonradex`` will be published shortly. In the mean time, please just cite the gihub repository (https://github.com/gica3618/pythonradex) in your paper.

pythonradex-2.0.0/src/pythonradex/__about__.py

@@ -1,4 +0,0 @@
-# SPDX-FileCopyrightText: 2025-present Gianni Cataldi <cataldi.gia@gmail.com>
-#
-# SPDX-License-Identifier: MIT
-__version__ = "0.0.1"