2.6.5. prismatique.sample.generate_S_matrices

generate_S_matrices(sample_specification, probe_model_params=None, output_dirname='S_matrix_generator_output', max_data_size=2000000000, worker_params=None, skip_validation_and_conversion=False)

Generate the \(S\)-matrices for a given sample model and probe model.

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

For each frozen phonon configuration subset, this Python function generates the corresponding \(S\)-matrices and saves them to a set of files. See the documentation for the subpackage prismatique.stem for a discussion on \(S\)-matrices, and the class prismatique.thermal.Params for a discussion on frozen phonon configuration subsets.

For each frozen phonon configuration subset, the corresponding \(S\)-matrix data is written to a file with the basename "S_matrices_of_subset_"+str(i)+".h5", with i being the subset index.

In addition to the \(S\)-matrix files, three other files are generated as well: The first is a JSON file with the basename "sample_specification.json" which contains, in a serialized format, the simulation parameters related to the modelling of the sample; the second file is a JSON file with the basename "worker_params.json" which contains, in a serialized format, the simulation parameters related to GPU and CPU workers; and the third file is a JSON file with the basename "probe_model_params.json" which contains, in a serialized format, the simulation parameters related to the modelling of the probe.

Parameters:

sample_specificationprismatique.sample.ModelParams | prismatique.sample.PotentialSliceSubsetIDs

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.

Otherwise, if sample_specification is an instance of the class prismatique.sample.PotentialSliceSubsetIDs then sample_specification specifies a set of files, where each file stores the pre-calculated potential slices for a frozen phonon configuration subset. See the documentation for the aforementioned class for a further discussion on specifying pre-calculated potential slices.

probe_model_paramsembeam.stem.probe.ModelParams | None, optional

The model parameters of the probe. See the documentation for the class embeam.stem.probe.ModelParams for a discussion on said parameters. If probe_model_params is set to None [i.e. the default value], then the parameter will be reassigned to the value embeam.stem.probe.ModelParams().

Note that of parameters stored in probe_model_params, only the following are used:

• probe_model_params

  • convergence_semiangle

  • gun_model_params

    • mean_beam_energy

output_dirnamestr, optional

The relative or absolute path to the directory in which all output files are to be saved. If the directory doesn’t exist upon saving the output files, it will be created if possible.

max_data_sizeint, optional

The data size limit, in bytes, of the \(S\)-matrices to be generated. If the \(S\)-matrices to be generated would require a data size larger than the aforementioned limit, then an exception is raised and the \(S\)-matrices are not generated. Note that data size due to HDF5 file overhead and metadata are not taken into account.

worker_paramsprismatique.worker.Params | None, optional

The simulation parameters related to GPU and CPU workers. See the documentation for the class prismatique.worker.Params for a discussion on said parameters. If worker_params is set to None [i.e. the default value], then the aforementioned simulation parameters are set to default values.

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: