Ctrl+K

Project Class#

The project class objects contain the experimental data and model information which is used in the reflectivity calculation and optimisation algorithms. The two classes are projectClass, which is used for normal calculations, and domainsClass, which is used for domains calculations. The domainsClass contains additional information relating to the structure of the domains (domainRatio and domainContrasts).

How to create and modify a project is explained in the user guide.

The class itself mostly brings together the data structures describing the experimental model and data. These structures are:

The class is designed so that these data structures do not need to be accessed directly. For example, the bulk in parameters are stored in a parametersClass, and the method projectClass.addBulkIn will pass its arguments to the parametersClass.addParameter method of the bulk in parametersClass. The same applies to removing and changing data in each part of the project.

It is recommended that a project is created using the createProject function instead of creating a projectClass or domainsClass object directly; this function will validate input arguments and allow the creation of both types of project from the same entrypoint.

API.createProject(options)#

Creates a normal project or domain project object depending on the given calculation type. This is the recommended way to create a RAT project not via the projectClass or domainsClass.

Examples

To create a normal, standard layers project.

>>> project = createProject(name='New experiment', calcType='normal');

To create a domains, custom layers project with absorption.

>>> project = createProject(name='Domains experiment', calcType='domains', model='custom layers', absorption=true);
Parameters:

  • name (string or char array, default: '') – The name of the project.

  • calcType (calculationTypes, default: calculationTypes.Normal) – The calculation type which can be ‘normal’ or ‘domains’.

  • model (modelTypes, default: modelTypes.StandardLayers) – The layer model type which can be ‘standard layers’, ‘custom layers’, or ‘custom xy’.

  • geometry (geometryOptions, default: geometryOptions.AirSubstrate) – The geometry to use which can be ‘air/substrate’ or ‘substrate/liquid’.

  • absorption (logical, default: false) – Indicates whether imaginary component is used for the SLD value in layers.

Returns:

obj – A new normal project class or domains project class initialised with given parameters.

Return type:

projectClass or domainsClass

class API.projectClass.projectClass(experimentName, modelType, geometry, absorption)#

projectClass stores all the information that describes the experiment which is essential for running a RAT calculation. There are several components of a project such as the parameters, backgrounds, resolutions, custom files, data, contrast etc, the projectClass provides a number of methods to add, remove, and update these components. For example, for parameters, the addParameter, removeParameter, and setParameter methods are available for adding, removing, and updating parameters.

Examples

>>> project = projectClass();
>>> project = projectClass("Example Project");
>>> project = projectClass("Example Project", 'custom layers', 'substrate/liquid', true);
Parameters:

  • experimentName (string or char array, default: '') – The name of the project.

  • modelType (modelTypes, default: modelTypes.StandardLayers) – The layer model type which can be ‘standard layers’, ‘custom layers’, or ‘custom xy’.

  • geometry (geometryOptions, default: geometryOptions.AirSubstrate) – The geometry to use which can be ‘air/substrate’ or ‘substrate/liquid’.

  • absorption (logical, default: false) – Indicates whether imaginary component is used for the SLD value in layers.

parameters#

The project parameters.

Type:

parametersClass

bulkIn#

The bulkIn parameters.

Type:

parametersClass

bulkOut#

The bulkOut parameters.

Type:

parametersClass

scalefactors#

The scalefactors parameters.

Type:

parametersClass

layers#

An object which contains the layers information.

Type:

layersClass

data#

An object which contains the data table.

Type:

dataClass

customFile#

An object which contains the defined customFiles.

Type:

Custom file object

background#

An object which contains defined backgrounds and background parameters.

Type:

backgroundsClass object

resolution#

An object which contains defined resolutions and resolution parameters.

Type:

resolutionClass object

contrasts#

An object which contains contrast information.

Type:

contrastsClass object

addBackground(name, type, source, value1, value2, value3, value4, value5)#

Adds a new background to the project.

Examples

To add a new constant background with name only.

>>> project.addBackground('New Background');

To add a constant background.

>>> project.addBackground('New Background', 'constant', 'param name');

To add a function background with 2 parameters.

>>> project.addBackground('New Background', 'function', 'function name', 'param name', ''param name 2'');

To add a data background with an offset.

>>> project.addBackground('New Background', 'data', 'data name', 'offset param name');
Parameters:

  • name (string or char array, default: auto-generated name) – The name of the background.

  • type (allowedTypes, default: allowedTypes.Constant) – The type of background (constant, function or data).

  • source (string or char array or whole number, default: '') – The source of the background. if type is ‘constant’, this should be the name (or the row index) of a background parameter. if type is ‘data’, this should be the name (or the row index) of a dataset defined in projectClass.data. if type is ‘function’, this should be the name (or the row index) of a custom function defined in projectClass.customFiles.

  • value1 (string or char array or whole number, default: '') – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.

  • value2 (string or char array or whole number, default: '') – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.

  • value3 (string or char array or whole number, default: '') – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.

  • value4 (string or char array or whole number, default: '') – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.

  • value5 (string or char array or whole number, default: '') – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.

addBackgroundParam(name, min, value, max, fit, priorType, mu, sigma)#

Adds a new background parameter to project.

Examples

To add a new background parameter with no properties and an autogenerated name.

>>> project.addBackgroundParam();

To add a background parameter with all available properties.

