doc/RTD-Legacy/Motivation/index.rst

-.. _GettingStarted:
-
-What is the Motivation for SWIFT?
-=================================
-
-SWIFT is designing with parallelism from the very start. It is a bottom up approach with a task based 
-parallel infrastructure at it's very core. 
-
-.. toctree::
-   :maxdepth: 1

doc/RTD-Legacy/Physics/Gravity/gravity.rst

-.. _SWIFTGravity:
-
-Gravity
-=============================
-
-SWIFT implements the calculation of gravitational forces using a version of TreePM. 
-Matthieu - can you update this part? I know you have implemented a Multipole method here 
-with some SWIFT specific modifications. Could you write a brief overview of the idea?
-
-.. toctree::
-   :maxdepth: 1

doc/RTD-Legacy/Physics/SPH/sph.rst

-.. _SWIFTSPH:
-
-Smooth Particle Hydrodynamics
-=============================
-
-SWIFT simulates the universe using SPH. 
- 
-.. toctree::
-   :maxdepth: 1

doc/RTD-Legacy/Physics/index.rst

-.. _SWIFTPhysics:
-
-What Physics does SWIFT Simulate?
-=================================
-
-
-.. toctree::
-   :maxdepth: 1
-
-   SPH/sph.rst
-   Gravity/gravity.rst

doc/RTD-Legacy/conf.py

-# -*- coding: utf-8 -*-
-#
-# SWIFT documentation build configuration file, created by
-# sphinx-quickstart on Thu Nov  5 15:57:05 2015.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys, os
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration -----------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'SWIFT'
-copyright = u'2015: John Regan, James Willis, Stefan Arridge, Matthieu Schaller'
-
-# 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'
-# The full version, including alpha/beta/rc tags.
-release = '0.1'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'default'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'SWIFTdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'SWIFT.tex', u'SWIFT Documentation',
-   u'John Regan, James Willis, Stefan Arridge, Matthieu Schaller', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    ('index', 'swift', u'SWIFT Documentation',
-     [u'John Regan, James Willis, Stefan Arridge, Matthieu Schaller'], 1)
-]
-
-# If true, show URL addresses after external links.
-#man_show_urls = False
-
-
-# -- Options for Texinfo output ------------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-  ('index', 'SWIFT', u'SWIFT Documentation',
-   u'John Regan, James Willis, Stefan Arridge, Matthieu Schaller', 'SWIFT', 'One line description of project.',
-   'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False

doc/RTD-Legacy/index.rst

-.. SWIFT documentation master file, created by
-   sphinx-quickstart on Thu Nov  5 15:57:05 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to SWIFT's documentation!
-=================================
-
-This is the first go at writing some high level documentation for SWIFT. 
-It will be augmented and linked with the already available documentation.
-Contents:
-
-
-.. toctree::
-   :maxdepth: 2
-
-   Motivation/index.rst
-   Innovation/index.rst
-   Physics/index.rst
-   DeveloperGuide/developerguide.rst
-   FAQ/index.rst
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/RTD/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = SWIFTSPHWIthFine-grainedinter-dependentTasking
+SPHINXPROJ    = SWIFT-documentation
 SOURCEDIR     = source
 BUILDDIR      = build
 
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/RTD/README.md

 SWIFT Documentation
 ===================
 
-This is the main documentation for SWIFT that can be found on ReadTheDocs.
+This is the main documentation for SWIFT that can be found on ReadTheDocs
+or at `swiftsim.com/docs`.
 
 You will need the `sphinx` and `sphinx-autobuild` python packages (pip install
 them!) to build the documentation to html, as well as the `sphinx_rtd_theme`
 package which is used as the theme.
 
-To build the documentation, `make html` and then it is available in
-`build/html`.
+To build the documentation (from this directory), `make html` and the output
+files will be created in `build/html/`.
 
-Please consider adding documentation when you add code!
+To build the latex manual (from this directory), `make latexpdf` and the output
+files will be `build/latex/SWIFT-user-manual.pdf`.
 
 
+Please consider adding documentation when you add code!

doc/RTD/source/CSDS/index.rst

+Continuous Simulation Data Stream (CSDS)
+========================================
+
+The CSDS is a particle based output (e.g. snapshot) that takes into account the large difference of timescale.
+If you have any questions, a slack channel is available for it in SWIFT's slack.
+
+To run it, you will need to use the configuration option ``--enable-csds`` and the run time argument ``--csds``.
+Currently the CSDS is implemented only for GEAR, Gadget2 and the default modules, but can be easily extended to the other schemes by adding the CSDS structure to the particles and implementing the IO functions (see ``src/hydro/Gadget2/hydro_part.h``, ``src/hydro/Gadget2/hydro_csds.c`` and ``src/hydro/Gadget2/hydro_csds.h``).
+The main parameters of the CSDS are ``CSDS:delta_step`` and ``CSDS:index_mem_frac`` that define the time accuracy of the CSDS and the number of index files.
+The first parameter defines the number of active steps that a particle is doing before writing and the second defines the total storage size of the index files as a fraction of the dump file.
+
+For reading, the python wrapper is available through the configuration option ``--with-python``.
+I recommend running the SedovBlast_3D with the CSDS and then using the example ``csds/examples/reader_example.py``.
+This file is kept up to date with the most recent changes and includes a call to all the existing functions.
+If you need some extra information, a doc string is provided for the class ``csds.Reader`` and all its methods.
+
+If you wish to obtain a snapshot from the CSDS, a script is available in ``csds/examples/create_snapshot.py``.

