forgekernel 0.1.0__py3-none-any.whl

forgekernel/exact.py

@@ -0,0 +1,121 @@
+"""Exact rational linear algebra — the numerical substrate of K1.
+
+Every coordinate is a ``fractions.Fraction``; every predicate (side of
+plane, collinearity, orientation) is an exact sign computation. There
+are NO epsilons anywhere in this package: two points are equal iff
+their coordinates are equal, a point is on a plane iff the incidence
+expression is exactly zero. Approximation exists only at the export
+boundary (floats for tessellation/metrics), never inside a decision.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from math import gcd
+from typing import Iterable
+
+Vec = tuple[Fraction, Fraction, Fraction]
+
+
+def F(x) -> Fraction:
+    """Exact conversion. Floats convert via Fraction(float) — the exact
+    binary value, no decimal guessing and no denominator snapping — so
+    every decision made afterward is exact relative to the given inputs.
+    Slow denominators are ref's price for being the spec."""
+    return x if isinstance(x, Fraction) else Fraction(x)
+
+
+def vec(x, y, z) -> Vec:
+    return (F(x), F(y), F(z))
+
+
+def add(a: Vec, b: Vec) -> Vec:
+    return (a[0] + b[0], a[1] + b[1], a[2] + b[2])
+
+
+def sub(a: Vec, b: Vec) -> Vec:
+    return (a[0] - b[0], a[1] - b[1], a[2] - b[2])
+
+
+def neg(a: Vec) -> Vec:
+    return (-a[0], -a[1], -a[2])
+
+
+def smul(s: Fraction, a: Vec) -> Vec:
+    return (s * a[0], s * a[1], s * a[2])
+
+
+def dot(a: Vec, b: Vec) -> Fraction:
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def cross(a: Vec, b: Vec) -> Vec:
+    return (a[1] * b[2] - a[2] * b[1],
+            a[2] * b[0] - a[0] * b[2],
+            a[0] * b[1] - a[1] * b[0])
+
+
+def is_zero(a: Vec) -> bool:
+    return a[0] == 0 and a[1] == 0 and a[2] == 0
+
+
+class Plane:
+    """Oriented plane ``normal · x == d``. The normal is rational and
+    unnormalized; orientation carries meaning (outward = positive side)."""
+
+    __slots__ = ("n", "d")
+
+    def __init__(self, n: Vec, d: Fraction) -> None:
+        if is_zero(n):
+            raise ValueError("degenerate plane (zero normal)")
+        self.n = n
+        self.d = d
+
+    @classmethod
+    def from_points(cls, a: Vec, b: Vec, c: Vec) -> "Plane":
+        n = cross(sub(b, a), sub(c, a))
+        if is_zero(n):
+            raise ValueError("collinear points do not define a plane")
+        return cls(n, dot(n, a))
+
+    def side(self, p: Vec) -> int:
+        """Exact classification: +1 front, -1 back, 0 on."""
+        s = dot(self.n, p) - self.d
+        return (s > 0) - (s < 0)
+
+    def flipped(self) -> "Plane":
+        return Plane(neg(self.n), -self.d)
+
+    def canonical(self) -> tuple:
+        """Hashable canonical form: normal scaled to coprime integers with a
+        sign convention — coplanarity comparisons become tuple equality."""
+        nums = [self.n[0], self.n[1], self.n[2], self.d]
+        den = 1
+        for v in nums:
+            den = den * v.denominator // gcd(den, v.denominator)
+        ints = [int(v * den) for v in nums]
+        g = 0
+        for v in ints:
+            g = gcd(g, abs(v))
+        if g:
+            ints = [v // g for v in ints]
+        for v in ints[:3]:
+            if v != 0:
+                if v < 0:
+                    ints = [-w for w in ints]
+                break
+        return tuple(ints)
+
+    def coplanar_key(self) -> tuple:
+        """Canonical form ignoring orientation (for adjacency grouping)."""
+        c = self.canonical()
+        return min(c, tuple(-v for v in c))
+
+
+def centroid(points: Iterable[Vec]) -> Vec:
+    pts = list(points)
+    k = Fraction(1, len(pts))
+    acc = (Fraction(0), Fraction(0), Fraction(0))
+    for p in pts:
+        acc = add(acc, p)
+    return smul(k, acc)

forgekernel/interval.py

@@ -0,0 +1,141 @@
+"""Certified intervals — the K3 number kind (ADR-0019).
+
+A ``CInterval`` is a pair of exact rationals ``[lo, hi]`` that *provably*
+brackets a real value. Arithmetic only ever widens the bracket; it never
+loses the enclosure. Rational ``+ - *`` are exact (an interval widens
+only because its inputs already had width), so a bracket grows *only* at
+the genuinely irrational steps — ``pi`` and ``sqrt`` — and by a bounded,
+reportable amount.
+
+This is not a float with error bars. The bounds are the primitive and
+they are rigorous: ``pi`` enters through a digit-verified rational
+enclosure; ``sqrt(x)`` returns ``[a, b]`` with ``a*a <= x <= b*b``.
+
+A topological decision may consult ``sign()`` only when the interval
+strictly excludes zero (``certified``); otherwise the caller tightens or
+refuses — never guesses.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from math import isqrt
+
+# pi to 60 decimal places (a widely tabulated, digit-verified constant).
+# Stored as the integer floor(pi * 10**60); truncation is a rigorous lower
+# bound and +1 ulp a rigorous upper bound, so [lo, hi] certainly brackets pi.
+_PI_NUM = 3141592653589793238462643383279502884197169399375105820974944
+_PI_SCALE = 10 ** 60
+
+
+def pi_interval() -> "CInterval":
+    """A certified rational enclosure of pi (width 1e-60)."""
+    lo = Fraction(_PI_NUM, _PI_SCALE)
+    return CInterval(lo, lo + Fraction(1, _PI_SCALE))
+
+
+def _sqrt_low(x: Fraction, scale: int) -> Fraction:
+    """Largest r = m/scale with r*r <= x (rational lower bound of sqrt(x))."""
+    if x < 0:
+        raise ValueError("sqrt of a negative certified interval")
+    m = isqrt((x.numerator * scale * scale) // x.denominator)
+    r = Fraction(m, scale)
+    # isqrt floor guarantees r*r <= x; nudge defensively (never loops in practice)
+    while r * r > x:
+        m -= 1
+        r = Fraction(m, scale)
+    return r
+
+
+def _sqrt_high(x: Fraction, scale: int) -> Fraction:
+    """Smallest r = m/scale with r*r >= x (rational upper bound of sqrt(x))."""
+    lo = _sqrt_low(x, scale)
+    r = lo + Fraction(1, scale)
+    while r * r < x:            # at most a couple of steps
+        r += Fraction(1, scale)
+    return r
+
+
+class CInterval:
+    """A certified real: lo <= true value <= hi, both exact rationals."""
+
+    __slots__ = ("lo", "hi")
+
+    # width of the rational sqrt bracket (1e-50): far below any float epsilon
+    _SQRT_SCALE = 10 ** 50
+
+    def __init__(self, lo, hi=None) -> None:
+        lo = lo if isinstance(lo, Fraction) else Fraction(lo)
+        if hi is None:
+            hi = lo
+        else:
+            hi = hi if isinstance(hi, Fraction) else Fraction(hi)
+        if lo > hi:
+            raise ValueError(f"degenerate interval [{lo}, {hi}]")
+        self.lo = lo
+        self.hi = hi
+
+    # -- construction ---------------------------------------------------------
+
+    @staticmethod
+    def exact(x) -> "CInterval":
+        """A zero-width interval around an exact rational."""
+        f = x if isinstance(x, Fraction) else Fraction(x)
+        return CInterval(f, f)
+
+    # -- arithmetic (enclosure-preserving) ------------------------------------
+
+    def __add__(self, o: "CInterval") -> "CInterval":
+        o = _as_ci(o)
+        return CInterval(self.lo + o.lo, self.hi + o.hi)
+
+    __radd__ = __add__
+
+    def __sub__(self, o: "CInterval") -> "CInterval":
+        o = _as_ci(o)
+        return CInterval(self.lo - o.hi, self.hi - o.lo)
+
+    def __rsub__(self, o) -> "CInterval":
+        return _as_ci(o).__sub__(self)
+
+    def __mul__(self, o: "CInterval") -> "CInterval":
+        o = _as_ci(o)
+        prods = (self.lo * o.lo, self.lo * o.hi, self.hi * o.lo, self.hi * o.hi)
+        return CInterval(min(prods), max(prods))
+
+    __rmul__ = __mul__
+
+    def sqrt(self) -> "CInterval":
+        s = self._SQRT_SCALE
+        return CInterval(_sqrt_low(self.lo, s), _sqrt_high(self.hi, s))
+
+    # -- certified queries ----------------------------------------------------
+
+    def sign(self) -> int:
+        """+1/-1 if the interval strictly excludes zero; else raise — the
+        sign is not certified and the caller must tighten or refuse."""
+        if self.lo > 0:
+            return 1
+        if self.hi < 0:
+            return -1
+        raise ValueError("sign not certified: interval straddles zero")
+
+    @property
+    def mid(self) -> Fraction:
+        return (self.lo + self.hi) / 2
+
+    @property
+    def width(self) -> Fraction:
+        return self.hi - self.lo
+
+    def to_float(self) -> float:
+        """Reported value: the midpoint. The true value is within
+        ``width/2`` of it, and ``width`` is available for the report."""
+        return float(self.mid)
+
+    def __repr__(self) -> str:
+        return f"CInterval({float(self.lo):.6g}~{float(self.hi):.6g})"
+
+
+def _as_ci(x) -> CInterval:
+    return x if isinstance(x, CInterval) else CInterval.exact(x)

forgekernel/io.py

@@ -0,0 +1,56 @@
+"""Native serialization — exact, canonical, hashable (ADR-0018).
+
+Rationals serialize as "num/den" strings, so a round-trip is BIT-exact
+and two equal solids produce identical bytes: geometry identity by
+hash, the property OCCT never offered.
+"""
+
+from __future__ import annotations
+
+import json
+from fractions import Fraction
+
+from forgekernel.brep import Polygon, Solid
+
+SCHEMA = "forge/solid@1"
+
+
+def _fr(v: Fraction) -> str:
+    return f"{v.numerator}/{v.denominator}"
+
+
+def _unfr(s: str) -> Fraction:
+    n, d = s.split("/")
+    return Fraction(int(n), int(d))
+
+
+def dumps(solid: Solid) -> str:
+    doc = {"schema": SCHEMA, "polys": [
+        {"source": p.source,
+         "verts": [[_fr(v[0]), _fr(v[1]), _fr(v[2])] for v in p.verts]}
+        for p in solid.polys]}
+    return json.dumps(doc, sort_keys=True, separators=(",", ":")) + "\n"
+
+
+def loads(text: str) -> Solid:
+    doc = json.loads(text)
+    if doc.get("schema") != SCHEMA:
+        raise ValueError(f"unsupported solid schema {doc.get('schema')!r}")
+    return Solid([Polygon([(_unfr(a), _unfr(b), _unfr(c))
+                           for a, b, c in p["verts"]], p["source"])
+                  for p in doc["polys"]])
+
+
+def to_stl(solid: Solid, name: str = "forge") -> str:
+    """ASCII STL from the exact tessellation (floats at the boundary)."""
+    mesh = solid.tessellate()
+    v = mesh["vertices"]
+    out = [f"solid {name}"]
+    for a, b, c in mesh["triangles"]:
+        out += ["facet normal 0 0 0", "outer loop",
+                f"vertex {v[a][0]:.9g} {v[a][1]:.9g} {v[a][2]:.9g}",
+                f"vertex {v[b][0]:.9g} {v[b][1]:.9g} {v[b][2]:.9g}",
+                f"vertex {v[c][0]:.9g} {v[c][1]:.9g} {v[c][2]:.9g}",
+                "endloop", "endfacet"]
+    out.append(f"endsolid {name}")
+    return "\n".join(out) + "\n"

forgekernel/kernel.py

@@ -0,0 +1,93 @@
+"""The K1 facade — pure-Python exact planar kernel operations.
+
+gitcad adapts this to its Kernel seam in a thin shim (gitcad.kernel.ref);
+nothing here depends on gitcad. Unsupported operator classes raise
+NotImplementedError with the stage that will bring them — honest refusal
+is part of the contract.
+"""
+
+from __future__ import annotations
+
+from forgekernel import csg
+from forgekernel.brep import Solid
+from forgekernel.exact import F, vec
+
+__all__ = ["Solid", "box", "prism", "boolean", "translate", "scale",
+           "mirror", "rotate_quarter"]
+
+
+def box(dx, dy, dz) -> Solid:
+    return Solid.box(dx, dy, dz)
+
+
+def prism(loop_xy, height, source_prefix: str = "prism") -> Solid:
+    return Solid.prism(loop_xy, height, source_prefix)
+
+
+def boolean(op: str, a: Solid, b: Solid) -> Solid:
+    fn = {"union": csg.union, "cut": csg.cut, "intersect": csg.intersect}.get(op)
+    if fn is None:
+        raise ValueError(f"unknown boolean op {op!r} (union|cut|intersect)")
+    out = fn(a, b)
+    bad = out.watertight_violations()
+    if bad:
+        raise ArithmeticError(f"boolean produced non-watertight result: {bad}")
+    return out
+
+
+def translate(s: Solid, x, y, z) -> Solid:
+    return s.translated(vec(F(x), F(y), F(z)))
+
+
+def scale(s: Solid, fx, fy=None, fz=None) -> Solid:
+    return s.scaled(fx, fx if fy is None else fy, fx if fz is None else fz)
+
+
+def mirror(s: Solid, axis: str) -> Solid:
+    return s.mirrored(axis)
+
+
+def rotate_quarter(s: Solid, axis: str, quarters: int) -> Solid:
+    return s.rotated_quarter(axis, quarters)
+
+
+def chamfer(s: Solid, distance) -> Solid:
+    """Exact chamfer on all convex rational-normal edges, with industrial
+    corner-triangle vertex truncation (oracle-matched semantics)."""
+    from forgekernel.brep import chamfer_corners, chamfer_planar, logical_edges
+
+    edges = logical_edges(s)
+    out = chamfer_planar(s, distance, edges)
+    return chamfer_corners(out, distance, edges)
+
+
+def draft(s: Solid, angle_deg: float, neutral_z=0, faces=None) -> Solid:
+    """Draft vertical faces by angle (tan converted exactly at input)."""
+    import math as _m
+
+    from forgekernel.brep import draft_box
+    from forgekernel.exact import F
+
+    t = F(_m.tan(_m.radians(angle_deg)))
+    return draft_box(s, t, F(neutral_z))
+
+
+def shell(s: Solid, thickness) -> Solid:
+    """Hollow to a wall thickness (closed shell, exact for box solids)."""
+    from forgekernel.brep import shell_box
+
+    return shell_box(s, thickness)
+
+
+def fillet_box(a, b, c, r, origin=(0, 0, 0)):
+    """Rounded box (all edges+corners filleted r) — exact Q[pi] volume."""
+    from forgekernel.quadric import RoundedBox
+
+    return RoundedBox(a, b, c, r, origin)
+
+
+def sweep(profile_area, path):
+    """Mitered sweep of a convex profile — exact volume in Q[sqrt d]."""
+    from forgekernel.quadric import MiteredSweep
+
+    return MiteredSweep(profile_area, path)

forgekernel/loft.py

@@ -0,0 +1,185 @@
+"""K3.7 — smooth multi-section loft, exact volume.
+
+A smooth loft interpolates a stack of same-count section polygons with a
+natural cubic spline in the section parameter v. Its volume is *exactly
+rational*: each vertex coordinate x_j(v), y_j(v) and the height z(v) are
+piecewise-cubic polynomials with **rational** coefficients (the natural-
+spline tridiagonal system is solved in ℚ), so the cross-section area
+
+    A(v) = ½ Σ_j (x_j y_{j+1} − x_{j+1} y_j)          (shoelace)
+
+is a polynomial in v, and
+
+    V = ∫ A(v) z'(v) dv
+
+integrates exactly per spline segment. OCCT skins a B-spline surface and
+Gauss-quadratures the volume; forge returns a Fraction.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+
+F = Fraction
+
+
+def natural_spline_M(vals):
+    """Second derivatives M_k of the natural cubic spline through ``vals``
+    at unit-spaced knots (M_0 = M_n = 0). Exact rational Thomas solve."""
+    n = len(vals) - 1
+    if n < 1:
+        return [F(0)] * len(vals)
+    if n == 1:
+        return [F(0), F(0)]
+    # tridiagonal: M_{k-1} + 4M_k + M_{k+1} = 6(v_{k+1}-2v_k+v_{k-1})
+    a = [F(1)] * (n - 1)          # sub-diagonal
+    b = [F(4)] * (n - 1)          # diagonal
+    c = [F(1)] * (n - 1)          # super-diagonal
+    d = [6 * (vals[k + 1] - 2 * vals[k] + vals[k - 1]) for k in range(1, n)]
+    # forward sweep
+    for i in range(1, n - 1):
+        m = a[i] / b[i - 1]
+        b[i] -= m * c[i - 1]
+        d[i] -= m * d[i - 1]
+    x = [F(0)] * (n - 1)
+    x[-1] = d[-1] / b[-1]
+    for i in range(n - 3, -1, -1):
+        x[i] = (d[i] - c[i] * x[i + 1]) / b[i]
+    return [F(0)] + x + [F(0)]
+
+
+def _seg_cubic(v0, v1, M0, M1):
+    """Coefficients [c0,c1,c2,c3] (power basis in local s∈[0,1]) of the
+    natural-spline segment with endpoints v0,v1 and 2nd derivs M0,M1
+    (unit knot spacing h=1). S(s)=v0(1-s)+v1 s + ((s³-s)M1 + ((1-s)³-(1-s))M0)/6."""
+    # expand to power basis in s
+    # term A = v0(1-s) + v1 s = v0 + (v1-v0)s
+    c = [v0, v1 - v0, F(0), F(0)]
+    # term B = M1(s³-s)/6 : +M1/6 s³ - M1/6 s
+    c[3] += M1 / 6
+    c[1] += -M1 / 6
+    # term C = M0((1-s)³-(1-s))/6.  (1-s)³ = 1-3s+3s²-s³ ; (1-s)=1-s
+    # (1-s)³-(1-s) = -2s+3s²-s³  → times M0/6
+    c[1] += M0 / 6 * (-2)
+    c[2] += M0 / 6 * 3
+    c[3] += M0 / 6 * (-1)
+    return c
+
+
+def _poly_mul(a, b):
+    out = [F(0)] * (len(a) + len(b) - 1)
+    for i, ai in enumerate(a):
+        for j, bj in enumerate(b):
+            out[i + j] += ai * bj
+    return out
+
+
+def _poly_add(a, b):
+    out = [F(0)] * max(len(a), len(b))
+    for i, ai in enumerate(a):
+        out[i] += ai
+    for j, bj in enumerate(b):
+        out[j] += bj
+    return out
+
+
+def _poly_sub(a, b):
+    return _poly_add(a, [-c for c in b])
+
+
+def _poly_deriv(a):
+    return [a[i] * i for i in range(1, len(a))] or [F(0)]
+
+
+def _poly_integ01(a):
+    return sum(ci / (i + 1) for i, ci in enumerate(a))
+
+
+class LoftSolid:
+    """Exact-volume smooth loft through ``sections`` = [(loop, z), …] with
+    equal vertex counts. ``loop`` is a list of (x, y)."""
+
+    provenance = "exact"
+
+    def __init__(self, sections) -> None:
+        self.sections = [([tuple(F(c) for c in pt) for pt in loop], F(z))
+                         for loop, z in sections]
+        counts = {len(loop) for loop, _ in self.sections}
+        if len(self.sections) < 2 or len(counts) != 1:
+            raise ValueError("loft: ≥2 sections of equal vertex count")
+        self.m = len(self.sections[0][0])           # verts per section
+        self.n = len(self.sections)                  # section count
+
+    def _splines(self):
+        """Per-vertex x,y splines (M arrays) + the z spline."""
+        xs = [[self.sections[k][0][j][0] for k in range(self.n)]
+              for j in range(self.m)]
+        ys = [[self.sections[k][0][j][1] for k in range(self.n)]
+              for j in range(self.m)]
+        zs = [self.sections[k][1] for k in range(self.n)]
+        Mx = [natural_spline_M(xs[j]) for j in range(self.m)]
+        My = [natural_spline_M(ys[j]) for j in range(self.m)]
+        Mz = natural_spline_M(zs)
+        return xs, ys, zs, Mx, My, Mz
+
+    def _moments(self):
+        """Signed volume and the three first moments (∫x dV, ∫y dV, ∫z dV),
+        all exact ℚ. Volume ``V = ∫ A(v) z'(v) dv`` with A the shoelace
+        cross-section area; the moments add the polygon area-moments
+        ``Qx = ∫∫ x dA`` and ``Qy = ∫∫ y dA`` (exact for a polygon) and the
+        ``z·A`` integrand. The section-loop orientation cancels in every
+        centroid ratio because A, Qx, Qy all carry the same signed factor."""
+        xs, ys, zs, Mx, My, Mz = self._splines()
+        Vs = Ix = Iy = Iz = F(0)
+        for seg in range(self.n - 1):
+            xpoly = [_seg_cubic(xs[j][seg], xs[j][seg + 1],
+                                Mx[j][seg], Mx[j][seg + 1]) for j in range(self.m)]
+            ypoly = [_seg_cubic(ys[j][seg], ys[j][seg + 1],
+                                My[j][seg], My[j][seg + 1]) for j in range(self.m)]
+            zpoly = _seg_cubic(zs[seg], zs[seg + 1], Mz[seg], Mz[seg + 1])
+            zprime = _poly_deriv(zpoly)
+            area = [F(0)]           # A(s) = ½ Σ cross_j
+            qx = [F(0)]             # ∫∫ x dA = ⅙ Σ (x_j+x_k)·cross_j
+            qy = [F(0)]             # ∫∫ y dA = ⅙ Σ (y_j+y_k)·cross_j
+            for j in range(self.m):
+                k = (j + 1) % self.m
+                cross = _poly_sub(_poly_mul(xpoly[j], ypoly[k]),
+                                  _poly_mul(xpoly[k], ypoly[j]))
+                area = _poly_add(area, cross)
+                qx = _poly_add(qx, _poly_mul(_poly_add(xpoly[j], xpoly[k]), cross))
+                qy = _poly_add(qy, _poly_mul(_poly_add(ypoly[j], ypoly[k]), cross))
+            area = [c / 2 for c in area]
+            qx = [c / 6 for c in qx]
+            qy = [c / 6 for c in qy]
+            Vs += _poly_integ01(_poly_mul(area, zprime))
+            Ix += _poly_integ01(_poly_mul(qx, zprime))
+            Iy += _poly_integ01(_poly_mul(qy, zprime))
+            Iz += _poly_integ01(_poly_mul(_poly_mul(zpoly, area), zprime))
+        return Vs, Ix, Iy, Iz
+
+    def volume(self) -> Fraction:
+        return abs(self._moments()[0])
+
+    def centroid(self):
+        """Exact centroid in ℚ³ — the true first-moment centroid, not the
+        bbox centre. Signed volume and moments share orientation, so the
+        ratio is orientation-independent."""
+        Vs, Ix, Iy, Iz = self._moments()
+        if Vs == 0:
+            raise ValueError("loft: degenerate (zero signed volume)")
+        return (Ix / Vs, Iy / Vs, Iz / Vs)
+
+    def bbox_f(self):
+        lo = [float("inf")] * 3
+        hi = [float("-inf")] * 3
+        for loop, z in self.sections:
+            for x, y in loop:
+                lo[0], hi[0] = min(lo[0], float(x)), max(hi[0], float(x))
+                lo[1], hi[1] = min(lo[1], float(y)), max(hi[1], float(y))
+            lo[2], hi[2] = min(lo[2], float(z)), max(hi[2], float(z))
+        return tuple(lo), tuple(hi)
+
+    def centroid_f(self):
+        """Float centroid, derived from the exact :meth:`centroid` (not the
+        bbox centre — that is only correct for a symmetric loft)."""
+        return tuple(float(c) for c in self.centroid())