ratapi 0.0.0.dev16__cp315-cp315-win_amd64.whl

ratapi/controls.py

@@ -0,0 +1,258 @@
+"""The Controls class for providing RAT algorithm settings."""
+
+import contextlib
+import os
+import tempfile
+import warnings
+from pathlib import Path
+
+import prettytable
+from pydantic import (
+    BaseModel,
+    Field,
+    ValidationError,
+    ValidatorFunctionWrapHandler,
+    model_serializer,
+    model_validator,
+)
+
+from ratapi.utils.custom_errors import custom_pydantic_validation_error
+from ratapi.utils.enums import BoundHandling, Display, Parallel, Procedures, Strategies
+
+common_fields = [
+    "procedure",
+    "parallel",
+    "numSimulationPoints",
+    "resampleMinAngle",
+    "resampleNPoints",
+    "display",
+]
+update_fields = ["updateFreq", "updatePlotFreq"]
+fields = {
+    "calculate": common_fields,
+    "simplex": [*common_fields, "xTolerance", "funcTolerance", "maxFuncEvals", "maxIterations", *update_fields],
+    "de": [
+        *common_fields,
+        "populationSize",
+        "fWeight",
+        "crossoverProbability",
+        "strategy",
+        "targetValue",
+        "numGenerations",
+        *update_fields,
+    ],
+    "ns": [*common_fields, "nLive", "nMCMC", "propScale", "nsTolerance"],
+    "dream": [*common_fields, "nSamples", "nChains", "jumpProbability", "pUnitGamma", "boundHandling", "adaptPCR"],
+}
+
+
+class Controls(BaseModel, validate_assignment=True, extra="forbid", use_attribute_docstrings=True):
+    """The full set of controls parameters for all five procedures that are required for the compiled RAT code."""
+
+    # All Procedures
+    procedure: Procedures = Procedures.Calculate
+    """Which procedure RAT should execute. Can be 'calculate', 'simplex', 'de', 'ns', or 'dream'."""
+
+    parallel: Parallel = Parallel.Single
+    """How the calculation should be parallelised. Can be 'single', 'contrasts' or 'points'."""
+
+    numSimulationPoints: int = Field(500, ge=2)
+    """The number of points used for reflectivity simulations where no data is supplied."""
+
+    resampleMinAngle: float = Field(0.9, le=1, gt=0)
+    """The upper threshold on the angle between three sampled points for resampling, in units of radians over pi."""
+
+    resampleNPoints: int = Field(50, gt=0)
+    """The number of initial points to use for resampling."""
+
+    display: Display = Display.Iter
+    """How much RAT should print to the terminal. Can be 'off', 'iter', or 'final'."""
+
+    # Simplex
+    xTolerance: float = Field(1.0e-6, gt=0.0)
+    """[SIMPLEX] The termination tolerance for step size."""
+
+    funcTolerance: float = Field(1.0e-6, gt=0.0)
+    """[SIMPLEX] The termination tolerance for change in chi-squared."""
+
+    maxFuncEvals: int = Field(10000, gt=0)
+    """[SIMPLEX] The maximum number of function evaluations before the algorithm terminates."""
+
+    maxIterations: int = Field(1000, gt=0)
+    """[SIMPLEX] The maximum number of iterations before the algorithm terminates."""
+
+    # Simplex and DE
+    updateFreq: int = 1
+    """[SIMPLEX, DE] Number of iterations between printing progress updates to the terminal."""
+
+    updatePlotFreq: int = 20
+    """[SIMPLEX, DE] Number of iterations between updates to live plots."""
+
+    # DE
+    populationSize: int = Field(20, ge=1)
+    """[DE] The number of candidate solutions that exist at any time."""
+
+    fWeight: float = Field(0.5, gt=0.0)
+    """[DE] The step size for how different mutations are to their parents."""
+
+    crossoverProbability: float = Field(0.8, gt=0.0, lt=1.0)
+    """[DE] The probability of exchange of parameters between individuals at any iteration."""
+
+    strategy: Strategies = Strategies.RandomWithPerVectorDither
+    """[DE] The algorithm used to generate new candidates."""
+
+    targetValue: float = Field(1.0, ge=1.0)
+    """[DE] The value of chi-squared at which the algorithm will terminate."""
+
+    numGenerations: int = Field(500, ge=1)
+    """[DE] The maximum number of iterations before the algorithm terminates."""
+
+    # NS
+    nLive: int = Field(150, ge=1)
+    """[NS] The number of points to sample."""
+
+    nMCMC: int = Field(0, ge=0)
+    """[NS] If non-zero, an MCMC process with ``nMCMC`` chains will be used instead of MultiNest."""
+
+    propScale: float = Field(0.1, gt=0.0, lt=1.0)
+    """[NS] A scaling factor for the ellipsoid generated by MultiNest."""
+
+    nsTolerance: float = Field(0.1, ge=0.0)
+    """[NS] The tolerance threshold for when the algorithm should terminate."""
+
+    # Dream
+    nSamples: int = Field(20000, ge=0)
+    """[DREAM] The total number of function evaluations (number of algorithm generations times number of chains)."""
+
+    nChains: int = Field(10, gt=1)
+    """[DREAM] The number of Markov chains to use in the algorithm."""
+
+    jumpProbability: float = Field(0.5, gt=0.0, lt=1.0)
+    """[DREAM] The probability range for the size of jumps in sampling. Larger values mean more variable jumps."""
+
+    pUnitGamma: float = Field(0.2, gt=0.0, lt=1.0)
+    """[DREAM] The probability that the scaling-down factor of jumps will be ignored and a larger jump will be taken."""
+
+    boundHandling: BoundHandling = BoundHandling.Reflect
+    """[DREAM] How steps past the space boundaries should be handled. Can be 'off', 'reflect', 'bound', or 'fold'."""
+
+    adaptPCR: bool = True
+    """[DREAM] Whether the crossover probability for differential evolution should be adapted during the run."""
+
+    # Private field for IPC file
+    _IPCFilePath: str = ""
+
+    @model_validator(mode="wrap")
+    def warn_setting_incorrect_properties(self, handler: ValidatorFunctionWrapHandler) -> "Controls":
+        """Raise a warning if the user sets fields that apply to other procedures."""
+        model_input = self
+        try:
+            input_dict = model_input.__dict__
+        except AttributeError:
+            input_dict = model_input
+
+        validated_self = None
+        try:
+            validated_self = handler(self)
+        except ValidationError as exc:
+            procedure = input_dict.get("procedure", Procedures.Calculate)
+            custom_error_msgs = {
+                "extra_forbidden": f'Extra inputs are not permitted. The fields for the "{procedure}"'
+                f" controls procedure are:\n    "
+                f"{', '.join(fields.get('procedure', []))}\n",
+            }
+            custom_error_list = custom_pydantic_validation_error(exc.errors(include_url=False), custom_error_msgs)
+            raise ValidationError.from_exception_data(exc.title, custom_error_list, hide_input=True) from None
+
+        if isinstance(model_input, validated_self.__class__):
+            # This is for changing fields in a defined model
+            changed_fields = [key for key in input_dict if input_dict[key] != validated_self.__dict__[key]]
+        elif isinstance(model_input, dict):
+            # This is for a newly-defined model
+            changed_fields = input_dict.keys()
+        else:
+            raise ValueError('The input to the "Controls" model is invalid.')
+
+        new_procedure = validated_self.procedure
+        allowed_fields = fields[new_procedure]
+        for field in changed_fields:
+            if field not in allowed_fields:
+                incorrect_procedures = [key for (key, value) in fields.items() if field in value]
+                warnings.warn(
+                    f'\nThe current controls procedure is "{new_procedure}", but the property'
+                    f' "{field}" applies instead to the {", ".join(incorrect_procedures)} procedure.\n\n'
+                    f' The fields for the "{new_procedure}" controls procedure are:\n'
+                    f"    {', '.join(fields[new_procedure])}\n",
+                    stacklevel=2,
+                )
+
+        return validated_self
+
+    @model_serializer
+    def serialize(self):
+        """Filter fields so only those applying to the chosen procedure are serialized."""
+        return {model_field: getattr(self, model_field) for model_field in fields[self.procedure]}
+
+    def __repr__(self) -> str:
+        fields_repr = ", ".join(repr(v) if a is None else f"{a}={v!r}" for a, v in self.model_dump().items())
+        return f"{self.__repr_name__()}({fields_repr})"
+
+    def __str__(self) -> str:
+        table = prettytable.PrettyTable()
+        table.field_names = ["Property", "Value"]
+        table.add_rows([[k, v] for k, v in self.model_dump().items()])
+        return table.get_string()
+
+    def initialise_IPC(self):
+        """Set up the inter-process communication file."""
+        IPC_obj, self._IPCFilePath = tempfile.mkstemp()
+        os.write(IPC_obj, b"\x00")
+        os.close(IPC_obj)
+        return None
+
+    def sendStopEvent(self):
+        """Send the stop event via the inter-process communication file.
+
+        Warnings
+        --------
+        UserWarning
+            Raised if we try to delete an IPC file that was not initialised.
+
+        """
+        if os.path.isfile(self._IPCFilePath):
+            with open(self._IPCFilePath, "wb") as f:
+                f.write(b"\x01")
+        else:
+            warnings.warn("An IPC file was not initialised.", UserWarning, stacklevel=2)
+        return None
+
+    def delete_IPC(self):
+        """Delete the inter-process communication file."""
+        with contextlib.suppress(FileNotFoundError):
+            os.remove(self._IPCFilePath)
+        self._IPCFilePath = ""
+        return None
+
+    def save(self, filepath: str | Path = "./controls.json"):
+        """Save a controls object to a JSON file.
+
+        Parameters
+        ----------
+        filepath : str or Path
+            The path to where the controls file will be written.
+        """
+        filepath = Path(filepath).with_suffix(".json")
+        filepath.write_text(self.model_dump_json())
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Controls":
+        """Load a controls object from file.
+
+        Parameters
+        ----------
+        path : str or Path
+            The path to the controls object file.
+
+        """
+        file = Path(path)
+        return cls.model_validate_json(file.read_text())