doc/RTD/source/CitingSWIFT/index.rst

+.. Citing SWIFT
+   Matthieu Schaller, 5th April 2020
+
+Disclaimer, Citing SWIFT & Giving Credit
+========================================
+
+First of all, thank you for using SWIFT for your projects!
+
+Licensing
+~~~~~~~~~
+
+SWIFT is licensed under the LGPL version 3.0. A copy of the license is provided
+in the file ``COPYING`` at the root of the repository. It can also be found
+online `here <https://www.gnu.org/licenses/lgpl-3.0-standalone.html>`_ as an
+extension to the `GPL <https://www.gnu.org/licenses/gpl-3.0-standalone.html>`_.
+
+.. figure:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
+    :width: 100px
+    :alt: LGPL v3.0 logo
+
+Disclaimer
+~~~~~~~~~~
+
+We would like to emphasise that SWIFT comes without any warranty of accuracy,
+correctness or efficiency. As mentioned in the license, the software comes
+`as-is` and the onus is on the user to get meaningful results. Whilst the
+authors will endeavour to answer questions related to using the code, we
+recommend users build and maintain their own copies. This documentation contains
+the most basic information to get started. Reading it and possibly also the
+source code is the best way to start running simulations.
+
+The users are responsible to understand what the code is doing and for the
+results of their simulation runs.
+
+Note also that the values of the parameters given in the examples are only
+indicative. We recommend users experiment by themselves and a campaign of
+experimentation with various values is highly encouraged. Each problem will
+likely require different values and the sensitivity to the details of the
+physical model is something left to the users to explore.
+
+Acknowledgment & Citation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SWIFT code was last described in this `publication
+<https://ui.adsabs.harvard.edu/abs/2023arXiv230513380S/abstract>`_, which
+introduced the core solver, the numerical methods used as well as many
+extensions. We ask users running SWIFT for their research to please cite this
+paper when they present their results. This paper is best referenced by the
+following bibtex citation block:
+
+.. code-block:: bibtex
+
+  @ARTICLE{2023arXiv230513380S,
+    author = {{Schaller}, Matthieu and others},
+    title = "{SWIFT: A modern highly-parallel gravity and smoothed particle hydrodynamics solver for astrophysical and cosmological applications}",
+    journal = {\mnras},
+    keywords = {software: simulations, methods: numerical, software: public release, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics, Astrophysics - Earth and Planetary Astrophysics, Astrophysics - Astrophysics of Galaxies, Computer Science - Distributed, Parallel, and Cluster Computing},
+    year = 2024,
+    month = may,
+    volume = {530},
+    number = {2},
+    pages = {2378-2419},
+    doi = {10.1093/mnras/stae922},
+    archivePrefix = {arXiv},
+    eprint = {2305.13380},
+    primaryClass = {astro-ph.IM},
+    adsurl = {https://ui.adsabs.harvard.edu/abs/2024MNRAS.530.2378S},
+    adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+  }
+
+
+In order to keep track of usage and measure the impact of the software, we
+kindly ask users publishing scientific results using SWIFT to add the following
+sentence to the acknowledgment section of their papers:
+
+.. code-block:: text
+		
+   The research in this paper made use of the SWIFT open-source simulation code
+   (http://www.swiftsim.com, Schaller et al. 2018) version X.Y.Z.
+   
+with the version number set to the version used for the simulations and the
+reference pointing to the `ASCL entry <https://ascl.net/1805.020>`_ of the
+code. This corresponds to the following bibtex citation block:
+
+.. code-block:: bibtex
+
+   @MISC{2018ascl.soft05020S,
+     author = {{Schaller}, Matthieu and others},
+     title = "{SWIFT: SPH With Inter-dependent Fine-grained Tasking}",
+     keywords = {Software },
+     howpublished = {Astrophysics Source Code Library},
+     year = 2018,
+     month = may,
+     eid = {ascl:1805.020},
+     pages = {ascl:1805.020},
+     archivePrefix = {ascl},
+     eprint = {1805.020},
+     adsurl = {https://ui.adsabs.harvard.edu/abs/2018ascl.soft05020S},
+     adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+   }
+
+When using models or parts of the code whose details were introduced in other
+papers, we kindly ask that the relevant work is properly acknowledge and
+cited. This includes the :ref:`subgrid`, the :ref:`planetary` extensions, the
+:ref:`hydro` and :ref:`rt`, or the particle-based :ref:`neutrinos`.

doc/RTD/source/CommandLineOptions/index.rst

@@ -11,7 +11,10 @@ For instance, just running the ``swift`` binary will not use any SPH or gravity;
 the particles will just sit still!
 
 Below is a list of the command line options and when they should be used. The same list
-can be found by typing ``./swift -h``::
+can be found by typing ``./swift -h``:
+
+.. code-block:: none
+
 
     -h, --help                        show this help message and exit
 
@@ -19,26 +22,57 @@ can be found by typing ``./swift -h``::
 
     -b, --feedback                    Run with stars feedback.
     -c, --cosmology                   Run with cosmological time integration.
-    --temperature                     Run with temperature calculation. 
+    --temperature                     Run with temperature calculation.
     -C, --cooling                     Run with cooling (also switches on --temperature).
     -D, --drift-all                   Always drift all particles even the ones
                                       far from active particles. This emulates
                                       Gadget-[23] and GIZMO's default behaviours.
-    -F, --star-formation	      Run with star formation.
+    -F, --star-formation              Run with star formation.
     -g, --external-gravity            Run with an external gravitational potential.
     -G, --self-gravity                Run with self-gravity.
     -M, --multipole-reconstruction    Reconstruct the multipoles every time-step.
     -s, --hydro                       Run with hydrodynamics.
     -S, --stars                       Run with stars.
     -B, --black-holes                 Run with black holes.
+    -k, --sinks                       Run with sink particles.
     -u, --fof                         Run Friends-of-Friends algorithm to
                                       perform black hole seeding.
+    --lightcone                       Generate lightcone outputs.
     -x, --velociraptor                Run with structure finding.
+    --line-of-sight                   Run with line-of-sight outputs.
     --limiter                         Run with time-step limiter.
+    --sync                            Run with time-step synchronization
+                                      of particles hit by feedback events.
+    --csds                            Run with the Continuous Simulation Data
+                                      Stream (CSDS).
+    -R, --radiation                   Run with radiative transfer.
+    --power                           Run with power spectrum outputs.
+
+  Simulation meta-options:
+
+    --quick-lyman-alpha               Run with all the options needed for the
+                                      quick Lyman-alpha model. This is equivalent
+                                      to --hydro --self-gravity --stars --star-formation
+                                      --cooling.
+    --eagle                           Run with all the options needed for the
+                                      EAGLE model. This is equivalent to --hydro
+                                      --limiter --sync --self-gravity --stars
+                                      --star-formation --cooling --feedback
+                                      --black-holes --fof.
+    --gear                            Run with all the options needed for the
+                                      GEAR model. This is equivalent to --hydro
+                                      --limiter --sync --self-gravity --stars
+                                      --star-formation --cooling --feedback.
+    --agora                           Run with all the options needed for the
+                                      AGORA model. This is equivalent to --hydro
+                                      --limiter --sync --self-gravity --stars
+                                      --star-formation --cooling --feedback.
 
   Control options:
 
     -a, --pin                         Pin runners using processor affinity.
+    --nointerleave                    Do not interleave memory allocations across
+                                      NUMA regions.
     -d, --dry-run                     Dry run. Read the parameter file, allocates
                                       memory but does not read the particles
                                       from ICs. Exits before the start of time
@@ -58,12 +92,24 @@ can be found by typing ``./swift -h``::
                                       read from the parameter file. Can be used
                                       more than once {sec:par:value}.
     -r, --restart                     Continue using restart files.
-    -t, --threads=<int>               The number of threads to use on each MPI
-                                      rank. Defaults to 1 if not specified.
+    -t, --threads=<int>               The number of task threads to use on each
+                                      MPI rank. Defaults to 1 if not specified.
+    --pool-threads=<int>              The number of threads to use on each MPI
+                                      rank for the threadpool operations.
+                                      Defaults to the numbers of task threads
+                                      if not specified.
     -T, --timers=<int>                Print timers every time-step.
     -v, --verbose=<int>               Run in verbose mode, in MPI mode 2 outputs
                                       from all ranks.
-    -y, --task-dumps=<int>            Time-step frequency at which task analysis
-                                      files and/or tasks are dumped.
+    -y, --task-dumps=<int>            Time-step frequency at which task graphs
+                                      are dumped.
+    --cell-dumps=<int>                Time-step frequency at which cell graphs
+                                      are dumped.
     -Y, --threadpool-dumps=<int>      Time-step frequency at which threadpool
                                       tasks are dumped.
+    --dump-tasks-threshold=<flt>      Fraction of the total step's time spent
+                                      in a task to trigger a dump of the task plot
+                                      on this step
+
+See the file examples/parameter_example.yml for an example of parameter file.
+