Porespy

:rocket: New features

- Added `pc_to_satn` function to filters \new
- Added `satn_to_seq` function to filters \new
- Added `satn_profile` to metrics \new
- Added `find_h` to metrics \new
- Added `pc_curve` to metrics which accepts either sizes or pressures \new
- Added `satn_to_panels` to visualization folder to create a montage of invasion steps \new
- Added `prep_for_imshow` to visualization folder to adjust image for passing to plt.imshow \new
- Created `simulations` module to replace `dns` \new \api
- Moved `tortuosity` function to `simulations` and renamed it `tortuosity_fd` for finite difference \new \api
- Added `drainage` function to the new `simulations` module, which incorporates the effect of gravity \new

:cake: Enhancements

- Added ability to pass custom peaks to snow algorithms \enh
- Phase labels no longer need to be contiguous in snow functions or `snow2` extraction \enh
- Phase labels of 0 can now be passed to `snow2`, if `phase_alias` argument is provided \enh
- Added ability to specify residual invading phase in `drainage` \enh
- Added surface option to trim/fill functions to optionally remove artifacts on the surfaces \enh
- Added optional strel arg to `trim_nonpercolating_paths` \enh

:wrench: Maintenance

- Removed joss folder from top level of repo \maint
- Decreased size of examples to accelerate testing and building \maint
- Added many quantitative unit tests for snow functions \maint
- Using much small images in snow tests to improve testing speed \maint
- Minor adjustments/improvements to various trim peaks functions \maint
- Consolidated jit sphere insertion funcs into a single file under `tools` \maint
- Streamlined and simplified CI workflows \maint
- Renamed how-tos to reference and other maintenance of docs \docs \maint
- Added citations file to repo \maint
- Dropped support for Python 3.6 and 3.7 per NEP29 \maint
- Fixed examples CI to use the official pytest-split \maint
- Temporarily excluded `imagej` module from coverage due to CI/dependency issues \maint
- Removed transforms3d from requirements as it's no longer needed \maint
- Added 4th digit to semantic version to indicate number of merges into dev branch

:warning: API changes

- Deprecated `pc_curve_from_mio` in favor of just `pc_curve(sizes=sizes)` \api
- Created `simulations` module to replace `dns` \new \api
- Moved `tortuosity` function to `simulations` and renamed it `tortuosity_fd` for finite difference \new \api
- Deprecated `dns.tortuosity` though provided a wrapper to the moved and renamed version `tortuosity_fd` \api

:bug: Bugfixes

- Fixed bug in `region_volumes` method \bug
- Fixed `cylindrical_plug` generator to work in 2D \bug
- Fixed bugs in `snow2` when accuracy was 'high': missing throat\_perimeters and incorrect voxel scaling \bug
- Fixed a memory leak in `tortuosity_fd`

:green\_book: Documentation

- Removed excess badges from readme \doc
- Major updates to all example notebooks \docs
- Renamed how-tos to reference and other maintenance of docs \docs \maint
- Added 2 new examples on the basic use of `drainage` and explaining its inner workings \docs
- Updated some notebooks to work with new version of openpnm (2.8+) \doc

Installation
Normally porespy can be installed using ``conda install -c conda-forge porespy=2.1``; however, to reproduce the exact environment which this release was built upon (i.e. at some point in the future), download one of the requirements files below (i.e. requirements_ps21_py310_win64.txt), then run the following at the conda prompt:


conda create --name <env> --file requirements_ps21_py310_win64.txt
conda activate <env>

where ``<env>`` is your chosen environment name.

:bug: Bugfixes

- Fixed snow2 which called missing function in accuracy='high' mode

