Update from upstream develop

.github/copilot-instructions.md

@@ -4,6 +4,16 @@ For reviewing PRs:
 * Use meaningful variable names, e.g. `measurement` not `msm`, avoid abbreviations.
 * Flag overly complex or long/functions: break up in smaller functions
 * On Windows it is necessary to explicitly export all functions from the library which should be externally accessible. To do this, include the macro `GTSAM_EXPORT` in your class or function definition.
+* When adding or modifying public classes/methods, always review and follow `Using-GTSAM-EXPORT.md` before finalizing changes, including template specialization/export rules.
 * If we add a C++ function to a `.i` file to expose it to the wrapper, we must ensure that the parameter names match exactly between the declaration in the header file and the declaration in the `.i`. Similarly, if we change any parameter names in a wrapped function in a header file, or change any parameter names in a `.i` file, we must change the corresponding function in the other file to reflect those changes.
 * Classes are Uppercase, methods and functions lowerMixedCase.
+* Public fields in structs keep plain names (no trailing underscore).
 * Apart from those naming conventions, we adopt Google C++ style.
+* Notebooks in `*/doc/*.ipynb` and `*/examples/*.ipynb` should follow the standard preamble:
+  1) title/introduction markdown cell,
+  2) copyright markdown cell tagged `remove-cell`,
+  3) Colab badge markdown cell,
+  4) Colab install code cell tagged `remove-cell`,
+  5) imports/setup code cell.
+  Use the same `remove-cell` tagging convention as existing notebooks so docs build and Colab behavior stay consistent.
+* After any code change, always run relevant tests via `make -j6 testXXX.run` in the build folder $WORKSPACE/build. If in VS code, ask for escalated permissions if needed.

