RascalSoftware · alexhroom · Apr 17, 2025 · Mar 14, 2025 · Mar 14, 2025 · Mar 14, 2025
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
@@ -28,6 +28,7 @@ jobs:
 
         wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip
         unzip Linux.zip -d API/
+        rm API/utilities/mockFunction.m  # as otherwise the MATLAB reference fails to parse it
 
         # we get pandoc from web as apt version is outdated
         wget https://github.com/jgm/pandoc/releases/download/3.6.2/pandoc-3.6.2-1-amd64.deb

diff --git a/source/reference/matlab/backgroundsClass.rst b/source/reference/matlab/backgroundsClass.rst
@@ -1,52 +1,19 @@
-.. _table: https://uk.mathworks.com/help/matlab/tables.html
-
 .. _backgroundsClass:
 
 =================
 Backgrounds Class
 =================
 
-This class makes the backgrounds in RAT. Backgrounds are defined in a two stage process. Firstly we define the actual fitted parameters. 
-These are held in a 'ParametersClass' table. Then, we group these into the backgrounds themselves using a multiTypeTable(`table`_). So, we can then use the 
-background parameters to either define background as constant, data or a function.
-
-.. list-table:: The methods on the left call the methods on the right in the table.
-    :widths: 50 50
-    :header-rows: 1
-
-    * - Method in Project Class
-      - Method in backgroundsClass 
-    * - projectClass.addBackgroundParam()
-      - backgroundsClass.backgroundParams.addParameter() 
-    * - projectClass.removeBackgroundParam()
-      - backgroundsClass.backgroundParams.removeParameter()
-    * - projectClass.setBackgroundParamValue()
-      - backgroundsClass.backgroundParams.setValue()
-    * - projectClass.addBackground()
-      - backgroundsClass.addBackground()
-    * - projectClass.removeBackground()
-      - backgroundsClass.removeBackground()
-
-.. note::
- 1. For constant, only one parameter is supplied to multi type table. 
- 2. For data, only the data itself is supplied as a cell. 
- 3. For function, the function name is supplied, along with up to three parameters (from the parameters table) which are then supplied to the function to
-    calculate the background. 
-
-In each case, the background can either be added to the simulation or subtracted from the data.
 
-.. code-block:: MATLAB
-    :caption: Example showing how backgroundsClass methods are called.
+The `backgroundsClass` holds data describing how background noise should be accounted for in the experiment. This data is the type of background (which can
+be either constant, a function, or from data), the source of the background, and any relevant parameters.
 
