drainage(im, voxel_size, pc=None, inlets=None, outlets=None, residual=None, bins=25, delta_rho=1000, g=9.81, sigma=0.072, theta=180)[source]#

Simulate drainage using image-based sphere insertion, optionally including gravity

  • im (ndarray) – The image of the porous media with True values indicating the void space.

  • voxel_size (float) – The resolution of the image in meters per voxel edge.

  • pc (ndarray, optional) – An array containing precomputed capillary pressure values in each voxel. If not provided then the Washburn equation is used with the provided values of sigma and theta. If the image is 2D only 1 principle radii of curvature is included.

  • inlets (ndarray (default = x0)) – A boolean image the same shape as im, with True values indicating the inlet locations. See Notes. If not specified it is assumed that the invading phase enters from the bottom (x=0).

  • outlets (ndarray, optional) – Similar to inlets except defining the outlets. This image is used to assess trapping. If not provided then trapping is ignored, otherwise a mask indicating which voxels were trapped is included amoung the returned data.

  • residual (ndarray, optional) – A boolean array indicating the locations of any residual defending phase. This is added to the intermediate image prior to trimming disconnected clusters, so will create connections to some clusters that would otherwise be removed. The residual phase is indicated in the final image by -np.inf values, since there are invaded at all applied capillary pressures.

  • bins (int or array_like (default = 25)) – The range of pressures to apply. If an integer is given then bins will be created between the lowest and highest pressures in the pc. If a list is given, each value in the list is used directly in order.

  • delta_rho (float (default = 997)) – The density difference between the invading and defending phases. Note that if air is displacing water this value should be -997 (1-998).

  • g (float (default = 9.81)) – The gravitational constant prevailing for the simulation. The default is 9.81. If the domain is on an angle, such as a tilted micromodel, this value should be scaled appropriately by the user (i.e. g = 9.81 sin(alpha) where alpha is the angle relative to the horizonal). Setting this value to zeor removes any gravity effects.

  • sigma (float (default = 0.072)) – The surface tension of the fluid pair. If pc is provided this is ignored.

  • theta (float (defaut = 180)) – The contact angle of the sytem in degrees. If pc is provded this is ignored.


results – A dataclass-like object with the following attributes:




A numpy array with each voxel value indicating the capillary pressure at which it was invaded


A numpy array with each voxel value indicating the global saturation value at the point it was invaded


1D array of capillary pressure values that were applied


1D array of non-wetting phase saturations for each applied value of capillary pressure (pc).

Return type:

Results object


  • The direction of gravity is always towards the x=0 axis

  • This algorithm has only been tested for gravity stabilized configurations, meaning the more dense fluid is on the bottom. Be sure that inlets are specified accordingly.


Click here to view online example.