sirocco-rt · jhmatthews · May 22, 2026 · Nov 8, 2024 · Nov 8, 2024 · Nov 9, 2024
diff --git a/.gitignore b/.gitignore
@@ -1,11 +1,14 @@
 # This is the git ignore for python
 # ignore binaries in bin/ such as e.g. py78a
+bin/sirocco*
+bin/swind*
 bin/py*
 bin/windsave2table*
 bin/rad_hydro*
 bin/inspect_wind*
 bin/modify_wind*
 
+
 # Run files
 *.spec*
 *.pf.old
@@ -60,6 +63,7 @@ Makefile
 docs/sphinx/html/
 docs/sphinx/doctrees/
 docs/sphinx/venv/
+docs/sphinx/source/py_progs/py4py_auto/
 
 # doxygen stuff
 docs/doxygen/html/
@@ -95,7 +99,7 @@ source/version.h
 # we also should not track templates.h.old either
 source/templates.h.old
 
-# python output files
+# sirocco output files
 *.diag
 *.spec
 *.log_spec
@@ -105,10 +109,16 @@ source/templates.h.old
 *.sig
 *.out.pf
 logfile
+*.wind_save
 
 # IDE files
 .idea/
 **/*.vscode/
 py_progs/.idea/
 scratch/
 
+
+# files from sed or other -e modifier
+*-e 
+
+
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 The code is under active development, but we are looking for beta users to test the code, and potentially use it for their own research. If you are interested in using Sirocco please contact Knox Long via long[at]stsci[dot]edu 
 or James Matthews via james[dot]matthews[at]physics[dot]ox[dot]ac[dot]uk.
 
-Documentation is hosted on [ReadTheDocs]((https://sirocco-rt.readthedocs.io).
+Documentation is hosted on [ReadTheDocs](https://sirocco-rt.readthedocs.io).
 
 ## Installation
 

diff --git a/bin/Setup_Py_Dir b/bin/Setup_Py_Dir
@@ -0,0 +1 @@
+Setup_Sirocco_Dir
diff --git a/docs/documentation_overview.html b/docs/documentation_overview.html
@@ -32,6 +32,22 @@ <h1>Documentation Overview for Sirocco<br>
           tracked in git.</li>
         <li>To generate the Sphinx documentation one needs <a
             href="http://www.sphinx-doc.org/en/master/">sphinx</a></li>
+        <li>Because we use an package called <a moz-do-not-send="true"
+            href="https://pysi.readthedocs.io/en/stable/">PySi</a> in
+          conjunction with some of the Jupyter scripts and because this
+          code has some verison dependences, we recommend creating an
+          environment to encapsulate the version needed to compile all
+          of the documention.&nbsp; In conda, one can create this with:</li>
+        <ul>
+          <li>conda<span class="w"> </span>create<span class="w"> </span>-n<span
+              class="w"> </span>xsphinx<span class="w"> </span><span
+              class="nv">python</span><span class="o">=</span><span
+              class="m">3</span>.1</li>
+          <li>conda<span class="w"> </span>activate<span class="w"> </span>xsphinx</li>
+          <li>cd docs/sphinx</li>
+          <li>pip3<span class="w"> </span>install<span class="w"> </span>-r<span
+              class="w"> </span>requirements.txt</li>
+        </ul>
       </ul>
       <ul>
       </ul>
@@ -78,6 +94,7 @@ <h1>Documentation Overview for Sirocco<br>
 
 
 
+
         provides information about the source code.</li>
       <ul>
         <li>Like the other documentation, the Doxygen information is not
@@ -108,6 +125,7 @@ <h1>Documentation Overview for Sirocco<br>
 
 
 
+
             <br>
           </li>
           <li>To get the graphs that show which routines call which

diff --git a/docs/doxygen/sirocco_docs.config b/docs/doxygen/sirocco_docs.config
@@ -885,6 +885,7 @@ EXCLUDE                += ../../source/modify_wind.c
 EXCLUDE                += ../../source/rad_hydro_files.c
 EXCLUDE                += ../../source/rpy_optd_trans.c
 EXCLUDE                += ../../source/py_optd.c
+EXCLUDE                += ../../source/templates.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

diff --git a/docs/parameters/Central_object.geometry_for_source.yaml b/docs/parameters/Central_object.geometry_for_source.yaml
@@ -13,6 +13,13 @@ values:
     Emission is cosine-weighted in the direction of the sphere normal at the point of emission.
     Photons that would be spawned in an extended disk (if :ref:`Disk.type` is `vertically.extended`)
     are re-generated.
+  bubble: |
+    The central source radiates from between two spheres, one with radius :ref:`Central_object.radius` 
+    and one with radius :ref:`Central_object.bubble_size`. The photon directions are individually isotropic but do not necessarily
+    create a truly isotropic source.
+  iso: |
+    The central source radiates from the surface of a sphere with radius :ref:`Central_object.radius`.
+    Emission is truly isotropic, so photons are emitted in the same direction as the random point on the sphere surface where they are emitted.
 parent:
   System_type: [agn, bh]
   Central_object.radiation: true

diff --git a/docs/parameters/Ionization_cycles.convergence_fraction.yaml b/docs/parameters/Ionization_cycles.convergence_fraction.yaml
@@ -0,0 +1,12 @@
+name: '@estop.Ionization_cycles.convergence_fraction(%)'
+description: |
+  The minimum percentage of cells that must be converged before early stopping
+  is allowed. This acts as a floor to prevent the code from stopping early on
+  a model that is stably unconverged (e.g. only 50% of cells converged).
+  For example, a value of 80 means at least 80% of cells must be converged
+  for the early stopping check to trigger.
+  Only queried when the -early_stopping switch is used.
+type: Double
+values: 0 to 100
+default: 80
+file: setup.c
diff --git a/docs/parameters/Ionization_cycles.convergence_lookback.yaml b/docs/parameters/Ionization_cycles.convergence_lookback.yaml
@@ -0,0 +1,10 @@
+name: '@estop.Ionization_cycles.convergence_lookback'
+description: |
+  The number of consecutive cycles over which the convergence fraction must
+  be stable (average absolute change < tolerance) before early stopping triggers.
+  Larger values are more conservative. Only queried when the -early_stopping
+  switch is used.
+type: Integer
+values: 2 to 100
+default: 5
+file: setup.c
diff --git a/docs/parameters/Ionization_cycles.convergence_tolerance.yaml b/docs/parameters/Ionization_cycles.convergence_tolerance.yaml
@@ -0,0 +1,14 @@
+name: '@estop.Ionization_cycles.convergence_tolerance(%)'
+description: |
+  Percentage tolerance for early stopping of ionization cycles. If the
+  average cycle-to-cycle change in the convergence fraction over the
+  lookback window falls below this percentage AND the convergence fraction
+  is at or above the floor set by @estop.Ionization_cycles.convergence_fraction,
+  ionization stops early and proceeds to spectrum extraction. For example,
+  a value of 2 means stop when the average change is less than 2%.
+  Only queried when the -early_stopping switch is used.
+  Typical values: 1 to 5
+type: Double
+values: '> 0'
+default: 2
+file: setup.c
diff --git a/docs/parameters/Ionization_cycles.min_cycles.yaml b/docs/parameters/Ionization_cycles.min_cycles.yaml
@@ -0,0 +1,9 @@
+name: '@estop.Ionization_cycles.min_cycles'
+description: |
+  The minimum number of ionization cycles to complete before early stopping
+  is allowed. This prevents premature termination before the wind has had
+  a chance to settle. Only queried when the -early_stopping switch is used.
+type: Integer
+values: Greater than or equal to 0
+default: 0
+file: setup.c
diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile
@@ -14,6 +14,9 @@ help:
 
 .PHONY: help Makefile
 
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) --ignore "*py4py_auto*" --ignore "*/.ipynb_checkpoints*" --ignore "*/__pycache__*" --ignore "*.sphinx_cannot_doc"
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt
@@ -12,4 +12,6 @@ sqlalchemy
 jinja2==3.1.4
 sphinx_gallery
 pyhdf
