qpe-zig

Qualitative Process Engine (Forbus 1984) — qualitative-physics scenario builder, upstream of the QRG-stack.

A single-binary AGPL-3.0 implementation of the Qualitative Process Engine (Forbus 1984) in Zig.

QRG-stack lineage

flowchart LR
    A[Physical scenario] --> B[qpe-zig<br/>Qualitative Process Engine]
    B --> C[Structured representation]
    C --> D[mac-fac-vector<br/>MAC/FAC retrieval]
    D --> E[Base description]
    E --> F[sme-zig<br/>Structure-Mapping Engine]
    F --> G[Analogical mapping]

    click B "https://github.com/SMC17/qpe-zig" "qpe-zig"
    click D "https://github.com/SMC17/mac-fac-vector" "mac-fac-vector"
    click F "https://github.com/SMC17/sme-zig" "sme-zig"

    style B fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style D fill:#fef3c7,stroke:#d97706,color:#92400e
    style F fill:#fce7f3,stroke:#db2777,color:#9d174d

Loading

qpe-zig is the upstream node of the QRG-stack triangle: it consumes a declarative description of a physical situation written in QPF (a KRF-based DSL) and produces the structured qualitative-physics representations that downstream analogical-reasoning systems consume.

What ships

Component	Proof level
QPT algorithm spec (spec/QPT_ALGORITHM.md)	sketch
QPF DSL spec (spec/QPF_FORMAT.md)	sketch
KRF lexer + s-expr + parser	unit-tested
QPF model loader	unit-tested
Phase 1 — Process compilation	integration-tested
Single-binary, libc-only runtime gate	verified (ldd)

Gate	Result
Internal correctness (zig build test)	25/25 unit tests pass
Integration script (scripts/integration_test.sh)	3/3 canonical scenarios parse + Phase 1 enumerates ≥1 PI each
Runtime dependencies	libc only

Proof vocabulary (sketch, unit-tested, integration-tested) follows the repository's harness conventions. This is pre-1.0 substrate.

What does NOT ship yet

Component	Status
Phase 2 — Influence resolution	not started
Phase 3 — Limit analysis	not started
Phase 4 — Envisionment construction	not started
ATMS backend (Forbus 1988)	not started
Reference-output capture vs QPE v4	not started

The pre-registered falsifier exp-1779411744 triggers on Phase-4 envisionment correctness against captured QPE v4 reference output. That gate is not yet runnable; it gates Phases 2-4 + reference capture. No claim of envisionment correctness is made.

What QPE computes

A Qualitative Process Engine takes as input a description of a physical situation expressed in five vocabulary primitives (Forbus 1984 §2-3):

• Individuals — typed things in the world (water-in-kettle, kettle, room-air).
• Individual views — parametrized state descriptors that apply to one or more individuals ((is-liquid water-in-kettle)).
• Quantities — measurable continuous parameters, each with a magnitude in {Q-, Q0, Q+} and a derivative in {D-, D0, D+}.
• Processes with five slots: pattern of individuals, preconditions (assumption-based), quantity-conditions (numeric comparisons), relations that become true when active, and influences (direct I+/I- or indirect functional Q+/Q-).
• Limit hypotheses — candidate state transitions when a quantity reaches a limit value (e.g. boiling-point reached).

It produces:

• an envisionment graph — qualitative states reachable from the initial scenario and the transitions between them, each transition justified by the limit hypothesis that fired;
• a per-state influence summary for every quantity; and
• (under the ATMS backend, planned per Forbus 1988) a justification graph for every conclusion, with contradiction-driven pruning of inconsistent assumption sets.

The four phases

Specified in spec/QPT_ALGORITHM.md; currently shipped:

1. Phase 1 — Process compilation. For each process definition, enumerate every binding of its individuals slot against the current population, with type filtering. **(Shipped; 3 unit tests
   • integration gate over all 3 canonical scenarios.)**