>>> project.addBackgroundParam('Background Value D2O'', 1e-8, 2.8e-6, 1e-5, true, 'gaussian', 1, 5);

Other examples of adding background parameters with a subset of properties.

>>> project.addBackgroundParam('Background Value D2O');  % Background parameter name only with others set to default
>>> project.addBackgroundParam('Background Value D2O', 1e-8);  % Background parameter name and min only. Value and max will be set to 1e-8 to keep limits valid
>>> project.addBackgroundParam('Background Value D2O', 1e-8, 2.8e-6, 1e-5, true);  % priors will be default
Parameters:

  • name (string or char array, default: auto-generated name) – The name of the background parameter.

  • min (double, default: 0.0) – The minimum value that the background parameter could take when fitted.

  • value (double, default: 0.0) – The value of the background parameter, default will be equal to min if this is not set.

  • max (double, default: 0.0) – The maximum value that the background parameter could take when fitted, default will be equal to value if this is not set.

  • fit (logical, default: false) – Whether the background parameter should be fitted in a calculation.

  • priorType (PriorTypes, default: PriorTypes.Uniform) – For Bayesian calculations, whether the prior likelihood is assumed to be ‘uniform’, ‘gaussian’, or ‘jeffreys’.

  • mu (double, default: 0.0) – If the prior type is Gaussian, the mean of the Gaussian function for the prior likelihood.

  • sigma (double, default: Inf) – If the prior type is Gaussian, the standard deviation of the Gaussian function for the prior likelihood.

addContrast(options)#

Add a new contrast to the project.

Examples

To add a new contrast with name only.

>>> project.addContrast(name='new contrast');

To add a new contrast with other properties.

>>> project.addContrast(name='new contrast', bulkIn='Silicon', bulkOut='D2O', background='D2O Background', ...
                        resolution='Resolution 1', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O', model={'Oxide', 'Bilayer tails'});
Parameters:

options –

Keyword/value pair to properties to update for the specific contrast.

  • name (char array or string, default: ‘’) the name of the contrast.

  • data (char array or string, default: ‘’) the name of the dataset parameter used by the contrast.

  • background (char array or string, default: ‘’) the name of the background for the contrast.

  • backgroundAction (backgroundActions, default: backgroundActions.Add) whether the background should be added to the simulation (‘add’) or subtracted from the data (‘subtract’).

  • bulkIn (char array or string, default: ‘’) the name of the bulk-in parameter which defines the SLD of the interface between the first layer and the environment.

  • bulkOut (char array or string, default: ‘’) the name of the bulk-out parameter which defines the SLD of the interface between the last layer and the environment.

  • scalefactor (char array or string, default: ‘’) the name of the scalefactor parameter which defines how much the data for this contrast should be scaled.

  • resolution (char array or string, default: ‘’) the name of the instrument resolution for this contrast.

  • resample (logical, default: false) whether adaptive resampling should be used for interface microslicing.

  • repeatLayers (whole number, default: 1) indicates the number of times the layers should be repeated, this is only supported for standard layers.

  • model (cell) if this is a standard layers model, this should be a list of layer names that make up the slab model for this contrast.

    For custom models, this should be a single custom file name for the custom model function.

addCustomFile(name, filename, language, path, functionName)#

Adds a new custom file to the project. For MATLAB, the provided file must be in the matlab path when running.

Examples

To add a new custom file entry with name only.

>>> project.addCustomFile('custom file 1');

To add custom file with name, and filename.

>>> project.addCustomFile('custom file 1', 'customBilayer.m');

To add a Python custom files.

>>> project.addCustomFile('custom file 1', 'customBilayer.py', 'python', 'C:/stuff', 'custom_bilayer);
Parameters:

  • name (string or char array, default: auto-generated name) – The name of this custom file object.

  • filename (string or char array, default: '') – The name of the file containing the custom function.

  • language (supportedLanguages, default: supportedLanguages.Matlab) – What language the custom function is written in: ‘matlab’, ‘python’, or ‘cpp’ (via a dynamic library)

  • path (string or char array, default: '') – The path to the custom file.

  • functionName (string or char array, default: '') – The name of the custom function within the file.

addData(name, data, dataRange, simRange)#

Adds a new dataset to the project.

Examples

To add a new dataset with name only.

>>> project.addData('Data 1');

To add dataset with name and data.

>>> project.addData('Data 1', [1, 0, 0; 2, 0, 0; 3, 0, 0; 4, 0, 0]);

To add dataset with name, data and the ranges.

>>> project.addData('Data 1', [1, 0, 0; 2, 0, 0; 3, 0, 0; 4, 0, 0], [2, 3], [1, 4]);
Parameters:

  • name (string or char array, default: auto-generated name) – The name of the dataset.

  • data (float, default: []) – 3 or 4 column data for the dataset, the data should have (x, y, error) columns and may have optional resolution column.

  • dataRange (float, default: [data(1, 1), data(end, 1)] or [] if no data) – The minimum and maximum range of data to use from the dataset.

  • simRange (float, default: [0.005, 0.7]) – The minimum and maximum range to use for simulation.

addLayer(varargin)#

Adds a new layer to the project. This method can be called in 2 ways. The first for when absorption is false

addLayer(name, thickness, realSLD, roughness, hydration, hydrateWith)

and the second includes an extra argument imaginarySLD for when absorption is true.

addLayer(name, thickness, realSLD, imaginarySLD, roughness, hydration, hydrateWith)

Examples

To add a new layer with name only.

>>> project.addLayer(, 'New layer');

To add a new layer when absorption is false.

>>> project.addLayer('Water Layer', 'Water thickness', 'Water SLD', 'Bilayer heads roughness', 'Water hydration', 'Bulk out');

To add a new layer when absorption is true.

>>> project.addLayer('Layer 1', 'Layer thickness', 'Layer Real SLD', 'Layer Imaginary SLD', 'Layers roughness, 'Layer hydration', 'Bulk in');
Parameters:

  • name (string or char array, default: auto-generated name) – The name of this layer.

  • thickness (string or char array or whole number, default: '') – The name (or the row index) of the parameter describing the thickness of this layer.

  • realSLD (string or char array or whole number, default: '') – The name (or the row index) of the parameter describing the real (scattering) term for the scattering length density of this layer.

  • imaginarySLD (string or char array or whole number, default: '') – The name (or the row index) of the parameter describing the imaginary (absorption) term for the scattering length density of this layer.

  • roughness (string or char array or whole number, default: '') – The name (or the row index) of the parameter describing the roughness of this layer.

  • hydration (string or char array or whole number, default: '') – The name (or the row index) of the parameter describing the percent hydration for the layer

  • hydrateWith (hydrationTypes, default: hydrationTypes.BulkOut) – Whether the layer is hydrated with the “bulk in” or “bulk out”.

addLayerGroup(layerGroup)#

Adds a group of layers to the project.

Examples

>>> firstLayer = {'Water Layer', 'Water thickness', 'Water SLD', 'Bilayer heads roughness', 'Water hydration', 'Bulk out'};
>>> secondLayer = {'Layer 1', 'Layer thickness', 'Layer Real SLD', 'Layer Imaginary SLD', 'Layers roughness, 'Layer hydration', 'Bulk in'};
>>> project.addLayerGroup({firstLayer, secondLayer});
Parameters:

  • layerGroup (cell of cell array) – The inner cells should contain the properties of the layers to add.

  • 1'} (project.addLayerGroup({{'Layer)

  • 2'}}); ({'Layer)

addResolution(name, type, source, value1, value2, value3, value4, value5)#

Adds a new resolution to the project.

Examples

To add a new constant resolution with name only.

>>> project.addResolution('New Resolution');

To add a constant resolution.

>>> project.addResolution(New Resolution', 'constant', 'param name');

To add a data resolution.

>>> project.addResolution('New Resolution', 'data');
Parameters:

  • name (string or char array, default: auto-generated name) – The name of the resolution.

  • type (allowedTypes, default: allowedTypes.Constant) – The type of resolution (constant or data).

  • source (string or char array, default: '') – The source of the resolution. if type is ‘constant’, this should be the name (or the row index) of a resolution parameter. if type is ‘data’, this should be empty. RAT will expect a fourth column in the datafile.

  • value1 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

  • value2 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

  • value3 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

  • value4 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

  • value5 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

addResolutionParam(name, min, value, max, fit, priorType, mu, sigma)#

Adds a new resolution parameter to the project.

Examples

To add a new resolution parameter with no properties and an autogenerated name.

>>> project.addResolutionParam();

To add a resolution parameter with all available properties.

>>> project.addResolutionParam('Resolution Param 1', 20, 50, 60, true, 'gaussian', 1, 5);

Other examples of adding resolution parameters with a subset of properties.

>>> project.addResolutionParam('Resolution Param 1');  % Resolution parameter name only with others set to default
>>> project.addResolutionParam('Resolution Param 1', 23);  % Resolution parameter name and min only. Value and max will be set to 23 to keep limits valid
>>> project.addResolutionParam('Resolution Param 1', 23, 24, 25, true);  % priors will be default
Parameters:

  • name (string or char array, default: auto-generated name) – The name of the resolution parameter.

  • min (double, default: 0.0) – The minimum value that the resolution parameter could take when fitted.

  • value (double, default: 0.0) – The value of the resolution parameter, default will be equal to min if this is not set.

  • max (double, default: 0.0) – The maximum value that the resolution parameter could take when fitted, default will be equal to value if this is not set.

  • fit (logical, default: false) – Whether the resolution parameter should be fitted in a calculation.

  • priorType (PriorTypes, default: PriorTypes.Uniform) – For Bayesian calculations, whether the prior likelihood is assumed to be ‘uniform’, ‘gaussian’, or ‘jeffreys’.

  • mu (double, default: 0.0) – If the prior type is Gaussian, the mean of the Gaussian function for the prior likelihood.

  • sigma (double, default: Inf) – If the prior type is Gaussian, the standard deviation of the Gaussian function for the prior likelihood.

background#

backgroundsClass object

clone()#

Creates a clone of the project.

Examples

>>> clonedProject = project.clone();
Returns:

clonedProject – A new instance of projectClass with the same properties defined in the current projectClass.

Return type:

projectClass

contrasts#

contrastsClass object

customFile#

Custom file object

data#

dataClass object

delete()#

Destroys the wrappers

getAllAllowedNames()#

Returns a struct with all currently set names of normal parameters, background and resolution parameters, backgrounds, resolutions, bulk-ins, bulk-outs, scalefactors, data, custom files and contrast model for the project.

Returns:

names – A struct with names of all the normal parameters, background and resolution parameters, backgrounds, resolutions, bulk-ins, bulk-outs, scalefactors, data, custom files and contrast model entries in the project.

Return type:

struct

layers#

layersClass object

removeBackground(row)#

Removes a background from the project.

Examples

To remove the second background in the table (background in row 2).

>>> project.removeBackground(2);

To remove background with a specific name.

>>> project.removeBackground('Background 1');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the background to remove. If it is text, it is the name of the background to remove.

removeBackgroundParam(row)#

Removes a given background parameter from the project.

Examples

To remove the second background parameter in the table (parameter in row 2).

>>> project.removeBackgroundParam(2);

To remove background parameter with a specific name.

>>> project.removeBackgroundParam('Background Value D2O');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the background parameter to remove. If it is text, it is the name of the background parameter to remove.

removeContrast(row)#

Removes a given contrast from the project.

Examples

To remove the second contrast in the table (contrast in row 2).

>>> project.removeContrast(2);

To remove contrast with a specific name.

>>> project.removeContrast('contrast 1');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the contrast to remove. If it is text, it is the name of the contrast to remove.

removeCustomFile(row)#

Removes a given custom file from the project.

Examples

To remove the second custom file in the table (custom file in row 2).

>>> project.removeCustomFile(2);

To remove custom file with a specific name.

>>> project.removeCustomFile('custom file 1');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the custom file to remove. If it is text, it is the name of the custom file to remove.

removeData(row)#

Removes a given dataset from the project.

Examples

To remove the second dataset in the table (dataset in row 2).

>>> project.removeData(2);

To remove dataset with a specific name.

>>> project.removeData('D2O');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the dataset to remove. If it is text, it is the name of the dataset to remove.

removeLayer(layer)#

Removes a given layer from the project.

Examples

To remove the second layer in the table (layer in row 2).

>>> project.removeLayer(2);

To remove layer with a specific name.

>>> project.removeLayer('D2O');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the layer to remove. If it is text, it is the name of the layer to remove.

removeResolution(row)#

Removes a resolution from project.

Examples

To remove the second resolution in the table (resolution in row 2).

>>> project.removeResolution(2);

To remove resolution with a specific name.

>>> project.removeResolution('Resolution 1');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the resolution to remove. If it is text, it is the name of the resolution to remove.

removeResolutionParam(row)#

Removes a resolution parameter from the project.

Examples

To remove the second resolution parameter in the table (parameter in row 2).

>>> project.removeResolutionParam(2);

To remove resolution parameter with a specific name.

>>> project.removeResolutionParam('Resolution Param 1');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the resolution parameter to remove. If it is text, it is the name of the resolution parameter to remove.

resolution#

resolutionClass object

setBackground(row, options)#

General purpose method for updating properties of an existing background.

Examples

To change the name and value of the second background in the table (background in row 2).

>>> backgrounds.setBackground(2, name='Background 1', type='constant', source='param name');

To change the properties of a background called ‘Background 1’.

>>> backgrounds.setBackground('Background 1', name='New Background', type='function', source='custom file name', value1='param name');
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the background to update. If it is text, it is the name of the background to update.

  • options –

    Keyword/value pair to properties to update for the specific background.

    • name (char array or string, default: ‘’) the new name of the background.

    • type (allowedTypes, default: allowedTypes.empty()) the type of background (constant, function or data).

    • source (char array or string or whole number, default: ‘’) the new source of the background.

    • value1, value2, value3, value4, value5 (char array or string or whole number, default: ‘’) any extra values required for the background.

setBackgroundParam(row, options)#

General purpose method for updating properties of an existing parameter. Any unset property will remain unchanged.

Examples

To change the name and value of the second background parameter in the table (parameter in row 2).

>>> project.setBackgroundParam(2, 'name', 'Background 2', 'value', 50);

To change the all properties of a background parameter called ‘Background Value D2O’.

>>> project.setBackgroundParam('Background Value D2O', 'name', 'Background 2', 'min', 20, 'value', 50, 'max', 60, ...
>>>                            'fit', true, 'priorType', 'gaussian', 'mu', 1, 'sigma', 5);
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the background parameter to update. If it is text, it is the name of the background parameter to update.

  • options –

    Keyword/value pair to properties to update for the specific background parameter.

    • name (char array or string, default: ‘’) the new name of the background parameter.

    • min (double, default: []) the new minimum value of the background parameter.

    • value (double, default: []) the new value of the background parameter.

    • max (double, default: []) the new maximum value of the background parameter.

    • fit (logical, default: logical.empty()) the new fit flag of the background parameter.

    • priorTypes (priorTypes, default: priorTypes.empty()) the new prior type of the background parameter.

    • mu (double, default: []) the new mean of the Gaussian function for the prior.

    • sigma (double, default: []) The new standard deviation of the Gaussian function for the prior.

setContrast(row, options)#

General purpose method for updating properties of an existing contrast.

Examples

To change the properties of the second contrast in the object.

>>> project.setContrast(2, name='new contrast', bulkIn='Silicon', bulkOut='D2O', background='D2O Background', ...
                        resolution='Resolution 1', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O', model='Oxide Model'});

To change the properties of a contrast called ‘Contrast 1’.

>>> project.setContrast('Contrast 1', name='new contrast', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O'});
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the contrast to update. If it is text, it is the name of the contrast to update.

  • options –

    Keyword/value pair to properties to update for the specific contrast.

    • name (char array or string, default: ‘’) the name of the contrast.

    • data (char array or string, default: ‘’) the name of the dataset parameter used by the contrast.

    • background (char array or string, default: ‘’) the name of the background for the contrast.

    • backgroundAction (backgroundActions, default: backgroundActions.Add) whether the background should be added to the simulation (‘add’) or subtracted from the data (‘subtract’).

    • bulkIn (char array or string, default: ‘’) the name of the bulk-in parameter which defines the SLD of the interface between the first layer and the environment.

    • bulkOut (char array or string, default: ‘’) the name of the bulk-out parameter which defines the SLD of the interface between the last layer and the environment.

    • scalefactor (char array or string, default: ‘’) the name of the scalefactor parameter which defines how much the data for this contrast should be scaled.

    • resolution (char array or string, default: ‘’) the name of the instrument resolution for this contrast.

    • resample (logical, default: false) whether adaptive resampling should be used for interface microslicing.

    • repeatLayers (whole number, default: 1) indicates the number of times the layers should be repeated, this is only supported for standard layers.

    • model (char array or string or cell string) if this is a standard layers model, this should be a list of layer names that make up the slab model for this contrast.

      For custom models, this should be a single custom file name for the custom model function.

setContrastModel(row, model)#

Updates the model of an existing contrast.

Examples

To change the model of the second contrast in the project.

>>> project.setContrastModel(2, 'Oxide Model'});

To change the properties of a contrast called ‘Contrast 1’.

>>> project.setContrastModel('Contrast 1', 'Oxide Model');

To change multiple contrasts at once. The snippet below will change 1, 2, and 3.

>>> project.setContrastModel(1:3, {'Layer 1', 'Layer 2'});
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the contrast to update. If it is text, it is the name of the contrast to update.

  • model (char array or string or cell string) – If this is a standard layers model, this should be a list of layer names that make up the slab model for this contrast. For custom models, this should be a single custom file name for the custom model function.

setCustomFile(row, options)#

General purpose method for updating properties of an existing custom file.

Examples

To change the name and filename of the second custom file in the table (custom file in row 2).

>>> file.setCustomFile(2, name='custom file 1', filename='customFunction.m');

To change the properties of a custom file called ‘custom file 1’.

>>> file.setCustomFile('custom file 1', name='new custom file', filename='customFunction.py', language='python');
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the custom file to update. If it is text, it is the name of the custom file to update.

  • options –

    Keyword/value pair to properties to update for the specific custom file.

    • name (char array or string, default: ‘’) the new name of the custom file.

    • filename (char array or string, default: ‘’) the new filename of the custom file.

    • language (supportedLanguages, default: supportedLanguages.empty()) the new language of the custom file.

    • path (char array or string, default: ‘’) the new path of the custom file.

    • functionName (char array or string, default: ‘) the new function name of the custom file.

setData(row, options)#

General purpose method for updating properties of an existing dataset.

Examples

To change the name and data of the second dataset in the table (dataset in row 2).

>>> project.setData(2, name='Data 1', data=[1, 0, 0; 2, 0, 0; 3, 0, 0; 4, 0, 0]);

To change the properties of a dataset called ‘Data 1’.

>>> project.setData('Data 1', name='Data H2O', dataRange=[2, 3]);
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the dataset to update. If it is text, it is the name of the dataset to update.

  • options –

    Keyword/value pair to properties to update for the specific dataset.

    • name (char array or string, default: ‘’) the new name of the dataset.

    • data (float, default: []) the new data array.

    • dataRange (float, default: []) the new data range.

    • simRange (float, default: []) the new simulation range.

setLayer(row, varargin)#

Update properties of an existing layer. Any unset property will remain unchanged.

Examples

To update the thickness of the second layer in the table (layer in row 2).

>>> project.setLayer(2, thickness='New thickness');

To change the properties of a layer called ‘Layer 1’.

>>> project.setLayer('Layer 1', name='new layer', thickness='New thickness', sld='Layer SLD');

To change the imaginary SLD when absorption is true.

>>> project.setLayer('Layer 1', name='new layer', thickness='New thickness', realSLD='Layer SLD', imaginarySLD='Layer Imaginary SLD');
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row of the layer to update. If it is text, it is the name of the layer to update.

  • varargin –

    Keyword/value pair to properties to update for the specific parameter.

    • name (string or char array or whole number, default: ‘’) the new name of the layer.

    • thickness (string or char array or whole number, default: ‘’) The name (or the row index) of the parameter describing the thickness of this layer.

    • sld, realSLD (string or char array or whole number, default: ‘’) The name (or the row index) of the parameter describing the real (scattering) term of the SLD.

    • imaginarySLD (string or char array or whole number, default: ‘’) the new name (or the row index) of the parameter describing the imaginary (absorption) term of the SLD.

    • roughness (string or char array or whole number, default: ‘’) the new name (or the row index) of the parameter describing the roughness of this layer.

    • hydration (string or char array or whole number, default: ‘’) the new name (or the row index) of the parameter describing the percent hydration for the layer

    • hydrateWith (hydrationTypes, default: hydrationTypes.empty()) whether the layer is hydrated with the “bulk in” or “bulk out”.

setResolution(row, options)#

General purpose method for updating properties of an existing resolution.

Examples

To change the name and value of the second resolution in the table (resolution in row 2).

>>> project.setResolution(2, name='Resolution 1', type='constant', source='param name');

To change the properties of a resolution called ‘Resolution 1’.

>>> project.setResolution('Resolution 1', name='New Resolution 1', type='data');
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the resolution to update. If it is text, it is the name of the resolution to update.

  • options –

    Keyword/value pair to properties to update for the specific resolution.

    • name (char array or string, default: ‘’) the new name of the resolution.

    • type (allowedTypes, default: allowedTypes.empty()) the type of resolution (constant or data).

    • source (char array or string, or whole number, default: ‘’) the new source of the resolution.

    • value1, value2, value3, value4, value5 (char array or string or whole number, default: ‘’) any extra values required for the resolution.

setResolutionParam(row, options)#

General purpose method for updating properties of an existing resolution parameter. Any unset property will remain unchanged.

Examples

To change the name and value of the second resolution parameter in the table (parameter in row 2).

>>> project.setResolutionParam(2, 'name', 'Resolution Param 1', 'value', 50);

To change the all properties of a resolution parameter called ‘Resolution Param 2’.

>>> project.setResolutionParam('Resolution Param 2', 'name', 'Resolution Param 1', 'min', 20, 'value', 50, 'max', 60, ...
>>>                            'fit', true, 'priorType', 'gaussian', 'mu', 1, 'sigma', 5);
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the resolution parameter to update. If it is text, it is the name of the resolution parameter to update.

  • options –

    Keyword/value pair to properties to update for the specific resolution parameter.

    • name (char array or string, default: ‘’) the new name of the resolution parameter.

    • min (double, default: []) the new minimum value of the resolution parameter.

    • value (double, default: []) the new value of the resolution parameter.

    • max (double, default: []) the new maximum value of the resolution parameter.

    • fit (logical, default: logical.empty()) the new fit flag of the resolution parameter.

    • priorTypes (priorTypes, default: priorTypes.empty()) the new prior type of the resolution parameter.

    • mu (double, default: []) the new mean of the Gaussian function for the prior.

    • sigma (double, default: []) The new standard deviation of the Gaussian function for the prior.

toDomainsClass()#

Creates a new domainsClass object and copies the properties from current projectClass.

Examples

>>> domainsProject = project.toDomainsClass();
Returns:

domainsObj – An instance of domainsClass with the same properties defined in the projectClass.

Return type:

domainsClass

toStruct()#

Converts the projectClass into a structure array.

Returns:

outStruct – A struct which contains the properties from the projectClass.

Return type:

struct

writeScript(options)#

Writes a MATLAB script to a given file path. This script can be run to reproduce the current projectClass object.

Examples

>>> project.writeScript(path="newScript.m");
Parameters:

  • objName (string or char array, default: 'project') – The name to use for the project object in the script.

  • path (string or char array, default: 'projectScript.m') – The relative or absolute file path where the script should be written to.

class API.projectClass.domainsClass(experimentName, modelType, geometry, absorption)#

domainsClass stores all the information that describes a domains experiment which is essential for running a RAT domains calculation. The domainsClass contains similar components to a normal project such as the parameters, backgrounds, resolutions, custom files, data, contrast etc, but also stores the domains ratio and domains contrast which are unique to a domains calculation. The domainsClass provides a number of methods to add, remove, and update these components. For example, for domain ratio, the addDomainsRatio, removeDomainsRatio, and setDomainsRatio methods are available for adding, removing, and updating parameters.

Examples

>>> domains = domainsClass();
>>> domains = domainsClass("Example Project");
>>> domains = domainsClass("Example Project", 'custom layers', 'substrate/liquid', true);
Parameters:

  • experimentName (string or char array, default: '') – The name of the domains project.

  • modelType (modelTypes, default: modelTypes.StandardLayers) – The layer model type which can be ‘standard layers’, ‘custom layers’, or ‘custom xy’.

  • geometry (geometryOptions, default: geometryOptions.AirSubstrate) – The geometry to use which can be ‘air/substrate’ or ‘substrate/liquid’.

  • absorption (logical, default: false) – Indicates whether imaginary component is used for the SLD value in layers.

parameters#

The project parameters.

Type:

parametersClass

bulkIn#

The bulkIn parameters.

Type:

parametersClass

bulkOut#

The bulkOut parameters.

Type:

parametersClass

scalefactors#

The scalefactors parameters.

Type:

parametersClass

layers#

An object which contains the layers information.

Type:

layersClass

data#

An object which contains the data table.

Type:

dataClass

customFile#

An object which contains the defined customFiles.

Type:

Custom file object

background#

An object which contains defined backgrounds and background parameters.

Type:

backgroundsClass object

resolution#

An object which contains defined resolutions and resolution parameters.

Type:

resolutionClass object

contrasts#

An object which contains contrast information.

Type:

contrastsClass object

domainRatio#

The domain ratio parameters.

Type:

parametersClass

domainContrasts#

An object which contains domain contrast information.

Type:

domainContrastsClass

addContrast(options)#

Add a new contrast to the project.

Examples

To add a new contrast with name only.

>>> domains.addContrast(name='new contrast');

To add a new contrast with other properties.

>>> domains.addContrast(name='new contrast', bulkIn='Silicon', bulkOut='D2O', background='D2O Background', ...
                        resolution='Resolution 1', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O', ...
                        domainRatio='Domain Ratio 1', model={'Domains 1', 'Domains 2'});
Parameters:

options –

Keyword/value pair to properties to update for the specific contrast.

  • name (char array or string, default: ‘’) the name of the contrast.

  • data (char array or string, default: ‘’) the name of the dataset parameter used by the contrast.

  • background (char array or string, default: ‘’) the name of the background for the contrast.

  • backgroundAction (backgroundActions, default: backgroundActions.Add) whether the background should be added to the simulation (‘add’) or subtracted from the data (‘subtract’).

  • bulkIn (char array or string, default: ‘’) the name of the bulk-in parameter which defines the SLD of the interface between the first layer and the environment.

  • bulkOut (char array or string, default: ‘’) the name of the bulk-out parameter which defines the SLD of the interface between the last layer and the environment.

  • scalefactor (char array or string, default: ‘’) the name of the scalefactor parameter which defines how much the data for this contrast should be scaled.

  • resolution (char array or string, default: ‘’) the name of the instrument resolution for this contrast.

  • resample (logical, default: false) whether adaptive resampling should be used for interface microslicing.

  • repeatLayers (whole number, default: 1) indicates the number of times the layers should be repeated, this is only supported for standard layers.

  • domainRatio (char array or string, default: ‘’) the name of the domain ratio parameter.

  • model (cell) if this is a standard layers model, this should be a list of domain contrast names for this contrast.

    For custom models, this should be a single custom file name for the custom model function.

addDomainContrast(options)#

Add a new domain contrast to the project.

Examples

To add a new domain contrast with name only.

>>> domains.addDomainContrast(name='new domain contrast');

To add a new domain contrast with model.

>>> domains.addDomainContrast(name='new domain contrast', model='Oxide');
>>> domains.addDomainContrast(name='new domain contrast', model={'Oxide', 'Bilayer tails'});
Parameters:

options –

Keyword/value pair to properties to update for the specific domain contrast.

  • name (char array or string, default: ‘’) the name of the domain contrast.

  • model (cell) this should be a list of layer names that make up the slab model for this domain contrast.

addDomainRatio(name, min, value, max, fit, priorType, mu, sigma)#

Adds a new domain ratio parameter. Expects the name of domain ratio, min, value, max, and if fit is off or on

project.addDomainRatio(‘Domain Ratio 2’, 0.4, 0.5, 0.6, true); Adds an new domain ratio to the project.

Examples

To add a new domain ratio with no properties and an autogenerated name.

>>> domains.addDomainRatio();

To add a domain ratio with all available properties.

>>> domains.addDomainRatio('New Domain Ratio', 0.4, 0.5, 0.6, true, 'gaussian', 1, 5);

Other examples of adding domain ratios with a subset of properties.

>>> domains.addDomainRatio('New Domain Ratio');  % Domain ratio name only with others set to default
>>> domains.addDomainRatio('New Domain Ratio', 0.4);  % Domain ratio name and min only. Value and max will be set to 0.4 to keep limits valid
>>> domains.addDomainRatio('New Domain Ratio', 0.4, 0.5, 0.6, true);  % priors will be default
Parameters:

  • name (string or char array, default: auto-generated name) – The name of the domain ratio.

  • min (double, default: 0.0) – The minimum value that the domain ratio could take when fitted.

  • value (double, default: 0.0) – The value of the domain ratio, default will be equal to min if this is not set.

  • max (double, default: 0.0) – The maximum value that the domain ratio could take when fitted, default will be equal to value if this is not set.

  • fit (logical, default: false) – Whether the domain ratio should be fitted in a calculation.

  • priorType (PriorTypes, default: PriorTypes.Uniform) – For Bayesian calculations, whether the prior likelihood is assumed to be ‘uniform’, ‘gaussian’, or ‘jeffreys’.

  • mu (double, default: 0.0) – If the prior type is Gaussian, the mean of the Gaussian function for the prior likelihood.

  • sigma (double, default: Inf) – If the prior type is Gaussian, the standard deviation of the Gaussian function for the prior likelihood.

domainContrasts#

Modified contrast class with no data for domains

domainRatio#

Class for specifying the ratio between domains

getAllAllowedNames()#

Returns a struct with all currently set names of normal parameters, background and resolution parameters, backgrounds, resolutions, bulk-ins, bulk-outs, scalefactors, data, custom files, contrast model, domain ratios, and domain contrasts for the project.

Returns:

names – A struct with names of all the normal parameters, background and resolution parameters, backgrounds, resolutions, bulk-ins, bulk-outs, scalefactors, data, custom files, contrast model, domain ratios, and domain contrasts entries in the project.

Return type:

struct

removeDomainContrast(row)#

Removes a given domain contrast from the project.

Examples

To remove the second domain contrast in the table (domain contrast in row 2).

>>> domains.removeDomainContrast(2);

To remove domain contrast with a specific name.

>>> domains.removeDomainContrast('domain contrast 1');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the domain contrast to remove. If it is text, it is the name of the domain contrast to remove.

removeDomainRatio(row)#

Removes a domain ratio from the project.

Examples

To remove the second domain ratio in the table (domain ratio in row 2).

>>> domains.removeDomainRatio(2);

To remove domain ratio with a specific name.

>>> domains.removeDomainRatio('Domain Ratio 2');
Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the domain ratio to remove. If it is text, it is the name of the domain ratio to remove.

setContrast(row, options)#

General purpose method for updating properties of an existing contrast.

Examples

To change the properties of the second contrast in the object.

>>> domains.setContrast(2, name='new contrast', bulkIn='Silicon', bulkOut='D2O', background='D2O Background', ...
                        resolution='Resolution 1', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O', model={'Domains 1', 'Domains 2'}});

To change the properties of a contrast called ‘Contrast 1’.

>>> domains.setContrast('Contrast 1', name='new contrast', domainRatio='Domain Ratio 1', model={'Domains 1', 'Domains 2'});
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the contrast to update. If it is text, it is the name of the contrast to update.

  • options –

    Keyword/value pair to properties to update for the specific contrast.

    • name (char array or string, default: ‘’) the name of the contrast.

    • data (char array or string, default: ‘’) the name of the dataset parameter used by the contrast.

    • background (char array or string, default: ‘’) the name of the background for the contrast.

    • backgroundAction (backgroundActions, default: backgroundActions.Add) whether the background should be added to the simulation (‘add’) or subtracted from the data (‘subtract’).

    • bulkIn (char array or string, default: ‘’) the name of the bulk-in parameter which defines the SLD of the interface between the first layer and the environment.

    • bulkOut (char array or string, default: ‘’) the name of the bulk-out parameter which defines the SLD of the interface between the last layer and the environment.

    • scalefactor (char array or string, default: ‘’) the name of the scalefactor parameter which defines how much the data for this contrast should be scaled.

    • resolution (char array or string, default: ‘’) the name of the instrument resolution for this contrast.

    • resample (logical, default: false) whether adaptive resampling should be used for interface microslicing.

    • repeatLayers (whole number, default: 1) indicates the number of times the layers should be repeated, this is only supported for standard layers.

    • domainRatio (char array or string, default: ‘’) the name of the domain ratio parameter.

    • model (char array or string or cell string) if this is a standard layers model, this should be a list of domain contrast names for this contrast.

      For custom models, this should be a single custom file name for the custom model function.

setContrastModel(row, model)#

Updates the model of an existing contrast.

Examples

To change the model of the second contrast in the project.

>>> domains.setContrastModel(2, {'Domains 1', 'Domains 2'});

To change the properties of a contrast called ‘Contrast 1’.

>>> domains.setContrastModel('Contrast 1', {'Domains 1', 'Domains 2'});

To change multiple contrasts at once. The snippet below will change 1, 2, and 3.

>>> domains.setContrastModel(1:3, {'Domains 1', 'Domains 2'});
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the contrast to update. If it is text, it is the name of the contrast to update.

  • model (char array or string or cell string) – If this is a standard layers model, this should be a list of domain contrast names for this contrast. For custom models, this should be a single custom file name for the custom model function.

setDomainContrast(row, options)#

General purpose method for updating properties of an existing domain contrast.

Examples

To change the properties of the second domain contrast in the object.

>>> domains.setDomainContrast(2, name='new domain contrast', model='Oxide Model'});

To change the properties of a domain contrast called ‘Domain Contrast 1’.

>>> domains.setDomainContrast('Domain Contrast 1', name='new domain contrast', model={'Oxide', 'Bilayer tails'});
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the domain contrast to update. If it is text, it is the name of the domain contrast to update.

  • options –

    Keyword/value pair to properties to update for the specific domain contrast.

    • name (char array or string, default: ‘’) the name of the domain contrast.

    • model (char array or string or cell string) this should be a list of layer names that make up the slab model for this contrast.

setDomainContrastModel(row, model)#

Updates the model of an existing domain contrast.

Examples

To change the model of the second domain contrast in the project.

>>> domains.setDomainContrastModel(2, 'Oxide Model'});

To change the properties of a domain contrast called ‘Contrast 1’.

>>> domains.setDomainContrastModel('Contrast 1', {'Domains 1', 'Domains 2'});

To change multiple domain contrasts at once. The snippet below will change 1, 2, and 3.

>>> domains.setDomainContrastModel(1:3, {'Layer 1'});
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the domain contrast to update. If it is text, it is the name of the domain contrast to update.

  • model (char array or string or cell string) – This should be a list of layer names that make up the slab model for this domain contrast.

setDomainRatio(row, options)#

General purpose method for updating properties of an existing domain ratio. Any unset property will remain unchanged.

Examples

To change the name and value of the second domain ratio in the table (domain ratio in row 2).

>>> domains.setDomainRatio(2, name='Domain Ratio 1', value=0.55);

To change the all properties of a domain ratio called ‘Domain Ratio 1’.

>>> domains.setDomainRatio('Domain Ratio 1', name='New Domain Ratio', min=0.4, value=0.5, max=0.6, ...
>>>                        fit=true, priorType=gaussian, mu=1, sigma=5);
Parameters:

  • row (string or char array or whole number) – If row is an integer, it is the row number of the domain ratio to update. If it is text, it is the name of the domain ratio to update.

  • options –

    Keyword/value pair to properties to update for the specific domain ratio.

    • name (char array or string, default: ‘’) the new name of the domain ratio.

    • min (double, default: []) the new minimum value of the domain ratio.

    • value (double, default: []) the new value of the domain ratio.

    • max (double, default: []) the new maximum value of the domain ratio.

    • fit (logical, default: logical.empty()) the new fit flag of the domain ratio.

    • priorTypes (priorTypes, default: priorTypes.empty()) the new prior type of the domain ratio.

    • mu (double, default: []) the new mean of the Gaussian function for the prior.

    • sigma (double, default: []) The new standard deviation of the Gaussian function for the prior.

toProjectClass()#

Creates a new projectClass object and copies the properties from current domainsClass.

Examples

>>> normalProject = domains.toProjectClass();
Returns:

projectObj – An instance of projectClass with the common properties copied from the domainsClass.

Return type:

projectClass

toStruct()#

Converts the domainsClass into a structure array.

Returns:

outStruct – A struct which contains the properties from the domainsClass.

Return type:

struct