# sas.sascalc.invariant package

## Submodules

## sas.sascalc.invariant.invariant module

This module implements invariant and its related computations.

author:

  Gervaise B. Alina/UTK

author:

  Mathieu Doucet/UTK

author:

  Jae Cho/UTK

author:

  Paul Butler/NIST/UD/UTK – refactor in 2020

class sas.sascalc.invariant.invariant.Extrapolator(data, model=None)

  Bases: `object`

  Extrapolate I(q) distribution using a given model

  fit(power=None, qmin=None, qmax=None)

    Fit data for \(y = ax + b\) return \(a\) and \(b\)

    Parameters:

      - power – a fixed, otherwise None

      - qmin – Minimum Q-value

      - qmax – Maximum Q-value

class sas.sascalc.invariant.invariant.Guinier(scale=1, radius=60)

  Bases: `Transform`

  class of type Transform that performs operations related to guinier function

  evaluate_model(x)

    return calculated I(q) for the model

    Calculates the Guinier expression \(F(x)= s * \exp\left(-(r x)^{2/3}\right)\)

  evaluate_model_errors(x)

    Returns the error on I(q) for the given array of q-values

    Parameters:

      x – array of q-values

  extract_model_parameters(constant, slope, dconstant=0, dslope=0)

    assign new value to the scale and the radius

  linearize_q_value(value)

    Transform the input q-value for linearization

    Parameters:

      value – q-value

    Returns:

      q*q

class sas.sascalc.invariant.invariant.InvariantCalculator(data, background=0, scale=1)

  Bases: `object`

  Compute invariant if data is given. Can provide volume fraction and surface area if the user provides Porod constant and contrast values.

  Precondition:

    the user must send a data of type DataLoader.Data1D the user provide background and scale values.

  Note:

    Some computations depends on each others.

  property background
  get_data()
    Returns:

      self._data

  get_extra_data_high(npts_in=None, q_end=10, npts=20)

    Returns the extrapolated data used for the high-Q invariant calculation. By default, the distribution will cover the data points used for the extrapolation. The number of overlap points is a parameter (npts_in). By default, the maximum q-value of the distribution will be Q_MAXIMUM, the maximum q-value used when extrapolating for the purpose of the invariant calculation.

    Parameters:

      - npts_in – number of data points for which the extrapolated data overlap

      - q_end – is the maximum value to uses for extrapolated data

      - npts – the number of points in the extrapolated distribution

  get_extra_data_low(npts_in=None, q_start=None, npts=20)

    Returns the extrapolated data used for the loew-Q invariant calculation. By default, the distribution will cover the data points used for the extrapolation. The number of overlap points is a parameter (npts_in). By default, the maximum q-value of the distribution will be the minimum q-value used when extrapolating for the purpose of the invariant calculation.

    Parameters:

      - npts_in – number of data points for which the extrapolated data overlap

      - q_start – is the minimum value to uses for extrapolated data

      - npts – the number of points in the extrapolated distribution

  get_extrapolation_power(range='high')
    Returns:

      the fitted power for power law function for a given extrapolation range

  get_qstar(extrapolation=None)

    Compute the invariant of the local copy of data.

    Parameters:

      extrapolation – string to apply optional extrapolation

    Return q_star:

      invariant of the data within data’s q range

    Warning:

      When using setting data to Data1D , the user is responsible of checking that the scale and the background are properly apply to the data

  get_qstar_high(high_q_limit=None)

    Compute the invariant for extrapolated data at high q range.

    Implementation:

        data = self._get_extra_data_high()
        return self._get_qstar()

    Return q_star:

      the invariant for data extrapolated at high q.

  get_qstar_low(low_q_limit=None)

    Compute the invariant for extrapolated data at low q range.

    Implementation:

        data = self._get_extra_data_low()
        return self._get_qstar()

    Return q_star:

      the invariant for data extrapolated at low q.

  get_qstar_with_error(extrapolation=None)

    Compute the invariant uncertainty. This uncertainty computation depends on whether or not the data is smeared.

    Parameters:

      extrapolation – string to apply optional extrapolation

    Returns:

      invariant, the invariant uncertainty

  get_surface(contrast, porod_const, extrapolation=None)

    Compute the specific surface from the data.

    Historically, Sv was computed with the invariant and the Porod constant so as not to have to know the contrast in order to get the Sv as:

        surface = (pi * V * (1- V) * porod_const) / q_star

    However, that turns out to be a pointless exercise since it also requires a knowledge of the volume fractions and from the volume fraction and the invariant the contrast can be calculated as:

        contrast**2 = q_star / (2 * pi**2 * V * (1- V))

    Thus either way, mathematically it is always identical to computing with only the contrast and the Porod Constant. up to and including SasView versions 4.2.2 and 5.0.1 the implementation used the traditional circular approach.

    Implementation:

        Given the above, as of SasView 4.3 and 5.0.2 we compute Sv simply
        from the Porod Constant and the contrast between the two phases as:

        surface = porod_const / (2 * pi contrast**2)

    Parameters:

      - contrast – contrast between the two phases

      - porod_const – Porod constant

      - extrapolation – string to apply optional extrapolation. This will only be needed if and when the contrast term is calculated from the invariant.

    Returns:

      specific surface

  get_surface_with_error(contrast, porod_const, extrapolation=None)

    As of SasView 4.3 and 5.0.3, the specific surface is computed directly from the contrast and porod_constant wich are currently user inputs with no option for any uncertainty so no uncertainty can be calculated. However we include the uncertainty computation for future use if and when these values get an uncertainty. This is given as:

        ds = sqrt[(s'_cp)**2 * dcp**2 + (s'_contrast)**2 * dcontrast**2]

    where s’_x is the partial derivative of S with respect to x

    which gives (this should be checked before using in anger):

        ds = sqrt((dporod_const**2 * contrast**2 + 4 * (porod_const *
                      dcontrast)**2) / (4 * pi**2 * contrast**6))

    We also assume some users will never enter a value for uncertainty so allow for None even when it is an option.

    Parameters:

      - contrast – contrast value eventually with the error

      - porod_const – porod constant value eventually with the error

      - extrapolation – string to apply optional extrapolation. This will only be needed if and when the contrast term is calculated from the invariant.

    Return s, ds:

      the surface, with its uncertainty

  get_volume_fraction(contrast, extrapolation=None)

    Compute volume fraction is deduced as follows:

        q_star = 2*(pi*contrast)**2* volume( 1- volume)
        for k = 10^(-8)*q_star/(2*(pi*|contrast|)**2)
        we get 2 values of volume:
             with   1 - 4 * k >= 0
             volume1 = (1- sqrt(1- 4*k))/2
             volume2 = (1+ sqrt(1- 4*k))/2

        q_star: the invariant value included extrapolation is applied
                     unit  1/A^(3)*1/cm
                q_star = self.get_qstar()

        the result returned will be 0 <= volume <= 1

    Parameters:

      - contrast – contrast value provides by the user of type float. contrast unit is 1/A^(2)= 10^(16)cm^(2)

      - extrapolation – string to apply optional extrapolation

    Returns:

      volume fraction

    Note:

      volume fraction must have no unit

  get_volume_fraction_with_error(contrast, extrapolation=None)

    Compute uncertainty on volume value as well as the volume fraction This uncertainty is given by the following equation:

        sigV = dV/dq_star * sigq_star

    so that:

        sigV = (k * sigq_star) /(q_star * math.sqrt(1 - 4 * k))

        for k = 10^(-8)*q_star/(2*(pi*|contrast|)**2)

    Notes:

    - 10^(-8) converts from cm^-1 to A^-1

    - q_star: the invariant, in cm^-1A^-3, including extrapolated values if they have been requested

    - dq_star: the invariant uncertainty

    - dV: the volume uncertainty

    The uncertainty will be set to -1 if it can’t be computed.

    Parameters:

      - contrast – contrast value

      - extrapolation – string to apply optional extrapolation

    Returns:

      V, dV = volume fraction, error on volume fraction

  property scale
  set_data(data)
  set_extrapolation(range, npts=4, function=None, power=None)

    Set the extrapolation parameters for the high or low Q-range. Note that this does not turn extrapolation on or off.

    Parameters:

      - range – a keyword set the type of extrapolation . type string

      - npts – the numbers of q points of data to consider for extrapolation

      - function – a keyword to select the function to use for extrapolation. of type string.

      - power – an power to apply power_low function

