homlab-solver 0.1.0__tar.gz

homlab_solver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Homology Lab
+
+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.

homlab_solver-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: homlab-solver
+Version: 0.1.0
+Summary: 针对单个无交叉点图的 HomLab 求解算法。
+License-Expression: MIT
+License-File: LICENSE
+Author: GGN_2015
+Author-email: neko@jlulug.org
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# homlab-solver
+
+`homlab-solver` is a small Python package for solving a single non-intersecting
+HomLab diagram stored as JSON.
+
+The package currently exposes a Python API. It does not define a command-line
+entry point yet.
+
+## Requirements
+
+- Python 3.10 or newer
+- No runtime dependencies outside the Python standard library
+
+## Installation
+
+After the package is published to PyPI:
+
+```bash
+python -m pip install homlab-solver
+```
+
+For local development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick Start
+
+```python
+import random
+
+from homlab_solver import solve_single_json
+
+rng = random.Random(42)
+result = solve_single_json("test.json", rng=rng)
+
+if result.msg:
+    raise RuntimeError(result.msg)
+
+print(result.ans)
+```
+
+You can run the same example from a shell:
+
+```bash
+python - <<'PY'
+import random
+from homlab_solver import solve_single_json
+
+result = solve_single_json("test.json", rng=random.Random(42))
+
+if result.msg:
+    raise SystemExit(result.msg)
+
+print(result.ans)
+PY
+```
+
+With the sample `test.json` in this repository, the output is:
+
+```text
+(-A^2-A^(-2)) * C[-1, 1, -2]
+```
+
+## API
+
+### `solve_single_json(filepath, rng, loop_value="(-A^2-A^(-2))", eps=1e-8)`
+
+Solves one HomLab JSON file.
+
+Parameters:
+
+- `filepath`: path to a HomLab JSON file.
+- `rng`: a `random.Random` instance used for small geometric perturbations and
+  randomized ray tests. Pass a seeded instance when you need reproducible output.
+- `loop_value`: symbolic value used for each free loop.
+- `eps`: floating-point tolerance for geometric predicates.
+
+Returns a `SolverObject` with:
+
+- `ans`: the computed symbolic answer, or `None` if solving failed.
+- `msg`: an empty string on success, or an error message on failure.
+
+## Input JSON
+
+The solver expects a JSON object describing a single HomLab diagram. At minimum,
+the file must include:
+
+```json
+{
+  "type": "homlab",
+  "n": 2,
+  "hs": {
+    "handle_genus_0000000": {"x": 0.5, "y": 0.35},
+    "handle_genus_0000001": {"x": 1.35, "y": 0.35},
+    "handle_border_0000000": {"x": 0.5, "y": -0.2},
+    "handle_border_0000001": {"x": 1.35, "y": -0.2}
+  },
+  "ns": {
+    "node_0000000": {"x": 0.0, "y": 0.0}
+  },
+  "es": {
+    "edge_0000000": {
+      "id_1": "handle_genus_0000000",
+      "id_2": "node_0000000"
+    }
+  }
+}
+```
+
+Important constraints:
+
+- `type` must be `"homlab"`.
+- `n` must be `2`.
+- The four handle IDs shown above are required by the current solver.
+- Normal node IDs should start with `node_`.
+- Handle IDs should start with `handle_`.
+- Edge objects must contain `id_1` and `id_2`.
+- IDs starting with `#` are treated as special metadata and ignored by the
+  solving step.
+- Non-handle nodes are expected to have degree `2`.
+- Handle nodes are expected to have degree `0` or `1`.
+
+## Building
+
+This project uses `poetry-core` as its build backend. To build a source
+distribution and wheel:
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+The generated artifacts will be written to `dist/`.
+
+Before uploading to PyPI, check the package metadata:
+
+```bash
+python -m pip install --upgrade twine
+python -m twine check dist/*
+```
+
+Upload to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.
+

homlab_solver-0.1.0/README.md

