Base

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

Bases: dict

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

Parameters
  • 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

Notes

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

Functionality

props

List of keys containing numerical arrays

labels

List of key containing boolean arrays

pores

throats

Returns pore / throat indices that have given labels

Ps, Ts

Indices for ALL pores and throats on object

num_pores ,

num_throats

Counts the number of pores or throats with a given label

Np, Nt

Total number of pores and throats on the object

tomask

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

toindices

Converts a boolean mask to pore or throat indices

map_pores ,

map_throats

Given indices on object B returns corresponding indices on object A

interleave_data

Fetches data from associated objects into a single array

interpolate_data

Given pore or throat data, interpolate the other

filter_by_label

Given indices find those with specific labels

show_hist

Method for quickly plotting histograms of data

check_data_health

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:

Attribute

Functionality

name

The string name of the object, unique to each Project

settings

A dictionary containing various setting values

project

A handle to the Project containing the object

Examples

It is possible to create an instance of Base, although it is not very useful except for demonstration purposes as done here.

>>> import openpnm as op
>>> obj = op.core.Base(Np=4, Nt=5)

Now query the object for its basic properties:

>>> obj.Np, obj.Nt  # Number of pores and throats
(4, 5)

Add a label to the object, as a boolean with True where the label applies:

>>> obj['pore.new_label'] = [ True, False, False, True]

See list of available labels and confirm new_label was added:

>>> print(obj.labels())
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
1     : pore.all
2     : pore.new_label
3     : throat.all
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――

Use the label to fetch pores where it was applied:

>>> Ps = obj.pores('new_label')
>>> print(Ps)
[0 3]

Find the number of pores with label:

>>> print(obj.num_pores('new_label'))
2

Convert between indices and boolean mask

>>> mask = obj.tomask(throats=[0, 2, 4])
>>> print(mask)
[ True False  True False  True]
>>> inds = obj.toindices(mask)
>>> print(inds)
[0 2 4]
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

check_data_health()[source]

Check the health of pore and throat data arrays.

Returns

health – A basic dictionary with an added health attribute that is True if all entries in the dict are deemed healthy (empty lists), or False otherwise.

Return type

HealthDict object

Examples

>>> import openpnm
>>> pn = openpnm.network.Cubic(shape=[5, 5, 5])
>>> h = pn.check_data_health()
>>> h.health
True
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’).

Parameters
  • 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’

Notes

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.

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[5, 5, 5])
>>> len(pn.labels())  # There are 10 total labels on the network
12
>>> pn.clear(mode='labels')
>>> len(pn.labels())  # Kept only 'pore.all' and 'throat.all'
2
>>> 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
4
>>> pn.clear(mode='labels')
>>> 'pore.'+geom.name in pn.keys()  # The geometry labels were kept
True
>>> len(pn.props())  # The network has two properties
2
>>> pn.clear(element='pore', mode='props')
>>> 'pore.coords' in pn.keys()  # The pore property was removed
True
>>> pn.clear()  # Remove everything except protected labels and arrays
>>> print(sorted(list(pn.keys(element='pore', mode='all'))))
['pore.all', 'pore.coords', 'pore.geo1']
filter_by_label(pores=[], throats=[], labels=None, mode='or')[source]

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

Parameters
  • pores (array_like) – List of pores or throats to be filtered

  • throats (or) – List of pores or throats to be filtered

  • labels (list of strings) – The labels to apply as a filter

  • mode (string) –

    Controls how the filter is applied. Options include:

    ’or’, ‘union’, ‘any’: (default) Returns a list of the given locations where any of the given labels exist.

    ’and’, ‘intersection’, ‘all’: Only locations where all the given labels are found.

    ’xor’, ‘exclusive_or’: Only locations where exactly one of the given labels are found.

    ’nor’, ‘none’, ‘not’: Only locations where none of the given labels are found.

    ’nand’ : Only locations with some but not all of the given labels are returned.

    ’xnor’ : Only locations with more than one of the given labels are returned.

