A GPU-native logic programming language for unified symbolic reasoning.
Documentation: xlog.md · Whitepaper (PDF) · Language reference · Examples
Neural-symbolic systems today keep symbolic reasoning on the CPU while neural computation runs on the GPU, and every training iteration pays a PCIe round-trip that dominates wall-clock time at scale. XLOG closes that gap: one compiler and one CUDA runtime span four reasoning paradigms — deterministic Datalog, exact and approximate probabilistic inference, epistemic reasoning, and differentiable neural-symbolic training — with SAT/MaxSAT verification available as a shared solver service and zero tracked host–device transfers in production data planes.
Implemented in Rust with custom CUDA kernels, XLOG caches compiled circuits across training
iterations and exposes GPU-resident results as zero-copy DLPack and Arrow C Device
views to PyTorch, JAX, and cuDF; persistent Python relation replacements instead take owned
device-to-device snapshots (Arrow IPC covers host-side interchange). On the MNIST-addition
neural-symbolic benchmark, circuit caching
yields a measured 2.74× end-to-end training speedup (95% CI [2.29, 3.18]) in a
cached-vs-uncached ablation of XLOG's own pipeline, and steady epochs run 2.80× faster than
Scallop at matched accuracy under an identical protocol.
XLOG is not a DSL bolted onto a tensor framework. It is a full typed logic programming language:
- Typed predicates over a closed scalar set (
u32,u64,i32,i64,f32,f64,bool,symbol) with single-pass type inference that rejects ill-typed programs before any GPU kernel runs. - User-defined functions, modules and imports, stratified aggregation, and integrity constraints, so programs decompose cleanly instead of collapsing into flat rule lists.
- One syntax for four paradigms: deterministic rules, probabilistic facts and annotated disjunctions, epistemic operators, and neural predicate declarations (
nn/k) share the same typed language. - Shared solver services: SAT/MaxSAT features and verification use the GPU-resident
GpuCnfrepresentation and CDCL service rather than defining another reasoning paradigm. - GPU-resident semantics: relational operators, circuit evaluation, and verification paths run on the device instead of bouncing through the host.
- A runtime inside your training loop, not a service: CUDA-backed DLPack producers provide zero-copy transient inputs, while DLPack capsules and the Arrow C Device interface expose zero-copy device views of query results and gradients; Arrow IPC handles host-side interchange.
- Neural-symbolic training where the logic structure depends on the program, not on network weights: compiled circuits are cached across iterations, so only weights change, never the DAG.
- Probabilistic reasoning where exact inference benefits from a compile-once, evaluate-many discipline across repeated queries or training loops.
- Graph analytics, program analysis, and recursive queries over device-resident data, with semi-naive fixpoint evaluation and minimal host round-trips.
- Learned-rule induction (differentiable ILP) with GPU-resident credit assignment, sparse candidate masks, and transactional promotion gates.
Create reachability.xlog:
pred edge(u32, u32).
pred reach(u32, u32).
edge(1, 2).
edge(2, 3).
edge(3, 4).
reach(X, Y) :- edge(X, Y).
reach(X, Z) :- reach(X, Y), edge(Y, Z).
?- reach(1, N).Run it:
./target/release/xlog run reachability.xlogExpected output:
__xlog_query_0
+-------+
| col_0 |
+-------+
| 2 |
| 3 |
| 4 |
+-------+
The language reference covers the full surface, and the
examples directory contains annotated programs for lists and meta-predicates,
magic sets, probabilistic aggregates, approximate inference, epistemic reasoning
(examples/epistemic/), and Python neural-symbolic training
(examples/python/).
| Category | Capabilities |
|---|---|
| Datalog core | Rules, facts, recursion (semi-naive fixpoint), stratified negation, aggregation, magic sets, incremental parsing |
| Type system & modules | Typed predicates, user-defined functions, modules with use imports, private visibility, reversible symbols |
| Arithmetic | is expressions, + - * / %, builtins (abs, min, max, pow, cast), if/then/else |
| Lists & meta-predicates | Finite list<T> and term values, safe findall / maplist / term-inspection predicates, deterministic negation-as-failure |
| Aggregation | Head-positional count, sum, min, max, logsumexp, aggregate lifting |
| Probabilistic inference | Exact inference via knowledge compilation (compiling the program to decision-DNNF — a circuit form that turns exact probability into one arithmetic pass — then evaluating it as a GPU arithmetic circuit), Monte Carlo sampling, well-founded-semantics negation, approximate-inference pragmas |
| Epistemic reasoning | Epistemic operators with finite nested modal chains; two selectable semantics — faeel (the default: a fact counts only if the program derives it) and g91 (the classical 1991 reading, which also accepts a self-supporting cycle); Generate-Propagate-Test for acyclic programs; a GPU-backed descending tuple-compatibility fixpoint for supported g91 possible cycles; GPU-backed well-founded evaluation for supported cycles through negation; epistemic splitting; probabilistic epistemic evidence |
| SAT / MaxSAT | GPU CDCL verifier with on-device model and proof validation, MaxSAT, portfolio solving, continuous local search |
| Neural-symbolic training | Neural predicates (nn/k), PyTorch autograd integration, circuit caching across iterations, term embeddings, joint neural + symbolic rule-weight training |
| Rule induction | Differentiable ILP with sparse GPU masks, deterministic mode, promotion pipeline, holdout validation, and bounded exact induction (xlog-induce) with top-K CUDA scoring |
| GPU execution | Custom CUDA kernels for hash joins, radix sort, filter, dedup, union, difference, group-by; worst-case-optimal joins; delta coalescing; runtime CSE; adaptive re-optimization; persistent hash-index reuse |
| Float semantics | IEEE 754 total ordering for f32/f64 (NaN > Inf > nums > +0 > -0 > -Inf) |
| Diagnostics & provenance | Rule and fact provenance, proof traces, planner telemetry, host-transfer audits, module-boundary diagnostics, --stats per-stratum timing and memory accounting |
| Interop | CUDA-backed DLPack producers and capsules, Arrow C Device interface (zero-copy transient/device views; owned device snapshots for persistent Python relations), Arrow IPC (host serialization), PyTorch, JAX, cuDF, Python bindings (pyxlog) |
XLOG programs are typed logic programs. The shared frontend parses and normalizes source into an AST, validates schemas and safety, and analyzes strongly connected components (SCCs) in the dependency graph. Three purpose-built reasoning IRs then fan out from the normalized AST; there is no universal AST-to-RIR lowering step. The execution paths are:
- deterministic RIR evaluation via semi-naive fixpoints (
xlog-runtimeandxlog-gpu); - probabilistic PIR inference via knowledge compilation to device-resident
arithmetic circuits (
xlog-prob); - epistemic EIR dispatch — chosen from the program's dependency shape — to
Generate-Propagate-Test, a founded least fixpoint (
faeel), a descending tuple-compatibility fixpoint (g91), or GPU-backed well-founded evaluation (xlog-logicandxlog-gpu); - differentiable training via PyTorch autograd integration (
xlog-neuralandpyxlog), composing neural predicates with the relevant reasoning IR.
SAT/MaxSAT features and circuit verification use the shared GPU-resident GpuCnf
and CDCL solver service in xlog-solve; the service is not another reasoning IR.
Language features worth naming:
- Reversible symbols provide bidirectional string↔ID mapping, so query output stays human-readable without giving up GPU-friendly dense integer identifiers.
- Stratified aggregation compiles to
GroupByRIR nodes executed as radix-sort-and-reduce kernels. - Integrity constraints are headless rules desugared into auxiliary rules whose output must be empty at evaluation completion.
- Pragma directives influence compiler behavior from within a program.
For the design rationale, see the technical whitepaper.
Public releases of XLOG are supported on Linux x86_64 with an NVIDIA GPU and CUDA Toolkit 13.x:
- Linux
x86_64 nvidia-smisees the GPUnvcc --versionworks- Rust
rustcandcargoare available - Python 3.8 or newer
xlog probhost-readable output requiresxlog-clibuilt withhost-io
Run the doctor first after cloning:
python scripts/xlog_doctor.pygit clone https://github.com/BrainyBlaze/xlog.git
cd xlog
python scripts/xlog_doctor.py
# Recommended: build the CLI with host-readable output enabled.
# Without `host-io`, `xlog prob` cannot print results and fails with
# "Host output is disabled".
cargo build --release -p xlog-cli --features host-io
# Full workspace build (libraries, tests, benches; CLI without host-io):
cargo build --releaseThe release binary is ./target/release/xlog.
Published artifacts correspond to tagged releases. Check the selected artifact's release notes for its API surface; build from source for later source-tree APIs.
Download the Linux x86_64 archive from the GitHub Releases page, unpack it, and run the bundled
xlog binary from the extracted directory. Public release archives are built with host-io, so
xlog prob has host-readable output without a rebuild.
Install the latest published pyxlog wheel from PyPI:
pip install pyxlogpyxlog auto-configures XLOG_CUBIN_DIR from its packaged pyxlog/kernels/ directory when the
wheel includes staged CUDA artifacts. If you are running probe scripts, artifact replays, or
source-tree experiments outside that packaged layout, export XLOG_CUBIN_DIR yourself before
importing pyxlog:
export XLOG_CUBIN_DIR=/path/to/xlog/crates/pyxlog/python/pyxlog/kernelsFor an API present in a source checkout but absent from the selected wheel, use the local development install below.
Install a published CLI crate from crates.io:
cargo install xlog-cli --features host-ioAs with the GitHub and PyPI artifacts, published crate versions correspond to
tagged releases. Their release notes define the included API surface. The
Cargo-installed binary embeds portable PTX for all runtime kernels, so it can run
without a sidecar kernels/ directory. If a staged kernels/ directory or
XLOG_CUBIN_DIR is present, xlog still prefers those filesystem artifacts so
release archives and local builds can use architecture-specific cubins first.
XLOG does not track generated .ptx or .cubin files in git. Kernel artifacts are produced from
kernels/*.cu by the Rust build and are resolved at runtime in this order:
XLOG_CUBIN_DIR- a package- or binary-adjacent
kernels/directory - Cargo build output for source-tree builds
- embedded portable PTX compiled into the Cargo-installed binary
This means cargo install xlog-cli --features host-io works without a sidecar kernels/ directory,
while GitHub release archives and PyPI wheels still ship staged kernel artifacts for faster,
architecture-specific startup when available.
Install into the exact Python interpreter used by your downstream project. Do not rely on bare
maturin develop from the xlog checkout: if this repository has its own .venv, maturin can
install into that environment while your project imports a different Python.
python scripts/install_pyxlog_for_python.py --python /usr/local/bin/python --userThe helper stages CUDA kernels, builds a local wheel for the requested interpreter, installs that
wheel with the same interpreter's pip, and verifies that the installed pyxlog package contains
pyxlog/kernels/.
# Deterministic execution
./target/release/xlog run program.xlog
./target/release/xlog run program.xlog --output csv
./target/release/xlog run program.xlog --output arrow --output-dir ./results
# External data (Arrow IPC)
./target/release/xlog run program.xlog --input edge=graph.arrow
# Probabilistic execution
./target/release/xlog prob program.xlog --prob-engine exact_ddnnf
./target/release/xlog prob program.xlog --prob-engine mc --samples 10000 --seed 42
# Profiling
./target/release/xlog run program.xlog --stats
./target/release/xlog run program.xlog --stats --stats-format json
# Explain diagnostics
./target/release/xlog explain program.xlog
./target/release/xlog explain --format json program.xlog
./target/release/xlog run --helpSee the CLI reference for the complete flag reference.
The documentation website is xlog.md. Key references in this repository:
| Document | Scope |
|---|---|
| Whitepaper (PDF) | Primary technical reference: language, architecture, probabilistic inference, epistemic reasoning, neural-symbolic bridge, evaluation, and related work |
| Language reference | Full language surface: types, predicates, rules, modules, UDFs, aggregations, pragmas |
| Architecture | System design, crate structure, IR layers, GPU execution model |
| Benchmarks | Performance methodology and benchmark artifacts |
| Probabilistic tier | Exact knowledge compilation and Monte Carlo inference |
| Solver services | GPU CDCL verifier, SAT/MaxSAT services, workspace arena reuse |
| Differentiable ILP training | Trainer architecture and the GPU hot-loop contract |
| Exact induction | End-to-end rule-induction training results |
| WCOJ architecture guide | Worst-case-optimal joins: RIR, promoter, dispatch, cost model, recursive integration |
| WCOJ user guide | Eligibility, fallback behavior, performance tuning, troubleshooting |
| CLI reference | Full flag and subcommand reference |
| Arrow / DLPack interop | Zero-copy transient and result handoff, owned persistent relation snapshots, and Arrow IPC interchange with cuDF, PyTorch, and JAX |
| Python bindings | pyxlog API surface |
| CUDA certification | Kernel certification suite coverage |
| Roadmap | Feature status and planned work |
| Examples | Annotated programs: basics, arithmetic, graphs, aggregations, probabilistic, epistemic, and neural |
xlog/
├── crates/
│ ├── xlog-core/ # Foundation types and traits
│ ├── xlog-ir/ # Intermediate representations (RIR nodes)
│ ├── xlog-logic/ # Language frontend: parser, stratifier, lowerer, optimizer
│ ├── xlog-runtime/ # Deterministic query executor
│ ├── xlog-cuda/ # GPU kernels and memory management
│ ├── xlog-stats/ # Runtime statistics and optimizer feedback
│ ├── xlog-prob/ # Probabilistic inference (exact + MC)
│ ├── xlog-neural/ # Neural-symbolic integration
│ ├── xlog-solve/ # SAT/MaxSAT solver services
│ ├── xlog-gpu/ # High-level Rust API
│ ├── xlog-induce/ # Native exact-induction engine and scorer
│ ├── pyxlog/ # Python bindings + training API
│ ├── xlog-cli/ # Command-line interface
│ └── xlog-cuda-tests/ # CUDA certification suite
├── kernels/ # CUDA kernel sources (.cu)
├── examples/ # Example .xlog programs + Python neural-symbolic demos
├── docs/ # Documentation site source (published to xlog.md)
└── paper/ # Technical whitepaper (LaTeX source)
# Full test suite (release mode recommended for GPU tests)
cargo test --workspace --all-targets --exclude pyxlog --release
# CUDA certification suite only
cargo test -p xlog-cuda-tests --test certification_suite --release
# Canonical manual GPU release validation
bash scripts/validate_release_gpu.sh --mode release
# Run an example program
cargo run -p xlog-cli --release -- run examples/xlog/00-basics/01_tc_reachability.xlogContributions are welcome. Please read CONTRIBUTING.md and the
architecture overview first for the crate layout and
layering rules, and run cargo fmt plus cargo clippy --all-targets -- -D warnings before
submitting.
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
XLOG builds on research in logic programming languages, GPU-accelerated Datalog, probabilistic logic programming, and neural-symbolic AI. Primary influences:
- Prolog (SWI-Prolog) and Mercury — typed logic programming traditions
- Souffle — typed Datalog with ahead-of-time compilation
- GPUlog — HISA indexing and parallel fixpoint on GPU
- VFLog — columnar GPU Datalog
- ProbLog and DeepProbLog — probabilistic logic programming and neural-symbolic integration
- d4 — decision-DNNF compilation reference