doc/RTD/source/TimeStepping/timestep_synchronization.rst

@@ -5,3 +5,22 @@
    
 Time-step synchronization
 =========================
+
+Enabled with command-line option ``--sync``.
+
+We also implement a synchronization step to change the time-step 
+of particles that have been directly affected by external source 
+terms, typically feedback events. Durier & Dalla Vecchia (2012) 
+showed that the Saitoh & Makino (2009) mechanism was not sufficient 
+in scenarios where particles receive energy in the middle of their 
+regular time-step. When particles are affected by feedback (see 
+Sections 8.1, 8.2, and 8.3 of Schaller et al. (2024), MNRAS 530:2), 
+we flag them for synchronization. A final pass over the particles, 
+implemented as a task acting on any cell which was drifted to the 
+current time, takes these flagged particles, interrupts their current 
+step to terminate it at the current time and forces them back onto 
+the timeline (Section 2.4, ibid) at the current step. They then recompute 
+their time-step and get integrated forward in time as if they were 
+on a short time-step all along. This guarantees a correct propagation 
+of energy and hence an efficient implementation of feedback. The use 
+of this mechanism is always recommended in simulations with external source terms.

doc/RTD/source/VELOCIraptorInterface/stfwithswift.rst

@@ -5,13 +5,13 @@
 Configuring SWIFT with VELOCIraptor
 ===================================
 
-.. toctree::    
-   :maxdepth: 2    
-   :hidden:    
+.. toctree::
+   :maxdepth: 2
+   :hidden:
    :caption: Contents:
 
 In the following three paragraphs we will explain how to setup VELOCIraptor,
-how to compile it and how to compile SWIFT with VELOCIraptor. 
+how to compile it and how to compile SWIFT with VELOCIraptor.
 
 
 Setting up VELOCIraptor
@@ -25,15 +25,15 @@ VELOCIraptor. This can be done by cloning the repository on GitHub::
 The SWIFT interface is in the master branch of VELOCIraptor so nothing is more
 is needed besides fetching the latest version of the `NBodyLib` that the code
 relies upon::
-  
-  cd VELOCIraptor-STF 
+
+  cd VELOCIraptor-STF
   git submodule update --init --recursive
 
 To get VELOCIraptor working with SWIFT simply use::
 
   mkdir build
   cd build
-  cmake ../ -DVR_USE_HYDRO=ON -DVR_USE_SWIFT_INTERFACE=ON -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_BUILD_TYPE=Release 
+  cmake ../ -DVR_USE_HYDRO=ON -DVR_USE_SWIFT_INTERFACE=ON -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_BUILD_TYPE=Release
 
 The first parameter activates the processing of gas, stars and black holes. It
 can be omitted for simulations evolving only dark matter.
@@ -59,32 +59,50 @@ The next part is compiling SWIFT with VELOCIraptor and assumes you already
 downloaded SWIFT from the GitLab repository. This can be done by running
 
 .. code:: bash
-  
-  ./autogen.sh 
-  ./configure --with-velociraptor=/path/to/VELOCIraptor-STF/src 
-  make 
+
+  ./autogen.sh
+  ./configure --with-velociraptor=/path/to/VELOCIraptor-STF/build/src
+  make
 
 In which ``./autogen.sh`` only needs to be run once after the code is cloned
 from the GitLab_, and ``/path/to/`` is the path to the ``VELOCIraptor-STF``
