A Python package for performing pore network modeling of porous media

Last update: Dec 30, 2022

Overview

Overview of OpenPNM

OpenPNM is a comprehensive framework for performing pore network simulations of porous materials.

More Information

For more details about the package can be found in the on-line documentation

Stay Informed

It is surprizingly hard to communicate with our users, since Github doesn't allow sending out email newsletters or announcements. To address this gap, we have created a Substack channel, where you can subscribe to our feed to receive periodic news about important events and updates. Also, follow us on Twitter (@OpenPnm) for periodic announcements about new releases and other important events.

Installation and Requirements

Preferred method

The preferred way of installing OpenPNM is through Anaconda Cloud using:

conda install -c conda-forge openpnm

Alternative method

OpenPNM can also be installed from the Python Package Index using:

pip install openpnm

However, we don't recommend installing using pip since pypardiso, which is a blazing fast direct solver, is not available for Windows users who use Python 3.7+.

For developers

For developers who intend to change the source code or contribute to OpenPNM, the source code can be downloaded from Github and installed by running:

pip install -e 'path/to/downloaded/files'

The advantage to installing from the source code is that you can edit the files and have access to your changes each time you import OpenPNM.

OpenPNM requires the Scipy Stack (Numpy, Scipy, Matplotlib, etc), which is most conveniently obtained by installing the Anaconda Distribution.

Example Usage

The following code block illustrates how to use OpenPNM to perform a mercury intrusion porosimetry simulation:

import openpnm as op
pn = op.network.Cubic(shape=[10, 10, 10], spacing=0.0001)
geo = op.geometry.SpheresAndCylinders(network=pn, pores=pn.Ps, throats=pn.Ts)
Hg = op.phases.Mercury(network=pn)
phys = op.physics.Standard(network=pn, phase=Hg, geometry=geo)
mip = op.algorithms.Porosimetry(network=pn, phase=Hg)
mip.set_inlets(pores=pn.pores(['left', 'right', 'top', 'bottom']))
mip.run()

The network can be visualized in ParaView giving the following:

The drainage curve can be visualized with mip.plot_intrusion_curve() giving something like this:

A collection of examples is available in the examples folder of this repository: Examples

Asking Questions and Getting Help

Github now has a Discussions function, which works similarly to stack overflow. Please post your question in the Q&A category so devs or users can provide answers, vote on accepted answers, improve on each other's answers, and generally discuss things. Most importantly, all answers are searchable so eventually, once enough questions have been posted and answered, you can find what you're looking for with a simple search.

Contact

OpenPNM is developed by the Porous Materials Engineering and Analysis Lab (PMEAL), in the Department of Chemical Engineering at the University of Waterloo in Waterloo, Ontario, Canada.

The lead developer for this project is Prof. Jeff Gostick ([email protected]).

Acknowledgements

OpenPNM is grateful to CANARIE for their generous funding over the past few years. We would also like to acknowledge the support of NSERC of Canada for funding many of the student that have contributed to OpenPNM since it's inception in 2011.

Citation

If you use OpenPNM in a publication, please cite the following paper:

Gostick et al. "OpenPNM: a pore network modeling package." Computing in Science & Engineering 18, no. 4 (2016): 60-74. doi:10.1109/MCSE.2016.49

Also, we ask that you "star" ⭐ this repository so we can track the number of users who are interested in this project, which is helpful for securing future grant funding.

Comments

Visualize Throats in Paraview

This would be very useful to help ensure things are looking right, but at the moment my Paraview simulations only show lines between pores.

I recall that @jhinebau once sent me a complex recipe for putting throat cylinders in paraview (using a series of paraview commands), but I wonder if there is something we can do to the output VTP files to include exactly what paraview needs to simply add oriented gliphs?

GanttDue: 2018-10-25
enhancement

opened by jgostick 31
Dirichlet to value and Neumann to rate?

The ambiguity of the neumann boundary condition is causing problems...apparently OpenFOAM calls them fixed_value and fixed_rate. Should we just go with value and rate?
discussion

opened by jgostick 27
Not able to run version 1.6

Hi, This might be a trivial issue, but I am not able to solve it. I have done a clean install of the version 1.6 on Winpython 3.4.4.6. But I am not able to do anything thereafter. I keep getting the following error " ImportError: No module named 'openPNM' "

I did not have any problems like this with the previous version. I have tried changing the path variable but that did not work. Could anyone please help?

Regards Deep
question

opened by DMaxJ 22
Issue with the permeability computation from IO.Statoil network

The Permeability calculation by OpenPNM seems to underestimate its actual value about 2 times compared to other codes; there's maybe a missing (x2) factor somewhere in the code....I can't figure out where. Any suggestion?

opened by mtembel 21
Stitching parts of different networks together

Hello everyone!

I am thinking about stitching together networks in such a manner that for example I take 2 times 10x10x10 networks with x width, and I would like to create a new network in which every pore and throat below x/2 (width) inherits 1st network's properties, and above x/2 inherits 2nd network's properties (so connections, geometries remain). Throats which overlap with both sides should be trimmed, and connections should be made with the closest possible pores at the boundaries. I would like to inquire if there is any command that could help me or do I have to create this function from the very beginning?

Thank you for your help! :)
question

opened by Eravalord 20
What to do about Boundary Pores
I think we need to think about a proper treatment of boundary pores for both linear transport and percolation. And whether we need them and whether taking them out causes more problems than keeping them. Currently they are causing a lot of issues for the conductance models.

They are useful for percolation when you want to start the simulation with zero saturation

They are useful for transport for when you need a coplanar face for effective properties

