pythonradex 1.0.0__tar.gz

pythonradex-1.0.0/.gitignore

@@ -0,0 +1,125 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+#Gianni added:
+docs/__static/
+docs/_templates/
+
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+virt_env/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# Gianni stuff
+tests/RADEX_test_cases/*.out
+tests/RADEX_test_cases/radex.in
+tests/Radex
+manual_tests_and_benchmarks/lime/lime-master
+manual_tests_and_benchmarks/lime/template_model.c
+manual_tests_and_benchmarks/molpop-cep_benchmark/Gianni_models/*.out
+manual_tests_and_benchmarks/molpop-cep_benchmark/molpop
+manual_tests_and_benchmarks/molpop-cep_benchmark/molpop-cep-master
+TODO.txt
+documents
+manual_tests_and_benchmarks/benchmarking_vs_RADEX_and_LIME/*.fits
+**/radex.out
+.pytest_cache
+manual_tests_and_benchmarks/performance_tests/radex_test_performance.out
+virtenv_cheatsheet.txt
+pytest_cheatsheet.txt
+testPyPi_instructions.txt

pythonradex-1.0.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .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.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

pythonradex-1.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Gianni Cataldi
+
+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.

pythonradex-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+include README.txt

pythonradex-1.0.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: pythonradex
+Version: 1.0.0
+Summary: 1D non-LTE radiative transfer
+Project-URL: Documentation, https://pythonradex.readthedocs.io/en/latest/
+Project-URL: Issues, https://github.com/gica3618/pythonradex/issues
+Project-URL: Source, https://github.com/gica3618/pythonradex
+Author-email: Gianni Cataldi <cataldi.gia@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: non-LTE,radex,radiative transfer
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: numba>=0.61.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.14
+Description-Content-Type: text/plain
+
+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 from the LAMDA database. 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,...)
+
+For more details, please refer to the documentation: http://pythonradex.readthedocs.io/
+
+pythonradex is written and maintained by Gianni Cataldi

pythonradex-1.0.0/PyPi_publication_cheatsheet.txt

@@ -0,0 +1,2 @@
+see https://www.pyopensci.org/python-package-guide/tutorials/publish-pypi.html
+

pythonradex-1.0.0/README.txt

@@ -0,0 +1,5 @@
+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 from the LAMDA database. 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,...)
+
+For more details, please refer to the documentation: http://pythonradex.readthedocs.io/
+
+pythonradex is written and maintained by Gianni Cataldi

pythonradex-1.0.0/docs/API.rst

@@ -0,0 +1,66 @@
+API
+=====
+
+.. _rad_trans_API:
+
+The ``Cloud`` class
+------------------------------------
+The core of ``pyhonradex`` is the ``Cloud`` class which is used to solve the radiative transfer.
+
+.. autoclass:: pythonradex.radiative_transfer.Cloud
+    :members: __init__, update_parameters, solve_radiative_transfer, fluxes_of_individual_transitions, tau_nu, spectrum, model_grid, print_results 
+
+.. _read_LAMDA_API:
+
+Reading LAMDA files
+-------------------------
+``pyhonradex`` provides a convenient function in the ``LAMDA_file`` module to read files from the LAMDA database:
+
+.. autofunction:: pythonradex.LAMDA_file.read
+
+.. _atomic_transition_API:
+
+Representation of molecular levels and transitions
+---------------------------------------------------------
+``pyhonradex`` contains a number of classes to represent molecular data such as the energy levels and transitions between these levels. The molecular data is typically read from a `LAMDA file <https://home.strw.leidenuniv.nl/~moldata>`_.
+
+.. autoclass:: pythonradex.atomic_transition.Level
+    :members:
+
+.. autoclass:: pythonradex.atomic_transition.RadiativeTransition
+    :members: Tex
+
+.. autoclass:: pythonradex.atomic_transition.EmissionLine
+    :members: Tex,tau_nu0,tau_nu
+
+.. autoclass:: pythonradex.atomic_transition.CollisionalTransition
+    :members: Tex,coeffs
+
+.. _Molecule_API:
+
+.. autoclass:: pythonradex.molecule.Molecule
+    :members: __init__, LTE_level_pop
+
+.. autoclass:: pythonradex.molecule.EmittingMolecule
+    :members: __init__, get_tau_nu0_lines, get_tau_nu0_lines_LTE, get_Tex
+
+.. _line_profiles_API:
+
+Representation of line profiles
+---------------------------------
+``pyhonradex`` allows two types of line profiles: Gaussian and rectangular. These are represented by the following classes.
+
+.. autoclass:: pythonradex.atomic_transition.GaussianLineProfile
+    :members: phi_nu,phi_v
+    
+.. autoclass:: pythonradex.atomic_transition.RectangularLineProfile
+    :members: phi_nu,phi_v
+
+.. _helpers_API:
+
+Convenience functions
+--------------------------
+The ``helpers`` module provides a number of convenience functions.
+
+.. automodule:: pythonradex.helpers
+    :members: B_nu,generate_CMB_background,FWHM2sigma

