Merge pull request #54 from decarlof/main

Improved the docs

docs/demo/readrec_aps.py

@@ -34,9 +34,6 @@ def read_aps(fname):
     args.propagation_distance         = meta_dict['measurement_instrument_detector_motor_stack_setup_z'][0]
     args.energy                       = meta_dict['measurement_instrument_monochromator_energy'][0]
     args.retrieve_phase_alpha         = 0.0008
-    args.rotation_axis_sift_threshold = 0.5 # remove this once the default for rotation-axis-sift-threshold in config.py is set to 0.5 (now is '0.5')
-
-
 
 def main():
 

docs/source/api/tomocupy.find_center.rst

@@ -10,5 +10,4 @@
 
    .. autosummary::
 
-   find_min_max
-   register_shift_sift
+   FindCenter

docs/source/api/tomocupy.remove_stripe.rst

@@ -10,4 +10,9 @@
 
    .. autosummary::
 
+      DWTForward
+      DWTInverse
+      afb1d
+      remove_all_stripe
       remove_stripe_fw
+      remove_stripe_ti

docs/source/bibtex/cite.bib

@@ -12,3 +12,12 @@ @article{Nikitin:22
 abstract = {Fast 3D data analysis and steering of a tomographic experiment by changing environmental conditions or acquisition parameters require fast, close to real-time, 3D reconstruction of large data volumes. Here a performance-optimized {\it TomocuPy} package is presented as othera GPU alternative to the commonly used central processing unit (CPU) based {\it TomoPy} package for tomographic reconstruction. {\it TomocuPy} utilizes modern hardware capabilities to organize a 3D asynchronous reconstruction involving parallel read/write operations with storage drives, CPU{--}GPU data transfers, and GPU computations. In the asynchronous reconstruction, all the operations are timely overlapped to almost fully hide all data management time. Since most cameras work with less than 16-bit digital output, the memory usage and processing speed are furthermore optimized by using 16-bit floating-point arithmetic. As a result, 3D reconstruction with {\it TomocuPy} became 20{--}30 times faster than its multi-threaded CPU equivalent. Full reconstruction (including read/write operations and methods initialization) of a 2048${\sp 3}$ tomographic volume takes less than 7s on a single Nvidia Tesla A100 and PCIe 4.0 NVMe SSD, and scales almost linearly increasing the data size. To simplify operation at synchrotron beamlines, {\it TomocuPy} provides an easy-to-use command-line interface. Efficacy of the package was demonstrated during a tomographic experiment on gas-hydrate formation in porous samples, where a steering option was implemented as a lens-changing mechanism for zooming to regions of interest.},
 keywords = {tomography, reconstruction, GPU, NVMe SSD, conveyor processing, asynchronous processing},
 }
+
+@misc{Nikitin:24,
+      title={Laminography as a tool for imaging large-size samples with high resolution}, 
+      author={Viktor Nikitin and Gregg Wildenberg and Alberto Mittone and Pavel Shevchenko and Alex Deriy and Francesco De Carlo},
+      year={2024},
+      eprint={2401.11101},
+      archivePrefix={arXiv},
+      primaryClass={physics.comp-ph}
+}

docs/source/conf.py

@@ -339,5 +339,8 @@
     'tomocupy.cfunc_filter',
     'tomocupy.cfunc_filterfp16',    
     'tomocupy.cfunc_linerec',    
-    'tomocupy.cfunc_linerecfp16',]
+    'tomocupy.cfunc_linerecfp16',
+    'tomocupy.cfunc_usfft1d',
+    'tomocupy.cfunc_usfft2d',
+    'tomocupy.cfunc_fft2d']
 

docs/source/credits.rst

@@ -3,7 +3,7 @@ Credits
 =======
 
 
-If you use tomocupy, we kindly request that you cite :cite:`Nikitin:22`.
+If you use tomocupy, we kindly request that you cite :cite:`Nikitin:22` and :cite:`Nikitin:24`.
 
 Citations
 =========

docs/source/install.rst

@@ -2,8 +2,8 @@
 Installation and test
 =====================
 