2. Phase 2 — Influence resolution. Check quantity-conditions; for each quantity, sum the direct influences contributed by active PIs to derive the qualitative derivative. (Not started.)
3. Phase 3 — Limit analysis. For each quantity with a non-zero derivative, identify reachable limit values and emit limit hypotheses. (Not started.)
4. Phase 4 — Envisionment construction. Drive states forward by firing limit hypotheses, re-running Phases 1-3 in each successor state, deduplicating by canonical state signature, until the graph closes. (Not started.)

Quickstart

zig build -Doptimize=ReleaseFast       # produces zig-out/bin/qpe-zig
zig-out/bin/qpe-zig parse   corpus/canonical/01-boiling-water.qpf
zig-out/bin/qpe-zig compile corpus/canonical/01-boiling-water.qpf
./scripts/integration_test.sh          # build + libc gate + parse + Phase 1

Current Phase-1 enumerations:

Scenario	Individuals	PIs
01 boiling-water	5	22
02 falling-with-drag	1	2
03 heat-flow between two blocks	3	6

Layout

spec/      English-language algorithm + DSL specifications
corpus/    Canonical QP scenarios in QPF (.qpf) form
bench/     Benchmark protocol (planned)
reference/ Bibliography + reference-output captures (planned)
scripts/   Integration test + planned QPE v4 baseline capture
src/       Zig source (KRF substrate + QPF loader + Phase 1)

Citations

• Forbus, K. D. (1984). "Qualitative process theory." Artificial Intelligence 24:85-168. — the foundational paper; defines processes, individual views, quantities, influences (I+/I-/Q+/Q-), limit analysis, envisionment. (Canonical for this layer.)
• Forbus, K. D. (1988). "QPE: Using assumption-based truth maintenance for qualitative simulation." International Journal for Artificial Intelligence in Engineering. — describes the QPE implementation with an ATMS backend.
• Forbus, K. D. (1993). "Qualitative process theory: Twelve years after." Artificial Intelligence 59:115-123.
• Forbus, K. D. (2018). Qualitative Representations: How People Reason and Learn About the Continuous World. MIT Press.
• Forbus, K. D., Gentner, D., & Law, K. (1995). "MAC/FAC: A model of similarity-based retrieval." Cognitive Science 19(2):141-205. (Companion paper for the downstream mac-fac-vector layer.)
• Falkenhainer, B., Forbus, K. D., & Gentner, D. (1989). "The structure-mapping engine: Algorithm and examples." Artificial Intelligence 41:1-63. (Companion paper for the terminal sme-zig layer.)

See reference/SOURCES.md for the full bibliography.

Companion lanes

• qpe-zig — Qualitative Process Engine (this repo, upstream layer)
• mac-fac-vector — MAC/FAC retrieval
• sme-zig — Structure-Mapping Engine

The three together (qpe → mac-fac → sme) reproduce the canonical qualitative-reasoning / analogy pipeline as license-clean, auditable, single-binary substrate.

Non-claims

• No claim of envisionment correctness — Phases 2-4 not implemented.
• No claim of ATMS-backed contradiction-driven pruning — backend not started.
• No claim of reference-equivalence with QPE v4 — capture not performed.
• No claim of throughput superiority over QPE v4 — no comparable benchmark.
• No "production-grade" or v1.x claim — pre-1.0 substrate.

Why this exists

Qualitative physics gives a small, auditable, license-clean substrate for causal reasoning about continuous systems — the kind of reasoning frontier models still demonstrably struggle with on process-and-mechanism tasks. The algorithms were specified in 1984-1988 and refined for forty years; the original QPE Lisp source remains available via QRG's sme4 distribution. Re-implementing the engine as a single-binary, libc-only Zig program makes it usable as a component in modern pipelines, including the qpe → mac-fac → sme retrieval-and-mapping flow this repo is the head of.

License

AGPL-3.0-only. See LICENSE. Inbound = outbound per CONTRIBUTING.md.