porescene.model module

Pore Networks

class porescene.model.PoreNetwork[source]

Bases: object

classmethod from_mat(pth, vars_nwk, vars_state={}, no_states=[], *, swap_axes=True)[source]

Creates a PoreNetwork instance by importing the pore network data from a MATLAB .mat file.

Attention

Variable import from .mat files is only supported for MATLAB files in version 7.3 that are based on HDF5. When saving the MATLAB file, make sure to set the -v7.3 in MATLAB’s save function.

MATLAB
1save('myfile.mat', "-v7.3");

Attention

While the first index in MATLAB arrays is 1, Python (and numpy) arrays are 0-indexed. This importer function automatically converts the MATLAB indices into 0-based Python indices.

Note that this applies to following properties:

Attention

MATLAB stores multi-dimensional arrays in column-major order, while numpy defaults to row-major order. Dumping a voxel image out of MATLAB and reading it back with numpy (e.g. via numpy.fromfile() followed by reshape()) therefore reverses the storage order of its dimensions, which swaps the array’s first and third (spatial) axes while leaving the second axis untouched – what MATLAB calls its first dimension ends up as numpy’s third axis, and vice versa, while the second dimension stays in place.

Since porescene.utility.volume2mesh() builds its mesh directly from such a numpy voxel array, meshes it produces have their first and third axes swapped relative to the coordinate frame the .mat file’s own variables (e.g. pos_p) were written in. By default (swap_axes=True), this importer swaps the first and third columns of every imported position array (PoreNetwork.pore_position and its _top/_bottom/_left/ _right/_front/_back variants) to match, so pore/throat coordinates line up with meshes built by volume2mesh(). Pass swap_axes=False to import the coordinates verbatim in the MATLAB axis order instead, e.g. when no voxel-image mesh is involved.

Parameters:

  • pth (Path) – Path to the MATLAB .mat file.

  • vars_nwk (dict[str, str]) – A map that specifies the corresponding variables in the .mat file for the properties of the PoreNetwork instance.

  • vars_state (dict[str, tuple[str, str]]) –

    A map that relates the variables from the .mat file to PoreNetworkProperty instances.

    The key in the dict has to be identical to PoreNetworkProperty.name, and the value is a tuple containing two string, mapping the variables names that hold the pore and throat data, respectively.

    As example: in case for "temperature" field data, the .mat file contains a variable T_pores that holds the temperature of each pore, while the variable T_throats holds the temperature values of each throat.

    Imagine, also some acetone concentration has been computed, an additional key "concentration_acetone" has to be added in a similar way to the dict.

    Python
    1state_vars = {
2    "temperature": ("T_pores", "T_throats")
3    "concentration_acetone": ("C_acetone_pores", "C_acetone_throats")
4}

    By convention, the first array dimension is equal to the number of pores/ throats, while the second dimension contains the evolution of the field, e.g in case of the temperature field, it might be the temporal evolution (when the pore network contains 6274 pores and 149366 throats, and 1000 temperature steps have been calculated, variable T_pores has a size of 6274 × 1000 and T_throats has a size of 149366 × 1000).

  • no_states (list[int]) –

    In case there is state data contained in the .mat file, the state indices given in states, are wrapped into PoreNetworkState instances.

    For example, if 1000 states have been calculated, but only every 100th state should be visualized, then no_states could be:

    Python
    1no_states = np.linspace(0, 1000, num=10)

  • swap_axes (bool) – If True (default), swaps the first and third columns of every imported position array to compensate for the MATLAB/numpy axis-order mismatch described above, e.g. aligning coordinates with meshes built by porescene.utility.volume2mesh(). Set to False to import the coordinates verbatim, in the MATLAB axis order.

Returns:

PoreNetwork instance created from given .mat file

Return type:

Self

add_state(no_state)[source]

Adds a PoreNetworkState to the current model instance.

Return type:

Self

get_state(no_state)[source]

Returns a PoreNetworkState from the instance.

Return type:

PoreNetworkState

throat_count(left=False, right=False, front=False, back=False, bottom=False, top=False)[source]

Number of throats in the network.

