pijl 0.1.0__tar.gz

pijl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moxxie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pijl-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: pijl
+Version: 0.1.0
+Summary: A visual logic circuit editor and simulator
+Keywords: logic,circuit,simulator,digital,gates
+Author: moxxie
+Author-email: moxxie <moxxie@knolastna.me>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: pyglet>=2.1.16
+Requires-Dist: scipy>=1.17.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/voxathon/pijl
+Project-URL: Repository, https://github.com/voxathon/pijl
+Project-URL: Issues, https://github.com/voxathon/pijl/issues
+Description-Content-Type: text/markdown
+
+# pijl
+
+A visual logic circuit editor and simulator. Place gates, draw wires, and
+package circuits into reusable macros.
+
+## Install
+
+```bash
+uv tool install pijl
+```
+
+or with pip:
+
+```bash
+pip install pijl
+```
+
+## Run
+
+```bash
+pijl
+```
+
+On Windows, `pijl-gui` launches the editor without a console window.
+
+Projects are saved under `%APPDATA%\pijl` on Windows (set `PIJL_DATA` to use a
+different location).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run pijl
+```
+
+## License
+
+MIT

pijl-0.1.0/README.md

@@ -0,0 +1,39 @@
+# pijl
+
+A visual logic circuit editor and simulator. Place gates, draw wires, and
+package circuits into reusable macros.
+
+## Install
+
+```bash
+uv tool install pijl
+```
+
+or with pip:
+
+```bash
+pip install pijl
+```
+
+## Run
+
+```bash
+pijl
+```
+
+On Windows, `pijl-gui` launches the editor without a console window.
+
+Projects are saved under `%APPDATA%\pijl` on Windows (set `PIJL_DATA` to use a
+different location).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run pijl
+```
+
+## License
+
+MIT

pijl-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "pijl"
+version = "0.1.0"
+description = "A visual logic circuit editor and simulator"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "logic",
+    "circuit",
+    "simulator",
+    "digital",
+    "gates",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+]
+dependencies = [
+    "numpy>=2.5.3",
+    "pyglet>=2.1.16",
+    "scipy>=1.17.0",
+]
+
+[[project.authors]]
+name = "moxxie"
+email = "moxxie@knolastna.me"
+
+[project.urls]
+Homepage = "https://github.com/voxathon/pijl"
+Repository = "https://github.com/voxathon/pijl"
+Issues = "https://github.com/voxathon/pijl/issues"
+
+[project.scripts]
+pijl = "pijl:main"
+
+[project.gui-scripts]
+pijl-gui = "pijl:main"
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

pijl-0.1.0/pyproject.toml.orig

