From be28903be7e91e0819a93b7fe57474cbfdbcd47c Mon Sep 17 00:00:00 2001 From: gnzng Date: Mon, 10 Nov 2025 12:23:09 -0800 Subject: [PATCH 1/8] refactor: CI installation process to use 'uv' for faster dependency management --- .github/workflows/main.yml | 21 ++++++++------- .github/workflows/publish.yml | 12 +++++---- pyproject.toml | 50 +++++++++++++++++++++++++++++++++- requirements.txt | 11 -------- setup.py | 51 ----------------------------------- 5 files changed, 67 insertions(+), 78 deletions(-) delete mode 100644 requirements.txt delete mode 100644 setup.py diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5cc6d9bb..84f4a001 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -22,14 +22,15 @@ jobs: with: python-version: ${{ matrix.python-version }} - - name: Install dependencies + - name: Install uv run: | - pip install --upgrade pip - pip install -r requirements.txt - pip install -e . --no-deps + pip install uv + - name: Install dependencies with uv + run: | + uv pip install ."[tests]" - name: Run tests - run: pytest + run: python -m pytest build-docs: if: github.event_name == 'push' && github.ref == 'refs/heads/master' @@ -52,12 +53,12 @@ jobs: with: python-version: '3.9' - - name: Install dependencies + - name: Install uv + run: | + pip install uv + - name: Install dependencies with uv run: | - pip install --upgrade pip - pip install -r requirements.txt - pip install sphinx sphinx_rtd_theme sphinx-argparse - pip install -e . --no-deps + uv pip install ."[docs]"" - name: Build docs working-directory: docs diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 8ff35188..dbb1a1a4 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -19,12 +19,14 @@ jobs: uses: actions/setup-python@v4 with: python-version: "3.x" - - name: Install dependencies + - name: Install uv run: | - python -m pip install --upgrade pip - pip install setuptools wheel - - name: Build package (setup.py) + pip install uv + - name: Install project with uv run: | - python setup.py sdist bdist_wheel + uv pip install -e . + - name: Build package with uv + run: | + uv build - name: Publish package distributions to PyPI uses: pypa/gh-action-pypi-publish@release/v1 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index b7fd46a9..703942ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,51 @@ +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "cdtools-py" +description = "Tools for coherent diffractive imaging and ptychography" +readme = "README.md" +requires-python = ">=3.8" +license = { file = "LICENSE.txt" } +authors = [ + { name = "Abe Levitan", email = "abraham.levitan@psi.ch" }, + { name = "Madelyn Cain" }, + { name = "Anastasiia Kutakh" } +] +maintainers = [ + { name = "Abe Levitan", email = "abraham.levitan@psi.ch" } +] +keywords = ["ptychography", "CDI", "imaging", "torch", "differentiable"] +classifiers = [ + "Programming Language :: Python :: 3", + "Operating System :: OS Independent", + "License :: OSI Approved :: MIT License" +] +urls = { "Homepage" = "https://github.com/cdtools-developers/cdtools", "Documentation" = "https://cdtools-developers.github.io/cdtools/" } +dependencies = [ + "numpy>=1.0", + "scipy>=1.0", + "matplotlib>=2.0", + "torch>=2.3.0", + "h5py>=2.1", + "python-dateutil", +] +dynamic = ["version"] + +[tool.setuptools.dynamic] +version = {attr = "cdtools._version.__version__"} + +[project.optional-dependencies] +tests = [ + "pytest", + "pooch" +] +docs = [ + "sphinx>=4.3.0", + "sphinx-argparse", + "sphinx_rtd_theme>=0.5.1" +] + [tool.ruff] -# Decrease the maximum line length to 79 characters. line-length = 79 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 1c584c86..00000000 --- a/requirements.txt +++ /dev/null @@ -1,11 +0,0 @@ -numpy>=1.0 -scipy>=1.0 -matplotlib>=2.0 # 2.0 introduces better colormaps which are used by default -torch>=1.9.0 #1.9.0 implements support for autograd on indexed complex tensors -h5py>=2.1 -python-dateutil -pytest -pooch -sphinx>=4.3.0 # Fixes a bug with bulleted lists -sphinx-argparse -sphinx_rtd_theme>=0.5.1 # Fixes a bug with bulleted lists diff --git a/setup.py b/setup.py deleted file mode 100644 index ae710d77..00000000 --- a/setup.py +++ /dev/null @@ -1,51 +0,0 @@ -import setuptools -import os -import re - -with open("README.md", "r") as fh: - long_description = fh.read() - -# read version from src/cdtools/_version.py -version_file = os.path.join("src/cdtools", "_version.py") -with open(version_file) as f: - version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]", f.read(), re.M) -if not version_match: - raise RuntimeError("Unable to find version string.") -version = version_match.group(1) - -setuptools.setup( - name="cdtools-py", - version=version, - python_requires='>3.8', # recommended minimum version for pytorch 2.3.0 - author="Abe Levitan", - author_email="abraham.levitan@psi.ch", - description="Tools for coherent diffractive imaging and ptychography", - long_description=long_description, - long_description_content_type="text/markdown", - url="https://github.com/cdtools-developers/cdtools", - install_requires=[ - "numpy>=1.0", - "scipy>=1.0", - "matplotlib>=2.0", # 2.0 has better colormaps which are used by default - "python-dateutil", - "torch>=2.3.0", #2.3.0 is the earliest release for which L-BFGS works directly on complex-valued leaf tensors - "h5py>=2.1"], - extras_require={ - 'tests': [ - "pytest", - "pooch", - ], - 'docs': [ - "sphinx>=4.3.0", - "sphinx-argparse", - "sphinx_rtd_theme>=0.5.1" - ] - }, - package_dir={"": "src"}, - packages=setuptools.find_packages("src"), - classifiers=[ - "Programming Language :: Python :: 3", - "Operating System :: OS Independent", - ], -) - From 728cf9d59029457901b2f2aa9f41dc35c0584b50 Mon Sep 17 00:00:00 2001 From: gnzng Date: Mon, 10 Nov 2025 12:23:25 -0800 Subject: [PATCH 2/8] update readme and installation docs --- README.md | 45 +++++++++++++++++++++ docs/source/installation.rst | 78 +++++++++++++++++++++++------------- 2 files changed, 96 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 76371bf7..71f81e6d 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,57 @@ model.compare(dataset) # See how the simulated and measured patterns compare plt.show() ``` +# Installation + +CDTools can be installed in several ways depending on your needs. For most users, installation from pypi is recommended. For developers or those who want the latest features, installation from source is available. + +## Installation from pypi + CDTools can be installed via pip as the [cdtools-py](https://pypi.org/project/cdtools-py/) package on [PyPI](https://pypi.org/): ```bash $ pip install cdtools-py ``` +or using [uv](https://github.com/astral-sh/uv): + +```bash +$ uv pip install cdtools-py +``` + +## Installation from Source + +For development or to access the latest features, CDTools can be installed directly from source: + + +```bash +$ git clone https://github.com/cdtools-developers/cdtools.git +$ cd cdtools +$ pip install -e . +``` + + +or using [uv](https://github.com/astral-sh/uv): + +```bash +$ git clone https://github.com/cdtools-developers/cdtools.git +$ cd cdtools +$ uv pip install -e . +``` + +## Installing for Contributors (with tests and docs dependencies) + +If you want to run the test suite or build the documentation, install with the extra dependencies: + +```bash +$ pip install -e ."[tests,docs]" +``` +or with uv: +```bash +$ uv pip install -e ."[tests,docs]" +``` + + Further documentation is found [here](https://cdtools-developers.github.io/cdtools/). diff --git a/docs/source/installation.rst b/docs/source/installation.rst index cf86477e..486588f1 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -15,6 +15,14 @@ To install from `PyPI`_, run: $ pip install cdtools-py +or you can use `uv`_ for a faster installation: + +.. _`uv`: https://github.com/astral-sh/uv + +.. code:: bash + + $ uv pip install cdtools-py + Pytorch, a major dependence of CDTools, often needs to be installed with a specific CUDA version for machine compatability. If you run into issues with pytorch, consider first installing pytorch into your environment using the instructions on `the pytorch site`_. .. _`the pytorch site`: https://pytorch.org/get-started/locally/ @@ -31,18 +39,51 @@ The source code for CDTools is hosted on `Github`_. .. _`Github`: https://github.com/cdtools-developers/cdtools -Step 2: Install Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To download the source code, you can either clone the repository using git: + +.. code:: bash + + $ git clone https://github.com/cdtools-developers/cdtools.git + +or you can download a zip file of the repository from the `releases page`_. + +.. _`releases page`: https://github.com/cdtools-developers/cdtools/releases -The major dependency for CDTools is pytorch version 2.3.0 or greater. Because the details of the pytorch installation can vary depending on platform and GPU availability, it is recommended that you first install pytorch using the instructions on `the pytorch site`_. The remaining dependencies can be installed by running the following command from the top level directory of the git repository: + +Step 2: Install +^^^^^^^^^^^^^^^ + +Move to the directory where you downloaded the source code. It is recommended that you create a new python virtual environment to install CDTools into. + +Installation using pip and uv. Editable mode is recommended for development purposes and is added with the `-e` flag. .. code:: bash - - $ pip install -r requirements.txt -Note that several optional dependencies used for testing and documentation will also be installed. The full set of dependencies and minimum requirements are listed below. CDTools is reguarly tested with the latest versions of these packages and with python 3.8 through 3.12. + $ pip install -e . + +or using uv: + +.. code:: bash + + $ uv pip install -e . + -Required dependencies: +To install the required test and documentation dependencies as well, use: + +.. code:: bash + + $ pip install -e ."[tests,docs]" + +or using uv: + +.. code:: bash + + $ uv pip install -e ."[tests,docs]" + +CDTools is reguarly tested with the latest versions of these packages and with python 3.8 through 3.12. + + +Required dependencies (see pyproject.toml for all details): * `numpy `_ >= 1.0 * `scipy `_ >= 1.0 @@ -63,30 +104,13 @@ Optional dependencies for building docs: * `sphinx_rtd_theme `_ >= 0.5.1 -Step 3: Install -^^^^^^^^^^^^^^^ - -To install CDTools, run the following command from the top level directory of the git repository: - -.. code:: bash - - $ pip install -e . --no-deps - - -This will install CDTools in developer mode, so that changes to the code will propagate to the installed version immediately. This is best if you plan to actively develop CDTools. If you simply need a custom environment, you can also install CDTools in standard mode using: - -.. code:: bash - - $ pip install . --no-deps - - -Step 4: Run The Tests -^^^^^^^^^^^^^^^^^^^^^ +Optional step 4: Run The Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To ensure that the installation has worked correctly, it is recommended that you run the unit tests. Execute the following command from the top level directory of the git repository: .. code:: bash - $ pytest + $ python -m pytest If any tests fail, make sure that you have all the noted dependencies properly installed. If you do, and things still aren't working, `open an issue on the github page `_ and we'll get to the bottom of it. From 18c794b5db8d03e4d6bc0e5f1c7c108d76bfb427 Mon Sep 17 00:00:00 2001 From: gnzng Date: Mon, 10 Nov 2025 12:37:44 -0800 Subject: [PATCH 3/8] fix: add virtual environment creation step in CI github workflows --- .github/workflows/main.yml | 12 +++++++++++- .github/workflows/publish.yml | 5 +++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 84f4a001..3316f7dc 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -25,6 +25,11 @@ jobs: - name: Install uv run: | pip install uv + + - name: Create virtual environment + run: | + uv venv + - name: Install dependencies with uv run: | uv pip install ."[tests]" @@ -56,9 +61,14 @@ jobs: - name: Install uv run: | pip install uv + + - name: Create virtual environment + run: | + uv venv + - name: Install dependencies with uv run: | - uv pip install ."[docs]"" + uv pip install ."[docs]" - name: Build docs working-directory: docs diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index dbb1a1a4..9beed2b6 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -22,6 +22,11 @@ jobs: - name: Install uv run: | pip install uv + + - name : Create virtual environment + run: | + uv venv + - name: Install project with uv run: | uv pip install -e . From e94499a6a4eecc5d289a8787ec334cf3954abf85 Mon Sep 17 00:00:00 2001 From: gnzng Date: Mon, 10 Nov 2025 12:42:32 -0800 Subject: [PATCH 4/8] fix: update pytest command to use 'uv' for consistency in CI workflow --- .github/workflows/main.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3316f7dc..672014e3 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -35,7 +35,8 @@ jobs: uv pip install ."[tests]" - name: Run tests - run: python -m pytest + run: | + uv run pytest build-docs: if: github.event_name == 'push' && github.ref == 'refs/heads/master' From 5a3e154e8df6181bc8cb9904b0c9b189a537da69 Mon Sep 17 00:00:00 2001 From: gnzng Date: Mon, 10 Nov 2025 12:50:59 -0800 Subject: [PATCH 5/8] add Python 3.13 to the CI workflow matrix --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 672014e3..db280c73 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -11,7 +11,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] continue-on-error: true steps: From 11ed3df35e72bb8844c6bbfe3b66c8af8b76c1d2 Mon Sep 17 00:00:00 2001 From: gnzng Date: Tue, 11 Nov 2025 14:33:55 -0600 Subject: [PATCH 6/8] ending python 3.8 support, adding python 3.14 to automatic test --- .github/workflows/main.yml | 2 +- docs/source/installation.rst | 4 ++-- pyproject.toml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index db280c73..f748b517 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -11,7 +11,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] + python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] continue-on-error: true steps: diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 486588f1..11c3aada 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,7 +1,7 @@ Installation ============ -CDTools supports python >=3.8 and can be installed via pip as the the `cdtools-py`_ package on `PyPI`_. If you plan to contribute to the code or need a custom environment, installation from source is also possible. +CDTools supports python >=3.9 and can be installed via pip as the the `cdtools-py`_ package on `PyPI`_. If you plan to contribute to the code or need a custom environment, installation from source is also possible. .. _`cdtools-py`: https://pypi.org/project/cdtools-py/ .. _`PyPI`: https://pypi.org/ @@ -80,7 +80,7 @@ or using uv: $ uv pip install -e ."[tests,docs]" -CDTools is reguarly tested with the latest versions of these packages and with python 3.8 through 3.12. +CDTools is reguarly tested with the latest versions of these packages and with python 3.9 through 3.14. Required dependencies (see pyproject.toml for all details): diff --git a/pyproject.toml b/pyproject.toml index 703942ea..11ccebce 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" name = "cdtools-py" description = "Tools for coherent diffractive imaging and ptychography" readme = "README.md" -requires-python = ">=3.8" +requires-python = ">=3.9" license = { file = "LICENSE.txt" } authors = [ { name = "Abe Levitan", email = "abraham.levitan@psi.ch" }, From 3c9e9eb1c7fd58a493dace13c156d70c46efa568 Mon Sep 17 00:00:00 2001 From: gnzng Date: Wed, 12 Nov 2025 08:59:37 -0600 Subject: [PATCH 7/8] adding pure pip install pipeline to CI --- .github/workflows/main.yml | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f748b517..a24af2b7 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -7,7 +7,7 @@ on: branches: [ master ] jobs: - test: + test-uv-pip-install: runs-on: ubuntu-latest strategy: matrix: @@ -37,6 +37,28 @@ jobs: - name: Run tests run: | uv run pytest + + test-pip-install: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.9', '3.14'] + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v3 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies with pip + run: | + pip install ."[tests]" + + - name: Run tests + run: | + pytest build-docs: if: github.event_name == 'push' && github.ref == 'refs/heads/master' From 3f46caf757daba51e39ec03193cc1b0b6af0db0c Mon Sep 17 00:00:00 2001 From: gnzng Date: Wed, 12 Nov 2025 09:04:53 -0600 Subject: [PATCH 8/8] update authors list in pyproject.toml and move further doc link --- README.md | 6 ++---- pyproject.toml | 2 ++ 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 71f81e6d..742b4725 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ model.compare(dataset) # See how the simulated and measured patterns compare plt.show() ``` +Further documentation is found [here](https://cdtools-developers.github.io/cdtools/). + # Installation CDTools can be installed in several ways depending on your needs. For most users, installation from pypi is recommended. For developers or those who want the latest features, installation from source is available. @@ -76,10 +78,6 @@ or with uv: $ uv pip install -e ."[tests,docs]" ``` - -Further documentation is found [here](https://cdtools-developers.github.io/cdtools/). - - CDTools was developed in the [photon scattering lab](https://scattering.mit.edu/) at MIT, and further development took place within the [computational x-ray imaging group](https://www.psi.ch/en/cxi) at PSI. The code is distributed under an MIT (a.k.a. Expat) license. If you would like to publish any work that uses CDTools, please contact [Abe Levitan](mailto:abraham.levitan@psi.ch). Have a wonderful day! diff --git a/pyproject.toml b/pyproject.toml index 11ccebce..9ba1438c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,6 +10,8 @@ requires-python = ">=3.9" license = { file = "LICENSE.txt" } authors = [ { name = "Abe Levitan", email = "abraham.levitan@psi.ch" }, + { name = "Dayne Y. Sasaki" }, + { name = "Damian Guenzing" }, { name = "Madelyn Cain" }, { name = "Anastasiia Kutakh" } ]