Added TIntegrator

feat: Add TIntegrator class for numerical integration

- Introduced TIntegrator class to perform numerical integration on a signal line.
- Supports three integration methods:
  - Trapezoidal (default)
  - Simpson
  - Boole

docs:
- Updated Doxygen comments for better clarity and completeness.

Author: ilvoron

.clang-tidy

@@ -12,6 +12,14 @@ Checks: >
 CheckOptions:
     - key: bugprone-reserved-identifier.AllowedIdentifiers
       value: '_USE_MATH_DEFINES'
+    - key: readability-magic-numbers.IgnoredFloatingPointValues
+      value: '1.0;100.0;2.0;6.0;90.0'
+    - key: cppcoreguidelines-avoid-magic-numbers.IgnoredFloatingPointValues
+      value: '1.0;100.0;2.0;6.0;90.0'
+    - key: readability-magic-numbers.IgnoredIntegerValues
+      value: '1;2;3;4;7;12;32'
+    - key: cppcoreguidelines-avoid-magic-numbers.IgnoredIntegerValues
+      value: '1;2;3;4;7;12;32'
 
 WarningsAsErrors: 'bugprone-*,performance-*'
 HeaderFilterRegex: 'src/*.*'

src/core/TCore.h

@@ -8,7 +8,8 @@
  * TODO: [GLOBAL] ??? Investigate adding asynchronous computation ???
  * TODO: [GLOBAL] ??? Investigate adding interfaces for signal processing ???
  * TODO: [GLOBAL] Validate @throws tags in the documentation
- * ? Consider using "std::optional" for optional parameters
+ * ? Consider using "std::optional" for optional parameters ?
+ * ? use ++i instead of i++ in for loops ?
  */
 
 #pragma once

src/core/TSignalLine.h

@@ -7,6 +7,7 @@
  * TODO: ??? Add generation inside the signal line ???
  * !TODO: ??? Make a class for Point ???
  * TODO: Add push/pop point method
+ * !TODO: Make it get only x or y coordinates vector
  */
 
 #pragma once
