sas.sascalc.pr package

Submodules

sas.sascalc.pr.calc module

Converted invertor.c’s methods. Implements low level inversion functionality, with conditional Numba njit compilation.

sas.sascalc.pr.calc.dprdr(pars, d_max, r)

dP(r)/dr calculated from the expansion.

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • r – r-value.

Returns:

dP(r)/dr.

sas.sascalc.pr.calc.dprdr_calc(i, d_max, r)
sas.sascalc.pr.calc.int_pr(pars, d_max, nslice)

Integral of P(r).

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • nslice – nslice.

Returns:

Integral of P(r).

sas.sascalc.pr.calc.int_pr_square(pars, d_max, nslice)

Regularization term calculated from the expansion.

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • nslice – nslice.

Returns:

Regularization term calculated from the expansion.

sas.sascalc.pr.calc.iq(pars, d_max, q)

Scattering intensity calculated from the expansion.

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • q – q (vector).

Returns:

Scattering intensity from the expansion across all q.

sas.sascalc.pr.calc.iq_smeared(p, q, d_max, height, width, npts)

Scattering intensity calculated from the expansion, slit-smeared.

Parameters:

  • p – c-parameters.

  • q – q (vector).

  • height – slit_height.

  • width – slit_width.

  • npts – npts.

Returns:

Scattering intensity from the expansion slit-smeared across all q.

sas.sascalc.pr.calc.njit(*args, **kw)
sas.sascalc.pr.calc.npeaks(pars, d_max, nslice)

Get the number of P(r) peaks.

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • nslice – nslice.

Returns:

Number of P(r) peaks.

sas.sascalc.pr.calc.ortho(d_max, n, r)

Orthogonal Functions: B(r) = 2r sin(pi*nr/d)

Parameters:

  • d_max – d_max.

  • n –

Returns:

B(r).

sas.sascalc.pr.calc.ortho_derived(d_max, n, r)

First derivative in of the orthogonal function dB(r)/dr.

Parameters:

  • d_max – d_max.

  • n –

Returns:

First derivative in dB(r)/dr.

sas.sascalc.pr.calc.ortho_transformed(q, d_max, n)

Fourier transform of the nth orthogonal function.

Parameters:

  • q – q (vector).

  • d_max – d_max.

  • n –

Returns:

Fourier transform of nth orthogonal function across all q.

sas.sascalc.pr.calc.ortho_transformed_smeared(q, d_max, n, height, width, npts)

Slit-smeared Fourier transform of the nth orthogonal function. Smearing follows Lake, Acta Cryst. (1967) 23, 191.

Parameters:

  • q – q (vector).

  • d_max – d_max.

  • n –

  • height – slit_height.

  • width – slit_width.

  • npts – npts.

Returns:

Slit-smeared Fourier transform of nth orthogonal function across all q.

sas.sascalc.pr.calc.positive_errors(pars, err, d_max, nslice)

Get the fraction of the integral of P(r) over the whole range of r that is at least one sigma above 0.

Parameters:

  • pars – c-parameters.

  • err – error terms.

  • d_max – d_max.

  • nslice – nslice.

Returns:

The fraction of the integral of P(r) over the whole range of r that is at least one sigma above 0.

sas.sascalc.pr.calc.positive_integral(pars, d_max, nslice)

Get the fraction of the integral of P(r) over the whole range of r that is above 0. A valid P(r) is defined as being positive for all r.

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • nslice – nslice.

Returns:

The fraction of the integral of P(r) over the whole range of r that is above 0.

sas.sascalc.pr.calc.pr(pars, d_max, r)

P(r) calculated from the expansion

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • r – r-value to evaluate P(r).

Returns:

P(r).

sas.sascalc.pr.calc.pr_err(pars, err, d_max, r)

P(r) calculated from the expansion, with errors.

Parameters:

  • pars – c-parameters.

  • err – err.

  • r – r-value.

Returns:

[P(r), dP(r)].

sas.sascalc.pr.calc.reg_term(pars, d_max, nslice)

Regularization term calculated from the expansion.

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • nslice – nslice.

Returns:

Regularization term calculated from the expansion.

sas.sascalc.pr.calc.rg(pars, d_max, nslice)

R_g radius of gyration calculation

R_g**2 = integral[r**2 * p(r) dr] / (2.0 * integral[p(r) dr])

Parameters:

  • pars – c-parameters.

  • d_max – d_max.

  • nslice – nslice.

Returns:

R_g radius of gyration.

sas.sascalc.pr.distance_explorer module

Module to explore the P(r) inversion results for a range of D_max value. User picks a number of points and a range of distances, then get a series of outputs as a function of D_max over that range.

class sas.sascalc.pr.distance_explorer.DistExplorer(pr_state)

Bases: object

The explorer class

