StoG

This module defines the StoG class that tries to replicate the previous stog program behavior in an organized fashion with the ability to re-construct the workflow.

exception pystog.stog.NoInputFilesException[source]

Bases: Exception

Exception when no files are given to process

class pystog.stog.StoG(**kwargs)[source]

Bases: object

The StoG class is used to put together the Converter, Transformer, and FourierFilter class functionalities to reproduce the original stog Fortran program behavior. This class is meant to put together the functionality of the classes into higher-level calls to construct workflows for merging and processing multiple recprical space functions into a final output real space function.

This pythonized-version of the original Fortran stog uses numpy for data storage, organization, and manipulation “under the hood”.

Examples:

>>> import json
>>> from pystog import StoG
>>> with open("../data/examples/argon_pystog.json", 'r') as f:
>>>     kwargs = json.load(f)
>>> stog = StoG(**kwargs)
>>> stog.read_all_data()
>>> stog.merge_data()
>>> stog.write_out_merged_data()

property GKofR_title

The title of the $G_{Keen Version}(r)$ with all corrections applied.

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

add_dataset(info, yscale=1.0, yoffset=0.0, xoffset=0.0, ydecimals=16, **kwargs)[source]

Takes the info with the dataset and manipulations, such as scales, offsets, cropping, etc., and creates an individual numpy array for the pattern.

Parameters:

info (dict) – Dict with information for dataset (filename, manipulations, etc.)
yscale (float) – Scale factor for the Y data (i.e. $S(Q)$ , $F(Q)$ , etc.)
yoffset (float) – Offset factor for the Y data (i.e. $S(Q)$ , $F(Q)$ , etc.)
xoffset – Offset factor for the X data (i.e. $Q$ )

append_file(new_file)[source]

Appends a file to the file list

Parameters:: new_file (str) – New file name to append
Returns:: File list with appended new_file
Return type:: list

apply_lorch(q, sq, r, dsq=None)[source]

Performs the Fourier transform using the Lorch dampening correction on the merged $S(Q)$ from the sq_master dictionary to generate the desired real space function with this correction. The results from both reciprocal space and real space are:

Saved back to the respective “master” dictionaries
Saved to files via the stem_name
Returned from function

Parameters:

q (numpy.array or list) – $Q$ -space vector
sq (numpy.array or list) – $S(Q)$ vector
r (numpy.array or list) – $r$ -space vector
dsq (numpy.array or list, optional) – $S(Q)$ uncertainty vector

Returns:

Returns a tuple with $r$ and selected real space function

Return type:

tuple of numpy.array

static apply_scales_and_offset(x, y, dy=None, yscale=1.0, yoffset=0.0, xoffset=0.0)[source]

Applies scales to the Y-axis and offsets to both X and Y axes.

Parameters:

x (numpy.array or list) – X-axis data
y (numpy.array or list) – Y-axis data
yscale (float) – Y-axis scale factor
yoffset (float) – Y-axis offset factor
xoffset (float) – X-axis offset factor

Returns:

X and Y vectors after scales and offsets applied

Return type:

numpy.array pair

property bcoh_sqrd

The average coherent scattering length, squared: $\langle b_{coh} \rangle^2$ = $( \sum_{i} c_{i} b_{coh,i} ) ( \sum_{i} c_{i} b^*_{coh,i} )$ where the subscript $i$ implies for atom type $i$ , $c_{i}$ is the concentration of $i$ , $b_{coh,i}$ is the coherent scattering length of $i$ , and $b^*_{coh,i}$ is the complex coherent scattering length of $i$

The real part of the $b_{coh,i}$ term can be found from the Coh b column of the NIST neutron scattering length and cross section table found here: https://www.ncnr.nist.gov/resources/n-lengths/list.html

Units are in $fm$ in the table for the $b_{coh,i}$ term. Thus, $\langle b_{coh} \rangle^2$ has units of $fm^2$ (and what PyStoG expects). NOTE: 100 $fm^2$ == 1 $barn$ .

Getter:: Return the value of $\langle b_{coh} \rangle^2$
Setter:: Set the value for $\langle b_{coh} \rangle^2$
Type:: float

property btot_sqrd

