Docs for basis

gtsam/basis/basis.md

@@ -0,0 +1,66 @@
+# Basis
+
+The `basis` module provides tools for representing continuous functions as
+linear combinations of basis functions or as values at interpolation points.
+It is useful for smooth function approximation, trajectory modeling, and
+building factors that constrain functions (or their derivatives) at specific
+points.
+
+At a high level, you choose a basis (Fourier or Chebyshev), decide whether you
+want a coefficient-based representation or a pseudo-spectral one (values at
+Chebyshev points), and then use the provided factors or fitting utilities to
+solve for parameters in GTSAM.
+
+## Getting Oriented
+
+- **Coefficient-based bases**: `Chebyshev1Basis`, `Chebyshev2Basis`, and
+  `FourierBasis` treat the parameters as coefficients on basis functions.
+- **Pseudo-spectral basis**: `Chebyshev2` treats the parameters as values at
+  Chebyshev points and uses barycentric interpolation.
+- **Factors**: A family of unary factors enforce function values or derivatives
+  at specific points, including vector- and manifold-valued variants.
+- **Fitting**: `FitBasis` performs least-squares regression from samples.
+
+## Core Concepts
+
+- [Basis](doc/Basis.ipynb): CRTP base class providing evaluation and derivative
+  functors, Jacobians, and common helpers.
+
+## Polynomial Bases
+
+- [Chebyshev1Basis](doc/Chebyshev1Basis.ipynb): First-kind Chebyshev basis
+  $T_n(x)$ on $[-1,1]$ (coefficient-based).
+- [Chebyshev2Basis](doc/Chebyshev2Basis.ipynb): Second-kind Chebyshev basis
+  $U_n(x)$ on $[-1,1]$ (coefficient-based).
+- [FourierBasis](doc/FourierBasis.ipynb): Real Fourier series basis for
+  periodic functions.
+
+## Pseudo-Spectral Basis
+
+- [Chebyshev2](doc/Chebyshev2.ipynb): Chebyshev points, barycentric
+  interpolation, differentiation/integration matrices, and quadrature weights.
+
+## Factors for Basis Evaluation
+
+These factors connect basis parameters to measurements of values or derivatives.
+
+- [EvaluationFactor](doc/EvaluationFactor.ipynb): Scalar value at a point.
+- [VectorEvaluationFactor](doc/VectorEvaluationFactor.ipynb): Vector value at a
+  point.
+- [VectorComponentFactor](doc/VectorComponentFactor.ipynb): Single component of
+  a vector value.
+- [ManifoldEvaluationFactor](doc/ManifoldEvaluationFactor.ipynb): Manifold-valued
+  measurement (e.g., `Rot3`, `Pose3`).
+
+## Factors for Derivative Constraints
+
+- [DerivativeFactor](doc/DerivativeFactor.ipynb): Scalar derivative at a point.
+- [VectorDerivativeFactor](doc/VectorDerivativeFactor.ipynb): Vector derivative
+  at a point.
+- [ComponentDerivativeFactor](doc/ComponentDerivativeFactor.ipynb): Single
+  component of a vector derivative.
+
+## Fitting from Data
+
+- [FitBasis](doc/FitBasis.ipynb): Build a least-squares problem from samples and
+  solve for basis parameters.

gtsam/basis/doc/Basis.ipynb