@@ -0,0 +1,45 @@
+[project]
+name = "pijl"
+version = "0.1.0"
+description = "A visual logic circuit editor and simulator"
+readme = "README.md"
+authors = [
+    { name = "moxxie", email = "moxxie@knolastna.me" }
+]
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["logic", "circuit", "simulator", "digital", "gates"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+]
+dependencies = [
+    "numpy>=2.5.3",
+    "pyglet>=2.1.16",
+    "scipy>=1.17.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/voxathon/pijl"
+Repository = "https://github.com/voxathon/pijl"
+Issues = "https://github.com/voxathon/pijl/issues"
+
+[project.scripts]
+pijl = "pijl:main"
+
+[project.gui-scripts]
+pijl-gui = "pijl:main"
+
+[build-system]
+requires = ["uv_build>=0.12.20,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

pijl-0.1.0/src/pijl/__init__.py

@@ -0,0 +1,4 @@
+def main() -> None:
+    from .ui import run
+
+    run()

pijl-0.1.0/src/pijl/macros.py

@@ -0,0 +1,129 @@
+"""Macros as part types: what lets a saved board be placed on another board.
+
+A MacroType is built from a macro's saved board (its body). Its pins are the
+body's IN / OUT ports, top to bottom by position (ties: left to right, then
+uid). A pin is *identified* by its port's uid (that's what save files use, so
+moving ports around inside a macro never rewires the boards using it); its
+index only says where it's drawn. A port's label is the pin's name; unlabeled
+ones are numbered by position.
+
+The circuit never evaluates a macro: it expands the body into hidden parts and
+joins the nets through the ports (see Circuit._expand). So a macro costs exactly
+what its gates cost and adds no delay.
+
+MacroBook loads definitions on demand and caches them. A macro that (directly or
+through others) contains itself can't load; it shows up as a missing kind.
+Catalog is what the circuit and the file format look kinds up in: part scripts
+plus macros.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from .parts import Look, PartType, Registry
+from .snapshot import MACRO, Snapshot
+
+
+class CycleError(KeyError):
+    """A macro that contains itself."""
+
+
+class MacroType(PartType):
+    def __init__(self, name: str, body: Snapshot, catalog: Catalog) -> None:
+        self.name = name
+        self.kind = MACRO + name
+        self.title = name
+        self.body = body
+        self.look = Look(label="below", swatch="MACRO_SWATCH", body="MACRO_BODY", pin_labels=True)
+        # Every kind inside must exist (KeyError / CycleError otherwise): a body that
+        # can't be built fully isn't a macro that can be placed.
+        types = {uid: catalog.get(d[0]) for uid, d in body.parts.items()}
+        self.in_ids = _ports(body, types, "in")
+        self.out_ids = _ports(body, types, "out")
+        self.ins = _names(body, self.in_ids)
+        self.outs = _names(body, self.out_ids)
+        # the macros used directly in the body
+        self.uses = frozenset(d[0][len(MACRO):] for d in body.parts.values() if d[0].startswith(MACRO))
+
+
+def _ports(body: Snapshot, types: dict[int, PartType], side: str) -> tuple[int, ...]:
+    """Uids of the body's ports on one side, top to bottom (world y points up)."""
+    found = [(uid, d) for uid, d in body.parts.items() if types[uid].port == side]
+    found.sort(key=lambda item: (-item[1][3], item[1][2], item[0]))
+    return tuple(uid for uid, _ in found)
+
+
+def _names(body: Snapshot, ids: tuple[int, ...]) -> tuple[str, ...]:
+    return tuple(body.parts[uid][1] or str(i + 1) for i, uid in enumerate(ids))
+
+
+class MacroBook:
+    """Macro definitions by name, loaded when first needed. `load(name)` gives a
+    macro's body Snapshot, or raises (KeyError / OSError / ValueError) if it can't."""
+
+    def __init__(self, catalog: Catalog, load: Callable[[str], Snapshot]) -> None:
+        self.catalog = catalog
+        self.load = load
+        self._types: dict[str, MacroType] = {}
+        self._loading: list[str] = []  # names being loaded right now (a repeat means a cycle)
+
+    def get(self, name: str) -> MacroType:
+        t = self._types.get(name)
+        if t is not None:
+            return t
+        if name in self._loading:
+            raise CycleError(f"{name} contains itself ({' -> '.join(self._loading[self._loading.index(name):])} -> {name})")
+        self._loading.append(name)
+        try:  # both steps can need other macros (nested ones), so both count as loading
+            try:
+                body = self.load(name)
+            except CycleError:
+                raise
+            except (KeyError, OSError, ValueError) as e:
+                raise KeyError(f"macro {name!r}: {e.args[0] if isinstance(e, KeyError) and e.args else e}") from None
+            t = MacroType(name, body, self.catalog)
+        finally:
+            self._loading.pop()
+        self._types[name] = t
+        return t
+
+    def forget(self) -> None:
+        """Definitions changed on disk (a macro was saved): load them again when needed.
+        Parts already on the board keep the definition they were made from."""
+        self._types.clear()
+
+    def contains(self, outer: str, inner: str) -> bool:
+        """Does macro `outer` have `inner` inside it, at any depth? (Unloadable: no.)"""
+        seen, todo = set(), [outer]
+        while todo:
+            name = todo.pop()
+            try:
+                uses = self.get(name).uses
+            except KeyError:
+                continue
+            if inner in uses:
+                return True
+            todo += [u for u in uses if u not in seen]
+            seen.update(uses)
+        return False
+
+
+class Catalog:
+    """Every kind of part that exists: the part scripts' types plus macros ("macro:<name>")."""
+
+    def __init__(self, registry: Registry, load: Callable[[str], Snapshot]) -> None:
+        self.registry = registry
+        self.book = MacroBook(self, load)
+
+    def get(self, kind: str) -> PartType:
+        if kind.startswith(MACRO):
+            return self.book.get(kind[len(MACRO):])
+        return self.registry.get(kind)
+
+    def __contains__(self, kind: str) -> bool:
+        try:
+            self.get(kind)
+        except KeyError:
+            return False
+        return True

pijl-0.1.0/src/pijl/main.py

@@ -0,0 +1,9 @@
+from pijl.ui import run
+
+
+def main():
+    run()
+
+
+if __name__ == "__main__":
+    main()

pijl-0.1.0/src/pijl/parts/__init__.py

@@ -0,0 +1,27 @@
+"""Part types: what kinds of parts exist and how each one behaves.
+
+Everything except IN/OUT (see ports.py) comes from part scripts. The ones that
+ship with pijl live in templates/ and are copied into every new project; the
+project's copy is what gets loaded (see project.py). No pyglet in here.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from .contract import API, Ctx, Look, PartType, part
+from .registry import Registry, fresh_props, load
+
+TEMPLATES = Path(__file__).parent / "templates"
+
+
+@cache
+def builtin_registry() -> Registry:
+    """The ports plus the shipped templates, loaded straight from the package.
+    For tests and anything else that has no project."""
+    return load(TEMPLATES)
+
+
+__all__ = ["API", "Ctx", "Look", "PartType", "Registry", "TEMPLATES", "builtin_registry",
+           "fresh_props", "load", "part"]

pijl-0.1.0/src/pijl/parts/contract.py

@@ -0,0 +1,130 @@
+"""The part-script contract: what a part script provides, and what the engine promises it.
+
+A part script is a .py file in a project's parts folder (see registry.py for how
+they're found). It declares `API = 1` and a `register(reg)` function that calls
+`reg.add(...)` with PartTypes -- as many as it likes:
+
+    from pijl.parts import part
+
+    API = 1
+
+    def register(reg):
+        reg.add(part("NAND", ins=("a", "b"), outs=("out",), eval=lambda a, b: ~(a & b)))
+
+`part(...)` is shorthand for a pure PartType. Anything else subclasses PartType
+and overrides whichever hooks it needs; every hook is optional.
+
+What the engine promises:
+  - eval runs once per kind per step, on arrays: element i of every input array
+    (and of the result) belongs to ctx.parts[i]. Inputs are numpy bool arrays, so
+    use & | ^ ~, not `and`/`or`/`not`. Return a tuple with one value per output
+    pin (just the value if there's one pin); each value is an array or list with
+    one entry per instance, or a scalar, which is copied to every instance.
+  - Every hook runs on the main thread. Start your own threads if you need them;
+    just don't touch the UI from them.
+  - A hook that raises disables its kind (in that circuit) and reports the error.
+    Nothing else stops.
+  - open() runs when a real instance appears -- never for the ghosts that follow
+    the cursor before placement -- and every opened instance gets a close().
+  - Parts that aren't `pure` are never skipped, cached or reordered; only live
+    (opened) instances of them are evaluated.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from ..sim.circuit import Part
+
+API = 1  # bump when this contract changes in a way old scripts can't follow
+
+LABEL_SIDES = ("below", "left", "right")
+
+
+@dataclass(frozen=True)
+class Look:
+    """How the editor draws a part. Colors are names from ui/theme.py."""
+    narrow: bool = False                # IO-width body with smaller text
+    label: str = "below"                # where the user's label goes: below, left, right
+    lit: tuple[str, str] | None = None  # body (off, on) colors, following the part's first pin
+    swatch: str = "PART_BODY"           # its color in the part picker
+    body: str = "PART_BODY"             # body (fill, border) colors, unless `lit` says otherwise
+    pin_labels: bool = True             # name tags next to the pins (Tab picks hidden / hover / always)
+
+
+class PartType:
+    """One kind of part. Class attributes are the defaults; instances may set their own."""
+    kind: str = ""                   # stable id: save files refer to parts by it
+    title: str = ""                  # what the body says, if not the kind
+    ins: tuple[str, ...] = ()        # input pin names, top to bottom
+    outs: tuple[str, ...] = ()       # output pin names, top to bottom
+    props: dict[str, Any] = {}       # per-instance settings (JSON values); each instance gets a copy
+    pure: bool = False               # outputs depend only on inputs: the engine may optimize it
+    category: str = ""               # default collection in the part picker ("" = loose)
+    look: Look = Look()
+    port: str | None = None          # "in" / "out": macro ports. Engine-only, see ports.py
+
+    def eval(self, ctx: Ctx, *ins):
+        """Every step: input arrays in, output arrays (or scalars) out."""
+
+    def open(self, part: Part) -> None:
+        """A real instance appeared."""
+
+    def close(self, part: Part) -> None:
+        """An opened instance is going away (deleted, undone, app closing)."""
+
+    def frame(self, ctx: Ctx) -> None:
+        """Once per frame, outside the step loop, for the live instances."""
+
+    def click(self, part: Part) -> None:
+        """The user clicked a placed instance. Overriding this makes the part clickable
+        (a click then no longer selects it)."""
+
+    def has(self, hook: str) -> bool:
+        """Does this type override `hook`? Hooks it doesn't override are never called."""
+        return getattr(type(self), hook) is not getattr(PartType, hook)
+
+    def __repr__(self) -> str:
+        return f"<PartType {self.kind}>"
+
+
+@dataclass
+class Ctx:
+    """What a hook sees: a batch of instances of one kind."""
+    parts: list[Part]
+    tick: int = 0  # simulation steps since the circuit was created
+    time: float = field(default_factory=time.monotonic)
+
+    @property
+    def n(self) -> int:
+        return len(self.parts)
+
+    @property
+    def props(self) -> list[dict[str, Any]]:
+        return [p.props for p in self.parts]
+
+    @property
+    def state(self) -> list[dict[str, Any]]:
+        """Per-instance scratch space, kept for as long as the instance lives."""
+        return [p.state for p in self.parts]
+
+
+class FunctionPart(PartType):
+    """A pure part whose eval is a plain function of its inputs. Made by part()."""
+    pure = True
+
+    def __init__(self, kind: str, ins, outs, fn: Callable, category: str, look: Look) -> None:
+        self.kind, self.ins, self.outs = kind, tuple(ins), tuple(outs)
+        self.fn, self.category, self.look = fn, category, look
+
+    def eval(self, ctx: Ctx, *ins):
+        return self.fn(*ins)
+
+
+def part(kind: str, ins=(), outs=(), eval: Callable = None, *, category: str = "",
+         look: Look = Look()) -> PartType:
+    """A pure part from a function: `eval` takes one array per input pin."""
+    return FunctionPart(kind, ins, outs, eval, category, look)

pijl-0.1.0/src/pijl/parts/ports.py

@@ -0,0 +1,35 @@
+"""IN and OUT: the two parts the engine itself defines.
+
+Inside a macro they are its pins (the flattener removes them and joins the nets
+on either side), so their meaning can't be up to a script. On the top-level
+board they're a switch and an LED. No script may define a part with a `port`.
+"""
+
+from __future__ import annotations
+
+from .contract import Look, PartType
+
+
+class Switch(PartType):
+    kind = "IN"
+    outs = ("out",)
+    port = "in"
+    category = "I/O"
+    look = Look(narrow=True, label="left", lit=("SWITCH_OFF", "SWITCH_ON"), swatch="SWITCH_ON",
+                pin_labels=False)  # one pin: a tag would only say "out"
+
+    def click(self, part) -> None:
+        # No eval: the output keeps whatever the user last set it to.
+        pin = part.outputs[0]
+        pin.state = not pin.state
+
+
+class Led(PartType):
+    kind = "OUT"
+    ins = ("in",)
+    port = "out"
+    category = "I/O"
+    look = Look(narrow=True, label="right", lit=("LED_OFF", "LED_ON"), swatch="LED_ON", pin_labels=False)
+
+
+PORTS: tuple[PartType, ...] = (Switch(), Led())