The average coherent scattering length, squared: $\langle b_{tot}^2 \rangle$ = $\sum_{i} c_{i} b_{tot,i}^2$ = $\frac{1}{4 \pi} \sum_i c_{i} \sigma_{tot,i}$ where the subscript $i$ implies for atom type $i$ , $c_{i}$ is the concentration of $i$ and $\sigma_{tot,i}$ is the total cross-section of $i$

The real part of the $b_{coh,i}$ term can be found from the Scatt xs column of the NIST neutron scattering length and cross section table found here: https://www.ncnr.nist.gov/resources/n-lengths/list.html

Units are in $barn$ (=100 $fm^2$ ) in the table for the $\sigma_{tot,i}$ term. Thus, you must multiply $\sum_{i} c_{i} b_{tot,i}^2$ by 100 to go from $barn$ to $fm^2$ (what PyStoG expects).

Getter:: Return the value of $\sum_{i} c_{i} b_{tot,i}^2$
Setter:: Set the value for $\sum_{i} c_{i} b_{tot,i}^2$
Type:: float

converter: The converter attribute defines the Converter which is used to do all inner conversions necessary to go from the input reciprocal space functions, produce diagnostics for the selected real space functions, and finally output the desired real space function Must of type pystog.converter.Converter

property density

The number density used (atoms/ $\AA^{3}$ ) used for the $\rho_{0}$ term in the equations

Getter:: Return the density value
Setter:: Set the density value
Type:: float

property dgr_master

The “master” dictionary for the real space function uncertainties that are generated for each processing step.

Getter:: Returns the current “master” real space uncertainty dictionary generated up to the current step in the workflow.
Setter:: Sets the “master” real space uncertainty dictionary
Type:: dict[str:numpy.ndarray]

property dr

The real space function X axis data, $r$ -space vector

Getter:: Return the $r$ vector
Setter:: Set the $r$ vector
Type:: numpy.array

property dsq_master

The “master” dictionary for the $S(Q)$ uncertainties that are generated for each processing step.

Getter:: Returns the current “master” $S(Q)$ uncertainty dictionary generated up to the current step in the workflow.
Setter:: Sets the “master” $S(Q)$ uncertainty dictionary
Type:: dict[str:numpy.ndarray]

extend_file_list(new_files)[source]

Extend the file list with a list of new files

Parameters:: new_files – List of new files
Returns:: File list extended by new_files
Return type:: list

extract(hdf_file, path, index=None)[source]

extract_path_from_title(hdf_file, title, title_path='title', wksp_path='workspace')[source]

extract_xy(hdf_file, xpath, ypath, epath=None, **kwargs)[source]

property files

The files that contain the reciprocal space data to merge together.

Getter:: Current list of files to merge
Setter:: Set the list of files to merg
Type:: list

filter: The filter attribute defines the FourierFilter which is used to do all Fourier filtering if the fourier_filter_cutoff attribute is supplied. Must of type pystog.fourier_filter.FourierFilter

fourier_filter()[source]

Performs the Fourier filter on the sq_master pattern to generate the desired real space function with this correction. The results from both reciprocal space and real space are:

Saved back to the respective “master” dictionaries
Saved to files via the stem_name
Returned from function

Returns:: Returns a tuple with $r$ , the selected real space function, $Q$ , and $S(Q)$ functions
Return type:: tuple of numpy.array

property fourier_filter_cutoff

This sets the cutoff in $r$ -space for the Fourier filter. The minimum is automatically 0.0. Thus, from 0.0 to fourier_filter_cutoff is reverse transformed, subtracted in reciprocal space, and then the difference is back-transformed.

See pystog.fourier_filter.FourierFilter for more information.

Getter:: Return currently set cutoff value
Setter:: Set cutoff value
Type:: float

property fq_title

The title of the $F(Q)$ function after merging and a fourier filter correction.

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property gr_ft_title

The title for the real space function after both merging and a fourier filter correction

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property gr_lorch_title

The title for the real space function with the lorch correction

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property gr_master

The “master” dictionary for the real space functions that are generated for each processing step.

Getter:: Returns the current “master” real space functions dictionary generated up to the current step in the workflow.
Setter:: Sets the “master” real space function dictionary
Type:: dict[str:numpy.ndarray]

property gr_title

The title of the real space function directly after merging the reciprocal space functions without any further corrections.

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property lorch_flag

