Merge pull request #83 from tldr-group/release-v1.1

Release v1.1

.gitignore

@@ -24,6 +24,7 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+*.tiff
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

.readthedocs.yml

@@ -1,16 +1,22 @@
-# .readthedocs.yml
+# .readthedocs.yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
 version: 2
 
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-    configuration: docs/conf.py
+   configuration: docs/conf.py
 
-# Optionally set the version of Python and requirements required to build your docs
+# Optionally declare the Python requirements required to build your docs
 python:
-    version: 3.8
-    install:
-        - requirements: docs/requirements.txt
+   install:
+   - requirements: docs/requirements.txt

HISTORY.md

@@ -1,5 +1,14 @@
 # History
 
+## 1.1.0 (2023-07-24)
+
+---
+
+-   Added comments from reviewers
+-   Added examples to documentation
+-   Added API documentation
+-   Fix test times on comparison
+
 ## 1.0.0 (2023-03-23)
 
 ---

docs/index.rst

@@ -2,12 +2,13 @@ Welcome to TauFactor's documentation!
 ======================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    readme
    installation
    usage
+   taufactor
    contributing
    authors
    history

docs/taufactor.rst

@@ -0,0 +1,45 @@
+API Reference
+=================
+
+
+Core module
+-----------------
+
+taufactor.taufactor module
+~~~~~~~~~~~~~~~~~
+
+
+.. automodule:: taufactor.taufactor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Submodules
+-----------------
+
+taufactor.metrics module
+~~~~~~~~~~~~~~~~~
+
+
+.. automodule:: taufactor.metrics
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+taufactor.utils module
+~~~~~~~~~~~~~~~~~
+
+
+.. automodule:: taufactor.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+------------------
+
+.. automodule:: taufactor
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/usage.md

@@ -1,6 +1,6 @@
 # Using Taufactor
 
-This documentation covers the full usage of TauFactor
+This documentation covers the common usage of TauFactor. For a more detailed description see the [module API documentation](./taufactor.rst).
 
 ## Core solver
 

paper.bib

