diff --git a/docs/source/api/python/mantid/utils/index.rst b/docs/source/api/python/mantid/utils/index.rst index 7fad317e7cfd..c7079d2b12f1 100644 --- a/docs/source/api/python/mantid/utils/index.rst +++ b/docs/source/api/python/mantid/utils/index.rst @@ -1,5 +1,6 @@ .. _mantid.utils: + ==================== :mod:`mantid.utils` ==================== @@ -10,10 +11,10 @@ can be used as a library to pull internal functions from an algorithm so that the code can be shared with external software needing the same functionality without the need to duplicate code. -Unit tests for functions in this module should be placed in the -``Framework/PythonInterface/test/python/mantid/utils/`` directory and -added to its ``CMakeLists.txt`` to make sure the testing code gets -registered with Mantid. +.. toctree:: + :maxdepth: 1 + + reflectometry Calling functions from ``utils`` @@ -69,3 +70,12 @@ can be called from different algorithms. element_size=2, # integration element cube in mm cache_dir="/tmp", # cache diretory for speeding up repeated calculation ) + + +Testing ``utils`` +================= + +Unit tests for functions in this module should be placed in the +``Framework/PythonInterface/test/python/mantid/utils/`` directory and +added to its ``CMakeLists.txt`` to make sure the testing code gets +registered with Mantid. diff --git a/docs/source/api/python/mantid/utils/reflectometry.rst b/docs/source/api/python/mantid/utils/reflectometry.rst new file mode 100644 index 000000000000..ddcd9706f399 --- /dev/null +++ b/docs/source/api/python/mantid/utils/reflectometry.rst @@ -0,0 +1,38 @@ +.. _mantid.utils.reflectometry: + +Reflectometry Utilities +======================= + + +ORSO format IO +-------------- + +The ``mantid.utils.reflectometry.orso_helper`` module provides functionality for reading and saving +reflectivity data in the ORSO standard [#ORSO]_ format. +The orsopy library [#orsopy]_ is used to collect numerical data as well as metadata into meaningful data structures +which are later assembled and written out to file. +The file's format can be ASCII (``.ort``) or binary Nexus (``.orb``). + +The ``orso_helper`` module defines classes such as ``MantidORSOSaver``, ``MantidORSODataset``, +and ``MantidORSODataColumns`` to facilitate the creation, manipulation, and saving of ORSO datasets. +The ``MantidORSOSaver`` class manages the saving of datasets in ASCII or Nexus formats, +while the ``MantidORSODataset`` class constructs the dataset with necessary metadata and data columns. +Finally, the ``MantidORSODataColumns`` class handles the addition and management of data columns and their +associated metadata. + + +.. image:: /images/orso_helper.png + :alt: Class diagram showing the main classes and their relationships + :width: 50% + +This module integrates with the rest of the Mantid framework to ensure that reflectivity is standardized +and shared in compliance with ORSO specifications. +For instance, the module provides the backend functionality for the implementation of algorithm +:ref:`algm-SaveISISReflectometryORSO`. + + +References +---------- + +.. [#ORSO] ORSO file format specification: `https://www.reflectometry.org/file_format/specification `_ +.. [#orsopy] orsopy Python library: `https://orsopy.readthedocs.io/en/latest/ `_ diff --git a/docs/source/images/orso_helper.png b/docs/source/images/orso_helper.png new file mode 100644 index 000000000000..3f855b057fb1 Binary files /dev/null and b/docs/source/images/orso_helper.png differ diff --git a/docs/source/images/orso_helper.puml b/docs/source/images/orso_helper.puml new file mode 100644 index 000000000000..0f0b7b75be59 --- /dev/null +++ b/docs/source/images/orso_helper.puml @@ -0,0 +1,41 @@ +@startuml + +class orsopy.Column {} + +class orsopy.ErrorColumn {} + +class orsopy.OrsoDataset{} + +class orsopy.Orso{} + +class orsopy.Header{} + +class MantidORSOSaver { + - _datasets: List[MantidORSODataset] + + add_dataset(dataset: MantidORSODataset) + + save_orso_ascii() + + save_orso_nexus() +} + +class MantidORSODataset { + - _data_columns: MantidORSODataColumns + - _header: orsopy.Orso(_data_columns.header_info,...) + + dataset() : OrsoDataset(_header, _data_columns.data) +} + +class MantidORSODataColumns { + + data: np.ndarray + + header_info: List[Union[Column, ErrorColumn]] +} + +orsopy.Orso <-- orsopy.Header + +MantidORSOSaver "1" *-- "0..*" MantidORSODataset +MantidORSODataset *-- MantidORSODataColumns +MantidORSODataset *-- orsopy.Orso +MantidORSODataset ..> orsopy.OrsoDataset : returns + +MantidORSODataColumns "1" *-- "0..*" orsopy.Column +MantidORSODataColumns "1" *-- "0..*" orsopy.ErrorColumn + +@enduml