Merge pull request #1123 from sirocco-rt/docs-patch

Docs patch: improve docs on code operation, radiative transfer and installation

docs/sphinx/source/index.rst

@@ -10,13 +10,20 @@ SIROCCO - Simulating Ionization and Radiation in Outflows Created by Compact Obj
 .. figure:: images/logo.png
     :width: 300px
 
+.. image:: https://img.shields.io/badge/arXiv-2410.19908-b31b1b.svg?style=for-the-badge
+   :target: https://arxiv.org/abs/2410.19908
+
+.. image:: https://img.shields.io/badge/Github-sirocco-4475A0.svg?style=for-the-badge&logo=github&logoColor=white
+   :target: https://github.com/sirocco-rt/sirocco
+
 SIROCCO is a Monte-Carlo radiative transfer code designed to simulate the spectrum of biconical (or spherical)
 winds in disk systems.  It was formerly known as Python, and originally written by
 `Long and Knigge (2002) <https://ui.adsabs.harvard.edu/abs/2002ApJ...579..725L/abstract>`_ and
 was intended for simulating the spectra of winds in cataclysmic variables. Since then, it has
 also been used to simulate the spectra of systems ranging from young stellar objects to AGN. 
 SIROCCO is named after the `Sirocco wind <https://en.wikipedia.org/wiki/Sirocco>`_, and also 
 stands for Simulating Ionization and Radiation in Outflows Created by Compact Objects. 
+sirocco-0.1, the version of the code in October 2024, is described by `Matthews, Long et al. <https://arxiv.org/abs/2410.19908>`_
 
 The program is written in C and can be compiled on systems runining various flavors of linux, including macOS and the
 Windows Subsystem for Linux (WSL). The code is is available on `GitHub <https://github.com/sirocco-rt/sirocco>`_. Issues
@@ -32,7 +39,7 @@ Various documentation exists:
 
 * A :doc:`Quick Guide <quick>` describing how to install and run SIROCCO (in a fairly mechanistic fashion).
 * More detailed documentation on this site and in the docs/sphinx/ folder of the repository. 
-* A code release paper, submitted in October 2024
+* A `code release paper <https://arxiv.org/abs/2410.19908>`_, submitted to MNRAS in October 2024
 * Various PhD theses that describe the code in more detail: 
     * Higginbottom, N (2014): `Modelling accretion disk winds in quasars <https://eprints.soton.ac.uk/368584/>`_, 
     * Matthews, J. (2016): `Disc Winds Matter: Modelling Accretion And Outflow On All Scales <https://ui.adsabs.harvard.edu/abs/2016PhDT.......348M/abstract>`_, 

docs/sphinx/source/installation.rst

@@ -14,16 +14,22 @@ Installation
 SIROCCO and the various routines associated are set up in a self-contained directory structure.
 The basic directory structure and the data files that one needs to run SIROCCO need to be retrieved and compiled.
 
-If you want to obtain a stable (!) release, go to the `Releases <https://github.com/sirocco-rt/sirocco/releases/>`_ page.
-
-If you want to download the latest dev version, you can zip up the git repository by clicking on the zip icon to the right of the GitHub page.
-Alternatively, clone it directly as
+If you want to obtain a stable (!) release, go to the `Releases <https://github.com/sirocco-rt/sirocco/releases/>`_ page. 
+this version is usually fairly closely synced with the default :code:`main` branch, so you can also zip up the git repository by clicking on the zip icon to the right of the GitHub
+page or clone the repository directly:
 
 .. code:: bash
 
     $ git clone [email protected]:sirocco-rt/sirocco.git
 
-If you anticipate contributing to development we suggest Forking the repository and submitting pull requests with any proposed changes.
+Development work is typically merged into a development branch :code:`dev`
+If you want to download the latest :code:`dev` version, you can clone it as
+
+.. code:: bash
+
+    $ git clone -b dev [email protected]:sirocco-rt/sirocco.git
+
+If you anticipate contributing to development we suggest forking the repository and submitting pull requests with any proposed changes.
 
 Once you have the files, you need to cd to the new directory and set your environment variables
 
@@ -46,9 +52,8 @@ note that export syntax is for bash- for csh use
 
 The atomic data needed to run SIROCCO is included in the distribution.
 
-
 The source code for SIROCCO is under actively development and is updated fairly often. Normally, one does not need to redo the entire installation process, since this includes GSL setup.
-Instead, one can pull in changes and recompile the source code by running
+Instead, one can pull in changes, or make changes yourself, and recompile the source code by running
 
 .. code:: bash
 

docs/sphinx/source/operation.rst

