Cleaned up the docs a bit

Author: harpolea

compressible/problems/kh.py

@@ -9,12 +9,12 @@
 def init_data(my_data, rp):
     """ initialize the Kelvin-Helmholtz problem """
 
-    msg.bold("initializing the sedov problem...")
+    msg.bold("initializing the Kelvin-Helmholtz problem...")
 
     # make sure that we are passed a valid patch object
     if not isinstance(my_data, patch.CellCenterData2d):
         print(my_data.__class__)
-        msg.fail("ERROR: patch invalid in sedov.py")
+        msg.fail("ERROR: patch invalid in kh.py")
 
     # get the density, momenta, and energy as separate variables
     dens = my_data.get_var("density")

compressible/problems/logo.py

@@ -8,13 +8,13 @@
 
 
 def init_data(my_data, rp):
-    """ initialize the sedov problem """
+    """ initialize the logo problem """
 
     msg.bold("initializing the logo problem...")
 
     # make sure that we are passed a valid patch object
     if not isinstance(my_data, patch.CellCenterData2d):
-        print("ERROR: patch invalid in sedov.py")
+        print("ERROR: patch invalid in logo.py")
         print(my_data.__class__)
         sys.exit()
 

docs/source/particles_basics.rst

@@ -1,12 +1,12 @@
-Particles overview
-==================
+Particles
+=========
 
 A solver for modelling particles.
 
 ``particles.particles`` implementation and use
 ----------------------------------------------
 
-We import the basic particles functionality as:
+We import the basic particles module functionality as:
 
 .. code-block:: python
 
@@ -20,28 +20,48 @@ The particles solver is made up of two classes:
   about a collection of particles.
 
 The particles are stored as a dictionary, and their positions are updated
-based on the velocity on the grid. The keys are assumed to be the initial
-positions of the particles (however this is only used for plotting purposes
-so any tuple would be fine).
+based on the velocity on the grid. The keys are tuples of the particles'
+initial positions (however the values of the keys themselves are never used
+in the module, so this could be altered using e.g. a custom ``particle_generator``
+function without otherwise affecting the behaviour of the module).
 
-The particles can be initialised in a number of ways:
+The particles can be initialized in a number of ways:
 
-* :func:`randomly_generate_particles <particles.particles.Particle.randomly_generate_particles>`,
-  which randomly generates ``n_particles`` within the domain;
-* :func:`grid_generate_particles <particles.particles.Particle.grid_generate_particles>`,
+* :func:`randomly_generate_particles <particles.particles.Particles.randomly_generate_particles>`,
+  which randomly generates ``n_particles`` within the domain.
+* :func:`grid_generate_particles <particles.particles.Particles.grid_generate_particles>`,
   which will generate approximately ``n_particles`` equally spaced in the
-  x-direction and y-direction (though the uses the same number of particles in
+  x-direction and y-direction (note that it uses the same number of particles in
   each direction, so the spacing will be different in each direction if the
-  domain is not square.) The number of particles will be increased/decreased
-  in order to fill the whole domain;
-* :func:`array_generate_particles <particles.particles.Particle.array_generate_particles>`,
-  generates particles based on array of particle positions passed to the constructor;
-* the user can define their own ``particle_generator`` and pass this into the
-  Particles constructor. This function takes the number of particles to be
+  domain is not square). The number of particles will be increased/decreased
+  in order to fill the whole domain.
+* :func:`array_generate_particles <particles.particles.Particles.array_generate_particles>`,
+  which generates particles based on array of particle positions passed to the
+  constructor.
+* The user can define their own ``particle_generator`` function and pass this into the
+  ``Particles`` constructor. This function takes the number of particles to be
   generated and returns a dictionary of ``Particle`` objects.
 
