2.5.21. prismatique.load.potential_slices

potential_slices(filename, multi_dim_slice=None, num_superslices=0, average_thermally=False, average_laterally_in_space=False, skip_validation_and_conversion=False)

From a given prismatique output file that stores potential slices of a sample, load a specified subcollection of said potential slices into a hyperspy signal.

See also the documentation for the class prismatique.discretization.Params for a discussion on potential slices.

Parameters:

filenamestr

The relative or absolute path to the file containing the potential slices of interest. Any non-temporary file generated by the function prismatique.sample.generate_potential_slices(), prismatique.stem.sim.run(), or prismatique.hrtem.sim.run(), with originally a basename of the form "potential_slices_of_subset_"+str(i)+".h5" is valid, where i is a nonnegative integer.

multi_dim_slicetuple (int | slice | list (int)) | None, optional

The “multidimensional slice object”, which specifies the subcollection of potential slices to load from file. We define a multi-dimensional slice object as a tuple of items which contains at most one item being a list of integers, and the remaining items being slice and/or int objects.

If multi_dim_slice is a tuple of length 2, then multi_dim_slice[0] specifies a set of atomic configuration indices, where each atomic configuration index corresponds to a frozen phonon configuration; and multi_dim_slice[1] specifies a set of sample slice indices, where each sample slice index corresponds to a different sample slice at a different \(z\)-coordinate. In this case, the current Python function will load the potential slices of the frozen phonon configurations specified by multi_dim_slice[0], at the \(z\)-coordinates specified by multi_dim_slice[1]. Note that a sample slice index \(n\) corresponds to a sample slice at the \(z\)-coordinate \(z_{n}\), where \(z_{n}\) is given by Eq. (2.3.1.5).

Otherwise, if multi_dim_slice is set to None, then all the potential slices stored in the file are loaded.

num_superslicesint, optional

The number of potential superslices to form from the potential slices to be loaded from file, per frozen phonon configuration. We define a potential superslice as the sum of a group of potential slices. Let N be the total number of potential slices stored in the file per frozen phonon configuration, M be the number of slices to be loaded per frozen phonon configuration, n=int(np.ceil(M / max(num_superslices, 1))), and single_dim_slice=multi_dim_slice[1] if multi_dim_slice is not None else slice(None). If num_superslices is a positive int, then for each integer i satisfying 0<=i<num_superslices-1, the i th superslice is calculated by summing the potential slices with the corresponding indices np.arange(N)[single_dim_slice][i*n:(i+1)*n], and for i==num_superslices-1, the i th superslice is calculated by summing the potential slices with the corresponding indices np.arange(N)[single_dim_slice][i*n:M]. Otherwise, if num_superslices==0, then no potential superslices are formed.

average_thermallybool, optional

If average_thermally is set to True, then the potential slices and superslices are averaged over the selected frozen phonon configurations. Otherwise, the potential slices are not averaged over the selected frozen phonon configurations.

average_laterally_in_spacebool, optional

If average_laterally_in_space is set to True, then the potential slices and superslices are averaged laterally in space. Otherwise, the potential slices are not averaged laterally in space.

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:

potential_slice_signalhyperspy.signal.BaseSignal | hyperspy._signals.signal2d.Signal2D

The subcollection of potential slices, stored in an instance of the hyperspy._signals.signal2d.Signal2D class if average_laterally_in_space is set to False, otherwise it is stored in an instance of the hyperspy.signal.BaseSignal. See the documentation and/or reference guide for the hyperspy package for details on how to use instances of the hyperspy._signals.signal2d.Signal2D and hyperspy.signal.BaseSignal classes.

navigational_to_original_indices_mapdict

A dictionary that maps the navigational indices of the hyperspy signal potential_slice_signal to the original indices specified by multi_dim_slice. For example, if the original atomic configuration indices map to a set of corresponding navigational indices, then navigational_to_original_indices_map["atomic_config_indices"][i] yields the atomic configuration index specified in the expression single_dim_slice=multi_dim_slice[0] if multi_dim_slice is not None else slice(None) that corresponds to the i th atomic configuration index in the nagivation index space of potential_slice_signal, where i is a nonnegative integer smaller than the total number of atomic configuration indices specified in single_dim_slice.