Target Functions (Low Level API)#

targetFunctions.reflectivityCalculation(problemStruct, controls)#

Compute the reflectivity and SLD curves for a given model using the Abeles matrix formalism.

Main entry point into the reflectivity calculation for the toolbox. This is the main function that is called by any of the minimisers or analysis tools from the rest of the toolbox.

The main job of this function is to decide which type of calculation (i.e. ‘Target function’) is required, and call the relevant routines. Different model types are specified in sub functions. The types of available target functions are:

  • normal - The main basic target function type, for non polarised neutrons (or x-rays) with non-absorbing samples.

  • domains - Target function for samples consisting of domains which are larger than the beam lateral coherence length.

Parameters:
  • problemStruct (struct) – The project class as a struct (generated via parseClassToStructs)

  • controls (struct) – The controls struct (generated via parseClassToStructs)

Returns:

result – The results of the calculation.

Return type:

struct

Common Functions#

targetFunctions.common.backSort(qzshiftIndex, scalefactorIndex, bulkInIndex, bulkOutIndex, qzshiftValues, scalefactorValues, bulkInValues, bulkOutValues)#

Distributes the background and shift values among the different contrasts

INPUTS:
  • qzshiftIndex: Index of the qzshift value associated with this contrast

  • scalefactorIndex: Index of the scalefactor value associated with this contrast

  • bulkInIndex: Index of the BulkIn value associated with this contrast

  • bulkOutIndex: Index of the BulkOut value associated with this contrast

  • qzshiftValues: List of all qzshift values

  • scalefactorValues: List of all scalefactor values

  • bulkInValues: List of all bulk In values

  • bulkOutValues: List of all bulk Out values

OUTPUTS:
  • qzshift: qzshift value for this contrast

  • scalefactor: scalefactor value for this contrast

  • bulkIn: bulk In value for this contrast

  • bulkOut: bulk Out value for this contrast

targetFunctions.common.constructBackground(backgroundType, backgroundParamIndices, shiftedData, customFiles, backgroundParamValues, simulationXData, dataIndices)#

Apply background parameters to the background.

For function backgrounds, this means running the function using the defined parameters. For data and constant backgrounds, this means taking any predefined background data and adding any supplied parameters.

targetFunctions.common.constructResolution(resolutionType, resolutionParamIndex, shiftedData, customFiles, resolutionParamValues, simulationXData, dataIndices)#

Apply resolution parameters to the resolution.

For data and constant resolutions, this means taking any predefined resolution data and adding any supplied parameters.

targetFunctions.common.getFitNames(problemStruct)#

Note that this order of parameters fields is hard-coded by this routine, packParams, packParamsPriors, and unpackParams

targetFunctions.common.makeSimulationRange(data, simulationLimits)#

Construct the x data for the simulation. This consists of the x data from the supplied data, plus additional points above and below the data range as necessary.

targetFunctions.common.shiftData(scalefactor, qzshift, dataPresent, data, dataLimits, simulationLimits)#

Shifts the data according to scale factor. If there is no data, makes x-data over the simulation range.

INPUTS:
  • scalefactor: problemStruct.scalefactors

  • qzshift: problemStruct.qzshifts

  • dataPresent: problemStruct.dataPresent

  • data: problemStruct.data

  • dataLimits: problemStruct.dataLimits

  • simulationLimits: problemStruct.simulationLimits

OUTPUTS:
  • shiftedData: Data shifted using given scale factor

targetFunctions.common.costFunctions.chiSquared(shiftedData, reflectivity, nParams)#

Chi-squared function is used to evaluate the goodness of fit. It is a measure of the difference between the observed and expected reflectivity.

targetFunctions.common.groupLayers.allocateLayersForContrast(layerIndices, layerValues)#

Decide which layers are needed for a particular contrast. This function takes the master array of all layers and extracts which parameters are required for a particular contrast.

INPUTS:

layerValues - List of all the available layers layerIndices - Array detailing which layers are required for this contrast

targetFunctions.common.groupLayers.allocateParamsToLayers(paramValues, layersDetails)#

Allocates parameters from the parameter array to the correct layers

This function takes the list of all layers in ‘layersDetails’, then loops over all the layers, putting in the correct parameter value from the parameters array into each layer in the ‘layerValues’ cell array