This sets the option to perform the Lorch dampening correction for the $Q$ range. Generally, will help reduce Fourier “ripples”, or AKA “Gibbs phenomenon”, due to discontinuity at $Q_{max}$ if the reciprocal space function is not at the $Q -> \infty$ limit. Yet, will also broaden real space function peaks, possibly dubiously.

See pystog.transformer.Transformer fourier_transform and _low_x_correction methods for where this is applied.

Getter:: Return bool of applying the Lorch dampening correction
Setter:: Set whether the correction is applied or not
Type:: bool

property low_q_correction

This sets the option to perform a low- $Q$ correction for the omitted $Q$ range.

See pystog.transformer.Transformer _low_x_correction method for more information.

Getter:: Return bool of applying the low- $Q$ correction
Setter:: Set whether the correction is applied or not
Type:: bool

merge_data()[source]

Merges the reciprocal space data stored in the reciprocal_individuals numpy array into a single, merged recirocal space function. Stores the S(Q) result in sq_master dictionary using sq_title (default: “S(Q) Merged”).

Also, converts this merged $S(Q)$ into $Q[S(Q)-1]$ via the Converter class and applies any modification specified in merged_opts dict attribute, specified by the ‘Q[S(Q)-1]’ key of the dict. If there is modification, this modified $Q[S(Q)-1]$ will be converted to $S(Q)$ and replace the $S(Q)$ directly after merge.

Example dict of merged_opts for scaling of $S(Q)$ by 2 and then offsetting $Q[S(Q)-1]$ by 5:

{
    "Merging": {
        "Y": {
            "Offset": 0.0,
            "Scale": 2.0
        },
        "Q[S(Q)-1]": {
            "Y": "Offset": 5.0,
            "Scale": 1.0
        }
    }
}

property merged_opts

This sets the options to perform after merging the reciprocal space functions together, such as an overall offset and scale.

Getter:: Return the options currently set
Setter:: Set the options for the merged pattern
Type:: dict

property q_master

The “master” dictionary for the domain :math:Q` of the reciprocal space functions that are generated for each processing step.

Getter:: Returns the current “master” $Q$ reciprocal space functions dictionary generated up to the current step in the workflow.
Setter:: Sets the “master” $Q$ dictionary
Type:: dict[str:numpy.ndarray]

property qmax

The $Q_{max}$ value to use for the Fourier transforms (from recirocal space -> real space). This overrides xmax attribute if qmax < xmax.

Getter:: Returns the current set value
Setter:: Set the qmax value for the Fourier transforms
Type:: float

property qmin

The $Q_{min}$ value to use for the Fourier transforms (from recirocal space -> real space). This overrides xmin attribute if xmin < qmin.

Getter:: Returns the current set value
Setter:: Set the $Q_{min}$ value for the Fourier transforms
Type:: float

property qsq_minus_one_title

The title of the $Q[S(Q)-1]$ function directly after merging the reciprocal space functions without any further corrections.

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property r_master

The “master” dictionary for the domain :math:r` of the real space functions that are generated for each processing step.

Getter:: Returns the current “master” $r$ real space functions dictionary generated up to the current step in the workflow.
Setter:: Sets the “master” $r$ dictionary
Type:: dict[str:numpy.ndarray]

property rdelta

The $\Delta r$ for the $r$ -space vector

Getter:: Return $\Delta r$ value
Setter:: Set the $\Delta r$ value and update $r$ -space vector via the dr attribute
Type:: value

read_all_data(**kwargs)[source]

Reads all the data from the files attribute Uses the read_dataset method on each file.

Will append all datasets to the numpy storage array, reciprocal_individuals, and also convert to $S(Q)$ and add to the sq_individuals numpy storage array in add_dataset method via read_dataset method.

read_all_nexus_file_banks()[source]

read_dataset(info, xcol=0, ycol=1, dycol=2, sep='\\s+', skiprows=2, **kwargs)[source]

Reads an individual file and uses the add_dataset method to apply all dataset manipulations, such as scales, offsets, cropping, etc.

Parameters:

info (dict) – Dict with information for dataset (filename, manipulations, etc.)
xcol (int) – Column in data file for X-axis
ycol (int) – Column in data file for Y-axis
dycol (int) – Column in data file for Y uncertainty
sep (raw string) – Separator for the file used by numpy.loadtxt
skiprows (int) – Number of rows to skip. Passed to numpy.loadtxt