-directory on your machine. In general ``./configure`` can be run with other
-options as desired. After this we can run SWIFT with VELOCIraptor, but for this
-we first need to add several lines to the yaml file of our simulation
+directory on your machine. Note that this path must be absolute (i.e. relative
+to ``/``, if you want to run the MPI version of VELOCIraptor as well as a
+non-MPI one with the same version of SWIFT, then you will need to compile
+VELOCIraptor twice and create two builds, then use the
+``--with-velociraptor-mpi`` configure option to point to the MPI build and the
+``--with-velociraptor`` option to point at the non-MPI build.
+In general ``./configure`` can be run with other options as desired.
+
+If you see reports about missing references to ``MPI::Comm`` and
+similar functions, then you will also need to include the C++ version
+of the MPI library in ``LIBS`` variable as part of the configuration
+(or by setting the ``LIBS`` environment variable), as in:
+
+.. code:: bash
+
+  ./configure --with-velociraptor=/path/to/VELOCIraptor-STF/build/src LIBS=-lmpi++
+
+other names and libraries may be necessary as these are MPI flavour determined.
+
+After this we can run SWIFT with VELOCIraptor, but for this we first need to
+add several lines to the yaml file of our simulation
+
 
-    
 .. code:: YAML
 
-   StructureFinding:      
+   StructureFinding:
      config_file_name:     vrconfig_3dfof_subhalos_SO_hydro.cfg
      basename:             haloes
      scale_factor_first:   0.02
      delta_time:           1.02
 
-In which we specify the ``.cfg`` file that is used by VELOCIraptor and the 
-other parameters which SWIFT needs to use. In the case of 
+In which we specify the ``.cfg`` file that is used by VELOCIraptor and the
+other parameters which SWIFT needs to use. In the case of
 the Small Cosmological Volume DMO example we can run a simulation with halo
 finder as::
 
-  cd examples/SmallCosmoVolume_DM 
+  cd examples/SmallCosmoVolume_DM
   ../swift --cosmology --hydro --self-gravity --velociraptor --threads=8 small_cosmo_volume_dm.yml
 
 Which activates the VELOCIraptor interface.

doc/RTD/source/conf.py

@@ -18,15 +18,29 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'SWIFT: SPH With Inter-dependent Fine-grained Tasking'
-copyright = '2014-2020, SWIFT Collaboration'
-author = 'SWIFT Team'
+project = "SWIFT: SPH With Inter-dependent Fine-grained Tasking"
+copyright = "2014-2023, SWIFT Collaboration"
+author = "SWIFT Team"
 
 # The short X.Y version
-version = '0.9'
+version = "2025.04"
 # The full version, including alpha/beta/rc tags
-release = '0.9.0'
-
+release = "2025.04"
+
+# -- Find additional scripts to run as part of the documentation build -------
+import glob
+import os
+import subprocess
+
+additional_scripts = glob.glob("**/*.py", recursive=True)
+# remove this script
+additional_scripts.remove("conf.py")
+for additional_script in additional_scripts:
+    wdir, script = os.path.split(additional_script)
+    print(f"Running {additional_script}...")
+    status = subprocess.run(f"python3 {script}", shell=True, cwd=wdir)
+    if not status.returncode == 0:
+        raise RuntimeError(f"Could not run script!")
 
 # -- General configuration ---------------------------------------------------
 
@@ -38,34 +52,32 @@ release = '0.9.0'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.todo',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.graphviz'
+    "sphinx.ext.todo",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.graphviz",
 ]
 
-graphviz_dot_args=[
-    "-Grankdir=LR"
-]
+graphviz_dot_args = ["-Grankdir=LR"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = [".templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -73,7 +85,7 @@ language = None
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -81,7 +93,7 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # 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
@@ -108,7 +120,7 @@ html_theme = 'sphinx_rtd_theme'
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'SWIFTSPHWIthFine-grainedinter-dependentTaskingdoc'
+htmlhelp_basename = "SWIFTSPHWIthFine-grainedinter-dependentTaskingdoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -116,16 +128,13 @@ htmlhelp_basename = 'SWIFTSPHWIthFine-grainedinter-dependentTaskingdoc'
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
-    # 'papersize': 'letterpaper',
-
+    "papersize": "a4paper",
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -135,8 +144,13 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'SWIFTSPHWIthFine-grainedinter-dependentTasking.tex', 'SWIFT: SPH WIth Fine-grained inter-dependent Tasking Documentation',
-     'Josh Borrow', 'manual'),
+    (
+        master_doc,
+        "SWIFT-user-manual.tex",
+        "SWIFT user & developer documentation",
+        "SWIFT Collaboration",
+        "manual",
+    )
 ]
 
 
@@ -145,8 +159,13 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'swiftsphwithfine-grainedinter-dependenttasking', 'SWIFT: SPH WIth Fine-grained inter-dependent Tasking Documentation',
-     [author], 1)
+    (
+        master_doc,
+        "swiftsphwithfine-grainedinter-dependenttasking",
+        "SWIFT: SPH WIth Fine-grained inter-dependent Tasking Documentation",
+        [author],
+        1,
+    )
 ]
 
 
@@ -156,9 +175,15 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'SWIFTSPHWIthFine-grainedinter-dependentTasking', 'SWIFT: SPH WIth Fine-grained inter-dependent Tasking Documentation',
-     author, 'SWIFTSPHWIthFine-grainedinter-dependentTasking', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "SWIFTSPHWIthFine-grainedinter-dependentTasking",
+        "SWIFT: SPH WIth Fine-grained inter-dependent Tasking Documentation",
+        author,
+        "SWIFTSPHWIthFine-grainedinter-dependentTasking",
+        "One line description of project.",
+        "Miscellaneous",
+    )
 ]
 
 

doc/RTD/source/index.rst

@@ -7,9 +7,22 @@ Welcome to SWIFT: SPH With Inter-dependent Fine-grained Tasking's documentation!
 ================================================================================
 
 Want to get started using SWIFT? Check out the on-boarding guide available
-here. SWIFT can be used as a drop-in replacement for Gadget-2 and initial
-conditions in hdf5 format for Gadget can directly be read by SWIFT. The only
-difference is the parameter file that will need to be adapted for SWIFT.
+`here <https://swift.strw.leidenuniv.nl/onboarding.pdf>`_.
+
+.. figure:: CitingSWIFT/SWIFT_logo.png
+    :width: 300px
+    :align: center
+    :alt: SWIFT logo
+
+SWIFT is an open-source cosmological and astrophysical numerical
+solver designed to run efficiently on modern hardware. A comprehensive
+and extensive set of models for galaxy formation as well as planetary
+physics are provided alongside a large series of examples.
+
+This users' and developers' documentation is best enjoyed with a glass
+of Amarone and Rachmaninoff's second piano concerto in the
+background. We note that good results have also been reported using a
+tumbler of 16yrs old Lagavulin.
 
 .. toctree::
    :maxdepth: 2
@@ -27,10 +40,13 @@ difference is the parameter file that will need to be adapted for SWIFT.
    FriendsOfFriends/index
    VELOCIraptorInterface/index
    LineOfSights/index
+   LightCones/index
    EquationOfState/index
    ExternalPotentials/index
+   Neutrinos/index
+   RadiativeTransfer/index
    NewOption/index
    Task/index
    AnalysisTools/index
-   Logger/index
+   CSDS/index
    ImplementationDetails/index

doc/onboardingGuide/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)
+

doc/onboardingGuide/README.md

+SWIFT Onboarding Guide
+======================
+
+This is an onboarding guide for SWIFT that can be found on `https://swift.strw.leidenuniv.nl/onboarding.pdf`.
+
+You will need the `sphinx` and python package (pip install it), as well as a working
+TeX distribution.
+
+To build the documentation (from this directory), run ``make latexpdf`` and the output
+files will be created in `build/latex/`.
+

