Metadata-Version: 2.4
Name: ganrec
Version: 0.3.0
Summary: A deep neural network data reconstruction platform
Project-URL: homepage, https://github.com/XYangXRay/ganrec
Project-URL: repository, https://github.com/XYangXRay/ganrec
Project-URL: documentation, https://github.com/XYangXRay/ganrec
Author-email: Xiaogang Yang <xiaogang.yang@outlook.com>
License: BSD 3-Clause License
        
        Copyright (c) 2022, Brookhaven National Lab
        All rights reserved.
        
        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.
        
        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.
License-File: AUTHORS.rst
License-File: LICENSE
Keywords: Data reconstruction,GAN,Phase retrieval,Tomography
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: ipykernel>=6.0.0
Requires-Dist: ipython>=8.12.3
Requires-Dist: matplotlib>=3.3.2
Requires-Dist: numpy>=1.19.2
Requires-Dist: scikit-image>=0.19.3
Requires-Dist: tifffile>=2023.12.9
Requires-Dist: tqdm>=4.65.0
Provides-Extra: pytorch
Requires-Dist: quantities; extra == 'pytorch'
Requires-Dist: torch>=2.0.0; extra == 'pytorch'
Requires-Dist: torchvision; extra == 'pytorch'
Provides-Extra: tensorflow
Requires-Dist: tensorflow[and-cuda]>=2.17.0; extra == 'tensorflow'
Description-Content-Type: text/markdown

# GANrec: A GAN-based data reconstruction framework

![PyPI](https://img.shields.io/pypi/v/ganrec)
![Python Version](https://img.shields.io/pypi/pyversions/ganrec)
![License](https://img.shields.io/pypi/l/ganrec)
[![CI](https://github.com/XYangXRay/ganrec/actions/workflows/python-app.yml/badge.svg)](https://github.com/XYangXRay/ganrec/actions/workflows/python-app.yml)

## Overview

GANrec is an data reconstruction framework that harnesses the power of Generative Adversarial Networks (GANs). While traditional reconstruction methods primarily rely on intricate algorithms to piece together fragmented data, GANrec employs the generative capabilities of GANs to reimagine and revitalize data reconstruction.

Originally designed for the fields of tomography and phase retrieval, GANrec shines in its adaptability. With a provision to input the forward model, the framework can be flexibly adapted for complex data reconstruction processes across diverse applications.

## Features

1. GAN-powered Reconstruction: At its core, GANrec employs GANs to assist in the reconstruction process, enabling more accurate and efficient results than conventional methods.
2. Specialized for Tomography & Phase Retrieval: GANrec has been optimized for tomography and phase retrieval applications, ensuring precision and reliability in these domains.
3. Modular Design: The framework's architecture allows users to provide their forward model, making it adaptable for various complex data reconstruction challenges.
4. Efficient and Scalable: Built to handle large datasets, GANrec ensures that speed and efficiency are maintained without compromising the accuracy of reconstruction.

## Installation

The simplest way is pip. Pixi and Conda sections below show example runtime environments.

### Pip (quickest)

Install GANrec with your preferred backend in one step using extras:

```bash
# TensorFlow backend
pip install "ganrec[tensorflow]"

# PyTorch backend
pip install "ganrec[pytorch]"
```

Notes:
- For TensorFlow GPU wheels, see TensorFlow’s docs (e.g., tensorflow[and-cuda]) and ensure compatible NVIDIA drivers/CUDA.
- For PyTorch, use the selector on pytorch.org for OS/CUDA-specific commands if the generic wheel doesn’t match your system.

### Pixi (recommended)

Pixi manages environments and dependencies declaratively via `pyproject.toml`.

- Default backend (TensorFlow with CUDA extras; no PyTorch):

```bash
pixi install
```

- Optional PyTorch backend (no TensorFlow):

```bash
pixi -e pytorch install
```

Quick start with Pixi:

1) Install Pixi (see https://pixi.sh)
2) Clone this repo and enter it:
   - git clone https://github.com/XYangXRay/ganrec.git && cd ganrec
3) Install the default environment (TensorFlow):
   - pixi install
4) Or install the PyTorch environment only:
   - pixi -e pytorch install
5) Run examples:
   - pixi run python examples/holography_tf.py
   - pixi -e pytorch run python examples/tomography_torch.py

Note: Environments are defined in `pyproject.toml` — `default` uses TensorFlow; `pytorch` uses PyTorch.

### Conda environment (example runtime)

#### 1. Create & Activate a Conda Environment
Open your terminal or command prompt and create a new conda environment named `ganrec` with Python 3.11:

```bash
conda create --name ganrec python=3.11
conda activate ganrec
```

#### 2. Install ganrec with your preferred backend
Then install via pip extras as above.


## Additional Notes for Users

### Choosing Between TensorFlow and PyTorch
If you're not sure which one to choose, consider the specific requirements of your project or any existing familiarity you have with either library.
TensorFlow is often chosen for its production deployment capabilities and integration with TensorFlow Extended (TFX).
PyTorch is favored for its ease of use, dynamic computation graph, and strong support from the research community.
### Installing GPU Support
ganrec requires heavy duty work with GPU, make sure to install the GPU versions of TensorFlow or PyTorch. Instructions for this can be found on the respective official websites (TensorFlow and PyTorch).

## Examples

GANrec currently has applications for tomography reconstruction and in-line phase contrast (holography) phase retrieval:

1. X-ray tomography reconstruction:
   - [Tomography Example](https://github.com/XYangXRay/ganrec/blob/main/examples/tomography_tf.ipynb)
2. Holography phase retrieval:
   - [Phase retrieval Example](https://github.com/XYangXRay/ganrec/blob/main/examples/holography_tf.ipynb)

You can also run the Python examples directly:

```bash
# TensorFlow tomography example
pixi run python examples/tomography_tf.py

# TensorFlow holography example
pixi run python examples/holography_tf.py

# PyTorch tomography example
pixi -e pytorch run python examples/tomography_torch.py
```

## References

If you find GANrec is useful in your work, please consider citing:

J. Synchrotron Rad. (2020). 27, 486-493.
Available at: https://doi.org/10.1107/S1600577520000831
