Tyr: Generalized Planning in C++20 and Python

Tyr is designed to address several challenges in modern planning systems:

  1. Unified grounded and lifted planning within a type-safe API.

  2. Rapid prototyping through Python bindings with type hints, backed by a high-performance C++ core.

  3. Support for expressive numeric planning formalisms across both grounded and lifted reasoning paradigms (see Supported PDDL Features).

  4. Integration of learning and reasoning by supporting collections of planning tasks over a shared planning domain.

Technical Overview

  • PDDL frontend: Tyr uses Loki to parse, normalize, and translate PDDL input. The parser is implemented with Boost and provides informative error messages for syntactically invalid input. The normalization pipeline largely follows the approach described in Section 4 of Concise finite-domain representations for PDDL planning tasks.

  • Datalog engine: Tyr implements a parallel semi-naive Datalog engine for lifted successor generation, axiom evaluation, relaxed planning graph heuristics, and task grounding. Its execution model is synchronous and supports both rule-level and grounding-level parallelism.

  • Ground planning: For grounded tasks, Tyr uses data structures inspired by The Fast Downward Planning System to efficiently identify applicable actions in a given state. Grounding often yields substantial performance improvements, although it is not always feasible for large tasks.

  • State representation: Tyr statically analyzes domain and problem files and partitions predicates, functions, and related structures into strongly typed categories such as static, fluent, and derived atoms. This design prevents accidental mixing of conceptually different entities. To represent sequences compactly, Tyr uses tree databases of perfectly balanced binary trees, allowing common subsequences to be shared through shared subtrees. As a special case, Tyr synthesizes finite-domain variables for fluent atoms in grounded planning, largely following the method described in Section 5 of Concise finite-domain representations for PDDL planning tasks, enabling more compact storage when grounding is feasible.

  • Memory model: Tyr stores generated data in hierarchically structured, geometrically growing buffers. For variable-sized objects, it uses Cista for serialization and zero-copy deserialization. This design allows derived buffers to inherit data from parent buffers without duplication. For example, multiple tasks can share a domain, and multiple workers can share task data.

Getting Started

The library consists of a formalism and a planning component. The formalism component is responsible for representing PDDL entities. The planning component provides functionality for implementing search algorithms, as well as off-the-shelf implementations of eager A*, lazy GBFS, and heuristics such as blind, max, add, and FF. Below is a minimal overview of the Python and C++ APIs for implementing custom search algorithms.

Python Interface

Pytyr is available at PyPI and can be installed with pip install pytyr.

Detailed examples are available in the python/examples directory:

  • structures.py – Parse and traverse all planning formalism structures.
  • builder.py – Create new planning formalism structures.
  • invariants.py – Synthesize invariants, access candidate variable bindings, and match atoms through unification.
  • astar_eager.py – Use and customize off-the-shelf search algorithms.
  • gbfs_lazy.py – Implement a custom search algorithm from scratch.

The Python interface for implementing search algorithms is:

# Recommended namespace aliases
from pytyr.planning import ExecutionContext
import pytyr.formalism.planning as tfp
import pytyr.planning.lifted as tpl  # pytyr.planning.ground also exists

# Parse and translate a task over a domain.
parser = tfp.Parser("domain.pddl")
# Instantiate a lifted task.
task = tpl.Task(parser.parse_task("problem.pddl"))

# Instantiate a single-threaded execution environment.
execution_context = ExecutionContext(1)

# Instantiate the planning objects. Factories assign unique context indices so
# state views from different state repositories hash and compare correctly.
axiom_evaluator_factory = tpl.AxiomEvaluatorFactory()
state_repository_factory = tpl.StateRepositoryFactory()
successor_generator_factory = tpl.SuccessorGeneratorFactory()
axiom_evaluator = axiom_evaluator_factory.create(task, execution_context)
state_repository = state_repository_factory.create(task, axiom_evaluator)
successor_generator = successor_generator_factory.create(task, execution_context, state_repository)

# Get the initial node (state + metric value)
initial_node = successor_generator.get_initial_node()

# Get the labeled successor nodes (sequence of ground action + node)
labeled_successor_nodes = successor_generator.get_labeled_successor_nodes(initial_node)

C++ Interface

The C++ interface for implementing search algorithms is:

#include <tyr/tyr.hpp>

// Recommended namespace aliases.
namespace tfp = tyr::formalism::planning;
namespace tp = tyr::planning;

// Parse and translate a task over a domain.
auto parser = tfp::Parser("domain.pddl");
// Instantiate a lifted task.
auto task = tp::Task<tp::LiftedTag>::create(parser.parse_task("problem.pddl"));

// Instantiate a single-threaded execution environment
auto execution_context = ygg::ExecutionContext::create(1);

