visualisation

existing classes

pylj comes with four different methods for visualising the simulation that is taking place:

  • JustCell
  • RDF
  • Scattering
  • Interactions
  • Energy

Full information about the existing classes can be found in the pylj.sample class documentation.

building your own class

Using the inbuild tools it is straightforward to build your own custom sample class, or to have students design their own.

Each sample class consists of at least an __init__ function and an update function. The __init__ function should select the number of panes in the visualisation environment by calling the sample.environment(n) function and setup the various windows using the different setup functions. The update function then updates the panes each time it is called, this function should consist of a series of update functions related to each pane. A commented example of the JustCell sample class is shown below.

class JustCell(object):
    """The JustCell class will plot just the particle positions.
    This is a simplistic sampling class for quick visualisation.

    Parameters
    ----------
    system: System
        The whole system information.
    """
    def __init__(self):
        # First the fig and ax must be defined. These are the
        # Matplotlib.figure.Figure object for the whole
        # visualisation environment and the axes object (or
        # array of axes objects) related to the individual panes.
        fig, ax = environment(1)

        # This is a setup function (detailed below) for the
        # particle positions
        setup_cellview(ax, system)

        # Generally looks better with the tight_layout function
        # called
        plt.tight_layout()

        # The Matplotlib.figure.Figure and axes object are set to
        # self variables for the class
        self.ax = ax
        self.fig = fig

    def update(self, system):
        """This updates the visualisation environment. Often this
        can be slower than the cythonised force calculation so
        use this wisely.

        Parameters
        ----------
        system: System
            The whole system information.
        """
        # This is the update function (detailed below) for the
        # particle positions
        update_cellview(self.ax, system)

        # The use of the `%matplotlib notebook' magic function in
        # the Jupyter notebook means that the canvas must be
        # redrawn
        self.fig.canvas.draw()

The setup_cellview and update_cellview functions have the following form.

def setup_cellview(ax, system):
    """Builds the particle position visualisation pane.

    Parameters
    ----------
    ax: Axes object
        The axes position that the pane should be placed in.
    system: System
        The whole system information.
    """
    # Assign the particles x and y coordinates to new lists
    xpos = system.particles['xposition']
    ypos = system.particles['yposition']

    # This simply defines the size of the particle such that
    # it is proportional to the box size
    mk = (1052.2 / (system.box_length - 0.78921) - 1.2174)

    # Plot the initial positions of the particles
    ax.plot(xpos, ypos, 'o', markersize=mk,
            markeredgecolor='black', color='#34a5daff')

    # Make the box the right size and remove the ticks
    ax.set_xlim([0, system.box_length])
    ax.set_ylim([0, system.box_length])
    ax.set_xticks([])
    ax.set_yticks([])

def update_cellview(ax, system):
    """Updates the particle positions visualisation pane.

    Parameters
    ----------
    ax: Axes object
        The axes position that the pane should be placed in.
    system: System
        The whole system information.
    """
    # Assign the particles x and y coordinates to new lists
    xpos = system.particles['xposition']
    ypos = system.particles['yposition']

    # The plotted data is accessed as an object in the axes
    # object
    line = ax.lines[0]
    line.set_ydata(ypos)
    line.set_xdata(xpos)

Hopefully, it is clear how a custom enivornment could be created. Currently there are functions to setup and update the following panes:

  • cellview: the particle positions
  • rdfview: the radial distribution function
  • diffview: the scattering profile
  • msdview: the mean squared deviation against time
  • pressureview: the instantaneous pressure against time
  • tempview: the instantaneous temperature against time
  • forceview: the total force against time
  • energyview: the total energy against time

For those plotted against time, the samples are stored as np.arrays in the System object. To design a new sampling pane based on a different variable it may be necessary to impliment this in the System class, and the sampling of it would be added to the sample function in the particular module being used e.g. md.