diff --git a/.gitignore b/.gitignore
index 07ea0fb4e..68c69a08b 100644
--- 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,6 +109,7 @@ source/templates.h.old
*.sig
*.out.pf
logfile
+*.wind_save
# IDE files
.idea/
@@ -112,3 +117,8 @@ logfile
py_progs/.idea/
scratch/
+
+# files from sed or other -e modifier
+*-e
+
+
diff --git a/README.md b/README.md
index c0f6fdbed..5e72822ef 100644
--- 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
new file mode 120000
index 000000000..988122696
--- /dev/null
+++ b/bin/Setup_Py_Dir
@@ -0,0 +1 @@
+Setup_Sirocco_Dir
\ No newline at end of file
diff --git a/docs/documentation_overview.html b/docs/documentation_overview.html
index b9635554d..0d527635a 100644
--- a/docs/documentation_overview.html
+++ b/docs/documentation_overview.html
@@ -32,6 +32,22 @@ Documentation Overview for Sirocco
tracked in git.
To generate the Sphinx documentation one needs sphinx
+ Because we use an package called PySi 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. In conda, one can create this with:
+
+ - conda create -n xsphinx python=3.1
+ - conda activate xsphinx
+ - cd docs/sphinx
+ - pip3 install -r requirements.txt
+
@@ -78,6 +94,7 @@ Documentation Overview for Sirocco
+
provides information about the source code.
- Like the other documentation, the Doxygen information is not
@@ -108,6 +125,7 @@
Documentation Overview for Sirocco
+
- To get the graphs that show which routines call which
diff --git a/docs/doxygen/sirocco_docs.config b/docs/doxygen/sirocco_docs.config
index 9ce3de33b..3fddebebc 100644
--- 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
index 13798c1ca..dea96e965 100644
--- 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
new file mode 100644
index 000000000..d1ca2ed34
--- /dev/null
+++ 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
new file mode 100644
index 000000000..91f8ae7f6
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/parameters/Ionization_cycles.convergence_tolerance.yaml b/docs/parameters/Ionization_cycles.convergence_tolerance.yaml
new file mode 100644
index 000000000..34bccf269
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/parameters/Ionization_cycles.min_cycles.yaml b/docs/parameters/Ionization_cycles.min_cycles.yaml
new file mode 100644
index 000000000..8d54d534a
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile
index 644de6c5f..e83f4927f 100644
--- 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
index 3158573ab..8a897c78e 100644
--- 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
\ No newline at end of file
diff --git a/docs/sphinx/requirements_nopysi.txt b/docs/sphinx/requirements_nopysi.txt
new file mode 100644
index 000000000..8d32556f8
--- /dev/null
+++ 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
index f868d1a13..d3ad8657f 100755
--- a/docs/sphinx/source/conf.py
+++ b/docs/sphinx/source/conf.py
@@ -79,7 +79,7 @@
# 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
@@ -87,9 +87,9 @@
# 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
index 4fcf4ac9d..c455f4bc9 100644
--- 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
new file mode 100644
index 000000000..e1c9aa60c
Binary files /dev/null and b/docs/sphinx/source/images/Speculate_logo5.png differ
diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst
index a06ebb8fa..c1c2e28a0 100644
--- a/docs/sphinx/source/index.rst
+++ b/docs/sphinx/source/index.rst
@@ -23,7 +23,7 @@ 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 `_, 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. `_
+sirocco-1.0, the version of the code in January 2025, is described by `Matthews, Long et al. `_
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 `_. Issues
@@ -31,6 +31,8 @@ regarding the code and suggestions for improvement should be reported there. We
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 `_.
+
---------------------------------------
Documentation \& Publications
---------------------------------------
@@ -39,7 +41,7 @@ Various documentation exists:
* A :doc:`Quick Guide ` 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 to MNRAS in October 2024
+* A `code release paper `_, 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 `_,
* Matthews, J. (2016): `Disc Winds Matter: Modelling Accretion And Outflow On All Scales `_,
@@ -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
index 58d3c74cd..25ecaceef 100644
--- 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/docs/sphinx/source/input/parameters/central_object/Central_object/Central_object.geometry_for_source.rst b/docs/sphinx/source/input/parameters/central_object/Central_object/Central_object.geometry_for_source.rst
index dfcc31a07..55a9885c8 100644
--- a/docs/sphinx/source/input/parameters/central_object/Central_object/Central_object.geometry_for_source.rst
+++ b/docs/sphinx/source/input/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 `_
@@ -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
index eb76afd06..6d25fe49f 100644
--- 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
index 742bd9106..7b13f4d4e 100644
--- 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/docs/sphinx/source/input/parameters/other/Diag/Diag.use_upweighting_of_simple_macro_atoms.rst b/docs/sphinx/source/input/parameters/other/Diag/Diag.use_upweighting_of_simple_macro_atoms.rst
index e91f3b903..50b863a65 100644
--- a/docs/sphinx/source/input/parameters/other/Diag/Diag.use_upweighting_of_simple_macro_atoms.rst
+++ b/docs/sphinx/source/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
new file mode 100644
index 000000000..8c0c8629e
--- /dev/null
+++ 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/*
diff --git a/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_fraction.rst b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_fraction.rst
new file mode 100644
index 000000000..0c0d8e331
--- /dev/null
+++ b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_fraction.rst
@@ -0,0 +1,21 @@
+@estop.Ionization_cycles.convergence_fraction
+===============================================
+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.
+
+Type
+ Double
+
+Values
+ 0 to 100
+
+Default
+ 80
+
+File
+ `setup.c `_
+
+Parent(s)
+ * ``-early_stopping`` switch
diff --git a/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_lookback.rst b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_lookback.rst
new file mode 100644
index 000000000..dbb24ed94
--- /dev/null
+++ b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_lookback.rst
@@ -0,0 +1,20 @@
+@estop.Ionization_cycles.convergence_lookback
+===============================================
+The number of consecutive cycles over which the convergence fraction must be stable
+(average absolute change less than the tolerance) before early stopping triggers.
+Larger values are more conservative.
+
+Type
+ Integer
+
+Values
+ 2 to 100
+
+Default
+ 5
+
+File
+ `setup.c `_
+
+Parent(s)
+ * ``-early_stopping`` switch
diff --git a/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_tolerance.rst b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_tolerance.rst
new file mode 100644
index 000000000..49d751dbc
--- /dev/null
+++ b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.convergence_tolerance.rst
@@ -0,0 +1,22 @@
+@estop.Ionization_cycles.convergence_tolerance
+================================================
+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
+:ref:`@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%.
+
+Type
+ Double
+
+Values
+ Greater than 0
+
+Default
+ 2
+
+File
+ `setup.c `_
+
+Parent(s)
+ * ``-early_stopping`` switch
diff --git a/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.min_cycles.rst b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.min_cycles.rst
new file mode 100644
index 000000000..9d8a73c13
--- /dev/null
+++ b/docs/sphinx/source/input/parameters/other/early_stopping/Ionization_cycles.min_cycles.rst
@@ -0,0 +1,19 @@
+@estop.Ionization_cycles.min_cycles
+=====================================
+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.
+
+Type
+ Integer
+
+Values
+ Greater than or equal to 0
+
+Default
+ 0
+
+File
+ `setup.c `_
+
+Parent(s)
+ * ``-early_stopping`` switch
diff --git a/docs/sphinx/source/input/parameters/other/monochromatic/monochromatic.wavelength.rst b/docs/sphinx/source/input/parameters/other/monochromatic/monochromatic.wavelength.rst
index 7dcb38c60..6e0f04643 100644
--- a/docs/sphinx/source/input/parameters/other/monochromatic/monochromatic.wavelength.rst
+++ b/docs/sphinx/source/input/parameters/other/monochromatic/monochromatic.wavelength.rst
@@ -1,5 +1,5 @@
monochromatic.wavelength
-================
+================================
Currently if affected by an issue on Github repo. Monochromatic.wavelength option not prompting. #1071. Be warned!
diff --git a/docs/sphinx/source/input/parameters/rt_ion/Matom_transition_mode.rst b/docs/sphinx/source/input/parameters/rt_ion/Matom_transition_mode.rst
index a5b2266b5..c38e83239 100644
--- a/docs/sphinx/source/input/parameters/rt_ion/Matom_transition_mode.rst
+++ b/docs/sphinx/source/input/parameters/rt_ion/Matom_transition_mode.rst
@@ -1,5 +1,5 @@
Matom_transition_mode
-================
+================================
This option allows the user to determine which mode to use for the macro-atom transition probabilities. The macro atom is not a single atom; it represents an ensemble of atoms of a particular type. The mc_jumps method is a stochastic treatment and the matrix method is a state machine. The default is set to mc_jumping. More information on macro atoms can be found in the :ref:`macro atoms` section. Be wary of using matrix mode due to the high memory requirements.
diff --git a/docs/sphinx/source/input/parameters/wind.rst b/docs/sphinx/source/input/parameters/wind.rst
index fad3af1b0..9507b5ed2 100644
--- a/docs/sphinx/source/input/parameters/wind.rst
+++ b/docs/sphinx/source/input/parameters/wind.rst
@@ -1,6 +1,6 @@
-####
+########
Winds
-####
+########
All possible parameter options for a selection of different wind models. Some parameters may not be available depending on the model and options selected. Descriptions of the wind models can be found in the :ref:`wind models` and :ref:`wind model parameters` sections.
diff --git a/docs/sphinx/source/input/parameters/wind/SV/SV.diskmax.rst b/docs/sphinx/source/input/parameters/wind/SV/SV.diskmax.rst
index b61b5a22e..e9b012cdd 100644
--- a/docs/sphinx/source/input/parameters/wind/SV/SV.diskmax.rst
+++ b/docs/sphinx/source/input/parameters/wind/SV/SV.diskmax.rst
@@ -9,7 +9,7 @@ Type
Double
Unit
- cm
+ This entry is in units of the radious of the central object.
Values
Greater than or equal to :ref:`sv.diskmin` (inner radius disk wind)
diff --git a/docs/sphinx/source/input/parameters/wind/SV/SV.diskmin.rst b/docs/sphinx/source/input/parameters/wind/SV/SV.diskmin.rst
index bdaa9d206..91aa97688 100644
--- a/docs/sphinx/source/input/parameters/wind/SV/SV.diskmin.rst
+++ b/docs/sphinx/source/input/parameters/wind/SV/SV.diskmin.rst
@@ -9,7 +9,7 @@ Type
Double
Unit
- cm
+ This entry has units that are multiples of the central object radius
Values
Greater than or equal to :ref:`Central_object.radius`
diff --git a/docs/sphinx/source/input/parameters/wind/Wind/Wind.ionization.rst b/docs/sphinx/source/input/parameters/wind/Wind/Wind.ionization.rst
index 4db3ac068..b6b51471d 100644
--- a/docs/sphinx/source/input/parameters/wind/Wind/Wind.ionization.rst
+++ b/docs/sphinx/source/input/parameters/wind/Wind/Wind.ionization.rst
@@ -9,20 +9,52 @@ Type
Values
on.the.spot
- Use a simple on the spot approximation to calculated the ionization.
+ Use a simple on-the-spot approximation to calculate the ionization.
LTE_te
Calculate ionization based on the Saha equation using
- the electron temperature. (This is intended as a diagnostic
- mode.)
+ the electron temperature. The electron temperature is not
+ iterated; it remains at the value set during initialization
+ (from Wind.t.init, or from the imported model for hydro winds).
+ (This is intended as a diagnostic mode.)
LTE_tr
Calculate ionization based on the Saha equation using
- the radiation temperature. (This is intended as a diagnstic mode)
+ the radiation temperature. Unlike LTE_te, the radiation
+ temperature is updated each cycle from the mean frequency
+ of the radiation field estimated during photon transport,
+ so the ionization evolves as the radiation field converges.
+ The electron temperature is not iterated.
+ (This is intended as a diagnostic mode.)
+
+ LTE_iterate
+ Calculate ionization using the Saha equation at the electron temperature,
+ with the electron temperature determined by balancing heating and cooling.
+ Both ion populations and partition functions are calculated in LTE.
+ Unlike other modes, here, both the heating and cooling are changed as part
+ of the iteration proces. At each trial temperature, the Saha equation
+ is solved to update ion densities, and the heating is scaled to
+ reflect the new densities. Specifically, the routine scales heated recorded
+ during photon transfer by the ratio of the original ion density for each cycle
+ to the trial densites for photoionization and Auger heating. Similarly,
+ for free free, Compton and line heating are scaled by the electron density.
+ This approach is more self-conistent than modifying only the cooling.
+ As is the case for other most modes, changes are dampted with results from the
+ previous ionization cycle to prevent changes from being too large between ionization
+ cycles. This mode is intended for situations where LTE ionization is
+ physically appropriate and one wants to determine the electron temperature
+ self-consistently.
ML93
- Use the modified on the spot approimation described by
- `Mazzli & Lucy 1993 `_
+ Use the modified on-the-spot approximation described by
+ `Mazzali & Lucy 1993 `_.
+ At each ionization cycle, the electron temperature is set to
+ t_e = 0.9 * t_r. Ionization fractions are first computed using
+ the Saha equation at t_r, then corrected using the Lucy-Mazzali
+ estimators which account for the dilute, non-Planckian radiation field.
+ The partition functions are evaluated using the dilution factor W.
+ This mode does not attempt to balance heating and cooling to determine
+ t_e self-consistently.
fixed
Read the ion aboundances in from a file. All cells will have
@@ -49,6 +81,16 @@ Values
through a cell. There is no attempt to model the spectrum. Invert the rate matrix equation to
calculate the ionization.
+ matrix_multi
+ Similar to matrix_pow, except in this case a more aggessive approach to reaching
+ ion state/temperature balance is attempted. With matrix_pow and the various other
+ matrix methods, a single attempt is made to balance heating and cooling and then
+ a new ionization state is calculate based on the derived electron temperature. With
+ this method, an interation is performed, with this process being carried out multiple
+ times. Currently number of iterations is fixed and set by the parameter NEBULARMODE_MATRIX_MULTISHOT
+ which can be found in sirrocco.h. This mode was developed to accelerate convergence in
+ dense plasmas, but is still regarded as somewhat experimental as of 2025 Sept.
+
File
`setup.c `_
diff --git a/docs/sphinx/source/input/parameters/wind/Wind/Wind.type.rst b/docs/sphinx/source/input/parameters/wind/Wind/Wind.type.rst
index e44a28912..f6223545d 100644
--- a/docs/sphinx/source/input/parameters/wind/Wind/Wind.type.rst
+++ b/docs/sphinx/source/input/parameters/wind/Wind/Wind.type.rst
@@ -20,7 +20,7 @@ Values
A special purpose mode used by the sirocco.collaboration for importing models from Zeus and Pluto. (Depreciated) (:ref:`Hydro`)
imported
- A general purpose mode for importing a wind from an ascii file (see also :doc:`SIROCCO Script documentation <../wind_models/importing_models>`).
+ A general purpose mode for importing a wind from an ascii file (see also :doc:`Importing Models `).
kwd
The Knigge-Woods-Drew parameterization of a bi-conical flow. (:ref:`KWD`)
diff --git a/docs/sphinx/source/input/system_description.rst b/docs/sphinx/source/input/system_description.rst
index 6ebeb8971..406e2fffd 100644
--- a/docs/sphinx/source/input/system_description.rst
+++ b/docs/sphinx/source/input/system_description.rst
@@ -26,7 +26,7 @@ The first set of parameters which SIROCCO needs are information about the overal
Central_object.rad_type_to_make_wind(bb,models,power,cloudy,brems,mono) power
Central_object.luminosity(ergs/s) 4.72063e+37
Central_object.power_law_index -1.5
- Central_object.geometry_for_source(sphere,lamp_post,bubble) sphere
+ Central_object.geometry_for_source(sphere,lamp_post,bubble,iso) sphere
:ref:`System_type` is starting point, a basic classification of the type of object one is trying to model.
This is used to guide further questions about the object and to set defaults.
diff --git a/docs/sphinx/source/installation.rst b/docs/sphinx/source/installation.rst
index 870d7d0b0..5e7a75451 100644
--- a/docs/sphinx/source/installation.rst
+++ b/docs/sphinx/source/installation.rst
@@ -63,7 +63,7 @@ Instead, one can pull in changes, or make changes yourself, and recompile the so
which will compile the main program. The program plus full set of auxiliary programs (such as windsave2table and py_wind, see below) can be compiled using :code:`make all`.
Running SIROCCO
-==============
+====================
To run SIROCCO you need to add the following to your $PATH variable:
@@ -103,7 +103,7 @@ where -np followed by a number designates the number of threads assigned.
Auxiliary programs
-------------------
+--------------------------
There are two programs that are useful for extracting information about models
@@ -120,7 +120,7 @@ The two files are run as follows
Brief descriptions of command line options for running these routines can obtained using a -h switch
SIROCCO scripts
---------------
+----------------------
There are a number of python scripts that can be used to plot results
from a SIROCCO run. These are not particularly well documented and many have been developed
diff --git a/docs/sphinx/source/meta.rst b/docs/sphinx/source/meta.rst
index b24a3f292..25ef9b373 100644
--- a/docs/sphinx/source/meta.rst
+++ b/docs/sphinx/source/meta.rst
@@ -2,7 +2,7 @@ Meta-documentation
##################
How to document SIROCCO
-======================
+=================================
This documentation is written in **ReStructured Text**, and parsed by **Sphinx**.
A general guide to **ReStructured Text** can be found `here `_.
@@ -20,7 +20,33 @@ We require the **Python 3** version of **Sphinx**. Install it, and the other mod
cd docs/sphinx
pip3 install -r requirements.txt
-Building the documentation
+If you use conda/minconda or a similar environment management tool, we recommend you create a new enviroment
+for compoling the sphinx documentation. This is because there are some version dependences (which are probably a little strict)
+in the package `pysi `_ which is used in some of the Jupyter scripts.
+
+An example that is known to work, if you are in the sphinx directory:
+
+.. code :: bash
+
+ conda create -n xsphinx python=3.10
+ conda activate xsphinx
+ pip3 install -r requirements.txt
+
+or similar, with a virtual env that is not conda-based:
+
+.. code :: bash
+
+ python3 -m venv xsphinx
+ source xsphinx/bin/activate
+ pip3 install -r requirements.txt
+
+Alternatively, you can install pysi separately (for example, downloading from github yourself and installing it with pip.
+A version of the requirements.txt file without pysi is provided as ``requirements_nopysi.txt``.
+
+In the absence of installing this package, you can still edit and recompile the sphinx documentation, but
+you will see errors associated with this missing package. This should not prevent you from improving other
+parts of the documentation. A version of the requirements.txt file without pysi is provided as ``requirements_nopysi.txt``.
+
--------------------------
Once **Sphinx** is installed, you can make the documentation using a **Makefile** as:
@@ -29,6 +55,8 @@ Once **Sphinx** is installed, you can make the documentation using a **Makefile*
make html
+
+
You can tell if the documentation was built successfully by looking at the output of ``make html``.
You should see:
@@ -51,6 +79,15 @@ Do this via:
make clean
make html
+Alternatively, you can use ``sphinx-autobuild`` to automatically rebuild the documentation when changes are detected.
+To do this run:
+
+.. code :: bash
+
+ make livehtml
+
+This will start a local server (usually at http://127.0.0.1:8000) where you can view the documentation.
+
General documentation
=====================
diff --git a/docs/sphinx/source/plotting.rst b/docs/sphinx/source/plotting.rst
index 631b1d1ef..331a9f446 100644
--- a/docs/sphinx/source/plotting.rst
+++ b/docs/sphinx/source/plotting.rst
@@ -1,4 +1,4 @@
-Plotting \& Processing Outputs
+Tutorials \& Plotting
#####################################
SIROCCO produces a large number of files in both binary and ascii format. Tools exist to examine the binary files.
@@ -8,14 +8,30 @@ PySi
PySi, short for PySIROCCO, is a python package designed to interface with the SIROCCO code.
It can be installed from its `own Github repository `_
under the sirocco-rt organisation. We recommend installing this package for reading code outputs.:
-isntructions to do so can be found in the README of that repository.
+instructions to do so can be found in the README of that repository.
+
+The API documentation for PySi can be found :doc:`here `.
+
+PySi can also be used from the command line. For example, the command
+
+.. code-block:: bash
+
+ pysi plot spectrum observer [model_name]
+
+will allow you to plot a spectrum, whereas
+
+.. code-block:: bash
+
+ pysi plot wind property [model_name] [variable]
+
+will allow you to plot the wind property specified by [variable]. For more flexibility, see the tutorials.
.. admonition :: Warning to users!
-These tutorials are not complete, and our approach to interfacing
-with the code has not been uniform across the collaboration. Nevertheless, these
-tutorials should give you the basic tools needed to look at spectra and wind properties,
-with more detail on python scripts and packages provided in :ref:`the API documentation `.
+ These tutorials are not complete, and our approach to interfacing
+ with the code has not been uniform across the collaboration. Nevertheless, these
+ tutorials should give you the basic tools needed to look at spectra and wind properties,
+ with more detail on python scripts and packages provided in :doc:`the API documentation