read_nexus_file_by_bank(nexus_file, bank, title, err=False, **kwargs)[source]: Reads an individual file bank by bank and uses the extract_xy to handle extraction and extract_path_from_title to obtain coord paths

property real_space_function

The real space function to use throughoutt the processing

Getter:: Returns the currently select real space function
Setter:: Set the selected real space function and updates other title attributes that rely on this in their name.
Type:: str

property reciprocal_individuals

The storage array for the input reciprocal space functions loaded from files and with the loading processing from add_dataset class method.

Getter:: Returns the current individual, input reciprocal space functions numpy array. The dimensions is $3 x N*M$ where N is the number of patterns stored and M is the length of the patterns.
Setter:: Sets the numpy array
Type:: numpy.ndarray

property rmax

The $R_{max}$ valuefor the $r$ -space vector

Getter:: Return $R_{max}$ value
Setter:: Set the $R_{max}$ value and update $r$ -space vector via the dr attribute
Type:: value

property rmin

The $R_{min}$ valuefor the $r$ -space vector

Getter:: Return $R_{min}$ value
Setter:: Set the $R_{min}$ value and update $r$ -space vector via the dr attribute
Type:: value

save_xy(filename, xdata, ydata, edata=None)[source]

property sq_ft_title

The title of the $S(Q)$ function after merging and a fourier filter correction.

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property sq_individuals

The storage array for the $S(Q)$ generated from each input reciprocal space dataset in reciprocal_individuals array.

Getter:: Returns the current individual $S(Q)$ reciprocal space functions numpy array. The dimensions is $3 x N*M$ where N is the number of patterns stored and M is the length of the patterns.
Setter:: Sets the numpy array
Type:: numpy.ndarray

property sq_master

The “master” dictionary for the $S(Q)$ reciprocal space functions that are generated for each processing step.

Getter:: Returns the current “master” $S(Q)$ reciprocal space functions dictionary generated up to the current step in the workflow.
Setter:: Sets the “master” $S(Q)$ function dictionary
Type:: dict[str:numpy.ndarray]

property sq_title

The title of the $S(Q)$ function directly after merging the reciprocal space functions without any further corrections.

Getter:: Returns the current title for this function
Setter:: Sets the title for this function
Type:: str

property stem_name

A stem name to prefix for all output files. Replicates the stog Fortran program behavior.

Getter:: Return the currently set stem name
Setter:: Set the stem name for output files
Type:: str

transform_merged()[source]: Performs the Fourier transform on the merged sq_master pattern to generate the desired real space function with this correction. The results for real space are: the domain is saved to the r_master dictionary and the range is saved to the gr_master dictionary, with both using the gr_title for the key of the dictionaries.

transformer: The transformer attribute defines the Transformer which is used to do all Fourier transforms necessary from reciprocal space to real space and vice versa. Must of type pystog.transformer. Transformer

write_out_ft(filename=None)[source]

Helper function for writing out the Fourier filter correction.

Parameters:: filename (str) – Filename to write to

write_out_ft_gr(filename=None)[source]

Helper function for writing out the Fourier filtered real space function

Parameters:: filename (str) – Filename to write to

write_out_ft_sq(filename=None)[source]

Helper function for writing out the Fourier filtered $S(Q)$

Parameters:: filename (str) – Filename to write to

write_out_lorched_gr(filename=None)[source]

Helper function for writing out the Lorch dampened real space function

Parameters:: filename (str) – Filename to write to

write_out_merged_gr(filename=None)[source]

Helper function for writing out the merged real space function

Parameters:: filename (str) – Filename to write to

write_out_merged_sq(filename=None)[source]

Helper function for writing out the merged $S(Q)$

Parameters:: filename (str) – Filename to write to

write_out_rmc_fq(filename=None)[source]

Helper function for writing out the output $F(Q)$

Parameters:: filename (str) – Filename to write to

write_out_rmc_gr(filename=None)[source]

Helper function for writing out the output $G_{Keen Version}(Q)$

Parameters:: filename (str) – Filename to write to

property xmax

The maximum X value of all datasets to use for Fourier transforms (from recirocal space -> real space)

Getter:: Returns the current set value
Setter:: Set the xmax value for the Fourier transforms
Type:: float

property xmin

The minimum X value of all datasets to use for Fourier transforms (from recirocal space -> real space)

Getter:: Returns the current set value
Setter:: Set the xmin value for the Fourier transforms
Type:: float