TEM3: event tutorial

This tutorial covers the TEM3 event mechanism, including:

1. Basics of EventManager and EventKind

2. Event queue control (enable/disable, size, retrieval)

3. Callback registration and deregistration

4. Real-machine event monitoring (optional)

Note

• Operations involving actual instrument control must follow your facility’s operating rules.

• The first part of this tutorial uses simulation (put_event) and can be explored safely.

from datetime import datetime, timedelta
import time

from PyJEM import TEM3

1. Checking EventManager and Event Types

Use TEM3.EventManager() to obtain the event management object.

queue_info()

queue_info() returns the queue state of all events as a dictionary. Each entry contains the following fields:

Field	Description
datasize	Size of data stored in the queue
maxsize	Maximum number of events the queue can hold
enabled	Whether the event is enabled

TEM3.EventKind

Available event types are enumerated in TEM3.EventKind. Representative examples are shown below.

Event Name	Description
ChgMag	Magnification change
ChgFunctionMode	Function mode change
ChangedTemStemMode	TEM/STEM mode change
ChgStageX / ChgStageY / ChgStageZ	Stage X/Y/Z position change
ChgStageTX / ChgStageTY	Stage tilt change
ChgDefocus	Defocus change

# 1) Create event manager and inspect available events
em = TEM3.EventManager()

print("Event queue summary (first 8):")
info = em.queue_info()
for i, (name, meta) in enumerate(info.items()):
    if i >= 8:
        break
    print(f"{name}: size={meta['datasize']} maxsize={meta['maxsize']} enabled={meta['enabled']}")

print("\nSample event names:")
print([e.name for e in list(TEM3.EventKind)[:10]])

Event queue summary (first 8):
ChangeSpectrumMode: size=0 maxsize=10 enabled=True
ChangedAcdHeatEnd: size=0 maxsize=10 enabled=True
ChangedAcdHeatStart: size=0 maxsize=10 enabled=True
ChangedBakeOutEnd: size=0 maxsize=10 enabled=True
ChangedBakeOutStart: size=0 maxsize=10 enabled=True
ChangedGIFMode: size=0 maxsize=10 enabled=True
ChangedHomePositionOfDeflector: size=0 maxsize=10 enabled=True
ChangedRelativeValueOfDeflector: size=0 maxsize=10 enabled=True

Sample event names:
['ChangeSpectrumMode', 'ChangedAcdHeatEnd', 'ChangedAcdHeatStart', 'ChangedBakeOutEnd', 'ChangedBakeOutStart', 'ChangedGIFMode', 'ChangedHomePositionOfDeflector', 'ChangedRelativeValueOfDeflector', 'ChangedSaafLimitStatus', 'ChangedSaafMode']

2. Registering Callbacks

Register, list, and deregister functions to be called when an event occurs.

The following cell demonstrates the full cycle of registering, invoking, and deregistering a callback for the ChgMag event.

Operation	Method	Description
Register	regist_method(event_name, func, key)	Register a callback function with a key
List	method_list(event_name)	Retrieve the list of registered callbacks
Deregister	unregist_method(event_name, key)	Remove a callback by key

event_name = TEM3.EventKind.ChgMag.name

def on_chg_mag(*args):
    print("[callback] ChgMag received:", args)

# Register callback
em.regist_method(event_name, on_chg_mag, "demo_chg_mag")
print("registered callbacks:", len(em.method_list(event_name)))

# Simulate callback dispatch for tutorial purpose
for cb in em.method_list(event_name):
    cb({"from": "tutorial", "at": datetime.now().isoformat()})

# Unregister callback
em.unregist_method(event_name, "demo_chg_mag")
print("callbacks after unregist:", len(em.method_list(event_name)))

registered callbacks: 1
[callback] ChgMag received: ({'from': 'tutorial', 'at': '2026-03-23T14:47:27.028220'},)
callbacks after unregist: 0

3. Monitoring Real-Machine Events (Hardware Required)

This section requires a live TEM3 connection.
Once connected, changing magnification or other settings on the instrument will enqueue the corresponding events.

The following cell connects to TEM3 and monitors multiple events for 20 seconds.
Operating the instrument (magnification, stage, mode, etc.) will record the corresponding events in the queue.

Events monitored:

Event Name	Triggering Operation
ChgMag	Magnification change
ChgFunctionMode	Function mode change
ChangedTemStemMode	TEM/STEM mode switch
ChgStageX / ChgStageY / ChgStageZ	Stage position change
ChgStageTX / ChgStageTY	Stage tilt change
ChgDefocus	Defocus change

After monitoring ends, a summary of total event count, per-type counts, and a timeline of the first events is printed.

# Real-machine event monitor: log what happened
from collections import Counter

connected = TEM3.connect()
print("TEM3 connected:", connected)

if not connected:
    print("Skip monitoring because TEM3 is not connected.")