doc/onboardingGuide/source/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "SWIFT Onboarding Guide"
+copyright = "2023, SWIFT Collaboration"
+author = "SWIFT Collaboration"
+
+# The full version, including alpha/beta/rc tags
+release = "1.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- 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 = "alabaster"
+
+# 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"]
+
+
+# -- Options for LaTeX-PDF output --------------------------------------------
+# See https://www.sphinx-doc.org/en/master/latex.html for more options
+
+latex_theme = "howto"
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    "papersize": "a4paper",
+    # The font size ('10pt', '11pt' or '12pt').
+    "pointsize": "10pt",
+    # Font package inclusion.
+    "fontpkg": r"""
+\usepackage[sfdefault]{AlegreyaSans} %% Option 'black' gives heavier bold face
+\renewcommand*\oldstylenums[1]{{\AlegreyaSansOsF #1}}
+""",
+    # Other possible choices:
+    # \usepackage[sfdefault]{ClearSans} %% option 'sfdefault' activates Clear Sans as the default text font
+    # \usepackage[sfdefault,light]{merriweather} %% Option 'black' gives heavier bold face
+    #  %\usepackage[sfdefault,book]{FiraSans} %% option 'sfdefault' activates Fira Sans as the default text font
+    #  %\usepackage{marcellus} %% option 'sfdefault' activates Fira Sans as the default text font
+    # ------------------------------------------
+    # override use of fncychap
+    "fncychap": r"""
+""",
+    # pass options to packages sphinx already loads
+    "passoptionstopackages": r"""
+\PassOptionsToPackage{top=6.1cm, bottom=1cm, left=0.6cm, right=0.6cm}{geometry}
+""",
+    # Additional stuff for the LaTeX preamble.
+    "preamble": r"""
+\usepackage{multicol} % use two columns throughout the document
+
+\setcounter{secnumdepth}{0} % turn off chapter numbering
+
+% Reduce spacing after headings
+%------------------------------------
+% https://tex.stackexchange.com/questions/53338/reducing-spacing-after-headings
+\usepackage{titlesec}
+
+\titlespacing\title{0pt}{0pt plus 0pt minus 0pt}{0pt plus 0pt minus 0pt}
+\titlespacing\chapter{0pt}{0pt plus 0pt minus 0pt}{0pt plus 0pt minus 0pt}
+\titlespacing\section{0pt}{4pt plus 0pt minus 8pt}{4pt plus 0pt minus 4pt}
+\titlespacing\subsection{0pt}{1pt plus 0pt minus 4pt}{0pt plus 0pt minus 8pt}
+\titlespacing\subsubsection{0pt}{1pt plus 0pt minus 2pt}{0pt plus 0pt minus 8pt}
+
+% Reduce section font sizes
+%------------------------------------
+\titleformat*{\section}{\Large\bf}
+\titleformat*{\subsection}{\normalsize\bf}
+\titleformat*{\subsubsection}{\small\bf}
+
+
+
+% Modify the way inline verbatim behaves.
+%------------------------------------------
+% this version changes the text color.
+%\definecolor{inlineVerbatimTextColor}{rgb}{0.6, 0.4, 0.5}
+%\protect\renewcommand{\sphinxcode}[1]{\textcolor{inlineVerbatimTextColor}{\texttt{#1}}}
+
+% this version keeps the text color, but adds a colorful box.
+\definecolor{inlineVerbatimBorderColor}{rgb}{0.90, 1.00, 0.95}
+
+\protect\renewcommand{\sphinxcode}[1]{\colorbox{inlineVerbatimBorderColor}{\texttt{#1}}}
+
+
+% Drawing and image positioning
+%---------------------------------
+\usepackage{tikz}
+\usetikzlibrary{positioning}
+
+
+% Reduce space between \item
+%----------------------------------
+
+\let\tempone\itemize
+\let\temptwo\enditemize
+\renewenvironment{itemize}{\tempone\addtolength{\itemsep}{-0.5\baselineskip}}{\temptwo}
+""",
+    #  last thing before \begin{document}:
+    "makeindex": r"""
+\pagestyle{empty}
+""",
+    #  override title making.
+    "maketitle": r"""
+\begin{multicols}{2} % make two columns
+""",
+    #  additional footer content
+    "atendofbody": r"""
+\end{multicols} % make two columns
+""",
+    #  override ToC.
+    "tableofcontents": r"""
+""",
+    "extraclassoptions": r"""
+""",
+    #  sphinx related stuff
+    "sphinxsetup": r"""
+VerbatimColor={rgb}{0.90, 1.00, 0.95},
+verbatimwithframe=false,
+hmargin={0.6cm, 0.6cm},
+vmargin={5.2cm, 1cm},
+TitleColor={rgb}{0.40,0.00,0.33},
+OuterLinkColor={rgb}{0., 0.40, 0.27},
+""",
+}
+
+latex_documents = [
+    (
+        "index",  # startdocname
+        "onboarding.tex",  # targetname
+        "SWIFT Onboarding Guide",  # title
+        "SWIFT Collaboration",  # author
+        "howto",  # theme
+        False,  # toctree only
+    )
+]

doc/onboardingGuide/source/dependencies.rst

