OrdinaryPercolation

class OrdinaryPercolation(*args, **kwargs)[source]

Bases: openpnm.algorithms.GenericAlgorithm.GenericAlgorithm

Ordinary percolation simulation with or without access limitations.

Parameters
  • network (OpenPNM Network object) – The Network upon which this simulation should be run

  • name (string, optional) – An identifying name for the object. If none is given then one is generated.

  • project (OpenPNM Project object) – Either a Network or a Project must be specified

Notes

Ordinary percolation refers the process of finding all bonds or sites in the network that can be invaded at a given threshold, then setting them all to invaded in a single step.

Optionally, it is possible to then find the clusters of invaded bonds or sites that are NOT connected to the inlets and setting them back to an uninvaded state.

An overview of percolation theory can be found on Wikipedia

If the simulation is repeated for increasing threshold values until the entire domain is invaded, then a percoaltion curve is obtained. The threshold at which each site and bond was invaded is recorded, so it is possible to find invading configurations easily using Boolean logic.

Method

Description

reset

Resets the various data arrays on the object…

setup

Used to specify necessary arguments to the s…

set_inlets

Set the locations from which the invader ent…

set_outlets

Set the locations through which defender exi…

set_residual

Specify locations of any residual invader. …

run

Runs the percolation algorithm to determine …

get_percolation_t…

Finds the threshold value where a percolating…

is_percolating

Returns a True or False value to indicate if…

get_intrusion_data

Obtain the numerical values of the calculate…

plot_intrusion_curve

Plot the percolation curve as the invader vo…

get_intrusion_data(Pc=None)[source]

Obtain the numerical values of the calculated intrusion curve

Returns

  • A named-tuple containing arrays of applied capillary pressures and

  • invading phase saturation.

get_percolation_threshold()[source]

Find the invasion threshold at which a cluster spans from the inlet to the outlet sites

is_percolating(applied_pressure)[source]

Returns a True or False value to indicate if a percolating cluster spans between the inlet and outlet pores that were specified at the given applied pressure.

Parameters

applied_pressure (scalar, float) – The pressure at which percolation should be checked

Returns

Return type

A simple boolean True or False if percolation has occured or not.

plot_intrusion_curve(fig=None)[source]

Plot the percolation curve as the invader volume or number fraction vs the applied capillary pressure.

reset()[source]

Resets the various data arrays on the object back to their original state. This is useful for repeating a simulation at different inlet conditions, or invasion points for instance.

results(Pc=None)[source]

This method determines which pores and throats are filled with invading phase at the specified capillary pressure, and creates several arrays indicating the occupancy status of each pore and throat for the given pressure.

Parameters

Pc (scalar) – The capillary pressure for which an invading phase configuration is desired.

Returns

  • A dictionary containing an assortment of data about distribution

  • of the invading phase at the specified capillary pressure. The data

  • include

  • **’pore.occupancy’** (A value between 0 and 1 indicating the)

  • fractional volume of each pore that is invaded. If no late pore

  • filling model was applied, then this will only be integer values

  • (either filled or not).

  • **’throat.occupancy’** (The same as ‘pore.occupancy’ but for throats.)

  • This dictionary can be passed directly to the update method of

  • the *Phase object. These values can then be accessed by models*

  • or algorithms.

run(points=25, start=None, stop=None)[source]

Runs the percolation algorithm to determine which pores and throats will be invaded at each given pressure point.

Parameters
  • points (int or array_like) – An array containing the pressure points to apply. If a scalar is given then an array will be generated with the given number of points spaced between the lowest and highest values of throat entry pressures using logarithmic spacing. To specify low and high pressure points use the start and stop arguments.

  • start (int) – The optional starting point to use when generating pressure points. If not given the half the lowest capillary entry pressure in the network is used.

  • stop (int) – The optional stopping point to use when generating pressure points. If not given, then twice the highest capillary entry pressure in the network is used.

Note

The inlet sites are set to invaded to start the simulation. This means that if ‘internal’ pores are used as inlets the capillary pressure curve will begin at a non-zero invading phase saturation. To avoid this either set the inlet pore volumes to zero or add boundary pores to the inlet face, and set their volumes to zero.

set_inlets(pores=[], overwrite=False)[source]

Set the locations from which the invader enters the network

Parameters
  • pores (array_like) – Locations that are initially filled with invader, from which clusters grow and invade into the network

  • overwrite (boolean) – If True then all existing inlet locations will be removed and then the supplied locations will be added. If False (default), then supplied locations are added to any already existing inlet locations.

set_outlets(pores=[], overwrite=False)[source]

Set the locations through which defender exits the network.

This is only necessary for calculating the percolation threshold.

Parameters
  • pores (array_like) – Locations where the defender can exit the network. Any defender that does not have access to these sites will be trapped.

  • overwrite (boolean) – If True then all existing outlet locations will be removed and then the supplied locations will be added. If False (default), then supplied locations are added to any already existing outlet locations.

set_residual(pores=[], throats=[], overwrite=False)[source]

Specify locations of any residual invader. These locations are set to invaded at the start of the simulation.

Parameters
  • pores (array_like) – The pores locations that are to be filled with invader at the beginning of the simulation.

  • throats (array_like) – The throat locations that are to be filled with invader at the beginning of the simulation.

  • overwrite (boolean) – If True then all existing inlet locations will be removed and then the supplied locations will be added. If False, then supplied locations are added to any already existing locations.

setup(phase=None, access_limited=None, mode='', throat_entry_pressure='', pore_entry_pressure='', pore_volume='', throat_volume='')[source]

Used to specify necessary arguments to the simulation. This method is useful for resetting the algorithm or applying more explicit control.

Parameters
  • phase (OpenPNM Phase object) – The Phase object containing the physical properties of the invading fluid.

  • access_limited (boolean) – If True the invading phase can only enter the network from the invasion sites specified with set_inlets. Otherwise, invading clusters can appear anywhere in the network. This second case is the normal ordinary percolation in the traditional sense, while the first case is more physically representative of invading fluids.

  • mode (string) –

    Specifies the type of percolation process to simulate. Options are:

    ’bond’ - The percolation process is controlled by bond entry thresholds.

    ’site’ - The percolation process is controlled by site entry thresholds.

  • pore_entry_pressure (string) – The dictionary key on the Phase object where the pore entry pressure values are stored. The default is ‘pore.capillary_pressure’. This is only accessed if the mode is set to site percolation.

  • throat_entry_pressure (string) – The dictionary key on the Phase object where the throat entry pressure values are stored. The default is ‘throat.capillary_pressure’. This is only accessed if the mode is set to bond percolation.

  • 'pore_volume' (string) – The dictionary key containing the pore volume information.

  • 'throat_volume' (string) – The dictionary key containing the pore volume information.