// Instantiate the planning objects. Factories assign unique context indices so
// state views from different state repositories hash and compare correctly.
auto axiom_evaluator_factory = tp::AxiomEvaluatorFactory<tp::LiftedTag>();
auto state_repository_factory = tp::StateRepositoryFactory<tp::LiftedTag>();
auto successor_generator_factory = tp::SuccessorGeneratorFactory<tp::LiftedTag>();

auto axiom_evaluator = axiom_evaluator_factory.create(task, execution_context);
auto state_repository = state_repository_factory.create(task, axiom_evaluator);
auto successor_generator = successor_generator_factory.create(task, execution_context, state_repository);

// Get the initial node (state + metric value).
auto initial_node = successor_generator->get_initial_node();

// Get the labeled successor nodes (sequence of ground action + node).
auto labeled_successor_nodes = successor_generator->get_labeled_successor_nodes(initial_node);

Dependencies

Tyr consumes native dependencies from Python packages:

  • pyyggdrasil >= 0.0.25, < 0.1 for shared third-party native dependencies.
  • pypddl >= 1.0.25, < 1.1 for Loki's PDDL parser library, headers, and CMake package.
  • pypddl-datasets >= 0.0.9, < 0.1 for the PDDL benchmark data used by the C++ test and profiling fixtures (resolved from its cache at CMake configure time).

The shared workspace layout, layered install order, and the common build-from-source and CMake-integration patterns are documented in the Planning and Learning build instructions; the sections below cover tyr/pytyr-specific details.

Build C++

Install Tyr's native dependency providers into the active Python environment, then configure CMake with their native prefixes:

python -m pip install 'pyyggdrasil>=0.0.25,<0.1' 'pypddl>=1.0.25,<1.1' 'pypddl-datasets>=0.0.9,<0.1'

cmake -S . -B build \
  -DPython_EXECUTABLE="$(python -c 'import sys; print(sys.executable)')"

cmake --build build -j4

CMake discovers the installed provider packages automatically through cmake/bootstrap_pyyggdrasil.cmake (which locates pyyggdrasil and adds its native prefix to CMAKE_PREFIX_PATH; find_package(yggdrasil) then resolves the rest of the chain) and links against the yggdrasil::yggdrasil and loki::parsers targets. To point at different prefixes explicitly:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH="$(python -m pyyggdrasil --prefix);$(python -m pypddl --prefix)"

CMake options:

Option Default Description
TYR_BUILD_TESTS OFF Build Tyr tests.
TYR_BUILD_EXECUTABLES OFF Build Tyr executables.
TYR_BUILD_PROFILING OFF Build Tyr profiling targets.
TYR_BUILD_PYTYR OFF Build pytyr Python bindings.
TYR_HEADER_INSTANTIATION OFF Instantiate templates in in-tree translation units at higher compile-time cost.
TYR_ENABLE_INNER_PARALLELISM OFF Enable inner parallelism for expensive lifted rule evaluation.
TYR_USE_LLD ON Use LLVM lld with Clang when available.
TYR_ENABLE_LTO ON Enable link-time optimization for Release builds.
TYR_STATE_STORAGE_POLICY Tree State storage backend; accepted values are Tree and Hashset.

Single-config CMake builds default to Release. On GCC and Clang, Debug builds use -Og with debug symbols, RelWithDebInfo keeps frame pointers and disables LTO, and Release LTO uses GCC LTO or Clang ThinLTO. Editable installs and wheels disable TYR_USE_LLD and TYR_ENABLE_LTO by default for build reliability.

Install Tyr from a configured build directory with:

cmake --install build --prefix=<path/to/installation-directory>

More detailed Tyr-specific build instructions are available in docs/BUILD.md.

Build Python

python -m pip install .[test]
pytest python/tests

CMake Integration

This section covers pytyr-specific paths and targets; the general pattern for consuming the native prefixes from CMake is in the common CMake integration instructions.

The Python package pytyr installs Tyr's native headers, shared library, and CMake package config under pytyr.native_prefix(). Use pytyr.cmake_prefix() and pytyr.cmake_dir() (or python -m pytyr --prefix / --cmake-dir from the shell) to locate them. Downstream CMake projects should include the native prefixes of pytyr and its native package dependencies in CMAKE_PREFIX_PATH:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH="$(python -m pyyggdrasil --prefix);$(python -m pypddl --prefix);$(python -m pytyr --prefix)"

Tyr exports the tyr::core aggregate target.

Project links

Data verified by PyPI on Jul 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for DominikDrexler from gravatar.com DominikDrexler

Credits

Author: Dominik Drexler

GitHub Statistics

Data verified by PyPI on Jul 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.9

Provides Extra