@@ -59,6 +59,7 @@ @misc{fidgit
 }
 
 @article{gostick2019porespy,
+  doi = {10.1051/0004-6361/201629272},
   title={PoreSpy: A python toolkit for quantitative analysis of porous media images},
   author={Gostick, Jeff T and Khan, Zohaib A and Tranter, Thomas G and Kok, Matthew DR and Agnaou, Mehrez and Sadeghi, Mohammadamin and Jervis, Rhodri},
   journal={Journal of Open Source Software},
@@ -79,6 +80,7 @@ @article{ferguson2018puma
 }
 
 @article{le2021openimpala,
+  doi={10.1016/j.softx.2021.100729},
   title={Openimpala: Open source image based parallisable linear algebra solver},
   author={Le Houx, James and Kramer, Denis},
   journal={SoftwareX},
@@ -89,6 +91,7 @@ @article{le2021openimpala
 }
 
 @article{cooper2016taufactor,
+  doi={10.1016/j.softx.2016.09.002},
   title={TauFactor: An open-source application for calculating tortuosity factors from tomographic data},
   author={Cooper, Samuel J and Bertei, Antonio and Shearing, Paul R and Kilner, JA and Brandon, Nigel P},
   journal={SoftwareX},
@@ -99,6 +102,7 @@ @article{cooper2016taufactor
 }
 
 @article{hart1999measurement,
+  doi={10.1016/s1386-5056(98)00163-4},
   title={Measurement and classification of retinal vascular tortuosity},
   author={Hart, William E and Goldbaum, Michael and C{\^o}t{\'e}, Brad and Kube, Paul and Nelson, Mark R},
   journal={International journal of medical informatics},
@@ -110,6 +114,7 @@ @article{hart1999measurement
 }
 
 @article{carey2016estimating,
+  doi={10.1111/gwat.12406},
   title={Estimating tortuosity coefficients based on hydraulic conductivity},
   author={Carey, Grant R and McBean, Edward A and Feenstra, Stan},
   journal={Groundwater},
@@ -121,6 +126,7 @@ @article{carey2016estimating
 }
 
 @article{landesfeind2018tortuosity,
+  doi={10.1149/2.0231803jes},
   title={Tortuosity of battery electrodes: validation of impedance-derived values and critical comparison with 3D tomography},
   author={Landesfeind, Johannes and Ebner, Martin and Eldiven, Askin and Wood, Vanessa and Gasteiger, Hubert A},
   journal={Journal of The Electrochemical Society},
@@ -132,6 +138,7 @@ @article{landesfeind2018tortuosity
 }
 
 @article{dahari2023fusion,
+  doi={10.1002/aenm.202370009},
   title={Fusion of Complementary 2D and 3D Mesostructural Datasets Using Generative Adversarial Networks (Adv. Energy Mater. 2/2023)},
   author={Dahari, Amir and Kench, Steve and Squires, Isaac and Cooper, Samuel J},
   journal={Advanced Energy Materials},
@@ -142,6 +149,7 @@ @article{dahari2023fusion
   publisher={Wiley Online Library}
 }
 @article{kench2022microlib,
+  doi={10.1038/s41597-022-01744-1},
   title={MicroLib: A library of 3D microstructures generated from 2D micrographs using SliceGAN},
   author={Kench, Steve and Squires, Isaac and Dahari, Amir and Cooper, Samuel J},
   journal={Scientific Data},
@@ -162,6 +170,7 @@ @article{withers2021x
   publisher={Nature Publishing Group UK London}
 }
 @article{nguyen2020electrode,
+  doi={10.1038/s41524-020-00386-4},
   title={The electrode tortuosity factor: why the conventional tortuosity factor is not well suited for quantifying transport in porous Li-ion battery electrodes and what to use instead},
   author={Nguyen, Tuan-Tu and Demorti{\`e}re, Arnaud and Fleutot, Benoit and Delobel, Bruno and Delacourt, Charles and Cooper, Samuel J},
   journal={npj Computational Materials},
@@ -182,6 +191,7 @@ @incollection{pytorch
   url       = {http://papers.neurips.cc/paper/9015-pytorch-an-imperative-style-high-performance-deep-learning-library.pdf}
 }
 @article{cooper2017simulated,
+  doi={10.1016/j.electacta.2017.07.152},
   title={Simulated impedance of diffusion in porous media},
   author={Cooper, Samuel J and Bertei, Antonio and Finegan, Donal P and Brandon, Nigel P},
   journal={Electrochimica Acta},
@@ -191,6 +201,7 @@ @article{cooper2017simulated
   publisher={Elsevier}
 }
 @article{tjaden2016origin,
+  doi={10.1016/j.coche.2016.02.006},
   title={On the origin and application of the Bruggeman correlation for analysing transport phenomena in electrochemical systems},
   author={Tjaden, Bernhard and Cooper, Samuel J and Brett, Daniel JL and Kramer, Denis and Shearing, Paul R},
   journal={Current opinion in chemical engineering},

paper.md

@@ -18,16 +18,17 @@ authors:
       affiliation: 1
     - name: Samuel Cooper
       corresponding: true # (This is how to denote the corresponding author)
+      orcid: 0000-0003-4055-6903
       affiliation: 1
 affiliations:
-    - name: Imperial College London, UK
+    - name: Imperial College London, United Kingdom
       index: 1
 date: 9 March 2023
 bibliography: paper.bib
 ---
 # Summary
 
-TauFactor 2 is an open-source, GPU accelerated microstructural analysis tool for extracting metrics from voxel based data, including transport properties such as the touristy factor. Tortuosity factor, $\tau$, is a material parameter that defines the reduction in transport arising from the arrangement of the phases in a multiphase medium (see \autoref{example}). As shown in \autoref{eq:tort}, the effective transport co-efficient of a material, $D_{\text{eff}}$, can be calculated from the phases intrinsic transport coefficient, $D$, volume fraction, $\epsilon$, and $\tau$ [@cooper2016taufactor] (note, this value of $\tau$ should not be squared [@tjaden2016origin]).
+TauFactor 2 is an open-source, GPU accelerated microstructural analysis tool for extracting metrics from voxel based data, including transport properties such as the touristy factor. Tortuosity factor, $\tau$, is a material parameter that defines the reduction in transport arising from the arrangement of the phases in a multiphase medium (see \autoref{example}). As shown in \autoref{eq:tort}, the effective transport coefficient of a material, $D_{\text{eff}}$, can be calculated from the phases intrinsic transport coefficient, $D$, volume fraction, $\epsilon$, and $\tau$ [@cooper2016taufactor] (note, this value of $\tau$ should not be squared [@tjaden2016origin]).
 
 \begin{equation}\label{eq:tort}
 D_{\text{eff}} = D\dfrac{\epsilon}{\tau}
@@ -58,6 +59,10 @@ To compare the performance of TauFactor 2 to other available software, a test vo
 
 ![Speed comparison for the four solvers when applied to the test volume. The mean time across all 3 directions is plotted. The values of the overconverged $\tau$ in each direction are: 1.1513, 1.3905, 4.2431. \label{speeds}](tauspeeds.pdf)
 
+# Authorship Contributions
+
+SK wrote the base, periodic and multiphase solvers with input from IS. IS wrote the electrode solver, metric calculations and documentation, and also performed speed tests for other software packages. The project was supervised by SC, and based on his original MATLAB tool. All authors contributed to the writing and editing of the manuscript.
+
 # Acknowledgements
 
 This work was supported by funding from the EPSRC Faraday Institution Multi-Scale Modelling project

requirements_dev.txt

@@ -11,6 +11,6 @@ Click==7.0
 pytest==4.6.5
 matplotlib>3.6
 pytest-runner==5.2
-numpy==1.24.2
+numpy>=1.24.2
 tifffile==2023.2.3
 myst-parser==0.18.1

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.0.0
+current_version = 1.1.0
 commit = True
 tag = True
 

setup.py

@@ -36,6 +36,8 @@
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
     ],
     description="TauFactor is an application for calculating tortuosity factors from tomographic data",
     install_requires=requirements,
@@ -50,6 +52,6 @@
     test_suite='tests',
     tests_require=test_requirements,
     url='https://github.com/tldr-group/taufactor',
-    version='1.0.0',
+    version='1.1.0',
     zip_safe=False,
 )

taufactor/__init__.py

@@ -2,6 +2,6 @@
 
 __author__ = """Isaac Squires"""
 __email__ = 'is21@ic.ac.uk'
-__version__ = '1.0.0'
+__version__ = '1.1.0'
 
 from .taufactor import *

taufactor/metrics.py

@@ -55,7 +55,7 @@ def surface_area(img, phases, periodic=False):
 
     SA_map = torch.zeros_like(img)
     if not isinstance(phases, list):
-        phases = [phases]
+        raise TypeError('phases should be a list')
     for i in range(dim):
         for j in [1, -1]:
             i_rolled = torch.roll(img, j, i)
@@ -86,6 +86,13 @@ def surface_area(img, phases, periodic=False):
     return sa
 
 def triple_phase_boundary(img):
+    """Calculate triple phase boundary density i.e. fraction of voxel verticies that touch at least 3 phases
+
+    Args:
+        img (numpy array): image to calculate metric on     
+    Returns:
+        float: triple phase boundary density 
+    """
     phases = torch.unique(torch.tensor(img))
     if len(phases)!=3:
         raise ValueError('Image must have exactly 3 phases')

taufactor/taufactor.py

@@ -21,7 +21,6 @@ def __init__(self, img, bc=(-0.5, 0.5), D_0=1, device=torch.device('cuda')):
         for multiple solves.
 
         :param img: input img with 1s conductive and 0s non-conductive
-        :param precision:  cp.single or cp.double
         :param bc: Upper and lower boundary conditions. Leave as default.
         :param D_0: reference material diffusivity
         :param device: pytorch device, can be cuda or cpu 
@@ -166,12 +165,16 @@ def check_convergence(self, verbose, conv_crit, start, iter_limit):
         # print progress
         self.semi_converged, self.new_fl, err = self.check_vertical_flux(
             conv_crit)
-        self.D_rel = ((self.new_fl) * self.L_A /
-                      abs(self.top_bc - self.bot_bc)).cpu()
-        self.tau = self.VF / \
-            self.D_rel if self.D_rel != 0 else torch.tensor(torch.inf)
         if self.semi_converged == 'zero_flux':
+            self.D_rel = 0
+            self.tau = np.inf
             return True
+        else:
+            self.D_rel = ((self.new_fl) * self.L_A /
+                        abs(self.top_bc - self.bot_bc)).cpu()
+            self.tau = self.VF / \
+                self.D_rel if self.D_rel != 0 else torch.tensor(torch.inf)
+
 
         if verbose == 'per_iter':
             print(
@@ -196,10 +199,10 @@ def check_vertical_flux(self, conv_crit):
         vert_flux[self.conc[:, 1:-1, 1:-1, 1:-1] == 0] = 0
         fl = torch.sum(vert_flux, (0, 2, 3))[1:-1]
         err = (fl.max() - fl.min())*2/(fl.max() + fl.min())
-        if err < conv_crit or torch.isnan(err).item():
-            return True, torch.mean(fl), err
         if fl.min() == 0:
             return 'zero_flux', torch.mean(fl), err
+        if err < conv_crit or torch.isnan(err).item():
+            return True, torch.mean(fl), err
         return False, torch.mean(fl), err
 
     def check_rolling_mean(self, conv_crit):
@@ -233,7 +236,6 @@ def __init__(self, img, bc=(-0.5, 0.5), D_0=1, device=torch.device('cuda:0')):
         for multiple solves.
 
         :param img: input img with 1s conductive and 0s non-conductive
-        :param precision:  cp.single or cp.double
         :param bc: Upper and lower boundary conditions. Leave as default.
         :param D_0: reference material diffusivity
 
@@ -313,7 +315,6 @@ def __init__(self, img, cond={1: 1}, bc=(-0.5, 0.5), device=torch.device('cuda:0
         :param img: input img with n conductive phases labelled as integers, and 0s for non-conductive
         :param cond: dict with n phase labels as keys, and their corresponding conductivities as values e.g
         for a 2 phase material, {1:0.543, 2: 0.420}, with 1s and 2s in the input img
-        :param precision:  cp.single or cp.double
         :param bc: Upper and lower boundary conditions. Leave as default.
         """
 
@@ -495,7 +496,6 @@ def check_vertical_flux(self, conv_crit):
                      :-2, 1:-1, 1:-1]) * self.pre_factors[1][:, :-2, 1:-1, 1:-1]
         vert_flux[self.nn == torch.inf] = 0
         fl = torch.sum(vert_flux, (0, 2, 3))[2:-2]
-        print(fl.argmin(), fl.argmax())
         err = (fl.max() - fl.min())*2/(fl.max() + fl.min())
         if err < conv_crit or torch.isnan(err).item():
             return True, torch.mean(fl), err