cpp-pd-code-simplify-interface 0.1.25

Python interface for cpp-pd-code-simplify with runtime C++ compilation.

cpp-pd-code-simplify-interface

cpp-pd-code-simplify-interface is a Python package for calling the cpp-pd-code-simplify C++ implementation from Python.

The package is designed for PyPI distribution:

pip install cpp-pd-code-simplify-interface

It ships the C++ source code inside the wheel and source distribution. On first use, the package compiles a cached local dynamic library through cpp-simple-interface; later calls reuse that library through ctypes. A C++17 compiler compatible with g++ must be available at runtime.

Runtime dependencies are handled per platform. On Windows, the interface uses objdump -p or dumpbin /DEPENDENTS when available, then caches MinGW runtime DLLs such as libstdc++-6.dll, libgcc_s_*.dll, and libwinpthread-1.dll next to the generated DLL. On Linux it adds $ORIGIN rpath and can inspect ldd; on macOS it adds @loader_path rpath and can inspect otool -L. Load failures are wrapped with platform-specific dependency hints.

The core C++ source and header are not stored as permanent generated copies in this subproject. The custom Poetry build backend syncs them from the repository root during poetry build, embeds them in the wheel and sdist, then removes the temporary copies from the working tree.

Calls use the C++ library's default preprocessing pipeline: R1-move removal, true R2-bigon removal, and nugatory-crossing removal, then iterative mid-simplification.

Example

import cpp_pd_code_simplify_interface as simplify

pd_code = "PD[X[1,5,2,4],X[3,1,4,6],X[5,3,6,2]]"
result = simplify.simplify(pd_code)
print(result["final_pd_code"])

Returned final_pd_code strings are normalized for display: each crossing is written from the under-incoming edge, labels are renumbered along oriented components from 1, and crossing rows are sorted lexicographically. This is applied only at the final JSON boundary; the C++ backend keeps its internal numbering unchanged while simplifying.

The default max_paths=-1 uses deterministic heuristic green-path sampling in the C++ backend. Use ban_heuristic=True to request exhaustive green-path enumeration for a manageable input. Use reduction_round=K to cap applied mid-simplification rounds; the default -1 runs until stable. In default heuristic mode, a miss is followed by the native deterministic non-monotone failover, then a brute-force proof pass, then the RIII failover before the diagram is treated as stable. Use timeout=K to cap a call at K seconds; the default -1 has no timeout. Use verbose=True to forward timestamped C++ progress logs to stderr. If a call times out, the returned dictionary still contains the best PD code found so far and sets timed_out to True. Brute-force green-path enumeration is streamed by the C++ backend; pass bruteforce_budget=N to cap brute-force green-path checks per PD code. The default is 200000, and -1 disables that cap. If the budget is exhausted, the returned dictionary still contains the current best PD code and sets resource_limited to True. Verbose log lines use local wall-clock time in YYYY-MM-DD HH:MM:SS format. When max_thread=-1 reaches a brute-force search phase, verbose logs also include actual_threads, the worker count selected by the C++ backend for that phase. The backend call runs in a helper process, so Ctrl+C can terminate active C++ work and its worker threads cleanly. Use log_file=PATH, or CLI flag --log-file PATH, to tee stdout and stderr into a flushed backup log file. Use show_step_pd=True, or CLI flag --show-step-pd, to print step_pd_code[ROUND]: PD[...] to stdout after each mid-simplification witness is applied and canonicalized, before that round's automatic local cleanup.

Batch use:

results = simplify.simplify_many([pd_code, "PD[]"])

To select a compiler:

CXX=clang++ python your_script.py

Windows PowerShell:

$env:CXX = "C:\path\to\g++.exe"
python your_script.py

On Windows, use a compiler whose target architecture matches Python. A 64-bit Python process needs a 64-bit MinGW-w64/UCRT, Clang, or MSVC-compatible compiler target. Legacy MinGW.org toolchains are not supported because they do not provide the C++ threading runtime used by the simplifier.

Command-line use also supports multi-line PD-code files:

python -m cpp_pd_code_simplify_interface --pd-file inputs.pd --max-paths -1 --verbose

Build And Publish

From this directory:

poetry build
poetry publish

Use poetry publish --build to build and upload in one command.

For local testing:

poetry run python -m cpp_pd_code_simplify_interface "PD[]"