atsds-egg 0.0.11

package/README.md

@@ -0,0 +1,143 @@
+# E-Graph Support Package for DS
+
+An E-Graph (Equality Graph) implementation for the DS deductive system, providing efficient management and manipulation of equivalence classes of terms.
+
+This package implements the egg-style E-Graph data structure with deferred congruence closure, enabling efficient equality reasoning. Inspired by the [egg library](https://egraphs-good.github.io/).
+
+## Features
+
+- **E-Graph Data Structure**: Manage equivalence classes of terms efficiently
+- **Union-Find**: Path-compressed union-find for disjoint set management
+- **Congruence Closure**: Automatic maintenance of congruence relationships
+- **Deferred Rebuilding**: egg-style deferred rebuilding for performance
+- **Python Integration**: Seamless integration with apyds terms
+- **Type-Safe**: Full type hints for Python 3.11+
+
+## Installation
+
+### Python (pip)
+
+```bash
+pip install apyds-egg
+```
+
+Requires Python 3.11-3.14.
+
+## Quick Start
+
+### Python Example
+
+```python
+import apyds
+from apyds_egg import EGraph
+
+# Create an E-Graph
+eg = EGraph()
+
+# Add terms to the E-Graph
+a = eg.add(apyds.Term("a"))
+b = eg.add(apyds.Term("b"))
+x = eg.add(apyds.Term("x"))
+
+# Add compound terms
+ax = eg.add(apyds.Term("(+ a x)"))
+bx = eg.add(apyds.Term("(+ b x)"))
+
+# Initially, (+ a x) and (+ b x) are in different E-classes
+assert eg.find(ax) != eg.find(bx)
+
+# Merge a and b
+eg.merge(a, b)
+
+# Rebuild to restore congruence
+eg.rebuild()
+
+# Now (+ a x) and (+ b x) are in the same E-class
+assert eg.find(ax) == eg.find(bx)
+```
+
+## Core Concepts
+
+### E-Graph
+
+An E-Graph is a data structure that efficiently represents and maintains equivalence classes of terms. It consists of:
+
+- **E-Nodes**: Nodes representing terms with an operator and children
+- **E-classes**: Equivalence classes of E-Nodes
+- **Union-Find**: Data structure for managing E-class equivalence
+- **Congruence**: Two terms are congruent if they have the same operator and their children are in equivalent E-classes
+
+### Congruence Closure
+
+The E-Graph maintains congruence closure automatically. When two E-classes are merged, the E-Graph rebuilds to ensure that congruent terms remain in the same E-class:
+
+```python
+eg = EGraph()
+
+# Add terms
+fa = eg.add(apyds.Term("(f a)"))
+fb = eg.add(apyds.Term("(f b)"))
+
+# Merge a and b
+a = eg.add(apyds.Term("a"))
+b = eg.add(apyds.Term("b"))
+eg.merge(a, b)
+
+# Rebuild maintains congruence
+eg.rebuild()
+
+# Now (f a) and (f b) are equivalent
+assert eg.find(fa) == eg.find(fb)
+```
+
+## API Overview
+
+### EGraph
+
+- `__init__()`: Create a new E-Graph
+- `add(term: apyds.Term) -> EClassId`: Add a term to the E-Graph
+- `merge(a: EClassId, b: EClassId) -> EClassId`: Merge two E-classes
+- `rebuild() -> None`: Restore congruence closure
+- `find(eclass: EClassId) -> EClassId`: Find canonical E-class representative
+
+## Building from Source
+
+### Prerequisites
+
+- Python 3.11-3.14
+- apyds package
+
+### Python Package
+
+```bash
+cd egg
+
+# Install dependencies
+uv sync --extra dev
+
+# Build package
+uv build
+
+# Run tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov
+```
+
+## License
+
+This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
+
+## Repository
+
+- **GitHub**: [USTC-KnowledgeComputingLab/ds](https://github.com/USTC-KnowledgeComputingLab/ds) (in `/egg` directory)
+- **Python Package**: [apyds-egg](https://pypi.org/project/apyds-egg/)
+
+## Author
+
+Hao Zhang <hzhangxyz@outlook.com>
+
+## Related
+
+This package is a support library for the [DS (Deductive System)](https://github.com/USTC-KnowledgeComputingLab/ds) project. For the main DS library with C++ core and bindings, see the [main repository](https://github.com/USTC-KnowledgeComputingLab/ds).

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+import { Term } from 'atsds';
+
+/**
+ * E-Graph implementation for atsds (TypeScript version)
+ * E-Graph (Equality Graph) for representing equivalence classes of terms.
+ */
+
+type EClassId = number & {
+    __brand: "EClassId";
+};
+declare class DefaultMap<K, V> extends Map<K, V> {
+    private readonly factory;
+    constructor(factory: () => V);
+    get(key: K): V;
+}
+declare class UnionFind<T> {
+    /**
+     * Union-find data structure for managing disjoint sets.
+     */
+    parent: Map<T, T>;
+    constructor();
+    /**
+     * Find the canonical representative of x's set with path compression.
+     * @param x - The element to find.
+     * @returns The canonical representative of x's set.
+     */
+    find(x: T): T;
+    /**
+     * Union two sets and return the canonical representative.
+     * @param a - The first element.
+     * @param b - The second element.
+     * @returns The canonical representative of the merged set.
+     */
+    union(a: T, b: T): T;
+}
+/**
+ * ENode - Node in the E-Graph with an operator and children.
+ */
+declare class ENode {
+    op: string;
+    children: EClassId[];
+    /**
+     * @param op - The operator
+     * @param children - The children E-class IDs
+     */
+    constructor(op: string, children: EClassId[]);
+    /**
+     * Canonicalize children using the find function.
+     * @param find - Function to find the canonical E-class ID.
+     * @returns A new ENode with canonicalized children.
+     */
+    canonicalize(find: (id: EClassId) => EClassId): ENode;
+    /**
+     * Get a string key representation for this ENode for use in Maps/Objects.
+     * @returns A unique string representation of this ENode.
+     */
+    key(): string;
+}
+/**
+ * EGraph - E-Graph for representing equivalence classes of terms.
+ */
+declare class EGraph {
+    private next_id;
+    private hashcons;
+    private unionfind;
+    private classes;
+    private parents;
+    private worklist;
+    /**
+     * Generate a fresh E-class ID.
+     * @returns A new E-class ID.
+     */
+    private freshId;
+    /**
+     * Find the canonical representative of an E-class.
+     * @param eclass - The E-class ID to find.
+     * @returns The canonical E-class ID.
+     */
+    find(eclass: EClassId): EClassId;
+    /**
+     * Add a term to the E-Graph and return its E-class ID.
+     * @param term - An atsds Term to add to the E-Graph.
+     * @returns The E-class ID for the added term.
+     */
+    add(term: Term): EClassId;
+    /**
+     * Convert an atsds Term to an ENode.
+     * @param term - The Term to convert.
+     * @returns The converted ENode.
+     */
+    private termToEnode;
+    /**
+     * Add an ENode to the E-Graph.
+     * @param enode - The ENode to add.
+     * @returns The E-class ID for the added ENode.
+     */
+    private addEnode;
+    /**
+     * Merge two E-classes and defer congruence restoration.
+     * @param a - The first E-class ID to merge.
+     * @param b - The second E-class ID to merge.
+     * @returns The canonical E-class ID of the merged class.
+     */
+    merge(a: EClassId, b: EClassId): EClassId;
+    /**
+     * Restore congruence by processing the worklist.
+     */
+    rebuild(): void;
+    /**
+     * Restore congruence for a single E-class.
+     */
+    private repair;
+}
+
+export { DefaultMap, EGraph, ENode, UnionFind };
+export type { EClassId };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{List as t}from"atsds";class s extends Map{factory;constructor(t){super(),this.factory=t}get(t){return this.has(t)||this.set(t,this.factory()),super.get(t)}}class e{parent;constructor(){this.parent=new Map}find(t){return this.parent.has(t)||this.parent.set(t,t),this.parent.get(t)!==t&&this.parent.set(t,this.find(this.parent.get(t))),this.parent.get(t)}union(t,s){const e=this.find(t),n=this.find(s);return e!==n&&this.parent.set(n,e),e}}class n{op;children;constructor(t,s){this.op=t,this.children=s}canonicalize(t){return new n(this.op,this.children.map(s=>t(s)))}key(){return`${this.op}(${this.children.join(",")})`}}class i{next_id=0;hashcons=new Map;unionfind=new e;classes=new s(()=>new Set);parents=new s(()=>new Set);worklist=new Set;freshId(){const t=this.next_id;return this.next_id+=1,t}find(t){return this.unionfind.find(t)}add(t){const s=this.termToEnode(t);return this.addEnode(s)}termToEnode(s){const e=s.term();if(e instanceof t){const t=[];for(let s=0;s<e.length();s++){const n=e.getitem(s),i=this.add(n);t.push(i)}return new n("()",t)}return new n(s.toString(),[])}addEnode(t){const s=(t=t.canonicalize(this.find.bind(this))).key(),e=this.hashcons.get(s);if(e)return this.find(e[1]);const n=this.freshId();this.hashcons.set(s,[t,n]),this.unionfind.parent.set(n,n),this.classes.get(n).add(t);for(const s of t.children)this.parents.get(s).add([t,n]);return n}merge(t,s){const e=this.find(t),n=this.find(s);if(e===n)return e;const i=this.unionfind.union(e,n);for(const t of this.classes.get(n))this.classes.get(i).add(t);this.classes.delete(n);for(const t of this.parents.get(n))this.parents.get(i).add(t);return this.parents.delete(n),this.worklist.add(i),i}rebuild(){for(;this.worklist.size>0;){const t=new Set(Array.from(this.worklist).map(t=>this.find(t)));this.worklist.clear();for(const s of t)this.repair(s)}}repair(t){const s=new Map;for(const[e,n]of this.parents.get(t)){this.hashcons.delete(e.key());const t=e.canonicalize(this.find.bind(this)),i=t.key(),r=this.find(n);s.has(i)?this.merge(r,s.get(i)[1]):(s.set(i,[t,r]),this.hashcons.set(i,[t,r]))}this.parents.get(t).clear();for(const[e,n]of s)this.parents.get(t).add(n)}}export{s as DefaultMap,i as EGraph,n as ENode,e as UnionFind};

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "atsds-egg",
+    "description": "E-Graph implementation for atsds",
+    "author": "Hao Zhang <hzhangxyz@outlook.com>",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/USTC-KnowledgeComputingLab/ds.git",
+        "directory": "egg"
+    },
+    "type": "module",
+    "exports": "./dist/index.mjs",
+    "main": "dist/index.mjs",
+    "module": "dist/index.mjs",
+    "browser": "dist/index.mjs",
+    "types": "dist/index.d.mts",
+    "files": [
+        "dist/index.d.mts",
+        "dist/index.mjs"
+    ],
+    "scripts": {
+        "build": "rollup --config rollup.config.mjs",
+        "test": "cross-env NODE_OPTIONS='$NODE_OPTIONS --experimental-vm-modules' jest --config=jest.config.mjs",
+        "all": "run-s build test"
+    },
+    "dependencies": {
+        "atsds": "^0.0.11"
+    },
+    "devDependencies": {
+        "@rollup/plugin-terser": "^0.4.4",
+        "@rollup/plugin-typescript": "^12.3.0",
+        "@types/jest": "^30.0.0",
+        "cross-env": "^10.1.0",
+        "jest": "^30.2.0",
+        "npm-run-all": "^4.1.5",
+        "rollup": "^4.54.0",
+        "rollup-plugin-dts": "^6.3.0",
+        "ts-jest": "^29.4.6",
+        "tslib": "^2.8.1",
+        "typescript": "^5.9.3"
+    },
+    "version": "0.0.11"
+}