Getting Started

Requirements

Software: pytrax only relies on a few core python modules including Numpy and matplotlib, among others. These packages can be difficult to install from source, so it’s highly recommended to download the Anaconda Python Distrubution install for your platform, which will install all of these packages for you (and many more!). Once this is done, you can then run the installation of pytrax as described in the next section.

Hardware: Although there are no technical requirements, it must be noted that working with large images (>500**3) requires a substantial computer, with perhaps 16 or 32 GB of RAM. You can work on small images using normal computers to develop work flows, then size up to a larger computer for application on larger images.

Installation

pytrax is available on the Python Package Index (PyPI) and can be installed with the usual pip command as follows:

pip install pytrax

When installing in this way, the source code is stored somewhere deep within the Python installation folder, so it’s not convenient to play with or alter the code. If you wish to customize the code, then it might be better to download the source code from github into a personal directory (e.g C:\pytrax) then install as follows:

pip install -e C:\pytrax

The ‘-e’ argument means that the package is ‘editable’ so any changes you make to the code will be available the next time that pytrax is imported.

Basic Usage

To use pytrax simply import it at the Python prompt:

>>> import pytrax as pt

At the moment the package is very lightweight and it is expected that users have their own images to analyze. For testing purposes we make use of another one of our packages called PoreSpy. As well as having lots of image analysis tools for porous media, PoreSpy also contains an image generators module to produce a sample image as follows:

>>> import porespy as ps
>>> image = ps.generators.blobs(shape=[100, 100])

Running the random walk simulation to estimate the tortuosity tensor is then completed with a few extra commands:

>>> rw = pt.RandomWalk(image)
>>> rw.run(nt=1000, nw=1000, same_start=False, stride=1, num_proc=None)

Here the RandomWalk class is instantiated with the image that we generated and run with some parameters: nt is the number of time steps, nw is the number of walkers, same_start sets the walkers to have the same starting position in the image and is False (by default), stride is the number of steps between successive saves for calculations and output and num_proc is the number of parallel processors to use (defaulting to half the number available).

Plotting Results

pytrax has some built in plotting functionality to plot the coordinates of the walkers and also the mean square displacement vs. time which can be viewed with the following commands:

>>> rw.plot_walk_2d(check_solid=True, data='t')
>>> rw.plot_msd()

The first plotting function plots the image and the walker steps and is colored by time step, changing the data argument to be w changes the color to walker index. The check_solid argument checks that the solid voxels in the image are not walked upon which is useful when changes to the code are made as a quick sense check. The walkers are free to leave the original image providing that there is a porous pathway at the edges. When this happens they are treated to be travelling in a reflected domain and the plotting function also displays this. The second plotting function shows the mean and axial square displacement and applies linear regression to fit a straight line with intercept through zero. The gradient of the slope is inversely proportional to the tortuosity of the image in that direction. This follows the definition of tortuosity being the ratio of diffusivity in open space to diffusivity in the porous media.

Exporting Results

For 3D images the plot_walk_2d function can be used to view a slice of the walk and image, however, for better visualization it is recommended to use the export function and view the results in Paraview. A tutorial on how to do this is provided but the following function will export the image and walker data:

>>> rw.export_walk(image=None, path=None, sub='data', prefix='rw_', sample=1)

The image argument optionally lets you export the original image or the larger reflected image which are both stored on the rw object as rw.im and rw.im_big, respectively. Leaving the argument as None will not export any image. path is the directory to save the data and when set to None will default to the current working directory, sub creates a subfolder under the path directory to save the data in and defaults to data, prefix gives all the data a prefix and defaults to rw_ and finally sample is a down-sampling factor which in addition to the stride function in the run command will only output walker coordinates for time steps that are multiples of this number.