2.7.1. prismatique.scan.generate_probe_positions

generate_probe_positions(sample_specification, scan_config=None, filename=None, skip_validation_and_conversion=False)

Generate the probe positions specified by a given scanning configuration for a given sample.

Parameters:

sample_specificationprismatique.sample.ModelParams | prismatique.sample.PotentialSliceSubsetIDs | prismatique.sample.SMatrixSubsetIDs | prismatique.sample.PotentialSliceAndSMatrixSubsetIDs

The simulation parameters specifying the sample model.

If sample_specification is of the type prismatique.sample.ModelParams, then sample_specifications specifies sample model parameters that are used to construct the model from scratch, i.e. the potential slices for each frozen phonon configuration subset are calculated from said model parameters. See the documentation for the classes prismatique.discretization.Params and prismatique.thermal.Params for discussions on potential slices and frozen phonon configuration subsets respectively. Note that of parameters stored in sample_specification, only the following are used:

• sample_specification

  • atomic_coords_filename

  • unit_cell_tiling

Otherwise, if sample_specification is an instance of the class prismatique.sample.PotentialSliceSubsetIDs, the class prismatique.sample.SMatrixSubsetIDs, or the class prismatique.sample.PotentialSliceAndSMatrixSubsetIDs, then sample_specification specifies a set of files, where each file stores either the pre-calculated potential slices or \(S\)-matrices for a frozen phonon configuration subset. See the documentation for the aforementioned classes for further discussions on specifying pre-calculated objects. See the documentation for the subpackage prismatique.stem for a discussion on \(S\)-matrices.

scan_configarray_like (float, shape=(num_positions, 2)) | prismatique.scan.rectangular.Params | str | None, optional

If scan_config is a real-valued two-column matrix, then it specifies a set of probe positions, where scan_config[i][0] and scan_config[i][1] specify respectively the \(x\)- and \(y\)-coordinates of the probe position indexed by i, in units of angstroms, with 0<=i<num_positions and num_positions being the number of probe positions. If scan_config is of the type prismatique.scan.rectangular.Params, then it specifies a rectangular grid-like pattern of probe positions. See the documentation for this class for more details. If scan_config is a string, then scan_config is a path to a file that specifies a set of probe positions. The file must be encoded as ASCII text (UTF-8). The file should be formatted as follows: the first line can be whatever header the user desires, i.e. the first line is treated as a comment; each subsequent line except for the last is of the form “x y”, where “x” and “y” are the \(x\)- and \(y\)-coordinates of a probe position, in units of angstroms; and the last line in the file should be “-1”.

Since periodic boundaries conditions (PBCs) are assumed in the \(x\)- and \(y\)-dimensions, \(x\)- and \(y\)-coordinates can take on any real numbers. If scan_config is set to None, [i.e. the default value], then the probe is to be scanned across the entire unit cell of the simulation, in steps of 0.25 angstroms in both the \(x\)- and \(y\)-directions.

filenamestr | None, optional

If filename is set to a valid filename, then the generated probe positions are saved to a file with the filename filename. The file is formatted as follows: the first line is “probe positions in units of Å”; each subsequent line except for the last is of the form “x y”, where “x” and “y” are the \(x\)- and \(y\)-coordinates of a probe position, in units of angstroms; and the last line in the file is “-1”. Otherwise, if filename is set to None [i.e. the default value], then the generated probe positions are not saved to file.

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:

probe_positionsarray_like (float, shape=(num_positions, 2))

If we let num_positions be the number of probe positions, then probe_positions[i][0] and probe_positions[i][1] are the \(x\)- and \(y\)-coordinates of the i th probe position in units of Å, where 0<=i<num_positions.