From ab30afb10ef2d94b61d3c2a35148430db65c139e Mon Sep 17 00:00:00 2001 From: Abe Levitan Date: Wed, 2 Jul 2025 14:21:43 +0200 Subject: [PATCH] Update the documentation to reflect the existence of a PyPI package --- README.md | 8 +- docs/source/installation.rst | 75 +++++++++------ docs/source/intro.rst | 1 - example_environment.yml | 181 ----------------------------------- setup.py | 2 +- 5 files changed, 52 insertions(+), 215 deletions(-) delete mode 100644 example_environment.yml diff --git a/README.md b/README.md index 696ab4f..76371bf 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,13 @@ model.compare(dataset) # See how the simulated and measured patterns compare plt.show() ``` -Full installation instructions and documentation can be found [here](https://cdtools-developers.github.io/cdtools/). +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 +``` + +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). diff --git a/docs/source/installation.rst b/docs/source/installation.rst index d998f93..cf86477 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,79 +1,92 @@ Installation ============ -Step 1: Download ----------------- +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. -The source code for CDTools is hosted on `Github`_. At the moment, the repository remains private while we decide on licensing. Access can be granted upon request by contacting `Abe Levitan `_. +.. _`cdtools-py`: https://pypi.org/project/cdtools-py/ +.. _`PyPI`: https://pypi.org/ -.. _`Github`: https://github.com/cdtools-developers/cdtools +Option 1: Installation from PyPI +-------------------------------- -The repository remains under active development as of early 2025. +To install from `PyPI`_, run: -Step 2: Install Dependencies ----------------------------- +.. code:: bash + + $ pip install cdtools-py -CDTools is regularly tested with Python versions 3.8 to 3.12, so it is recommended to use one of these versions. In general, CDTools requires Python 3.7 or higher. - -The major dependency for CDTools is pytorch (version 1.9.0 or greater). Because the details of the installation can vary depending on platform, GPU availability, etc, it is recommended that you follow the install instructions on `the pytorch site`_ to install pytorch before installing the remaining dependencies. +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/ -pytorch stopped supporting installation using conda for installation, so it is recommended continue the installation using pip. +Option 2: Installation from source +---------------------------------- + + +Step 1: Download +^^^^^^^^^^^^^^^^ + +The source code for CDTools is hosted on `Github`_. + +.. _`Github`: https://github.com/cdtools-developers/cdtools + + +Step 2: Install Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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: .. code:: bash $ pip install -r requirements.txt -This will install all required dependencies and verify that they meet the pytorch version requirements. Additionally, several optional dependencies used for testing and documentation will also be installed. The full set of dependencies and minimum requirements are listed below is listed below. - -CDTools is reguarly tested with the latest versions of the packages shown below. +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. Required dependencies: * `numpy `_ >= 1.0 * `scipy `_ >= 1.0 * `matplotlib `_ >= 2.0 - * `pytorch `_ >= 1.9.0 + * `pytorch `_ >= 2.3.0 * `python-dateutil `_ * `h5py `_ >= 2.1 -Optional dependencies: +Optional dependencies for running tests: * `pytest `_ * `pooch `_ + +Optional dependencies for building docs: + * `sphinx `_ >= 4.3.0 * `sphinx-argparse `_ * `sphinx_rtd_theme `_ >= 0.5.1 -The file "example_environment.yml", included in the repository's top level directory, contains an example of an environment with all dependencies properly installed on a linux machine with a GPU, circa early 2024. - Step 3: Install ---------------- +^^^^^^^^^^^^^^^ -To install CDTools, run the following command from the top level directory (the directory including the setup.py file). - -.. code:: bash - - $ pip install . --no-deps - - -This will install a copy of the code, as it exists at the moment of installation. If you would prefer for changes to the code to propagate to the installed version without reinstalling, install the package in developer mode: +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 ---------------------- +^^^^^^^^^^^^^^^^^^^^^ -To ensure that the installation has worked correctly, it is recommended that you run the unit tests. After ensuring that pytest is installed, run the following command from the top level directory: +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 - -If any tests fail, make sure that you have all the noted dependencies properly installed. If you do, and things still aren't working, `send me (Abe Levitan) an email `_ and we'll get to the bottom of it. CDTools has been tested on linux and mac, on CPU, CUDA, and MPS. +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. diff --git a/docs/source/intro.rst b/docs/source/intro.rst index 3a2e8d4..22bc2c1 100644 --- a/docs/source/intro.rst +++ b/docs/source/intro.rst @@ -44,7 +44,6 @@ The high-level interface to CDTools - datasets and models - is built on a set of - functions for accessing stored data in .cxi files - plotting tools to visualize data and reconstructions - basic operations, like light propagators, needed for coherent diffraction -- tools that implement basic operations - such as light propagation - relevant to coherent diffraction. - analysis functions for assessing the quality of reconstructions diff --git a/example_environment.yml b/example_environment.yml deleted file mode 100644 index 46767a2..0000000 --- a/example_environment.yml +++ /dev/null @@ -1,181 +0,0 @@ -name: democdtoolsenv -channels: - - pytorch - - nvidia - - conda-forge - - defaults -dependencies: - - _libgcc_mutex=0.1=main - - _openmp_mutex=5.1=1_gnu - - alabaster=0.7.16=pyhd8ed1ab_0 - - babel=2.14.0=pyhd8ed1ab_0 - - blas=1.0=mkl - - brotli=1.0.9=h9c3ff4c_4 - - bzip2=1.0.8=h7b6447c_0 - - c-ares=1.19.1=h5eee18b_0 - - ca-certificates=2024.2.2=hbcca054_0 - - certifi=2024.2.2=pyhd8ed1ab_0 - - charset-normalizer=2.0.4=pyhd3eb1b0_0 - - colorama=0.4.6=pyhd8ed1ab_0 - - commonmark=0.9.1=py_0 - - contourpy=1.2.0=py311hdb19cb5_0 - - cuda-cudart=12.1.105=0 - - cuda-cupti=12.1.105=0 - - cuda-libraries=12.1.0=0 - - cuda-nvrtc=12.1.105=0 - - cuda-nvtx=12.1.105=0 - - cuda-opencl=12.3.101=0 - - cuda-runtime=12.1.0=0 - - cycler=0.12.1=pyhd8ed1ab_0 - - dbus=1.13.18=hb2f20db_0 - - docutils=0.20.1=py311h38be061_3 - - exceptiongroup=1.2.0=pyhd8ed1ab_2 - - expat=2.2.10=h9c3ff4c_0 - - ffmpeg=4.3=hf484d3e_0 - - filelock=3.13.1=py311h06a4308_0 - - fontconfig=2.14.1=hef1e5e3_0 - - fonttools=4.25.0=pyhd3eb1b0_0 - - freetype=2.12.1=h4a9f257_0 - - future=1.0.0=pyhd8ed1ab_0 - - glib=2.78.4=h6a678d5_0 - - glib-tools=2.78.4=h6a678d5_0 - - gmp=6.2.1=h295c915_3 - - gmpy2=2.1.2=py311hc9b5ff0_0 - - gnutls=3.6.15=he1e5248_0 - - gst-plugins-base=1.14.1=h6a678d5_1 - - gstreamer=1.14.1=h5eee18b_1 - - h5py=3.9.0=py311hdd6beaf_0 - - hdf5=1.12.1=h2b7332f_3 - - icu=58.2=hf484d3e_1000 - - idna=3.4=py311h06a4308_0 - - imagesize=1.4.1=pyhd8ed1ab_0 - - importlib-metadata=7.0.1=pyha770c72_0 - - iniconfig=2.0.0=pyhd8ed1ab_0 - - intel-openmp=2023.1.0=hdb19cb5_46306 - - jinja2=3.1.3=py311h06a4308_0 - - jpeg=9e=h5eee18b_1 - - kiwisolver=1.4.4=py311h6a678d5_0 - - krb5=1.20.1=h143b758_1 - - lame=3.100=h7b6447c_0 - - lcms2=2.12=h3be6417_0 - - ld_impl_linux-64=2.38=h1181459_1 - - lerc=3.0=h295c915_0 - - libclang=10.0.1=default_hb85057a_2 - - libcublas=12.1.0.26=0 - - libcufft=11.0.2.4=0 - - libcufile=1.8.1.2=0 - - libcurand=10.3.4.107=0 - - libcurl=8.5.0=h251f7ec_0 - - libcusolver=11.4.4.55=0 - - libcusparse=12.0.2.55=0 - - libdeflate=1.17=h5eee18b_1 - - libedit=3.1.20230828=h5eee18b_0 - - libev=4.33=h516909a_1 - - libevent=2.1.12=hdbd6064_1 - - libffi=3.4.4=h6a678d5_0 - - libgcc-ng=11.2.0=h1234567_1 - - libgfortran-ng=13.2.0=h69a702a_0 - - libgfortran5=13.2.0=ha4646dd_0 - - libglib=2.78.4=hdc74915_0 - - libgomp=11.2.0=h1234567_1 - - libiconv=1.16=h7f8727e_2 - - libidn2=2.3.4=h5eee18b_0 - - libjpeg-turbo=2.0.0=h9bf148f_0 - - libllvm10=10.0.1=he513fc3_3 - - libnghttp2=1.57.0=h2d74bed_0 - - libnpp=12.0.2.50=0 - - libnvjitlink=12.1.105=0 - - libnvjpeg=12.1.1.14=0 - - libpng=1.6.39=h5eee18b_0 - - libpq=12.17=hdbd6064_0 - - libssh2=1.10.0=hdbd6064_2 - - libstdcxx-ng=11.2.0=h1234567_1 - - libtasn1=4.19.0=h5eee18b_0 - - libtiff=4.5.1=h6a678d5_0 - - libunistring=0.9.10=h27cfd23_0 - - libuuid=1.41.5=h5eee18b_0 - - libwebp-base=1.3.2=h5eee18b_0 - - libxcb=1.15=h7f8727e_0 - - libxkbcommon=1.0.1=hfa300c1_0 - - libxml2=2.9.14=h74e7548_0 - - llvm-openmp=14.0.6=h9e868ea_0 - - lz4-c=1.9.4=h6a678d5_0 - - markupsafe=2.1.3=py311h5eee18b_0 - - matplotlib=3.8.0=py311h06a4308_0 - - matplotlib-base=3.8.0=py311ha02d727_0 - - mkl=2023.1.0=h213fc3f_46344 - - mkl-service=2.4.0=py311h5eee18b_1 - - mkl_fft=1.3.8=py311h5eee18b_0 - - mkl_random=1.2.4=py311hdb19cb5_0 - - mpc=1.1.0=h10f8cd9_1 - - mpfr=4.0.2=hb69a4c5_1 - - mpmath=1.3.0=py311h06a4308_0 - - munkres=1.1.4=pyh9f0ad1d_0 - - ncurses=6.4=h6a678d5_0 - - nettle=3.7.3=hbbd107a_1 - - networkx=3.1=py311h06a4308_0 - - nspr=4.35=h6a678d5_0 - - nss=3.89.1=h6a678d5_0 - - numpy=1.26.3=py311h08b1b3b_0 - - numpy-base=1.26.3=py311hf175353_0 - - openh264=2.1.1=h4ff587b_0 - - openjpeg=2.4.0=h3ad879b_0 - - openssl=3.0.13=h7f8727e_0 - - packaging=23.2=pyhd8ed1ab_0 - - pcre2=10.42=hebb0a14_0 - - pillow=10.2.0=py311h5eee18b_0 - - pip=23.3.1=py311h06a4308_0 - - platformdirs=4.2.0=pyhd8ed1ab_0 - - pluggy=1.4.0=pyhd8ed1ab_0 - - ply=3.11=py_1 - - pooch=1.8.1=pyhd8ed1ab_0 - - pygments=2.17.2=pyhd8ed1ab_0 - - pyparsing=2.4.7=pyhd8ed1ab_1 - - pyqt=5.15.10=py311h6a678d5_0 - - pyqt5-sip=12.13.0=py311h5eee18b_0 - - pytest=8.0.1=pyhd8ed1ab_1 - - python=3.11.7=h955ad1f_0 - - python-dateutil=2.8.2=pyhd8ed1ab_0 - - python_abi=3.11=2_cp311 - - pytorch=2.2.1=py3.11_cuda12.1_cudnn8.9.2_0 - - pytorch-cuda=12.1=ha16c6d3_5 - - pytorch-mutex=1.0=cuda - - pytz=2024.1=pyhd8ed1ab_0 - - pyyaml=6.0.1=py311h5eee18b_0 - - qt-main=5.15.2=h327a75a_7 - - readline=8.2=h5eee18b_0 - - requests=2.31.0=py311h06a4308_1 - - scipy=1.11.4=py311h08b1b3b_0 - - setuptools=68.2.2=py311h06a4308_0 - - sip=6.7.12=py311h6a678d5_0 - - six=1.16.0=pyh6c4a22f_0 - - snowballstemmer=2.2.0=pyhd8ed1ab_0 - - sphinx=7.2.6=pyhd8ed1ab_0 - - sphinx-argparse=0.4.0=pyhd8ed1ab_0 - - sphinx_rtd_theme=2.0.0=pyha770c72_0 - - sphinxcontrib-applehelp=1.0.8=pyhd8ed1ab_0 - - sphinxcontrib-devhelp=1.0.6=pyhd8ed1ab_0 - - sphinxcontrib-htmlhelp=2.0.5=pyhd8ed1ab_0 - - sphinxcontrib-jquery=4.1=pyhd8ed1ab_0 - - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_0 - - sphinxcontrib-qthelp=1.0.7=pyhd8ed1ab_0 - - sphinxcontrib-serializinghtml=1.1.10=pyhd8ed1ab_0 - - sqlite=3.41.2=h5eee18b_0 - - sympy=1.12=py311h06a4308_0 - - tbb=2021.8.0=hdb19cb5_0 - - tk=8.6.12=h1ccaba5_0 - - tomli=2.0.1=pyhd8ed1ab_0 - - torchaudio=2.2.1=py311_cu121 - - torchtriton=2.2.0=py311 - - torchvision=0.17.1=py311_cu121 - - tornado=6.3.3=py311h5eee18b_0 - - typing_extensions=4.9.0=py311h06a4308_1 - - tzdata=2023d=h04d1e81_0 - - urllib3=2.1.0=py311h06a4308_0 - - wheel=0.41.2=py311h06a4308_0 - - xz=5.4.5=h5eee18b_0 - - yaml=0.2.5=h7b6447c_0 - - zipp=3.17.0=pyhd8ed1ab_0 - - zlib=1.2.13=h5eee18b_0 - - zstd=1.5.5=hc292b87_0 - diff --git a/setup.py b/setup.py index 8ac2e50..4e62c0f 100644 --- a/setup.py +++ b/setup.py @@ -12,7 +12,7 @@ setuptools.setup( description="Tools for coherent diffractive imaging and ptychography", long_description=long_description, long_description_content_type="text/markdown", - url="https://github.mit.edu/scattering/CDTools.git", + url="https://github.com/cdtools-developers/cdtools", install_requires=[ "numpy>=1.0", "scipy>=1.0",