generators

generators

Functions

Name	Description
bcc	Generate a body-centered cubic lattice
cubic	Generate a simple cubic lattice
cubic2	Generate coordinates and connections for a cubic lattice
cubic_template	Generate a simple cubic lattice matching the shape of the provided tempate
delaunay	Generate a network based on Delaunay triangulation of random points
fcc	Generate a face-centered cubic lattice
gabriel	Generate a network based on a Gabriel tessellation, which is a subset of
relative_neighborhood	Generate a network based on a relative neighborhood, which is a subset of
urquhart	Generate a network based on a relative neighborhood, which is a subset of
voronoi	Generate a network based on a Voronoi tessellation of base points
voronoi_delaunay_dual	Generate a dual Voronoi-Delaunay network from given base points

bcc

generators.bcc(
    shape,
    spacing=1,
    method='kdtree',
    node_prefix='node',
    edge_prefix='edge',
)

Generate a body-centered cubic lattice

Parameters

Name	Type	Description	Default
shape	array_like	The number of corner sites in each direction. A cubic lattice of this size is created and then ‘body-centered’ nodes are added afterward.	required
spacing	array_like or float	The size of a unit cell in each direction. If an scalar is given it is applied in all 3 directions.	1
method	str	Dictate how neighbors are found. Options are: =============== ====================================================== mode meaning =============== ====================================================== ‘kdtree’ Uses scipy.spatial.KDTree to find all neighbors within the unit cell ‘triangulation’ Uses scipy.spatial.Delaunay to find all neighbors =============== ======================================================	'kdtree'

Returns

Name	Type	Description
network	dict	A dictionary containing ‘coords’, ‘conns’ and various boolean labels (i.e. ‘node.center’)

Notes

It is not clear whether KDTree or Delaunay are faster. In fact it is surely possible to find the neighbors formulaically but this is not implemented yet.

cubic

