Merge pull request #1122 from sirocco-rt/dev

dev->main: mostly documentation and cleanup
sirocco-rt · Oct 29, 2024 · bcae89f · bcae89f
2 parents 5fc7b81 + 82ba76f
commit bcae89f
Show file tree

Hide file tree

Showing 266 changed files with 1,125 additions and 3,680 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -53,7 +53,7 @@ jobs:
     - name: Checking Sirocco compiled and can read in inputs correctly
       run: |
         cd $SIROCCO/examples/gh-workflow/
-        $SIROCCO/bin/Setup_Py_Dir
+        $SIROCCO/bin/Setup_Sirocco_Dir
         $SIROCCO/bin/sirocco -i cv_macro_benchmark
         $SIROCCO/bin/sirocco -i cv_standard
         $SIROCCO/bin/sirocco -i fiducial_agn

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-<img src="https://github.com/user-attachments/assets/1f4b0865-251d-407f-821a-021f7a0beac8" alt="drawing" style="width:400px;"/>
+<img src="https://github.com/user-attachments/assets/1f262fb8-5f67-42df-ac5f-68ac7f792e15" alt="drawing" style="width:400px;"/>
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13969075.svg)](https://doi.org/10.5281/zenodo.13969075)
 [![C/C++ CI](https://github.com/sirocco-rt/sirocco/actions/workflows/build.yml/badge.svg)](https://github.com/sirocco-rt/sirocco/actions/workflows/build.yml)
@@ -64,7 +64,7 @@ To run Sirocco you need to add the following to your $PATH variable:
 
 You can then setup your symbolic links by running 
 
-    $ Setup_Py_Dir
+    $ Setup_Sirocco_Dir
 
 and run the code by typing, e.g.
 

diff --git a/bin/Setup_Py_Dir → bin/Setup_Sirocco_Dir b/bin/Setup_Py_Dir → bin/Setup_Sirocco_Dir
diff --git a/docs/documentation_overview.html b/docs/documentation_overview.html
@@ -5,7 +5,8 @@
     <title>index</title>
   </head>
   <body>
-    <h1>Documentation Overview</h1>
+    <h1>Documentation Overview for Sirocco<br>
+    </h1>
     <p> Note:&nbsp; Documentation is an ongoing effort, and is not
       always up to date. If you notice a problem, please open an<a
         moz-do-not-send="true"
@@ -16,14 +17,15 @@ <h1>Documentation Overview</h1>
     <p> At present the main resources are as follows: </p>
     <ul>
       <li>A draft version of a <a href="cookbook.pdf">cookbook</a>
-        which describes how to install&nbsp; and update Python and run a
-        first model</li>
+        which describes how to install&nbsp; and update Sirocco and run
+        a first model</li>
       <li> A <a href="sphinx/html/index.html">Sphinx</a> repository,
-        which provides the main documentation for Python</li>
+        which provides the main documentation for Sirocco</li>
       <ul>
         <li>A fairly up-to-date version of this documentation may be
           found on Readthedocs <a
-            href="https://agnwinds.readthedocs.io/en/readthedocs/">here</a></li>
+            href="https://sirocco-rt.readthedocs.io/en/latest/"
+            moz-do-not-send="true">here</a></li>
         <li>However, if one wishes to have the latest/local version, or
           the version for a particular branch, one needs to generate the
           html files locally from the source (.rst) files which are
@@ -46,7 +48,7 @@ <h1>Documentation Overview</h1>
       </ul>
       <li> A <a href="pydocs/doc_py_progs.html">pydocs repository</a>
         which provides information about the python scripts contained in
-        $PYTHON/py_progs</li>
+        $SIROCCO/py_progs</li>
       <ul>
         <li>These files are also tracked by git.&nbsp; <br>
         </li>
@@ -75,6 +77,7 @@ <h1>Documentation Overview</h1>
 
 
 
+
         provides information about the source code.</li>
       <ul>
         <li>Like the other documentation, the Doxygen information is not
@@ -104,6 +107,7 @@ <h1>Documentation Overview</h1>
 
 
 
+
             <br>
           </li>
           <li>To get the graphs that show which routines call which

diff --git a/docs/doxygen/python_docs.config → docs/doxygen/sirocco_docs.config b/docs/doxygen/python_docs.config → docs/doxygen/sirocco_docs.config
@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "Python MCRT"
+PROJECT_NAME           = "Sirocco MCRT"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version

diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt
@@ -12,4 +12,4 @@ sqlalchemy
 jinja2==3.1.4
 sphinx_gallery
 pyhdf
-sphinx-autoapi==3.1.1
+sphinx-autoapi==3.1.1
diff --git a/docs/sphinx/source/atomic/bound_bound.rst b/docs/sphinx/source/atomic/bound_bound.rst
@@ -23,8 +23,8 @@ We have also used a line list from Verner in the past
 
 
 Translation to SIROCCO format
-============================
-There are several steps to creating the data used in SIROCCO from that in gfall.dat, that are carried out by py_read_kurucz and py_link. The first routine reads the gfall.dat file and creates two output files, a file containing the lines and the associated such as the effective oscillatory strength and a file which contains information about the ion levels.  py_read_kurucz chooses only a portion of the Kurucz lines, namely those associated with ions with ionization potentials in a certain range and lines with gf factors exceeding a certain value. The second program py_link attempts to create a model ion with links between the levels and the ions.  Both of these routines are driven by .pf files, similar to what are used in python.  Examples of the .pf files are in the directory py_kurucz
+======================================
+There are several steps to creating the data used in SIROCCO from that in gfall.dat, that are carried out by py_read_kurucz and py_link. The first routine reads the gfall.dat file and creates two output files, a file containing the lines and the associated such as the effective oscillatory strength and a file which contains information about the ion levels.  py_read_kurucz chooses only a portion of the Kurucz lines, namely those associated with ions with ionization potentials in a certain range and lines with gf factors exceeding a certain value. The second program py_link attempts to create a model ion with links between the levels and the ions.  Both of these routines are driven by .pf files, similar to what are used in SIROCCO.  Examples of the .pf files are in the directory py_kurucz
 
 In practice we have not used these data for any SIROCCO publications. At some point early in the AGN project, NSH increased the number of lines, and generated lines\_linked\_ver\_2.dat and levels\_ver\_2.dat. I think this was because there was a small bug which meant the oscillator strength cut that was stated was not that which was applied.
 
@@ -69,12 +69,12 @@ one needs to index everything self-consistentl
 
 
 SIROCCO structure
-================
+================================
 
 Line data is stored in the data structure **lines**
 
 Comments
 ========
-The version of gfall.dat that is used in SIROCCO is out of date, though whether this affects any of the lines actually used in python is unclear.  The website listed above has a link to newer versions of gfall.dat.
+The version of gfall.dat that is used in SIROCCO is out of date, though whether this affects any of the lines actually used in SIROCCO is unclear.  The website listed above has a link to newer versions of gfall.dat.
 
 
diff --git a/docs/sphinx/source/atomic/bound_bound_electron_collision_strengths.rst b/docs/sphinx/source/atomic/bound_bound_electron_collision_strengths.rst
@@ -20,7 +20,7 @@ These values of :math:`\Upsilon` simply replace :math:`\Omega`.
 In the asbsence of data in this format, the Van Regemorter approximation is utilized.
 
 Translation to SIROCCO format
-============================
+======================================
 
 It is necessary to link each line in our line list with the relevant electron collision strength. This is achieved using the python script "coll_stren_lookup.py" which first reads in the  "lines_linked_ver_2.py" line list, then attempts to work out which lines are which by comparing the energy and the oscillator strength of the line. If these match to within a factor of 10% then the code logs this as a possible match. If better matches come along, then the code adopts those instead.
 
@@ -67,7 +67,7 @@ and
 So, to get :math:`\Upsilon` for a given T, one converts T to x via the correct equation, then linearly interpolate between values of :math:`y(x)`, then convert back to :math:`\Upsilon`.
 
 SIROCCO structure
-================
+==========================
 
 The data is stored in SIROCCO in the Coll\_stren structure which has memebers
 

diff --git a/docs/sphinx/source/atomic/bound_free_topbase.rst b/docs/sphinx/source/atomic/bound_free_topbase.rst
@@ -9,7 +9,7 @@ Obtained from The `Opacity project <http://cdsweb.u-strasbg.fr/topbase/topbase.h
 
 
 Translation to SIROCCO format
-============================
+======================================
 
 ksl - It's not clear that we are now making use of the topbase data in this way but my original attempt to incorporate topbase photoinization data into SIROCCO is contained in the directory topbase. Processing of these files was done by py_top_phot. My feeling is that we can replace these remarks with those that are more up to date, once Nick and James discuss this section, and delete any mention of my original attempt on this in the data-gen archive.
 
@@ -64,12 +64,12 @@ For the macro atom case, the indices relate to the energy levels, that is these
 The TopBase energies are inaccurate and so generally adjustments are made using Chianti or some other source to fix up the energy levels.
 
 SIROCCO structure
-================
+==========================
 
 The data are stored in the Topbase_phot stucture which can be found in atomic.h
 
 Criteria for usage in SIROCCO run
-================================
+==========================================
 
 Data has to be read into SIROCCO in a logical order.  For a set of  phototionization x-sections to be accepted, the energy levels (or configuratios) must already have been defiend.  See :doc:`levels`
 
@@ -119,6 +119,6 @@ This is the shape of a hydrogenic cross-section and whilst it is not accurate
 for non-hydrogenic ions, it is more realistic (and conservative) than some of 
 the unphysically shallow gradients that were being found.
 This is also briefly described in section~3.7.2 of Matthews PhD thesis.
-The python scripts can be found in the `data-gen <https://github.com/agnwinds/data-gen>`_ repository progs/extrapolate\_xs/ 
+The python scripts can be found in the `data-gen <https://github.com/sirocco-rt/data-gen>`_ repository progs/extrapolate\_xs/ 
 with docstrings describing their use.
 
diff --git a/docs/sphinx/source/atomic/bound_free_verner.rst b/docs/sphinx/source/atomic/bound_free_verner.rst
@@ -16,7 +16,7 @@ There are three sources for this data
 
 
 Translation to SIROCCO format
-============================
+======================================
 
 **Tabulation Process**
 
@@ -62,7 +62,7 @@ This data is linked to the relevant ion via z and state, islp and level are not
 This data is linked to the relevant ion via z and state. the n_shell and l_subshell numbers are used to cross reference to the electron yield records. As above, the last record shows how many points are in the fit, and the data pairs making up the fit follow with the keyword InnerVY.
 
 SIROCCO structure
-================
+==========================
 
 Where the data is stored internally in SIROCCO
 

diff --git a/docs/sphinx/source/atomic/direct_ionization.rst b/docs/sphinx/source/atomic/direct_ionization.rst
@@ -11,7 +11,7 @@ The data comes directly from `Dere 2006, A&A, 466, 771 <https://www.aanda.org/ar
 
 
 Translation to SIROCCO format
-============================
+======================================
 
 
 The data table is downloaded in its entirety  from the data table associated with the paper. All that happens is that the table is saved to a text file, and the keyword DI_DERE is just prepended to each row.
@@ -41,7 +41,7 @@ The rate coefficient R(T) is recovered from the scaled rate coefficient in the t
 where :math:`E_{1}` is the first exponential integral. In python we use the  gsl_sf_expint_E1 routine in gsl.
 
 SIROCCO structure
-================
+==========================
 
 This data is stored in the  dere_di_rate structure with members
 

diff --git a/docs/sphinx/source/atomic/electron_yields.rst b/docs/sphinx/source/atomic/electron_yields.rst
@@ -10,7 +10,7 @@ Source
 This data comes from `Kaastra and Mewe 1993, A&A, 97, 443 <http://articles.adsabs.harvard.edu/full/1993A%26AS...97..443K>`_ . The data is downloaded from the vizier site linked and put into a file called "electron_yield.data"
 
 Translation to SIROCCO format
-============================
+======================================
 
 The translation takes place using the python script "kaastra_2_py.py" which takes the saved raw data file "electron_yield.data" and compares it line by line to the inner shell cross section data in "vy_innershell_tab.data"(see above). The n shell and l subshell to which each record applies is coded in the KM data and needs to be decoded. This is what the script does, and all the script then does is output the yield data into a new file "kaastra_electron_yield.data" which contains the n and l cross reference.
 
@@ -36,9 +36,9 @@ The data is linked to the correct inner shell photoionization cross section (and
 
 
 SIROCCO structure
-================
+==========================
 
-The data is stored in python in the inner_elec_yield structure which contains
+The data is stored in SIROCCO in the inner_elec_yield structure which contains
 
 - int nion - Index to the ion which was the parent of the inner shell ionization
 - int z, istate - element and ionization state of parent ion

diff --git a/docs/sphinx/source/atomic/elem_ions.rst b/docs/sphinx/source/atomic/elem_ions.rst
@@ -10,8 +10,8 @@ This data comes from `Verner, Barthel & Tytler, 1994, ApJ 108, 287. <http://arti
 
 
 
-Translation to python:
-======================
+Translation to SIROCCO:
+================================
 
 The original data and the translation can be found in py\_verner.  A simple awkscript converts the downloaded data to SIROCCO format.
 
@@ -93,7 +93,7 @@ Note that only evident changed is the label, but in this case the number of nlte
 
 
 SIROCCO structure:
-=================
+===========================
 This data is held in SIROCCO in various fields in structures **elements** and **ions**.
 
 Comments:

diff --git a/docs/sphinx/source/atomic/free-free.rst b/docs/sphinx/source/atomic/free-free.rst
@@ -14,13 +14,13 @@ The free-free Gaunt factors are taken from  `Sutherland 1998, MNRAS, 300, 321. <
 
 The last file is the one we use to calculate free-free emission, since this in integrated gaunt factor over a population of electrons  with a Boltzmann distribution of velocities.  The other two files could be of use in the future should we wish to have gaunt factor corrections for the heating rates,in which case we should use the gffgu.dat data file. However generally speaking free-free heating is never important and there would be significant overhead in calculating a gaunt factor for each photon.
 
-Translation to python
-=====================
+Translation to SIROCCO
+===============================
 The file is simply modified by hand to put a label "FF\_GAUNT" at the start of each data line and a hash at the start of each comment line.
 
 Datafile - gffint.dat:
 ======================
-The format of the data file to be read into python is as follows:
+The format of the data file to be read into SIROCCO is as follows:
 
 +----------+------------------------+---------------------------+-----------+-----------+-----------+
 |Label     | :math:`\log(\gamma^2)` |:math:`<g_{ff}(\gamma^2)>` |:math:`s_1`|:math:`s_2`|:math:`s_3`|
@@ -49,7 +49,7 @@ where
 :math:`\Delta=\log(x)-\log(\gamma^2)`
 
 SIROCCO structure
-================
+==========================
 This data is held internally in SIROCCO in the structure **gaunt_total** which has members
 
 - log_gsqrd

diff --git a/docs/sphinx/source/atomic/levels.rst b/docs/sphinx/source/atomic/levels.rst
@@ -13,8 +13,8 @@ Level information can be derived from a variety of sources, by:
    * more commonly, for data abstracted from TopBase or Chianti
 
 
-Translation to python:
-======================
+Translation to SIROCCO:
+================================
 
 
 
@@ -83,7 +83,7 @@ between ions, and so it includes the ionization energy of the lower level ioniza
 Note that the radiative rates are not used. The original intention was to use this to define the 
 difference between metastable and normal levels, with the expectation that if the level was metastable it 
 would be put in Boltzmann equilibrium with the ground state. 
-Right now python uses :math:`10^{15}` seconds, essentially a Hubble time to do this, but this portion of the 
+Right now SIROCCO uses :math:`10^{15}` seconds, essentially a Hubble time to do this, but this portion of the 
 code is not, according to ss, tested. 
 
 The primary source for this is usually the NIST database, although similar information is usually available in Chianti. 
@@ -94,7 +94,7 @@ Since they quote J, one converts to g = 2J+1
 The ionization potential is not used, as it is redundant with the excitation energy which is, and the last column giving the configuration is also for information only.
 
 SIROCCO structure:
-=================
+===========================
 This data is held in SIROCCO in various fields in structure **config**.
 
 Comments:

diff --git a/docs/sphinx/source/atomic/photon_yields.rst b/docs/sphinx/source/atomic/photon_yields.rst
@@ -9,7 +9,7 @@ Source
 This data comes from `Kaastra and Mewe 1993, A&A, 97, 443 <http://articles.adsabs.harvard.edu/full/1993A%26AS...97..443K>`_ . The data is downloaded from the vizier site linked and put into a file called "fluorescent\_yield.data"
 
 Translation to SIROCCO format
-============================
+======================================
 
 The translation takes place using the python script "kaastra_2_py.py". All identical to electron yield, but input file is "fluorescent_yield.data" and output is "kaastra_fluorescent_yield.data"
 
@@ -35,9 +35,9 @@ The data is linked to the correct inner shell photoionization cross section (and
 
 
 SIROCCO structure
-================
+==========================
 
-The data is stored in python in the inner_fluor_yield structure which contains
+The data is stored in SIROCCO in the inner_fluor_yield structure which contains
 
 
 - int nion - Index to the ion which was the parent of the inner shell ionization

diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -87,9 +87,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '88'
+version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '88a'
+release = '0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/sphinx/source/developer/cuda.rst b/docs/sphinx/source/developer/cuda.rst
@@ -241,7 +241,7 @@ The following code exert is an example of using the wrapper function to solve a
 .. code:: c
     :caption: The API to solve a linear system hasn't changed
 
-    #include "python.h"
+    #include "sirocco.h"
 
     double *populations = malloc(nions * sizeof(*populations));
     double *ion_density = malloc(nions * sizeof(*populations));
@@ -269,7 +269,7 @@ Here is an example of using a similar wrapper function to calculate the inverse
 .. code:: c
     :caption: The API has changed slightly for calculating the inverse, now that it has a wrapper function
 
-    #include "python.h"
+    #include "sirocco.h"
 
     double Q_matrix = malloc(matrix_size * matrix_size * sizeof(double));
     double Q_inverse = malloc(matrix_size * matrix_size * sizeof(double));
@@ -383,7 +383,7 @@ The steps for compiling and link GPU and CPU code are outlined below in pseudo-M
     $(CC) $(C_FLAGS) $(C_SOURCE) -c -o $(C_OBJECTS)
 
     # Link the CUDA and C object code and libraries together using the C compiler
-    $(CC) $(CUDA_OBJECTS) $(C_OBJECTS) -o python $(CUDA_LIBS) $(C_LIBS)
+    $(CC) $(CUDA_OBJECTS) $(C_OBJECTS) -o sirocco $(CUDA_LIBS) $(C_LIBS)
 
 These steps are effectively replicated in the Makefile :code:`$SIROCCO/source/Makefile`, where a deconstructed example is
 shown below.
@@ -409,8 +409,8 @@ shown below.
     endif
 
     # So to compile SIROCCO, we have something which looks vaguely like this. Note that
-    # we use the CUDA_OBJECTS recipe as a requirement for the python recipe. This CUSOLVER_STATUS_SUCCESS
+    # we use the CUDA_OBJECTS recipe as a requirement for the sirocco recipe. This CUSOLVER_STATUS_SUCCESS
     # the CUDA source to be compiled to object code *if* NVCC is defined
-    python: startup python.o $(python_objects) $(CUDA_OBJECTS)
-        $(CC) $(CFLAGS) python.o $(python_objects) $(CUDA_OBJECTS) $(kpar_objects) $(LDFLAGS) -o python
+    sirocco: startup sirocco.o $(sirocco_objects) $(CUDA_OBJECTS)
+        $(CC) $(CFLAGS) sirocco.o $(sirocco_objects) $(CUDA_OBJECTS) $(kpar_objects) $(LDFLAGS) -o sirocco