clean up docs a bit and set thumbnails for examples

docs/source/conf.py

@@ -63,10 +63,10 @@
     'style_external_links': False,
     # Toc options
     'collapse_navigation': False,
-    'sticky_navigation': True,
-    'navigation_depth':5
+    'navigation_depth':3,
 }
-
+# 
+# 'sticky_navigation': False,
 
 # 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,

docs/source/general_intro.rst

@@ -1,17 +1,24 @@
-General Intro to `beamshapes`
-=============================
+Concepts behind :code:`beamshapes`
+==================================
 Sound sources don't radiate sound uniformly most of the time. Even us humans for instance, we emit more energy while talking to the front than to the back. The exact (non-uniform) pattern in which sound is radiated defines the 'beamshape' of a source. The beamshape is typically a combination of the frequency of emitted sound and the geometry of the vibrating surface and its associated (non-vibrating) surfaces. 
 
 Let's go through the main concepts required to use the `beamshapes` package.
 
 Source models
 -------------
-A 'beamshape' is tightly bound to the input parameters, and the sound source model behind
-it eg. piston in a sphere, cap of a sphere etc. The source model refers to the source
-of sound and its geometric properties, and assumptions of the vibrations etc. According
+The source model refers to the source of sound and its geometric properties, and assumptions of the vibrations etc. According
 to the situation in hand, different source models may be physically/biologically relevant! 
 
 
+There are two main ways to predict how sound will radiate from a source - analytical or numerical modelling. Analytical models
+start with equations defining the physics of sound radiation and move on to produce mathematical solutions. Numerical
+methods use various numerical algorithms (eg. finite-element method) to computationally simulate sound radiation. :code:`beamshapes`
+specifically implements analytical source models with pre-defined solutions. The advantage of using such analytical models is the lower
+number of parameters needed to describe and understand the resulting sound radation. 
+
+Below is a brief description of the source models and the parameters relevant to them. For more information on each of the model's please refer to 
+the source references. 
+
 Piston in an infinite baffle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~	
 .. image:: ./_static/piston_in_inf_baffle.png.png
@@ -22,6 +29,8 @@ Piston in an infinite baffle
 Here a rigid circular disk (the 'piston') vibrates back and forth between a hole in a huge baffle that matches the disk's size.
 The parameters needed to define this model are the wavenumber and piston radius. 
 
+Reference : Chp 13, Beranek, L. L., & Mellow, T. (2019). Acoustics: sound fields and transducers. Academic Press.
+
 Point on a sphere
 ~~~~~~~~~~~~~~~~~
 .. image:: ./_static/point_on_sphere.png.png
@@ -32,6 +41,8 @@ Point on a sphere
 An infinitesimally small portion of a sphere's surface (the 'point') is considered to vibrate. The rest of the sphere does not vibrate.
 The parameters needed to define this model are the wavenumber and sphere radius. 
 
+Reference: Chp 12, Beranek, L. L., & Mellow, T. (2019). Acoustics: sound fields and transducers.
+Academic Press.
 
 Oscillating cap of a sphere
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -47,6 +58,9 @@ relation :math:`u(R,\theta) = u_{0}cos \theta`, where :math:`\theta` is the dist
 
 The parameters needed to define this model are wavenumber, sphere radius, and the aperture angle of the cap. 
 
+Reference: Chp 12, Beranek, L. L., & Mellow, T. (2019). Acoustics: sound fields and transducers.
+Academic Press.
+
 Piston in a sphere
 ~~~~~~~~~~~~~~~~~~
 
@@ -59,51 +73,18 @@ A sphere is sliced, and the 'cap' is discarded. The 'open' portion of the sliced
 This piston in the sphere vibrates to produce sound. The parameters needed to define this model are wavenumber, sphere radius, 
 aperture angle of the piston, and piston radius. 
 
+Reference: Chp 12, Beranek, L. L., & Mellow, T. (2019). Acoustics: sound fields and transducers.
+Academic Press.
+
 Input Parameters
 ----------------
 The inputs will tend to be model-specific, but the common input parameters
 to keep in mind are:
 
