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.26, < 0.1 for shared third-party native dependencies.
  • pypddl >= 1.0.26, < 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.26,<0.1' 'pypddl>=1.0.26,<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_ENABLE_SEMI_NAIVE ON Enable semi-naive lifted Datalog 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 26, 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 26, 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.33.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.33-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.33-cp313-cp313-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

pytyr-0.0.33-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.33-cp312-cp312-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

pytyr-0.0.33-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.33-cp311-cp311-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

pytyr-0.0.33-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.33-cp310-cp310-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

pytyr-0.0.33-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.33-cp39-cp39-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.9macOS 11.0+ ARM64

File details

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

File metadata

  • Download URL: pytyr-0.0.33.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.33.tar.gz
Algorithm Hash digest
SHA256 7e058fa12b05f3c0899c542a89ff96731546fe825703557bcfc9aa5d2553820c
MD5 d4c4ac0bfbd54c01ea2cfc41b94004f8
BLAKE2b-256 5f6f4f2562003d9471ee1abbbb3fb7d53625132f79b6355a77b9a473370bccc5

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33.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.33-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 4bb88c39dd9d00d5af8c9e8478aecbf9e38e5211236ede7e630b81471c7db31c
MD5 a8bfcc0f5e59b6b8e41463bc42dd35b1
BLAKE2b-256 8b523c0cc2344aa1c7f159aa0aff9c1bc61c39d19b932999a6420411443393b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b3c214360000228377cc2b36bf255b615d4a69ccaff66af2adfd0428aa54f819
MD5 ce292fae132833cc74fa83ccd3bbbaa0
BLAKE2b-256 c416dc794676fc54d73737d63737ca35543ab7593f110b7fd28eddefbf02f008

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 498015381c9911488f1a3d0bc1f411e47537c1c5162d068702dd6e9f49633b91
MD5 35e1e6225c2fe672fe3c1821dae8b955
BLAKE2b-256 ac16c3faf243b8f11fe02f04f7166d25b9641180e5f90f32abc0157a5651f719

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d664b60ab16508c0c73778af5543feb8df391be90982e48f68d14947f0efcbfc
MD5 94f519b398267554d9e93f97ffbac26e
BLAKE2b-256 0bb917717aacca8a895bf549d2f4067cedccc6366279e8704b3d076e2268af2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 264d7bea39a3afa81b8c77eb042d6f3a0086b655d57e785437a247dd174f402c
MD5 185ed617b3917aa57ca13c4abd3c80a1
BLAKE2b-256 6a7cc3ac20ebda8b850d624897b937ce6353c70fed98454c138ef67ce21a09eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a0e259d10f3db04fd961366cb07035653bc04517fbb915c54f9cb26105010c79
MD5 580bd11cd20cd56478976f02e2e08e7b
BLAKE2b-256 94c014eb75156610ca8493c486bbd7550e6365ad1c556478ceab8f0e14d2cd84

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 463ff3a154c7e6c5b6b9de7f6c0db69340c7e4bd9b828c532a9187d780c91e94
MD5 add8d9c2fedef2461f0f66d7ce8309f0
BLAKE2b-256 3bfedce7f1aafe75d3cce6e03776e36447b6d2696dc440f24ec0c6bc882c9620

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8ca51f44ab3cbe095d089a1a8d7a35eb20e22ba1b55f72777986b4ddd7d53e19
MD5 2c8dcad3551d0ce1c0fa74145f6e6ac6
BLAKE2b-256 ba87b582e56de7892acfebb9b5f80c53f37ba0964c5f4e88e133d5a32089b4dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 393b1191cbe169b029a6a46a20e4d91de7b3dcd25e876838a00c8ce9baad791b
MD5 ca8b19b76049d91b49459cfcdd76e732
BLAKE2b-256 e755dfc78e888efcc85ab317a09922f1080ba5c45a8c211eda8cae7ac693b5e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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.33-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pytyr-0.0.33-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5990e4c0f66976c207879417849b6c6893e12c4f40f7d666f7104914905b98fc
MD5 1f3e1e33ec60002a82428df016dce827
BLAKE2b-256 676c94ee9d0f46fe6b5dfb47dcac6871890c03decc2c6000ee118f065f74d450

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytyr-0.0.33-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

This release

0.0.33 This release

11 files

0.0.32

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