@@ -0,0 +1,152 @@
+# homlab-solver
+
+`homlab-solver` is a small Python package for solving a single non-intersecting
+HomLab diagram stored as JSON.
+
+The package currently exposes a Python API. It does not define a command-line
+entry point yet.
+
+## Requirements
+
+- Python 3.10 or newer
+- No runtime dependencies outside the Python standard library
+
+## Installation
+
+After the package is published to PyPI:
+
+```bash
+python -m pip install homlab-solver
+```
+
+For local development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick Start
+
+```python
+import random
+
+from homlab_solver import solve_single_json
+
+rng = random.Random(42)
+result = solve_single_json("test.json", rng=rng)
+
+if result.msg:
+    raise RuntimeError(result.msg)
+
+print(result.ans)
+```
+
+You can run the same example from a shell:
+
+```bash
+python - <<'PY'
+import random
+from homlab_solver import solve_single_json
+
+result = solve_single_json("test.json", rng=random.Random(42))
+
+if result.msg:
+    raise SystemExit(result.msg)
+
+print(result.ans)
+PY
+```
+
+With the sample `test.json` in this repository, the output is:
+
+```text
+(-A^2-A^(-2)) * C[-1, 1, -2]
+```
+
+## API
+
+### `solve_single_json(filepath, rng, loop_value="(-A^2-A^(-2))", eps=1e-8)`
+
+Solves one HomLab JSON file.
+
+Parameters:
+
+- `filepath`: path to a HomLab JSON file.
+- `rng`: a `random.Random` instance used for small geometric perturbations and
+  randomized ray tests. Pass a seeded instance when you need reproducible output.
+- `loop_value`: symbolic value used for each free loop.
+- `eps`: floating-point tolerance for geometric predicates.
+
+Returns a `SolverObject` with:
+
+- `ans`: the computed symbolic answer, or `None` if solving failed.
+- `msg`: an empty string on success, or an error message on failure.
+
+## Input JSON
+
+The solver expects a JSON object describing a single HomLab diagram. At minimum,
+the file must include:
+
+```json
+{
+  "type": "homlab",
+  "n": 2,
+  "hs": {
+    "handle_genus_0000000": {"x": 0.5, "y": 0.35},
+    "handle_genus_0000001": {"x": 1.35, "y": 0.35},
+    "handle_border_0000000": {"x": 0.5, "y": -0.2},
+    "handle_border_0000001": {"x": 1.35, "y": -0.2}
+  },
+  "ns": {
+    "node_0000000": {"x": 0.0, "y": 0.0}
+  },
+  "es": {
+    "edge_0000000": {
+      "id_1": "handle_genus_0000000",
+      "id_2": "node_0000000"
+    }
+  }
+}
+```
+
+Important constraints:
+
+- `type` must be `"homlab"`.
+- `n` must be `2`.
+- The four handle IDs shown above are required by the current solver.
+- Normal node IDs should start with `node_`.
+- Handle IDs should start with `handle_`.
+- Edge objects must contain `id_1` and `id_2`.
+- IDs starting with `#` are treated as special metadata and ignored by the
+  solving step.
+- Non-handle nodes are expected to have degree `2`.
+- Handle nodes are expected to have degree `0` or `1`.
+
+## Building
+
+This project uses `poetry-core` as its build backend. To build a source
+distribution and wheel:
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+The generated artifacts will be written to `dist/`.
+
+Before uploading to PyPI, check the package metadata:
+
+```bash
+python -m pip install --upgrade twine
+python -m twine check dist/*
+```
+
+Upload to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

homlab_solver-0.1.0/homlab_solver/__init__.py

@@ -0,0 +1,5 @@
+from .main import solve_single_json
+
+__all__ = [
+    "solve_single_json"
+]

homlab_solver-0.1.0/homlab_solver/geo.py

