Skip to content

Commit aed1715

Browse files
dellaertdellaert
authored
Merge pull request #2375 from borglab/doc/basis
Docs for basis
2 parents 9f65ed7 + 1e32c74 commit aed1715

17 files changed

+5672
-14
lines changed

‎gtsam/basis/basis.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Basis
2+
3+
The `basis` module provides tools for representing continuous functions as
4+
linear combinations of basis functions or as values at interpolation points.
5+
It is useful for smooth function approximation, trajectory modeling, and
6+
building factors that constrain functions (or their derivatives) at specific
7+
points.
8+
9+
At a high level, you choose a basis (Fourier or Chebyshev), decide whether you
10+
want a coefficient-based representation or a pseudo-spectral one (values at
11+
Chebyshev points), and then use the provided factors or fitting utilities to
12+
solve for parameters in GTSAM.
13+
14+
## Getting Oriented
15+
16+
- **Coefficient-based bases**: `Chebyshev1Basis`, `Chebyshev2Basis`, and
17+
`FourierBasis` treat the parameters as coefficients on basis functions.
18+
- **Pseudo-spectral basis**: `Chebyshev2` treats the parameters as values at
19+
Chebyshev points and uses barycentric interpolation.
20+
- **Factors**: A family of unary factors enforce function values or derivatives
21+
at specific points, including vector- and manifold-valued variants.
22+
- **Fitting**: `FitBasis` performs least-squares regression from samples.
23+
24+
## Core Concepts
25+
26+
- [Basis](doc/Basis.ipynb): CRTP base class providing evaluation and derivative
27+
functors, Jacobians, and common helpers.
28+
29+
## Polynomial Bases
30+
31+
- [Chebyshev1Basis](doc/Chebyshev1Basis.ipynb): First-kind Chebyshev basis
32+
$T_n(x)$ on $[-1,1]$ (coefficient-based).
33+
- [Chebyshev2Basis](doc/Chebyshev2Basis.ipynb): Second-kind Chebyshev basis
34+
$U_n(x)$ on $[-1,1]$ (coefficient-based).
35+
- [FourierBasis](doc/FourierBasis.ipynb): Real Fourier series basis for
36+
periodic functions.
37+
38+
## Pseudo-Spectral Basis
39+
40+
- [Chebyshev2](doc/Chebyshev2.ipynb): Chebyshev points, barycentric
41+
interpolation, differentiation/integration matrices, and quadrature weights.
42+
43+
## Factors for Basis Evaluation
44+
45+
These factors connect basis parameters to measurements of values or derivatives.
46+
47+
- [EvaluationFactor](doc/EvaluationFactor.ipynb): Scalar value at a point.
48+
- [VectorEvaluationFactor](doc/VectorEvaluationFactor.ipynb): Vector value at a
49+
point.
50+
- [VectorComponentFactor](doc/VectorComponentFactor.ipynb): Single component of
51+
a vector value.
52+
- [ManifoldEvaluationFactor](doc/ManifoldEvaluationFactor.ipynb): Manifold-valued
53+
measurement (e.g., `Rot3`, `Pose3`).
54+
55+
## Factors for Derivative Constraints
56+
57+
- [DerivativeFactor](doc/DerivativeFactor.ipynb): Scalar derivative at a point.
58+
- [VectorDerivativeFactor](doc/VectorDerivativeFactor.ipynb): Vector derivative
59+
at a point.
60+
- [ComponentDerivativeFactor](doc/ComponentDerivativeFactor.ipynb): Single
61+
component of a vector derivative.
62+
63+
## Fitting from Data
64+
65+
- [FitBasis](doc/FitBasis.ipynb): Build a least-squares problem from samples and
66+
solve for basis parameters.