They are annoying as part of the model framework where they may not contain the data needed for some models to work and end up having unphysical values or fudged data

They are easy to add to cubic networks but not random or extracted

So is it more useful and consistent to treat them as real pores in a sort of ultra high-porous material that sits directly in contact with the main domain and give them real diameters, volumes, conductances. Then when doing percolation and stuff it's simple enough to look at saturation in a bulk geometry rather than the whole domain. Or is it better to not give them any physical properties, maybe not even a geometry so that all the interleaved data returns nans and then give them special treatment in the conductance models - fudging the nans into real values when needed?
discussion
opened by TomTranter 18
flow_shape_factor models yield nans when L / D > 0.5

The problem is on this line

The arctan term goes to inf when the argument == 1 and nan when arg > 1, so when L / D > 0.5 it's then multiplied by 2, and creates an undefined result. This is putting nans in the hydraulic conductance array.
bug high priority

opened by jgostick 17
Added I/O support for JSON Graph Format
List of changes:

This PR adds an I/O class called JSONGraphFormat that is able to .save() and .load() network geometry files in the JSON Graph Format.

The adherence to the format is enforced by means of .__validate_json__(), that checks the JSON file against the jgf_schema.pkl.

This validation functionality requires the jsonschema module, which I added to conda_requirements.txt.

Two unit tests were created for each of the JSONGraphFormat class methods: one for the success, one for the failure. Appropriate fixtures were created to support the tests. The new classes have 100% test coverage.

Bonus: I also added .editorconfig to help you standardise the code formatting across many developers and IDEs.

Closes #934
opened by neumannrf 17
Removing pores/throats

I'm hitting some hard to figure out bugs trying to debug the prune method on my Template class.

I have a network for which I already set the pore info and pore data corresponding to a certain set of points and point pairs. Further attempts to change this structure are impeded by the "self protecting" nature of the dictionary. How can I override these and ensure that any other constants/attributes being used to keep em in check are overridden as well?
enhancement

opened by HaroldDay 17
Read networkx graph object directly
As per personal communication with @jgostick , NetworkX.load() is replaced by a function that accepts a networkX graph directly, instead of using an intermediate YAML file.

Checks on the input graph:

Checking if supplied object is networkX graph

Checking if supplied graph is undirected

Checking if numbering of G.nodes() contains any gaps

Checking if numbering of G.nodes() starts at 0

The implementation is very similar to the original YAML approach. There was no need to remove duplicates from conns anymore, but it's still sorting because I could not determine if G.edges() returns a sorted list.

I didn't manage to fill an ndarray of strings, such as _sp.ndarray((N,M), dtype=str), correctly. hence there are a few checks to see if dtype is str. Without these checks and the use of dtype='object', the ndarray would contain only empty strings. Perhaps there is a more elegant way to handle this?

Lastly, test_load_networkx in IOTest.py will need to be updated.
opened by joosthvanderlinden 16
K of Berea sandstone

Hi, I tried to test the example of importing data from ICL and fortunately I got the results , but the K measured by OpenPNM is 4700md, which is quite different from the value from ICL, about 1486mD. So what causes that? My idea is the trim operation or the random data extracted from ICL (Berea)data?
bug pore-scale model

opened by johnwebster 16
Elaborate in docs about how models can be run manually

It would give people confidence in the models if they could run them themselves and see the results returned. OpenPNM collects these results, but users can run the models too.
documentation

opened by jgostick 0
proj_to_vtk breaks when drainage and/or invasion algorithms present

As mentioned in #2659 the io function is looking for a soln attribute on the algorithms and not finding it. Also I think it's looking for a quantity key in the settings. Basically the io function is assuming that only transport algorithms are present.

Actually, I'm wondering why it's looking for algorithms at all...I think these functions only output the network and phases?
bug

opened by jgostick 0
the size_by argument in plot_coordinates should be squared internally

The size used by matplotlib refers to the area of the markers not the diameter. When passing 'pore.diameter' to the size_by it doesn't quite work, but if you do 'pore.diameter'**2 they markers are sized correctly. We should probably do this internally.
enhancement easy

opened by jgostick 0
Create a tutorial for Nernst-Planck and charge transport equations

Hello, please consider developing an example notebook on how to use OpenPNM v3 for a simple Nernst Planck implementation with charge conservation equations. Thank you!

opened by pbriml 3

Releases(v3.1.1)

v3.1.1(Dec 30, 2022)
:bug: Bugfixes

Fixed center-to-center throat length helper model to always return an array

Source code(tar.gz)
Source code(zip)
v3.1.0(Nov 13, 2022)
:rocket: New features

Added wrapper for pyamg.ruge_stuben_solver to openpnm.solvers

:cake: Enhancements

Fetching 'pore.source' from an algorithm without any source terms defined returns empty dict instead of KeyError

:wrench: Maintenance

Removed the use of py from unit tests

Switched CI linter from pycodestyle to flake8

Fixed numerous style errors throughout to satisfy flake8

:green_book: Documentation

Enhanced some example notebooks, added a new notebook on managing clustered networks

Source code(tar.gz)
Source code(zip)
v3.0.0(Oct 12, 2022)
:fireworks: Major Changes

Removed geometry and physics modules

Removed use of Geometry and Physics objects

Moved plot functions from topotools to a new visualization module

Removed materials and metrics modules in favor of creating detailed examples

Removed the term Generic from all class names to improve readability #api

:rocket: New features

Added a solvers module containing classes that define a generic api for using arbitrary numerical solvers

Added an integrators module containing classes that define the api for transient solvers

Added a wrapper to leverage the scipy.integrate.ivp_solve function for transient problems