class sas.sascalc.invariant.invariant.PowerLaw(scale=1, power=4)

  Bases: `Transform`

  class of type transform that perform operation related to power_law function

  evaluate_model(x)

    given a scale and a radius transform x, y using a power_law function

  evaluate_model_errors(x)

    Returns the error on I(q) for the given array of q-values :param x: array of q-values

  extract_model_parameters(constant, slope, dconstant=0, dslope=0)

    Assign new value to the scale and the power

  linearize_q_value(value)

    Transform the input q-value for linearization

    Parameters:

      value – q-value

    Returns:

      \(\log(q)\)

class sas.sascalc.invariant.invariant.Transform

  Bases: `object`

  Define interface that need to compute a function or an inverse function given some x, y

  evaluate_model(x)

    Returns an array f(x) values where f is the Transform function.

  evaluate_model_errors(x)

    Returns an array of I(q) errors

  extract_model_parameters(constant, slope, dconstant=0, dslope=0)

    set private member

  get_allowed_bins(data)

    Goes through the data points and returns a list of boolean values to indicate whether each points is allowed by the model or not.

    Parameters:

      data – Data1D object

  linearize_data(data)

    Linearize data so that a linear fit can be performed. Filter out the data that can’t be transformed.

    Parameters:

      data – LoadData1D instance

  linearize_q_value(value)

    Transform the input q-value for linearization

## sas.sascalc.invariant.invariant_mapper module

This module is a wrapper to a map function. It allows to loop through different invariant objects to call the same function

sas.sascalc.invariant.invariant_mapper.get_qstar(inv, extrapolation=None)

  Get invariant value (Q*)

sas.sascalc.invariant.invariant_mapper.get_qstar_with_error(inv, extrapolation=None)

  Get invariant value with uncertainty

sas.sascalc.invariant.invariant_mapper.get_surface(inv, contrast, porod_const, extrapolation=None)

  Get surface with uncertainty

sas.sascalc.invariant.invariant_mapper.get_surface_with_error(inv, contrast, porod_const, extrapolation=None)

  Get surface with uncertainty

sas.sascalc.invariant.invariant_mapper.get_volume_fraction(inv, contrast, extrapolation=None)

  Get volume fraction

sas.sascalc.invariant.invariant_mapper.get_volume_fraction_with_error(inv, contrast, extrapolation=None)

  Get volume fraction with uncertainty

## Module contents