test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytyr-0.0.32.tar.gz (1.0 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pytyr-0.0.32-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pytyr-0.0.32-cp313-cp313-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

pytyr-0.0.32-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pytyr-0.0.32-cp312-cp312-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

pytyr-0.0.32-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pytyr-0.0.32-cp311-cp311-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

pytyr-0.0.32-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pytyr-0.0.32-cp310-cp310-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

pytyr-0.0.32-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

pytyr-0.0.32-cp39-cp39-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded CPython 3.9macOS 11.0+ ARM64

File details

Details for the file pytyr-0.0.32.tar.gz.

File metadata

  • Download URL: pytyr-0.0.32.tar.gz
  • Upload date:
  • Size: 1.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pytyr-0.0.32.tar.gz
Algorithm Hash digest
SHA256 a65436ced3b38968d2dc45db4d683853cf31454a9cc8f66952814c888cef3f66
MD5 b38719a9c806df2ea98f46c8559de50d
BLAKE2b-256 1d91b7e03a3124c876286ff21bce9accfcde337ebf1b13ed84bdaa3f7fd89895

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32.tar.gz:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f9534cba0da963288da2a80bc8eb38958682bd28a397c9aa1eaad5e65caed07b
MD5 35e36696eac33b36ee6903488988857e
BLAKE2b-256 da12a05ca39035d3fd9bdad9050f3f2797e735b7c9fe1c8b5c68f9bda3a5d681

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0c6aff62ef07bed746e3accba9987739e3cd2e9d98ef51876a7886a0851486d9
MD5 4086f11b62b266f1ba67b9fb25c10f55
BLAKE2b-256 9f6da914ce7cb05b69c4cd890ea757ac2f01f527101052e3716ef64dbc422ad0

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 027b557ddc6e145f78d994fedb9867cb22ef2a093ba2e7bd7434be153244146b
MD5 715dc580ca129fb5617ab30123a2ce21
BLAKE2b-256 2c9e65aa3c5265697cd7fbf7ddb861ac3abf8a6be963980884bf85e203e5fb7a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9f569d20a47b2155f64b868b23a2cb5c0f6080326b97eca211ca290668f67115
MD5 77c10d9ea4a9425ae00fc26f75e1f811
BLAKE2b-256 55e2e1b43a558d015f7556185879e9524d0723c2652776b39603319ab232827b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bcd94eea0d0f52b4e5313eb9ac8dfd94025dc13c30ea06ff315ea375b87bb1d8
MD5 9b2f771d1095012274ad9f1f5221e65e
BLAKE2b-256 7d664af54150ea3663978a70c3a46fcdc225b3909e44f7180baf36b45b3b1864

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8424536d4a70dc866ec70ef40abea712e4251535a954b1065e581a75de1e01bc
MD5 ef91c36659eef75885777e9e34aa60e2
BLAKE2b-256 f12e6a85e85ca06d996d8f2271487679e038111f6bb270b58169ea4c17f36b7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ae937c26be8a81de8ebc20625ec8bfbbf4198a3769a92cbcdc9fd503b1e57c7b
MD5 ba313df4b44c0a1a4c7ea4f3e4956d78
BLAKE2b-256 7a7e976b03c6ca9ed9ef7011aa24d34bb2a2d566f668e1f42c646a929e00d51a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 07b9e192ce237e5abc1731b01cabde94e79d8dad5f93f93e7efded23b449f2c6
MD5 856835f4363724be2f305af9f5c2fdac
BLAKE2b-256 49753af44e74d0140a57d0f61049039e75e5e279e436237263caced04f6d3e5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 130369ec694dd503817a0679f7951789848d23fb5a808a0ab380c563c78b9ecb
MD5 1e2a0b48bd3527ab896c34a193107d01
BLAKE2b-256 20be458179733150ca5a78fe4802eab34a3987aa06c559d72a4f41cbc0a171e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytyr-0.0.32-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.32-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 724004dbd6b87ca19a4e59f071b5449f6d608b8a7bc3ad5088957e75fc5ad7d8
MD5 d09ed6d4ad39876af2202d8471a8f0b4
BLAKE2b-256 aad90d9be8ddaaef8f363b27f953b702e84058e8fbf46a5604f73eb4abf9b361

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.32-cp39-cp39-macosx_11_0_arm64.whl:

Publisher: release.yml on planning-and-learning/tyr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.1

3 files

0.2.0

3 files

0.1.0

3 files

0.0.34

11 files

0.0.33

11 files

This release

0.0.32 This release

11 files

0.0.31

11 files

0.0.30

11 files

0.0.29

11 files

0.0.28

11 files

0.0.27

11 files

0.0.26

11 files

0.0.25

11 files

0.0.24

11 files

0.0.23

11 files

0.0.22

11 files

0.0.21

11 files

0.0.20

11 files

0.0.19

11 files

0.0.18

11 files

0.0.17

11 files

0.0.16

11 files

0.0.15

11 files

0.0.12

11 files

0.0.11

11 files

0.0.10

9 files

0.0.9

16 files

0.0.8

16 files

0.0.7

16 files

0.0.6

16 files

0.0.5

16 files

0.0.4

16 files

0.0.3

16 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page