@@ -0,0 +1,155 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Basis\n",
+        "\n",
+        "<a href=\"https://colab.research.google.com/github/borglab/gtsam/blob/develop/gtsam/basis/doc/Basis.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>\n",
+        "\n",
+        "## Overview\n",
+        "\n",
+        "The `Basis` class is a CRTP base class that defines common utilities for representing functions as linear combinations of basis functions. Derived classes provide `CalculateWeights` and `DerivativeWeights`, while `Basis` supplies functors and helpers for evaluation, vector-valued evaluation, and derivative computation with Jacobians with respect to parameters.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "tags": [
+          "remove-cell"
+        ]
+      },
+      "source": [
+        "GTSAM Copyright 2010-2022, Georgia Tech Research Corporation,\n",
+        "Atlanta, Georgia 30332-0415\n",
+        "All Rights Reserved\n",
+        "\n",
+        "Authors: Frank Dellaert, et al. (see THANKS for the full author list)\n",
+        "\n",
+        "See LICENSE for the license information\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 4,
+      "id": "6775be6c",
+      "metadata": {
+        "tags": [
+          "remove-cell"
+        ]
+      },
+      "outputs": [],
+      "source": [
+        "# Install GTSAM from pip if running in Google Colab\n",
+        "try:\n",
+        "    import google.colab\n",
+        "    %pip install --quiet gtsam-develop\n",
+        "except ImportError:\n",
+        "    pass  # Not in Colab\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "ce1fbbd5",
+      "metadata": {},
+      "source": [
+        "## Key Functionality / API\n",
+        "\n",
+        "- `WeightMatrix(N, X)` and `WeightMatrix(N, X, a, b)` build stacked weight matrices.\n",
+        "- `EvaluationFunctor` evaluates a scalar function at `x`.\n",
+        "- `VectorEvaluationFunctor` evaluates vector-valued functions from a parameter matrix.\n",
+        "- `VectorComponentFunctor` evaluates a single component of a vector-valued function.\n",
+        "- `ManifoldEvaluationFunctor` evaluates manifold-valued functions via local coordinates.\n",
+        "- `DerivativeFunctor`, `VectorDerivativeFunctor`, and `ComponentDerivativeFunctor` compute derivatives.\n",
+        "- `kroneckerProductIdentity` builds efficient block Jacobians for vector-valued cases.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "46f84e69",
+      "metadata": {},
+      "source": [
+        "## Derived Classes\n",
+        "\n",
+        "- `Chebyshev1Basis` (first-kind Chebyshev polynomials)\n",
+        "- `Chebyshev2Basis` (second-kind Chebyshev polynomials)\n",
+        "- `FourierBasis` (real Fourier series)\n",
+        "- `Chebyshev2` (pseudo-spectral Chebyshev points)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "c8e177a8",
+      "metadata": {},
+      "source": [
+        "## Usage Example\n",
+        "\n",
+        "This example builds a weight matrix for a Chebyshev basis and evaluates\n",
+        "Fourier weights at a point.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 5,
+      "id": "905a64a4",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Chebyshev2 WeightMatrix shape: (5, 5)\n",
+            "First row: [1. 0. 0. 0. 0.]\n",
+            "FourierBasis weights at x=0.3: [1.    0.955 0.296 0.825 0.565]\n"
+          ]
+        }
+      ],
+      "source": [
+        "import numpy as np\n",
+        "import gtsam\n",
+        "\n",
+        "np.set_printoptions(precision=3, suppress=True)\n",
+        "\n",
+        "N = 5\n",
+        "X = np.linspace(-1.0, 1.0, 5)\n",
+        "W = gtsam.Chebyshev2.WeightMatrix(N, X)\n",
+        "print(\"Chebyshev2 WeightMatrix shape:\", np.asarray(W).shape)\n",
+        "print(\"First row:\", np.asarray(W)[0])\n",
+        "\n",
+        "x = 0.3\n",
+        "weights = gtsam.FourierBasis.CalculateWeights(N, x)\n",
+        "print(\"FourierBasis weights at x=0.3:\", np.asarray(weights).ravel())\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Source\n",
+        "- [Basis.h](https://github.com/borglab/gtsam/blob/develop/gtsam/basis/Basis.h)\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "py312",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.12.6"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

gtsam/basis/doc/Chebyshev1Basis.ipynb

@@ -0,0 +1,136 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Chebyshev1Basis\n",
+        "\n",
+        "<a href=\"https://colab.research.google.com/github/borglab/gtsam/blob/develop/gtsam/basis/doc/Chebyshev1Basis.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>\n",
+        "\n",
+        "## Overview\n",
+        "\n",
+        "`Chebyshev1Basis` provides the first-kind Chebyshev polynomial basis $T_n(x)$ on the interval $[-1, 1]$. Parameters are coefficients of the basis functions, making this a classic orthogonal polynomial expansion for smooth function approximation.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "tags": [
+          "remove-cell"
+        ]
+      },
+      "source": [
+        "GTSAM Copyright 2010-2022, Georgia Tech Research Corporation,\n",
+        "Atlanta, Georgia 30332-0415\n",
+        "All Rights Reserved\n",
+        "\n",
+        "Authors: Frank Dellaert, et al. (see THANKS for the full author list)\n",
+        "\n",
+        "See LICENSE for the license information\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "metadata": {
+        "tags": [
+          "remove-cell"
+        ]
+      },
+      "outputs": [],
+      "source": [
+        "# Install GTSAM from pip if running in Google Colab\n",
+        "try:\n",
+        "    import google.colab\n",
+        "    %pip install --quiet gtsam-develop\n",
+        "except ImportError:\n",
+        "    pass  # Not in Colab\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Key Functionality / API\n",
+        "\n",
+        "- `CalculateWeights(N, x, a=-1, b=1)` returns the $1 \t\\times N$ basis weights.\n",
+        "- `DerivativeWeights(N, x, a=-1, b=1)` returns weights for the derivative.\n",
+        "- `WeightMatrix(N, X)` stacks weights for a vector of sample points.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "922e3685",
+      "metadata": {},
+      "source": [
+        "## Usage Example\n",
+        "\n",
+        "Evaluate first-kind Chebyshev weights at a point and build a weight\n",
+        "matrix for multiple sample points.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 2,
+      "id": "30b37cbb",
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Weights at x=0.25: [ 1.     0.25  -0.875 -0.688  0.531  0.953]\n",
+            "WeightMatrix shape: (5, 6)\n",
+            "Row for x=0: [ 1.  0. -1. -0.  1.  0.]\n"
+          ]
+        }
+      ],
+      "source": [
+        "import numpy as np\n",
+        "import gtsam\n",
+        "\n",
+        "np.set_printoptions(precision=3, suppress=True)\n",
+        "\n",
+        "N = 6\n",
+        "x = 0.25\n",
+        "weights = gtsam.Chebyshev1Basis.CalculateWeights(N, x)\n",
+        "print(\"Weights at x=0.25:\", np.asarray(weights).ravel())\n",
+        "\n",
+        "X = np.linspace(-1.0, 1.0, 5)\n",
+        "W = gtsam.Chebyshev1Basis.WeightMatrix(N, X)\n",
+        "print(\"WeightMatrix shape:\", np.asarray(W).shape)\n",
+        "print(\"Row for x=0:\", np.asarray(W)[2])\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Source\n",
+        "- [Chebyshev.h](https://github.com/borglab/gtsam/blob/develop/gtsam/basis/Chebyshev.h)\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "py312",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.12.6"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}