Returns

  • A list of pores (or throats) that have been filtered according the

  • given criteria. The returned list is a subset of the received list of

  • pores (or throats).

See also

pores, throats

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[5, 5, 5])
>>> pn.filter_by_label(pores=[0, 1, 25, 32], labels='left')
array([0, 1])
>>> Ps = pn.pores(['top', 'bottom', 'back'], mode='or')
>>> pn.filter_by_label(pores=Ps, labels=['top', 'back'],
...                    mode='and')
array([ 24,  49,  74,  99, 124])
get_conduit_data(prop, mode='mean')[source]

Combined requested data into a single 3-column array

Parameters
  • 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)

Returns

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

Return type

ndarray

interleave_data(prop)[source]

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

Parameters

prop (string) – The property name to be retrieved

Returns

Return type

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

Notes

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.

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[2, 2, 2])
>>> Ps = pn['pore.top']
>>> 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)

Parameters
  • 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’.

Returns

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

Return type

ND-array

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[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.

Parameters
  • 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

Notes

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’.)

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic([5, 5, 5])
>>> pn.keys(mode='props')  # Get all props
['pore.coords', 'throat.conns']
>>> pn.keys(mode='props', element='pore')  # Get only pore props
['pore.coords']
labels(pores=[], throats=[], element=None, mode='union')[source]

Returns a list of labels present on the object

Additionally, this function can return labels applied to a specified set of pores or throats

Parameters
  • element (string) – Controls whether pore or throat labels are returned. If empty then both are returned (default).

  • throats) (pores (or) – The pores (or throats) whose labels are sought. If left empty a list containing all pore and throat labels is returned.

  • mode (string, optional) –

    Controls how the query should be performed. Only applicable when pores or throats are specified:

    ’or’, ‘union’, ‘any’: (default) Returns the labels that are assigned to any of the given locations.

    ’and’, ‘intersection’, ‘all’: Labels that are present on all the given locations.

    ’xor’, ‘exclusive_or’ : Labels that are present on only one of the given locations.

    ’nor’, ‘none’, ‘not’: Labels that are not present on any of the given locations.

    ’nand’: Labels that are present on all but one of the given locations

    ’xnor’: Labels that are present on more than one of the given locations. ‘nxor’ is also accepted.

Returns

  • A list containing the labels on the object. If pores or

  • throats are given, the results are filtered according to the

  • specified mode.

See also

props, keys

Notes

Technically, ‘nand’ and ‘xnor’ should also return pores with none of the labels but these are not included. This makes the returned list more useful.

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[5, 5, 5])
>>> pn.labels(pores=[11, 12])
['pore.all', 'pore.internal', 'pore.left', 'pore.surface']
map_pores(pores, origin, filtered=True)[source]

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

Parameters
  • pores (array_like) – The indices of the pores on the object specifiedin origin

  • origin (OpenPNM Base object) – The object corresponding to the indices given in pores

  • filtered (boolean (default is True)) – If True then a ND-array of indices is returned with missing indices removed, otherwise a named-tuple containing both the indices and a boolean mask with False indicating which locations were not found.

Returns

  • Pore indices on the calling object corresponding to the same pores

  • on the origin object. Can be an array or a tuple containing an

  • array and a mask, depending on the value of filtered.

See also

pores, map_throats

map_throats(throats, origin, filtered=True)[source]

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

Parameters
  • throats (array_like) – The indices of the throats on the object specified in origin

  • origin (OpenPNM Base object) – The object corresponding to the indices given in throats

  • filtered (boolean (default is True)) – If True then a ND-array of indices is returned with missing indices removed, otherwise a named-tuple containing both the indices and a boolean mask with False indicating which locations were not found.

Returns

  • Throat indices on the calling object corresponding to the same throats

  • on the origin object. Can be an array or a tuple containing an

  • array and a mask, depending on the value of filtered.

