8. connectivity — A class and functions for handling nodal connectivity.

A class and functions for handling nodal connectivity.

This module defines a specialized array class for representing nodal connectivity. This is e.g. used in mesh models, where geometry is represented by a set of numbered points (nodes) and the geometric elements are described by refering to the node numbers. In a mesh model, points common to adjacent elements are unique, and adjacency of elements can easily be detected from common node numbers.

Classes defined in module connectivity

class connectivity.Connectivity

A class for handling element/node connectivity.

A connectivity object is a 2-dimensional integer array with all non-negative values. In this implementation, all values should be smaller than 2**31. Furthermore, all values in a row should be unique. This is not enforced at creation time, but a method is provided to check the uniqueness.

A new Connectivity object is created with the following syntax::
Connectivity(data=[],dtyp=None,copy=False,nplex=0)

Parameters:

  • data: should be integer type and evaluate to an 2-dim array.
  • dtype: can be specified to force an integer type. By default set from data.
  • copy: can be set True to force copying the data. By default, the specified data will be used without copying, if possible.
  • nplex: can be specified to force a check on the plexitude of the data, or to set the plexitude for an empty Connectivity. An error will be raised if the specified data do not match the specified plexitude.

A Connectivity object stores its maximum value found at creation time in an attribute _max.

Methods

nelems()

Return the number of elements in the Connectivity table.

nplex()

Return the plexitude of the elements in the Connectivity table.

encode(permutations=True, return_magic=False)

Encode the element connectivities into single integer numbers.

Each row of numbers is encoded into a single integer value, so that equal rows result in the same number and different rows yield different numbers. Furthermore, enough information can be kept to restore the original rows from these single integer numbers. This is seldom needed however, because the original data are available from the Connectivity table itself.

  • permutations: if True(default), two rows are considered equal if they contain the same numbers regardless of their order. If False, two rows are only equal if they contain the same numbers at the same position.
  • return_magic: if True, return a codes,magic tuple. The default is to return only the codes.

Return value(s):

  • codes: an (nelems,) shaped array with the element code numbers,
  • magic: the information needed to restore the original rows from the codes. See Connectivity.decode()
testDegenerate()

Flag the degenerate elements (rows).

A degenerate element is a row which contains at least two equal values.

This function returns an array with the value True or False for each row. The True values flag the degenerate rows.

listDegenerate()

Return a list with the numbers of the degenerate elements.

listNonDegenerate()

Return a list with the numbers of the non-degenerate elements.

removeDegenerate()

Remove the degenerate elements from a Connectivity table.

Degenerate elements are rows with repeating values. Returns a Connectivity with the degenerate elements removed.

testDoubles(permutations=True)

Test the Connectivity list for doubles.

By default, doubles are elements that consist of the same set of nodes, in any particular order. Setting permutations to False will only find the double rows that have matching values at every position.

This function returns a tuple with two arrays:

  • an index used to sort the elements
  • a flags array with the value True for indices of the unique elements and False for those of the doubles.
listUnique()

Return a list with the numbers of the unique elements.

listDoubles()

Return a list with the numbers of the double elements.

removeDoubles(permutations=True)

Remove doubles from a Connectivity list.

By default, doubles are elements that consist of the same set of nodes, in any particular order. Setting permutations to False will only remove the double rows that have matching values at matching positions.

Returns a new Connectivity with the double elements removed.

selectNodes(nodsel)

Return a connectivity table with a subset of the nodes.

nodsel is an object that can be converted to a 1-dim or 2-dim array. Examples are a tuple of local node numbers, or a list of such tuples all having the same length. Each row of nodsel holds a list of local node numbers that should be retained in the new Connectivity table.

insertLevel(nodsel)

Insert an extra hierarchical level in a Connectivity table.

A Connectivity table identifies higher hierchical entities in function of lower ones. This function will insert an extra hierarchical level. For example, if you have volumes defined in function of points, you can insert an intermediate level of edges, or faces. The return value is a tuple of two Connectivities (hi,lo), where:

  • hi: defines the original elements in function of the intermediate level ones,
  • lo: defines the intermediate level items in function of the lowest level ones.

Intermediate level items that consist of the same items in any permutation order are collapsed to single items. The low level items respect the numbering order inside the original elements, but it is undefined which of the collapsed sequences is returned.

There is currently no inverse operation, because the precise order of the items in the collapsed rows is lost.

untangle(ind=None)

Untangle a Connectivity into lower plexitude tables.

There is no point in untangling a plexitude 2 structure. Plexitudes lower than 2 can not be untangled. Default is to untangle to plex-2 data (as in polygon to line segment).

Return a tuple edges,faces where

  • edges is an (nedges,2) int array of edges connecting two node numbers.
  • faces is an (nelems,nplex) int array with the edge numbers connecting each pair os subsequent nodes in the elements of elems.

