feat: Add RangedVector3 class (#2308)

Author: trisyoungs

src/math/CMakeLists.txt

@@ -65,6 +65,8 @@ add_library(
   praxis.h
   range.cpp
   range.h
+  rangedVector3.cpp
+  rangedVector3.h
   regression.cpp
   regression.h
   sampledData1D.cpp

src/math/rangedVector3.cpp

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (c) 2026 Team Dissolve and contributors
+
+#include "math/rangedVector3.h"
+
+RangedVector3::RangedVector3(const Vector3 &value) : value_(value) {}
+
+RangedVector3::RangedVector3(const Vector3 &value, std::optional<Vector3> min, std::optional<Vector3> max)
+    : min_(min), max_(max)
+{
+    set(value);
+}
+
+RangedVector3::operator Vector3() const { return value_; }
+
+/*
+ * Data
+ */
+
+// Impose limit on vector
+Vector3 RangedVector3::limit(const Vector3 &v) const
+{
+    Vector3 result = v;
+    if (hasLowerBound())
+    {
+        result.x = result.x < min_->x ? min_->x : result.x;
+        result.y = result.y < min_->y ? min_->y : result.y;
+        result.z = result.z < min_->z ? min_->z : result.z;
+    }
+    if (hasUpperBound())
+    {
+        result.x = result.x > max_->x ? max_->x : result.x;
+        result.y = result.y > max_->y ? max_->y : result.y;
+        result.z = result.z > max_->z ? max_->z : result.z;
+    }
+    return result;
+}
+
+// Set from vector
+void RangedVector3::set(const Vector3 &v) { value_ = limit(v); }
+
+// Return whether the number has lower bound
+bool RangedVector3::hasLowerBound() const { return min_.has_value(); }
+
+// Return whether the number has upper bound
+bool RangedVector3::hasUpperBound() const { return max_.has_value(); }
+
+// Return whether the number has bounds
+bool RangedVector3::isBounded() const { return hasLowerBound() && hasUpperBound(); }
+
+// Return optional min
+std::optional<Vector3> RangedVector3::min() const { return min_; }
+
+// Return optional max
+std::optional<Vector3> RangedVector3::max() const { return max_; }
+
+// Return x component of vector
+double RangedVector3::x() const { return value_.x; }
+
+// Return y component of vector
+double RangedVector3::y() const { return value_.y; }
+
+// Return z component of vector
+double RangedVector3::z() const { return value_.z; }
+
+// Return current value
+Vector3 RangedVector3::value() const { return value_; }
+
+/*
+ * Serialisable
+ */
+
+// Express as a serialisable value
+void RangedVector3::serialise(std::string tag, SerialisedValue &target) const { value_.serialise(tag, target); }
+
+// Read values from a serialisable value
+void RangedVector3::deserialise(const SerialisedValue &node) { value_.deserialise(node); }

src/math/rangedVector3.h

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (c) 2026 Team Dissolve and contributors
+
+#pragma once
+
+#include "base/serialiser.h"
+#include "math/vector3.h"
+#include <optional>
+
+// Ranged Vector3
+class RangedVector3 : public Serialisable<>
+{
+    public:
+    RangedVector3() = default;
+    RangedVector3(const Vector3 &value);
+    RangedVector3(const Vector3 &value, std::optional<Vector3> min, std::optional<Vector3> max = {});
+    ~RangedVector3() = default;
+    operator Vector3() const;
+
+    /*
+     * Data
+     */
+    protected:
+    // Value
+    Vector3 value_;
+    // Lower bound
+    std::optional<Vector3> min_;
+    // Upper bound
+    std::optional<Vector3> max_;
+
+    private:
+    // Impose limit on vector
+    Vector3 limit(const Vector3 &v) const;
+
+    public:
+    // Set from vector
+    void set(const Vector3 &v);
+    // Return whether the number has lower bound
+    bool hasLowerBound() const;
+    // Return whether the number has upper bound
+    bool hasUpperBound() const;
+    // Return whether the number has bounds
+    bool isBounded() const;
+    // Return optional min
+    std::optional<Vector3> min() const;
+    // Return optional max
+    std::optional<Vector3> max() const;
+    // Return x component of vector
+    double x() const;
+    // Return y component of vector
+    double y() const;
+    // Return z component of vector
+    double z() const;
+    // Return current value
+    Vector3 value() const;
+
+    /*
+     * Serialisable
+     */
+    public:
+    // Express as a serialisable value
+    void serialise(std::string tag, SerialisedValue &target) const override;
+    // Read values from a serialisable value
+    void deserialise(const SerialisedValue &node) override;
+};

tests/math/CMakeLists.txt

@@ -10,6 +10,7 @@ dissolve_add_test(SRC geometryMin.cpp)
 dissolve_add_test(SRC interpolator.cpp)
 dissolve_add_test(SRC peaks.cpp)
 dissolve_add_test(SRC polynomial.cpp)
+dissolve_add_test(SRC rangedVector3.cpp)
 dissolve_add_test(SRC sampledValues.cpp)
 dissolve_add_test(SRC svd.cpp)
 dissolve_add_test(SRC vector3.cpp)

tests/math/rangedVector3.cpp

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (c) 2026 Team Dissolve and contributors
+
+#include "math/rangedVector3.h"
+#include "tests/testData.h"
+#include <gtest/gtest.h>
+
+namespace UnitTest
+{
+TEST(RangedVector3Test, Construction)
+{
+    // No limiting
+    RangedVector3 v1({1.0, 2.0, 3.0});
+    EXPECT_DOUBLE_EQ(v1.x(), 1.0);
+    EXPECT_DOUBLE_EQ(v1.y(), 2.0);
+    EXPECT_DOUBLE_EQ(v1.z(), 3.0);
+
+    // Limiting on construction - minimum only
+    RangedVector3 v2({1.0, 2.0, 3.0}, Vector3{2.0, 0.0, 0.0});
+    EXPECT_DOUBLE_EQ(v2.x(), 2.0);
+    EXPECT_DOUBLE_EQ(v2.y(), 2.0);
+    EXPECT_DOUBLE_EQ(v2.z(), 3.0);
+
+    // Limiting on construction - minimum and maximum
+    RangedVector3 v3({1.0, 2.0, 3.0}, Vector3{2.0, 0.0, 0.0}, Vector3{10.0, 1.0, 0.0});
+    EXPECT_DOUBLE_EQ(v3.x(), 2.0);
+    EXPECT_DOUBLE_EQ(v3.y(), 1.0);
+    EXPECT_DOUBLE_EQ(v3.z(), 0.0);
+}
+
+TEST(RangedVector3Test, Set)
+{
+    RangedVector3 v({}, Vector3(-1.0, -2.0, -3.0), Vector3(1.0, 2.0, 3.0));
+    EXPECT_DOUBLE_EQ(v.x(), 0.0);
+    EXPECT_DOUBLE_EQ(v.y(), 0.0);
+    EXPECT_DOUBLE_EQ(v.z(), 0.0);
+
+    v.set({-3.0, -3.0, -3.0});
+    EXPECT_DOUBLE_EQ(v.x(), -1.0);
+    EXPECT_DOUBLE_EQ(v.y(), -2.0);
+    EXPECT_DOUBLE_EQ(v.z(), -3.0);
+
+    v.set({2.0, 1.0, 6.0});
+    EXPECT_DOUBLE_EQ(v.x(), 1.0);
+    EXPECT_DOUBLE_EQ(v.y(), 1.0);
+    EXPECT_DOUBLE_EQ(v.z(), 3.0);
+}
+} // namespace UnitTest