-    #. `k`, wavenumber. This is :math:`\frac{2\pi}{\lambda}` - this is another wave of defining the frequency of the vibrating part, and the sound produced. :math:`\lambda`is the wavelength of the sound, also defined as :math:`\frac{v_\text{sound}}{\text{frequency}}`. 
+    #. `k`, wavenumber. This is :math:`\frac{2\pi}{\lambda}` - this is another wave of defining the frequency of the vibrating part, and the sound produced. :math:`\lambda` is the wavelength of the sound, also defined as :math:`\frac{v_\text{sound}}{\text{frequency}}`. 
     #. `a` : piston radius, wherever applicable
     #. `R` : sphere radius, wherever applicable. 
     #. :math:`\alpha, \theta, \phi`: various angles describing the size of the oscillating portion. These angles are in radians - not degrees!
 
 
-Directionality functions
-------------------------
-Each source model has an associated `directionality` function with it. 
-The directionality function returns the :math:`20log_{10}(D_{\theta}/D_{0})`
-value for a given set of angles. Some models require a long time to compute 
-coefficients, and also output other objects to save time for future runs.
-
-The oscillating cap in a sphere does not produce additional output
-
-.. code-block:: shell
-
-    # .... having chosen certain input parameters and put them into  input_params
-    >>> import mpmath
-    >>> import beamshapes as beamshapes
-    >>> from beamshapes import cap_in_sphere_directionality
-    >>> angles = mpmath.linspace(0,pi,10) 
-    >>>  _, spherecap_beam = cap_in_sphere_directionality(angles, input_params)
-
-In case the chosen source model's directionality requires intensive calculations
-to generate estimates, then the calculated outputs are also returned. 
-
-.. code-block:: shell
-
-    # .... having chosen certain input parameters and put them into input_params 
-    >>> import mpmath
-    >>> import beamshapes as beamshapes
-    >>> from beamshapes import piston_in_sphere_directionality
-    >>> angles = mpmath.linspace(0,pi,10) 
-    >>> An_out, spherepiston_beam = piston_in_sphere_directionality(angles, input_params)
-    # in case you need to calculate more points now - it saves time to do this:
-    >>> input_params['An'] = An_out
-    >>> new_angles = mpmath.linspace(0,pi,100)
-    >>> _, detailed_spherepiston_beam = piston_in_sphere_directionality(new_angles, input_params)
-
-
-
 

docs/source/index.rst

@@ -6,33 +6,20 @@
 Beamshapes: directivity patterns for various sound sources
 ==========================================================
 
-Introduction
-~~~~~~~~~~~~
-The `beamshapes` package implements directivity functions (:math:`\frac{D_{\theta}}{D_{0}}`) of various published 
-sound radiation models.
 
-What is a directivity function? It's a function that quantifies how sound level changes as you change
-the frequency of the emitted sound, and location of the receiver. 
+.. include:: ./intro_why_who.rst
 
-Check out a general introduction to the concepts of the package :doc:`here <general_intro>`.
+.. toctree::
+      :maxdepth: 4
+      :caption: Concepts
 
-Why `beamshapes`?
-~~~~~~~~~~~~~~~~~
-While there are many sound radiation models described in the literature, there aren't
-that many (also see `levitate <https://github.com/AppliedAcousticsChalmers/levitate/blob/master/levitate/transducers.py>`_ and `pyroomacoustics <https://pyroomacoustics.readthedocs.io/en/pypi-release/pyroomacoustics.directivities.html>`_) openly available computational implementations of their beamshapes.
+      ./general_intro.rst
 
-Who is this useful for? 
-~~~~~~~~~~~~~~~~~~~~~~~
-Acousticians and bio-acousticians looking to assess model-fits or perform 
-parameter estimation on their sound sources. Check out more on the how
-to use this package in the :doc:`examples <gallery_examples/index>`. 
+.. toctree::
+      :maxdepth: 4
+      :caption: Use Cases
 