The order of the edges respects the node order, and starts with nodes 0-1. The node numbering in the edges is always lowest node number first.

For untangled Connectivities obtained with the default indices, an inverse operation is available as hi.tangle(lo). Degenerate rows may come back as a permutation!

tangle(lo)

Compress two hierarchical Connectivity levels to a single one.

self and lo are two hierarchical Connectivity tables, representing higher and lower level respectively. This means that the elements of self hold numbers which point into lo to obtain the lowest level items.

In the current implementation, the plexitude of lo should be 2!

As an example, in a structure of triangles, hi could represent triangles defined by 3 edges and lo could represent edges defined by 2 vertices. The compress method will then result in a table with plexitude 3 defining the triangles in function of the vertices.

This is the inverse operation of untangle (without specifying ind). The algorithm only works if all vertex numbers of an element are unique.

inverse()

Return the inverse index of a Connectivity table

Functions defined in module connectivity

connectivity.enmagic2(cols, magic=0)

Encode two integer values into a single integer.

cols is a (n,2) array of non-negative integers smaller than 2**31. The result is an (n) array of type int64, where each value is unique for each row of values in the input. The original input can be restored with demagic2.

If a magic value larger than the maximum integer in the table is given, it will be used. If not, it will be taken as the maximum+1. A negative magic value triggers a fastencode scheme.

The return value is a tuple with the codes and the magic used.

connectivity.demagic2(codes, magic)

Decode an integer number into two integers.

The arguments codes and magic are the result of an enmagic2() operation. This will restore the original two values for the codes.

A negative magic value flags the fastencode option.

connectivity.inverseIndex(index, maxcon=4)

Return an inverse index.

Index is an (nr,nc) array of integers, where only non-negative integers are meaningful, and negative values are silently ignored. A Connectivity is a suitable argument.

The inverse index is an integer array, where row i contains all the row numbers of index that contain the number i. Because the number of rows containing the number i is usually not a constant, the resulting array will have a number of columns mr corresponding to the highest row-occurrence of any single number. Shorter rows are padded with -1 values to flag non-existing entries.

Negative numbers in index are disregarded. The return value is an (mr,mc) shaped integer array where: - mr will be equal to the highest positive value in index, +1. - mc will be equal to the highest multiplicity of any number in index.

On entry, maxcon is an estimate for this value. The procedure will automatically change it if needed.

Each row of the reverse index for a number that occurs less than mc times in index, will be filled up with -1 values.

mult is the highest possible multiplicity of any number in a single column of index.

connectivity.adjacencyList(elems)

Create adjacency lists for 2-node elements.

connectivity.adjacencyArray(elems, maxcon=5)

Create adjacency array for 2-node elements.

elems is a (nr,2) shaped integer array. The result is an integer array with shape (nr,mc), where row i holds a sorted list of the nodes that are connected to node i, padded with -1 values to create an equal list length for all nodes.

connectivity.adjacencyArrays(elems, nsteps=1)

Create adjacency arrays for 2-node elements.

elems is a (nr,2) shaped integer array. The result is a list of adjacency arrays, where row i of adjacency array j holds a sorted list of the nodes that are connected to node i via a shortest path of j elements, padded with -1 values to create an equal list length for all nodes. This is: [adj0, adj1, ..., adjj, ... , adjn] with n=nsteps.

connectivity.connected(index, i)

Return the list of elements connected to element i.

index is a (nr,nc) shaped integer array. An element j of index is said to be connected to element i, if element j has at least one (non-negative) value in common with element i.

The result is a sorted list of unique element numbers, not containing the element number i itself.

connectivity.adjacent(index, inv=None)

Return an index of connected elements.

index is a (nr,nc) shaped integer array. An element j of index is said to be connected to element i, if element j has at least one (non-negative) value in common with element i.

The result is an integer array with shape (nr,mc), where row i holds a sorted list of the elements that are connected to element i, padded with -1 values to create an equal list length for all elements.

The result of this method provides the same information as repeated calls of connected(index,i), but may be more efficient if nr becomes large.

The inverse index may be specified, if it was already computed.

connectivity.closedLoop(elems)

Check if a set of line elements form a closed curve.

elems is a connection table of line elements, such as obtained from the fuse() method on a plex-2 Formex.

The return value is a tuple of:

  • return code:
    • 0: the segments form a closed loop
    • 1: the segments form a single non-closed path
    • 2: the segments form multiple not connected paths
  • a new connection table which is equivalent to the input if it forms a closed loop. The new table has the elements in order of the loop.
connectivity.connectedLineElems(elems)

Partition a segmented curve into connected segments.

The input argument is a (nelems,2) shaped array of integers. Each row holds the two vertex numbers of a single line segment.

The return value is a list of (nsegi,2) shaped array of integers.

Documentation

Previous topic

7. geometry — A generic interface to the Coords transformation methods

Next topic

9. simple — Predefined geometries with a simple shape.

This Page