pymomentum-cpu 0.1.93.post0__cp312-cp312-macosx_14_0_arm64.whl

include/momentum/solver/solver.h

@@ -0,0 +1,155 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/math/types.h>
+#include <momentum/solver/fwd.h>
+
+#include <string>
+#include <unordered_map>
+
+namespace momentum {
+
+/// Common options for numerical optimization solvers.
+struct SolverOptions {
+  /// Minimum number of iterations before checking convergence criteria
+  size_t minIterations = 1;
+
+  /// Maximum number of iterations before terminating
+  size_t maxIterations = 2;
+
+  /// Convergence threshold for relative error change
+  float threshold = 1.0f;
+
+  /// Enable detailed logging during optimization
+  bool verbose = false;
+
+  /// Virtual destructor for polymorphic behavior
+  virtual ~SolverOptions() = default;
+};
+
+/// Base class for numerical optimization solvers.
+///
+/// Provides common functionality for iterative optimization algorithms
+/// including parameter management, convergence checking, and history tracking.
+template <typename T>
+class SolverT {
+ public:
+  /// Constructor with solver options and function to optimize
+  SolverT(const SolverOptions& options, SolverFunctionT<T>* solver);
+
+  virtual ~SolverT() = default;
+
+  /// Returns the name of the solver implementation
+  [[nodiscard]] virtual std::string_view getName() const = 0;
+
+  /// Updates solver configuration with new options
+  virtual void setOptions(const SolverOptions& options);
+
+  /// Solves the optimization problem
+  ///
+  /// @param[in,out] params Vector of initial guess, updated with the optimized solution
+  /// @return Final objective function value after optimization
+  double solve(Eigen::VectorX<T>& params);
+
+  /// Specifies which parameters should be optimized
+  ///
+  /// @param parameters Bitset where each bit indicates if the corresponding parameter is enabled
+  virtual void setEnabledParameters(const ParameterSet& parameters);
+
+  /// Returns the current set of enabled parameters
+  [[nodiscard]] const ParameterSet& getActiveParameters() const;
+
+  /// Sets the current parameter values without solving
+  void setParameters(const Eigen::VectorX<T>& params);
+
+  /// Controls whether to store iteration history for debugging and analysis
+  void setStoreHistory(bool b);
+
+  /// Returns the history of the solver's iterations
+  ///
+  /// The history contains matrices for parameters, errors, and other solver-specific data
+  [[nodiscard]] const std::unordered_map<std::string, Eigen::MatrixX<T>>& getHistory() const;
+
+  /// Returns the minimum number of iterations before checking convergence
+  [[nodiscard]] size_t getMinIterations() const;
+
+  /// Returns the maximum number of iterations before terminating
+  [[nodiscard]] size_t getMaxIterations() const;
+
+  [[nodiscard]] size_t getNumParameters() const {
+    return numParameters_;
+  }
+
+  /// Returns the history of objective function values over the iterations of the solve
+  [[nodiscard]] const std::vector<double>& getErrorHistory() const {
+    return errorHistory_;
+  }
+
+ protected:
+  /// Initializes solver state before optimization begins
+  virtual void initializeSolver() = 0;
+
+  /// Performs a single iteration of the optimization algorithm
+  virtual void doIteration() = 0;
+
+ protected:
+  /// Total number of parameters in the optimization problem
+  size_t numParameters_;
+
+  /// Function to be optimized
+  SolverFunctionT<T>* solverFunction_;
+
+  /// Current parameter values
+  Eigen::VectorX<T> parameters_;
+
+  /// Bitset indicating which parameters are enabled for optimization
+  ParameterSet activeParameters_;
+
+  /// Number of parameters currently enabled for optimization
+  int actualParameters_;
+
+  /// Flag indicating parameter structure has changed
+  ///
+  /// Used to trigger reinitialization of solver data structures
+  bool newParameterPattern_;
+
+  /// Current iteration count
+  size_t iteration_{};
+
+  /// Current objective function value
+  double error_{};
+
+  /// Previous iteration's objective function value
+  double lastError_{};
+
+  /// Whether to record optimization progress for analysis
+  bool storeHistory = false;
+
+  /// Recorded data from optimization process
+  ///
+  /// Contains matrices for parameters, errors, and other solver-specific data
+  std::unordered_map<std::string, Eigen::MatrixX<T>> iterationHistory_;
+  /// History of objective function values over the iterations
+  std::vector<double> errorHistory_;
+
+  /// Whether to output detailed progress information
+  bool verbose_ = false;
+
+ private:
+  /// Minimum iterations before checking convergence criteria
+  size_t minIterations_{};
+
+  /// Maximum iterations before terminating optimization
+  size_t maxIterations_{};
+
+  /// Relative error change threshold for convergence
+  float threshold_{};
+};
+
+} // namespace momentum