ratapi/events.py

@@ -0,0 +1,88 @@
+"""Hooks for connecting to run callback events."""
+
+import os
+from collections.abc import Callable
+
+from ratapi.rat_core import EventBridge, EventTypes, PlotEventData, ProgressEventData
+
+
+def notify(event_type: EventTypes, data: str | PlotEventData | ProgressEventData) -> None:
+    """Call registered callbacks with data when event type has been triggered.
+
+    Parameters
+    ----------
+    event_type : EventTypes
+        The event type that was triggered.
+    data : str or PlotEventData or ProgressEventData
+        The data sent by the event. The message event data is a string.
+
+    """
+    callbacks = __event_callbacks[event_type]
+    for callback in callbacks:
+        callback(data)
+
+
+def get_event_callback(event_type: EventTypes) -> list[Callable[[str | PlotEventData | ProgressEventData], None]]:
+    """Return all callbacks registered for the given event type.
+
+    Parameters
+    ----------
+    event_type : EventTypes
+        The event type.
+
+    Returns
+    -------
+    callback : Callable[[Union[str, PlotEventData, ProgressEventData]], None]
+        The callback for the event type.
+
+    """
+    return list(__event_callbacks[event_type])
+
+
+def register(event_type: EventTypes, callback: Callable[[str | PlotEventData | ProgressEventData], None]) -> None:
+    """Register a new callback for the event type.
+
+    Parameters
+    ----------
+    event_type : EventTypes
+        The event type to register.
+    callback : Callable[[Union[str, PlotEventData, ProgressEventData]], None]
+        The callback for when the event is triggered.
+
+    """
+    if not isinstance(event_type, EventTypes):
+        raise ValueError("event_type must be a events.EventTypes enum")
+
+    if len(__event_callbacks[event_type]) == 0:
+        __event_impl.register(event_type)
+    __event_callbacks[event_type].add(callback)
+
+
+def clear(key=None, callback=None) -> None:
+    """Clear all event callbacks or specific callback.
+
+    Parameters
+    ----------
+    key : EventTypes, optional
+        The event type of the callback to clear if given.
+    callback : Callable[[Union[str, PlotEventData, ProgressEventData]], None], optional
+        A callback for an event which will be cleared if given.
+
+    """
+    if key is None and callback is None:
+        for key in __event_callbacks:
+            __event_callbacks[key] = set()
+    elif key is not None and callback is not None:
+        __event_callbacks[key].remove(callback)
+
+    for value in __event_callbacks.values():
+        if value:
+            break
+    else:
+        __event_impl.clear()
+
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+os.environ["RAT_PATH"] = os.path.join(dir_path, "")
+__event_impl = EventBridge(notify)
+__event_callbacks = {EventTypes.Message: set(), EventTypes.Plot: set(), EventTypes.Progress: set()}

