NRSS.morphology#

class NRSS.morphology.Material(materialID=1, Vfrac=None, S=None, theta=None, psi=None, NumZYX=None, energies=None, opt_constants=None, name=None)#

Bases: OpticalConstants

Object to hold the voxel-level data for a CyRSoXS morphology. Inherits from the OpticalConstants class.

materialID#

Integer value denoting the material number. Used in CyRSoXS

Type:

int

Vfrac#

Volume fractions for a Material

Type:

ndarray

theta#

The second Euler angle (ZYZ convention)

Type:

ndarray

psi#

The third Euler angle (ZYZ convention)

Type:

ndarray

NumZYX#

Dimensions of the Material arrays (NumZ, NumY, NumX)

Type:

tuple or list

name#

Name of the Material (e.g. ‘Polystyrene’)

Type:

str

copy()#
class NRSS.morphology.Morphology(numMaterial, materials=None, PhysSize=None, config={'CaseType': 0, 'EAngleRotation': [0.0, 1.0, 0.0], 'Energies': [270.0], 'MorphologyType': 0}, create_cy_object=True)#

Bases: object

Object used to hold all the components necessary for a complete CyRSoXS morphology

input_mapping#

A dictionary to handle specific configuration input types

Type:

dict

numMaterial#

Number of materials present in the morphology

Type:

int

materials#

A dictionary of Material objects

Type:

dict

PhysSize#

The physical size of each cubic voxel’s three dimensions

Type:

float

NumZYX#

Number of voxels in the Z, Y, and X directions (NumZ, NumY, NumX)

Type:

tuple or list

config#

A dictionary of configuration parameters for CyRSoXS

Type:

dict

create_cy_object#

Boolean value that decides if the CyRSoXS objects are created upon instantiation

Type:

bool

simulated#

Boolean value that tracks whether or not the simulation has been run

Type:

bool

load_morph_hdf5(hdf5_file, create_cy_object=True)#

Class method that creates a Morphology object from a morphology HDF5 file

create_inputData()#

Creates a CyRSoXS InputData object and populates it with parameters from self.config

create_optical_constants()#

Creates a CyRSoXS RefractiveIndex object and populates it with optical constants from the materials dict

create_voxel_data()#

Creates a CyRSoXS VoxelData object and populates it with the voxel information from the materials dict

run(stdout=True, stderr=True, return_xarray=True, print_vec_info=False)#

Creates a CyRSoXS ScatteringPattern object if not already created, and submits all CyRSoXS objects to run the simulation

scattering_to_xarray(return_xarray=True, print_vec_info=False)#

Copies the CyRSoXS ScatteringPattern arrays to an xarray in the format used by PyHyperScattering for further analysis

property AlgorithmType#
property CaseType#
property EAngleRotation#
property Energies#
property EwaldsInterpolation#
property MorphologyType#
property PhysSize#
property ReferenceFrame#
property RotMask#
property WindowingType#
check_materials(quiet=True)#
property config#
config_default = {'AlgorithmType': 0, 'CaseType': 0, 'EAngleRotation': [0.0, 1.0, 0.0], 'Energies': [270.0], 'EwaldsInterpolation': 1, 'MorphologyType': 0, 'ReferenceFrame': 1, 'RotMask': 0, 'WindowingType': 0}#
config_to_inputData()#
create_inputData()#
create_optical_constants()#
create_update_cy()#
create_voxel_data()#
input_mapping = {'AlgorithmType': ['setAlgorithm', [0, 1]], 'CaseType': ['setCaseType', [<CaseType.Default: 0>, <CaseType.BeamDivergence: 1>, <CaseType.GrazingIncidence: 2>]], 'EwaldsInterpolation': ['interpolationType', [<InterpolationType.NearestNeighour: 0>, <InterpolationType.Linear: 1>]], 'MorphologyType': ['setMorphologyType', [<MorphologyType.EulerAngles: 0>, <MorphologyType.VectorMorphology: 1>]], 'ReferenceFrame': ['referenceFrame', [0, 1]], 'RotMask': ['rotMask', [False, True]], 'WindowingType': ['windowingType', [<FFTWindowing.NoPadding: 0>, <FFTWindowing.Hanning: 1>]]}#
load_config(config_file)#
load_matfile(matfile)#
classmethod load_morph_hdf5(hdf5_file, create_cy_object=False)#
property numMaterial#
run(stdout=True, stderr=True, return_xarray=True, print_vec_info=False, validate=False)#
scattering_to_xarray(return_xarray=True, print_vec_info=False)#
property simulated#
update_optical_constants()#
update_voxel_data()#
validate_all(quiet=True)#
visualize_materials(*args, **kwargs)#

Reads in morphology HDF5 file and checks that the format is consistent for CyRSoXS. Optionally plots and returns select quantities.