:pushpin: Pinned Dependencies
The following file can be used to produce a working installation of PoreSpy v2.0.2: [conda_pinned_requirements_v2.0.2.txt](https://github.com/PMEAL/porespy/files/7900833/conda_pinned_requirements_v2.0.2.txt)

:wrench: Maintenace

- Make pyfastnoisesimd optional for conda-forge builds to work \maint

:rocket: New features

- Added optional parallelization to many functions using dask
- Added image-based invasion percolation algorithm (ibip) to filters
- GPU-accelerated the image-based invasion percolation (IBIP) algorithm
- Added nl\_means\_layered function for parallelized noise removal \new
- Added boxcount to metrics \new
- Added random\_cantor\_dust and sierpinski\_foam to generators \new
- Added borders and faces to generators \new
- Added pseudo\_electrostatic\_packing to generators \new
- Added pseudo\_gravity\_packing of spheres to generators \new
- Added wrapper to generic ImageJ functions \new
- Added a lightweight wrapper for the classic MaximalBall algorithm \new
- Added settings to top level of package to control behavior like hidding progress bars and messages \new
- Added unpad function to tools module \new
- New IO method to_stl for exporting an image to STL mesh \new
- Added cylinder\_plug function to generators, used in extract\_cylinder function for improved speed \new
- Added ps\_round function to tools to produce disk and ball strels programmtically \new
- Added ps\_rect function to tools for programatically generating 2D or 3D rectilinear strels \new
- Added io function to save an image as a Paraview state file and open directly in Paraview \new
- Added function to export a sphere pack image to COMSOL \new

:cake: Enhancements

- Exposed sigma and r\_max in snow\_2 \enh
- Better support for 2D images \enh
- Added option to trim\_nearby\_peak to apply a threshold for distance check \enh
- Added ability to set loglevel by number as well as name \enh
- Unified various snow extraction algorithms under new snow2 function \enh
- Added more robust inference of Python environment (terminal vs. notebook) \enh
- Migrated to "loguru" from Python's stdlib "logging" for logger messages \enh
- Improved various metrics and the bar chart function in the visualization module to work together better \enh
- Added spacing to show\_planes \enh
- Extended RSA api with clearance and return\_spheres arguments, and now accepts im or shape \enh
- Cylinders generator now also accepts porosity (previously only number of cylinders) \enh
- Refactored make\_contiguous to use less memory and by 5x faster \enh

:wrench: Maintenance

- Fix a bug in examples CI where if no tests were collected, CI reported as failed \maint
- Replaced array\_split dependency with custom-made function \maint
- Parallelized examples' CI, and switched to Mambaforge \maint
- Fixed codecov to include numba-jitted methods in coverage report \maint
- Removed Dask progress bars and minor refactoring \maint
- Included ParaView unit tests in the macOS build \maint
- Update Actions to accommodate the native support of "ci skip" by GitHub + minor tweaks \maint
- Migrate from pip to conda for CI \maint

:warning: API changes

- Replaced namedtuples with custom Results container \api
- Replaced perlin\_noise with fractal\_noise in the generators module based on fastnoisesimd (and pyfastnoisesimd) packages \api
- Moved several functions between submodules, deleted others, and renamed files \api
- Altered phase\_fractions to accept alias and return dict, e.g. {'void': 0.44, 'solid':0.56} \api
- Switched radius argument to just r throughout package \api
- Switched to maxiter throughout, instead of max_iter or max_iters or iter_max \api
- Radial density distribution now only accepts distance transform \api
- Reduced the number of arguments in the snow family of functions \api
- Enhanced add\_boundary\_regions function to accept pad\_width instead of face names \api
- Updated lattice\_spheres to be much more flexible, renamed and added args \api
- Remove to\_openpnm function from io module \api
- Renamed some metrics to be more consistent with each other \api
- Fixed up regionprops\_3d to behave equivalently to scikits-image, including delayed evaluation \api

:bug: Bugfixes

- Fixed tqdm progress bar bug that always defaulted to text-based \bug
- Fixed edge case bugs on RSA and insert\_cylinders \bug
- Rewrote trim\_saddle\_points to avoid hitting max\_iters as oftern \bug
- Fixed tiny bug in L value used in dns.tortuosity (L -\> (L -1)) that was prevent tau =1 in open space \bug
- Fixed bug in find\_outer\_region \bug
- Fixed missing type check in hold\_peaks \bug
- Added check to ensure filter output size matches input in chunked\_func \bug
- Fixed bug in trim\_percolation\_paths \bug
- Fixed snow\_dual to handle unsegmented solid regions \bug
- Fixed a bug in add\_boundary\_regions that occasionally led to some unlabeled pores \bug

:green\_book: Documentation

- Large overhaul of docstrings, consistent argument naming between functions \doc
- Added many new example notebooks and revamped documentation site \docs
- Moved documentation from readthedocs to GitHub Pages + major enhancements \doc

:bug: Bugfixes

- Fixed dask version in setup.py (porespy using `pip install porespy` had a missing dask module)

:rocket: New features

- Added snow\_partitioning\_parallel to filters module
- Added fully automated deployment to PyPI via GitHub Actions
- Added dns submodule with tortuosity function
- Added customized bar plot option to visualization module
- Added full pytest integration for automated testing of notebook examples
- Added custom imshow and a wrapper at top level for instant access
- Added GitHub Actions workflow to replace Travis CI
- Added two functions to tools module: size\_to\_seq and seq\_to\_satn
- Added two functions to tools module: size\_to\_seq and seq\_to\_satn
- Added option to trim\_nonpercolating\_paths to accepts masks
- Added porosity\_profile example

:warning: API changes

- Changed direction to axis in some vis functions
- Removed dims and ndims, typos
- Changed all internal distance transforms to much faster edt instead of scipy.ndimage.distance\_transform\_edt

:bug: Bugfixes

- Fixed CI testing error due to pep8 incompatibility with the latest pytest
- Fixed mising dns submodue install in setup file
- Fixed subdivide to return tuples, enhanced to accept flattened and overlap args
- Fixed bugs in snow\_n regarding non-contiguous aliases and missing labels
- Fixed cylinders generator to provide a more uniform porosity distribution
- Fixed some examples that were issuing deprecation warnings