pythonradex-1.0.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pythonradex-1.0.0/docs/citation.rst

@@ -0,0 +1,3 @@
+Citation
+===================
+If you use ``pythonradex`` in your research, please cite XXXXXXXXXXXXXXXXXXXXXXXXXXX

pythonradex-1.0.0/docs/conf.py

@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+#Gianni:
+sys.path.append(os.path.abspath('../src'))
+#take some info from pyproject.toml:
+from sphinx_pyproject import SphinxConfig
+config = SphinxConfig("../pyproject.toml", globalns=globals())
+
+
+# -- Project information -----------------------------------------------------
+
+project = config.name
+copyright = '2025, Gianni Cataldi'
+author = config.author
+
+# The full version, including alpha/beta/rc tags
+release = version = config.version
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
+    'sphinx_rtd_theme',
+    "nbsphinx",
+    "sphinx.ext.napoleon"
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+#Gianni additions
+autodoc_member_order = 'bysource'
+
+html_context = {
+    "display_github": True, # Integrate GitHub
+    "github_user": "gica3618", # Username
+    "github_repo": "pythonradex", # Repo name
+    "github_version": "master", # Version
+    "conf_py_path": "/docs/", # Path in the checkout to the docs root
+}

pythonradex-1.0.0/docs/difference_pythonradex_RADEX.rst

@@ -0,0 +1,30 @@
+Differences between ``pythonradex`` and ``RADEX``
+------------------------------------------------------
+
+Overlapping lines and continuum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``pythonradex`` is able to handle excitation effects of overlapping lines (i.e. lines that are so close in frequency that photons emitted from one line can be absorbed by another line). ``pythonradex`` is also able to include effects of an internal radiation field specified by the user (typically arising from dust that is mixed with the gas). Both of these effects are not included in ``RADEX``.
+
+Programming language and performance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+While ``RADEX`` is written in Fortran, ``pythonradex`` is written in python. Fortran is generally much faster than python. Still, in the typical use case of calculating several models over a grid of parameters (e.g. column density, temperature), ``pythonradex`` can outperform RADEX by a factor of a few, depending on the input parameters. This is achieved by an architecture that avoids unnecessary or repeating calculations as much as possible and just-in-time compilation using the `numba <https://numba.readthedocs.io>`_ package.
+
+Different output
+^^^^^^^^^^^^^^^^^^^^^^
+There is a difference between the outputs of ``RADEX`` and ``pythonradex``. The ``RADEX`` output :math:`T_R` (or the corresponding flux outputs) is intended to be directly compared to telescope data. To be more specific, from the computed optical depth and excitation temperature, ``RADEX`` first computes :math:`I_\mathrm{tot} = B_\nu(T_\mathrm{ex})(1-e^{-\tau_\nu}) + I_\mathrm{bg}e^{-\tau_\nu}`, i.e. the total intensity at the line centre that is recorded at the telescope, where :math:`I_\mathrm{bg}` is the background radiation. This is the sum of the radiation from the gas (first term) and the background radiation attenuated by the gas (second term). From this, ``RADEX`` assumes the observer has subtracted the background, giving :math:`I_\mathrm{measured} = I_\mathrm{tot} - I_\mathrm{bg} = (B_\nu(T_\mathrm{ex})-I_\mathrm{bg})(1-e^{-\tau_\nu})`. The ``RADEX`` output :math:`T_R` is the Rayleigh-Jeans temperature corresponding to :math:`I_\mathrm{measured}`. This output may or may not be the right quantity to be compared to observations. For example, it is almost certainly not appropriate to be compared to interferometric data. On the other hand, ``pythonradex`` outputs the pure line flux without any background subtraction, i.e. the output corresponds simply to the flux emitted by the gas (for a slab geometry, that would simply be :math:`B_\nu(T_\mathrm{ex})(1-e^{-\tau_\nu}))`. This allows the user to decide how the flux should be compared to observations, which depends on the telescope etc.
+
+.. _sphere_flux_difference:
+
+Different flux for spherical geometry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For a given excitation temperature :math:`T_{ex}` and optical depth :math:`\tau_\nu`, ``RADEX`` calculates the flux as
+
+.. math::
+    I_\nu = B_\nu(T_{ex})(1-e^{-\tau_\nu})
+
+for all geometries. However, this expression is only valid for slab geometries, but not for spherical geometries ("uniform sphere" and "LVG sphere"). On the other hand, ``pythonradex`` uses the correct formulae for spherical geometries (see the :ref:`section about geometries<geometries>` for more details). This can for example be demonstrated by considering the optically thin limit. In this limit, each photon escapes from the cloud. The total flux (in [W/m\ :sup:`2`]) is then simply given by
+
+.. math::
+    F_\mathrm{thin} = V_\mathrm{sphere}nx_2A_{21}\Delta E \frac{1}{4\pi d^2}
+
+where :math:`V_\mathrm{sphere}=\frac{4}{3}R^3\pi` is the volume of the sphere, :math:`n` the constant number density, :math:`x_2` the fractional level population of the upper level, :math:`A_{21}` the Einstein coefficient, :math:`\Delta E` the energy difference between the upper and lower level, and :math:`d` the distance of the source. ``pythonradex`` correctly reproduces this limiting case. On the other hand, ``RADEX`` overestimates the optically thin flux by a factor 1.5.

pythonradex-1.0.0/docs/examples.rst

@@ -0,0 +1,16 @@
+.. _examples:
+
+Examples
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   notebooks/get_started
+   notebooks/simple_example
+   notebooks/grid_search
+   notebooks/optically_thick_spectrum
+   notebooks/overlapping_lines
+   notebooks/LVG_geometry
+   notebooks/continuum_effects
+   notebooks/reading_LAMDA_files

pythonradex-1.0.0/docs/faq.rst

@@ -0,0 +1,11 @@
+FAQ
+==========
+
+How should negative optical depth be interpreted?
+----------------------------------------------------------
+
+As discussed by [vanderTak07]_, for certain parameters ("especially low density and/or strong radiation field", to quote [vanderTak07]_), negative optical depth can arise due to a level population inversion. This requires non-local treatement of the radiative transfer, which is not possible with ``pyhonradex``. The results should still be valid, though less accurate, for optical depths only slightly negative (:math:`\tau_\nu\gtrsim-0.1`). However, the results for more strongly negative optical depths should be ignored ([vanderTak07]_). ``pyhonradex`` provides an option to print a warning if the solution contains negative optical depths using the ``warn_negative_tau`` parameter of the :ref:`Cloud class <rad_trans_API>`.
+
+I get an "Underlying object has vanished" error
+------------------------------------------------------
+This probably indicates a problem with the caching of the ``numba``-compiled functions used by ``pyhonradex``. Deleting the __pycache__ folder should solve the issue.

pythonradex-1.0.0/docs/geometry.rst

@@ -0,0 +1,98 @@
+.. _geometries:
+
+Cloud geometries
+======================
+
+The calculations of the escape probability and the emerging flux depend on the adopted geometry. Below we give an overview of the geometries available in ``pyhonradex``. For all geometries, we assume a homogeneous medium (i.e. constant number density). For convenience, the escape probabilities are expresses as functions of optical depth :math:`\tau_\nu` rather than the absorption coefficient :math:`\alpha_\nu`.
+
+Uniform sphere
+----------------------
+A homogeneous, static sphere. The escape probability is given in [Osterbrock74]_:
+
+.. math::
+    :name: eq:beta_uniform_sphere
+
+    \beta(\tau_\nu) = \frac{3}{2\tau_\nu}\left(1-\frac{2}{\tau_\nu^2}+\left(\frac{2}{\tau_\nu}+\frac{2}{\tau_\nu^2}\right) e^{-\tau_\nu}\right)
+
+where :math:`\tau_\nu` is the optical depth of the diameter of the sphere. The observed flux (in [W/m\ :sup:`2`/Hz]) can also be calculated from [Osterbrock74]_ and is given by:
+
+.. math::
+
+    F_\nu = \frac{2B_\nu(T_\mathrm{ex})\Omega}{\tau_\nu^2}\left(\frac{\tau_\nu^2}{2}-1+(\tau_\nu+1)e^{-\tau_\nu}\right)
+
+where :math:`B_\nu(T_\mathrm{ex})` is the Planck function evaluated at the excitation temperature :math:`T_\mathrm{ex}`, :math:`\Omega` is the solid angle of the source (given by :math:`\Omega=R^2\pi/d^2` with :math:`R` the radius of the sphere and :math:`d` the distance of the source). Note that ``RADEX`` calculates the flux with the formula for a slab geometry, which is incorrect. See :doc:`difference_pythonradex_RADEX` for more details.
+
+Uniform slab
+----------------------
+A homogeneous, static slab. The escape probability is given by (e.g. [Elitzur92]_):
+
+.. math::
+
+    \beta(\tau_\nu) = \frac{\int_0^1 (1-e^{-\tau_\nu/\mu})\mu\mathrm{d}\mu}{\tau_\nu}
+
+The observed flux (in [W/m\ :sup:`2`/Hz]) is given by:
+
+.. math::
+    :name: eq:flux_uniform_slab
+
+    F_\nu = B_\nu(T_\mathrm{ex})(1-e^{-\tau_\nu})\Omega
+
+where :math:`\Omega` is the solid angle of the emitting region.
+
+
+LVG sphere
+-------------------
+The Large Velocity Gradient (LVG) approximation is applicable if the characteristic flow velocity along the line of sight is much larger than the local random (e.g. thermal) velocities (e.g. [Scoville74]_, [Elitzur92]_). Here, we consider the model by [Goldreich74]_: A homogeneous sphere with a constant, radial velocity gradient :math:`\mathrm{d}v/\mathrm{d}r=V/R` where :math:`V` is the velocity at the sphere surface and :math:`R` is the radius of the sphere. The escape probability is given by
+
+.. math::
+    :name: eq:beta_LVG_sphere
+
+    \beta(\tau) = \frac{1-e^{-\tau}}{\tau}
+
+Note that here, :math:`\tau` is the optical depth of the diameter of the sphere, and is constant in the interval :math:`[-V,V]` (and zero outside). The observed flux can be derived by using an approach similar to [deJong75]_. It is given by
+
+.. math::
+
+    F_\nu = B_\nu(T_\mathrm{ex})(1-e^{-\tau})\Omega\left(1-\frac{v^2}{V^2}\right)
+
+where :math:`v=c(1-\nu/\nu_0)` with :math:`c` the speed of light and :math:`\nu_0` the rest frequency. As in the case of the static sphere, also for the LVG sphere ``RADEX`` incorrectly uses the formula for a slab geometry to calculate the flux (see :doc:`difference_pythonradex_RADEX` for more details).
+
+
+LVG slab
+-------------------
+Here we consider a homogeneous slab with a constant velocity gradient :math:`\mathrm{d}v/\mathrm{d}z`, where :math:`z` is the coordinate perpendicular to the slab surface, along the line of sight. The escape probability is given by [Scoville74]_ as
+
+.. math::
+
+    \beta(\tau) = \frac{1-e^{-3\tau}}{3\tau}
+
+Here again, :math:`\tau` is the constant optical depth over the velocity interval with a width given by :math:`\frac{\mathrm{d}v}{\mathrm{d}z}Z` with :math:`Z` the total depth of the slab. The flux is given by the same formula as for the uniform slab.
+
+Geometries emulating ``RADEX``
+-------------------------------------
+Mainly for test and legacy purposes, ``pythonradex`` offers two additional geometries that emulate the behaviour of ``RADEX``.
+
+Uniform sphere RADEX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This geometry uses the same formula (:ref:`Eq. 1 <eq:beta_uniform_sphere>`) for the escape probability as the uniform sphere, but uses the formula (:ref:`Eq. 2 <eq:flux_uniform_slab>`) for the uniform slab to calculate the flux.
+
+
+LVG sphere RADEX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The paper describing ``RADEX`` ([vanderTak07]_) says that ``RADEX`` uses the formula given in :ref:`Eq. 3 <eq:beta_LVG_sphere>` to calculate the escape probability of an LVG sphere. However, by inspecting the ``RADEX`` source code, it is found that at least the current version uses a different formula that seems to be based on [deJong80]_. It is given by
+
+.. math::
+
+    \beta(\tau) = \frac{1}{\tau_\nu\sqrt{\ln(\tau_\nu/(2\sqrt{\pi}))}} \qquad \text{if } \tau_\nu\geq 7
+
+and
+
+.. math::
+
+    \beta(\tau) = \frac{4-4e^{-2.34\tau_\nu/2}}{4.68\tau_\nu} \qquad \text{if } \tau_\nu< 7
+
+Thus, the geometry "LVG sphere RADEX" uses this formula. For the flux, it uses the same formula (:ref:`Eq. 2 <eq:flux_uniform_slab>`) as for the uniform slab (despite the spherical geometry).
+
+The line width parameter ``width_v``
+------------------------------------------
+It is immportant to understand the different interpretations of the input parameter ``width_v`` used by ``pythonradex`` (see :ref:`API of the Cloud class <rad_trans_API>`). For static geometries, this refers to the local emission width (typically the thermal width). ``pythonradex`` allows two kinds of local emission profiles (parameter ``line_profile_type``): "Gaussian" (in which case ``width_v`` refers to the FWHM) and "rectangular". On the other hand, for the LVG geometries ("LVG sphere" and "LVG slab"), ``width_v`` refers to the global velocity width of the cloud. For the "LVG sphere", ``width_v`` is equal to :math:`2V` (with :math:`V` the velocity at the sphere surface). For the "LVG slab", ``width_v`` equals :math:`\mathrm{d}v/\mathrm{d}zZ` (with :math:`Z` the depth of the slab and :math:`\mathrm{d}v/\mathrm{d}z` the constant velocity gradient). For these geometries, the parameter ``line_profile_type`` needs to be set to "rectangular". This ensures that the optical depth is calculated correctly.

pythonradex-1.0.0/docs/help.rst

@@ -0,0 +1,4 @@
+Help / Bug reports
+=======================
+
+For questions or bug reports, please open an issue at `<https://github.com/gica3618/pythonradex/issues>`_.

pythonradex-1.0.0/docs/index.rst

@@ -0,0 +1,69 @@
+.. pythonradex documentation master file, created by
+   sphinx-quickstart on Thu Dec  7 13:57:20 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the ``pyhonradex`` documentation!
+=================================================
+
+``pythonradex`` solves the radiative transfer for a uniform medium in non-LTE with an escape probability formalism. The code can be used to quickly estimate the emission from an astrophysical gas given input parameters such as the kinetic temperature, the column density and the density of the collision partners.
+
+``pythonradex`` is a python re-implementation of the RADEX code [vanderTak07]_. It is generally faster than RADEX (when calculating a grid of models) and provides additional functionality that is not included in RADEX (treatment of overlapping lines, treatment of internal dust continuum, output of spectra,...).
+
+``pyhonradex`` also provides a convenient method to read files from the LAMDA_ database.
+
+Please see the :ref:`example notebooks<examples>` for an overview of the functionalities offered by ``pythonradex``.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   examples
+   theory
+   geometry
+   difference_pythonradex_RADEX
+   faq
+   help
+   API
+   citation
+   
+
+
+Acknowledgement
+=================
+I would like to thank Simon Bruderer for his helpful clarifications about the ALI method. I also thank Andrés Asensio Ramos for helpful discussions about the LVG geometry and help with the `MOLPOP-CEP` code that was used to benchmark `pythonradex`.
+
+
+Bibliography
+=================
+
+.. [deJong80] de Jong, T., Boland, W., & Dalgarno, A. 1980, Astronomy and Astrophysics, 91, 68
+
+.. [deJong75] de Jong, T., Chu, S., & Dalgarno, A. 1975, Astrophysical Journal, 199, 69 
+
+.. [Elitzur92] Elitzur, M. 1992, *Astronomical masers*, ISBN 978-0-7923-1217-8, Springer Dordrecht
+
+.. [Goldreich74] Goldreich, P., & Kwan, J. 1974, Astrophysical Journal, 189, 441
+
+.. [Hubeny03] Hubeny, I. 2003, Accelerated Lambda Iteration: An Overview. Stellar Atmosphere Modeling 288, 17
+
+.. [Ng74] Ng, K.-C. 1974, Journal of Chemical Physics, 61, 2680
+
+.. [Osterbrock74] Osterbrock, D. E. 1974, *Astrophysics of Gaseous Nebulae*, ISBN 0-716-70348-3, W. H. Freeman
+
+.. [Rybicki91] Rybicki, G. B., & Hummer, D. G. 1991, Astronomy and Astrophysics, 245, 171
+
+.. [Rybicki92] Rybicki, G. B., & Hummer, D. G. 1992, Astronomy and Astrophysics, 262, 209
+
+.. [Rybicki04] Rybicki, G. B., & Lightman, A.P. 2004, *Radiative Processes in Astrophysics*, ISBN 0-471-82759-2, Wiley-VCH
+
+.. [Scoville74]  Scoville, N. Z., & Solomon, P. M. 1991, Astrophysical Journal, 187, L67
+
+.. [vanderTak07]  van der Tak, F. F. S., Black, J. H., Schöier, F. L., Jansen, D. J., & van Dishoeck, E. F. 2007, Astronomy and Astrophysics, 468, 627
+
+
+.. _RADEX: http://home.strw.leidenuniv.nl/~moldata/radex.html
+
+.. _LAMDA: http://home.strw.leidenuniv.nl/~moldata/

pythonradex-1.0.0/docs/installation.rst

@@ -0,0 +1,12 @@
+Installation
+=================
+
+``pythonradex`` is compatible with python versions 3.10 to 3.13. ``pythonradex`` can be installed with Pip or Conda:
+
+* pip install XXXXXX
+
+* conda XXXX
+
+If you have any trouble installing, please raise an issue `here <https://github.com/gica3618/pythonradex/issues>`_.
+
+The ``pythonradex`` code is publicly available on `github <https://github.com/gica3618/pythonradex>`_.

pythonradex-1.0.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd