ttricco · Aug 20, 2026 · Jul 24, 2025 · Nov 25, 2025 · Nov 25, 2025 · Nov 27, 2025
diff --git a/README.md b/README.md
@@ -1,30 +1,43 @@
 Sarracen
 ========
 
-A Python library for smoothed particle hydrodynamics (SPH) analysis and visualization.
+A Python library for smoothed particle hydrodynamics (SPH) analysis and 
+visualization.
 
 About
 -----
 
-Sarracen is built upon the pandas, Matplotlib and NumPy libraries. It can load SPH particle data into a pandas DataFrame object that has been extended to allow for rendering of particle data and interpolation of particles to fixed grids. Additionally, this allows for access to the rich landscape of Python scientific and statistical libraries. All SPH functions offer multi-threaded CPU and CUDA implementations. Our intended application is for astrophysical SPH data. 
+Sarracen is built upon the pandas, Matplotlib and NumPy libraries. It can load 
+SPH particle data into a pandas DataFrame object that has been extended to 
+allow for rendering of particle data and interpolation of particles to fixed 
+grids. Additionally, this allows for access to the rich landscape of Python 
+scientific and statistical libraries. All SPH functions offer multi-threaded 
+CPU and CUDA implementations. Our intended application is for astrophysical SPH
+data. 
 
 Installation
 ------------
 
-The latest stable release and associated dependencies can be installed from PyPi:
+The latest stable release and associated dependencies can be installed from 
+PyPi:
 
     pip install sarracen
 
 This is the recommended way to install Sarracen.
 
-To install the latest development snapshot, install using this GitHub repository. Either clone the repository and add it to your path so that it can be imported, or install directly through pip:
+To install the latest development snapshot, install using this GitHub 
+repository. Either clone the repository and add it to your path so that it can 
+be imported, or install directly through pip:
 
     pip install git+https://github.com/ttricco/sarracen.git
 
 Documentation
 -------------
 