__call__(dmin=None, dmax=None, npts=10)

Compute the outputs as a function of D_max.

Parameters:

  • dmin – minimum value for D_max

  • dmax – maximum value for D_max

  • npts – number of points for D_max

__dict__ = mappingproxy({'__module__': 'sas.sascalc.pr.distance_explorer', '__firstlineno__': 43, '__doc__': '\nThe explorer class\n', '__init__': <function DistExplorer.__init__>, '__call__': <function DistExplorer.__call__>, '__static_attributes__': ('_default_max', '_default_min', 'pr_state'), '__dict__': <attribute '__dict__' of 'DistExplorer' objects>, '__weakref__': <attribute '__weakref__' of 'DistExplorer' objects>, '__annotations__': {}})
__doc__ = '\nThe explorer class\n'
__firstlineno__ = 43
__init__(pr_state)

Initialization.

Parameters:

pr_state – sas.sascalc.pr.invertor.Invertor object

__module__ = 'sas.sascalc.pr.distance_explorer'
__static_attributes__ = ('_default_max', '_default_min', 'pr_state')
__weakref__

list of weak references to the object

class sas.sascalc.pr.distance_explorer.Results

Bases: object

Class to hold the inversion output parameters as a function of D_max

__dict__ = mappingproxy({'__module__': 'sas.sascalc.pr.distance_explorer', '__firstlineno__': 20, '__doc__': '\nClass to hold the inversion output parameters\nas a function of D_max\n', '__init__': <function Results.__init__>, '__static_attributes__': ('bck', 'chi2', 'd_max', 'errors', 'iq0', 'osc', 'pos', 'pos_err', 'rg'), '__dict__': <attribute '__dict__' of 'Results' objects>, '__weakref__': <attribute '__weakref__' of 'Results' objects>, '__annotations__': {}})
__doc__ = '\nClass to hold the inversion output parameters\nas a function of D_max\n'
__firstlineno__ = 20
__init__()

Initialization. Create empty arrays and dictionary of labels.

__module__ = 'sas.sascalc.pr.distance_explorer'
__static_attributes__ = ('bck', 'chi2', 'd_max', 'errors', 'iq0', 'osc', 'pos', 'pos_err', 'rg')
__weakref__

list of weak references to the object

sas.sascalc.pr.invertor module

class sas.sascalc.pr.invertor.Invertor(logic: InversionLogic)

Bases: object

__dict__ = mappingproxy({'__module__': 'sas.sascalc.pr.invertor', '__firstlineno__': 22, '__init__': <function Invertor.__init__>, 'x': <property object>, 'y': <property object>, 'err': <property object>, 'npoints': <property object>, 'ny': <property object>, 'nerr': <property object>, 'is_valid': <function Invertor.is_valid>, 'clone': <function Invertor.clone>, 'lstsq': <function Invertor.lstsq>, 'invert': <function Invertor.invert>, 'iq': <function Invertor.iq>, 'get_iq_smeared': <function Invertor.get_iq_smeared>, 'pr': <function Invertor.pr>, 'pr_err': <function Invertor.pr_err>, 'basefunc_ft': <function Invertor.basefunc_ft>, 'oscillations': <function Invertor.oscillations>, 'get_peaks': <function Invertor.get_peaks>, 'get_positive': <function Invertor.get_positive>, 'get_pos_err': <function Invertor.get_pos_err>, 'rg': <function Invertor.rg>, 'iq0': <function Invertor.iq0>, 'accept_q': <function Invertor.accept_q>, 'check_for_zero': <function Invertor.check_for_zero>, 'estimate_numterms': <function Invertor.estimate_numterms>, 'estimate_alpha': <function Invertor.estimate_alpha>, '_get_matrix': <function Invertor._get_matrix>, '_get_invcov_matrix': <function Invertor._get_invcov_matrix>, '_get_reg_size': <function Invertor._get_reg_size>, '__static_attributes__': ('alpha', 'background', 'chi2', 'cov', 'dmax', 'elapsed', 'est_bck', 'info', 'logic', 'nfunc', 'noOfTerms', 'out', 'q_max', 'q_min', 'slit_height', 'slit_width', 'suggested_alpha'), '__dict__': <attribute '__dict__' of 'Invertor' objects>, '__weakref__': <attribute '__weakref__' of 'Invertor' objects>, '__doc__': None, '__annotations__': {'chi2': 'float', 'elapsed': 'float', 'suggested_alpha': 'float', 'nfunc': 'int', 'out': 'npt.NDArray[np.float64] | None', 'cov': 'npt.NDArray[np.float64] | None', 'background': 'float', 'info': 'dict', 'dmax': 'float', 'q_min': 'float', 'q_max': 'float', 'est_bck': 'bool', 'alpha': 'float', 'slit_height': 'float', 'slit_width': 'float', 'noOfTerms': 'int'}})
__doc__ = None
__firstlineno__ = 22
__init__(logic: InversionLogic)
__module__ = 'sas.sascalc.pr.invertor'
__static_attributes__ = ('alpha', 'background', 'chi2', 'cov', 'dmax', 'elapsed', 'est_bck', 'info', 'logic', 'nfunc', 'noOfTerms', 'out', 'q_max', 'q_min', 'slit_height', 'slit_width', 'suggested_alpha')
__weakref__