-We can initialize particles in a problem using the following code in the
-solver's ``Simulation.initialize`` function:
+We can turn on/off the particles solver using the following runtime paramters:
+
++--------------------------------------------------------------------------------+
+|``[particles]``                                                                 |
++=======================+========================================================+
+|``do_particles``       | do we want to model particles? (0=no, 1=yes)           |
++-----------------------+--------------------------------------------------------+
+|``n_particles``        | number of particles to be modelled                     |
++-----------------------+--------------------------------------------------------+
+|``particle_generator`` | how do we initialize the particles? "random"           |
+|                       | randomly generates particles throughout the domain,    |
+|                       | "grid" generates equally spaced particles, "array"     |
+|                       | generates particles at positions given in an array     |
+|                       | passed to the constructor. This option can be          |
+|                       | overridden by passing a custom generator function to   |
+|                       | the ``Particles`` constructor.                         |
++-----------------------+--------------------------------------------------------+
+
+Using these runtime parameters, we can initialize particles in a problem using
+the following code in the solver's ``Simulation.initialize`` function:
 
 .. code-block:: python
 
@@ -58,38 +78,34 @@ update of the other variables in the solver's ``Simulation.evolve`` function:
    if self.particles is not None:
         self.particles.update_particles(self.dt)
 
+This will both update the positions of the particles and enforce the boundary
+conditions.
+
 For some problems (e.g. advection), the x- and y- velocities must also be passed
 in as arguments to this function as they cannot be accessed using the standard
-``get_var("velocity")`` command.
+``get_var("velocity")`` command. In this case, we would instead use
+
+.. code-block:: python
+
+   if self.particles is not None:
+        self.particles.update_particles(self.dt, u, v)
 
-We can turn on/off the particles solver using the following runtime paramters:
 
-+--------------------------------------------------------------------------------+
-|``[particles]``                                                                 |
-+=======================+========================================================+
-|``do_particles``       | do we want to model particles? (0=no, 1=yes)           |
-+-----------------------+--------------------------------------------------------+
-|``n_particles``        | number of particles to be modelled                     |
-+-----------------------+--------------------------------------------------------+
-|``particle_generator`` | how do we initialize the particles? "random"           |
-|                       | randomly generates particles throughout the domain,    |
-|                       | "grid" generates equally spaced particles. This        |
-|                       | option can be overridden by passing a custom generator |
-|                       | function to the ``Particles`` constructor.             |
-+-----------------------+--------------------------------------------------------+
 
 Plotting particles
 ------------------
 
-Particles can be plotted by getting their positions using
+Given the ``Particles`` object ``particles``, we can plot the particles by getting
+their positions using
 
 .. code-block:: python
 
    particle_positions = particles.get_positions()
 
 In order to track the movement of particles over time, it's useful
-to 'dye' the particles based on their initial positions. This can
-be done by calling
+to 'dye' the particles based on their initial positions. Assuming that the
+keys of the particles dictionary were set as the particles' initial positions,
+this can be done by calling
 
 .. code-block:: python
 

particles/particles.py

@@ -248,7 +248,7 @@ def enforce_particle_boundaries(self):
             # -x boundary
             if p.x < myg.xmin:
                 if xlb in ["outflow", "neumann"]:
-                    del self.particles[k]
+                    del(self.particles[k])
                     continue
                 elif xlb == "periodic":
                     p.x = myg.xmax + p.x - myg.xmin
@@ -260,7 +260,7 @@ def enforce_particle_boundaries(self):
             # +x boundary
             if p.x > myg.xmax:
                 if xrb in ["outflow", "neumann"]:
-                    del self.particles[k]
+                    del(self.particles[k])
                     continue
                 elif xrb == "periodic":
                     p.x = myg.xmin + p.x - myg.xmax
@@ -272,7 +272,7 @@ def enforce_particle_boundaries(self):
             # -y boundary
             if p.y < myg.ymin:
                 if ylb in ["outflow", "neumann"]:
-                    del self.particles[k]
+                    del(self.particles[k])
                     continue
                 elif ylb == "periodic":
                     p.y = myg.ymax + p.y - myg.ymin
@@ -284,7 +284,7 @@ def enforce_particle_boundaries(self):
             # +y boundary
             if p.y > myg.ymax:
                 if yrb in ["outflow", "neumann"]:
-                    del self.particles[k]
+                    del(self.particles[k])
                     continue
                 elif yrb == "periodic":
                     p.y = myg.ymin + p.y - myg.ymax