diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 4ee01d69..815f8ba0 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -21,8 +21,17 @@ jobs: python-version: '3.11' - name: Build docs run: | + # create an x11 display because otherwise MATLAB refuses to export live scripts... + sudo apt install -y xvfb + export DISPLAY=':99.0' + Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & + wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip unzip Linux.zip -d API/ + + # we get pandoc from web as apt version is outdated + wget https://github.com/jgm/pandoc/releases/download/3.6.2/pandoc-3.6.2-1-amd64.deb + sudo apt install -y ./pandoc-3.6.2-1-amd64.deb python -m pip install --upgrade pip pip install matlabengine==24.1.* pip install -r requirements.txt diff --git a/.gitignore b/.gitignore index c7c5425b..73092706 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,7 @@ source/_outputs/ # autogenerated documentation source/reference/python/RATapi.* +source/python_examples/data/ +source/matlab_examples/*.html +source/python_examples/notebooks/* +!source/python_examples/notebooks/README.md diff --git a/README.md b/README.md index 3c88d0ee..c8fe400a 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ Download the appropriate version of RAT from the GitHub [release](https://github wget https://github.com/RascalSoftware/RAT/releases/download/nightly/Linux.zip unzip Linux.zip -d API/ +You also must have `pandoc` installed to build the Python example Jupyter notebooks. See the installation instructions [here](https://pandoc.org/installing.html). + To build the HTML docs, type the following into a terminal with access to the Python executable: diff --git a/requirements.txt b/requirements.txt index 540e74f2..49410a82 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,6 +3,8 @@ sphinxcontrib-matlabdomain==0.18 pydata-sphinx-theme==0.15.2 sphinx_design==0.6.0 sphinx-copybutton==0.5.2 +jupyter==1.0.0 +nbsphinx==0.9.6 RATapi==0.0.0.dev4 autodoc_pydantic==2.2.0 enum-tools[sphinx]==0.12.0 diff --git a/source/conf.py b/source/conf.py index 29dd9e11..6d05b51f 100644 --- a/source/conf.py +++ b/source/conf.py @@ -7,8 +7,13 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. import os import sys +import shutil import datetime +import zipfile +from importlib import metadata from urllib.parse import urljoin +from urllib.request import urlretrieve +from pathlib import Path # -- Project information ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -33,17 +38,60 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(".."))) from version import get_doc_version doc_version = get_doc_version() - + # -- General configuration --------------------------------------------------- # add extensions path for snippets sys.path.append(os.path.abspath("./_ext")) -extensions = ['sphinxcontrib.matlab', 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinxcontrib.autodoc_pydantic', 'sphinx_design', 'sphinx_copybutton', 'snippets', 'enum_tools.autoenum'] +extensions = ['sphinxcontrib.matlab', 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinxcontrib.autodoc_pydantic', 'sphinx_design', 'sphinx_copybutton', 'snippets', 'enum_tools.autoenum', 'nbsphinx'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +# -- Setup example files ----------------------------------------------------- +PYTHON_RAT_RELEASE = metadata.version("RATapi") + +if not os.path.isdir("./python_examples/data"): + zip_dir, headers = urlretrieve(f"https://github.com/RascalSoftware/python-RAT/archive/refs/tags/{PYTHON_RAT_RELEASE}.zip") + with zipfile.ZipFile(zip_dir) as zf: + zf.extractall() + print("Copying Jupyter notebooks...") + for directory in ['normal_reflectivity', 'domains', 'absorption']: + for file in Path(f"./python-RAT-{PYTHON_RAT_RELEASE}/RATapi/examples/{directory}/").glob('*'): + shutil.copy(file, "./python_examples/notebooks/") + + shutil.copytree(f"./python-RAT-{PYTHON_RAT_RELEASE}/RATapi/examples/data", "./python_examples/data", dirs_exist_ok=True) + + shutil.rmtree(f"./python-RAT-{PYTHON_RAT_RELEASE}") + +if not os.path.isfile("./matlab_examples/standardLayersDSPCSheet.html"): + try: + from matlab.engine import start_matlab + except ImportError: + print("Could not copy MATLAB live scripts as MATLAB is not installed.") + else: + print("Starting MATLAB Engine...") + eng = start_matlab() + matlab_examples_path = Path("./matlab_examples").resolve() + eng.eval("cd('../API'); addPaths;", nargout=0) + for sheet in ['normalReflectivity/standardLayers/standardLayersDSPCSheet', + 'normalReflectivity/customLayers/customLayersDSPCSheet', + 'normalReflectivity/customXY/customXYDSPCSheet', + 'domains/standardLayers/domainsStandardLayersSheet', + 'domains/customLayers/domainsCustomLayersSheet', + 'domains/customXY/domainsCustomXYSheet', + 'miscellaneous/convertRascal1Project/convertRascal', + 'miscellaneous/alternativeLanguages/customModelLanguagesSheet',]: + filename = Path(sheet).name + folder = str(Path(sheet).parent) + print(f"exporting {sheet}") + eng.cd(f"examples/{folder}", nargout=0) + eng.matlab.internal.liveeditor.executeAndSave(str(Path(f"../API/examples/{sheet}.mlx").resolve()), nargout=0) + eng.export(f"{filename}.mlx", str(matlab_examples_path / f"{filename}.html"), nargout=0) + eng.cd("../../../", nargout=0) + + # -- Options for HTML output ------------------------------------------------- #set primary_domain = 'matlab' primary_domain = None @@ -84,6 +132,30 @@ autodoc_typehints = "description" +nbsphinx_prolog = r""" +{% set docname = 'doc/' + env.doc2path(env.docname, base=None)|string %} + +.. raw:: html + +
+ This page was generated from the notebook {{ env.docname.split('/')|last|e + '.ipynb' }} found in + the Python-RAT repository. + Download notebook. +
+ +.. note:: + + To get the output project and results from this example in your Python session, run: + + .. code-block:: python + + from RATapi.examples import {{ env.docname.split('/')|last|e }} + project, results = {{ env.docname.split('/')|last|e }}() + +------------------------------------------------------------------------------------- + +""" + ### autodoc_pydantic settings # hide JSON schemas by default autodoc_pydantic_model_show_json = False diff --git a/source/examples.rst b/source/examples.rst new file mode 100644 index 00000000..151df19b --- /dev/null +++ b/source/examples.rst @@ -0,0 +1,21 @@ +Examples +======== + +Several examples are provided for RAT in both Python and MATLAB: + + +Matlab +------ + +.. toctree:: + :maxdepth: 3 + + matlab_examples/index + +Python +------ + +.. toctree:: + :maxdepth: 3 + + python_examples/index diff --git a/source/examples/DSPC_custom_XY.rst b/source/examples/DSPC_custom_XY.rst deleted file mode 100644 index 0697c2a8..00000000 --- a/source/examples/DSPC_custom_XY.rst +++ /dev/null @@ -1,79 +0,0 @@ -============== -DSPC Custom XY -============== - -This shows an example of using a :ref:`custom XY` model to analyse reflectivity from a supported bilayer of DSPC. - -Similar to :ref:`DSPC_Custom_Layers`, we can make use of the fact that the volumes, and of course the atomistic composition are known. So, -for lipid tails for example, then we can take a literature value for the tails volume, have a fittable parameter for the lipid area per molecule, and then the tail thickness will simply be - -.. math:: \text{Tail Thick} = \frac{\text{Tail Volume}}{\text{Lipid APM}}. - -Since the volume is known, then the SLD of the tails is also obviously easily calculable. - -In this model, we make distributions to represent the volume fractions of each of the components in the sample, the convert these to SLD's, as described in :ref:`[1] `. - -We also make our volume fractions as optional outputted parameters from our file. The optional nature of this output means we can suppress it to run the model, then -activate it to make final output plots of our analysis. - -.. image:: ../images/examples/volumeFractions.png - :align: center - :alt: Volume fractions - -This example can be run as a script or interactively using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - .. note:: The custom model used is a MATLAB model - **examples/normalReflectivity/customXY/customXYDSPC.m**. - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'normalReflectivity', 'customXY')); - customXYDSPCScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'normalReflectivity', 'customXY')); - edit customXYDSPCSheet - - - .. tab-item:: Python - :sync: Python - - .. note:: The custom model used is a Python model - **RATapi.examples.normal_reflectivity.custom_XY_DSPC.py**. - - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.normal_reflectivity.DSPC_custom_XY.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.normal_reflectivity.DSPC_custom_XY() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.normal_reflectivity.DSPC_custom_XY.ipynb - - -.. _ref_1: - -[1] Sheker et al, J. Appl. Phys, 100, 102216 (2011) [`DOI 10.1063/1.3661986 `_] - diff --git a/source/examples/DSPC_custom_layers.rst b/source/examples/DSPC_custom_layers.rst deleted file mode 100644 index 4496f214..00000000 --- a/source/examples/DSPC_custom_layers.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _DSPC_Custom_Layers: - -================== -DSPC Custom Layers -================== - -This shows an example of using a :ref:`custom layers` model to analyse reflectivity from a supported bilayer of DSPC. - -In this example, we can make use of the fact that the volumes, and of course the atomistic composition are known. So, for lipid tails for example, then we can -take a literature value for the tails volume, have a fittable parameter for the lipid area per molecule, and then the tail thickness will simply be - -.. math:: Tail Thick = Tail Volume / Lipid APM. - -Since the volume is known, then the SLD of the tails is also obviously easily calculable. - -In addition, the datasets for this example, have a resolution (per point) in their fourth column. We use this resolution in our analysis, rather than declaring a constant, fittable one. - -This example can be run as a script or interactively using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - .. note:: The custom model used is a MATLAB model - **examples/normalReflectivity/customLayers/customBilayerDSPC.m**. - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'normalReflectivity', 'customLayers')); - customLayersDSPCScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'normalReflectivity', 'customLayers')); - edit customLayersDSPCSheet.mlx - - - .. tab-item:: Python - :sync: Python - - .. note:: The custom model used is a Python model - **RATapi.examples.normal_reflectivity.custom_bilayer_DSPC.py**. - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.normal_reflectivity.DSPC_custom_layers.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.normal_reflectivity.DSPC_custom_layers() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.normal_reflectivity.DSPC_custom_layers.ipynb diff --git a/source/examples/DSPC_standard_layers.rst b/source/examples/DSPC_standard_layers.rst deleted file mode 100644 index 7c906e53..00000000 --- a/source/examples/DSPC_standard_layers.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _DSPC_Standard_Layers: - -==================== -DSPC Standard Layers -==================== -This shows an example of using a :ref:`standard layers` model to analyse reflectivity from a floating bilayer of DSPC. - -The model is set up in the script, we set Gaussian priors on some of the parameters, build the two contrasts, run the calculation and plot the results. - -This example can be run as a script or interactively using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'normalReflectivity', 'standardLayers')); - standardLayersDSPCScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'normalReflectivity', 'standardLayers')); - edit standardLayersDSPCSheet.mlx - - - .. tab-item:: Python - :sync: Python - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.normal_reflectivity.DSPC_standard_layers.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.normal_reflectivity.DSPC_standard_layers() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.normal_reflectivity.DSPC_standard_layers.ipynb diff --git a/source/examples/convert_r1_project.rst b/source/examples/convert_r1_project.rst deleted file mode 100644 index 38dc9145..00000000 --- a/source/examples/convert_r1_project.rst +++ /dev/null @@ -1,52 +0,0 @@ -============================= -Converting a RasCAL-1 Project -============================= - -If you have projects from RasCAL1, there is a simple utility supplied with the toolbox that makes converting between formats easy as explained in :ref:`conversionFuncs`. - -This example shows the conversion of a RasCAL-1 custom layers project into a RAT project and vice versa, because this is a custom layers project, the custom model -function **Model_IIb.m** which in the example directory is required to run the converted RAT project successfully. - -This example can be run using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - .. note:: The custom model used is a MATLAB model - **examples/miscellaneous/convertRascal1Project/Model_IIb.m**. - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'miscellaneous', 'convertRascal1Project')); - edit convertRascal.mlx - - - .. tab-item:: Python - :sync: Python - - .. note:: The custom model used is a MATLAB model - **RATapi.examples.convert_rascal_project.Model_IIb.m**. - A python version is provided for the jupyter notebook - **RATapi.examples.convert_rascal_project.Model_IIb.py** - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.convert_rascal_project.convert_rascal.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.convert_rascal_project.convert_rascal() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.convert_rascal_project.convert_rascal.ipynb diff --git a/source/examples/custom_model_languages.rst b/source/examples/custom_model_languages.rst deleted file mode 100644 index 80583b4d..00000000 --- a/source/examples/custom_model_languages.rst +++ /dev/null @@ -1,56 +0,0 @@ -================================== -Alternative Custom Model Languages -================================== - -In this example, we setup a :ref:`custom layers` problem using three different programming language (MATLAB, Python, and C++) to write the custom model function. -The provided C++ function needs to be compiled into a dynamic library using instructions given in :ref:`customLanguages` or instructions specific to your compiler. - - -This example can be run using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - .. note:: The custom models used are - - **examples/miscellaneous/languages/alloyDomains.m**, - **examples/miscellaneous/languages/alloyDomains.m**, - **examples/miscellaneous/languages/alloyDomains.m**. - - .. warning:: For Python custom functions, you will need to setup the python environment for MATLAB, see `Setup MATLAB to use Python `_ - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'miscellaneous', 'alternativeLanguages')); - customModelLanguagesScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'miscellaneous', 'alternativeLanguages')); - edit customModelLanguagesSheet.mlx - - - .. tab-item:: Python - :sync: Python - - .. note:: The custom models used are - - **RATapi.examples.languages.custom_bilayer.cpp**, - **RATapi.examples.languages.custom_bilayer.py**, - **RATapi.examples.languages.custom_bilayer.m**. - - .. warning:: For MATLAB custom functions, ensure MATLAB and matlabengine are installed :ref:`install`. - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.languages.run_custom_file_languages.py - diff --git a/source/examples/domains_custom_XY.rst b/source/examples/domains_custom_XY.rst deleted file mode 100644 index 7f9bef42..00000000 --- a/source/examples/domains_custom_XY.rst +++ /dev/null @@ -1,60 +0,0 @@ -================================= -Incoherent Summing with Custom XY -================================= - -This is an example of using incoherent summing ('domains') from custom XY models. - -The domain custom XY model is similar to a normal custom models, except that the input (function arguments) of the custom function contains an additional 'domains' parameter as described in :ref:`domainsCustomModels`. - -This parameter tells the function which is the current domain, so the appropriate layer stack can be generated. - -This example can be run as a script or interactively using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - .. note:: The custom model used is a MATLAB model - **examples/domains/customXY/domainsXY.m**. - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'domains', 'customXY')); - domainsCustomXYScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'domains', 'customXY')); - edit domainsCustomXYSheet.mlx - - - .. tab-item:: Python - :sync: Python - - .. note:: The custom model used is a Python model - **RATapi.examples.domains.domains_XY_model.py**. - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.domains.domains_custom_XY.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.domains.domains_custom_XY() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.domains.domains_custom_XY.ipynb diff --git a/source/examples/domains_custom_layers.rst b/source/examples/domains_custom_layers.rst deleted file mode 100644 index 64f39d95..00000000 --- a/source/examples/domains_custom_layers.rst +++ /dev/null @@ -1,60 +0,0 @@ -===================================== -Incoherent Summing with Custom Layers -===================================== - -This is an example of using incoherent summing ('domains') from custom layers models. The sample is a simple two layer of permalloy/gold, with up/down domains - -The domain custom model is similar to a normal custom models, except that the input (function arguments) of the custom function contains an additional 'domains' parameter as described in :ref:`domainsCustomModels`. - -This parameter tells the function which is the current domain, so the appropriate layer stack can be generated. - -This example can be run as a script or interactively using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - .. note:: The custom model used is a MATLAB model - **examples/domains/customLayers/alloyDomains.m**. - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'domains', 'customLayers')); - domainsCustomXYScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'domains', 'customLayers')); - edit domainsCustomXYSheet.mlx - - - .. tab-item:: Python - :sync: Python - - .. note:: The custom model used is a Python model - **RATapi.examples.domains.alloy_domains.py**. - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.domains.domains_custom_layers.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.domains.domains_custom_layers() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.domains.domains_custom_layers.ipynb diff --git a/source/examples/domains_standard_layers.rst b/source/examples/domains_standard_layers.rst deleted file mode 100644 index ece6061a..00000000 --- a/source/examples/domains_standard_layers.rst +++ /dev/null @@ -1,64 +0,0 @@ -======================================= -Incoherent Summing with Standard Layers -======================================= - -Analysing data containing domains using standard layers models is done in a similar way to a normal standard layers model, but with a couple of -additional steps. - -A normal standard layers model defines parameters, which are grouped into layers, and then these are arranged into contrasts. For sample containing domains, the -layers are first grouped into domain 'contrasts', which are just groupings of layers with none of the additional parameters of a contrast (such as resolutions -etc). Then, the actual experimental contrasts are built in the usual way, but with the model set as any two of the domains. - -.. image:: ../images/domainsGraph.png - :align: center - :alt: Domains graph - -To control the ratio between the domains, we can add domain ratios as described in :ref:`domainsStanlay`. And each contrast has an additional field -for domain ratios which is set as one of the values from this block. - -This example can be run as a script or interactively using the instructions below. - -.. tab-set:: - :sync-group: code - - .. tab-item:: Matlab - :sync: Matlab - - **Run Script**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'domains', 'standardLayers')); - domainsStandardLayersScript - - **Run Interactively**: - - .. code-block:: Matlab - - root = getappdata(0, 'root'); - cd(fullfile(root, 'examples', 'domains', 'standardLayers')); - edit domainsStandardLayersSheet.mlx - - - .. tab-item:: Python - :sync: Python - - **Run Script**: - - .. code-block:: console - - python RATapi.examples.domains.domains_standard_layers.py - - **Run as Function**: - - .. code-block:: Python - - import RATapi as RAT - problem, results = RAT.examples.domains.domains_standard_layers() - - **Run Interactively**: - - .. code-block:: console - - jupyter notebook RATapi.examples.domains.domains_standard_layers.ipynb diff --git a/source/guide.rst b/source/guide.rst index 3c7c607c..502c74e5 100644 --- a/source/guide.rst +++ b/source/guide.rst @@ -8,7 +8,8 @@ User Guide :maxdepth: 2 tutorial/index - examples/index + matlab_examples/index + python_examples/index algorithms/index advanced/index calcTypes/index diff --git a/source/index.rst b/source/index.rst index 0b05b0f4..fc8000fa 100644 --- a/source/index.rst +++ b/source/index.rst @@ -45,7 +45,9 @@ RAT contains a number of improvements over legacy RasCAL, including: * :ref:`guide`: Learn the core principles of RAT with code snippets. - * :ref:`examples`: Jump into some practical examples. + * :ref:`matlabExamples`: Jump into some practical examples for the MATLAB interface. + + * :ref:`pythonExamples`: Explore some practical examples for the Python interface. .. grid-item-card:: @@ -77,6 +79,5 @@ RAT contains a number of improvements over legacy RasCAL, including: install guide - reference/matlab/index - reference/python/index - + examples + reference/index diff --git a/source/matlab_examples.pdf b/source/matlab_examples.pdf new file mode 100644 index 00000000..086835e9 Binary files /dev/null and b/source/matlab_examples.pdf differ diff --git a/source/matlab_examples/DSPC_custom_XY.rst b/source/matlab_examples/DSPC_custom_XY.rst new file mode 100644 index 00000000..21fab247 --- /dev/null +++ b/source/matlab_examples/DSPC_custom_XY.rst @@ -0,0 +1,49 @@ +============== +DSPC Custom XY +============== + +This shows an example of using a :ref:`custom XY` model to analyse reflectivity from a supported bilayer of DSPC. + +Similar to :ref:`DSPC_Custom_Layers`, we can make use of the fact that the volumes, and of course the atomistic composition are known. So, +for lipid tails for example, then we can take a literature value for the tails volume, have a fittable parameter for the lipid area per molecule, and then the tail thickness will simply be + +.. math:: \text{Tail Thick} = \frac{\text{Tail Volume}}{\text{Lipid APM}}. + +Since the volume is known, then the SLD of the tails is also obviously easily calculable. + +In this model, we make distributions to represent the volume fractions of each of the components in the sample, the convert these to SLD's, as described in :ref:`[1] `. + +We also make our volume fractions as optional outputted parameters from our file. The optional nature of this output means we can suppress it to run the model, then +activate it to make final output plots of our analysis. + +.. image:: ../images/examples/volumeFractions.png + :align: center + :alt: Volume fractions + +This example can be run as a script or interactively using the instructions below. + + +.. note:: The custom model used is a MATLAB model - **examples/normalReflectivity/customXY/customXYDSPC.m**. + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'normalReflectivity', 'customXY')); + customXYDSPCScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'normalReflectivity', 'customXY')); + edit customXYDSPCSheet.mlx + +.. _ref_1: + +[1] Shekhar et al, J. Appl. Phys, 100, 102216 (2011) [`DOI 10.1063/1.3661986 `_] + +.. raw:: html + :file: customXYDSPCSheet.html diff --git a/source/matlab_examples/DSPC_custom_layers.rst b/source/matlab_examples/DSPC_custom_layers.rst new file mode 100644 index 00000000..b72f0320 --- /dev/null +++ b/source/matlab_examples/DSPC_custom_layers.rst @@ -0,0 +1,41 @@ +.. _DSPC_Custom_Layers: + +================== +DSPC Custom Layers +================== + +This shows an example of using a :ref:`custom layers` model to analyse reflectivity from a supported bilayer of DSPC. + +In this example, we can make use of the fact that the volumes, and of course the atomistic composition are known. So, for lipid tails for example, then we can +take a literature value for the tails volume, have a fittable parameter for the lipid area per molecule, and then the tail thickness will simply be + +.. math:: Tail Thick = Tail Volume / Lipid APM. + +Since the volume is known, then the SLD of the tails is also obviously easily calculable. + +In addition, the datasets for this example, have a resolution (per point) in their fourth column. We use this resolution in our analysis, rather than declaring a constant, fittable one. + +This example can be run as a script or interactively using the instructions below. + + +.. note:: The custom model used is a MATLAB model - **examples/normalReflectivity/customLayers/customBilayerDSPC.m**. + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'normalReflectivity', 'customLayers')); + customLayersDSPCScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'normalReflectivity', 'customLayers')); + edit customLayersDSPCSheet.mlx + + +.. raw:: html + :file: customLayersDSPCSheet.html diff --git a/source/matlab_examples/DSPC_standard_layers.rst b/source/matlab_examples/DSPC_standard_layers.rst new file mode 100644 index 00000000..c4568c74 --- /dev/null +++ b/source/matlab_examples/DSPC_standard_layers.rst @@ -0,0 +1,30 @@ +.. _DSPC_Standard_Layers: + +==================== +DSPC Standard Layers +==================== +This shows an example of using a :ref:`standard layers` model to analyse reflectivity from a floating bilayer of DSPC. + +The model is set up in the script, we set Gaussian priors on some of the parameters, build the two contrasts, run the calculation and plot the results. + +This example can be run as a script or interactively using the instructions below. + + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'normalReflectivity', 'standardLayers')); + standardLayersDSPCScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'normalReflectivity', 'standardLayers')); + edit standardLayersDSPCSheet.mlx + +.. raw:: html + :file: standardLayersDSPCSheet.html diff --git a/source/matlab_examples/convert_r1_project.rst b/source/matlab_examples/convert_r1_project.rst new file mode 100644 index 00000000..32ef7d4f --- /dev/null +++ b/source/matlab_examples/convert_r1_project.rst @@ -0,0 +1,23 @@ +============================= +Converting a RasCAL-1 Project +============================= + +If you have projects from RasCAL1, there is a simple utility supplied with the toolbox that makes converting between formats easy as explained in :ref:`conversionFuncs`. + +This example shows the conversion of a RasCAL-1 custom layers project into a RAT project and vice versa, because this is a custom layers project, the custom model +function **Model_IIb.m** which in the example directory is required to run the converted RAT project successfully. + +This example can be run using the instructions below. + +.. note:: The custom model used is a MATLAB model - **examples/miscellaneous/convertRascal1Project/Model_IIb.m**. + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'miscellaneous', 'convertRascal1Project')); + edit convertRascal.mlx + +.. raw:: html + :file: convertRascal.html diff --git a/source/matlab_examples/custom_model_languages.rst b/source/matlab_examples/custom_model_languages.rst new file mode 100644 index 00000000..e4a06985 --- /dev/null +++ b/source/matlab_examples/custom_model_languages.rst @@ -0,0 +1,36 @@ +================================== +Alternative Custom Model Languages +================================== + +In this example, we setup a :ref:`custom layers` problem using three different programming language (MATLAB, Python, and C++) to write the custom model function. +The provided C++ function needs to be compiled into a dynamic library using instructions given in :ref:`customLanguages` or instructions specific to your compiler. + + +This example can be run using the instructions below. + + +.. note:: The custom models used are - + **examples/miscellaneous/languages/alloyDomains.m**, + **examples/miscellaneous/languages/alloyDomains.m**, + **examples/miscellaneous/languages/alloyDomains.m**. + +.. warning:: For Python custom functions, you will need to setup the python environment for MATLAB, see `Setup MATLAB to use Python `_ + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'miscellaneous', 'alternativeLanguages')); + customModelLanguagesScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'miscellaneous', 'alternativeLanguages')); + edit customModelLanguagesSheet.mlx + +.. raw:: html + :file: customModelLanguagesSheet.html diff --git a/source/matlab_examples/domains_custom_XY.rst b/source/matlab_examples/domains_custom_XY.rst new file mode 100644 index 00000000..bf6080fb --- /dev/null +++ b/source/matlab_examples/domains_custom_XY.rst @@ -0,0 +1,33 @@ +================================= +Incoherent Summing with Custom XY +================================= + +This is an example of using incoherent summing ('domains') from custom XY models. + +The domain custom XY model is similar to a normal custom models, except that the input (function arguments) of the custom function contains an additional 'domains' parameter as described in :ref:`domainsCustomModels`. + +This parameter tells the function which is the current domain, so the appropriate layer stack can be generated. + +This example can be run as a script or interactively using the instructions below. + + +.. note:: The custom model used is a MATLAB model - **examples/domains/customXY/domainsXY.m**. + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'domains', 'customXY')); + domainsCustomXYScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'domains', 'customXY')); + edit domainsCustomXYSheet.mlx + +.. raw:: html + :file: domainsCustomXYSheet.html diff --git a/source/matlab_examples/domains_custom_layers.rst b/source/matlab_examples/domains_custom_layers.rst new file mode 100644 index 00000000..b23d161e --- /dev/null +++ b/source/matlab_examples/domains_custom_layers.rst @@ -0,0 +1,33 @@ +===================================== +Incoherent Summing with Custom Layers +===================================== + +This is an example of using incoherent summing ('domains') from custom layers models. The sample is a simple two layer of permalloy/gold, with up/down domains + +The domain custom model is similar to a normal custom models, except that the input (function arguments) of the custom function contains an additional 'domains' parameter as described in :ref:`domainsCustomModels`. + +This parameter tells the function which is the current domain, so the appropriate layer stack can be generated. + +This example can be run as a script or interactively using the instructions below. + + +.. note:: The custom model used is a MATLAB model - **examples/domains/customLayers/alloyDomains.m**. + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'domains', 'customLayers')); + domainsCustomLayersScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'domains', 'customLayers')); + edit domainsCustomLayersSheet.mlx + +.. raw:: html + :file: domainsCustomLayersSheet.html diff --git a/source/matlab_examples/domains_standard_layers.rst b/source/matlab_examples/domains_standard_layers.rst new file mode 100644 index 00000000..435b88bc --- /dev/null +++ b/source/matlab_examples/domains_standard_layers.rst @@ -0,0 +1,39 @@ +======================================= +Incoherent Summing with Standard Layers +======================================= + +Analysing data containing domains using standard layers models is done in a similar way to a normal standard layers model, but with a couple of +additional steps. + +A normal standard layers model defines parameters, which are grouped into layers, and then these are arranged into contrasts. For sample containing domains, the +layers are first grouped into domain 'contrasts', which are just groupings of layers with none of the additional parameters of a contrast (such as resolutions +etc). Then, the actual experimental contrasts are built in the usual way, but with the model set as any two of the domains. + +.. image:: ../images/domainsGraph.png + :align: center + :alt: Domains graph + +To control the ratio between the domains, we can add domain ratios as described in :ref:`domainsStanlay`. And each contrast has an additional field +for domain ratios which is set as one of the values from this block. + +This example can be run as a script or interactively using the instructions below. + +**Run Script**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'domains', 'standardLayers')); + domainsStandardLayersScript + +**Run Interactively**: + +.. code-block:: Matlab + + root = getappdata(0, 'root'); + cd(fullfile(root, 'examples', 'domains', 'standardLayers')); + edit domainsStandardLayersSheet.mlx + + +.. raw:: html + :file: domainsStandardLayersSheet.html diff --git a/source/examples/imaginary.rst b/source/matlab_examples/imaginary.rst similarity index 100% rename from source/examples/imaginary.rst rename to source/matlab_examples/imaginary.rst diff --git a/source/examples/index.rst b/source/matlab_examples/index.rst similarity index 82% rename from source/examples/index.rst rename to source/matlab_examples/index.rst index 339f8b56..c8612d7e 100644 --- a/source/examples/index.rst +++ b/source/matlab_examples/index.rst @@ -1,9 +1,9 @@ -.. _examples: +.. _matlabExamples: -======== -Examples -======== -A number of examples are provided to demonstrate the functionality available in the MATLAB and Python interface of RAT. +=============== +MATLAB Examples +=============== +A number of examples are provided to demonstrate the functionality available in the MATLAB interface of RAT. ****************** Normal Calculation diff --git a/source/python_examples/index.rst b/source/python_examples/index.rst new file mode 100644 index 00000000..b0342dcc --- /dev/null +++ b/source/python_examples/index.rst @@ -0,0 +1,37 @@ +.. _pythonExamples: + +=============== +Python Examples +=============== +A number of examples are provided to demonstrate the functionality available in the Python interface of RAT. + +****************** +Normal Calculation +****************** + +.. toctree:: + :maxdepth: 1 + + notebooks/DSPC_standard_layers + notebooks/DSPC_custom_layers + notebooks/DSPC_custom_xy + +****************** +Domain Calculation +****************** + +.. toctree:: + :maxdepth: 1 + + notebooks/domains_standard_layers + notebooks/domains_custom_layers + notebooks/domains_custom_XY + +************* +Miscellaneous +************* + +.. toctree:: + :maxdepth: 1 + + notebooks/absorption diff --git a/source/python_examples/notebooks/README.md b/source/python_examples/notebooks/README.md new file mode 100644 index 00000000..9048a0c5 --- /dev/null +++ b/source/python_examples/notebooks/README.md @@ -0,0 +1,5 @@ +## Notebooks folder + +This folder contains the notebooks so they can be built by Sphinx. + +It is populated with notebooks by `sphinx build` (see `conf.py`) diff --git a/source/reference/index.rst b/source/reference/index.rst new file mode 100644 index 00000000..383aeae5 --- /dev/null +++ b/source/reference/index.rst @@ -0,0 +1,24 @@ +API Reference +============= + +This section of the documentation contains API reference information for the +Python and MATLAB versions of RAT. + +MATLAB Reference +---------------- + +.. toctree:: + :maxdepth: 3 + + matlab/index + + +Python Reference +---------------- + +.. toctree:: + :maxdepth: 3 + + python/index + +