@@ -0,0 +1,90 @@
+import math
+import random
+from typing import List, Tuple
+
+
+def vec_sub(p1: Tuple[float, float], p2: Tuple[float, float]) -> Tuple[float, float]:
+    """
+    两点相减得到向量: p1 - p2
+    :param p1: 起点坐标 (x, y)
+    :param p2: 终点坐标 (x, y)
+    :return: 二维向量 (dx, dy)
+    """
+    return (p1[0] - p2[0], p1[1] - p2[1])
+
+
+def vec_cross(v1: Tuple[float, float], v2: Tuple[float, float]) -> float:
+    """
+    计算两个二维向量的叉积（标量结果）
+    :param v1: 向量1 (x1, y1)
+    :param v2: 向量2 (x2, y2)
+    :return: 叉积值 = x1*y2 - y1*x2
+    """
+    return v1[0] * v2[1] - v1[1] * v2[0]
+
+def ray_segment_intersect(
+    ray_origin: Tuple[float, float],
+    ray_dir: Tuple[float, float],
+    seg_p1: Tuple[float, float],
+    seg_p2: Tuple[float, float],
+    eps: float
+) -> bool:
+    """
+    判断射线与线段是否相交
+    :param ray_origin: 射线起点 (x, y)
+    :param ray_dir: 射线方向向量 (dx, dy)
+    :param seg_p1: 线段端点1
+    :param seg_p2: 线段端点2
+    :param eps: 浮点精度阈值
+    :return: 相交返回 True，否则 False
+    """
+    x0, y0 = ray_origin
+    dx_r, dy_r = ray_dir
+    x1, y1 = seg_p1
+    x2, y2 = seg_p2
+
+    den = (x2 - x1) * dy_r - (y2 - y1) * dx_r
+    if abs(den) < eps:
+        return False
+
+    t_numer = (x0 - x1) * dy_r - (y0 - y1) * dx_r
+    s_numer = (x0 - x1) * (y2 - y1) - (y0 - y1) * (x2 - x1)
+
+    t = t_numer / den
+    s = s_numer / den
+
+    # t ∈ [0,1] 在线段内，s > 0 在射线正方向
+    return (0.0 - eps <= t <= 1.0 + eps) and (s > eps)
+
+
+def point_in_ring(
+    ring: List[Tuple[float, float]],
+    p: Tuple[float, float],
+    rng: random.Random,
+    eps: float = 1e-12
+) -> bool:
+    """
+    随机射线法判断二维点是否在简单闭合环内部
+    :param ring: 环顶点列表 [(x,y), ...]，简单无自交环
+    :param p: 待检测点 (x0, y0)
+    :param rng: 外部传入的随机数生成器对象
+    :param eps: 浮点计算精度阈值
+    :return: True=点在圈内，False=点在圈外
+    """
+    x0, y0 = p
+    intersect_count = 0
+    n = len(ring)
+    if n < 3:
+        return False
+
+    # 生成随机方向射线
+    angle = rng.uniform(0.0, math.pi * 2)
+    ray_dir = (math.cos(angle), math.sin(angle))
+
+    for i in range(n):
+        p1 = ring[i]
+        p2 = ring[(i + 1) % n]
+        if ray_segment_intersect(p, ray_dir, p1, p2, eps):
+            intersect_count += 1
+
+    return intersect_count % 2 == 1

homlab_solver-0.1.0/homlab_solver/main.py