.github/scripts/compare_time_sfmbal_benchmarks.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Compare timeSFMBAL benchmark JSON files and render a PR-friendly markdown body."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Dict
+
+
+def _load_result(path: Path) -> Dict[str, float]:
+    with path.open("r", encoding="utf-8") as f:
+        payload = json.load(f)
+    if not isinstance(payload, list):
+        raise ValueError(f"{path} is not a JSON array")
+
+    metrics: Dict[str, float] = {}
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name")
+        value = item.get("value")
+        if not isinstance(name, str):
+            continue
+        if not isinstance(value, (int, float)):
+            continue
+        metrics[name] = float(value)
+    return metrics
+
+
+def _collect_results(folder: Path) -> Dict[str, Dict[str, float]]:
+    if not folder.exists():
+        return {}
+
+    results: Dict[str, Dict[str, float]] = {}
+    for path in sorted(folder.glob("*.json")):
+        runner_id = path.stem
+        results[runner_id] = _load_result(path)
+    return results
+
+
+def _fmt_seconds(value: float | None) -> str:
+    if value is None:
+        return "N/A"
+    return f"{value:.6f}"
+
+
+def _fmt_delta(head: float | None, base: float | None) -> str:
+    if head is None or base is None:
+        return "N/A"
+    delta = head - base
+    return f"{delta:+.6f}"
+
+
+def _fmt_percent(head: float | None, base: float | None) -> str:
+    if head is None or base is None or base == 0.0:
+        return "N/A"
+    pct = (head - base) / base * 100.0
+    return f"{pct:+.2f}%"
+
+
+def render_markdown(
+    head_results: Dict[str, Dict[str, float]],
+    base_results: Dict[str, Dict[str, float]],
+    head_sha: str,
+    base_sha: str,
+) -> str:
+    lines = ["<!-- time-sfmbal-benchmark -->", "## timeSFMBAL benchmark", ""]
+    lines.append(f"- Head: `{head_sha}`")
+    if base_sha:
+        lines.append(f"- Base: `{base_sha}`")
+    lines.append("")
+
+    if not head_results:
+        lines.append("No head benchmark results were found.")
+        return "\n".join(lines) + "\n"
+
+    lines.append(
+        "| Runner | Metric | Base (s) | Head (s) | Delta (s) | Change |"
+    )
+    lines.append("| --- | --- | ---: | ---: | ---: | ---: |")
+
+    missing_base_runners = []
+    for runner_id in sorted(head_results):
+        head_metrics = head_results[runner_id]
+        base_metrics = base_results.get(runner_id, {})
+        if not base_metrics:
+            missing_base_runners.append(runner_id)
+
+        metric_names = sorted(set(head_metrics) | set(base_metrics))
+        for metric_name in metric_names:
+            head_value = head_metrics.get(metric_name)
+            base_value = base_metrics.get(metric_name)
+            lines.append(
+                "| "
+                + f"{runner_id} | `{metric_name}` | {_fmt_seconds(base_value)} | "
+                + f"{_fmt_seconds(head_value)} | {_fmt_delta(head_value, base_value)} | "
+                + f"{_fmt_percent(head_value, base_value)} |"
+            )
+
+    if missing_base_runners:
+        lines.append("")
+        lines.append(
+            "Missing base benchmark cache for: "
+            + ", ".join(f"`{runner}`" for runner in missing_base_runners)
+            + "."
+        )
+
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Compare per-runner timeSFMBAL benchmark JSON files."
+    )
+    parser.add_argument("--head-dir", required=True, help="Directory with head JSON files")
+    parser.add_argument("--base-dir", required=True, help="Directory with base JSON files")
+    parser.add_argument("--head-sha", required=True, help="Head commit SHA")
+    parser.add_argument("--base-sha", default="", help="Base commit SHA")
+    parser.add_argument("--output", required=True, help="Output markdown file")
+    args = parser.parse_args()
+
+    head_dir = Path(args.head_dir)
+    base_dir = Path(args.base_dir)
+    output = Path(args.output)
+
+    head_results = _collect_results(head_dir)
+    base_results = _collect_results(base_dir)
+    markdown = render_markdown(head_results, base_results, args.head_sha, args.base_sha)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(markdown, encoding="utf-8")
+    print(markdown, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/scripts/python.sh

@@ -24,6 +24,7 @@ if [ -z ${PYTHON_VERSION+x} ]; then
 fi
 
 export PYTHON="python${PYTHON_VERSION}"
+NO_BOOST_BUILD=OFF
 
 function install_dependencies()
 {
@@ -43,20 +44,26 @@ function install_dependencies()
 
 function build()
 {
-  export CMAKE_GENERATOR=Ninja
   BUILD_PYBIND="ON"
+  USE_BOOST_FEATURES="ON"
+  ENABLE_BOOST_SERIALIZATION="ON"
+
+  if [ "${NO_BOOST_BUILD}" == "ON" ]; then
+    USE_BOOST_FEATURES="OFF"
+    ENABLE_BOOST_SERIALIZATION="OFF"
+  fi
 
   # Add Boost hints on Windows
   BOOST_CMAKE_ARGS=""
-  if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OSTYPE" == "cygwin" ]]; then
+  if [ "${NO_BOOST_BUILD}" != "ON" ] && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OSTYPE" == "cygwin" ]]; then
     if [ -n "${BOOST_ROOT}" ]; then
      BOOST_ROOT_UNIX=$(echo "$BOOST_ROOT" | sed 's/\\/\//g')
      BOOST_CMAKE_ARGS="-DBOOST_ROOT=${BOOST_ROOT_UNIX} -DBOOST_INCLUDEDIR=${BOOST_ROOT_UNIX}/include -DBOOST_LIBRARYDIR=${BOOST_ROOT_UNIX}/lib"
     fi
   fi
 
   cmake $GITHUB_WORKSPACE \
-      -B build \
+      -B build -G Ninja \
       -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} \
       -DGTSAM_BUILD_TESTS=OFF \
       -DGTSAM_BUILD_UNSTABLE=${GTSAM_BUILD_UNSTABLE:-ON} \
@@ -68,20 +75,28 @@ function build()
       -DGTSAM_UNSTABLE_BUILD_PYTHON=${GTSAM_BUILD_UNSTABLE:-ON} \
       -DGTSAM_PYTHON_VERSION=$PYTHON_VERSION \
       -DPYTHON_EXECUTABLE:FILEPATH=$(which $PYTHON) \
-      -DGTSAM_USE_BOOST_FEATURES=ON \
-      -DGTSAM_ENABLE_BOOST_SERIALIZATION=ON \
+      -DGTSAM_USE_BOOST_FEATURES=${USE_BOOST_FEATURES} \
+      -DGTSAM_ENABLE_BOOST_SERIALIZATION=${ENABLE_BOOST_SERIALIZATION} \
       -DGTSAM_ALLOW_DEPRECATED_SINCE_V43=OFF \
       -DCMAKE_INSTALL_PREFIX=$GITHUB_WORKSPACE/gtsam_install \
       $BOOST_CMAKE_ARGS
 
-  # Set to 2 cores so that Actions does not error out during resource provisioning.
-  cmake --build build -j2
-
-  cmake --build build --target python-install
+  if [ "${NO_BOOST_BUILD}" == "ON" ]; then
+    # Build only wrapper targets for the no-Boost verification lane.
+    cmake --build build -j2 --target gtsam_py gtsam_unstable_py
+  else
+    # Set to 2 cores so that Actions does not error out during resource provisioning.
+    cmake --build build -j2
+    cmake --build build --target python-install
+  fi
 }
 
 function test()
 {
+  if [ "${NO_BOOST_BUILD}" == "ON" ]; then
+    export PYTHONPATH="$GITHUB_WORKSPACE/build/python:$PYTHONPATH"
+  fi
+
   cd $GITHUB_WORKSPACE/python/gtsam/tests
   $PYTHON -m unittest discover -v
   cd $GITHUB_WORKSPACE
@@ -94,8 +109,30 @@ function test()
   # cmake --build build --target python-test-unstable
 }
 
+# Parse optional flags.
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 {-d|-b|-t} [--no-boost]"
+  exit 2
+fi
+
+ACTION="$1"
+shift
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --no-boost)
+      NO_BOOST_BUILD=ON
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 2
+      ;;
+  esac
+  shift
+done
+
 # select between build or test