See also

throats, map_pores

property network

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

num_pores(labels='all', mode='or')[source]

Returns the number of pores of the specified labels

Parameters
  • labels (list of strings) – The pore labels that should be included in the count. If not supplied, all pores are counted.

  • labels – Label of pores to be returned

  • mode (string, optional) –

    Specifies how the count should be performed. The options are:

    ’or’, ‘union’, ‘any’ : (default) Pores with one or more of the given labels are counted.

    ’and’, ‘intersection’, ‘all’ : Pores with all of the given labels are counted.

    ’xor’, ‘exclusive_or’ : Pores with only one of the given labels are counted.

    ’nor’, ‘none’, ‘not’ : Pores with none of the given labels are counted.

    ’nand’ : Pores with some but not all of the given labels are counted.

    ’xnor’ : Pores with more than one of the given labels are counted.

Returns

Np – Number of pores with the specified labels

Return type

int

See also

num_throats, count

Notes

Technically, ‘nand’ and ‘xnor’ should also count pores with none of the labels, however, to make the count more useful these are not included.

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[5, 5, 5])
>>> pn.num_pores()
125
>>> pn.num_pores(labels=['top'])
25
>>> pn.num_pores(labels=['top', 'front'], mode='or')
45
>>> pn.num_pores(labels=['top', 'front'], mode='xnor')
5
num_throats(labels='all', mode='union')[source]

Return the number of throats of the specified labels

Parameters
  • labels (list of strings, optional) – The throat labels that should be included in the count. If not supplied, all throats are counted.

  • mode (string, optional) –

    Specifies how the count should be performed. The options are:

    ’or’, ‘union’, ‘any’ : (default) Throats with one or more of the given labels are counted.

    ’and’, ‘intersection’, ‘all’ : Throats with all of the given labels are counted.

    ’xor’, ‘exclusive_or’ : Throats with only one of the given labels are counted.

    ’nor’, ‘none’, ‘not’ : Throats with none of the given labels are counted.

    ’nand’ : Throats with some but not all of the given labels are counted.

    ’xnor’ : Throats with more than one of the given labels are counted.

Returns

Nt – Number of throats with the specified labels

Return type

int

See also

num_pores, count

Notes

Technically, ‘nand’ and ‘xnor’ should also count throats with none of the labels, however, to make the count more useful these are not included.

pores(labels='all', mode='or', asmask=False, target=None)[source]

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

Parameters
  • labels (string or list of strings) – The label(s) whose pores locations are requested. This argument also accepts ‘*’ for wildcard searches.

  • mode (string) –

    Specifies how the query should be performed. The options are:

    ’or’, ‘union’, ‘any’ : (default) Pores with one or more of the given labels are returned.

    ’and’, ‘intersection’, ‘all’ : Pores with all of the given labels are returned.

    ’xor’, ‘exclusive_or’ : Pores with only one of the given labels are returned.

    ’nor’, ‘none’, ‘not’ : Pores with none of the given labels are returned.

    ’nand’ : Pores with not all of the given labels are returned.

    ’xnor’ : Pores with more than one of the given labels are returned.

  • asmask (boolean) – If True then a boolean array of length Np is returned with True values indicating the pores that satisfy the query.

  • target (OpenPNM Base object) – If given, the returned indices will be indexed relative to the target object. This can be used to determine how indices on one object map onto another object.

Returns

  • A Numpy array containing pore indices filtered by the logic specified

  • in mode.

See also

throats, map_pores

Notes

Technically, nand and xnor should also return pores with none of the labels but these are not included. This makes the returned list more useful.

To perform more complex or compound queries, you can opt to receive the result a a boolean mask (asmask=True), then manipulate the arrays manually.

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[5, 5, 5])
>>> Ps = pn.pores(labels=['top', 'back'], mode='union')
>>> Ps[:5]  # Look at first 5 pore indices
array([ 4,  9, 14, 19, 20])
>>> pn.pores(labels=['top', 'back'], mode='xnor')
array([ 24,  49,  74,  99, 124])
props(element=None, mode='all', deep=False)[source]

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

