class Base(*args, **kwargs)[source]

Bases: dict

Contains methods for working with the data in the OpenPNM dict objects

  • project (OpenPNM Project object, optional) – The Project with which the object should be assigned. If not supplied then a new Project is created

  • name (string, optional) – The unique name of the object. If not given one will be generated.

  • Np (int, default is 0) – The total number of pores to be assigned to the object

  • Nt (int, default is 0) – The total number of throats to be assigned to the object


This Base class is used as the template for all other OpenPNM objects, including Networks, Geometries, Phases, Physics, and Algorithms. This class is a subclass of the standard dict so has the usual methods such as pop and keys, and has extra methods for working specifically with OpenPNM data. These are outlined briefly in the following table:

Method or Attribute



List of keys containing numerical arrays


List of key containing boolean arrays



Returns pore / throat indices that have given labels

Ps, Ts

Indices for ALL pores and throats on object

num_pores ,


Counts the number of pores or throats with a given label

Np, Nt

Total number of pores and throats on the object


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


Converts a boolean mask to pore or throat indices

map_pores ,


Given indices on object B returns corresponding indices on object A


Fetches data from associated objects into a single array


Given pore or throat data, interpolate the other


Given indices find those with specific labels


Method for quickly plotting histograms of data


Ensures all data arrays are valid and complete

In addition to the above methods, there are a few attributes which provide access to useful items:




The string name of the object, unique to each Project


A dictionary containing various setting values


A handle to the Project containing the object

property Np

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

property Nt

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

property Ps

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

property Ts

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

clear(element=None, mode='all')[source]

A subclassed version of the standard dict’s clear method. This can be used to selectively clear certain data from the object, including properties and/or labels. Importantly, it does NOT clear items that are required to maintain the integrity of the simulation. These are arrays that define the topology (ie. ‘pore.all’, ‘pore.coords’, ‘throat.all’, ‘throat.conns’), as well as arrays that indicate associations bewteen objects (ie. ‘pore.geo_01’).

  • element (string or list of strings) – Can be either ‘pore’ or ‘throat’, which specifies whether ‘pore’ and/or ‘throat’ arrays should be cleared. The default is both.

  • mode (string or list of strings) –

    This controls what is cleared from the object. Options are:

    ’props’ : Removes all numerical property values from the object dictionary

    ’model_data’ : Removes only numerical data that were produced by an associated model

    ’labels’ : Removes all labels from the object dictionary, except those relating to the pore and throat locations of associated objects

    ’all’ : Removes both ‘props’ and ‘labels’


If you wish to selectively remove some properties but not others, use something like del object['pore.blah'] at the Python prompt. This can also be done in a for-loop to remove a list of items.


>>> import openpnm as op
>>> pn =[5, 5, 5])
>>> len(pn.labels())  # There are 10 total labels on the network
>>> pn.clear(mode='labels')
>>> len(pn.labels())  # Kept only 'pore.all' and 'throat.all'
>>> geom = op.geometry.GenericGeometry(network=pn, pores=pn.Ps,
...                                    throats=pn.Ts, name='geo1')
>>> len(pn.labels())  # 2 new labels were added for geometry locations
>>> pn.clear(mode='labels')
>>> 'pore.' in pn.keys()  # The geometry labels were kept
>>> len(pn.props())  # The network has two properties
>>> pn.clear(element='pore', mode='props')
>>> 'pore.coords' in pn.keys()  # The pore property was removed
>>> pn.clear()  # Remove everything except protected labels and arrays
>>> print(sorted(list(pn.keys(element='pore', mode='all'))))
['pore.all', 'pore.coords', 'pore.geo1']
get_conduit_data(prop, mode='mean')[source]

Combined requested data into a single 3-column array

  • prop (string) – The dictionary key to the property of interest

  • mode (string) –

    How interpolation should be peformed for missing values. If values are present for both pores and throats, then this argument is ignored. The interpolate data method is used. Options are:

    • ’mean’ (default)

      Finds the mean value of the neighboring pores (or throats)

    • ’min’

      Finds the minimuem of the neighboring pores (or throats)

    • ’max’

      Finds the maximum of the neighboring pores (or throats)


conduit_data – An Nt-by-3 array with each column containg the requested property for each pore-throat-pore conduit.

Return type



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


prop (string) – The property name to be retrieved


Return type

A full length (Np or Nt) array of requested property values.


This makes an effort to maintain the data ‘type’ when possible; however when data are missing this can be tricky. Data can be missing in two different ways: A set of pores is not assisgned to a geometry or the network contains multiple geometries and data does not exist on all. Float and boolean data is fine, but missing ints are converted to float when nans are inserted.