targetFunctions.common.groupLayers.groupLayersMod(layers, subRoughs, geometry)#

Arrange layers according to geometry. The paratt calculation proceeds through the z,rho,rough stack; and the parameter ‘ssub’ is the final roughness encountered.

  • For air/liquid ‘ssub’ is therefore the substrate roughness.

  • For solid/liquid, the substrate roughness is the first roughness encountered, and ‘ssub’ is then the roughness of the outermost layer.

USAGE:

[outLayers, ssubs] = groupLayersMod(resampledLayers,subRoughs,geometry)
INPUTS:
  • layers: List of layer values for this contrast.

  • subRoughs: Double of substrate roughness for this contrast.

  • geometry: ‘Air / Liquid (or solid)’ or ‘Solid / Liquid’

Outputs:
  • outputLayers: Layers parameter values for this contrast.

  • ssubs: vector of ssub values.

Normal Target Functions (normalTF)#

targetFunctions.normalTF.coreLayersCalculation(contrastLayers, roughness, geometry, bulkIn, bulkOut, resample, calcSld, shiftedData, simulationXData, dataIndices, repeatLayers, resolution, background, backgroundAction, parallelPoints, resampleMinAngle, resampleNPoints)#

This is the main reflectivity calculation for all layers models in the normal target function.

The function first arranges the roughness’ in the correct order according to geometry. Then, if required it calculates the SLD profile and if requested resamples this into a number of zero-roughness layers (roughness resampling). It the applies any scalefactors and qz shifts the data requires. This is done before calculating the reflectivity to ensure that the reflectivity is calculated over the same range in qz as the shifted datapoints. The main reflectivity calculation is then called, including the resolution function. The calculation outputs two profiles - ‘reflect’ which is the same range as the points, and ‘simulation’ which can be a different range to allow extrapolation. Finally, the background correction is applied.

targetFunctions.normalTF.customLayers(problemStruct, controls)#

The custom layers, normalTF reflectivity calculation. The function extracts the relevant parameters from the input arrays, allocates these on a pre-contrast basis, then calls the ‘coreLayersCalculation’ (the core layers normalTF calc is shared between multiple calculation types).

targetFunctions.normalTF.customXY(problemStruct, controls)#

Extract parameters from problemStruct

targetFunctions.normalTF.processCustomFunction(contrastBulkIns, contrastBulkOuts, bulkInValues, bulkOutValues, contrastCustomFiles, numberOfContrasts, numberOfOutputColumns, customFiles, paramValues, useImaginary)#

Top-level function for processing custom layers for all the contrasts.

targetFunctions.normalTF.standardLayers(problemStruct, controls)#

This is the main reflectivity calculation of the standard layers calculation type. It extracts the required parameters for the contrasts from the input arrays, then passes the main calculation to ‘coreLayersCalculation’, which carries out the calculation itself. The core calculation is common for both standard and custom layers.

Domains Target Functions (domainsTF)#

targetFunctions.domainsTF.averageReflectivity(reflectivity1, reflectivity2, simulation1, simulation2, domainRatio)#

Calculates the averaged reflectivity for domains samples (incoherent sum)

targetFunctions.domainsTF.customLayers(problemStruct, controls)#

The custom layers, domainsTF reflectivity calculation. The function extracts the relevant parameters from the input arrays, allocates these on a pre-contrast basis, then calls the ‘coreLayersCalculation’ (the core layers domainsTF calc is shared between multiple calculation types).

targetFunctions.domainsTF.customXY(problemStruct, controls)#

Extract parameters from problemStruct

targetFunctions.domainsTF.processCustomFunction(contrastBulkIns, contrastBulkOuts, bulkInValues, bulkOutValues, contrastCustomFiles, numberOfContrasts, numberOfOutputColumns, customFiles, paramValues, useImaginary)#

Top-level function for processing custom layers for all the contrasts.

targetFunctions.domainsTF.standardLayers(problemStruct, controls)#

This is the main reflectivity calculation of the standard layers calculation type. It extracts the required parameters for the contrasts from the input arrays, then passes the main calculation to ‘coreLayersCalculation’, which carries out the calculation itself. The core calculation is common for both standard and custom layers.