pythonradex 1.0.9__tar.gz → 2.0.0__tar.gz

pythonradex-2.0.0/.github/workflows/draft-pdf.yml

@@ -0,0 +1,28 @@
+name: Draft PDF
+on:
+  push:
+    paths:
+      - joss_paper/**
+      - .github/workflows/draft-pdf.yml
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: joss_paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: joss_paper/paper.pdf

pythonradex-2.0.0/.gitignore

@@ -0,0 +1,132 @@
+# 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/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-cep-master
+manual_tests_and_benchmarks/benchmarking_vs_RADEX_and_LIME/*.fits
+manual_tests_and_benchmarks/performance_tests/radex_test_preformance.inp
+manual_tests_and_benchmarks/performance_tests/radex_test_performance.out
+manual_tests_and_benchmarks/performance_tests/pythonradex_vs_radex/*.out
+manual_tests_and_benchmarks/performance_tests/pythonradex_vs_radex/radex_test_preformance.inp
+manual_tests_and_benchmarks/performance_tests/pythonradex_vs_radex/test_radex_mini_wrapper.inp
+docs/notebooks/test.inp
+docs/notebooks/test.out
+docs/notebooks/radex_log.txt
+docs/notebooks/grid.inp
+docs/notebooks/grid.out
+**/radex.out
+.pytest_cache
+joss_paper/code/co.inp
+joss_paper/code/co.out
+joss_paper/code/radex_log.txt
+joss_paper/code/molpop-cep-master
+joss_paper/code/molpopcep_models/*.out

pythonradex-2.0.0/CITATION.cff

@@ -0,0 +1,21 @@
+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'."
+authors:
+  - given-names: Gianni
+    family-names: Cataldi
+    affiliation: National Astronomical Observatory of Japan
+    orcid: "https://orcid.org/0000-0002-2700-9676"
+keywords:
+  - python
+  - astronomy
+  - astrophysics
+  - radiative transfer
+  - non-LTE
+  - escape probability
+  - line emission

pythonradex-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing to pythonradex
+
+Thank you for your interest in contributing to `pythonradex`. All kinds of contributions are welcome, including bug reports, code improvements and documentation updates.
+
+---
+
+## Reporting issues
+
+If you encounter a bug or other problems, please [open an issue](https://github.com/gica3618/pythonradex/issues) with:
+
+- A clear description of the problem
+- Steps to reproduce it
+- Expected vs. actual behavior
+- Version information (`python`, `pythonradex`, OS)
+
+---
+
+## Requesting new features
+
+If you have ideas for new features, feel free to [open an issue](https://github.com/gica3618/pythonradex/issues).
+
+---
+
+## Contributing Code
+
+### Getting Started
+
+1. **Fork** the repository on GitHub.
+2. **Clone** your fork locally:
+
+        git clone https://github.com/<your-username>/pythonradex.git
+
+3. **Create a development environment** (use a python version supported by `pythonradex`). You can use either `conda` or `venv`. For example:
+
+        cd pythonradex
+        python3 -m venv virt_env_name
+        source virt_env_name/bin/activate
+
+4. **Install in editable mode with development dependencies:**
+
+        pip install -e .[dev]
+
+   This installs `pythonradex`, `pytest` and additional packages to modify and build the documentation and run the example notebooks.
+
+
+### Running Tests
+
+**If you contribute code, please also add corresponding test code whenever possible**. All test code uses `pytest` and is located in the `tests/` folder.
+
+To run the whole test suite, you can for example do:
+
+    python3 -m pytest tests/
+
+To see detailed output:
+
+    python3 -m pytest -v tests/
+
+If you only want to run the tests of a specific test file, for example `test_LAMDA_file.py`:
+
+    python3 -m pytest tests/test_LAMDA_file.py
+
+If you only want to run a specific test:
+
+    python3 -m pytest tests/test_LAMDA_file.py::test_levels
+
+**Please make sure all tests pass before submitting a pull request.**
+
+
+### Style Guide
+
+Please use `black` to auto-format the files or notebooks you modified. `black` is installed if you install `pythonradex` with development dependencies.
+
+---
+
+## Contributing to the documentation and example notebooks
+
+Documentation is located in the `docs/` folder and hosted on [ReadTheDocs](https://pythonradex.readthedocs.io/en/latest/).
+
+### Documentation Style Guide
+
+- Use **reStructuredText (`.rst`)** syntax for Sphinx documentation.
+- Use **double backticks** for code, commands, and Python package names, e.g.:
+  ```
+  You can install ``pythonradex`` using ``pip``.
+  ```
+
+### Build the documentation locally
+
+To build the documentation locally:
+
+    cd docs
+    make html
+
+or on Windows:
+
+    cd docs
+    .\make.bat html
+
+The generated HTML files will appear in `docs/_build/html/`. Open `docs/_build/html/index.html` in your browser to preview the site.
+
+### Notebooks
+
+Example notebooks are located in `docs/examples/`. You can run them with
+
+    jupyter notebook docs/examples/
+
+Before submitting a pull request, please clear all output and re-run the notebook fully to ensure it executes cleanly from top to bottom.
+
+---
+
+## Submitting a Pull Request
+
+1. Create a new branch:
+
+        git checkout -b fix-something
+
+2. Make your changes.
+3. Run tests to ensure everything passes.
+4. Commit with a clear message
+5. Push your branch:
+
+        git push origin fix-something
+
+6. Open a **Pull Request** on GitHub against the `main` branch.
+
+---
+
+## License
+
+By contributing to `pythonradex`, you agree that your contributions will be licensed under the [MIT License](./LICENSE).
+
+---
+
+Thank you for contributing to `pythonradex`!
+
+
+*This file was initially drafted with assistance from ChatGPT (OpenAI GPT-5).*

pythonradex-2.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: pythonradex
+Version: 2.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
+Provides-Extra: dev
+Requires-Dist: black[jupyter]; extra == 'dev'
+Requires-Dist: jupyter; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: nbsphinx; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Provides-Extra: notebooks
+Requires-Dist: jupyter; extra == 'notebooks'
+Requires-Dist: matplotlib; extra == 'notebooks'
+Requires-Dist: pandas; extra == 'notebooks'
+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 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/
+
+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

@@ -0,0 +1,7 @@
+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/
+
+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/docs/API.rst

@@ -0,0 +1,66 @@
+API
+=====
+
+.. _rad_trans_API:
+
+The ``Source`` class
+------------------------------------
+The core of ``pyhonradex`` is the ``Source`` class which is used to solve the radiative transfer.
+
+.. autoclass:: pythonradex.radiative_transfer.Source
+    :members: __init__, update_parameters, solve_radiative_transfer, frequency_integrated_emission, tau, spectrum, emission_at_line_center, print_results 
+
+.. _read_LAMDA_API:
+
+Reading LAMDA files
+-------------------------
+``pyhonradex`` provides a convenient function in the ``LAMDA_file`` module to read files that follow the `LAMDA format <https://home.strw.leidenuniv.nl/~moldata/molformat.html>`_, for example from the `EMAA <https://emaa.osug.fr/>`_ or `LAMDA <https://home.strw.leidenuniv.nl/~moldata/>`_ databases:
+
+.. 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
+
+.. autoclass:: pythonradex.atomic_transition.CollisionalTransition
+    :members: Tex,coeffs
+
+.. _Molecule_API:
+
+.. autoclass:: pythonradex.molecule.Molecule
+    :members: __init__, Boltzmann_level_population
+
+.. 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,RJ_brightness_temperature,Planck_brightness_temperature

pythonradex-2.0.0/docs/benchmark_vs_RADEX.rst

@@ -0,0 +1,13 @@
+.. _benchmark_vs_RADEX:
+
+Benchmark vs ``RADEX``
+=========================
+Here we compare the output and performance of ``RADEX`` and ``pythonradex``. The notebooks below can be downloaded from `here`_. To run the notebooks yourself, you will need to have the ``jupyter``, ``matplotlib`` and ``pandas`` packages installed.
+
+.. _here: https://github.com/gica3618/pythonradex/tree/master/docs/notebooks
+
+.. toctree::
+   :maxdepth: 1
+
+   notebooks/benchmark_vs_RADEX
+   notebooks/performance_comparison_vs_RADEX

pythonradex-2.0.0/docs/conf.py

@@ -0,0 +1,75 @@
+# 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"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "pythonradex"
+copyright = "2025, Gianni Cataldi"
+author = "Gianni Cataldi"
+
+# The full version, including alpha/beta/rc tags
+release = "1.0"
+
+
+# -- 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-2.0.0/docs/contact.rst

@@ -0,0 +1,4 @@
+Contact
+========================================
+
+For questions, bug reports, ideas for new features etc., please open an issue at `<https://github.com/gica3618/pythonradex/issues>`_. If you need to contact the maintainer directly, you can reach out via email: cataldi.gia@gmail.com.

pythonradex-2.0.0/docs/difference_pythonradex_RADEX.rst

@@ -0,0 +1,63 @@
+Differences between ``pythonradex`` and ``RADEX``
+------------------------------------------------------
+
+Overlapping lines and internal 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. Simple performance tests suggest that ``pythonradex`` outperforms ``RADEX`` in the typical use case of calculating several models over a grid of parameters (e.g. column density, temperature). The speed advantage of ``pythonradex`` from these tests ranges from ~2 up to more than 10, depending on the input parameters and the computing environment. To optimize its performance, ``pythonradex`` employs an architecture that avoids unnecessary or repeating calculations as much as possible. In addition, it uses just-in-time compilation using the `numba <https://numba.readthedocs.io>`_ package.
+
+Different flux 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 optical depth and excitation temperature, ``RADEX`` first computes :math:`I_\mathrm{tot} = B_\nu(T_\mathrm{ex})(1-e^{-\tau}) + I_\mathrm{bg}e^{-\tau}`, i.e. the total specific 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})`. 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 emission without any background subtraction, i.e. the output corresponds simply to the emission emitted by the gas (for a slab geometry, the fluxes would be based on the specific intensity given simply by :math:`B_\nu(T_\mathrm{ex})(1-e^{-\tau}))`. This allows the user to decide how the flux should be compared to observations.
+
+.. _sphere_flux_difference:
+
+Different specific intensity and flux for spherical geometry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For a given excitation temperature :math:`T_{ex}` and optical depth :math:`\tau`, ``RADEX`` calculates the specific intensity as
+
+.. math::
+    I_\nu = B_\nu(T_{ex})(1-e^{-\tau})
+
+for all geometries. However, this expression is only valid for slab geometries, but not for spherical geometries ("static sphere" and "LVG sphere"). In contrast, ``pythonradex`` uses different formulae for spherical geometries (see the :ref:`section about geometries<geometries>` for more details).
+
+For a static sphere, the specific intensity depends on the position on the sphere: if one looks towards the center of the sphere, it will be brighter than the sphere edges (because when looking through the center, the column density is higher), unless the sphere is completely optically thick. Therefore, the specific intensity, or brightness temperature, computed by ``RADEX`` using the above equation corresponds to what one would observe towards the center of the sphere if the observations resolved the sphere. On the other hand, ``pythonradex`` computes a sort of mean specific intensity, in the sense that if that specific intensity is multiplied by the solid angle of the sphere (:math:`R^2\pi/d^2`, with :math:`R` the physical radius of the sphere and :math:`d` the distance), you get the correct total flux density. So the specific intensity computed by ``pythonradex`` corresponds to what one would measure from completely unresolved observations (assuming an appropriate beam-filling factor is applied).
+
+Similarly, for an LVG sphere, ``RADEX`` returns the specific intensity towards the center of the sphere, while ``pythonradex`` returns a specific intensity such that if multiplied by the solid angle, the correct flux density is computed. In addition, ``pythonradex`` computes the correct frequency dependence of the specific intensity (see :doc:`geometry`).
+
+Whether resolved or unresolved, ``pythonradex`` gives the correct total flux (W/m\ :sup:`2`) emitted by the whole sphere, while ``RADEX`` might not (depending on the optical depth and geometry). The following figure illustrates the difference in flux that results from using different formulae. For a static sphere, using the slab formula (as done by ``RADEX``) overestimates the flux in the optically thin limit by a factor 1.5. This factor simply represents the volume ratio between a "spherical slab" (i.e. a cylinder) and a sphere. In the optically thick limit, only the surface of the static sphere is visible, so either formula gives 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 due to the LVG assumption that all photons escape unless absorbed locally.
+
+.. This figure comes from joss_paper/code/compare_flux_formulae_spherical_geometry.py
+.. figure:: images/flux_comparison_spherical_geometries.png
+   :align: center
+   :width: 80%
+   :alt: Flux comparison slab formula (RADEX) vs pythonradex formulas
+
+   For the two spherical geometries, we computed the flux using the slab formula (as done by ``RADEX``) and formulae appropriate for a sphere (as done by ``pythonradex``). The figure shows the ratio of the fluxes as function of optical depth.
+
+To verify that ``pythonradex`` calculates the flux correctly, one may consider the optically thin limit where the flux can be calculated directly. In this limit, all photons escape the source. 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, but ``RADEX`` overestimates the optically thin flux by a factor 1.5.
+
+Flux calculation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``RADEX`` computes the flux by assuming that the flux density has a Gaussian profile (see Appendix A.2, point 5, in [vanderTak07]_). However, for optically thick lines, the flux density profile is not Gaussian, even if the intrinsic line profile (and thus optical depth profile) is. On the other hand, ``pythonradex`` calculates the flux by integrating over the flux density profile, thus taking its shape into account. Note though, as commented by [vanderTak07]_, that proper modelling of optically thick lines cannot really be achieved anyway by 1D codes like ``RADEX`` or ``pythonradex``.
+
+Different escape probability for LVG sphere
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For the spherical LVG geometry, ``RADEX`` and ``pythonradex`` use different formulae to calculate the escape probability. Please see the :ref:`section about geometries<geometries>` for more details.
+
+
+Different behaviour for H\ :sub:`2` collider densities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Whenever the LAMDA-formatted molecular data file contains collisional rates for H\ :sub:`2`, but the user does not provide an H\ :sub:`2` density, ``RADEX`` just adds an H\ :sub:`2` density of :math:`10^5` cm\ :sup:`-3` by default to the calculation.
+
+Furthermore, if the molecular data file contains rates for ortho-H\ :sub:`2` and para-H\ :sub:`2`, but not for H\ :sub:`2`, and the user supplies an H\ :sub:`2` density instead of densities for ortho-H\ :sub:`2` and para-H\ :sub:`2`, then ``RADEX`` will convert the supplied H\ :sub:`2` density into densities of H\ :sub:`2` and H\ :sub:`2` assuming a thermal ortho/para ratio.
+
+On the other hand, ``pythonradex`` does not add H\ :sub:`2` by default, nor allow the user to request colliders that are not present in the molecular data file.

pythonradex-2.0.0/docs/examples.rst

@@ -0,0 +1,19 @@
+.. _examples:
+
+Examples
+=============
+The individual notebooks presented below can be downloaded from `here`_. To run the notebooks yourself, you will need to have the ``jupyter`` and ``matplotlib`` packages installed.
+
+.. _here: https://github.com/gica3618/pythonradex/tree/master/docs/notebooks
+
+.. 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-2.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:`Source 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.