Adds orsopy integration for .ort files and ORSO models

.github/workflows/run_tests.yml

@@ -53,5 +53,5 @@ jobs:
       - name: Install and Test with pytest
         run: |
           export PATH="$pythonLocation:$PATH"
-          python -m pip install -e .[Dev]
+          python -m pip install -e .[Dev,Orso]
           pytest tests/ --cov=RATapi --cov-report=term

RATapi/__init__.py

@@ -6,6 +6,6 @@
 from RATapi.controls import Controls
 from RATapi.project import Project
 from RATapi.run import run
-from RATapi.utils import convert, plotting
+from RATapi.utils import convert, orso, plotting
 
-__all__ = ["examples", "models", "events", "ClassList", "Controls", "Project", "run", "plotting", "convert"]
+__all__ = ["examples", "models", "events", "ClassList", "Controls", "Project", "run", "plotting", "convert", "orso"]

RATapi/classlist.py

@@ -296,6 +296,19 @@ def extend(self, other: Sequence[T]) -> None:
         self._check_unique_name_fields(other)
         self.data.extend(other)
 
+    def union(self, other: Sequence[T]) -> None:
+        """Extend the ClassList by a sequence, ignoring input items with names that already exist."""
+        if other and not (isinstance(other, Sequence) and not isinstance(other, str)):
+            other = [other]
+
+        self.extend(
+            [
+                item
+                for item in other
+                if hasattr(item, self.name_field) and getattr(item, self.name_field) not in self.get_names()
+            ]
+        )
+
     def set_fields(self, index: Union[int, slice, str, T], **kwargs) -> None:
         """Assign the values of an existing object's attributes using keyword arguments."""
         self._validate_name_field(kwargs)

RATapi/examples/orso_integration/orso_integration.ipynb

@@ -0,0 +1,188 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# ``orsopy`` Integration"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "``python-RAT`` contains some integration with ``orsopy``, allowing for convenient interaction with the ``.ort`` file format. This integration is available through the `RATapi.utils.orso` submodule."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import RATapi.utils.orso"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Creating models from the ORSO model description language\n",
+    "\n",
+    "The [ORSO model description format](https://www.reflectometry.org/advanced_and_expert_level/file_format/simple_model) allows the description of a standard slab model as a one-line string, provided that all the layer materials are defined [in the ORSO SLD database](https://slddb.esss.dk/slddb/).\n",
+    "\n",
+    "The function `RATapi.utils.orso.orso_model_to_rat` function can read a model and return an `ORSOSample` dataclass, which gives bulk in and bulk out parameters for the model, a list of all layers defined in the model, and all the parameters needed to define those layers as RAT models. \n",
+    "\n",
+    "**Note:** the ORSO format gives the thicknesses of materials in *nanometres*. When we convert them to RAT parameters, the units will be converted to Angstroms.\n",
+    "\n",
+    "For example, the string `air | Ni 100 | SiO2 0.5 | Si` describes a 1000 angstrom nickel film backed by a 5 angstrom silicon oxide layer. The bulk-in and bulk-out are air and silicon respectively. The roughnesses and SLDs will be calculated or taken from the ORSO SLD database."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create the RAT parameters and layers from this model\n",
+    "sample = RATapi.utils.orso.orso_model_to_rat(\"air | Ni 100 | SiO2 0.5 | Si\")\n",
+    "print(sample)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also set `absorption=True` and the model will account for absorption. For example if we change the nickel film for a boron carbide film and want to account for its relatively high absorption, we can add it to the output:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sample = RATapi.utils.orso.orso_model_to_rat(\"vacuum | B4C 100 | SiO2 0.5 | Si\", absorption=True)\n",
+    "print(sample)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, ORSO supports defining repeated layers using parentheses. For example, if we had a polarising multilayer of 5 repetitions of 70 angstrom silicon and 70 angstrom iron, we could represent it as `air | 5 ( Si 7 | Fe 7 ) | Si`.\n",
+    "\n",
+    "RAT will only create the number of layers and parameters necessary, but the `ORSOSample` object's `model` attribute will give a list of layer names with the structure of the model preserved, which can be given as the layer model for a Contrast."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sample = RATapi.utils.orso.orso_model_to_rat(\"air | 5 ( Si 7 | Fe 7 ) | Si\")\n",
+    "print(sample)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Reading in data and models from .ort files"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "RAT can also load both data and model information from an .ort file. This is done through the `ORSOProject` object, which takes a file path and can also optionally account for absorption.\n",
+    "\n",
+    "The example data file we use here is example data for an unknown film on deposited on silicon."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pathlib\n",
+    "data_path = pathlib.Path(\"../data\")\n",
+    "\n",
+    "orso_data = RATapi.utils.orso.ORSOProject(data_path / \"c_PLP0011859_q.ort\")\n",
+    "print(orso_data)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `ORSOProject` object contains two lists: `ORSOProject.data` and `ORSOProject.samples`. The former is a list of Data objects with each dataset defined in the file, and the latter is a list of `ORSOSample` objects (like above) with model information. Note that if the .ort file does not define a model for a dataset, that index of `ORSOProject.samples` will be None.\n",
+    "\n",
+    "It's then easy to access this data to create a RAT `Project` that represents our data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from RATapi.models import Background, Contrast, Parameter, Resolution\n",
+    "\n",
+    "dataset = orso_data.data[0]\n",
+    "sample = orso_data.samples[0]\n",
+    "\n",
+    "project = RATapi.Project(\n",
+    "    name = \"Example Project\",\n",
+    "    geometry = \"substrate/liquid\",\n",
+    "    parameters = sample.parameters,\n",
+    "    bulk_in = [sample.bulk_in],\n",
+    "    bulk_out = [sample.bulk_out],\n",
+    "    scalefactors = [Parameter(name=\"Scalefactor\", min=0, value=0.34, max=1.5)],\n",
+    "    background_parameters = [Parameter(name=\"Background Parameter\", min=0, value=2e-6, max=1)],\n",
+    "    backgrounds = [Background(name=\"Background\", type=\"constant\", source=\"Background Parameter\")],\n",
+    "    resolutions = [Resolution(name=\"Data Resolution\", type=\"data\")],\n",
+    "    data = [dataset],\n",
+    "    layers = sample.layers,\n",
+    "    contrasts = [Contrast(\n",
+    "        name = \"prist4\",\n",
+    "        data = dataset.name,\n",
+    "        background = \"Background\",\n",
+    "        bulk_in = sample.bulk_in.name,\n",
+    "        bulk_out = sample.bulk_out.name,\n",
+    "        scalefactor = \"Scalefactor\",\n",
+    "        resolution = \"Data Resolution\",\n",
+    "        model = sample.model,\n",
+    "    )]\n",
+    ")\n",
+    "\n",
+    "controls = RATapi.Controls()\n",
+    "project, results = RATapi.run(project, controls)\n",
+    "RATapi.plotting.plot_ref_sld(project, results)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}