gtsam/gtsam/inference/doc/Ordering.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ordering_intro_md"
      },
      "source": [
        "# Ordering"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ordering_desc_md"
      },
      "source": [
        "An `Ordering` specifies the order in which variables are eliminated during inference (e.g., Gaussian elimination, multifrontal QR). The choice of ordering significantly impacts the computational cost and fill-in (sparsity) of the resulting Bayes net or Bayes tree.\n",
        "\n",
        "GTSAM provides several algorithms to compute good orderings automatically (like COLAMD, METIS) or allows you to specify a custom ordering."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ordering_colab_md"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/borglab/gtsam/blob/develop/gtsam/inference/doc/Ordering.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ordering_pip_code",
        "tags": [
          "remove-cell"
        ]
      },
      "outputs": [],
      "source": [
        "%pip install gtsam"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 15,
      "metadata": {
        "id": "ordering_import_code"
      },
      "outputs": [],
      "source": [
        "import gtsam\n",
        "from gtsam import Ordering, VariableIndex\n",
        "# Need a graph type for automatic ordering\n",
        "from gtsam import SymbolicFactorGraph\n",
        "from gtsam import symbol_shorthand\n",
        "\n",
        "X = symbol_shorthand.X\n",
        "L = symbol_shorthand.L"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ordering_create_md"
      },
      "source": [
        "## Creating an Ordering\n",
        "\n",
        "Orderings can be created manually or computed automatically from a factor graph."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 16,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "ordering_manual_code",
        "outputId": "6789abcd-ef01-2345-6789-abcdef012345"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Manual Ordering: Position 0: x1, l1, x2, l2, x0\n"
          ]
        }
      ],
      "source": [
        "# Manual creation (list of keys)\n",
        "manual_ordering = Ordering([X(1), L(1), X(2), L(2), X(0)])\n",
        "manual_ordering.print(\"Manual Ordering: \")"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 18,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "ordering_auto_code",
        "outputId": "789abcde-f012-3456-789a-bcdef0123456"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "COLAMD Ordering: Position 0: l1, x0, x1, l2, x2\n",
            "Constrained COLAMD (x0, x2 last): Position 0: l2, l1, x1, x2, x0\n"
          ]
        }
      ],
      "source": [
        "# Automatic creation requires a factor graph\n",
        "# Let's use a simple SymbolicFactorGraph for structure\n",
        "graph = SymbolicFactorGraph()\n",
        "graph.push_factor(X(0))\n",
        "graph.push_factor(X(0), X(1))\n",
        "graph.push_factor(X(1), X(2))\n",
        "graph.push_factor(X(0), L(1))\n",
        "graph.push_factor(X(1), L(1))\n",
        "graph.push_factor(X(1), L(2))\n",
        "graph.push_factor(X(2), L(2))\n",
        "\n",
        "# COLAMD (Column Approximate Minimum Degree) ordering\n",
        "colamd_ordering = Ordering.ColamdSymbolicFactorGraph(graph)\n",
        "colamd_ordering.print(\"COLAMD Ordering: \")\n",
        "\n",
        "# Constrained COLAMD (force x0 and x2 to be eliminated last)\n",
        "constrained_ordering = Ordering.ColamdConstrainedLastSymbolicFactorGraph(graph, gtsam.KeyVector([X(0), X(2)]))\n",
        "constrained_ordering.print(\"Constrained COLAMD (x0, x2 last): \")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ordering_access_md"
      },
      "source": [
        "## Accessing Elements\n",
        "\n",
        "An `Ordering` behaves like a vector of keys."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 19,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "ordering_access_code",
        "outputId": "89abcdef-0123-4567-89ab-cdef01234567"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Ordering size: 5\n",
            "Key at position 0: l1\n"
          ]
        }
      ],
      "source": [
        "print(f\"Ordering size: {colamd_ordering.size()}\")\n",
        "\n",
        "# Access by index\n",
        "key_at_0 = colamd_ordering.at(0)\n",
        "print(f\"Key at position 0: {gtsam.DefaultKeyFormatter(key_at_0)}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ordering_append_md"
      },
      "source": [
        "## Appending Keys\n",
        "\n",
        "You can append keys using `push_back`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 20,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "ordering_append_code",
        "outputId": "9abcdef0-1234-5678-9abc-def012345678"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Appended Ordering: Position 0: l1, x0, x1, l2, x2, l0, x3\n"
          ]
        }
      ],
      "source": [
        "appended_ordering = Ordering(colamd_ordering)\n",
        "appended_ordering.push_back(L(0))\n",
        "appended_ordering.push_back(X(3))\n",
        "\n",
        "appended_ordering.print(\"Appended Ordering: \")"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "display_name": "gtsam",
      "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.13.1"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}