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.10.

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]"

Narrower PEP 621 extras are available for lean deployments: control-core, control-gui, control-hardware, calibration-core, calibration-viz, calibration-notebooks, calibration-materials, and calibration-cameca.

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

Validate or recover an acquisition without starting the GUI:

pyccapt validate-config pyccapt/config.toml
pyccapt validate-hdf5 path/to/experiment.h5
pyccapt recover-run path/to/chunks path/to/recovered.h5

The repository also provides deterministic detector/property tests, golden scientific fixtures, injected failure tests, and an opt-in two-million-ion regression benchmark (PYCCAPT_RUN_BENCHMARKS=1 pytest tests/performance). CI enforces critical-contract coverage and typing, clean wheel/sdist installation, dependency and secret scanning, CodeQL, and SBOM generation.

Run calibration tutorials:

jupyter lab

Then open notebooks under pyccapt/calibration/tutorials.

Configuration

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

Reusable experiment queues are separate TOML files. Select Setup Parameters → TOML Plan → Load TOML in the main GUI, review the compact queue, then start it. Use Add / Edit / Duplicate / Save As to prepare plans without typing parameter blocks. Automatic Alignment maps each experiment's explicit sample_id to its saved Cameras position; without alignment the queue uses the current stage position. Automatic stage alignment checks the saved position and up to 16 broad probes scaled from the configured ±50 µm range. Repeatable rate jumps and coherent dense hitmap regions trigger a second pass within ±15 µm, then fine XY within ±5 µm. Probe targets stay 0.2 µm inside the original boundary. Failed searches return to saved Z/XY and retry at +100 V within the configured voltage/time limits. Fine Z approach is enabled after stable XY centring and circular-fit validation, with a total 20 µm advance limit from saved Z. Initial transfer/settling/error history is saved as meta_data/alignment_transfer.jsonl; failed pre-start moves retain their journal under data/alignment_sequences/. See Automatic Alignment for all settings.

Copy experiment_plan.example.toml and follow the experiment-plan instructions. The main window opens at 760 × 670 with monitor-aware scrolling. Advanced settings… groups detection mode, control algorithm, refresh frequency, pulse-voltage limits and K_p settings in a separate dialog. The Advanced settings label and button sit directly below the target Detection Rate input on the left. A separator below the Run Statistics detection rate precedes Electrode and Flat Test. A second line separates these buttons from the bordered Auto Alignment box containing both voltage fields and Automatic Alignment. Start sits above Stop in a separate group just above the bottom full-width separator. The parameter sources are TextBox for a single run and TOML Plan for a queue.

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.

Control owners share a consistent state contract for requests, readbacks, connection, faults and stale data. Existing device guards and hardware command sequences are preserved. Live health carries these records; each dataset saves meta_data/control_states.json for later diagnosis. See STATE_MECHANISMS.md for the implementation, evidence limits and developer instructions.

The combined Pumps/Vacuum and Gates window opens at 1280 × 640. Bordered boxes group cryo temperatures and their target control, the three venting buttons, and all six Buffer/LL/CLL chamber and pre-vacuum displays. The gauge displays keep their existing sizes and colours; the vacuum plots, Gates controls and load-lock temperature controls remain visible. Smaller monitors use scrolling as needed. Venting sits beside the Gates diagram, separated from the vacuum LCDs by open space. The Buffer Chamber Pre label has enough width to stay on one line.

Stage Control opens at 880 × 220. Its nine position readouts and speed selectors use compact widths, with less spacing around the headers and Z jog buttons. All axis controls, Home, Reference, STOP and Override Access remain visible.

Cameras uses a narrower 900 × 700 default window, with each exposure slider and value on one row. All six camera views, camera connections, sample positions and instrument monitors remain available. Camera connection rows show the serial and slot on one line; hover for the model and full state. Bottom notifications disappear after five seconds and are not restored by routine refreshes. Laser Control defaults to 980 × 650: laser settings, readouts and alignment controls sit beside the response plot, with all stage controls below. Its messages share a two-line area; scroll or hover to read longer messages. Alignment fields have space between rows and columns, and the window grows to fit readable controls when needed. Visualization opens at 980 × 570, with Hold DC, Set DC and the target voltage field on one row, and the running/stopped indicator in the top-right corner. It has two rows of spectrum controls. Its four upper rectangular panels always have identical widths and heights, including during window resizing. These windows scroll on smaller screens so controls remain accessible.

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 (mehrpad.monajem@fau.de)

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.