include/momentum/solver/solver_function.h

@@ -0,0 +1,126 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/math/types.h>
+#include <momentum/solver/fwd.h>
+
+#include <unordered_map>
+
+namespace momentum {
+
+/// Abstract base class for optimization objective functions
+///
+/// Provides the interface for computing objective function values, gradients,
+/// and other derivatives needed by numerical optimization algorithms.
+template <typename T>
+class SolverFunctionT {
+ public:
+  virtual ~SolverFunctionT() = default;
+
+  /// Evaluates the objective function at the given parameter values
+  ///
+  /// @param parameters Current parameter values
+  /// @return Objective function value (typically sum of squared errors)
+  virtual double getError(const VectorX<T>& parameters) = 0;
+
+  /// Computes the gradient of the objective function
+  ///
+  /// @param parameters Current parameter values
+  /// @param[out] gradient Computed gradient vector
+  /// @return Objective function value
+  virtual double getGradient(const VectorX<T>& parameters, VectorX<T>& gradient) = 0;
+
+  /// Computes the Jacobian matrix for least squares problems
+  ///
+  /// @param parameters Current parameter values
+  /// @param[out] jacobian Jacobian matrix (m×n for m residuals and n parameters)
+  /// @param[out] residual Vector of residual values
+  /// @param[out] actualRows Number of active residual rows
+  /// @return Objective function value
+  virtual double getJacobian(
+      const VectorX<T>& parameters,
+      MatrixX<T>& jacobian,
+      VectorX<T>& residual,
+      size_t& actualRows) = 0;
+
+  /// Computes the Hessian matrix of second derivatives
+  ///
+  /// Default implementation throws an exception as this is rarely needed
+  /// @param parameters Current parameter values
+  /// @param[out] hessian Computed Hessian matrix
+  virtual void getHessian(const VectorX<T>& parameters, MatrixX<T>& hessian);
+
+  /// Computes JᵀJ and JᵀR for Gauss-Newton optimization
+  ///
+  /// Default implementation computes these from the Jacobian
+  /// @param parameters Current parameter values
+  /// @param[out] jtj Approximated Hessian matrix (JᵀJ)
+  /// @param[out] jtr Gradient vector (JᵀR)
+  /// @return Objective function value
+  virtual double getJtJR(const VectorX<T>& parameters, MatrixX<T>& jtj, VectorX<T>& jtr);
+
+  /// Computes sparse JᵀJ and JᵀR for large-scale problems
+  ///
+  /// Default implementation returns 0.0 and must be overridden for sparse optimization
+  /// @param parameters Current parameter values
+  /// @param[out] jtj Sparse approximated Hessian matrix
+  /// @param[out] jtr Gradient vector
+  /// @return Objective function value
+  virtual double
+  getJtJR_Sparse(const VectorX<T>& parameters, SparseMatrix<T>& jtj, VectorX<T>& jtr);
+
+  /// Computes derivatives needed by the solver
+  ///
+  /// Default implementation calls getJtJR
+  /// @param parameters Current parameter values
+  /// @param[out] hess Hessian matrix or approximation
+  /// @param[out] grad Gradient vector
+  /// @return Objective function value
+  virtual double
+  getSolverDerivatives(const VectorX<T>& parameters, MatrixX<T>& hess, VectorX<T>& grad);
+
+  /// Updates parameters using the computed step direction
+  ///
+  /// @param[in,out] parameters Current parameters, updated in-place
+  /// @param gradient Step direction (typically the negative gradient)
+  virtual void updateParameters(VectorX<T>& parameters, const VectorX<T>& gradient) = 0;
+
+  /// Specifies which parameters should be optimized
+  ///
+  /// Default implementation does nothing
+  /// @param parameterSet Bitset where each bit indicates if the corresponding parameter is enabled
+  virtual void setEnabledParameters(const ParameterSet& parameterSet);
+
+  /// Returns the total number of parameters in the optimization problem
+  [[nodiscard]] size_t getNumParameters() const;
+
+  /// Returns the number of parameters currently enabled for optimization
+  [[nodiscard]] size_t getActualParameters() const;
+
+  /// Records solver state for debugging and analysis
+  ///
+  /// @param[in,out] history Map to store iteration data
+  /// @param iteration Current iteration number
+  /// @param maxIterations Maximum number of iterations
+  virtual void storeHistory(
+      std::unordered_map<std::string, MatrixX<T>>& history,
+      size_t iteration,
+      size_t maxIterations_);
+
+ protected:
+  /// Total number of parameters in the optimization problem
+  size_t numParameters_{};
+
+  /// Number of parameters currently enabled for optimization
+  ///
+  /// Always less than or equal to numParameters_
+  size_t actualParameters_{};
+};
+
+} // namespace momentum

include/momentum/solver/subset_gauss_newton_solver.h

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <momentum/solver/fwd.h>
+#include <momentum/solver/solver.h>
+
+namespace momentum {
+
+/// Extended options for the Subset Gauss-Newton optimization algorithm
+///
+/// Provides configuration specific to the subset-based Gauss-Newton solver
+/// that optimizes only a selected subset of parameters
+struct SubsetGaussNewtonSolverOptions : SolverOptions {
+  /// Damping parameter added to Hessian diagonal for numerical stability; see
+  /// https://en.wikipedia.org/wiki/Levenberg%E2%80%93Marquardt_algorithm
+  ///
+  /// Higher values improve stability but may slow convergence
+  float regularization = 0.05f;
+
+  /// Enables backtracking line search to ensure error reduction at each step
+  bool doLineSearch = false;
+
+  /// Default constructor
+  SubsetGaussNewtonSolverOptions() = default;
+
+  /// Construct from base solver options while preserving Subset Gauss-Newton defaults
+  /* implicit */ SubsetGaussNewtonSolverOptions(const SolverOptions& baseOptions)
+      : SolverOptions(baseOptions) {}
+};
+
+/// Gauss-Newton solver that optimizes only a selected subset of parameters
+///
+/// This specialized solver efficiently handles cases where only some parameters
+/// need to be optimized while others remain fixed. It remaps the active parameters
+/// to a smaller optimization problem, reducing computational cost.
+template <typename T>
+class SubsetGaussNewtonSolverT : public SolverT<T> {
+ public:
+  /// Creates a solver with the specified options and function to optimize
+  SubsetGaussNewtonSolverT(const SolverOptions& options, SolverFunctionT<T>* solver);
+
+  /// Returns "SubsetGaussNewton" as the solver name
+  [[nodiscard]] std::string_view getName() const override;
+
+  /// Updates solver configuration, handling both base and Subset Gauss-Newton specific options
+  void setOptions(const SolverOptions& options) final;
+
+  /// Specifies which parameters should be optimized
+  ///
+  /// Updates the internal mapping between full parameter space and optimization subset
+  void setEnabledParameters(const ParameterSet& parameters) final;
+
+ protected:
+  /// Performs one iteration of the Subset Gauss-Newton algorithm
+  ///
+  /// Computes the Jacobian, forms a reduced optimization problem for the enabled parameters,
+  /// solves it, and updates the full parameter vector
+  void doIteration() final;
+
+  /// Initializes solver state before optimization begins
+  void initializeSolver() final;
+
+ private:
+  /// Whether the solver has been initialized
+  bool initialized_{};
+
+  /// Jacobian matrix for the full parameter space
+  Eigen::MatrixX<T> jacobian_;
+
+  /// Residual vector
+  Eigen::VectorX<T> residual_;
+
+  /// Hessian approximation (JᵀJ) for the subset of enabled parameters
+  Eigen::MatrixX<T> subsetHessian_;
+
+  /// Gradient vector (JᵀR) for the subset of enabled parameters
+  Eigen::VectorX<T> subsetGradient_;
+
+  /// Cholesky factorization solver for the subset problem
+  Eigen::LLT<Eigen::MatrixX<T>> llt_;
+
+  /// Regularization parameter for numerical stability
+  float regularization_;
+
+  /// Whether to perform line search during parameter updates
+  bool doLineSearch_;
+
+  /// Step direction in the full parameter space
+  Eigen::VectorX<T> delta_;
+
+  /// Step direction in the reduced parameter space
+  Eigen::VectorX<T> subsetDelta_;
+
+  /// Mapping from subset parameter indices to full parameter indices
+  std::vector<int> enabledParameters_;
+
+  /// Updates the mapping between full and subset parameter spaces
+  ///
+  /// Called when the set of enabled parameters changes
+  void updateEnabledParameters();
+};
+
+} // namespace momentum