@@ -3,6 +3,9 @@ Code Operation
 
 The basic code operation of SIROCCO is split into different cycles; First, the ionization state is calculated (:doc:`Ionization Cycles <operation/ionization_cycles>`). As these photons pass through the simulation grid, their heating and ionizing effect on the plasma is recorded through the use of Monte Carlo estimators. This process continues until the code converges on a solution in which the heating and cooling processes are balanced and the temperature stops changing significantly (see :doc:`Convergence & Errors <output/evaluation>`). Once the ionization and temperature structure of the outflow has been calculated, the spectrum is synthesized by tracking photons through the plasma until sufficient signal-to-noise is achieved in the output spectrum for lines to be easily identified (:doc:`Spectral Cycles <operation/spectral_cycles>`).
 
+.. figure:: images/flowchart.png
+    :width: 500px
+
 .. toctree::
    :glob:
 

docs/sphinx/source/physics.rst

@@ -2,7 +2,7 @@ Physics & Radiative Transfer
 ------------------------------
 
 Various physical concepts are incorporated into SIROCCO.  
-Some of these are descibed below:
+Some of these are descibed below. We also recommend consulting `Matthews, Long et al. <https://arxiv.org/abs/2410.19908>`_ 
 
 .. toctree::
    :glob:

docs/sphinx/source/physics/radiative_transfer.rst

@@ -3,30 +3,35 @@ Radiative Transfer Modes
 
 SIROCCO has a number of different radiative transfer modes, which affect the treatment of lines and scattering, and also whether we use indivisible packet constraints or allow photon weights to be attenuated by continuum absorption. These modes are selected with the parameter :ref:`Line_transfer`. The different modes are briefly described on that parameter page. This page is designed to give an overview of the assumptions and concepts behind, as well as the basic operation of, the different techniques. The aim is that, in partnership with the parameter page and the atomic data documentation, all the information regarding the different radiative transfer modes should be present.
 
-For introductions and references regarding Monte Carlo radiative transfer techniques generally, we recommend reading `Noebauer & Sim 2019 <https://ui.adsabs.harvard.edu/abs/2019LRCA....5....1N/abstract>`_. For specifics regarding SIROCCO, we recommend reading `Long & Knigge 2002 <https://ui.adsabs.harvard.edu/abs/2002ApJ...579..725L/abstract>`_ as well as  PhD theses by `Higginbottom <https://eprints.soton.ac.uk/368584/1/Higginbottom.pdf>`_ and `Matthews <https://ui.adsabs.harvard.edu/abs/2016PhDT.......348M/abstract>`_. 
+For introductions and references regarding Monte Carlo radiative transfer techniques generally, we recommend reading `Noebauer & Sim 2019 <https://ui.adsabs.harvard.edu/abs/2019LRCA....5....1N/abstract>`_. For specifics regarding SIROCCO, we recommend reading the `release paper <https://arxiv.org/abs/2410.19908>`_ as well as `Long & Knigge 2002 <https://ui.adsabs.harvard.edu/abs/2002ApJ...579..725L/abstract>`_  and PhD theses by `Higginbottom <https://eprints.soton.ac.uk/368584/1/Higginbottom.pdf>`_ and `Matthews <https://ui.adsabs.harvard.edu/abs/2016PhDT.......348M/abstract>`_. 
 
 Sobolev Approximation
 ======================
 SIROCCO always uses the Sobolev approximation to treat line transfer. In this approximation, it is assumed that the thermal line width is small compared to the velocity gradient. The Sobolev approximation is described extensively in astrophysics literature, and so we do not describe it in detail here. We refer the users to section 8.2 of `Noebauer & Sim 2019 <https://ui.adsabs.harvard.edu/abs/2019LRCA....5....1N/abstract>`_ and references there in for a discussion of the Sobolev escape probabilities approach.
 
-Weight Reduction v Indivisible Packets 
+Classic v Hybrid macro-atom mode 
 =======================================
-SIROCCO was originally written in such a way that photon packet weights were not indivisible and allowed to be attenuated. This is the way the code is described in the original `Long & Knigge 2002 <https://ui.adsabs.harvard.edu/abs/2002ApJ...579..725L/abstract>`_ paper. In the standard, weight reduction mode, photon weights are attenuated by continuum opacities (free-free, bound-free). Conservation of energy is then hopefully achieved by calculating the emission from the wind .
+(or, Weight Reduction v Indivisible Packets)
 