-sphinx-autoapi==3.1.1
+sphinx-autoapi
+sphinx-autobuild
+git+https://github.com/sirocco-rt/pysi.git@main#egg=pysi
diff --git a/docs/sphinx/requirements_nopysi.txt b/docs/sphinx/requirements_nopysi.txt
@@ -0,0 +1,16 @@
+sphinx~=7.3
+sphinx-issues==4.1.0
+ipython
+nbsphinx
+sphinx-rtd-theme
+docutils
+astropy
+numpy
+matplotlib
+scipy
+sqlalchemy
+jinja2==3.1.4
+sphinx_gallery
+pyhdf
+sphinx-autoapi
+sphinx-autobuild
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -79,17 +79,17 @@
 # General information about the project.
 project = "SIROCCO"
 
-copyright = '2018-2024, Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Nicolas Scepi, Austen Wallis, Amin Mosallanezhad'
+copyright = '2018-2025, Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Nicolas Scepi, Austen Wallis, Amin Mosallanezhad'
 author = 'Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Nicolas Scepi, Austen Wallis, Amin Mosallanezhad'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '1.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '1.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -120,6 +120,7 @@
     "../../../py_progs/py4py/py4py",
 ]
 autoapi_root = 'py_progs/py4py_auto'
+autoapi_keep_files = True
 autoapi_python_class_content = 'both'
 autoapi_template_dir = '_templates'
 