-Sarracen's documentation is hosted online at [https://sarracen.readthedocs.io](https://sarracen.readthedocs.io).
+Sarracen's documentation is hosted online at 
+[https://sarracen.readthedocs.io](https://sarracen.readthedocs.io). 
+
+The documentation contains examples and full API references.
 
 Contributing
 ------------
@@ -35,22 +48,27 @@ Contributions are welcomed and appreciated. Here are some ways to get involved:
 - Improving the documentation or providing examples.
 - Writing code to add optimizations or new features.
 
-Please use the [GitHub issue tracker](https://github.com/ttricco/sarracen/issues) to raise any bugs or to submit feature
-requests. If something does not work as you might expect, please let us know. If there are features that you feel are
-missing, please let us know.
+Please use the [GitHub issue tracker](https://github.com/ttricco/sarracen/issues) to raise any bugs or to submit 
+feature requests. If something does not work as you might expect, please let us
+know. If there are features that you feel are missing, please let us know.
 
-Code submissions should be submitted as a pull request. Make sure that all existing unit tests successfully pass, and 
-please add any new unit tests that are relevant. Documentation changes should also be submitted as a pull request.
+Code submissions should be submitted as a pull request. Make sure that all 
+existing unit tests successfully pass, and please add any new unit tests that 
+are relevant. Documentation changes should also be submitted as a pull request.
 
-If you are stuck or need help, [raising an issue](https://github.com/ttricco/sarracen/issues) is a good place to start. 
-This helps us keep common issues in public view. Feel free to also [email](mailto:tstricco@mun.ca) with questions.
+If you are stuck or need help, 
+[raising an issue](https://github.com/ttricco/sarracen/issues) is a good place 
+to start. This helps us keep common issues in public view. Feel free to also 
+[email](mailto:tstricco@mun.ca) with questions.
 
 Please note that we adhere to a [code of conduct](CODE_OF_CONDUCT.md).
 
 Citation
 --------
 
-Please cite the paper if you use Sarracen within your work. Sarracen is published with the Journal of Open Source Software (DOI: [10.21105/joss.05263](https://doi.org/10.21105/joss.05263)).
+Please cite the paper if you use Sarracen within your work. Sarracen is 
+published with the Journal of Open Source Software (DOI: 
+[10.21105/joss.05263](https://doi.org/10.21105/joss.05263)).
 
 ```
 @ARTICLE{Sarracen,

diff --git a/docs/api.rst b/docs/api.rst
@@ -9,22 +9,41 @@ API Reference
 File reading
 ------------
 
-Sarracen can read all general file formats supported by pandas (csv, notably).
+Sarracen's design goal is to read data from multiple SPH codes while preserving
+full functionality. All the general file formats supported by pandas (csv,
+notably) work within Sarracen.
 
-For SPH codes, Sarracen supports reading the native binary format of the `Phantom
-SPH code <https://phantomsph.bitbucket.io>`_. Raise an issue on our GitHub if you
-would like Sarracen to be able to read the file format for other SPH codes (or
-make a pull request!).
+For SPH codes, Sarracen supports reading the native binary format of the
+`Phantom code <https://phantomsph.bitbucket.io>`_, the `Gasoline code
+<https://gasoline-code.com/>`_, and the `Shamrock code
+<https://shamrock-code.github.io/>`_.
+
+Raise an issue on our GitHub if you would like Sarracen to be able to read the
+file format for other SPH codes (or make a pull request!).
 
 .. autosummary::
    :toctree: api/
 
    read_csv
-   read_phantom
-   read_marisa
-   read_gradsph
    read_gasoline
+   read_gradsph
+   read_marisa
+   read_phantom
+   read_phantom_ev
    read_shamrock
+   read_shamrock_vtk
+
+
+File writing
+------------
+
+Sarracen can write native binary Phantom dump files. SarracenDataFrames can
+also be dumped to .csv using pandas functionality.
+
+.. autosummary::
+   :toctree: api/
+
+   write_phantom
 
 
 SarracenDataFrame
@@ -51,6 +70,7 @@ Extra Quantities
    :nosignatures:
 
    SarracenDataFrame.calc_density
+   SarracenDataFrame.calc_one_fluid_quantities
    SarracenDataFrame.centre_of_mass
 
 Rendering
@@ -73,10 +93,11 @@ Interpolation
    SarracenDataFrame.sph_interpolate
 
 
-Kernels
--------
+sarracen.kernels
+----------------
 
-The default smoothing kernel is the cubic spline. Additional smoothing kernels are included within Sarracen.
+The default smoothing kernel is the cubic spline. Additional smoothing kernels
+are included within the kernels module.
 
 .. autosummary::
    :toctree: api/
@@ -86,8 +107,8 @@ The default smoothing kernel is the cubic spline. Additional smoothing kernels a
    kernels.QuinticSplineKernel
 
 
-Disc
-----
+sarracen.disc
+-------------
 
 Accretion disc analysis routines are in the disc module.
 
@@ -99,3 +120,15 @@ Accretion disc analysis routines are in the disc module.
    disc.angular_momentum
    disc.scale_height
    disc.honH
+
+
+sarracen.ptmass
+---------------
+
+Analysis routines related to point masses and sink particles are in the ptmass
+module.
+
+.. autosummary::
+   :toctree: api/
+
+   ptmass.classify_bound_particles
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -11,54 +11,107 @@ Contributions are welcomed and appreciated. Here are some ways to get involved:
 - Improving the documentation or providing examples.
 - Writing code to add optimizations or new features.
 
-Please use the `GitHub issue tracker <https://github.com/ttricco/sarracen/issues>`_ to raise any bugs or to submit feature
-requests. If something does not work as you might expect, please let us know. If there are features that you feel are
-missing, please let us know.
+Please use the `GitHub issue tracker
+<https://github.com/ttricco/sarracen/issues>`_ to raise any bugs or to submit
+feature requests. If something does not work as you might expect, please let us
+know. If there are features that you feel are missing, please let us know.
 
-Code submissions should be submitted as a pull request. Make sure that all existing unit tests successfully pass, and
-please add any new unit tests that are relevant. Documentation changes should also be submitted as a pull request.
+Code submissions should be submitted as a pull request. Make sure that all
+existing unit tests successfully pass, and please add any new unit tests that
+are relevant. Documentation changes should also be submitted as a pull request.
 
-If you are stuck or need help, `raising an issue <https://github.com/ttricco/sarracen/issues>`_ is a good place to start.
-This helps us keep common issues in public view. Feel free to also `email <mailto:tstricco@mun.ca>`_ with questions.
-
-Please note that we adhere to a `code of conduct <https://github.com/ttricco/sarracen/blob/main/CODE_OF_CONDUCT.md>`_.
+If you are stuck or need help, `raising an issue
+<https://github.com/ttricco/sarracen/issues>`_ is a good place to start. This
+helps us keep common issues in public view. Feel free to also `email
+<mailto:tstricco@mun.ca>`_ with questions.
 
+Please note that we adhere to a `code of conduct
+<https://github.com/ttricco/sarracen/blob/main/CODE_OF_CONDUCT.md>`_.
 
 Developer Guidelines
 --------------------
 
-There are several guiding principles to the development of Sarracen that we follow.
+There are several guiding principles to the development of Sarracen that we
+follow.
 
 1. **Simple, intuitive API.**
 
-   A low barrier of entry for new users is important to us. This is why we model off of common scientific libraries, as we expect our users to be familiar with these tools. The naming of functions and their arguments should be clear, follow standard patterns, and avoid unnecessary complexity.
+    A low barrier of entry for new users is important to us. This is why we
+    model off of common scientific libraries, as we expect our users to be
+    familiar with these tools. The naming of functions and their arguments
+    should be clear, follow standard patterns, and avoid unnecessary
+    complexity.
 
 2. **Efficiency.**
 
-   Performance is important. A simple guiding principle is to leverage built-in pandas or NumPy functions when possible.
+    Performance is important. A simple guiding principle is to leverage
+    built-in pandas or NumPy functions when possible.
 
 3. **Pure Python.**
 
-   Sarracen is developed entirely in Python, without mixing in other code extensions such as Cython. Code efficiency is important, but we prioritize the maintainability and portability afforded by a pure Python codebase.
+    Sarracen is developed entirely in Python, without mixing in other code
+    extensions such as Cython. Code efficiency is important, but we prioritize
+    the maintainability and portability afforded by a pure Python codebase.
 
 4. **Unit tested.**
 
-   We use pytest to comprehensively test Sarracen. Any new code added should come with an associated set of unit tests. System testing is important, but unit tests ensure the long-term correctness and reliability of Sarracen.
+    We use pytest to comprehensively test Sarracen. Any new code added should
+    come with an associated set of unit tests. System testing is important, but
+    unit tests ensure the long-term correctness and reliability of Sarracen.
 
 5. **Avoid code lint.**
 
-   We use flake8 to conform to Python style guides. Avoiding lint might not help write good code, but it can help avoid writing bad code. Our aim is to reduce technical debt to help ensure consistency and readability across the codebase.
+    We use flake8 to conform to Python style guides. Avoiding lint might not
+    help write good code, but it can help avoid writing bad code. Our aim is to
+    reduce technical debt to help ensure consistency and readability across the
+    codebase.
 
-If you have a new code addition or a change to existing code that you would like to submit, start by making a pull request (PR) on GitHub.
 
 Pull Requests
 -------------
 
-All changes to Sarracen's code base are made through Pull Requests. Start by forking Sarracen on GitHub. Add your changes to your repository on your GitHub account (optionally on a development branch on your account). Then use GitHub to open a new Pull Request. Add details about your change, and resolve any issues found by the automated GitHub actions.
+If you have a new code addition or a change to existing code that you would
+like to submit, start by making a pull request (PR) on GitHub.
+
+All changes to Sarracen's code base are made through Pull Requests. Start by
+forking Sarracen on GitHub. Add your changes to your repository on your GitHub
+account (optionally on a development branch on your account). Then use GitHub
+to open a new Pull Request. Add details about your change, and resolve any
+issues found by the automated GitHub actions.
 
-GitHub Actions
+Code Lint
 --------------
 
-Code commits use GitHub actions to automatically check for code lint.
+Sarracen uses ``flake8`` to follow Python style guides on naming conventions,
+code structure, and formatting. This is sometimes annoying, but adopting a
+single style is beneficial.
+
+Sarracen also uses type hints across the code base. Python
+is not a typed language, but type hints help to avoid bugs and make intent
+clear.
+
+You can run flake8 on your local codebase as follows:
+
+.. code-block::
+
+    pip install flake8
+    flake8 sarracen
+
+You can also run flake8 on specific directories or files, rather than the whole
+codebase. A list of specific errors per file with line numbers will be returned.
+
+GitHub actions will automatically run flake8 on pull requests.
+
+If the automated linter finds lint errors in your code, then go to the
+``Checks`` tab on the PR. Expand the section "Super-linter" marked by the red
+X, and then expand the PYTHON_FLAKE8 section. This will give you the output
+from flake8, such as the specific lines of code and their associated lint
+errors.
+
+In the example below, the specific flake8 errors are given on lines 261, 262,
+and 263 of the output. These point out that there is an undefined variable,
+no blank lines after class or function declaration, and that there was no
+newline at the end of the file. Yes, we do care about having a newline at the
+end of the file.
 
-If the automated linter finds lint errors in your code, check the details by going into the action's job details. Expand the section "Super-linter" marked by the red X, and then expand the PYTHON_FLAKE8 section. This will give you the output from flake8, such as the specific lines of code and their associated lint errors.
+.. image:: contributing/flake8.png
diff --git a/docs/contributing/flake8.png b/docs/contributing/flake8.png
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -4,6 +4,9 @@
 Examples
 ========
 
+Below you will find a handful of examples of typical Sarracen usage. More
+documentation is always appreciated!
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:

diff --git a/docs/examples/dustydisc.rst b/docs/examples/dustydisc.rst
@@ -11,6 +11,9 @@ The host star is 1 solar mass. It has two orbiting Jupiter mass planets at 10 an
 
 The star and planets are modeled using sink particles. The gas and dust modeled using two species of particles. The analysis below is after 25 orbits of the outer planet.
 
+Reading the Data
+----------------
+
 In a Jupyter notebook, or other interactive Python environment,
 
 >>> # A sample analysis of the Orszag-Tang vortex at t=0.5.
@@ -41,6 +44,9 @@ In Phantom, gas particles are ``itype=1`` and dust particles ``itype=7``. There
 
 Sarracen supports pandas style slicing. For example, to get a SarracenDataFrame of just the gas particles, one could use ``sdf[sdf.itype==1]``.
 
+Visualization
+-------------
+
 Cross-sectional renderings of the gas and dust components of the disc are below.
 
 >>> sdf[sdf.itype == 1].render('rho', xlim=(-40, 40), ylim=(-40, 40), log_scale=True, xsec=0.0)
@@ -62,3 +68,25 @@ Sarracen's render function returns a Matplotlib Axes object (and can accept one
 
 .. image:: dustydisc/dustydisc-gas-sinks.png
     :width: 400
+
+
+Analysis
+--------
+
+Sarracen can calculate the surface density profile of the disc.
+
+>>> import seaborn as sns
+>>>
+>>> sigma, bins = sarracen.disc.surface_density(sdf, r_out=80, retbins=True)
+>>>
+>>> ax = sns.lineplot(x=bins, y=sigma)
+>>> ax.set_yscale('log')
+
+.. image:: dustydisc/dustydisc-surface-density.png
+    :width: 450
+
+Notice the two dips at the locations at the planets.
+
+There are several more useful analysis routines in the ``disc`` module of
+Sarracen.
+