-case $1 in
+case $ACTION in
   -d)
     install_dependencies
     ;;

.github/scripts/python_wheels/cibw_before_all.sh

@@ -8,7 +8,6 @@ set -x
 
 PYTHON_VERSION="$1"
 PROJECT_DIR="$2"
-ARCH=$(uname -m)
 
 export PYTHON="python${PYTHON_VERSION}"
 
@@ -33,11 +32,26 @@ BOOST_PREFIX="$HOME/opt/boost"
 ./bootstrap.sh --prefix=${BOOST_PREFIX}
 
 if [ "$(uname)" == "Linux" ]; then
-    ./b2 install --prefix=${BOOST_PREFIX} --with=all -d0
+    ./b2 install --prefix=${BOOST_PREFIX} -d0 --with-graph \
+        --with-move --with-optional --with-program_options --with-random \
+        --with-serialization --with-smart_ptr --with-timer --with-chrono
 elif [ "$(uname)" == "Darwin" ]; then
-    ./b2 install --prefix=${BOOST_PREFIX} --with=all -d0 \
+    ./b2 install --prefix=${BOOST_PREFIX} -d0 --with-graph \
+        --with-move --with-optional --with-program_options --with-random \
+        --with-serialization --with-smart_ptr --with-timer --with-chrono \
+        architecture=arm \
         cxxflags="-mmacosx-version-min=${MACOSX_DEPLOYMENT_TARGET}" \
         linkflags="-mmacosx-version-min=${MACOSX_DEPLOYMENT_TARGET}"
+    ./b2 install --prefix=${BOOST_PREFIX}/x86 -d0 --with-graph \
+        --with-move --with-optional --with-program_options --with-random \
+        --with-serialization --with-smart_ptr --with-timer --with-chrono \
+        architecture=x86 \
+        cxxflags="-mmacosx-version-min=${MACOSX_DEPLOYMENT_TARGET}" \
+        linkflags="-mmacosx-version-min=${MACOSX_DEPLOYMENT_TARGET}"
+    for dylib in ${BOOST_PREFIX}/lib/*.dylib; do
+        lipo -create -output $dylib $dylib ${BOOST_PREFIX}/x86/lib/$(basename $dylib)
+    done
+    rm -r ${BOOST_PREFIX}/x86
 fi
 cd ..
 
@@ -67,6 +81,7 @@ rm -rf CMakeCache.txt CMakeFiles
 cmake $PROJECT_DIR \
     -B build \
     -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} \
+    -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" \
     -DGTSAM_BUILD_TESTS=OFF \
     -DGTSAM_BUILD_UNSTABLE=${GTSAM_BUILD_UNSTABLE:-ON} \
     -DGTSAM_USE_QUATERNIONS=OFF \

.github/scripts/unix.sh

@@ -17,9 +17,8 @@ function configure()
 
   # GTSAM_BUILD_WITH_MARCH_NATIVE=OFF: to avoid crashes in builder VMs
   # CMAKE_CXX_FLAGS="-w": Suppress warnings to avoid IO latency in CI logs
-  export CMAKE_GENERATOR=Ninja
   cmake $GITHUB_WORKSPACE \
-      -B build \
+      -B build -G Ninja \
       -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE:-Debug} \
       -DCMAKE_CXX_FLAGS="-w" \
       -DGTSAM_BUILD_TESTS=${GTSAM_BUILD_TESTS:-OFF} \