ratapi/examples/__init__.py

@@ -0,0 +1,25 @@
+"""Usage examples for the Python RAT API."""
+
+from ratapi.examples.absorption.absorption import absorption
+from ratapi.examples.convert_rascal_project.convert_rascal import convert_rascal
+from ratapi.examples.domains.domains_custom_layers import domains_custom_layers
+from ratapi.examples.domains.domains_custom_XY import domains_custom_XY
+from ratapi.examples.domains.domains_standard_layers import domains_standard_layers
+from ratapi.examples.normal_reflectivity.DSPC_custom_layers import DSPC_custom_layers
+from ratapi.examples.normal_reflectivity.DSPC_custom_XY import DSPC_custom_XY
+from ratapi.examples.normal_reflectivity.DSPC_data_background import DSPC_data_background
+from ratapi.examples.normal_reflectivity.DSPC_function_background import DSPC_function_background
+from ratapi.examples.normal_reflectivity.DSPC_standard_layers import DSPC_standard_layers
+
+__all__ = [
+    "absorption",
+    "domains_custom_layers",
+    "domains_custom_XY",
+    "domains_standard_layers",
+    "DSPC_custom_layers",
+    "DSPC_custom_XY",
+    "DSPC_standard_layers",
+    "DSPC_data_background",
+    "DSPC_function_background",
+    "convert_rascal",
+]