-        % Change the name of the existing parameters to refer to D2O
-        problem.setBacksPar(1,'name','Backs par D2O','fit',true,'min',1e-8,'max',1e-5);
+- For a constant resolution, the source will be the name of a background parameter (added via `projectClass.addBackgroundParam`;
+- for a data resolution, it will be the name of a data object (added via `projectClass.addData`) with an optional offset background parameter in the `value_1` field;
+- for a function resolution, it will be the name of a custom file (added via `projectClass.addCustomFile`) with up to five background parameters used
+  in the function in fields `value_1` through to `value_5`.
 
-        % Add a new constant background
-        problem.addBackground('Background SMW','constant','Backs par SMW');
 
-*********
-Reference
-*********
 .. default-domain:: mat
 .. autoclass:: API.projectClass.backgroundsClass
-    :members:
+    :members:
diff --git a/source/reference/matlab/contrastsClass.rst b/source/reference/matlab/contrastsClass.rst
@@ -1,48 +1,9 @@
 ===============
 Contrasts Class
 ===============
-Contrast Class is a class to responsible to manipulate contrasts. While adding the contrast, the input(cell array) goes through some checks and if no input is given, the contrast is 
-automatically named and counter is incremented. If only name was given, contrast is incremented and the cell array's name is set to current name.
+The Contrasts Class is a class to manipulate contrasts, which describe a single "experimental sample" (e.g. a level of deuteration).
 
-The cell array of contrasts is sent to Contrast Class to get converted to a struct `parseContrastInput` method which gets attached to the class object.
 
-.. code-block:: MATLAB
-    :caption: Adding a contrast (D20 Contrast)
-
-        problem.addContrast('name','Bilayer / D2O',...
-            'background','Background D2O',...
-            'resolution','Resolution 1',...
-            'scalefactor', 'Scalefactor 1',...
-            'resample',false,....
-            'bulkOut', 'SLD D2O',... 
-            'bulkIn', 'Silicon',...
-            'data', 'Bilayer / D2O');
-
-
-While setting contrasts to a model, `setContrastModel` method is called. This method is called with a cell array of a { number , cell array }. The number being what contrast 
-is and the cell array containing the information about the model. The main purpose of this method is to set the contrast to a model based on specified type of model. Based 
-on the type of model, the code checks whether some of the contrast names are allowed or not. If not, it throws an error.
-
-
-.. code-block:: MATLAB
-    :caption: Setting a contrast to a model
-
-        % 1 refers to the contrast number and the rest Layer information
-        problem.setContrastModel(1,{'Oxide Layer',...
-              'Water Layer',...
-              'Bil inner head',...
-              'Bil tail',...
-              'Bil tail',...
-              'Bil outer head'});
-
-***********************
-Domains Contrasts Class
-***********************
-The Domains Contrasts Class is a simplified model only contrasts class for the Domains calculation.
-
-*********
-Reference
-*********
 .. default-domain:: mat
 .. autoclass:: API.projectClass.contrastsClass
     :members:

diff --git a/source/reference/matlab/customFileClass.rst b/source/reference/matlab/customFileClass.rst
@@ -5,7 +5,7 @@ Custom File Class
 =================
 
 RAT enables users to define their own custom files. They can be linked to RAT through Custom File class. Like other classes, the inputs are checked for
-the right order and type. Also, it uses `table`_ data type to store the custom files. Custom files can be added or removed using the methods this class provides. 
+the right order and type.
 
 The custom file table has the following columns:
 
@@ -15,30 +15,16 @@ The custom file table has the following columns:
 4. Path of the custom file
 
 If the 4 columns are supplied, a new row (cell array of strings) is made using the supplied inputs. Then, `addCustomFile` method is used to append the row to the object.
-This method takes care of the error checking and incrementing the count of the custom files. It also makes a table of the row supplied. This table helps with displaying it 
-properly on terminal.
-
-.. code-block:: MATLAB
-    :caption: Adding MATLAB custom file.
-
-        %                       Row Name   Custom File Name  Language   Path
-        problem.addCustomFile('DSPC Model','customBilayer.m','matlab',pwd);
-
-.. code-block:: MATLAB
-    :caption: Adding C++ custom file.
-
-            % For C++, function name of the cpp file is supplied
-            %                       Row Name        DLL/function Name  Language   Path
-            problem.addCustomFile('DSPC CPP Model','customBilayer','c++',pwd);
+This method takes care of the error checking and incrementing the count of the custom files. The contents of the class are displayed as a table.
 
 
 .. note::
-    RAT only supports C++ (via dynamic library), MATLAB, and Python.
+    RAT supports custom files in C++ (compiled to dynamic library), MATLAB, and Python.
 
 
 *********
 Reference
 *********
 .. default-domain:: mat
 .. autoclass:: API.projectClass.customFileClass
-    :members:
+    :members:
diff --git a/source/reference/matlab/dataClass.rst b/source/reference/matlab/dataClass.rst
@@ -17,37 +17,9 @@ The dataTable is a `table`_ with 4 columns. The following are the 4 columns:
    simulation, and the second element is the maximum value of the simulation. (optional)
 
 
-.. list-table:: The methods on the left call the methods on the right in the table.
-    :widths: 25 25
-    :header-rows: 1
-
-    * - Method in Project Class
-      - Method in Data Class 
-    * - projectClass.addData()
-      - dataClass.addData() 
-    * - projectClass.setData()
-      - dataClass.setData()
-
-
-Like other classes, it has methods to setData, setDataRange or any individual column/parameter. It also checks if the data given is in the right format, 
-and if so, it stores it. If not, it has proper conditional statements to pinpoint the error. Like warning about duplicate names, number of inputs, type of an
-input .. etc. 
-
-.. code-block:: MATLAB
-    :caption: Adding data. Usually, the data is in .dat files. So, `readmatrix` built-in method is used to read the data into a variable.
-
-        D2O_data = readmatrix('c_PLP0016596.dat');
-        % Add the data to the project
-        projectClass.addData('Bilayer / D2O', D2O_data(:,1:3));
-
-.. code-block:: MATLAB
-    :caption: Setting data range. (Min and Max values)
-
-        problem.setData(2,'dataRange',[0.013 0.35]);
-
 *********
 Reference
 *********
 .. default-domain:: mat
 .. autoclass:: API.projectClass.dataClass
-    :members:
+    :members:
diff --git a/source/reference/matlab/entryFunctions.rst b/source/reference/matlab/entryFunctions.rst
@@ -1,7 +1,7 @@
 ===================
 RAT Entry Functions
 ===================
-The user should begin by creating a project and controls object, then the user can run RAT like shown below
+Once a project and controls class have been created, RAT is run via the `RAT` function:
 
 .. code-block:: MATLAB
     :caption: Sample usage of RAT class.
@@ -16,14 +16,12 @@ The user should begin by creating a project and controls object, then the user c
         [problem,results] = RAT(problem,controls);
 
 
-When the RAT function is called, the classes are passed into internal functions like `parseClassToStructs` which takes the classes and breaks them down into cells, 
-limits, priors and more importantly converts the project class to struct. 
+The RAT function turns the `projectClass` and `controlsClass` into relevant structs and cell arrays.
 
-Then, the `RATMain` function redirects the control flow based on what procedure is selected in controlsClass. One of the redirecting functions will call the reflectivityCalculation
-which starts the reflectivity calculation.
+The `parseClassToStructs` function converts the user-friendly data input into an object that can be passed to compiled code.
+
+Then, the `RATMain` function redirects the control flow based on what procedure is selected in `controlsClass`.
 
-Some interesting data type changes are needed because of how things work with coder. Coder wont accept variable sized cell arrays contains variable sized arrays (strings for eg) 
-in a field of a struct. So, look at `parseClassToStructs` function to understand how the data is converted.
 
 .. default-domain:: mat
 .. autofunction:: API.RAT
@@ -32,4 +30,4 @@ in a field of a struct. So, look at `parseClassToStructs` function to understand
 .. autofunction:: API.RATMain
 
 
-.. autofunction:: API.parseClassToStructs
+.. autofunction:: API.parseClassToStructs
diff --git a/source/reference/matlab/index.rst b/source/reference/matlab/index.rst
@@ -10,5 +10,6 @@ MATLAB API Reference
     controlClass
     entryFunctions
     targetFunctions
+    minimisers/index
     plotting
     utilities
diff --git a/source/reference/matlab/layersClass.rst b/source/reference/matlab/layersClass.rst
@@ -1,46 +1,11 @@
 ============
 Layers Class
 ============
+Layers give physical information for each layer in a slab model (such as thickness, SLD, roughness and hydration).
 Layers can be added as a group or individually. When added as a group, `addLayerGroup` method in projectClass iterates over the list of layers and
 adds them one by one using `addLayer` method which is used to add individual layers.
 
-.. list-table:: The methods on the left call the methods on the right in the table.
-    :widths: 25 25
-    :header-rows: 1
 
-    * - Method in Project Class
-      - Method in Layers Class 
-    * - projectClass.addLayerGroup()
-      - layersClass.addLayer() 
-    * - projectClass.addLayer()
-      - layersClass.addLayer()
-    * - projectClass.setLayerValue()
-      - layersClass.setLayerValue()
-
-
-.. code-block:: MATLAB
-    :caption: Adding layers as a group. Can set to a class using projectClass.addLayerGroup(Layers)
-
-        projectClass.addLayerGroup({waterLayer ; bilInnerHead ; bilTails ; bilOuterHead})
-
-
-.. code-block:: MATLAB
-    :caption: Adding layers individually. Can set to a class using projectClass.addLayer(Layer)
-
-        waterLayer = {
-            'Water Layer',...           % Layer name
-            'Water thick',...
-            'Water SLD',...
-            'Bilayer heads rough',...    % Outer interface of the water layer is a bilayer headgroup
-            'Water hydr',...
-            'Bulk out'
-        };
-
-        projectClass.addLayer(waterLayer);
-
-*********
-Reference
-*********
 .. default-domain:: mat
 .. autoclass:: API.projectClass.layersClass
-    :members:
+    :members:
diff --git a/source/reference/matlab/minimisers/de.rst b/source/reference/matlab/minimisers/de.rst
@@ -0,0 +1,8 @@
+Differential Evolution
+----------------------
+
+See :ref:`DE` for information on differential evolution.
+
+.. default-domain:: mat
+.. automodule:: minimisers.DE
+   :members:
diff --git a/source/reference/matlab/minimisers/dream.rst b/source/reference/matlab/minimisers/dream.rst
@@ -0,0 +1,15 @@
+DREAM
+-----
+
+See :ref:`DREAM` for information on DREAM.
+
+.. default-domain:: mat
+.. automodule:: minimisers.DREAM
+   :members:
+
+.. automodule:: minimisers.DREAM.functions
+   :members:
+
+.. automodule:: minimisers.DREAM.postprocessing
+   :members:
+
diff --git a/source/reference/matlab/minimisers/generalUtils.rst b/source/reference/matlab/minimisers/generalUtils.rst
@@ -0,0 +1,11 @@
+General Minimiser Utilities
+---------------------------
+
+General utilities used by the minimisers.
+
+.. default-domain:: mat
+.. automodule:: minimisers.generalUtils
+   :members:
+
+.. automodule:: minimisers.generalUtils.bayesStats
+   :members:
diff --git a/source/reference/matlab/minimisers/index.rst b/source/reference/matlab/minimisers/index.rst
@@ -0,0 +1,17 @@
+Minimisers
+----------
+
+This submodule contains the minimisation algorithms used to optimise
+a model.
+
+For explanatory information on the minimisation algorithms,
+see the :ref:`algorithms section of the documentation<algorithms>`.
+
+.. toctree::
+   :maxdepth: 1
+
+   simplex
+   de
+   ns
+   dream
+   generalUtils
diff --git a/source/reference/matlab/minimisers/ns.rst b/source/reference/matlab/minimisers/ns.rst
@@ -0,0 +1,8 @@
+Nested Sampling
+---------------
+
+See :ref:`nestedSampling` for more information on nested sampling.
+
+.. default-domain:: mat
+.. automodule:: minimisers.NS
+   :members:
diff --git a/source/reference/matlab/minimisers/simplex.rst b/source/reference/matlab/minimisers/simplex.rst
@@ -0,0 +1,8 @@
+Simplex
+-------
+
+See :ref:`simplex` for more information on the Nelder-Mead Simplex method.
+
+.. default-domain:: mat
+.. automodule:: minimisers.simplex
+   :members: