2.5.2. prismatique.load.S_matrix_wavefunctions

S_matrix_wavefunctions(filename, multi_dim_slice=None, skip_validation_and_conversion=False)

From a given prismatique output file that stores \(S\)-matrices, load a specified subcollection of said \(S\)-matrices into a hyperspy signal.

See the documentation for the subpackage prismatique.stem for a discussion on \(S\)-matrices.

Parameters:

filenamestr

The relative or absolute path to the file containing the \(S\)-matrices of interest. Any non-temporary file generated by the function prismatique.sample.generate_S_matrices(), or prismatique.stem.sim.run() using the PRISM algorithm, with originally a basename of the form "S_matrices_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 \(S\)-matrices 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 \(\mathbf{k}_{xy}\) indices, where each \(\mathbf{k}_{xy}\) index corresponds to a different \(\mathbf{k}_{xy}\)-momentum vector of a plane wave used to calculate a different \(S\)-matrix. In this case, the current Python function will load the \(S\)-matrices of the frozen phonon configurations specified by multi_dim_slice[0], calculated using the plane waves with the \(\mathbf{k}_{xy}\)-momenta vectors specified by multi_dim_slice[1]. Note that prismatique.sample.S_matrix_k_xy_vectors(sample_specification, probe_model_params)[multi_dim_slice[1]]` yields the aforementioned specified :math:`\mathbf{k}_{xy}`-momenta vectors, where ``sample_specification and probe_model_params are objects of the appropriate types representing the sample model/model parameters and the probe model parameters respectively, used to generate the \(S\)-matrices.

Otherwise, if multi_dim_slice is set to None, then all the \(S\)-matrices stored in the file are loaded.

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:

S_matrix_wavefunction_signalhyperspy._signals.complex_signal2d.ComplexSignal2D

The subcollection of \(S\)-matrices, stored in an instance of the hyperspy._signals.complex_signal2d.ComplexSignal2D class. See the documentation and/or reference guide for the hyperspy package for details on how to use instances of the hyperspy._signals.complex_signal2d.ComplexSignal2D class.

navigational_to_original_indices_mapdict

A dictionary that maps the navigational indices of the hyperspy signal S_matrix_wavefunction_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 S_matrix_wavefunction_signal, where i is a nonnegative integer smaller than the total number of atomic configuration indices specified in single_dim_slice.