Usage¶

Installation¶

From PyPI¶

The simplest way is to install Atomize from PyPI:

Linux / macOSWindows

pip3 install atomize-py

pip install atomize-py

From source (editable install)¶

To get the latest version, hack on the code, or write your own instrument modules, clone the repository and install it in editable mode (-e), so that changes to the source take effect without reinstalling:

Linux / macOSWindows

git clone https://github.com/Anatoly1010/Atomize.git
cd Atomize
pip3 install -e .

git clone https://github.com/Anatoly1010/Atomize.git
cd Atomize
pip install -e .

Optional dependencies (extras)¶

Some features need extra packages, installed via "extras" in square brackets. These work with both the PyPI and the source installs (replace . with atomize-py for a PyPI install, e.g. pip3 install atomize-py[math]):

Extra	Command	Adds
`[math]`	`pip3 install -e .[math]`	`scipy` for fitting, signal processing, and DEER analysis
`[test]`	`pip3 install -e .[test]`	`pytest` and the test dependencies for running the suite

You can combine extras: pip3 install -e .[math,test].

Note

On Windows use pip instead of pip3 in the commands above.

Isolated environment (recommended)¶

To avoid conflicts with system-wide packages, install Atomize into a virtual environment:

Linux / macOSWindows

python3 -m venv atomize-env
source atomize-env/bin/activate
pip3 install atomize-py        # or: pip3 install -e . from a source checkout

python -m venv atomize-env
atomize-env\Scripts\activate
pip install atomize-py         # or: pip install -e . from a source checkout

The environment must be activated each time before launching Atomize. As an alternative, conda can be used to manage the isolated environment.

Running¶

Once installed, run the GUI from the terminal (the same command on Linux, macOS, and Windows):

atomize

If you installed Atomize into an isolated environment, activate it first (see Isolated environment above).

General Configuration¶

In the terminal where you launched Atomize, the paths to the configuration files and some other details are displayed as follows:

SYSTEM = Linux
DATA DIRECTORY = /path/to/experimental/data/to/open/
SCRIPTS DIRECTORY = /path/to/atomize/scripts/
MAIN CONFIG PATH = ~/.config/atomize-py/
DEVICE CONFIG DIRECTORY = ~/.config/atomize-py/device_config/
EDITOR = text editor used for editing scripts

The MAIN CONFIG PATH shows a path to a general configuration file with the name main_config.ini. It should be changed at will according to the description below:

[DEFAULT]
# configure the text editor that will opened when the
# Edit button is pressed.
# "EDITOR":
editor  = subl                              ; Linux
editorW = /path/to/text_editor/on/Windows/  ; Windows

# configure the directory that will opened when Open 1D Data
# or Open 2D Data feature is used in the Liveplot tab.
# "DATA DIRECTORY":
open_dir = /path/to/experimental/data/to/open/

# configure the directory that will be opened when the
# Open Script button is pressed:
# "SCRIPTS DIRECTORY":
script_dir = /path/to/atomize/scripts/

# configure Telegram bot
telegram_bot_token =
message_id =

Instrument Modules¶

To communicate with a device one should:

modify the config file located in DEVICE CONFIG DIRECTORY of the desired device accordingly. Choose the desired protocol (rs-232, gpib, ethernet, etc.) and correct the settings of the specified protocol in accordance with device settings. A little bit more detailed information about protocol settings can be found here.
import the module or modules in your script and initialize the appropriate class. A class always has the same name as the module file. Initialization connect the desired device, if the settings are correct. For more detailed information, see documentation.

# importing of the instruments
import atomize.device_modules.Keysight_3000_Xseries as keys
import atomize.device_modules.Lakeshore331 as tc

# initialization of the instruments
dsox3034t    = keys.Keysight_3000_Xseries()
lakeshore331 = tc.Lakeshore331()

# using the instruments
name_oscilloscope = dsox3034t.oscilloscope_name()
temperature       = lakeshore331.tc_temperature('CH A')

