Docs update

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
@@ -76,7 +95,8 @@ Interpolation
 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 Sarracen.
 
 .. autosummary::
    :toctree: api/

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:: flake8.png

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:

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)
@@ -52,13 +58,35 @@ Cross-sectional renderings of the gas and dust components of the disc are below.
 
 .. image:: dustydisc/dustydisc-dust.png
     :width: 400
-
 Rendering sink particles can use Matplotlib's ``scatter()``, where sink particles are plotted as a scatterplot over the rendered image. Seaborn's ``scatterplot()`` is another good option.
 
+
 Sarracen's render function returns a Matplotlib Axes object (and can accept one too).
 
 >>> ax = sdf[sdf.itype == 1].render('rho', xlim=(-40, 40), ylim=(-40, 40), log_scale=True, xsec=0.0)
 >>> ax.scatter(x=sdf_sinks['x'], y=sdf_sinks['y'], color='white')
 
 .. 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.
+

docs/index.rst

@@ -6,15 +6,27 @@
 Sarracen documentation
 ======================
 
-Sarracen is a Python library for analysis and visualization of smoothed particle hydrodynamics (SPH) data.
-
-It is built upon the pandas and Matplotlib data and visualization libraries.  SPH data can be loaded into a pandas
-DataFrame structure that has been extended to support SPH. Visualizations of the data use the SPH kernel, and a variety
-of rendering options are available. All SPH interpolation functions are optimized using Numba into machine code with
-both multi-threaded and CUDA enabled routines. Our primary intended application is for astrophysical SPH simulations.
-
-Visit the :ref:`quick start guide <quick_start>` to learn the basics of Sarracen. For details on specific functions,
-consult the :ref:`API reference <api>`. The codebase can be found on `GitHub <https://github.com/ttricco/sarracen/>`_.
+Sarracen is a Python library for analysis and visualization of smoothed
+article hydrodynamics (SPH) data.
+
+Our goal is to leverage the rich data science toolkits available in Python for
+the analysis of SPH data. Sarracen is built upon the pandas and Matplotlib data
+and visualization libraries. SPH data can be loaded into a pandas DataFrame
+structure that has been extended to support SPH. Sarracen should be familiar to
+you if you have previous experience with Matplotlib, NumPy or pandas. Our
+primary intended application is for astrophysical SPH simulations.
+
+Visualizations of the data use the SPH kernel, and a variety of rendering
+options are available. All SPH interpolation functions are optimized into
+machine code using Numba with both multi-threaded and CUDA enabled routines.
+Our aim is to provide common analyses tasks as part of Sarracen, for example,
+calculating surface density profiles. This aids in correctness, performance and
+reproducibility.
+
+Visit the :ref:`quick start guide <quick_start>` to learn the basics of
+Sarracen. For details on specific functions, consult the :ref:`API reference
+<api>`. The codebase can be found on `GitHub
+<https://github.com/ttricco/sarracen/>`_.
 
 .. toctree::
    :maxdepth: 1
@@ -25,7 +37,7 @@ consult the :ref:`API reference <api>`. The codebase can be found on `GitHub <ht
    render
    examples
    api
-   contributing
+   contributing/index
 
 
 Indices and tables