Geometry Models

Overview of Submodule

This submodule contains pore-scale models that calculate geometrical properties. These models are to be added to a Geometry object.

Detailed Model Documentation

Pore size

The pore-size models in this sub-module are used to apply desired pore-size distributions to a pore network. Most of the models accept pore seeds, and then look-up pore-sizes from cumuative distribtions functions. There is also a model for finding the largest possible sphere that can be placed on each site.

equivalent_diameter(target, pore_volume='pore.volume', pore_shape='sphere')[source]

Calculates the diameter of a sphere or edge-length of a cube with same volume as the pore.

Parameters
  • target (OpenPNM Geometry Object) – The Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_volume (string) – The dictionary key containing the pore volume values

  • pore_shape (string) – The shape of the pore body to assume when back-calculating from volume. Options are ‘sphere’ (default) or ‘cube’.

Returns

D – Array containing pore diameter values.

Return type

NumPy ndarray

from_neighbor_throats(target, prop, mode='max')[source]

Adopt a value from the values found in neighboring throats

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • prop (string) – The dictionary key of the array containing the throat property to be used in the calculation.

  • mode (string) – Controls how the pore property is calculated. Options are ‘min’, ‘max’ and ‘mean’.

Returns

value – Array containing customized values based on those of adjacent throats.

Return type

ND-array

generic_distribution(target, func, seeds='pore.seed')[source]

Accepts an ‘rv_frozen’ object from the Scipy.stats submodule and returns values from the distribution for the given seeds

This uses the ppf method of the stats object

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seeds (string, optional) – The dictionary key on the Geometry object containing random seed values (between 0 and 1) to use in the statistical distribution.

  • func (object) – An ‘rv_frozen’ object from the Scipy.stats library with all of the parameters pre-specified.

Returns

values – Array containing random numbers based on given ppf.

Return type

NumPy ndarray

Examples

The following code illustrates the process of obtaining a ‘frozen’ Scipy stats object and adding it as a model:

>>> import scipy
>>> import numpy
>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[3, 3, 3])
>>> geo = op.geometry.GenericGeometry(network=pn, pores=pn.Ps, throats=pn.Ts)
>>> geo.add_model(propname='pore.seed',
...               model=op.models.geometry.pore_seed.random)

Now retrieve the stats distribution and add to geo as a model:

>>> stats_obj = scipy.stats.weibull_min(c=2, scale=.0001, loc=0)
>>> geo.add_model(propname='pore.size',
...               model=op.models.geometry.pore_size.generic_distribution,
...               seeds='pore.seed',
...               func=stats_obj)
>>> import matplotlib.pyplot as plt
>>> fig = plt.hist(stats_obj.ppf(q=numpy.random.rand(1000)), bins=50)
largest_sphere(target, fixed_diameter='pore.fixed_diameter', iters=5)[source]

Finds the maximum diameter pore that can be placed in each location without overlapping any neighbors.

