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 pyyggdrasil.execution 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)
successor_generator = successor_generator_factory.create(task, execution_context)

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

# Get the labeled successor nodes (sequence of action binding + node)
labeled_successor_nodes = successor_generator.get_labeled_successor_nodes(initial_node, state_repository, axiom_evaluator)

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<tyr::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<tyr::LiftedTag>();
auto state_repository_factory = tp::StateRepositoryFactory<tyr::LiftedTag>();
auto successor_generator_factory = tp::SuccessorGeneratorFactory<tyr::LiftedTag>();

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

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

// Get the labeled successor nodes (sequence of action binding + node).
auto labeled_successor_nodes = successor_generator->get_labeled_successor_nodes(initial_node, *state_repository, *axiom_evaluator);

Dependencies

Tyr consumes native dependencies from Python packages:

  • pyyggdrasil >= 0.0.27, < 0.1 for shared third-party native dependencies.
  • pypddl >= 1.0.27, < 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.27,<0.1' 'pypddl>=1.0.27,<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.
TYR_RELATION_STORAGE_POLICY Word Relation storage backend; accepted values are Word and Bit. Bit packing uses num_objects supplied when creating repositories.

RepositoryFactory.create_repository(parent_repository=None, num_objects=None) accepts the total object count for the repository. None keeps the full object-index width; child counts include the parent object universe.

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 Aug 13, 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 Aug 13, 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.34.tar.gz (712.4 kB 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.34-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.9 MB view details)

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

pytyr-0.0.34-cp313-cp313-macosx_11_0_arm64.whl (4.3 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

pytyr-0.0.34-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.9 MB view details)

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

pytyr-0.0.34-cp312-cp312-macosx_11_0_arm64.whl (4.3 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

pytyr-0.0.34-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.9 MB view details)

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

pytyr-0.0.34-cp311-cp311-macosx_11_0_arm64.whl (4.3 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

pytyr-0.0.34-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.9 MB view details)

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

pytyr-0.0.34-cp310-cp310-macosx_11_0_arm64.whl (4.3 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

pytyr-0.0.34-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.9 MB view details)

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

pytyr-0.0.34-cp39-cp39-macosx_11_0_arm64.whl (4.3 MB view details)

Uploaded CPython 3.9macOS 11.0+ ARM64

File details

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

File metadata

  • Download URL: pytyr-0.0.34.tar.gz
  • Upload date:
  • Size: 712.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pytyr-0.0.34.tar.gz
Algorithm Hash digest
SHA256 2194bbae07a7f22dcc2245ffa49a834f9214fff069a833a9ce1a11afa02c29cb
MD5 19a90ee9074204d053839a43aff76083
BLAKE2b-256 9b73722c8113b1a44f2de5597966ee5e3af43b766b9d034c667b7b89eaed4cb7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0b3f735cfe1139bbf65398bdd1e5a93e9f1c700ff6d8660a3999c1594ef3e161
MD5 7fb818caa6d111ace56d1f0e2f66c78b
BLAKE2b-256 62df990fbf02564d6e2e529e1011bffb9c24df79cb45d9243e36df03e7325467

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 57a7a154e2a0e4bfeb800e6654dc3fb1af4d431c75e0d7d0b39b0c1fc6ecf2bd
MD5 6294b53de935c93ec623fd750cfa73e3
BLAKE2b-256 4308ae5d480a0c6592cca884177e61bc68ec3154975a2cbf07970dd235e14c1e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2798f4195cdd0001f215ecdd284d669c16c2f22df3f89d95a9198bef95a2d398
MD5 d0eb9d500b5f3f910b52957aa769fb95
BLAKE2b-256 61e3edbbaed68ec52a351f53d903e050d668611348be6526d9d146ca6217d543

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 cfb21b1ca46bdf7dd637faf412c59043522c3723725755d72cc93196df48a23b
MD5 18b07d06814da59527632ae12211f807
BLAKE2b-256 b6179bf6dae0da6c78ae30588aa8caffd8d1ad2b5d30393d26e8d4223700515e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a64f04bdc0ffc9a04c866369b2f13e413386efb1884bc1b7aa3eff553512e283
MD5 a52a6d2e75c1ceda87008e8048f4581d
BLAKE2b-256 09b6acf2bbbabb35548ae508b9b297a91890b5f25da1495c95d74bb56ff575d9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ce87f792cbf39e0862de93f56d6664f4acb4e5abcd3684692cdefd40be152931
MD5 cd27f629162cb2b9f4b5a3d7c1e37272
BLAKE2b-256 6dc7ad8347573c225c54b069127cfd86793391baef261c44817667cfc56683b4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 41e196d03ea8a2ece6d7d62499fb509f3955c92748b29c07344e54cb656472ac
MD5 e500247b6752a7c1b39d1a227075906b
BLAKE2b-256 06976b131acef58fd2d6fc092e840f8622c4795ef86022a7c6647ae0e2ec58b2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e77c76fefe1dd9b5df879cba62f1aff0f66c958b94b75bdf016c3fd6bae3b0e3
MD5 57ac7aa176c16a0f49ff97fcae58dcd5
BLAKE2b-256 537e2ee67e4e414b9a6cae343f450e2433f9d252ace637b5adccb5f27a981a8d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 19fc81a2e450211ab7340391edb65520bd6a9d4fddd822f8f9263b09e0405abe
MD5 ee507219df2113ef148ab011bb317c07
BLAKE2b-256 f664a9028d21b176d57adfa4a69fa2425c578baae95ae6a72059db5419a24001

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pytyr-0.0.34-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 770228302e246879fcfbb707d3369e75c1a481d8ff0d0560940c13bf529bfae1
MD5 4e98e480a899ef21195c75aec0e32bd1
BLAKE2b-256 6e159640e4c299401337ccfc2a3dd1064632338908425c0b7cceead7d541aa18

See more details on using hashes here.

Provenance

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

This release

0.0.34 This release

11 files

0.0.33

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