Parameters
  • 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.

Returns

  • 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

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[3, 3, 3])
>>> pn.props('pore')
['pore.coords']
>>> pn.props('throat')
['throat.conns']
>>> pn.props()
['pore.coords', 'throat.conns']
set_label(label, pores=None, throats=None, mode='add')[source]

Creates or updates a label array

Parameters
  • label (string) – The label to apply to the specified locations

  • pores (array_like) – A list of pore indices or a boolean mask of where given label should be added or removed (see mode)

  • throats (array_like) – A list of throat indices or a boolean mask of where given label should be added or removed (see mode)

  • mode (string) –

    Controls how the labels are handled. Options are:

    ’add’ - Adds the given label to the specified locations while keeping existing labels (default)

    ’overwrite’ - Removes existing label from all locations before adding the label in the specified locations

    ’remove’ - Removes the given label from the specified locations leaving the remainder intact.

    ’purge’ - Removes the specified label from the object

show_hist(props=['pore.diameter', 'throat.diameter', 'throat.length'], bins=20, fontsize=14, **kwargs)[source]

Show a quick plot of key property distributions.

Parameters
  • 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.

Notes

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

throats(labels='all', mode='or', asmask=False, target=None)[source]

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

Parameters
  • labels (string or list of strings) – The throat label(s) whose locations are requested. If omitted, ‘all’ throat inidices are returned. This argument also accepts ‘*’ for wildcard searches.

  • mode (string) –

    Specifies how the query should be performed. The options are:

    ’or’, ‘union’, ‘any’ : (default) Throats with one or more of the given labels are returned.

    ’and’, ‘intersection’, ‘all’ : Throats with all of the given labels are returned.

    ’xor’, ‘exclusive_or’ : Throats with only one of the given labels are returned.

    ’nor’, ‘none’, ‘not’ : Throats with none of the given labels are returned.

    ’nand’ : Throats with not all of the given labels are returned.

    ’xnor’ : Throats with more than one of the given labels are returned.

  • asmask (boolean) – If True then a boolean array of length Nt is returned with True values indicating the throats that satisfy the query.

  • target (OpenPNM Base object) – If given, the returned indices will be indexed relative to the target object. This can be used to determine how indices on one object map onto another object.

Returns

  • A Numpy array containing throat indices filtered by the logic specified

  • in mode.

See also

pores, map_throats

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[3, 3, 3])
>>> Ts = pn.throats()
>>> Ts[0:5]  # Look at first 5 throat indices
array([0, 1, 2, 3, 4])
toindices(mask)[source]

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

Parameters

mask (array_like booleans) – A boolean array with True at locations where indices are desired. The appropriate indices are returned based an the length of mask, which must be either Np or Nt long.

Returns

  • A list of pore or throat indices corresponding the locations where

  • the received mask was True.

See also

tomask

Notes

This behavior could just as easily be accomplished by using the mask in pn.pores()[mask] or pn.throats()[mask]. This method is just a convenience function and is a complement to tomask.

tomask(pores=None, throats=None)[source]

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

Parameters

throats (pores or) – List of pore or throat indices. Only one of these can be specified at a time, and the returned result will be of the corresponding length.

Returns

  • A boolean mask of length Np or Nt with True in the specified pore or

  • throat locations.

See also

toindices

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[5, 5, 5])
>>> mask = pn.tomask(pores=[0, 10, 20])
>>> sum(mask)  # 3 non-zero elements exist in the mask (0, 10 and 20)
3
>>> len(mask)  # Mask size is equal to the number of pores in network
125
>>> mask = pn.tomask(throats=[0, 10, 20])
>>> len(mask)  # Mask is now equal to number of throats in network
300