Introduction#
When we are at the calculations point our data analysis - that the data has been properly reduced, and we have some idea of a modelling strategy, we can still then split the problem specification into two parts.
The Model Definition describes our data, our model, the various parameters we may have along with their limits or priors, and other quantities such as bulk SLD’s or backgrounds.
The Controls Block summarises the actions which we want to do with our model. So it specifies which algorithm we might want to apply to improve our model fit, along with algorithm parameters such as maximum function evaluations or gradients etc.
Keeping these two separate gives a high degree of flexibility as to how we can approach a data analysis problem. For example, suppose we have defined a Model Definition block which contains the data and model details for a given fitting problem, we then decide that we would like to optimise this first using a genetic algorithm, and then run a Bayesian analysis to obtain the parameter posterior distributions. To do all this we only need to define our model once, and run it twice whilst simply modifying the Controls Block to tweak the algorithm that is run in each case. Also, once we are satisfied with our model, we can save it or export it, and re-use this basic pattern for subsequent analysis with different, related data sets. Keeping the Model and Controls separate gives a high degree of flexibility as to how tasks can be formulated and run.
So, an input into RAT always conforms to this picture: a model definition class to specify the problem, and a controls definition class that tells RAT what analysis task you would like to do:
The outputs are always another problemDef class, and a results block. The new problemDef class is identical to the inputted one, except with updated values of the fitted parameters (e.g. after running a fit). The results block as a set of arrays containing the results of the calculations, such as simulated reflectivities, SLD profiles or parameter distributions. We will discuss more about these in next Section where we look at the inputs and outputs in more detail.
In the next section, we will look at an example calculation, in order to introduce the basics of the RAT toolbox. Before we proceed, it is useful to keep a couple of things in mind:
- Different model types - There are many possible types of model, and this is done by having more than one version of
the problemDef class:
Standard Problem: Problem types which are well described by a non-polarised beam, with no absorption (i.e., real refractive index only).
Standard Problem with imaginary refractive index.
Domains Problem Type (‘incoherent summing’).
Within each problem class, there is the option of Custom Layer or Custom XY model definitions. These will be discussed in more detail in a later section.
In this section we’ll look at the project definition class in more detail, we’ll see how we can use the class methods to build and modify a model, and how to carry out the analysis.
Note
If you are a RasCAL-1 user, you probably have existing RasCAL models that you would like to analyse using RAT. If so, there is no need to re-make the model from scratch. Instead, there are conversion utilities (Convert between RAT and RasCAL-1). In fact, for those who prefer a graphical model builder, using the RasCAL-1 GUI to build a basic model and then converting to RAT is a viable workflow.
An example - A simple model of a lipid layer#
(a) Specifying the Model.
In the next section, we’ll look in detail how to set up the problem definition for a given situation. Initially though, it is useful to take a pre-prepared problem definition, and to see how this is then used in RAT. As an example, we’ll use some neutron reflectivity data for a lipid monolayer, collected at various deuterations, which we want to analyse simultaneously.
In terms of reflectivity, the interface we want to model (i.e. a monolayer at an air-water interface) is usually well modelled by two layers: the hydrophobic tail regions of the lipids, which locate outside the bulk water interface, and the hydrophilic heads which are adjacent (or embedded) in the bulk aqueous phase.
In our example, the layers can be either deuterated of hydrogenated, and the bulk water can either be D2O or ACMW.
We are going to analyze our monolayer data using a RasCAL type standard layers model, in that we identify which parameters we need to describe the model, group these into layers (which are defined as a thickness, roughness, SLD and hydration), and then group the layers along with data into contrasts. The advantage of this approach is that it is simple to share parameters between layers, so a layer representing deuterated headgroups should share the same thickness and roughness parameters as a layer representing hydrogenated heads, but they should differ from each other in their SLD.
The problem definition in RAT is done by making an instance of a project class object, and then using the class methods to set up the parameters, layers and so on this instance. The details of setting up a projectClass object is discussed in next Section, but for now, we’ll look at a pre-prepared example.
% Load in a pre-made problem Definition class
root = getappdata(0, 'root');
problem = load(fullfile(root, '/examples/tutorialFiles/twoContrastExample.mat'));
problem = problem.problem;
% Have a look at what we have
disp(problem)
# TODO update with data
problem = get_problem()
print(problem)
modelType: 'standard layers'
experimentName: 'DSPC monolayers'
geometry: 'air/substrate'
Parameters: ----------------------------------------------------------------------------------------------
p Name Min Value Max Fit?
__ ________________________ ______ _______ _____ _____
1 "Substrate Roughness" 1 3 5 true
2 "Tails Thickness" 10 20 30 true
3 "Heads Thickness" 3 11 16 true
4 "Tails Roughness" 2 5 9 true
5 "Heads Roughness" 2 5 9 true
6 "Deuterated Tails SLD" 4e-06 6e-06 2e-05 true
7 "Hydrogenated Tails SLD" -6e-07 -4e-07 0 true
8 "Deuterated Heads SLD" 1e-06 3e-06 8e-06 true
9 "Hydrogenated Heads SLD" 1e-07 1.4e-06 3e-06 true
10 "Heads Hydration" 0 0.3 0.5 true
Bulk In: --------------------------------------------------------------------------------------------------
p Name Min Value Max Fit?
_ _________ ___ _____ ___ _____
1 "SLD Air" 0 0 0 false
Bulk Out: -------------------------------------------------------------------------------------------------
p Name Min Value Max Fit?
_ __________ _______ ________ ________ _____
1 "SLD D2O" 6.2e-06 6.35e-06 6.35e-06 true
2 "SLD ACMW" -1e-06 0 1e-06 true
Scalefactors: -------------------------------------------------------------------------------------------------
p Name Min Value Max Fit?
_ _______________ ____ _____ ____ _____
1 "Scalefactor 1" 0.02 0.23 0.25 true
Backgrounds: -----------------------------------------------------------------------------------------------
(a) Background Parameters:
p Name Min Value Max Fit?
_ __________________ _____ _______ _____ _____
1 "Backs Value ACMW" 1e-07 5.5e-06 1e-05 true
2 "Backs Value D2O" 1e-08 2.8e-06 1e-05 true
(b) Backgrounds:
p Name Type Value 1 Value 2 Value 3 Value 4 Value 5
_ _________________ __________ __________________ _______ _______ _______ _______
1 "Background ACMW" "constant" "Backs Value ACMW" "" "" "" ""
2 "Background D2O" "constant" "Backs Value D2O" "" "" "" ""
Resolutions: ---------------------------------------------------------------------------------------------
(a) Resolutions Parameters:
p Name Min Value Max Fit?
_ __________________ ____ _____ ____ _____
1 "Resolution par 1" 0.01 0.03 0.05 false
(b) Resolutions:
p Name Type Value 1 Value 2 Value 3 Value 4 Value 5
_ ______________ __________ __________________ _______ _______ _______ _______
1 "Resolution 1" "constant" "Resolution par 1" "" "" "" ""
Layers: --------------------------------------------------------------------------------------------------
p Name Thickness SLD Roughness Hydration Hydrate with
_ ____________________ _________________ ________________________ _________________ _________________ ____________
1 "Hydrogenated Heads" "Heads Thickness" "Hydrogenated Heads SLD" "Heads Roughness" "Heads Hydration" "bulk out"
2 "Deuterated Heads" "Heads Thickness" "Deuterated Heads SLD" "Heads Roughness" "Heads Hydration" "bulk out"
3 "Hydrogenated Tails" "Tails Thickness" "Hydrogenated Tails SLD" "Tails Roughness" "" "bulk out"
4 "Deuterated Tails" "Tails Thickness" "Deuterated Tails SLD" "Tails Roughness" "" "bulk out"
Custom Files: ------------------------------------------------------------------------------------------------------
Name Filename Function Name Language Path
____ ________ _____________ ________ ____
"" "" "" "" ""
Data: ------------------------------------------------------------------------------------------------------
Name Data Data Range Simulation Range
________________________ ______________________ _____________________ _____________________
"Simulation" "No Data" "-" "[ 0.0050 , 0.7000 ]"
"H-tail / D-head / ACMW" "Data array: [51 x 3]" "[ 0.0518 , 0.5888 ]" "[ 0.0518 , 0.5888 ]"
"D-tail / H-head / D2O" "Data array: [51 x 3]" "[ 0.0518 , 0.5888 ]" "[ 0.0518 , 0.5888 ]"
Contrasts: -----------------------------------------------------------------------------------------------
p 1 2
___________________ _______________________ ________________________
"Name" "D-tail/H-Head/D2O" "H-tail/D-Head/ACMW"
"Data" "D-tail / H-head / D2O" "H-tail / D-head / ACMW"
"Background" "Background D2O" "Background ACMW"
"Background Action" "add" "add"
"Bulk in" "SLD Air" "SLD Air"
"Bulk out" "SLD D2O" "SLD ACMW"
"Scalefactor" "Scalefactor 1" "Scalefactor 1"
"Resolution" "Resolution 1" "Resolution 1"
"Resample" "false" "false"
"Model" "Deuterated Tails" "Hydrogenated Tails"
"" "Hydrogenated Heads" "Deuterated Heads"
Name: ----------------------------------------------------------------------------------------------
DSPC monolayers
Calculation: ---------------------------------------------------------------------------------------
non polarised
Model: ---------------------------------------------------------------------------------------------
standard layers
Geometry: ------------------------------------------------------------------------------------------
air/substrate
Parameters: ----------------------------------------------------------------------------------------
+-------+------------------------+--------+---------+-------+------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+------------------------+--------+---------+-------+------+------------+-----+-------+
| 0 | Substrate Roughness | 1.0 | 3.0 | 5.0 | True | uniform | 0.0 | inf |
| 1 | Tails Thickness | 10.0 | 20.0 | 30.0 | True | uniform | 0.0 | inf |
| 2 | Heads Thickness | 3.0 | 11.0 | 16.0 | True | uniform | 0.0 | inf |
| 3 | Tails Roughness | 2.0 | 5.0 | 9.0 | True | uniform | 0.0 | inf |
| 4 | Heads Roughness | 2.0 | 5.0 | 9.0 | True | uniform | 0.0 | inf |
| 5 | Deuterated Tails SLD | 4e-06 | 6e-06 | 2e-05 | True | uniform | 0.0 | inf |
| 6 | Hydrogenated Tails SLD | -6e-07 | -4e-07 | 0.0 | True | uniform | 0.0 | inf |
| 7 | Deuterated Heads SLD | 1e-06 | 3e-06 | 8e-06 | True | uniform | 0.0 | inf |
| 8 | Hydrogenated Heads SLD | 1e-07 | 1.4e-06 | 3e-06 | True | uniform | 0.0 | inf |
| 9 | Heads Hydration | 0.0 | 0.3 | 0.5 | True | uniform | 0.0 | inf |
+-------+------------------------+--------+---------+-------+------+------------+-----+-------+
Bulk In: -------------------------------------------------------------------------------------------
+-------+---------+-----+-------+-----+-------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+---------+-----+-------+-----+-------+------------+-----+-------+
| 0 | SLD Air | 0.0 | 0.0 | 0.0 | False | uniform | 0.0 | inf |
+-------+---------+-----+-------+-----+-------+------------+-----+-------+
Bulk Out: ------------------------------------------------------------------------------------------
+-------+----------+---------+----------+----------+------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+----------+---------+----------+----------+------+------------+-----+-------+
| 0 | SLD D2O | 6.2e-06 | 6.35e-06 | 6.35e-06 | True | uniform | 0.0 | inf |
| 1 | SLD ACMW | -6e-07 | -5.6e-07 | -3e-07 | True | uniform | 0.0 | inf |
+-------+----------+---------+----------+----------+------+------------+-----+-------+
Scalefactors: --------------------------------------------------------------------------------------
+-------+---------------+------+-------+------+------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+---------------+------+-------+------+------+------------+-----+-------+
| 0 | Scalefactor 1 | 0.02 | 0.23 | 0.25 | True | uniform | 0.0 | inf |
+-------+---------------+------+-------+------+------+------------+-----+-------+
Background Parameters: -----------------------------------------------------------------------------
+-------+------------------+-------+---------+-------+------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+------------------+-------+---------+-------+------+------------+-----+-------+
| 0 | Backs Value ACMW | 1e-07 | 5.5e-06 | 1e-05 | True | uniform | 0.0 | inf |
| 1 | Backs Value D2O | 1e-08 | 2.8e-06 | 1e-05 | True | uniform | 0.0 | inf |
+-------+------------------+-------+---------+-------+------+------------+-----+-------+
Backgrounds: ---------------------------------------------------------------------------------------
+-------+-----------------+----------+------------------+---------+---------+---------+---------+
| index | name | type | value 1 | value 2 | value 3 | value 4 | value 5 |
+-------+-----------------+----------+------------------+---------+---------+---------+---------+
| 0 | Background ACMW | constant | Backs Value ACMW | | | | |
| 1 | Background D2O | constant | Backs Value D2O | | | | |
+-------+-----------------+----------+------------------+---------+---------+---------+---------+
Resolution Parameters: -----------------------------------------------------------------------------
+-------+--------------------+------+-------+------+-------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+--------------------+------+-------+------+-------+------------+-----+-------+
| 0 | Resolution Param 1 | 0.01 | 0.03 | 0.05 | False | uniform | 0.0 | inf |
+-------+--------------------+------+-------+------+-------+------------+-----+-------+
Resolutions: ---------------------------------------------------------------------------------------
+-------+--------------+----------+--------------------+---------+---------+---------+---------+
| index | name | type | value 1 | value 2 | value 3 | value 4 | value 5 |
+-------+--------------+----------+--------------------+---------+---------+---------+---------+
| 0 | Resolution 1 | constant | Resolution Param 1 | | | | |
+-------+--------------+----------+--------------------+---------+---------+---------+---------+
Data: ----------------------------------------------------------------------------------------------
+-------+------------------------+----------------------+---------------------+---------------------+
| index | name | data | data range | simulation range |
+-------+------------------------+----------------------+---------------------+---------------------+
| 0 | Simulation | [] | [] | [0.005, 0.7] |
| 1 | H-tail / D-head / ACMW | Data array: [51 x 3] | [0.051793, 0.58877] | [0.051793, 0.58877] |
| 2 | D-tail / H-head / D2O | Data array: [51 x 3] | [0.051793, 0.58877] | [0.051793, 0.58877] |
+-------+------------------------+----------------------+---------------------+---------------------+
Layers: --------------------------------------------------------------------------------------------
+-------+--------------------+-----------------+------------------------+-----------------+-----------------+--------------+
| index | name | thickness | SLD | roughness | hydration | hydrate with |
+-------+--------------------+-----------------+------------------------+-----------------+-----------------+--------------+
| 0 | Hydrogenated Heads | Heads Thickness | Hydrogenated Heads SLD | Heads Roughness | Heads Hydration | bulk out |
| 1 | Deuterated Heads | Heads Thickness | Deuterated Heads SLD | Heads Roughness | Heads Hydration | bulk out |
| 2 | Hydrogenated Tails | Tails Thickness | Hydrogenated Tails SLD | Tails Roughness | | bulk out |
| 3 | Deuterated Tails | Tails Thickness | Deuterated Tails SLD | Tails Roughness | | bulk out |
+-------+--------------------+-----------------+------------------------+-----------------+-----------------+--------------+
Contrasts: -----------------------------------------------------------------------------------------
+-------+--------------------+-----------------------+-----------------+-------------------+---------+----------+---------------+--------------+----------+--------------------+
| index | name | data | background | background action | bulk in | bulk out | scalefactor | resolution | resample | model |
+-------+--------------------+-----------------------+-----------------+-------------------+---------+----------+---------------+--------------+----------+--------------------+
| 0 | D-tail/H-Head/D2O | D-tail / H-head / D2O | Background D2O | add | SLD Air | SLD D2O | Scalefactor 1 | Resolution 1 | False | Deuterated Tails |
| | | | | | | | | | | Hydrogenated Heads |
| 1 | H-tail/D-Head/ACMW | D-tail / H-head / D2O | Background ACMW | add | SLD Air | SLD ACMW | Scalefactor 1 | Resolution 1 | False | Hydrogenated Tails |
| | | | | | | | | | | Deuterated Heads |
+-------+--------------------+-----------------------+-----------------+-------------------+---------+----------+---------------+--------------+----------+--------------------+
This may initially look quite complicated, but it is fairly self-explanatory in terms of representing a typical RasCAL model (and should make sense to anyone familiar to the RasCAL gui, with some thought). The various aspects of the model definition are grouped together, then eventually combined to make our contrasts. These groups are:
1. The Parameters Group - This block defines all the parameters that we need to specify our model. In our layers case, we need 10 parameters to define our system: A bulk interface roughness, thickness and roughness for the headgroups and tails, and SLD values for the layers, depending on whether they are deuterated or not. In this block we also define the parameter values and their allowed ranges, and specify if they are included in the fit:-
p Name Min Value Max Fit?
__ ________________________ ______ _______ _____ _____
1 "Substrate Roughness" 1 3 5 true
2 "Tails Thickness" 10 20 30 true
3 "Heads Thickness" 3 11 16 true
4 "Tails Roughness" 2 5 9 true
5 "Heads Roughness" 2 5 9 true
6 "Deuterated Tails SLD" 4e-06 6e-06 2e-05 true
7 "Hydrogenated Tails SLD" -6e-07 -4e-07 0 true
8 "Deuterated Heads SLD" 1e-06 3e-06 8e-06 true
9 "Hydrogenated Heads SLD" 1e-07 1.4e-06 3e-06 true
10 "Heads Hydration" 0 0.3 0.5 true
+-------+------------------------+--------+---------+-------+------+------------+-----+-------+
| index | name | min | value | max | fit | prior type | mu | sigma |
+-------+------------------------+--------+---------+-------+------+------------+-----+-------+
| 0 | Substrate Roughness | 1.0 | 3.0 | 5.0 | True | uniform | 0.0 | inf |
| 1 | Tails Thickness | 10.0 | 20.0 | 30.0 | True | uniform | 0.0 | inf |
| 2 | Heads Thickness | 3.0 | 11.0 | 16.0 | True | uniform | 0.0 | inf |
| 3 | Tails Roughness | 2.0 | 5.0 | 9.0 | True | uniform | 0.0 | inf |
| 4 | Heads Roughness | 2.0 | 5.0 | 9.0 | True | uniform | 0.0 | inf |
| 5 | Deuterated Tails SLD | 4e-06 | 6e-06 | 2e-05 | True | uniform | 0.0 | inf |
| 6 | Hydrogenated Tails SLD | -6e-07 | -4e-07 | 0.0 | True | uniform | 0.0 | inf |
| 7 | Deuterated Heads SLD | 1e-06 | 3e-06 | 8e-06 | True | uniform | 0.0 | inf |
| 8 | Hydrogenated Heads SLD | 1e-07 | 1.4e-06 | 3e-06 | True | uniform | 0.0 | inf |
| 9 | Heads Hydration | 0.0 | 0.3 | 0.5 | True | uniform | 0.0 | inf |
+-------+------------------------+--------+---------+-------+------+------------+-----+-------+
2. The Layers Group - Once we have our parameters, we then need to group these into layers, in traditional RasCAL style. For our model, we always have two layers - a headgroup and the associated tails. Each of which can be deuterated, so we set up 4 layers in total, sharing the parameters between the layers as necessary:
p Name Thickness SLD Roughness Hydration Hydrate with
_ ____________________ _________________ ________________________ _________________ _________________ ____________
1 "Hydrogenated Heads" "Heads Thickness" "Hydrogenated Heads SLD" "Heads Roughness" "Heads Hydration" "bulk out"
2 "Deuterated Heads" "Heads Thickness" "Deuterated Heads SLD" "Heads Roughness" "Heads Hydration" "bulk out"
3 "Hydrogenated Tails" "Tails Thickness" "Hydrogenated Tails SLD" "Tails Roughness" "" "bulk out"
4 "Deuterated Tails" "Tails Thickness" "Deuterated Tails SLD" "Tails Roughness" "" "bulk out"
+-------+--------------------+-----------------+------------------------+-----------------+-----------------+--------------+
| index | name | thickness | SLD | roughness | hydration | hydrate with |
+-------+--------------------+-----------------+------------------------+-----------------+-----------------+--------------+
| 0 | Hydrogenated Heads | Heads Thickness | Hydrogenated Heads SLD | Heads Roughness | Heads Hydration | bulk out |
| 1 | Deuterated Heads | Heads Thickness | Deuterated Heads SLD | Heads Roughness | Heads Hydration | bulk out |
| 2 | Hydrogenated Tails | Tails Thickness | Hydrogenated Tails SLD | Tails Roughness | | bulk out |
| 3 | Deuterated Tails | Tails Thickness | Deuterated Tails SLD | Tails Roughness | | bulk out |
+-------+--------------------+-----------------+------------------------+-----------------+-----------------+--------------+
3. ‘Instrument’ Parameters: (Backgrounds, scalefactors and resolutions) - These are necessary to specify our model, and are specified in much the same way as the parameters. The background and resolutions blocks have a more complicated format to allow flexibility in how these are specified, which will be discussed further in a later section. These are the parameters that appear in the experimental Parameters tab of the RasCAL model builder, and are subsequently included in the definitions of the contrasts at the end of the worksheet.
4. Data - Each contrast has to have a dataset associated with it, whether or not it contains data or not. An empty data object (i.e. containing no data and just simulation ranges), means RAT will calculate the reflectivity only. When data is present, chi-squared will also be calculated. For our problem, we have two datasets and these are coded in to the data block ready to be incorporated into contrasts:
Name Data Data Range Simulation Range
________________________ ______________________ _____________________ _____________________
"Simulation" "No Data" "-" "[ 0.0050 , 0.7000 ]"
"H-tail / D-head / ACMW" "Data array: [51 x 3]" "[ 0.0518 , 0.5888 ]" "[ 0.0518 , 0.5888 ]"
"D-tail / H-head / D2O" "Data array: [51 x 3]" "[ 0.0518 , 0.5888 ]" "[ 0.0518 , 0.5888 ]"
+-------+------------------------+----------------------+---------------------+---------------------+
| index | name | data | data range | simulation range |
+-------+------------------------+----------------------+---------------------+---------------------+
| 0 | Simulation | [] | [] | [0.005, 0.7] |
| 1 | H-tail / D-head / ACMW | Data array: [51 x 3] | [0.051793, 0.58877] | [0.051793, 0.58877] |
| 2 | D-tail / H-head / D2O | Data array: [51 x 3] | [0.051793, 0.58877] | [0.051793, 0.58877] |
+-------+------------------------+----------------------+---------------------+---------------------+
5. Contrasts - Once we have defined all the components of our model, we need to group them together into contrasts. We have two datasets we want to consider, so two contrasts. We have the relevant instrument parameters, and also we specify which layers are included in each contrast (model).
p 1 2
___________________ _______________________ ________________________
"Name" "D-tail/H-Head/D2O" "H-tail/D-Head/ACMW"
"Data" "D-tail / H-head / D2O" "H-tail / D-head / ACMW"
"Background" "Background D2O" "Background ACMW"
"Background Action" "add" "add"
"Bulk in" "SLD Air" "SLD Air"
"Bulk out" "SLD D2O" "SLD ACMW"
"Scalefactor" "Scalefactor 1" "Scalefactor 1"
"Resolution" "Resolution 1" "Resolution 1"
"Resample" "false" "false"
"Model" "Deuterated Tails" "Hydrogenated Tails"
"" "Hydrogenated Heads" "Deuterated Heads"
+-------+--------------------+-----------------------+-----------------+-------------------+---------+----------+---------------+--------------+----------+--------------------+
| index | name | data | background | background action | bulk in | bulk out | scalefactor | resolution | resample | model |
+-------+--------------------+-----------------------+-----------------+-------------------+---------+----------+---------------+--------------+----------+--------------------+
| 0 | D-tail/H-Head/D2O | D-tail / H-head / D2O | Background D2O | add | SLD Air | SLD D2O | Scalefactor 1 | Resolution 1 | False | Deuterated Tails |
| | | | | | | | | | | Hydrogenated Heads |
| 1 | H-tail/D-Head/ACMW | D-tail / H-head / D2O | Background ACMW | add | SLD Air | SLD ACMW | Scalefactor 1 | Resolution 1 | False | Hydrogenated Tails |
| | | | | | | | | | | Deuterated Heads |
+-------+--------------------+-----------------------+-----------------+-------------------+---------+----------+---------------+--------------+----------+--------------------+
(b) Running our Model.
As implied from figure (1), running RAT requires not only our input model specification, but also a controls block telling RAT what to do. We will discuss the controls block in more detail in A Closer Look at the Controls Class, but for this demo we will just make an instance of the controls block and modify a few parameters to run the demo:
% Make an instance of controls class
controls = controlsClass();
disp(controls)
# Make an instance of controls class
controls = RAT.Controls()
print(controls)
controlsClass with properties:
parallel: 'single'
procedure: 'calculate'
calcSldDuringFit: 0
display: 'iter'
resampleMinAngle: 0.9000
resampleNPoints: 50
+------------------+-----------+
| Property | Value |
+------------------+-----------+
| procedure | calculate |
| parallel | single |
| calcSldDuringFit | False |
| resampleMinAngle | 0.9 |
| resampleNPoints | 50 |
| display | iter |
+------------------+-----------+
This makes an instance of the controls Class we have called controls. The various properties of the class allow the type of calculation to be specified, in terms of parallelisation, choice of algorithm to be applied and so on. Here we are specifying a single threaded calculation of our reflectivities only (the default) - in other words we are not asking RAT to do any kind of fit with our parameters. We can now send our problem definition and controls classes to the RAT toolbox:
[problem, results] = RAT(problem, controls);
disp(results)
problem, results = RAT.run(problem, controls);
print(results)
Starting RAT ________________________________________________________________________________________________
Elapsed time is 0.159741 seconds.
Finished RAT ______________________________________________________________________________________________
Starting RAT ───────────────────────────────────────────────────────────────────────────────────────────────────────────
Elapsed time is 0.001 seconds
Finished RAT ───────────────────────────────────────────────────────────────────────────────────────────────────────────
It is worth noticing here that this is always the general format for calling RAT. There are two inputs - a problem definition and a controls block, and the result is two outputs - another copy of the problem, and a new, results block.
The problem that returns is a copy of our input, except that the parameter values will be changed by any procedure done. So, if we run a simple fit, then the output problemDef will have the values of the best-fit parameters. Here, we are not doing any fitting yet, and so the output is an exact copy. Also, we overwrite our original input class with the output by using the same name (‘problem’) as an input and an output, but you don’t have to do it this way.
Once we’ve run our model through RAT, then the second output (we call results here) is an array which contains the output of the calculation :
reflectivity: {2x1 cell}
simulation: {2x1 cell}
shiftedData: {2x1 cell}
layerSlds: {2x1 cell}
sldProfiles: {2x1 cell}
resampledLayers: {2x1 cell}
calculationResults: [1x1 struct]
contrastParams: [1x1 struct]
fitParams: [15x1 double]
fitNames: {15x1 cell}
reflectivity = [Data array: [51 x 2], Data array: [51 x 2]],
simulation = [Data array: [51 x 2], Data array: [51 x 2]],
shiftedData = [Data array: [51 x 3], Data array: [51 x 3]],
layerSlds = [[Data array: [2 x 3]], [Data array: [2 x 3]]],
sldProfiles = [[Data array: [182 x 2]], [Data array: [182 x 2]]],
resampledLayers = [[Data array: [1 x 3]], [Data array: [1 x 3]]],
calculationResults = CalculationResults(
chiValues = [278.31497186 463.11042095],
sumChi = 741.4253928160788,
),
contrastParams = ContrastParams(
backgroundParams = [2.8e-06 5.5e-06],
scalefactors = [0.23 0.23],
bulkIn = [0. 0.],
bulkOut = [ 6.35e-06 -5.60e-07],
resolutionParams = [0.03 0.03],
subRoughs = [3. 3.],
resample = [0. 0.],
),
fitParams = [3.],
fitNames = ['Substrate Roughness', 'Tails Thickness', 'Heads Thickness', 'Tails Roughness', 'Heads Roughness', 'Deuterated Tails SLD', 'Hydrogenated Tails SLD', 'Deuterated Heads SLD', 'Hydrogenated Heads SLD', 'Heads Hydration', 'Backs Value ACMW', 'Backs Value D2O', 'Scalefactor 1', 'SLD D2O', 'SLD ACMW'],
This contains the results of our calculations, so for us including the SLD profiles and reflectivities calculated from our problemDef class. We can now plot the output, either manually (by taking the relevant parts from the results array), or using one of the supplied plotting utilities:
fig(1); clf;
plotRefSLD(problem, results)
RAT.plotting.plot_ref_sld(problem, results)
We can see that our model is looking fairly sensible, but that our guess values for the parameters are pretty wide off the mark.