ecode-cutting 0.2.3__py3-none-any.whl

ecode_cutting/models.py

@@ -0,0 +1,230 @@
+"""公开数据模型。尺寸使用调用方统一的单位，内部计算按精度转换为整数。"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+class ValidationError(ValueError):
+    """输入或计算参数不合法。"""
+
+
+class UnsupportedFeatureError(NotImplementedError):
+    """输入格式或平台专属接口尚不能在本实现中表达。"""
+
+
+@dataclass(frozen=True, slots=True)
+class Material:
+    id: str = ""
+    description: str = ""
+    thickness: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class Part:
+    width: float
+    height: float = 1.0
+    count: int = 1
+    rotatable: bool = True
+    id: str = ""
+    material: int = -1
+    angle_start: float = 0.0
+    angle_end: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class Stock:
+    width: float
+    height: float = 1.0
+    count: int = 1
+    id: str = ""
+    waste: bool = False
+    material: int = -1
+
+
+@dataclass(slots=True)
+class Options:
+    saw_width: float = 0.0
+    trim_left: float = 0.0
+    trim_top: float = 0.0
+    trim_right: float = 0.0
+    trim_bottom: float = 0.0
+    complete_mode: bool = True
+    waste_size_min: float = 0.0
+    use_layout_minimization: bool = False
+    max_cut_level: int = 2_147_483_647
+    cross_section: float = 0.0
+    linear_allow_rotate: bool = False
+    linear_exact_angle: bool = True
+    linear_allow_flipping: bool = False
+    minimize_sheet_rotation: bool = False
+    max_layout_size: int = 0
+    linear_max_size_per_stock: int = 0
+    linear_max_size_per_stock_threshold: float = 0.5
+    max_decimal_point: int = 3
+    linear_sort_ascending: bool = False
+    max_size_per_stock: int = 0
+    allow_combine_stock_regular_and_waste: bool = False
+    use_large_stock_first: bool = False
+    cut_direction: str = "auto"
+    roll_mode: bool = False
+    # 新增的显式预算控制；None 表示不限制时间，取消回调仍有效。
+    time_limit: float | None = 10.0
+    max_attempts: int = 4
+    seed: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Placement:
+    input_index: int
+    instance_index: int
+    width: float
+    height: float
+    x: float
+    y: float = 0.0
+    id: str = ""
+    material: int = -1
+    rotated: bool = False
+    flipped: bool = False
+    angle_start: float = 0.0
+    angle_end: float = 0.0
+    # 斜角零件使用真实轮廓；普通矩形留空并由宽高表示。
+    polygon: tuple[tuple[float, float], ...] = ()
+
+    @property
+    def area(self) -> float:
+        """真实轮廓面积；先平移原点，避免远离零点的坐标乘积互相消减。"""
+        if not self.polygon:
+            return self.width * self.height
+        x0, y0 = self.polygon[0]
+        points = tuple((x - x0, y - y0) for x, y in self.polygon)
+        return abs(sum(x * points[(i + 1) % len(points)][1]
+                       - points[(i + 1) % len(points)][0] * y
+                       for i, (x, y) in enumerate(points))) / 2
+
+
+@dataclass(frozen=True, slots=True)
+class Remnant:
+    width: float
+    height: float
+    x: float
+    y: float = 0.0
+    material: int = -1
+    angle: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class Cut:
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    level: int = 0
+    angle: float = 90.0
+    part_indices: tuple[int, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class StockComponent:
+    input_index: int
+    instance_index: int
+    width: float
+    id: str = ""
+    waste: bool = False
+    material: int = -1
+
+
+@dataclass(frozen=True, slots=True)
+class Layout:
+    input_index: int
+    instance_index: int
+    width: float
+    height: float
+    id: str = ""
+    material: int = -1
+    waste: bool = False
+    parts: tuple[Placement, ...] = ()
+    remnants: tuple[Remnant, ...] = ()
+    cuts: tuple[Cut, ...] = ()
+    trim_cuts: tuple[Cut, ...] = ()
+    components: tuple[StockComponent, ...] = ()
+    # 净板以外的原卷尾段，坐标相对于输入原料；不计入本次已用净板面积。
+    roll_remnants: tuple[Remnant, ...] = ()
+
+    @property
+    def all_remnants(self) -> tuple[Remnant, ...]:
+        return self.remnants + self.roll_remnants
+
+    @property
+    def fill_ratio(self) -> float:
+        area = self.width * self.height
+        return sum(p.area for p in self.parts) / area if area else 0.0
+
+    @property
+    def nominal_fill_ratio(self) -> float:
+        area = self.width * self.height
+        return sum(p.width * p.height for p in self.parts) / area if area else 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class Unplaced:
+    input_index: int
+    count: int
+    id: str = ""
+    reason: str = "没有可用且满足约束的原料"
+
+
+@dataclass(frozen=True, slots=True)
+class LayoutGroup:
+    first_layout_index: int
+    layout_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class Result:
+    layouts: tuple[Layout, ...] = ()
+    unplaced: tuple[Unplaced, ...] = ()
+    elapsed: float = 0.0
+    linear: bool = False
+    cancelled: bool = False
+    timed_out: bool = False
+    attempts: int = 0
+    layout_groups: tuple[LayoutGroup, ...] = ()
+
+    @property
+    def complete(self) -> bool:
+        return not self.unplaced
+
+    @property
+    def placed_part_count(self) -> int:
+        return sum(len(layout.parts) for layout in self.layouts)
+
+    @property
+    def used_stock_count(self) -> int:
+        return sum(len(layout.components) or 1 for layout in self.layouts)
+
+    @property
+    def fill_ratio(self) -> float:
+        area = sum(s.width * s.height for s in self.layouts)
+        return sum(p.area for s in self.layouts for p in s.parts) / area if area else 0.0
+
+    @property
+    def nominal_fill_ratio(self) -> float:
+        area = sum(s.width * s.height for s in self.layouts)
+        return sum(p.width * p.height for s in self.layouts for p in s.parts) / area if area else 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """只输出 JSON 可序列化数据，方便 Web 接口直接返回。"""
+        return {**asdict(self), "complete": self.complete,
+                "placed_part_count": self.placed_part_count,
+                "used_stock_count": self.used_stock_count, "fill_ratio": self.fill_ratio,
+                "nominal_fill_ratio": self.nominal_fill_ratio}
+
+
+@dataclass(frozen=True, slots=True)
+class Progress:
+    elapsed: float
+    placed: int = 0
+    requested: int = 0
+    attempt: int = 0

ecode_cutting/portfolio.py

@@ -0,0 +1,234 @@
+"""在同一总预算内搜索并比较独立的可行候选。"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, replace
+from math import isfinite
+from typing import Any, Callable, Sequence
+
+from ._common import Runtime, integer, normalize_options, number, validate
+from .models import Layout, Options, Part, Progress, Result, Stock, ValidationError
+
+
+def _json_value(value):
+    if isinstance(value, float) and not isfinite(value):
+        return None
+    if isinstance(value, dict):
+        return {key: _json_value(item) for key, item in value.items()}
+    if isinstance(value, (tuple, list)):
+        return [_json_value(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class PlanMetrics:
+    requested_parts: int
+    placed_parts: int
+    unplaced_parts: int
+    completion_ratio: float
+    used_stock_count: int
+    used_layout_count: int
+    total_stock_size: float
+    total_part_size: float
+    utilization: float
+    utilization_percent: float
+    cut_count: int
+    layout_count: int
+    unit: str
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationPlan:
+    id: str
+    label: str
+    strategy: dict[str, Any]
+    result: Result
+    metrics: PlanMetrics
+    pareto_optimal: bool = False
+
+    @property
+    def complete(self) -> bool:
+        return self.result.complete
+
+    @property
+    def partial(self) -> bool:
+        return not self.complete
+
+    def to_dict(self) -> dict[str, Any]:
+        # 只遍历一次大布局，避免 asdict(self) 后又重复构造同一 Result。
+        return _json_value({"id": self.id, "label": self.label, "strategy": dict(self.strategy),
+                            "result": self.result.to_dict(), "metrics": asdict(self.metrics),
+                            "pareto_optimal": self.pareto_optimal,
+                            "complete": self.complete, "partial": self.partial})
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationPortfolio:
+    plans: tuple[OptimizationPlan, ...]
+    elapsed: float
+    searches_started: int
+    searches_completed: int
+    cancelled: bool
+    timed_out: bool
+    diagnostics: tuple[str, ...] = ()
+
+    @property
+    def best(self) -> OptimizationPlan | None:
+        return self.plans[0] if self.plans else None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"plans": [plan.to_dict() for plan in self.plans], "elapsed": self.elapsed,
+                "searches_started": self.searches_started, "searches_completed": self.searches_completed,
+                "cancelled": self.cancelled, "timed_out": self.timed_out,
+                "diagnostics": list(self.diagnostics)}
+
+
+def _ring(points):
+    if not points:
+        return ()
+    points = tuple(points)
+    reverse = points[::-1]
+    return min(*(points[i:] + points[:i] for i in range(len(points))),
+               *(reverse[i:] + reverse[:i] for i in range(len(points))))
+
+
+def _layout_key(layout: Layout) -> tuple:
+    # 忽略实例编号和标签；切割顺序和真实轮廓仍是方案的一部分。
+    parts = tuple(sorted((p.width, p.height, p.x, p.y, p.material,
+                          p.angle_start, p.angle_end, _ring(p.polygon))
+                         for p in layout.parts))
+    def cuts(items):
+        return tuple((*min((c.x1, c.y1, c.x2, c.y2), (c.x2, c.y2, c.x1, c.y1)),
+                      c.level, c.angle) for c in items)
+    components = tuple((c.width, c.material, c.waste) for c in layout.components)
+    roll_remnants = tuple((r.width, r.height, r.x, r.y, r.material) for r in layout.roll_remnants)
+    return (layout.width, layout.height, layout.material, layout.waste, components,
+            parts, cuts(layout.cuts), cuts(layout.trim_cuts), roll_remnants)
+
+
+def _result_key(result: Result) -> tuple:
+    return tuple(sorted(_layout_key(layout) for layout in result.layouts))
+
+
+def _metrics(result: Result, requested: int, linear: bool) -> PlanMetrics:
+    stock_size = sum(s.width if linear else s.width * s.height for s in result.layouts)
+    part_size = sum(p.area / s.height if linear else p.area
+                    for s in result.layouts for p in s.parts)
+    utilization = part_size / stock_size if stock_size else 0.0
+    placed = result.placed_part_count
+    return PlanMetrics(requested, placed, sum(u.count for u in result.unplaced),
+                       placed / requested if requested else 1.0,
+                       result.used_stock_count, len(result.layouts), stock_size, part_size,
+                       utilization, utilization * 100,
+                       sum(len(s.cuts) + len(s.trim_cuts) for s in result.layouts),
+                       len(set(_result_key(result))), "length" if linear else "area")
+
+
+def _candidates(options: Options, maximum: int):
+    yield options
+    protected = options.use_layout_minimization and options.max_layout_size > 0
+    for index in range(1, maximum):
+        # 仅修改搜索偏好，不能改变任何加工约束。
+        yield replace(options, seed=options.seed + index,
+                      use_large_stock_first=(not options.use_large_stock_first
+                                             if index % 2 else options.use_large_stock_first),
+                      use_layout_minimization=(True if protected else
+                                               (not options.use_layout_minimization
+                                                if index % 4 >= 2 else options.use_layout_minimization)),
+                      minimize_sheet_rotation=(not options.minimize_sheet_rotation
+                                               if index % 8 >= 4 else options.minimize_sheet_rotation),
+                      linear_sort_ascending=(options.linear_sort_ascending or index % 6 >= 4),
+                      max_attempts=1 + (index // 2) % max(4, options.max_attempts))
+
+
+def _objective(plan: OptimizationPlan) -> tuple:
+    m = plan.metrics
+    return m.total_stock_size, m.used_stock_count, m.cut_count, m.layout_count
+
+
+def search_portfolio(stocks: Sequence[Stock], parts: Sequence[Part], options: Options, *,
+                     linear: bool, max_plans: int = 3, time_limit: float = 5.0,
+                     max_searches: int = 12,
+                     callback: Callable[[Progress], bool] | None = None) -> OptimizationPortfolio:
+    """返回最高完成件数的不同方案；预算为合作式检查，可能少量超时。
+
+    searches_completed 计入正常返回的求解调用，包括已返回部分解的中断调用。
+    pareto_optimal 相对于本次已搜索候选，以用料、原料数、切数及版式数评价。
+    """
+    from .engine import group_layouts
+    from .linear import solve_linear
+    from .rectangular import solve_rectangular
+
+    integer(max_plans, "max_plans", 1)
+    integer(max_searches, "max_searches", 1)
+    if callback is not None and not callable(callback):
+        raise ValidationError("callback 必须可调用")
+    budget = number(time_limit, "time_limit")
+    options = normalize_options(options)
+    stocks, parts = tuple(stocks), tuple(parts)
+    validate(stocks, parts, options, linear=linear)
+    if options.time_limit is not None:
+        budget = min(budget, options.time_limit)
+    requested = sum(p.count for p in parts)
+    total = Runtime(replace(options, time_limit=budget), requested, callback)
+    candidates: list[OptimizationPlan] = []
+    seen = set()
+    started = completed = 0
+    highest = -1
+    diagnostics = []
+    solver = solve_linear if linear else solve_rectangular
+    solver_name = "linear" if linear else "rectangular"
+    if (linear and requested > 64 and not options.waste_size_min
+            and not options.linear_max_size_per_stock and not options.max_size_per_stock
+            and all(p.angle_start in (0, 90) and p.angle_end in (0, 90) for p in parts)):
+        from ._linear_fast import solve_linear_fast
+        solver, solver_name = solve_linear_fast, "linear_fast"
+    for candidate in _candidates(options, max_searches):
+        if total.stopped(max(highest, 0), started):
+            break
+        remaining = max(0.0, budget - total.elapsed)
+        # 给首解更大份额，仍为之后的独立候选保留预算。
+        share = remaining if max_searches == started + 1 else remaining / min(4, max_searches - started)
+        runtime = Runtime(replace(candidate, time_limit=share), requested,
+                          lambda progress: total.stopped(progress.placed, started))
+        started += 1
+        result = group_layouts(solver(stocks, parts, candidate, runtime), candidate)
+        completed += 1
+        metrics = _metrics(result, requested, linear)
+        if metrics.placed_parts > highest:
+            highest = metrics.placed_parts
+            candidates.clear()
+            seen.clear()
+        key = _result_key(result)
+        if metrics.placed_parts == highest and key not in seen:
+            seen.add(key)
+            strategy = {name: getattr(candidate, name) for name in
+                        ("seed", "use_large_stock_first", "use_layout_minimization",
+                         "minimize_sheet_rotation", "max_attempts", "linear_sort_ascending")}
+            strategy["solver"] = solver_name
+            candidates.append(OptimizationPlan("", "", strategy, result, metrics))
+        if runtime.timed_out:
+            diagnostics.append(f"候选 {started} 用尽分配预算，保留已返回结果")
+        if total.stopped(max(highest, 0), started):
+            break
+
+    candidates.sort(key=_objective)
+    frontier = [not any(all(a <= b for a, b in zip(_objective(other), _objective(plan)))
+                        and _objective(other) != _objective(plan) for other in candidates)
+                for plan in candidates]
+    chosen = []
+    for index, plan in enumerate(candidates[:max_plans]):
+        m = plan.metrics
+        advantages = []
+        for field, label in (("total_stock_size", "用料较少"), ("cut_count", "切数较少"),
+                             ("layout_count", "版式较少")):
+            if getattr(m, field) == min(getattr(p.metrics, field) for p in candidates):
+                advantages.append(label)
+        label = "候选内" + "、".join(advantages) if advantages else "备选方案"
+        if plan.partial:
+            label += "（部分完成）"
+        chosen.append(replace(plan, id=f"plan-{index + 1}", label=label, pareto_optimal=frontier[index]))
+    if len(chosen) < max_plans:
+        diagnostics.append(f"本次搜索得到 {len(chosen)} 个不同的最高完成度方案")
+    return OptimizationPortfolio(tuple(chosen), total.elapsed, started, completed,
+                                 total.cancelled, total.timed_out, tuple(diagnostics))