include/rerun/archetypes/annotation_context.hpp

@@ -0,0 +1,157 @@
+// DO NOT EDIT! This file was auto-generated by crates/build/re_types_builder/src/codegen/cpp/mod.rs
+// Based on "crates/store/re_types/definitions/rerun/archetypes/annotation_context.fbs".
+
+#pragma once
+
+#include "../collection.hpp"
+#include "../component_batch.hpp"
+#include "../component_column.hpp"
+#include "../components/annotation_context.hpp"
+#include "../indicator_component.hpp"
+#include "../result.hpp"
+
+#include <cstdint>
+#include <optional>
+#include <utility>
+#include <vector>
+
+namespace rerun::archetypes {
+    /// **Archetype**: The annotation context provides additional information on how to display entities.
+    ///
+    /// Entities can use `components::ClassId`s and `components::KeypointId`s to provide annotations, and
+    /// the labels and colors will be looked up in the appropriate
+    /// annotation context. We use the *first* annotation context we find in the
+    /// path-hierarchy when searching up through the ancestors of a given entity
+    /// path.
+    ///
+    /// See also `datatypes::ClassDescription`.
+    ///
+    /// ## Example
+    ///
+    /// ### Segmentation
+    /// ![image](https://static.rerun.io/annotation_context_segmentation/6c9e88fc9d44a08031cadd444c2e58a985cc1208/full.png)
+    ///
+    /// ```cpp
+    /// #include <rerun.hpp>
+    ///
+    /// #include <algorithm> // fill_n
+    /// #include <vector>
+    ///
+    /// int main() {
+    ///     const auto rec = rerun::RecordingStream("rerun_example_annotation_context_segmentation");
+    ///     rec.spawn().exit_on_failure();
+    ///
+    ///     // create an annotation context to describe the classes
+    ///     rec.log_static(
+    ///         "segmentation",
+    ///         rerun::AnnotationContext({
+    ///             rerun::AnnotationInfo(1, "red", rerun::Rgba32(255, 0, 0)),
+    ///             rerun::AnnotationInfo(2, "green", rerun::Rgba32(0, 255, 0)),
+    ///         })
+    ///     );
+    ///
+    ///     // create a segmentation image
+    ///     const int HEIGHT = 200;
+    ///     const int WIDTH = 300;
+    ///     std::vector<uint8_t> data(WIDTH * HEIGHT, 0);
+    ///     for (auto y = 50; y <100; ++y) {
+    ///         std::fill_n(data.begin() + y * WIDTH + 50, 70, static_cast<uint8_t>(1));
+    ///     }
+    ///     for (auto y = 100; y <180; ++y) {
+    ///         std::fill_n(data.begin() + y * WIDTH + 130, 150, static_cast<uint8_t>(2));
+    ///     }
+    ///
+    ///     rec.log("segmentation/image", rerun::SegmentationImage(data.data(), {WIDTH, HEIGHT}));
+    /// }
+    /// ```
+    ///
+    /// ⚠ **This type is _unstable_ and may change significantly in a way that the data won't be backwards compatible.**
+    ///
+    struct AnnotationContext {
+        /// List of class descriptions, mapping class indices to class names, colors etc.
+        std::optional<ComponentBatch> context;
+
+      public:
+        static constexpr const char IndicatorComponentName[] =
+            "rerun.components.AnnotationContextIndicator";
+
+        /// Indicator component, used to identify the archetype when converting to a list of components.
+        using IndicatorComponent = rerun::components::IndicatorComponent<IndicatorComponentName>;
+        /// The name of the archetype as used in `ComponentDescriptor`s.
+        static constexpr const char ArchetypeName[] = "rerun.archetypes.AnnotationContext";
+
+        /// `ComponentDescriptor` for the `context` field.
+        static constexpr auto Descriptor_context = ComponentDescriptor(
+            ArchetypeName, "context",
+            Loggable<rerun::components::AnnotationContext>::Descriptor.component_name
+        );
+
+      public:
+        AnnotationContext() = default;
+        AnnotationContext(AnnotationContext&& other) = default;
+        AnnotationContext(const AnnotationContext& other) = default;
+        AnnotationContext& operator=(const AnnotationContext& other) = default;
+        AnnotationContext& operator=(AnnotationContext&& other) = default;
+
+        explicit AnnotationContext(rerun::components::AnnotationContext _context)
+            : context(ComponentBatch::from_loggable(std::move(_context), Descriptor_context)
+                          .value_or_throw()) {}
+
+        /// Update only some specific fields of a `AnnotationContext`.
+        static AnnotationContext update_fields() {
+            return AnnotationContext();
+        }
+
+        /// Clear all the fields of a `AnnotationContext`.
+        static AnnotationContext clear_fields();
+
+        /// List of class descriptions, mapping class indices to class names, colors etc.
+        AnnotationContext with_context(const rerun::components::AnnotationContext& _context) && {
+            context = ComponentBatch::from_loggable(_context, Descriptor_context).value_or_throw();
+            return std::move(*this);
+        }
+
+        /// This method makes it possible to pack multiple `context` in a single component batch.
+        ///
+        /// This only makes sense when used in conjunction with `columns`. `with_context` should
+        /// be used when logging a single row's worth of data.
+        AnnotationContext with_many_context(
+            const Collection<rerun::components::AnnotationContext>& _context
+        ) && {
+            context = ComponentBatch::from_loggable(_context, Descriptor_context).value_or_throw();
+            return std::move(*this);
+        }
+
+        /// Partitions the component data into multiple sub-batches.
+        ///
+        /// Specifically, this transforms the existing `ComponentBatch` data into `ComponentColumn`s
+        /// instead, via `ComponentBatch::partitioned`.
+        ///
+        /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
+        ///
+        /// The specified `lengths` must sum to the total length of the component batch.
+        Collection<ComponentColumn> columns(const Collection<uint32_t>& lengths_);
+
+        /// Partitions the component data into unit-length sub-batches.
+        ///
+        /// This is semantically similar to calling `columns` with `std::vector<uint32_t>(n, 1)`,
+        /// where `n` is automatically guessed.
+        Collection<ComponentColumn> columns();
+    };
+
+} // namespace rerun::archetypes
+
+namespace rerun {
+    /// \private
+    template <typename T>
+    struct AsComponents;
+
+    /// \private
+    template <>
+    struct AsComponents<archetypes::AnnotationContext> {
+        /// Serialize all set component batches.
+        static Result<Collection<ComponentBatch>> as_batches(
+            const archetypes::AnnotationContext& archetype
+        );
+    };
+} // namespace rerun