else:
    em = TEM3.EventManager()

    # Add or remove events to match your operation target
    watch_events = [
        TEM3.EventKind.ChgMag.name,
        TEM3.EventKind.ChgFunctionMode.name,
        TEM3.EventKind.ChangedTemStemMode.name,
        TEM3.EventKind.ChgStageX.name,
        TEM3.EventKind.ChgStageY.name,
        TEM3.EventKind.ChgStageZ.name,
        TEM3.EventKind.ChgStageTX.name,
        TEM3.EventKind.ChgStageTY.name,
        TEM3.EventKind.ChgDefocus.name,
    ]

    for ev_name in watch_events:
        em.set_enabled(ev_name, True)
        em.set_maxsize(ev_name, 100)

    monitor_seconds = 20
    print(f"Monitoring {len(watch_events)} events for {monitor_seconds} seconds...")
    print("Operate TEM now (change mag/stage/mode, etc.).")

    end = datetime.now() + timedelta(seconds=monitor_seconds)
    event_log = []

    while datetime.now() < end:
        for ev_name in watch_events:
            ev = em.get_event(ev_name)
            if ev is not None:
                event_log.append(ev)
                print(f"[{ev.time}] {ev.name}: {ev.data}")
        time.sleep(0.1)

    print("\n--- Summary ---")
    print("total events:", len(event_log))

    if event_log:
        counts = Counter(e.name for e in event_log)
        print("event counts:")
        for name, count in counts.most_common():
            print(f"  {name}: {count}")

        print("\nfirst 10 events (timeline):")
        for e in event_log[:10]:
            print(f"  {e.time} | {e.name} | {e.data}")
    else:
        print("No events captured.")

TEM3 connected: True
Monitoring 9 events for 20 seconds...
Operate TEM now (change mag/stage/mode, etc.).
[2026-04-03 15:37:08.120401] ChgMag: (2000000, 'X', 'x2.0M')
[2026-04-03 15:40:59.074381] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:37:09.459789] ChgMag: (2500000, 'X', 'x2.5M')
[2026-04-03 15:41:00.419068] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:37:13.635347] ChgMag: (2000000, 'X', 'x2.0M')
[2026-04-03 15:41:01.972621] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:37:15.454976] ChgMag: (1500000, 'X', 'x1.5M')
[2026-04-03 15:41:03.532489] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:51.466562] ChgMag: (20000, 'X', 'x20k')
[2026-04-03 15:41:05.061735] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:51.950044] ChgMag: (25000, 'X', 'x25k')
[2026-04-03 15:41:06.621841] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:53.273855] ChgMag: (30000, 'X', 'x30k')
[2026-04-03 15:41:08.183915] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:54.640979] ChgMag: (40000, 'X', 'x40k')
[2026-04-03 15:41:09.785154] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:56.187460] ChgMag: (50000, 'X', 'x50k')
[2026-04-03 15:41:11.302722] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:57.564335] ChgMag: (60000, 'X', 'x60k')
[2026-04-03 15:41:12.625081] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:40:59.074381] ChgMag: (80000, 'X', 'x80k')
[2026-04-03 15:41:00.419068] ChgMag: (100000, 'X', 'x100k')
[2026-04-03 15:41:01.972621] ChgMag: (120000, 'X', 'x120k')
[2026-04-03 15:41:03.532489] ChgMag: (150000, 'X', 'x150k')
[2026-04-03 15:41:05.061735] ChgMag: (200000, 'X', 'x200k')
[2026-04-03 15:41:06.621841] ChgMag: (250000, 'X', 'x250k')
[2026-04-03 15:41:08.183915] ChgMag: (300000, 'X', 'x300k')
[2026-04-03 15:41:09.785154] ChgMag: (400000, 'X', 'x400k')
[2026-04-03 15:41:11.302722] ChgMag: (500000, 'X', 'x500k')
[2026-04-03 15:41:12.625081] ChgMag: (600000, 'X', 'x600k')
[2026-04-03 15:41:21.429149] ChgMag: (20000, 'X', 'x20k')
[2026-04-03 15:41:21.429149] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:21.916072] ChgMag: (25000, 'X', 'x25k')
[2026-04-03 15:41:21.916072] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:23.242699] ChgMag: (30000, 'X', 'x30k')
[2026-04-03 15:41:23.242699] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:24.813252] ChgMag: (40000, 'X', 'x40k')
[2026-04-03 15:41:24.813252] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:26.195036] ChgMag: (50000, 'X', 'x50k')
[2026-04-03 15:41:26.195036] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:27.716587] ChgMag: (60000, 'X', 'x60k')
[2026-04-03 15:41:27.716587] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:29.101735] ChgMag: (80000, 'X', 'x80k')
[2026-04-03 15:41:29.101735] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:30.610721] ChgMag: (100000, 'X', 'x100k')
[2026-04-03 15:41:30.610721] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:32.157029] ChgMag: (120000, 'X', 'x120k')
[2026-04-03 15:41:32.157029] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:33.732630] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:33.732630] ChgMag: (150000, 'X', 'x150k')
[2026-04-03 15:41:35.304930] ChgMag: (200000, 'X', 'x200k')
[2026-04-03 15:41:35.304930] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:36.870486] ChgMag: (250000, 'X', 'x250k')
[2026-04-03 15:41:36.870486] ChgFunctionMode: (2, 'SMMAG')
[2026-04-03 15:41:38.446246] ChgMag: (300000, 'X', 'x300k')
[2026-04-03 15:41:38.446246] ChgFunctionMode: (2, 'SMMAG')

--- Summary ---
total events: 56
event counts:
  ChgMag: 33
  ChgFunctionMode: 23

first 10 events (timeline):
  2026-04-03 15:37:08.120401 | ChgMag | (2000000, 'X', 'x2.0M')
  2026-04-03 15:40:59.074381 | ChgFunctionMode | (2, 'SMMAG')
  2026-04-03 15:37:09.459789 | ChgMag | (2500000, 'X', 'x2.5M')
  2026-04-03 15:41:00.419068 | ChgFunctionMode | (2, 'SMMAG')
  2026-04-03 15:37:13.635347 | ChgMag | (2000000, 'X', 'x2.0M')
  2026-04-03 15:41:01.972621 | ChgFunctionMode | (2, 'SMMAG')
  2026-04-03 15:37:15.454976 | ChgMag | (1500000, 'X', 'x1.5M')
  2026-04-03 15:41:03.532489 | ChgFunctionMode | (2, 'SMMAG')
  2026-04-03 15:40:51.466562 | ChgMag | (20000, 'X', 'x20k')
  2026-04-03 15:41:05.061735 | ChgFunctionMode | (2, 'SMMAG')

Callback Monitoring for ChgMag Events

Register a callback function with regist_method and monitor the ChgMag (magnification change) event for 15 seconds.
Unlike a polling loop, the callback is invoked immediately when an event occurs.

Step	Method	Description
Register callback	regist_method(event_name, func, key)	Register a function to be called on event
Wait	time.sleep(15)	Wait 15 seconds while TEM events may occur
Deregister callback	unregist_method(event_name, key)	Remove the callback after monitoring ends

connected = TEM3.connect()
print("TEM3 connected:", connected)

if not connected:
    print("Skip monitoring because TEM3 is not connected.")
else:
    watch_event = TEM3.EventKind.ChgMag.name
    em.set_enabled(watch_event, True)
    em.set_maxsize(watch_event, 20)

    captured = []

    def on_chg_mag(*args):
        captured.append(args)
        print(f"[{datetime.now().isoformat()}] [ChgMag]", args)

    em.regist_method(watch_event, on_chg_mag, "monitor_chg_mag")
    print("Monitoring for 15 seconds via callback...")
    print("Try changing magnification on TEM during this period.")

    time.sleep(15)

    em.unregist_method(watch_event, "monitor_chg_mag")
    print("captured count:", len(captured))

TEM3 connected: True
Monitoring for 15 seconds via callback...
Try changing magnification on TEM during this period.
[2026-04-03T15:40:51.466562] [ChgMag] (20000, 'X', 'x20k')
[2026-04-03T15:40:51.950044] [ChgMag] (25000, 'X', 'x25k')
[2026-04-03T15:40:53.273855] [ChgMag] (30000, 'X', 'x30k')
[2026-04-03T15:40:54.640979] [ChgMag] (40000, 'X', 'x40k')
[2026-04-03T15:40:56.187460] [ChgMag] (50000, 'X', 'x50k')
[2026-04-03T15:40:57.564335] [ChgMag] (60000, 'X', 'x60k')
[2026-04-03T15:40:59.074381] [ChgMag] (80000, 'X', 'x80k')
[2026-04-03T15:41:00.419068] [ChgMag] (100000, 'X', 'x100k')
captured count: 8

Appendix: Manipulating the Event Queue (Offline)

For offline testing, use put_event to inject simulated events and verify queue behavior.

event_name = TEM3.EventKind.ChgMag.name

# Configure queue behavior
em.set_enabled(event_name, True)
em.set_maxsize(event_name, 3)

# Put 5 events into queue (maxsize=3 -> old events are dropped)
for i in range(5):
    em.put_event(event_name, {"sim_index": i, "note": "simulated event"})

print("qsize after put:", em.qsize(event_name))

# Drain queue
print("drain queue:")
while em.qsize(event_name) > 0:
    ev = em.get_event(event_name)
    print(ev)

qsize after put: 3
drain queue:
<Event name=ChgMag data={'sim_index': 2, 'note': 'simulated event'} time=2026-03-23 14:46:48.972974>
<Event name=ChgMag data={'sim_index': 3, 'note': 'simulated event'} time=2026-03-23 14:46:48.972974>
<Event name=ChgMag data={'sim_index': 4, 'note': 'simulated event'} time=2026-03-23 14:46:48.972974>