2.5.22. prismatique.load.probe_positions

probe_positions(filename, force_2_col_shape=True, skip_validation_and_conversion=False)

From a given STEM simulation output file, load the probe positions stored or specified therein.

Note that the cartesian coordinate system used to define the probe positions has its origin coinciding with the bottom left corner of the sample’s supercell [see the documentation for the class prismatique.discretization.Params for a discussion on sample supercells].

Parameters:

filenamestr

The relative or absolute path to the file containing the probe positions or specifying the scan pattern. Any non-temporary file generated by the function prismatique.stem.sim.run() that does not store potential slice or S-matrix data, is a valid file. In other words, any file generated by a STEM simulation with originally the basename "stem_sim_intensity_output.h5", "stem_sim_params.json", or a basename of the form "stem_sim_wavefunction_output_of_subset_"+str(i)+".h5", where i is a nonnegative integer.

See the documentation for the class prismatique.stem.output.Params for a discussion on the layout and structuring of prismatique STEM simulation output files.

force_2_col_shapebool, optional

If force_2_col_shape is set to False and prismatique.load.scan_pattern_type(filename) == "rectangular grid", then the return object storing the probe positions, probe_positions, is not a two-column array. Otherwise, probe_positions is a two-column array. See the description below of probe_positions for more details.

skip_validation_and_conversionbool, optional

If skip_validation_and_conversion is set to False, then validations and conversions are performed on the above parameters.

Otherwise, if skip_validation_and_conversion is set to True, no validations and conversions are performed on the above parameters. This option is desired primarily when the user wants to avoid potentially expensive validation and/or conversion operations.

Returns:

positionsarray_like (float, shape=(num_probe_positions, 2)) | array_like (float, shape=(Y_dim, X_dim, 2))

Let num_probe_positions be the number of probe positions. If force_2_col_shape==True or prismatique.load.scan_pattern_type(filename) != "rectangular grid", then positions[i][0] and positions[i][1] are the \(x\)- and \(y\)-components of the \(i^{\text{th}}\) probe position in units of Å, where i is an integer satisfying 0<=i<num_probe_positions.

If prismatique.load.scan_pattern_type(filename) == "rectangular grid", then the probe positions lie exactly on a rectangular grid with X_dim positions along the \(x\)-axis, Y_dim positions along the \(y\)-axis. Let rx be the set of possible \(x\)-coordinates of the probe in ascending order, and ry be the set of possible \(y\)-coordinates of the probe in descending order, both in units of Å. In the case that force_2_col_shape==False and prismatique.load.scan_pattern_type(filename) == "rectangular grid", positions[ry_idx][rx_idx][0]=rx[rx_idx] and positions[ry_idx][rx_idx][1]=ry[ry_idx], where rx_idx and ry_idx are non-negative integers satisfying rx_idx<X_dim and ry_idx<Y_dim respectively.