2.8.1.3. prismatique.stem.output.Params

class Params(base_params=None, alg_specific_params=None, skip_validation_and_conversion=False)[source]

Bases: PreSerializableAndUpdatable

The output parameters for STEM simulations.

See the documentation for the class prismatique.cbed.Params for a discussion on CBED patterns that is relevant to the discussion on this page. We refer to CBED patterns generated from a STEM simulation as 4D-STEM data.

prismatic simulates annular detectors shaped in concentric rings, where each ring has a fixed bin width that can be chosen by the user. This allows one to collect the integrated intensity over each ring in a given DP. Integrating over the rings this way for each CBED intensity pattern yields what we will refer to as the “3D_STEM intensity data/output”: there are still two spatial dimensions associated with each probe position, but now there is only one dimension associated with the diffraction data for each probe position, i.e. a radial dimension in momentum space.

We can collect a further reduced set of data by integrating/summing over a consecutive set of rings for each CBED intensity pattern. For example, for each CBED intensity pattern we could integrate over the first so many rings that encompasses the direct beam, thus collecting bright field data. Therefore, for each CBED intensity pattern we extract a single number, which is the integrated intensity over a solid ring [e.g. in dark field imaging] or a disk [e.g. in bright field imaging]. We will call the resulting data the “2D_STEM intensity data/output”.

From the 4D-STEM intensity data, we can also calculate the “center-of-mass” (COM) momentum for each probe position:

(2.8.1.3.1)\[\left\langle \mathbf{k}_{\text{COM}}\right\rangle = \frac{\int d\mathbf{k}\, I_{\text{STEM}}\left(k_{x},k_{y}\right)\mathbf{k}}{\int d\mathbf{k}\, I_{\text{STEM}}\left(k_{x},k_{y}\right)},\]

where \(I_{\text{STEM}}\left(k_{x},k_{y}\right)\) is the CBED intensity.

Upon the completion of a STEM simulation, prismatique can optionally save a variety of different STEM data to a set of HDF5 files based on the specifications of the user. This is done by taking the original output file generated by prismatic, and then restructuring it into one or more output files. If the output parameters specify that intensity data be saved, then said data is extracted from the original prismatic output files, postprocessed, and written to a new file with basename "stem_sim_intensity_output.h5" in a more readable layout. Assuming all intensity data is to be saved, this new output file has the following structure:

metadata: <HDF5 group>
- probe_positions: <HDF5 2D dataset>
  - dim 1: “probe idx”
  - dim 2: “vector component idx [0->x, 1->y]”
  - units: “Å”
  - pattern type: “rectangular grid” | “jittered rectangular grid” | “no underlying rectangular grid”
  - grid dimensions in units of probe shifts: <ordered pair> | “N/A”
- output_layer_depths: <HDF5 1D dataset>
  - dim 1: “output layer idx”
  - units: “Å”
- k_x: <HDF5 1D dataset>
  - dim 1: “k_x idx”
  - units: “1/Å”
- k_y: <HDF5 1D dataset>
  - dim 1: “k_y idx”
  - units: “1/Å”
- k_xy: <HDF5 1D dataset>
  - dim 1: “k_xy idx”
  - units: “1/Å”
data: <HDF5 group>
- 2D_STEM: <HDF5 group>
  - integrated_intensities: <HDF5 2D dataset>
    - dim 1: “output layer idx”
    - dim 2: “probe idx”
    - units: “dimensionless”
    - lower integration limit in mrads: <scalar>
    - upper integration limit in mrads: <scalar>
- 3D_STEM: <HDF5 group>
  - integrated_intensities: <HDF5 3D dataset>
    - dim 1: “output layer idx”
    - dim 2: “probe idx”
    - dim 3: “k_xy idx”
    - units: “dimensionless”
- 4D_STEM: <HDF5 group>
  - intensity_DPs: <HDF5 4D dataset>
    - dim 1: “output layer idx”
    - dim 2: “probe idx”
    - dim 3: “k_y idx”
    - dim 4: “k_x idx”
    - units: “dimensionless”
- center_of_mass_momentum: <HDF5 3D dataset>
  - dim 1: “output layer idx”
  - dim 2: “vector component idx [0->x, 1->y]”
  - dim 3: “probe idx”
  - units: “1/Å”

Note that the sub-bullet points listed immediately below a given HDF5 dataset display the HDF5 attributes associated with said HDF5 dataset. Each HDF5 scalar and dataset has a "units" attribute which, as the name suggests, indicates the units in which said data [i.e. the scalar or dataset] is expressed. Each HDF5 dataset will also have a set of attributes with names of the form "dim {}".format(i) with i being an integer ranging from 1 to the rank of said HDF5 dataset. Attribute "dim {}".format(i) of a given HDF5 dataset labels the \(i^{\text{th}}\) dimension of the underlying array of the dataset. Most of these dimension labels should be self-explanatory but for clarification: “idx” is short for “index”; “k_x” and “k_y” refer to the \(x\)- and \(y\)-components of the electron scattering momentum; and the notion of an output layer is discussed in the documentation for the class prismatique.stem.output.multislice.Params.

If the output parameters specify that complex-valued wavefunction data be saved, then said data is extracted from the original prismatic output files, and written to a new set of files: one file per frozen phonon/atomic configuration subset. Note that, unlike the intensity data, the complex-valued wavefunction data is not postprocessed. See the documentation for the class prismatique.thermal.Params for a discussion on frozen phonon configurations and their grouping into subsets. For the i th frozen phonon configuration subset, the corresponding wavefunction data is saved to the file with basename "stem_sim_wavefunction_output_of_subset_"+str(i)+".h5". Each one of these new output files has the following structure:

metadata: <HDF5 group>
- probe_positions: <HDF5 2D dataset>
  - dim 1: “probe idx”
  - dim 2: “vector component idx [0->x, 1->y]”
  - units: “Å”
  - pattern type: “rectangular grid” | “jittered rectangular grid” | “no underlying rectangular grid”
  - grid dimensions in units of probe shifts: <ordered pair> | “N/A”
- defocii: <HDF5 1D dataset>
  - dim 1: “defocus idx”
  - units: “Å”
- output_layer_depths: <HDF5 1D dataset>
  - dim 1: “output layer idx”
  - units: “Å”
- k_x: <HDF5 1D dataset>
  - dim 1: “k_x idx”
  - units: “1/Å”
- k_y: <HDF5 1D dataset>
  - dim 1: “k_y idx”
  - units: “1/Å”
data: <HDF5 group>
- 4D_STEM: <HDF5 group>
  - complex_valued_DPs: <HDF5 6D dataset>
    - dim 1: “output layer idx”
    - dim 2: “atomic config idx”
    - dim 3: “defocus idx”
    - dim 4: “probe idx”
    - dim 5: “k_y idx”
    - dim 6: “k_x idx”
    - units: “dimensionless”

prismatique can also optionally save the “potential slice” [i.e. Eq. (2.3.1.7)] data for each subset of frozen phonon configurations into separate HDF5 output files by extracting said data from the original prismatic output files. For the i th subset, the corresponding potential slice data is saved to an HDF5 output file with basename "potential_slices_"+str(i)+".h5". Unlike the output data in the file "stem_simulation_output.h5", the layout of the potential slice data is kept the same as that found in the original file [i.e. the same HDF5 paths are used]. The same layout needs to be used in order for prismatic to be able to successfully import/load pre-calculated potential slice data for future simulations.

Moreover if used/generated, prismatique can also optionally save the \(S\)-matrix [i.e. Eq. (2.8.37)] data into a separate HDF5 output files by extracting said data from the original prismatic output files. For the i th subset, the corresponding \(S\)-matrix data is saved to an HDF5 output file with basename "S_matrix_"+str(i)+".h5". The layout of the \(S\)-matrix data is kept the same as that found in the original file for the same reason mentioned for the potential slice data. Note that \(S\)-matrix data is only generated/used when STEM simulations are performed using the PRISM algorithm [see the documentation for the subpackage prismatique.stem for details on this algorithm].

It is beyond the scope of the documentation to describe the structure of the potential slice and \(S\)-matrix output files. Users can analyze the data in these output files with the help of the tools found in the module prismatique.load.

The last file that is always generated after running a STEM simulation is a JSON file that contains, in a serialized format, the simulation parameters used. This file has the basename "stem_sim_params.json".

Parameters:

base_paramsprismatique.stem.output.base.Params | None, optional

The base output parameters for the STEM simulation. See the documentation for the class prismatique.stem.output.base.Params for a discussion on said parameters. If base_params is set to None [i.e. the default value], then the aforementioned parameters are set to default values.

alg_specific_paramsprismatique.stem.output.multislice.Params | prismatique.stem.output.prism.Params | None, optional

The output parameters that are applicable only to the particular algorithm used perform the STEM simulation. If alg_specific_params is set to an instance of the class prismatique.stem.output.multislice.Params, then the multislice algorithm is used to perform the STEM simulation. See the documentation for the class prismatique.stem.output.multislice.Params for a discussion on the output parameters specific to the multislice algorithm. If alg_specific_params is set to an instance of the class prismatique.stem.output.prism.Params, then the PRISM algorithm is used to perform the STEM simulation. See the documentation for the class prismatique.stem.output.prism.Params for a discussion on the output parameters specific to the PRISM algorithm. If alg_specific_params is set to None [i.e. the default value], then the multislice algorithm is used to perform the STEM simulation with the aforementioned output parameters set to default values.

skip_validation_and_conversionbool, optional

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, both of which being dict objects.

Let params_to_be_mapped_to_core_attrs denote the dict representation of the constructor parameters excluding the parameter skip_validation_and_conversion, where each dict key key is a different constructor parameter name, excluding the name "skip_validation_and_conversion", and params_to_be_mapped_to_core_attrs[key] would yield the value of the constructor parameter with the name given by key.

If skip_validation_and_conversion is set to False, then for each key key in params_to_be_mapped_to_core_attrs, core_attrs[key] is set to validation_and_conversion_funcs[key] (params_to_be_mapped_to_core_attrs).

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to params_to_be_mapped_to_core_attrs.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of params_to_be_mapped_to_core_attrs, as it is guaranteed that no copies or conversions are made in this case.

Attributes:

core_attrs: dict: The “core attributes”.
de_pre_serialization_funcs: dict: The de-pre-serialization functions.
pre_serialization_funcs: dict: The pre-serialization functions.
validation_and_conversion_funcs: dict: The validation and conversion functions.

Methods

`de_pre_serialize`([serializable_rep, ...])	Construct an instance from a serializable representation.
`dump`([filename, overwrite])	Serialize instance and save the result in a JSON file.
`dumps`()	Serialize instance.
`get_core_attrs`([deep_copy])	Return the core attributes.
`get_de_pre_serialization_funcs`()	Return the de-pre-serialization functions.
`get_pre_serialization_funcs`()	Return the pre-serialization functions.
`get_validation_and_conversion_funcs`()	Return the validation and conversion functions.
`load`([filename, skip_validation_and_conversion])	Construct an instance from a serialized representation that is stored in a JSON file.
`loads`([serialized_rep, ...])	Construct an instance from a serialized representation.
`pre_serialize`()	Pre-serialize instance.
`update`([new_core_attr_subset_candidate, ...])	Update a subset of the core attributes.

Methods

`de_pre_serialize`	Construct an instance from a serializable representation.
`dump`	Serialize instance and save the result in a JSON file.
`dumps`	Serialize instance.
`get_core_attrs`	Return the core attributes.
`get_de_pre_serialization_funcs`	Return the de-pre-serialization functions.
`get_pre_serialization_funcs`	Return the pre-serialization functions.
`get_validation_and_conversion_funcs`	Return the validation and conversion functions.
`load`	Construct an instance from a serialized representation that is stored in a JSON file.
`loads`	Construct an instance from a serialized representation.
`pre_serialize`	Pre-serialize instance.
`update`	Update a subset of the core attributes.

Attributes

`core_attrs`	dict: The "core attributes".
`de_pre_serialization_funcs`	dict: The de-pre-serialization functions.
`pre_serialization_funcs`	dict: The pre-serialization functions.
`validation_and_conversion_funcs`	dict: The validation and conversion functions.

property core_attrs

dict: The “core attributes”.

The keys of core_attrs are the same as the attribute validation_and_conversion_funcs, which is also a dict object.

Note that core_attrs should be considered read-only.

property de_pre_serialization_funcs

dict: The de-pre-serialization functions.