The same idea is valid for plotting and file handling modules.

# importing of the general purpose modules
import atomize.general_modules.general_functions as general
import atomize.general_modules.csv_opener_saver as openfile

# initialization
file_handler  = openfile.Saver_Opener()
file_data     = file_handler.open_file_dialog()
header, data  = file_handler.open_1d(file_data, header=0)

# using
general.plot_1d('1D Plot', data[0], data[1],
                label='test_data', yname='Y axis', yscale='V')

Experimental Scripts¶

Python is used to write an experimental script. Examples can be found in the SCRIPTS DIRECTORY.

Workspace¶

The Main tab contains the Script Editor, Output and Queue panels. Use the script actions to open, edit and test a script, then Start to run it. Stop interrupts the current experiment and clears the queue. Add to Queue schedules scripts to run in sequence. The running script appears at the top of the Queue panel, marked Running, even when it was started with an empty queue.

Main workspace with script editor and a populated queue

The Liveplot tab displays live plots and lists them in the Plots panel. Long names in Queue and Plots are shortened in the middle; hover over an entry to see the full path or name. Right-click a list or plot to access its available actions.

Liveplot showing three green-dot plots with Show current run active and synthetic demonstration data

Output panel¶

Output shows script messages and errors. By default, it sits below the Script Editor on the Main tab. Check Shared in its header to keep the same output visible on every tab, including Liveplot and any control-center tab. Uncheck Shared to return it to Main.

Click the arrow button in the Output header to switch between bottom and right placement. The arrow points toward the next position. Drag the divider to adjust the panel size. The Shared setting, placement, and divider sizes are remembered between sessions.

Auto-scroll keeps the latest message visible, including when you move or resize Output. Scroll up to pause it and read older messages; your reading position is preserved as new messages arrive or the panel moves. Scroll back to the bottom, press Ctrl + End while Output has focus, or check Auto-scroll to follow the latest messages again. Auto-scroll starts enabled each time Atomize opens.

Additional Interactivity¶

The Output dock has the following additional features, available via its right-click menu:

clear all text from the dock;
open the local directory with the device configuration files;
print in the terminal all available instruments connected to your computer using pyvisa.

Keyboard shortcuts for the buttons on the Main tab — format Alt + key:

Shortcut	Button
`Alt + O`	Open Script
`Alt + E`	Edit Script
`Alt + U`	Update Script
`Alt + T`	Test Script
`Alt + S`	Start
`Alt + A`	Add to Queue
`Alt + H`	Help
`Alt + Q`	Quit

Use Tab / Shift+Tab to move between actions and Space to activate the focused button, including Stop.

The Script Editor dock has the following shortcuts:

Shortcut	Action
`Ctrl + G`	jump to specified line
`Ctrl + F`	search for the specified text
`Ctrl + N`	show the next occurrence
—	hidden characters can be displayed by selecting any text

Use Add to Queue to schedule the open script. Scripts added with this button are tested before being added. Execution proceeds from top to bottom.

Once a script starts successfully, it appears at the top of the Queue dock, marked Running, including when the queue was empty. Opening another script does not change this entry. You can add more scripts while it runs; they are appended below it. When the running script finishes, its entry is removed and the next waiting script starts automatically.

Drag waiting entries to change their execution order. The running entry stays first and cannot be moved or removed. The Queue dock's right-click menu provides:

Remove from Queue: remove the selected waiting entry;
Remove All: remove all waiting entries, keeping the running script and its entry.

Press Stop to interrupt the running script and clear the entire queue.

Note

In Atomize_ITC, Start also checks whether the Insys FPGA is in use, including by a RECT/AWG preview or experiment. This check applies when script tests are disabled or a previous test result is reused. A blocked launch leaves waiting scripts in the queue. Press Start again after the active acquisition finishes.

Warning

In Atomize_ITC, if the acquisition process terminates without releasing the FPGA, the computer must be rebooted before another acquisition. See pulser_close() for recovery requirements.

The Liveplot tab has the following additional features in the Plots list (available via right-click menu):

delete a selected dock with graphs;
open 1d data in csv multi-column format and plot it in a new graph dock;
open 2d data in csv format and plot it in a new graph dock.

A green dot beside a plot means it is receiving data. After 10 seconds without an update, the dot turns grey while the source remains connected; new data turns it green again. The dot remains visible when the plot is hidden and disappears when the source disconnects. Hover over a plot name to see its connection status and the time of its last data update. An idle connected plot shows Source connected, idle since HH:MM:SS.

Click Show current run to restore all connected plots (green or grey dots), including any you have hidden, and follow incoming plots from connected sources. The button is highlighted while this complete live view is active. Browsing a plot without a dot, entering Grid or hiding a live plot removes the highlight. The button is disabled when there are no connected plots.

Use Pin to keep a plot visible while browsing other plots or using Grid. Pinned plots appear in bold in the Plots list; select one and click Unpin to release it. Show current run displays only connected plots (green or grey dots): other pinned plots keep their pins but are hidden in this view.

Enable Grid to display several plots together. Click entries in the Plots list to add or remove them from the view. Pinned plots stay visible. Turn Grid off to return to the current plot plus any pinned plots.

When a new experiment starts, Grid turns off and live plots appear together automatically. Plots from finished runs leave the workspace but remain available in the Plots list. When an experiment finishes, its dots disappear, but the displayed plots remain on screen until you change the view or start a new experiment.

The buttons in each plot header control its view:

Button	Action
× (Hide plot)	Hides the plot without deleting its data. Hidden live plots continue receiving updates. Click the plot name in the Plots list to reopen it, or use Show current run to restore all connected plots (green or grey dots) together.
A (Auto range)	Fits the axes to the plotted data after zooming or panning. Available on both 1D and 2D plots.

For 2D image plots, the graph right-click Colormap menu selects the colour map and levelling — Default (standard auto-levels) or the opt-in Auto / Bipolar / Sequential modes, with Center bipolar on baseline (neutral white on a non-zero baseline) and Per-frame auto-levels for multi-frame stacks. See Colormap and levels for details.

The graph docks have the following additional features:

Feature	Action
Delete	Middle-click a curve name in the legend to remove it from the graph
Bring to Front	Left-click a curve name in the legend to move it to the top layer
Shift	Drag a curve with the mouse to shift it vertically or horizontally
Scale	Hold `Ctrl` while dragging a curve to scale it vertically
Reset	`Alt` + Left-click on a curve to reset its shift and scale to their original values
Toggle Widgets	Double-click to show/hide the cross-hair widget (for 1D plots) or the cross-section widget (for 2D plots)
Lock Position	Middle-click to lock the cross-hair or cross-section widget in its current position
Ruler	Hold `Shift` and left-drag to measure distance between two points. For 1D plots the endpoints snap to the nearest data point of the curve under the press position, and the ruler adopts that curve's color; the label shows ΔX, ΔY, and the (X, Y) of both endpoints. For 2D plots the endpoints snap to the nearest pixel center, and the label shows ΔX, ΔY, ΔZ, and the (X, Y, Z) of both endpoints. Hold `Shift + Ctrl` while dragging to use free coordinates without snapping. The ruler stays on screen independently of the cross-hair / cross-section widget — toggling that widget off leaves the ruler in place. To remove it, press `Shift` once more without dragging, or use Clear Ruler; it is also dropped automatically when the axes are transformed (FFT / log / derivative) or a new dataset is plotted.

Additional features available via right-click menu in the graph dock area:

Feature	Action
Import Data	Open 1D data in multi-column CSV format and plot it directly in the graph dock
Export Data	Save 2D data from the displayed contour plot
Hide Label	Toggle the visibility of labels on the cross-hair or cross-section widgets
Clear Ruler	Removes the current ruler overlay from the 1D or 2D plot