v3.0.0

[jgostick]

Change log

v3.0.0

🚀 New features

• Major update and revision of the various 'displacement' functions, now called drainage, imbibition and injection #api #enh
• Added imbibition function which handles trapping of nwp and residual wp
• Added reference implementations of drainage and imbibition using convolution, distance transform thresholding and brute-force sphere insertion
• Added the ability to include residual invading phase while considering trapping in both drainage and imbibition
• Added new qbip algorithm which incorporates gravity in invasion percolation simulations
• Added injection function as a wrapper to ibip and qbip
• Added hg_porosimetry which performs intrusion and extrusion using preset conditions
• Added capillary_transform function to filters for generating capillary pressure transform
• Added pc_map_to_pc_curve function for generate capillary pressure curves from output of new displacement functions
• Added many new function to filters for converting between different displacements maps (e.g. seq_to_satn and size_to_pc)
• Added find_Bo to metrics module
• Added new mode argument to find_trapped_voxels which accepts cluster and queue to select back end used
• Added separate functions for finding and filling closed and surface pores instead of using surface=True|False args
• Added find_closed_pores and find_surface_pores to filters
• Added fill_closed_pores and fill_surface_pores to filters
• Added find_invalid_pores and fill_invalid_pores to filters
• Added 'find_porosity_thresholdtometrics` which dilates solid until void no longer percolates
• Added is_percolating to metrics which checks if an image percolates in the specified direction(s)
• Added percolating_porosity to metrics which computes the void fraction associated with the percolating cluster(s)
• Added rev_tortuosity to metrics
• Added get_slices_slabs, get_slices_random, and get_slices_multigrid as additional ways to subdivide an image
• Added MAGNET network extraction tool to networks
• Added several functions related to MAGNET such as finding junctions and endpoints of skeletons
• Added erode and dilate to filters
• Added get_edt wrapper function to tools which will get pyedt if available otherwise use edt, and also set the number of parallel threads from settings.ncores
• Added get_conn function to tools
• Added ball, disk, square, cube to tools
• Added parallel version of regions_to_network contributed by @Arenhart
• Added marching_cubes and marching_squares functions which are jit-compatible
• Added conical_capillary to generators module
• Added elevation function to generators

🍰 Enhancements

• Added new implementations of the local_thickness filter
• Added aspect to get_slices_random
• Generators now ignore 0 and None in shape arg to yield a 2D image
• All progress bars now report name of calling function
• Add a fill_closed and fill_surface option to several functions which compute porosity
• Added fill_closed and fill_surface args to porosity and porosity_profile functions
• Changed default binning in displacement algs to log spacing
• Added porosity argument to fractal_noise generator
• Normalized sem and xray views to return images scaled between 0 and 1 for easier visualization
• Fixed and improved the pseudo packing functions
• Refactored, enhanced, and optimized sem

🔧 Maintenance

• Tidying up actions
• Bumped actions/checkout from 4 to 5
• porosimetry and local_thickness are now decoupled
• Added nightly CI workflows for PyPI and the dev branch separately
• bumped stefanzweifel/git-auto-commit-action from 5 to 6
• bumped pypa/cibuildwheel from 2.23.3 to 3.0.0
• Added parse_shape to tools
• All progress bars now obey porespy.settings.tqdm
• Updated porosity_profile and satn_profile to use im_to_slabs internally
• Moved ruff config to pyproject.toml
• Avoid overflow errors with _get_radial_sum #bug
• Updated tests that use the blobs image generator to specify exact porosity

⚠️ API changes

• Added separate functions for finding and filling closed and surface pores instead of using surface=True|False args #new
• porosimetry and local_thicknes now use method keyword instead of mode
• Renamed representative_elementary_volume to rev_porosity
• Renamed subdivide to get_slices_grid
• Using parallel_kws throughout package to specify parallelization related info
• Changed get_borders to return faces with mode of 'edges' and 'faces' in 2D
• Renamed all references to "blind pores" with "closed pores", such as fill_closed_pores
• Changed all references to things like strel, conns, etc to just conns which accepts 'min' and 'max'
• Change keyword mode to method throughout when appropriate
• Added periodic argument to blobs which makes a periodic image that also has uniform density near edges
• Ensure images start with im_<name> on returned Results objects
• Removed comsol functions from io submodule
• Removed maxball functions from networks submodule
• Removed original sierpinski_foam, renamed v2 to sierpinski_foam
• Updated sierpinski_foam function to accept shape and iteration
• Swapped colormap of xray function
• Returning fig, ax from all visualization functions
• Changed porosity_profile to return a results object with position and porosity
• Major update and revision of the various 'displacement' functions #enh #new
• Updated drainage function to have consistent api with imbibition
• Moved ibip to simulations
• Removed deprecated pc_curve_from_ibip and pc_curve_from_mio functions
• Changed pc_curve function to only accept capillary pressure maps
• Drainage now requires capillary pressure map as input
• Changed norm_to_uniform to all_to_uniform
• Removed rsa and RSA, replaced with random_spheres
• Unified random_spheres, pseudo_gravity_packing, and pseudo_electrostatic_packing functions to have same api
• Fixed and improved the pseudo packing functions #enh #bug

🐛 Bugfixes

• Change throat.direct_length calculation to use float64
• Fixed bug in cylinders generator where porosity increased near edges
• Fixed get_random_slices to ensure all blocks are cubic
• fixed bug in sphere_to_coord func so image is only 2d if one axis is all 0
• Fixed use of skeletonize_3d
• Avoid overflow errors with _get_radial_sum #maint
• Fix points_to_spheres bug in 3D
• Fixed and improved the pseudo packing functions #enh #api

📗 Documentation

• Migrated from autodoc to autoapi for more automated docs generation #docs
• Notebooks are forced to execute during build to ensure the latest is rendered
• Updated docstrings #docs
• Updated some documentation #docs
• Updated all documentation to reflect new api of the displacement functions
• Added 3 part tutorial on the interpretation of the displacement maps produced by the displacement functions
• Updated example for ibip #docs

---

This discussion was created from the release v3.0.0.

[jgostick]

This is a big release with lots of new features. Power users have been able to play with this by downloading the code directly from Github, but this release is now officially available on PyPI, so a simple pip install porespy will now get your V3. If you've been using V2, you can upgrade using pip install --upgrade porespy.

This is a "major" release because we did a number of backwards incompatible changes throughout the code. Your existing code may break in a few places, but I think it shouldn't be too painful because the general idea/workflow is the same.

I hope you find these new additions useful!