Parameters:

  • left (bool) – If true, outgoing throats on the left domain boundary are included in the throat count, by default False.

  • right (bool) – If true, outgoing throats on the right domain boundary are included in the throat count, by default False.

  • front (bool) – If true, outgoing throats on the front domain boundary are included in the throat count, by default False.

  • back (bool) – If true, outgoing throats on the back domain boundary are included in the throat count, by default False.

  • bottom (bool) – If true, outgoing throats on the bottom domain boundary are included in the throat count, by default False.

  • top (bool) – If true, outgoing throats on the top domain boundary are included in the throat count, by default False.

Returns:

Number of throats.

Return type:

int

property extent: ndarray

Physical dimensions (x, y, z) of the pore network domain.

property length_x: float

Physical extent of the pore network domain in first dimension.

property length_y: float

Physical extent of the pore network domain in second dimension.

property length_z: float

Physical extent of the pore network domain in third dimension.

property pnp: ndarray | None

Neighbor pores of each pore.

property pore_coordination_number: ndarray | None

Coordination number of each pore.

property pore_count: int

Number of pores in the network.

property pore_neighboring_pores: ndarray | None

Neighbor pores of each pore.

property pore_position: ndarray | None

Position of each pore.

property pore_position_back: ndarray | None

Position of each node at the sample bottom surface.

property pore_position_bottom: ndarray | None

Position of each node at the sample bottom surface.

property pore_position_front: ndarray | None

Position of each node at the sample bottom surface.

property pore_position_left: ndarray | None

Position of each node at the left sample surface.

property pore_position_right: ndarray | None

Position of each node at the right sample surface.

property pore_position_top: ndarray | None

Position of each node at the top sample surface.

property pore_radius: ndarray | None

Radius of each pore.

property pores_back: ndarray | None

Pores located at the back domain interface that have a connection to the surrounding.

property pores_bottom: ndarray | None

Pores located at the sample bottom interface that have a connection to the surrounding.

property pores_front: ndarray | None

Pores located at the front domain interface that have a connection to the surrounding.

property pores_left: ndarray | None

Pores located at the left domain interface that have a connection to the surrounding.

property pores_right: ndarray | None

Pores located at the right domain interface that have a connection to the surrounding.

property pores_top: ndarray | None

Pores located at the sample top interface that have a connection to the surrounding.

property states: list[PoreNetworkState]
property throat_coordination_number: ndarray | None

Coordination number of each throat.

property throat_length: ndarray | None

Length of each throat.

property throat_neighboring_pores: ndarray | None

Neighbor pores of each throat.

property throat_radius: ndarray | None

Radius of each throat.

property throat_radius_back: ndarray | None

Radius of each throat connection into the surrounding at the back domain boundary.

property throat_radius_bottom: ndarray | None

Radius of each throat connection into the surrounding at the bottom domain boundary.

property throat_radius_front: ndarray | None

Radius of each throat connection into the surrounding at the front domain boundary.

property throat_radius_left: ndarray | None

Radius of each throat connection into the surrounding at the left domain boundary.

property throat_radius_right: ndarray | None

Radius of each throat connection into the surrounding at the right domain boundary.

property throat_radius_top: ndarray | None

Radius of each throat connection into the surrounding at the top domain boundary.

property tnp: ndarray | None

Neighbor pores of each throat.

class porescene.model.PoreNetworkProperty(n)[source]

Bases: object

A wrapper for a single property of one state of a pore network.

set_data(vals_p, vals_t)[source]

Sets pore and throat related data at once.

Return type:

Self

property max: float

Hightest value from all values across pores and throats.

property min: float

Lowest value from all values across pores and throats.

property name: str

Name of the property.

property pore_values: ndarray | None

Pore related data values.

property throat_values: ndarray | None

Throat related data values.

class porescene.model.PoreNetworkState[source]

Bases: object

A wrapper for one state of a pore network.

add_property(prop)[source]

Add a PoreNetworkProperty.

Return type:

Self

get_property(name)[source]

Returns a PoreNetworkProperty by name.

Return type:

PoreNetworkProperty

has_property(name)[source]

Check if the model has data about property name.

Return type:

bool

property no: int
property properties: list[PoreNetworkProperty]
property time_points: list[float]