Python SDK

Examples

The SDK repository includes an examples/ directory with Jupyter notebooks demonstrating runs, sessions, attaching devices, and capabilities. The examples are organised into basics (core SDK features), EDS (spectrum and map acquisition), and deepfocus (autofocus).

Prerequisites

Python 3.9+
A reachable Semphony control server (e.g. DDEV or staging)
Install the examples extra: pip install semphony[examples] (adds Jupyter and python-dotenv)

Configuration

Copy examples/.env.example to examples/.env and set at least:

SEMPHONY_BASE_URL — control server URL
SEMPHONY_API_KEY — your API key from the Semphony dashboard

Optional variables: SEMPHONY_IMAGING_DEVICE_SLUG, SEMPHONY_DEFORMATION_DEVICE_SLUG, SEMPHONY_EDS_DEVICE_SLUG, SEMPHONY_RUN_NAME. In the notebooks, use from config import get_client to build a client from the environment.

cd semphony-python-sdk/examples
cp .env.example .env
# Edit .env with your values
jupyter notebook

Basics

Core SDK features: connecting, acquiring, stage control, centerings, geometric transformations, guardrails, and ROI operations.

Notebook	Description
acquire_100mu_image	Create a run and session, attach an imaging device, optionally define a 100 µm ROI, and acquire an image.
list_geometric_transformations	Attach an imaging device and list SharkSEM geometric transformations (beam shift, rotation, tilt correction, etc.).
list_and_reset_centerings	Enumerate available centerings (EnumCenterings) and reset the first one to zero.
save_roi	Capture a pyramidal ROI (ROI, L2, L1, L0) at the current stage position with `imaging.save_roi()`, save to disk, and load it back.
find_roi_same_session	Save an ROI, perturb the stage randomly, then navigate back using `imaging.find_roi()` with correlative matching. Available as notebook and script.
guardrails_demo	Demonstrate chamber/beam, absolute stage, and relative stage guardrails: set up guardrails, trigger violations, and inspect exceptions.
fix_beam_eds_workflow	Fix the beam to a point with `imaging.fix_beam_at()`, simulate EDS collection, then call `imaging.stop_scan()`.

EDS

EDS (Energy Dispersive Spectroscopy) examples: attach an EDS device and acquire spectra with eds.acquire_spectrum(). For combined SEM + EDS workflows (fix beam, then acquire), see the EDS capabilities doc and the basics example fix_beam_eds_workflow.

Notebook	Description
acquire_spectrum	Attach an EDS device and acquire a spectrum with `eds.acquire_spectrum()`; optionally download the file. Combine with imaging (fix beam) for point analysis.

DeepFocus

Autofocus examples using the DeepFocus neural network model. See the DeepFocus guide for full documentation on training, recalibration, and usage.

Notebook	Description
01_training_data_and_retrain	Collect training data at multiple locations and FOVs, then retrain the DeepFocus model with the SDK's training API.
02_autofocus_demo	Run iterative autofocus using a trained DeepFocus TorchScript model. Demonstrates convergence and result inspection.

Session handling tips

Notebooks — Use explicit session = run.session().start() and session.close() so you can spread work across multiple cells.

Scripts — Use the context manager with run.session() as s: for automatic start and cleanup.

Notebook style

session = run.session().start()
tescan.attach(session)
# ... cells ...
session.close()

Script style

with run.session() as s:
    tescan.attach(s)
    # ... work ...