Parameters:

  • z_slice (int) – Which z-slice of the array to plot.

  • subsample (int) – Number of voxels to display in X and Y

  • translate_x (int) – Number of voxels to translate image in x; meant for use with subsample

  • translate_y (int) – Number of voxels to translate image in y; meant for use with subsample

  • screen_euler (bool) – Suppress visualization of euler angles where vfrac < 0.05 or S < 0.05; intended to hilight edges

  • add_quiver (bool) – Adds lines to every voxel on the psi plot that indicate in-plane direction. Not recommended for resolutions larger than 128x128, best for resolutions 64x64 or lower.

  • quiver_bw (bool) – Intended to be used when add_quiver == True, when quiver_bw is True, the quiver arrows will be black and white instead of colored.

  • outputmat (list of ints) – Number of which materials to return

  • outputplot (list of strings) – Number of which plots to return, can include ‘vfrac’, ‘S’, ‘theta’, ‘psi’

  • outputaxes (bool) – If a plot is returned, include its axes

  • vfrac_range (list of tuples as [float, float]) – A custom range for vfrac colorbar

  • S_range (list of tuples as [float, float]) – A custom range for S colorbar

  • vfrac_cmap (str) – A custom substitution for vfrac colormap

  • S_cmap (str) – A custom substitution for vfrac colormap

  • runquiet (bool) – Boolean flag for running without plotting or outputting to console

  • batchMode (bool) – if true, prints console output and generates plots but doesnt show (provide exportDir for export)

  • plotstyle (str) – Use a light or dark background for plots. ‘dark’ - dark, ‘light’ - light

  • dpi (int) – The dpi at which the plot is generated. Per-material plot dimensions are 8.5” x 12.75”

  • exportDir (str, optional) – if provided, export directory to save any generated figures into, by default, will respect dpi and save as png, use exportParams to override

  • exportParams (dict, optional) – additional params to unpack into matplotlib.pyplot.savefig. Overrides existing params. ex: exportParams = {‘dpi’:600, format=’svg’}

Return type:

If outputmat and outputplot are correctly entered, will return an index list of images of the selected material and plot. Each list element will be a numpy array in RGB format that be displayed with imshow

write_config()#
write_constants(path=None)#
write_to_file(fname, author='NIST')#
class NRSS.morphology.OpticalConstants(energies, opt_constants=None, name='unknown')#

Bases: object

Object to hold dielectric optical constants in a format compatible with CyRSoXS

energies#

List of energies

Type:

list or array

opt_constants#

Dictionary of optical constants, where each energy is a key in the dict

Type:

dict

name#

String identifying the element or material for these optical constants

Type:

str

calc_constants(energies, reference_data, name='unkown')#

Interpolates optical constant data to the list of energies provided

load_matfile(matfile, name='unknown')#

Creates an OpticalConstants object from a previously written MaterialX.txt file

create_vacuum(energies)#

Convenience function to populate zeros for all optical constants

classmethod calc_constants(energies, reference_data, name='unknown')#
create_vacuum(energies)#
classmethod load_matfile(matfile, name='unknown')#
class NRSS.morphology.ParamSpec(name, *, bound=None, covariant=False, contravariant=False)#

Bases: _Final, _Immutable, _BoundVarianceMixin, _PickleUsingNameMixin

Parameter specification variable.

Usage:

P = ParamSpec('P')

Parameter specification variables exist primarily for the benefit of static type checkers. They are used to forward the parameter types of one callable to another callable, a pattern commonly found in higher order functions and decorators. They are only valid when used in Concatenate, or as the first argument to Callable, or as parameters for user-defined Generics. See class Generic for more information on generic types. An example for annotating a decorator:

T = TypeVar('T')
P = ParamSpec('P')

def add_logging(f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

@add_logging
def add_two(x: float, y: float) -> float:
    '''Add two numbers together.'''
    return x + y

Parameter specification variables can be introspected. e.g.:

P.__name__ == ‘P’

Note that only parameter specification variables defined in global scope can be pickled.

property args#
property kwargs#
class NRSS.morphology.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False)#

Bases: _Final, _Immutable, _BoundVarianceMixin, _PickleUsingNameMixin

Type variable.

Usage:

T = TypeVar('T')  # Can be anything
A = TypeVar('A', str, bytes)  # Must be str or bytes

Type variables exist primarily for the benefit of static type checkers. They serve as the parameters for generic types as well as for generic function definitions. See class Generic for more information on generic types. Generic functions work as follows:

def repeat(x: T, n: int) -> List[T]:

‘’’Return a list containing n references to x.’’’ return [x]*n

def longest(x: A, y: A) -> A:

‘’’Return the longest of two strings.’’’ return x if len(x) >= len(y) else y

The latter example’s signature is essentially the overloading of (str, str) -> str and (bytes, bytes) -> bytes. Also note that if the arguments are instances of some subclass of str, the return type is still plain str.

At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.

Type variables defined with covariant=True or contravariant=True can be used to declare covariant or contravariant generic types. See PEP 484 for more details. By default generic types are invariant in all type variables.

