Merge pull request #4 from robjmcgibbon/soap_docs

Update soap docs

Author: jchelly

source/_static/custom.css

@@ -121,3 +121,14 @@ nav img.flamingo_logo {
     vertical-align:middle;
     margin-right:0.7rem;
 }
+
+/*
+  Hide the page contents sidebar generated by the Piccolo sphinix
+  theme, since we display page contents in the left sidebar.
+*/
+#right_sidebar {
+  display: none;
+}
+#show_right_sidebar {
+  display: none;
+}

source/_templates/localtoc.html

@@ -0,0 +1,7 @@
+<!-- Set the title of the "Page contents" section in the sidebar -->
+{% if display_toc %}
+  <div class="sidebar-localtoc">
+    <p class="caption" role="heading">Page Contents</p>
+    {{ toc }}
+  </div>
+{% endif %}

source/conf.py

@@ -2,6 +2,8 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+from docutils import nodes
+from sphinx.application import Sphinx
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -18,6 +20,13 @@
 templates_path = ['_templates']
 exclude_patterns = []
 
+html_sidebars = {
+    "**": [
+        "globaltoc.html",  # Site contents
+        "localtoc.html",   # Page contents
+    ]
+}
+
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -62,3 +71,31 @@
     'https://unpkg.com/@highlightjs/cdn-assets@11.11.1/languages/python.min.js',
     'https://unpkg.com/@highlightjs/cdn-assets@11.11.1/languages/yaml.min.js',
 ]
+
+
+# Coloured inline roles for the SOAP property table.
+def _highlight_role(background):
+    """Return a docutils role function that wraps text in a highlighted <span>."""
+
+    def role(name, rawtext, text, lineno, inliner, options=None, content=None):
+        style = (
+            f"background-color: {background};"
+            " color: black;"
+            " padding: 1px 4px;"
+            " border-radius: 3px;"
+            " font-family: monospace;"
+        )
+        html = f'<span style="{style}">{text}</span>'
+        # raw() node so the HTML passes through unchanged; latex() node is a
+        # plain-text fallback for PDF builds.
+        node = nodes.raw("", html, format="html")
+        latex_node = nodes.raw("", text, format="latex")
+        return [node, latex_node], []
+
+    return role
+
+
+def setup(app: Sphinx):
+    app.add_role("avail", _highlight_role("#c8e6c9"))     # light green
+    app.add_role("snaponly", _highlight_role("#bbdefb"))  # light blue
+    app.add_role("unavail", _highlight_role("#ffcdd2"))   # light red

source/snapshots/index.rst

@@ -40,6 +40,7 @@ The following sections describe the layout and contents of the snapshots.
    Output redshifts <snapshot_redshifts>
    Particle properties <snapshot_particle_properties>
    Reading with swiftsimio <swiftsimio.rst>
+   Partial snapshots <snapshot_partial>
 
 For more information about the SWIFT simulation snapshot format used
 here, see the `SWIFT documentation

source/snapshots/snapshot_partial.rst

@@ -0,0 +1,41 @@
+Partial snapshots
+=================
+
+Alongside the full particle snapshots, we have retained partial snapshots for all of the original outputs (see :doc:`snapshot_redshifts` for the list). There are two kinds of partial snapshots. Both kinds have the same file format as the original snapshots, and can be opened using
+`swiftsimio
+<https://swiftsimio.readthedocs.io/en/latest/loading_data/index.html>`__.
+
+Downsampled snapshots
+---------------------
+
+For the downsampled snapshots at each output we select a random 1% of particles to keep (not the same 1% for each output). All black hole particles have been retained. The following fields are available for each particle type, with the description for each the same as in the
+:doc:`full snapshots <snapshot_particle_properties>`.
+
+.. note:: Masses (except for black hole masses) have been rescaled by a factor of 100 to conserve the total mass within the snapshot.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Particle Type
+     - Included Fields
+   * - Gas
+     - ``ComptonYParameters``, ``Coordinates``, ``Masses``, ``Velocities``
+   * - Dark matter
+     - ``Coordinates``, ``Masses``, ``Velocities``
+   * - Stars
+     - ``Coordinates``, ``Masses``, ``Velocities``
+   * - Black holes
+     - ``Coordinates``, ``DynamicalMasses``, ``SubgridMasses``, ``Velocities``
+   * - Neutrinos
+     - ``Coordinates``, ``Masses``, ``SampledSpeeds``, ``Velocities``, ``Weights``
+
+TODO: Add a link to an example downsampled snapshot directory
+
+Reduced snapshots
+-----------------
+
+The reduced snapshots contains all the particles within the :math:`R_{100c}` radius of a selection of massive halos. Within the SOAP catalogues each subhalo has a flag ``SOAP/IncludedInReducedSnapshot`` which indicates whether its particles are included in the reduced snapshot. To pick these halos we define a set of :math:`M_{200c}` halo mass bins of width 0.05 dex, with the lowest mass bin starting at :math:`M_{200c}=10^{13} M_\odot`. If a bin has less than 200 halos then we include all of them in the reduced snapshot, if not then we include a random 200.
+
+All of the properties available in the :doc:`full snapshots <snapshot_particle_properties>` are present in the reduced snapshots.
+
+TODO: Add a link to an example reduced snapshot directory