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

Improve documentation.

CITATION.cff

@@ -1,23 +1,23 @@
 cff-version: 1.2.0
-title: "Python"
-repository-code: https://github.com/agnwinds/python
-abstract: "A code for Monte Carlo simulation of radiative transfer & ionisation within astrophysical compact object systems."
-message: "If you use Python, please cite both the 2002 concept paper and the software release paper."
-version: 88a
-date-released: 2024-04-11
+title: "Sirocco"
+repository-code: https://github.com/sirocco-rt/sirocco
+abstract: "Simulating Ionization and Radiation in Outflows Created by Compact Objects"
+message: "If you use Sirocco, please cite both the 2002 concept paper and the software release paper."
+version: v0.1
+date-released: 2024-10-22
 doi: 10.1086/342879
 identifiers:
   - type: doi
     value: 10.1086/342879
-    description: "2002 concept paper for the Python project."
+    description: "2002 concept paper for the Sirocco project."
   - type: doi
     value: 10.1234/567890
     description: "[PLACEHOLDER] Software release paper for this software."
   - type: doi
     value: 10.1234/zenodo.5678
-    description: "[PLACEHOLDER] The Zenodo project DOI for the Python code."
+    description: "[PLACEHOLDER] The Zenodo project DOI for the Sirocco code."
 authors:
-  - name: The Python collaboration
+  - name: The Sirocco collaboration
   - family-names: Long
     given-names: Knox
     orcid: https://orcid.org/0000-0002-4134-864X
@@ -72,4 +72,4 @@ authors:
     affiliation: "University of Southampton"
   - family-names: Gupta
     given-names: Rahul
-    affiliation: "Imperial College London"
+    affiliation: "Imperial College London"

README.md

@@ -1,4 +1,8 @@
-# SIROCCO
+<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)
+[![Documentation Status](https://readthedocs.org/projects/sirocco-rt/badge/?version=latest)](https://sirocco-rt.readthedocs.io/en/latest/?badge=latest)
 
 *Sirocco* (Simulating Ionization and Radiation in Outflows Created by Compact Objects) is a Monte Carlo radiative transfer code which uses the Sobolev approximation. The code was formerly known as Python and renamed in October 2024. It has been developed by Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Manghamm Edward Parkinson, Mandy Hewitt and Nico Scepi. The code has been used for a variety of research projects invovling the winds of cataclysmic variables, young stellar objects, X-ray binaries and AGN.
 
@@ -7,12 +11,6 @@ or James Matthews via james[dot]matthews[at]physics[dot]ox[dot]ac[dot]uk.
 
 Documentation is hosted on [ReadTheDocs](http://sirocco-rt.readthedocs.io/en/dev/).
 
-## CI \& Docs Build Status
-
-[![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)
-
-[![Documentation Status](https://readthedocs.org/projects/sirocco-rt/badge/?version=latest)](https://sirocco-rt.readthedocs.io/en/latest/?badge=latest)
-
 ## 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. 
@@ -21,7 +19,7 @@ If you want to obtain a stable (!) release, go to the [Releases](https://github.
 
 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. Aternatively, you can clone the repository using 
 
-    $ git clone https://github.com/agnwinds/python.git 
+    $ git clone https://github.com/sirocco-rt/sirocco.git 
 
 If you anticipate contributing to development we suggest forking the repository and submitting pull requests with any proposed changes.
 
@@ -46,16 +44,16 @@ also to download various model grids of spectra that have been used in conjuncti
 
 These can be downloaded as follows:
 
-    $ cd $SIROCCO; git clone https://github.com/agnwinds/xmod xmod 
+    $ cd $SIROCCO; git clone https://github.com/sirocco-rt/xmod xmod 
 
 (Previously, both the atomic data and the model grids were stored in a separate repository.  Users wishing
 to run older versions of the code pre-84b may need to download the 
 [old data repository](https://github.com/sirocco-rt/data)  This repository can be downloaded as follows
 
 
-    $ cd $SIROCCO; git clone https://github.com/agnwinds/data data
+    $ cd $SIROCCO; git clone https://github.com/sirocco-rt/data data
 
-Those users interested in the current version of Python should not need to do this)
+Those users interested in the current version of Sirocco should not need to do this)
 
 ## Running Sirocco
 

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

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.
 
 

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
 

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.
 

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
 

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
 

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

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:

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

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:

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

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.