class openpnm.algorithms.InvasionPercolation(*args, **kwargs)[source]

A classic/basic invasion percolation algorithm optimized for speed.


network (GenericNetwork) – The Network upon which the invasion will occur.


This algorithm uses a binary heap to store all a list of all accessible throats, sorted according to entry pressure. This means that item [0] in the heap is the most easily invaded throat, so looking up which throat to invade next is computationally trivial. In order to keep the list sorted new throats to the list takes more time, however, the heap data structure is very efficient at this. Interested users can consult the wikipedia page on binary heaps for more information.


Start by importing the usual packages:

>>> import openpnm as op
>>> import scipy as sp
>>> import matplotlib.pyplot as plt

Create 2D cubic network for easier visualizaiton:

>>> S = np.array([100, 100, 1])
>>> pn =, spacing=0.0001, name='pn11')

Add a basic geometry:

>>> geom = op.geometry.SpheresAndCylinders(network=pn, pores=pn.Ps, throats=pn.Ts)

Create an invading phase, and attach the capillary pressure model:

>>> water = op.phases.Water(network=pn)
>>> water.add_model(propname='throat.entry_pressure',
...                 model=op.models.physics.capillary_pressure.washburn)

Initialize an invasion percolation object and define inlets:

>>> ip = op.algorithms.InvasionPercolation(network=pn, phase=water)
>>> ip.set_inlets(pores=0)

After running the algorithm the invading phase configuration at a given saturation can be obtained and assigned to the phase object:

>>> water.update(ip.results(Snwp=0.5))

Because it was a 2D network it’s easy to quickly visualize the invasion pattern as an image for verification:


Because the network is 2D and cubic, an image can be generated with color corresponding to a value. The following plots the entire invasion sequence, and the water configuraiton at Snwp = 0.5.

plt.subplot(1, 2, 1)

plt.imshow(np.reshape(ip['pore.invasion_sequence'], newshape=S[S > 1]))

plt.subplot(1, 2, 2)

plt.imshow(np.reshape(water['pore.occupancy'], newshape=S[S > 1]))


A shortcut to query the total number of pores on the object


A shortcut to query the total number of throats on the object


A shortcut to get a list of all pores on the object


A shortcut to get a list of all throats on the object


String representing the name of the object


A shortcut to get a handle to the associated network.


A shortcut to get a handle to the associated project.


Dictionary containing object settings.



Apply trapping based on algorithm described by Y.

get_conduit_data(poreprop[, throatprop, mode])

Combines requested data into a single 3-column array.


Get the percolation data as the invader volume or number fraction vs the capillary capillary pressure.


Retrieves requested property from associated objects, to produce a full Np or Nt length array.

interpolate_data(propname[, mode])

Determines a pore (or throat) property as the average of it's neighboring throats (or pores)

map_pores(pores, origin[, filtered])

Given a list of pore on a target object, finds indices of those pores on the calling object

map_throats(throats, origin[, filtered])

Given a list of throats on a target object, finds indices of those throats on the calling object

plot_intrusion_curve([ax, num_markers])

Plot the percolation curve as the invader volume or number fraction vs the capillary capillary pressure.

props([element, mode, deep])

Returns a list containing the names of all defined pore or throat properties.


Returns the phase configuration at the specified non-wetting phase (invading phase) saturation.


Performs the algorithm.

set_inlets([pores, overwrite])

param pores

The list of inlet pores from which the Phase can enter the Network

show_hist([props, bins, fontsize])

Shows a quick plot of key property distributions.


Converts a boolean mask to a list of pore or throat indices.

to_mask([pores, throats])

Convert a list of pore or throat indices into a boolean mask of the correct length.

toindices(*args, **kwargs)

Brief explanation of tomask

tomask(*args, **kwargs)

Brief explanation of tomask