class Voronoi(*args, **kwargs)[source]#

Random network formed by Voronoi tessellation of arbitrary base points.

  • points (array_like or int) – Can either be an N-by-D array of point coordinates which will be used directly, or a scalar value indicating the number of points to generate. If 3D points are supplied, and a 2D shape is specified, then the z-coordinate is ignored.See Notes for more details.

  • shape (array_like) –

    The size and shape of the domain:



    [x, y, z]

    A 3D cubic domain of dimension x, y and z

    [x, y, 0]

    A 2D square domain of size x by y

  • trim (bool, optional) – If True then all Voronoi vertices laying outside the domain will be removed.

  • reflect (bool, optional) – If True then the base points will be reflected across all the faces of the domain prior to performing the tessellation. This feature is best combined with trim=True to make nice flat faces on all sides of the domain.

  • f (float) – The fraction of points which should be reflected. The default is 1 which reflects all the points in the domain, but this can lead to a lot of unnecessary points, so setting to 0.1 or 0.2 helps speed, but risks that the tessellation may not have smooth faces if not enough points are reflected.

  • relaxation (int) – The number of time to iteratively relax the base points by moving them to the centroid of their respective Voronoi hulls. The default it 0.

  • settings (dataclass-like or dict, optional) – User defined settings for the object to override defaults. Can be a dataclass-type object with settings stored as attributes or a python dicionary of key-value pairs. Settings are stored in the settings attribute of the object.

  • name (str, optional) – A unique name to assign to the object for easier identification. If not given one will be generated.


These points are used by the Voronoi tessellation, meaning these points will each lie in the center of a Voronoi cell, so they will not be the pore centers. The number of pores in the returned network will greater that the number of points supplied or requested.

It is also possible to generate circular [r, 0], cylindrical [r, z], and spherical domains [r], but this feature does not quite work as desired. It does not produce a truly clean outer surface since the tessellation are conducted in cartesian coordinates, so the circular and spherical surfaces have artifacts. Scipy recently added the ability to do tessellations on spherical surfaces, for geological applications, but this is not flexible enough, yet.


Shortcut to retrieve the number of pores in the domain


Shortcut to retrieve the number of throats in the domain


Shortcut to retrieve the indices of all pores


Shortcut to retrieve the indices of all throats


Adjacency matrix in the specified sparse format, with throat IDs indicating the non-zero values.


Returns the connectivity matrix of the network.


Returns the list of pore coordinates of the network.


Incidence matrix in the specified sparse format, with pore IDs indicating the non-zero values.


Shortcut to retrieve a handle to the network object associated with the


This attribute stores ‘scalar’ data that can be used by pore-scale models.



add_model(propname, model[, domain, regen_mode])

Add a pore-scale model to the object, along with the desired arguments

add_model_collection(models[, domain, ...])

Add a collection of several models at once

create_adjacency_matrix([weights, fmt, ...])

Generates a weighted adjacency matrix in the desired sparse format

create_incidence_matrix([weights, fmt, ...])

Creates a weighted incidence matrix in the desired sparse format

filter_by_label([pores, throats, labels, mode])

Returns which of the supplied pores (or throats) has the specified label(s)

find_connected_pores([throats, flatten, mode])

Return a list of pores connected to the given list of throats

find_connecting_throat(P1, P2)

Return the throat index connecting pairs of pores.

find_nearby_pores(pores, r[, flatten, ...])

Find all pores within a given radial distance of the input pore(s) regardless of whether or not they are toplogically connected.

find_neighbor_pores(pores[, mode, flatten, ...])

Returns a list of pores that are direct neighbors to the given pore(s)

find_neighbor_throats(pores[, mode, ...])

Returns a list of throats neighboring the given pore(s)


Adjacency matrix in the specified sparse format, with throat IDs indicating the non-zero values.


Fetches an Nt-by-3 array of the requested property


Incidence matrix in the specified sparse format, with pore IDs indicating the non-zero values.

interpolate_data(propname[, mode])

Generates an array of the requested pore/throat data by interpolating the neighboring throat/pore data.

labels([pores, throats, element, mode])

Returns a list of labels present on the object

num_neighbors(pores[, mode, flatten])

Returns the number of neigbhoring pores for each given input pore

num_pores([labels, mode])

Returns the number of pores of the specified labels

num_throats([labels, mode])

Return the number of throats of the specified labels

pores([labels, mode, asmask])

Returns pore indicies where given labels exist, according to the logic specified by the mode argument.


Retrieves a list of keys that contain numerical data (i.e. "properties").

regenerate_models([propnames, exclude])

Runs all the models stored in the object's models attribute

run_model(propname[, domain])

Runs the requested model and places the result into the correct locations

set_label(label[, pores, throats, mode])

Creates or updates a label array

throats([labels, mode, asmask])

Returns throat locations where given labels exist, according to the logic specified by the mode argument.


Converts a boolean mask to pore or throat indices

to_mask([pores, throats])

Generates a boolean mask with True values in the given locations