-Tomocupy works in NVidia GPUs of compute capability 6.0 and higher. To run tomocupy the system should have an nvidia driver installed (https://developer.nvidia.com/cuda-downloads). Cuda Toolkit is not necessary.
-Run 'nvidia-smi' to check whether the driver is installed. For check compute capability of the GPU, see http://mylifeismymessage.net/find-the-compute-capability-of-your-nvidia-graphics-card-gpu/. 
+Tomocupy works in NVidia GPUs of compute capability 6.0 and higher. To run tomocupy the system should have an `nvidia driver installed <https://developer.nvidia.com/cuda-downloads>`_. Cuda Toolkit is not necessary.
+Run ``nvidia-smi`` to check whether the driver is installed. For check compute capability of the GPU, see `this document <http://mylifeismymessage.net/find-the-compute-capability-of-your-nvidia-graphics-card-gpu/>`_. 
 
 1. Add conda-forge to anaconda channels
 
@@ -16,6 +16,7 @@ Run 'nvidia-smi' to check whether the driver is installed. For check compute cap
 2. Environmental solver mamba works much faster than the regular one, use
 
 ::
+
     (base)$ conda install -n base conda-libmamba-solver
     (base)$ conda config --set solver libmamba
 
@@ -52,6 +53,7 @@ Installation for development
 2. Environmental solver mamba works much faster than the regular one, use
 
 ::
+
     (base)$ conda install -n base conda-libmamba-solver
     (base)$ conda config --set solver libmamba
 
@@ -83,7 +85,7 @@ Installation for development
     (tomocupy)$ cd -
 
 
-6. Make sure that the path to nvcc compiler is set (or set it by e.g. 'export CUDACXX=/local/cuda-11.7/bin/nvcc') and install tomocupy
+6. Make sure that the path to nvcc compiler is set (or set it by e.g. ``export CUDACXX=/local/cuda-11.7/bin/nvcc``) and install tomocupy
 
 ::
     
@@ -95,22 +97,19 @@ Installation for development
 Additional instructions for Windows
 ===================================
 
-Install Build VS 2019 utils:
-
-https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2019
-
-Install CUDA toolkit, e.g. 
+#. Install `Build VS 2019 utils <https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2019>`_
 
-https://developer.nvidia.com/cuda-11.2.2-download-archive?target_os=Windows&target_arch=x86_64
+#. Install CUDA toolkit, e.g. `cuda 11_2_2 <https://developer.nvidia.com/cuda-11.2.2-download-archive?target_os=Windows&target_arch=x86_64>`_
 
-Note: it is better to have only 1 version of VS and 1 version of CUDA toolkit on your system to avoid problems with environmental variables
+#. Install `Anaconda for windows <https://docs.anaconda.com/free/anaconda/install/windows/>`_ and use Powershell in which tomocupy environment can be created
 
-Install Anaconda for windows https://docs.anaconda.com/free/anaconda/install/windows/ and use Powershell in which tomocupy environment can be created
+.. note::
+    It is better to have only one version of VS and one version of CUDA toolkit on your system to avoid problems with environmental variables
 
 ==========
 Unit tests
 ==========
-Check the library path to cuda or set it by 'export LD_LIBRARY_PATH=/local/cuda-11.7/lib64'
+Check the library path to cuda or set it by ``export LD_LIBRARY_PATH=/local/cuda-11.7/lib64``
 
 Run the following to check all functionality
 ::
@@ -142,7 +141,8 @@ Installation on Polaris supercomputer
     module add gcc/11.2.0
     module add cudatoolkit-standalone/11.4.4
 
-*we work with cuda-11.4 not with cuda-12.1 because the current driver version on polaris is 11.4:
+.. note::
+    We work with cuda-11.4 not with cuda-12.1 because the current driver version on polaris is 11.4
 
 3. create tomocupy environment, specifying cudatoolkit=11.4
 
@@ -174,7 +174,8 @@ Installation on Polaris supercomputer
 
     qsub -I -A hp-ptycho -l select=4:system=polaris -l filesystems=home:eagle -l walltime=30:00 -q debug-scaling
 
-*replace hp-ptycho by your project
+.. note::
+    Replace hp-ptycho by your project
 
 8. test tomocupy:
 

docs/source/usage.rst

@@ -5,45 +5,73 @@ Usage
 Examples
 ========
 
-Try center reconstruction
+Command Line Interface
+----------------------
+
+**tomocupy** includes a commad-line-interface (CLI). The simplest way to set a reconstruction parameter is to directly
+pass it as an option to the ``tomocupy`` command. Some options also accept an argument, while others simple enable certain
+behavior. Parameters given directly via the command line will override those given via a parameter file or global configuration file.
+
+To list all the options supported by the tomocupy CLI, after installing tomocupy, type::
+
+    (tomocupy)$ tomocupy -h
+    (tomocupy)$ tomocupy recon -h
+    (tomocupy)$ tomocupy recon_steps -h
+
+Below are different **reconstruction** examples
+
+Try center
+~~~~~~~~~~
 ::
-   
+
    (tomocupy)$ tomocupy recon --file-name data/test_data.h5 --nsino-per-chunk 4 --reconstruction-type try --center-search-width 100
 
-Full volume reconstruction
+Full volume
+~~~~~~~~~~~
 ::
 
    (tomocupy)$ tomocupy recon --file-name data/test_data.h5 --nsino-per-chunk 4 --rotation-axis 700 --reconstruction-type full
 
-Double FOV reconstruction
+Double FOV
+~~~~~~~~~~
 ::
 
     (tomocupy)$ (tomocupy)$ tomocupy recon --file-name data/test_data.h5 --nsino-per-chunk 4 --rotation-axis 700 --reconstruction-type full --file-type double_fov
 
-Full volume reconstruction with phase retrieval
+Full volume rec with phase retrieval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ::
 
     (tomocupy)$ tomocupy recon_steps --file-name data/test_data.h5 --nsino-per-chunk 4 --rotation-axis 700 --reconstruction-type full --energy 20 --pixel-size 1.75 --propagation-distance 100 --retrieve-phase-alpha 0.001 --retrieve-phase-method paganin --reconstruction-type full 
 
-Laminographic try reconstruction
+Laminographic try
+~~~~~~~~~~~~~~~~~
 ::
 
     (tomocupy)$ tomocupy recon_steps --file-name data/test_data.h5 --nsino-per-chunk 8 --nproj-per-chunk 8 --reconstruction-type try --center-search-width 100 --lamino-angle 20
 
-Laminographic try angle reconstruction
+Laminographic try angle
+~~~~~~~~~~~~~~~~~~~~~~~
 ::
 
     (tomocupy)$ tomocupy recon_steps --file-name data/test_data.h5 --nsino-per-chunk 8 --nproj-per-chunk 8 --rotation-axis 700 --reconstruction-type try_lamino --lamino-search-width 2 --lamino-angle 20
 
-Laminographic full reconstruction
+Laminographic full rec
+~~~~~~~~~~~~~~~~~~~~~~
 ::
     
     (tomocupy)$ tomocupy recon_steps --file-name data/test_data.h5 --nsino-per-chunk 8 --nproj-per-chunk 8--reconstruction-type full --rotation-axis 700 --lamino-angle 20
 
-More options
-============
-::
 
-    (tomocupy)$ tomocupy -h
-    (tomocupy)$ tomocupy recon -h
-    (tomocupy)$ tomocupy recon_steps -h
+Reconstruct APS data 
+--------------------
+
+This section contains the readrec_aps script.
+
+Download file: :download:`readrec_aps.py
+<../../docs/demo/readrec_aps.py>`
+
+.. literalinclude:: ../../docs/demo/readrec_aps.py
+    :tab-width: 4
+    :linenos:
+    :language: guess

src/tomocupy/__main__.py

@@ -1,3 +1,43 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# *************************************************************************** #
+#                  Copyright © 2022, UChicago Argonne, LLC                    #
+#                           All Rights Reserved                               #
+#                         Software Name: Tomocupy                             #
+#                     By: Argonne National Laboratory                         #
+#                                                                             #
+#                           OPEN SOURCE LICENSE                               #
+#                                                                             #
+# Redistribution and use in source and binary forms, with or without          #
+# modification, are permitted provided that the following conditions are met: #
+#                                                                             #
+# 1. Redistributions of source code must retain the above copyright notice,   #
+#    this list of conditions and the following disclaimer.                    #
+# 2. Redistributions in binary form must reproduce the above copyright        #
+#    notice, this list of conditions and the following disclaimer in the      #
+#    documentation and/or other materials provided with the distribution.     #
+# 3. Neither the name of the copyright holder nor the names of its            #
+#    contributors may be used to endorse or promote products derived          #
+#    from this software without specific prior written permission.            #
+#                                                                             #
+#                                                                             #
+# *************************************************************************** #
+#                               DISCLAIMER                                    #
+#                                                                             #
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS         #
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT           #
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS           #
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT    #
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,      #
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    #
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR      #
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF      #
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING        #
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS          #
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                #
+# *************************************************************************** #
+
 import sys
 import time
 import argparse
@@ -16,6 +56,10 @@
 from tomocupy.dataio import reader
 from tomocupy.dataio import writer
 
+__author__ = "Viktor Nikitin"
+__copyright__ = "Copyright (c) 2022, UChicago Argonne, LLC."
+__docformat__ = 'restructuredtext en'
+
 log = logging.getLogger(__name__)
 
 

src/tomocupy/config.py

@@ -54,6 +54,9 @@
 from tomocupy import utils
 from tomocupy import __version__
 
+__author__ = "Viktor Nikitin"
+__copyright__ = "Copyright (c) 2022, UChicago Argonne, LLC."
+__docformat__ = 'restructuredtext en'
 
 log = logging.getLogger(__name__)
 
@@ -376,7 +379,7 @@ def default_parameter(func, param):
         'type': str,
         'help': "Projection pairs to find rotation axis. Each second projection in a pair will be flipped and used to find shifts from the first element in a pair. The shifts are used to calculate the center.  Example [0,1499] for a 180 deg scan, or [0,1499,749,2249] for 360, etc.", },
     'rotation-axis-sift-threshold': {
-        'default': '0.5',
+        'default': 0.5,
         'type': float,
         'help': "SIFT threshold for rotation search.", },
     'rotation-axis-method': {

src/tomocupy/global_vars.py

@@ -1,3 +1,44 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# *************************************************************************** #
+#                  Copyright © 2022, UChicago Argonne, LLC                    #
+#                           All Rights Reserved                               #
+#                         Software Name: Tomocupy                             #
+#                     By: Argonne National Laboratory                         #
+#                                                                             #
+#                           OPEN SOURCE LICENSE                               #
+#                                                                             #
+# Redistribution and use in source and binary forms, with or without          #
+# modification, are permitted provided that the following conditions are met: #
+#                                                                             #
+# 1. Redistributions of source code must retain the above copyright notice,   #
+#    this list of conditions and the following disclaimer.                    #
+# 2. Redistributions in binary form must reproduce the above copyright        #
+#    notice, this list of conditions and the following disclaimer in the      #
+#    documentation and/or other materials provided with the distribution.     #
+# 3. Neither the name of the copyright holder nor the names of its            #
+#    contributors may be used to endorse or promote products derived          #
+#    from this software without specific prior written permission.            #
+#                                                                             #
+#                                                                             #
+# *************************************************************************** #
+#                               DISCLAIMER                                    #
+#                                                                             #
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS         #
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT           #
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS           #
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT    #
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,      #
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    #
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR      #
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF      #
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING        #
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS          #
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                #
+# *************************************************************************** #
+
 from argparse import Namespace
+
 args = Namespace()
 params = Namespace()

src/tomocupy/logging.py

@@ -52,7 +52,9 @@
 import logging
 from logging import *
 
-
+__author__ = "Viktor Nikitin"
+__copyright__ = "Copyright (c) 2022, UChicago Argonne, LLC."
+__docformat__ = 'restructuredtext en'
 __all__ = ['setup_custom_logger', 'ColoredLogFormatter'] + logging.__all__
 
 

src/tomocupy/processing/remove_stripe.py

@@ -44,6 +44,8 @@
 from cupyx.scipy.ndimage import binary_dilation
 from cupyx.scipy.ndimage import uniform_filter1d
 
+__all__ = ['DWTForward', 'DWTInverse', 'afb1d', 'remove_all_stripe', 'remove_stripe_fw', 'remove_stripe_ti']
+
 ###### Ring removal with wavelet filtering (adapted for cupy from pytroch_wavelet package https://pytorch-wavelets.readthedocs.io/)##########
 
 def _reflect(x, minx, maxx):

src/tomocupy/processing/retrieve_phase.py

@@ -44,6 +44,8 @@
 import cupy as cp
 from cupy.fft import fft2, ifft2
 
+__all__ = ['paganin_filter', ]
+
 BOLTZMANN_CONSTANT = 1.3806488e-16  # [erg/k]
 SPEED_OF_LIGHT = 299792458e+2  # [cm/s]
 PI = 3.14159265359

src/tomocupy/utils.py

@@ -50,7 +50,9 @@
 from tomocupy import logging
 log = logging.getLogger(__name__)
 
-# Print iterations progress
+__author__ = "Viktor Nikitin"
+__copyright__ = "Copyright (c) 2022, UChicago Argonne, LLC."
+__docformat__ = 'restructuredtext en'
 
 
 def printProgressBar(iteration, total, qsize, prefix='', suffix='', decimals=1, length=100, fill='█', printEnd="\r"):