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

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

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']
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']
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.

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']
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.