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.

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

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 pandas and numpy for data storage, organization, and manipulation and matplotlib for diagonostic visualization “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()

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, index=0, 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 invidual DataFrame.

Will append the DataFrame to the df_inviduals attribute DataFrame and also convert to $S(Q)$ and add to the df_sq_individuals attribute DataFrame.

Parameters:	info (dict) – Dict with information for dataset (filename, manipulations, etc.) index (int) – Index of the added reciprocal space function dataset 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$ )

add_to_dataframe(x, y, df, title)[source]¶

Takes X,Y dataset and adds it to the given Datframe df, with the given title. Utility function for updating the class DataFrames.

Parameters:	x (numpy.array or list) – X-axis vector y (numpy.array or list) – Y-axis vector df (pandas.DataFrame) – DataFrame to append (x, y) pair to as a column title (str) – The title of the column in the DataFrame
Returns:	DataFrame with X,Y data appended with given title
Return type:	pandas.DataFrame

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)[source]¶

Performs the Fourier transform using the Lorch dampening correction on the merged $S(Q)$ from the df_sq_master DataFrame 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” DataFrames
Saved to files via the stem_name
(optional) Plotted for diagnostics
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
Returns:	Returns a tuple with $r$ and selected real space function
Return type:	tuple of numpy.array

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

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 = None¶: 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

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

df_gr_master¶

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

Getter:	Returns the current “master” real space function DataFrame
Setter:	Sets the “master” real space function DataFrame
Type:	pandas.DataFrame

df_individuals¶

The DataFrame 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 DataFrame
Setter:	Sets the DataFrame
Type:	pandas.DataFrame

df_sq_individuals¶

The DataFrame for the $S(Q)$ generated from each input reciprocal space dataset in df_individuals class DataFrame.

Getter:	Returns the current individual $S(Q)$ reciprocal space functions DataFrame
Setter:	Sets the DataFrame
Type:	pandas.DataFrame

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

dr¶

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

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

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

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 = None¶: 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 df_sq_master DataFrame 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” DataFrames
Saved to files via the stem_name
(optional) Plotted for diagnostics
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

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 transfomed, 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

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

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

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

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

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

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 df_individuals class DataFrame into a single, merged recirocal space function. Stores the S(Q) result in df_sq_master class DataFrame.

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 }
        }

…

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

plot_flag¶

This sets the option for matplotlib to display diagnostic plots or not.

Getter:	Return bool of flag
Setter:	Set whether the diagnostics are displayed or not
Type:	bool

plot_gr(xlabel='r', ylabel='G(r)', title='', exclude_list=None)[source]¶

Helper function to plot the real space functions in the “master” DataFrame, df_gr_master.

Parameters:	xlabel (str) – X-axis label ylabel (str) – Y-axis label title (str) – Title of plot exclude_list (list of str) – List of titles of columns in DataFrame to exclude from plot

plot_merged_sq()[source]¶: Helper function to multiplot the individual real space functions in the df_individuals DataFrame, these functions as individual $S(Q)$ , the merged $S(Q)$ from the individual functions, and $Q[S(Q)-1]$ .

plot_sq(xlabel='Q', ylabel='S(Q)', title='', exclude_list=None)[source]¶

Helper function to plot the $S(Q)$ functions in the “master” DataFrame, df_sq_master.

Parameters:	xlabel (str) – X-axis label ylabel (str) – Y-axis label title (str) – Title of plot exclude_list (list of str) – List of titles of columns in DataFrame to exclude from plot

plot_summary_gr()[source]¶: Helper function to multiplot the real space functions during processing and the $G_{Keen Version}(Q)$ function.

plot_summary_sq()[source]¶: Helper function to multiplot the reciprocal space functions during processing and the $F(Q)$ function.

plotting_kwargs¶

The plot settings for visualization via matplotlib

Getter:	Returns the current arguments
Setter:	Sets the plotting kwargs
Type:	dict

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

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

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

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 as DataFrames to the df_inviduals attribute DataFrame and also convert to $S(Q)$ and add to the df_sq_individuals attribute DataFrame in add_dataset method via read_dataset method.

read_dataset(info, xcol=0, ycol=1, 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.

Will append the DataFrame to the df_inviduals attribute DataFrame and also convert to $S(Q)$ and add to the df_sq_individuals attribute DataFrame in add_dataset method.

Parameters:	info (dict) – Dict with information for dataset (filename, manipulations, etc.) xcol (int) – The column in the data file that contains the X-axis ycol (int) – The column in the data file that contains the Y-axis sep (raw string) – Separator for the file used by pandas.read_csv skiprows (int) – Number of rows to skip. Passed to pandas.read_csv

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

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

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

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

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

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 df_sq_master DataFrame to generate the desired real space function with this correction. The results for real space are: saved back to the gr_master DataFrame

transformer = None¶: 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

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

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