Added Demo network generator which includes geometry models already assigned and ready for instant use

Added official support for mixtures, including pore-scale models for first-approximation calculations of pure and mixture properties

Added topotools.find_interface_throats to find throats between two sets of pores

Added SteadyStateSolution class for storing the results of steady state algorithms

Added TransientSolution class for storing results of transient algorithms at each time step, including ability to interpolate between times

Added mechanism to declare any property to be variable (i.e. a function of the solved quantity)

Added a params attribute to all objects for storing scalar values and constants

Added support to the dictionary objects for pn['param.foo'] which looks up values from pn.params['foo'] in a way that works seamlessly with existing pore-scale models

Added x as a property to Transport classes for easy access to the solved quantity

Added ability to compute the physical properties of arbitrary pure gases and liquids using correlations from the chemicals package

Added a framework for computing properties of mixtures as a function of composition using correlations from the chemicals package

Added generate_voxel_image to visualization module

Added a set of pore-scale topology models under models.network

Added plot_network_jupyter function to visualization module which creates an interactive visualization using Plotly

Created a contrib folder/module for putting experimental and beta features, and well as contributions before they are adopted into the main code base

Added TransientMultiPhysics class to the contrib folder

Added new plot_network function based on vispy to contrib folder

Revised the settings attribute on objects to work more like python's dataclasses with settings as attributes, while also enforcing their type

:cake: Enhancements

Adopted rich package for formatting logger messages

Added ScipyCG to the solvers module (uses scipy.sparse.linalg.cg)

Added intersecting_cones/pyramids size factor models, as well as hybrid cones_and_cylinders which adopt intersecting cones/pyramids as needed

Re-implemented the percolation algorithms for better consistency between them

Added call method to ModelWrapper so they can run themselves directly with zero effort by user

Enhanced BV formulations to allow variable number of electrons

Created openpnm.models.collections containing dict files of preset models for all sub-classes to simplify instantiation

Allowed setting of default solver in the workspace.settings

Enhance _validate_data_health to account for throats without an assigned conductance model

Augmented getitem on dictionaries to return a numeric value if used as a key, so pn[1.0] returns 1.0. This allows passing in scalar values to pore-scale models with no need to assign that scalar to all locations first

Add tqdm progress bar for Newton iterations in ReactiveTransport

Added asmask argument to neighbor lookup functions

Added ability to delete nested/hierarchical keys simultaneously (i.e. del obj['pore.nested'])

Added a pore-scale model function for generating values according to a given a histogram

Added a check for stall in ReactiveTransport

Relaxed convergence checks in ReactiveTransport to facilitate iterative solves

Project, models, and settings are now pretty-printed when evaluated at REPL (IPython console)

Updated math functions in misc to accept an array of props instead of individual args

added get_conduit_data method to Base class

Enhanced versioning so that dev builds get their own "build number" as X.Y.Z.devN

:wrench: Maintenance

Got code coverage to 90%

Removed several minor dependencies including flatdict which is no longer maintained

The dependencies in requirements.txt are now synced with those in setup.py

Stopped getting logger from root level to prevent interfering with other packages' outputs

Fixed exporting transient data to paraview to work with new TransientSolution class

Settings are applied after calling super().init and they are no longer passed up the init chain

Moved iterative props machinery to Algorithm

Fixed string splitting at dots to work better with multi-dot name

Improved handling of missing keys on Phase objects for cleaner tracebacks when autointerpolation is enables

Major refactor of topotools module into library of functions requiring no openpnm specific classes

Modules/submodules in setup.py are now automatically filled using setuptools package

Replaced for-loop with numpy unbuffered operations in surface area models

Reorganized openpnm.models.misc/phase/physics modules to keep namespace clean

Removed relaxation_source from ReactiveTransportSettings as we no longer apply relaxation to source term

Leveraged __all__ functionality throughout code to control imports of functions

Added a runtime check to see if x0 contains infs/nans

Refactored Transport to put boundary condition functions in a mixin

Added unit tests for Salome, COMSOL, and STL I/O classes

Changed regenerate_models to work when models lack regen_mode argument

Removed cache_b, changed cache_A to cache since b is very small

Removed numba deprecation warning

Updated list of rules to be ignored by flake8 style check

Removed freeze_models option from ModelsMixin

Deleted many unused functions from utils.misc

Added style check workflow to actions

Refactor Transport and subclassed algorithms' run method

Switched to scipy's convergence checker

Refactor of set_label

Removed "internal" label from Bravais and CubicDual

Broke up Base class into several mixins for more control of inheritance #maint

:warning: API changes

Complete removal of Geometry and Physics objects, in favor of Network and Phase handling all related data and models directly

Renamed models.topology to models.network

Removed PETSc solver wrapper (needs to be revisited)

Removed MixedInvasionPercolation(Coop) and OrdinaryPercolation algorithms until they can be better supported

Replaced target keyword with network or phase throughout all pore-scale models, except ones that are truly general

Conduit properties and now stored as Nt-by-3 arrays instead of dicts

