Further improve docs layout and add unfinished ptycho models to repo

This commit is contained in:
Abe Levitan committed 2019-09-04 16:27:55 -04:00
1 parent de186592cb
commit e80bf05f25
7 files changed
+487 -52

No files matched your search

+16
View File
@@ -1,3 +1,19 @@
Examples
========
Included with the repository are a number of example scripts that demonstrate how various aspects of CDTools work. It is recommended to read through several of them before continuing to the tutorial, to get a feel for how the ptychography scripts work.
Simple Ptycho
-------------
This script runs a ptychography reconstruction using the SimplePtycho model. This model implements a straightforward transmission ptychography geometry, with no position refinement, incoherent modes, or other doodads (only a background model).
.. literalinclude:: ../../examples/simple_ptycho.py
Running this script leads to a very poor reconstruction on the example data, however depending on the dataset the model can produce reasonable results. When reading this script, note the basic workflow: First, data is read into a dataset object. Then, a model is created to match the geometry stored in the dataset, with a default initialization for all the parameters. Next, a reconstruction is run (and the progress reported out). Finally, the finished reconstruction is inspected.
Gold Balls Ptycho
-----------------
+13 -24
View File
@@ -1,3 +1,16 @@
.. toctree::
:hidden:
:maxdepth: 1
self
installation
examples
tutorial
general
datasets
models
tools/index
indices_tables
Introduction to CDTools
=======================
@@ -32,27 +45,3 @@ CDTools makes it simple to load and inspect from data stored in .cxi files using
The high-level interface to CDTools is built on a lower level "three-legged stool". This consists of tools to access stored data, tools to visualize data and reconstructions, and tools that implement basic operations relevant to coherent diffraction. All of these tools can be used directly alongside the high-level interface, when needed.
Enough blabber. If you're interested, read the docs!
Documentation Overview
======================
.. toctree::
:maxdepth: 1
installation
examples
tutorial
general
datasets
models
tools/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
+6
View File
@@ -0,0 +1,6 @@
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
+27 -16
View File
@@ -1,17 +1,19 @@
Installation
============
CDTools can be downloaded from it's `MIT github page`_, and the relevant prerequisites can be downloaded via pip, conda, or most python package managers.
Step 1: Download
----------------
.. _`MIT github page`: https://github.mit.edu/Scattering/ADCD
The source code for CDTools is hosted on it's `MIT github page`_. Access to the MIT github page can be granted to any member of the MIT community - if you are not a member, access can be arranged through a guest account on MIT's GitHub enterprise server.
.. _`MIT github page`: https://github.mit.edu/Scattering/CDTools
Access to the MIT github page can be granted to any member of the MIT community - if you are not a member, access can be arranged through a guest account on the github enterprise server
It is recommended that you clone the repository, rather than just downloading the contents, as it remains under heavy development. Cloning the repository will allow you to get access to new updates.
Prerequisites
-------------
Step 2: Install Dependencies
----------------------------
CDTools has the following prerequisites:
CDTools depends on the following packages:
* `numpy <http://www.numpy.org>`_
* `scipy <http://www.scipy.org>`_
@@ -20,30 +22,39 @@ CDTools has the following prerequisites:
* `python-dateutil <https://github.com/dateutil/dateutil/>`_
* `h5py <https://www.h5py.org/>`_
All of these can be installed via pip or conda. It is required that pytorch is ilt with MKL, as that enables FFTs. Additionally, installing pytorch with CUDA support is recommended for running any serious reconstructions with the package. The code is written to be python 2.7+ compatible, although it is only tested in python 3.
And has optional dependencies on
Finally, to run the tests, pytest is required, and to build the docs, sphinx and sphinx-argparse are required.
* `pytest <https://docs.pytest.org/>`_
* `sphinx <https://www.sphinx-doc.org/>`_
* `sphinx-argparse <https://sphinx-argparse.readthedocs.io>`_
All of these can be installed via pip or conda. Finally, CDTools is written to be python 2.7+ compatible, but is only actively tested on python 3.
*It is required that pytorch is built with MKL*, as that enables FFTs. Additionally, installing pytorch *with CUDA support* is recommended, if you intend to run any serious reconstructions with the package.
Finally, the optional depencency on pytest enables the tests to be run to confirm a successful installation. Sphinx and sphinx-argparse are only required if you plan on building the documentation.
Installation
------------
Step 3: Install
---------------
CDTools can be installed via pip, although it is recommended to install it in development mode as changes to the code are pushed to the MIT github quite frequently.
To install in developer mode, run the following command from the top level directory (the directory including the setup.py file)
To install in CDTools in developer mode (recommended, to allow any updates to be pushed immediately through your system), run the following command from the top level directory (the directory including the setup.py file)
.. code:: bash
$ pip install -e .
If you prefer to use a tool other than pip, CDTools can be installed via any other package management tool that works with a setup.py file.
Run The Tests
-------------
Step 4: Run The Tests
---------------------
To ensure that the installation has worked correctly, it is recommended to run the unit tests. After ensuring that `pytest <https://docs.pytest.org/en/latest/>`_ is installed, run the following command from the top level directory:
To ensure that the installation has worked correctly, it is recommended, although not required, that you run the unit tests. After ensuring that pytest is installed, run the following command from the top level directory:
.. code:: bash
$ pytest
If any tests fail, make sure that you have all the noted dependencies properly installed (specifically that pytorch is installed with MKL support). If so, `shoot me an email <alevitan@mit.edu>`_ and we'll get to the bottom of it.