+.. dependencies
+
+Dependencies
+============
+
+To compile SWIFT, you will need the following libraries:
+
+HDF5
+~~~~
+
+Version 1.10.x or higher is required. Input and output files are stored as HDF5
+and are compatible with the GADGET-2 specification. A parallel-HDF5 build
+and HDF5 >= 1.12.x is recommended when running over MPI.
+
+MPI
+~~~
+A recent implementation of MPI, such as Open MPI (v3.x or higher), is required,
+or any library that implements at least the MPI 3 standard.
+
+Libtool
+~~~~~~~
+The build system depends on libtool.
+
+FFTW
+~~~~
+Version 3.3.x or higher is required for periodic gravity.
+
+ParMETIS or METIS
+~~~~~~~~~~~~~~~~~
+One is required for domain decomposition and load balancing.
+
+GSL
+~~~
+The GSL 2.x is required for cosmological integration.
+
+In most cases the configuration script will be able to detect the libraries
+installed on the system. If that is not the case, the script can be pointed
+towards the libraries' location using the following parameters
+
+.. code-block:: bash
+
+  ./configure --with-gsl=<PATH-TO-GSL>
+
+and similar for the other libaries.
+
+Optional Dependencies
+=====================
+
+There are also the following *optional* dependencies:
+
+libNUMA
+~~~~~~~
+libNUMA is used to pin threads.
+
+TCmalloc/Jemalloc/TBBmalloc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TCmalloc/Jemalloc/TBBmalloc are used for faster memory allocations when available.
+
+Python
+~~~~~~
+To run the examples, you will need python 3 and some of the standard scientific libraries (numpy, matplotlib).
+Some examples make use of the `swiftsimio <https://swiftsimio.readthedocs.io/en/latest/>`_ library,
+which is a dedicated and maintained visualisation and analysis library for SWIFT.
+
+GRACKLE
+~~~~~~~
+GRACKLE cooling is implemented in SWIFT. If you wish to take advantage of it, you will need it installed.
+
+HEALPix C library
+~~~~~~~~~~~~~~~~~
+This is required for making light cone HEALPix maps. 
+
+CFITSIO
+~~~~~~~
+This may be required as a dependency of HEALPix.
+
+
+

doc/onboardingGuide/source/getting_help.rst

+.. getting help
+
+Getting Help
+============
+
+
+Feel free to contact us on `Gitter (gitter.im/swiftsim) <https://gitter.im/swiftsim>`_
+or on our `GitHub (github.com/swiftsim/swiftsim) <https://github.com/swiftsim/swiftsim>`_ 
+by creating an issue.
+
+The code documentation is available on `swiftsim.com/docs <https://swiftsim.com/docs>`_, and
+is also shipped along with the code in the ``docs/RTD`` directory. 
+This onboarding guide is available online as well on 
+`swiftsim.com/onboarding.pdf <https://swift.strw.leidenuniv.nl/onboarding.pdf>`_

doc/onboardingGuide/source/getting_the_code.rst

+.. Getting The Code
+
+
+Getting The Code
+=================
+
+The code is available from our GitLab (core developers) and GitHub (public mirror)
+repositories. You can download it over https from the following locations:
+
++ https://github.com/swiftsim/swiftsim.git
++ https://gitlab.cosma.dur.ac.uk/swift/swiftsim.git
+
+

doc/onboardingGuide/source/header_first_page.rst

+.. Produce the header title on the first page.
+
+.. raw:: latex
+
+   % remove all headers/footers
+   \pagestyle{empty}
+
+   % Add image
+   \tikz[remember picture,overlay]
+       \node[opacity=1.0,inner sep=0pt, anchor=north] at (current page.north)
+       {\includegraphics[width=\paperwidth,height=5cm]{../../source/header_page1.jpg}};
+
+   % for whatever reason, an ugly spacing is added.  Remove it here.
+   \vspace{-1.8\baselineskip}
+
+

doc/onboardingGuide/source/header_second_page.rst

+.. Produce the header title on the second page.
+
+
+.. raw:: latex
+
+   % remove all headers/footers
+   \pagestyle{empty}
+
+   % Add background image
+   \tikz[remember picture,overlay]
+       \node[opacity=1.0,inner sep=0pt, anchor=north] at (current page.north)
+       {\includegraphics[width=\paperwidth,height=5cm]{../../source/header_page2.jpg}};
+
+   % Add logo
+   \tikz[remember picture,overlay]
+       \node[below left = -1.9cm and -1.5cm] at (current page.north)
+       {\includegraphics[height=8cm]{../../source/logo/BirdW.pdf}};
+
+   % for whatever reason, an ugly spacing is added.  Remove it here.
+   \vspace{-3.3\baselineskip}

doc/onboardingGuide/source/index.rst