@@ -46,6 +47,7 @@ static const std::string DEFAULT_GRAPH_LABEL =
 }  // namespace SL
 
 /**
+ * @struct Point
  * @brief Represents a 2D point with x and y coordinates.
  */
 struct Point {
@@ -54,6 +56,7 @@ struct Point {
 };
 
 /**
+ * @struct TSignalLineParams
  * @brief Contains parameters used for describing a signal line.
  */
 struct TSignalLineParams {

src/gen/TGenerator.h

@@ -19,6 +19,7 @@ static const std::string DEFAULT_GRAPH_LABEL =
 }  // namespace GEN
 
 /**
+ * @struct TGeneratorParams
  * @brief Parameters for generating a signal line.
  */
 struct TGeneratorParams {

src/io/TFileWriter.h

@@ -10,6 +10,7 @@
 #include <string>
 
 /**
+ * @struct TFileWriterParams
  * @brief Parameters for writing a signal line to a file.
  */
 struct TFileWriterParams {

src/io/TGnuPlotViewer.h

@@ -16,6 +16,7 @@
 #include <string>
 
 /**
+ * @struct TGnuPlotViewerParams
  * @brief Parameters for configuring the GnuPlot viewer.
  */
 struct TGnuPlotViewerParams {

src/proc/TDifferentiator.cpp

@@ -37,6 +37,9 @@ bool TDifferentiator::isExecuted() const {
   return _isExecuted;
 }
 
+// TODO: Move differentiation logic to a separate method for each
+// differentiation method
+// TODO: Add switch-case for each differentiation method
 void TDifferentiator::execute() {
   if (_params.signalLine == nullptr) {
     throw SignalProcesserException("Invalid signal line (nullptr)");

src/proc/TDifferentiator.h

@@ -44,6 +44,7 @@ enum class DifferentiationMethod : std::uint8_t {
 };
 
 /**
+ * @struct TDifferentiatorParams
  * @brief Parameters for differentiating a signal line.
  */
 struct TDifferentiatorParams {

src/proc/TIntegrator.cpp

@@ -0,0 +1,95 @@
+#include "TIntegrator.h"
+#include <cstddef>
+#include "TCore.h"
+#include "TSignalLine.h"
+
+/**
+ ** PUBLIC METHODS
+ */
+
+TIntegrator::TIntegrator(const TSignalLine* signalLine,
+                         IntegrationMethod method)
+    : _params{signalLine, method} {}
+
+TIntegrator::TIntegrator(TIntegratorParams params) : _params(params) {}
+
+double TIntegrator::getIntegral() const {
+  if (!_isExecuted) {
+    throw SignalProcesserException("Integrator not executed");
+  }
+  return _integral;
+}
+
+const TIntegratorParams& TIntegrator::getParams() const {
+  return _params;
+}
+
+bool TIntegrator::isExecuted() const {
+  return _isExecuted;
+}
+
+// TODO: Move integration logic to a separate method for each integration method
+void TIntegrator::execute() {
+  if (_params.signalLine == nullptr) {
+    throw SignalProcesserException("Invalid signal line (nullptr)");
+  }
+  if (_params.signalLine->getParams().pointsCount < 2) {
+    throw SignalProcesserException(
+        "Insufficient number of points: at least 2 points are required");
+  }
+
+  const std::size_t pointsCount = _params.signalLine->getParams().pointsCount;
+  _integral = 0.0;
+
+  switch (_params.method) {
+    case IntegrationMethod::Trapezoidal:
+      for (size_t i = 1; i < pointsCount; ++i) {
+        const double xCoordBefore = _params.signalLine->getPoint(i - 1).x;
+        const double xCoord = _params.signalLine->getPoint(i).x;
+        const double yCoordBefore = _params.signalLine->getPoint(i - 1).y;
+        const double yCoord = _params.signalLine->getPoint(i).y;
+        _integral += (yCoordBefore + yCoord) / 2.0 * (xCoord - xCoordBefore);
+      }
+      break;
+
+    case IntegrationMethod::Simpson:
+      if (pointsCount % 2 == 0) {
+        throw SignalProcesserException(
+            "Simpson's rule requires an odd number of points");
+      }
+      for (size_t i = 1; i < pointsCount - 1; i += 2) {
+        const double xCoordBefore = _params.signalLine->getPoint(i - 1).x;
+        const double xCoordNext = _params.signalLine->getPoint(i + 1).x;
+        const double yCoordBefore = _params.signalLine->getPoint(i - 1).y;
+        const double yCoord = _params.signalLine->getPoint(i).y;
+        const double yCoordNext = _params.signalLine->getPoint(i + 1).y;
+        _integral += (xCoordNext - xCoordBefore) / 6.0 *
+                     (yCoordBefore + 4 * yCoord + yCoordNext);
+      }
+      break;
+
+    case IntegrationMethod::Boole:
+      if (pointsCount % 4 != 1) {
+        throw SignalProcesserException(
+            "Boole's rule requires number of points to be 4k + 1");
+      }
+      for (size_t i = 0; i < pointsCount - 4; i += 4) {
+        const double xCoord = _params.signalLine->getPoint(i).x;
+        const double xCoordNext4 = _params.signalLine->getPoint(i + 4).x;
+        const double yCoord = _params.signalLine->getPoint(i).y;
+        const double yCoordNext1 = _params.signalLine->getPoint(i + 1).y;
+        const double yCoordNext2 = _params.signalLine->getPoint(i + 2).y;
+        const double yCoordNext3 = _params.signalLine->getPoint(i + 3).y;
+        const double yCoordNext4 = _params.signalLine->getPoint(i + 4).y;
+        _integral += (xCoordNext4 - xCoord) / 90.0 *
+                     (7 * yCoord + 32 * yCoordNext1 + 12 * yCoordNext2 +
+                      32 * yCoordNext3 + 7 * yCoordNext4);
+      }
+      break;
+
+    default:
+      throw SignalProcesserException("Unknown integration method");
+  }
+
+  _isExecuted = true;
+}

src/proc/TIntegrator.h

@@ -0,0 +1,137 @@
+#pragma once
+
+#include "TSignalLine.h"
+
+#include <cstdint>
+
+/**
+ * @enum IntegrationMethod
+ * @brief Specifies the available methods for numerical integration.
+ *
+ * This enumeration defines several methods for performing numerical
+ * integration:
+ *
+ * - `Trapezoidal`:
+ *   This method uses the trapezoidal rule for numerical integration. It
+ * approximates the area under the curve by dividing the curve into trapezoids.
+ * This method requires at least two points for computation and works well for
+ * functions that are linear or approximately linear between points. The
+ * trapezoidal rule calculates the area of each trapezoid and sums them up.
+ *   - Minimum points required: 2.
+ *
+ * - `Simpson`:
+ *   This method uses Simpson's rule, which is based on approximating the
+ * function by a quadratic polynomial on each segment. It requires an odd number
+ * of points (at least 3) because it calculates the area using pairs of
+ * intervals, forming parabolic segments that give a higher level of accuracy
+ * than the trapezoidal rule for smooth functions.
+ *   - Minimum points required: 3 (must be an odd number).
+ *
+ * - `Boole`:
+ *   This method uses Boole's rule (also known as the fifth-degree polynomial
+ * rule), which is a higher-order numerical integration method. It approximates
+ * the function using a polynomial of degree 5 on each segment. Boole's rule
+ * requires that the number of points satisfies the condition \(4k + 1\),
+ * meaning the number of points must be equal to 5, 9, 13, etc.
+ *   - Minimum points required: 5 (must satisfy \(4k + 1\) condition).
+ */
+enum class IntegrationMethod : std::uint8_t {
+  Trapezoidal,  ///< Trapezoidal rule (requires at least 2 points).
+  Simpson,  ///< Simpson's rule (requires at least 3 points, and the number must
+            ///< be odd).
+  Boole     ///< Boole's rule (requires at least 5 points, and the number must
+            ///< satisfy 4k + 1).
+};
+
+/**
+ * @struct TIntegratorParams
+ * @brief Defines the parameters used for numerical integration.
+ */
+struct TIntegratorParams {
+  const TSignalLine* signalLine =
+      nullptr;  ///< Pointer to the signal line to be integrated.
+  IntegrationMethod method =
+      IntegrationMethod::Trapezoidal;  ///< (optional) Integration method.
+};
+
+/**
+ * @class TIntegrator
+ * @brief Class for performing numerical integration on a signal line.
+ */
+class TIntegrator {
+ public:
+  /**
+   * @brief Constructs a TIntegrator with a signal line and an integration
+   * method.
+   *
+   * @param signalLine Pointer to the signal line to integrate.
+   * @param method (optional) The method to use for integration.
+   */
+  TIntegrator(const TSignalLine* signalLine,
+              IntegrationMethod method = IntegrationMethod::Trapezoidal);
+
+  /**
+   * @brief Constructs a TIntegrator with integration parameters.
+   *
+   * @param params Structure containing the parameters for signal integration.
+   */
+  TIntegrator(TIntegratorParams params);
+
+  /**
+   * @brief Default destructor.
+   */
+  ~TIntegrator() = default;
+
+  /**
+   * @brief Default copy constructor.
+   */
+  TIntegrator(const TIntegrator&) = default;
+
+  /**
+   * @brief Default move constructor.
+   */
+  TIntegrator(TIntegrator&&) noexcept = default;
+
+  /**
+   * @brief Default copy assignment operator.
+   */
+  TIntegrator& operator=(const TIntegrator&) = default;
+
+  /**
+   * @brief Default move assignment operator.
+   */
+  TIntegrator& operator=(TIntegrator&&) noexcept = default;
+
+  /**
+   * @brief Retrieves the computed integral.
+   *
+   * @return double The result of the numerical integration.
+   */
+  [[nodiscard]] double getIntegral() const;
+
+  /**
+   * @brief Retrieves the parameters used for integration.
+   *
+   * @return const TIntegratorParams& Reference to the integration parameters.
+   */
+  [[nodiscard]] const TIntegratorParams& getParams() const;
+
+  /**
+   * @brief Checks whether the integration has been executed.
+   *
+   * @return bool True if the integration process has been executed, false
+   * otherwise.
+   */
+  [[nodiscard]] bool isExecuted() const;
+
+  /**
+   * @brief Executes the numerical integration of the signal line.
+   */
+  void execute();
+
+ private:
+  double _integral = 0.0;          ///< Stores the computed integral value.
+  TIntegratorParams _params = {};  ///< Parameters for integration.
+  bool _isExecuted =
+      false;  ///< Indicates if the integration has been executed.
+};