gtsam/gtsam/inference/doc/Symbol.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "symbol_intro_md"
      },
      "source": [
        "# Symbol"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "symbol_desc_md"
      },
      "source": [
        "A `Symbol` is a GTSAM class used to create semantically meaningful keys (`gtsam.Key`) for variables. It combines a character (`unsigned char`) and an index (`uint64_t`) into a single 64-bit integer key. This allows for easy identification of variable types and their indices, e.g., 'x' for poses and 'l' for landmarks, like `x0`, `x1`, `l0`."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "symbol_colab_md"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/borglab/gtsam/blob/develop/gtsam/inference/doc/Symbol.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": "symbol_pip_code",
        "tags": [
          "remove-cell"
        ]
      },
      "outputs": [],
      "source": [
        "%pip install --quiet gtsam-develop"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "id": "symbol_import_code"
      },
      "outputs": [],
      "source": [
        "import gtsam\n",
        "from gtsam import Symbol"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "symbol_init_md"
      },
      "source": [
        "## Initialization\n",
        "\n",
        "A `Symbol` can be created by providing a character and an index. It can also be created by decoding an existing `gtsam.Key` (integer)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "symbol_create_code",
        "outputId": "c1d2e3f4-a5b6-7890-bcde-f12345678901"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Symbol from char/index: x5\n",
            "Symbol from key 8646911284551352325: x5\n"
          ]
        }
      ],
      "source": [
        "# Create Symbol 'x' with index 5\n",
        "sym1 = Symbol('x', 5)\n",
        "print(f\"Symbol from char/index: {sym1.string()}\")\n",
        "\n",
        "# Get the underlying integer key\n",
        "key1 = sym1.key()\n",
        "\n",
        "# Reconstruct Symbol from the key\n",
        "sym2 = Symbol(key1)\n",
        "print(f\"Symbol from key {key1}: {sym2.string()}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "symbol_props_md"
      },
      "source": [
        "## Properties and Usage\n",
        "\n",
        "You can access the character, index, and underlying integer key."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "symbol_access_code",
        "outputId": "d2e3f4a5-b6c7-8901-cdef-123456789012"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Symbol: l10\n",
            "  Char: 108\n",
            "  Index: 10\n",
            "  Key: 7782220156096217098\n"
          ]
        }
      ],
      "source": [
        "landmark_sym = Symbol('l', 10)\n",
        "\n",
        "print(f\"Symbol: {landmark_sym.string()}\")\n",
        "print(f\"  Char: {landmark_sym.chr()}\")\n",
        "print(f\"  Index: {landmark_sym.index()}\")\n",
        "print(f\"  Key: {landmark_sym.key()}\")\n",
        "\n",
        "# Symbols are often used directly where Keys are expected in GTSAM functions,\n",
        "# as they implicitly convert.\n",
        "# e.g., values.insert(landmark_sym, gtsam.Point3(1,2,3))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "symbol_shorthand_md"
      },
      "source": [
        "## Shorthand Functions\n",
        "\n",
        "GTSAM provides convenient shorthand functions `X(j)`, `L(j)`, etc., which are equivalent to `gtsam.Symbol('x', j)`, `gtsam.Symbol('l', j)`. To use these, first import with `from gtsam import symbol_shorthand`, then set up the variables you want to use with statements like `X = symbol_shorthand.X`."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 9,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "symbol_shorthand_code",
        "outputId": "e3f4a5b6-c7d8-9012-def0-234567890123"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Symbol('x', 0).key() == X(0): True\n",
            "Symbol('l', 1).key() == L(1): True\n"
          ]
        }
      ],
      "source": [
        "from gtsam import symbol_shorthand\n",
        "\n",
        "X = symbol_shorthand.X\n",
        "L = symbol_shorthand.L\n",
        "\n",
        "print(f\"Symbol('x', 0).key() == X(0): {Symbol('x', 0).key() == X(0)}\")\n",
        "print(f\"Symbol('l', 1).key() == L(1): {Symbol('l', 1).key() == L(1)}\")"
      ]
    }
  ],
  "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
}