Add SavePolarizationNXcanSAS Algorithm (#39118)

* Change spin state validator to input std::string and accept an optional extra spin paramter

* Refactor constructor for spin state validator where necessary

* add save pol algorithm

* Add cansas and nexus definitions for polarization

* Add polarization to SaveNXcanSAS base

* Refactor NXcanSASHelper file to save polarized metadata and data

* Add missing spin combinations

* Add helper struct for handling spin vectors and add error signal to file

* Add default suffix for sas entry

* Add a struct to handle spin vectors more gracefully, and reorganied code better

* Add some validation for input spin strings and reorganized redundant code

* Save docs file with basic info

* typo in definitions

* Remove private class methods and inherit from nxcansasfiletest class to access those methods

* Add helper test class for SaveNXcanSASTest and SavePolarizedNXcanSASTest

* Add release notes

* Clean SavePolarized class

* ammend release note typo

* Add nxcansas polarization states to polarization correction helpers

* Add SavePolarized test suite

* Refactor NXcanSAS test helpers to accomodate polarized data

* Update definitions

* Refactor, reorganized and clean NXcanSAS helper library

* - Refactor, reorganized and clean base algorithm
- Improve validation for polarized data
- Add definitions for standard properties
- Improve polarized component map creation

* Modify signature of prepareFilename after refactor of helper file

* Modify signature of prepareFilename after refactor of helper file in SavePol algorithm

* Refactor Load and Save NXcanSAS test after changing the structure of transmission parameters in helper test file

* Refactor, reorganized and clean helper test class
Add more private methods for testing polarized data

* Flesh out docs

* Add instrument file to unit_testing folder in instruments with a polarized sans instrument

* Fix some cppcheck warnings

* Changes after rebase

* Fix doxygen typo and include error

* Try to fix docs typo

* Refactor return of extra pairs

* Reword error message and use output stream to simplify conditional error message

* - Bring spin state validator from kernel
- Remove dependencies with Mantid::algorithms
- Homogeneize all const to west const

* Remove link to mantid algorithms from data handling

* Add better error message in spin state validator

* Add separator parameter to split string into vector

* Update file date

* Move SaveNXcanSAS and SavePolarizedNXcanSAS property names to nxcansasdefinitions

* - Add helper class for storing data dimensions information
- Split save polarized fucntion into smaller functions

* - Remove property names from cansasbase
- Split validator of polarized properties into smaller validator functions

* Use initilization list for points and histogram variables

* Add consts where appropriate in NXcanSASFileTest

* Fix grammar typo in release notes

* - Rename parameter separator to separators
- Specify the role of separators splitting multiple characters
- Add test for multiple character separators

* - Add consts where appropriate
- Rename Pin, Pout to pIn, pOut
- Prefix getters in DataDimensions struct with get
- Fix various docstring typos

* - Improve error handling in areAxisNumeric function
- Fix various typos in docstrings
- Add consts were appropriate

* Use std iterator function to check non numeric axis and avoid cppcheck warning

Author: adriazalvarez

Framework/Algorithms/src/PolarizationCorrectionFredrikze.cpp

@@ -297,7 +297,7 @@ void PolarizationCorrectionFredrikze::init() {
       "An output workspace.");
 
   const auto spinStateValidator =
-      std::make_shared<SpinStateValidator>(std::unordered_set<int>{2, 4}, true, 'p', 'a', true);
+      std::make_shared<SpinStateValidator>(std::unordered_set<int>{2, 4}, true, "p", "a", true);
 
   declareProperty(Prop::INPUT_SPIN_STATES, "", spinStateValidator,
                   "The order of spin states in the input workspace group. The possible values are 'pp,pa,ap,aa' or "

Framework/Algorithms/src/PolarizationCorrectionWildes.cpp

@@ -336,7 +336,7 @@ void PolarizationCorrectionWildes::init() {
                       FlipperConfigurations::ON_OFF + ", " + FlipperConfigurations::ON_ON,
                   flipperConfigValidator, "Flipper configurations of the input workspaces.");
   const auto spinStateValidator =
-      std::make_shared<Kernel::SpinStateValidator>(std::unordered_set<int>{0, 2, 4}, false, '+', '-', true);
+      std::make_shared<Kernel::SpinStateValidator>(std::unordered_set<int>{0, 2, 4}, false, "+", "-", true);
   declareProperty(Prop::SPIN_STATES, "", spinStateValidator, "The order of the spin states in the output workspace.");
   declareProperty(
       std::make_unique<API::WorkspaceProperty<API::MatrixWorkspace>>(Prop::EFFICIENCIES, "", Kernel::Direction::Input),

Framework/Algorithms/src/PolarizationEfficiencyCor.cpp

@@ -97,12 +97,12 @@ void PolarizationEfficiencyCor::init() {
       "Ap, Rho and Alpha for Fredrikze.");
 
   const auto wildesFlipperValidator =
-      std::make_shared<SpinStateValidator>(std::unordered_set<int>{1, 2, 3, 4}, true, '0', '1', true);
+      std::make_shared<SpinStateValidator>(std::unordered_set<int>{1, 2, 3, 4}, true, "0", "1", true);
   declareProperty(Prop::FLIPPERS, "", wildesFlipperValidator,
                   "Flipper configurations of the input workspaces  (Wildes method only)");
 
   const auto spinStateValidator =
-      std::make_shared<SpinStateValidator>(std::unordered_set<int>{0, 2, 4}, true, '+', '-', true);
+      std::make_shared<SpinStateValidator>(std::unordered_set<int>{0, 2, 4}, true, "+", "-", true);
   declareProperty(Prop::OUTPUT_WILDES_SPIN_STATES, "", spinStateValidator,
                   "The order of the spin states in the output workspace. (Wildes method only).");
 
@@ -114,7 +114,7 @@ void PolarizationEfficiencyCor::init() {
                   "(Fredrikze method only)");
 
   const auto fredrikzeSpinStateValidator =
-      std::make_shared<SpinStateValidator>(std::unordered_set<int>{2, 4}, true, 'p', 'a', true);
+      std::make_shared<SpinStateValidator>(std::unordered_set<int>{2, 4}, true, "p", "a", true);
 
   declareProperty(Prop::INPUT_FRED_SPIN_STATES, "", fredrikzeSpinStateValidator,
                   "The order of spin states in the input workspace group. The possible values are 'pp,pa,ap,aa' or "

Framework/DataHandling/CMakeLists.txt

@@ -189,6 +189,7 @@ set(SRC_FILES
     src/SavePDFGui.cpp
     src/SavePHX.cpp
     src/SaveParameterFile.cpp
+    src/SavePolarizedNXcanSAS.cpp
     src/SaveRKH.cpp
     src/SaveRMCProfile.cpp
     src/SaveReflectometryAscii.cpp
@@ -401,6 +402,7 @@ set(INC_FILES
     inc/MantidDataHandling/SavePDFGui.h
     inc/MantidDataHandling/SavePHX.h
     inc/MantidDataHandling/SaveParameterFile.h
+    inc/MantidDataHandling/SavePolarizedNXcanSAS.h
     inc/MantidDataHandling/SaveRKH.h
     inc/MantidDataHandling/SaveRMCProfile.h
     inc/MantidDataHandling/SaveReflectometryAscii.h
@@ -598,6 +600,7 @@ set(TEST_FILES
     SavePDFGuiTest.h
     SavePHXTest.h
     SaveParameterFileTest.h
+    SavePolarizedNXcanSASTest.h
     SaveRKHTest.h
     SaveRMCProfileTest.h
     SaveReflectometryAsciiTest.h

Framework/DataHandling/inc/MantidDataHandling/NXcanSASDefinitions.h

@@ -12,8 +12,49 @@ namespace Mantid {
 namespace DataHandling {
 
 namespace NXcanSAS {
+
+/// Property names for save algorithms.
+namespace StandardProperties {
+static const std::string INPUT_WORKSPACE = "InputWorkspace";
+static const std::string FILENAME = "Filename";
+static const std::string RADIATION_SOURCE = "RadiationSource";
+static const std::string DETECTOR_NAMES = "DetectorNames";
+static const std::string TRANSMISSION = "Transmission";
+static const std::string TRANSMISSION_CAN = "TransmissionCan";
+static const std::string SAMPLE_TRANS_RUN_NUMBER = "SampleTransmissionRunNumber";
+static const std::string SAMPLE_DIRECT_RUN_NUMBER = "SampleDirectRunNumber";
+static const std::string CAN_SCATTER_RUN_NUMBER = "CanScatterRunNumber";
+static const std::string CAN_DIRECT_RUN_NUMBER = "CanDirectRunNumber";
+static const std::string BKG_SUB_WORKSPACE = "BackgroundSubtractionWorkspace";
+static const std::string BKG_SUB_SCALE = "BackgroundSubtractionScaleFactor";
+static const std::string GEOMETRY = "Geometry";
+static const std::string SAMPLE_HEIGHT = "SampleHeight";
+static const std::string SAMPLE_WIDTH = "SampleWidth";
+static const std::string SAMPLE_THICKNESS = "SampleThickness";
+} // namespace StandardProperties
+
+namespace PolProperties {
+static const std::string INPUT_SPIN_STATES = "InputSpinStates";
+static const std::string POLARIZER_COMP_NAME = "PolarizerComponentName";
+static const std::string ANALYZER_COMP_NAME = "AnalyzerComponentName";
+static const std::string FLIPPER_COMP_NAMES = "FlipperComponentNames";
+static const std::string MAG_FIELD_STRENGTH_LOGNAME = "MagneticFieldStrengthLogName";
+static const std::string MAG_FIELD_DIR = "MagneticFieldDirection";
+inline std::map<std::string, std::string> POL_COMPONENTS = {
+    {"polarizer", POLARIZER_COMP_NAME}, {"analyzer", ANALYZER_COMP_NAME}, {"flipper", FLIPPER_COMP_NAMES}};
+} // namespace PolProperties
+
+namespace SpinStateNXcanSAS {
+static const std::string SPIN_PARA = "+1";
+static const std::string SPIN_ANTIPARA = "-1";
+static const std::string SPIN_ZERO = "0";
+} // namespace SpinStateNXcanSAS
+
 // General
-enum class WorkspaceDimensionality { oneD, twoD, other };
+enum class WorkspaceDimensionality { other, oneD, twoD };
+
+// NXcanSAS file extension
+const std::string NX_CANSAS_EXTENSION = ".h5";
 
 // NXcanSAS Tag Definitions
 const std::string sasUnitAttr = "units";
@@ -46,6 +87,7 @@ const std::string sasEntryDefinitionFormat = "NXcanSAS";
 const std::string sasEntryTitle = "title";
 const std::string sasEntryRun = "run";
 const std::string sasEntryRunInLogs = "run_number";
+const std::string sasEntryDefaultSuffix = "01";
 
 // SASdata
 const std::string sasDataClassAttr = "SASdata";
@@ -112,6 +154,42 @@ const std::string sasBeamAndSampleSizeUnitAttrValue = "mm";
 
 const std::string sasInstrumentIDF = "idf";
 
+// SASpolarization
+// WIP: Initial proposal: https://wiki.cansas.org/index.php?title=NXcanSAS_v1.1
+const std::string sasDataPout = "Pout";
+const std::string sasDataPin = "Pin";
+const std::string sasDataPoutIndicesAttr = "Pout_indices";
+const std::string sasDataPinIndicesAttr = "Pin_indices";
+constexpr int sasDataPoutIndicesValue = 1;
+constexpr int sasDataPinIndicesValue = 0;
+const std::string sasDataPolarizationUnitAttr = "none";
+
+struct InstrumentPolarizer {
+  explicit InstrumentPolarizer(const std::string &type, const std::string &name) : m_type(type), m_name(name) {};
+  std::string sasPolarizerClassAttr() const { return "SAS" + m_type; }
+  std::string sasPolarizerGroupAttr() const { return "sas" + m_type; }
+  std::string nxPolarizerClassAttr() const { return (m_type == "flipper") ? "NX" + m_type : "NXpolarizer"; }
+  static std::string sasPolarizerName() { return "name"; }
+  static std::string sasPolarizerDeviceType() { return "type"; }
+  static std::string sasPolarizerIDFDeviceType() { return "device-type"; }
+  static std::string sasPolarizerDistance() { return "distance"; }
+  static std::string sasPolarizerDistanceUnitAttr() { return "m"; }
+  const std::string &getComponentName() const { return m_name; }
+  const std::string &getComponentType() const { return m_type; }
+
+private:
+  std::string m_type;
+  std::string m_name;
+};
+
+const std::string sasSampleMagneticField = "magnetic_field";
+const std::string sasSampleEMFieldDirectionAttr = "direction";
+const std::string sasSampleEMFieldDirectionSphericalAttr = "direction_spherical";
+const std::string sasSampleEMFieldDirectionPolar = "polar_angle";
+const std::string sasSampleEMFieldDirectionAzimuthal = "azimuthal_angle";
+const std::string sasSampleEMFieldDirectionRotation = "rotation_angle";
+const std::string sasSampleEMFieldDirectionUnitsAttr = "degrees";
+
 // SASprocess
 const std::string sasProcessClassAttr = "SASprocess";
 const std::string nxProcessClassAttr = "NXprocess";

Framework/DataHandling/inc/MantidDataHandling/NXcanSASHelper.h

@@ -6,21 +6,24 @@
 // SPDX - License - Identifier: GPL - 3.0 +
 #pragma once
 
-#include "MantidAPI/Algorithm.h"
 #include "MantidAPI/MatrixWorkspace_fwd.h"
+#include "MantidAPI/WorkspaceGroup_fwd.h"
 #include "MantidDataHandling/DllConfig.h"
 #include <H5Cpp.h>
 #include <filesystem>
+#include <vector>
 
 namespace Mantid {
 namespace DataHandling {
 namespace NXcanSAS {
 // Helper functions for algorithms saving in NXcanSAS format.
 enum class WorkspaceDimensionality;
 
-std::string MANTID_DATAHANDLING_DLL makeCanSASRelaxedName(const std::string &input);
-std::filesystem::path MANTID_DATAHANDLING_DLL prepareFilename(const std::string &baseFilename, int index,
-                                                              bool isGroup = false);
+// DATA
+void MANTID_DATAHANDLING_DLL addData1D(H5::Group &data, const Mantid::API::MatrixWorkspace_sptr &workspace);
+void MANTID_DATAHANDLING_DLL addData2D(H5::Group &data, const Mantid::API::MatrixWorkspace_sptr &workspace);
+
+// STANDARD METADATA
 void MANTID_DATAHANDLING_DLL addDetectors(H5::Group &group, const Mantid::API::MatrixWorkspace_sptr &workspace,
                                           const std::vector<std::string> &detectorNames);
 void MANTID_DATAHANDLING_DLL addInstrument(H5::Group &group, const Mantid::API::MatrixWorkspace_sptr &workspace,
@@ -36,12 +39,27 @@ void MANTID_DATAHANDLING_DLL addProcessEntry(H5::Group &group, const std::string
 void MANTID_DATAHANDLING_DLL addTransmission(H5::Group &group, const Mantid::API::MatrixWorkspace_const_sptr &workspace,
                                              const std::string &transmissionName);
 
-void MANTID_DATAHANDLING_DLL addData1D(H5::Group &data, const Mantid::API::MatrixWorkspace_sptr &workspace);
-void MANTID_DATAHANDLING_DLL addData2D(H5::Group &data, const Mantid::API::MatrixWorkspace_sptr &workspace);
+// POLARIZED DATA
+void MANTID_DATAHANDLING_DLL addPolarizedData(H5::Group &data, const Mantid::API::WorkspaceGroup_sptr &wsGroup,
+                                              const std::string &inputSpinStates);
+void MANTID_DATAHANDLING_DLL addPolarizer(H5::Group &group, const Mantid::API::MatrixWorkspace_sptr &workspace,
+                                          const std::string &componentName, const std::string &componentType,
+                                          const std::string &groupSuffix);
+
+// POLARIZED METADATA
+void MANTID_DATAHANDLING_DLL addSampleEMFields(H5::Group &group, const Mantid::API::MatrixWorkspace_sptr &workspace,
+                                               const std::string &emFieldStrengthLog, const std::string &emFieldDir);
+void MANTID_DATAHANDLING_DLL addEMFieldDirection(H5::Group &group, const std::string &emFieldDir);
+
+// UTILITY
+std::string MANTID_DATAHANDLING_DLL makeCanSASRelaxedName(const std::string &input);
+H5::H5File MANTID_DATAHANDLING_DLL prepareFile(const std::filesystem::path &path);
+std::filesystem::path MANTID_DATAHANDLING_DLL prepareFilename(const std::string &baseFilename,
+                                                              bool addDigitSuffix = false, size_t index = 0);
 
+std::string MANTID_DATAHANDLING_DLL addDigit(size_t index);
 WorkspaceDimensionality MANTID_DATAHANDLING_DLL
 getWorkspaceDimensionality(const Mantid::API::MatrixWorkspace_sptr &workspace);
-std::vector<std::string> MANTID_DATAHANDLING_DLL splitDetectorNames(std::string detectorNames);
 
 } // namespace NXcanSAS
 } // namespace DataHandling

Framework/DataHandling/inc/MantidDataHandling/SaveNXcanSASBase.h

@@ -8,28 +8,43 @@
 
 #include "MantidAPI/Algorithm.h"
 #include "MantidAPI/MatrixWorkspace_fwd.h"
+#include "MantidAPI/WorkspaceGroup_fwd.h"
 #include "MantidDataHandling/DllConfig.h"
+
 #include <H5Cpp.h>
 #include <filesystem>
 
 namespace Mantid {
 namespace DataHandling {
 
-/** SaveNXcanSASBase : Base class to save a reduced workspace in the NXcanSAS format. Currently
- * only MatrixWorkspaces resulting from
- * 1D and 2D reductions are supported.
+/** SaveNXcanSASBase : Base class to save a reduced workspace in the NXcanSAS format.
+ *  Depending on the derived algorithm, it contains a member that stores standard SANS reduced data
+ *  in 1D or 2D from group or matrix workspaces,or polarized SANS reduced data in 1D or 2D from group workspaces.
  */
 class MANTID_DATAHANDLING_DLL SaveNXcanSASBase : public API::Algorithm {
 protected:
-  void saveSingleWorkspaceFile(const API::MatrixWorkspace_sptr &workspace, const std::filesystem::path &path);
-  void addStandardMetadata(const Mantid::API::MatrixWorkspace_sptr &workspace, H5::Group &sasEntry);
-  void addData(H5::Group &group, const Mantid::API::MatrixWorkspace_sptr &workspace);
+  void addStandardMetadata(const Mantid::API::MatrixWorkspace_sptr &workspace, H5::Group &sasEntry) const;
+  void addPolarizedMetadata(const Mantid::API::MatrixWorkspace_sptr &workspace, H5::Group &sasEntry) const;
+  void addData(H5::Group &group, const Mantid::API::MatrixWorkspace_sptr &workspace) const;
+  void addPolarizedData(H5::Group &group, const Mantid::API::WorkspaceGroup_sptr &wsGroup) const;
   H5::Group addSasEntry(H5::H5File &file, const Mantid::API::MatrixWorkspace_sptr &workspace,
-                        const std::string &suffix);
+                        const std::string &suffix) const;
+
   void initStandardProperties();
-  std::map<std::string, std::string> validateStandardInputs();
+  void initPolarizedProperties();
+  std::map<std::string, std::string> validateStandardInputs() const;
+  // Polarized data and metadata
+  std::map<std::string, std::string> validatePolarizedInputWorkspace(const std::vector<std::string> &spinVec) const;
+  std::map<std::string, std::string> validateSpinStateStrings(const std::vector<std::string> &spinVec) const;
+  std::map<std::string, std::string> validatePolarizedMetadata() const;
+
+  void saveSingleWorkspaceFile(const API::MatrixWorkspace_sptr &workspace, const std::filesystem::path &path) const;
+  void savePolarizedGroup(const API::WorkspaceGroup_sptr &wsGroup, const std::filesystem::path &path) const;
 
   std::unique_ptr<API::Progress> m_progress = nullptr;
+
+private:
+  std::map<std::string, std::vector<std::string>> createPolarizedComponentMap() const;
 };
 
 } // namespace DataHandling

Framework/DataHandling/inc/MantidDataHandling/SavePolarizedNXcanSAS.h

@@ -0,0 +1,48 @@
+// Mantid Repository : https://github.com/mantidproject/mantid
+//
+// Copyright © 2025 ISIS Rutherford Appleton Laboratory UKRI,
+//   NScD Oak Ridge National Laboratory, European Spallation Source,
+//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
+// SPDX - License - Identifier: GPL - 3.0 +
+#pragma once
+
+#include "MantidDataHandling/DllConfig.h"
+#include "MantidDataHandling/SaveNXcanSASBase.h"
+
+namespace Mantid {
+namespace DataHandling {
+
+/** SavePolarizedNXcanSAS : Extends SaveNXcanSAS adding metadata for polarized SANS measurements.
+ */
+class MANTID_DATAHANDLING_DLL SavePolarizedNXcanSAS final : public SaveNXcanSASBase {
+public:
+  /// Constructor
+  SavePolarizedNXcanSAS();
+  /// Virtual dtor
+  ~SavePolarizedNXcanSAS() override = default;
+  const std::string name() const override { return "SavePolarizedNXcanSAS"; }
+  const std::string summary() const override {
+    return "Save a Group Workspace with reduced SANS polarized data in NXcanSAS Format.";
+  }
+
+  /// InputWorkspace property only accepts workspace groups so we don't want the base algorithm class to process
+  /// them as it will done in exec.
+  bool checkGroups() override { return false; }
+
+  /// Algorithm's version
+  int version() const override { return (1); }
+  const std::vector<std::string> seeAlso() const override { return {"SaveNXcanSAS", "LoadNXcanSAS"}; }
+  /// Algorithm's category for identification
+  const std::string category() const override { return "DataHandling\\Nexus"; }
+
+  std::map<std::string, std::string> validateInputs() override;
+
+private:
+  /// Initialisation code
+  void init() override;
+  /// Execution code
+  void exec() override;
+};
+
+} // namespace DataHandling
+} // namespace Mantid