de_pre_serialization_funcs has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and pre_serialization_funcs denote the attributes validation_and_conversion_funcs pre_serialization_funcs respectively, the last of which being a dict object as well.

Let core_attrs_candidate_1 be any dict object that has the same keys as validation_and_conversion_funcs, where for each dict key key in core_attrs_candidate_1, validation_and_conversion_funcs[key](core_attrs_candidate_1) does not raise an exception.

Let serializable_rep be a dict object that has the same keys as core_attrs_candidate_1, where for each dict key key in core_attrs_candidate_1, serializable_rep[key] is set to pre_serialization_funcs[key](core_attrs_candidate_1[key]).

The items of de_pre_serialization_funcs are expected to be set to callable objects that would lead to de_pre_serialization_funcs[key](serializable_rep[key]) not raising an exception for each dict key key in serializable_rep.

Let core_attrs_candidate_2 be a dict object that has the same keys as serializable_rep, where for each dict key key in validation_and_conversion_funcs, core_attrs_candidate_2[key] is set to de_pre_serialization_funcs[key](serializable_rep[key]).

The items of de_pre_serialization_funcs are also expected to be set to callable objects that would lead to validation_and_conversion_funcs[key](core_attrs_candidate_2) not raising an exception for each dict key key in core_attrs_candidate_2.

Note that de_pre_serialization_funcs should be considered read-only.

classmethod de_pre_serialize(serializable_rep={}, skip_validation_and_conversion=False)

Construct an instance from a serializable representation.

Parameters:

serializable_repdict, optional

A dict object that has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, the last of which being a dict object as well.

The items of serializable_rep are expected to be objects that would lead to de_pre_serialization_funcs[key](serializable_rep[key]) not raising an exception for each dict key key in serializable_rep.

Let core_attrs_candidate be a dict object that has the same keys as serializable_rep, where for each dict key key in serializable_rep, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

The items of serializable_rep are also expected to be set to objects that would lead to validation_and_conversion_funcs[key](core_attrs_candidate) not raising an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If skip_validation_and_conversion is set to False, then for each key key in serializable_rep, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), with validation_and_conversion_funcs and core_attrs_candidate_1 being introduced in the above description of serializable_rep.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class: An instance constructed from the serializable representation serializable_rep.

dump(filename='serialized_rep_of_fancytype.json', overwrite=False)

Serialize instance and save the result in a JSON file.

Parameters:

filenamestr, optional: The relative or absolute path to the JSON file in which to store the serialized representation of an instance.
overwritebool, optional: If overwrite is set to False and a file exists at the path filename, then the serialized instance is not written to that file and an exception is raised. Otherwise, the serialized instance will be written to that file barring no other issues occur.

Returns:

dumps()

Serialize instance.

Returns:

serialized_repdict: A serialized representation of an instance.

get_core_attrs(deep_copy=True)

Return the core attributes.

Parameters:

deep_copybool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If deep_copy is set to True, then a deep copy of core_attrs is returned. Otherwise, a shallow copy of core_attrs is returned.

Returns:

core_attrsdict: The attribute core_attrs.

classmethod get_de_pre_serialization_funcs()[source]

Return the de-pre-serialization functions.

Returns:

de_pre_serialization_funcsdict: The attribute de_pre_serialization_funcs.

classmethod get_pre_serialization_funcs()[source]

Return the pre-serialization functions.

Returns:

pre_serialization_funcsdict: The attribute pre_serialization_funcs.

classmethod get_validation_and_conversion_funcs()[source]

Return the validation and conversion functions.

Returns:

validation_and_conversion_funcsdict: The attribute validation_and_conversion_funcs.

classmethod load(filename='serialized_rep_of_fancytype.json', skip_validation_and_conversion=False)

Construct an instance from a serialized representation that is stored in a JSON file.

Users can save serialized representations to JSON files using the method fancytypes.PreSerializable.dump().

Parameters:

filenamestr, optional

The relative or absolute path to the JSON file that is storing the serialized representation of an instance.

filename is expected to be such that json.load(open(filename, "r")) does not raise an exception.

Let serializable_rep=json.load(open(filename, "r")).

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, both of which being dict objects as well.