‎gtsam/basis/doc/Basis.ipynb‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Basis\n",
8+
"\n",
9+
"<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",
10+
"\n",
11+
"## Overview\n",
12+
"\n",
13+
"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"
14+
]
15+
},
16+
{
17+
"cell_type": "markdown",
18+
"metadata": {
19+
"tags": [
20+
"remove-cell"
21+
]
22+
},
23+
"source": [
24+
"GTSAM Copyright 2010-2022, Georgia Tech Research Corporation,\n",
25+
"Atlanta, Georgia 30332-0415\n",
26+
"All Rights Reserved\n",
27+
"\n",
28+
"Authors: Frank Dellaert, et al. (see THANKS for the full author list)\n",
29+
"\n",
30+
"See LICENSE for the license information\n"
31+
]
32+
},
33+
{
34+
"cell_type": "code",
35+
"execution_count": 4,
36+
"id": "6775be6c",
37+
"metadata": {
38+
"tags": [
39+
"remove-cell"
40+
]
41+
},
42+
"outputs": [],
43+
"source": [
44+
"# Install GTSAM from pip if running in Google Colab\n",
45+
"try:\n",
46+
" import google.colab\n",
47+
" %pip install --quiet gtsam-develop\n",
48+
"except ImportError:\n",
49+
" pass # Not in Colab\n"
50+
]
51+
},
52+
{
53+
"cell_type": "markdown",
54+
"id": "ce1fbbd5",
55+
"metadata": {},
56+
"source": [
57+
"## Key Functionality / API\n",
58+
"\n",
59+
"- `WeightMatrix(N, X)` and `WeightMatrix(N, X, a, b)` build stacked weight matrices.\n",
60+
"- `EvaluationFunctor` evaluates a scalar function at `x`.\n",
61+
"- `VectorEvaluationFunctor` evaluates vector-valued functions from a parameter matrix.\n",
62+
"- `VectorComponentFunctor` evaluates a single component of a vector-valued function.\n",
63+
"- `ManifoldEvaluationFunctor` evaluates manifold-valued functions via local coordinates.\n",
64+
"- `DerivativeFunctor`, `VectorDerivativeFunctor`, and `ComponentDerivativeFunctor` compute derivatives.\n",
65+
"- `kroneckerProductIdentity` builds efficient block Jacobians for vector-valued cases.\n"
66+
]
67+
},
68+
{
69+
"cell_type": "markdown",
70+
"id": "46f84e69",
71+
"metadata": {},
72+
"source": [
73+
"## Derived Classes\n",
74+
"\n",
75+
"- `Chebyshev1Basis` (first-kind Chebyshev polynomials)\n",
76+
"- `Chebyshev2Basis` (second-kind Chebyshev polynomials)\n",
77+
"- `FourierBasis` (real Fourier series)\n",
78+
"- `Chebyshev2` (pseudo-spectral Chebyshev points)\n"
79+
]
80+
},
81+
{
82+
"cell_type": "markdown",
83+
"id": "c8e177a8",
84+
"metadata": {},
85+
"source": [
86+
"## Usage Example\n",
87+
"\n",
88+
"This example builds a weight matrix for a Chebyshev basis and evaluates\n",
89+
"Fourier weights at a point.\n"
90+
]
91+
},
92+
{
93+
"cell_type": "code",
94+
"execution_count": 5,
95+
"id": "905a64a4",
96+
"metadata": {},
97+
"outputs": [
98+
{
99+
"name": "stdout",
100+
"output_type": "stream",
101+
"text": [
102+
"Chebyshev2 WeightMatrix shape: (5, 5)\n",
103+
"First row: [1. 0. 0. 0. 0.]\n",
104+
"FourierBasis weights at x=0.3: [1. 0.955 0.296 0.825 0.565]\n"
105+
]
106+
}
107+
],
108+
"source": [
109+
"import numpy as np\n",
110+
"import gtsam\n",
111+
"\n",
112+
"np.set_printoptions(precision=3, suppress=True)\n",
113+
"\n",
114+
"N = 5\n",
115+
"X = np.linspace(-1.0, 1.0, 5)\n",
116+
"W = gtsam.Chebyshev2.WeightMatrix(N, X)\n",
117+
"print(\"Chebyshev2 WeightMatrix shape:\", np.asarray(W).shape)\n",
118+
"print(\"First row:\", np.asarray(W)[0])\n",
119+
"\n",
120+
"x = 0.3\n",
121+
"weights = gtsam.FourierBasis.CalculateWeights(N, x)\n",
122+
"print(\"FourierBasis weights at x=0.3:\", np.asarray(weights).ravel())\n"
123+
]
124+
},
125+
{
126+
"cell_type": "markdown",
127+
"metadata": {},
128+
"source": [
129+
"## Source\n",
130+
"- [Basis.h](https://github.com/borglab/gtsam/blob/develop/gtsam/basis/Basis.h)\n"
131+
]
132+
}
133+
],
134+
"metadata": {
135+
"kernelspec": {
136+
"display_name": "py312",
137+
"language": "python",
138+
"name": "python3"
139+
},
140+
"language_info": {
141+
"codemirror_mode": {
142+
"name": "ipython",
143+
"version": 3
144+
},
145+
"file_extension": ".py",
146+
"mimetype": "text/x-python",
147+
"name": "python",
148+
"nbconvert_exporter": "python",
149+
"pygments_lexer": "ipython3",
150+
"version": "3.12.6"
151+
}
152+
},
153+
"nbformat": 4,
154+
"nbformat_minor": 5
155+
}

‎gtsam/basis/doc/Chebyshev1Basis.ipynb‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Chebyshev1Basis\n",
8+
"\n",
9+
"<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",
10+
"\n",
11+
"## Overview\n",
12+
"\n",
13+
"`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"
14+
]
15+
},
16+
{
17+
"cell_type": "markdown",
18+
"metadata": {
19+
"tags": [
20+
"remove-cell"
21+
]
22+
},
23+
"source": [
24+
"GTSAM Copyright 2010-2022, Georgia Tech Research Corporation,\n",
25+
"Atlanta, Georgia 30332-0415\n",
26+
"All Rights Reserved\n",
27+
"\n",
28+
"Authors: Frank Dellaert, et al. (see THANKS for the full author list)\n",
29+
"\n",
30+
"See LICENSE for the license information\n"
31+
]
32+
},
33+
{
34+
"cell_type": "code",
35+
"execution_count": 1,
36+
"metadata": {
37+
"tags": [
38+
"remove-cell"
39+
]
40+
},
41+
"outputs": [],
42+
"source": [
43+
"# Install GTSAM from pip if running in Google Colab\n",
44+
"try:\n",
45+
" import google.colab\n",
46+
" %pip install --quiet gtsam-develop\n",
47+
"except ImportError:\n",
48+
" pass # Not in Colab\n"
49+
]
50+
},
51+
{
52+
"cell_type": "markdown",
53+
"metadata": {},
54+
"source": [
55+
"## Key Functionality / API\n",
56+
"\n",
57+
"- `CalculateWeights(N, x, a=-1, b=1)` returns the $1 \t\\times N$ basis weights.\n",
58+
"- `DerivativeWeights(N, x, a=-1, b=1)` returns weights for the derivative.\n",
59+
"- `WeightMatrix(N, X)` stacks weights for a vector of sample points.\n"
60+
]
61+
},
62+
{
63+
"cell_type": "markdown",
64+
"id": "922e3685",
65+
"metadata": {},
66+
"source": [
67+
"## Usage Example\n",
68+
"\n",
69+
"Evaluate first-kind Chebyshev weights at a point and build a weight\n",
70+
"matrix for multiple sample points.\n"
71+
]
72+
},
73+
{
74+
"cell_type": "code",
75+
"execution_count": 2,
76+
"id": "30b37cbb",
77+
"metadata": {},
78+
"outputs": [
79+
{
80+
"name": "stdout",
81+
"output_type": "stream",
82+
"text": [
83+
"Weights at x=0.25: [ 1. 0.25 -0.875 -0.688 0.531 0.953]\n",
84+
"WeightMatrix shape: (5, 6)\n",
85+
"Row for x=0: [ 1. 0. -1. -0. 1. 0.]\n"
86+
]
87+
}
88+
],
89+
"source": [
90+
"import numpy as np\n",
91+
"import gtsam\n",
92+
"\n",
93+
"np.set_printoptions(precision=3, suppress=True)\n",
94+
"\n",
95+
"N = 6\n",
96+
"x = 0.25\n",
97+
"weights = gtsam.Chebyshev1Basis.CalculateWeights(N, x)\n",
98+
"print(\"Weights at x=0.25:\", np.asarray(weights).ravel())\n",
99+
"\n",
100+
"X = np.linspace(-1.0, 1.0, 5)\n",
101+
"W = gtsam.Chebyshev1Basis.WeightMatrix(N, X)\n",
102+
"print(\"WeightMatrix shape:\", np.asarray(W).shape)\n",
103+
"print(\"Row for x=0:\", np.asarray(W)[2])\n"
104+
]
105+
},
106+
{
107+
"cell_type": "markdown",
108+
"metadata": {},
109+
"source": [
110+
"## Source\n",
111+
"- [Chebyshev.h](https://github.com/borglab/gtsam/blob/develop/gtsam/basis/Chebyshev.h)\n"
112+
]
113+
}
114+
],
115+
"metadata": {
116+
"kernelspec": {
117+
"display_name": "py312",
118+
"language": "python",
119+
"name": "python3"
120+
},
121+
"language_info": {
122+
"codemirror_mode": {
123+
"name": "ipython",
124+
"version": 3
125+
},
126+
"file_extension": ".py",
127+
"mimetype": "text/x-python",
128+
"name": "python",
129+
"nbconvert_exporter": "python",
130+
"pygments_lexer": "ipython3",
131+
"version": "3.12.6"
132+
}
133+
},
134+
"nbformat": 4,
135+
"nbformat_minor": 5
136+
}

0 commit comments

Comments
 (0)