class*args, **kwargs)[source]

Crystal lattice types including fcc, bcc, sc, and hcp

These arrangements not only allow more dense packing than the standard Cubic for higher porosity materials, but also have more interesting non-straight connections between the various pore sites.

More information on Bravais lattice notation can be found on wikipedia.

  • shape (array_like) – The number of pores in each direction. This value is a bit ambiguous for the more complex unit cells used here, but generally refers to the the number for ‘corner’ sites

  • spacing (array_like (optional)) – The spacing between pores in all three directions. Like the shape this is a bit ambiguous but refers to the spacing between corner sites. Essentially it controls the dimensions of the unit cell. If a scalar is given it is applied to all directions. The default is 1.

  • mode (str) –

    The type of lattice to create. Options are:


    Simple cubic (Same as Cubic)


    Body-centered cubic lattice


    Face-centered cubic lattice


    Hexagonal close packed (Note Implemented Yet)

  • name (str) – An optional name for the object to help identify it. If not given, one will be generated.

See also

Cubic, CubicDual


The pores are labelled as beloning to ‘corner_sites’ and ‘body_sites’ in bcc or ‘face_sites’ in fcc. Throats are labelled by the which type of pores they connect, e.g. ‘throat.corner_to_body’.


  • Bravais lattice can also have a skew to them, but this is not implemented yet.

  • Support for 2D networks has not been added yet.

  • Hexagonal Close Packed (hcp) has not been implemented yet, but is on the todo list.


import openpnm as op
import matplotlib.pyplot as plt

sc =[3, 3, 3], mode='sc')
bcc =[3, 3, 3], mode='bcc')
fcc =[3, 3, 3], mode='fcc')

# Since these three networks all have the same domain size, it is clear
# that both 'bcc' and 'fcc' have more pores per unit volume. This is
# particularly helpful for modeling higher porosity materials.
print(sc.Np, bcc.Np, fcc.Np)

# They all have the same number corner sites, which corresponds to the
# [3, 3, 3] shape that was specified

# Shift 'bcc' and 'fcc' networks by 3 and 6 units, respectively, so
# we can visualize them side by side in a single figure
bcc['pore.coords'][:, 0] += 3
fcc['pore.coords'][:, 0] += 6

# Visualization of these three networks can be done quickly using the
# functions in topotools. Firstly, merge them all into a single network
# for convenience
op.topotools.merge_networks(sc, [bcc, fcc])

fig, ax = plt.subplots(figsize=(6, 6))
op.topotools.plot_connections(sc, ax=ax)

For larger networks and more control over presentation use Paraview.


A shortcut to query the total number of pores on the object


A shortcut to query the total number of throats on the object


A shortcut to get a list of all pores on the object


A shortcut to get a list of all throats on the object


Adjacency matrix in the specified sparse format, with throat IDs indicating the non-zero values.


Returns the connectivity matrix of the network.


Returns the list of pore coordinates of the network.


Incidence matrix in the specified sparse format, with pore IDs indicating the non-zero values.


List of available models on the objects


String representing the name of the object


A shortcut to get a handle to the associated network.


A shortcut to get a handle to the associated project.


Dictionary containing object settings.


add_boundary_pores(labels, spacing)

Add boundary pores to the specified faces of the network

add_model(propname, model[, regen_mode])

Adds a new model to the models dictionary.


This method check the network topological health.

create_adjacency_matrix([weights, fmt, ...])

Generates a weighted adjacency matrix in the desired sparse format

create_incidence_matrix([weights, fmt, ...])

Creates a weighted incidence matrix in the desired sparse format

filter_by_label([pores, throats, labels, mode])

Returns which of the supplied pores (or throats) has the specified label(s)

find_connected_pores([throats, flatten, mode])

Return a list of pores connected to the given list of throats

find_connecting_throat(P1, P2)

Return the throat index connecting pairs of pores.

find_nearby_pores(pores, r[, flatten, ...])

Find all pores within a given radial distance of the input pore(s) regardless of whether or not they are toplogically connected.

find_neighbor_pores(pores[, mode, flatten, ...])

Returns a list of pores that are direct neighbors to the given pore(s)

find_neighbor_throats(pores[, mode, flatten])

Returns a list of throats neighboring the given pore(s)


Adjacency matrix in the specified sparse format, with throat IDs indicating the non-zero values.

get_conduit_data(poreprop[, throatprop, mode])

Combines requested data into a single 3-column array.


Incidence matrix in the specified sparse format, with pore IDs indicating the non-zero values.


Retrieves requested property from associated objects, to produce a full Np or Nt length array.

interpolate_data(propname[, mode])

Determines a pore (or throat) property as the average of it's neighboring throats (or pores)

labels([pores, throats, element, mode])

Returns a list of labels present on the object

num_neighbors(pores[, mode, flatten])

Returns the number of neigbhoring pores for each given input pore

num_pores([labels, mode])

Returns the number of pores of the specified labels

num_throats([labels, mode])

Return the number of throats of the specified labels


Return parameter names and values in a dictionary

pores([labels, mode, asmask, to_global])

Returns pore indicies where given labels exist, according to the logic specified by the mode argument.

props([element, mode, deep])

Returns a list containing the names of all defined pore or throat properties.

regenerate_models([propnames, exclude, deep])

Re-runs the specified model or models.

remove_model([propname, mode])

Removes model and data from object.

set_label(label[, pores, throats, mode])

Creates or updates a label array

show_hist([props, bins, fontsize])

Shows a quick plot of key property distributions.

throats([labels, mode, asmask, to_global])

Returns throat locations where given labels exist, according to the logic specified by the mode argument.


Converts a boolean mask to a list of pore or throat indices.

to_mask([pores, throats])

Convert a list of pore or throat indices into a boolean mask of the correct length.