filename is also expected to be such that de_pre_serialization_funcs[key](serializable_rep[key]) does not raise an exception for each dict key key in de_pre_serialization_funcs.

Let core_attrs_candidate be a dict object that has the same keys as de_pre_serialization_funcs, where for each dict key key in serializable_rep, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

filename is also expected to be such that validation_and_conversion_funcs[key](core_attrs_candidate) does not raise an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

Let core_attrs_candidate be as defined in the above description of filename.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), , with validation_and_conversion_funcs and core_attrs_candidate being introduced in the above description of filename.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class: An instance constructed from the serialized representation stored in the JSON file.

classmethod loads(serialized_rep='{}', skip_validation_and_conversion=False)

Construct an instance from a serialized representation.

Users can generate serialized representations using the method dumps().

Parameters:

serialized_repstr | bytes | bytearray, optional

The serialized representation.

serialized_rep is expected to be such that json.loads(serialized_rep) does not raise an exception.

Let serializable_rep=json.loads(serialized_rep).

Let validation_and_conversion_funcs and de_pre_serialization_funcs denote the attributes validation_and_conversion_funcs de_pre_serialization_funcs respectively, both of which being dict objects as well.

serialized_rep is also expected to be such that de_pre_serialization_funcs[key](serializable_rep[key]) does not raise an exception for each dict key key in de_pre_serialization_funcs.

Let core_attrs_candidate be a dict object that has the same keys as serializable_rep, where for each dict key key in de_pre_serialization_funcs, core_attrs_candidate[key] is set to de_pre_serialization_funcs[key](serializable_rep[key])``.

serialized_rep is also expected to be such that validation_and_conversion_funcs[key](core_attrs_candidate) does not raise an exception for each dict key key in serializable_rep.

skip_validation_and_conversionbool, optional

Let core_attrs denote the attribute core_attrs, which is a dict object.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (core_attrs_candidate), with validation_and_conversion_funcs and core_attrs_candidate_1 being introduced in the above description of serialized_rep.

Otherwise, if skip_validation_and_conversion is set to True, then core_attrs is set to core_attrs_candidate.copy(). This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of core_attrs_candidate, as it is guaranteed that no copies or conversions are made in this case.

Returns:

instance_of_current_clsCurrent class: An instance constructed from the serialized representation.

property pre_serialization_funcs

dict: The pre-serialization functions.

pre_serialization_funcs has the same keys as the attribute validation_and_conversion_funcs, which is also a dict object.

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, the last of which being a dict object as well.

For each dict key key in core_attrs, pre_serialization_funcs[key](core_attrs[key]) is expected to yield a serializable object, i.e. it should yield an object that can be passed into the function json.dumps without raising an exception.

Note that pre_serialization_funcs should be considered read-only.

pre_serialize()

Pre-serialize instance.

Returns:

serializable_repdict: A serializable representation of an instance.

update(new_core_attr_subset_candidate={}, skip_validation_and_conversion=False)

Update a subset of the core attributes.

Parameters:

new_core_attr_subset_candidatedict, optional

A dict object.

skip_validation_and_conversionbool, optional

Let validation_and_conversion_funcs and core_attrs denote the attributes validation_and_conversion_funcs and core_attrs respectively, both of which being dict objects.

If skip_validation_and_conversion is set to False, then for each key key in core_attrs that is also in new_core_attr_subset_candidate, core_attrs[key] is set to validation_and_conversion_funcs[key] (new_core_attr_subset_candidate).

Otherwise, if skip_validation_and_conversion is set to True, then for each key key in core_attrs that is also in new_core_attr_subset_candidate, core_attrs[key] is set to new_core_attr_subset_candidate[key]. This option is desired primarily when the user wants to avoid potentially expensive deep copies and/or conversions of the dict values of new_core_attr_subset_candidate, as it is guaranteed that no copies or conversions are made in this case.

property validation_and_conversion_funcs

dict: The validation and conversion functions.

The keys of validation_and_conversion_funcs are the names of the constructor parameters, excluding skip_validation_and_conversion if it exists as a construction parameter.

Let core_attrs denote the attribute core_attrs, which is also a dict object.

For each dict key key in core_attrs, validation_and_conversion_funcs[key](core_attrs) is expected to not raise an exception.

Note that validation_and_conversion_funcs should be considered read-only.