4DSTEM Studio

4DSTEM Studio · Help

Troubleshooting

Applies to 4DSTEM Studio 5.4 and later

The app says what is wrong in its own words. This page lists those messages and what to do about each.

A file does not open

The app refuses the file and names a reason. The reader never guesses. The message says what it found and what it expected; File formats explains the usual ones.

"Could not open …". The file is missing, or macOS did not let the app read it. Check that the file is where you picked it, and open it again with Open Dataset… (⌘O).

"Vendor data is truncated". The file is shorter than its header says, which usually means a copy that did not finish. Copy the file again from the microscope computer.

"… is no longer reachable: its disk was disconnected". The dataset is on an external disk or a network share that went away. Reconnect it and reopen the dataset.

"Dataset rank … is not supported". The HDF5 dataset you chose is not a 4D-STEM scan. The app expects a dataset with three or four dimensions.

The app asks for a folder

Merlin and EMPAD data, and session files, sit in more than one file. macOS may give the app only the file you picked. The app then shows an Open panel on the dataset's folder: click Open there. It asks once and remembers the folder.

If the dataset's folder cannot be written to, for example on a read-only share, use Change Session File… to keep the session somewhere else. See Sessions.

The dataset is large or the app is slow

"More than half of this Mac's memory; other apps may slow down." The selection you are about to load is large for this Mac. In Open with Options…, crop the scan or raise the Bin factor until This selection fits, or turn Keep in memory off.

Keep in memory is dimmed. The dataset would not fit; the caption under the switch says by how much. Crop or bin, or work from the file.

Everything works but is slow. With Keep in memory off, each analysis reads the file in pieces. A dataset on a network share or a slow external disk is read at that disk's speed: copy it to the internal disk. Large datasets has the details.

The calibration says "Not quantitative"

The Prepare workspace lists each part of the calibration with its state: Not set, From file, Measured, Manual, From session or Not quantitative. The verdict underneath reads Quantitative, or "Not quantitative — still needed:" followed by the parts that are in the way.

The verdict or the row says What to do
A part is Not set Measure it in Prepare, or type the value if you know it. The voltage and the pixel sizes come from the file when it carries them.
Origin: "Spot pattern" or "Centre of mass scattered" The strong disks of a crystal pull the centre of mass off the beam. Run Detect All Disks in Bragg Disks, then Origin from Bragg Peaks in Prepare. Check afterwards that the Bragg vector map shows sharp spots.
Origin: "Beam stop over the direct beam" Set the origin method to Friedel when the row suggests it; otherwise set the origin by hand.
Origin: "exceeds probe radius; recalibrate before quantitative use" The fit moved further than the probe is wide. Run Calibrate Origin again after checking the probe radius.
Origin: "Window pull … (the window is mostly background…)" The fit window holds little signal. The maps are fine for finding features; do not quote their numbers.

You can still work

A dataset that is not quantitative can still be imaged and mapped. The results are marked, and their numbers are in pixels. Use them to find features, and calibrate before you report values.

Disk detection finds too few or too many disks

Tune on single patterns first: one on a feature and one in the matrix. Change one setting at a time and look at the circles on the pattern after each change.

What you see What to change
Circles on empty background Raise Minimum relative. To find the noise floor, lower it until false disks appear on the background, then set it just above.
Weak disks are missing Lower Minimum relative. If a saturated direct beam sets the scale, use Reference outside to measure against the brightest disk outside that radius.
Circles larger or smaller than the disks The probe radius is wrong. Correct Probe radius and click Build Kernel again.
Neighbouring disks are lost in pairs Minimum spacing is larger than the distance between the closest real disks. Lower it.
Disks at the detector edge are missing Edge exclusion drops disks cut by the edge. That is expected.
"This pattern was truncated to the configured maximum peak count." Raise Maximum peaks, or raise the threshold if the extra disks are noise.
Noisy data, unstable positions Raise Pattern smoothing σ or Correlation smoothing σ, and keep Correlation power at 1.

There is no single right value. The defaults are scaled to the detector, and the right threshold depends on the dynamic range of your data.

"Detection settings changed — rerun Detect All Disks". Strain, orientation and phase maps are built from the disks of the whole scan. After you change a detection setting, run Detect All Disks again before the next map.

A step cannot run

When a step cannot run, the app names what is missing. The usual ones:

  • "Needs Detect All Disks first." The step works on the detected disks. Run Detect All Disks in Bragg Disks.
  • "mrad needs accelerating voltage and Q pixel calibration." Set both in Prepare.
  • "From an earlier run — the settings above have changed." The result on screen no longer matches the settings. Run the step again.

Updates

The app checks once a day whether a newer version exists. To check now, choose Check for Updates… in the app menu. To turn the daily check off, clear Settings › General › Check for updates automatically.

If an update does not install, download the current disk image from the 4DSTEM Studio page and replace the app in Applications. Your settings, recent datasets and sessions stay.

An agent cannot connect

  1. Open Settings › Agents and turn on Let agents on this Mac look at open windows.
  2. Read Status. "On (port 47811), no agent has asked yet" means the app is listening and the agent has not reached it. "Could not open:" is followed by the reason. The port in the status is the one the app uses; it takes another when 47811 is in use.
  3. Click Copy Connection Command and paste it into Terminal once. The command holds the token; an agent set up with an older token is refused after New Token.

The agent can look but not act. Tools that change something need Let agents run analyses, which is off by default.

The agent is on another computer. The app answers only on the Mac it runs on. Run the agent on the same Mac.

Something else

Write to mail@mac4dstem.com or open an issue on GitHub. Say which version you use (About 4DSTEM Studio in the app menu), the file format, and the message the app showed. Support has the contact details.