ratapi/examples/absorption/__init__.py

@@ -0,0 +1 @@
+"""An example of using absorption in a RAT project."""

ratapi/examples/absorption/absorption.py

@@ -0,0 +1,172 @@
+"""An example for using absorption in RAT."""
+
+import pathlib
+
+import numpy as np
+
+import ratapi as RAT
+
+
+def absorption():
+    """Run a custom layers model including absorption.
+
+    RAT allows the use of an imaginary, as well as real part of the SLD.
+    The effect of this is usually seen below the critical edge, and must sometimes be accounted for.
+
+    This is an example of a Custom Layers project using absorption. used here is Custom Layers.
+    It analyses a bilayer sample on a permalloy / gold substrate,
+    measured using polarised neutrons, against D2O and H2O, leading to 4 contrasts in total.
+    Absorption (i.e. imaginary SLD) is defined for Gold and the Permalloy,
+    to account for non-flat data below the critical edge.
+    """
+    problem = RAT.Project(
+        name="Absorption example",
+        calculation="normal",
+        model="custom layers",
+        geometry="substrate/liquid",
+        absorption=True,
+    )
+
+    # Add the required parameters (substrate roughness is already there by default)
+    problem.parameters.append(name="Alloy Thickness", min=100.0, value=135.6, max=200.0, fit=True)
+    problem.parameters.append(name="Alloy SLD up", min=6.0e-6, value=9.87e-6, max=1.2e-5, fit=True)
+    problem.parameters.append(name="Alloy SLD imaginary up", min=1.0e-9, value=4.87e-8, max=1.0e-7, fit=True)
+    problem.parameters.append(name="Alloy SLD down", min=6.0e-6, value=7.05e-6, max=1.3e-5, fit=True)
+    problem.parameters.append(name="Alloy SLD imaginary down", min=1.0e-9, value=4.87e-8, max=1.0e-7, fit=True)
+    problem.parameters.append(name="Alloy Roughness", min=2.0, value=5.71, max=10.0, fit=True)
+    problem.parameters.append(name="Gold Thickness", min=100.0, value=154.7, max=200.0, fit=True)
+    problem.parameters.append(name="Gold Roughness", min=0.1, value=5.42, max=10.0, fit=True)
+    problem.parameters.append(name="Gold SLD", min=4.0e-6, value=4.49e-6, max=5.0e-6, fit=True)
+    problem.parameters.append(name="Gold SLD imaginary", min=1.0e-9, value=4.20e-8, max=1.0e-7, fit=True)
+
+    problem.parameters.append(name="Thiol APM", min=40.0, value=56.27, max=100.0, fit=True)
+    problem.parameters.append(name="Thiol Head Hydration", min=20.0, value=30.0, max=50.0, fit=True)
+    problem.parameters.append(name="Thiol Coverage", min=0.5, value=0.9, max=1.0, fit=True)
+
+    problem.parameters.append(name="CW Thickness", min=1.0, value=12.87, max=25.0, fit=True)
+    problem.parameters.append(name="Bilayer APM", min=48.0, value=65.86, max=90.0, fit=True)
+    problem.parameters.append(name="Bilayer Head Hydration", min=20.0, value=30.0, max=50.0, fit=True)
+    problem.parameters.append(name="Bilayer Roughness", min=1.0, value=3.87, max=10.0, fit=True)
+    problem.parameters.append(name="Bilayer Coverage", min=0.5, value=0.94, max=1.0, fit=True)
+
+    # Change the existing Bulk In parameter to be Silicon
+    problem.bulk_in.set_fields(0, name="Silicon", min=2.0e-6, value=2.073e-6, max=2.1e-6)
+
+    # We need 2 bulk outs - D2O and H2O
+    problem.bulk_out.set_fields(0, name="D2O", min=5.8e-06, value=6.21e-06, max=6.35e-06, fit=True)
+    problem.bulk_out.append(name="H2O", min=-5.6e-07, value=-3.15e-07, max=0.0, fit=True)
+
+    # Use a different scalefactor for each dataset
+    del problem.scalefactors[0]
+    problem.scalefactors.append(name="Scalefactor 1", min=0.5, value=1, max=1.5, fit=True)
+    problem.scalefactors.append(name="Scalefactor 2", min=0.5, value=1, max=1.5, fit=True)
+    problem.scalefactors.append(name="Scalefactor 3", min=0.5, value=1, max=1.5, fit=True)
+    problem.scalefactors.append(name="Scalefactor 4", min=0.5, value=1, max=1.5, fit=True)
+
+    # Similarly, use an individual background for each dataset
+    del problem.backgrounds[0]
+    del problem.background_parameters[0]
+
+    problem.background_parameters.append(
+        name="Background parameter 1", min=5.0e-08, value=7.88e-06, max=9.0e-05, fit=True
+    )
+    problem.background_parameters.append(
+        name="Background parameter 2", min=1.0e-08, value=5.46e-06, max=9.0e-05, fit=True
+    )
+    problem.background_parameters.append(
+        name="Background parameter 3", min=1.0e-06, value=9.01e-06, max=9.0e-05, fit=True
+    )
+    problem.background_parameters.append(
+        name="Background parameter 4", min=1.0e-06, value=5.61e-06, max=9.0e-05, fit=True
+    )
+
+    problem.backgrounds.append(name="Background 1", type="constant", source="Background parameter 1")
+    problem.backgrounds.append(name="Background 2", type="constant", source="Background parameter 2")
+    problem.backgrounds.append(name="Background 3", type="constant", source="Background parameter 3")
+    problem.backgrounds.append(name="Background 4", type="constant", source="Background parameter 4")
+
+    # Make the resolution fittable
+    problem.resolution_parameters.set_fields(0, fit=True)
+
+    # Now add the data we need
+    data_path = pathlib.Path(__file__).parents[1] / "data"
+
+    data_1 = np.loadtxt(data_path / "D2O_spin_down.dat")
+    problem.data.append(name="D2O_dn", data=data_1)
+
+    data_2 = np.loadtxt(data_path / "D2O_spin_up.dat")
+    problem.data.append(name="D2O_up", data=data_2)
+
+    data_3 = np.loadtxt(data_path / "H2O_spin_down.dat")
+    problem.data.append(name="H2O_dn", data=data_3)
+
+    data_4 = np.loadtxt(data_path / "H2O_spin_up.dat")
+    problem.data.append(name="H2O_up", data=data_4)
+
+    # Add the custom file
+    problem.custom_files.append(
+        name="DPPC absorption",
+        filename="volume_thiol_bilayer.py",
+        language="python",
+        path=pathlib.Path(__file__).parent,
+    )
+
+    # Finally add the contrasts
+    problem.contrasts.append(
+        name="D2O Down",
+        data="D2O_dn",
+        background="Background 1",
+        bulk_in="Silicon",
+        bulk_out="D2O",
+        scalefactor="Scalefactor 1",
+        resolution="Resolution 1",
+        resample=True,
+        model=["DPPC absorption"],
+    )
+
+    problem.contrasts.append(
+        name="D2O Up",
+        data="D2O_up",
+        background="Background 2",
+        bulk_in="Silicon",
+        bulk_out="D2O",
+        scalefactor="Scalefactor 2",
+        resolution="Resolution 1",
+        resample=True,
+        model=["DPPC absorption"],
+    )
+
+    problem.contrasts.append(
+        name="H2O Down",
+        data="H2O_dn",
+        background="Background 3",
+        bulk_in="Silicon",
+        bulk_out="H2O",
+        scalefactor="Scalefactor 3",
+        resolution="Resolution 1",
+        resample=True,
+        model=["DPPC absorption"],
+    )
+
+    problem.contrasts.append(
+        name="H2O Up",
+        data="H2O_up",
+        background="Background 4",
+        bulk_in="Silicon",
+        bulk_out="H2O",
+        scalefactor="Scalefactor 4",
+        resolution="Resolution 1",
+        resample=True,
+        model=["DPPC absorption"],
+    )
+
+    # Now make a controls block and run the code
+    controls = RAT.Controls(parallel="contrasts", resampleNPoints=150)
+    problem, results = RAT.run(problem, controls)
+
+    return problem, results
+
+
+if __name__ == "__main__":
+    problem, results = absorption()
+    RAT.plotting.plot_ref_sld(problem, results, True)