-In indivisible packet mode, there is a fundamental shift in philosophy. All energy packets are strictly indivisible and conserve energy whenever they undergo radiative processes (the only exception is adiabatic cooling). Thus, even bound-free absorption is dealt with at a single interaction point.
+SIROCCO has two modes of operation when it comes to radiative transfer: the first is the *hybrid macro-atom* mode, which is usually the more physically accurate; the second is the *classic* mode, which has been extensively used by our collaboration in the past and is still the more appropriate choice for certain applications. We will use this language throughout in describing the two modes of operation. Although both of these modes are designed with the same fundamental physical principles in mind, they differ firstly in how they enforce energy conservation and radiative equilibrium, and secondly in how they handle line transfer and the model atom.
 
-Indivisible packet mode is activated by setting the :ref:`Line_transfer` parameter to either ``macro_atoms`` or ``macro_atoms_thermal_trapping``. The terminology adopted here is slightly confusing, since the line transfer mode does not explicitly include a macro-atom treatment of atomic species (see next subsection).
+SIROCCO was originally written in such a way that photon packet weights were not indivisible and allowed to be attenuated. This is the way the code is described in the original `Long & Knigge 2002 <https://ui.adsabs.harvard.edu/abs/2002ApJ...579..725L/abstract>`_ paper. In this classic mode, photon weights are attenuated by continuum opacities (free-free, bound-free). Conservation of energy is then hopefully achieved by calculating the emission from the wind.
 
-.. admonition:: Developer Note
-
-  The radiative transfer mode is stored using the code variable geo.rt_mode.
+In hybrid macro-atom mode, there is a fundamental shift in philosophy. All energy packets are strictly indivisible and conserve energy whenever they undergo radiative processes (the only exception is adiabatic cooling). Thus, even bound-free absorption is dealt with at a single interaction point.
+
+.. admonition:: Choosing the mode
+
+  Hybrid macro-atom (indivisible packet) mode is activated by setting the :ref:`Line_transfer` parameter to either :code:`macro_atoms` or :code:`macro_atoms_thermal_trapping`. 
+  Classic (weight reduction) mode is activated by selected :code:`escape_prob` or :code:`thermal_trapping`, where the latter choice in both cases means to use anisotropic scattering (recommended).
+
+The terminology adopted here is slightly confusing, since the line transfer mode does not explicitly include a macro-atom treatment of atomic species (see next subsection).
 
 Macro-atoms and 2-level-atoms 
 ==============================
 The macro-atom scheme was devised by Leon Lucy in the early 2000s (`Lucy 2002 <https://ui.adsabs.harvard.edu/abs/2002A%26A...384..725L/abstract>`_, `Lucy 2003 <https://ui.adsabs.harvard.edu/abs/2003A%26A...403..261L/abstract>`_). 
 It involves the reformulation of the process of radiation transport through a plasma in radiative equilibrium into a traffic-flow problem. Lucy showed that, when in radiative equilibrium, the energy flows through a system depend only on the transition probabilities and atomic physics associated with the levels the energy flow interacts with. By quantising this energy flow into radiant (r-) and kinetic (k-) packets, we can simulate the energy transport through a plasma discretised into volume elements (*macro-atoms*), whose associated transition probabilities govern the interaction of radiant and kinetic energy with the ionization and excitation energy associated with the ions of the plasma.
 
-.. todo:: add refs, describe properly.
+.. todo:: improve this description.
 
 .. admonition:: Developer Note
 
@@ -39,14 +44,8 @@ Isotropic v Anisotropic Line Scattering
 ============================================
 SIROCCO always treats electron scattering as an isotropic process, and continuum emission processes are also treated as isotropic, except for Compton scattering. For Compton scattering, the direction and energy change is calculated self-consistently according to the energy change formula :math:`E/E'=1+(h \nu/mc^2)(1+\cos\theta)`. We first draw a random cross section that our photon packet will see. This cross section represents an energy change and hence a direction. The distribution of angles is taken care of by using a differential cross section vs energy change function. 
 
-.. admonition:: Caution
-
-  Compton scattering is currently not accounted for when using indivisible packet mode. 
-
 Line emission and scattering is isotropic unless one of the  ``thermal_trapping`` line transfer modes is selected. In the thermal trapping mode, any line interaction or emission results in an anisotropic direction being generated. This direction is generated by a rejection method which samples the Sobolev escape probability in each direction from the line interaction region. Unless you specifically want to consider isotropic line emission, we recommend always using the anisotropic thermal trapping mode. 
 
-.. todo:: move the below to where we describe photon sources and generation?
-
 In the case of isotropic emission, the direction of a photon packet is chosen so that the probability of emission in each bin of solid angle is the same. It follows that 
 
 .. math::
@@ -79,6 +78,5 @@ In the case of a resonance scatter with line transition u to j, the new frequenc
 
 The above formulae are the non-relativistic case, which is currently used in the code. However, this should in general be improved to use the special relativistic formula. This would produce more accurate Doppler shifts for the fastest regions of an outflow, as the current treatment introduces errors of order 5 Angstroms at the blue edges of the highest velocity absorption lines in quasar and CV wind models.
 
-When real photons resonantly (or electron) scatter off real plasma in a flow, they conserve energy and frequency in the co-moving frame of the plasma. In the case of an outflow, doing the frame transformation from system->flow->system over the course of an interaction results in a redshifting of a photon, and as a result an energy loss - in other words, the photon does work on the flow even though energy is conserved in the co-moving frame. Indivisible packet schemes (such as macro-atoms) often enforce strict energy conservation in the frame of a given cell (physically, but see also `Lucy 2002 <https://ui.adsabs.harvard.edu/abs/2002A%26A...384..725L/abstract>`_). This means that, when keeping track of packets in the observer frame, one needs to correct the energies (not just the frequencies) using a Doppler shift. SIROCCO does **not** currently conserve energy in the co-moving frame.
-
-.. todo:: test whether this is an issue.
+When real photons resonantly (or electron) scatter off real plasma in a flow, they conserve energy and frequency in the co-moving frame of the plasma. In the case of an outflow, doing the frame transformation from system->flow->system over the course of an interaction results in a redshifting of a photon, and as a result an energy loss - in other words, the photon does work on the flow even though energy is conserved in the co-moving frame. Indivisible packet schemes (such as macro-atoms) often enforce strict energy conservation in the frame of a given cell (physically, but see also `Lucy 2002 <https://ui.adsabs.harvard.edu/abs/2002A%26A...384..725L/abstract>`_). This means that, when keeping track of packets in the observer frame, one needs to correct the energies (not just the frequencies) using a Doppler shift.
+SIROCCO does conserve energy in the co-moving frame.

docs/sphinx/source/plotting.rst

@@ -23,4 +23,5 @@ with more detail on python scripts and packages provided in :ref:`the API docume
 .. nbgallery::
    plotting/plot_spectrum
    plotting/plot_wind
-   plotting/Convergence
+   plotting/Convergence
+   plotting/ion-models

docs/sphinx/source/plotting/Convergence.ipynb

@@ -113,7 +113,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 5,
    "id": "823376ab-46ab-459e-86f8-30d65d0f69b0",
    "metadata": {},
    "outputs": [
@@ -151,7 +151,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 6,
    "id": "f0dfcc31-4f85-40b2-ab68-6403ab0c1d9d",
    "metadata": {},
    "outputs": [
@@ -161,7 +161,7 @@
        "[]"
       ]
      },
-     "execution_count": 12,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -192,7 +192,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 7,
    "id": "3ec0fab5-5b11-4c81-af49-66271fdb760b",
    "metadata": {},
    "outputs": [

docs/sphinx/source/running_sirocco.rst

@@ -97,22 +97,29 @@ which may be useful in certain special cases.  These include:
   are maintained as to the number of times the error occurred, but it is not printed
   to the diagnostic file. The default is 100 (per process)
 
--classic
+-f                    
+  Invoke a fixed temperature mode
+
+-nonrel
   Reverts to using v/c corrections for special relativity and eliminates work done to treat
   co-moving frames properly.  This is for testing, and is likely to be removed in the not
   too distant future.
 
--srclassic
-   Use SIROCCO with full special relativity for Doppler shits, etc., but do not include any co-moving frame effects.
+-sr_doppler_only
+  Use SIROCCO with full special relativity for Doppler shits, etc., but do not include any co-moving frame effects.
 
 -no-matrix-storage
-   Do not store macro-atom transition matrices if using the macro-atom line transfer and the matrix matom_transition_mode.
+  Do not store macro-atom transition matrices if using the macro-atom line transfer and the matrix matom_transition_mode.
 
 -ignore_partial_cells
-   Ignore wind cells that are only partially filled by the wind (This is now the default)
+  Ignore wind cells that are only partially filled by the wind (This is now the default)
 
 -include_partial_cells
-   Include wind cells that are only partially filled by the wind
+  Include wind cells that are only partially filled by the wind
+
+-xtest
+  Instead of running sirocco, call the routine xtest so that one can diagnose issues associted with the 
+  setup.  This is only useful to developers.
 
 Running Different Versions of SIROCCO
 =================================
@@ -130,4 +137,4 @@ You can then run a specific installed version by replacing the SIROCCO executabl
 
   .. code :: bash
 
-    sirocco87a root.pf
+    sirocco-0.1 root.pf