diff --git a/.github/workflows/publishDocs.yml b/.github/workflows/publishDocs.yml deleted file mode 100644 index 5258428fb..000000000 --- a/.github/workflows/publishDocs.yml +++ /dev/null @@ -1,50 +0,0 @@ -name: Publish Docs - -on: - push: - branches: [ master ] - paths: - - 'docs/**' - release: - types: [published] - workflow_dispatch: - inputs: - git-ref: - description: Git Ref (Optional) - required: false - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v2 - with: - submodules: recursive - - name: Checkout gh-pages - uses: actions/checkout@v2 - with: - ref: gh-pages - path: docs/_web - - name: Set up Python 3.9 - uses: actions/setup-python@v2 - with: - python-version: 3.9 - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r docs/requirements.txt - sudo apt-get update && sudo apt-get install -y octave liboctave-dev graphviz - - name: Build and Deploy Docs - run: | - cd docs - make html - octave --no-gui --no-window-system buildM2htmlDocs.m - dot -Tpng build/html/api_reference/graph.dot -o build/html/api_reference/graph.png - python deploy.py ${{github.ref}} - cd _web - git config user.name github-actions - git config user.email github-actions@github.com - git add -A - git commit -m "Publish Documentation" || true - git push diff --git a/.gitignore b/.gitignore index b5d2fc665..bf5ae1f33 100644 --- a/.gitignore +++ b/.gitignore @@ -33,9 +33,6 @@ cppDeploy/ *.mlappinstall *.mltbx _build/ -docs/build/ -docs/.buildinfo -docs/*.inv DREAM_diagnostics.txt __pycache__/ *.o diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 874d7bb84..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "3rdParty/m2html"] - path = 3rdParty/m2html - url = https://github.com/gllmflndn/m2html diff --git a/3rdParty/m2html b/3rdParty/m2html deleted file mode 160000 index e226320f2..000000000 --- a/3rdParty/m2html +++ /dev/null @@ -1 +0,0 @@ -Subproject commit e226320f2ae2fe15342ac070bace9a18a84f522b diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c36aedc7..8603925e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,4 +36,4 @@ The code coverage report should be generated to a htmlcov folder after the tests Documentation ------------- -The documentation is currently in the docs folder. Look at the docs [README](docs/README.md) for more info +The documentation source code is in the [RAT_docs](https://github.com/RascalSoftware/RAT-Docs) repository but the built docs are deployed at https://rascalsoftware.github.io/RAT/ diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf10..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 3ff35bcbb..000000000 --- a/docs/README.md +++ /dev/null @@ -1,33 +0,0 @@ -Documentation -============= -The documentation is in the **docs** folder. This consist of the developer documentation, m2html generated docs, and -user manual. - -Build developer docs --------------------- -The documentation should be built using the provided Sphinx make file. The reStructuredText source is in the docs/source -folder while the build will be placed in the docs/build. The build requires a python executable and the python packages -in the requirements.txt - - conda create -n RAT python=3.9 - conda activate RAT - pip install -r requirements.txt - -In the terminal with access to the the python executable - - cd docs - make html - -Build with m2html ------------------ -The m2html documentation is built using the m2html MATLAB toolbox available in the 3rdParty folder. In the MATLAB -terminal (use 'runMATLABCommand' in any other terminal) - - cd docs - buildM2htmlDocs - - -Build user manual ------------------ -The user manual is still in MS word document and will be converted to restructuredText later. - \ No newline at end of file diff --git a/docs/buildM2htmlDocs.m b/docs/buildM2htmlDocs.m deleted file mode 100644 index e658abe8f..000000000 --- a/docs/buildM2htmlDocs.m +++ /dev/null @@ -1,10 +0,0 @@ -% Download m2html and place it in 3rdParty -cd('..') -path = ['3rdParty', '/m2html']; -addpath(path) - -m2html('mfiles',{'targetFunctions','API'},'htmldir','docs/build/html/api_reference', 'recursive','on',... -'global','on','template','frame', 'index', 'menu', 'graph', 'on', 'source', 'on'); - -% Docs are in the docs folder -disp('The m2html docs are in docs/build/html/api_reference') diff --git a/docs/deploy.py b/docs/deploy.py deleted file mode 100644 index 2c7d0b942..000000000 --- a/docs/deploy.py +++ /dev/null @@ -1,41 +0,0 @@ -import os -import shutil -import sys - -sys.path.insert(0, os.path.abspath('..')) -DOCS_PATH = os.path.abspath(os.path.dirname(__file__)) -VERSION_FILE = os.path.join(DOCS_PATH, '..', 'version.txt') - -ref = 'master' - -with open(VERSION_FILE, 'r') as version_file: - version = version_file.read() - -if len(sys.argv) > 1 and sys.argv[1].strip().endswith(version): - ref = version - -BUILD_PATH = os.path.join(DOCS_PATH, 'build', 'html') -WEB_PATH = os.path.join(DOCS_PATH, '_web', ref) - -if os.path.isdir(WEB_PATH): - shutil.rmtree(WEB_PATH, ignore_errors=True) - -shutil.copytree(BUILD_PATH, WEB_PATH, ignore=shutil.ignore_patterns('.buildinfo', 'objects.inv', '.doctrees', - '_sphinx_design_static')) - -if ref == version: - INDEX_FILE = os.path.join(DOCS_PATH, '_web', 'index.html') - data = [ - '\n', - '\n', - ' \n', - f' Redirecting to https://rascalsoftware.github.io/RAT/{ref}/\n', - ' \n', - f' \n', - f' \n', - ' \n', - '', - ] - - with open(INDEX_FILE, 'w') as index_file: - index_file.writelines(data) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index e8d633c1f..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,41 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "html" ( - %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - - goto end -) - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index b016beea8..000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -sphinx==6.2.1 -sphinxcontrib-matlabdomain==0.18 -sphinx_design==0.5.0 diff --git a/docs/source/ADR.rst b/docs/source/ADR.rst deleted file mode 100644 index 856c7b60e..000000000 --- a/docs/source/ADR.rst +++ /dev/null @@ -1,330 +0,0 @@ -:orphan: - -.. _ADR: - -============================== -Architectural Decision Records -============================== - - -**Alexandrian pattern** -======================== - -Introduction -------------- - -- Prologue (Summary) - -- Discussion (Context) - -- Solution (Decision) - -- Consequences (Results) - -Specifics ---------- - -- Prologue (Summary) - - - Statement to summarize: - - - | In the context of (use case) - | facing (concern) - | we decided for (option) - | to achieve (quality) - | accepting (downside). - -- Discussion (Context) - - - Explain the forces at play (technical, political, social, - project). - - - This is the story explaining the problem we are looking to - resolve. - -- Solution - - - Explain how the decision will solve the problem. - -- Consequences - - - Explain the results of the decision over the long term. - - - Did it work, not work, was changed, upgraded, etc. - -**TLDR: This record contains justifications, reasons as to why something -had to be done, the way it was done, and how to improve on it (as of -July 2022)** - -Decision Record 1: Using Anvil as a webhook and Pull Request trigger for merge checks -===================================================================================== - -.. _introduction-1: - -Introduction -------------- - -`Anvil `__ is a research software -testing platform built by STFC (Science and Technology Facilities -Council) to run tests on a range of platforms in an automated manner. -Anvil is based on Jenkins, a famous DevOps tool, which helps to automate -the mundane tasks of running tests, compilation, etc. - -RAT Toolbox is a CLI application in MATLAB which needs a test suite in -an automated manner and Jenkins proved to be a worthy tool for this job -after talks between Lamar, Martyn and Arwel. - -With Anvil being run on Jenkins, it is decided that Anvil is an -excellent choice to manage the webhooks and merge checks. - -.. _specifics-1: - -Specifics ---------- - -Discussion -########### - -RAT Toolbox is going to be an open-source data analysis software for -Neutron Reflectivity calculations. Once it has become public, it -attracts a wide range of contributors, especially on GitHub. It is -important that the contributors follow certain instructions to NOT break -the code. To ensure that, every time a contributor tries to commit code -into the repository through a pull request, it is decided that the -repository needs to be put through a series of automated tasks to ensure -nothing has been changed in a way that could break the code or result in -unexpected outputs. - -Solution -######### - -The whole thing can be automated using a Jenkins pipeline with Anvil as -a trigger and manager for the webhooks and pull requests, respectively. -Anvil is available to GitHub repositories as a GitHub App that can be -‘downloaded’ into desired repositories from GitHub Marketplace. This -allows Anvil to have proper rights and settings to tether the Pull -Requests to an instance of Jenkins that builds the job in a freshly -created Virtual Machine to make sure everything works in order. - -Consequences ------------- - -This idea seems to be working very well for now and the foreseeable -future as long as Anvil and its dependencies (STFC Cloud) are also -functional. Although, occasional system-wide shutdown causes disruptions -in availability of the nodes in which case developer needs to manually -login to the machine to ssh back to the Jenkins instance of Anvil. -Contact Alan Kyffin for more details on this. - -Decision Record 2: Converting MATLAB code to C++ -================================================ - -.. _introduction-2: - -Introduction ------------- - -RAT is made of MATLAB and so was RasCal. Arwel decided to introduce some -major performance upgrades to RAT by converting MATLAB code base to C++. -A MATLAB app called MATLAB Coder can be used to automatically convert -the MATLAB code into C++ as opposed to the mundane task of -hand-scripting MATLAB to C++. - -.. _specifics-2: - -Specifics ------------ - -“C++ averages a processing speed that is over **500 times** faster than -Matlab code. Not only does this apply for this code, but this can also -be applied for any other code comparison between Matlab and C++ -MEX-files “ (`Andrews `__) - -To be able to use C++ MEX files, MATLAB coder can integrate the -generated code into the projects as source code, static libraries, or -dynamic libraries. The generated code can also be packaged as a -MEX-function for use in MATLAB. Moreover, the generated code is readable -and portable. - -.. _consequences-1: - -Consequences ------------- - -MATLAB coder is a fantastic way to do this task, especially with great -technical support from MathWorks. **Improved speed but introduced a -little bit of complexity to the code.** This could be a stable, -long-standing approach to converting MATLAB code to C++, but more -efficient converters could be on their way, especially with OpenAI’s -`Codex models `__ - -Decision Record 3: Using MATLAB’s Project environment for internal MATLAB workflow -==================================================================================== - -.. _introduction-3: - -Introduction ------------- - -MATLAB’s Project is a scalable environment where one can manage, -customize tasks, put all the files in one place and use version control -from MATLAB. Using such an environment can help reduce time and effort -in simple tasks like running tests, checks etc. So, Arwel and Sethu has -decided to make use of this by putting RAT into this scalable project -environment. - -.. _specifics-3: - -Specifics ---------- - -RAT has many folders with many files in it. Project environment has a -dependency checker which analyses the relations between all the folders -and it also helps prevent unexpected folder/file ‘moves’ which might -bring dependency issues. Moreover, the Project environment can run tests -which is useful, especially while working with the DevOps side. It can -ease the process of code generation since selected files can do selected -tasks. RAT has a file which adds folders to the path so that they can be -accessed straight away while a program is running but this is a manual -task. With the Project environment, the task can be automated using a -startup file that does whatever needs to be done when the Project -environment is instantiated. MATLAB Coder can directly accept a .prj -(project file similar file type for Matlab Coder) and convert desired -files to C++. - -.. _consequences-2: - -Consequences ------------- - -The Project environment eases many mundane tasks hence enabling -automation and solving the problem of adding paths in a separate file -and updating it as new files are being added. The Project environment is -a relatively new feature from MATLAB, with time it can only get better -and assist RAT with more useful tools. - -**Update**: The Project does get complicated especially if a developer -pushes one commit from the Project environment (GUI) which is, -surprising, highly recommended and the other from the command line. It -gets even worse as multiple commits from multiple people follow the -same. This would cause problems of merge conflicts if one were not -careful. - -**Update**: - -Project env has been removed since it is too underdeveloped/too messy to -act as a rigid base for version control and continuous integration. It -is very prone to merge conflicts. Especially, when working from -different OS. - -Decision Record 4: Enabling users to use custom scripts from multiple languages -================================================================================ - -.. _introduction-4: - -Introduction ------------- - -The idea of custom scripts is a jail-break way of achieving extreme -flexibility in terms of data analysis of desired inputs. Having the -flexibility of being able to support languages like python, MATLAB and -C++ really multiplies the users and also provides the feasibility of -adapting to new features by simply adding those corresponding libraries -to the code base. Irrespective of the language used, the compiler adapts -to the language and automatically manages the compatibility issues. - -**Why** -------- - -Flexibility. A user does not have to code in an unfamiliar language to -use the software. Also, increases the user base. - -Specifics ---------------- - -As of July 2022, RAT supports 2 famous languages for the custom models -feature. Matlab and C++. The way it works is as follows: - -1. Converting user’s cpp file into a .dll or .so dynamic lib (in short) - -2. Using an open-source project called dylib to help extract the user - function from the dynamic library made by user and then pass the - inputs to that. (Check dev docs for more) - -3. Get the outputs back. - -Future ------- - -There are plans to add Python to the list of supported languages once -the current iteration is stable enough. - -Decision Record 5: Increasing Error Tolerance to ignore the slight differences in Mex functions in Unit Tests -============================================================================================================== - -.. _introduction-5: - -Introduction ------------- - -There was an error just beyond the RelTol (relative tolerance) limit set -by Arwel which is 4.44089209850063e-15. There are 3 test cases that -crossed the tolerance limit. One of the failed tests has an error of -1.30104260698261e-17. - -**Why** --------- - -Such micro-errors may creep in from compilers and may vary by OS -(Operating System) as well. Since the current experience with error -tolerances is too limited, the ideal tolerance shall be set in the later -stages of development. - -**How** --------- - -The tolerances can be set for each test file in the testSuite folder of -the RAT home directory. Tolerances can also be set by each test as well. -This gives flexibility if one of the functions acts mysteriously. - -Decision Record 6: Use C API to manage custom scripts instead of C++ API for Matlab and back to C++ -==================================================================================================== - -| **Introduction** - -| The whole RAT toolbox is *technically a* C++ codebase and in order to - manage custom scripts from users, the RAT needs to talk to the user - script’s language and make a connection to seek the variables from the - script. - -History -------- - -At first, Arwel and Sethu decided to create a C++ class that constructs -MATLAB Engine pointer which can be referenced to a feval() command to -exercise in MATLAB workspace. This feature helps us exercise user’s -scripts and get them back to C++. The problem with this approach is that -MATLAB Coder is internally embedded with MATLAB Data array and *these -classes are really bad when we include engine.h as a header in our C++.* -A total week of trying to make it work in multiple only concluded that -the approach is impossible. - -| As a plan B, Arwel suggested Sethu to create a class that inherits - from Handle class. This MATLAB class creates an instance of MATLAB - Engine which can started,closed and used to execute a MATLAB function. - This superficially looks absurd especially with executing MATLAB from - MATLAB but the main reason to do this was to have the Handle class - converted to a pointer with Coder’s help. Sethu and Arwel got to a - really good stage with this and then one fine morning, Arwel found out - that the MATLAB coder allows only one instance of handle class to go - through which means we cannot parallelize over multiple instances. - This meant we could not use the MATLAB class anymore. -| This brought us to a new blended idea of using C function in C++ to - eliminate the need for MATLAB in between. This is currently being - worked on but god help us. - -Update: -------- - -God did help us. This method didn’t work out but this work can be used -to compile RAT successfully! (A diff use currently being planned) diff --git a/docs/source/DE.rst b/docs/source/DE.rst deleted file mode 100644 index a84a88652..000000000 --- a/docs/source/DE.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _DE: - -Differential Evolution -...................... - -Differential evolution (DE) is a method that optimizes a problem by iteratively trying to improve a candidate solution with regard to a given measure of quality. It is an -example of a 'genetic algorithm', whereas the principles of Darwinian Evolution are used to 'evolve' the correct solution from an initial set of guesses. - -DE is used for multidimensional real-valued functions but does not use the gradient of the problem being optimized, which means DE does not -require the optimization problem to be differentiable, as is required by classic optimization methods. - -DE optimizes a problem by maintaining a population of candidate solutions and creating new candidate solutions by combining existing ones according to its simple formulae, -and then keeping whichever candidate solution has the best score or fitness on the optimization problem at hand. In this way, the optimization problem is treated as a black box -that merely provides a measure of quality given a candidate solution and the gradient is therefore not needed. - -As with all the RAT algorithms, DE is selected using the 'procedure' attribute of the controls block:- - -.. code-block:: MATLAB - - controls = controlsClass(); - controls.procedure = 'DE' - -This reveals the DE specific parameters in controls:- - -.. image:: images/deControls.png - :width: 600 - :alt: The contrast group - - -For all the algorithms in the RAT implementation of DE (see below), the parameters have the following meanings:- - -populationSize - For DE a number of sets of parameters (population) evolve using random mutation, or exchange of - parameters (analogous to genes!) between the members of the population. - -numGenerations - How many iterations of DE to run. - -crossoverProbability - The probability of exchange of parameters between individuals at each generation (value between [0 - 1]). - -fWeight - A weighting value controlling the stepsize of mutations. - -strategy - The algorithm used (see below). - -Target Value - The value of chi-squared to aim for (algorithm will terminate if this is reached). - - -DE is also somewhat sensitive to -the choice of the stepsize fWeight. A good initial guess is to -choose fWeight from interval [0.5, 1], e.g. 0.8. The crossover -probability (between 0 -1) helps to maintain -the diversity of the population but should be close to 1 for most -practical cases. Only separable problems do better with CR close to 0. -If the parameters are correlated, high values of F_CR work better. -The reverse is true for no correlation. - -The number of population members I_NP is also not very critical. A -good initial guess is 10*I_D. - -The 'strategy' selects between variations in the actual selection agorithm. -The options are:- - -#. DE/rand/1. -#. DE/local-to-best/1. -#. DE/best/1 with jitter. -#. DE/rand/1 with per-vector-dither -#. DE/rand/1 with per-generation-dither -#. DE/rand/1 either-or-algorithm - diff --git a/docs/source/DREAM.rst b/docs/source/DREAM.rst deleted file mode 100644 index 58ef303e8..000000000 --- a/docs/source/DREAM.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _DREAM: - -Bayesian Analysis - DREAM -......................... - -The main Bayesian Sampler bundled with RAT is an implementation of the DREAM (DiffeRential Evolution Adaptive Metropolis) -algorithm first described by `Vrugt`_. - - - - - - - - - - - - - -.. _Vrugt: https://www.sciencedirect.com/science/article/abs/pii/S1364815215300396 diff --git a/docs/source/_static/banner.png b/docs/source/_static/banner.png deleted file mode 100644 index 8f287cf3c..000000000 Binary files a/docs/source/_static/banner.png and /dev/null differ diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png deleted file mode 100644 index f13892744..000000000 Binary files a/docs/source/_static/logo.png and /dev/null differ diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst deleted file mode 100644 index 1929d1232..000000000 --- a/docs/source/advanced.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _advanced: - -=============== -Advanced Topics -=============== -In this section we discuss some of the advanced features of the toolbox:- - - -.. toctree:: - :maxdepth: 2 - - resampling - parallelisation - customLanguages - events - - - diff --git a/docs/source/algorithms.rst b/docs/source/algorithms.rst deleted file mode 100644 index 3808d1fb7..000000000 --- a/docs/source/algorithms.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _algorithms: - -========== -Algorithms -========== - -RAT has 4 built-in algorithms for data fitting and analysis. The Nelder-Mead Simplex and Differential Evolution -are traditional minimisers, whereas the other two (DREAM and Nested Sampling) are Bayes samplers. The use -of an external library (`Paramonte`_.) for Bayesian sampling is also supported. - - -.. toctree:: - :maxdepth: 2 - - simplex - DE - DREAM - nestedSampling - paramonte - -.. _Paramonte: https://www.cdslab.org/paramonte/ \ No newline at end of file diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index b566d6b10..000000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,440 +0,0 @@ -:orphan: - -===== -API -===== - -API is the folder that contains the two main classes of RAT are. They are **Project Class** and **Controls Class** and these are the classes user interacts with. - -.. note:: - The "API" name comes from the generalized view how APIs work. In this case, the API sends the information back and forth from the top level classes to targetFunctions. - - -.. _ProjectClass: - -Project Class -============== -Project Class is all about data. It contains the very data user wants to work with. It stores all the data required for reflectivity calculations. -Everything in RAT comes from projectClass in one way or another. There are many functions that deal with breaking down the data from Project Class into smaller pieces -so that they can be used in other parts of the software. - - -Project Class has lot of other classes that help create objects for inputs. They are : - -1. Parameter Class -2. Resolution Class -3. Data Class -4. Contrasts Class -5. Custom File Class - -.. note:: - Most of these classes have the following in common: - - 1. They are all called from Project Class. - 2. Methods to add or remove or change an attribute depending on the class. - 3. Methods to find the location based on input value. Finding row when given an attribute's name or vice versa (Not all of them though). - 4. Display methods. - 5. A 'toStruct' method which output the class parameters as a struct. - - -Parameters Class ------------------ - -Parameters Class helps to add,set or remove parameters to the Project Class. The class has a constructor that gets initiated when Parameter class is called. This constructor -sets important initial values to the class obj (object) like variable name, types. It also initiates a "table" that helps to store all the parameters. Table is a really useful -data type provided by matlab. Check this link to know more about `table`_. - -.. 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 Parameters Class - * - projectClass.addParamGroup() - - parametersClass.addParam() - * - projectClass.addParam() - - parametersClass.addParam() - * - projectClass.removeParam() - - parametersClass.removeParam() - * - projectClass.setParameter() - - parametersClass.setParameter() - * - projectClass.setParameter() - - parametersClass.setValue() - - -When adding parameters, they can be added individually or as a group (see below). When added as a group, `addParamGroup` method in projectClass iterates over the -list of parameters and adds them one by one using `addParam` method which is used to add individual parameters. - -.. code-block:: MATLAB - :caption: Adding parameters as a group. Can set to a class using projectClass.addParamGroup(Parameters) - - Parameters = { - % Name min val max fit? - {'Oxide thick', 5, 20, 60, true }; - {'Oxide SLD', 3e-6, 3.41e-6, 4e-6, false }; - {'Oxide Hydration' 0, 20, 30, true }}; - - -.. code-block:: MATLAB - :caption: Adding parameters individually. Can set to a class using projectClass.addParam(Parameter) - - Oxide = {'Oxide Layer',... % Name of the layer - 'Oxide thick',... % Layer thickness - 'Oxide SLD',... % Layer SLD - 'Substrate Roughness',... % Layer roughness - 'Oxide Hydration',... % Oxide hydration (percent) - 'bulk out' }; % Which bulk phase is hydrating the layer - - % Add this to the projectClass... - projectClass.addLayer(Oxide); - -.. _table: https://uk.mathworks.com/help/matlab/tables.html - -When *addParam* method is called, the method checks the input through a series of checks to find out -if there are any unexpected values at unexpected places. For example, having logical value in place of a numerical value argument. With *setParameter* method, -one can set the value of any parameter independently. However, there are other methods that helps setting individual parameters. For example, *setName* method helps -to set the name of a parameter. - -.. note:: - - 1. You can add Bulk in and Bulk out with this class - 2. You can add scale factor with this class - - - -Layers in Project Class ------------------------------- -Like Parameters, 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_realSLD.addLayer() - * - projectClass.addLayer() - - layersClass_realSLD.addLayer() - * - projectClass.setLayerValue() - - layersClass_realSLD.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); - - -Bulk In and Bulk Out ---------------------- -Bulk In and Bulk Out are ........................to be added. They are set using the `addParam` method in parameter class since they have the same columns in the table. - -.. 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 Parameter Class - * - projectClass.addBulkIn/addBulkOut() - - parametersClass.addParam() - * - projectClass.removeBulkIn/removeBulkOut() - - parametersClass.removeParam() - * - projectClass.setBulkIn/setBulkOut() - - parametersClass.setParameter() - -Although, Project class provides one level higher interface so that one can use `addBulkIn` and `addBulkOut` methods from projectClass to set these parameters. - -.. code-block:: MATLAB - :caption: Adding Bulk Out. Can set to a class using projectClass.addBulkOut(BulkIn) - - % Name min val max fit? - problem.addBulkOut({'SLD SMW',2e-6,2.073e-6,3e-6,true}); - - - -`setParameter` or `setBulk(In/Out)` does the same thing which is converting cell array to struct. - -Background 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.addBacksPar() - - backgroundsClass.addBacksPar() - * - projectClass.removeBacksPar() - - backgroundsClass.removeBacksPar() - * - projectClass.setBacksPar() - - backgroundsClass.setBacksPar() - * - projectClass.addBackground() - - backgroundsClass.addBackground() - * - projectClass.removeBackground() - - backgroundsClass.removeBackground() - * - projectClass.setBackground{Value/Name}() - - backgroundsClass.setBackground{Value/Name}() - -Some of the methods of Background Class are: - -1. `addBacksPar` - This method adds the parameter to the back parameter table. -2. `setBacksParValue` - Set a parameter value in the back parameter table. -3. `removeBacksPar` - Remove a parameter from the backsPar/ back parameter table. -4. `addBackground` - Add a background to the background table. -5. `setBackground` - Set a background value in the background table. (Based on row) - - -.. 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. - - % 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); - - % Add a new constant background - problem.addBackground('Background SMW','constant','Backs par SMW'); - - -Multi-Type Table -################# -Multi-type Table is a custom table type. It is a general type of table that can altered to one's needs by taking advantage of methods that allow -adding rows, setting values of an element, etc. This class is used in Background Class. - - -Data Class ------------ - -Data Class is a class to helps add or set data. Data can be addded using `addData` method. The `addData` method expects a cell array of cell array. Like other methods there's -a check that directs different cases based on the length of inputs (1 meaning only name or data entered. If only name is entered, error prompted saying 'Single input is expected -to be data name'. Case 2 being both name and data supplied and data is added accordingly). It uses `table`_ data type to do that. -The dataTable is a `table`_ with 4 columns. The following are the 4 columns: - -1. Name of the data -2. Second column is the data itself -3. Data range. The data range is a cell array with two elements, the first element is the minimum value of the data, and - the second element is the maximum value of the data. (optional) -4. Simulation range. The simulation range is a cell array with two elements, the first element is the minimum value of the - 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, `dlmread` built-in method is used to read the data into a variable. - - D2O_data = dlmread('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]); - - -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 custom file table has the following columns: - -1. Name of the row in the Custom File table -2. Name of the custom file -3. Language of the custom file -4. Path of the custom file - -If all of the 4 columns are supplied, a new row (cell array of strings) is made using the supplied inputs. Then, `appendNewRow` method is used to append the row to the obj. -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); - - - - -.. warning:: - RAT only supports C++, MATLAB, Octave and potentially Python. - - -Contrast 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 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,.... - 'nbs', 'SLD D2O',... % This is bulk out ('Nb Subs') - 'nba', 'Silicon',... % This is bulk in ('Nb Air') - '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 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'}); - - -Resolution Class ----------------- - -Resolutions are defined in a two stage process. Firstly, actual fitted parameters are defined. These are held in a 'Parameter Class' table (referring to data type). -Then,these are grouped into the resolutions themselves using a multi-type table. Then the resolution parameters can be used to either define resolution as -constant, data, or a function. - -The constructor is called with the parameters and resolutions as input. The parameters are stored in the resolPars table whereas the resolutions are stored in -the resolutions table and the allowed types are defined in the allowedTypes variable. - -.. note:: - - 1. For constant only one parameter is supplied to multi-type table. - 2. For data, the name is supplied, along with name of the data in the data table. - 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 resolution. - -In each case, the Resolutions can either be added to or subtracted from the data. - - -.. _controlsClass: - -Controls Class -============== - -ControlsClass is all about control. It is necessary in determine the way RAT works. It deals with how the user interacts with the software. From type of parallelization -to whether the users wants to calculate SLD during fit and even how many iteration an algorithm should do ..etc. - - -There are 5 different `controlsClass.procedures` that can be used with RAT. They are: - -1. **Simplex** -2. **Differential Evolution** - Optimizes a problem by iteratively improving a candidate solution based on an evolutionary process -3. **Nested Sampler** - Estimates directly how the likelihood function relates to prior mass -4. **DREAM** -5. **Calculate** - -Each of them has their own unique set of options. The fields in class object of controlsClass are -automatically updated based on the procedure selected. - -RAT uses parallelization to speed up the calculation. This is achieved using Parallel Computing Toolbox. The user can choose to use the parallelization or not and -if yes, what to parallelize on. (Points or Contrasts or all) - -.. code-block:: MATLAB - :caption: Sample usage of controlsClass. - - controls = controlsClass(); - controls.calcSldDuringFit = false; - controls.nsimu = 7000; - controls.repeats = 3; - controls.parallel = 'contrasts'; - -.. code-block:: MATLAB - :caption: Alternate usage of controlsClass. - - controls = controlsClass(); - controls = controls.setProcedure('dream',... - {'nSamples', 6000,... - 'nChains', 10,... - 'parallel', 'contrasts'}) - -RAT -==== - -After the user has defined the projectClass and controlsClass, the user can run RAT like shown below - -.. code-block:: MATLAB - :caption: Sample usage of RAT class. - - % Initialize the project class - problem = projectClass(); - - % Initialize the controls class - controls = controlsClass(); - - % call the RAT function - [problem,results] = RAT(problem,controls); - - -When the RAT function is called, the classes are passed into internal functions like `RatParseClassToStructs_new` which takes the classes and breaks them down into cells, -limits,prior and more importantly converts the project class to struct. - -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. - - -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 `RatParseClassToStructs_new` function to understand how the data is converted. diff --git a/docs/source/backgroundsClass.rst b/docs/source/backgroundsClass.rst deleted file mode 100644 index 48d0fd243..000000000 --- a/docs/source/backgroundsClass.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _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. - - % 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); - - % Add a new constant background - problem.addBackground('Background SMW','constant','Backs par SMW'); - - -Reference ---------- -.. autoclass:: API.projectClass.backgroundsClass - :members: \ No newline at end of file diff --git a/docs/source/calcTypes.rst b/docs/source/calcTypes.rst deleted file mode 100644 index 145fc9c92..000000000 --- a/docs/source/calcTypes.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _calcTypes: - -=========================== -Different Calculation Types -=========================== -The previous sections discuss more conventional reflectivity calculations. RAT can also handle more advanced calculation types, and -these are discussed in the following sections: - - -.. toctree:: - :maxdepth: 2 - - imaginary - incoherent - oilWater - magnetic diff --git a/docs/source/chapter1.rst b/docs/source/chapter1.rst deleted file mode 100644 index 87c2fe203..000000000 --- a/docs/source/chapter1.rst +++ /dev/null @@ -1,174 +0,0 @@ -.. _chapter1: - - -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: - -.. image:: images/userManual/chapter1/ratInput.png - :alt: RAT input model - -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 the next chapter where we look at the outputs in more detail. Similarly, we will look in more detail at the input classes in the next section. - -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's 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. These are (those in italics not initial release): - - * 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'). - * *Oil/Water problem type (phase 2)* - * *Polarised problem type (phase 2)* - -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 RasCAL1 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 (:ref:`conversionFuncs`). In fact, for those who prefer a graphical model builder, using the RasCAL1 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's -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. - -.. image:: images/userManual/chapter1/lipidMonolayer.png - :width: 300 - :alt: The lipid monolayer example - -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's 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 *projectClass* 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 chapter 2, but for now, we'll look at a pre-prepared example. - -.. code-block:: MATLAB - - % Load in a pre-made problem Definition class - problem = load('twoContrastExample.mat'); - problem = problem.problem; - - % Have a look at what we have - disp(problem) - - -.. image:: images/userManual/chapter1/lipidModel-1.png - :width: 700 - :alt: The lipid monolayer model output display (first half) -.. image:: images/userManual/chapter1/lipidModel-2.png - :width: 700 - :alt: The lipid monolayer model output display (second half) - -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:- - -.. image:: images/userManual/chapter1/parameterGroup.png - :width: 500 - :alt: The parameter group - -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: - -.. image:: images/userManual/chapter1/layersGroup.png - :width: 900 - :alt: The layers group - -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: - -.. image:: images/userManual/chapter1/dataGroup.png - :width: 900 - :alt: The data group - -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*). - -.. image:: images/userManual/chapter1/contrastGroup.png - :width: 900 - :alt: The contrast group - -**(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 Chapter 4, but for this demo we will just make an instance of the controls block and modify a few parameters to run the demo: - -.. image:: images/userManual/chapter1/controlsClass.png - :width: 400 - :alt: Control class - -This makes an instance of the *controlsClass* 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: - -.. image:: images/userManual/chapter1/ratRun.png - :alt: RAT run - -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 : - -.. image:: images/userManual/chapter1/dispResults.png - :alt: disp(results) - -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: - -.. code-block:: MATLAB - - fig(1); clf; - plotRefSLD(problem, results) - -.. image:: images/userManual/chapter1/plots.png - :alt: reflectivity and SLD plots - -We can see that our model is looking fairly sensible, but that our guess values for the parameters are pretty wide off the mark. - - - - - - diff --git a/docs/source/chapter2.rst b/docs/source/chapter2.rst deleted file mode 100644 index 18e868478..000000000 --- a/docs/source/chapter2.rst +++ /dev/null @@ -1,623 +0,0 @@ -.. _chapter2: - - -The Problem Definition Input Class -.................................. -In the previous section, we saw an example of how we set up and run an analysis using the RAT toolbox. Every call to the toolbox has two parts: the **problem definition** class, where we define the model, add the data and define our contrasts, and the **controls class** where we -tell the toolbox what type of analysis we would like to do. The reason for splitting things up in this way is that once our model is defined, we can interact with it in various ways without needing to modify the model. So, we can experiment with our data, trying out different types of analysis, and explore the -landscape of solutions by simply modifying the *controls* class, leaving the *problem* class alone. - -As well as having two inputs, RAT always provides two outputs, so the call to the toolbox is always of this form:- - -.. code-block:: MATLAB - - [problem, results] = RAT(problem, controls) - -In this case we have called our inputs *problem* and *controls*, but they can be called anything. Likewise, we have called our outputs *problem* and *results*, but we are free to call them anything we like. We will look at the outputs in more detail in the next section. - -The first input, *problem*, is an instance of a class called *projectClass*: - -.. code-block:: MATLAB - - >>> problem = projectClass('my project'); - >>> class(problem) - - ans = - 'projectClass' - -And if we take a look at it, we can see the class contains a series of sections, where we can define our parameters, make different kinds of model, load in our data and do everything we need to set up our model. - -.. image:: images/userManual/chapter2/model1.png - :alt: model (first half) -.. image:: images/userManual/chapter2/model2.png - :alt: model (second half) - -We can see that the class has a number of attributes, defining all we need for our analysis. In our case, we have no parameters or data, and have not defined any contrasts, so this will not do anything useful in RAT. Defining a model is a case of populating the sections in the project class, which we do using the class methods: - -.. image:: images/userManual/chapter2/projectClassMethods.png - :alt: Project Class Methods - -It's clear from the method names (i.e. *addData*) that these methods are going to be useful to us for building our model. In the following sections, -we will look at each of these methods and see how they can be used to define our reflectivity analysis problem. (There is also a utility which will convert a RasCAL model into a *projectClass* for use in RAT. -This means that you can use the RasCAL GUI to set up your model if you like and then use the speed of RAT to conduct your analysis.) - -In terms of the outputs, note that we have called the first output *problem*, but we don't need to do that. The first of the two outputs is another **projectClass**, but updated with the results of the calculation. -So, if we run a fit, the fitted parameters will be updated with the best fit values of our procedure. In giving the output the same name as the input, we're overwriting our input with best fit values, but if you don't -want to do this, you can give the inputs and outputs different names (e.g. '[outProblem,results] = RAT(problem,controls)'' or whatever you like). The second output can also be called whatever you like, and this is a struct -containing the simulated reflectivities, SLD's and so on from whatever procedure you have asked RAT to do: - -.. image:: images/userManual/chapter2/reflectivitiesStruct.png - :width: 300 - :alt: Reflectivities Struct - -In the next sections, we'll discuss the methods of the **projectClass**, and see how they allow us to build up a model by populating the various sections. - -The Components of ProjectClass -============================== - -**Project Defining Methods** -++++++++++++++++++++++++++++ - -The first step is always to create an instance of the **projectClass** to hold our model. This is always done by assigning **projectClass** to our variable name (we will mostly use *problem* in this manual, but it can be anything), which always requires a name for our project as an input: - -.. code-block:: MATLAB - - problem = projectClass('My Problem'); - -This creates an instance of **projectClass** and assigns it to the variable *problem*, and gives it the title 'My Problem'. - -The first part of the created *problem* has two other settable fields: *modelType* and *Geometry*. - -**Geometry -** This can be set to either *air/substrate* or *substrate/liquid* using the **setGeometry** method. It can take the values of *air/substrate* or *substrate/liquid*. - -.. code-block:: MATLAB - - >> problem.setGeometry('air/substrate'); - >> problem.setGeometry('substrate/liquid'); - -The effect of this parameter is in the numbering of roughness's in layer models. In any model for n-layers, -there are always n+1 associated interfaces, and hence n+1 roughness parameters required. In RAT, the bulk interface roughness -is a protected parameter and always exists, and this parameter controls where this roughness is placed in the layer stack. So, for two layers defined with thickness, -SLD and roughness as [d\ :sub:`1`, :math:`\rho_\mathrm{1}`, r\ :sub:`1`] and [d\ :sub:`2`, :math:`\rho_\mathrm{2}`, r\ :sub:`2`], then for the *substrate/liquid* geometry -the substrate roughness is placed as the first roughness the beam meets, and the layer roughness's refer to the interface after the particular layer. -or the *air/substrate* case, the opposite is true, and the substrate roughness is the last roughness in the stack, with the layer roughness referring to the interface before each layer. - -ModelType - As is the case for RasCAL, there are three ways of defining models in RAT:- - -* **Standard Layers** - The model is defined in terms of parameters, which are distributed into layers, and subsequently grouped into contrasts. No external functions are needed. -* **Custom Layers** - Parameters are again defined and grouped into layers, but this time the layer definitions come from a user model script. This then gives complete flexibility of how layers are defined, so allowing models to be written in terms of area per molecule or material density, for example. This custom script controls translating these input parameters into a [d, :math:`\rho`, r] model. This is probably the most useful operating mode for RasCAL. -* **Custom XY-Profile** - This modelling mode also relies on a custom model function, but in this case does away with [d, :math:`\rho`, r] layers completely. Instead, the custom function uses the parameters to define a continuous SLD profile, which RAT then uses to calculate the reflectivity. - -The model type is set using the **setModelType** method: - -.. code-block:: MATLAB - - >> problem.setModelType('standard layers'); - >> problem.setModelType('custom layers'); - >> problem.setModelType('custom XY'); - -Custom modelling is described in more depth in a later section. - -**The ‘Parameters’ Block** -++++++++++++++++++++++++++ - -Any model, where it be layers or anything else is always defined by parameters. These appear in the parameters block and are specified by a name, a value, minimum and maximum ranges and a flag defining whether the parameter is fitted or fixed: - -.. image:: images/userManual/chapter2/parameterBlock.png - :width: 500 - :alt: Parameter Block - -The substrate roughness is a protected parameter in all cases (it defines the Fresnel roughness) and cannot be renamed or deleted. Its values can be set to any numerical values however. - -To add a parameter, you can use the **addParam** method, either by just specifying a name, in which case the parameter takes on default values, or by specifying the whole parameter at once (note the Matlab cell array curly brackets syntax for the latter): - -.. code-block:: MATLAB - - >> problem.addParameter('My new param'); - >> problem.addParameter('My other new param',10,20,30,false); - -To avoid having to make a whole load of **addParam** statements for large projects with many parameters, you can define them at once in a cell array, and add them using the **addParamGroup** method (again notice the curly brackets syntax - this is a {cell array of {cell arrays}} : - -.. code-block:: MATLAB - - pGroup = {{'Layer thick', 10, 20, 30, true}; - {'Layer SLD', 1e-6, 3e-6 5e-6, true}; - {'Layer rough', 5, 7, 10, true}}; - - >> problem.addParameterGroup(pGroup) - -The resulting parameters block looks like this: - -.. image:: images/userManual/chapter2/resultingParameterBlock1.png - :width: 400 - :alt: Parameter Block after adding param group - -.. note:: - Parameters can't have duplicate names. Attempting to duplicate a name will throw an error. This can cause problems when loading in RasCAL1 projects - where duplicate names are allowed. - -To subsequently change the values of the parameters (including names), there are a few methods you can use. For each of the methods, you can refer to the parameter by its name or its number. There are dedicated methods for each of the attributes of the parameters: - -.. code-block:: MATLAB - - problem.setParameterName('My new param', 'My changed param'); - problem.setParameterConstr(2,0.96,3.62); - problem.setParameterValue(4,20.22); - problem.setParameterFit('Layer rough',false); - -.. image:: images/userManual/chapter2/resultingParameterBlock2.png - :width: 600 - :alt: Parameter Block after changing properties - -Alternatively, you can set a number of properties of a given parameter at once using name / value pairs. - -.. code-block:: MATLAB - - problem.setParameter(4,'name','thick','min',15,'max',33,'fit',false) - -.. image:: images/userManual/chapter2/resultingParameterBlock3.png - :width: 600 - :alt: Parameter Block after changing properties using set parameter - -You can remove a parameter from the block using its name or number. Note that if you remove a parameter from the middle of the block, subsequent parameter numbers will change. Also, if you try to remove the substrate roughness you will get an error: - -.. code-block:: MATLAB - - problem.removeParameter(4); - -.. image:: images/userManual/chapter2/resultingParameterBlock4.png - :width: 600 - :alt: Parameter Block after removing a parameter - -.. image:: images/userManual/chapter2/parameterRemoveError.png - :width: 600 - :alt: Error when trying to remove Substrate Roughness - -**The Layers Block (Standard Layers models only)** -++++++++++++++++++++++++++++++++++++++++++++++++++ - -For each of the custom models cases, the model building is done using a script (discussed in detail in chapter 3). For standard layers models however, model building is done by grouping the parameters into layers, and then into contrasts (as is the case for RasCAL). The layers block is not visible when either of the two custom modes is selected. Again, layers are built using methods of the project class. As an example here, we make a new project class, add some parameters, and create some layers. - -For this example, we will make two layers representing a deuterated and hydrogenated version of the same layer. So, the layers will share all their parameters except for the SLD. - -Start by making a new project, and adding the parameters we will need: - -.. code-block:: MATLAB - - problem = projectClass('Layers Example'); - - params = {{'Layer Thickness', 10, 20, 30, false}; - {'H SLD', -6e-6, -4e-6, -1e-6, false}; - {'D SLD', 5e-6, 7e-6, 9e-6, true}; - {'Layer rough', 3, 5, 7, true}; - {'Layer hydr', 0, 10, 20, true}}; - - problem.addParameterGroup(params); - -A layer is defined in terms of a name, thickness, SLD, roughness and (optional) hydration, along with details of which bulk phase is hydrating the layer. The easiest way to define these is to group the parameters into cell arrays, and then add them to the project as a layers group: - -.. code-block:: MATLAB - - % Make the layers - H_layer = {'H Layer','Layer Thickness','H SLD','Layer rough','Layer hydr','bulk out'}; - D_layer = {'D Layer','Layer Thickness','D SLD','Layer rough','Layer hydr','bulk out'}; - - % Add them to the project - as a cell array{}.. - problem.addLayerGroup({H_layer, D_layer}); - -Our two layers now appear in the Layers block of the project: - -.. image:: images/userManual/chapter2/twoLayerGroup.png - :alt: Layers after adding two layers - -Note that in RAT, hydration is percent hydration between 0 and 100. It is not necessary to define a hydration at all, and we can also make layers without this parameter: - -.. code-block:: MATLAB - - % Non hydrated layer - Dry_Layer = {'Dry Layer', 'Layer Thickness', 'D SLD', 'Layer rough'}; - problem.addLayer(Dry_Layer); - -.. image:: images/userManual/chapter2/threeLayerGroup1.png - :alt: Layers after adding third dry layer - -To set the value of an existing layer, you can use the 'setLayerValue' method, at the moment using numbers for the layer number, layer parameter and parameter to be changed. So for example: - -.. code-block:: MATLAB - - problem.setLayerValue(1,2,3); - -changes parameter 2 (Thickness) of Layer 1 (H Layer) to the 3rd Parameter of the parameter block (H SLD): - -.. image:: images/userManual/chapter2/threeLayerGroup2.png - :alt: Layers after changing thickness - -.. note:: - SetLayer Value allows the use of names rather than numbers if required because numbers are not very intuitive. - -The layers are then used to set up the contrasts as usual with a standard layers model. - -**Bulk Phases** -+++++++++++++++ - -These are treated in the same way as parameters e.g. - -.. code-block:: MATLAB - - problem.addBulkIn('Silicon',2.0e-6,2.07e-6,2.1e-6,false); - problem.addBulkOut('H2O',-0.6e-6,-0.56e-6,-0.5e-6,false); - -.. image:: images/userManual/chapter2/bulkPhases.png - :width: 600 - :alt: Bulk In and Bulk Out - -There are no individual methods for each parameter of these, but the values can be modified using name / value pairs as is the case for parameters, using the **setBulkIn** and **setBulkOut** methods e.g. - -.. code-block:: MATLAB - - problem.setBulkOut(1, 'value', 5.9e-6, 'fit', true); - -**Scalefactors** -++++++++++++++++ -The *scalefactors* are another parameters block like the bulk phases. You can add *scalefactors* with the **addScalefactor** method. Similarly, you can set the values with the **setScalefactor** method as with the previous blocks. - -.. code-block:: MATLAB - - problem.addScalefactor('New Scalefactor',0.9,1.0,1.1,true); - problem.setScalefactor(1,'value',1.01); - -**Backgrounds** -+++++++++++++++ -The backgrounds block is used to define the type of background applied to each contrast, and the parameters used to define the backgrounds themselves. The fittable parameters are in the -'Background Params' block, and the backgrounds themselves are in the 'Backgrounds' block: - -.. image:: images/userManual/chapter2/basicBackground.png - :width: 800 - :alt: basic background - -The 'Background Parameters' is in fact another instance of the parametersClass, and there are corresponding methods to fit, set limits and so on for these. - -The backgrounds can be one of three types: 'constant', 'function' or 'data'. The three types are discussed in more detail below: - -.. note:: - Only 'constant' and 'data' are allowed in phase 1, and 'function' will be introduced in phase 2. - -* **Constant** - This is the normal background type from RasCAL1. Each background requires one *and only one* Background Parameter associated with it, as follows: - -.. code-block:: MATLAB - - problem.addBackgroundParam('My New Backpar',1e-8,1e-7,1e-6,true); - problem.addBackground('My New Background','constant','My New BackPar'); - -With this code snippet we've made a new background, with the value taken from the (fittable) parameter called 'My New Backpar': - -.. image:: images/userManual/chapter2/constBackgroundAdd.png - :width: 800 - :alt: basic background - -This is then available to be used by any of our contrasts (see later). - -* **Data** - This option is used when a measured data background is available. Suppose our measured data is in a datafile loaded into the data block (see later), and called 'My Background Data'. To define a data background, we simply specify this datafile in our background specification: - -.. code-block:: MATLAB - - problem.addBackground('Data Background 1','data','My Data Background') - -.. image:: images/userManual/chapter2/dataBackground.png - :width: 800 - :alt: data background - -This is then used in the reflectivity calculation for any contrast in which it is specified. - -.. note:: - No 'Background Parameters' are associated with data backgrounds. Also, take care to make sure that the background and data with which it is intended to be used *have the same q values*, otherwise an interpolation will be carried out which will be slower. - -**Resolutions** -+++++++++++++++ -As is the case for the backgrounds, the resolutions block is also splot into two parts: a parameters block which defines the fittable parameters, and then the main Resolutions block which groups these as required into actual resolutions. -The three types are: - -* **Constant**: The default type. A resolutionParameter defines the width of a sliding Gaussian window convolution applied to the data. -* **Function**: Convolution of the data with an arbitrary, user defined function (not yet implemented). -* **Data**: Convolution with a sliding Gaussian defined by a fourth column of a datafile. - - -.. note:: - Only 'Constant' and 'Data' are implemented in phase 1. Convolution with an arbitrary function will be introduced in phase 2. - -To define a resolution parameter, we use the addResolutionParam method: - -.. code-block:: MATLAB - - problem.addResolutionParam('My Resolution Param',0.02,0.05,0.08,true) - -.. image:: images/userManual/chapter2/resolClass.png - :width: 800 - :alt: resolution class - - -Then, we make the actual resolution referring to whichever one of the resolution parameters: - -.. code-block:: MATLAB - - problem.addResolution('My new resolution','constant','My Resolution Param') - problem.addResolution('My Data Resolution','data') - -.. image:: images/userManual/chapter2/resolClassModified.png - :width: 800 - :alt: resolution class with parameters added - -.. note:: - There are no parameters with Data resolution. Instead this tells RAT to expect a fourth column in the datafile. If no fourth column exists in the data to which this is applied, RAT will throw an error at runtime. - - - -**Data** -++++++++ -The data block contains the data which defines at which points in q the reflectivity is calculated at each contrast. By default, it initialises with a single 'Simulation' entry: - -.. image:: images/userManual/chapter2/defaultData.png - :width: 800 - :alt: default Data class - -For each entry in the table there are four fields: - -* **Name** : The name you choose to give the datafile (for reference in the contrasts block) -* **Data** : An array containing the data itself (empty for Simulation). -* **Data Range** : The min / max range of the data you wish to include in the fit. As is the case for RasCAL, you do not have to include all the data in the calculation of chi-squared. This range cannot lie outside the range of any data added to the second column. -* **Simulation Range** : The total range of the simulation to be calculated. This can lie outside the range of the data to allow for extrapolation, but must be >= the overall data range. - -To add data, we first load it into Matlab, then create a new data entry containing it: - -.. code-block:: MATLAB - - >> myData = dlmread('c_PLP0016596.dat'); - >> problem.addData('My new datafile',myData) - -and out new dataset appears in the table: - -.. image:: images/userManual/chapter2/dataAdded.png - :width: 800 - :alt: data added to class - -Note that we did not specify data or simulation ranges, and so these default to the min / max values of the data added. To change these (or anything else about the data entry) -use the *'setData'* method. Also note that this data has a fourth column, and so can be used as a data resolution if you wish. - -**Putting it all together – defining contrasts** -++++++++++++++++++++++++++++++++++++++++++++++++ - -As is the case for RasCAL, once we have defined the various aspects of our project i.e. backgrounds, data and so on, we group these together into contrasts to make out fitting project. We can add a contrast using just it's name, and edit it later, or we can specify which parts of our project we want to add to the contrast using name value pairs: - -.. code-block:: MATLAB - - problem.addContrast('name', 'D-tail/H-Head/D2O',... - 'background', 'Background D2O',... - 'resolution', 'Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'BulkOut', 'SLD D2O',... - 'BulkIn', 'SLD air',... - 'data', 'D-tail / H-head / D2O'); - -The values which we add must refer to names within the other blocks of the project. So, if you try to add a *scalefactor* called 'scalefactor1' when this name doesn't exist in the *scalefactors* block, then an error will result. - -Once we have added the contrasts, then we need to set the model, either by adding layers for a *standard layers* project, or a custom model file (we will discuss these in chapter 3). To add either layers or a custom file, we use the **setModel** method. In the case of layers, we give a list of layer names, in order from bulk in to bulk out. So for a monolayer for example, we would specify tails and then heads in a cell array: - -.. code-block:: MATLAB - - problem.setContrastModel(1,{'Deuterated tails','Hydrogenated heads'}); - -The data can be either a datafile or the simulation object in the data block. Once we have defined our contrasts they appear in the *contrasts* block at the end of the project when it is displayed. - -The Monolayer Example In Full -............................. -In the previous sections, we showed an example of a pre-loaded problem definition class, which we used to analyse data from two contrasts of a lipid monolayer. Now, rather than loading in a pre-defined version of this problem we can use our class methods to build this from scratch, and do the same analysis as we did there, but this time from a script. - -To start, we first make an instance of the project class: - -.. code-block:: MATLAB - - problem = projectClass('DSPC monolayers'); - -Then we need to define the parameters we need. We'll do this by making a parameters block, and adding these to project class with the **addParamGroup** method: - -.. code-block:: MATLAB - - % Define the parameters: - Parameters = { - % Name min val max fit? - {'Tails Thickness', 10, 20, 30, true}; - {'Heads Thickness', 3, 11, 16, true}; - {'Tails Roughness', 2, 5, 9, true}; - {'Heads Roughness', 2, 5, 9, true}; - {'Deuterated Tails SLD', 4e-6, 6e-6, 2e-5, true}; - {'Hydrogenated Tails SLD', -0.6e-6, -0.4e-6, 0, true}; - {'Deuterated Heads SLD', 1e-6, 3e-6, 8e-6, true}; - {'Hydrogenated Heads SLD', 0.1e-6, 1.4e-6, 3e-6, true}; - {'Heads Hydration', 0, 0.3, 0.5, true}; - }; - - problem.addParameterGroup(Parameters); - -Next we need to group the parameters into our layers. We need four layers in all, representing deuterated and hydrogenated versions of the heads and tails: - -.. code-block:: MATLAB - - H_Heads = {'Hydrogenated Heads',... - 'Heads Thickness',... - 'Hydrogenated Heads SLD',... - 'Heads Roughness',... - 'Heads Hydration',... - 'bulk out' }; - - D_Heads = {'Deuterated Heads',... - 'Heads Thickness',... - 'Deuterated Heads SLD',... - 'Heads Roughness',... - 'Heads Hydration',... - 'bulk out' }; - - D_Tails = {'Deuterated Tails',... - 'Tails Thickness',... - 'Deuterated Tails SLD',... - 'Tails Roughness'}; - - H_Tails = {'Hydrogenated Tails',... - 'Tails Thickness',... - 'Hydrogenated Tails SLD',... - 'Tails Roughness'}; - -.. note:: - The headgroups are hydrated and so share a hydration parameter, whereas the tails are not. - -We add our layers to the project using the **addLayerGroup** method: - -.. code-block:: MATLAB - - problem.addLayerGroup({H_Heads; D_Heads; H_Tails; D_Tails}); - -We are using two different subphases: D2O and ACMW. We need a different constant background for each, so we need two 'backPar' parameters. There is already one background parameter in the project as a default, so we rename this and add a second one: - -.. code-block:: MATLAB - - problem.setBackgroundParamName(1, 'Backs value ACMW'); % Use existing backsPar - problem.setBackgroundParamValue(1, 5.5e-6); - problem.addBackgroundParam('Backs Value D2O', 1e-8, 2.8e-6, 1e-5); - -Use these parameters to define two constant backgrounds, again using the existing default for one of them: - -.. code-block:: MATLAB - - problem.addBackground('Background D2O', 'constant', 'Backs Value D2O'); - problem.setBackground(1, 'name', 'Background ACMW', 'value1', 'Backs Value ACMW'); - -We need two subphases for our project. D2O is already in the project as a default, so we only need to add the bulk out for ACMW - -.. code-block:: MATLAB - - problem.addBulkOut('SLD ACMW', -1e-6, 0.0, 1e-6, true); - -Now we need to add the data. We read in the two files into MATLAB, and put the data into the data block with appropriate names: - -.. code-block:: MATLAB - - d13ACM = dlmread('d13acmw20.dat'); - d70d2O = dlmread('d70d2o20.dat'); - problem.addData('H-tail / D-head / ACMW', d13ACM); - problem.addData('D-tail / H-head / D2O', d70d2O); - -We have everything we need to now build our contrasts. We have two contrasts in all, and we build them using name / value pairs for all the different parts of the contrasts (i.e. selecting which background and bulk phases etc we need using the names we have given them.) - -.. code-block:: MATLAB - - problem.addContrast('name', 'D-tail/H-Head/D2O',... - 'background', 'Background D2O',... - 'resolution', 'Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'BulkOut', 'SLD D2O',... - 'BulkIn', 'SLD air',... - 'data', 'D-tail / H-head / D2O'); - - problem.addContrast('name', 'H-tail/D-Head/ACMW',... - 'background', 'Background ACMW',... - 'resolution', 'Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'BulkOut', 'SLD ACMW',... - 'BulkIn', 'SLD air',... - 'data', 'H-tail / D-head / ACMW'); - -To define the models for each contrast, we add the relevant layers as appropriate: - -.. code-block:: MATLAB - - problem.setContrastModel(1, {'Deuterated tails','Hydrogenated heads'}); - problem.setContrastModel(2, {'hydrogenated tails','deuterated heads'}); - -We need to make sure that we are fitting the relevant backgrounds, scalefactors and bulk phase values: - -.. code-block:: MATLAB - - problem.setBackgroundParam(1,'fit', true); - problem.setBackgroundParam(2,'fit', true); - problem.setScalefactor(1,'fit', true); - problem.setBulkOut(1,'fit', true); - -Now have a look at our project, to make sure it all looks reasonable - -.. code-block:: MATLAB - - disp(problem) - -.. image:: images/userManual/chapter2/dispProblem1.png - :alt: Display the details of problem (first half) -.. image:: images/userManual/chapter2/dispProblem2.png - :alt: Display the details of problem (second half) - -Now we'll calculate this to check the agreement with the data. We need an instance of the controls class, with the procedure attribute set to *calculate* (the default): - -.. code-block:: MATLAB - - controls = controlsClass(); - - disp(controls) - -.. image:: images/userManual/chapter1/controlsClass.png - :width: 400 - :alt: Displays Controls - -We then send all of this to RAT, and plot the output: - -.. code-block:: MATLAB - - [problem,results] = RAT(problem,controls); - -.. image:: images/userManual/chapter2/ratRun1.png - :alt: Displays the RAT processing and chi squared - -.. code-block:: MATLAB - - figure(1); clf; - plotRefSLD(problem, results) - - -.. image:: images/userManual/chapter2/plot1.png - :alt: Displays reflectivity and SLD plot - -To do a fit, we change the *procedure* attribute of the controls class to **simplex** . We will also change the 'parallel' option to 'contrasts', so that each contrast gets it's own calculation thread, and modify the output to only display the final result (rather than each iteration): - -.. code-block:: MATLAB - - controls.procedure = 'simplex'; - controls.parallel = 'contrasts'; - controls.display = 'final'; - -.. image:: images/userManual/chapter1/simplexControls.png - :width: 500 - :alt: simplex controls class - -..and then run our fit and plot the results... - -.. image:: images/userManual/chapter1/simplexRun.png - :width: 800 - :alt: running simplex - -.. image:: images/userManual/chapter1/simplexFit.png - :width: 600 - :alt: simplex results - -.. code-block:: MATLAB - - disp(results) - -.. image:: images/userManual/chapter2/dispResults.png - :width: 300 - :alt: Displays results - -We can now plot the results of our fit: - -.. code-block:: MATLAB - - figure; clf - plotRefSLD(out,results) - -.. image:: images/userManual/chapter2/plot2.png - :alt: Displays reflectivity and SLD plot diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index aa4beb70b..000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,76 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -import os -import sys -import datetime - -# -- Project information ----------------------------------------------------- -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -exclude_patterns = [] -current_dir = os.path.dirname(os.path.abspath(__file__)) -matlab_src_dir = os.path.abspath(os.path.join(current_dir, '..','..')) -sys.path.insert(0, matlab_src_dir) - -project = 'RAT' -copyright = u'2022-{}, ISIS Neutron and Muon Source'.format(datetime.date.today().year) -author = 'Arwel Hughes, Sethu Pastula, Rabiya Farooq, Paul Sharp, Stephen Nneji' - -# The full version, including alpha/beta/rc tags -with open(os.path.join(matlab_src_dir, 'version.txt'), 'r') as version_file: - release = version_file.read() - -# -- General configuration --------------------------------------------------- -extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc', 'sphinx_design'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# -- Options for HTML output ------------------------------------------------- -#set primary_domain = 'matlab' -primary_domain = 'mat' -matlab_keep_package_prefix = False -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'alabaster' -bgcolor = 'white' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_favicon = "_static/logo.png" -html_static_path = ['_static'] -pygments_dark_style = 'monokai' -# html_css_files = ["custom.css"] - -html_sidebars = { - '**': [ - 'about.html', - 'searchbox.html', - 'navigation.html', - ] -} - -html_logo = '' -html_theme_options = {'logo': 'logo.png', - 'logo_name': False, - 'fixed_sidebar': True, - 'logo_name': False, - 'logo_text_align': None, - 'page_width': '75%', - 'sidebar_width': '250px', - } - -rst_prolog = """ -.. |RAT banner| image:: _static/banner.png - :alt: RAT banner -""" diff --git a/docs/source/contrastsClass.rst b/docs/source/contrastsClass.rst deleted file mode 100644 index 176d71700..000000000 --- a/docs/source/contrastsClass.rst +++ /dev/null @@ -1,48 +0,0 @@ -=============== -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 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 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 ---------- -.. autoclass:: API.projectClass.contrastsClass - :members: - -.. autoclass:: API.projectClass.domainContrastsClass - :members: diff --git a/docs/source/controlClass.rst b/docs/source/controlClass.rst deleted file mode 100644 index a5f880a80..000000000 --- a/docs/source/controlClass.rst +++ /dev/null @@ -1,44 +0,0 @@ -============== -Controls Class -============== -ControlsClass is all about control. It is necessary in determining the way RAT works. It deals with how the user interacts with the software. From type of parallelization, -to whether the users wants to calculate SLD during fit, and even how many iteration an algorithm should do etc. - - -There are 5 different `controlsClass.procedures` that can be used with RAT. They are: - -1. **Simplex** -2. **Differential Evolution (DE)** - Optimizes a problem by iteratively improving a candidate solution based on an evolutionary process -3. **Nested Sampler (NS)** - Estimates directly how the likelihood function relates to prior mass -4. **DREAM** -5. **Calculate** - -Each of them has their own unique set of options. The fields in class object of controlsClass are -automatically updated based on the procedure selected. - -RAT uses parallelization to speed up the calculation. This is achieved using Parallel Computing Toolbox. The user can choose to use the parallelisation or not and -if yes, what to parallelize on. (Single, Points or Contrasts) - -.. code-block:: MATLAB - :caption: Sample usage of controlsClass. - - controls = controlsClass(); - controls.procedure = procedures.Dream; - controls.nSamples = 6000; - controls.nChains = 10; - controls.parallel = parallelOptions.Contrasts; - -.. code-block:: MATLAB - :caption: Alternate usage of controlsClass. - - controls = controlsClass(); - controls = controls.setProcedure('dream',... - {'nSamples', 6000,... - 'nChains', 10,... - 'parallel', 'contrasts'}) - - -Reference ---------- -.. autoclass:: API.controlsClass - :members: \ No newline at end of file diff --git a/docs/source/controlsInfo.rst b/docs/source/controlsInfo.rst deleted file mode 100644 index 69b53344f..000000000 --- a/docs/source/controlsInfo.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _controlsInfo: - -A Closer Look at the Controls Class -................................... - -We have already seen in previous sections that once the problem has been defined in the projectClass, it is necessary to define a controls -class which, as it's name suggests, tells RAT what we want to do with the project. - -Making an instance of the controls class is quite simple:- - -.. code-block:: MATLAB - - controls = controlsClass() - - -This then creates an instance of controlsClass with a number of options defined: - -.. image:: images/userManual/controlsDemo/simpleControls.png - :width: 700 - :alt: Simple controls - -We will look at each of thesee in more detail below. Note that the options that are visible depend on -the algorithm selected. So, at the moment the controls are set to 'calculate', which will simply calculate the reflectivity and -SLD with any associated problem. If we select 'simplex' as the algorithm, a different set of options appears:- - -.. image:: images/userManual/controlsDemo/simplexControls.png - :width: 550 - :alt: Simplex controls - -...which allow the user to set things such as tolerance targets and so on. There is a different set of options for each algorithm. -We will no look at each of the available options in turn. - -Class Methods for the controlsClass -=================================== - -**Parallel** -++++++++++++ -TODO - -**Procedure** -+++++++++++++ -TODO - -**calcSldDuringFit** -++++++++++++++++++++ -TODO - -**display** -+++++++++++ -TODO - -**resamPars** -+++++++++++++ -TODO \ No newline at end of file diff --git a/docs/source/conversionFuncs.rst b/docs/source/conversionFuncs.rst deleted file mode 100644 index 8be23908a..000000000 --- a/docs/source/conversionFuncs.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _conversionFuncs: - -=============================== -Convert between RAT and RasCAL1 -=============================== - -Two utilities are provided to convert between RasCAL1 and RAT projects: - -* **Convert from R1 to RAT** : You can convert any R1 project directly to a projectClass and analyse using RAT -* **Convert from RAT to R1** : You can also do the reverse and convert a projectClass back to an R1 project if you wish. - - - -Convert R1 to RAT -................. - -As an example, we can use the *'monolayer_8_contrasts* demo example shipped with RasCAl1: - -.. image:: images/misc/rascal1.png - :width: 800 - :alt: rascal1 - - -To convert this, simply navigate to the project directory, and convert is as follows: - -.. code-block:: MATLAB - - problem = r1ToProjectClass('monolayer_8_contrasts.mat') - -This produces a *projectClass* containing the R1 project, which can then be analysed as normal: - -.. code-block:: - - controls = controlsClass(); - controls.procedure = 'de'; - controls.parallel = 'contrasts'; - [problem,results] = RAT(problem,controls); - plotRefSLD(problem,results); - -.. image:: images/misc/r1Converted.png - :width: 800 - :alt: rascal1 converted - - - -. - -Convert RAT to a RasCAL1 Project -................................ - -It is also possible to do the opposite conversion, and convert any *projectClass* back to an R1 project: - -.. code-block:: - - projectClassToR1(problem,'saveproject',true,'dirName','testProject','fileName','myConvertedProject') - -This will create the usual RasCAL1 project structure in a directory called *testProject*, with a filename called *myConvertedProject.mat* -This can then be loaded into RasCAL1 as normal. - - -. diff --git a/docs/source/customFileClass.rst b/docs/source/customFileClass.rst deleted file mode 100644 index 89a5b2d1b..000000000 --- a/docs/source/customFileClass.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. _table: https://uk.mathworks.com/help/matlab/tables.html - -================= -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 custom file table has the following columns: - -1. Name of the row in the Custom File table -2. Name of the custom file -3. Language of the custom file -4. Path of the custom file - -If all of 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); - - -.. warning:: - RAT only supports C++, MATLAB, and Python. - - - -Reference ---------- -.. autoclass:: API.projectClass.customFileClass - :members: \ No newline at end of file diff --git a/docs/source/customLanguages.rst b/docs/source/customLanguages.rst deleted file mode 100644 index b854988d9..000000000 --- a/docs/source/customLanguages.rst +++ /dev/null @@ -1,371 +0,0 @@ -.. _customLanguages: - - -Custom Models in Python or C++ -.............................. - -Custom models are usually written in Matlab, but RAT allows alternative languages to be used. You can write your custom models either in Python or C++. -The reason for the Python functionality is mainly since this is the more natural choice when using RAT from Python with pythonRAT, but also because the user might choose to incorporate Python libraries into the custom models that are not available in Matlab. -The reason for C++ if for pure speed, where very computationally demanding custom models calculations are required. Both optios are easy to use in RAT. - -.. note:: - Examples of using Python and C++ custom models can be found in the /examples/miscellaneous/alternativeLanguages folder - -Python Custom Models -==================== -.. note:: - Before you use Python from your Matlab session, please ensure that Python is `configured correctly on your system. `_ - - -Custom models in Python and Matlab are very similar in structure. The following Matlab custom model can easily be translated to the Python version: - -.. code-block:: MATLAB - - %customBilayer.m - function [output,sub_rough] = customBilayer(params,bulk_in,bulk_out,contrast) - - sub_rough = params(1); - oxide_thick = params(2); - oxide_hydration = params(3); - lipidAPM = params(4); - headHydration = params(5); - bilayerHydration = params(6); - bilayerRough = params(7); - waterThick = params(8); - - - % We have a constant SLD for the oxide.. - oxide_SLD = 3.41e-6; - - % Now make the lipid layers.. - % Use known lipid volume and compositions - % to make the layers - - % define all the neutron b's. - bc = 0.6646e-4; %Carbon - bo = 0.5843e-4; %Oxygen - bh = -0.3739e-4; %Hydrogen - bp = 0.513e-4; %Phosphorus - bn = 0.936e-4; %Nitrogen - bd = 0.6671e-4; %Deuterium - - % Now make the lipid groups.. - COO = (4*bo) + (2*bc); - GLYC = (3*bc) + (5*bh); - CH3 = (2*bc) + (6*bh); - PO4 = (1*bp) + (4*bo); - CH2 = (1*bc) + (2*bh); - CHOL = (5*bc) + (12*bh) + (1*bn); - - % Group these into heads and tails: - Head = CHOL + PO4 + GLYC + COO; - Tails = (34*CH2) + (2*CH3); - - % We need volumes for each. - % Use literature values: - vHead = 319; - vTail = 782; - - % we use the volumes to calculate the SLD's - SLDhead = Head / vHead; - SLDtail = Tails / vTail; - - % We calculate the layer thickness' from - % the volumes and the APM... - headThick = vHead / lipidAPM; - tailThick = vTail / lipidAPM; - - % Manually deal with hydration for layers in - % this example. - oxSLD = (oxide_hydration * bulk_out(contrast)) + ((1 - oxide_hydration) * oxide_SLD); - headSLD = (headHydration * bulk_out(contrast)) + ((1 - headHydration) * SLDhead); - tailSLD = (bilayerHydration * bulk_out(contrast)) + ((1 - bilayerHydration) * SLDtail); - - % Make the layers - oxide = [oxide_thick oxSLD sub_rough]; - water = [waterThick bulk_out(contrast) bilayerRough]; - head = [headThick headSLD bilayerRough]; - tail = [tailThick tailSLD bilayerRough]; - - output = [oxide ; water ; head ; tail ; tail ; head]; - end - -A straight Python translation (into a Python module) is as follows: - -.. code-block:: Python - - # customBilayer.py - import numpy as np - - def customBilayer(params, bulk_in, bulk_out, contrast): - params = np.array(params); - bulk_in = np.array(bulk_in); - bulk_out = np.array(bulk_out); - - sub_rough = params[0] - oxide_thick = params[1] - oxide_hydration = params[2] - lipidAPM = params[3] - headHydration = params[4] - bilayerHydration = params[5] - bilayerRough = params[6] - waterThick = params[7] - - # We have a constant SLD for the oxide.. - oxide_SLD = 3.41e-6 - - # Now make the lipid layers.. - # Use known lipid volume and compositions - # to make the layers - - # define all the neutron b's. - bc = 0.6646e-4 # Carbon - bo = 0.5843e-4 # Oxygen - bh = -0.3739e-4 # Hydrogen - bp = 0.513e-4 # Phosphorus - bn = 0.936e-4 # Nitrogen - bd = 0.6671e-4 # Deuterium - - # Now make the lipid groups.. - COO = (4*bo) + (2*bc) - GLYC = (3*bc) + (5*bh) - CH3 = (2*bc) + (6*bh) - PO4 = (1*bp) + (4*bo) - CH2 = (1*bc) + (2*bh) - CHOL = (5*bc) + (12*bh) + (1*bn) - - # Group these into heads and tails: - Head = CHOL + PO4 + GLYC + COO - Tails = (34*CH2) + (2*CH3) - - # We need volumes for each. - # Use literature values: - vHead = 319 - vTail = 782 - - # we use the volumes to calculate the SLD's - SLDhead = Head / vHead - SLDtail = Tails / vTail - - # We calculate the layer thickness' from - # the volumes and the APM... - headThick = vHead / lipidAPM - tailThick = vTail / lipidAPM - - # Manually deal with hydration for layers in - # this example. - oxSLD = (oxide_hydration * bulk_out[contrast]) + ((1 - oxide_hydration) * oxide_SLD) - headSLD = (headHydration * bulk_out[contrast]) + ((1 - headHydration) * SLDhead) - tailSLD = (bilayerHydration * bulk_out[contrast]) + ((1 - bilayerHydration) * SLDtail) - - # Make the layers - oxide = [oxide_thick, oxSLD, sub_rough] - water = [waterThick, bulk_out[contrast], bilayerRough] - head = [headThick, headSLD, bilayerRough] - tail = [tailThick, tailSLD, bilayerRough] - - output = np.array([oxide, water, head, tail, tail, head]) - - return output, sub_rough - - -In order to use this custom model, we need a couple of extra steps. Firstly we need to ensure that the current folder is on the pythonpath. You can do this from the Matlab prompt.. - -.. code-block:: MATLAB - - if count(py.sys.path,pwd) == 0 - insert(py.sys.path,int32(0),pwd); - end - - -To use this model from RAT, you need to add it to the current project, taking care to specify the language correctly.. - -.. code-block:: MATLAB - - problem.addCustomFile('myModel','customBilayer.py','python',pwd); - -You can then use this in your calculations in the same way as a normal, Matlab custom model. - -.. note:: - Remember if you change your Python module, the changes will not automatically be registered by Python and you will need to reload the module into Python. You can do this using the following Matlab function (call this after any edits to your module).. -.. code-block:: MATLAB - - function reloadPy(name) - - % Save the module name (so we can reload it after clear..) - save('tempSave','name'); - - % Clear all classes (scoping means that the base workspace is unaffected) - warning('off','MATLAB:ClassInstanceExists') - clear classes - - % Reload the name.... - name = load('tempSave'); - name = name.name; - - % Now reload the module.... - mod = py.importlib.import_module(name); - py.importlib.reload(mod); - - % Get rid of our temporary file... - delete('tempSave.mat'); - end - - -C++ Custom Models -================= -If Matlab or Python custom models are too slow, you also have the option of providing a C++ custom model. You then have to compile and build this into a shared library in order to use it with RAT. - -Following on from our custom bilayer examples, the equivalent C++ custom model should follow this format.. - -.. code-block:: C++ - - //customBilayer.cpp - - #include - - #if defined(_WIN32) || defined(_WIN64) - #define LIB_EXPORT __declspec(dllexport) - #else - #define LIB_EXPORT - #endif - - // We user extern "C" decorator to avoid name mangling.... - extern "C" { - - LIB_EXPORT void customBilayer(std::vector& params, std::vector& bulkIn, std::vector& bulkOut, int contrast, std::vector& output, double* outputSize, double* rough) - { - double subRough = params[0]; - double oxideThick = params[1]; - double oxideHydration = params[2]; - double lipidAPM = params[3]; - double headHydration = params[4]; - double bilayerHydration = params[5]; - double bilayerRough = params[6]; - double waterThick = params[7]; - - // We have a constant SLD for the oxide - double oxideSLD = 3.41e-6; - - // Now make the lipid layers.. - // Use known lipid volume and compositions - // to make the layers - - // define all the neutron b's. - double bc = 0.6646e-4; //Carbon - double bo = 0.5843e-4; //Oxygen - double bh = -0.3739e-4; //Hydrogen - double bp = 0.513e-4; //Phosphorus - double bn = 0.936e-4; //Nitrogen - double bd = 0.6671e-4; //Deuterium - - // Now make the lipid groups.. - double COO = (4*bo) + (2*bc); - double GLYC = (3*bc) + (5*bh); - double CH3 = (2*bc) + (6*bh); - double PO4 = (1*bp) + (4*bo); - double CH2 = (1*bc) + (2*bh); - double CHOL = (5*bc) + (12*bh) + (1*bn); - - // Group these into heads and tails: - double Head = CHOL + PO4 + GLYC + COO; - double Tails = (34*CH2) + (2*CH3); - - // We need volumes for each. - // Use literature values: - double vHead = 319; - double vTail = 782; - - // we use the volumes to calculate the SLD's - double SLDhead = Head / vHead; - double SLDtail = Tails / vTail; - - // We calculate the layer thickness' from - // the volumes and the APM... - double headThick = vHead / lipidAPM; - double tailThick = vTail / lipidAPM; - - // Manually deal with hydration for layers in - // this example. - double oxSLD = (oxideHydration * bulkOut[contrast]) + ((1 - oxideHydration) * oxideSLD); - double headSLD = (headHydration * bulkOut[contrast]) + ((1 - headHydration) * SLDhead); - double tailSLD = (bilayerHydration * bulkOut[contrast]) + ((1 - bilayerHydration) * SLDtail); - - // Make the layers - // oxide... - output.push_back(oxideThick); - output.push_back(oxSLD); - output.push_back(subRough); - - // Water... - output.push_back(waterThick); - output.push_back(bulkOut[contrast]); - output.push_back(bilayerRough); - - // Heads... - output.push_back(headThick); - output.push_back(headSLD); - output.push_back(bilayerRough); - - // Tails... - output.push_back(tailThick); - output.push_back(tailSLD); - output.push_back(bilayerRough); - - // Tails... - output.push_back(tailThick); - output.push_back(tailSLD); - output.push_back(bilayerRough); - - // Heads... - output.push_back(headThick); - output.push_back(headSLD); - output.push_back(bilayerRough); - - *rough = subRough; - - outputSize[0] = 6; // row - Necessary to output how many layers in stack - outputSize[1] = 3; - } - } // extern "C" - - -Before you can use this file, you need to compile and build it into a shared library. The details will vary according to you system, for example... - -* Clang on Apple (OSX) - -.. code-block:: Bash - - clang -c customBilayer.cpp -o customBilayer.o -std=c++11 -arch x86_64 - clang -shared customBilayer.o -o customBilayer.dylib -arch x86_64 -lc++ - -* GCC on Linux: - -.. code-block:: Bash - - g++ -fPIC -c customBilayer.cpp -o customBilayer.o -std=c++11 - g++ -shared customBilayer.o -o customBilayer.so - -* Windows (with MSVC): - - cl /EHsc /LD customBilayer.cpp - -This will create either customBilayer.dylib (OSX), customBilayer.dll (Windows) or customBilayer.so (Linux). - -To use this, we just add the relevant model to out project, in the same way as for Matlab and Python models: - -.. code-block:: MATLAB - - problem.addCustomFile('DSPC Model','customBilayer.dylib','cpp',pwd); - -You can then use your C++ custom model in your ptoject as normal. - - -Performance Comparisons -======================= - - - - - - diff --git a/docs/source/customModels.rst b/docs/source/customModels.rst deleted file mode 100644 index 0e6f6b380..000000000 --- a/docs/source/customModels.rst +++ /dev/null @@ -1,631 +0,0 @@ -.. _customModelsExamples: - - -Custom Models -............. - -The Standard Layers approach is useful for quickly setting up simple models, but parameterising models in this way is not always the best way of analysing data. For example, in the case of lipids, it is often natural and intuitive to analyse the data in terms of area per lipid rather than in terms of d, :math:`\rho` and roughness. Similarly, for solid state samples thinking in terms of density and composition is often more appropriate than SLD. In common with RasCAL, you can parameterise your model in any way you like, and then rather than building the model in the input class, the model is constructed using a custom model script. This is by far the most powerful method for using RAT for data analysis, as virtually any type of model can be implemented in this way. - -Again in common with RasCAL, there are two main options for custom modelling: - -* **Custom Layers** - In this method, the parameters are grouped into layers within the script, with the output then defining layers as [d, :math:`\rho`, r] triplets. - -* **Custom XY Profile** - In this method the input parameters are used to create a z (in Angstroms) versus SLD curve, from which the reflectivity is calculated. - - -Custom Layers Models -==================== - -The general principle of custom layers models is that we take the defined parameters, and arrange them into an array layers using some code. This is a very powerful -way of defining your model, since you have the freedom to parameterise and define your model however you wish. So rather than beong restricted to just simple [d, rho, sigma] combinations as parameters, you can -define your model in terms of more scientifically useful parameters, such are Area per molecule or density for example. The basic structure of any custom layers script always has the same format: - -.. code-block:: MATLAB - - function [layers,subRough] = myCustomModel(problems,bulkIn,bulkOut,contrast) - - % Some code to define your model - - layers = [d1, rho1, sig1 - d2, rho2, sig2]; - - -In other words, you get parameters and bulk SLD's in (along with a flag 'contrast' telling your script which contrast to work on), and your code needs to construct the layers array defining the model. -In the next section we'll demonstrate this by making an example to fit a lipi dbilayer sample. - -**DSPC Bilayer Example** - - -In biophysical studies, one of the most common parameters of interest is the area occupied per lipid, be it in a bilayer or a monolayer. Often for lipids, the volume occupied per component is known, which leads to a simple way of calculating the thickness of the head and tail groups. Let the volume of the heads and tails be V\ :sub:`Head` and V\ :sub:`Tail` respectively. Then, for a given Area per Lipid, the thickness of the two layers will be given by :math:`D_\mathrm{Head} = \frac{V_\mathrm{Head}}{APM}` for the headgroup thickness, and :math:`D_\mathrm{Tail} = \frac{V_\mathrm{Tail}}{APM}` for the tail layers. - -In terms of the SLD's, because the volume and composition of each layer is known, then for each, the SLD can be calculated as :math:`\rho = \frac {\sum_{i} n_\mathrm{i} b_\mathrm{i}}{V}` in the usual way. Using literature values for the volumes therefore, rather than parameterising a lipid in terms of thickness, roughness, SLD and coverage of the lipid layers (i.e. head and tail) separately, we can just use a single APM parameter for the whole lipid. In terms of the calculation, we still specify d, :math:`\rho`, rough and coverage on a per layer basis for RAT, but we calculate these in a script for the bilayer from the APM and known composition and volume. This not only gives us the ability to fit our data using more realistic biophysical parameters (in our case APM), but also reduces the number of parameters (dimensions) of our model. - -The figure shows the system we are measuring. We have a single, hydrogenated DSPC bilayer supported on a silicon surface. The silicon is, as always, coated with an oxide layer. The bilayer may or may not be complete (i.e. partially hydrated) so we will need hydration parameters, and there is the possibility of a thin water layer between the bilayer and the substrate. We also need some roughness parameters, both for the substrate and the bilayer itself. We will build a custom model for this and use it to analyse the bilayer data at three contrasts. - -.. image:: images/userManual/chapter3/bilayer.png - :alt: Bilayer on silicon diagram - -Looking at our system, we can see that we are going to need 8 parameters in total: - -.. list-table:: - - * - **Parameters** - - **Description** - * - Substrate Roughness - - This roughness is used for the silicon and oxide layer - * - Oxide Thickness - - Thickness of the oxide layer - * - Oxide hydration - - Required to deal with incomplete coverage of the oxide, which is common - * - Lipid APM - - Area per molecule of the DSPC bilayer, which is the same for both heads and tails. - * - Head Hydration - - The hydration level of the bilayer headgroups - * - Bilayer Hydration - - Overall coverage parameter for the DSPC bilayer - * - Bilayer roughness - - Roughness parameter for the bilayer, which we assume is the same for heads and tails. - * - Water Thickness - - Thickness of a possible hydrating layer between the membrane and the oxide. - -These are the parameters that we will define in the parameters block. - -We start in the usual way by making in instance of the **projectClass**, but this time we change the project type to *custom layers*, and also change the geometry to *solid/liquid*: - -.. code-block:: MATLAB - - problem = projectClass('Orso lipid example - custom layers'); - problem.setModelType('custom layers'); - problem.setGeometry('Substrate/liquid'); - -If you look at the class, you will see that the *layers* block is no longer visible. We aren't going to need this for *custom layers*. Instead, we need a custom script, which takes our inputs and converts this in to a list of [d, :math:`\rho`, r] layers. - -First, we add our seven parameters (remember that Substrate Roughness is always there as the first parameter), which we do as before using the **addParamGroup** method: - -.. code-block:: MATLAB - - Parameters = { - % Name min val max fit? - {'Oxide thick', 5, 20, 60, true }; - {'Oxide Hydration' 0, 0.2, 0.5, true }; - {'Lipid APM' 45 55 65 true }; - {'Head Hydration' 0 0.2 0.5 true }; - {'Bilayer Hydration' 0 0.1 0.2 true }; - {'Bilayer Roughness' 2 4 8 true }; - {'Water Thickness' 0 2 10 true }; - }; - - problem.addParamGroup(Parameters); - -The custom file that we are going to use is called *customBilayer.m*. This is a MATLAB (or Octave - both are identical) function, which takes our input parameters and translates them into a list of layers. To add the file, we use the **addCustomFile** method: - -.. code-block:: MATLAB - - % name filename language path - problem.addCustomFile('DSPC Model', 'customBilayer.m' ,'matlab', pwd); - - -The custom files are in exactly the same format at those in RasCAL. To add it to our project in RAT we always need to specify four things: - -* **Name** - This is any name we choose for this custom file. This is the name we use later to add this to the contrasts. - -* **Filename** - This is the actual filename of the custom file, including its file extension (MATLAB and octave are both '.m') - -* **Language** - The language which we are going to use to process the file. We are choosing MATLAB, which means that the native MATLAB interpreter (i.e. the one we are using to call the project in this example) will be used to process the script. There is further discussion on the languages available and their merits in chapter 6. - -* **Path** - The path to our custom file. In this case it's in the same directory as the model script (pwd). - - -At this point it's useful to look at *customBilayer.m* and then go through it section by section: - -.. code-block:: MATLAB - - function [output,sub_rough] = customBilayer(params,bulk_in,bulk_out,contrast) - %CUSTOMBILAYER RASCAL Custom Layer Model File. - % - % - % This file accepts 3 vectors containing the values for - % Params, bulk in and bulk out - % The final parameter is an index of the contrast being calculated - % The m-file should output a matrix of layer values, in the form.. - % Output = [thick 1, SLD 1, Rough 1, Percent Hydration 1, Hydrate how 1 - % .... - % thick n, SLD n, Rough n, Percent Hydration n, Hydration how n] - % The "hydrate how" parameter decides if the layer is hydrated with - % Bulk out or Bulk in phases. Set to 1 for Bulk out, zero for Bulk in. - % Alternatively, leave out hydration and just return.. - % Output = [thick 1, SLD 1, Rough 1, - % .... - % thick n, SLD n, Rough n] }; - % The second output parameter should be the substrate roughness - - sub_rough = params(1); - oxide_thick = params(2); - oxide_hydration = params(3); - lipidAPM = params(4); - headHydration = params(5); - bilayerHydration = params(6); - bilayerRough = params(7); - waterThick = params(8); - - % We have a constant SLD for the oxide - oxide_SLD = 3.41e-6; - - % Now make the lipid layers.. - % Use known lipid volume and compositions - % to make the layers. - - % define all the neutron b's. - bc = 0.6646e-4; %Carbon - bo = 0.5843e-4; %Oxygen - bh = -0.3739e-4; %Hydrogen - bp = 0.513e-4; %Phosphorus - bn = 0.936e-4; %Nitrogen - bd = 0.6671e-4; %Deuterium - - % Now make the lipid groups.. - COO = (4*bo) + (2*bc); - GLYC = (3*bc) + (5*bh); - CH3 = (2*bc) + (6*bh); - PO4 = (1*bp) + (4*bo); - CH2 = (1*bc) + (2*bh); - CHOL = (5*bc) + (12*bh) + (1*bn); - - % Group these into heads and tails: - Head = CHOL + PO4 + GLYC + COO; - Tails = (34*CH2) + (2*CH3); - - % We need volumes for each. - % Use literature values: - vHead = 319; - vTail = 782; - - % we use the volumes to calculate the SLD's - SLDhead = Head / vHead; - SLDtail = Tails / vTail; - - % We calculate the layer thickness' from - % the volumes and the APM... - headThick = vHead / lipidAPM; - tailThick = vTail / lipidAPM; - - % Manually deal with hydration for layers in - % this example. - oxSLD = (oxide_hydration * bulk_out(contrast)) + ((1 - oxide_hydration) * oxide_SLD); - headSLD = (headHydration * bulk_out(contrast)) + ((1 - headHydration) * SLDhead); - tailSLD = (bilayerHydration * bulk_out(contrast)) + ((1 - bilayerHydration) * SLDtail); - - % Make the layers - oxide = [oxide_thick oxSLD sub_rough]; - water = [waterThick bulk_out(contrast) bilayerRough]; - head = [headThick headSLD bilayerRough]; - tail = [tailThick tailSLD bilayerRough]; - - % Group the layers to make the output - output = [oxide ; water ; head ; tail ; tail ; head]; - - end - -The standard format for a custom layers file always has 4 inputs: - -.. code-block:: MATLAB - - (params, bulk_in, bulk_out, contrast) - -Params is a list of parameter values for the layers, which appear in the same order that we defined them in our parameters block, so is always a [1 x nParams] array of doubles. It's useful to split this array into its individual parameters at the start of the custom file, although you don't have to do this: - -.. code-block:: MATLAB - - sub_rough = params(1); - oxide_thick = params(2); - oxide_hydration = params(3); - lipidAPM = params(4); - headHydration = params(5); - bilayerHydration = params(6); - bilayerRough = params(7); - waterThick = params(8); - -The next two inputs are arrays of all the bulk in and bulk out values for all the contrasts, and 'contrast' is an integer telling the script which contrast it should calculate. The reason for passing the values of the bulk phases is that these are needed to calculate the SLD's of the layers if they are hydrated. So, to calculate the SLD of the Oxide layer, we take the known SLD for Silicon dioxide, and then use the oxide coverage parameter to calculate the effective SLD of the oxide. Because we define our coverage as a parameter between 0 and 1, where 1 is full coverage and 0 is fully hydrated, we can work out this SLD as a simple ratio between oxide SLD and water SLD - -:math:`SLD_\mathrm{Hydrated layer} = (Hydration * SLD_\mathrm{water}) + ((1-Hydration)*SLD_\mathrm{layer})` - -The input parameter *bulk_in* is an array which is a list of the current SLD's for all the contrasts, so the current SLD of the water (which may be being fitted) is given by bulk_out(contrast). Therefore, the effective SLD of the oxide layer at a particular contrast is given by: - -.. code-block:: MATLAB - - oxide_SLD = 3.41e-6; - oxSLD = (oxide_hydration * bulk_out(contrast)) + ((1 - oxide_hydration) * oxide_SLD); - -To work out the thickness of the lipid layers, we use literature values for the head and tails volumes, and divide these by the APM (parameter 4 in our list): - -.. code-block:: MATLAB - - % We need volumes for each. - % Use literature values: - vHead = 319; - vTail = 782; - - % We calculate the layer thickness' from - % the volumes and the APM... - headThick = vHead / lipidAPM; - tailThick = vTail / lipidAPM; - -For the SLD's, we again make use of these volumes, but we need to work out the sum of the scattering lengths from the layers compositions: - -.. code-block:: MATLAB - - % define all the neutron b's. - bc = 0.6646e-4; %Carbon - bo = 0.5843e-4; %Oxygen - bh = -0.3739e-4; %Hydrogen - bp = 0.513e-4; %Phosphorus - bn = 0.936e-4; %Nitrogen - bd = 0.6671e-4; %Deuterium - - % Now make the lipid groups.. - COO = (4*bo) + (2*bc); - GLYC = (3*bc) + (5*bh); - CH3 = (2*bc) + (6*bh); - PO4 = (1*bp) + (4*bo); - CH2 = (1*bc) + (2*bh); - CHOL = (5*bc) + (12*bh) + (1*bn); - - % Group these into heads and tails: - Head = CHOL + PO4 + GLYC + COO; - Tails = (34*CH2) + (2*CH3); - - % we use the volumes to calculate the SLD's - SLDhead = Head / vHead; - SLDtail = Tails / vTail; - -We also do the coverage correction as we did for the Oxide: - -.. code-block:: MATLAB - - headSLD = (headHydration * bulk_out(contrast)) + ((1 - headHydration) * SLDhead); - tailSLD = (bilayerHydration * bulk_out(contrast)) + ((1 - bilayerHydration) * SLDtail); - -This gives us all the parameters we need to define our layers. In other words, we have a thickness, SLD and roughness for each: - -.. code-block:: MATLAB - - % Make the layers - oxide = [oxide_thick oxSLD sub_rough]; - water = [waterThick bulk_out(contrast) bilayerRough]; - head = [headThick headSLD bilayerRough]; - tail = [tailThick tailSLD bilayerRough]; - -We then put these together to make our stack: - -.. code-block:: MATLAB - - output = [oxide; water; head; tail; tail; head]; - -Note the use of semicolons. In Matlab / Octave syntax, this concatenates arrays columnwise. So if you take an array a = [a1, a2, a3], and another b = [b1, b2, b3], then [a ; b] produces an array that looks like this: - -.. math:: - - \begin{bmatrix} a_\mathrm{1} & a_\mathrm{2} & a_\mathrm{3} \\ b_\mathrm{1} & b_\mathrm{2} & b_\mathrm{3} \end{bmatrix} - -In other words, the entire purpose of our custom layer file is to take our parameters in a scientifically useful form (e.g. Area per Lipid in our case), and to translate these into a list of thick, SLD, rough layers for the whole interface. You have complete freedom in how you do this, which means that you can make any kind of layer model you can think of using a custom layers file, including layers that are mixtures of adjoining layers and so on. As long as you can describe your system as layers with an error function (i.e. Nevot and Croce) roughness you can describe them using custom layer modelling. - -The rest of the custom model is defined in the same way as the standard layers model, using the same class methods as in the last chapter. So, since we want to analyse three contrasts simultaneously, we need the following: - -.. code-block:: MATLAB - - % Change bulk in from air to silicon.... - problem.setBulkIn(1,'name','Silicon','min',2.07e-6,'value',2.073e-6,'max',2.08e-6,'fit',false); - - % Add two more values for bulk out.... - problem.addBulkOut('SLD SMW',1e-6,2.073e-6,3e-6,true); - problem.addBulkOut('SLD H2O',-0.6e-6,-0.56e-6,-0.3e-6,true); - - problem.setBulkOut(1,'fit',true,'min',5e-6); - - % Read in the datafiles - D2O_data = dlmread('c_PLP0016596.dat'); - SMW_data = dlmread('c_PLP0016601.dat'); - H2O_data = dlmread('c_PLP0016607.dat'); - - % Add the data to the project - problem.addData('Bilayer / D2O', D2O_data(:,1:3)); - problem.addData('Bilayer / SMW', SMW_data(:,1:3)); - problem.addData('Bilayer / H2O', H2O_data(:,1:3)); - - problem.setData(2,'dataRange',[0.013 0.37]); - problem.setData(3,'dataRange',[0.013 0.37]); - problem.setData(4,'dataRange',[0.013 0.37]); - - % Change the name of the existing parameters to refer to D2O - problem.setBackgroundParam(1,'name','Backs par D2O','fit',true,'min',1e-10,'max',1e-5,'val',1e-6); - - % Add two new backs parameters for the other two.. - problem.addBackgroundParam('Backs par SMW',1e-10,1e-6,1e-5,true); - problem.addBackgroundParam('Backs par H2O',1e-10,1e-6,1e-5,true); - - % And add the two new constant backgrounds.. - problem.addBackground('Background SMW','constant','Backs par SMW'); - problem.addBackground('Background H2O','constant','Backs par H2O'); - - % And edit the other one.... - problem.setBackground(1,'name','Background D2O', 'value1','Backs par D2O'); - - % Set the scalefactor... - problem.setScalefactor(1,'Value',1,'min',0.5,'max',2,'fit',true); - - % Make the contrasts... - problem.addContrast('name','Bilayer / D2O',... - 'background','Background D2O',... - 'resolution','Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'nbs', 'SLD D2O',... % This is bulk out ('Nb Subs') - 'nba', 'Silicon',... % This is bulk in ('Nb Air') - 'data', 'Bilayer / D2O'); - - % SMW contrast.. - problem.addContrast('name','Bilayer / SMW',... - 'background','Background SMW',... - 'resolution','Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'nbs', 'SLD SMW',... % This is bulk out - 'nba', 'Silicon',... % This is bulk in - 'data', 'Bilayer / SMW'); - - % SMW contrast.. - problem.addContrast('name','Bilayer / H2O',... - 'background','Background H2O',... - 'resolution','Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'nbs', 'SLD H2O',... % This is bulk out - 'nba', 'Silicon',... % This is bulk in - 'data', 'Bilayer / H2O'); - -Finally, we add the model, again using the **setContrastModel** method, but in this case we give the name of our custom model from the custom files block (rather than a list of layers): - -.. code-block:: MATLAB - - problem.setContrastModel(1,'DSPC Model'); - problem.setContrastModel(2,'DSPC Model'); - problem.setContrastModel(3,'DSPC Model'); - -Our final projectClass looks like this: - -.. code-block:: MATLAB - - disp(problem) - -.. image:: images/userManual/chapter3/dispProblem1.png - :alt: Displays project class (first half) -.. image:: images/userManual/chapter3/dispProblem2.png - :alt: Displays project class (second half) - -To run this, we make a controls block as before, and pass this to RAT. This time we will do a DREAM analysis (we will discuss the controls block and available algorithms in more detail in Chapter 4). - -.. code-block:: MATLAB - - controls = controlsClass(); - controls.parallel = 'contrasts'; - - disp(controls) - -.. image:: images/userManual/chapter3/dispControls.png - :width: 300 - :alt: Displays the controls - -.. code-block:: MATLAB - - [problem,results] = RAT(problem,controls); - -.. image:: images/userManual/chapter3/ratRun.png - :alt: Displays RAT executing calculations - - - - -Custom XY Profile Models -======================== - -Although many systems can be well described by layers, sometimes these are not the most appropriate. So for example, we may want to incorporate SLD profiles from molecular simulations, or use interfaces that are not error functions. In these cases, a second type of custom model can be used, where instead of the custom model function outputting a list of layers, it builds a continuous SLD profile, which is then automatically microsliced by RAT to calculate the reflectivity. This gives a high degree of flexibility for the type of model that can be generated. -The inputs into customXY are the same as for Custom Layers, but the output is now always an [n x 2] array defining a continuous SLD: - -.. code-block:: MATLAB - - function [SLD,subRough] = myCustomXY(problems,bulkIn,bulkOut,contrast) - - % Some code to define your model - - SLD = [X1, Y1 - X2, Y2 - ... - Xn Yn]; - - -In other words, as the name suggests, a customXY model outputs a continuous SLD profile rather than a list of layers. THis makes it easy to incorporate information -such as protein volume fractions from simulations, or to make interfaces that are not describes as error functions, for example. - -As an example, we will do a simulation of a metal layer on Silicon, with a surface roughness that is governed by a tanh function rather than an error function. - -Because we are making the full SLD profile, if we want layers in it then we have to define our own. This is quite easy since a layer is just two error functions back-to-back. -I the following code snippet we'll make an example of a simple layer.... - -.. code-block:: MATLAB - - % Make a range for our simulation.... - z = 0:100; - - % Define fome layer patameters.... - height = 1; - roughLeft = 3; - roughRight = 8; - centre = 50; - width = 50; - - r = centre + (width/2); - l = centre - (width/2); - - a = (z-l)./((2^0.5) * roughLeft); - b = (z-r)./((2^0.5) * roughRight); - - f = (height/2)*(erf(a)-erf(b)); - - figure(1); clf - plot(z,f); - axis([0 100 0 1.5]); - -.. image:: images/userManual/chapter3/simpleLayer.png - :width: 800 - :alt: simple layer - - - -A simple stack of such layers covers any regions of your model that are intended to be simple layers. For our tanh layer, we will do a similar thing, but replace one side with a tanh distribution... - - -.. code-block:: MATLAB - - function [SLD,subRough] = tanhLayer(params,bulkIn,bulkOut,contrast) - - % Flag to control whether we do a debug plot.... - debugPlot = true; - - % Make the z array..... - z = 0:150; - - % Split up the parameters... - subRough = params(1); - layerThick = params(2); - layerSLD = params(3); - layerRough = params(4); - - % Make a layer for the silicon.. - width = 50; - [silicon,siSurface] = erfLayer(z,width,0,subRough,subRough,2.073e-6); - - % Make the tanh layer.... - centre = siSurface + layerThick/2; - layer = tanh(z,layerThick,centre,subRough,layerRough,layerSLD); - - % Our total SLD is just the sum of the functions representing our model, - % but we flip it so that the substrate is on the fight side of the model - silicon = fliplr(silicon); - layer = fliplr(layer); - SLD = silicon + layer; - - % Do a debug plot... - if debugPlot - figure(1); clf; - plot(z,silicon); - hold on - plot(z,layer); - plot(z,SLD,'k-','LineWidth',2.0); - - end - - end - - function [f,layerSurface] = erfLayer(x,xw,xcen,s1,s2,h); - % Produces a step function convoluted with differnt error functions - % on each side. - % Convstep (x,xw,xcen,s1,s2,h) - % x = vector of x values - % xw = Width of step function - % xcen = Centre point of step function - % s1 = Roughness parameter of left side - % s2 = Roughness parameter of right side - % h = Height of step function. - - r = xcen + (xw/2); - l = xcen - (xw/2); - - a = (x-l)./((2^0.5)*s1); - b = (x-r)./((2^0.5)*s2); - - f = (h/2)*(erf(a)-erf(b)); - - layerSurface = r; - - end - - function [f,layerSurface] = tanh(x,xw,xcen,s1,s2,h); - - % tanhlayer (x,xw,xcen,s1,s2,h) - % x = vector of x values - % xw = Width of step function - % xcen = Centre point of step function - % s1 = Roughness parameter of left side - % s2 = Roughness parameter of right side - % h = Height of step function. - - r = xcen + (xw/2); - l = xcen - (xw/2); - - a = (x-l)./((2^0.5)*s1); - b = (x-r)./((2^0.5)*s2); - - f = (h/2)*(erf(a)-erf(b)); - - layerSurface = r; - - end - - - -.. note:: - - Since we want this to be an air-liquid sample, we flip the model once we have created it to leave the substrate on the right of the plot. Broadly speaking, - you can imagine the neutrons travelling left to right, with the left side of the plot being Bulk In, and Bulk Out on the right.. - - -To run our simulation, we make a RAT model as normal: - -.. code-block:: MATLAB - - problem = createProject(model = 'custom XY', geometry = 'Air/substrate'); - - % Add the parameters - parameters = {{'layerThick',10, 50, 70 } - {'layerSLD', 2e-6, 3e-6, 4e-6} - {'layerRough', 5, 8, 12 } - }; - - problem.addParameterGroup(parameters); - - % Change the bulk-out to Si.... - problem.setBulkOut(1,'name','SLD Silicon','value',2.073e-6,'fit',false); - - % Add the custom model.... - problem.addCustomFile('LayerMod','tanhLayer.m','matlab',pwd); - - % Make the contrast... - problem.addContrast('name', 'Simple Layer',... - 'bulkIn', 'SLD Air',... - 'bulkOut', 'SLD Silicon',... - 'resolution', 'Resolution 1',... - 'scalefactor', 'Scalefactor 1',... - 'background', 'Background 1',... - 'Data', 'Simulation'); - - problem.setContrastModel(1,'LayerMod'); - -..run it and plot the results... - -.. code-block:: MATLAB - - [problem,resuts] = RAT(problem,controls); - - figure(1); clf - plotRefSLD(problem,results); - - - -.. image:: images/userManual/chapter3/customTwoLayerFig.png - :width: 500 - :alt: Dtwo layers XY - - -When sent to RAT, customXY SLD profiles are automatically resampled into layers with adaptive resampling: - -.. image:: images/userManual/chapter3/twoLayerRAT.png - :width: 800 - :alt: Displays the final customXY result - diff --git a/docs/source/dataClass.rst b/docs/source/dataClass.rst deleted file mode 100644 index f6d511b44..000000000 --- a/docs/source/dataClass.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _table: https://uk.mathworks.com/help/matlab/tables.html - -========== -Data Class -========== - -Data Class is a class to helps add or set data. Data can be addded using `addData` method. The `addData` method expects a cell array of cell array. Like other methods there's -a check that directs different cases based on the length of inputs (1 meaning only name or data entered. If only name is entered, error prompted saying 'Single input is expected -to be data name'. Case 2 being both name and data supplied and data is added accordingly). It uses `table`_ data type to do that. -The dataTable is a `table`_ with 4 columns. The following are the 4 columns: - -1. Name of the data -2. Second column is the data itself -3. Data range. The data range is a cell array with two elements, the first element is the minimum value of the data, and - the second element is the maximum value of the data. (optional) -4. Simulation range. The simulation range is a cell array with two elements, the first element is the minimum value of the - 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, `dlmread` built-in method is used to read the data into a variable. - - D2O_data = dlmread('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 ---------- -.. autoclass:: API.projectClass.dataClass - :members: \ No newline at end of file diff --git a/docs/source/devDocumentation.rst b/docs/source/devDocumentation.rst deleted file mode 100644 index 991a822ec..000000000 --- a/docs/source/devDocumentation.rst +++ /dev/null @@ -1,224 +0,0 @@ -:orphan: - -======================== -Developer Documentation -======================== - -This documentation is intended towards developers who wish to understand how RAT's core workflow works and all the different components of the software. -The following picture shows the core workflow of RAT. - -.. image:: images/toolbox.png - :alt: RAT's core workflow - -Unit Testing -============== - -Unit Testing is the process of testing multiple individual pieces/features of the software. It helps to find bugs easily and quickly since each individual feature is tested -independently. - - -RAT's unit tests are written in MATLAB using :code:`matlab.unittest` framework. -These unit tests are written to test the following set of functions: - -1. :ref:`CommonFunctions` - -2. :ref:`nonPolarisedTF` - -3. :ref:`ProjectClass` - -4. :ref:`controlsClass` - -.. note:: - All the common function tests compare the **stable output** against the **on-demand output** of a function. This is done to make sure that the current function is behaving - as expected. On the contrary, all the nonPolarisedTF tests compare the MATLAB output against the MEX output. This is done to make sure and catch any unseen errors during - compiling the MEX file by MATLAB Coder. - -**Stable output** = This is the output of a certain function obtained when the function is working as expected. - -**On-demand output** = This is the output of a certain function at the moment. So, that current function can be tested against the stable one. - -.. note:: - Despite tests being written in MATLAB, RAT's unit tests also test the C++ code of RAT in a way. - This is achieved through comparing the outputs of mex and matlab versions of all the possible parallelization of nonPolarisedTF.reflectivityCalculation. - This includes the following: - - 1. nonPolarisedTF.customLayers (Single, Points and Contrast) - 2. nonPolarisedTF.customXY (Single, Points and Contrast) - 3. nonPolarisedTF.standardLayers (Single, Points and Contrast) - - - -Custom Layers Functionality ------------------------------ - -RAT allows users to create their own custom models and use them in the reflectivity calculations. RAT currently supports C++ and MATLAB custom models meaning users can upload -their model in the form of a function in MATLAB. However, there is a slight complication with the C++. - -In order, to use the custom C++ model, the user needs to compile the function into a shared library (preferably using GCC) and then provide the path and name of the function inside the shared library to RAT. -The following guide will help the user to do this. - - -How does C++ custom model work? -------------------------------- -The implementation of the custom C++ model functionality is bit complicated but the idea is simple. For sake of explanation, DLL and dynamic library are interchangeably used here. - -1. The user submits a DLL file that has the custom C++ model in the form of a function. Our job is to get that function so we can run with the arguments from RAT. In order to *get* - the file we used an open-source project called `dylib`_. dylib helps us extract the function from the DLL at runtime which means we can use the function at runtime. - - -2. When the users makes the DLL, they put the *DYLIB_API* macro at the beginning of the function which exports the function. - - -3. There is a class called *libManager.h* in *RAT/targetFunctions/common/loopCppCustlayWrapper* directory which opens a DLL and extracts the function when given the - path to the DLL. Then runs the function with the arguments from RAT. This the C++ side of the implementation - - -4. We need a gateway that allows MATLAB inputs to go into the C++ side of the code. This is done by creating a MEX function using MATLAB Coder. The file *testDLL.m* is compiled by - Matlab Coder. - - This file basically passes the inputs from MATLAB Workspace to the function from *libManager.h* which runs those inputs/arguments on the function from the DLL. - - -5. As soon the we pass and compute the results comeback into the MATLAB workspace. - -The above explanation holds true for the case of MATLAB version of RAT. If this feature is being used in the compiled version of RAT (i.e setting reflectivity_calculation_wrapper case to **mex**), -there's a case statement that will treat testDLL_mex as an extrinsic function and not a MEX function as per the guidelines of MATLAB Coder. - - -How to create a custom C++ model ---------------------------------- - -1. First Step is to make sure your cpp file is error-free and follow the guidelines mentioned in this step. Your cpp file should contain your custom model and -custom model should be a function. In order for RAT to fetch your custom model/function, it needs to be exported. So, you have to get `dylib.hpp`_ here and put **DYLIB_API** -macro in front of the function name. - -.. _dylib.hpp: https://github.com/martin-olivier/dylib/releases/download/v1.8.2/dylib.hpp - -.. _dylib: https://github.com/martin-olivier/dylib/ - -.. code-block:: - - DYLIB_API void myCustomFunction(double *params...etc....) - - -2. Now that you have put DYLIB_API in front of the dependencies. It is time to make a dynamic library of your model. To do this, you must follow platform specific instructions below. - -Lets say your file is called **myModel.cpp** and your function is called **myCustomFunction** - -.. dropdown:: How to compile a shared library on Windows - - - **Windows - DLL** - - - **Prerequisites**: MinGW or Microsoft Visual Studio Compiler (MSVC) but GCC is strongly suggested - - **GCC** - - .. code-block:: bash - - g++ -c myModel.cpp -o myModel.o Generate an object file - g++ -shared myModel.o -o myModel.dll outputs a DLL named myModel.dll - - **MSVC (Microsoft Visual Studio Compiler)** - - Open *Developer Command Prompt for Visual Studio* - - .. code-block:: bash - - cl.exe /LD myModel.cpp /EHsc You should see myModel.dll in the current directory - -.. dropdown:: How to compile a shared library on Linux/IDAAS - - **Linux/IDAAS - .so** - - - .. code-block:: bash - - g++ -c myModel.cpp -o myModel.o -std=c++11 Generate an object file - g++ -shared myModel.o -o myModel.so outputs a .so named myModel.so - - - - -Additional Documentation -======================== - -This documentation is very detailed in terms of code. It contains direct links to definitions of functions involved and is helpful for developers -who want to understand how RAT works in more detail. - - -The following documentation shows code along with visualizations. -Click on the link below to see the code. - -`Additional Documentation`_ - -.. _Additional Documentation: ./api_reference/index.html - -Dependency Graph ------------------ -The following picture shows the dependency graph of RAT. The dependency graph is a graph that shows how the different components of RAT work together. -Click on the nodes to see the documentation of the component. - -Click on the "Graph" to see the dependency graph. - -`Graph`_ - -.. _Graph: ./api_reference/graph.html - - - -DevOps -====== -DevOps is extremely important for any software that needs faster deployments and easier maintenance of existing deployments and RAT is exactly that. - - -Jenkins --------- - -.. put an image of jenkins logo here - -.. image:: https://th.bing.com/th/id/OIP.GKIe0tehC6rMKoG86wMkewHaFb?w=266&h=193&c=7&r=0&o=5&pid=1.7 - - -.. _Jenkins: https://jenkins.io/ - - -`Jenkins`_ is a famous automation tool that automates building, testing and deploying. At the moment, it is used for building and testing but the deployments could be automated as well. -At STFC, there is a platform called Anvil (not be confused with Anvil the web development tool). Anvil is a service that hosts Jenkins instances for various teams across the STFC's intranet. -This is managed by **Alan Kyffin**. - -STFC Cloud ----------- - -RAT owns two nodes/machines( Windows and Linux) in the cloud which are connected to Anvil. They help build,test the RAT in different operating systems. - -.. warning:: - These nodes must be manually logged in if there's any disruption in the STFC network (happens usually during updates/network-wide shutdowns). - In order to connect the nodes to Anvil, a command is used. This command can be obtained from Arwel Hughes. - -Contacts -^^^^^^^^^ - -1. Issues with Linux node - Alexander Dibbo -2. Issues with Windows node - Simon Hodder (usually someone on his team will help) - - -Work Flow ---------- - -This section details how everything works together in the DevOps department. - -1. First, there is GitHub repository at `RAT`_ which is source for all of the DevOps. Every time, there's a Pull Request (PR) or a push, Jenkins gets triggered. This is achieved - using the Anvil Github App that recognizes these changes and initiates builds. -2. When Jenkins gets triggered, usually it builds according to the "Jenkinsfile" in the repository."Jenkinsfile" is a file that contains the instructions for Jenkins to build the project. Jenkins sends these commands to the nodes in the cloud and build/tests the project. - If the build/test is successful, the PR or push is successful and the PR/push is merged. If the build/test is unsuccessful, the PR/push must be reviewed. - -.. _RAT: https://github.com/arwelHughes/RAT - - - -References for Developers -------------------------- -1. Checkout the :ref:`ADR` (ADR) for RAT. This document contains all the decisions made in the past and why they were made. - This can be found in RasCal Planner in Microsoft Planner. diff --git a/docs/source/domainsCustomLayers.rst b/docs/source/domainsCustomLayers.rst deleted file mode 100644 index a6386a448..000000000 --- a/docs/source/domainsCustomLayers.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _domainsCustomLayers: - - -Custom Models with Domains -.......................... - -For custom layers models with domains, in the spirit of RAT custom models, all the work regarding domain construction is left to the user from within the custom model. -In the custom model itself, there is an extra input parameter for the custom model: - -.. code-block:: MATLAB - - function [output,subRough] = myCustomModel(params,bulkIN,bulkOut,contrast,domainNumber) - - -The first four parameters are the same as for a normal custom model. The final *'domainNumber'* parameter is an integer with a value which is either 1 or 2. Then, it is up -to the user to build the correct domain. So for example, within the custom model: - -.. code-block:: MATLAB - - switch(domainNumber) - case 1 - % - otherwise - % - end - diff --git a/docs/source/domainsCustomXY.rst b/docs/source/domainsCustomXY.rst deleted file mode 100644 index 88b54f491..000000000 --- a/docs/source/domainsCustomXY.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _domainsCustomXY: - - -Custom XY Models with Domains -............................. - -TODO \ No newline at end of file diff --git a/docs/source/domainsStanlay.rst b/docs/source/domainsStanlay.rst deleted file mode 100644 index b046a919c..000000000 --- a/docs/source/domainsStanlay.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _domainsStanlay: - - -Standard Layers Domains -....................... - -.. note:: - See the */examples/domains/standardLayers/* folder for an example of standard layers with domains. - -In order to use domains, we create a project of the correct type.... - -.. code-block:: MATLAB - - problem = createProject(calcType="domains") - -The principle of setting up these calculations relies on firstly grouping the layers into domains, then grouping the defined domains intro contrasts, according to a 'domain ratio' parameter: - -.. image:: images/userManual/calcTypes/domainGraph.png - :width: 800 - -The example (in the examples folder), we define the layers as for conventional Standard Layers projects: - -.. code-block:: MATLAB - - Layer1 = {'Layer 1',... % Name of the layer - 'L1 thick',... % Layer thickness - 'L1 SLD',... % Layer SLD - 'L1 Rough',... % Layer roughness - 'L1 Hydr',... % hydration (percent) - 'bulk out' }; - - Layer2 = {'Layer 2',... % Name of the layer - 'L2 thick',... % Layer thickness - 'L2 SLD',... % Layer SLD - 'L2 Rough',... % Layer roughness - 'L2 Hydr',... % hydration (percent) - 'bulk out' }; - - Layer3 = {'Layer 3',... % Name of the layer - 'L2 thick',... % Layer thickness - 'L2 SLD',... % Layer SLD - 'L2 Rough',... % Layer roughness - 'L2 Hydr',... % hydration (percent) - 'bulk out' }; - - problem.addLayerGroup({Layer1, Layer2, Layer3}); - - -.. image:: images/userManual/calcTypes/domainLayersTable.png - :width: 800 - -From this point, the model diverges from the usual Standard Layers case, in that these are grouped into 'domain contrasts', which appear in an additional table in the -display projectClass. Domains contrasts consist of only layers, with no bulk phases etc.. - -.. image:: images/userManual/calcTypes/domainContrastTable.png - :width: 800 - -It is then these that are grouped into the final contrasts model. For each contrast, there must be two (*and only two*) domain contrasts. In addition, each contrast requires a -Domain Ratio parameter. This is a fittable parameter between 0 and 1, that appears in the Domain Ratio table: - -.. image:: images/userManual/calcTypes/domainRatioTable.png - :width: 800 - -leading to the final contrast structure of two domains, and one domain ratio: - -.. image:: images/userManual/calcTypes/domainContrast.png - :width: 800 - - -.. note:: For domain ratio, a ratio of 0 means 100% Domain 1, whilst conversely a ratio of 1 means 100% Domain 2. - diff --git a/docs/source/entryFunctions.rst b/docs/source/entryFunctions.rst deleted file mode 100644 index 3045b6dc3..000000000 --- a/docs/source/entryFunctions.rst +++ /dev/null @@ -1,34 +0,0 @@ -=================== -RAT Entry Functions -=================== -The user should begin by creating a project and controls object, then the user can run RAT like shown below - -.. code-block:: MATLAB - :caption: Sample usage of RAT class. - - % Initialize the project class - problem = createProject(); - - % Initialize the controls class - controls = controlsClass(); - - % call the RAT function - [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. - -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. - -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. - -.. autofunction:: API.RAT - - -.. autofunction:: API.RATMain - - -.. autofunction:: API.parseClassToStructs \ No newline at end of file diff --git a/docs/source/events.rst b/docs/source/events.rst deleted file mode 100644 index a307f73d0..000000000 --- a/docs/source/events.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _events: - -Handling Events During Calculations -=================================== - diff --git a/docs/source/images/advanced/adaptiveSpPic.png b/docs/source/images/advanced/adaptiveSpPic.png deleted file mode 100644 index a90fcbfd8..000000000 Binary files a/docs/source/images/advanced/adaptiveSpPic.png and /dev/null differ diff --git a/docs/source/images/advanced/controlsBlock.png b/docs/source/images/advanced/controlsBlock.png deleted file mode 100644 index 4b80408d7..000000000 Binary files a/docs/source/images/advanced/controlsBlock.png and /dev/null differ diff --git a/docs/source/images/advanced/dotsSLD.png b/docs/source/images/advanced/dotsSLD.png deleted file mode 100644 index 82e7ed51e..000000000 Binary files a/docs/source/images/advanced/dotsSLD.png and /dev/null differ diff --git a/docs/source/images/advanced/layersPic.png b/docs/source/images/advanced/layersPic.png deleted file mode 100644 index 804b600f8..000000000 Binary files a/docs/source/images/advanced/layersPic.png and /dev/null differ diff --git a/docs/source/images/advanced/resampleContrast.png b/docs/source/images/advanced/resampleContrast.png deleted file mode 100644 index c8e4e0a84..000000000 Binary files a/docs/source/images/advanced/resampleContrast.png and /dev/null differ diff --git a/docs/source/images/advanced/resamplePic.png b/docs/source/images/advanced/resamplePic.png deleted file mode 100644 index 88144380d..000000000 Binary files a/docs/source/images/advanced/resamplePic.png and /dev/null differ diff --git a/docs/source/images/deControls.png b/docs/source/images/deControls.png deleted file mode 100644 index 2ee51bd7e..000000000 Binary files a/docs/source/images/deControls.png and /dev/null differ diff --git a/docs/source/images/misc/bayes95.png b/docs/source/images/misc/bayes95.png deleted file mode 100644 index 376832e5a..000000000 Binary files a/docs/source/images/misc/bayes95.png and /dev/null differ diff --git a/docs/source/images/misc/bayesRef1.png b/docs/source/images/misc/bayesRef1.png deleted file mode 100644 index 3feb24c69..000000000 Binary files a/docs/source/images/misc/bayesRef1.png and /dev/null differ diff --git a/docs/source/images/misc/bayesq4.png b/docs/source/images/misc/bayesq4.png deleted file mode 100644 index d6e78c065..000000000 Binary files a/docs/source/images/misc/bayesq4.png and /dev/null differ diff --git a/docs/source/images/misc/chainPlot.png b/docs/source/images/misc/chainPlot.png deleted file mode 100644 index d605b16a3..000000000 Binary files a/docs/source/images/misc/chainPlot.png and /dev/null differ diff --git a/docs/source/images/misc/cornerPlot.png b/docs/source/images/misc/cornerPlot.png deleted file mode 100644 index 3118e86a6..000000000 Binary files a/docs/source/images/misc/cornerPlot.png and /dev/null differ diff --git a/docs/source/images/misc/eventContents.png b/docs/source/images/misc/eventContents.png deleted file mode 100644 index 93389c750..000000000 Binary files a/docs/source/images/misc/eventContents.png and /dev/null differ diff --git a/docs/source/images/misc/histNoSmooth.png b/docs/source/images/misc/histNoSmooth.png deleted file mode 100644 index 55b16c5f3..000000000 Binary files a/docs/source/images/misc/histNoSmooth.png and /dev/null differ diff --git a/docs/source/images/misc/histSmooth.png b/docs/source/images/misc/histSmooth.png deleted file mode 100644 index 8be26c9fa..000000000 Binary files a/docs/source/images/misc/histSmooth.png and /dev/null differ diff --git a/docs/source/images/misc/r1Converted.png b/docs/source/images/misc/r1Converted.png deleted file mode 100644 index c5acd4be8..000000000 Binary files a/docs/source/images/misc/r1Converted.png and /dev/null differ diff --git a/docs/source/images/misc/rascal1.png b/docs/source/images/misc/rascal1.png deleted file mode 100644 index a3d1cb3b8..000000000 Binary files a/docs/source/images/misc/rascal1.png and /dev/null differ diff --git a/docs/source/images/misc/resamPlot.png b/docs/source/images/misc/resamPlot.png deleted file mode 100644 index ad712f6dc..000000000 Binary files a/docs/source/images/misc/resamPlot.png and /dev/null differ diff --git a/docs/source/images/misc/runDE.png b/docs/source/images/misc/runDE.png deleted file mode 100644 index 764c85ad3..000000000 Binary files a/docs/source/images/misc/runDE.png and /dev/null differ diff --git a/docs/source/images/misc/simPlot1.png b/docs/source/images/misc/simPlot1.png deleted file mode 100644 index 5e6b2398b..000000000 Binary files a/docs/source/images/misc/simPlot1.png and /dev/null differ diff --git a/docs/source/images/misc/simPlot2.png b/docs/source/images/misc/simPlot2.png deleted file mode 100644 index 0f85dc28c..000000000 Binary files a/docs/source/images/misc/simPlot2.png and /dev/null differ diff --git a/docs/source/images/misc/updateBreakPoint.png b/docs/source/images/misc/updateBreakPoint.png deleted file mode 100644 index 4e0eed7ce..000000000 Binary files a/docs/source/images/misc/updateBreakPoint.png and /dev/null differ diff --git a/docs/source/images/misc/updatePlotFreq.png b/docs/source/images/misc/updatePlotFreq.png deleted file mode 100644 index b084288a7..000000000 Binary files a/docs/source/images/misc/updatePlotFreq.png and /dev/null differ diff --git a/docs/source/images/simplexControls.png b/docs/source/images/simplexControls.png deleted file mode 100644 index adad3df4d..000000000 Binary files a/docs/source/images/simplexControls.png and /dev/null differ diff --git a/docs/source/images/standTF.PNG b/docs/source/images/standTF.PNG deleted file mode 100644 index 7b954ef7c..000000000 Binary files a/docs/source/images/standTF.PNG and /dev/null differ diff --git a/docs/source/images/toolbox.png b/docs/source/images/toolbox.png deleted file mode 100644 index e4a19ca9c..000000000 Binary files a/docs/source/images/toolbox.png and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/domainContrast.png b/docs/source/images/userManual/calcTypes/domainContrast.png deleted file mode 100644 index 255bf9c9d..000000000 Binary files a/docs/source/images/userManual/calcTypes/domainContrast.png and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/domainContrastTable.png b/docs/source/images/userManual/calcTypes/domainContrastTable.png deleted file mode 100644 index d19341954..000000000 Binary files a/docs/source/images/userManual/calcTypes/domainContrastTable.png and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/domainGraph.jpeg b/docs/source/images/userManual/calcTypes/domainGraph.jpeg deleted file mode 100644 index ffe76d95f..000000000 Binary files a/docs/source/images/userManual/calcTypes/domainGraph.jpeg and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/domainGraph.png b/docs/source/images/userManual/calcTypes/domainGraph.png deleted file mode 100644 index c6df3d382..000000000 Binary files a/docs/source/images/userManual/calcTypes/domainGraph.png and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/domainLayersTable.png b/docs/source/images/userManual/calcTypes/domainLayersTable.png deleted file mode 100644 index bc346f207..000000000 Binary files a/docs/source/images/userManual/calcTypes/domainLayersTable.png and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/domainRatioTable.png b/docs/source/images/userManual/calcTypes/domainRatioTable.png deleted file mode 100644 index 401064f07..000000000 Binary files a/docs/source/images/userManual/calcTypes/domainRatioTable.png and /dev/null differ diff --git a/docs/source/images/userManual/calcTypes/imaginarySL.png b/docs/source/images/userManual/calcTypes/imaginarySL.png deleted file mode 100644 index c108887a4..000000000 Binary files a/docs/source/images/userManual/calcTypes/imaginarySL.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/contrastGroup.png b/docs/source/images/userManual/chapter1/contrastGroup.png deleted file mode 100644 index 58454d009..000000000 Binary files a/docs/source/images/userManual/chapter1/contrastGroup.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/controlsClass.png b/docs/source/images/userManual/chapter1/controlsClass.png deleted file mode 100644 index 50424d340..000000000 Binary files a/docs/source/images/userManual/chapter1/controlsClass.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/dataGroup.png b/docs/source/images/userManual/chapter1/dataGroup.png deleted file mode 100644 index 229861052..000000000 Binary files a/docs/source/images/userManual/chapter1/dataGroup.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/dispResults.png b/docs/source/images/userManual/chapter1/dispResults.png deleted file mode 100644 index 7cfcbd3a0..000000000 Binary files a/docs/source/images/userManual/chapter1/dispResults.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/layersGroup.png b/docs/source/images/userManual/chapter1/layersGroup.png deleted file mode 100644 index f42f07647..000000000 Binary files a/docs/source/images/userManual/chapter1/layersGroup.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/lipidModel-1.png b/docs/source/images/userManual/chapter1/lipidModel-1.png deleted file mode 100644 index 684298fed..000000000 Binary files a/docs/source/images/userManual/chapter1/lipidModel-1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/lipidModel-2.png b/docs/source/images/userManual/chapter1/lipidModel-2.png deleted file mode 100644 index d0679b76e..000000000 Binary files a/docs/source/images/userManual/chapter1/lipidModel-2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/lipidMonolayer.png b/docs/source/images/userManual/chapter1/lipidMonolayer.png deleted file mode 100644 index 7e47d6e29..000000000 Binary files a/docs/source/images/userManual/chapter1/lipidMonolayer.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/membraneCartoon.png b/docs/source/images/userManual/chapter1/membraneCartoon.png deleted file mode 100644 index 2cacc2df1..000000000 Binary files a/docs/source/images/userManual/chapter1/membraneCartoon.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/parameterGroup.png b/docs/source/images/userManual/chapter1/parameterGroup.png deleted file mode 100644 index 296f86019..000000000 Binary files a/docs/source/images/userManual/chapter1/parameterGroup.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/plots.png b/docs/source/images/userManual/chapter1/plots.png deleted file mode 100644 index 647d3549d..000000000 Binary files a/docs/source/images/userManual/chapter1/plots.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/ratInput.png b/docs/source/images/userManual/chapter1/ratInput.png deleted file mode 100644 index 30cfcfbcd..000000000 Binary files a/docs/source/images/userManual/chapter1/ratInput.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/ratRun.png b/docs/source/images/userManual/chapter1/ratRun.png deleted file mode 100644 index b0735d91b..000000000 Binary files a/docs/source/images/userManual/chapter1/ratRun.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/simplexControls.png b/docs/source/images/userManual/chapter1/simplexControls.png deleted file mode 100644 index 5f42ca30d..000000000 Binary files a/docs/source/images/userManual/chapter1/simplexControls.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/simplexFit.png b/docs/source/images/userManual/chapter1/simplexFit.png deleted file mode 100644 index 7e05b030f..000000000 Binary files a/docs/source/images/userManual/chapter1/simplexFit.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/simplexFitControls.png b/docs/source/images/userManual/chapter1/simplexFitControls.png deleted file mode 100644 index 9d2b3a32a..000000000 Binary files a/docs/source/images/userManual/chapter1/simplexFitControls.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter1/simplexRun.png b/docs/source/images/userManual/chapter1/simplexRun.png deleted file mode 100644 index 1fbc8de85..000000000 Binary files a/docs/source/images/userManual/chapter1/simplexRun.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/basicBackground.png b/docs/source/images/userManual/chapter2/basicBackground.png deleted file mode 100644 index 089cc4bd5..000000000 Binary files a/docs/source/images/userManual/chapter2/basicBackground.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/bulkPhases.png b/docs/source/images/userManual/chapter2/bulkPhases.png deleted file mode 100644 index 705f6a990..000000000 Binary files a/docs/source/images/userManual/chapter2/bulkPhases.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/constBackgroundAdd.png b/docs/source/images/userManual/chapter2/constBackgroundAdd.png deleted file mode 100644 index 4756ded50..000000000 Binary files a/docs/source/images/userManual/chapter2/constBackgroundAdd.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/controlsProcedure.png b/docs/source/images/userManual/chapter2/controlsProcedure.png deleted file mode 100644 index 32d9ea985..000000000 Binary files a/docs/source/images/userManual/chapter2/controlsProcedure.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dataAdded.png b/docs/source/images/userManual/chapter2/dataAdded.png deleted file mode 100644 index 0ececa448..000000000 Binary files a/docs/source/images/userManual/chapter2/dataAdded.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dataBackground.png b/docs/source/images/userManual/chapter2/dataBackground.png deleted file mode 100644 index 7ccd09882..000000000 Binary files a/docs/source/images/userManual/chapter2/dataBackground.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/defaultData.png b/docs/source/images/userManual/chapter2/defaultData.png deleted file mode 100644 index 354fc17be..000000000 Binary files a/docs/source/images/userManual/chapter2/defaultData.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dispControls.png b/docs/source/images/userManual/chapter2/dispControls.png deleted file mode 100644 index 0b8cf9d67..000000000 Binary files a/docs/source/images/userManual/chapter2/dispControls.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dispOut1.png b/docs/source/images/userManual/chapter2/dispOut1.png deleted file mode 100644 index e281c0ddc..000000000 Binary files a/docs/source/images/userManual/chapter2/dispOut1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dispOut2.png b/docs/source/images/userManual/chapter2/dispOut2.png deleted file mode 100644 index 99423961a..000000000 Binary files a/docs/source/images/userManual/chapter2/dispOut2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dispProblem1.png b/docs/source/images/userManual/chapter2/dispProblem1.png deleted file mode 100644 index 1b9f24467..000000000 Binary files a/docs/source/images/userManual/chapter2/dispProblem1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dispProblem2.png b/docs/source/images/userManual/chapter2/dispProblem2.png deleted file mode 100644 index 9cccd2b1c..000000000 Binary files a/docs/source/images/userManual/chapter2/dispProblem2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/dispResults.png b/docs/source/images/userManual/chapter2/dispResults.png deleted file mode 100644 index 6a59559b4..000000000 Binary files a/docs/source/images/userManual/chapter2/dispResults.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/model1.png b/docs/source/images/userManual/chapter2/model1.png deleted file mode 100644 index c3af3190b..000000000 Binary files a/docs/source/images/userManual/chapter2/model1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/model2.png b/docs/source/images/userManual/chapter2/model2.png deleted file mode 100644 index 64fc61a7f..000000000 Binary files a/docs/source/images/userManual/chapter2/model2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/parameterBlock.png b/docs/source/images/userManual/chapter2/parameterBlock.png deleted file mode 100644 index a31dbc07b..000000000 Binary files a/docs/source/images/userManual/chapter2/parameterBlock.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/parameterRemoveError.png b/docs/source/images/userManual/chapter2/parameterRemoveError.png deleted file mode 100644 index b34811d54..000000000 Binary files a/docs/source/images/userManual/chapter2/parameterRemoveError.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/plot1.png b/docs/source/images/userManual/chapter2/plot1.png deleted file mode 100644 index b3bbb77ea..000000000 Binary files a/docs/source/images/userManual/chapter2/plot1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/plot2.png b/docs/source/images/userManual/chapter2/plot2.png deleted file mode 100644 index 946628820..000000000 Binary files a/docs/source/images/userManual/chapter2/plot2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/projectClassMethods.png b/docs/source/images/userManual/chapter2/projectClassMethods.png deleted file mode 100644 index fd17f6315..000000000 Binary files a/docs/source/images/userManual/chapter2/projectClassMethods.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/ratRun1.png b/docs/source/images/userManual/chapter2/ratRun1.png deleted file mode 100644 index 40edb7dea..000000000 Binary files a/docs/source/images/userManual/chapter2/ratRun1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/ratRun2.png b/docs/source/images/userManual/chapter2/ratRun2.png deleted file mode 100644 index e24afce79..000000000 Binary files a/docs/source/images/userManual/chapter2/ratRun2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/reflectivitiesStruct.png b/docs/source/images/userManual/chapter2/reflectivitiesStruct.png deleted file mode 100644 index 2ff450ae7..000000000 Binary files a/docs/source/images/userManual/chapter2/reflectivitiesStruct.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/resolClass.png b/docs/source/images/userManual/chapter2/resolClass.png deleted file mode 100644 index a6871de9e..000000000 Binary files a/docs/source/images/userManual/chapter2/resolClass.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/resolClassModified.png b/docs/source/images/userManual/chapter2/resolClassModified.png deleted file mode 100644 index 17b812179..000000000 Binary files a/docs/source/images/userManual/chapter2/resolClassModified.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/resultingParameterBlock1.png b/docs/source/images/userManual/chapter2/resultingParameterBlock1.png deleted file mode 100644 index 27201b05b..000000000 Binary files a/docs/source/images/userManual/chapter2/resultingParameterBlock1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/resultingParameterBlock2.png b/docs/source/images/userManual/chapter2/resultingParameterBlock2.png deleted file mode 100644 index d77b3f611..000000000 Binary files a/docs/source/images/userManual/chapter2/resultingParameterBlock2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/resultingParameterBlock3.png b/docs/source/images/userManual/chapter2/resultingParameterBlock3.png deleted file mode 100644 index 8be925745..000000000 Binary files a/docs/source/images/userManual/chapter2/resultingParameterBlock3.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/resultingParameterBlock4.png b/docs/source/images/userManual/chapter2/resultingParameterBlock4.png deleted file mode 100644 index 295735511..000000000 Binary files a/docs/source/images/userManual/chapter2/resultingParameterBlock4.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/threeLayerGroup1.png b/docs/source/images/userManual/chapter2/threeLayerGroup1.png deleted file mode 100644 index c5fc2b3f5..000000000 Binary files a/docs/source/images/userManual/chapter2/threeLayerGroup1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/threeLayerGroup2.png b/docs/source/images/userManual/chapter2/threeLayerGroup2.png deleted file mode 100644 index f9cdd6583..000000000 Binary files a/docs/source/images/userManual/chapter2/threeLayerGroup2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter2/twoLayerGroup.png b/docs/source/images/userManual/chapter2/twoLayerGroup.png deleted file mode 100644 index 7554b362e..000000000 Binary files a/docs/source/images/userManual/chapter2/twoLayerGroup.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/bilayer.png b/docs/source/images/userManual/chapter3/bilayer.png deleted file mode 100644 index 2cacc2df1..000000000 Binary files a/docs/source/images/userManual/chapter3/bilayer.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/copyProject1.png b/docs/source/images/userManual/chapter3/copyProject1.png deleted file mode 100644 index 06e4af357..000000000 Binary files a/docs/source/images/userManual/chapter3/copyProject1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/copyProject2.png b/docs/source/images/userManual/chapter3/copyProject2.png deleted file mode 100644 index 7693a9ab4..000000000 Binary files a/docs/source/images/userManual/chapter3/copyProject2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/customTwoLayerFig.png b/docs/source/images/userManual/chapter3/customTwoLayerFig.png deleted file mode 100644 index 3ec98bd63..000000000 Binary files a/docs/source/images/userManual/chapter3/customTwoLayerFig.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/dispControls.png b/docs/source/images/userManual/chapter3/dispControls.png deleted file mode 100644 index 18cc47b4a..000000000 Binary files a/docs/source/images/userManual/chapter3/dispControls.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/dispProblem1.png b/docs/source/images/userManual/chapter3/dispProblem1.png deleted file mode 100644 index 9ca862c6e..000000000 Binary files a/docs/source/images/userManual/chapter3/dispProblem1.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/dispProblem2.png b/docs/source/images/userManual/chapter3/dispProblem2.png deleted file mode 100644 index 02c0281b6..000000000 Binary files a/docs/source/images/userManual/chapter3/dispProblem2.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/loadingBack.png b/docs/source/images/userManual/chapter3/loadingBack.png deleted file mode 100644 index bd37301be..000000000 Binary files a/docs/source/images/userManual/chapter3/loadingBack.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/ratRun.png b/docs/source/images/userManual/chapter3/ratRun.png deleted file mode 100644 index 40ec1e119..000000000 Binary files a/docs/source/images/userManual/chapter3/ratRun.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/ratSimpleLayer.png b/docs/source/images/userManual/chapter3/ratSimpleLayer.png deleted file mode 100644 index beeed2b2a..000000000 Binary files a/docs/source/images/userManual/chapter3/ratSimpleLayer.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/referenceChange.png b/docs/source/images/userManual/chapter3/referenceChange.png deleted file mode 100644 index 22efb31c3..000000000 Binary files a/docs/source/images/userManual/chapter3/referenceChange.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/resultsStruct.png b/docs/source/images/userManual/chapter3/resultsStruct.png deleted file mode 100644 index 6cf46da4e..000000000 Binary files a/docs/source/images/userManual/chapter3/resultsStruct.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/simpleLayer.png b/docs/source/images/userManual/chapter3/simpleLayer.png deleted file mode 100644 index a7acc6619..000000000 Binary files a/docs/source/images/userManual/chapter3/simpleLayer.png and /dev/null differ diff --git a/docs/source/images/userManual/chapter3/twoLayerRAT.png b/docs/source/images/userManual/chapter3/twoLayerRAT.png deleted file mode 100644 index d170e92e4..000000000 Binary files a/docs/source/images/userManual/chapter3/twoLayerRAT.png and /dev/null differ diff --git a/docs/source/images/userManual/controlsDemo/simpleControls.png b/docs/source/images/userManual/controlsDemo/simpleControls.png deleted file mode 100644 index 806521a31..000000000 Binary files a/docs/source/images/userManual/controlsDemo/simpleControls.png and /dev/null differ diff --git a/docs/source/images/userManual/controlsDemo/simplexControls.png b/docs/source/images/userManual/controlsDemo/simplexControls.png deleted file mode 100644 index bd8e2f5c0..000000000 Binary files a/docs/source/images/userManual/controlsDemo/simplexControls.png and /dev/null differ diff --git a/docs/source/imaginary.rst b/docs/source/imaginary.rst deleted file mode 100644 index 267dcd80f..000000000 --- a/docs/source/imaginary.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _imaginary: - - -Adding the Imaginary Refractive Index -..................................... - -In contrast to RasCAL1, RAT allows the inclusion of the imaginary part of the refractive index to the project. The exact method of doing this varies according to the calculation type, -but at the project top-level, the method of enabling it is always the same. If the project is called 'problem', then: - -.. code-block:: MATLAB - - problem.absorption = true; - -How this is then handled depends on the calculation type. - -**Standard Layers Models** -++++++++++++++++++++++++++ -The imaginary refractive index appears as a new column in the 'Layers' block.. - -.. image:: images/userManual/calcTypes/imaginarySL.png - :width: 600 - :alt: imaginary layers - -Then, the value of this column are set (from the Parameters block) in the same way as all the other cells in the table. - -**Custom Models** -++++++++++++++++++++++++ -For custom models, an extra column is also required in the output from the custom function. - -So, for example, in the */examples/miscellaneous/absorption* folder, there is a Custom Layers example including absorption. In this example (a bilayer on a gold surface) -an imaginary SLD is required for the metal layers: - -.. code-block:: MATLAB - - GOLD = [goldThick goldSLD goldISLD goldRough]; - alloyUp = [alloyThick alloySLDUp alloyISLDUp alloyRough]; - alloyDown = [alloyThick alloySLDDown alloyISLDDown alloyRough]; - -but there is no imaginary component expected for the organic layers (but the extra column is still necessary). - -.. code-block:: MATLAB - - BILTAILS = [thickTail sldTail 0 bilayerRough]; - BILHEAD = [thickHead sldHead 0 bilayerRough]; - BILME = [thickMe sldMe 0 bilayerRough]; - - -For custom XY models, it is necessary to construct a profile which represents the imaginary SLD across the sample, and this then appears as am extra column in the output: - -.. code-block:: MATLAB - - output = [X1 SLD1 SLD_im_1 - X2 SLD2 SLD_im_2 - ... - Xn SLDn SLD_im_n] ; - diff --git a/docs/source/incoherent.rst b/docs/source/incoherent.rst deleted file mode 100644 index fddcb2133..000000000 --- a/docs/source/incoherent.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _incoherent: - - -Incoherent Summing (Domains) -............................ - -When a sample contains domains of different compositions, how these are handled depends of the size of the domains relative to the lateral neutron coherence length (nC). -When domains are smaller than nC, we create the SLD profile as an average SLD of the domains, and calculate the reflectivity as normal. -If the domains are larger that nC, instead we have to calculate the reflectivity from each domain separately, and then averege them. It is to calculate the latter type of -domain that the 'domainClass' is used. As with 'normal reflectivity', we can handle domains with each of our calculations types:- - -.. toctree:: - :maxdepth: 2 - - domainsStanlay - domainsCustomLayers - domainsCustomXY \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 9008f5e85..000000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,59 +0,0 @@ -|RAT banner| - -.. _RAT: - - -RAT is an acronym for Reflectivity Algorithms Toolbox, which is the calculation engine for the forthcoming RasCAL2. As -with the original RasCAL, RAT is a toolbox for analysising neutron reflectivity data at multiple contrasts. It is designed -to be flexible, allowing analysis using traditional layer models, but also using user defined custom models. These models -do not assume any prerequisite, but instead allow complete freedom to the user to specify and parameterise their model -however they wish, either as an array of layers, or as a continuous SLD profile. -The original RasCAL was written in Matlab, and RAT is too. However RAT is then converted to native C++ using Matlab Coder . -This has the advantage of the ease of use of Matlab for development, combined with the power and speed of C++. In addition, -because the engine is in C++ it can be called from other languages other than just Matlab. There is a Python interface under development -(although not yet functional). - -The Matlab Interface described in this documentation means that for the first time RasCAL projects are fully scriptable, -meaning that full analysis can be provided via a script for publications for example, or analysis performed using RAT incorporated -into jupyter notebooks and so on. - -RAT contains a number of enhancements as compared to legacy rascal, including: - -* Automatic paralellisation (MPI) either over contrasts or points using a simple flag -* Advanced interface microslicing using adaptive resampling -* Option to write custom models in Matlab, Python or C++ -* Custom models for background and resolution functions (not yet functional) -* Fast Bayesian analysis using DREAM or the external Paramonte Sampler -* Parallel Bayes using Paramonte via 'mpiexcec' -* An integrated Nested sampler for Bayesian model selection -* Fully validated against ORSO examples -* Ability to load and run RasCAL1 projects (usually) without modification -* Plotting routines for easy visualisation of data and fits - -…. and more! - -As well as this documentation, there are extensive examples in the RAT/examples folder. - - -Index -##### - -.. toctree:: - :maxdepth: 2 - - install - tutorial - algorithms - advanced - calcTypes - utilities - reference - support - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index c3feac204..000000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,39 +0,0 @@ -============ -Installation -============ -RAT can be used either by running the m-files directly or using a compiled mex file. -RAT ships with a pre-compiled MEX file which is available to download from the |release| page. -To use the mex do the following: - -1. Download the source code and the pre-compiled mex for your operating system. -2. Extract the source code and the mex files. -3. Replace the **compile** folder in the RAT source code with the one from the extracted mex folder. -4. Open MATLAB and navigate to the folder containing the RAT source code. -5. Run *addPaths.m* which will add the necessary paths -6. Run your script. - -However, if you want to build RAT on your local machine, you need to follow the steps below. - -Build the MEX on your local machine ------------------------------------ -A C/C++ compiler and MATLAB (2021 or later) is required for building the mex. The following MATLAB toolboxes are also required: - -- MATLAB Coder -- MATLAB Compiler -- Parallel Computing Toolbox -- Statistics and Machine Learning Toolbox (for DREAM Minimizer) - -To build the mex, do the following: - -1. Download the RAT source code from the |release| page. -2. Open MATLAB and navigate to the folder containing the RAT source code. -3. Run *addPaths.m* then run *buildScript.m* in MATLAB. This will add the necessary paths and builds the MEX file. - This could take several minutes depending on your machine. -4. The MEX files will be created in the **RAT/compile** folder. - -If no error shows up, you should be able to run the MEX file. - - -.. |release| raw:: html - - Github Release diff --git a/docs/source/layersClass.rst b/docs/source/layersClass.rst deleted file mode 100644 index be84e0445..000000000 --- a/docs/source/layersClass.rst +++ /dev/null @@ -1,44 +0,0 @@ -============ -Layers Class -============ -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 ---------- -.. autoclass:: API.projectClass.layersClass - :members: \ No newline at end of file diff --git a/docs/source/livePlot.rst b/docs/source/livePlot.rst deleted file mode 100644 index d6fcf542b..000000000 --- a/docs/source/livePlot.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _livePlot: - - -Events and Live Updating Plots -.............................. - -Sometimes it is useful to be able to monitor the progress / success of a fit in real time for long simulations. For Simplex and DE fits, RAT sends out 'events', which send out data concerning the -reflectivity, SLD's and so on as the fit progresses. By writing functions that 'listen' to these events, you can use this information to build various kinds of graphical updates to suit your needs. -In this section, we'll use this capability to build a live, updating plot of reflectivity and SLD, similar to that of the main RasCAL GUI. - -.. note:: - The code in this section already exists in the repo (utilities / plotting), and you can activate the full updating plot at any time by just typing 'useLivePlot()' at the Matlab command window. But we detail it here to illustrate how to interact with events. - -**Registering Listeners** - -On the Matlab side, the interaction with RAT event is via the 'eventManager' class. To register a listener, we use the 'register' method to associate a function with the event. - -.. code-block:: MATLAB - - eventManager.register(eventTypes.Plot, 'updatePlot'); - -In this line, we've done two things: we've registered a 'listener' for 'Plot' events, and defined the function 'updatePlot' as the function that runs when the event is triggered (known as a 'handler') -We need to define the handler function: - -.. code-block:: MATLAB - - function updatePlot(varargin) - - h = figure(1000); % Select / open the figure - - subplot(1,2,1); cla % Reflectivity plot panel - subplot(1,2,2); cla % SLD plot panel - plotRefSLDHelper(varargin{:}); % Use the standard RAT reflectivity plot - drawnow limitrate % Make sure it updates - - end - - -We can put a breakpoint in our function to examine the contents of varargin - -.. image:: images/misc/updateBreakPoint.png - :width: 300 - :alt: breakpoint in update function - -We see that it's a struct containing everything needed to make our custom plot: - -.. image:: images/misc/eventContents.png - :width: 300 - :alt: contents of events - -In other words, RAT has packaged the current state of the reflectivity and SLD's, along with a number of other items that you can use to make a plot however you like. -For these purposes, we just make use of the existing RAT plot routine to make our plot. The result is the updating plot routine bundled with RAT. - -**Frequency of events** - -To control how often the event is triggered, we set the 'updatePlotFreq' parameter in the controls block, which defaults to 20: - -.. image:: images/misc/updatePlotFreq.png - :width: 300 - :alt: contents of events - -.. note:: - If you set the plot frequency too low (i.e. make the plot update too often), this will slow your fit as Matlab takes time out of the analysis to update the figure. - Updating every 20 iterations is a reasonable compromise between speed and utility. - diff --git a/docs/source/magnetic.rst b/docs/source/magnetic.rst deleted file mode 100644 index ee481c963..000000000 --- a/docs/source/magnetic.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _magnetic: - - -Reflectivity from Magnetic Samples -................................... - -.. note:: - Magnetism has not been implemented in Release 1, and will be included - in a later release of RAT. \ No newline at end of file diff --git a/docs/source/nestedSampling.rst b/docs/source/nestedSampling.rst deleted file mode 100644 index ee0dc6319..000000000 --- a/docs/source/nestedSampling.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _nestedSampling: - - -Bayesian Model Selection - Nested Sampling -.......................................... - -TODO \ No newline at end of file diff --git a/docs/source/oilWater.rst b/docs/source/oilWater.rst deleted file mode 100644 index d1b549bc6..000000000 --- a/docs/source/oilWater.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _oilWater: - - -Reflectivity from Oil/Water Samples -................................... - -.. note:: - Oil/Water has not been implemented in Release 1, and will be included - in a later release of RAT. - - diff --git a/docs/source/parallelisation.rst b/docs/source/parallelisation.rst deleted file mode 100644 index 6f5e582ef..000000000 --- a/docs/source/parallelisation.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _Parallelisation: - -Parallelising Calculations -................................... - -RAT has in-built parallelisation for speeding up calculations. It will either parallelise over points and this is easily selectable from the controls class. In addition, it is possible to use the external Paramonte sampler -to run Bayesian analysis in parallell using 'mpiexcec' - -Internal Parallelisation -======================== -The controls class allows selection of parallel calculations for all algorithms. The parallelisation can be either over 'contrasts' or 'points'... - -* **points** - In this case, each reflectivity curve is split into a number of sections, and the reflectivity for each set of points is calculated by an individual thread. Only the reflectivity calculation itself is parallelised, and the rest runs sequentially on a single thread. -* **contrasts** - Each contrast *in its entirety* gets it's own calculation thread. - -The parallelisation scheme is chosen from the controls class: - -.. code-block:: MATLAB - - controls = controlsClass() - - % Choose no parallelisation.. - controls.parallel = 'single'; - - % Parallelise over points... - controls.parallel = 'points' - - % Parallelise over contrasts... - controls.parallel = 'contrasts' - - -Generally speaking, unless you have an inordinate amount of points in your datafiles, the greatest speed increase always results from parallelising over contrasts. In fact, if the number of points in your data -is relatively small, parallelising over points can even slow things down because of the extra calculation overhead! It's a good idea to verify which is fastest for a give problem at the start of an analysis. - -Parallel Bayes with MIPEXCEC and Paramonte -========================================== - - - diff --git a/docs/source/parametersClass.rst b/docs/source/parametersClass.rst deleted file mode 100644 index 0d169fac5..000000000 --- a/docs/source/parametersClass.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _table: https://uk.mathworks.com/help/matlab/tables.html - -================ -Parameters Class -================ - -Parameters Class helps to add, set or remove parameters to the Project Class. The class has a constructor that gets initiated when Parameter class is called. This constructor -sets important initial values to the class obj (object) like variable name, types. It also initiates a "table" that helps to store all the parameters. Table is a really useful -data type provided by matlab. Check this link to know more about `table`_. - -.. 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 Parameters Class - * - projectClass.addParameterGroup() - - parametersClass.addParameter() - * - projectClass.addParameter() - - parametersClass.addParameter() - * - projectClass.removeParameter() - - parametersClass.removeParameter() - * - projectClass.setParameter() - - parametersClass.setParameter() - * - projectClass.setParameter() - - parametersClass.setValue() - - -When adding parameters, they can be added individually or as a group (see below). When added as a group, `addParameterGroup` method in projectClass iterates over the -list of parameters and adds them one by one using `addParameter` method which is used to add individual parameters. - -.. code-block:: MATLAB - :caption: Adding parameters as a group. Can set to a class using projectClass.addParameterGroup(Parameters) - - Parameters = { - % Name min val max fit? - {'Oxide thick', 5, 20, 60, true }; - {'Oxide SLD', 3e-6, 3.41e-6, 4e-6, false }; - {'Oxide Hydration' 0, 20, 30, true }}; - - -.. code-block:: MATLAB - :caption: Adding parameters individually. Can set to a class using projectClass.addParameter(Parameter) - - Oxide = {'Oxide Layer',... % Name of the layer - 'Oxide thick',... % Layer thickness - 'Oxide SLD',... % Layer SLD - 'Substrate Roughness',... % Layer roughness - 'Oxide Hydration',... % Oxide hydration (percent) - 'bulk out' }; % Which bulk phase is hydrating the layer - - % Add this to the projectClass... - projectClass.addLayer(Oxide); - -When *addParameter* method is called, the method checks the input through a series of checks to find out -if there are any unexpected values at unexpected places. For example, having logical value in place of a numerical value argument. With *setParameter* method, -one can set the value of any parameter independently. However, there are other methods that helps setting individual parameters. For example, *setName* method helps -to set the name of a parameter. - -.. note:: - - 1. You can add Bulk in and Bulk out with this class - 2. You can add scale factor with this class - -Reference ---------- -.. autoclass:: API.projectClass.parametersClass - :members: \ No newline at end of file diff --git a/docs/source/paramonte.rst b/docs/source/paramonte.rst deleted file mode 100644 index 036742dc1..000000000 --- a/docs/source/paramonte.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _paramonte: - - -The Paramonte Sampler -..................... - -TODO \ No newline at end of file diff --git a/docs/source/plotFuns.rst b/docs/source/plotFuns.rst deleted file mode 100644 index ae7a1d8fa..000000000 --- a/docs/source/plotFuns.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _simplePlotting: - - -Basic Plotting -.............. - -The simplest plot available is a simple display of the contents of the *problem* and *results* blocks. -This takes the following form: - -.. code-block:: MATLAB - - figure(1); clf - plotRefSLD(problem,results) - -.. image:: images/misc/simPlot1.png - :alt: disp(results) - - -This produces a basic plot of the reflectivity and SLD. - -If this plot is not cleared before subsequent plots, then *plotRefSLD* will overplot allowing the results of calculations to be compared: - -.. image:: images/misc/runDE.png - :alt: run DE - -.. image:: images/misc/simPlot2.png - :alt: fit plot - -If you don't wish to overplot, just clear the figure before re-running plotRefSLD. - -If you are resampling your SLD's, the *plotRefSLD* will automatically show the resampled layers for you: - -.. image:: images/misc/resamPlot.png - :alt: resampled plot - - - diff --git a/docs/source/plotFunsBayes.rst b/docs/source/plotFunsBayes.rst deleted file mode 100644 index 53553fd35..000000000 --- a/docs/source/plotFunsBayes.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. _bayesPlotting: - -========================== -Plotting Bayesian Analysis -========================== - -A number of function exist for plotting the results of Bayesian analysis. - -Reflectivity and SLD -.................... - -A simple reflectivity shaded plot can be displayed as follows: - -.. code-block:: MATLAB - - figure(1); clf - bayesShadedPlot(problem,results) - - -.. image:: images/misc/bayesRef1.png - :width: 800 - :alt: simple shaded plot - - -By default, this shows a standard reflectivity plot with a 65% shaded confidence interval. - -There are a number of options to customise the plot: - -**Interval** - You can sepcify either the 65% or 95% confidence interval to display: - -.. code-block:: MATLAB - - bayesShadedPlot(problem,results,'interval',95) - -.. image:: images/misc/bayes95.png - :width: 800 - :alt: 95 shaded plot - - -**Type** - You can also specify a q4 plot for the reflectivity: - -.. image:: images/misc/bayesq4.png - :width: 800 - :alt: bayes q4 plot - - - -Posterior Histograms -.................... - -You can easily view the marginalised Bayesian posteriors from your analysis: - -.. code-block:: MATLAB - - plotHists(results) - -.. image:: images/misc/histSmooth.png - :width: 800 - :alt: smooth hists - -By default, *plotHists* carries out a KDE smooth of the histograms. You can optionally choose no smoothing: - -.. code-block:: MATLAB - - plotHists(results,'smooth',false) - -.. image:: images/misc/histNoSmooth.png - :width: 800 - :alt: smooth hists - - - -Corner Plots -............ - -To produce a cornerplot, simply use the *cornerPlot* function: - -.. code-block:: MATLAB - - cornerPlot(results) - -.. image:: images/misc/cornerPlot.png - :width: 800 - :alt: cornerPlot - - -Chain View -.......... - -Finally, you can check the integrity of your markov chain as follows: - -.. code-block:: MATLAB - - mcmcplot(results.chain,[],results.fitNames,'chainpanel'); - -.. image:: images/misc/chainPlot.png - :width: 800 - :alt: chainPlot - diff --git a/docs/source/projectClass.rst b/docs/source/projectClass.rst deleted file mode 100644 index dee937f6b..000000000 --- a/docs/source/projectClass.rst +++ /dev/null @@ -1,72 +0,0 @@ -============= -Project Class -============= -Project Class is all about data. It contains the very data user wants to work with. It stores all the data required for reflectivity calculations. -Everything in RAT comes from projectClass in one way or another. There are many functions that deal with breaking down the data from Project Class into smaller pieces -so that they can be used in other parts of the software. - - -Project Class has lot of other classes that help create objects for inputs. They are : - -.. toctree:: - :maxdepth: 1 - - parametersClass - resolutionsClass - backgroundsClass - dataClass - layersClass - customFileClass - contrastsClass - - -.. note:: - Most of these classes have the following in common: - - 1. They are all called from Project Class. - 2. Methods to add or remove or change an attribute depending on the class. - 3. Methods to find the location based on input value. Finding row when given an attribute's name or vice versa (Not all of them though). - 4. Display methods. - 5. A 'toStruct' method which output the class parameters as a struct. - - -.. 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 Parameter Class - * - projectClass.addBulkIn/addBulkOut() - - parametersClass.addParameter() - * - projectClass.removeBulkIn/removeBulkOut() - - parametersClass.removeParameter() - * - projectClass.setBulkIn/setBulkOut() - - parametersClass.setParameter() - -Although, Project class provides one level higher interface so that one can use `addBulkIn` and `addBulkOut` methods from projectClass to set these parameters. - -.. code-block:: MATLAB - :caption: Adding Bulk Out. Can set to a class using projectClass.addBulkOut(BulkIn) - - % Name min val max fit? - problem.addBulkOut({'SLD SMW',2e-6,2.073e-6,3e-6,true}); - - -Domains Class -------------- -RAT currently supports two calculation types (nonPolarised and Domains). The Domains Class is a project class with extra parameters (domainRatio, domainContrasts) for the Domains calculation. - - -.. note:: - It is recommended to use `API.createProject` instead of creating a Project or Domains object directly. - - -Reference ---------- -.. autofunction:: API.createProject - -.. autoclass:: API.projectClass.projectClass - :members: - -.. autoclass:: API.projectClass.domainsClass - :members: diff --git a/docs/source/reference.rst b/docs/source/reference.rst deleted file mode 100644 index 584f51050..000000000 --- a/docs/source/reference.rst +++ /dev/null @@ -1,12 +0,0 @@ -============= -API Reference -============= - -.. toctree:: - :maxdepth: 2 - - projectClass - controlClass - entryFunctions - targetFunctions - utilityFunctions diff --git a/docs/source/resampling.rst b/docs/source/resampling.rst deleted file mode 100644 index 9e5ad5306..000000000 --- a/docs/source/resampling.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _resampling: - -Profile Resampling ('microslicing') -................................... - -The Nevot-Croce roughness approximation only strictly holds for cases where the interface roughness is much less than the layer thickness. Ths usual way -of handling cases where there are such layers, is to split the interfaces into a large number of layers of zero roughness, so that the roughness problem -is circumvented: - -.. image:: images/advanced/resamplePic.png - :width: 700 - :alt: old resampling - -However, this kind of 'dumb microslicing' causes the creation of a large number of layers, which may not all be necessary and will significantly slow down the calculation. - -This problem of finding the lowest number of individual points that will completely describe a waveform is a common problem in signal processing. RAT uses a techique -borrowed from SP called Adaptive Resampling (AR). - -AR is an interative process which aims to find the lowest number of points that will best describe a curve. It does this by adding points where the angle between neighbouring -points becomes greater than a threshold value. So, it adds more points where the signal is changing most strongly (in order to capture all details of the curvature). So, for a -cosine wave, the resampled points cluster at the regions of largest curvature: - -.. image:: images/advanced/adaptiveSpPic.png - :width: 700 - :alt: adaotive cosine - -So, for the continuous cosine curve show in blue, the AR algorithm has chosen the red points as being most representative. In other words, if the red points were -joined with straight lines, the resulting curve would be very similar to the original signal. The salient point is that more points are required where the gradient -of the signal is changing quickly, and those where the gradient is constant can be represented by fewer points. - -RAT borrows the AR trick from the signal processors, and uses this method to resample the SLD profiles. The AR algorithm is used to find the best series of points -that will represent the profile most accurately, and then each of these points is taken as the centre of layer (of zero roughness). The thickness of each layer is half the -distance between neighbouring points. So, for an SLD profile of a floating bilayer (blue line), AR selects the red points: - -.. image:: images/advanced/dotsSLD.png - :width: 700 - :alt: sld and dots... - -..which are then converted into a set of zero roughness layers: - -.. image:: images/advanced/layersPic.png - :width: 700 - :alt: sld and dots... - -**Using Resampling in RAT** -Using resampling on a contrast in RAT is very simple. For any contrast that you want to reample, then simply set the 'resample' flag for that contrast to 'true' - -.. code-block:: MATLAB - - problem.setContrast(1,'resample',true) - -.. image:: images/advanced/resampleContrast.png - :width: 400 - :alt: resample contrast - - -The resampling itself is controlled by the 'resamPars' field in the controls block: - -.. image:: images/advanced/controlsBlock.png - :width: 400 - :alt: resample contrast - -The resampPars field has two parameters in it, corresponding to the minimum angle and minimum points (resamPars = [minAngle minPoints] ) which to use to resample the profiles. -These have the following effects: - -* **minAngle** - The algorithm refines near the points which form, together with their left and right neighbours, a triangle with central angle smaller than the given value. So, a larger value of minAngle results in a finer resampling. minAngle is defined as a multiple of pi (i.e. minAngle = 0.9 refines where the adjacent points form an angle greater than 0.9 * pi) - -* **nPoints** - The initial number of domain points (layers). The algorithm will start from this number of layers, and refine until all the *minAngle* criteria are satisfied. - -.. note:: - Generally, *minAngle* has a larger effect on the eventual resampling than *nPoints*. - - diff --git a/docs/source/resolutionsClass.rst b/docs/source/resolutionsClass.rst deleted file mode 100644 index 75d793a0a..000000000 --- a/docs/source/resolutionsClass.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _table: https://uk.mathworks.com/help/matlab/tables.html - -================= -Resolutions Class -================= - -Resolutions are defined in a two stage process. Firstly, actual fitted parameters are defined. These are held in a 'Parameter Class' table (referring to data type). -Then, these are grouped into the resolutions themselves using a multi-type table. Then the resolution parameters can be used to either define resolution as -constant, data, or a function. - -The constructor is called with the parameters and resolutions as input. The parameters are stored in the resolPars table whereas the resolutions are stored in -the resolutions table and the allowed types are defined in the allowedTypes variable. - -.. note:: - - 1. For constant only one parameter is supplied to multi-type table. - 2. For data, the name is supplied, along with name of the data in the data table. - 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 resolution. - -In each case, the Resolutions can either be added to or subtracted from the data. - - -Reference ---------- -.. autoclass:: API.projectClass.resolutionsClass - :members: diff --git a/docs/source/savingAndClasses.rst b/docs/source/savingAndClasses.rst deleted file mode 100644 index 4deadef05..000000000 --- a/docs/source/savingAndClasses.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. _savingAndClasses: - -Saving Your Work (working with classes) -======================================= -When you have completed your analysis, usually uou will want to save a copy of your work for subsequent. Since everything about your model and results are contained -is their own classes (actually a struct for 'results'), this is very easy. But, there are a couple of pitfalls to be aware of.. - -Saving to a file -................ -Suppose you have a model defined in problem, and you have run this through RAT and you want to save your work for later... - -.. image:: images/userManual/chapter1/ratInput.png - :width: 600 - :alt: RAT input model - -SO. 'problem' now contains a copy of the input problem, and results the relevant reflectivities, SLD's and so on. Because everything is in these two outputs, then saving your mork is -just a matter of saving these to file. It's good practice to keep everything together, and a good way of doing this is to collect them into a struct... - -.. image:: images/userManual/chapter3/resultsStruct.png - :width: 700 - :alt: results struct - -Then, you only need to save the struct to a file to save all of your work: - -.. code-block:: MATLAB - - save('myResultsFile','myResults'); - - -At a later date, you only need to load back in your struct, split it up into it's components and away you go: - -.. image:: images/userManual/chapter3/loadingBack.png - :width: 700 - :alt: loading back - - -Copying projectClass -.................... -During an analysis, it may be tempting to try to make a copy of your project, so that you can modify one of them in order to carry out some kind of comparison between them for example. -But, you need to be aware of how matlab deals with attempt to copy a class. - -For example, first make an instance of projectClass: - -.. image:: images/userManual/chapter3/copyProject1.png - :width: 700 - :alt: copy project 1 - -Now, we try to make a copy: - -.. image:: images/userManual/chapter3/copyProject2.png - :width: 700 - :alt: copy project 2 - -If we then attempt to modify problem2, we find that the original problem has also changed! - -.. image:: images/userManual/chapter3/referenceChange.png - :width: 700 - :alt: copy project 2 - -In other words, *problem2 and problem 1 are references to the same instance of projectClass!* If you reall want a new instance, -you will need to save the class toa file, and load it into a new variable with a different name. - - -Exporting as a Script -..................... -Although saving a binary version of the class is useful, sometimes it would be better to have a script version which will reproduce the class. This is done using the -'toScript' method of projectClass: - -.. code-block:: MATLAB - - problem = projectClass(); - problem.writeScript(script = "myProjectScript"); - -Then, RAT will create a file containing all the statements needed to re-create your project: - -.. code-block:: MATLAB - - % THIS FILE IS GENERATED FROM RAT VIA THE "WRITESCRIPT" ROUTINE. IT IS NOT PART OF THE RAT CODE. - - project = createProject(name='', calcType='non polarised', model='standard layers', geometry='air/substrate', absorption=false); - - project.setParameterValue(1, 20); - project.setParameterLimits(1, 1, 5); - project.setParameterFit(1, true); - project.setParameterPrior(1, 'uniform', 0, Inf); - - - project.removeBulkIn(1); - project.addBulkIn('SLD Air', 0, 0, 0, false, 'uniform', 0, Inf); - - project.removeBulkOut(1); - project.addBulkOut('SLD D2O', 6.2e-06, 6.35e-06, 6.35e-06, false, 'uniform', 0, Inf); - - project.removeScalefactor(1); - project.addScalefactor('Scalefactor 1', 0.02, 0.23, 0.25, false, 'uniform', 0, Inf); - - project.removeQzshift(1); - project.addQzshift('Qz shift 1', -0.0001, 0, 0.0001, false, 'uniform', 0, Inf); - - project.removeBackgroundParam(1); - project.addBackgroundParam('Background Param 1', 1e-07, 1e-06, 1e-05, false, 'uniform', 0, Inf); - - project.removeResolutionParam(1); - project.addResolutionParam('Resolution par 1', 0.01, 0.03, 0.05, false, 'uniform', 0, Inf); - - project.removeBackground(1); - project.removeResolution(1); - - project.addBackground('Background 1', 'constant', 'Background Param 1', '', '', '', ''); - - project.addResolution('Resolution 1', 'constant', 'Resolution par 1', '', '', '', ''); - - project.removeData(1); - project.addData('Simulation'); - project.setData(1, 'simRange', [0.005 0.7]); - - -This is useful because you can then edit this file as you wish, to re-use it as a template for further projects. - -.. note:: - - Developers Note: We get that the format of the created file currently leaves something to desired! It works, but is very untidy.. - This will be cleaned up in a future release... - - diff --git a/docs/source/simplex.rst b/docs/source/simplex.rst deleted file mode 100644 index 301aaddea..000000000 --- a/docs/source/simplex.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _simplex: - - -Nelder-Mead Simplex -................... - -The Nelder-Mead simplex method for finding a local minimum of a function of several variables. For two variables, a simplex is a triangle, and -the method is a pattern search that compares function values at the three vertices of a -triangle. The worst vertex, where f (x, y) is largest, is rejected and replaced with a new -vertex. A new triangle is formed and the search is continued. The process generates -a sequence of triangles (which might have different shapes), for which the function -values at the vertices get smaller and smaller. The size of the triangles is reduced and -the coordinates of the minimum point are found. - -The algorithm can extend to any number of dimensions, where to find the minimum of a function of N variables the simplex is then a generalized triangle in N dimensions. -It is effective and computationally compact, and has the advantage of not requiring the gradient of the underlying function to be defined. - -The main advantage of simplex methods for reflectivity is that they are robust in the face of competing local minima, and quickly converge to -the region where the true global minimum lies. Finding the absolute local minimum for high dimensional problems can be slow however (i.e. simplex methods -are really Global Minimisers, and can be slow to converge locally). - -To selct the simplex in RAT, we use the 'procedure' attribute of the controls block:- - -.. code-block:: MATLAB - - controls = controlsClass(); - controls.procedure = 'simplex' - -Then, a number of additional fields become visible in the controls block, which are the parameters -for the simplex:- - -.. image:: images/simplexControls.png - :width: 600 - :alt: The contrast group - -Many of these have been described in :ref:`controlsInfo`, but a few here are specific to the simplex:- - -tolX - - -tolFun - - -maxFunEvals - - -updateFreq - - -updatePlotFreq - - - diff --git a/docs/source/support.rst b/docs/source/support.rst deleted file mode 100644 index 4b8f0b423..000000000 --- a/docs/source/support.rst +++ /dev/null @@ -1,12 +0,0 @@ -======= -Support -======= - -The easiest way to get help with the project is to start discussions or open an issue on -Github_. - -.. _Github: https://github.com/RascalSoftware/RAT - - - - diff --git a/docs/source/targetFunctions.rst b/docs/source/targetFunctions.rst deleted file mode 100644 index f60c0b4ca..000000000 --- a/docs/source/targetFunctions.rst +++ /dev/null @@ -1,36 +0,0 @@ -================================ -Target Functions (Low Level API) -================================ -.. automodule:: targetFunctions - :members: - -.. _CommonFunctions: - -Common Functions ----------------- -.. automodule:: targetFunctions.common - :members: - -.. automodule:: targetFunctions.common.costFunctions - :members: - -.. automodule:: targetFunctions.common.groupLayers - :members: - -.. _nonPolarisedTF: - -Non-Polarised Target Functions (nonPolarisedTF) - -.. automodule:: targetFunctions.+nonPolarisedTF.+customLayers - :members: - -.. automodule:: targetFunctions.+nonPolarisedTF.+customXY - :members: - -Domains Target Functions (domainsTF) ------------------------------------- -.. automodule:: targetFunctions.+domainsTF.+customLayers - :members: - -.. automodule:: targetFunctions.+domainsTF.+customXY - :members: diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst deleted file mode 100644 index 14375e4eb..000000000 --- a/docs/source/tutorial.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _tutorial: - -======== -Tutorial -======== - -.. toctree:: - :maxdepth: 2 - - chapter1 - chapter2 - controlsInfo - customModels - savingAndClasses diff --git a/docs/source/utilities.rst b/docs/source/utilities.rst deleted file mode 100644 index d3775187c..000000000 --- a/docs/source/utilities.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _utilities: - -================= -Utility Functions -================= - -RAT has a number of utility functions that are provided to assist data analysis. -These are mainly plotting functions:- - - -.. toctree:: - :maxdepth: 1 - - plotFuns - plotFunsBayes - livePlot - conversionFuncs diff --git a/docs/source/utilityFunctions.rst b/docs/source/utilityFunctions.rst deleted file mode 100644 index 8a5fccf2a..000000000 --- a/docs/source/utilityFunctions.rst +++ /dev/null @@ -1,3 +0,0 @@ -================= -Utility Functions -================= \ No newline at end of file diff --git a/examples/domains/customLayers/domainsCustomLayerSheet.mlx b/examples/domains/customLayers/domainsCustomLayerSheet.mlx deleted file mode 100644 index 27207e3cc..000000000 Binary files a/examples/domains/customLayers/domainsCustomLayerSheet.mlx and /dev/null differ diff --git a/examples/domains/customLayers/domainsCustomLayerTest.m b/examples/domains/customLayers/domainsCustomLayersScript.m similarity index 100% rename from examples/domains/customLayers/domainsCustomLayerTest.m rename to examples/domains/customLayers/domainsCustomLayersScript.m diff --git a/examples/domains/customLayers/domainsCustomLayersSheet.mlx b/examples/domains/customLayers/domainsCustomLayersSheet.mlx new file mode 100644 index 000000000..6e419ed10 Binary files /dev/null and b/examples/domains/customLayers/domainsCustomLayersSheet.mlx differ diff --git a/examples/domains/customXY/domainsCustomXYMain.m b/examples/domains/customXY/domainsCustomXYScript.m similarity index 100% rename from examples/domains/customXY/domainsCustomXYMain.m rename to examples/domains/customXY/domainsCustomXYScript.m diff --git a/examples/domains/customXY/domainsCustomXYSheet.mlx b/examples/domains/customXY/domainsCustomXYSheet.mlx index c0c5ffdfe..f8c323499 100644 Binary files a/examples/domains/customXY/domainsCustomXYSheet.mlx and b/examples/domains/customXY/domainsCustomXYSheet.mlx differ diff --git a/examples/domains/standardLayers/domainsStandardLayersSheet.mlx b/examples/domains/standardLayers/domainsStandardLayersSheet.mlx index db7c4a512..f50ab6361 100644 Binary files a/examples/domains/standardLayers/domainsStandardLayersSheet.mlx and b/examples/domains/standardLayers/domainsStandardLayersSheet.mlx differ diff --git a/examples/miscellaneous/alternativeLanguages/customModelLanguages.m b/examples/miscellaneous/alternativeLanguages/customModelLanguagesScript.m similarity index 100% rename from examples/miscellaneous/alternativeLanguages/customModelLanguages.m rename to examples/miscellaneous/alternativeLanguages/customModelLanguagesScript.m diff --git a/examples/miscellaneous/alternativeLanguages/customModelLanguagesSheet.mlx b/examples/miscellaneous/alternativeLanguages/customModelLanguagesSheet.mlx new file mode 100644 index 000000000..144b548ee Binary files /dev/null and b/examples/miscellaneous/alternativeLanguages/customModelLanguagesSheet.mlx differ diff --git a/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayers.m b/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayers.m index f16055886..28f9a79d7 100644 --- a/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayers.m +++ b/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayers.m @@ -59,9 +59,10 @@ % them in the data block.... % Read in the datafiles -D2O_data = dlmread('c_PLP0016596.dat'); -SMW_data = dlmread('c_PLP0016601.dat'); -H2O_data = dlmread('c_PLP0016607.dat'); +root = getappdata(0, 'root'); +D2O_data = dlmread(fullfile(root, '/examples/normalReflectivity/customLayers/c_PLP0016596.dat')); +SMW_data = dlmread(fullfile(root, '/examples/normalReflectivity/customLayers/c_PLP0016601.dat')); +H2O_data = dlmread(fullfile(root, '/examples/normalReflectivity/customLayers/c_PLP0016607.dat')); % Add the data to the project problem.addData('Bilayer / D2O', D2O_data(:,1:3)); @@ -77,7 +78,7 @@ % % Add the custom file to the project.... -problem.addCustomFile('DSPC Model','customBilayer.m','matlab',pwd); +problem.addCustomFile('DSPC Model','customBilayer.m','matlab'); %% % % diff --git a/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayersWorksheet.mlx b/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayersWorksheet.mlx deleted file mode 100644 index 492e32fb7..000000000 Binary files a/examples/miscellaneous/alternativeLanguages/orsoDSPCCustomLayersWorksheet.mlx and /dev/null differ diff --git a/examples/miscellaneous/convertRasCAL1Project/convertRascal.mlx b/examples/miscellaneous/convertRasCAL1Project/convertRascal.mlx deleted file mode 100644 index 98da889a3..000000000 Binary files a/examples/miscellaneous/convertRasCAL1Project/convertRascal.mlx and /dev/null differ diff --git a/examples/miscellaneous/convertRasCAL1Project/Model_IIb.m b/examples/miscellaneous/convertRascal1Project/Model_IIb.m similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/Model_IIb.m rename to examples/miscellaneous/convertRascal1Project/Model_IIb.m diff --git a/examples/miscellaneous/convertRasCAL1Project/README.md b/examples/miscellaneous/convertRascal1Project/README.md similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/README.md rename to examples/miscellaneous/convertRascal1Project/README.md diff --git a/examples/miscellaneous/convertRascal1Project/convertRascal.mlx b/examples/miscellaneous/convertRascal1Project/convertRascal.mlx new file mode 100644 index 000000000..ae43fb5e5 Binary files /dev/null and b/examples/miscellaneous/convertRascal1Project/convertRascal.mlx differ diff --git a/examples/miscellaneous/convertRasCAL1Project/d13acmw20.dat b/examples/miscellaneous/convertRascal1Project/d13acmw20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/d13acmw20.dat rename to examples/miscellaneous/convertRascal1Project/d13acmw20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/d13d2o20.dat b/examples/miscellaneous/convertRascal1Project/d13d2o20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/d13d2o20.dat rename to examples/miscellaneous/convertRascal1Project/d13d2o20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/d70acmw20.dat b/examples/miscellaneous/convertRascal1Project/d70acmw20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/d70acmw20.dat rename to examples/miscellaneous/convertRascal1Project/d70acmw20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/d70d2o20.dat b/examples/miscellaneous/convertRascal1Project/d70d2o20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/d70d2o20.dat rename to examples/miscellaneous/convertRascal1Project/d70d2o20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/d83acmw20.dat b/examples/miscellaneous/convertRascal1Project/d83acmw20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/d83acmw20.dat rename to examples/miscellaneous/convertRascal1Project/d83acmw20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/d83d2o20.dat b/examples/miscellaneous/convertRascal1Project/d83d2o20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/d83d2o20.dat rename to examples/miscellaneous/convertRascal1Project/d83d2o20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/hd2o20.dat b/examples/miscellaneous/convertRascal1Project/hd2o20.dat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/hd2o20.dat rename to examples/miscellaneous/convertRascal1Project/hd2o20.dat diff --git a/examples/miscellaneous/convertRasCAL1Project/monolayerVolumeModel.mat b/examples/miscellaneous/convertRascal1Project/monolayerVolumeModel.mat similarity index 100% rename from examples/miscellaneous/convertRasCAL1Project/monolayerVolumeModel.mat rename to examples/miscellaneous/convertRascal1Project/monolayerVolumeModel.mat diff --git a/examples/miscellaneous/roundRobin/roundRobin.mlx b/examples/miscellaneous/roundRobin/roundRobin.mlx index 64de1fd2e..27c116a42 100644 Binary files a/examples/miscellaneous/roundRobin/roundRobin.mlx and b/examples/miscellaneous/roundRobin/roundRobin.mlx differ diff --git a/examples/normalReflectivity/customLayers/customLayersDSPCSheet.mlx b/examples/normalReflectivity/customLayers/customLayersDSPCSheet.mlx index 6f7bccb95..6510bc6a5 100644 Binary files a/examples/normalReflectivity/customLayers/customLayersDSPCSheet.mlx and b/examples/normalReflectivity/customLayers/customLayersDSPCSheet.mlx differ diff --git a/examples/normalReflectivity/customXY/customXYDSPCSheet.mlx b/examples/normalReflectivity/customXY/customXYDSPCSheet.mlx index c8eb0f481..4ba302917 100644 Binary files a/examples/normalReflectivity/customXY/customXYDSPCSheet.mlx and b/examples/normalReflectivity/customXY/customXYDSPCSheet.mlx differ diff --git a/examples/normalReflectivity/standardLayers/standardLayersDSPCSheet.mlx b/examples/normalReflectivity/standardLayers/standardLayersDSPCSheet.mlx index 7bb3f93a9..9c1e8f6bc 100644 Binary files a/examples/normalReflectivity/standardLayers/standardLayersDSPCSheet.mlx and b/examples/normalReflectivity/standardLayers/standardLayersDSPCSheet.mlx differ diff --git a/ratDocs.m b/ratDocs.m index 040a46a00..51bde44c0 100644 --- a/ratDocs.m +++ b/ratDocs.m @@ -1,17 +1,26 @@ +% Opens the documentation in the System browser. +versionRegex = ['(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)' ... + '(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)' ... + '(?:\.(?:0|[1-9]\d*|\d *[a-zA-Z-][0-9a-zA-Z-]*))*))?' ... + '(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?']; +version = {}; +url = 'https://rascalsoftware.github.io/RAT/'; +versionURL = ''; -% Opens the documentation in the Matlab browser. - -% Get the root path.. -[thisPath,~,~] = fileparts(mfilename('fullpath')); % Could also use getappdata(0,'root') here - -% Build the full filename of the index -indexLoc = fullfile(thisPath,'docs','build','html','index.html'); - -% open if present, error if not -if ~exist(indexLoc,'file') - error('Documentation does not seem to have been built'); -else - web(indexLoc); -end +try + versionText = fileread('version.txt'); + tokens = regexp(versionText, versionRegex, 'tokens'); + versionURL = [url, tokens{1}{1}, '.', tokens{1}{2}, '/']; + webread(versionURL); % Check the page can be found + url = versionURL; +catch ME + switch ME.identifier + case 'MATLAB:webservices:HTTP404StatusCodeError' + fprintf('Loading %s\n', url); + otherwise + fprintf('Something happened when trying to load %s\n: %s\n', versionURL, ME.message); + end +end +web(url); diff --git a/tests/ORSO/testORSOValidation.m b/tests/ORSO/testORSOValidation.m index d24edabd6..39b4bb3fa 100644 --- a/tests/ORSO/testORSOValidation.m +++ b/tests/ORSO/testORSOValidation.m @@ -24,6 +24,12 @@ function testORSO(testCase, layersFile, dataFile) end + methods (TestClassTeardown) + function clear(~) + close all % Close figure after run + end + end + methods (Static) function out = orsoTest(layersFile, dataFile) diff --git a/tests/testExamples.m b/tests/testExamples.m index ac68f75f7..48aa98b8a 100644 --- a/tests/testExamples.m +++ b/tests/testExamples.m @@ -16,8 +16,8 @@ ['miscellaneous' filesep 'backgroundTypes'],... ['miscellaneous' filesep 'bayesBenchmark'],... ['miscellaneous' filesep 'roundRobin'],... - ['miscellaneous' filesep 'convertRasCAL1Project']}; - exampleLiveScriptFile = {'domainsStandardLayersSheet', 'domainsCustomLayerSheet',... + ['miscellaneous' filesep 'convertRascal1Project']}; + exampleLiveScriptFile = {'domainsStandardLayersSheet', 'domainsCustomLayersSheet',... 'domainsCustomXYSheet', 'bayesBenchmark', 'convertRascal'} % exampleLiveScriptFile = {'domainsStandardLayersSheet', 'domainsCustomLayerSheet', 'domainsCustomXYSheet',... % 'customLayersDSPCSheet', 'standardLayersDSPCSheet', 'customXYDSPCSheet',... @@ -28,8 +28,8 @@ 'customLayersDSPCScript',... 'orsoCustomXYDSPC',... 'domainsStandardLayersScript', ... - 'domainsCustomLayerTest',... - 'domainsCustomXYMain',... + 'domainsCustomLayersScript',... + 'domainsCustomXYScript',... 'absorptionDPPC50'}; exampleName = {'original_dspc_bilayer', 'original_dspc_bilayer', 'original_dspc_bilayer',... 'Orso lipid example - custom layers', 'Orso lipid example - custom XY',... @@ -76,6 +76,17 @@ function testCleanUp(testCase) end end + + methods(Static) + function setupCurrentDir(testCase, scriptFile) + import matlab.unittest.fixtures.CurrentFolderFixture + + [pwdPath, ~, ~] = fileparts(which(scriptFile)); + testCase.applyFixture(CurrentFolderFixture(pwdPath)) + end + end + + methods (Test,ParameterCombination="sequential") % Runs the different examples sequentially function testScriptExamples(testCase, ... @@ -93,11 +104,7 @@ function testScriptExamples(testCase, ... % verifies example exists with .m extension testCase.verifyEqual(exist(exampleScriptFile,'file'), 2); - import matlab.unittest.fixtures.CurrentFolderFixture - - [pwdPath, ~, ~] = fileparts(which(exampleScriptFile)); - testCase.applyFixture(CurrentFolderFixture(pwdPath)) - + testExamples.setupCurrentDir(testCase, exampleScriptFile) % runs the example file evalc(exampleScriptFile); @@ -126,8 +133,9 @@ function testScriptExamples(testCase, ... close all; end - function testLiveScriptExamples(~, exampleLiveScriptFile) + function testLiveScriptExamples(testCase, exampleLiveScriptFile) % runs the example live script file + testExamples.setupCurrentDir(testCase, exampleLiveScriptFile) evalc(exampleLiveScriptFile); close all; end @@ -137,10 +145,7 @@ function testWriteScript(testCase, exampleScriptFile) % to a script that can regenerate the object % verifies example exists with .m extension testCase.verifyEqual(exist(exampleScriptFile,'file'), 2); - import matlab.unittest.fixtures.CurrentFolderFixture - - [pwdPath, ~, ~] = fileparts(which(exampleScriptFile)); - testCase.applyFixture(CurrentFolderFixture(pwdPath)) + testExamples.setupCurrentDir(testCase, exampleScriptFile) % runs the example file evalc(exampleScriptFile);