polycubetools 1.1.0__py3-none-any.whl

polycubetools/grid.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import json
+from typing import Self, TYPE_CHECKING
+
+from .models import Coordinate
+from .utils import is_valid_fence
+
+if TYPE_CHECKING:
+    import os
+    from .hull import AbstractHull
+    from .models import RotatedPolycube, JSON_SOLUTION, SNAPSHOT
+
+__all__ = ("Grid", "HullGrid")
+
+
+class Grid:
+    def __init__(self, size: Coordinate, offset: Coordinate = Coordinate(0, 0, 0)) -> None:
+        """Creates a cuboid grid with the given size and offset."""
+        self._size = size
+        self._offset = offset
+        self._offset_size = size + offset
+        self._cells: dict[Coordinate, int] = {}
+        """Grid cells, mapping coordinates to polycube ids."""
+
+    def __contains__(self, item: object) -> bool:
+        return item in self._cells
+
+    @property
+    def size(self) -> Coordinate:
+        return self._size
+
+    @property
+    def offset(self) -> Coordinate:
+        return self._offset
+
+    def in_bounds(self, pos: Coordinate) -> bool:
+        """Checks if the given coordinate is within the grid bounds."""
+        offset, offset_size = self._offset, self._offset_size
+        px, py, pz = pos.x, pos.y, pos.z
+        return offset.x <= px < offset_size.x and offset.y <= py < offset_size.y and offset.z <= pz < offset_size.z
+
+    def place(self, polycube: RotatedPolycube, offset: Coordinate) -> None:
+        """Places the polycube at the given offset.
+        Assumes that the polycube can be placed, use can_place to check beforehand!
+        """
+        cells = self._cells
+        for coord in polycube.coords:
+            cells[coord + offset] = polycube.id
+
+    def can_place(self, polycube: RotatedPolycube, offset: Coordinate) -> bool:
+        """Checks if the polycube can be placed at the given offset, or more precisely,
+        if every cell it would occupy is empty and in bounds.
+        """
+        cells, in_bounds = self._cells, self.in_bounds
+        for coord in polycube.coords:
+            coord += offset
+            if coord in cells or not in_bounds(coord):
+                return False
+        return True
+
+    def to_json(self, filename: str | os.PathLike[str] | None = None) -> JSON_SOLUTION:
+        """Exports the current grid into the JSON format, returns it, and writes it to a file if specified."""
+        output: JSON_SOLUTION = [[self.size.x, self.size.y, self.size.z]]
+        output.extend([[_id, coord.x, coord.y, coord.z] for coord, _id in self._cells.items()])
+
+        if filename is not None:
+            with open(filename, "w") as f:
+                json.dump(output, f, indent=2)
+
+        return output
+
+    def format(self) -> str:
+        """Exports the current grid into a human-readable format."""
+
+        raise NotImplementedError
+
+    def merge(self, other: Grid) -> None:
+        """Copies all cubes from another grid into this one, according to the offset of the grids."""
+
+        raise NotImplementedError
+
+    def validate(self) -> bool:
+        """Checks if there is a valid polycube fence in the grid."""
+        return is_valid_fence(set(self._cells.keys()))
+
+    @classmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT) -> Self:
+        """Reconstructs a grid from a snapshot and a hull.
+        Snapshot must have been generated by to_snapshot().
+        """
+        size = Coordinate.from_tuple(snapshot["size"])
+        offset = Coordinate.from_tuple(snapshot["offset"])
+        cells = {Coordinate.from_tuple(t): i for t, i in snapshot["cells"].items()}
+
+        self = cls(size, offset)
+        self._cells = cells
+        return self
+
+    def to_snapshot(self) -> SNAPSHOT:
+        """Retrieves a pickable snapshot of the grid, reconstructible with from_snapshot()"""
+        return {
+            "size": self._size.to_tuple(),
+            "offset": self._offset.to_tuple(),
+            "cells": {c.to_tuple(): i for c, i in self._cells.items()},
+        }
+
+
+class HullGrid[H: AbstractHull](Grid):
+    def __init__(self, size: Coordinate, hull: H, offset: Coordinate = Coordinate(0, 0, 0)) -> None:
+        """Creates a Grid that contains a hull and allows certain operations on it."""
+        super().__init__(size, offset)
+        self._hull = hull
+        self._active_frontier: set[Coordinate] = set()
+
+    def place(self, polycube: RotatedPolycube, offset: Coordinate) -> None:
+        super().place(polycube, offset)
+        self._hull.update_frontier(polycube, offset)
+        self._update_active_frontier(polycube, offset)
+
+    @property
+    def hull(self) -> H:
+        """Direct access to the hull, prefer using the proxied methods when possible:
+        frontier, active_frontier, in_hull, in_inner_part
+        """
+        return self._hull
+
+    @property
+    def frontier(self) -> frozenset[Coordinate]:
+        """Returns a frozen view of the current frontier coordinates."""
+        return frozenset(self._hull.frontier)
+
+    @property
+    def active_frontier(self) -> frozenset[Coordinate]:
+        """Returns a frozen view of the current active frontier coordinates."""
+        return frozenset(self._active_frontier)
+
+    @active_frontier.setter
+    def active_frontier(self, value: set[Coordinate]) -> None:
+        """Sets the active frontier coordinates. Only use this if you know what you're doing"""
+        self._active_frontier = value
+
+    def _update_active_frontier(self, polycube: RotatedPolycube, offset: Coordinate) -> None:
+        """Remove the coordinates of the polycube at the offset from the frontier, if present."""
+        placed_points = [point + offset for point in polycube.coords]
+        placed_points_neighbors = [point + offset for point in polycube.get_all_neighbor_cells()]
+
+        for placed_point in placed_points:
+            if placed_point not in self._active_frontier:
+                continue
+
+            self._active_frontier.remove(placed_point)
+
+        for point in placed_points_neighbors:
+            if point in self._cells or point not in self._hull.frontier:
+                continue
+
+            self._active_frontier.add(point)
+
+    def in_hull(self, pos: Coordinate) -> bool:
+        """Checks if the given coordinate is inside the hull."""
+        return self._hull.in_hull(pos)
+
+    def in_inner_part(self, pos: Coordinate) -> bool:
+        """Checks if the given coordinate is inside the inner part of the hull."""
+        return self._hull.in_inner_part(pos)
+
+    @classmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT, hull: H | None = None) -> Self:
+        """Reconstructs a grid from a snapshot and a hull.
+        Snapshot must have been generated by to_snapshot().
+        """
+        if hull is None:
+            raise ValueError("Hull must be provided when reconstructing a HullGrid from a snapshot.")
+
+        size = Coordinate.from_tuple(snapshot["size"])
+        offset = Coordinate.from_tuple(snapshot["offset"])
+        cells = {Coordinate.from_tuple(t): i for t, i in snapshot["cells"].items()}
+        active_frontier = {Coordinate.from_tuple(t) for t in snapshot["active_frontier"]}
+
+        self = cls(size, hull, offset)
+        self._cells = cells
+        self._active_frontier = active_frontier
+        return self
+
+    def to_snapshot(self) -> SNAPSHOT:
+        """Retrieves a pickable snapshot of the grid, reconstructible with from_snapshot()
+        Note: You have to serialize the hull separately, use Hull.to_snapshot and Hull.from_snapshot.
+        """
+        snapshot = super().to_snapshot()
+        snapshot["active_frontier"] = tuple(c.to_tuple() for c in self._active_frontier)
+        return snapshot

polycubetools/hull.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Self, TYPE_CHECKING
+
+from .models import Coordinate
+
+if TYPE_CHECKING:
+    from .models import RotatedPolycube, SNAPSHOT
+
+__all__ = ("AbstractHull", "CoordinateHull", "CuboidHull")
+
+
+class AbstractHull(ABC):
+    def __init__(self) -> None:
+        self.frontier: set[Coordinate] = set()
+
+    def update_frontier(self, polycube: RotatedPolycube, offset: Coordinate) -> None:
+        """Remove the coordinates of the polycube at the offset from the frontier, if present."""
+        self.frontier.difference_update(c + offset for c in polycube.coords)
+
+    @classmethod
+    @abstractmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT) -> Self:
+        """Constructs a hull from a snapshot."""
+        pass
+
+    @abstractmethod
+    def to_snapshot(self) -> SNAPSHOT:
+        """Exports the hull into a snapshot."""
+        pass
+
+    @abstractmethod
+    def in_hull(self, pos: Coordinate) -> bool:
+        """Checks if the given coordinate is inside the hull."""
+        pass
+
+    @abstractmethod
+    def in_inner_part(self, pos: Coordinate) -> bool:
+        """Checks if the given coordinate is inside the inner part of the hull."""
+        pass
+
+
+class CoordinateHull(AbstractHull):
+    def __init__(self, coords: frozenset[Coordinate], frontier: set[Coordinate] | None = None) -> None:
+        super().__init__()
+        self.coords = coords
+
+        if frontier is None:
+            self.frontier = set(coords)
+        else:
+            self.frontier = frontier
+
+    @classmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT) -> Self:
+        coords = frozenset(Coordinate.from_tuple(t) for t in snapshot["coords"])
+        frontier = {Coordinate.from_tuple(t) for t in snapshot["frontier"]}
+
+        return cls(coords, frontier)
+
+    def to_snapshot(self) -> SNAPSHOT:
+        return {
+            "coords": tuple(c.to_tuple() for c in self.coords),
+            "frontier": tuple(c.to_tuple() for c in self.frontier),
+        }
+
+    def in_hull(self, pos: Coordinate) -> bool:
+        return pos in self.coords
+
+    def in_inner_part(self, pos: Coordinate) -> bool:
+        raise NotImplementedError(
+            "Inner part is not defined for coordinate hulls (you can implement it in a subclass if needed)"
+        )
+
+
+class CuboidHull(AbstractHull):
+    def __init__(self, min_coord: Coordinate, max_coord: Coordinate, frontier: set[Coordinate] | None = None) -> None:
+        super().__init__()
+        self.min_coord = min_coord
+        self.max_coord = max_coord
+
+        if frontier is None:
+            self.init_frontier()
+        else:
+            self.frontier = frontier
+
+    def init_frontier(self):
+        """Initialize the frontier with all the coordinates of the cuboid."""
+        self.frontier.clear()
+        minc, maxc = self.min_coord, self.max_coord
+
+        for x in range(self.min_coord.x, self.max_coord.x + 1):
+            for y in range(self.min_coord.y, self.max_coord.y + 1):
+                for z in range(self.min_coord.z, self.max_coord.z + 1):
+                    if x == minc.x or x == maxc.x or y == minc.y or y == maxc.y or z == minc.z or z == maxc.z:
+                        self.frontier.add(Coordinate(x, y, z))
+
+    @classmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT) -> Self:
+        minc = Coordinate.from_tuple(snapshot["min"])
+        maxc = Coordinate.from_tuple(snapshot["max"])
+        frontier = {Coordinate.from_tuple(t) for t in snapshot["frontier"]}
+
+        return cls(minc, maxc, frontier)
+
+    def to_snapshot(self) -> SNAPSHOT:
+        return {
+            "min": self.min_coord.to_tuple(),
+            "max": self.max_coord.to_tuple(),
+            "frontier": tuple(c.to_tuple() for c in self.frontier),
+        }
+
+    def in_hull(self, pos: Coordinate) -> bool:
+        minc, maxc = self.min_coord, self.max_coord
+        px, py, pz = pos.x, pos.y, pos.z
+        return px == minc.x or px == maxc.x or py == minc.y or py == maxc.y or pz == minc.z or pz == maxc.z
+
+    def in_inner_part(self, pos: Coordinate) -> bool:
+        minc, maxc = self.min_coord, self.max_coord
+        px, py, pz = pos.x, pos.y, pos.z
+        return minc.x < px < maxc.x and minc.y < py < maxc.y and minc.z < pz < maxc.z

polycubetools/models.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = (
+    "Coordinate",
+    "Placement",
+    "Polycube",
+    "PolycubePlacement",
+    "RotatedPolycube",
+    "JSON_SOLUTION",
+    "SIX_NEIGHBORHOOD_DIRECTIONS",
+    "SNAPSHOT",
+    "TWENTY_SIX_NEIGHBORHOOD_DIRECTIONS",
+)
+
+from typing import Any, Self
+
+type JSON_SOLUTION = list[list[int | str]]
+type SNAPSHOT = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Coordinate:
+    """Represents a single point in a 3D grid."""
+
+    x: int
+    y: int
+    z: int
+
+    @classmethod
+    def from_tuple(cls, coords: tuple[int, int, int]) -> Coordinate:
+        return cls(*coords)
+
+    def to_tuple(self) -> tuple[int, int, int]:
+        return self.x, self.y, self.z
+
+    def __add__(self, other: Coordinate) -> Coordinate:
+        """Pairwise addition of coordinates."""
+        return Coordinate(self.x + other.x, self.y + other.y, self.z + other.z)
+
+    def __sub__(self, other: Coordinate) -> Coordinate:
+        """Pairwise subtraction of coordinates."""
+        return Coordinate(self.x - other.x, self.y - other.y, self.z - other.z)
+
+
+@dataclass(frozen=True, slots=True)
+class RotatedPolycube:
+    """Represents a specific rotation of a polycube."""
+
+    id: int
+    """The id of the base polycube."""
+    coords: frozenset[Coordinate]
+    """The coordinates of the n unit-cubes that make up the polycube."""
+
+    def get_all_neighbor_cells(self) -> frozenset[Coordinate]:
+        """Return all 6-neighborhood cells adjacent to this rotated polycube."""
+        return frozenset(
+            [
+                point + offset
+                for point in self.coords
+                for offset in SIX_NEIGHBORHOOD_DIRECTIONS
+                if point + offset not in self.coords
+            ]
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Polycube:
+    """Represents a single n-polycube."""
+
+    id: int
+    rotations: tuple[RotatedPolycube, ...]
+    """All unique rotations of this polycube."""
+
+
+@dataclass(frozen=True, slots=True)
+class Placement:
+    """Represents a placement of a specifically rotated polycube on a specific coordinate."""
+
+    rotated_polycube: RotatedPolycube
+    pos: Coordinate
+
+    @classmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT) -> Self:
+        rpc_id = snapshot["rotated_polycube_id"]
+        rpc_coords = frozenset(Coordinate.from_tuple(t) for t in snapshot["rotated_polycube_coords"])
+        rpc = RotatedPolycube(rpc_id, rpc_coords)
+        pos = Coordinate.from_tuple(snapshot["pos"])
+        return cls(rpc, pos)
+
+    def to_snapshot(self) -> SNAPSHOT:
+        return {
+            "rotated_polycube_id": self.rotated_polycube.id,
+            "rotated_polycube_coords": tuple(c.to_tuple() for c in self.rotated_polycube.coords),
+            "pos": self.pos.to_tuple(),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PolycubePlacement:
+    """Represents a placement of a generic polycube, so all its rotations on a specific coordinate."""
+
+    polycube: Polycube
+    pos: Coordinate
+
+    @classmethod
+    def from_snapshot(cls, snapshot: SNAPSHOT) -> Self:
+        polycube_id = snapshot["polycube_id"]
+        rpc_coords = snapshot["rotated_polycube_coords"]
+        rpcs = tuple(
+            RotatedPolycube(polycube_id, frozenset(Coordinate.from_tuple(t) for t in rpc_coord))
+            for rpc_coord in rpc_coords
+        )
+        polycube = Polycube(polycube_id, rpcs)
+        pos = Coordinate.from_tuple(snapshot["pos"])
+        return cls(polycube, pos)
+
+    def to_snapshot(self) -> SNAPSHOT:
+        return {
+            "polycube_id": self.polycube.id,
+            "rotated_polycube_coords": tuple(
+                tuple(c.to_tuple() for c in rpc.coords) for rpc in self.polycube.rotations
+            ),
+            "pos": self.pos.to_tuple(),
+        }
+
+
+SIX_NEIGHBORHOOD_DIRECTIONS = (
+    Coordinate(1, 0, 0),
+    Coordinate(-1, 0, 0),
+    Coordinate(0, 1, 0),
+    Coordinate(0, -1, 0),
+    Coordinate(0, 0, 1),
+    Coordinate(0, 0, -1),
+)
+"""All possible directions in a 3D Grid (without diagonals).
+The neighbors grows additively with the dimension: 2 * dimension."""
+
+TWENTY_SIX_NEIGHBORHOOD_DIRECTIONS = (
+    # 6 orthogonal directions (6-neighborhood)
+    Coordinate(1, 0, 0),
+    Coordinate(-1, 0, 0),
+    Coordinate(0, 1, 0),
+    Coordinate(0, -1, 0),
+    Coordinate(0, 0, 1),
+    Coordinate(0, 0, -1),
+    # 12 edge-diagonal directions (connecting edge centers)
+    Coordinate(1, 1, 0),
+    Coordinate(1, -1, 0),
+    Coordinate(-1, 1, 0),
+    Coordinate(-1, -1, 0),
+    Coordinate(1, 0, 1),
+    Coordinate(1, 0, -1),
+    Coordinate(-1, 0, 1),
+    Coordinate(-1, 0, -1),
+    Coordinate(0, 1, 1),
+    Coordinate(0, 1, -1),
+    Coordinate(0, -1, 1),
+    Coordinate(0, -1, -1),
+    # 8 face-diagonal directions (connecting corners)
+    Coordinate(1, 1, 1),
+    Coordinate(1, 1, -1),
+    Coordinate(1, -1, 1),
+    Coordinate(1, -1, -1),
+    Coordinate(-1, 1, 1),
+    Coordinate(-1, 1, -1),
+    Coordinate(-1, -1, 1),
+    Coordinate(-1, -1, -1),
+)
+"""All possible directions in a 3D Grid.
+The neighbors grows exponentially with the dimension: 3 ^ dimension - 1."""

polycubetools/solver.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import logging
+import os
+from abc import ABC, abstractmethod
+from concurrent.futures import Future, ProcessPoolExecutor
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING, Iterable, Sequence, Callable
+
+from .grid import HullGrid
+from .models import Placement, PolycubePlacement
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+    from .hull import AbstractHull
+    from .grid import Grid
+    from .models import Polycube, JSON_SOLUTION, SNAPSHOT
+
+__all__ = ("AbstractSolver", "ParallelSolver", "ScoreSolver", "SolverStatus")
+
+
+class SolverStatus(StrEnum):
+    INITIALIZED = auto()
+    RUNNING = auto()
+    FINISHED = auto()
+    FAILED = auto()
+
+
+class AbstractSolver[G: Grid](ABC):
+    def __init__(self, grid: G, polycubes: tuple[Polycube, ...]) -> None:
+        """The base init function. It must be called when being overwritten: super().__init__(grid, polycubes)"""
+        self._grid = grid
+        self._polycubes = polycubes
+        self._status = SolverStatus.INITIALIZED
+        self._logger = logging.getLogger(__name__)
+
+    @property
+    def grid(self) -> G:
+        return self._grid
+
+    @property
+    def polycubes(self) -> tuple[Polycube, ...]:
+        return self._polycubes
+
+    @property
+    def status(self) -> SolverStatus:
+        return self._status
+
+    def set_finished(self) -> None:
+        self._status = SolverStatus.FINISHED
+
+    def set_failed(self, message: str) -> None:
+        self._status = SolverStatus.FAILED
+        self._logger.error("Run failed: %s", message)
+
+    @abstractmethod
+    def step(self) -> None:
+        """Performs a single iteration of the solving logic.
+        This method should eventually call self.set_finished() or self.set_failed() to finish the run.
+        """
+        pass
+
+    def is_running(self) -> bool:
+        return self.status == SolverStatus.RUNNING
+
+    def run(self, output_file: str | PathLike[str] | None) -> JSON_SOLUTION:
+        """Runs the solver until the status is set to finished or failed.
+        Finally returns the grid as JSON and writes it to the specified file if specified.
+        """
+        self._status = SolverStatus.RUNNING
+        self._logger.info("Solver run started")
+
+        while self.is_running():
+            self.step()
+
+        self.done()
+        return self.grid.to_json(output_file)
+
+    def done(self):
+        self._logger.info("Solver run completed with status: %s", self.status)
+
+
+class _GenericScoreSolver[H: AbstractHull, C, SC, SR](AbstractSolver[HullGrid[H]], ABC):
+    def __init__(self, grid: HullGrid[H], polycubes: tuple[Polycube, ...]) -> None:
+        super().__init__(grid, polycubes)
+        self.remaining: dict[int, Polycube] = {p.id: p for p in polycubes}
+
+    @abstractmethod
+    def score(self, candidate: SC) -> SR:
+        pass
+
+    @abstractmethod
+    def next_candidates(self) -> Sequence[C]:
+        pass
+
+    @abstractmethod
+    def _compute_best(self, candidates: Iterable[C]) -> tuple[Placement | None, int]:
+        """Computes the highest scoring candidate, deterministically."""
+        pass
+
+    def after_place(self, placement: Placement) -> None:
+        """Called after a polycube is placed, override if needed, but you should call the super method."""
+        del self.remaining[placement.rotated_polycube.id]
+
+    def step(self) -> None:
+        candidates = self.next_candidates()
+        if not candidates:
+            self.set_failed("No more candidates to try")
+            return
+
+        p, score = self._compute_best(candidates)
+        if p is None:
+            self.set_failed("No valid placement found")
+            return
+
+        if self._logger.isEnabledFor(logging.DEBUG):
+            self._logger.debug("Selected best candidate: %s with score: %d", p, score)
+
+        if not self.grid.can_place(p.rotated_polycube, p.pos):
+            self.set_failed("Found placement is not valid")
+            return
+
+        self.grid.place(p.rotated_polycube, p.pos)
+        self.after_place(p)
+        if not self.grid.frontier:
+            self.set_finished()
+
+
+class ScoreSolver[H: AbstractHull](_GenericScoreSolver[H, Placement, Placement, int], ABC):
+    def _compute_best(self, candidates: Iterable[Placement]) -> tuple[Placement | None, int]:
+        """Computes the highest scoring candidate, deterministically."""
+        p = max(candidates, key=self.score)
+        return p, self.score(p)
+
+
+type _snapshots = tuple[SNAPSHOT, SNAPSHOT, SNAPSHOT]
+type _future_result = Future[tuple[SNAPSHOT, int]]
+
+
+class ParallelSolver[H: AbstractHull](_GenericScoreSolver[H, PolycubePlacement, _snapshots, _future_result]):
+    def __init__(
+        self,
+        grid: HullGrid[H],
+        polycubes: tuple[Polycube, ...],
+        scorer: Callable[[SNAPSHOT, SNAPSHOT, SNAPSHOT], tuple[SNAPSHOT, int]],
+    ):
+        super().__init__(grid, polycubes)
+        self.scorer = scorer
+
+        max_workers = os.cpu_count() or 1
+        self.ex = ProcessPoolExecutor(max_workers=max_workers)
+
+    @abstractmethod
+    def next_candidates(self) -> Sequence[PolycubePlacement]:
+        pass
+
+    def score(self, candidate: _snapshots) -> _future_result:
+        return self.ex.submit(self.scorer, *candidate)
+
+    def _compute_best(self, candidates: Iterable[PolycubePlacement]) -> tuple[Placement | None, int]:
+        grid_snap = self.grid.to_snapshot()
+        hull_snap = self.grid.hull.to_snapshot()
+
+        futures: list[_future_result] = [self.score((hull_snap, grid_snap, p.to_snapshot())) for p in candidates]
+        best_score = -100000
+        best_p: SNAPSHOT | None = None
+        for fut in futures:
+            placement, score = fut.result()
+            if score > best_score:
+                best_score = score
+                best_p = placement
+
+        return Placement.from_snapshot(best_p) if best_p is not None else None, best_score
+
+    def done(self):
+        super().done()
+        self.ex.shutdown()