Type variables can be introspected. e.g.:

T.__name__ == ‘T’ T.__constraints__ == () T.__covariant__ == False T.__contravariant__ = False A.__constraints__ == (str, bytes)

Note that only type variables defined in global scope can be pickled.

NRSS.morphology.check_NumMat(f, morphology_type)#

Checks and validates the number of materials in the HDF5 file

Parameters:

  • f (file object)

  • morphology_type (int) – 0 - Euler, 1 - Vector

Returns:

num_mat – Number of materials in file

Return type:

int

NRSS.morphology.morphology_visualizer(morphology, z_slice: int = 0, subsample: int = None, translate_x: int = None, translate_y: int = None, screen_euler: bool = True, add_quiver: bool = False, quiver_bw: bool = True, outputmat: list = None, outputplot: list = None, outputaxes: bool = True, vfrac_range: list = None, S_range: list = None, vfrac_cmap: str = None, S_cmap: str = None, runquiet: bool = False, batchMode: bool = False, plotstyle: str = 'light', dpi: int = 300, exportDir: str = None, exportParams: dict = None)#

Reads in morphology HDF5 file and checks that the format is consistent for CyRSoXS. Optionally plots and returns select quantities.

Parameters:

  • z_slice (int) – Which z-slice of the array to plot.

  • subsample (int) – Number of voxels to display in X and Y

  • translate_x (int) – Number of voxels to translate image in x; meant for use with subsample

  • translate_y (int) – Number of voxels to translate image in y; meant for use with subsample

  • screen_euler (bool) – Suppress visualization of euler angles where vfrac < 0.05 or S < 0.05; intended to hilight edges

  • add_quiver (bool) – Adds lines to every voxel on the psi plot that indicate in-plane direction. Not recommended for resolutions larger than 128x128, best for resolutions 64x64 or lower.

  • quiver_bw (bool) – Intended to be used when add_quiver == True, when quiver_bw is True, the quiver arrows will be black and white instead of colored.

  • outputmat (list of ints) – Number of which materials to return

  • outputplot (list of strings) – Number of which plots to return, can include ‘vfrac’, ‘S’, ‘theta’, ‘psi’

  • outputaxes (bool) – If a plot is returned, include its axes

  • vfrac_range (list of tuples as [float, float]) – A custom range for vfrac colorbar

  • S_range (list of tuples as [float, float]) – A custom range for S colorbar

  • vfrac_cmap (str) – A custom substitution for vfrac colormap

  • S_cmap (str) – A custom substitution for vfrac colormap

  • runquiet (bool) – Boolean flag for running without plotting or outputting to console

  • batchMode (bool) – if true, prints console output and generates plots but doesnt show (provide exportDir for export)

  • plotstyle (str) – Use a light or dark background for plots. ‘dark’ - dark, ‘light’ - light

  • dpi (int) – The dpi at which the plot is generated. Per-material plot dimensions are 8.5” x 12.75”

  • exportDir (str, optional) – if provided, export directory to save any generated figures into, by default, will respect dpi and save as png, use exportParams to override

  • exportParams (dict, optional) – additional params to unpack into matplotlib.pyplot.savefig. Overrides existing params. ex: exportParams = {‘dpi’:600, format=’svg’}

Return type:

If outputmat and outputplot are correctly entered, will return an index list of images of the selected material and plot. Each list element will be a numpy array in RGB format that be displayed with imshow

NRSS.morphology.read_config(config_file)#
NRSS.morphology.read_material(filename)#
NRSS.morphology.wraps(wrapper: Callable[[P], T]) → Callable[[Callable[[P], T]], Callable[[P], T]]#

A decorator to preserve the original function’s docstring.

Parameters:

wrapper – The wrapper function.

Returns:

A decorator that preserves the original function’s docstring.

NRSS.morphology.write_hdf5(material_list, PhysSize, fname, MorphologyType=0, ordering='ZYX', author='NIST')#

Writes Euler or Vector Morphology format into CyRSoXS-compatible HDF5 file and returns the hdf5 filename

Parameters:

  • material_list (lists) – List of material lists. Euler Ex. [[Mat_1_Vfrac, Mat_1_S, Mat_1_Theta, Mat_1_Psi],[Mat_2_Vfrac, Mat_2_S, Mat_2_Theta, Mat_2_Psi]] Vector Ex. [[Mat_1_alignment, Mat_1_unaligned],[Mat_2_alignment, Mat_2_unaligned]]

  • PhysSize (float) – Voxel size

  • fname (str or path) – name of hdf5 file to write

  • MorphologyType (int) – 0 - Euler 1 - Vector

  • ordering (str) – String denoting the axes ordering. ‘ZYX’ or ‘XYZ’

  • author (str) – Name of author writing the morphology

Returns:

Name of hdf5 file written

Return type:

fname

NRSS.morphology.write_opts(optical_constants, material_num, path)#