diff --git a/docs/sphinx/source/developer/mpi_comms.rst b/docs/sphinx/source/developer/mpi_comms.rst
@@ -58,7 +58,7 @@ elements in an array of that same type. Consider the example below,
     int *my_int_arr = malloc(10 * sizeof(int));
     int num_ints = 11;
 
-In this case there are 11 :code:`int`s which will want to be communicated. In practise, calculating the communication
+In this case there are 11 integer variables which will want to be communicated. In practise, calculating the communication
 buffer is usually done as in the code example below:
 
 .. code:: c

diff --git a/docs/sphinx/source/images/Speculate_logo5.png b/docs/sphinx/source/images/Speculate_logo5.png
diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst
@@ -23,14 +23,16 @@ was intended for simulating the spectra of winds in cataclysmic variables. Since
 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>`_
+sirocco-1.0, the version of the code in January 2025, 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
 regarding the code and suggestions for improvement should be reported there.  We actively encourage others to make use of
 the code for their own science.  If anyone has questions about whether the code might be useful for a project, we
 encourage you to contact one of the authors of the code.
 
+You can join the users mailing list through our `Sirocco Users Google Group <https://groups.google.com/g/sirocco-users>`_.
+
 ---------------------------------------
 Documentation \& Publications
 ---------------------------------------
@@ -39,7 +41,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 <https://arxiv.org/abs/2410.19908>`_, submitted to MNRAS in October 2024
+* A `code release paper <https://arxiv.org/abs/2410.19908>`_, published in MNRAS in January 2025.
 * 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>`_, 
@@ -61,6 +63,9 @@ Knox Long
   Space Telescope Science Institute, 3700 San Martin Drive, Baltimore, MD 21218, USA
   Eureka Scientific, Inc., 2452 Delmer St., Suite 100, Oakland, CA 94602-3017, USA
 
+James Matthews
+  Department of Physics, Astrophysics, University of Oxford, Denys Wilkinson Building, Keble Road, Oxford, OX1 3RH, UK
+
 Christian Knigge
   Department of Physics and Astronomy, University of Southampton, Southampton, SO17 1BJ, UK
 
@@ -70,9 +75,6 @@ Stuart Sim
 Nick Higginbottom
   Department of Physics and Astronomy, University of Southampton, Southampton, SO17 1BJ, UK
 
-James Matthews
-  Department of Physics, Astrophysics, University of Oxford, Denys Wilkinson Building, Keble Road, Oxford, OX1 3RH, UK
-
 Sam Mangham
   Department of Physics and Astronomy, University of Southampton, Southampton, SO17 1BJ, UK
 
@@ -112,6 +114,7 @@ Amin Mosallanezhad
    examples
    physics
    atomic
+   speculate
    meta
    developer
    *
diff --git a/docs/sphinx/source/input/parameters.rst b/docs/sphinx/source/input/parameters.rst
@@ -17,7 +17,7 @@ A top-level parameter overview when initialising a .pf file. These parameters ar
    parameters/*
 
 Primary .pf Parameters
-********************
+***************************
 
 * :ref:`System_type`
 

diff --git a/...parameters/central_object/Central_object/Central_object.geometry_for_source.rst b/...parameters/central_object/Central_object/Central_object.geometry_for_source.rst
@@ -20,8 +20,13 @@ Values
     are re-generated.
 
   bubble
-    The central source radiates from random positions within a sphere of a given radius. 
-    This model generates isotropic photons.
+    The central source radiates from between two spheres, one with radius :ref:`Central_object.radius` 
+    and one with radius :ref:`Central_object.bubble_size`. The photon directions are individually isotropic but do not necessarily
+    create a truly isotropic source.
+
+  iso 
+    The central source radiates from the surface of a sphere with radius :ref:`Central_object.radius`.
+    Emission is truly isotropic, so photons are emitted in the same direction as the random point on the sphere surface where they are emitted.
 
 File
   `setup_star_bh.c <https://github.com/sirocco-rt/sirocco/blob/master/source/setup_star_bh.c>`_
@@ -35,4 +40,5 @@ Parent(s)
 
 Child(ren)
   * :ref:`Central_object.lamp_post_height`
+  * :ref:`Central_object.bubble_size`
 
diff --git a/docs/sphinx/source/input/parameters/other.rst b/docs/sphinx/source/input/parameters/other.rst
@@ -1,6 +1,6 @@
-#####
+#########################
 Others and Diagnostics
-#####
+#########################
 
 Possible parameter options linked to the advanced diagnostic tools and other adhoc options of the model. Some parameters may not be available depending on model selected.
 

diff --git a/docs/sphinx/source/input/parameters/other/Diag/Diag.keep_ioncycle_spectra.rst b/docs/sphinx/source/input/parameters/other/Diag/Diag.keep_ioncycle_spectra.rst
@@ -1,5 +1,5 @@
 Diag.keep_ioncycle_spectra
-================
+================================
 
 Decide whether or not to keep a copy of the log_spec_tot file after
 each spectral cycle in order to track the changes as the

diff --git a/...urce/input/parameters/other/Diag/Diag.use_upweighting_of_simple_macro_atoms.rst b/...urce/input/parameters/other/Diag/Diag.use_upweighting_of_simple_macro_atoms.rst
@@ -1,14 +1,5 @@
 Diag.use_upweighting_of_simple_macro_atoms
-<<<<<<< HEAD
-=====================================================================================
-Advanced command, allows one to turn on the "upweighting"
-scheme for simple ions in indivisible packet mode, as described under the 
-:ref:`Bound-free Continua of Simple Atoms` section. 
-
-Type
-  Boolean (yes/no)
-=======
-================
+===============================================
 
 Advanced command, allows one to use the “upweighting” scheme for simple ions in indivisible packet mode, as described under the :ref:`Bound-free Continua of Simple Atoms` section.
 
@@ -21,4 +12,3 @@ File
 Parent(s)
    * :ref:`Diag.extra`: ``True``
 
->>>>>>> xdoc
diff --git a/docs/sphinx/source/input/parameters/other/early_stopping.rst b/docs/sphinx/source/input/parameters/other/early_stopping.rst
@@ -0,0 +1,12 @@
+early_stopping
+==============
+Parameters controlling convergence-based early stopping of ionization cycles (accessed using the
+``-early_stopping`` flag, see :ref:`Running SIROCCO`). When enabled, sirocco monitors the
+convergence fraction across cycles and can terminate ionization early when both a stability
+criterion and a minimum convergence floor are satisfied. The parameters are prefixed with
+``@estop.`` in the parameter file.
+
+.. toctree::
+   :glob:
+
+   early_stopping/*