pyccapt 0.2.3

A Python package for atom probe control and data calibration.

PyCCAPT

PyCCAPT is a modular, FAIR-oriented Python package for atom probe tomography (APT) instrument control, data calibration, and reconstruction workflows.

It provides:

• experiment control and acquisition for APT hardware
• calibration workflows such as t0 and flight-path estimation, ROI selection, voltage and bowl correction, and ranging
• reconstruction and visualization tooling
• interoperable data export for HDF5-based workflows and common APT exchange formats

Project Scope

PyCCAPT was developed and validated on the OXCART atom probe platform and is designed to be adaptable to other APT systems through device-specific modules. Current integrations include detector backends such as Surface Concept and RoentDek, together with modular support for common laboratory hardware.

Installation

PyCCAPT requires Python >=3.9.

Recommended Quick Start (Conda)

For most users, this is the best way to install PyCCAPT:

conda create -n pyccapt python=3.11
conda activate pyccapt
python -m pip install --upgrade pip
pip install "pyccapt[full]"

If you want to work from this repository instead of PyPI:

git clone https://github.com/mmonajem/pyccapt.git
cd pyccapt
conda activate pyccapt
pip install -e ".[full]"

Predefined conda environment files are also included in the repo:

conda env create -f environment.yml
conda env create -f environment.full.yml

Other Installation Options

1. Install from PyPI:

pip install pyccapt

Optional dependency groups:

pip install "pyccapt[calibration]"
pip install "pyccapt[control]"
pip install "pyccapt[full]"

Module-specific editable installs:

pip install -e ".[control]"
pip install -e ".[calibration]"

Faster local installs

The editable (-e) step is fast; most of the time goes into resolving and downloading dependencies. A few scientific dependencies are heavy: numba pulls in llvmlite (and backtracks or builds from source if no wheel matches your Python), and tables/h5py build against the HDF5 C library when no wheel is available. The dependencies are also unpinned, so pip downloads metadata for many candidate versions to satisfy the numpy ranges that numba, tables, and h5py require.

To speed it up:

# Resolve/download in parallel with uv
uv pip install -e ".[full]"

# Or let conda provide the heavy binaries, then skip re-resolving them
conda install -c conda-forge numpy scipy pandas h5py pytables numba matplotlib
pip install -e . --no-deps

# During iterative development, when deps are already installed
pip install -e . --no-deps

See docs/installation for details.

Running PyCCAPT

Start the control application:

pyccapt

Fallback entrypoint:

python -m pyccapt.control

Run tests:

pytest -q --run-calibration
pytest -q --run-control
pytest -q

Run calibration tutorials:

jupyter lab

Then open notebooks under pyccapt/calibration/tutorials.

Configuration

Control runtime configuration is stored in pyccapt/config.toml.

Control GUI electrode labels are stored in pyccapt/control/electrode.toml:

[electrodes]
names = [
  "NiC1", # Nickel electrode
  "CuC1", # Copper electrode
]

For device toggles, prefer enabled and disabled. Legacy on and off values still work.

Control Highlights

The control stack includes the main acquisition GUI together with dedicated windows for gates, pumps and vacuum, cameras, laser, stage control, visualization, and baking. Startup reports unavailable configured ports clearly, GUI error boxes wrap long messages, and Access Override now asks for confirmation before allowing a run to proceed with missing enabled devices.

Vacuum logs are written under pyccapt/files/logs/vacuum, and baking logs are written under pyccapt/files/logs/baking/<timestamp>.

Calibration Highlights

PyCCAPT calibration workflows cover detector hit maps, FDM views, mass-spectrum calibration, bowl and voltage correction, reconstruction, and downstream visualization.

Mass calibration runs as a pipeline: initial t0/flight-path estimate → voltage correction → bowl correction → optional per-ion-index time-drift correction → adaptive per-peak residual fit. A Config preset dropdown in the data-processing notebook selects between adaptive residual (default), adaptive residual with time-drift correction (for long runs with measurable drift), and the legacy adaptive residual. A separate NIST reference fit rescales the calibrated m/c onto reference masses without re-fitting the voltage, bowl, or drift terms. See docs/CALIBRATION.md for the stages and presets.

Processed calibration datasets can be exported as HDF5, EPOS, POS, and ATO. Saved range tables can be reloaded from PyCCAPT HDF5 files as well as IVAS/LEAP range files in .rrng and .rng format.

The data-processing and visualization tutorials also expose a Load raw tdc toggle and a matching Save raw tdc toggle. When both are enabled, the raw /tdc group from the acquisition file is loaded alongside /dld and linked event-by-event via a shared event_group_id column. Every cropping step the user performs on /dld is then automatically reflected on the linked raw rows when the calibrated dataset is saved, while raw rows that never had a matching dld event are preserved untouched. See docs/Calibration_DATA_STRUCTURE.md for the on-disk schema.

