diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 000000000..e58d31d31 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,148 @@ +# This file describes how to cite the quantem software (schema: https://citation-file-format.github.io). +# It is maintained by hand. Unlike Zenodo's auto-generated author list, this file will not +# pick up new contributors on its own: update `authors`, `version`, and `date-released` +# with each release. +message: >- + If you use quantem in your research, please cite this software using the metadata below, + along with any relevant method papers listed in the README. +title: "quantem: quantitative electron microscopy analysis toolkit" +abstract: >- + quantem is a quantitative electron microscopy data analysis toolkit built on PyTorch, + providing tools for analyzing many kinds of transmission electron microscopy data. +type: software +authors: + - given-names: "Arthur R. C." + family-names: McCray + orcid: "0000-0001-6077-4698" + affiliation: "Stanford University" + - given-names: Colin + family-names: Ophus + orcid: "0000-0003-2348-8558" + affiliation: "Stanford University" + - given-names: "Stephanie M." + family-names: Ribet + orcid: "0000-0002-7117-066X" + affiliation: "Lawrence Berkeley National Laboratory" + - given-names: Georgios + family-names: Varnavides + orcid: "0000-0001-8338-3323" + affiliation: "Delft University of Technology" + - given-names: Cedric + family-names: Lim + orcid: "0009-0000-1319-5175" + affiliation: "Stanford University" + - given-names: Karen + family-names: Ehrhardt + # orcid: "" + # affiliation: "" + - given-names: Matthew + family-names: Feickert + # orcid: "" + # affiliation: "" + - given-names: Carter + family-names: Francis + # orcid: "" + # affiliation: "" + - given-names: "Sangjoon Bob" + family-names: Lee + # orcid: "" + # affiliation: "" + - given-names: Darshan + family-names: Mali + # orcid: "" + # affiliation: "" + - given-names: Nicholas + family-names: Marchese + # orcid: "" + # affiliation: "" + - given-names: Will + family-names: Millsaps + # orcid: "" + # affiliation: "" +doi: 10.5281/zenodo.18642593 # concept DOI (always resolves to the latest release) +license: MIT +repository-code: "https://github.com/electronmicroscopy/quantem" +url: "https://github.com/electronmicroscopy/quantem" +keywords: + - electron microscopy + - 4D-STEM + - ptychography + - tomography + - TEM + - STEM + - PyTorch +references: + - type: article + title: "Deep generative priors for robust and efficient electron ptychography" + authors: + - given-names: "Arthur R. C." + family-names: McCray + - given-names: "Stephanie M." + family-names: Ribet + - given-names: Georgios + family-names: Varnavides + - given-names: Colin + family-names: Ophus + year: 2025 + url: "https://arxiv.org/abs/2511.07795" + notes: "arXiv:2511.07795" + - type: article + title: "Relaxing Direct Ptychography Sampling Requirements via Parallax Imaging Insights" + authors: + - given-names: Georgios + family-names: Varnavides + - given-names: "Julie Marie" + family-names: Bekkevold + - given-names: "Stephanie M." + family-names: Ribet + - given-names: "Mary C." + family-names: Scott + - given-names: Lewys + family-names: Jones + - given-names: Colin + family-names: Ophus + journal: "Microscopy and Microanalysis" + volume: 32 + issue: 2 + year: 2026 + doi: 10.1093/mam/ozaf139 + - type: article + title: >- + Missing Wedge Inpainting and Joint Alignment in Electron Tomography through + Implicit Neural Representations + authors: + - given-names: Cedric + family-names: Lim + - given-names: Corneel + family-names: Casert + - given-names: "Arthur R. C." + family-names: McCray + - given-names: Serin + family-names: Lee + - given-names: Andrew + family-names: Barnum + - given-names: Jennifer + family-names: Dionne + - given-names: Colin + family-names: Ophus + year: 2025 + url: "https://arxiv.org/abs/2512.08113" + notes: "arXiv:2512.08113" + - type: article + title: >- + Multi-angle Precession Electron Diffraction (MAPED): A Versatile Approach to + 4D-STEM Precession + authors: + - given-names: "Stephanie M." + family-names: Ribet + - given-names: Rohan + family-names: Dhall + - given-names: Colin + family-names: Ophus + - given-names: "Karen C." + family-names: Bustillo + journal: "Microscopy and Microanalysis" + volume: 31 + issue: 6 + year: 2025 + doi: 10.1093/mam/ozaf103 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..670ce9f6c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,49 @@ +# Contributing to quantem + +Thanks for your interest in improving quantem! Bug reports, feature requests, and pull requests are all welcome. + +## Contribution workflow + +- Open an [issue](https://github.com/electronmicroscopy/quantem/issues) to report a bug or discuss a feature before starting larger work. +- Fork the repository and create a feature branch off the appropriate base branch (`dev` for most work or ask a maintainer if you are unsure). +- Make your changes, keeping them formatted and linted (see below), and add tests where it makes sense. +- Push to your fork and open a pull request against `electronmicroscopy/quantem`. + +## Development setup + +We use [uv](https://docs.astral.sh/uv/) to manage the package. + +Getting started: + +- [install uv](https://docs.astral.sh/uv/getting-started/installation/) +- `git clone` the repo and `cd` into the directory +- run `uv sync` to install all the dependencies in an editable environment +- run `uv sync --all-packages` to also install `quantem.widget` (optional) + +For widget developers (requires [Node.js](https://nodejs.org/)): + +- `cd widget && npm install` to install JS dependencies +- `npm run build` to build the widget +- `npm run dev` to watch for changes during development + +The following will set up the pre-commit and [ruff](https://github.com/astral-sh/ruff) for linting and formatting. These commands only need to be run once when first setting up your dev environment: + +- `uv tool install pre-commit` +- `uv tool install ruff` +- `pre-commit install` + +Once these have been installed, the `.pre-commit-config.yaml` file will be run when trying to `git commit`. Errors that cannot be auto-fixed will be listed and you will have to resolve them before committing. In many cases you will get a warning that the formatting and auto-fixes have been applied; you can stage the changes for commit with `git add -u` and the pre-commit should allow you to commit your changes. + +Dependency management: + +- use `uv add package_name` to add dependencies +- use `uv remove package_name` to remove dependencies +- use `uv add dev_package_name --dev` to add a dev dependency, i.e. that devs need (e.g. pytest) but you don't want shipped to users +- use `uv pip install testing_package_name` to install a package you think you might need, but don't want to add to dependencies just yet + +Running python/scripts in environment: + +- use `uv run python`, `uv run jupyterlab` etc. to automatically activate the environment and run your command +- alternatively use `source .venv/bin/activate` to explicitly activate environment and use `python`, `jupyterlab` etc. as usual + - note that if you're using an IDE like VS Code, it probably activates the environment automatically + diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 993a6a034..32df792e5 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,38 +1,47 @@ -# Developer Instructions +# Contributors -We use [uv](https://docs.astral.sh/uv/) to manage the package. +``quantem`` is developed by researchers and students across the electron microscopy community. +Thank you to everyone who has contributed code, ideas, bug reports, and tutorials. -Getting started: +Contributions are broken down by module: -- [install uv](https://docs.astral.sh/uv/getting-started/installation/) -- `git clone` the repo and `cd` into the directory -- run `uv sync` to install all the dependencies in an editable environment -- run `uv sync --all-packages` to also install `quantem.widget` (optional) +## Core +- [Georgios Varnavides](https://github.com/gvarnavi) +- [Arthur McCray](https://github.com/arthurmccray) +- [Colin Ophus](https://github.com/cophus) +- [Stephanie Ribet](https://github.com/smribet) +- [Cedric Lim](https://github.com/cedriclim1) +- [Matthew Feickert](https://github.com/matthewfeickert) -For widget developers (requires [Node.js](https://nodejs.org/)): +## Diffraction +- [Karen Ehrhardt](https://github.com/ehrhardtkm) +- [Colin Ophus](https://github.com/cophus) +- [Nicholas Marchese](https://github.com/NJMarchese) -- `cd widget && npm install` to install JS dependencies -- `npm run build` to build the widget -- `npm run dev` to watch for changes during development +## Diffractive Imaging +- [Arthur McCray](https://github.com/arthurmccray) +- [Georgios Varnavides](https://github.com/gvarnavi) +- [Stephanie Ribet](https://github.com/smribet) +- [Sangjoon Bob Lee](https://github.com/bobleesj) -The following will set up the pre-commit and [ruff](https://github.com/astral-sh/ruff) for linting and formatting. These commands only need to be run once when first setting up your dev environment: +## Imaging +- [Colin Ophus](https://github.com/cophus) +- [Sangjoon Bob Lee](https://github.com/bobleesj) +- [Will Millsaps](https://github.com/wwmills) +- [Darshan Mali](https://github.com/darshan-mali) -- `uv tool install pre-commit` -- `uv tool install ruff` -- `pre-commit install` +## Spectroscopy +- [Colin Ophus](https://github.com/cophus) +- [Stephanie Ribet](https://github.com/smribet) -Once these have been installed, the `.pre-commit-config.yaml` file will be run when trying to `git commit`. Errors that cannot be auto-fixed will be listed and you will have to resolve them before committing. In many cases you will get a warning that the formatting and auto-fixes have been applied; you can stage the changes for commit with `git add -u` and the pre-commit should allow you to commit your changes. +## Tomography +- [Cedric Lim](https://github.com/cedriclim1) +- [Arthur McCray](https://github.com/arthurmccray) -Dependency management: +For the complete, always-up-to-date list of everyone who has contributed, +see the [GitHub contributors graph](https://github.com/electronmicroscopy/quantem/graphs/contributors). -- use `uv add package_name` to add dependencies -- use `uv remove package_name` to remove dependencies -- use `uv add dev_package_name --dev` to add a dev dependency, i.e. that devs need (e.g. pytest) but you don't want shipped to users -- use `uv pip install testing_package_name` to install a package you think you might need, but don't want to add to dependencies just yet +--- -Running python/scripts in environment: - -- use `uv run python`, `uv run jupyterlab` etc. to automatically activate the environment and run your command -- alternatively use `source .venv/bin/activate` to explicitly activate environment and use `python`, `jupyterlab` etc. as usual - - note that if you're using an IDE like VS Code, it probably activates the environment automatically - +This list is maintained by hand and grouped by contribution history. If your name is missing, +listed incorrectly, or you would like it shown differently, please open a pull request or issue. \ No newline at end of file diff --git a/README.md b/README.md index f08b9ed06..489291c0b 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,59 @@ +quantem_logo + # quantem -This is the home repository for the quantitative electron microscopy (quantem) data analysis toolkit. +[![PyPI version](https://img.shields.io/pypi/v/quantem.svg)](https://pypi.org/project/quantem/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18642593-blue)](https://doi.org/10.5281/zenodo.18642593) + +``quantem`` is a quantitative electron microscopy data analysis toolkit built on [PyTorch](https://pytorch.org/). It brings together tools for reconstructing or analyzing a wide range of transmission electron microscopy (TEM) techniques, including nanobeam diffraction, phase retrieval, real-space imaging and tomography, spectroscopy, and related analyses within a consistent, GPU-accelerated API. + +## Capabilities + +- **Ptychographic phase retrieval**: ML-enabled iterative reconstruction ([McCray et al., 2025](https://arxiv.org/abs/2511.07795)) and direct methods ([Varnavides et al., 2026](https://doi.org/10.1093/mam/ozaf139)). +- **Tomography**: fast and accurate HAADF tomography using implicit representations ([Lim et al., 2025](https://arxiv.org/abs/2512.08113)). +- **Imaging**: drift correction and lattice analysis for (S)TEM images. +- **Data structures & I/O**: a unified `Dataset` hierarchy that reads common electron-microscopy formats and serializes to [Zarr](https://zarr.dev/). +- **Visualization**: publication-quality figures with perceptually-uniform colormaps. +- **GPU-accelerated & ML-ready**: a PyTorch backend with neural object representations and multi-GPU / multi-node reconstruction. +- **Spectroscopy**: GPU-accelerated spectra fitting for EDS and EELS, under development. +- **Diffraction**: multi-angle precession electron diffraction (MAPED), under development ([Ribet et al., 2025](https://doi.org/10.1093/mam/ozaf103)). + +## Installation + +quantem is available on the [Python Package Index](https://pypi.org/project/quantem/) and requires Python 3.11+: + +```bash +pip install quantem +``` + +This installs PyTorch as a dependency. For CUDA-specific PyTorch builds, follow the [official PyTorch install guide](https://pytorch.org/get-started/locally/) for your platform first. + +To install from source or set up a development environment, see [CONTRIBUTING.md](CONTRIBUTING.md). A local install can also be used to access the newest development features of individual modules that exist on feature branches prior to PRs. + +### GPU acceleration + +For custom CUDA kernels that accelerate tomography, ptychography, and io behind a torch-native API, see the companion [quantem-cuda](https://github.com/electronmicroscopy/quantem-cuda) package (optional, more coming soon). + +## Getting started + +The [quantem-tutorials](https://github.com/electronmicroscopy/quantem-tutorials) repository contains Jupyter notebooks that walk through the main workflows for each module. + +## Citing + +If you use quantem in your research, please cite this repository as well as the relevant paper(s) for any module(s) that you used: + +- **quantem (software)**: please cite the version you used. Ready to use citations can be copied from the [Zenodo record](https://doi.org/10.5281/zenodo.18642593), or from the "Cite this repository" button on [GitHub](https://github.com/electronmicroscopy/quantem). -## Installation Instructions +- **Iterative ptychography**: McCray, A. R. C., Ribet, S. M., Varnavides, G., & Ophus, C. (2025). *Deep generative priors for robust and efficient electron ptychography.* arXiv:2511.07795. https://arxiv.org/abs/2511.07795 +- **Direct ptychography**: Varnavides, G., Bekkevold, J. M., Ribet, S. M., Scott, M. C., Jones, L., & Ophus, C. (2026). *Relaxing Direct Ptychography Sampling Requirements via Parallax Imaging Insights.* Microscopy and Microanalysis, 32(2), ozaf139. https://doi.org/10.1093/mam/ozaf139 +- **Electron tomography (implicit neural representations)**: Lim, C., Casert, C., McCray, A. R. C., Lee, S., Barnum, A., Dionne, J., & Ophus, C. (2025). *Missing Wedge Inpainting and Joint Alignment in Electron Tomography through Implicit Neural Representations.* arXiv:2512.08113. https://arxiv.org/abs/2512.08113 +- **Multi-angle precession electron diffraction (MAPED)**: Ribet, S. M., Dhall, R., Ophus, C., & Bustillo, K. C. (2025). *Multi-angle Precession Electron Diffraction (MAPED): A Versatile Approach to 4D-STEM Precession.* Microscopy and Microanalysis, 31(6), ozaf103. https://doi.org/10.1093/mam/ozaf103 -The package is available on the Python Package Index (PyPi), as [quantem](https://pypi.org/project/quantem/). -You can install it using `pip install quantem`. +## Contributing -For a developer install, please refer to [CONTRIBUTORS.md](CONTRIBUTORS.md). +Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup and workflow, and [CONTRIBUTORS.md](CONTRIBUTORS.md) for the people who have built quantem. ## License diff --git a/media/.placeholder b/media/.placeholder deleted file mode 100644 index e69de29bb..000000000 diff --git a/media/quantem_logo_53.png b/media/quantem_logo_53.png new file mode 100644 index 000000000..83dab2242 Binary files /dev/null and b/media/quantem_logo_53.png differ