+.. Onboarding Guide
+   Mladen Ivkovic, January 2023
+
+======================
+SWIFT Onboarding Guide
+======================
+
+.. Note: There seems to be some issue with sphinx, where the first and highest
+   heading in the hierarchy will be skipped when generating pdfs. We don't make
+   a title for this guide anyway, so add the title of the guide above so the
+   first section will be displayed correctly.
+
+
+.. This is the first page of the onboarding guide
+   -----------------------------------------------------------------
+
+.. include:: header_first_page.rst
+
+.. include:: what_swift_can_do.rst
+.. include:: getting_the_code.rst
+.. include:: getting_help.rst
+.. include:: initial_setup.rst
+
+.. raw:: latex
+
+    % fill column.
+    \vfill\null
+
+.. include:: dependencies.rst
+
+
+
+
+.. This is the second page of the onboarding guide
+   -----------------------------------------------------------------
+
+.. raw:: latex
+
+   \vfill\null
+   \newpage
+
+.. include:: header_second_page.rst
+
+.. include:: useful_configuration_flags.rst
+.. include:: runtime_options.rst
+.. include:: running_example.rst
+.. include:: submission_script.rst
+
+
+

doc/onboardingGuide/source/initial_setup.rst

+Initial Setup
+=============
+
+We use autotools for setup. To get a basic running version of the code (the executable binaries are found in the top directory), use:
+
+.. code-block:: bash
+
+  ./autogen.sh
+  ./configure
+  make
+
+
+MacOS Specific Oddities
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To build on MacOS you will need to enable compiler warnings due to an
+incomplete implementation of pthread barriers. DOXYGEN also has some issues on
+MacOS, so it is best to leave it out. To configure:
+
+.. code-block:: bash
+
+  ./configure --enable-compiler-warnings \
+      --disable-doxygen-doc
+
+When using the ``clang`` compiler, the hand-written vectorized routines
+have to be disabled. This is done at configuration time by adding
+the flag ``--disable-hand-vec``.
+
+

doc/onboardingGuide/source/running_example.rst

+.. Running an Example
+   Josh Borrow, 5th April 2018
+   Mladen Ivkovic, Jan 2023
+
+Running an Example
+==================
+
+SWIFT provides a number of examples that you can run in the ``examples/`` directory. 
+Many are detailed in their respective ``README`` files, and contain python scripts
+(files with the suffix ``.py``) to both generate initial conditions and plot results.
+The python scripts usually contain their respective documentation at the top of the 
+script file itself.
+
+
+Sod Shock
+~~~~~~~~~
+
+In this example, we will run the 3D SodShock test. You will need to configure and 
+compile the code as follows:
+
+.. code-block:: bash
+   
+   ./configure
+   make
+
+Then to run the code, we first download and build the
+initial conditions:
+
+.. code-block:: bash
+
+    cd examples/HydroTests/SodShock_3D
+    ./getGlass.sh
+    python3 makeIC.py
+    ../../../swift --hydro --threads=4 sodShock.yml
+
+We can plot the solution with the included python script
+as follows: 
+
+.. code-block:: bash
+
+    python3 plotSolution.py 1
+
+The argument ``1`` tells the python plotting script to use the snapshot with number 
+1 for the plot.
+
+
+
+Small Cosmological Volume
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As a second example, we run a small cosmolgical 
+volume containing dark matter only starting at redshift :math:`z = 50`.
+Like for the Sod Shock example, it suffices to configure (``./configure``) and 
+compile (``make``) the code without any extra flags.
+
+After downloading the initial conditions, we run the code with cosmology and
+self-gravity:
+
+.. code-block:: bash
+
+    cd examples/SmallCosmoVolume/SmallCosmoVolume_DM
+    ./getIC.sh
+    ../../../swift --cosmology --self-gravity \ 
+        --threads=8 small_cosmo_volume_dm.yml
+
+
+We can plot the solution with the included python script
+as follows:
+
+.. code-block:: bash
+
+    python3 plotProjection.py 31
+
+The ``plotProjection.py`` script requires the 
+`swiftsimio <https://swiftsimio.readthedocs.io/en/latest/>`_
+library.
+
+An example containing both baryonic and dark matter is
+``examples/SmallCosmoVolume/SmallCosmoVolume_hydro``. To run with
+hydrodynamics, the ``--hydro`` flag needs to be provided as well:
+
+.. code-block:: bash
+
+    ../../../swift --cosmology --self-gravity \ 
+        --hydro --threads=8 small_cosmo_volume.yml
+
+
+