Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release v1 #64

Merged
merged 22 commits into from
Mar 23, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion HISTORY.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# History

## 1.0.0 ()
## 1.0.0 (2023-03-23)

---

- Migrated to PyTorch from CuPy
- New convergence criteria
- New documentation style
- CI testing
- Includes TauFactor paper

## 0.1.4 (2022-07-11)

Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ TauFactor is an application for calculating tortuosity factors from tomographic
- Documentation: [https://taufactor.readthedocs.io](https://taufactor.readthedocs.io).

<p align="center">
<img src="https://tldr-group.github.io/static/media/tau_example.685a0640.png" alt="TauFactor" width="324" height="324">
<img src="https://tldr-group.github.io/static/media/tau_example.2c29eaf9.png" alt="TauFactor" width="324" height="324">
</p>
<p align="center">
<a href="https://pypi.python.org/pypi/taufactor">
Expand All @@ -27,6 +27,12 @@ TauFactor is an application for calculating tortuosity factors from tomographic

Before installing taufactor, [download the most recent version of PyTorch](https://pytorch.org/get-started/locally/). Ensure you have `pytorch>=1.10` installed in your Python environment.

For example, for a Linux machine with CUDA GPU

```
conda install pytorch pytorch-cuda=11.7 -c pytorch -c nvidia
```

## Quickstart

To install TauFactor via PyPI
Expand Down
Binary file added TF-500x500x500-1x2x6-v3.tiff.zip
Binary file not shown.
6 changes: 6 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@

Before installing taufactor, [download the most recent version of PyTorch](https://pytorch.org/get-started/locally/). Your exact PyTorch configuration will depend on your operating system and GPU availability. Ensure your PyTorch version is `pytorch>=1.0`.

For example, for a Linux machine with CUDA GPU

```
conda install pytorch pytorch-cuda=11.7 -c pytorch -c nvidia
```

## Stable release

To install TauFactor via PyPI
Expand Down
10 changes: 9 additions & 1 deletion docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,19 @@ import tifffile
# load segmented image
img = tifffile.imread('path/filename')
s = tau.Solver(img)
s.solve()
# tau
s.tau
# D_eff
s.D_eff
```

The iteration limit, convergence criteria and verbosity of the solver can be adjusted. Setting `verbose='per_iter'` logs the output of the solver every 100 steps whilst solving. The `conv_crit` controls the value at which convergence is met.

```python
s.solve(verbose='per_iter', conv_crit='1e-5')
```

### Flux direction

The direction of flow by default is the first index of the loaded image. If a different direction is required, the image must be permuted before solving. To visualise this and give guidance, the utility function `flux_direction` can be used
Expand All @@ -46,8 +53,9 @@ import tifffile
# load segmented image
img = tifffile.imread('path/filename')
flux_direction(img)
img = torch.permute(img, (1,2,0))
img = torch.permute(torch.tensor(img), (1,2,0))
s = tau.Solver(img)
s.solve()
```

## Other Solvers
Expand Down
Binary file added example.pdf
Binary file not shown.
142 changes: 142 additions & 0 deletions paper.bib
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,145 @@ @misc{fidgit
journal = {GitHub repository},
url = {https://github.com/arfon/fidgit}
}

@article{gostick2019porespy,
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},
volume={4},
number={37},
pages={1296},
year={2019}
}

@article{ferguson2018puma,
title={PuMA: the porous microstructure analysis software},
author={Ferguson, Joseph C and Panerai, Francesco and Borner, Arnaud and Mansour, Nagi N},
journal={SoftwareX},
volume={7},
pages={81--87},
year={2018},
publisher={Elsevier}
}

@article{le2021openimpala,
title={Openimpala: Open source image based parallisable linear algebra solver},
author={Le Houx, James and Kramer, Denis},
journal={SoftwareX},
volume={15},
pages={100729},
year={2021},
publisher={Elsevier}
}

@article{cooper2016taufactor,
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},
volume={5},
pages={203--210},
year={2016},
publisher={Elsevier}
}

@article{hart1999measurement,
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},
volume={53},
number={2-3},
pages={239--252},
year={1999},
publisher={Elsevier}
}

@article{carey2016estimating,
title={Estimating tortuosity coefficients based on hydraulic conductivity},
author={Carey, Grant R and McBean, Edward A and Feenstra, Stan},
journal={Groundwater},
volume={54},
number={4},
pages={476--487},
year={2016},
publisher={Wiley Online Library}
}

@article{landesfeind2018tortuosity,
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},
volume={165},
number={3},
pages={A469--A476},
year={2018},
publisher={The Electrochemical Society}
}

@article{dahari2023fusion,
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},
volume={13},
number={2},
pages={2370009},
year={2023},
publisher={Wiley Online Library}
}
@article{kench2022microlib,
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},
volume={9},
number={1},
pages={645},
year={2022},
publisher={Nature Publishing Group UK London}
}
@article{withers2021x,
title={X-ray computed tomography},
author={Withers, Philip J and Bouman, Charles and Carmignato, Simone and Cnudde, Veerle and Grimaldi, David and Hagen, Charlotte K and Maire, Eric and Manley, Marena and Du Plessis, Anton and Stock, Stuart R},
journal={Nature Reviews Methods Primers},
volume={1},
number={1},
pages={18},
year={2021},
publisher={Nature Publishing Group UK London}
}
@article{nguyen2020electrode,
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},
volume={6},
number={1},
pages={123},
year={2020},
publisher={Nature Publishing Group UK London}
}

@incollection{pytorch,
title = {PyTorch: An Imperative Style, High-Performance Deep Learning Library},
author = {Paszke, Adam and Gross, Sam and Massa, Francisco and Lerer, Adam and Bradbury, James and Chanan, Gregory and Killeen, Trevor and Lin, Zeming and Gimelshein, Natalia and Antiga, Luca and Desmaison, Alban and Kopf, Andreas and Yang, Edward and DeVito, Zachary and Raison, Martin and Tejani, Alykhan and Chilamkurthy, Sasank and Steiner, Benoit and Fang, Lu and Bai, Junjie and Chintala, Soumith},
booktitle = {Advances in Neural Information Processing Systems 32},
pages = {8024--8035},
year = {2019},
publisher = {Curran Associates, Inc.},
url = {http://papers.neurips.cc/paper/9015-pytorch-an-imperative-style-high-performance-deep-learning-library.pdf}
}
@article{cooper2017simulated,
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},
volume={251},
pages={681--689},
year={2017},
publisher={Elsevier}
}
@article{tjaden2016origin,
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},
volume={12},
pages={44--51},
year={2016},
publisher={Elsevier}
}
Loading