The Surface Concept raw-data workflow can recover physically valid hits from pulses that fired only some delay-line channels: each delay-line axis is paired and cross-matched by time-of-flight, and recovered rows are tagged with a dlts count and a dlts_quality label. See docs/CALIBRATION.md.

The visualization helpers also include optional precipitate clustering with both Min-Max and Maximum-Separation algorithms, plus iso-surface and proxigram workflows for interface analysis. Scatter sub-sampling in the reconstruction and visualization plots is seeded, so re-running a plot on the same dataset produces the same figure.

For control part of the package you can follow the steps on documentation.

Documentation

• Full documentation: Read the Docs
• Control guide: docs/configuration
• Calibration tutorials: docs/tutorials

Google Colab notebooks currently supported:

• Data processing
• Visualization

Additional Jupyter-only widget workflows are available under pyccapt/calibration/tutorials/jupyter_files, including L_and_t0_determination.ipynb, raw_data_analysis.ipynb, cameca_raw_import.ipynb, reflectron_correction.ipynb, and tapsim_node_builder.ipynb.

Data Structures

• Control data model: pyccapt/control/DATA_STRUCTURE.md
• Calibration data model: pyccapt/calibration/DATA_STRUCTURE.md

Tutorial Dataset

Calibration tutorial data (pure aluminum), including raw and processed outputs, is available on Zenodo:

Citation

If you use PyCCAPT in your work, please cite:

@article{monajem2025pyccapt,
  title={PyCCAPT: A Python Package for Open-Source Atom Probe Instrument Control and Data Calibration},
  author={Monajem, Mehrpad and Ott, Benedict and Heimerl, Jonas and Meier, Stefan and Hommelhoff, Peter and Felfer, Peter},
  journal={Microscopy Research and Technique},
  volume={88},
  number={12},
  pages={3199--3210},
  year={2025},
  publisher={Wiley Online Library}
}

Citation metadata is also available in CITATION.cff.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development workflow and pull-request guidance.

Support

• Issues and bug reports: GitHub Issues
• Contact: Mehrpad Monajem ([e-mail])

Third-party hardware SDKs and libraries

PyCCAPT integrates with several pieces of third-party hardware and uses the corresponding vendor SDKs / Python wrappers. These remain the intellectual property of their respective owners; the files under the listed paths are either thin wrappers around vendor APIs or are adapted from vendor-provided example code, and are used here under the licence terms shipped with each SDK. Where a wrapper is largely vendor-provided code, the source file carries an attribution header.

Component	Vendor / project	Used by
Origami XPS laser CLI	NKT Photonics	pyccapt/control/nkt_photonics/origamiClassCLI.py, nktpbus_activate.py
NKTPDLL (NKTPBus protocol DLL + Python wrapper)	NKT Photonics	pyccapt/control/nkt_photonics/nktpbus_switch.py (loads the vendor's NKTPDLL.dll and bundled NKTP_DLL.py)
MCS2 stage controller SDK (smaract.ctl)	SmarAct GmbH	pyccapt/control/smaract_mcs2/
Surface Concept TDC SDK (scTDC)	Surface Concept GmbH	pyccapt/control/tdc_surface_concept/
RoentDek TDC8HP wrapper	RoentDek Handels GmbH	pyccapt/control/tdc_roentdek/
DRS digitizer library	Paul Scherrer Institute (PSI)	pyccapt/control/drs/
Thorlabs APT motor SDK	Thorlabs Inc.	pyccapt/control/thorlabs_apt/
Pfeiffer TPG362 vacuum-gauge protocol	Pfeiffer Vacuum	pyccapt/control/devices/pfeiffer_gauges.py
Edwards TIC AGC vacuum-controller protocol	Edwards Vacuum	pyccapt/control/devices/edwards_tic.py
CryoVac TIC 500 temperature-controller protocol	CryoVac GmbH	pyccapt/control/devices/initialize_devices.py (command_cryovac and friends)
MCC Universal Library (mcculw) for thermocouples	Measurement Computing	pyccapt/control/core/baking_loging.py
simple_pid PID controller	Martin Lundberg (MIT licence)	pyccapt/control/apt/apt_exp_control.py
PyQt6	Riverbank Computing (GPLv3 / commercial)	All GUI windows under pyccapt/control/gui/

To use a given component, install the vendor's SDK or Python package per their documentation (see requirements.txt / pyproject.toml for pip packages, and the vendor's installer for the proprietary SDKs that ship DLLs). A missing SDK only disables the corresponding device — the rest of PyCCAPT continues to work.

License

PyCCAPT is licensed under the GNU General Public License v3.0. See LICENSE.