Changed how source terms are tracked from obj.settings['sources'] to obj[pore.sources'] to be consistent with how boundary conditions are tracked (i.e. alg['pore.bc.rate'])

Changed the behavior of the mode argument when adding boundary conditions

Converted the Project class to a minimal pseudo-list, with no extraneous methods inherited from list cluttering the namespace

Initialization of Base2 objects no longer accepts settings

Exposed iterative_props, removed set_variable_props

Removed ModelsMixin from Algorithm since algorithms don't typically need models

Removed prefix and name from settings

Refined the Butler-Volmer model formulations to match Newman's book

Created Drainage class in algorithms with more limited scope to replace OrdinaryPercolation and Porosimetry

Removed nlin_max_iter from ReactiveTransportSettings in favor of newton_maxiter

Move Multiphase to contrib folder to indicate it is experimental

Transport algorithms' run method now returns one or more Solution objects inside dictionary named according to the quantity they contain

Made network a mandatory argument on phase and algorithm objects

Renamed tomask and toindices to to_mask and to_indices since the underscore is the common convention in other packages like pandas

Moved get_domain_area and get_domain_length from attributes on transport algorithms to topotools, for more general use

Made phase a mandatory argument in algorithms instead of allowing it to be set in settings after the fact

Removed old multiphysics algorithms (PNP) in preparation for new approach

Removed effective property calculation methods from Transport since these can be computed by users themselves

Complete rewrite/redesign of linear solvers and transient algorithms

Added a Solution object for returning data from algorithms

Added a Solver class to handle matrix math which is passed as an argument to run methods

Removed StickAndBall geometry class (use SpheresAndCylinders instead)

Removed classic_ordinary_diffusion and classic_hagen_poiseuille conductance models

Refactored conductance models to work with size factors rather than shape factors

Removed redundant sympy source models and made generic one much easier to use

Removed num_points argument from Delaunay/Voronoi classes in favor points=int

Removed spacing and shape attribute from Cubic and moved to topotools as functions

Removed setup method from algorithms in favor of adding to settings attribute directly

Deprecated models.geometry.pore_area/throat_area in favour of pore/throat_cross_sectional_area

:bug: Bugfixes

Calling regenerate_models on a mixture now first regenerates each component

Fixed a critical bug in duplicate_throats

Fixed color_by argument in plot_coordinates/connections to accept partial list of values if pores/throats specified

Fixed ReactiveTransport's run method to accept instantiated solver, not the class itself

Fixed a bug in XDMF output where dimensions were reversed

Fixed bug in lens and pendular_ring models

Fixed bug in Transport to properly check for connected network including connections with boundary conditions

Fixed regex bug in setup.cfg that broke the 4th digit counter

:green_book: Documentation

Reorganized examples folder and documentation website

Refactored and automated generation of the documentation

Completely rewrote examples to form comprehensive tutorials and reference docs

Fixed module docstrings to satisfy sphinx

Updated list of options in docstrings to use tables

Applied docrep and matplotlib's substituion throughout the package to make docstrings more consistent

Removed tables of classes, methods and attributes from docstrings, and moved to sphinx docs instead

Fixed hydraulic conductance equation in docstring

Source code(tar.gz)
Source code(zip)
v2.8.2(Sep 8, 2021)
:bug: Bugfixes

Updated advection-diffusion and advection-diffusion-migration models to work with new size coefficient models #bug

Fixed bug/typo in the setup method of the classes TransientAdvectionDiffusion and TransientIonicConduction #bug

Source code(tar.gz)
Source code(zip)
v2.8.1(Aug 9, 2021)
:wrench: Maintenance

Improving error checking in snow2 test #maint

Source code(tar.gz)
Source code(zip)
v2.8.0(Aug 9, 2021)
:rocket: New features

Added new flexible species classes with properties determined using "chemicals" package #new

Added export to Statoil format and a wrapper for calling pnflow.exe #new

Added support for GPU solvers via CuPy library #new

Overhauled and renovated the conduit flow approach (see docs) #new

:cake: Enhancements

Updated PoreSpy IO class to work with PoreSpy V2 #enh

Enhance tic/toc functions #enh

Changed matplotlib backend to SVG in examples for sharper images #enh

Plot functions now accept axis as well as figure handles #enh

:wrench: Maintenance

Updated requirements in porespy_requirements.txt and in setup.py #maint

Add lower bound for docrep version in requirements #maint

Replaced pardiso4py with pypardiso (now officially in pip and conda-forge) #maint

Minor refactoring of TransientReactiveTransport to make it more readable #maint

Fixed incorrect scipy.sparse import in graphtools #maint

Fixed failing Ubuntu Action by adding openmpi as a test dependency #maint

:warning: API changes

Flipped "front" and "back" labels to respect the right-hand-rule #api

Added logger message to Cubic init notifying about front/back switch #api

plot_connections, plot_coordinates, and plot_intrusion_curve now accept axis obj rather than figure #api

ad_dif and ad_dif_mig conductance models no longer export local Peclet numbers #api

:bug: Bugfixes

Fixed bug in cylindrical point generator and replaced missing Delaunay example #bug

Flipped "front" and "back" labels to respect the right-hand-rule #bug

Corrected pore.seed in StickAndBall2D to be same as the 3D version #bug

:green_book: Documentation

Changed matplotlib backend to SVG in examples for sharper images #doc

Updated documentation to pydata theme #doc

Source code(tar.gz)
Source code(zip)
v2.7.0(Feb 24, 2021)
v2.7.0

:rocket: New features

Added a function to filter pores based on number of neighbors (topotools.filter_pores_by_z)

Added ability to open networks directly in paraview to the IO submodule

Added is_fully_connected function to topotools that is called by transport solvers ensure non-singular matrices, including connectivity between boundary pores

Added remove_source method to ReactiveTransport classes, and mode to set_source method

:cake: Enhancements

Fixed dependency_map to include pure props (those w/o an explicit model)

Enhanced dependency_map to show pores as circles and throats as squares [#1853]

Enhanced plot_coordinates defaults to make pores more visible [#1850]

Catch undefined pores/throats at runtime

:wrench: Maintenance

Update Actions to accommodate the native support for "ci skip" by GitHub [#1860]

Updated deprecated docrep methods [#1854]

Removed unused functions from misc module

Remove ReactiveTransport._set_variable_props

:warning: API changes

Fixed TransientReactiveTransport to always run until t_final (removed steady state check) [#1851]

Increased logger level to critical when saving PNM files

:bug: Bugfixes

Fixed subtle bug in MixedIP algorithm

Fixed a bug in spacing for Cubic networks with only two pores [#1844]

Fixed minor bug in trim if all throats are removed

Source code(tar.gz)
Source code(zip)
v2.6.0(Dec 4, 2020)
v2.6.0

:rocket: New features

Added source term models for Butler-Volmer kinetics

Added set_outflow_BC to NernstPlanck algorithm

Added a web-based dependency map using D3-tree javascript library

Added stitch_pores function to topotools for joining disconnected pores within an existing network

New robust version-agnostic PNM file format, see PR#1621 for details

set_rate_BC now optionally accepts total_rate, which is equally distributed among pores

Added name to settings

Added uuid to all objects (stored as a hidden setting _uuid)

Added a new grid class called Tableist to better handle the project grid

:cake: Enhancements

Add _validate_data_health to the run method of algorithms

Vastly improved the default formatting of show_hist's grid layout

Storing the transient solution times in the settings to make indexing into [email protected] arrays easier

Revamped the documentation, also it's now hosted on GitHub Pages (numba breaks readthedocs)

Exposed the ability to set/change/remove locations where physics and geometries are applied

Speed up neighbour throat lookups by ~100X

Enhanced extend function to work with phases present

Removing exception in stitch if phases are present

Allow merging of networks when geometry is present

Improved behavior when physics objects are instantiated without an associated phase

Improved grid functionality on the project class

Fixed PNM load_project method to deal with class attrs

Fixed scaling in plot_conns and plot_coords

:wrench: Maintenence

Improved the boundary condition setters to prevent invalid combinations

Changed _get_solver behavior to fall back to spsolve if pardiso missing

Refactored MultiPhase and fixed the global partition coefficient model's dependency handling bug

Extended checks for invalid 't_schemes' setting on transient algs

Added examples and tests for the Salome export class

Changed PARDISO solver backend from haasad/pypardiso to conda-forge/pardiso4py

:warning: API changes

Renamed throat_shape_factor submodule (+ dict keys in method args) to capillary_shape_factor for clarity

Renamed pore/throat_area submodules (+ dict keys in method args) to cross_sectional_area for clarity

Changed "_2D" to "2D" in class names and lowercased "_2D" in method names

Deprecating python 3.6

:bug: Bugfixes

Fixed bug in charge source term (in Nernst-Planck) that produced all 0s in some cases

Properly combine BCs and ICs on first time step in ReactiveTransientTransport

Saving to PNM now skips models with non-serializable args

Added a check to ensure phase is defined before running alg

Plot conns/coords methods now pass kwargs on to matplotlib functions

Workspace load_project now reads file AND returns the project

topotools.dimensionality is now more robust with respect to numerical round-off

Object names are now enforced to be unique within a project

Updated Imported geometry class to accept project as well as network

ReactiveTransport now checks for convergence when maximum iterations reached and reports if not achieved

:green_book: Documentation

Fixed a typo in data_and_topology_storage.ipynb example

adding readme to tutorials folder

New example discussing domain size calculations

Improved docstring in add_model to include new explicit mode

Fixed a typo in adding_boundary_pores.ipynb

Fixed a typo in docstrings of topotools.reduce_coordinates

Added a tutorial on using the dev branch of openpnm via git

Fixed typo in relative permeability calculation notebook

Significantly revamped the examples directory for improved categorization of material

Source code(tar.gz)
Source code(zip)
v2.5.0(Aug 29, 2020)
:cake: Enhancements

Enhanced RelativePermeability to better support directional simulations

Enhanced CI workflows; migrated from pip to conda

Enhanced ball_and_stick shape factors to raise Exception if the underlying assumption is violated

Enhanced merge_networks to fully handle networks with existing geometries

:warning: API changes

Changed docrep installation to use 0.2.7

Changed default solver from Scipy's spsolve to PyPardiso's direct solver

:bug: Bugfixes

Fixed the incorrect scaling issue of plot_connections and plot_networkx

Fixed deprecation warnings for Scipy, HDF5, and numpy

Fixed CI testing error due to pep8 incompatibility with the latest pytest

Fixed use of sp to np to avoid breaking when scipy removes numpy from it's namespace in version 2.0

Fixed some issues in NernstPlanck algs, changed name of solver class, added tests and scripts

Fixed typo in usage of map_pores

Source code(tar.gz)
Source code(zip)
v2.4.2(Jul 14, 2020)
:bug: Bugfixes

Fixed bug in interleave_data that inferred incorrect datatypes in some instances

Source code(tar.gz)
Source code(zip)
v2.4.1(Jul 11, 2020)
:bug: Bugfixes

Fixed caching/uncaching of A matrix to work with all sub-classed transport algorithms, not just ReactiveTransport

Source code(tar.gz)
Source code(zip)
v2.4.0(Jul 10, 2020)
:rocket: New features

Added conns and coords attributes to GenericNetwork

Added axes labels for plot_coordinates plot_connections method

Added a wrapper for PyPardiso solver, and a pseudo-interface for solvers

:cake: Enhancements

Optimized find_neighbor_sites to run up to 4x and num_neighbors to run up to 30x faster

Enhanced algorithm sanity check to include topology health check

Enhanced error/exception messages in several spots

Enhanced stitch method with new mode and ability to specify labels for new stitch throats

Enhanced io.PoreSpy.load to accept dict handle

:warning: API changes

Changed _check_for_nans to _validate_data_health

Changed Cubic class to reject connectivity = 8 or 12 as they generate disconnected networks

:bug: Bugfixes

Fixed handling of Nt by 2 conductance arrrays (i.e. diff_cond in ad_dif_conductance)

Fixed _get_iterative_props to now include "variable_props" in the returned list of props

Fixed scaling in plot_coordinates, and changed size_by and color_by to ONLY accept ND-arrays

Fixed OpenPNM IO load method to properly return project

Fixed plot_networkx scaling issue when plotting consecutively

Bugfix: variable conductance now triggers A rebuild

Fixed bug in bond_percolation that allowed early invasion into throats connected to invading cluster

Fixed TransientReactiveTransport to run repeatedly + optimized unit tests

Fixed bug in set_rate_BC: multiple values are now accepted

Source code(tar.gz)
Source code(zip)
v2.3.3(Jul 1, 2020)
:rocket: New features

Added automatic generation of release notes when deploying to PyPI

Added automatic deployment to PyPI using GitHub Actions

:bug: Bugfixes

Fixed bug in find_connected_pores/sites to enforce upper triangular adjacency matrix #patch

Source code(tar.gz)
Source code(zip)
v2.3.1(Apr 15, 2020)

This hotfix repairs a bug in the handling of overlapping pores for cases where the pores overlap but the throat endpoints are not collinear with the pore centers. This bug was leading to erroneous calculations of permeability and tortuosity in extracted networks by incorrect conductance values for affected conduits.
Source code(tar.gz)
Source code(zip)
v2.3.0(Apr 12, 2020)
This release is a bit ahead of schedule (based on our plan to release at the beginning of each semester), but it's a very important release. It fixes several important bugs in the ReactiveTransport class and adds some major improvements to the handling of iterative calculations, among other things. The complete list of updates is given below:

🚀 Improvements and Enhancements

Major upgrade to pore-scale model dependency checking

Added detailed checking for NaNs in GenericTransport

Enhanced the mixture submodule

Renamed the PNP related classes to more descriptive names

Improved performance of CubicTemplate by removing finding and labeling of surface pores

Enhanced plot_networkx to work for 1D networks and improved robustness

Improved docstrings in algorithms, especially settings, with help of docrep

Added Python 3.8 to testing suite

Consolidated solver tolerances

Algorithms now accept initial guess when calling run

README.md now renders propertly on PyPI

Optimized OpenPNM import time dramatically

Added full pytest integration for jupyter notebooks, as well as scipy 2 deprecation-proofing

🚀 New Features and Functionality

Added a PoreSpy option to io module

Added preliminary ability to export to Salome

Add example on how to create a custom phase object

Added inspect_locations method to the Project class

🐛🐛🐛 Major Bug Fixes

Fixed _run_generic to rebuild A and b when cache_A/b set to False

Fixed PETSc wrapper to be compatible with the latest MUMPS release

Fixed missing minus sign when using source terms in transient algs with Crank-Nicolson

Fixed dispersion rate calculation

Improved tolerance in transient simulations to match steady-state

🐛 Minor Bug Fixes

Default values for source term models now ensure zero rate/S1/S2

Replaced is not with != throughout

Removed use of floats as indices in arange and linspace

Fix set_source so calling it w/ same propname does not lead to duplicate source terms

Solver rejects solution when residual equals tolerance

Fixed throat models that would break with no throats were present

Fix dispersion conductance bug: now updates iteratively

Fixed bug in merge_networks when networks were 2D

Source code(tar.gz)
Source code(zip)
v2.2.0(Jan 11, 2020)
This is the first release of 2020, and is hopefully part of a new 'semester-based' release schedule. So instead of waiting an undefined amount of time until we have enough new features for a release, we will release all the new features we have added in the past semester.

🚀 New features (experimental)

The MultiPhase class for better automated handling of multiphase simulations, including species partitioning between phases

The Mixtures submodule for better automated handling of mixtures such as air or brine

🐛 Improvements and bugfixes

Example scripts have been moved out of the main directory and into /scripts

Enhanced the cooperative pore filling models for the MixedIP algorithm

Improved speed of InvasionPercolation very substantially (about 25x)

Enhanced purge_object to accept list of objects

Added reset method to GenericTransport and ReactiveTransport so objects can be reused inside a for-loop

Bug fix in plot_networkx method

Source code(tar.gz)
Source code(zip)
v2.0.3(Oct 24, 2018)

I recently added a small feature that appends the git commit to the version number for users working on a branch other than master, but the import of gitpython apparently fails if the host machine does not have git installed. Now this import occurs inside a try-accept so will not break
Source code(tar.gz)
Source code(zip)
v2.0.2(Oct 20, 2018)

Several of our dependencies broke with the release of numpy 1.15, so users doing pip install with a recent conda installation (on windows) would receive a build error. This version has moved the offending deps to be optional.

There are a number of other small bug fixes and tweaks that were also added, but these were not as urgent.
Source code(tar.gz)
Source code(zip)
v2.0.0(Aug 23, 2018)
🚀 New features and capabilities

All Transport algorithms are now transient, including non-linear reactions

A Dispersion algorithm with 4 optional discretization schemes has been added

A mixed percolation algorithm has been added that can model drainage and/or imbibition, and includes detailed menisci movements such as snap-off, burst, and coalescence

Several new network generators have been added such as bcc and fcc lattices

Support for several new solvers, including pyAMG and scikit-umfpack which can now both be installed using pip, and PetSc, assuming you are able to install it yourself (not supported by pip).

The symmetry of the coefficient matrix is now maintained when boundary conditions are are added, which significantly improves the speed of some CG based solvers (>2x faster).

Pore-Scale Models

Much more rigorous and accurate pore-scale conductance models

Pore-scale models can now be assigned to any object, so a model that calculates pore diameters can be assigned to a network if desired

Pore-scale models are now stored in a top level module, making then more prominent and easier to find

Importing and Exporting Data

Added support for two new data export formats: hdf5 and xdmf. These are designed for storing massive data sets with maximum speed, and the xdmf format can be open in Paraview for vastly sped-up visualization

The PNM file format was refined to save either single projects or entire workspaces seamlessly

Better Organization and General Housekeeping

The algorithm classes have been completely re-written for better consistency

A settings attribute has been added to all objects to contain various flags and values which used to be stored as hidden attributes

Topological manipulation tools have been moved from a sub-module of network to a top level module (topotools) to make it easier to access and more prominent

A Project class has been added, that acts as a container for a given pore network simulation, such that the Workspace is populated with a collection of Projects, each of which contains a Network object and all other associated objects (i.e. geometries, phases, etc.)

📖 Documentation

The documentation has been thoroughly overhauled, and now includes complete coverage of all modules, classes, methods, and functions.

The OpenPNM-Example repository has been converted to Jupyter Notebooks so users can download actual functioning code to get started

⚠️ Backwards incompatible changes

One of the main reasons for the version bump to 2.0 was to allow several long delayed changes that break backward compatibility. These are all quite superficial, so any experience using V1.0 should be easily transferred:

All module names, including the package itself, have been changed to lowercase in accord with pep8 rules

Neumann and Dirichlet boundary conditions have been renamed to Rate and Value to be more descriptive

The behavior of the various lookup methods (pores, find_neighbor_pores) have been cleaned up for better consistency

A unique Physics objects must be defined for each Geomery object. This is a bit more effort for the user, but allows much more reliable associations between objects. The new Project class has a grid method that can help to organize and visualize these associations.

Source code(tar.gz)
Source code(zip)
v2.0.0-beta.2(Aug 17, 2018)

Source code(tar.gz)
Source code(zip)
v2.0.0-beta.1(Jul 22, 2018)

This adds the last few weeks of bug fixes and tweaks to the master code. The final release is schedule for July 27th, 2018.
Source code(tar.gz)
Source code(zip)
v2.0.0-beta.0(Jul 9, 2018)

This is a beta release of V2. A more verbose release announcement will come when the beta tag is dropped.
Source code(tar.gz)
Source code(zip)
v1.7.0(Jul 9, 2018)

The main addition of this release is a Mixed Invasion Percolation algorithm, which was used in our recent publication in TiPM.

The OpenPNM team has been working VERY hard on V2, which is now available on PyPI in beta form, so this will be the last release of the V1 branch.
Source code(tar.gz)
Source code(zip)
v1.6.2(Jul 5, 2017)

Numpy has been warning us for a while that certain indexing tricks would be deprecated, and that moment has arrived. This minor patch fixes a few places in the code where this error occurred.
Source code(tar.gz)
Source code(zip)
v1.6.1(Feb 18, 2017)

Source code(tar.gz)
Source code(zip)
v1.6.0(Feb 17, 2017)
🚀 New features

Two new Network classes have been added that support Dual networks

CubicDual creates an normal cubic network of size [x, y, z] called the 'primary' network, then adds 'secondary' cubic network of size [x-1, y-1, z-1] at the interstices of the 'primary' lattice. These two networks are then interconnected to each other. The point of this class it to enable both pore phase and solid phase transport simultaneously, through primary and secondary networks, as well as allowing exchange between them via the interconnections.

DelaunayVoronoiDual is motivated by the same idea as the CubicDual, but uses a Delaunay tessellation of random points as the 'primary' network and the Voronoi tessellation as the 'secondary' network.

Two new plotting functions were added to Network.tools: plot_coordinates and plot_connections. These are meant for quickly verifying the topology of a network without having to spin-up Paraview

Several function have been added to Network.tools

template_disc_ring creates a circular template for use in Cubic

generate_base_points generates random points for use in Delaunay and DelaunayVoronoiDual

A new pore-scale model called largest_sphere was added to Geometry.models that calculates the largest possible pore diameter to put in each location without overlapping the neighboring pores. This model is particularly useful for random networks where the spacing between pore centers is unknown.

A method for finding the pores on the surface of a network was added to Network.tools called find_surface_pores.

⚠️ API changes

add_boundaries now accepts a list of which face to add boundaries to, rather than doing all sides (which is still the default).

Support for Python 3.3 has been dropped, and support for 3.6 has been added. OpenPNM is also compatible with the latest version of Numpy, which made a few significant changes in indexing rules.

The save and load methods of the Workspace class are now called save_workspace and load_workspace to more clearly indicate their job.

Source code(tar.gz)
Source code(zip)
v1.5.0(Jun 2, 2016)
🍏 Major enhancements and changes

Added two new import classes for importing from iMorph and 3DMA-Rock.

Now uses dill instead of Python's standard pickle library. This means that custom pore scale models and classes can be saved to "pnm" files.

Changed the name of the "Controller" object to "Workspace", which more literally describes it's role. "Controller" can still be used for backward compatibility.

All Network and topology manipulation tools are now found under Network.tools although they can still be accessed via Utilities.topology for backwards compatibility.

Completely reworked documentation. The 'user guide' now consists of 3 tutorials of varying levels, with the aim that users will know how to use OpenPNM pretty well after completing all three. There is also a separate 'reference' section in the user guide that explains the inner workings of the code in more detail, but users don't have to sift through these to get started anymore.

All documentation is now hosted on ReadTheDocs, which rebuilds the documentation every time a new commit is pushed to Github. The docs will now always be up-to-date!

A new parallel repository has been created to house all Examples at https://github.com/PMEAL/OpenPNM-Examples. All the code in this repository is tested against the latest version of OpenPNM on PyPI, so if there are any broken examples we'll know about it. This will remedy the frustration felt by many users when trying to learn OpenPNM by examples. This is also why the Tutorials were created as the main User Guide (see 5 above).

🚀 New features

Added ability to have spatially varying pore seed values, which is useful for creating porosity distributions or undulations.

Added new arguments to num_neighbors. It can now apply set logic (i.e. 'union' and 'intersection') when counting neighbors, and it can now count neighboring throats as well as pores with the element keyword (which is 'pores' by default to maintain backwards compatibility).

Object handles are now stored in dicts rather than lists, so you can access them by name (geom.phases['air']) and also iterate on the dict (pn.phases.values()). This was implemented in a backwards compatible way so geom.phases() and geom.phases('air') still work as they used to...of course using the dict syntax is encourage henceforth.

🐛 Minor improvements and bugfixes

Fixed code coverage reporting on Codecov

Changed many print statements to logger messages

Several private methods were removed that were never called by the code

🥇 Acknowledgements

The OpenPNM Developers would like to thank the following people for contributing to this release:

Matthew Stadelman (@stadelmanma) for crafting the iMorph IO class

Masa Prodanovic for help with the 3DMA-Rock import class

Source code(tar.gz)
Source code(zip)
v1.4.6(Apr 27, 2016)
Almost all changes in this minor release are back-end fixes, or were at least implemented in a backwards compatible way. Looking at the length of this list makes me realize that we should be doing minor version bumps more often!

⚠️ API changes (backend)

set_locations was removed from Core and moved to Base.Tools as a new class. This functionality is now added to GenericGeometry and GenericPhysics via composition, so they still have a set_locations method, but Phase and Network objects do not.

Codecov is now working again

Test coverage was increased by 2%

Object handles are now stored in dicts rather than lists, so you can access them by name (geom.phases['air']) and also iterate on the dict (pn.phases.values()). This was implemented in a backwards compatible way so geom.phases() and geom.phases('air') still work as they used to...of course using the dict syntax is encourage henceforth.

Several private methods were removed that were never called by the code

The check_network_health method now finds duplicate throats in a more robust and reliable way

Loading simulations from a pnm file now registers objects with the Controller properly

The tools located under Utilities.topology have been moved to Network.tools, but wrapper methods were left in the old location for backward compatibility.

Many little tweaks in PR #547

Changed many print statements to logger messages

Added a mode argument to num_neighbors so you can count neighbors that meet given criteria

Source code(tar.gz)
Source code(zip)
v1.4.5(Mar 17, 2016)

The setup.py had a circular reference to our package leading to it being initialized before being installed. On machines without the necessary dependencies (i.e. new users) this was throwing an import error upon installation.

This update has been pushed to PyPI so all future attempts at pip install openpnm should work.
Source code(tar.gz)
Source code(zip)
v1.4.4(Mar 11, 2016)

Fixed bug in add_boundary_pores that was leading to double addition of throats Changed code in GenericLinearSolver to prevent Warnings
Source code(tar.gz)
Source code(zip)

A Python package for performing pore network modeling of porous media

Related tags

Overview

Overview of OpenPNM

More Information

Stay Informed

Installation and Requirements

Preferred method

Alternative method

For developers

Example Usage

Asking Questions and Getting Help

Contact

Acknowledgements

Citation

Comments

List of changes:

Releases(v3.1.1)

v3.1.1(Dec 30, 2022)

:bug: Bugfixes

v3.1.0(Nov 13, 2022)

:rocket: New features

:cake: Enhancements

:wrench: Maintenance

:green_book: Documentation

v3.0.0(Oct 12, 2022)

:fireworks: Major Changes

:rocket: New features

:cake: Enhancements

:wrench: Maintenance

:warning: API changes

:bug: Bugfixes

:green_book: Documentation

v2.8.2(Sep 8, 2021)

:bug: Bugfixes

v2.8.1(Aug 9, 2021)

:wrench: Maintenance

v2.8.0(Aug 9, 2021)

:rocket: New features

:cake: Enhancements

:wrench: Maintenance

:warning: API changes

:bug: Bugfixes

:green_book: Documentation

v2.7.0(Feb 24, 2021)

v2.7.0

:rocket: New features

:cake: Enhancements

:wrench: Maintenance

:warning: API changes

:bug: Bugfixes

v2.6.0(Dec 4, 2020)

v2.6.0

:rocket: New features

:cake: Enhancements

:wrench: Maintenence

:warning: API changes

:bug: Bugfixes

:green_book: Documentation

v2.5.0(Aug 29, 2020)

:cake: Enhancements

:warning: API changes

:bug: Bugfixes

v2.4.2(Jul 14, 2020)

:bug: Bugfixes

v2.4.1(Jul 11, 2020)

:bug: Bugfixes

v2.4.0(Jul 10, 2020)

:rocket: New features

:cake: Enhancements

:warning: API changes

:bug: Bugfixes

v2.3.3(Jul 1, 2020)

:rocket: New features

:bug: Bugfixes

v2.3.1(Apr 15, 2020)

v2.3.0(Apr 12, 2020)

🚀 Improvements and Enhancements

🚀 New Features and Functionality

🐛🐛🐛 Major Bug Fixes