PyNeuraLogic: Differentiable Logic Programs as a GNN Replacement
PyNeuraLogic lets you use Python to create Differentiable Logic Programs
At a glance
- What is it?
- PyNeuraLogic is a Python library that turns logic rules into differentiable computation graphs, so a propagation rule you write as text becomes a trainable neural layer. It is a research-grade tool for relational learning, not a drop-in replacement for PyTorch Geometric.
- Who is it for?
- Adopt PyNeuraLogic if your model is naturally expressed as relations and rules rather than as fixed tensor operations, and if you are willing to read the documentation and the linked papers before writing code. Do not adopt it if you need a large ecosystem of pretrained models, a stable class-based API, or a team that already knows PyTorch Geometric.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem PyNeuraLogic solves: rules instead of layer classes
In a standard graph neural network library you express a model by composing layer classes. A message passing layer is a class, a pooling operation is a class, and a small change to the propagation scheme usually means writing a new class or subclassing an existing one. PyNeuraLogic takes the opposite approach. You declare logical variables and relations, compose them into rules, and the library compiles that rule set into a differentiable computation graph. The README states that this inference process is equivalent to forward propagation in deep learning, so numeric parameters attached to rules are learned the same way weights are learned in a neural network. The audience is therefore narrow and specific: researchers and engineers who already think in terms of relations, who want to try propagation schemes that do not map cleanly onto existing GNN layers, and who are comfortable reading a paper to understand a tool. The README points to relational pattern matching, hypergraphs, nested graphs, relational databases, and inclusion of logical background knowledge as things that fit naturally. If your work is standard node classification on a citation graph, this is more machinery than you need.
How a rule becomes a differentiable graph
The mechanism is visible in the README's GNN example. A propagation rule is written as a logic clause: R.msg2(Var.X) <= (R.msg1(V.Y), R.edge(V.Y, V.X)). The left side is the head, the right side is the body. The body says that the representation of node X is computed from the representation of an adjacent node Y and the edge relation between Y and X. Weights are attached by annotating the relation with a shape. R.msg2(Var.X)[5,10] <= (R.msg1(V.Y)[10,20], R.edge(V.Y, V.X)) projects a [20,1] input embedding through a learnable [10,20] layer before aggregation, then a [5,10] layer after it. Aggregation and activation are selected with a trailing annotation: (R.msg2(V.X)[5,10] <= (R.msg1(V.Y)[10,20], R.edge(V.Y, V.X))) | [Transformation.RELU, Aggregation.AVG], which the README identifies as the classic GCN layer specification. The mermaid diagram in the README shows what the backend builds from this: one rule neuron per matching edge, each weighted, each passed through ReLU, then averaged by an aggregation neuron, then passed through a second weight to an output neuron with a tanh activation. The README says the backend engine creates these computation graphs in a fully automated and dynamic fashion, which is the key architectural claim. You do not align tensors by hand. The cost is that the graph is built at runtime from the rule set, so the shape of the computation depends on the data instance rather than on a static declaration.
Installation and the first runnable rule
The README does not include an installation command, but the PyPI badge points at the package name neuralogic, so the conventional install is pip install neuralogic. Treat that as an inference from the badge rather than a quoted instruction, and confirm it against the documentation before scripting it into a build. The README also does not give a complete runnable script. It gives rule fragments and links to the documentation at pyneuralogic.readthedocs.io, including a language reference page and a database deep learning tutorial. The fragments use a logtalk code fence and reference symbols such as Var.X, R.edge, Transformation.RELU, and Aggregation.AVG. Those are the config-level names you will need to import or alias in Python. The README does not show the import lines, the dataset loading calls, or the training loop, so the first hour with this library is documentation reading, not copy-pasting. That is a real friction point and worth budgeting for. The releases page shows v0.9.2 in August 2026, v0.9.1 two weeks earlier, and v0.9.0 in June 2026, so the project is on a fast minor-version cadence and the API surface is still moving.
The performance claim and what it does not cover
The README states that for a range of common GNN models and applications, such as learning with molecules, PyNeuraLogic is considerably faster than the popular GNN frameworks, and links to a benchmarks page with a chart. That is the project's own claim, and the README does not describe the hardware, the baseline versions, or the datasets behind the chart. You should read the benchmarks page itself before repeating the claim internally. More importantly, the README says the framework does not come at the cost of performance for basic GNNs, which is a narrower statement than it first appears. It is a claim about parity or better on common models, not a claim that the general relational machinery is free. A rule set with many relations and object types will produce a different computation graph than a fixed GCN layer, and nothing in the README quantifies that case. The honest reading is that the expressiveness is the product and the performance claim is a supporting argument for the subset of models the authors benchmarked.
Where PyNeuraLogic is the wrong tool
The clearest limitation is the one the README states as a virtue: the backend builds computation graphs dynamically, from the rule set, at runtime. Dynamic graph construction means the work of planning the computation happens per input rather than once at model definition time. For small relational datasets, such as molecules, that is the intended use. For a large homogeneous graph where a fixed two-layer message passing network would do, you are paying for a general engine to solve a problem that has a direct tensor implementation. The second limitation is the API surface. The README explicitly contrasts PyNeuraLogic with frameworks that offer a zoo of blackbox class names, and presents coding at the level of logical principles as the alternative. That is a genuine design position, but it means there is no catalogue of ready-made layers to import. You write the rule. The third is documentation shape: the README gives fragments, not runnable programs, and the fuller material lives in a ReadTheDocs site plus linked papers. A team without anyone willing to read the language reference will stall. Finally, the version numbering is still 0.9.x, and the three most recent releases are all within roughly three months of each other. Plan for upgrades that change behaviour.
How it differs from PyTorch Geometric
PyTorch Geometric is the obvious comparison and the difference is structural, not cosmetic. In PyTorch Geometric you pick a convolution class such as GCNConv, wire it into a module, and the message passing scheme is fixed by that class. Changing the aggregation means changing the class or its arguments. In PyNeuraLogic the message passing scheme is the rule text, and the aggregation is an annotation on that rule, as in the Aggregation.AVG example. The practical consequence is that a novel propagation scheme which would require a new PyTorch Geometric layer is a one-line edit here. The reverse consequence is that PyTorch Geometric gives you a large library of implemented layers, standard dataset loaders, and a community whose examples you can copy. PyNeuraLogic gives you a smaller, more abstract surface and expects you to build the model from rules. Neither is better in the abstract. If your model is a known GNN variant, PyTorch Geometric is the shorter path. If your model is a relational program that happens to include a GNN as a special case, PyNeuraLogic is the one that matches the shape of the problem. The README makes this point directly when it notes that a graph is a special case of a binary logical relation.
Maintenance, licence, and upgrade exposure
The licence is MIT, which is permissive and places few restrictions on use and modification. That covers the PyNeuraLogic repository. The README states that the differentiable inference is provided through a separate NeuraLogic backend repository, and it does not state that backend's licence. If you plan to redistribute anything, check the backend's licence separately rather than assuming MIT covers the whole stack. On maintenance, the release history shows v0.9.0, v0.9.1, and v0.9.2 within about three months, and the last push to the default branch is dated the same period. A fast 0.9.x cadence usually means the maintainers are still settling the API, so pin your dependency to an exact version in requirements or pyproject rather than using a range, and read the release notes before moving between minor versions. The README does not describe a deprecation policy or a compatibility guarantee, so treat each minor bump as potentially breaking until you have checked. There is also no stated support window, which matters if you are building something you intend to keep running for years.
Editorial conclusion
Adopt PyNeuraLogic if your model is naturally expressed as relations and rules rather than as fixed tensor operations, and if you are willing to read the documentation and the linked papers before writing code. Do not adopt it if you need a large ecosystem of pretrained models, a stable class-based API, or a team that already knows PyTorch Geometric. Verify first that the rule you want to write actually compiles: the aggregation and activation annotations, the weight shape syntax such as [5,10], and the exact import path for the LiftedRule or template helpers are the parts most likely to differ from what you expect. The MIT licence means you can read and modify the source, but the backend is a separate repository with its own licensing, so check that before any commercial redistribution.
Community notes