Atmosphere switching - release v2.1.0 (#303)

* Atmosphere wrapper introduced for switching between extensions without re-installing X-PSI

* Adding the wrapper file missing from the previous commit

* Making basic numerical test run working as well.

* Atmosphere options passed as a string from the user instead of an integer.

* Function renamings and beaming moved the wrapper.

Beaming modification is now mooved to the wrapper function, and it can be used for many atmosphere extensions (instead of having it as a separate extension). Setting it on or off is now based on an additional input argument.

* Switching between elsewhere atmosphere extensions implemented.

* Error handling if atmosphere data not provided.

Exception raised now in Python if atmosphere data were not provided, even though using numerical atmosphere extension.

* Passing atmosphere also for cede=True.

* Surface radiation field tools upgraded.

Tutorial and the related intensity functions in X-PSI upgraded for the atmosphere switching without re-installing X-PSI.

* Atmosphere options implented also to Everywhere and integrator.py.

* Added option for user extension.

An option added for user to provide their own atmosphere extension by replacing some files. In addition, atmosphere options included now also for imaging in Photosphere and pixelmesh.

* Installation+documentation updates, and cleaning.

* Version numbers and setup description updated.

* Doc updates 1

* Now unnecessary archives removed.

* Doc updates 2

Tutorials re-run and comments updated.

* Doc updates 3

More tutorials re-run and updated.

* Module generator tutorial updated.

* CHANGELOG and small doc updates.

* Adding beam_opt value checks

in everywhere and in `HotRegion.py` and in `Everywhere.py`

* Adding elsewhere_user in the wrapper

* required versions of cython

for CI tests

* Update basic_environment.yml

* cython version requirements

* Notebook Surface Radiation Field Tool completed

with extra info to create a CustomPhotosphere with atmosphere extension 'Num4D'

* Meaning of old scripts clarified.

* small cleaning

* warning if loading atmosphere data for default user elsewhere BB

* Added sanity checks in hot_wrapper and elsewhere_wrapper

Added checks to default to BB in case the `atmos_extension` values are different than the expected 1, 2, 3.  It should not happen, but in case it does, the crash might be difficult to understand.

* Small version date and number fixes.

---------

Co-authored-by: sguillot <sebastien.guillot@irap.omp.eu>

Author: thjsal

CHANGELOG.rst

@@ -34,6 +34,48 @@ and this project adheres to
 .. ^^^^^^^^^^^
 
 
+[v2.1.0] - 2023-09-08
+~~~~~~~~~~~~~~~~~~~~~
+
+Summary
+^^^^^^^
+
+* Atmosphere switching implemented without need for re-installing X-PSI for different atmosphere extensions. **Note that old scripts using the numerical atmosphere extension need to be slightly modified (see Deprecated below).**
+
+Added
+^^^^^
+
+* Atmosphere extension flag ``atm_ext`` that can be used to select the wanted atmosphere extension (for an instance of HotRegion, Elsewhere, or Everywhere class). The default option is a blackbody atmosphere, but a numerical atmosphere extension can be switched by setting ``atm_ext="Num4D"``.
+
+* Beaming modification flag ``beam_opt`` (an integer) that can be used to select the wanted atmospheric beaming correction model for an instance of HotRegion or Everywhere class (not implemented to Elsewhere currently). The default option is no modification. See the docstring for HotRegion class for other options.
+
+* Extra atmosphere extension ``xpsi/surface_radiation_field/hot_user.pyx`` that can be replaced with a user-modified atmosphere model before (re-)installing X-PSI. This model can then be used by setting ``atm_ext="user"`` allowing still the possibility to use the other built-in options without re-installing X-PSI.
+
+* Options to switch atmosphere extension and beaming option in the surface radiation field tools (``xpsi/surface_radiation_field/__init__.pyx``).
+
+Changed
+^^^^^^^
+
+* Documentation, tutorials, and example scripts updated for using the new atmosphere switching (except ``xpsi/module_generator.py``).
+
+Deprecated
+^^^^^^^^^^
+
+* The previous way of installing X-PSI with different atmosphere extensions has been deprecated. **To use the old python scripts (files usually named as `main.py`) to run X-PSI with numerical atmosphere setup, one needs to add `atm_ext="Num4D"` as an input parameter for all the relevant HotRegion/Elsewhere/Everywhere objects.**
+
+Removed
+^^^^^^^
+
+* Archived versions of atmosphere extensions that are not needed anymore.
+
+Attribution
+^^^^^^^^^^^
+
+Tuomo Salmi,
+Bas Dorsman,
+Sebastien Guillot
+
+
 [v2.0.3] - 2023-07-11
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -53,6 +95,7 @@ Fixed
 
 Added
 ^^^^^
+
 * Added a keyword argument in ``xpsi/PostProcessing/_corner.py`` to allow user to define the decimal precisions for all the credible intervals printed in the figures (T.S.).
 
 * Added a photosphere setter in ``xpsi/Star.py`` which should allow producing residual and signal plots for models with multiple photosphere objects as explained in ``https://github.com/xpsi-group/xpsi/issues/304`` (Y.K, T.S.).
@@ -62,7 +105,9 @@ Added
 Attribution
 ^^^^^^^^^^^
 
-Tuomo Salmi, Yves Kini, Sebastien Guillot
+Tuomo Salmi,
+Yves Kini,
+Sebastien Guillot
 
 
 [v2.0.2] - 2023-06-09

docs/source/Emitting_patterns_2Dprojection.ipynb

@@ -21,13 +21,13 @@ Second script called `examples/examples_modeling_tutorial/TestRun_BB.py`__ is a
 
 __ t2_
 
-Third script called `examples/examples_modeling_tutorial/TestRun_Num.py`__ is also a test run, which is similar to the :doc:`Modeling<Modeling>` tutorial, except using the numerical atmosphere extension (X-PSI installed using the flag ``--NumHot``).
+Third script called `examples/examples_modeling_tutorial/TestRun_Num.py`__ is also a test run, which is similar to the :doc:`Modeling<Modeling>` tutorial, except using the numerical atmosphere extension.
 
 .. _t3: https://github.com/xpsi-group/xpsi/tree/main/examples/examples_modeling_tutorial/TestRun_Num.py
 
 __ t3_
 
-Fourth script called `examples/examples_modeling_tutorial/TestRun_NumBeam.py`__ is a similar test run as the previous, except using a numerical atmosphere extension with extra parameters allowing deviations to the atmospheric beaming pattern (X-PSI installed using the flag ``--NumHotBeam`` instead of ``--NumHot``).
+Fourth script called `examples/examples_modeling_tutorial/TestRun_NumBeam.py`__ is a similar test run as the previous, except using a numerical atmosphere extension with extra parameters allowing deviations to the atmospheric beaming pattern.
 
 .. _t4: https://github.com/xpsi-group/xpsi/tree/main/examples/examples_modeling_tutorial/TestRun_NumBeam.py
 

docs/source/Example_script_and_modules.rst

@@ -25,16 +25,6 @@ If you want to test the binaries on a login node, note that you can
 compile with multiple instruction sets for auto-dispatch using the ``-x`` and
 ``-ax`` flags. See the :ref:`hpcsystems` page for examples.
 
-.. rubric:: What atmosphere extension should I use?
-
-If you want to do some quick calculations and run the Modeling tutorial, you should use the default blackbody atmosphere extension. But if you want to use similar atmosphere models as in the published X-PSI applications so far, you should use to the numerical atmosphere extension when installing X-PSI (see instructions in :ref:`install`).
-
-Note that using the model scripts with an unintended atmosphere extension may lead to a segmentation fault error if trying to use numerical atmosphere without providing numerical atmosphere data. Or if using the scripts including the numerical atmosphere data with the blackbody extension, you can get unexpected results, printing though a warning that numerical atmosphere data were preloaded but not used. Examples of numerical atmosphere data, which are required by the numerical atmosphere extension, can be found here: `doi:10.5281/zenodo.7094144`__. Examples of how to use the numerical atmospheres are shown e.g. in Surface radiation field tools -tutorial and in :ref:`example_script`.
-
-.. _Zenodo: https://doi.org/10.5281/zenodo.7094144
-
-__ Zenodo_
-
 
 Sampling
 ^^^^^^^^

docs/source/FAQ.rst

@@ -18,8 +18,6 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To run this tutorial, you should install X-PSI with the default (blackbody) atmosphere extension module, which is compiled when installing X-PSI with default settings. \n",
-    "\n",
     "Some extra data files not available on the GitHub repository are needed to run this tutorial. They can be found in the [Zenodo](https://zenodo.org/record/7094144) and should be placed in the directory `examples/examples_modeling_tutorial/model_data/` of your local xpsi directory.  These are the required files: \n",
     "- `nicer_v1.01_arf.txt`\n",
     "- `nicer_v1.01_rmf_matrix.txt`\n",
@@ -38,12 +36,12 @@
       "/=============================================\\\n",
       "| X-PSI: X-ray Pulse Simulation and Inference |\n",
       "|---------------------------------------------|\n",
-      "|                Version: 2.0.0               |\n",
+      "|                Version: 2.1.0               |\n",
       "|---------------------------------------------|\n",
       "|      https://xpsi-group.github.io/xpsi      |\n",
       "\\=============================================/\n",
       "\n",
-      "Imported GetDist version: 1.4\n",
+      "Imported GetDist version: 1.4.3\n",
       "Imported nestcheck version: 0.2.1\n"
      ]
     }
@@ -928,7 +926,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "ll = -29322.44238519; time = 0.621\n"
+      "ll = -29322.44238519; time = 0.649\n"
      ]
     }
    ],