@@ -0,0 +1,249 @@
+from typing import Optional
+from dataclasses import dataclass
+import os
+import json
+import random
+
+# 几何运算函数
+try:
+    from .geo import ray_segment_intersect, point_in_ring, vec_sub, vec_cross
+except:
+    from geo import ray_segment_intersect, point_in_ring, vec_sub, vec_cross
+
+@dataclass
+class SolverObject:
+    ans:Optional[str] = None # 计算结果
+    msg:str = ""             # 错误信息（空字符串表示没有错误）
+
+# 统计节点的 “度”
+def count_degree_solve_nxt(ns:dict[str, dict], es:dict[str, dict]) -> tuple[dict[str, int], dict[str, set[str]]]:
+    degree_of_node = dict()
+    nxt_node_dict:dict[str, set[str]] = dict()
+    for node_id in ns:
+        degree_of_node[node_id] = 0
+        nxt_node_dict[node_id] = set() # 记录所有后继节点
+    
+    # 统计节点度（连接了两个节点）
+    for edge_id in es:
+        node_id_1 = es[edge_id]["id_1"]
+        node_id_2 = es[edge_id]["id_2"]
+        degree_of_node[node_id_1] += 1
+        degree_of_node[node_id_2] += 1
+        nxt_node_dict[node_id_1].add(node_id_2)
+        nxt_node_dict[node_id_2].add(node_id_1)
+    
+    # 返回节点度和所有后继节点
+    return degree_of_node, nxt_node_dict
+
+# 给定一个 JSON 文件描述的无交叉点图
+# 计算它对应的多项式项（目前不根据文件名分析 A 的次数）
+def solve_single_json(filepath:str, rng:random.Random, loop_value:str="(-A^2-A^(-2))", eps=1e-8) -> SolverObject:
+
+    # 文件不存在
+    if not os.path.isfile(filepath):
+        return SolverObject(msg=f"file {filepath} not found.")
+    
+    # 先试图加载出文件中的所有数据，得到 data_dict
+    try:
+        data_dict = dict()
+        with open(filepath, "r", encoding="utf-8") as fpin:
+            data_dict = json.load(fpin)
+    except Exception as err:
+        return SolverObject(msg=f"Error when reading file {filepath}: {err}.")
+    
+    # 检查文件类型标记
+    if data_dict.get("type") != "homlab":
+        return SolverObject(msg=f"Type of {filepath} is not homlab.")
+    
+    # ns 中记录了所有节点（包括 handle 节点）的坐标信息
+    ns = data_dict["ns"]
+    hs = data_dict["hs"] # 注意，root 的结构不是太一样，root 的结构 ns 里面没有 handle
+    for hid in hs:
+        if ns.get(hid) is None:
+            ns[hid] = {
+                "x": hs[hid]["x"], # 记录这个信息到 nid
+                "y": hs[hid]["y"]
+            }
+    es = data_dict["es"] # 记录了所有边的信息
+
+    # 叠加一个随机的小变量
+    for nid in ns:
+        if nid.startswith("#"): # 如果是一个特殊变量
+            continue
+        ns[nid]["x"] += rng.uniform(eps*-30, eps*30)
+        ns[nid]["y"] += rng.uniform(eps*-30, eps*30)
+
+    # 删掉特殊节点与特殊边
+    for node_id in [nid for nid in ns]:
+        if node_id.startswith('#'):
+            del ns[node_id]
+    for edge_id in [eid for eid in es]:
+        if edge_id.startswith('#'):
+            del es[edge_id]
+
+    # 确保图中只有两个 genus，目前我的算法不能计算两个 genus 以外的东西
+    genus_cnt = data_dict["n"]
+    if genus_cnt != 2:
+        return SolverObject(msg=f"Genus count of {filepath} is not 2.")
+    
+    # 统计节点的度
+    degree_dict, nxt_node_dict = count_degree_solve_nxt(ns, es)
+    erased_node_list = []
+    for node_id in degree_dict:
+
+        # 如果一个节点没有度，那么我们就把他从 ns 中删掉
+        if degree_dict[node_id] == 0 and (not node_id.startswith("handle_")):
+            erased_node_list.append(node_id)
+
+    # 删除应该删除的节点
+    for node_id in erased_node_list:
+        del ns[node_id]
+        del degree_dict[node_id]
+
+    # vis 数组中记录遍历过程中某个节点是否已经访问过
+    vis = dict()
+    for node_id in ns:
+        vis[node_id] = 0 # 记录成没有访问过
+
+    # 开始和结束点必须是 handle_ 节点
+    # handle_ 节点度为 0 或 1，非 handle_ 节点度应该为 2（不为 2 说明线不合法）
+    for node_id in degree_dict:
+
+        # 抓手节点的度应该为 0 或者 1
+        if node_id.startswith("handle_"):
+            if degree_dict[node_id] not in [0, 1]:
+                return SolverObject(msg=f"Degree of {node_id} ({degree_dict[node_id]}) not in [0, 1].")
+        
+        # 普通节点的度应该为 2
+        else:
+            assert node_id.startswith("node_")
+            if degree_dict[node_id] != 2:
+                return SolverObject(msg=f"Degree of {node_id} ({degree_dict[node_id]}) != 2.")
+
+    # 确定图片中 “下” 的方向
+    # 用 0 号节点，从 handle_border 指向 handle_genus_ 确定
+    # 从 border 指向 genus 的方向（down_x  和 down_y 中必然有一个 0）
+    down_x = (hs["handle_genus_0000000"]["x"] - hs["handle_border_0000000"]["x"])
+    down_y = (hs["handle_genus_0000000"]["y"] - hs["handle_border_0000000"]["y"])
+
+    # 记录右侧的方向
+    # 这里可以从左指向右侧
+    right_x = (hs["handle_genus_0000001"]["x"] - hs["handle_genus_0000000"]["x"])
+    right_y = (hs["handle_genus_0000001"]["y"] - hs["handle_genus_0000000"]["y"])
+
+    # 这个向量必须是指向平面外
+    # 理论上是向下的但是这里手性反转了，扎心
+    assert vec_cross((right_x, right_y), (down_x, down_y)) > 0
+
+    # 记录所有链，将节点编号映射到链编号与链内序号
+    def _node_dfs(node_id_now:str, chain_now:list):
+        if vis[node_id_now] != 0: # 每个节点至多访问一次
+            return
+        vis[node_id_now] = 1
+        chain_now.append(node_id_now) # 在两侧的节点递归
+        for node_id in nxt_node_dict[node_id_now]:
+            _node_dfs(node_id, chain_now)
+
+    # 记录所有链条
+    # 先遍历那些从 genus 开头的链条
+    chain_list = []
+    loop_list = []
+    for handle_id in hs:
+        if handle_id.startswith("handle_genus"): # 我们从 genus 出发向外遍历
+            if vis[handle_id] == 0 and degree_dict[handle_id] >= 1:
+                chain_list.append([])
+                _node_dfs(handle_id, chain_list[-1]) # 在新建的 list 上面做遍历
+    
+    # 继续试图遍历那些度为 2 的节点
+    # 这样可以得到所有的环
+    for node_id in ns:
+        if not vis[node_id] and degree_dict[node_id] == 2:
+            loop_list.append([])
+            _node_dfs(node_id, loop_list[-1]) # 在新建的 list 上面做遍历
+
+    # 将点的名字序列映射成坐标序列
+    def _get_coord_from_chain(nid_list:list[str]) -> list[tuple[float, float]]:
+        return [
+            (ns[nid]["x"], ns[nid]["y"]) # 获取坐标
+            for nid in nid_list
+        ]
+
+    # 获取 1 号 genus 的坐标（左侧的东西是零号 genus）
+    genus1_x = hs["handle_genus_0000001"]["x"]
+    genus1_y = hs["handle_genus_0000001"]["y"]
+
+    # 记录有多少个会影响 C 的圈
+    c_second = 0
+    loop_free = 0 # 记录有多少个可缩的东西
+
+    # 对于所有的环，我们需要判断空心环有多少个
+    # 包含了 0 degree 的 handle_genus_0000001 的环有多少个，两者分别统计
+    for loop in loop_list:
+        coord_of_loop = _get_coord_from_chain(loop)
+        if point_in_ring(coord_of_loop, (genus1_x, genus1_y), rng): # 这是一个会影响 C 的圈
+            c_second += 1
+        else:
+            loop_free += 1
+
+    # 我们需要给所有在 chain 上面的点进行编号
+    # 这样我们就可以通过相邻的 node 的 rank 的大小确定走向
+    node_rank = 0
+    node_map_to_node_rank:dict[str, int] = dict()
+    for chain in chain_list:
+        for nid in chain: # 按照 chain 上面的顺序递增
+            node_rank += 1
+            node_map_to_node_rank[nid] = node_rank
+
+    crs_cnt = []
+
+    # 我们需要计算 genus0 和 genus1 下方的所有跨越
+    for px, py in [
+        (hs["handle_genus_0000000"]["x"], hs["handle_genus_0000000"]["y"]),
+        (hs["handle_genus_0000001"]["x"], hs["handle_genus_0000001"]["y"])
+    ]:
+        crs_cnt.append(0) # 这里记录一个新的跨越数量
+        for eid in es:
+            nid_1 = es[eid]["id_1"]
+            nid_2 = es[eid]["id_2"]
+            # 跳过那些不在 chain 上的东西
+            if node_map_to_node_rank.get(nid_1) is None or node_map_to_node_rank.get(nid_2) is None:
+                continue
+            if node_map_to_node_rank[nid_1] >= node_map_to_node_rank[nid_2]: # 保证前进方向从 nid_1 到 nid_2
+                nid_1, nid_2 = nid_2, nid_1
+            assert node_map_to_node_rank[nid_1] < node_map_to_node_rank[nid_2]
+            n1_x = ns[nid_1]["x"] # 获取两个节点的坐标
+            n1_y = ns[nid_1]["y"]
+            n2_x = ns[nid_2]["x"]
+            n2_y = ns[nid_2]["y"]
+            # 计算与射线相交的线段
+            if ray_segment_intersect(
+                (px, py), (down_x, down_y), (n1_x, n1_y), (n2_x, n2_y), eps=eps):
+
+                # 获得一个从 genus 上端到起始节点的向量
+                vec_to_node = vec_sub((n1_x, n1_y), (px, py))
+                if vec_cross(vec_to_node, (down_x, down_y)) > 0:
+                    crs_cnt[-1] = crs_cnt[-1] - 1 # 从右到左的 -1， 从左到右是 +1，行为和 right 一致的是 -1
+                else:
+                    crs_cnt[-1] = crs_cnt[-1] + 1
+    
+    # 计算编码
+    crs_cnt[0] -= crs_cnt[1]
+    crs_value = f"C[{crs_cnt[0]}, {c_second}, {crs_cnt[1]}]"
+
+    if loop_free == 0:
+        return SolverObject(
+            ans=crs_value
+        )
+    else:
+        if loop_free == 1:
+            return SolverObject(
+                ans=loop_value + f" * " + crs_value
+            )
+        else:
+            return SolverObject(
+                ans=loop_value + f"^{loop_free} * " + crs_value
+            )
+
+if __name__ == "__main__":
+    rng = random.Random(42)
+    print(solve_single_json("root.json", rng=rng))

homlab_solver-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "homlab-solver"
+version = "0.1.0"
+description = "针对单个无交叉点图的 HomLab 求解算法。"
+authors = [
+    {name = "GGN_2015",email = "neko@jlulug.org"}
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"