tools
tools
Functions
| Name | Description |
|---|---|
| cart2cyl | Converts cartesian to cylindrical coordinates |
| cart2sph | Converts cartesian to spherical coordinates |
| change_prefix | Changes the prefix used when generating the graph |
| conns_to_am | Converts a list of connections into a Scipy sparse adjacency matrix |
| cyl2cart | Converts cylindrical to cartesian coordinates |
| dict_to_am | Convert a graph dictionary into a scipy.sparse adjacency matrix in |
| dict_to_im | Convert a graph dictionary into a scipy.sparse incidence matrix in COO |
| dimensionality | Checks the dimensionality of the network |
| find_coincident_nodes | Finds nodes with identical coordinates |
| find_surface_nodes | Identifies nodes on the outer surface of the domain using a Delaunay |
| find_surface_nodes_cubic | Identifies nodes on the outer surface of the domain assuming a cubic domain |
| generate_points_in_disk | Generates approximately equally spaced points inside a disk |
| generate_points_on_circle | Generates equally spaced points on a circle |
| generate_points_on_sphere | Generates approximately equispaced points on the surface of a sphere |
| get_cubic_shape | Determine shape of a cubic network |
| get_cubic_spacing | Determine spacing of a cubic network |
| get_domain_area | Determine the cross sectional area relative to the inlets/outlets. |
| get_domain_length | Determine the domain length relative to the inlets/outlets. |
| get_edge_prefix | Determines the prefix used for edge arrays from <edge_prefix>.conns |
| get_node_prefix | Determines the prefix used for node arrays from <edge_prefix>.coords |
| internode_distance | Find the distance between all nodes on set 1 to each node in set 2 |
| is_fully_connected | Checks whether graph is fully connected, i.e. not clustered |
| isgtriu | Determines if graph connections are in upper triangular format |
| isoutside | Identifies sites that lie outside the specified shape |
| issymmetric | A method to check if a square matrix is symmetric |
| istriangular | Returns True if the sparse adjacency matrix is either upper or lower |
| istril | Returns True if the sparse adjacency matrix is lower triangular |
| istriu | Returns True if the sparse adjacency matrix is upper triangular |
| rotate_coords | Rotates coordinates a given amount about each axis |
| shear_coords | Shears the coordinates a given amount about along axis |
| sph2cart | Converts spherical to cartesian coordinates |
| tri_to_am | Given a Delaunay triangulation object from Scipy’s spatial module, |
| vor_to_am | Given a Voronoi tessellation object from Scipy’s spatial module, |
cart2cyl
tools.cart2cyl(x, y, z=0)Converts cartesian to cylindrical coordinates
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | array_like | Arrays containing the cartesian coordinates to be transformed. Note that z is optional since it is unchanged during this operation. If z is omitted it is assumed to be 0, or equivalent to polar coordinates. |
required |
| y | array_like | Arrays containing the cartesian coordinates to be transformed. Note that z is optional since it is unchanged during this operation. If z is omitted it is assumed to be 0, or equivalent to polar coordinates. |
required |
| z | array_like | Arrays containing the cartesian coordinates to be transformed. Note that z is optional since it is unchanged during this operation. If z is omitted it is assumed to be 0, or equivalent to polar coordinates. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| r, theta, z : ndarrays | Three arrays containing the cylindrical coordinates of the given points |
Notes
Surprizingly (and annoyingly) this is not built into numpy, for reasons discussed here <https://github.com/numpy/numpy/issues/5228>_.
cart2sph
tools.cart2sph(x, y, z)Converts cartesian to spherical coordinates
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| x | array_like | Arrays containing the x, y and z coordinates to be converted | required |
| y | array_like | Arrays containing the x, y and z coordinates to be converted | required |
| z | array_like | Arrays containing the x, y and z coordinates to be converted | required |
Returns
| Name | Type | Description |
|---|---|---|
| r, theta, phi : ndarrays | Three arrays containing the spherical coordinate of each given point |
Notes
Surprizingly (and annoyingly) this is not built into numpy, for reasons discussed here <https://github.com/numpy/numpy/issues/5228>_.
change_prefix
tools.change_prefix(network, old_prefix, new_prefix)Changes the prefix used when generating the graph
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network graph | required |
| old_prefix | str | The current prefix to change, can either be a node or an edge prefix | required |
| new_prefix | str | The prefix to use instead | required |
Returns
| Name | Type | Description |
|---|---|---|
| network | dict | The graph dictionary will arrays assigned to new keys |
conns_to_am
tools.conns_to_am(
conns,
shape=None,
force_triu=True,
drop_diag=True,
drop_dupes=True,
drop_negs=True,
)Converts a list of connections into a Scipy sparse adjacency matrix
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| conns | array_like, N x 2 | The list of site-to-site connections | required |
| shape | list | The shape of the array. If none is given then it is taken as 1 + the maximum value in conns. |
None |
| force_triu | bool | If True (default), then all connections are assumed undirected, and moved to the upper triangular portion of the array | True |
| drop_diag | bool | If True (default), then connections from a site and itself are removed. | True |
| drop_dupes | bool | If True (default), then all pairs of sites sharing multiple connections are reduced to a single connection. | True |
| drop_negs | bool | If True (default), then all connections with one or both ends pointing to a negative number are removed. | True |
Returns
| Name | Type | Description |
|---|---|---|
| am | ndarray | A sparse adjacency matrix in COO format |
cyl2cart
tools.cyl2cart(r, theta, z=0)Converts cylindrical to cartesian coordinates
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | array_like | Arrays containing the cylindrical coordinates to be transformed. Note that z is optional since it is unchanged during this operation. If z is omitted it is assumed to be 0, or equivalent to polar coordinates. |
required |
| theta | array_like | Arrays containing the cylindrical coordinates to be transformed. Note that z is optional since it is unchanged during this operation. If z is omitted it is assumed to be 0, or equivalent to polar coordinates. |
required |
| z | array_like | Arrays containing the cylindrical coordinates to be transformed. Note that z is optional since it is unchanged during this operation. If z is omitted it is assumed to be 0, or equivalent to polar coordinates. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| x, y, z : ndarrays | Three arrays containing the cartesian coordinates of the given points |
Notes
Surprizingly (and annoyingly) this is not built into numpy, for reasons discussed here <https://github.com/numpy/numpy/issues/5228>_.
dict_to_am
tools.dict_to_am(network, weights=None)Convert a graph dictionary into a scipy.sparse adjacency matrix in COO format
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | A network dictionary | required |
| weights | ndarray | The weight values to use for the connections. If not provided then 1’s are assumed. | None |
Returns
| Name | Type | Description |
|---|---|---|
| am | sparse matrix | The sparse adjacency matrix in COO format |
Notes
If the edge connections in g are in upper-triangular form, then the graph is assumed to be undirected and the returned adjacency matrix is symmetrical (i.e. the triu entries are reflected in tril). If any edges are found in the lower triangle, then the returned adjacency matrix is unsymmetrical.
Multigraphs (i.e. duplicate connections between nodes) are not suported, but this is not checked for here to avoid overhead since this function is called frequently.
dict_to_im
tools.dict_to_im(network)Convert a graph dictionary into a scipy.sparse incidence matrix in COO format
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| im | sparse matrix | The sparse incidence matrix in COO format |
Notes
Rows correspond to nodes and columns correspond to edges. Each column has 2 nonzero values indicating which 2 nodes are connected by the corresponding edge. Each row contains an arbitrary number of nonzeros whose locations indicate which edges are directly connected to the corresponding node.
dimensionality
tools.dimensionality(network, cache=True)Checks the dimensionality of the network
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
| cache | (boolean, optional(default is True)) | If False then the dimensionality is recalculated even if it has already been calculated and stored in the graph dictionary. |
True |
Returns
| Name | Type | Description |
|---|---|---|
| dims | list | A 3-by-1 array containing True for each axis that contains multiple values, indicating that the pores are spatially distributed in that dimension. |
find_coincident_nodes
tools.find_coincident_nodes(network)Finds nodes with identical coordinates
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| duplicates | list of ndarrays | A list with each sublist indicating the indices of nodes that share a common set of coordinates |
Notes
This function works by computing a hash of the coordinates then finding all nodes with equivalent hash values. Hashes are supposed to be unique but they occassionally “collide”, meaning nodes may be identified as coincident that are not.
find_surface_nodes
tools.find_surface_nodes(network)Identifies nodes on the outer surface of the domain using a Delaunay tessellation
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| mask | ndarray | A boolean array of True values indicating which nodes were found on the surfaces. |
Notes
This function generates points around the domain the performs a Delaunay tesselation between these points and the network nodes. Any network nodes which are connected to a generated points is considered a surface node.
find_surface_nodes_cubic
tools.find_surface_nodes_cubic(network)Identifies nodes on the outer surface of the domain assuming a cubic domain to save time
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The graph dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| mask | ndarray | A boolean array of True values indicating which nodes were found on the surfaces. |
generate_points_in_disk
tools.generate_points_in_disk(n=100, r=1)Generates approximately equally spaced points inside a disk
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int | The number of points to generate | 100 |
| r | scalar | The radius of the disk | 1 |
Returns
| Name | Type | Description |
|---|---|---|
| coords | ndarray | An n by 2 array of x, y points (in cartesian coordinates) |
generate_points_on_circle
tools.generate_points_on_circle(n=100, r=1)Generates equally spaced points on a circle
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int | The number of points to generate | 100 |
| r | scalar | The radius of the disk | 1 |
Returns
| Name | Type | Description |
|---|---|---|
| coords | ndarray | An n by 2 array of x, y points (in cartesian coordinates) |
generate_points_on_sphere
tools.generate_points_on_sphere(n=100, r=1)Generates approximately equispaced points on the surface of a sphere
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int or [int, int] | If a single int is provided then this number of points will be generated using the Fibonacci method to make them approximately equally spaced. If a list of 2 ints is given, they are interpreted as the number of meridians and parallels to divide the sphere with. |
100 |
| r | scalar | The radius of the sphere on which the points should lie | 1 |
Returns
| Name | Type | Description |
|---|---|---|
| coords | ndarray | An array of x, y, z coordinates for the sphere which will be centered on [0, 0, 0] |
get_cubic_shape
tools.get_cubic_shape(network)Determine shape of a cubic network
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| shape | ndarray | An array containing the shape of the network each direction |
get_cubic_spacing
tools.get_cubic_spacing(network)Determine spacing of a cubic network
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| spacing | ndarray | An array containing the spacing between nodes in each direction |
get_domain_area
tools.get_domain_area(network, inlets=None, outlets=None)Determine the cross sectional area relative to the inlets/outlets.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
| inlets | array_like | The indices of the inlets | None |
| outlets | array_Like | The indices of the outlets | None |
Returns
| Name | Type | Description |
|---|---|---|
| area | scalar | The cross sectional area relative to the inlets/outlets. |
get_domain_length
tools.get_domain_length(network, inlets=None, outlets=None)Determine the domain length relative to the inlets/outlets.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
| inlets | array_like | The pore indices of the inlets. | None |
| outlets | array_Like | The pore indices of the outlets. | None |
Returns
| Name | Type | Description |
|---|---|---|
| area | scalar | The domain length relative to the inlets/outlets. |
get_edge_prefix
tools.get_edge_prefix(network)Determines the prefix used for edge arrays from <edge_prefix>.conns
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| edge_prefix | str | The value of <edge_prefix> used in g. This is found by scanning g.keys() until an array ending in '.conns' is found, then returning the prefix. |
Notes
This process is surprizingly fast, on the order of nano seconds, so this overhead is worth it for the flexibility it provides in array naming. However, since all dict are now sorted in Python, it may be helpful to ensure the 'conns' array is near the beginning of the list.
get_node_prefix
tools.get_node_prefix(network)Determines the prefix used for node arrays from <edge_prefix>.coords
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| node_prefix | str | The value of <node_prefix> used in g. This is found by scanning g.keys() until an array ending in '.coords' is found, then returning the prefix. |
Notes
This process is surprizingly fast, on the order of nano seconds, so this overhead is worth it for the flexibility it provides in array naming. However, since all dict are now sorted in Python, it may be helpful to ensure the 'conns' array is near the beginning of the list.
internode_distance
tools.internode_distance(network, inds_1=None, inds_2=None)Find the distance between all nodes on set 1 to each node in set 2
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
| inds_1 | array_like | A list containing the indices of the first set of nodes | None |
| inds_2 | array_Like | A list containing the indices of the first set of nodes. It’s OK if these indices are partially or completely duplicating nodes1. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| dist | array_like | A distance matrix with len(site1) rows and len(sites2) columns. The distance between site i in site1 and j in sites2 is located at (i, j) and (j, i) in the distance matrix. |
Notes
This function computes and returns a distance matrix, so can get large. For distances between larger sets a KD-tree approach would be better, which is available in scipy.spatial.
is_fully_connected
tools.is_fully_connected(network, inds=None)Checks whether graph is fully connected, i.e. not clustered
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
| inds | array_like(optional) | The indices of boundary nodes (i.e. inlets/outlets). If this is given the multiple sample spanning clusters will count as fully connected. | None |
Returns
| Name | Type | Description |
|---|---|---|
| flag | bool | If inds is not specified, then returns True only if the entire network is connected to the same cluster. If inds is given, then returns True only if all clusters are connected to the given boundary nodes. |
isgtriu
tools.isgtriu(network)Determines if graph connections are in upper triangular format
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary | required |
Returns
| Name | Type | Description |
|---|---|---|
| flag | bool | Returns True if all rows in “conns” are ordered as [lo, hi] |
isoutside
tools.isoutside(network, shape, rtol=0.0)Identifies sites that lie outside the specified shape
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| network | dict | The network dictionary. For convenience it is also permissible to just supply an N-by-D array of coordinates. | required |
| shape | array_like | The shape of the domain beyond which points are considered “outside”. The argument is treated as follows: ========== ============================================================ shape Interpretation ========== ============================================================ [x, y, z] A 3D cubic domain of dimension x, y and z with the origin at [0, 0, 0]. [x, y, 0] A 2D square domain of size x by y with the origin at [0, 0] [r, z] A 3D cylindrical domain of radius r and height z whose central axis starts at [0, 0, 0] [r, 0] A 2D circular domain of radius r centered on [0, 0] and extending upwards [r] A 3D spherical domain of radius r centered on [0, 0, 0] ========== ============================================================ | required |
| rtol | scalar or array_like | Controls how far a node must be from the domain boundary to be considered outside. It is applied as a fraction of the domain size as x[i] > (shape[0] + shape[0]*threshold) or y[i] < (0 - shape[1]*threshold). Discrete threshold values can be given for each axis by supplying a list the same size as shape. |
0.0 |
Returns
| Name | Type | Description |
|---|---|---|
| mask | boolean ndarray | A boolean array with True values indicating nodes that lie outside the domain. |
Notes
If the domain is 2D, either a circle or a square, then the z-dimension of shape should be set to 0.
issymmetric
tools.issymmetric(am)A method to check if a square matrix is symmetric Returns True if the sparse adjacency matrix is symmetric
istriangular
tools.istriangular(am)Returns True if the sparse adjacency matrix is either upper or lower triangular
istril
tools.istril(am)Returns True if the sparse adjacency matrix is lower triangular
istriu
tools.istriu(am)Returns True if the sparse adjacency matrix is upper triangular
rotate_coords
tools.rotate_coords(coords, a=0, b=0, c=0, R=None)Rotates coordinates a given amount about each axis
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| coords | ndarray | The site coordinates to be transformed. coords must be in 3D, but a 2D network can be represented by putting 0’s in the missing dimension. |
required |
| a | scalar | The amount in degrees to rotate about the x, y, and z-axis, respectively. | 0 |
| b | scalar | The amount in degrees to rotate about the x, y, and z-axis, respectively. | 0 |
| c | scalar | The amount in degrees to rotate about the x, y, and z-axis, respectively. | 0 |
| R | array_like | Rotation matrix. Must be a 3-by-3 matrix since coordinates are always in 3D. If this is given then a, b, and c are ignored. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| coords | ndarray | A copy of the given coords is made and returned to the rotation does not occur in place. |
See Also
shear_coords
shear_coords
tools.shear_coords(coords, ay=0, az=0, bx=0, bz=0, cx=0, cy=0, S=None)Shears the coordinates a given amount about along axis
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| coords | ndarray | The coordinates to be transformed | required |
| ay | scalar | The factor by which to shear along the x-axis as a function of y | 0 |
| az | scalar | The factor by which to shear along the x-axis as a function of z | 0 |
| bx | scalar | The factor by which to shear along the y-axis as a function of x | 0 |
| bz | scalar | The factor by which to shear along the y-axis as a function of z | 0 |
| cx | scalar | The factor by which to shear along the z-axis as a function of x | 0 |
| cy | scalar | The factor by which to shear along the z-axis as a function of y | 0 |
| S | array_like | The shear matrix. Must be a 3-by-3 matrix since pore coordinates are always in 3D. If this is given then the other individual arguments are ignored. | None |
Returns
| Name | Type | Description |
|---|---|---|
| coords | ndarray | The sheared coordinates. A copy of the supplied coordinates is made so that the operation is not performed in place. |
See Also
rotate_coords
Notes
The shear along the i th-axis is given as i* = i + aj. This means the new i coordinate is the old one plus some linear factor a in the j th direction.
The values of a, b, and c are essentially the inverse of the slope to be formed by the neighboring layers of sheared pores. A value of 0 means no shear, and neighboring points are stacked directly on top of each other; a value of 1 means they form a 45 degree diagonal, and so on.
If S is given, then is should be of the form:
::
S = [[1 , ay, az],
[bx, 1 , bz],
[cx, cy, 1 ]]
where any of the off-diagonal components can be 0 meaning no shearsph2cart
tools.sph2cart(r, theta, phi)Converts spherical to cartesian coordinates
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| r | array_like | Arrays containing the r, theta and phi coordinates to be transformed | required |
| theta | array_like | Arrays containing the r, theta and phi coordinates to be transformed | required |
| phi | array_like | Arrays containing the r, theta and phi coordinates to be transformed | required |
Returns
| Name | Type | Description |
|---|---|---|
| x, y, z : ndarrays | Three arrays containing the cartesian coordinates of the given points |
Notes
Surprizingly (and annoyingly) this is not built into numpy, for reasons discussed here <https://github.com/numpy/numpy/issues/5228>_.
tri_to_am
tools.tri_to_am(tri)Given a Delaunay triangulation object from Scipy’s spatial module, converts to a sparse adjacency matrix network representation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| tri | Delaunay Triangulation Object | This object is produced by scipy.spatial.Delaunay |
required |
Returns
| Name | Type | Description |
|---|---|---|
| A sparse adjacency matrix in COO format. The network is undirected | ||
| and unweighted, so the adjacency matrix is upper-triangular and all the | ||
| weights are set to 1. |
vor_to_am
tools.vor_to_am(vor)Given a Voronoi tessellation object from Scipy’s spatial module, converts to a sparse adjacency matrix network representation in COO format.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| vor | Voronoi Tessellation object | This object is produced by scipy.spatial.Voronoi |
required |
Returns
| Name | Type | Description |
|---|---|---|
| A sparse adjacency matrix in COO format. The network is undirected | ||
| and unweighted, so the adjacency matrix is upper-triangular and all the | ||
| weights are set to 1. |