-Source models implemented
-~~~~~~~~~~~~~~~~~~~~~~~~~
-* Point source on a sphere
-* Piston in an infinite baffle 
-* Oscillating cap of a sphere 
-* Piston in a sphere
+      gallery_examples/index.rst
 
 Wishlist for future releases 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -47,27 +34,6 @@ All of the sound-source models and directivity calculations are from Leo Beranek
 that may be of interest or to get an idea of how the wishlist models look like!
 
 
-Package installation
-~~~~~~~~~~~~~~~~~~~~
-
-`pip installation` : Install the latest stable version with :code:`pip install beamshapes` 
-
-`Local installation` : Install from the `GitHub repo <https://github.com/thejasvibr/bat_beamshapes>`_ directly by cloning and 
-following the instructions in the README.
-
-
-.. toctree::
-      :maxdepth: 4
-      :caption: Concepts
-
-      ./general_intro.rst
-
-.. toctree::
-      :maxdepth: 4
-      :caption: Use Cases
-
-      gallery_examples/index.rst
-
 
 Contributors
 ~~~~~~~~~~~~

examples/0_preprint_figures.py

@@ -19,6 +19,7 @@
 on your system. The piston in a sphere can take over 10 minutes to run for example!!
 
 """
+
 import mpmath
 import numpy as np 
 import matplotlib.pyplot as plt
@@ -27,6 +28,9 @@
 from beamshapes import cap_in_sphere_directivity
 from beamshapes import point_source_on_a_sphere_directivity
 
+# sphinx_gallery_thumbnail_path = '_static//piston_sphere_baffle.png'
+
+
 # the 'if__name__' pattern for a module is odd - but is required when running code with 
 # the multiprocessing package in Windows. The example should work without the if __name__
 # in Linux systems.

examples/1_piston_sphere_eg1.py

@@ -3,6 +3,8 @@
 =========================================
 
 """
+# sphinx_gallery_thumbnail_path = '_static/peak_and_higher_harmonic.png'
+
 import beamshapes
 import matplotlib.pyplot as plt
 import mpmath

examples/2_flint_pistoninsphere.py

@@ -3,6 +3,7 @@
 FLINT piston in sphere
 ======================
 This example shows how to run the FLINT piston in sphere implementation. 
+
 The :code:`python-flint` package is the python port for the FLINT package in C, 
 and runs extremely fast in comparison to :code:`mpmath`. However, it does
 have its own conventions. This run-through will highlight. 
@@ -12,6 +13,7 @@
 The :code:`python-flint` package currently only works on Linux. See `here <https://github.com/fredrik-johansson/python-flint/>`_
 and `here too <https://fredrikj.net/python-flint/>`_.
 """
+# sphinx_gallery_thumbnail_path = '_static//flint_pistoninsphere.png'
 
 import matplotlib.pyplot as plt
 import numpy as np 

examples/README.rst

@@ -1,3 +1,5 @@
 Examples
 ========
-A set of examples showing the capabilities  of the `beamshapes` package. 
+A set of examples showing the capabilities  of the :code:`beamshapes` package. 
+
+To get an overview of how to use `all` the currently implemented packages, start with `4 models at a time`. 

examples/cap_sphere.py

@@ -9,7 +9,7 @@
 import numpy as np 
 import matplotlib.pyplot as plt
 from beamshapes import cap_in_sphere_directivity
-
+# sphinx_gallery_thumbnail_path = '_static//capsphere_ka-10.0_dps=50.png'
 # %% 
 # This model assumes a curved portion of a sphere (the 'cap') oscillates
 # to produce sound. One cool thing about this model is that it produces somewhat

examples/pistoon_inf_baffle.py

@@ -4,6 +4,7 @@
 Piston in an infinite baffle example
 ====================================
 """
+# sphinx_gallery_thumbnail_path = '_static//PIB.png'
 
 #%% The piston in an infinite baffle is a classic model used to describe
 # the beamshapes of mouth-emitting bat species [1,2] (among other animals eg. [3]).