Quickstart

Quickstart#

Here, we provide a quick walkthough of how to get started with PtyRAD.

Step-by-step guide#

1. Create and Activate a clean Python Environment#

First, create and activate a new conda environment (ptyrad) with Python > 3.10:

conda create -n ptyrad python=3.12
conda activate ptyrad

💡 Note: After activating the environment, your terminal prompt should show (ptyrad) at the beginning, indicating that the environment is active.

2. Install PtyRAD into the (ptyrad) Environment#

Then install PtyRAD in the activated (ptyrad) environment using:

pip install ptyrad

If you’re using Windows with NVIDIA CUDA GPU, you will also need to install the GPU version of PyTorch with:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 --force-reinstall

PtyRAD can also be installed via conda. For detailed instructions on installing PtyRAD on different machines or pinning specific CUDA versions, see the installation guide.

3. Create a Starter Kit Folder Structure#

This starter kit folder ptyrad/ contains examples and templates params files, useful scripts and notebooks.

ptyrad init

# Folder structure

ptyrad/
├── data/             # Default directory for storing your 4D-STEM datasets
├── notebooks/        # Jupyter notebooks for common workflows and interactive analyses
├── output/           # Default directory where reconstruction results are saved
├── params/
│   ├── examples/     # Ready-to-run parameter files for included demo datasets (e.g., tBL_WSe2, PSO)
│   ├── templates/    # Templates ranging from minimal setups to full API reference
│   └── walkthrough/  # Tutorial-driven parameter files designed to guide you through specific features (e.g., multislice, advanced constraints, and hyperparameter tuning)
└── scripts/          # Utility scripts for fetching demo data and submitting batch jobs on computing clusters

4. Download the Demo Data#

We provide a helper script to automatically fetch the example datasets, and place it in the correct ptyrad/data/ folder:

cd ptyrad
python ./scripts/download_demo_data.py

After downloading and unzipping, the folder structure should look like this:

# Folder structure

ptyrad/
├── data/ 
│   ├── PSO/
│   └── tBL_WSe2/
├── notebooks/
├── output/   
├── params/
└── scripts/

5. Run the Demo Reconstructions#

Please check the following before running the demo:

  1. Demo datasets are downloaded and placed to the correct location under ptyrad/data/

  2. (ptyrad) environment is created and activated (in VS Code it’s the “Select Kernel”)

Now you’re ready to run a quick demo using one of two interfaces:

  • Interactive Jupyter interface (Recommended)

    Run the ptyrad/notebooks/run_ptyrad.ipynb in VS code, or run the following command in terminal:

    jupyter notebook ./tutorials/run_ptyrad.ipynb # Or direcly open it in VS code

  • Command-line interface (like your Miniforge Prompt terminal)

    # Assume working directory is at `ptyrad/` and (ptyrad) environment is activated
ptyrad run "params/examples/tBL_WSe2.yaml"
Contents