>>> import openpnm as op
>>> pn =[2, 2, 2])
>>> Ps = pn['']
>>> Ts = pn.find_neighbor_throats(pores=Ps)
>>> g1 = op.geometry.GenericGeometry(network=pn, pores=Ps, throats=Ts)
>>> Ts = ~pn.tomask(throats=Ts)
>>> g2 = op.geometry.GenericGeometry(network=pn, pores=~Ps, throats=Ts)
>>> g1['pore.value'] = 1
>>> print(g1['pore.value'])
[1 1 1 1]
>>> print(g2['pore.value'])  # 'pore.value' is defined on g1, not g2
[nan nan nan nan]
>>> print(pn['pore.value'])
[nan  1. nan  1. nan  1. nan  1.]
>>> g2['pore.value'] = 20
>>> print(pn['pore.value'])
[20  1 20  1 20  1 20  1]
>>> pn['pore.label'] = False
>>> print(g1['pore.label'])  # 'pore.label' is defined on pn, not g1
[False False False False]
interpolate_data(propname, mode='mean')[source]

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

  • propname (string) – The dictionary key to the values to be interpolated.

  • mode (string) – The method used for interpolation. Options are ‘mean’ (default), ‘min’, and ‘max’.


vals – An array containing interpolated pore (or throat) data

Return type



>>> import openpnm as op
>>> pn =[3, 1, 1])
>>> pn['pore.value'] = [1, 2, 3]
>>> pn.interpolate_data('pore.value')
array([1.5, 2.5])
keys(element=None, mode=None, deep=False)[source]

This subclass works exactly like keys when no arguments are passed, but optionally accepts an element and a mode, which filters the output to only the requested keys.

The default behavior is exactly equivalent to the normal keys method.

  • element (string) – Can be either ‘pore’ or ‘throat’, which limits the returned list of keys to only ‘pore’ or ‘throat’ keys. If neither is given, then both are assumed.

  • mode (string (optional)) –

    Controls which keys are returned. Options are:

    ’labels’ : Limits the returned list of keys to only ‘labels’ (boolean arrays)

    ’props’ : Limits he return list of keys to only ‘props’ (numerical arrays).

    ’all’ : Returns both ‘labels’ and ‘props’. This is equivalent to sending a list of both ‘labels’ and ‘props’.

    If no mode is specified then the normal KeysView object is returned.

  • deep (Boolean) – If set to True then the keys on all associated subdomain objects are returned as well.

See also

props, labels


This subclass can be used to get dictionary keys of specific kinds of data. It’s use augments props and labels by returning a list containing both types, but possibly limited by element type (‘pores’ or ‘throats’.)


>>> import openpnm as op
>>> pn =[5, 5, 5])
>>> pn.keys(mode='props')  # Get all props
['pore.coords', 'throat.conns']
>>> pn.keys(mode='props', element='pore')  # Get only pore props
property network

A shortcut to get a handle to the associated network There can only be one so this works

props(element=None, mode='all', deep=False)[source]

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

  • element (string, optional) – Can be either ‘pore’ or ‘throat’ to specify what properties are returned. If no element is given, both are returned

  • mode (string, optional) –

    Controls what type of properties are returned. Options are:

    ’all’ : Returns all properties on the object (default)

    ’models’ : Returns only properties that are associated with a model

    ’constants’ : returns data values that were not generated by a model, but manaully created.

  • deep (Boolean) – If set to True then the props on all associated subdomain objects are returned as well.


  • A an alphabetically sorted list containing the string name of all

  • pore or throat properties currently defined. This list is an iterable,

  • so is useful for scanning through properties.

See also

labels, keys


>>> import openpnm as op
>>> pn =[3, 3, 3])
>>> pn.props('pore')
>>> pn.props('throat')
>>> pn.props()
['pore.coords', 'throat.conns']
show_hist(props=['pore.diameter', 'throat.diameter', 'throat.length'], bins=20, fontsize=14, **kwargs)[source]

Show a quick plot of key property distributions.

  • props (string or list of strings) – The pore and/or throat properties to be plotted as histograms. By default this function will show ‘pore.diameter’, ‘throat.diameter’, and ‘throat.length’.

  • bins (int or array_like) – The number of bins to use when generating the histogram. If an array is given they are used as the bin spacing instead.

  • fontsize (int) – Sets the font size temporarily. The default size of matplotlib is 10, which is too small for many screens. This function has a default of 22, which does not overwrite the matplotlib setting. Note that you can override matplotlib setting globally with matplotlib.rcParams['font.size'] = 22.


Other keyword arguments are passed to the matplotlib.pyplot.hist function.