This method iteratively expands pores by increasing their diameter to encompass half of the distance to the nearest neighbor. If the neighbor is not growing because it’s already touching a different neighbor, then the given pore will never quite touch this neighbor. Increating the value of iters will get it closer, but it’s case of [Zeno’s paradox](https://en.wikipedia.org/wiki/Zeno%27s_paradoxes) with each step cutting the remaining distance in half

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • fixed_diameter (string) – The dictionary key containing the pore diameter values already assigned to network, if any. If not provided a starting value is assumed as half-way to the nearest neighbor.

  • iters (integer) – The number of iterations to perform when searching for maximum diameter. This function iteratively grows pores until they touch their nearest neighbor, which is also growing, so this parameter limits the maximum number of iterations. The default is 10, but 5 is usally enough.

Returns

D – Array containing pore diameter values.

Return type

NumPy ndarray

Notes

This model looks into all pores in the network when finding the diameter. This means that when multiple Geometry objects are defined, it will consider the diameter of pores on adjacent Geometries. If no diameters have been assigned to these neighboring pores it will assume 0. If diameter value are assigned to the neighboring pores AFTER this model is run, the pores will overlap. This can be remedied by running this model again.

normal(target, scale, loc, seeds='pore.seed')[source]

Produces values from a Weibull distribution given a set of random numbers.

Parameters
  • target (OpenPNM Object) – The object with which this function as associated. This argument is required to (1) set number of values to generate (geom.Np or geom.Nt) and (2) provide access to other necessary values (i.e. geom[‘pore.seed’]).

  • seeds (string, optional) – The dictionary key on the Geometry object containing random seed values (between 0 and 1) to use in the statistical distribution.

  • scale (float) – The standard deviation of the Normal distribution

  • loc (float) – The mean of the Normal distribution

Returns

values – Array containing normally distributed random numbers.

Return type

NumPy ndarray

Examples

The following code illustrates the inner workings of this function, which uses the ‘norm’ method of the scipy.stats module. This can be used to find suitable values of ‘scale’ and ‘loc’.

>>> import scipy
>>> import numpy
>>> func = scipy.stats.norm(scale=.0001, loc=0.001)
>>> import matplotlib.pyplot as plt
>>> fig = plt.hist(func.ppf(q=numpy.random.rand(10000)), bins=50)
random(target, seed=None, num_range=[0, 1])[source]

Create an array of random numbers of a specified size.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seed (int) – The starting seed value to send to Scipy’s random number generator. The default is None, which means different distribution is returned each time the model is run.

  • num_range (list) – A two element list indicating the low and high end of the returned numbers.

Returns

values – Array containing uniformly-distributed random numbers.

Return type

NumPy ndarray

weibull(target, shape, scale, loc, seeds='pore.seed')[source]

Produces values from a Weibull distribution given a set of random numbers.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seeds (string, optional) – The dictionary key on the Geometry object containing random seed values (between 0 and 1) to use in the statistical distribution.

  • shape (float) – This controls the skewness of the distribution, with ‘shape’ < 1 giving values clustered on the low end of the range with a long tail, and ‘shape’ > 1 giving a more symmetrical distribution.

  • scale (float) – This controls the width of the distribution with most of values falling below this number.

  • loc (float) – Applies an offset to the distribution such that the smallest values are above this number.

Returns

values – Array containing random numbers based on Weibull distribution.

Return type

NumPy ndarray

Examples

The following code illustrates the inner workings of this function, which uses the ‘weibull_min’ method of the scipy.stats module. This can be used to find suitable values of ‘shape’, ‘scale’` and ‘loc’. Note that ‘shape’ is represented by ‘c’ in the actual function call.

>>> import scipy
>>> import numpy
>>> func = scipy.stats.weibull_min(c=1.5, scale=0.0001, loc=0)
>>> import matplotlib.pyplot as plt
>>> fig = plt.hist(func.ppf(q=numpy.random.rand(10000)), bins=50)

Pore volume

These models calculate pore volumes depending on the specified shape

circle(target, pore_diameter='pore.diameter')[source]

Calculate pore volume from diameter assuming a spherical pore body

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

cone(target, pore_diameter='pore.diameter')[source]

Calculates pore volume from diameter assuming a conical pore body.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray

cube(target, pore_diameter='pore.diameter')[source]

Calculate pore volume from diameter assuming a cubic pore body

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray

cylinder(target, pore_diameter='pore.diameter')[source]

Calculate pore volume from diameter assuming a cylindrical pore body with a height equal to its diameter.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray

effective(target, pore_volume='pore.volume', throat_volume='throat.volume')[source]

Calculate the effective pore volume for optional use in transient simulations. The effective pore volume is calculated by adding half the volume of all neighbouring throats to the pore volume.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_volume (string) – The dictionary key of the pore volume values

  • throat_volume (string) – The dictionary key of the throat volume values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray

pyramid(target, pore_diameter='pore.diameter')[source]

Calculates pore volume from diameter assuming a truncated pyramid pore body.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray

sphere(target, pore_diameter='pore.diameter')[source]

Calculate pore volume from diameter assuming a spherical pore body

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray

square(target, pore_diameter='pore.diameter')[source]

Calculate pore volume from diameter assuming a cubic pore body

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

trapezoid(target, pore_diameter='pore.diameter')[source]

Calculates pore volume from diameter assuming a trapezoidal pore body.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary geometric properties.

  • pore_diameter (string) – The dictionary key of the pore diameter values

Returns

value – Array containing pore volume values.

Return type

NumPy ndarray


Pore seed

Pore seed models are use to calculate random numbers for each pore, which can subsequently be used in statistical distributions to calculate actual pore sizes.

random(target, seed=None, num_range=[0, 1])[source]

Create an array of random numbers of a specified size.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seed (int) – The starting seed value to send to Scipy’s random number generator. The default is None, which means different distribution is returned each time the model is run.

  • num_range (list) – A two element list indicating the low and high end of the returned numbers.

Returns

values – Array containing uniformly-distributed random numbers.

Return type

NumPy ndarray

spatially_correlated(target, weights=None, strel=None)[source]

Generates pore seeds that are spatailly correlated with their neighbors.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • weights (list of ints, optional) – The [Nx,Ny,Nz] distances (in number of pores) in each direction that should be correlated.

  • strel (array_like, optional (in place of weights)) –

    The option allows full control over the spatial correlation pattern by specifying the structuring element to be used in the convolution.

    The array should be a 3D array containing the strength of correlations in each direction. Nonzero values indicate the strength, direction and extent of correlations. The following would achieve a basic correlation in the z-direction:

  • ::

    strel = np.array([[[0, 0, 0], [0, 0, 0], [0, 0, 0]],

    [[0, 0, 0], [1, 1, 1], [0, 0, 0]], [[0, 0, 0], [0, 0, 0], [0, 0, 0]]])

Returns

values – Array containing pore seed values.

Return type

NumPy ndarray

Notes

This approach uses image convolution to replace each pore seed in the geoemtry with a weighted average of those around it. It then converts the new seeds back to a random distribution by assuming they new seeds are normally distributed.

Because is uses image analysis tools, it only works on Cubic networks.

This is the appproached used by Gostick et al 2 to create an anistropic gas diffusion layer for fuel cell electrodes.

References

2

J. Gostick et al, Pore network modeling of fibrous gas diffusion layers for polymer electrolyte membrane fuel cells. J Power Sources v173, pp277–290 (2007)

Examples

>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[10, 10, 10])
>>> Ps, Ts = pn.Ps, pn.Ts
>>> geom = op.geometry.GenericGeometry(network=pn, pores=Ps, throats=Ts)
>>> mod = op.models.geometry.pore_seed.spatially_correlated
>>> geom.add_model(propname='pore.seed', model=mod, weights=[2, 2, 2])

Pore surface area

circle(target, pore_diameter='pore.diameter', throat_cross_sectional_area='throat.cross_sectional_area')[source]

Calculates internal surface area of pore bodies assuming they are circular then subtracts the area of the neighboring throats in a crude way, by simply considering the throat cross-sectional area, thus not accounting for the actual curvature of the intersection.

Parameters
  • target (GenericGeometry) – The Geometry object for which these values are being calculated. This controls the length of the calculated array, and also provides access to other necessary thermofluid properties.

  • pore_diameter (str) – The dictionary key to the pore diameter array.

  • throat_cross_sectional_area (str) – The dictionary key to the throat cross sectional area array. Throat areas are needed since their insection with the pore are removed from the computation.

Returns

value – Array containing pore surface area values.

Return type

NumPy ndarray

cube(target, pore_diameter='pore.diameter', throat_cross_sectional_area='throat.cross_sectional_area')[source]

Calculates internal surface area of pore bodies assuming they are cubes then subtracts the area of the neighboring throats.

Parameters
  • target (GenericGeometry) – The Geometry object for which these values are being calculated. This controls the length of the calculated array, and also provides access to other necessary thermofluid properties.

  • pore_diameter (string) – The dictionary key to the pore diameter array.

  • throat_cross_sectional_area (str) – The dictionary key to the throat cross sectional area array. Throat areas are needed since their insection with the pore are removed from the computation.

Returns

value – Array containing pore surface area values.

Return type

NumPy ndarray

sphere(target, pore_diameter='pore.diameter', throat_cross_sectional_area='throat.cross_sectional_area')[source]

Calculates internal surface area of pore bodies assuming they are spherical then subtracts the area of the neighboring throats in a crude way, by simply considering the throat cross-sectional area, thus not accounting for the actual curvature of the intersection.

Parameters
  • target (GenericGeometry) – The Geometry object for which these values are being calculated. This controls the length of the calculated array, and also provides access to other necessary thermofluid properties.

  • pore_diameter (str) – The dictionary key to the pore diameter array.

  • throat_cross_sectional_area (str) – The dictionary key to the throat cross sectional area array. Throat areas are needed since their insection with the pore are removed from the computation.

Returns

value – Array containing pore surface area values.

Return type

NumPy ndarray

square(target, pore_diameter='pore.diameter', throat_cross_sectional_area='throat.cross_sectional_area')[source]

Calculates internal surface area of pore bodies assuming they are squares then subtracts the area of the neighboring throats.

Parameters
  • target (GenericGeometry) – The Geometry object for which these values are being calculated. This controls the length of the calculated array, and also provides access to other necessary thermofluid properties.

  • pore_diameter (str) – The dictionary key to the pore diameter array.

  • throat_cross_sectional_area (str) – The dictionary key to the throat cross sectional area array. Throat areas are needed since their insection with the pore are removed from the computation.

Returns

value – Array containing pore surface area values.

Return type

NumPy ndarray


Throat cross sectional area

cuboid(target, throat_diameter='throat.diameter')[source]

Calculate throat cross-sectional area for a cuboid throat

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – Dictionary key of the throat diameter values

Returns

value – Array containing throat cross-sectional area values.

Return type

NumPy ndarray

cylinder(target, throat_diameter='throat.diameter')[source]

Calculate throat cross-sectional area for a cylindrical throat

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – Dictionary key of the throat diameter values

Returns

value – Array containing throat cross-sectional area values.

Return type

NumPy ndarray

rectangle(target, throat_diameter='throat.diameter')[source]

Calculate throat cross-sectional area for a rectangular throat

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – Dictionary key of the throat diameter values


Throat size

equivalent_diameter(target, throat_area='throat.area', throat_shape='circle')[source]

Calculates the diameter of a cirlce or edge-length of a sqaure with same area as the throat.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • thorat_area (string) – The dictionary key to the throat area values

  • throat_shape (string) – The shape cross-sectional shape of the throat to assume when back-calculating from the area. Options are ‘circle’ (default) or ‘square’.

Returns

value – Array containing throat equivalent diameter.

Return type

NumPy ndarray

from_neighbor_pores(target, prop='pore.diameter', mode='min')[source]

Adopt a value based on the values in neighboring pores

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • prop (string) – The dictionary key to the array containing the pore property to be used in the calculation.

  • mode (string) – Controls how the throat property is calculated. Options are ‘min’, ‘max’ and ‘mean’.

  • ignore_nans (boolean (default is True)) – If True the result will ignore nans in the neighbors

Returns

value – Array containing customized values based on those of adjacent pores.

Return type

ND-array

generic_distribution(target, func, seeds='throat.seed')[source]

Accepts an ‘rv_frozen’ object from the Scipy.stats submodule and returns values from the distribution for the given seeds

This uses the ppf method of the stats object

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seeds (string, optional) – The dictionary key on the Geometry object containing random seed values (between 0 and 1) to use in the statistical distribution.

  • func (object) – An ‘rv_frozen’ object from the Scipy.stats library with all of the parameters pre-specified.

Returns

values – Array containing random numbers based on given ppf.

Return type

NumPy ndarray

Examples

The following code illustrates the process of obtaining a ‘frozen’ Scipy stats object and adding it as a model:

>>> import scipy
>>> import numpy
>>> import openpnm as op
>>> pn = op.network.Cubic(shape=[3, 3, 3])
>>> geo = op.geometry.GenericGeometry(network=pn, pores=pn.Ps, throats=pn.Ts)
>>> geo.add_model(propname='pore.seed',
...               model=op.models.geometry.pore_seed.random)

Now retrieve the stats distribution and add to geo as a model:

>>> stats_obj = scipy.stats.weibull_min(c=2, scale=.0001, loc=0)
>>> geo.add_model(propname='pore.size',
...               model=op.models.geometry.pore_size.generic_distribution,
...               seeds='pore.seed',
...               func=stats_obj)
>>> import matplotlib.pyplot as plt
>>> fig = plt.hist(stats_obj.ppf(q=numpy.random.rand(1000)), bins=50)
normal(target, scale, loc, seeds='throat.seed')[source]

Produces values from a Weibull distribution given a set of random numbers.

Parameters
  • target (OpenPNM Object) – The object with which this function as associated. This argument is required to (1) set number of values to generate (geom.Np or geom.Nt) and (2) provide access to other necessary values (i.e. geom[‘pore.seed’]).

  • seeds (string, optional) – The dictionary key on the Geometry object containing random seed values (between 0 and 1) to use in the statistical distribution.

  • scale (float) – The standard deviation of the Normal distribution

  • loc (float) – The mean of the Normal distribution

Returns

values – Array containing normally distributed random numbers.

Return type

NumPy ndarray

Examples

The following code illustrates the inner workings of this function, which uses the ‘norm’ method of the scipy.stats module. This can be used to find suitable values of ‘scale’ and ‘loc’.

>>> import scipy
>>> import numpy
>>> func = scipy.stats.norm(scale=.0001, loc=0.001)
>>> import matplotlib.pyplot as plt
>>> fig = plt.hist(func.ppf(q=numpy.random.rand(10000)), bins=50)
random(target, seed=None, num_range=[0, 1])[source]

Create an array of random numbers of a specified size.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seed (int) – The starting seed value to send to Scipy’s random number generator. The default is None, which means different distribution is returned each time the model is run.

  • num_range (list) – A two element list indicating the low and high end of the returned numbers.

Returns

values – Array containing uniformly-distributed random numbers.

Return type

NumPy ndarray

weibull(target, shape, scale, loc, seeds='throat.seed')[source]

Produces values from a Weibull distribution given a set of random numbers.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • seeds (string, optional) – The dictionary key on the Geometry object containing random seed values (between 0 and 1) to use in the statistical distribution.

  • shape (float) – This controls the skewness of the distribution, with ‘shape’ < 1 giving values clustered on the low end of the range with a long tail, and ‘shape’ > 1 giving a more symmetrical distribution.

  • scale (float) – This controls the width of the distribution with most of values falling below this number.

  • loc (float) – Applies an offset to the distribution such that the smallest values are above this number.

Returns

values – Array containing random numbers based on Weibull distribution.

Return type

NumPy ndarray

Examples

The following code illustrates the inner workings of this function, which uses the ‘weibull_min’ method of the scipy.stats module. This can be used to find suitable values of ‘shape’, ‘scale’` and ‘loc’. Note that ‘shape’ is represented by ‘c’ in the actual function call.

>>> import scipy
>>> import numpy
>>> func = scipy.stats.weibull_min(c=1.5, scale=0.0001, loc=0)
>>> import matplotlib.pyplot as plt
>>> fig = plt.hist(func.ppf(q=numpy.random.rand(10000)), bins=50)

Throat length

circles_and_rectangles(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are circles and throats are rectangles.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray

classic(target, pore_diameter='pore.diameter')[source]

Finds throat length as the pore-to-pore center distance, less the radii of each pore.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values

conduit_lengths(target, throat_endpoints='throat.endpoints', throat_length='throat.length', throat_centroid='throat.centroid')[source]

Calculates conduit lengths. A conduit is defined as half pore + throat + half pore.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_endpoints (str) – Dictionary key of the throat endpoint values.

  • throat_diameter (str) – Dictionary key of the throat length values.

  • throat_length (string (optional)) – Dictionary key of the throat length values. If not given then the direct distance bewteen the two throat end points is used.

Returns

  • Dictionary containing conduit lengths, which can be accessed via the dict

  • keys ‘pore1’, ‘pore2’, and ‘throat’.

cones_and_cylinders(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are cones and throats are cylinders.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray

ctc(target)[source]

Calculates throat length assuming point-like pores, i.e. center-to-center distance between pores. Also, this model assumes that pores and throat centroids are colinear.

Parameters

target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

Returns

value – Array containing throat length values.

Return type

ndarray

cubes_and_cuboids(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are cubes and throats are cuboids.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray

piecewise(target, throat_endpoints='throat.endpoints', throat_centroid='throat.centroid')[source]

Calculates throat length from end points and optionally a centroid

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_endpoints (str) – Dictionary key of the throat endpoint values.

  • throat_centroid (str) – Dictionary key of the throat centroid values, optional.

Returns

Lt – Array containing throat lengths for the given geometry.

Return type

ndarray

Notes

By default, the model assumes that the centroids of pores and the connecting throat in each conduit are colinear.

If throat_centroid is passed, the model accounts for the extra length. This could be useful for Voronoi or extracted networks.

pyramids_and_cuboids(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are pyramids and throats are cuboids.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray

spheres_and_cylinders(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are spheres and throats are cylinders.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray

squares_and_rectangles(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are squares and throats are rectangles.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray

trapezoids_and_rectangles(target, pore_diameter='pore.diameter', throat_diameter='throat.diameter')[source]

Finds throat length assuming pores are trapezoids and throats are rectangles.

Parameters
  • target (GenericGeometry) – Geometry object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • pore_diameter (str) – Dictionary key of the pore diameter values.

  • throat_diameter (str) – Dictionary key of the throat diameter values.

Returns

Array containing throat length values.

Return type

ndarray


Throat perimeter

cuboid(target, throat_diameter='throat.diameter')[source]

Calcuate the throat perimeter assuming a square cross-section

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – The dictionary key of the array containing the throat diameter values.

Returns

value – Array containing throat perimeter values.

Return type

NumPy ndarray

cylinder(target, throat_diameter='throat.diameter')[source]

Calcuate the throat perimeter assuming a circular cross-section

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – The dictionary key of the array containing the throat diameter values

Returns

value – Array containing throat perimeter values.

Return type

NumPy ndarray

rectangle(target, throat_diameter='throat.diameter')[source]

Calcuate the throat perimeter assuming a rectangular cross-section (2D)

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – The dictionary key of the array containing the throat diameter values

Returns

value – Array containing throat perimeter values.

Return type

NumPy ndarray


Throat surface area

cuboid(target, throat_diameter='throat.diameter', throat_length='throat.length')[source]

Calculate surface area for a cuboid throat

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – Dictionary key to the throat diameter array. Default is ‘throat.diameter’.

  • throat_length (string) – Dictionary key to the throat length array. Default is ‘throat.length’.

Returns

value – Array containing throat surface area values.

Return type

NumPy ndarray

cylinder(target, throat_diameter='throat.diameter', throat_length='throat.length')[source]

Calculate surface area for a cylindrical throat

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_diameter (string) – Dictionary key to the throat diameter array. Default is ‘throat.diameter’.

  • throat_length (string) – Dictionary key to the throat length array. Default is ‘throat.length’.

Returns

value – Array containing throat surface area values.

Return type

NumPy ndarray

extrusion(target, throat_perimeter='throat.perimeter', throat_length='throat.length')[source]

Calculate surface area for an arbitrary shaped throat give the perimeter and length.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_perimeter (string) – Dictionary key to the throat perimeter array. Default is ‘throat.perimeter’.

  • throat_length (string) – Dictionary key to the throat length array. Default is ‘throat.length’.

Returns

value – Array containing throat surface area values.

Return type

NumPy ndarray

rectangle(target, throat_length='throat.length')[source]

Calculate surface area for a rectangular throat

Only suitable for true 2D simulations

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_length (string) – Dictionary key to the throat length array. Default is ‘throat.length’.


Throat vector

pore_to_pore(target)[source]

Calculates throat vector as straight path between connected pores.

Parameters

target (OpenPNM object) – The object containing the geometrical properties of the throats

Returns

unit_vec – Array containing pore-to-pore unit vectors

Return type

NumPy ndarray, shape = (N, 3)

Notes

There is an important impicit assumption here: the positive direction is taken as the direction from the pore with the lower index to the higher. This corresponds to the pores in the 1st and 2nd columns of the ‘throat.conns’ array as stored on the etwork.


Throat volume

cuboid(target, throat_length='throat.length', throat_diameter='throat.diameter')[source]

Calculate throat volume assuing a square cross-section

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • and throat_diameter (throat_length) – The dictionary keys containing the arrays with the throat diameter and length values.

Returns

value – Array containing throat volume values.

Return type

NumPy ndarray

Notes

At present this models does NOT account for the volume reprsented by the intersection of the throat with a spherical pore body.

cylinder(target, throat_length='throat.length', throat_diameter='throat.diameter')[source]

Calculate throat volume assuing a cylindrical shape

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • and throat_diameter (throat_length) – The dictionary keys containing the arrays with the throat diameter and length values.

Returns

value – Array containing throat volume values.

Return type

NumPy ndarray

Notes

At present this models does NOT account for the volume reprsented by the intersection of the throat with a spherical pore body.

extrusion(target, throat_length='throat.length', throat_area='throat.area')[source]

Calculate throat volume from the throat area and the throat length. This method is useful for abnormal shaped throats.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • and throat_area (throat_length) – The dictionary keys containing the arrays with the throat area and length values.

Returns

value – Array containing throat volume values.

Return type

NumPy ndarray

Notes

At present this models does NOT account for the volume reprsented by the intersection of the throat with a spherical pore body.

lens(target, throat_diameter='throat.diameter', pore_diameter='pore.diameter')[source]

Calculates the volume residing the hemispherical caps formed by the intersection between cylindrical throats and spherical pores.

This volume should be subtracted from throat volumes if the throat lengths were found using throat end points.

Parameters
  • throat_diameter (string) – The dictionary keys containing the array with the throat diameter values.

  • pore_diameter (string) – The dictionary keys containing the array with the pore diameter values.

Returns

volume – The volume that should be subtracted from each throat volume to prevent double counting the volume of overlapping area.

Return type

ND-array

Notes

This model does NOT consider the possibility that multiple throats might overlap in the same location which could happen if throats are large and connectivity is random.

See also

pendular_ring

pendular_ring(target, throat_diameter='throat.diameter', pore_diameter='pore.diameter')[source]

Calculates the volume of the pendular rings residing between the end of a cylindrical throat and spherical pores that are in contact but not overlapping.

This volume should be added to the throat volume if the throat length was found as the center-to-center distance less the pore radii.

Parameters
  • throat_diameter (string) – The dictionary keys containing the array with the throat diameter values.

  • pore_diameter (string) – The dictionary keys containing the array with the pore diameter values.

Returns

volume – The volume that should be added to each throat volume to account for under-represented void volume at the pore-throat junctions.

Return type

ND-array

Notes

This model does NOT consider the possibility that multiple throats might overlap in the same location which could happen if throats are large and connectivity is random.

See also

lens

rectangle(target, throat_length='throat.length', throat_diameter='throat.diameter')[source]

Calculate throat volume assuing a rectangular shape

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • and throat_diameter (throat_length) – The dictionary keys containing the arrays with the throat diameter and length values.

Notes

At present this models does NOT account for the volume reprsented by the intersection of the throat with a spherical pore body.


Throat capillary shape factor

compactness(target, throat_perimeter='throat.perimeter', throat_area='throat.area')[source]

Mortensen et al. have shown that the Hagen-Poiseuille hydraluic resistance is linearly dependent on the compactness. Defined as perimeter^2/area. The dependence is not universal as shapes with sharp corners provide more resistance than those that are more elliptical. Count the number of vertices and apply the right correction.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_perimeter (string) – The dictionary key of the array containing the throat perimeter values.

  • throat_area (string) – The dictionary key of the array containing the throat area values.

Returns

alpha – Array containing throat compactness values.

Return type

NumPy ndarray

References

Mortensen N.A, Okkels F., and Bruus H. Reexamination of Hagen-Poiseuille flow: Shape dependence of the hydraulic resistance in microchannels. Physical Review E, v.71, pp.057301 (2005).

jenkins_rao(target, throat_perimeter='throat.perimeter', throat_area='throat.area', throat_diameter='throat.indiameter')[source]

Jenkins and Rao relate the capillary pressure in an eliptical throat to the aspect ratio

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_perimeter (string) – The dictionary key of the array containing the throat perimeter values.

  • throat_area (string) – The dictionary key of the array containing the throat area values.

  • throat_diameter (string) – The dictionary key of the array containing the throat diameter values.

Returns

value – Array containing throat capillary pressure values.

Return type

NumPy ndarray

References

Jenkins, R.G. and Rao, M.B., The effect of elliptical pores on mercury porosimetry results. Powder technology, 38(2), pp.177-180. (1984)

mason_morrow(target, throat_perimeter='throat.perimeter', throat_area='throat.area')[source]

Mason and Morrow relate the capillary pressure to the shaped factor in a similar way to Mortensen but for triangles.

Parameters
  • target (OpenPNM Object) – The object which this model is associated with. This controls the length of the calculated array, and also provides access to other necessary properties.

  • throat_perimeter (string) – The dictionary key of the array containing the throat perimeter values.

  • throat_area (string) – The dictionary key of the array containing the throat area values.

Returns

value – Array containing throat shape factor values.

Return type

NumPy ndarray

References

Mason, G. and Morrow, N.R.. Capillary behavior of a perfectly wetting liquid in irregular triangular tubes. Journal of Colloid and Interface Science, 141(1), pp.262-274 (1991).