list of weak references to the object

_get_invcov_matrix(nfunc: int, nr: int, a_obj: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the inverse covariance matrix, defined as inv_cov = a_transposed x a.

Parameters:

  • nfunc – number of base functions.

  • nr – number of r-points used when evaluating reg term.

  • a_obj – A array to compute inverse covariance matrix of.

Returns:

inv_cov matrix.

_get_matrix(nfunc: int, nr: int) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

Returns A matrix and b vector for least square problem.

Parameters:

  • nfunc – number of base functions.

  • nr – number of r-points used when evaluating reg term.

Returns:

A, b - the A matrix and b vector for least square problem.

_get_reg_size(nfunc: int, nr: int, a_obj: ndarray[tuple[Any, ...], dtype[float64]]) → tuple[float, float]

Computes sum_sig and sum_reg of input array given.

Parameters:

  • nfunc – number of base functions.

  • nr – number of r-points used when evaluating reg term.

  • a_obj – Array to compute sum_sig and sum_reg of.

Returns:

Tuple of sum of signal and sum of regularization term, for the given array.

accept_q(q: ArrayLike) → bool | ndarray[tuple[Any, ...], dtype[bool]]

Check whether a q-value is within acceptable limits.

Returns:

Boolean or boolean array indicating acceptance. True where q is within [q_min, q_max].

basefunc_ft(d_max: float, n: int, q: float | ndarray[tuple[Any, ...], dtype[float64]]) → float64 | ndarray[tuple[Any, ...], dtype[float64]]

Returns the value of the nth Fourier transformed base function.

Parameters:

  • d_max – d_max.

  • n –

  • q – q, scalar or vector.

Returns:

nth Fourier transformed base function, evaluated at q, as a scalar or vector depending on q.

check_for_zero(x: ArrayLike) → bool

Check whether any value in the array is zero.

Parameters:

x – array to check.

Returns:

True if any value in x is zero, False otherwise.

clone() → Invertor

Returns a copy of the invertor.

property err: ndarray[tuple[Any, ...], dtype[float64]]

Returns the error values of the data to be inverted.

estimate_alpha(nfunc: int) → tuple[float, str | None, float]

Returns a reasonable guess for the regularization constant, alpha.

Parameters:

nfunc – number of terms to use in the expansion.

Returns:

alpha, message, elapsed where, alpha is the estimate for alpha, message is a message for the user, elapsed is the computation time

estimate_numterms(isquit_func: Callable | None = None)

Returns a reasonable guess for the number of terms.

Parameters:

isquit_func – reference to thread function to call to check whether the computation needs to be stopped.

Returns:

number of terms, alpha, message.

get_iq_smeared(pars: ArrayLike, q: ArrayLike) → float64 | ndarray[tuple[Any, ...], dtype[float64]]

Calculates the slit-smeared scattering intensity I(q) from the expansion coefficients.

Parameters:

  • pars – c-parameters

  • q – q, scalar or vector.

Returns:

I(q), either scalar or vector depending on q.

get_peaks(pars: ArrayLike) → int

Returns the number of peaks in the output P(r) distribution for the given set of coefficients.

Parameters:

pars – c-parameters.

Returns:

number of P(r) peaks.

get_pos_err(pars: ArrayLike, pars_err: ArrayLike) → float

Returns the fraction of P(r) that is 1 standard deviation above zero over the full range of r for the given set of coefficients.

Parameters:

  • pars – c-parameters.

  • pars_err – pars_err.

Returns:

fraction of P(r) that is positive.

get_positive(pars: ArrayLike) → float

Returns the fraction of P(r) that is positive over the full range of r for the given set of coefficients.

Parameters:

pars – c-parameters.

Returns:

fraction of P(r) that is positive.

invert(nfunc: int = 10, nr: int = 20) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

Perform inversion to P(r).

This is a thin wrapper around lstsq() that handles temporary background subtraction when est_bck is disabled.

See \(lstsq\) for details of the linear system construction (including regularization) and the least-squares solve.

Parameters:

  • nfunc – number of base functions to use.

  • nr – number of r points to evaluate the 2nd derivative at for the reg. term.

Returns:

c_out, c_cov - the coefficients with covariance matrix.

iq(pars: ArrayLike, q: ArrayLike) → float64 | ndarray[tuple[Any, ...], dtype[float64]]

Calculates the scattering intensity I(q) from the expansion coefficients.

Parameters:

  • pars – c-parameters

  • q – q, scalar or vector.

Returns:

I(q), either scalar or vector depending on q.

iq0(pars: ArrayLike) → float

Returns the value of I(q=0).

Parameters:

pars – c-parameters.

Returns:

I(q=0)

is_valid() → bool

Check whether the number of x, y, and error values are all the same.

lstsq(nfunc: int = 5, nr: int = 20) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

The problem is solved by posing the problem as Ax = b, where x is the set of coefficients we are looking for.

Npts is the number of points.

In the following, i refers to the ith base function coefficient. The matrix has its entries j in its first Npts rows set to

A[i][j] = (Fourier transformed base function for point j)

We then choose a number of r-points, n_r, to evaluate the second derivative of P(r) at. This is used as our regularization term. For a vector r of length n_r, the following n_r rows are set to

A[i+Npts][j] = (2nd derivative of P(r), d**2(P(r))/d(r)**2,
evaluated at r[j])

The vector b has its first Npts entries set to

b[j] = (I(q) observed for point j)

The following n_r entries are set to zero.

The result is found by using scipy.linalg.basic.lstsq to invert the matrix and find the coefficients x. If the result does not allow us to compute the covariance matrix, a matrix filled with zeros will be returned.

Parameters:

  • nfunc – number of base functions to use.

  • nr – number of r points to evaluate the 2nd derivative at for the reg. term.

Returns:

c_out, c_cov - the coefficients with covariance matrix

property nerr: int

Returns the number of error values in the data to be inverted.

property npoints: int

Returns the number of x values in the data to be inverted.

property ny: int

Returns the number of y values in the data to be inverted.

oscillations(pars: ArrayLike) → float

Returns the value of the oscillation figure of merit for the given set of coefficients. For a sphere, the oscillation figure of merit is 1.1.

Parameters:

pars – c-parameters.

Returns:

oscillation figure of merit.

pr(pars: ArrayLike, r: ArrayLike) → float64 | ndarray[tuple[Any, ...], dtype[float64]]

Evaluates P(r).

Parameters:

  • pars – c-parameters.

  • r – r-value to evaluate P(r) at.

Returns:

P(r).

pr_err(c: ArrayLike, c_cov: ArrayLike | None, r: ArrayLike) → tuple[float64, float64]

Returns the value of P(r) for a given r, and base function coefficients, with error.

Parameters:

  • c – base function coefficients.

  • c_cov – covariance matrix of the base function coefficients. If None, no error will be calculated.

  • r – r-value(s) at which P(r) is evaluated.

Returns:

(P(r), dP(r))

rg(pars: ArrayLike) → float

Returns the value of the radius of gyration, Rg.

Parameters:

pars – c-parameters.

Returns:

Rg, the radius of gyration.

property x: ndarray[tuple[Any, ...], dtype[float64]]

Returns the x values of the data to be inverted.

property y: ndarray[tuple[Any, ...], dtype[float64]]

Returns the y values of the data to be inverted.

sas.sascalc.pr.num_term module

class sas.sascalc.pr.num_term.NTermEstimator(invertor)

Bases: object

__dict__ = mappingproxy({'__module__': 'sas.sascalc.pr.num_term', '__firstlineno__': 12, '__doc__': '\n    ', '__init__': <function NTermEstimator.__init__>, 'is_odd': <function NTermEstimator.is_odd>, 'sort_osc': <function NTermEstimator.sort_osc>, 'median_osc': <function NTermEstimator.median_osc>, 'get0_out': <function NTermEstimator.get0_out>, 'ls_osc': <function NTermEstimator.ls_osc>, 'compare_err': <function NTermEstimator.compare_err>, 'num_terms': <function NTermEstimator.num_terms>, '__static_attributes__': ('alpha_list', 'dataset', 'err_list', 'invertor', 'isquit_func', 'mess_list', 'nterm_max', 'nterm_min', 'osc_list'), '__dict__': <attribute '__dict__' of 'NTermEstimator' objects>, '__weakref__': <attribute '__weakref__' of 'NTermEstimator' objects>, '__annotations__': {}})
__doc__ = '\n    '
__firstlineno__ = 12
__init__(invertor)
__module__ = 'sas.sascalc.pr.num_term'
__static_attributes__ = ('alpha_list', 'dataset', 'err_list', 'invertor', 'isquit_func', 'mess_list', 'nterm_max', 'nterm_min', 'osc_list')
__weakref__

list of weak references to the object

compare_err()
get0_out()
is_odd(n)
ls_osc()
median_osc()
num_terms(isquit_func=None)
sort_osc()
sas.sascalc.pr.num_term.load(path)

Module contents

P(r) inversion for SAS