generators.cubic(
    shape,
    spacing=1,
    connectivity=6,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a simple cubic lattice

Parameters

Name	Type	Description	Default
shape	array_like	The number of unit cells in each direction. A unit cell has 1 vertex at its center.	required
spacing	array_like or float	The size of a unit cell in each direction. If an scalar is given it is applied in all 3 directions.	1

Returns

Name	Type	Description
network	dict	A dictionary containing coords and conns of a cubic network with the specified spacing and connectivity.

cubic2

generators.cubic2(
    shape,
    spacing=1.0,
    offset=0.5,
    faces=True,
    corners=False,
    edges=False,
    order='F',
)

Generate coordinates and connections for a cubic lattice

Parameters

Name	Type	Description	Default
shape	array - like	Number of sites along each dimension. A value of 0 or 1 are both considered to be a non-existent axis.	required
spacing	scalar or array - like	The spacing between sites in each direction. If a scalar value is given, it is applied to all directions.	1.0
offset	scalar of array-like	The offset to apply to the coordinates in each direction. If a scalar is given it is applied to all directions.	0.5
faces	bool	Flags to indicate which connections to create. If faces=True then connections are made between sites if their unit cells share a face, and so on. faces=True therefore creates 6 connections, corners=True adds 8 connections, and edges=True adds 12 connections. Each can be turned off or on independently. Note that using only faces=True results in 2 separate networks (in 3D) and also that corners and edges are treated the same in 2D.	True
corners	bool	Flags to indicate which connections to create. If faces=True then connections are made between sites if their unit cells share a face, and so on. faces=True therefore creates 6 connections, corners=True adds 8 connections, and edges=True adds 12 connections. Each can be turned off or on independently. Note that using only faces=True results in 2 separate networks (in 3D) and also that corners and edges are treated the same in 2D.	True
edges	bool	Flags to indicate which connections to create. If faces=True then connections are made between sites if their unit cells share a face, and so on. faces=True therefore creates 6 connections, corners=True adds 8 connections, and edges=True adds 12 connections. Each can be turned off or on independently. Note that using only faces=True results in 2 separate networks (in 3D) and also that corners and edges are treated the same in 2D.	True
order	str	Specifies the ordering of the coordinates to be in either "C" style where the last index is incremented first, or "F" style where the first index is incremented first. The default is "C" since this is what Numpy uses.	'F'

Returns

Name	Type	Description
	coords, conns : ndarrays	The ndarrays containing the [X, Y, Z] coordinates of each site, and the [source, target] connections between sites.

cubic_template

generators.cubic_template(
    template,
    spacing=1,
    connectivity=6,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a simple cubic lattice matching the shape of the provided tempate

Parameters

Name	Type	Description	Default
template	ndarray	Each True value will be treated as a vertex while all others will be trimmed.	required
spacing	array_like or float	The size of a unit cell in each direction. If an scalar is given it is applied in all 3 directions.	1

Returns

Name	Type	Description
network	dict	A dictionary containing ‘node.coords’ and ‘edge.conns’

delaunay

generators.delaunay(
    points,
    shape=[1, 1, 1],
    reflect=False,
    f=1,
    trim=True,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a network based on Delaunay triangulation of random points

Parameters

Name	Type	Description	Default
points	array_like or int	Can either be an N-by-3 array of point coordinates which will be used, or a scalar value indicating the number of points to generate	required
shape	array_like	Indicates the size and shape of the domain	[1, 1, 1]
reflect	boolean, optional (default = False)	If True then points are reflected across each face of the domain prior to performing the tessellation. These reflected points are automatically trimmed. Enabling this behavior prevents long-range connections between surface pores.	False
f	float	The fraction of points which should be reflected. The default is 1 which reflects all the points in the domain, but this can lead to a lot of unnecessary points, so setting to 0.1 or 0.2 helps speed, but risks that the tessellation may not have smooth faces if not enough points are reflected.	1
trim	boolean, optional (default = True)	If True then any points laying outside the domain are removed. This is mostly only useful if reflect=True.	True

Returns

Name	Type	Description
network	dict	A dictionary containing ‘node.coords’ and ‘edge.conns’
tri	Delaunay tessellation object	The Delaunay tessellation object produced by scipy.spatial.Delaunay

fcc

generators.fcc(
    shape,
    spacing=1,
    method='kdtree',
    node_prefix='node',
    edge_prefix='edge',
)

Generate a face-centered cubic lattice

Parameters

Name	Type	Description	Default
shape	array_like	The number of corner sites in each direction. A sipmle cubic lattice is created then the ‘face-sites’ are added afterwards.	required
spacing	array_like or float	The size of a unit cell in each direction. If an scalar is given it is applied in all 3 directions.	1
method	str	Dictate how neighbors are found. Options are: =============== ===================================================== mode meaning =============== ===================================================== ‘kdtree’ Uses scipy.spatial.KDTree to find all neighbors within the unit cell. ‘triangulation’ Uses scipy.spatial.Delaunay to find all neighbors. =============== =====================================================	'kdtree'

Returns

Name	Type	Description
network	dict	A dictionary containing ‘coords’, ‘conns’ and various boolean labels (i.e. ‘node.center’)

Notes

It is not clear whether KDTree of Delaunay are faster. In fact it is surely possible to find the neighbors formulaically but this is not implemented yet.

gabriel

generators.gabriel(
    points=None,
    delaunay=None,
    shape=None,
    reflect=False,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a network based on a Gabriel tessellation, which is a subset of the Delaunay triangulation

Parameters

Name	Type	Description	Default
points	array_like or int	Can either be an N-by-3 array of point coordinates which will be used, or a scalar value indicating the number of points to generate. This can be omitted if delaunay is provided.	None
delaunay	network dictionary	A dictionary containing coords and conns as produced by the delaunay function. If points are provided this is ignored.	None
shape	array_like	Indicates the size and shape of the domain	None
reflect	boolean, optional (default = False)	If True then points are reflected across each face of the domain prior to performing the tessellation. These reflected points are automatically trimmed. Enabling this behavior prevents long-range connections between surface pores.	False

Returns

Name	Type	Description
network	dict	A dictionary containing ‘node.coords’ and ‘edge.conns’

relative_neighborhood

generators.relative_neighborhood(
    points=None,
    delaunay=None,
    shape=None,
    reflect=False,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a network based on a relative neighborhood, which is a subset of the Delaunay triangulation

Parameters

Name	Type	Description	Default
points	array_like or int	Can either be an N-by-3 array of point coordinates which will be used, or a scalar value indicating the number of points to generate. This can be omitted if delaunay is provided.	None
delaunay	network dictionary	A dictionary containing coords and conns as produced by the delaunay function. If points are provided this is ignored.	None
shape	array_like	Indicates the size and shape of the domain	None
reflect	boolean, optional (default = False)	If True then points are reflected across each face of the domain prior to performing the tessellation. These reflected points are automatically trimmed. Enabling this behavior prevents long-range connections between surface pores.	False

Returns

Name	Type	Description
network	dict	A dictionary containing ‘node.coords’ and ‘edge.conns’

urquhart

generators.urquhart(
    points=None,
    delaunay=None,
    shape=None,
    reflect=False,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a network based on a relative neighborhood, which is a subset of the Delaunay triangulation

Parameters

Name	Type	Description	Default
points	array_like or int	Can either be an N-by-3 array of point coordinates which will be used, or a scalar value indicating the number of points to generate. This can be omitted if delaunay is provided.	None
delaunay	network dictionary	A dictionary containing coords and conns as produced by the delaunay function. If points are provided this is ignored.	None
shape	array_like	Indicates the size and shape of the domain	None
reflect	boolean, optional (default = False)	If True then points are reflected across each face of the domain prior to performing the tessellation. These reflected points are automatically trimmed. Enabling this behavior prevents long-range connections between surface pores.	False

Returns

Name	Type	Description
network	dict	A dictionary containing ‘node.coords’ and ‘edge.conns’

voronoi

generators.voronoi(
    points,
    shape=[1, 1, 1],
    trim=True,
    reflect=False,
    f=1,
    relaxation=0,
    node_prefix='node',
    edge_prefix='edge',
)

Generate a network based on a Voronoi tessellation of base points

Parameters

Name	Type	Description	Default
points	array_like or int	Can either be an N-by-3 array of point coordinates which will be used directly, or a scalar indicating the number of points to generate.	required
shape	array_like	The size and shape of the domain	[1, 1, 1]
trim	boolean	If True (default) then any vertices laying outside the domain given by shape are removed (as are the edges connected to them).	True
reflect	boolean, optional (default = False)	If True then points are reflected across each face of the domain prior to performing the tessellation. Enabling this behavior creates flat faces on all sizes of the domain.	False
f	float	The fraction of points which should be reflected. The default is 1 which reflects all the points in the domain, but this can lead to a lot of unnecessary points, so setting to 0.1 or 0.2 helps speed, but risks that the tessellation may not have smooth faces if not enough points are reflected.	1
relaxation	(int, optional(default=0))	The number of iterations to use for relaxing the base points. This is sometimes called Lloyd's algorithm <https://en.wikipedia.org/wiki/Lloyd%27s_algorithm>_. This function computes the new base points as the simple average of the Voronoi vertices instead of rigorously finding the center of mass, which is quite time consuming. To use the rigorous method, call the lloyd_relaxation function manually to obtain relaxed points, then pass the points directly to this funcion. The results are quite stable after only a few iterations.	0

Returns

Name	Type	Description
network	dict	A dictionary containing node coordinates and edge connections
vor	Voronoi tessellation object	The Voronoi tessellation object produced by scipy.spatial.Voronoi

voronoi_delaunay_dual

generators.voronoi_delaunay_dual(
    points,
    shape,
    trim=True,
    reflect=True,
    f=1,
    relaxation=0,
    node_prefix='node',
    edge_prefix='edge',
    return_tri=False,
)

Generate a dual Voronoi-Delaunay network from given base points

Parameters

Name	Type	Description	Default
points	array_like or scalar	The points to be tessellated. If a scalar is given a set of points of that size is generated inside the given shape.	required
shape	array_like	The size of the domain in which the points lie	required
trim	bool	If True (default) then all points lying beyond the given domain shape will be removed	True
reflect	(bool, optionl)	If True (Default) then points are reflected across each face of the domain prior to performing the tessellation.	True
f	float	The fraction of points which should be reflected. The default is 1 which reflects all the points in the domain, but this can lead to a lot of unnecessary points, so setting to 0.1 or 0.2 helps speed, but risks that the tessellation may not have smooth faces if not enough points are reflected.	1
relaxation	(int, optional(default=0))	The number of iterations to use for relaxing the base points. This is sometimes called Lloyd's algorithm <https://en.wikipedia.org/wiki/Lloyd%27s_algorithm>_. This function computes the new base points as the simple average of the Voronoi vertices instead of rigorously finding the center of mass, which is quite time consuming. To use the rigorous method, call the lloyd_relaxation function manually to obtain relaxed points, then pass the points directly to this funcion. The results are quite stable after only a few iterations.	0

Returns

Name	Type	Description
network	dict	A dictionary containing ‘.coords’ and ‘.conns’
vor	Voronoi object	The Voronoi tessellation object produced by scipy.spatial.Voronoi
tri	Delaunay object	The Delaunay triangulation object produced by scipy.spatial.Delaunay