feat: update engine modules, remove research 2 docs

engine/fold_engine.py

@@ -151,6 +151,8 @@ def apply_fold(
             elif face_sides[i] == "fixed" and face_sides[j] == "rotated":
                 new_paper.face_orders.append((j, i, 1))
 
+    new_paper.fold_count += 1
+
     return new_paper, None
 
 
@@ -205,3 +207,43 @@ def execute_fold_strategy(
         applied.append(fold)
 
     return current, applied, None
+
+
+def apply_pleat(
+    paper: Paper,
+    line1: dict,
+    line2: dict,
+    angle: float = 180.0,
+) -> tuple[Paper, str | None]:
+    """Pleat fold: valley at line1, mountain at line2 (two parallel folds).
+
+    Both line dicts have the form: {"start": [x, y], "end": [x, y]}
+    Returns (new_paper, error_or_None).
+    """
+    paper, err = apply_fold(paper, {"type": "valley", "line": line1, "angle": angle})
+    if err:
+        return paper, f"Pleat valley fold failed: {err}"
+    paper, err = apply_fold(paper, {"type": "mountain", "line": line2, "angle": angle})
+    if err:
+        return paper, f"Pleat mountain fold failed: {err}"
+    return paper, None
+
+
+def apply_crimp(
+    paper: Paper,
+    line1: dict,
+    line2: dict,
+    angle: float = 180.0,
+) -> tuple[Paper, str | None]:
+    """Crimp fold: mountain at line1, valley at line2 (reverse of pleat).
+
+    Both line dicts have the form: {"start": [x, y], "end": [x, y]}
+    Returns (new_paper, error_or_None).
+    """
+    paper, err = apply_fold(paper, {"type": "mountain", "line": line1, "angle": angle})
+    if err:
+        return paper, f"Crimp mountain fold failed: {err}"
+    paper, err = apply_fold(paper, {"type": "valley", "line": line2, "angle": angle})
+    if err:
+        return paper, f"Crimp valley fold failed: {err}"
+    return paper, None

engine/metrics.py

@@ -102,3 +102,130 @@ def compute_metrics(paper: Paper, original_paper: Paper | None = None) -> dict:
         "num_faces": len(paper.faces),
         "num_layers": paper.num_layers,
     }
+
+
+def compute_all_metrics(paper, task: dict, validation: dict) -> dict:
+    """Compute every metric and return a flat dict.
+
+    Called after physics + validation. Combines validity, compactness,
+    structural, efficiency, and deployability metrics.
+
+    Parameters
+    ----------
+    paper : Paper
+        Current paper state (after simulate()).
+    task : dict
+        Task definition with keys: width, height, target_ratio, target_box, must_deploy.
+    validation : dict
+        Output of validate_state(paper).
+    """
+    import numpy as np
+
+    bb = paper.bounding_box  # (3,) array
+    original_area = paper.original_area if paper.original_area > 0 else (paper.material.thickness_mm / 1000.0)
+    t = paper.material.thickness_mm / 1000.0
+    original_bbox_vol = original_area * t
+    folded_bbox_vol = float(bb[0] * bb[1] * bb[2]) if bb[2] > 0 else float(bb[0] * bb[1] * t)
+
+    # ── Folded area (XY footprint) ────────────────────────────────
+    if len(paper.vertices) >= 3:
+        try:
+            from scipy.spatial import ConvexHull
+            hull = ConvexHull(paper.vertices[:, :2])
+            folded_area = float(hull.volume)
+        except Exception:
+            ptp = np.ptp(paper.vertices[:, :2], axis=0)
+            folded_area = float(ptp[0] * ptp[1])
+    else:
+        folded_area = original_area
+
+    deployment_ratio = folded_area / original_area if original_area > 0 else 1.0
+    compactness = 1.0 - deployment_ratio
+    volume_compaction = folded_bbox_vol / original_bbox_vol if original_bbox_vol > 0 else 1.0
+    material_volume = original_area * t
+    packing_efficiency = material_volume / folded_bbox_vol if folded_bbox_vol > 0 else 0.0
+
+    # ── Target box check ─────────────────────────────────────────
+    target_box = task.get("target_box")
+    fits_target_box = False
+    if target_box and len(target_box) == 3:
+        fits_target_box = bool(
+            bb[0] <= target_box[0] + 1e-6 and
+            bb[1] <= target_box[1] + 1e-6 and
+            bb[2] <= target_box[2] + 1e-6
+        )
+
+    # ── Strain ───────────────────────────────────────────────────
+    strain = paper.strain_per_vertex
+    max_strain = float(np.max(strain)) if len(strain) > 0 else 0.0
+    mean_strain = float(np.mean(strain)) if len(strain) > 0 else 0.0
+
+    # ── Energy ───────────────────────────────────────────────────
+    energy = paper.energy
+
+    # ── Efficiency ───────────────────────────────────────────────
+    fold_count = paper.fold_count
+
+    # Crease complexity: entropy of M/V assignment distribution
+    mv_assignments = [a for a in paper.assignments if a in ("M", "V")]
+    if mv_assignments:
+        total = len(mv_assignments)
+        m_count = mv_assignments.count("M")
+        v_count = mv_assignments.count("V")
+        p_m = m_count / total if total > 0 else 0
+        p_v = v_count / total if total > 0 else 0
+        crease_complexity = 0.0
+        if p_m > 0:
+            crease_complexity -= p_m * np.log2(p_m)
+        if p_v > 0:
+            crease_complexity -= p_v * np.log2(p_v)
+    else:
+        crease_complexity = 0.0
+
+    folding_efficiency = compactness / max(fold_count, 1)
+
+    # ── Deployability ─────────────────────────────────────────────
+    must_deploy = task.get("must_deploy", False)
+    # Simple deployability heuristic: if valid and compactness > 0, assume deployable
+    is_deployable = bool(validation.get("is_valid", False) and compactness > 0.01) if must_deploy else None
+    # Deployment force estimate from total energy gradient (rough)
+    deployment_force_estimate = float(energy.get("fold", 0.0)) / max(paper.original_area, 1e-6)
+
+    return {
+        # Validity (from validation dict)
+        "is_valid": validation.get("is_valid", False),
+        "kawasaki_violations": validation.get("kawasaki_violations", 0),
+        "kawasaki_total_error": validation.get("kawasaki_total_error", 0.0),
+        "maekawa_violations": validation.get("maekawa_violations", 0),
+        "self_intersections": validation.get("self_intersections", 0),
+        "strain_exceeded": validation.get("strain_exceeded", False),
+
+        # Compactness
+        "deployment_ratio": float(deployment_ratio),
+        "compactness": float(compactness),
+        "volume_compaction": float(volume_compaction),
+        "packing_efficiency": float(packing_efficiency),
+        "fits_target_box": fits_target_box,
+        "bounding_box": bb.tolist(),
+
+        # Structural
+        "max_strain": max_strain,
+        "mean_strain": mean_strain,
+        "total_energy": float(energy.get("total", 0.0)),
+        "energy_bar": float(energy.get("bar", 0.0)),
+        "energy_facet": float(energy.get("facet", 0.0)),
+        "energy_fold": float(energy.get("fold", 0.0)),
+
+        # Efficiency
+        "fold_count": fold_count,
+        "folding_efficiency": float(folding_efficiency),
+        "crease_complexity": float(crease_complexity),
+
+        # Deployability
+        "is_deployable": is_deployable,
+        "deployment_force_estimate": float(deployment_force_estimate),
+
+        # Shape similarity placeholders
+        "chamfer_distance": None,
+        "hausdorff_distance": None,
+    }

engine/paper.py

@@ -89,6 +89,10 @@ class Paper:
     material: Material = field(default_factory=lambda: get_material("paper"))
     rest_lengths: np.ndarray = field(default_factory=lambda: np.empty(0))
     original_area: float = 0.0
+    rest_positions: np.ndarray = field(default_factory=lambda: np.empty((0, 3)))
+    strain_per_vertex: np.ndarray = field(default_factory=lambda: np.empty(0))
+    energy: dict = field(default_factory=lambda: {"total": 0.0, "bar": 0.0, "facet": 0.0, "fold": 0.0})
+    fold_count: int = 0
 
     # ── constructors ────────────────────────────────────────────────
 
@@ -125,7 +129,7 @@ class Paper:
             dtype=np.float64,
         )
 
-        return Paper(
+        paper = Paper(
             vertices=verts,
             edges=edges,
             faces=faces,
@@ -135,6 +139,8 @@ class Paper:
             rest_lengths=rest_lengths,
             original_area=width * height,
         )
+        paper.rest_positions = verts.copy()
+        return paper
 
     # ── dict / prompt serialization (matches mock_env.PaperState.to_dict) ──
 
@@ -165,6 +171,33 @@ class Paper:
             },
         }
 
+    def to_observation_dict(self) -> dict:
+        bb = self.bounding_box
+        return {
+            "vertices_coords": self.vertices.tolist(),
+            "edges_vertices": self.edges.tolist(),
+            "faces_vertices": self.faces,
+            "edges_assignment": list(self.assignments),
+            "edges_foldAngle": self.fold_angles.tolist(),
+            "num_vertices": len(self.vertices),
+            "num_edges": len(self.edges),
+            "num_faces": len(self.faces),
+            "bounding_box": bb.tolist(),
+            "num_layers": self.num_layers,
+            "material": {
+                "name": self.material.name,
+                "thickness_mm": self.material.thickness_mm,
+                "youngs_modulus_gpa": self.material.youngs_modulus_gpa,
+                "max_strain": self.material.max_strain,
+                "poisson_ratio": self.material.poissons_ratio,
+            },
+            "strain_per_vertex": self.strain_per_vertex.tolist(),
+            "energy": dict(self.energy),
+            "fold_count": self.fold_count,
+            "width": float(self.original_area ** 0.5) if self.original_area > 0 else 1.0,
+            "height": float(self.original_area ** 0.5) if self.original_area > 0 else 1.0,
+        }
+
     # ── FOLD format serialization ───────────────────────────────────
 
     def to_fold_json(self) -> str:
@@ -485,4 +518,8 @@ class Paper:
             ),
             rest_lengths=self.rest_lengths.copy(),
             original_area=self.original_area,
+            rest_positions=self.rest_positions.copy(),
+            strain_per_vertex=self.strain_per_vertex.copy(),
+            energy=dict(self.energy),
+            fold_count=self.fold_count,
         )

engine/physics.py

@@ -255,3 +255,263 @@ def _face_normal(verts: np.ndarray, face: list[int]) -> np.ndarray | None:
     if norm < 1e-15:
         return None
     return normal / norm
+
+
+# ────────────────────────────────────────────────────────────────────
+# Topology precomputation
+# ────────────────────────────────────────────────────────────────────
+
+def build_beam_list(paper: Paper) -> list[tuple[int, int, float, float]]:
+    """Build list of (node_a, node_b, rest_len, k_axial) for every edge.
+
+    Uses normalized stiffness values (arch doc constants) scaled by material
+    Young's modulus ratio — keeps the Verlet integrator stable at unit scale.
+    """
+    # Normalized stiffness constants (arch doc values)
+    K_AXIAL_BASE = 70.0
+    # Scale by material: paper (3 GPa) = 1.0 baseline
+    mat = paper.material
+    E_ratio = mat.youngs_modulus_gpa / 3.0
+    k_axial = K_AXIAL_BASE * E_ratio
+
+    beams = []
+    for ei, (v1, v2) in enumerate(paper.edges):
+        L0 = paper.rest_lengths[ei]
+        beams.append((int(v1), int(v2), float(L0), float(k_axial)))
+    return beams
+
+
+def build_crease_list(paper: Paper) -> list[tuple[int, int, int, int, float, float, str]]:
+    """Build list of (n1, n2, n3, n4, target_angle_rad, k, type) for each crease hinge.
+
+    Each hinge is defined by 4 nodes: n1-n2 is the hinge edge, n3 and n4 are
+    the wing-tip nodes of the two adjacent faces.
+    type is 'fold' (M/V crease) or 'facet' (interior flat edge).
+    """
+    verts = paper.vertices
+
+    # Build edge → face adjacency
+    edge_faces: dict[int, list[int]] = {}
+    for fi, face in enumerate(paper.faces):
+        n = len(face)
+        for k in range(n):
+            va, vb = face[k], face[(k + 1) % n]
+            for ei, e in enumerate(paper.edges):
+                if (e[0] == va and e[1] == vb) or (e[0] == vb and e[1] == va):
+                    edge_faces.setdefault(ei, []).append(fi)
+                    break
+
+    creases = []
+    for ei, adj in edge_faces.items():
+        if len(adj) < 2:
+            continue
+        f1, f2 = adj[0], adj[1]
+        face1, face2 = paper.faces[f1], paper.faces[f2]
+        n1, n2 = int(paper.edges[ei][0]), int(paper.edges[ei][1])
+
+        # Find wing-tip nodes (in each face, the vertex NOT on the shared edge)
+        wing1 = [v for v in face1 if v != n1 and v != n2]
+        wing2 = [v for v in face2 if v != n1 and v != n2]
+        if not wing1 or not wing2:
+            continue
+        n3, n4 = int(wing1[0]), int(wing2[0])
+
+        # Normalized stiffness constants (arch doc values), scaled by material
+        E_ratio = paper.material.youngs_modulus_gpa / 3.0
+        K_FACET = 0.2 * E_ratio
+        K_FOLD = 0.7 * E_ratio
+
+        asgn = paper.assignments[ei]
+        if asgn in ("M", "V"):
+            target = float(np.radians(paper.fold_angles[ei]))
+            k = K_FOLD
+            ctype = "fold"
+        else:
+            target = float(np.pi)
+            k = K_FACET
+            ctype = "facet"
+
+        creases.append((n1, n2, n3, n4, target, k, ctype))
+    return creases
+
+
+def _torque_to_forces(
+    p1: np.ndarray, p2: np.ndarray,
+    p3: np.ndarray, p4: np.ndarray,
+    torque: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Convert a dihedral torque into forces on the 4 hinge nodes.
+
+    p1-p2 is the hinge edge. p3 and p4 are wing tips.
+    Returns (f1, f2, f3, f4) as (3,) arrays.
+    """
+    e = p2 - p1
+    e_len = np.linalg.norm(e)
+    if e_len < 1e-12:
+        zero = np.zeros(3)
+        return zero, zero, zero, zero
+
+    e_hat = e / e_len
+
+    # Perpendicular components of wing vectors relative to hinge
+    d3 = p3 - p1
+    d4 = p4 - p1
+    d3_perp = d3 - np.dot(d3, e_hat) * e_hat
+    d4_perp = d4 - np.dot(d4, e_hat) * e_hat
+
+    len3 = np.linalg.norm(d3_perp)
+    len4 = np.linalg.norm(d4_perp)
+
+    if len3 < 1e-12 or len4 < 1e-12:
+        zero = np.zeros(3)
+        return zero, zero, zero, zero
+
+    # Force on wing tips proportional to torque / lever arm
+    f3 = torque / (len3 * e_len) * np.cross(e_hat, d3_perp / len3)
+    f4 = -torque / (len4 * e_len) * np.cross(e_hat, d4_perp / len4)
+
+    # Reaction forces distributed to hinge nodes
+    f1 = -(f3 + f4) * 0.5
+    f2 = -(f3 + f4) * 0.5
+
+    return f1, f2, f3, f4
+
+
+# ────────────────────────────────────────────────────────────────────
+# Verlet solver
+# ────────────────────────────────────────────────────────────────────
+
+def simulate(
+    paper: Paper,
+    fold_percent: float = 1.0,
+    n_steps: int = 500,
+    dt: float = 0.005,
+    damping: float = 0.15,
+) -> Paper:
+    """Run bar-and-hinge Verlet integration to relax the mesh.
+
+    Updates paper.vertices, paper.strain_per_vertex, and paper.energy in-place.
+    Returns the mutated paper for chaining.
+
+    Parameters
+    ----------
+    paper : Paper
+        Paper state after a fold has been applied (vertices already rotated).
+    fold_percent : float
+        How far along the fold to drive (0=flat, 1=full target angle).
+    n_steps : int
+        Maximum integration steps.
+    dt : float
+        Time step. Keep small (0.005) for stability with stiff materials.
+    damping : float
+        Velocity damping coefficient (0=undamped, 1=fully damped).
+    """
+    if len(paper.vertices) == 0:
+        return paper
+
+    beams = build_beam_list(paper)
+    creases = build_crease_list(paper)
+
+    pos = paper.vertices.copy()        # (N, 3) current positions
+    last_pos = pos.copy()              # (N, 3) previous positions (Verlet)
+
+    max_force_cap = 1e6  # prevent runaway forces
+
+    for _ in range(n_steps):
+        forces = np.zeros_like(pos)
+
+        # ── Beam (axial spring) forces ───────────────────────────────
+        for (a, b, L0, k) in beams:
+            delta = pos[b] - pos[a]
+            L = np.linalg.norm(delta)
+            if L < 1e-12:
+                continue
+            strain = (L - L0) / L0
+            F_mag = k * strain
+            F_vec = F_mag * (delta / L)
+            # Clamp to prevent instability
+            F_vec = np.clip(F_vec, -max_force_cap, max_force_cap)
+            forces[a] += F_vec
+            forces[b] -= F_vec
+
+        # ── Crease (dihedral spring) forces ─────────────────────────
+        for (n1, n2, n3, n4, target, k, ctype) in creases:
+            actual_target = target * fold_percent if ctype == "fold" else target
+            try:
+                theta = _compute_dihedral_rad(pos[n1], pos[n2], pos[n3], pos[n4])
+            except Exception:
+                continue
+            delta_theta = theta - actual_target
+            edge_len = np.linalg.norm(pos[n2] - pos[n1])
+            torque = k * edge_len * delta_theta
+            torque = float(np.clip(torque, -max_force_cap, max_force_cap))
+
+            f1, f2, f3, f4 = _torque_to_forces(
+                pos[n1], pos[n2], pos[n3], pos[n4], torque
+            )
+            forces[n1] += np.clip(f1, -max_force_cap, max_force_cap)
+            forces[n2] += np.clip(f2, -max_force_cap, max_force_cap)
+            forces[n3] += np.clip(f3, -max_force_cap, max_force_cap)
+            forces[n4] += np.clip(f4, -max_force_cap, max_force_cap)
+
+        # ── Verlet integration ───────────────────────────────────────
+        new_pos = pos + (1.0 - damping) * (pos - last_pos) + forces * (dt * dt)
+
+        # NaN guard
+        if np.any(np.isnan(new_pos)):
+            break
+
+        last_pos = pos
+        pos = new_pos
+
+        # ── Convergence check ────────────────────────────────────────
+        kinetic = np.sum((pos - last_pos) ** 2)
+        if kinetic < 1e-12:
+            break
+
+    # ── Write results back to paper ──────────────────────────────────
+    paper.vertices = pos
+    paper.strain_per_vertex = compute_strain(paper)
+    paper.energy = {
+        "total": compute_total_energy(paper),
+        "bar": compute_bar_energy(paper),
+        "facet": compute_facet_energy(paper),
+        "fold": compute_fold_energy(paper),
+    }
+
+    return paper
+
+
+def _compute_dihedral_rad(
+    p1: np.ndarray, p2: np.ndarray,
+    p3: np.ndarray, p4: np.ndarray,
+) -> float:
+    """Dihedral angle in radians between planes (p1,p2,p3) and (p1,p2,p4).
+
+    p1-p2 is the hinge edge. p3 and p4 are the wing tips.
+    Returns angle in [0, 2*pi).
+    """
+    e = p2 - p1
+    e_norm = np.linalg.norm(e)
+    if e_norm < 1e-12:
+        return float(np.pi)
+    e_hat = e / e_norm
+
+    n1 = np.cross(p3 - p1, e)
+    n2 = np.cross(e, p4 - p1)
+    len1 = np.linalg.norm(n1)
+    len2 = np.linalg.norm(n2)
+    if len1 < 1e-12 or len2 < 1e-12:
+        return float(np.pi)
+
+    n1 = n1 / len1
+    n2 = n2 / len2
+
+    cos_a = float(np.clip(np.dot(n1, n2), -1.0, 1.0))
+    angle = np.arccos(cos_a)
+
+    cross = np.cross(n1, n2)
+    if np.dot(cross, e_hat) < 0:
+        angle = 2.0 * np.pi - angle
+
+    return float(angle)

engine/validation.py

@@ -254,3 +254,25 @@ def validate_paper(paper: Paper) -> ValidationResult:
         self_intersection_count=si_count,
         is_valid=k_valid and m_valid and si_valid,
     )
+
+
+def validate_state(paper: Paper) -> dict:
+    """Run all validation checks and return a flat dict.
+
+    This is the interface used by OrigamiEnvironment. It calls the
+    existing validation functions and returns a dict with all fields
+    the environment and metrics system need.
+    """
+    result = validate_paper(paper)
+    strain_exceeded = bool(
+        len(paper.strain_per_vertex) > 0
+        and float(paper.strain_per_vertex.max()) > paper.material.max_strain
+    )
+    return {
+        "is_valid": result.is_valid and not strain_exceeded,
+        "kawasaki_violations": int(not result.kawasaki_valid),
+        "kawasaki_total_error": float(result.kawasaki_violation),
+        "maekawa_violations": int(not result.maekawa_valid),
+        "self_intersections": result.self_intersection_count,
+        "strain_exceeded": strain_exceeded,
+    }

research 2/openenv/2048_example.py

@@ -1,636 +0,0 @@
-"""
-Reference Implementation: OpenEnv + GRPO Reinforcement Learning for 2048 Game
-==============================================================================
-
-Extracted from the Unsloth / OpenEnv notebook:
-  https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/
-  OpenEnv_gpt_oss_(20B)_Reinforcement_Learning_2048_Game.ipynb
-
-This file contains ALL code cells from the notebook, organized into sections.
-It serves as a reference for how to build an OpenEnv-based RL environment
-and connect it to GRPO training via TRL.
-
-KEY ARCHITECTURE:
-  1. OpenEnv provides a server-based game environment (2048 via OpenSpiel)
-  2. The LLM generates a Python *strategy function* (code-as-action)
-  3. The strategy function is executed against the environment
-  4. Three reward functions score the output:
-     - function_works: Does the generated code parse and compile?
-     - no_cheating: Does it only use stdlib imports?
-     - strategy_succeeds: Does the strategy actually play the game well?
-  5. GRPO (from TRL) uses these rewards to train the model
-
-PROMPT/RESPONSE FORMAT:
-  - Prompt asks the LLM to write a Python function `strategy(board)` that
-    takes a list-of-lists board state and returns "0","1","2","3" (up/right/down/left)
-  - Response is wrapped in ```python ... ``` backticks
-  - The function is extracted, sandboxed, and executed against the live game
-
-REWARD STRUCTURE:
-  - function_works:     +1.0 if valid Python, -2.0 if no function / syntax error, -0.5 if exec fails
-  - no_cheating:        +1.0 if only stdlib imports, -20.0 if non-stdlib imports, -1.0 if no function
-  - strategy_succeeds:  +20.0 if reaches 2048, +2.0 if function runs but doesn't win,
-                        -1.0 on timeout, -3.0 on exception, 0 if function broken
-"""
-
-
-# =============================================================================
-# CELL 1: Installation (pip installs - shown for reference, not executable here)
-# =============================================================================
-"""
-%%capture
-import os, importlib.util
-!pip install --upgrade -qqq uv
-if importlib.util.find_spec("torch") is None or "COLAB_" in "".join(os.environ.keys()):
-    try: import numpy; get_numpy = f"numpy=={numpy.__version__}"
-    except: get_numpy = "numpy"
-    !uv pip install -qqq \\
-        "torch>=2.8.0" "triton>=3.4.0" {get_numpy} torchvision bitsandbytes "transformers==4.56.2" trackio \\
-        "unsloth_zoo[base] @ git+https://github.com/unslothai/unsloth-zoo" \\
-        "unsloth[base] @ git+https://github.com/unslothai/unsloth" \\
-        git+https://github.com/triton-lang/triton.git@0add68262ab0a2e33b84524346cb27cbb2787356#subdirectory=python/triton_kernels
-elif importlib.util.find_spec("unsloth") is None:
-    !uv pip install -qqq unsloth trackio
-!uv pip install --upgrade --no-deps transformers==4.56.2 tokenizers trl==0.22.2 unsloth unsloth_zoo
-"""
-
-
-# =============================================================================
-# CELL 2: Install OpenEnv from source
-# =============================================================================
-"""
-%%capture
-!pip install -qqq fastapi uvicorn requests open_spiel
-!pip install fastapi uvicorn requests
-!pip install open_spiel --prefer-binary
-!git clone https://github.com/meta-pytorch/OpenEnv.git > /dev/null 2>&1
-%cd OpenEnv
-!git checkout 83dda10
-"""
-
-import subprocess, sys, os
-from pathlib import Path
-# sys.path.insert(0, '.')  # Add OpenEnv root for envs module
-# sys.path.insert(0, './src')
-# working_directory = str(Path.cwd().parent.absolute() / "OpenEnv")
-
-
-# =============================================================================
-# CELL 3: Load the model with Unsloth
-# =============================================================================
-import os
-from unsloth import FastLanguageModel
-import torch
-
-max_seq_length = 768  # Can increase for longer RL output
-lora_rank = 4         # Larger rank = smarter, but slower
-
-model, tokenizer = FastLanguageModel.from_pretrained(
-    model_name = "unsloth/gpt-oss-20b",
-    load_in_4bit = True,
-    max_seq_length = max_seq_length,
-    offload_embedding = True,  # Offload embeddings to save more VRAM
-)
-
-
-# =============================================================================
-# CELL 4: Apply LoRA adapters
-# =============================================================================
-model = FastLanguageModel.get_peft_model(
-    model,
-    r = lora_rank,  # Choose any number > 0 ! Suggested 8, 16, 32, 64, 128
-    target_modules = [
-        "q_proj", "k_proj", "v_proj", "o_proj",
-        "gate_proj", "up_proj", "down_proj",
-    ],
-    lora_alpha = lora_rank * 2,  # *2 speeds up training
-    use_gradient_checkpointing = "unsloth",  # Reduces memory usage
-    random_state = 3407,
-)
-
-
-# =============================================================================
-# CELL 5: OpenEnv imports (environment-specific)
-# =============================================================================
-from envs.openspiel_env import OpenSpielEnv
-from envs.openspiel_env.models import OpenSpielAction, OpenSpielObservation
-
-
-# =============================================================================
-# CELL 6: OpenEnv process launch configuration
-# =============================================================================
-global port
-global openenv_process
-port = 9000
-openenv_process = None
-server = "envs.openspiel_env.server.app:app"
-environment = {
-    **os.environ,
-    "PYTHONPATH": f"{working_directory}/src",
-    "OPENSPIEL_GAME": "2048",
-    "OPENSPIEL_AGENT_PLAYER": "0",
-    "OPENSPIEL_OPPONENT_POLICY": "random",
-}
-
-# Augment Unsloth's OpenEnv creation function
-import functools
-from unsloth import is_port_open, launch_openenv
-launch_openenv = functools.partial(
-    launch_openenv,
-    working_directory = working_directory,
-    server = server,
-    environment = environment,
-    openenv_class = OpenSpielEnv,
-)
-
-
-# =============================================================================
-# CELL 7: Reset the environment and observe initial state
-# =============================================================================
-port, openenv_process = launch_openenv(port, openenv_process)
-result = openenv_process.reset()
-current_state = result.observation
-# current_state is an OpenSpielObservation with:
-#   .done            -> bool
-#   .reward          -> float or None
-#   .info_state      -> list of floats (flat board)
-#   .legal_actions   -> list of ints (e.g. [0,1,2,3])
-#   .game_phase      -> str
-#   .current_player_id -> int
-
-
-# =============================================================================
-# CELL 8: Convert flat info_state to 2D board
-# =============================================================================
-import numpy as np
-
-def convert_to_board(current_state):
-    n = len(current_state.info_state)
-    size = int(np.sqrt(n))
-    board = np.array_split(np.array(current_state.info_state, dtype=int), size)
-    board = [x.tolist() for x in board]
-    return board, size
-
-
-# =============================================================================
-# CELL 9: Pretty-print the 2048 board (collapsible in notebook)
-# =============================================================================
-def render_board(obs, colors: bool = True, border: bool = True, dot_for_zero: bool = True) -> str:
-    """
-    Pretty-print the board with colors that scale from 0 up to self.target.
-    Uses ANSI 256-color codes (works in most terminals). Set colors=False to disable.
-    """
-    import math
-    b, size = convert_to_board(obs)
-    mx = max((max(row) for row in b), default=0)
-    cell_w = max(3, len(str(mx)))
-
-    RESET = "\x1b[0m"
-
-    # A smooth-ish gradient from cool -> warm
-    GRAD = [33, 39, 45, 51, 50, 49, 48, 47, 46, 82, 118, 154, 190, 226, 220, 214, 208, 202, 196]
-    ZERO_FG = 239  # dim gray
-
-    def color_code(v: int) -> str:
-        if not colors:
-            return ""
-        if v == 0:
-            return f"\x1b[38;5;{ZERO_FG}m"
-        t = max(2, 2048)
-        try:
-            r = max(0.0, min(1.0, math.log2(v) / math.log2(t)))
-        except ValueError:
-            r = 0.0
-        idx = int(round(r * (len(GRAD) - 1)))
-        return f"\x1b[38;5;{GRAD[idx]}m"
-
-    def fmt(v: int) -> str:
-        s = "." if (v == 0 and dot_for_zero) else str(v)
-        s = s.rjust(cell_w)
-        return color_code(v) + s + (RESET if colors else "")
-
-    def hline(left: str, mid: str, right: str) -> str:
-        return left + mid.join("\u2500" * cell_w for _ in range(size)) + right
-
-    rows = []
-    if border:
-        rows.append(hline("\u250c", "\u252c", "\u2510"))
-    for r in range(size):
-        content = "\u2502".join(fmt(v) for v in b[r])
-        rows.append(("\u2502" + content + "\u2502") if border else content)
-        if border:
-            rows.append(hline("\u2514" if r == size - 1 else "\u251c",
-                            "\u2534" if r == size - 1 else "\u253c",
-                            "\u2518" if r == size - 1 else "\u2524"))
-    return "\n".join(rows)
-
-
-# =============================================================================
-# CELL 10: Demonstrate stepping through the environment
-# =============================================================================
-# Action mapping: 0 = up, 1 = right, 2 = down, 3 = left
-action = OpenSpielAction(action_id=0, game_name="2048")
-result = openenv_process.step(action)
-current_state = result.observation
-print(render_board(current_state))
-
-
-# =============================================================================
-# CELL 11: RL Environment - Strategy execution with time limit
-# =============================================================================
-from typing import Callable
-from unsloth import execute_with_time_limit
-import itertools
-
-def _execute_strategy(strategy, current_state: OpenSpielObservation):
-    """
-    Execute a strategy function against the 2048 environment.
-    The strategy receives a board (list of lists) and returns an action int.
-    Runs until the game is done or the strategy fails.
-    Returns (steps, whether_2048_was_reached).
-    """
-    assert callable(strategy)
-
-    steps = 0
-    total_reward = 0
-    while not current_state.done:
-        board, size = convert_to_board(current_state)
-        action = strategy(board)
-        try:
-            action = int(action)
-        except:
-            return steps, False
-        steps += 1
-        if type(action) is not int or action not in current_state.legal_actions:
-            return steps, max(itertools.chain.from_iterable(board)) == 2048
-
-        global port, openenv_process
-        port, openenv_process = launch_openenv(port, openenv_process)
-        action = OpenSpielAction(action_id=action, game_name="2048")
-        result = openenv_process.step(action)
-        current_state = result.observation
-        if result.reward is not None:
-            total_reward += result.reward
-    return steps, max(itertools.chain.from_iterable(board)) == 2048
-
-
-# Time-limited wrapper (2 seconds default, later changed to 5)
-@execute_with_time_limit(2)
-def execute_strategy(strategy: Callable, current_state: OpenSpielObservation):
-    return _execute_strategy(strategy, current_state)
-
-
-# =============================================================================
-# CELL 12: Test with a trivial strategy
-# =============================================================================
-def always_move_left(board):
-    return 3
-
-# Reset OpenEnv to an initial state!
-port, openenv_process = launch_openenv(port, openenv_process)
-result = openenv_process.reset()
-current_state = result.observation
-try:
-    steps, if_done = execute_strategy(always_move_left, current_state)
-except TimeoutError as e:
-    print(f"Timed out with error = {str(e)}")
-print(f"steps={steps}, if_done={if_done}")
-
-
-# =============================================================================
-# CELL 13: Extend time limit to 5 seconds for actual RL training
-# =============================================================================
-@execute_with_time_limit(5)
-def execute_strategy(strategy: Callable, current_state: OpenSpielObservation):
-    return _execute_strategy(strategy, current_state)
-
-
-# =============================================================================
-# CELL 14: Code safety - check_python_modules (anti-reward-hacking)
-# =============================================================================
-from unsloth import check_python_modules
-
-# Example: allowed (only stdlib)
-sample_ok = """
-def strategy(board):
-    import math
-    from typing import Callable
-    return "0"
-"""
-ok, info = check_python_modules(sample_ok)
-print("Only Python imports?", ok)  # True
-print(info)
-
-# Example: disallowed (numpy is non-stdlib)
-sample_bad = """
-def strategy(board):
-    from numpy import matmul
-    return "0"
-"""
-ok, info = check_python_modules(sample_bad)
-print("Only Python imports?", ok)  # False
-print(info)
-
-
-# =============================================================================
-# CELL 15: Sandboxed function execution (no global variable leakage)
-# =============================================================================
-from unsloth import create_locked_down_function
-
-# This will fail - np is not defined inside the sandbox
-function_bad = """
-def import_numpy():
-    np.matmul
-    print("Success")
-"""
-f = create_locked_down_function(function_bad)
-try:
-    f()
-except Exception as e:
-    print(str(e))  # "name 'np' is not defined"
-
-# This will work - no external references
-function_good = """
-def add(a, b):
-    def adder(a):
-        return a + b
-    return adder(b) + b
-"""
-f = create_locked_down_function(function_good)
-try:
-    print(f(10, 20))  # 60
-except Exception as e:
-    print(str(e))
-
-
-# =============================================================================
-# CELL 16: THE PROMPT - How the LLM interacts with the environment
-# =============================================================================
-prompt = """
-Create a new short 2048 strategy using only native Python code.
-You are given a list of list of numbers for the current board state.
-Output one action for "0", "1", "2", "3" on what is the optimal next step.
-Output your new short function in backticks using the format below:
-```python
-def strategy(board):
-    return "0" # Example
-```
-All helper functions should be inside def strategy. Only output the short function `strategy`.
-""".strip()
-print(prompt)
-
-
-# =============================================================================
-# CELL 17: Test inference before RL training
-# =============================================================================
-text = tokenizer.apply_chat_template(
-    [{"role": "user", "content": prompt}],
-    tokenize = False,
-    add_generation_prompt = True,
-    reasoning_effort = "low",
-)
-
-from transformers import TextStreamer
-_ = model.generate(
-    **tokenizer(text, return_tensors="pt").to("cuda"),
-    temperature = 1.0,
-    max_new_tokens = 512,
-    streamer = TextStreamer(tokenizer, skip_prompt=False),
-)
-
-
-# =============================================================================
-# CELL 18: REWARD FUNCTION 1 - extract_function (helper)
-# =============================================================================
-def extract_function(text):
-    """
-    Extract a Python function wrapped in triple backticks from the LLM response.
-    Returns the function source string, or None if not found.
-    """
-    if text.count("```") >= 2:
-        first = text.find("```") + 3
-        second = text.find("```", first)
-        fx = text[first:second].strip()
-        fx = fx.removeprefix("python\n")
-        fx = fx[fx.find("def"):]
-        if fx.startswith("def strategy(board):"):
-            return fx
-    return None
-
-
-# =============================================================================
-# CELL 19: REWARD FUNCTION 2 - function_works
-# =============================================================================
-def function_works(completions, **kwargs):
-    """
-    Reward: Does the generated code parse as valid Python and compile?
-    +1.0  if valid function that can be created
-    -0.5  if it has the right structure but exec fails
-    -2.0  if no function extracted or syntax error
-    """
-    scores = []
-    for completion in completions:
-        score = 0
-        response = completion[0]["content"]
-        function = extract_function(response)
-        if function is not None:
-            ok, info = check_python_modules(function)
-        if function is None or "error" in info:
-            score = -2.0
-        else:
-            try:
-                new_strategy = create_locked_down_function(function)
-                score = 1.0
-            except:
-                score = -0.5
-        scores.append(score)
-    return scores
-
-
-# =============================================================================
-# CELL 20: REWARD FUNCTION 3 - no_cheating
-# =============================================================================
-def no_cheating(completions, **kwargs):
-    """
-    Reward: Does the function only use Python stdlib imports?
-    +1.0   if only stdlib imports
-    -20.0  if non-stdlib imports (heavy penalty!)
-    -1.0   if function extraction failed
-    """
-    scores = []
-    for completion in completions:
-        score = 0
-        response = completion[0]["content"]
-        function = extract_function(response)
-        if function is not None:
-            ok, info = check_python_modules(function)
-            scores.append(1.0 if ok else -20.0)  # Penalize heavily!
-        else:
-            scores.append(-1.0)  # Failed creating function
-    return scores
-
-
-# =============================================================================
-# CELL 21: REWARD FUNCTION 4 - strategy_succeeds
-# =============================================================================
-import numpy as np
-
-global PRINTER
-PRINTER = 0
-
-def strategy_succeeds(completions, **kwargs):
-    """
-    Reward: Does the strategy actually play 2048 successfully?
-    +20.0  if the strategy reaches 2048 (massive reward!)
-    +2.0   if the function runs and plays but doesn't reach 2048
-    -1.0   if timeout (strategy takes too long)
-    -3.0   if exception during execution
-     0     if function is broken/can't be created
-    """
-    global PRINTER
-    scores = []
-    for completion in completions:
-        printed = False
-        score = 0
-        response = completion[0]["content"]
-        function = extract_function(response)
-        if PRINTER % 5 == 0:
-            printed = True
-            print(function)
-        PRINTER += 1
-        if function is not None:
-            ok, info = check_python_modules(function)
-        if function is None or "error" in info:
-            scores.append(0)
-            continue
-        try:
-            new_strategy = create_locked_down_function(function)
-        except:
-            scores.append(0)
-            continue
-        try:
-            # Reset OpenEnv to an initial state!
-            global port, openenv_process
-            port, openenv_process = launch_openenv(port, openenv_process)
-            result = openenv_process.reset()
-            current_state = result.observation
-            steps, if_done = execute_strategy(new_strategy, current_state)
-            print(f"Steps = {steps} If Done = {if_done}")
-            if printed is False:
-                print(function)
-            print(render_board(current_state))
-            if if_done:
-                scores.append(20.0)  # Success - massively reward!
-            else:
-                scores.append(2.0)   # Failed but function works!
-        except TimeoutError as e:
-            print("Timeout")
-            scores.append(-1.0)  # Failed with timeout
-        except Exception as e:
-            print(f"Exception = {str(e)}")
-            scores.append(-3.0)  # Failed
-    return scores
-
-
-# =============================================================================
-# CELL 22: Create the dataset (replicated prompt)
-# =============================================================================
-from datasets import Dataset
-
-dataset = Dataset.from_list([
-    {
-        "prompt": [{"role": "user", "content": prompt.strip()}],
-        "answer": 0,
-        "reasoning_effort": "low",
-    }
-] * 1000)
-
-maximum_length = len(tokenizer.apply_chat_template(
-    [{"role": "user", "content": prompt.strip()}],
-    add_generation_prompt=True,
-))
-print(f"Prompt token length: {maximum_length}")
-
-
-# =============================================================================
-# CELL 23: GRPO Training Configuration
-# =============================================================================
-max_prompt_length = maximum_length + 1  # + 1 just in case!
-max_completion_length = max_seq_length - max_prompt_length
-
-from trl import GRPOConfig, GRPOTrainer
-
-training_args = GRPOConfig(
-    temperature = 1.0,
-    learning_rate = 2e-4,
-    weight_decay = 0.001,
-    warmup_ratio = 0.1,
-    lr_scheduler_type = "linear",
-    optim = "adamw_8bit",
-    logging_steps = 1,
-    per_device_train_batch_size = 1,
-    gradient_accumulation_steps = 1,   # Increase to 4 for smoother training
-    num_generations = 2,               # Decrease if out of memory
-    max_prompt_length = max_prompt_length,
-    max_completion_length = max_completion_length,
-    # num_train_epochs = 1,            # Set to 1 for a full training run
-    max_steps = 600,
-    save_steps = 100,
-    report_to = "trackio",             # Can use Weights & Biases, TrackIO
-    output_dir = "outputs",
-)
-
-
-# =============================================================================
-# CELL 24: Create GRPO Trainer and Train
-# =============================================================================
-trainer = GRPOTrainer(
-    model = model,
-    processing_class = tokenizer,
-    reward_funcs = [
-        function_works,       # Reward 1: Is it valid Python?
-        no_cheating,          # Reward 2: Only stdlib imports?
-        strategy_succeeds,    # Reward 3: Does it actually play 2048?
-    ],
-    args = training_args,
-    train_dataset = dataset,
-)
-
-# Start training! (~5 hours for 600 steps on T4)
-# Expect 0 reward for ~first 100 steps, then gradual improvement
-trainer.train()
-
-
-# =============================================================================
-# CELL 25: Inference after RL training
-# =============================================================================
-text = tokenizer.apply_chat_template(
-    [{"role": "user", "content": prompt}],
-    tokenize = False,
-    add_generation_prompt = True,
-    reasoning_effort = "low",
-)
-
-from transformers import TextStreamer
-_ = model.generate(
-    **tokenizer(text, return_tensors="pt").to("cuda"),
-    temperature = 1.0,
-    max_new_tokens = 1024,
-    streamer = TextStreamer(tokenizer, skip_prompt=False),
-)
-
-
-# =============================================================================
-# CELL 26: Save the model (optional)
-# =============================================================================
-# Merge and push to hub in mxfp4 4bit format
-if False:
-    model.save_pretrained_merged("finetuned_model", tokenizer, save_method="mxfp4")
-if False:
-    model.push_to_hub_merged("repo_id/repo_name", tokenizer, token="hf...", save_method="mxfp4")
-
-# Merge and push to hub in 16bit
-if False:
-    model.save_pretrained_merged("finetuned_model", tokenizer, save_method="merged_16bit")
-if False:
-    model.push_to_hub_merged("hf/gpt-oss-finetune", tokenizer, save_method="merged_16bit", token="")

research 2/openenv/2048_pattern.md

@@ -1,74 +0,0 @@
-# 2048 Example — Code-as-Policy Pattern
-
-**Full code**: [2048_example.py](./2048_example.py)
-
-## Key Insight: LLM Writes Code, Not Moves
-
-The LLM does NOT play move-by-move. Instead:
-1. LLM receives a prompt asking it to write a `strategy(board)` function
-2. LLM generates Python code wrapped in triple backticks
-3. Code is extracted, sandboxed (no global access), and executed against the live game
-4. Reward is based on whether the strategy works
-
-This is **"code-as-policy"** — the LLM generates an algorithm, not individual actions.
-
-## The Prompt
-
-```
-Create a new short 2048 strategy using only native Python code.
-You are given a list of list of numbers for the current board state.
-Output one action for "0", "1", "2", "3" on what is the optimal next step.
-Output your new short function in backticks using the format below:
-```python
-def strategy(board):
-    return "0" # Example
-```
-All helper functions should be inside def strategy. Only output the short function `strategy`.
-```
-
-## Three Reward Functions
-
-| Function | Score | Condition |
-|---|---|---|
-| `function_works` | +1.0 | Valid Python that compiles |
-| | -0.5 | Right structure but exec fails |
-| | -2.0 | No function / syntax error |
-| `no_cheating` | +1.0 | Only stdlib imports |
-| | -20.0 | Non-stdlib imports |
-| `strategy_succeeds` | +20.0 | Reaches tile 2048 |
-| | +2.0 | Runs but doesn't win |
-| | -1.0 | Timeout (>5 sec) |
-| | -3.0 | Exception |
-
-## Training Setup
-
-- Model: `unsloth/gpt-oss-20b` with LoRA (r=4)
-- Trainer: `trl.GRPOTrainer` with `trl.GRPOConfig`
-- Dataset: 1000 copies of the same prompt (diversity from temperature=1.0)
-- `num_generations=2`, `max_steps=600`, `lr=2e-4`, `optim=adamw_8bit`
-- ~5 hours on T4, rewards start appearing after ~100 steps
-
-## OpenEnv-Specific Patterns
-
-```python
-# Launch environment server
-from unsloth import launch_openenv
-launch_openenv = functools.partial(
-    launch_openenv,
-    working_directory=working_directory,
-    server="envs.openspiel_env.server.app:app",
-    environment={**os.environ, "OPENSPIEL_GAME": "2048", ...},
-    openenv_class=OpenSpielEnv,
-)
-
-# Reset and step
-port, openenv_process = launch_openenv(port, openenv_process)
-result = openenv_process.reset()
-result = openenv_process.step(OpenSpielAction(action_id=0, game_name="2048"))
-```
-
-## Safety Utilities (from Unsloth)
-
-- `check_python_modules(code)` — returns (ok, info); ok=True if only stdlib imports
-- `create_locked_down_function(code)` — sandboxed exec, no global variable leakage
-- `execute_with_time_limit(seconds)` — decorator for timeout enforcement

research 2/openenv/overview.md

@@ -1,141 +0,0 @@
-# OpenEnv Framework (Meta) — What We Need to Know
-
-**Repo**: https://github.com/meta-pytorch/OpenEnv
-**Version**: 0.2.1 stable (required by hackathon), 0.2.2.dev0 in dev
-**License**: BSD 3-Clause | **Python**: 3.10+
-
-## Architecture
-
-Client-server over WebSocket. Environment runs inside Docker as a FastAPI server.
-
-```
-LLM/Agent  <-->  EnvClient (WebSocket)  <-->  Environment (FastAPI server in Docker)
-```
-
-## Core Types (from `openenv.core.env_server.types`)
-
-```python
-class Action(BaseModel):
-    metadata: Dict[str, Any] = Field(default_factory=dict)
-
-class Observation(BaseModel):
-    done: bool = False
-    reward: bool | int | float | None = None
-    metadata: Dict[str, Any] = Field(default_factory=dict)
-
-class State(BaseModel):
-    episode_id: Optional[str] = None
-    step_count: int = 0
-```
-
-## Creating a Custom Environment (Server Side)
-
-Subclass `Environment[ActT, ObsT, StateT]`:
-
-```python
-from openenv.core.env_server.interfaces import Environment
-from openenv.core.env_server.types import State
-
-class MyEnvironment(Environment[MyAction, MyObservation, MyState]):
-    SUPPORTS_CONCURRENT_SESSIONS = True
-
-    def reset(self, seed=None, episode_id=None, **kwargs) -> ObsT:
-        """Initialize episode, return initial observation."""
-
-    def step(self, action: ActT, timeout_s=None, **kwargs) -> ObsT:
-        """Execute action, return observation (with .done and .reward set)."""
-
-    @property
-    def state(self) -> StateT:
-        """Return current episode state."""
-```
-
-## Creating a Custom Client
-
-Subclass `EnvClient[ActT, ObsT, StateT]`:
-
-```python
-from openenv.core.env_client import EnvClient
-
-class MyEnvClient(EnvClient[MyAction, MyObservation, MyState]):
-    def _step_payload(self, action: ActT) -> Dict:
-        """Convert action to JSON dict for wire transmission."""
-
-    def _parse_result(self, payload: Dict) -> StepResult[ObsT]:
-        """Parse server response into StepResult."""
-
-    def _parse_state(self, payload: Dict) -> StateT:
-        """Parse state response into your State type."""
-```
-
-## Project Structure (`openenv init my_env`)
-
-```
-my_env/
-  __init__.py
-  models.py          # Action, Observation, State subclasses
-  client.py           # EnvClient subclass
-  openenv.yaml        # Manifest
-  pyproject.toml      # deps: "openenv-core[core]>=0.2.1"
-  server/
-    __init__.py
-    my_env_environment.py   # Environment subclass
-    app.py                  # create_app() call
-    Dockerfile
-    requirements.txt
-```
-
-## openenv.yaml Manifest
-
-```yaml
-spec_version: 1
-name: my_env
-type: space
-runtime: fastapi
-app: server.app:app
-port: 8000
-```
-
-## Server App Entry Point
-
-```python
-from openenv.core.env_server.http_server import create_app
-app = create_app(MyEnvironment, MyAction, MyObservation, env_name="my_env")
-```
-
-## Deploy to HF Spaces
-
-```bash
-openenv push [--repo-id username/my_env] [--private]
-```
-
-Dockerfile uses `ghcr.io/meta-pytorch/openenv-base:latest`, runs `uvicorn server.app:app --host 0.0.0.0 --port 8000`.
-
-## Concrete Example: Chess Environment
-
-```python
-class ChessAction(Action):
-    move: str  # UCI format "e2e4"
-
-class ChessObservation(Observation):
-    fen: str = ""
-    legal_moves: List[str] = []
-    is_check: bool = False
-    result: Optional[str] = None  # "1-0", "0-1", "1/2-1/2"
-
-class ChessState(State):
-    fen: str = "rnbqkbnr/..."
-    current_player: str = "white"
-    move_history: List[str] = []
-```
-
-Reward: +1.0 win, -1.0 loss, 0.0 draw, -0.1 invalid move.
-
-## Integration with GRPO Training
-
-From `examples/grpo_blackjack/`:
-1. `play_game()` — orchestrates env.reset() / env.step() loop
-2. `format_prompt()` — converts game state to LLM prompt
-3. `parse_action()` — extracts actions from LLM text
-4. `simple_grpo_loss()` — GRPO with KL penalty
-5. Compatible with: **TRL**, **Unsloth**, **SkyRL**, **ART**, **Oumi**

research 2/origami/existing_work.md

@@ -1,51 +0,0 @@
-# Existing RL & ML Work on Origami
-
-## "Automating Rigid Origami Design" — IJCAI 2023 (Most Relevant)
-
-- **Paper**: https://www.ijcai.org/proceedings/2023/0645.pdf
-- **Code**: https://github.com/belalugaX/rigid-origami
-
-**RL Formulation:**
-- Environment = board game on a grid
-- State = current vertex graph forming crease pattern
-- Actions = place vertices on grid (with action masking for symmetry)
-- Reward = sparse, based on objective (shape approximation, packaging)
-- Validation = triangle-triangle intersection + kinematic check
-
-**Algorithms tested:** Random, BFS, DFS, MCTS, Evolutionary, PPO
-**Finding:** Action space grows exponentially. Symmetry masking is critical.
-
-## ML for Origami Inverse Design — Nature 2022
-
-- Decision tree / random forest for inverse design
-- Given desired mechanical properties → predict crease pattern parameters
-- Relevant for: how to define reward functions around structural properties
-
-## UCLA Robotic Origami (2023)
-
-- Deep learning for robotic paper folding
-- RL for physical execution of folds (robot arm)
-- Different scope (physical manipulation, not pattern design)
-
-## Key Papers
-
-| Paper | Year | Key Contribution |
-|-------|------|-----------------|
-| Bern & Hayes | 1996 | Global flat-foldability is NP-complete |
-| Lang, "Computational origami" | 1996 | TreeMaker algorithm |
-| Tachi & Demaine, "Origamizer" | 2017 | Universal folding algorithm |
-| Ghassaei et al. | 2018 | GPU truss model simulation |
-| Lang, "Additive algorithm" | 2021 | Scalable local origami design |
-| Nature, "Algorithmic origami" | 2022 | Optimization frameworks |
-| IJCAI, "Automating Rigid Origami" | 2023 | RL for origami design |
-
-## Origami AI Roadmap (Community)
-
-Source: https://origami.kosmulski.org/blog/2023-01-12-origami-ai-roadmap
-
-Key insight — a minimal AI origami system needs:
-1. Intent → stick model converter (**the hard/missing part**)
-2. Stick model → crease pattern (TreeMaker exists)
-3. CP simulation/visualization (Ghassaei exists)
-
-Training data scarcity is a major challenge.

research 2/origami/fold_format.md

@@ -1,48 +0,0 @@
-# FOLD File Format — Our State Representation
-
-**Spec**: https://edemaine.github.io/fold/doc/spec.html (v1.2)
-**Format**: JSON | **GitHub**: https://github.com/edemaine/fold
-
-The standard interchange format for computational origami. We use this as our internal state.
-
-## Key Fields
-
-**Vertices:**
-- `vertices_coords`: `[[x,y], [x,y,z], ...]`
-
-**Edges:**
-- `edges_vertices`: `[[u,v], ...]` — endpoint pairs
-- `edges_assignment`: fold type per edge:
-  - `"M"` Mountain | `"V"` Valley | `"B"` Boundary | `"F"` Flat | `"U"` Unassigned
-- `edges_foldAngle`: degrees [-180, 180]; positive=valley, negative=mountain, 0=flat
-
-**Faces:**
-- `faces_vertices`: vertex IDs in counterclockwise order
-
-**Layer Ordering:**
-- `faceOrders`: `[f, g, s]` triples — s=+1 (f above g), s=-1 (f below g)
-
-**Metadata:**
-- `frame_classes`: `"creasePattern"`, `"foldedForm"`, `"graph"`
-- `frame_unit`: `"unit"`, `"mm"`, `"cm"`, `"m"`
-
-## Python Usage
-
-```python
-import json
-
-with open("model.fold") as f:
-    data = json.load(f)
-
-vertices = data["vertices_coords"]
-edges = data["edges_vertices"]
-assignments = data["edges_assignment"]    # ["M", "V", "B", ...]
-fold_angles = data.get("edges_foldAngle") # [-180, 180, 0, ...]
-faces = data["faces_vertices"]
-```
-
-## Why It Matters
-- Lingua franca of all origami software
-- JSON = trivially parseable, serializable for replay buffers
-- Encodes everything: geometry, fold types, angles, layer ordering
-- Both Ghassaei's simulator and PyOri support it

research 2/origami/fold_types_deep.md

@@ -1,997 +0,0 @@
-# Origami Fold Types, Bases, and Operations: Complete Action Space for RL Environment
-
-> Deep research compilation for building an origami reinforcement learning environment.
-> Covers: primitive operations, fold taxonomy, bases, crane sequence, tessellation patterns,
-> Huzita-Justin axioms, and complexity analysis.
-
----
-
-## Table of Contents
-
-1. [Huzita-Justin Axioms (The Primitive Action Space)](#1-huzita-justin-axioms---the-primitive-action-space)
-2. [All Fold Types (Compound Operations)](#2-all-fold-types---compound-operations)
-3. [Origami Bases (Starting Configurations)](#3-origami-bases---starting-configurations)
-4. [Crane (Tsuru) Fold Sequence](#4-crane-tsuru-complete-fold-sequence)
-5. [Compression/Packing Origami Patterns](#5-compressionpacking-origami-patterns)
-6. [Yoshizawa-Randlett Notation System](#6-yoshizawa-randlett-notation-system)
-7. [Fold Sequence Complexity](#7-fold-sequence-complexity)
-8. [Flat-Foldability Theorems](#8-flat-foldability-theorems)
-9. [RL Environment Design Implications](#9-rl-environment-design-implications)
-
----
-
-## 1. Huzita-Justin Axioms -- The Primitive Action Space
-
-These 7 axioms define ALL possible single-fold operations. Any single fold you can make on a
-piece of paper corresponds to exactly one of these axioms. They are the **true primitive
-action space** for origami.
-
-First discovered by Jacques Justin (1986), rediscovered by Humiaki Huzita (1991), with Axiom 7
-found by Koshiro Hatori (2001) and Robert J. Lang independently.
-
-### Axiom 1: Fold Through Two Points
-- **Input**: Two distinct points p1 and p2
-- **Output**: A unique fold (crease line) that passes through both points
-- **Geometric equivalent**: Drawing a line through two points (straightedge operation)
-- **Solutions**: Exactly 1
-- **Parameters**: `(p1_x, p1_y, p2_x, p2_y)`
-
-### Axiom 2: Point-to-Point Fold
-- **Input**: Two distinct points p1 and p2
-- **Output**: A unique fold that places p1 onto p2
-- **Geometric equivalent**: Constructing the perpendicular bisector of the segment p1-p2
-- **Solutions**: Exactly 1
-- **Parameters**: `(p1_x, p1_y, p2_x, p2_y)`
-
-### Axiom 3: Line-to-Line Fold
-- **Input**: Two lines l1 and l2
-- **Output**: A fold that places l1 onto l2
-- **Geometric equivalent**: Bisecting the angle between two lines
-- **Solutions**: 1 if lines are parallel (perpendicular bisector), 2 if lines intersect (two angle bisectors)
-- **Parameters**: `(l1_point, l1_direction, l2_point, l2_direction)`
-
-### Axiom 4: Fold Through Point Perpendicular to Line
-- **Input**: A point p1 and a line l1
-- **Output**: A unique fold perpendicular to l1 that passes through p1
-- **Geometric equivalent**: Constructing a perpendicular through a point
-- **Solutions**: Exactly 1
-- **Parameters**: `(p1_x, p1_y, l1_point, l1_direction)`
-
-### Axiom 5: Point-to-Line Through Point
-- **Input**: Two points p1, p2 and a line l1
-- **Output**: A fold that places p1 onto l1 and passes through p2
-- **Geometric equivalent**: Finding a tangent to a parabola from an external point (solves quadratic)
-- **Solutions**: 0, 1, or 2
-- **Parameters**: `(p1_x, p1_y, p2_x, p2_y, l1_point, l1_direction)`
-
-### Axiom 6: Two Points onto Two Lines (The Beloch Fold)
-- **Input**: Two points p1, p2 and two lines l1, l2
-- **Output**: A fold that simultaneously places p1 onto l1 AND p2 onto l2
-- **Geometric equivalent**: Finding a common tangent to two parabolas (solves cubic equations!)
-- **Solutions**: 0, 1, 2, or 3
-- **Parameters**: `(p1_x, p1_y, p2_x, p2_y, l1_point, l1_direction, l2_point, l2_direction)`
-- **Significance**: This is what gives origami more power than compass-and-straightedge. It can
-  trisect angles and double cubes (both impossible with compass/straightedge).
-  Named after Margherita Beloch, who showed in 1936 that this fold solves general cubic equations.
-
-### Axiom 7: Point-to-Line Perpendicular to Line
-- **Input**: One point p and two lines l1, l2
-- **Output**: A fold that places p onto l1 and is perpendicular to l2
-- **Geometric equivalent**: Constructing a perpendicular to a line that maps a point onto another line
-- **Solutions**: 0 or 1
-- **Parameters**: `(p_x, p_y, l1_point, l1_direction, l2_point, l2_direction)`
-
-### Summary Table: Axiom Action Parameters
-
-| Axiom | Inputs | Max Solutions | Solves | Key Use |
-|-------|--------|---------------|--------|---------|
-| O1 | 2 points | 1 | Linear | Line through two points |
-| O2 | 2 points | 1 | Linear | Perpendicular bisector |
-| O3 | 2 lines | 2 | Linear | Angle bisector |
-| O4 | 1 point + 1 line | 1 | Linear | Perpendicular through point |
-| O5 | 2 points + 1 line | 2 | Quadratic | Point onto line via point |
-| O6 | 2 points + 2 lines | 3 | **Cubic** | Simultaneous alignment |
-| O7 | 1 point + 2 lines | 1 | Quadratic | Perpendicular alignment |
-
-### Mathematical Power
-
-- **Compass + straightedge**: Solves up to degree-2 (quadratic) equations
-- **Origami (Axioms 1-7)**: Solves up to degree-3 (cubic) equations
-- **Multi-fold origami** (simultaneous folds): Can solve higher-degree equations
-
----
-
-## 2. All Fold Types -- Compound Operations
-
-While the Huzita-Justin axioms are the mathematical primitives, origami practice uses
-**compound fold types** -- named sequences that combine one or more axiom applications
-and layer manipulations. These are the operations an origami folder actually thinks in.
-
-### 2.1 Valley Fold (Tani-ori)
-
-**The most fundamental fold.**
-
-- **Geometry**: Paper is folded toward the viewer along a straight crease line. Creates a
-  V-shaped cross-section (concave when viewed from above).
-- **Dihedral angle**: gamma > 0 (positive fold angle between face normals)
-- **Flat-folded state**: gamma = +pi (180 degrees)
-- **Notation**: Dashed line (---) with filled arrowhead showing direction of motion
-- **Parameters**:
-  - `fold_line`: defined by a point and direction vector (or two points)
-  - `fold_angle`: 0 to pi (typically pi for flat fold)
-  - `layers_affected`: which layers of paper are being folded
-- **Axiom mapping**: Corresponds to any of Axioms 1-7 depending on how the fold line is determined
-- **Decomposition**: Single atomic operation
-
-### 2.2 Mountain Fold (Yama-ori)
-
-**The complement of valley fold.**
-
-- **Geometry**: Paper is folded away from the viewer along a straight crease line. Creates an
-  inverted-V cross-section (convex when viewed from above).
-- **Dihedral angle**: gamma < 0 (negative fold angle)
-- **Flat-folded state**: gamma = -pi (-180 degrees)
-- **Notation**: Dot-dash line (-.-.-) with hollow single-sided arrowhead
-- **Parameters**: Same as valley fold
-- **Relationship to valley**: A mountain fold is geometrically identical to a valley fold viewed
-  from the other side. Flipping the paper converts all mountains to valleys and vice versa.
-- **Decomposition**: Single atomic operation (equivalent to: turn paper over + valley fold + turn back)
-
-### 2.3 Inside Reverse Fold
-
-**Used extensively for heads, tails, beaks, and feet in animal models.**
-
-- **Geometry**: A pointed flap (at least 2 layers) is opened and the tip is pushed inward,
-  reversing the direction of the central crease while creating two new creases on either side.
-- **What happens**: The mountain fold along the spine of the flap is reversed (becomes valley)
-  between two new valley folds that diverge from a point on the original spine.
-- **Parameters**:
-  - `flap_to_reverse`: which flap/point
-  - `fold_line_angle`: angle of the new crease relative to the flap spine
-  - `fold_depth`: how far down the spine the reversal point sits
-- **Decomposition**: 2 valley folds + 1 mountain-to-valley conversion = 3 crease changes
-- **Prerequisite state**: Requires an existing folded flap with a central crease
-
-### 2.4 Outside Reverse Fold
-
-**The mirror complement of inside reverse fold.**
-
-- **Geometry**: A pointed flap is opened and the tip is wrapped around the outside, reversing
-  the central crease while creating two new creases.
-- **What happens**: The valley fold along the spine becomes mountain, and two mountain folds
-  diverge from a point on the spine. The flap wraps over the outside.
-- **Parameters**: Same as inside reverse fold
-- **Decomposition**: 2 mountain folds + 1 valley-to-mountain conversion = 3 crease changes
-- **Notation**: Mountain fold lines on near layer, valley on far layer, push arrow
-
-### 2.5 Squash Fold
-
-**Opens a flap and flattens it symmetrically.**
-
-- **Geometry**: A flap with at least 2 layers has its closed edge opened. A radial fold from
-  the closed point bisects the flap. The flap is pressed flat, creating two adjacent flaps
-  from one.
-- **What happens**: One existing crease becomes a fold, a new crease bisects the original flap,
-  and the flap is flattened into a diamond/square shape.
-- **Parameters**:
-  - `flap_to_squash`: which flap
-  - `bisecting_line`: the line that will become the new center (typically the symmetry axis)
-  - `direction`: which side to flatten toward
-- **Decomposition**: 1 new valley fold (bisector) + opening + flattening = compound operation
-- **Common use**: Preliminary base -> bird base transition; creating diamond shapes from triangular flaps
-
-### 2.6 Petal Fold
-
-**The signature fold of the bird base. Creates a long, narrow flap from a wider one.**
-
-- **Geometry**: Starting with two connected flaps (each with 2+ layers), two radial folds
-  are made from the open point so that the open edges lie along a reference crease. The top
-  layer is lifted and folded upward while the sides collapse inward.
-- **What happens**: A point is elongated by folding two edges to a center line, then lifting
-  the top layer while the creases collapse. Essentially two symmetrically-placed rabbit ears
-  executed simultaneously.
-- **Parameters**:
-  - `reference_crease`: the center line to fold edges toward
-  - `flap_edges`: the two edges that will be brought to the center
-  - `lift_direction`: up or down
-- **Decomposition**: 2 valley folds (edges to center) + 1 valley fold (top layer lift) +
-  2 mountain folds (collapse) = 5 simultaneous crease changes
-- **Common use**: Central operation in creating the bird base from preliminary base
-
-### 2.7 Rabbit Ear Fold
-
-**Creates a triangular flap that stands up from the surface.**
-
-- **Geometry**: Starting with a triangular region, fold the angle bisectors from two corners
-  on the same side of a reference diagonal. The resulting triangular flap is folded flat to
-  one side.
-- **What happens**: Three creases meet at a point -- two valley folds (bisectors) and one
-  mountain fold (the ridge of the raised triangle). The excess paper forms a small triangular
-  flap.
-- **Parameters**:
-  - `reference_crease`: the diagonal or edge used as the base
-  - `bisector_1_angle`: angle of first bisector fold
-  - `bisector_2_angle`: angle of second bisector fold
-  - `flap_direction`: which side the resulting flap folds to
-- **Decomposition**: 2 valley folds + 1 mountain fold = 3 simultaneous creases
-- **Common use**: Fish base construction, creating narrow triangular points
-
-### 2.8 Sink Fold (Three Variants)
-
-**Pushes a point or corner into the interior of the model. The most difficult standard fold.**
-
-#### 2.8a Open Sink
-- **Geometry**: A corner point is pushed inward, and the paper around it is opened and
-  reflattened. The surrounding paper forms a waterbomb-base-like configuration around
-  the sunken area.
-- **What happens**: Creases around the point are reversed (mountains become valleys and
-  vice versa). The paper can be opened flat during the process.
-- **Parameters**:
-  - `point_to_sink`: which vertex/corner
-  - `sink_depth`: how far to push in (defined by a crease line around the point)
-  - `crease_pattern`: the polygon of creases that defines the sink boundary
-- **Decomposition**: Multiple crease reversals; the paper is opened, re-creased, re-collapsed
-- **Difficulty**: Intermediate
-
-#### 2.8b Closed Sink
-- **Geometry**: Same goal as open sink, but the paper layers cannot be separated during the
-  operation. The corner is pushed in while the paper remains closed.
-- **What happens**: The point inverts without opening. Paper layers become deeply intertwined.
-  All axial creases around the point become mountain folds (key difference from open sink).
-- **Parameters**: Same as open sink
-- **Decomposition**: Simultaneous reversal of multiple creases without opening
-- **Difficulty**: Advanced -- requires significant force; layers lock together
-
-#### 2.8c Spread Sink (Spread Squash)
-- **Geometry**: A closed flap or point is pushed in while the surrounding paper spreads
-  outward and flattens. The sinked analog of the squash fold.
-- **What happens**: Creates a wide, flat area around the flap's base instead of a long point
-- **Parameters**: Same as open sink + spread direction
-- **Decomposition**: Sink + flatten/spread
-- **Difficulty**: Advanced
-
-### 2.9 Unsink Fold (Two Variants)
-
-**The inverse of sink -- pops a sunken point back out.**
-
-#### 2.9a Open Unsink
-- Makes a concave pocket convex without fully unfolding
-- The opposite of an open sink
-
-#### 2.9b Closed Unsink
-- Inverts a closed sink without opening the paper
-- Extremely difficult -- requires pulling (not pushing) hidden paper
-- Involves simultaneously folding a locking flap hidden inside
-
-### 2.10 Crimp Fold
-
-**A reverse fold applied to an edge rather than a point.**
-
-- **Geometry**: Opens a section of paper, applies a valley fold, then a mountain fold with
-  some paper between them, creating a zigzag profile.
-- **What happens**: Two parallel or near-parallel creases are created, with the paper between
-  them forming a step. The edge changes direction.
-- **Parameters**:
-  - `crimp_location`: where along the edge
-  - `fold_line_1`: first crease (valley)
-  - `fold_line_2`: second crease (mountain)
-  - `crimp_width`: distance between the two creases
-  - `crimp_angle`: angle of direction change
-- **Decomposition**: 1 valley fold + 1 mountain fold applied simultaneously to a multi-layer section
-- **Relationship**: Similar to pleat fold but applied to a folded edge (multiple layers);
-  like an inside reverse fold but without full reversal
-- **Common use**: Creating feet, zigzag shapes, direction changes in legs
-
-### 2.11 Pleat Fold (Accordion Fold)
-
-**The simplest compound fold -- alternating valleys and mountains.**
-
-- **Geometry**: A series of parallel or near-parallel alternating valley and mountain folds.
-  Creates a zigzag/accordion profile.
-- **What happens**: Paper forms parallel ridges and valleys, like a fan or accordion.
-- **Parameters**:
-  - `fold_lines[]`: array of parallel crease lines
-  - `fold_types[]`: alternating valley/mountain assignments
-  - `pleat_width`: distance between consecutive creases (can be uniform or varying)
-  - `num_pleats`: number of folds
-- **Decomposition**: n alternating valley + mountain folds
-- **Common use**: Adding detail (pleats in clothing), creating segmented forms, fan shapes
-
-### 2.12 Swivel Fold
-
-**A loosely-defined fold where one flap "swivels" around a pivot point.**
-
-- **Geometry**: A flap of paper rotates around a specific vertex or point while a connected
-  flap or edge is dragged around that pivot. One fold inevitably causes another.
-- **What happens**: Simultaneous folding of multiple connected regions around a pivot point.
-  One fold "trails" another.
-- **Parameters**:
-  - `pivot_point`: the vertex around which paper swivels
-  - `primary_fold_line`: the main fold being executed
-  - `trailing_fold_line`: the induced fold
-  - `swivel_angle`: angle of rotation
-- **Decomposition**: 2+ simultaneous folds (one driving, one or more trailing)
-- **Note**: Loosely defined; many different configurations qualify as "swivel folds"
-- **Common use**: Shaping flaps, creating offset angles, bird tails
-
-### Summary: Fold Type Taxonomy
-
-```
-ATOMIC FOLDS (single crease, corresponds to 1 axiom application):
-  |-- Valley Fold (gamma > 0)
-  |-- Mountain Fold (gamma < 0)
-
-COMPOUND FOLDS (multiple simultaneous creases):
-  |-- Reverse Folds
-  |   |-- Inside Reverse Fold (3 crease changes)
-  |   |-- Outside Reverse Fold (3 crease changes)
-  |
-  |-- Squash Fold (2-3 crease changes)
-  |
-  |-- Petal Fold (5 simultaneous crease changes)
-  |
-  |-- Rabbit Ear Fold (3 simultaneous creases)
-  |
-  |-- Sink Folds
-  |   |-- Open Sink (multiple reversals, paper opens)
-  |   |-- Closed Sink (multiple reversals, paper stays closed)
-  |   |-- Spread Sink (sink + flatten)
-  |
-  |-- Unsink Folds
-  |   |-- Open Unsink (reverse of open sink)
-  |   |-- Closed Unsink (reverse of closed sink)
-  |
-  |-- Crimp Fold (2 simultaneous folds on multi-layer edge)
-  |
-  |-- Pleat Fold (n alternating valley/mountain folds)
-  |
-  |-- Swivel Fold (2+ coupled folds around pivot)
-
-NON-FOLD OPERATIONS (manipulations):
-  |-- Turn Over (flip paper)
-  |-- Rotate (in-plane rotation)
-  |-- Inflate / Open (spread layers apart, puff out)
-  |-- Unfold (reverse a previous fold)
-  |-- Cut (kirigami -- not standard origami)
-```
-
-### Fold Parameter Space
-
-For an RL environment, each fold can be parameterized as:
-
-```
-Action = {
-  fold_type:     enum[valley, mountain, reverse_in, reverse_out, squash, petal,
-                      rabbit_ear, sink_open, sink_closed, spread_sink,
-                      unsink_open, unsink_closed, crimp, pleat, swivel,
-                      turn_over, rotate, inflate, unfold]
-
-  -- For atomic folds (valley/mountain):
-  fold_line:     (point: vec2, direction: vec2)  -- or (point1, point2)
-  fold_angle:    float [0, pi]                   -- how far to fold
-  layers:        bitset                          -- which layers to fold
-
-  -- For compound folds, additional params:
-  target_flap:   flap_id                         -- which flap to operate on
-  depth:         float                           -- for reverse/sink: how deep
-  angle:         float                           -- for reverse/crimp: fold angle
-  direction:     enum[left, right, up, down]     -- fold direction preference
-  width:         float                           -- for crimp/pleat: spacing
-
-  -- For manipulation operations:
-  rotation_angle: float                          -- for rotate
-  axis:          enum[horizontal, vertical]      -- for turn_over
-}
-```
-
----
-
-## 3. Origami Bases -- Starting Configurations
-
-Bases are standard intermediate forms that serve as starting points for families of models.
-**Yes, bases are shortcuts for common fold sequences.** They represent well-known crease
-patterns that produce useful distributions of flaps and points.
-
-### 3.1 Preliminary Base (Square Base)
-
-- **Shape**: Multi-layered diamond/square standing on a corner
-- **Flaps**: 4 flaps (2 front, 2 back)
-- **Points**: 1 closed point at top, 4 open edges at bottom
-- **Construction from flat square**:
-  1. Valley fold in half horizontally (1 fold)
-  2. Valley fold in half vertically (1 fold)
-  3. Unfold both (0 folds -- return to flat with creases)
-  4. Valley fold diagonally both ways (2 folds, unfold)
-  5. Collapse: push sides in using existing creases (simultaneous collapse)
-- **Total atomic folds**: ~4 creases + 1 collapse = ~5 operations
-- **Crease pattern**: 2 perpendicular valley diagonals + 2 perpendicular mountain edge-bisectors
-- **Key relationship**: Inverse of Waterbomb base (same creases, swapped mountain/valley)
-- **Gateway to**: Bird base, Frog base, Flower base
-
-### 3.2 Waterbomb Base
-
-- **Shape**: Flat triangle with multiple layers
-- **Flaps**: 4 flaps (2 front, 2 back)
-- **Points**: 4 points at base, closed edges at sides
-- **Construction from flat square**:
-  1. Valley fold both diagonals (2 folds, unfold)
-  2. Mountain fold horizontally and vertically (2 folds, unfold)
-  3. Collapse into triangle form
-- **Total atomic folds**: ~4 creases + 1 collapse = ~5 operations
-- **Crease pattern**: 2 perpendicular mountain diagonals + 2 perpendicular valley edge-bisectors
-- **Key relationship**: Inverse of Preliminary base (same creases, swapped mountain/valley)
-- **Gateway to**: Waterbomb (balloon), waterbomb tessellations, some Frog base variants
-
-### 3.3 Kite Base
-
-- **Shape**: Kite-shaped flat form
-- **Flaps**: 1 main point, 2 small triangular flaps
-- **Construction from flat square**:
-  1. Valley fold diagonal (1 fold, unfold -- reference crease)
-  2. Valley fold two adjacent edges to lie on the diagonal (2 folds)
-- **Total atomic folds**: 3 (simplest base)
-- **Gateway to**: Simple animals (dog face, cat face), Kite -> Fish base progression
-
-### 3.4 Fish Base
-
-- **Shape**: Diamond shape with 4 points (two long, two short)
-- **Flaps**: 4 points usable for fins/legs/petals
-- **Construction from flat square**:
-  1. Start with kite base (3 folds)
-  2. Rabbit ear fold on one end (3 simultaneous creases)
-  3. Rabbit ear fold on other end (3 simultaneous creases)
-  4. Fold resulting flaps down (2 folds)
-- **Total atomic folds**: ~8-11 operations
-- **Crease pattern**: Two rabbit ears against diagonal reference creases on opposite corners
-- **Gateway to**: Fish models, some flower models
-
-### 3.5 Bird Base (Crane Base)
-
-- **Shape**: Long diamond with 4 narrow flaps
-- **Flaps**: 4 long, narrow flaps (2 front, 2 back)
-- **Points**: All 4 original corners become elongated points
-- **Construction from flat square**:
-  1. Fold preliminary base (~5 operations)
-  2. Kite-fold front flaps: fold left and right edges to center line (2 valley folds)
-  3. Fold top triangle down over the kite folds (1 valley fold, then unfold)
-  4. Unfold the kite folds (restore)
-  5. Petal fold: lift bottom point up using existing creases (1 petal fold = ~5 crease changes)
-  6. Turn over
-  7. Repeat steps 2-5 on back side (mirror)
-- **Total atomic folds**: ~18-22 operations from flat square
-- **Key significance**: The most versatile and widely-used origami base
-- **Gateway to**: Crane, many birds, dragon, horse, and hundreds of other models
-
-### 3.6 Frog Base
-
-- **Shape**: 4 long narrow flaps radiating from center (more symmetrical than bird base)
-- **Flaps**: 4 long flaps + 4 shorter flaps
-- **Construction from flat square**:
-  1. Fold preliminary base (~5 operations)
-  2. Squash fold each of the 4 flaps (4 squash folds)
-  3. Petal fold each of the 4 resulting diamonds (4 petal folds)
-- **Total atomic folds**: ~25-30 operations from flat square
-- **Gateway to**: Frog, lily, iris, and other 4-legged/4-petal models
-
-### 3.7 Windmill Base
-
-- **Shape**: 4 triangular flaps arranged like a pinwheel
-- **Flaps**: 4 flaps that can rotate in a windmill pattern
-- **Construction from flat square**:
-  1. Fold and unfold both diagonals and both midlines (4 creases)
-  2. Fold all 4 edges to center (4 valley folds) -- this is the "blintz fold"
-  3. Unfold
-  4. Fold 2 opposite edges to center (2 valley folds)
-  5. Pull out trapped corners and flatten (2 squash-like operations)
-- **Total atomic folds**: ~12-15 operations
-- **Gateway to**: Windmill, some modular units, windmill-derived models
-
-### Base Relationship Map
-
-```
-Flat Square
-  |
-  +---> Kite Base ---------> Fish Base
-  |        (3 folds)            (8-11 folds)
-  |
-  +---> Preliminary Base ---> Bird Base ------> [Crane, Birds, etc.]
-  |        (5 folds)            (18-22 folds)
-  |                        |
-  |                        +-> Frog Base -----> [Frog, Lily, etc.]
-  |                              (25-30 folds)
-  |
-  +---> Waterbomb Base -----> [Waterbomb/Balloon, etc.]
-  |        (5 folds)
-  |
-  +---> Blintz Base --------> Windmill Base -> [Windmill, etc.]
-  |        (8 folds)            (12-15 folds)
-  |
-  +---> Book Fold / Cupboard Fold / etc.
-```
-
----
-
-## 4. Crane (Tsuru) Complete Fold Sequence
-
-The traditional origami crane (orizuru) is THE canonical origami model, and the best
-benchmark for an RL environment. Here is the complete fold-by-fold sequence from flat
-square to finished crane.
-
-### Phase 1: Create Crease Pattern (Pre-creasing)
-
-| Step | Operation | Fold Type | Fold Line | Result |
-|------|-----------|-----------|-----------|--------|
-| 1 | Fold square in half diagonally (corner to corner) | Valley fold | Main diagonal (bottom-left to top-right) | Triangle |
-| 2 | Unfold | Unfold | -- | Square with diagonal crease |
-| 3 | Fold in half on other diagonal | Valley fold | Other diagonal (bottom-right to top-left) | Triangle |
-| 4 | Unfold | Unfold | -- | Square with X crease |
-| 5 | Fold in half horizontally | Valley fold | Horizontal midline | Rectangle |
-| 6 | Unfold | Unfold | -- | Square with X + horizontal crease |
-| 7 | Fold in half vertically | Valley fold | Vertical midline | Rectangle |
-| 8 | Unfold | Unfold | -- | Square with full crease pattern (X + cross) |
-
-### Phase 2: Collapse into Preliminary Base
-
-| Step | Operation | Fold Type | Details | Result |
-|------|-----------|-----------|---------|--------|
-| 9 | Collapse: push left and right edges inward while folding top down | Simultaneous collapse | Diagonals become valley folds, midlines become mountain folds | Preliminary base (4-layer diamond) |
-
-### Phase 3: Kite Folds (Front)
-
-| Step | Operation | Fold Type | Fold Line | Result |
-|------|-----------|-----------|-----------|--------|
-| 10 | Fold left edge of top layer to center line | Valley fold | Left edge to center crease | Left kite flap |
-| 11 | Fold right edge of top layer to center line | Valley fold | Right edge to center crease | Kite shape |
-| 12 | Fold top triangle down over kite flaps | Valley fold | Horizontal line at top of kite flaps | Triangle folded over |
-| 13 | Unfold step 12 | Unfold | -- | Kite shape with horizontal crease |
-| 14 | Unfold steps 10-11 | Unfold | -- | Diamond with crease guides |
-
-### Phase 4: Front Petal Fold
-
-| Step | Operation | Fold Type | Details | Result |
-|------|-----------|-----------|---------|--------|
-| 15 | Lift bottom point of top layer upward using existing creases; sides collapse inward | Petal fold | Bottom point lifts to top; left and right edges fold to center simultaneously | Front petal fold complete -- one long narrow flap pointing up |
-
-### Phase 5: Repeat on Back
-
-| Step | Operation | Fold Type | Details | Result |
-|------|-----------|-----------|---------|--------|
-| 16 | Turn model over | Turn over | Flip along vertical axis | Back is now front |
-| 17 | Fold left edge to center line | Valley fold | Left edge to center | Left kite flap |
-| 18 | Fold right edge to center line | Valley fold | Right edge to center | Kite shape |
-| 19 | Fold top triangle down | Valley fold | Horizontal line at top | Triangle folded over |
-| 20 | Unfold step 19 | Unfold | -- | Kite with crease |
-| 21 | Unfold steps 17-18 | Unfold | -- | Diamond with creases |
-| 22 | Petal fold: lift bottom point up, collapse sides in | Petal fold | Same as step 15 on back | Bird base complete |
-
-### Phase 6: Narrow the Legs
-
-| Step | Operation | Fold Type | Details | Result |
-|------|-----------|-----------|---------|--------|
-| 23 | Fold left flap (front layer) edge to center | Valley fold | Left edge to centerline | Narrower left flap |
-| 24 | Fold right flap (front layer) edge to center | Valley fold | Right edge to centerline | Narrower right flap |
-| 25 | Turn over | Turn over | -- | Back side |
-| 26 | Fold left flap edge to center | Valley fold | Left edge to centerline | Narrower left flap (back) |
-| 27 | Fold right flap edge to center | Valley fold | Right edge to centerline | Narrower right flap (back) |
-
-### Phase 7: Form Neck and Tail
-
-| Step | Operation | Fold Type | Details | Result |
-|------|-----------|-----------|---------|--------|
-| 28 | Fold left bottom flap (front+back layers) upward along angle to form neck | Inside reverse fold | Fold line at ~60-70 degrees from vertical | Neck points upward at angle |
-| 29 | Fold right bottom flap upward to form tail | Inside reverse fold | Fold line at ~60-70 degrees from vertical | Tail points upward |
-
-### Phase 8: Form Head and Finish
-
-| Step | Operation | Fold Type | Details | Result |
-|------|-----------|-----------|---------|--------|
-| 30 | Fold tip of neck downward to form head/beak | Inside reverse fold | Small fold near tip of neck, ~30 degrees | Head with beak |
-| 31 | Gently pull wings apart from body and press bottom to create 3D body | Open/Inflate | Separate wing layers, crease body | Finished crane |
-
-### Crane Fold Statistics
-
-| Metric | Count |
-|--------|-------|
-| **Total numbered steps** | 31 |
-| **Valley folds** | 14 |
-| **Unfolds** | 6 |
-| **Petal folds** | 2 (each = ~5 atomic crease changes) |
-| **Inside reverse folds** | 3 (each = ~3 atomic crease changes) |
-| **Turn over** | 2 |
-| **Collapse** | 1 (= ~4 simultaneous crease changes) |
-| **Open/inflate** | 1 |
-| **Total atomic crease changes** | ~40-45 |
-| **Unique fold types used** | 5 (valley, petal, inside reverse, collapse, inflate) |
-
----
-
-## 5. Compression/Packing Origami Patterns
-
-These are tessellation and pattern-based folds used in engineering, not traditional origami
-art. Critical for understanding the space of possible flat-to-compact transformations.
-
-### 5.1 Miura-ori Fold
-
-- **Inventor**: Koryo Miura (1970)
-- **Geometry**: Tessellation of parallelograms with alternating mountain/valley creases.
-  In one direction, creases are straight lines with mirror-reflected parallelograms.
-  In the other direction, creases zigzag, with parallelograms translated across creases.
-- **Parameters**:
-  - Parallelogram angle (alpha): the acute angle of the parallelogram, typically 55-85 degrees
-  - Panel width and height
-  - Number of panels in each direction
-- **Rigid-foldable**: YES -- can be folded with completely rigid (non-bending) panels
-- **Degrees of freedom**: 1 (single DOF per unit cell). The entire sheet deploys/compacts
-  with a single motion.
-- **Compression**: Folds flat in BOTH directions simultaneously. Unfolds by pulling opposite
-  corners apart in a single motion.
-- **Poisson's ratio**: Always NEGATIVE (auxetic material). When you pull it in one direction,
-  it expands in the perpendicular direction too.
-- **Compression ratio**: Depends on number of panels; theoretically approaches thickness-only
-  when fully compressed. A sheet can compress to approximately (n_panels * t) where t is
-  material thickness.
-- **Applications**: Satellite solar panel arrays (Space Flyer Unit, 1995), metamaterials,
-  deployable shelters, foldable maps
-- **Crease pattern**: Regular grid of mountain and valley folds at specific angles
-
-### 5.2 Waterbomb Tessellation
-
-- **Geometry**: Repeating waterbomb base units tessellated across a surface. Each unit has
-  degree-6 vertices with alternating mountain/valley folds.
-- **Parameters**:
-  - Base unit size
-  - Grid dimensions
-  - Mountain/valley assignment per crease
-- **Rigid-foldable**: Partially (depends on configuration)
-- **Compression ratio**: ~3:1 (switching ratio)
-- **Properties**: Can form curved surfaces; used in origami-inspired robots; basis for
-  many adaptive structures
-- **Applications**: Soft robotics, adaptive surfaces, energy absorption
-
-### 5.3 Ron Resch Pattern
-
-- **Inventor**: Ron Resch (patent 1968)
-- **Geometry**: Folded equilateral triangles arranged in periodic radial formation.
-  Six triangles around a central point compress together to form a flat-surfaced hexagon.
-- **Parameters**:
-  - Triangle size
-  - Grid pattern (triangular or square variant)
-  - Fold depth
-- **Rigid-foldable**: No (requires panel bending)
-- **Compression ratio**: Up to 50:1 theoretical, ~6:1 practical (limited by creep)
-- **Specific elastic compression modulus**: 15-365 MPa/kg for standard designs;
-  novel variants reach 594-926 MPa/kg
-- **Properties**: Excellent energy absorption; creates two flat surfaces (top and bottom)
-  with triangular columns between them
-- **Applications**: Impact damping, packaging, architectural surfaces, sandwich panel cores
-
-### 5.4 Flasher Pattern
-
-- **Geometry**: Central polygon (typically hexagon or octagon) whose edges connect to
-  extending panels, each with identical crease geometry. Panels spiral around the
-  central polygon when folded.
-- **Parameters**:
-  - Central polygon type and size
-  - Number of extending panel rings
-  - Spiral angle
-  - Panel thickness (critical for rigid implementations)
-- **Compression ratio**: Stowed-to-deployed diameter ratio of ~9.2:1 for typical designs;
-  area ratio much higher (square of diameter ratio, ~85:1)
-- **Rigid-foldable**: With modifications (membrane hinges or diagonal folding to accommodate
-  panel thickness)
-- **Degrees of freedom**: 1 (deploys/compacts with single rotational motion)
-- **Applications**: Space solar arrays (250+ kW), solar sails, deployable reflectors,
-  NASA deployable structures
-- **Key challenge**: Accommodating real material thickness; zero-thickness models don't
-  directly translate
-
-### 5.5 Kresling Pattern
-
-- **Inventor**: Biruta Kresling
-- **Geometry**: Tessellated triangles forming a thin cylindrical structure. Diagonal fold
-  lines create helical creases around the cylinder.
-- **Parameters**:
-  - Number of polygon sides (n, typically 6-8)
-  - Cylinder radius
-  - Triangle aspect ratio
-  - Folding angles (beta and gamma relative to horizontal)
-- **Rigid-foldable**: NO (requires panel bending/deformation for compression)
-- **Degrees of freedom**: Coupled -- compression induces twist (axial-torsional coupling)
-- **Compression ratio**: ~1.5:1 switching ratio
-- **Bistability**: Key property -- can snap between extended and compressed states.
-  Geometrical parameters can be tuned for mono-, bi-, or multistability.
-- **Properties**: Compression-twist coupling, negative stiffness regions, energy storage
-- **Applications**: Soft robots, mechanical metamaterials, deployable tubes, vibration isolation,
-  energy harvesting
-
-### 5.6 Yoshimura Pattern
-
-- **Geometry**: Diamond/rhombus pattern around a cylinder, creating a Yoshimura buckle
-- **Rigid-foldable**: NO
-- **Properties**: Natural buckling pattern of thin cylindrical shells under axial compression
-- **Applications**: Crushable energy absorbers, deployable structures
-
-### Pattern Comparison Table
-
-| Pattern | Rigid-Foldable | DOF | Compression Ratio | Bistable | Key Property |
-|---------|---------------|-----|-------------------|----------|--------------|
-| Miura-ori | Yes | 1 | High (thickness-limited) | No | Auxetic (negative Poisson's ratio) |
-| Waterbomb | Partial | Multi | ~3:1 | No | Curved surfaces possible |
-| Ron Resch | No | Multi | ~6-50:1 | No | Excellent energy absorption |
-| Flasher | Modified yes | 1 | ~9.2:1 (diameter) | No | Spiral deployment |
-| Kresling | No | Coupled | ~1.5:1 | YES | Compression-twist coupling |
-| Yoshimura | No | Multi | Moderate | No | Natural buckling mode |
-
----
-
-## 6. Yoshizawa-Randlett Notation System
-
-The standard international notation system for origami diagrams, created by Akira Yoshizawa
-(1954) and formalized by Samuel Randlett and Robert Harbin (1961).
-
-### 6.1 Line Types
-
-| Line Style | Meaning | Description |
-|------------|---------|-------------|
-| Dashed line `------` | Valley fold | Paper folds toward you |
-| Dot-dash line `-.-.-.` | Mountain fold | Paper folds away from you |
-| Thin solid line | Existing crease | A crease already made in a previous step |
-| Thick solid line | Paper edge | The boundary of the paper |
-| Dotted line `......` | X-ray line | Hidden edge or crease visible through layers |
-
-### 6.2 Arrow Types
-
-| Arrow | Meaning | Visual |
-|-------|---------|--------|
-| Filled/split arrowhead, curved stem | Valley fold (fold toward you) | Shows rotation path of paper |
-| Hollow single-sided arrowhead | Mountain fold (fold away) | Hooks behind moving flap |
-| Double-sided hollow arrowheads | Fold and unfold | Make crease, then return |
-| Double-sided hollow (on existing fold) | Unfold only | Reverse an existing fold |
-| Arrow with loop in stem | Turn paper over | Flip horizontally or vertically |
-| Hollow cleft-tailed arrow | Push / Apply pressure | Used for sinks, inflations, reverses |
-| Arrow curving around layers | Hooking arrow | Shows which specific layers move |
-| Arrow touching down multiple times | Fold over and over | Repeated folding |
-
-### 6.3 Special Symbols
-
-| Symbol | Meaning |
-|--------|---------|
-| Circle with fraction + curved arrows | Rotate in plane (e.g., 1/4 turn) |
-| Box with step range + count | Repeat steps (e.g., "steps 5-8, x4") |
-| Open circle on paper | Hold here / grip point |
-| Perpendicular marks on edges | Equal distances |
-| Arc marks on angles | Equal angles |
-| Heavy circle around area | Cut-away view (shows hidden layers) |
-| Zigzag line (edge view) | Crimp/pleat layer diagram |
-| Stylized eye symbol | Next view location/angle |
-| Scissors symbol | Cut (kirigami) |
-| Puff/cloud symbol | Inflate / blow air |
-
-### 6.4 Compound Fold Notation
-
-| Fold Type | Notation Components |
-|-----------|-------------------|
-| Inside reverse | Mountain line (near layer) + valley line (far layer) + push arrow + valley motion arrow |
-| Outside reverse | Paired mountain/valley lines + hooked arrows showing opposite directions |
-| Squash | Valley fold line + push arrow + opening indicator |
-| Petal | 2 mountain lines + 1 valley line + lift arrow |
-| Rabbit ear | 3 valley lines (bisectors) + 1 mountain line + flap direction arrow |
-| Sink | Mountain fold line + push arrow (hollow for open sink; dots at corners for closed) |
-| Crimp | Edge-view zigzag diagram + paired fold lines |
-
----
-
-## 7. Fold Sequence Complexity
-
-### 7.1 Complexity Classification (OrigamiUSA Standard)
-
-| Level | Steps | Time | Fold Types Used |
-|-------|-------|------|-----------------|
-| Simple | 1-16 | 5-15 min | Valley and mountain folds only |
-| Low Intermediate | 10-20 | 10-20 min | + reverse folds |
-| Intermediate | 17-30 | 15-40 min | + squash, petal folds |
-| High Intermediate | 25-50 | 20-60 min | + sink folds, complex shaping |
-| Complex | 40-100 | 1-4 hours | All fold types, multi-step collapses |
-| Super Complex | 100-1000+ | Hours to weeks | Nested sinks, 10+ simultaneous creases |
-
-### 7.2 Model Complexity Examples
-
-| Model | Approximate Folds | Level | Key Operations |
-|-------|-------------------|-------|----------------|
-| Paper airplane | 5-7 | Simple | Valley folds only |
-| Fortune teller | 8 | Simple | Valley folds, turn over |
-| Waterbomb (balloon) | 10-12 | Simple | Valley, mountain, inflate |
-| Jumping frog | 15-18 | Low Intermediate | Valley, mountain, pleat |
-| Crane (tsuru) | 30-31 | Intermediate | Valley, petal, inside reverse, inflate |
-| Lily/Iris | 35-45 | Intermediate | Valley, petal, curl |
-| Traditional frog | 40-50 | High Intermediate | Valley, petal, sink, reverse |
-| Dragon | 60-100 | Complex | All fold types |
-| Kawasaki's rose | 40-60 | Complex | Twist folds, curl, 3D shaping |
-| Kamiya's Ryujin 3.5 (dragon) | 1000+ | Super Complex | Everything, including nested sinks |
-
-### 7.3 Complexity Scaling
-
-The relationship between fold count and model complexity is **super-linear**:
-
-- Each fold adds to the **state space** exponentially (more layers, more possible future folds)
-- Compound folds (petal, sink) each involve 3-10 atomic crease changes
-- **Layer count** grows exponentially: after n flat folds, up to 2^n layers in some regions
-- **Branching factor**: At each step, the number of possible next folds depends on the
-  current crease pattern, number of exposed edges, and layer configuration
-- **Collapse operations**: Some steps require 4-10+ creases to change simultaneously,
-  making them hard to decompose into atomic actions for RL
-
-### 7.4 Computational Complexity Results
-
-- **Flat-foldability** (single vertex): Polynomial -- checkable via Kawasaki's and Maekawa's theorems
-- **Flat-foldability** (multi-vertex, global): **NP-complete** (proven by Bern and Hayes, 1996)
-- **Simple fold sequences**: Can be verified in polynomial time
-- **Optimal fold sequences** (minimum folds to reach a target): Unknown complexity class,
-  likely intractable for complex models
-
----
-
-## 8. Flat-Foldability Theorems
-
-These theorems constrain what configurations are VALID in the state space -- they define the
-physics/rules of the environment.
-
-### 8.1 Kawasaki's Theorem (Kawasaki-Justin Theorem)
-
-**At a single flat-foldable vertex, the alternating sum of consecutive sector angles equals zero.**
-
-```
-alpha_1 - alpha_2 + alpha_3 - alpha_4 + ... = 0
-```
-
-Equivalently: if you partition the angles around a vertex into two alternating subsets,
-each subset sums to exactly 180 degrees.
-
-- **Applies to**: Single vertex, flat-foldable patterns
-- **Necessary and sufficient**: For single-vertex flat foldability (combined with Maekawa's)
-- **Discovered by**: Kawasaki, Robertson, and Justin (late 1970s - early 1980s)
-
-### 8.2 Maekawa's Theorem (Maekawa-Justin Theorem)
-
-**At every flat-foldable vertex, the number of mountain folds and valley folds differ by exactly 2.**
-
-```
-|M - V| = 2
-```
-
-Where M = number of mountain folds and V = number of valley folds at that vertex.
-
-- **Corollary**: The total number of creases at a flat-foldable vertex must be even
-- **Corollary**: Since M - V = +/- 2, and M + V = total creases, you can derive M and V
-  given the total number of creases
-
-### 8.3 Additional Constraints
-
-- **Two-colorability**: A flat-foldable crease pattern divides the paper into regions that
-  can be two-colored (like a checkerboard) such that regions sharing a crease get different colors
-- **No self-intersection**: Paper cannot pass through itself during folding
-- **Layer ordering**: At any point in a flat-folded model, the layers must have a consistent
-  stacking order that respects fold connectivity
-- **Global flat-foldability**: NP-complete for general crease patterns (Bern & Hayes, 1996)
-
-### 8.4 Implications for RL Environment
-
-These theorems define the **validity constraints** for the environment:
-- After each fold action, the resulting crease pattern must satisfy Kawasaki's and Maekawa's
-  theorems at every vertex for flat foldability
-- The layer ordering must remain consistent (no self-intersection)
-- Invalid actions (violating these constraints) should be either prevented or penalized
-
----
-
-## 9. RL Environment Design Implications
-
-### 9.1 Action Space Options
-
-Based on the research, there are three natural levels for defining the action space:
-
-#### Option A: Axiom-Level (Pure Primitives)
-```
-Action = HuzitaJustinAxiom(axiom_number, input_points, input_lines)
-```
-- **Size**: 7 axiom types x continuous parameters = continuous action space
-- **Pros**: Mathematically complete, provably covers all possible single folds
-- **Cons**: Very low-level; compound folds like petal fold require many steps;
-  the agent must discover compound operations on its own
-
-#### Option B: Named Fold Level (Origami Operations)
-```
-Action = FoldOperation(fold_type, target, parameters)
-```
-- **Size**: ~15-19 fold types x continuous parameters
-- **Pros**: Matches how humans think about origami; compound folds are single actions;
-  faster learning due to higher-level primitives
-- **Cons**: Not mathematically minimal; some folds are hard to parameterize (sink folds);
-  harder to implement a general simulator
-
-#### Option C: Hybrid (Recommended)
-```
-Action = {
-  level: [axiom | compound]
-  if axiom: (axiom_id, params...)
-  if compound: (fold_type, flap_id, params...)
-}
-```
-- **Pros**: Agent can use either low-level or high-level actions; macro-actions speed up
-  learning while atomic actions enable novel folds
-- **Cons**: Larger action space; need to implement both levels
-
-### 9.2 State Representation
-
-The state needs to capture:
-1. **Crease pattern**: Graph of vertices and creases with mountain/valley assignments
-2. **Layer ordering**: At every point, which layers are on top
-3. **3D configuration**: Current fold angles (dihedral angles at each crease)
-4. **Paper boundary**: The current outline of the folded paper
-
-### 9.3 Reward Shaping Considerations
-
-- **Target matching**: Compare current crease pattern to target model's crease pattern
-- **Base achievement**: Intermediate rewards for reaching known bases
-- **Fold validity**: Penalty for invalid folds (violating Kawasaki/Maekawa)
-- **Efficiency**: Bonus for fewer total folds
-- **Symmetry**: Reward for symmetric fold patterns (most models are symmetric)
-
-### 9.4 Key Challenges
-
-1. **Continuous action space**: Fold lines are defined by continuous parameters (position, angle)
-2. **Variable-length sequences**: Different models need different numbers of folds (5-1000+)
-3. **State explosion**: Layer count grows exponentially with folds
-4. **Physical constraints**: Paper cannot self-intersect; fold validity is non-trivial to check
-5. **3D reasoning**: Many operations (reverse folds, sinks) require reasoning about 3D geometry
-   even though the result is flat
-6. **Simultaneous creases**: Compound folds change 3-10 creases at once -- this is hard to
-   decompose for a step-by-step environment
-
-### 9.5 Suggested Starting Point
-
-For a first implementation, consider:
-- **Action space**: Valley fold + Mountain fold + Turn over + Unfold (4 operations with
-  continuous fold-line parameters)
-- **Target**: Simple models only (paper airplane, fortune teller, waterbomb)
-- **State**: 2D crease pattern + layer count map
-- **Expansion path**: Add reverse fold -> squash fold -> petal fold -> sink fold as the
-  agent masters simpler operations
-
----
-
-## Sources
-
-- [Huzita-Justin Axioms - Robert J. Lang](https://langorigami.com/article/huzita-justin-axioms/)
-- [Huzita-Hatori Axioms - Wikipedia](https://en.wikipedia.org/wiki/Huzita%E2%80%93Hatori_axioms)
-- [The Huzita-Justin Axioms - Origami Math](https://orimath.wordpress.com/2021/08/02/the-huzita-hatori-axioms/)
-- [One, Two, and Multi-Fold Origami Axioms - Alperin & Lang](https://langorigami.com/wp-content/uploads/2015/09/o4_multifold_axioms.pdf)
-- [Origami Diagramming Conventions - Robert J. Lang](https://langorigami.com/article/origami-diagramming-conventions/)
-- [Yoshizawa-Randlett System - Wikipedia](https://en.wikipedia.org/wiki/Yoshizawa%E2%80%93Randlett_system)
-- [Fold Hierarchy and Origin of Origami Symbols - British Origami](https://www.britishorigami.org/cp-lister-list/fold-hierarchy-and-origin-of-origami-symbols/)
-- [Origami Bases - Wikibooks](https://en.wikibooks.org/wiki/Origami/Techniques/Model_bases)
-- [Origami Techniques Practice - Wikibooks](https://en.wikibooks.org/wiki/Origami/Techniques/Practice)
-- [Kawasaki's Theorem - Wikipedia](https://en.wikipedia.org/wiki/Kawasaki's_theorem)
-- [Maekawa's Theorem - Wikipedia](https://en.wikipedia.org/wiki/Maekawa's_theorem)
-- [Flat Foldability - Abrashi Origami School](https://abrashiorigami.com/maekawa-justin-and-kawasaki-justin-theorems/)
-- [Mathematics of Paper Folding - Wikipedia](https://en.wikipedia.org/wiki/Mathematics_of_paper_folding)
-- [Miura Fold - Wikipedia](https://en.wikipedia.org/wiki/Miura_fold)
-- [Geometry of Miura-folded Metamaterials - PNAS](https://www.pnas.org/doi/10.1073/pnas.1217998110)
-- [Origami Engineering - Misseroni et al.](https://www.daraio.caltech.edu/publications/Misseroni_et_at_2024.pdf)
-- [Flasher Deployable Arrays - NASA](https://ntrs.nasa.gov/citations/20150004060)
-- [Analysis of Origami Flasher-Inspired Structures - MIT](https://dspace.mit.edu/bitstream/handle/1721.1/156648/bai-janebai-sb-meche-2024-thesis.pdf)
-- [Kresling Origami Mechanics - ScienceDirect](https://www.sciencedirect.com/science/article/abs/pii/S0022509624000966)
-- [Kresling Bistable Behavior - Cai & Deng](https://www.researchgate.net/publication/276173838_Bistable_Behavior_of_the_Cylindrical_Origami_Structure_With_Kresling_Pattern)
-- [Freeform Origami Tessellations - Tomohiro Tachi](https://origami.c.u-tokyo.ac.jp/~tachi/cg/FreeformOrigamiTessellationsTachi2013ASME.pdf)
-- [OrigamiUSA Difficulty Guidelines](https://origamiusa.org/difficulty)
-- [Origami Complexity Framework - ScienceDirect](https://www.sciencedirect.com/science/article/pii/S2095034921000489)
-- [Sink Fold - Abrashi Origami School](https://abrashiorigami.com/sink-fold/)
-- [Swivel Fold - Abrashi Origami School](https://abrashiorigami.com/swivel-fold/)
-- [Petal Fold - Abrashi Origami School](https://abrashiorigami.com/petal-fold/)
-- [Rabbit Ear - Origami Book](https://rabbitear.org/book/origami.html)
-- [From Fold to Function: Dynamic Origami Simulation](https://arxiv.org/html/2511.10580)
-- [Automating Rigid Origami Design - IJCAI](https://www.ijcai.org/proceedings/2023/0645.pdf)
-- [OrigamiSpace: Benchmarking LLMs in Origami](https://arxiv.org/html/2511.18450v1)
-- [Valley and Mountain Folds - British Origami](https://www.britishorigami.org/cp-resource/valley-mountain-folds/)
-- [Origami Crane Tutorial - Origami.me](https://origami.me/crane/)
-- [5 Essential Origami Bases - OrigamiZen](https://origamizen.com/5-essential-origami-bases-every-folder-should-master/)

research 2/origami/materials.md

@@ -1,52 +0,0 @@
-# Material Properties & Stress Simulation
-
-## Material Types
-
-| Material | Young's Modulus | Thickness | Use Case |
-|----------|----------------|-----------|----------|
-| Standard paper | ~2-4 GPa | 0.1 mm | Baseline origami |
-| Kami (origami paper) | ~2 GPa | 0.07 mm | Thin, easy to fold |
-| **Mylar** | ~3-5 GPa | 0.01-0.1 mm | **Space solar panels** |
-| **Aluminum foil** | ~70 GPa | 0.02 mm | **Deployable structures** |
-| Foil-backed paper | Composite | 0.1-0.2 mm | Metal + paper laminate |
-| Tyvek (synthetic) | ~0.2 GPa | 0.15 mm | Tear-resistant shelters |
-
-## How Material Affects the Environment
-
-Material properties change:
-- **Fold radius constraint** — thicker/stiffer = larger minimum bend radius
-- **Max layers** — thickness limits how many layers can stack
-- **Stress at creases** — Young's modulus × curvature = stress concentration
-- **Strain tolerance** — each material has a failure threshold
-
-## Stress Visualization
-
-**Ghassaei's approach (what we port):**
-- Per-vertex strain = avg percent deviation of edge lengths from rest lengths
-- Color map: blue (0 strain) → red (max strain)
-- This is **Cauchy strain / engineering strain**
-
-**For RL reward:**
-- `total_strain = mean(per_vertex_strain)` — lower = better physical validity
-- `max_strain` — must stay below material failure threshold
-- `crease_stress = f(fold_angle, thickness, Young's_modulus)` — per-crease penalty
-
-## Thickness Considerations
-- Real paper has nonzero thickness → gaps at vertices where layers meet
-- SWOMPS reference: panel=1mm, crease=0.3mm, panel E=2000MPa, crease E=20MPa
-- For engineering apps: offset panels, tapered hinges accommodate thickness
-- Start zero-thickness, add thickness as advanced feature
-
-## How to Use in Prompt
-
-```
-Material: Mylar (space-grade)
-- Thickness: 0.05mm
-- Young's modulus: 4 GPa
-- Max strain before failure: 3%
-- Max fold layers: 12
-
-Sheet: 1m × 1m
-Constraint: Pack into 10cm × 10cm × 5cm
-Must deploy to > 0.8m² area
-```

research 2/origami/math_physics_deep.md

@@ -1,1362 +0,0 @@
-# Deep Research: Mathematics, Physics, and Engineering Science of Origami
-
-> Theoretical foundations for building an origami simulation engine.
-> Compiled from academic literature, computational geometry research, and engineering publications.
-
----
-
-## Table of Contents
-
-1. [Mathematical Foundations](#1-mathematical-foundations)
-2. [Mechanics / Physics of Folding](#2-mechanics--physics-of-folding)
-3. [Computational Origami Theory](#3-computational-origami-theory)
-4. [Engineering Metrics](#4-engineering-metrics)
-5. [Key References and Sources](#5-key-references-and-sources)
-
----
-
-## 1. Mathematical Foundations
-
-### 1.1 Flat-Foldability: What Makes a Crease Pattern Flat-Foldable?
-
-A crease pattern is **flat-foldable** if it can be folded from a flat sheet of paper into a completely flat (2D) final state. This is the central question of combinatorial origami. A flat fold is formally modeled as a **piecewise isometric map** from a 2D region to itself, equipped with:
-
-1. A **crease pattern** (a planar graph embedded in the paper).
-2. A **mountain-valley (MV) assignment** labeling each crease as mountain (M) or valley (V).
-3. A **layer ordering** that specifies which regions of paper lie above which others in the folded state.
-
-For a crease pattern to be flat-foldable, ALL of the following must hold simultaneously:
-
-- **Local flat-foldability at every vertex** (Kawasaki-Justin condition).
-- **Valid MV assignment** consistent with Maekawa-Justin and Big-Little-Big constraints at every vertex.
-- **Global layer ordering** that is consistent (no paper passes through itself).
-- **No self-intersection** of the paper during the folding motion (for physical realizability).
-
-**Critical distinction:** A crease pattern can be *locally* flat-foldable at every vertex yet fail to be *globally* flat-foldable. Local conditions are necessary but not sufficient for multi-vertex patterns.
-
-**Two-colorability:** Every flat-foldable crease pattern is **two-colorable** -- the faces of the crease pattern can be colored with two colors such that no two adjacent faces share the same color. This follows from the fact that each crease reverses the orientation of the paper.
-
----
-
-### 1.2 Kawasaki-Justin Theorem
-
-#### Exact Statement
-
-**Kawasaki-Justin Theorem (Single-Vertex Flat-Foldability, Necessary and Sufficient):**
-Let a single vertex in a crease pattern have 2n crease lines meeting at it, creating consecutive sector angles alpha_1, alpha_2, ..., alpha_{2n} (summing to 2*pi). The crease pattern is flat-foldable at this vertex *if and only if*:
-
-```
-alpha_1 - alpha_2 + alpha_3 - alpha_4 + ... + alpha_{2n-1} - alpha_{2n} = 0
-```
-
-**Equivalent formulation (the 180-degree form):**
-
-```
-alpha_1 + alpha_3 + alpha_5 + ... + alpha_{2n-1} = pi   (= 180 degrees)
-alpha_2 + alpha_4 + alpha_6 + ... + alpha_{2n}   = pi   (= 180 degrees)
-```
-
-That is, the sum of every other angle equals pi. This form applies when the paper is initially flat (zero angular defect).
-
-**Immediate corollary:** The number of crease lines at a flat-foldable vertex must be **even** (2n lines creating 2n sectors).
-
-#### History
-
-This theorem was discovered independently by:
-- Toshikazu Kawasaki (1989)
-- Stuart Robertson (late 1970s)
-- Jacques Justin (1986)
-
-Hence it is properly called the **Kawasaki-Justin** theorem. The necessity was proven by all three; the sufficiency (that the angle condition is also sufficient for a *single* vertex) was first stated explicitly by Thomas Hull (1994).
-
-#### Proof Idea
-
-**Necessity:** When paper is folded flat, each crease reverses the paper's orientation. Place the first crease along the positive x-axis. In the flat-folded state, the paper accumulates rotation: after the first sector (angle alpha_1) comes the first crease, which reverses orientation. The second sector rotates by alpha_2 in the reversed direction. After traversing all 2n sectors and 2n creases, we must return to the starting direction. The net rotation is:
-
-```
-alpha_1 - alpha_2 + alpha_3 - ... - alpha_{2n} = 0
-```
-
-If this sum is not zero, the paper cannot close back on itself, so it cannot fold flat.
-
-**Sufficiency:** Given a crease pattern satisfying the angle condition, an explicit flat folding can be constructed via an **accordion fold** (crimp fold). Choose index i such that the partial alternating sum is minimized. Starting from sector alpha_{2i+1}, alternately assign mountain and valley folds, placing each angular wedge below previous folds. At each step until the final fold, the accordion fold avoids self-intersection.
-
-#### How to Compute
-
-For a simulation engine:
-
-```python
-def check_kawasaki(angles):
-    """
-    angles: list of sector angles [alpha_1, ..., alpha_2n] in radians,
-            measured consecutively around the vertex, summing to 2*pi.
-    Returns True if Kawasaki-Justin condition is satisfied.
-    """
-    if len(angles) % 2 != 0:
-        return False  # Must have even number of creases
-    alternating_sum = sum(a * ((-1)**i) for i, a in enumerate(angles))
-    return abs(alternating_sum) < EPSILON
-
-# Equivalent check:
-def check_kawasaki_180(angles):
-    odd_sum = sum(angles[i] for i in range(0, len(angles), 2))
-    even_sum = sum(angles[i] for i in range(1, len(angles), 2))
-    return abs(odd_sum - math.pi) < EPSILON and abs(even_sum - math.pi) < EPSILON
-```
-
-**For multi-vertex patterns:** Apply Kawasaki-Justin at *every* interior vertex. This gives a necessary condition for local flat-foldability, but is NOT sufficient for global flat-foldability.
-
----
-
-### 1.3 Maekawa-Justin Theorem
-
-#### Exact Statement
-
-**Maekawa-Justin Theorem:** At any interior vertex of a flat-foldable crease pattern, if M is the number of mountain folds and V is the number of valley folds, then:
-
-```
-M - V = +/- 2
-```
-
-#### Proof Idea
-
-Consider the cross-section near a flat-folded vertex. The paper forms a flat polygon when viewed edge-on. Each mountain fold contributes an interior angle of 360 degrees (the paper wraps over), and each valley fold contributes an interior angle of 0 degrees (the paper tucks under), or vice versa depending on viewing side.
-
-The sum of interior angles of an n-gon is (n-2) * 180 degrees. With n = M + V creases:
-
-```
-0 * V + 360 * M = (M + V - 2) * 180
-360M = 180M + 180V - 360
-180M - 180V = -360
-M - V = -2
-```
-
-Viewing from the other side reverses mountain and valley, giving M - V = +2. Therefore |M - V| = 2.
-
-**Corollary:** Since M + V = 2n (total creases) and M - V = +/-2, we get M = n+1, V = n-1 (or vice versa). There is always **one more mountain than valley** (or one more valley than mountain).
-
-**Corollary:** The total number of creases at a flat-foldable vertex must be even (consistent with Kawasaki-Justin).
-
-#### How to Compute
-
-```python
-def check_maekawa(assignment):
-    """
-    assignment: list of 'M' or 'V' for each crease at a vertex.
-    Returns True if Maekawa condition holds.
-    """
-    M = assignment.count('M')
-    V = assignment.count('V')
-    return abs(M - V) == 2
-
-def enumerate_maekawa_assignments(n_creases):
-    """
-    Generate all MV assignments satisfying Maekawa's theorem.
-    n_creases must be even (= 2k for some k).
-    Returns assignments with (k+1) mountains and (k-1) valleys, or vice versa.
-    """
-    from itertools import combinations
-    k = n_creases // 2
-    assignments = []
-    for n_mountains in [k + 1, k - 1]:
-        for mountain_positions in combinations(range(n_creases), n_mountains):
-            assignment = ['V'] * n_creases
-            for pos in mountain_positions:
-                assignment[pos] = 'M'
-            assignments.append(tuple(assignment))
-    return assignments
-```
-
-**Note:** Maekawa's theorem gives an upper bound on valid MV assignments. Not all assignments satisfying M - V = +/-2 are actually flat-foldable; additional constraints (Big-Little-Big, non-crossing) must also be checked.
-
----
-
-### 1.4 Big-Little-Big Angle Theorem
-
-#### Exact Statement
-
-**Big-Little-Big Lemma (BLB):** In a single-vertex crease pattern with sector angles alpha_1, ..., alpha_{2n}, if a sector angle alpha_i is a **strict local minimum** (i.e., alpha_{i-1} > alpha_i < alpha_{i+1}, with indices modulo 2n), then the two crease lines bounding that sector must have **opposite MV parities** -- one must be mountain and the other must be valley.
-
-#### Extended Form (Equal Angles)
-
-- If a local minimum consists of an **even** number of consecutive equal sector angles, the number of bordering M and V creases must differ by one.
-- If a local minimum consists of an **odd** number of consecutive equal sector angles, the number of bordering M and V creases must be equal.
-
-#### Proof Idea
-
-If both bounding creases had the same MV parity (both mountain or both valley), the larger flanking sectors would fold onto the same side of the paper, causing the paper to overlap and self-intersect through the small sector. The only way to avoid this collision is to fold one crease as mountain and the other as valley, so the larger sectors fold to opposite sides.
-
-More formally: consider the cross-section near the vertex after flat folding. The small sector must be "sandwiched" between its neighbors. If both adjacent creases have the same parity, the two large sectors would stack on the same side, creating a geometric impossibility (paper would need to pass through itself).
-
-#### Significance for Simulation
-
-The BLB lemma provides a powerful **pruning rule** for MV assignment search:
-
-1. Find all local-minimum sectors.
-2. For each, constrain the bounding creases to have opposite MV parity.
-3. This dramatically reduces the search space before attempting full layer-ordering.
-
-```python
-def apply_blb_constraints(angles, n_creases):
-    """
-    Returns a dict of constraints: {(crease_i, crease_j): 'opposite'}
-    for creases bounding local-minimum sectors.
-    """
-    constraints = {}
-    for i in range(n_creases):
-        prev = (i - 1) % n_creases
-        next_ = (i + 1) % n_creases
-        if angles[i] < angles[prev] and angles[i] < angles[next_]:
-            # Creases i and (i+1) % n bound sector i
-            c_left = i        # crease on the left of sector i
-            c_right = (i + 1) % n_creases  # crease on the right
-            constraints[(c_left, c_right)] = 'opposite'
-    return constraints
-```
-
-#### Role in Single-Vertex Foldability Algorithm
-
-The complete algorithm for single-vertex flat-foldability:
-
-1. Check **Kawasaki-Justin**: alternating angle sum = 0.
-2. Enumerate MV assignments satisfying **Maekawa-Justin**: |M - V| = 2.
-3. Filter by **Big-Little-Big**: opposite parity at local-minimum sectors.
-4. For remaining candidates, verify no self-intersection via a **layer ordering** check (crimp-and-uncrimp algorithm).
-
-This runs in **polynomial time** for single vertices (O(2^n) candidate assignments, but BLB pruning makes it tractable in practice for typical crease counts).
-
----
-
-### 1.5 Layer Ordering Problem
-
-#### What Is It?
-
-After a crease pattern is folded flat, different regions (facets) of the paper overlap. The **layer ordering** is a function that assigns each facet a position in a vertical stack wherever facets overlap. The ordering must satisfy:
-
-1. **Consistency**: If facet A is above B, and B is above C, then A must be above C (transitivity).
-2. **Non-crossing at creases**: Two facets sharing a crease line must be adjacent in the layer order along that crease (no other facet can be sandwiched between them at the crease).
-3. **Taco-taco constraint**: When two creases cross in the folded image, the layers from one crease cannot interleave arbitrarily with layers from the other.
-4. **Taco-tortilla constraint**: A crease folding layers cannot have an unfolded facet blocking its closure.
-
-#### Why NP-Hard?
-
-**Bern and Hayes (1996)** proved that determining whether a valid layer ordering exists for a given crease pattern with MV assignment is **NP-complete**.
-
-**Proof technique**: Reduction from **Not-All-Equal 3-SAT (NAE-3SAT)**:
-- A **pleat** (two parallel creases creating a fold) encodes a binary variable. The layer ordering of the pleat (which side goes on top) represents the variable's truth value.
-- A **clause gadget** is constructed where three pleats intersect. The gadget can be folded flat if and only if the three incoming pleat states are not all equal.
-- NAE-3SAT asks whether a Boolean formula in which each clause requires that its three literals not all have the same value is satisfiable. Since NAE-3SAT is NP-complete, flat-foldability is NP-complete.
-
-**Note on proof history**: A gap in the original 1996 proof went undetected for 20 years until Akitaya et al. (2016) repaired and strengthened it.
-
-#### Approximation and Tractability
-
-- **Fixed-parameter tractable (FPT)**: Flat foldability is FPT parameterized by the **ply** (maximum number of overlapping layers) and the **treewidth** of the cell adjacency graph. Time complexity: O((p!)^{O(w)} * n^2) where p = ply, w = treewidth, n = number of creases.
-- **Simple patterns**: For single-vertex patterns, the cell adjacency graph is a cycle (treewidth 1), so the algorithm is polynomial.
-- **Map folding (1D)**: Folding a 1D strip of paper with prescribed creases is solvable in O(n^2) time, but the 2D map folding problem remains open for general m x n grids.
-- **Heuristic approaches**: In practice, constraint propagation (Jason Ku's algorithm) works well:
-  1. Determine local layer orders from MV assignments at each crease.
-  2. Propagate implications (transitivity).
-  3. Recursively guess-and-check remaining ambiguities.
-  4. Backtrack on contradiction.
-
----
-
-### 1.6 Gaussian Curvature in Origami
-
-#### Fundamental Property
-
-Paper is a **developable surface**: it has **zero Gaussian curvature** everywhere. Gaussian curvature is the product of the two principal curvatures (K = kappa_1 * kappa_2). For paper:
-- At smooth (unfolded) points: the paper can bend in one direction but not two simultaneously, so at least one principal curvature is zero, giving K = 0.
-- At crease lines: the paper has a discontinuity in the surface normal (a "fold"), but the Gaussian curvature of each face on either side remains zero. The crease itself concentrates curvature into a 1D line.
-- At vertices: this is where things get interesting.
-
-#### Why Zero Everywhere Except at Vertices
-
-The **Gauss-Bonnet theorem** applied to origami: for a closed region of paper containing a vertex, the integral of Gaussian curvature over the region equals the **angular defect** at the vertex:
-
-```
-integral(K dA) = 2*pi - sum(sector_angles_at_vertex)
-```
-
-For a flat-foldable vertex (Kawasaki-Justin satisfied), the sector angles sum to 2*pi, so the angular defect is zero. The vertex has zero **discrete Gaussian curvature** -- consistent with the paper being developable.
-
-For a **non-flat** origami vertex (like a partially folded vertex), the angular defect can be nonzero. This is equivalent to the vertex having concentrated Gaussian curvature, which means the paper near that vertex is behaving like a **cone** (positive defect) or a **saddle** (negative defect). However, this is only possible if the paper is being stretched or compressed at the molecular level -- real paper resists this strongly.
-
-**Practical implication for simulation**: The faces of an origami model must remain **developable** (zero Gaussian curvature) at all times. Any deformation that introduces Gaussian curvature into a face is physically unrealistic unless the paper is being plastically deformed. This is why faces in rigid origami are modeled as perfectly rigid panels with zero curvature.
-
-#### Connection to Rigid Origami
-
-In rigid origami, faces must remain planar throughout folding. If triangulated faces are used, planarity is automatic (any three points define a plane). For non-triangular faces, enforcing planarity is a constraint that must be explicitly maintained, and violation of it implies non-zero Gaussian curvature -- physically forbidden for stiff materials.
-
----
-
-### 1.7 Rigid Origami
-
-#### Definition
-
-**Rigid origami** is origami where:
-- Each face of the crease pattern remains **perfectly rigid** (planar, undeformed) during folding.
-- All deformation is concentrated at the crease lines, which act as **revolute joints** (hinges).
-- The folding is a **continuous motion** from the flat state to the folded state.
-
-This is in contrast to "regular" origami where paper can bend, curve, and deform continuously.
-
-#### What Makes It Different
-
-| Property | Regular Origami | Rigid Origami |
-|----------|----------------|---------------|
-| Faces | Can bend and curve | Must remain perfectly planar |
-| Deformation | Distributed across paper | Concentrated at creases only |
-| Degrees of freedom | Very high (infinite-dimensional) | Finite (one fold angle per crease) |
-| Model | Continuous thin shell | Linkage mechanism |
-| Kinematic analogy | Flexible sheet | System of rigid panels + hinges |
-| Gaussian curvature of faces | Can be nonzero transiently | Always zero |
-
-#### Kinematic Model
-
-A rigid origami vertex with n creases is equivalent to a **spherical linkage** with n links and n revolute joints. The fold angles (rho_1, ..., rho_n) are the joint variables. The constraint is that the linkage must close:
-
-```
-R_1(rho_1) * R_2(rho_2) * ... * R_n(rho_n) = I   (identity matrix)
-```
-
-where R_i(rho_i) is the rotation matrix for the i-th crease by fold angle rho_i around the crease line direction.
-
-For a **degree-4 vertex** (4 creases, the most common in rigid origami patterns like Miura-ori), the spherical linkage has **1 degree of freedom** (generically). This means specifying one fold angle determines all others -- the entire pattern folds as a 1-DOF mechanism.
-
-#### Key Rigid Origami Patterns
-
-- **Miura-ori**: Degree-4 vertices, 1-DOF, negative Poisson's ratio, widely used in engineering.
-- **Yoshizawa pattern**: Various fold angles possible.
-- **Waterbomb base**: Degree-6 vertices, more complex kinematics.
-- **Kresling pattern**: Cylindrical, bistable, used in deployable structures.
-
-#### Rigid Foldability Conditions
-
-Not all crease patterns are rigidly foldable. Conditions:
-1. **Kawasaki-Justin** must hold at every vertex (necessary for flat-foldability).
-2. The **loop closure equations** (spherical linkage constraints) must have continuous solutions from the flat state.
-3. **Compatibility**: At each interior vertex, the fold angles of shared creases between adjacent vertices must agree.
-
-For degree-4 vertices, explicit analytical conditions exist. For higher-degree vertices and multi-vertex patterns, numerical methods are required.
-
----
-
-### 1.8 Single-Vertex Origami
-
-This is the **simplest and fully understood** case of origami mathematics.
-
-#### Configuration Space
-
-For a single vertex with 2n creases satisfying Kawasaki-Justin, the **configuration space** (set of valid folded states) is fully characterized:
-
-- **MV assignments**: The number of valid MV assignments can be computed by recursive formulas (Hull). For n creases with sector angles alpha_1, ..., alpha_{2n}, the count C(alpha_0, ..., alpha_{2n-1}) follows a recursion based on identifying the smallest sector and "crimping" it.
-
-- **Layer orderings**: For each valid MV assignment, the layer ordering is essentially unique (determined by the accordion fold construction from the sufficiency proof of Kawasaki-Justin).
-
-#### Complete Algorithm (Polynomial Time)
-
-```
-Input: sector angles alpha_1, ..., alpha_{2n}
-1. Check Kawasaki-Justin: alternating sum = 0?
-   If no -> not flat-foldable.
-2. For each candidate MV assignment satisfying Maekawa (|M-V| = 2):
-   a. Check Big-Little-Big constraints.
-   b. Simulate crimp folding to verify no self-intersection.
-3. Output all valid (MV assignment, layer ordering) pairs.
-```
-
-This is solvable in **polynomial time** because:
-- Maekawa limits the number of mountain folds to n+1 or n-1 (binomial choices).
-- BLB dramatically prunes the search.
-- The crimp algorithm processes creases sequentially.
-
-#### Rigid Single-Vertex
-
-For rigid origami, a single degree-2n vertex is a spherical n-bar linkage. Its configuration space is a smooth manifold whose dimension and topology depend on the sector angles. For degree-4 (the generic case), it is generically a 1-dimensional manifold (a curve) -- a single parameter (fold angle of one crease) determines the rest.
-
----
-
-### 1.9 Multi-Vertex Origami: Where Complexity Explodes
-
-#### The Fundamental Difficulty
-
-Multi-vertex origami is qualitatively harder than single-vertex because:
-
-1. **Global consistency**: Creases shared between vertices must have consistent fold angles and MV assignments at both endpoints.
-2. **Layer ordering becomes global**: The layer ordering must be consistent across the entire pattern, not just locally at each vertex.
-3. **Rigid compatibility**: In rigid origami, the fold angles at one vertex constrain fold angles at neighboring vertices, creating a coupled system of nonlinear equations.
-
-#### Complexity Results (Multi-Vertex)
-
-| Problem | Complexity |
-|---------|-----------|
-| Local flat-foldability (Kawasaki at each vertex) | Polynomial (check each vertex independently) |
-| MV assignment for flat fold | **NP-complete** (Bern-Hayes 1996) |
-| Layer ordering for flat fold | **NP-complete** (Bern-Hayes 1996) |
-| Flat foldability (combined) | **NP-complete** |
-| Rigid foldability (continuous motion) | **NP-complete** for arbitrary crease subsets |
-| Reconfiguration between flat states | **PSPACE-complete** |
-| Counting flat-folded states | **#P-complete** |
-| Self-similar infinite patterns | **Undecidable** |
-| Flat origami with optional creases | **Turing complete** (can simulate Rule 110) |
-
-#### Why Multi-Vertex is Hard: Intuition
-
-Each vertex locally constrains its creases, but these constraints propagate through the pattern. A pleat at one vertex forces a layer ordering that may conflict with a pleat at a distant vertex. The interconnection structure creates a constraint satisfaction problem equivalent to SAT.
-
-**Bern-Hayes gadgets**:
-- **Wire gadget**: A pleat (two parallel creases) propagates a binary signal (which layer is on top).
-- **NOT gadget**: A single crease crossing a pleat flips the signal.
-- **NAE clause gadget**: Three pleats meeting at a region that can fold flat iff the signals are not all equal.
-- These gadgets encode NAE-3SAT, proving NP-completeness.
-
-#### Practical Approaches for Simulation
-
-Despite NP-completeness in the worst case, many practical origami patterns are tractable:
-
-1. **Low ply**: Most artistic origami has bounded ply (< 10 layers). FPT algorithms with ply as parameter are efficient.
-2. **Tree-like structure**: Many patterns have cell adjacency graphs with low treewidth, enabling dynamic programming.
-3. **Constraint propagation**: Start from boundary conditions and propagate MV/layer constraints. Many patterns resolve without backtracking.
-4. **Physics-based simulation**: Avoid the combinatorial problem entirely by simulating the continuous folding process with forces and constraints.
-
----
-
-## 2. Mechanics / Physics of Folding
-
-### 2.1 What Physically Happens When Paper Is Folded
-
-Paper is a composite material: a network of **cellulose fibers** (typically 1-3 mm long, 20-40 micrometers in diameter) bonded together by hydrogen bonds, with pores filled with air, fillers (clay, calcium carbonate), and sizing agents.
-
-#### Microscale Mechanics of a Fold
-
-When paper is folded:
-
-1. **Elastic bending** (initial phase): The outer fibers are stretched in tension, inner fibers compressed. At the fold line, the paper experiences its maximum curvature. The bending stress follows approximately:
-   ```
-   sigma = E * y / R
-   ```
-   where E = Young's modulus, y = distance from neutral axis, R = radius of curvature.
-
-2. **Fiber rearrangement**: At moderate fold sharpness, fibers begin to slide relative to each other, breaking hydrogen bonds between fibers. This is an irreversible microstructural change.
-
-3. **Plastic deformation** (sharp fold): For a tight crease, the inner fibers buckle and permanently deform. The outer fibers may fracture or debond. The cellulose microfibrils within individual fibers undergo plastic kinking. The fold line experiences **localized plastic failure**.
-
-4. **Residual stress**: After unfolding, the permanently deformed fibers create internal stresses that give the paper a "memory" of the fold -- it preferentially returns to the folded state. This is the physical basis of crease memory.
-
-#### Key Parameters
-
-| Parameter | Typical Value (copy paper) |
-|-----------|---------------------------|
-| Thickness | 80-120 micrometers |
-| Young's modulus (MD) | 3-6 GPa |
-| Young's modulus (CD) | 1-3 GPa |
-| Bending stiffness | 5-15 mN*m |
-| Tensile strength | 20-80 MPa |
-| Strain at break | 1-5% |
-
-MD = machine direction, CD = cross direction. Paper is anisotropic due to preferential fiber alignment during manufacturing.
-
----
-
-### 2.2 Stress Concentration at Fold Lines
-
-#### The Problem
-
-A crease line is a **stress concentrator**. The radius of curvature at a sharp fold approaches zero, which would imply infinite stress according to linear elasticity:
-
-```
-sigma_max = E * t / (2R)
-```
-
-where t = paper thickness, R = radius of curvature at the fold.
-
-In reality, three mechanisms prevent infinite stress:
-1. **Finite fold radius**: Even a "sharp" fold has a radius of curvature of ~0.1-0.5 mm.
-2. **Plastic yielding**: The material yields before reaching the elastic stress limit.
-3. **Fiber debonding**: The network structure allows local failures that redistribute stress.
-
-#### Modeling Approach
-
-For simulation purposes, the stress concentration at a fold is typically not modeled explicitly. Instead:
-
-1. **Ideal crease model**: The crease is a geometric line of zero width. All deformation is captured by the fold angle. The crease has a **rest angle** (the angle it naturally tends toward) and a **torsional stiffness** (resistance to deviating from the rest angle).
-
-2. **Compliant crease model**: The crease has a finite width w. Within this width, the paper has reduced stiffness (due to plastic damage). The crease zone is modeled as a thin strip with modified material properties.
-
-3. **Damage model**: The crease stiffness changes as a function of folding history. Repeated folding reduces the rest angle toward the fully-folded state and may reduce stiffness.
-
----
-
-### 2.3 Elastic Energy Stored in a Fold
-
-The elastic energy of an origami structure comes from three sources:
-
-#### 1. Crease Folding Energy
-
-Each crease acts as a **torsional spring**. The energy stored in a crease of length L with fold angle rho (deviation from rest angle rho_0):
-
-```
-E_crease = (1/2) * kappa * L * (rho - rho_0)^2
-```
-
-where kappa is the torsional stiffness per unit length (units: N*m/m = N).
-
-For a crease at its rest angle, E_crease = 0. Energy increases quadratically as the fold angle deviates from rest.
-
-#### 2. Panel Bending Energy
-
-If panels are not perfectly rigid, they can bend. The bending energy density of a thin plate is:
-
-```
-e_bend = (B/2) * (kappa_1^2 + kappa_2^2 + 2*nu*kappa_1*kappa_2)
-```
-
-where B = Et^3/(12(1-nu^2)) is the flexural rigidity, kappa_1 and kappa_2 are principal curvatures, and nu is Poisson's ratio.
-
-For a developable (zero Gaussian curvature) deformation, one principal curvature is zero, simplifying to:
-
-```
-e_bend = (B/2) * kappa^2
-```
-
-#### 3. Stretching Energy
-
-If panels are stretched or compressed in-plane:
-
-```
-e_stretch = (Et/2) * (epsilon_xx^2 + epsilon_yy^2 + 2*nu*epsilon_xx*epsilon_yy + 2*(1-nu)*epsilon_xy^2) / (1 - nu^2)
-```
-
-In rigid origami, stretching energy is zero by assumption. In compliant origami, it is typically much smaller than bending energy for thin sheets.
-
-#### The Key Ratio: Origami Length Scale
-
-The competition between panel bending and crease folding defines a characteristic length:
-
-```
-L* = B / kappa
-```
-
-where B = flexural rigidity of the panel, kappa = torsional stiffness of the crease per unit length.
-
-- If panel size >> L*: the creases are relatively soft, and the structure behaves like **rigid origami** (panels stay flat, all deformation at creases).
-- If panel size << L*: the creases are relatively stiff, and the panels bend significantly -- the structure behaves as a **flexible shell**.
-
-For most paper origami, panel size >> L*, so rigid origami is a good approximation.
-
----
-
-### 2.4 Bending Stiffness vs. Fold Angle Relationship
-
-The moment-angle relationship of a crease is approximately **linear** for small deviations from the rest angle:
-
-```
-M = kappa * L * (rho - rho_0)
-```
-
-where M is the restoring moment, L is crease length, rho is current fold angle, rho_0 is rest angle.
-
-**Nonlinear effects at large deviations:**
-
-1. **Geometric nonlinearity**: For large fold angles, the effective lever arm changes, and the relationship between moment and angle becomes nonlinear.
-2. **Material nonlinearity**: At large deformations, the crease material (damaged paper fibers) exhibits nonlinear stress-strain behavior.
-3. **Contact**: When the fold approaches 0 degrees (fully folded) or 360 degrees, the paper layers contact each other, introducing a hard constraint.
-
-**For simulation**, a piecewise model is often used:
-
-```
-M(rho) = kappa * L * (rho - rho_0)                    for |rho - rho_0| < rho_threshold
-M(rho) = kappa * L * rho_threshold * sign(rho - rho_0)  for |rho - rho_0| >= rho_threshold
-```
-
-More sophisticated models use exponential or polynomial stiffening near full closure.
-
-**Accuracy Note**: The linear spring model is suggested for use when the folding angle deviation is less than approximately 45 degrees from rest. Beyond this range, nonlinear corrections become significant.
-
----
-
-### 2.5 Crease Mechanics: Permanent Effects
-
-A crease permanently alters paper properties:
-
-#### Rest Angle Shift (Plasticity)
-
-Before folding: rest angle = pi (flat, 180 degrees).
-After folding to angle rho_fold and releasing:
-
-```
-rho_0_new = pi - alpha * (pi - rho_fold)
-```
-
-where alpha is a plasticity parameter (0 = no plastic deformation, 1 = perfect memory of the fold). For sharp folds in standard paper, alpha is approximately 0.7-0.9.
-
-The rest angle shifts toward the folded state. This is why folded paper stays folded -- the physical basis of origami.
-
-#### Stiffness Reduction
-
-The torsional stiffness of a crease decreases with repeated folding:
-
-```
-kappa_n = kappa_0 * (1 - beta * log(n + 1))
-```
-
-where kappa_n is stiffness after n fold cycles, kappa_0 is initial stiffness, and beta is a material-dependent degradation parameter.
-
-This models the progressive breaking of fiber bonds with repeated folding.
-
-#### Anisotropy
-
-A crease introduces local anisotropy: the paper is much weaker in bending across the crease line than along it. In-plane stiffness across the crease is also reduced.
-
----
-
-### 2.6 Thickness Accommodation
-
-#### The Problem
-
-Mathematical origami assumes zero-thickness paper. Real materials have thickness t > 0, which creates problems:
-
-1. **Geometric interference**: When paper folds, the inner layers have shorter paths than outer layers. For a fold angle theta, the path length difference is approximately t * theta.
-2. **Accumulation**: In multi-layer folds, thickness accumulates, causing significant geometric errors.
-3. **Strain**: Thick materials experience significant bending strain at folds: epsilon = t/(2R).
-4. **Kinematics**: Thick panels cannot fold the same way as zero-thickness paper -- the kinematics change.
-
-#### Thickness Accommodation Techniques
-
-**1. Offset Panel Technique:**
-Panels are offset from the mathematical (zero-thickness) fold surface by t/2. Each panel sits on one side of the mathematical surface. Creases are placed at the edges of offset panels, creating gaps.
-
-- Preserves kinematics of the zero-thickness pattern.
-- Introduces gaps between panels at valley folds.
-- Simple to implement but creates asymmetry.
-
-**2. Tapered Panel Technique:**
-Panels are tapered (thinned) near crease lines, maintaining the mathematical surface at the center of each panel while allowing folding at the edges.
-
-- Preserves the same kinematic folding motion as the zero-thickness system.
-- Requires material removal.
-- Suitable for manufacturing.
-
-**3. Double Crease Technique:**
-A single mathematical crease is replaced by two parallel creases separated by a distance proportional to thickness. The strip between them accommodates the volume.
-
-- Simple and effective.
-- Changes the crease pattern geometry slightly.
-- Common in engineering applications.
-
-**4. Membrane Hinge Technique:**
-Thick panels are connected by thin flexible membranes (living hinges). The membrane serves as the hinge while the panels remain rigid and thick.
-
-- Clean separation of rigid panels and flexible hinges.
-- Widely used in manufactured products (e.g., plastic containers with living hinges).
-- The membrane can be different material from the panels.
-
-**5. Rolling Contact Technique:**
-Panels are connected by rolling contact elements that accommodate thickness through synchronized rolling motion.
-
-- Achieves true rigid foldability with thick panels.
-- Complex mechanism but kinematically exact.
-
----
-
-### 2.7 Spring-Hinge Model
-
-The **spring-hinge model** is the simplest mechanical model of origami:
-
-#### Model Description
-
-- Each **face** of the crease pattern is a rigid panel.
-- Each **crease** is a **torsional spring** (revolute joint with spring resistance).
-- The spring has:
-  - A **rest angle** rho_0 (the angle the crease naturally tends toward).
-  - A **torsional stiffness** kappa (resistance to deviation from rest angle).
-  - A **damping coefficient** c (energy dissipation during dynamic motion).
-
-#### Equations of Motion
-
-For a dynamic simulation:
-
-```
-I * d^2(rho)/dt^2 + c * d(rho)/dt + kappa * (rho - rho_0) = tau_external
-```
-
-where I is the moment of inertia, c is damping, kappa is torsional stiffness, and tau_external is any externally applied torque.
-
-For quasi-static simulation (slow folding), inertia is negligible:
-
-```
-c * d(rho)/dt + kappa * (rho - rho_0) = tau_external
-```
-
-#### Advantages
-
-- Simple and computationally efficient.
-- Captures the essential 1-DOF-per-crease kinematics.
-- Easy to implement.
-
-#### Limitations
-
-- Cannot capture face bending (faces are perfectly rigid).
-- Cannot capture stretching or shearing.
-- Crease stiffness is a single scalar (no width, no distributed behavior).
-- Poor accuracy for compliant origami where face bending is significant.
-
----
-
-### 2.8 Bar-and-Hinge Model (Ghassaei's Approach)
-
-The **bar-and-hinge model** is a more sophisticated mechanical model that captures three types of deformation while remaining computationally efficient.
-
-#### Model Description
-
-Each face of the crease pattern is triangulated (if not already triangular). The model then consists of:
-
-1. **Bars (edges)**: Each edge of the triangulated mesh is a bar with **axial stiffness**. Bars resist stretching and compression. This prevents the faces from stretching or shearing.
-
-2. **Fold hinges (at creases)**: Each crease line has a **torsional spring** connecting the two adjacent faces. This captures the crease folding behavior with a target fold angle and stiffness.
-
-3. **Facet hinges (within faces)**: Each pair of triangles sharing a non-crease edge has a **torsional spring** with high stiffness and a rest angle of pi (flat). This penalizes face bending, keeping faces approximately flat while allowing small deformations.
-
-#### Three Deformation Modes
-
-| Mode | Element | Stiffness | Physical meaning |
-|------|---------|-----------|-----------------|
-| Stretching/shearing | Bars | Axial stiffness (Et) | In-plane deformation of faces |
-| Face bending | Facet hinges | Flexural rigidity (B ~ Et^3) | Out-of-plane bending of faces |
-| Crease folding | Fold hinges | Torsional stiffness (kappa) | Folding at prescribed crease lines |
-
-#### Energy Formulation
-
-Total energy:
-
-```
-E_total = E_bar + E_facet + E_fold
-
-E_bar   = sum_bars   (1/2) * k_axial * (L - L_0)^2
-E_facet = sum_facets (1/2) * k_facet * l * (theta - pi)^2
-E_fold  = sum_folds  (1/2) * k_fold  * l * (rho - rho_target)^2
-```
-
-where L, L_0 = current and rest length of bars; theta = dihedral angle at facet edges; rho, rho_target = current and target fold angle at creases; l = edge length; and k values are stiffness parameters.
-
-#### Stiffness Parameters
-
-From Schenk and Guest's formulation:
-
-```
-k_axial = E * t * w / L_0          (bar axial stiffness)
-k_facet = E * t^3 / (12 * (1-nu^2))  (per unit length, facet bending)
-k_fold  = kappa                     (per unit length, crease torsion)
-```
-
-where E = Young's modulus, t = thickness, w = tributary width, nu = Poisson's ratio.
-
-#### Compliant Crease Extension
-
-For creases with finite width w_c, Ghassaei et al. extended the model:
-- The crease zone is represented by **7 nodes, 12 bars, and 8 rotational springs**.
-- Two rows of rotational springs (not one) capture the distributed curvature in the crease zone.
-- Additional bars capture torsional and extensional deformation within the crease.
-
-This extension is critical for predicting **bistability** and **multistability** in origami structures, which the simplified model misses.
-
-#### Solution Method
-
-The bar-and-hinge model is solved using **nonlinear static analysis**:
-
-1. Define target fold angles (rho_target) as a function of a folding parameter t in [0, 1].
-2. Increment t in small steps.
-3. At each step, minimize E_total using Newton-Raphson iteration:
-   - Compute forces: F_i = -partial(E_total)/partial(x_i)
-   - Compute stiffness matrix: K_ij = partial^2(E_total)/partial(x_i)partial(x_j)
-   - Update positions: delta_x = K^{-1} * F
-4. Check convergence.
-
-#### GPU-Accelerated Dynamic Variant (Origami Simulator)
-
-Amanda Ghassaei's browser-based Origami Simulator uses a dynamic variant:
-- All constraints (bars, facet hinges, fold hinges) generate forces.
-- Positions are updated via numerical integration (Euler or Verlet).
-- **Verlet integration**: x_{n+1} = 2*x_n - x_{n-1} + F*dt^2/m
-- GPU fragment shaders compute forces in parallel for fast performance.
-- Damping prevents oscillation; system converges to static equilibrium.
-- All creases fold simultaneously (not sequentially).
-
----
-
-## 3. Computational Origami Theory
-
-### 3.1 Tractability Landscape
-
-| Problem | Complexity | Notes |
-|---------|-----------|-------|
-| Single-vertex flat foldability (Kawasaki check) | **O(n)** | Sum alternating angles |
-| Single-vertex MV assignment | **Polynomial** | Recursive crimp algorithm |
-| Single-vertex layer ordering | **Polynomial** | Determined by MV assignment |
-| Multi-vertex local flat foldability | **Polynomial** | Check Kawasaki at each vertex independently |
-| Multi-vertex MV assignment | **NP-complete** | Bern-Hayes 1996 |
-| Multi-vertex layer ordering | **NP-complete** | Bern-Hayes 1996 |
-| Multi-vertex flat foldability (combined) | **NP-complete** | MV + layer ordering together |
-| Flat foldability (bounded ply + bounded treewidth) | **FPT**: O((p!)^{O(w)} n^2) | Tractable for simple patterns |
-| Map folding (1xn strip) | **O(n^2)** | |
-| Map folding (2xn grid) | **Polynomial** | |
-| Map folding (general mxn) | **Open** | Conjectured NP-hard |
-| Rigid foldability (continuous motion, all creases) | **Weakly NP-complete** | |
-| Rigid foldability (arbitrary crease subsets) | **Strongly NP-complete** | |
-| Reconfiguration between flat states | **PSPACE-complete** | |
-| Counting flat-folded states | **#P-complete** | |
-| Flat origami with optional creases | **Turing complete** | Simulates Rule 110 cellular automaton |
-| Self-similar infinite pattern foldability | **Undecidable** | coRE-complete |
-
-### 3.2 Single-Vertex Flat Foldability: Polynomial Time
-
-**Algorithm (Hull's Crimp Algorithm):**
-
-```
-Input: Sector angles alpha_1, ..., alpha_{2n} at a vertex.
-Output: All valid (MV assignment, layer ordering) pairs, or "not flat-foldable."
-
-1. Check Kawasaki-Justin: sum of odd-indexed angles = pi?
-   If not, return "not flat-foldable."
-
-2. Find the smallest sector angle alpha_min.
-   (If tie, choose any.)
-
-3. The two creases bounding alpha_min must have OPPOSITE MV parity
-   (Big-Little-Big lemma).
-
-4. "Crimp" the smallest sector: merge it with the adjacent sectors.
-   The new sector has angle = alpha_{i-1} - alpha_i + alpha_{i+1}
-   (which equals the original angle alpha_{i-1} or alpha_{i+1} minus the "crimped" difference).
-
-5. This reduces the vertex to a (2n-2)-crease vertex.
-   Recurse.
-
-6. Base case: 2 creases, angles pi, pi. Trivially foldable.
-```
-
-**Time complexity:** O(n^2) in the straightforward implementation, O(n log n) with priority queues.
-
-**Counting valid MV assignments:** Hull developed recursive formulas C(alpha_0,...,alpha_{2n-1}) for the number of valid MV assignments, based on the crimp structure. The count depends on angle multiplicities and can range from 2 (minimum, for generic angles) to 2^{n-1} (maximum, for equal angles).
-
-### 3.3 Multi-Vertex Flat Foldability: NP-Complete
-
-**The Bern-Hayes Construction (1996):**
-
-The reduction is from **NAE-3SAT** (Not-All-Equal 3-Satisfiability):
-- Given a Boolean formula in CNF where each clause has 3 literals.
-- NAE-3SAT asks: is there an assignment such that no clause has all three literals the same value?
-
-**Gadgets:**
-
-1. **Wire (pleat)**: Two parallel creases forming a pleat. Binary state = which layer goes on top. This encodes a Boolean variable.
-
-2. **Signal propagation**: The pleat's layer ordering propagates along the crease lines, maintaining the binary state.
-
-3. **Turn/crossover**: Pleats can turn corners and cross over each other using specific crease configurations.
-
-4. **NAE clause gadget**: Three pleats meeting at a junction. The junction can fold flat if and only if the three incoming layer orderings are NOT all equal. This directly encodes an NAE-3SAT clause.
-
-5. **Assembly**: Given an NAE-3SAT formula, construct a crease pattern with one pleat per variable and one clause gadget per clause, connected by wire gadgets. The crease pattern is flat-foldable iff the NAE-3SAT formula is satisfiable.
-
-Since NAE-3SAT is NP-complete, and the reduction is polynomial, multi-vertex flat foldability is NP-complete.
-
-**Implications for simulation**: There is no known polynomial-time algorithm for deciding flat-foldability of general crease patterns (unless P = NP). Practical simulation must use heuristics, constraint propagation, or physics-based approaches.
-
-### 3.4 Rigid Foldability: How to Check
-
-#### Degree-4 Vertices (Analytical)
-
-For a degree-4 vertex with sector angles (alpha, beta, gamma, delta) where alpha + beta + gamma + delta = 2*pi and Kawasaki-Justin holds (alpha + gamma = beta + delta = pi):
-
-The fold angles (rho_1, rho_2, rho_3, rho_4) are related by analytical expressions. For a Miura-ori type vertex:
-
-```
-tan(rho_2/2) = -(cos((alpha-beta)/2) / cos((alpha+beta)/2)) * tan(rho_1/2)
-tan(rho_3/2) = -(cos((alpha+delta)/2) / cos((alpha-delta)/2)) * tan(rho_1/2)
-tan(rho_4/2) = -(cos((alpha-beta)/2) / cos((alpha+beta)/2)) * tan(rho_3/2)
-```
-
-These give explicit fold-angle relationships, showing the 1-DOF nature.
-
-#### General Vertices (Numerical)
-
-For a vertex of degree n, the rigid foldability condition is the **loop closure equation** of the equivalent spherical linkage:
-
-```
-R(e_1, rho_1) * R(e_2, rho_2) * ... * R(e_n, rho_n) = I
-```
-
-where R(e_i, rho_i) is rotation by angle rho_i around axis e_i (the crease direction).
-
-This is a system of nonlinear equations in the fold angles. The number of degrees of freedom is n - 3 (for a spherical linkage with n links).
-
-**Solution methods:**
-1. **Newton-Raphson**: Iteratively solve the constraint equations starting from the flat state.
-2. **Continuation methods**: Trace the solution curve as a parameter (e.g., one fold angle) varies.
-3. **Dual quaternion method**: Model rotations using dual quaternions for improved numerical stability. The QRS method decomposes fold angles into quaternion representations for multi-vertex systems.
-
-#### Multi-Vertex Rigid Foldability
-
-For a pattern with multiple vertices:
-1. Each vertex imposes loop closure constraints.
-2. Shared creases between vertices must have the same fold angle.
-3. The combined system of constraints defines the configuration space.
-
-**Heuristic algorithms** (e.g., by Tachi) adjust vertex positions of initially non-rigid patterns to make them rigidly foldable. The configuration is represented by fold angles, and the folding trajectory is computed by projecting the desired motion onto the constraint manifold.
-
-### 3.5 Self-Intersection Detection
-
-Self-intersection detection is critical for validating origami configurations. Two types:
-
-#### 1. Discrete Self-Intersection (Flat Folds)
-
-For flat-folded states, self-intersection is detected by checking **layer ordering consistency**:
-- **Taco-taco constraint**: Two crossing creases create a "taco-taco" configuration. The layer ordering of the four resulting regions must be consistent (no interleaving that requires paper to pass through itself).
-- **Taco-tortilla constraint**: A crease adjacent to a non-creased region must not have the flat region blocking its closure.
-- **Transitivity**: If A > B and B > C in layer order, then A > C.
-
-Jason Ku's algorithm:
-1. Compute the overlap graph (which facets overlap in the folded state).
-2. For each pair of overlapping facets, determine ordering constraints from MV assignments at shared boundaries.
-3. Propagate implications via transitivity.
-4. Check for contradictions (cycles in the ordering).
-
-#### 2. Continuous Self-Intersection (During Folding)
-
-During the folding motion, faces may collide transiently even if the final state is valid.
-
-**Approaches:**
-- **Bounding volume hierarchies (BVH)**: Enclose each face in a bounding box. Test for overlap using a BVH tree. If bounding boxes overlap, test the actual triangles for intersection.
-- **Swept volume**: Track the volume swept by each face during a folding step. Check for overlaps between swept volumes.
-- **Incremental testing**: At each time step, check all face pairs for geometric intersection using triangle-triangle intersection tests (Moller's algorithm or similar).
-
-**Computational cost**: O(n^2) per time step for brute-force pairwise testing, O(n log n) with spatial acceleration structures.
-
-### 3.6 Fold-and-Cut Theorem
-
-#### Statement
-
-**Fold-and-Cut Theorem (Demaine, Demaine, Lubiw, 1998):** Every pattern of straight-line cuts in a flat piece of paper (i.e., any planar straight-line graph drawn on the paper) can be achieved by folding the paper flat and making a single complete straight cut.
-
-In other words: any shape (or collection of shapes) bounded by straight edges can be cut from a single sheet of paper with one straight cut, provided the paper is first folded appropriately.
-
-#### Two Proof Methods
-
-**1. Straight Skeleton Method (Demaine, Demaine, Lubiw):**
-- Compute the **straight skeleton** of the planar graph (a medial-axis-like structure formed by shrinking the faces of the graph at unit speed).
-- The straight skeleton edges become crease lines.
-- Add perpendicular creases to make the pattern flat-foldable.
-- The resulting crease pattern, when folded, aligns all cut edges along a single line, enabling the single cut.
-
-**2. Disk Packing Method (Bern, Demaine, Eppstein, Hayes):**
-- Pack disks into the faces of the graph, tangent to each edge.
-- The **Apollonius problem** (finding circles tangent to three given circles) is used to fill gaps.
-- The disk packing defines a decomposition into **molecules** (regions between disks).
-- **Universal molecules** are constructed for each region, providing crease patterns that fold each molecule flat.
-- The assembly of all molecules gives the complete crease pattern.
-
-#### Universal Molecule
-
-A **universal molecule** is a crease pattern for a convex polygonal region with prescribed fold directions on its boundary such that:
-1. It folds flat.
-2. All boundary edges align along a single line after folding.
-
-The universal molecule construction uses:
-- The **perpendicular folds** from each boundary edge.
-- **Rabbit ear** triangulations for triangular regions.
-- **Recursive decomposition** for higher polygons.
-
-This is a key primitive for computational origami design tools.
-
-### 3.7 Universal Molecule Approach
-
-The universal molecule approach is the computational backbone of the fold-and-cut construction and is more broadly used in computational origami design.
-
-**Algorithm:**
-
-1. **Input**: A planar straight-line graph G (the desired crease/cut pattern).
-2. **Compute the straight skeleton** of G. This produces a tree-like structure inside each face.
-3. **Decompose** the pattern into convex regions using the skeleton.
-4. **For each convex region**, construct a universal molecule:
-   a. Assign fold directions (M/V) on the boundary based on the desired folding.
-   b. Add internal creases: perpendicular folds from vertices, diagonal folds for triangulation.
-   c. Verify flat-foldability of the molecule.
-5. **Assemble** all molecules. The internal creases of adjacent molecules must be compatible.
-6. **Output**: Complete crease pattern with MV assignment.
-
-**Implementation challenges:**
-- The straight skeleton can have degenerate cases (vertices of degree > 3).
-- Disk packing requires solving Apollonius problems (circle tangent to three circles), which has up to 8 solutions per instance.
-- Numerical precision is critical: small errors in skeleton computation propagate to invalid crease patterns.
-- Software tools like **TreeMaker** (Robert Lang) and **ORIPA** implement variants of this approach.
-
----
-
-## 4. Engineering Metrics
-
-### 4.1 Deployment Ratio
-
-#### Definition
-
-The **deployment ratio** (or **packaging ratio**) quantifies how much an origami structure can expand from its folded (stowed) state to its deployed state:
-
-```
-DR = L_deployed / L_stowed
-```
-
-where L is a characteristic dimension (length, area, or volume, depending on application).
-
-**Variants:**
-
-- **Linear deployment ratio**: ratio of deployed length to stowed length (1D).
-- **Areal deployment ratio**: ratio of deployed area to stowed area (2D): DR_area = A_deployed / A_stowed.
-- **Volumetric deployment ratio**: ratio of deployed volume to stowed volume (3D).
-
-#### How It's Measured in Real Engineering
-
-1. **Satellite solar arrays**: Deployment ratio measured as deployed array area divided by launch fairing cross-section area. Typical: 10:1 to 50:1 for advanced designs.
-2. **Antenna reflectors**: Ratio of deployed aperture diameter to stowed package diameter. Typical: 5:1 to 20:1.
-3. **Emergency shelters**: Ratio of floor area deployed to storage volume. Typical: 20:1 to 100:1.
-
-#### Theoretical Limits
-
-For a Miura-ori pattern with m x n cells:
-```
-DR_linear ~ m * sin(theta)   (in one direction)
-DR_area ~ m * n * sin(theta)  (area ratio)
-```
-where theta is the fold angle parameter. As theta approaches 0, the deployment ratio increases, but the stowed package thickness also increases due to layer accumulation.
-
-**Practical limit**: Deployment ratio is bounded by the number of layers (ply) and the material thickness. For n layers of thickness t, the minimum stowed dimension is ~ n*t.
-
-### 4.2 Structural Stiffness of Folded State
-
-Origami structures exhibit **tunable stiffness** that depends on the fold state:
-
-#### Stiffness Modulation
-
-- **Flat (unfolded) state**: Maximum in-plane stiffness, minimum out-of-plane stiffness (it is just a flat sheet).
-- **Partially folded**: Stiffness varies continuously with fold angle. The structure gains out-of-plane stiffness (3D geometry provides structural depth) while losing some in-plane stiffness.
-- **Fully folded (compact)**: Complex stiffness behavior depending on pattern; often the stiffest configuration due to maximum layer stacking.
-
-#### Miura-ori Stiffness
-
-The effective in-plane stiffness of a Miura-ori pattern scales as:
-
-```
-K_x ~ E*t * (cos(theta)^2 / sin(theta))   (along corrugation direction)
-K_y ~ E*t * sin(theta)                      (perpendicular to corrugation)
-```
-
-where theta is the fold angle. Note that K_x diverges as the fold closes (theta -> 0), while K_y vanishes -- this is the auxetic behavior.
-
-The **out-of-plane bending stiffness** scales approximately as:
-
-```
-B_eff ~ E*t * h^2
-```
-
-where h is the effective structural depth (related to fold amplitude).
-
-#### Self-Locking
-
-Some origami patterns exhibit **self-locking**: at certain fold angles, geometric constraints prevent further motion without significant force. The structure transitions from a mechanism (zero-stiffness mode) to a structure (finite stiffness in all directions).
-
-### 4.3 Fatigue at Fold Lines
-
-#### The Problem
-
-Repeated folding and unfolding causes progressive damage at crease lines:
-
-1. **Cycle 1**: Initial plastic deformation creates the crease. Fiber bonds break, fibers permanently deform.
-2. **Cycles 2-10**: Crease softens, rest angle shifts further. The crease becomes "trained."
-3. **Cycles 10-100**: Gradual stiffness degradation. Fiber fracture accumulates.
-4. **Cycles 100-1000**: Significant weakening. Risk of crack propagation from the crease into the faces.
-5. **Cycles 1000+**: Material failure. The paper tears along the fold line.
-
-#### Fatigue Life
-
-The fatigue life depends on:
-- **Material**: Paper (100-1000 cycles), polymers (10^4-10^6), metals (10^3-10^5), shape memory alloys (10^6+).
-- **Fold angle amplitude**: Larger angle changes = faster fatigue.
-- **Fold radius**: Sharper folds = higher strain = faster fatigue.
-- **Loading rate**: Faster folding = more heat generation = accelerated degradation.
-
-#### Modeling Fatigue
-
-For simulation, a simple fatigue model:
-
-```
-kappa_N = kappa_0 * (1 - D(N))
-D(N) = (N / N_f)^p
-
-where:
-  kappa_N = stiffness after N cycles
-  kappa_0 = initial stiffness
-  N_f = cycles to failure
-  p = material exponent (typically 0.5-2)
-  D = damage variable (0 = undamaged, 1 = failed)
-```
-
-When D(N) = 1, the crease has failed (torn through).
-
-#### Design for Fatigue Resistance
-
-- **Living hinges**: Use a different, more fatigue-resistant material at the crease (e.g., polypropylene).
-- **Wider creases**: Distribute the deformation over a wider zone, reducing peak strain.
-- **Reduced fold amplitude**: Design for partial folding rather than full 180-degree folds.
-- **Material selection**: Elastomers and thermoplastic elastomers offer the best fatigue resistance.
-
-### 4.4 Bistability
-
-#### Definition
-
-An origami structure is **bistable** if it has two distinct stable equilibrium configurations separated by an energy barrier. The structure can "snap" between the two states.
-
-#### Mechanism
-
-Bistability arises from the competition between:
-1. **Crease energy**: Creases prefer their rest angles.
-2. **Face bending energy**: Faces resist bending.
-3. **Geometric constraints**: The topology of the pattern constrains the configuration space.
-
-When the energy landscape has two local minima (valleys) separated by a saddle point (hill), the structure is bistable.
-
-#### Example: Kresling Pattern
-
-The Kresling pattern (a cylindrical origami pattern) is naturally bistable:
-- **State 1**: Extended (tall cylinder).
-- **State 2**: Compressed (short, twisted cylinder).
-- **Transition**: Requires overcoming an energy barrier (the faces must bend temporarily during the snap-through).
-
-The bistability of the Kresling pattern can be tuned by adjusting:
-- Number of sides (polygon order).
-- Fold angle of the pattern.
-- Material stiffness ratio (crease vs. face).
-
-#### Modeling Bistability
-
-The bar-and-hinge model with compliant creases (Ghassaei's extended model) can capture bistability. The key is:
-1. Include face bending energy (facet hinges), not just crease folding energy.
-2. Use the compliant crease model (finite crease width) to capture torsional and extensional deformation in the crease zone.
-3. Trace the energy landscape as a function of a loading parameter to find multiple stable equilibria.
-
-**Critical**: The simplified spring-hinge model (rigid faces + torsional springs at creases) typically CANNOT predict bistability because it lacks face bending energy. The competition between face and crease energies is essential for bistability.
-
-### 4.5 Shape Memory in Origami Structures
-
-#### Crease-Level Shape Memory
-
-Individual creases exhibit shape memory due to plastic deformation:
-- After folding and unfolding, the crease "remembers" the fold angle.
-- Upon re-folding, the crease preferentially returns to its previously folded state.
-- The memory improves with repeated folding cycles.
-
-This is the basis of the **Miura-ori map**: a pre-folded Miura-ori pattern can be unfolded to flat and easily re-folded by pushing two opposite corners together. The crease memory guides the paper back to the correct folded state.
-
-#### Material-Level Shape Memory
-
-**Shape memory alloys (SMAs)** and **shape memory polymers (SMPs)** can be used to create origami structures with active shape memory:
-
-- **SMA origami**: Creases made from nitinol wire. At low temperature, the wire is flexible and the structure can be folded flat. Upon heating, the SMA transitions to its austenite phase and contracts, deploying the structure to its memorized 3D shape.
-- **SMP origami**: The entire sheet is a shape memory polymer. Heated above T_g, the polymer is soft and can be folded. Cooled below T_g, the polymer hardens in the folded state. Re-heating above T_g triggers autonomous deployment to the flat (or programmed 3D) state.
-
-#### For Simulation
-
-Shape memory can be modeled by making the rest angle a function of temperature:
-
-```
-rho_0(T) = rho_programmed                   for T < T_transition
-rho_0(T) = rho_deployed                     for T > T_transition
-rho_0(T) = interpolation in transition zone
-```
-
-### 4.6 Auxetic Behavior (Negative Poisson's Ratio)
-
-#### Definition
-
-A material or structure has **auxetic** behavior if it exhibits a **negative Poisson's ratio**: when stretched in one direction, it expands in the perpendicular direction (instead of contracting as normal materials do).
-
-#### Origami Auxetic Patterns
-
-**Miura-ori** is the canonical example of an auxetic origami pattern:
-
-```
-nu_xy = -1   (Poisson's ratio for in-plane deformation of Miura-ori)
-```
-
-When a Miura-ori sheet is pulled in the x-direction (along the corrugation), it also expands in the y-direction. This is a purely geometric effect arising from the kinematics of the fold pattern.
-
-**Physical explanation**: As the Miura-ori unfolds in one direction, the fold angle changes globally (it is a 1-DOF mechanism). This global angle change causes the pattern to simultaneously unfold in the perpendicular direction.
-
-#### Tunable Poisson's Ratio
-
-By modifying the pattern geometry, the Poisson's ratio can be tuned:
-
-- **Standard Miura-ori**: nu = -1 (isotropic auxetic in the folding mode).
-- **Modified Miura-ori** (varying parallelogram angles): nu can range from negative to positive.
-- **Reentrant patterns** (Tachi-Miura polyhedra, zigzag modifications): can achieve strongly negative Poisson's ratios (nu < -1).
-- **Hybrid patterns**: Combining different unit cells can create programmable Poisson's ratio fields.
-
-#### Engineering Applications
-
-1. **Impact absorption**: Auxetic structures densify under impact (all directions compress simultaneously), making them excellent energy absorbers.
-2. **Morphing surfaces**: Auxetic sheets can conform to doubly-curved surfaces (saddle shapes) without wrinkling, because the negative Poisson's ratio accommodates the required in-plane deformation.
-3. **Deployable structures**: The simultaneous expansion in all directions enables compact packaging and uniform deployment.
-4. **Medical stents**: Auxetic origami tubes expand radially when stretched axially, useful for vascular stents.
-
-#### For Simulation
-
-The effective Poisson's ratio of an origami pattern can be computed from the kinematic equations:
-
-```
-nu_eff = -(d(epsilon_y)/d(epsilon_x))
-
-where epsilon_x, epsilon_y are the effective in-plane strains
-computed from the fold-angle-dependent geometry.
-```
-
-For Miura-ori with parallelogram angle phi and fold angle theta:
-
-```
-nu_xy = -( (cos(theta) * tan(phi))^2 + sin(theta)^2 ) / (cos(theta)^2 * tan(phi)^2 + sin(theta)^2)
-```
-
-This gives nu_xy = -1 for the standard Miura-ori (symmetric case), but can vary for asymmetric variants.
-
----
-
-## 5. Key References and Sources
-
-### Foundational Texts
-
-- **Demaine, E.D. and O'Rourke, J.** (2007). *Geometric Folding Algorithms: Linkages, Origami, Polyhedra*. Cambridge University Press. -- The definitive monograph on computational origami.
-- **Lang, R.J.** (2011). *Origami Design Secrets: Mathematical Methods for an Ancient Art*. 2nd ed. A K Peters/CRC Press. -- Practical computational design methods including TreeMaker.
-- **Hull, T.C.** (2020). *Origametry: Mathematical Methods in Paper Folding*. Cambridge University Press. -- Modern mathematical treatment.
-
-### Key Papers
-
-- **Bern, M. and Hayes, B.** (1996). "The complexity of flat origami." *Proceedings of the 7th ACM-SIAM Symposium on Discrete Algorithms (SODA)*. -- Proved NP-completeness of flat foldability.
-- **Akitaya, H.A. et al.** (2016). "Box pleating is hard." *Proceedings of the 16th Japan Conference on Discrete and Computational Geometry and Graphs*. -- Repaired and strengthened Bern-Hayes proof.
-- **Hull, T.C. and Zakharevich, I.** (2025). "Flat origami is Turing complete." *arXiv:2309.07932v4*. -- Showed flat origami with optional creases can simulate universal computation.
-- **Schenk, M. and Guest, S.D.** (2011). "Origami folding: A structural engineering approach." *Origami 5: Fifth International Meeting of Origami Science, Mathematics, and Education*. -- Bar-and-hinge model foundations.
-- **Ghassaei, A. et al.** (2018). "Fast, interactive origami simulation using GPU computation." *Origami 7*. -- GPU-accelerated bar-and-hinge implementation (origamisimulator.org).
-- **Tachi, T.** (2009). "Simulation of rigid origami." *Origami 4: Fourth International Meeting of Origami Science, Mathematics, and Education*. -- Rigid origami simulator.
-- **Demaine, E.D., Demaine, M.L., and Lubiw, A.** (1998). "Folding and one straight cut suffice." *Proceedings of the 10th ACM-SIAM Symposium on Discrete Algorithms*. -- Fold-and-cut theorem.
-- **Liu, K. and Paulino, G.H.** (2017). "Nonlinear mechanics of non-rigid origami: an efficient computational approach." *Proceedings of the Royal Society A*, 473(2206). -- Advanced bar-and-hinge mechanics.
-
-### Computational Complexity
-
-- **Stern, A. and Hull, T.** (2025). "Computational Complexities of Folding." *arXiv:2410.07666*. -- Comprehensive survey of complexity results including FPT, PSPACE, #P, and undecidability results.
-- **Hull, T.C.** (1994). "On the mathematics of flat origamis." *Congressus Numerantium*, 100, 215-224. -- Sufficiency of Kawasaki's condition, counting MV assignments.
-
-### Engineering and Mechanics
-
-- **Filipov, E.T., Liu, K., Tachi, T., Schenk, M., and Paulino, G.H.** (2017). "Bar and hinge models for scalable analysis of origami." *International Journal of Solids and Structures*, 124, 26-45. -- Comprehensive bar-and-hinge formulation.
-- **Lang, R.J. et al.** (2018). "A review of thickness-accommodation techniques in origami-inspired engineering." *Applied Mechanics Reviews*, 70(1), 010805. -- Survey of thickness methods.
-- **Silverberg, J.L. et al.** (2014). "Using origami design principles to fold reprogrammable mechanical metamaterials." *Science*, 345(6197), 647-650. -- Programmable mechanical properties.
-- **Yasuda, H. and Yang, J.** (2015). "Reentrant origami-based metamaterials with negative Poisson's ratio and bistability." *Physical Review Letters*, 114(18), 185502. -- Auxetic and bistable origami.
-- **Lechenault, F., Thiria, B., and Adda-Bedia, M.** (2014). "Mechanical response of a creased sheet." *Physical Review Letters*, 112, 244301. -- Elastic theory of creases.
-
-### Software Tools
-
-- **Origami Simulator** (Ghassaei): https://origamisimulator.org/ -- Browser-based GPU-accelerated simulator.
-- **Rigid Origami Simulator** (Tachi): https://origami.c.u-tokyo.ac.jp/~tachi/software/ -- Rigid origami kinematic simulator.
-- **ORIPA** (Mitani): Crease pattern editor with flat-foldability checks.
-- **TreeMaker** (Lang): Computational origami design from stick figures.
-- **Rabbit Ear** (Kraft): JavaScript library for computational origami with Kawasaki/Maekawa solvers and layer ordering.
-
----
-
-## Appendix A: Huzita-Hatori Axioms (Origami Constructive Power)
-
-The **seven Huzita-Hatori axioms** define all possible single-fold operations in origami and establish that origami construction is strictly more powerful than compass-and-straightedge construction.
-
-| Axiom | Description | Geometric Power |
-|-------|-------------|----------------|
-| O1 | Given two points, fold a line through both. | Line through 2 points (same as straightedge) |
-| O2 | Given two points, fold one onto the other. | Perpendicular bisector |
-| O3 | Given two lines, fold one onto the other. | Angle bisector |
-| O4 | Given a point and a line, fold a perpendicular through the point. | Perpendicular through a point |
-| O5 | Given two points and a line, fold one point onto the line through the other. | Solves quadratic equations |
-| O6 | Given two points and two lines, fold each point onto its line simultaneously. | **Solves cubic equations** |
-| O7 | Given a point and two lines, fold the point onto one line with the fold perpendicular to the other. | Perpendicular fold onto a line |
-
-**Axiom O6 is the key**: It allows origami to solve cubic equations, which compass and straightedge cannot do. This enables:
-- **Angle trisection** (impossible with compass and straightedge).
-- **Doubling the cube** (impossible with compass and straightedge).
-- Construction of regular heptagon (7-sided polygon).
-
-These axioms were discovered by Jacques Justin (1986), rediscovered by Humiaki Huzita (1991), with axiom O7 found by Koshiro Hatori (2001) and independently by Robert Lang.
-
----
-
-## Appendix B: Summary of Key Formulas for Simulation Engine Implementation
-
-### Geometric Validation
-
-```
-Kawasaki-Justin:    sum_{i odd} alpha_i = pi
-Maekawa-Justin:     |M - V| = 2
-Big-Little-Big:     if alpha_{i-1} > alpha_i < alpha_{i+1},
-                    then MV(crease_i) != MV(crease_{i+1})
-```
-
-### Energy Model (Bar-and-Hinge)
-
-```
-E_total = E_bar + E_facet + E_fold
-
-E_bar   = sum (1/2) * k_a * (L - L0)^2
-E_facet = sum (1/2) * k_f * l * (theta - pi)^2
-E_fold  = sum (1/2) * k_c * l * (rho - rho_target)^2
-
-k_a = E*t*w/L0    (axial stiffness)
-k_f = E*t^3/(12*(1-nu^2))  (per unit length, flexural)
-k_c = crease torsional stiffness (per unit length)
-```
-
-### Rigid Origami Kinematics (Degree-4 Vertex)
-
-```
-tan(rho_2/2) = -cos((alpha-beta)/2) / cos((alpha+beta)/2) * tan(rho_1/2)
-```
-
-### Origami Length Scale
-
-```
-L* = B / kappa = (E*t^3/12) / kappa
-
-L* >> panel_size  -->  rigid origami regime
-L* << panel_size  -->  flexible shell regime
-```
-
-### Deployment Ratio
-
-```
-DR = L_deployed / L_stowed
-DR_area = A_deployed / A_stowed
-```
-
-### Effective Poisson's Ratio (Miura-ori)
-
-```
-nu_xy = -((cos(theta)*tan(phi))^2 + sin(theta)^2) /
-         (cos(theta)^2*tan(phi)^2 + sin(theta)^2)
-```
-
-### Fatigue Damage
-
-```
-D(N) = (N / N_f)^p
-kappa_N = kappa_0 * (1 - D(N))
-```
-
-### Numerical Integration (Verlet, for dynamic simulation)
-
-```
-x_{n+1} = 2*x_n - x_{n-1} + F * dt^2 / m
-```

research 2/origami/metrics.md

@@ -1,58 +0,0 @@
-# Metrics for the Origami RL Environment
-
-## Fold Validity
-
-| Metric | Formula | Use |
-|--------|---------|-----|
-| Kawasaki violation | Σ |alternating_angle_sum - 180°| per vertex | Reward penalty |
-| Maekawa violation | Σ |abs(M-V) - 2| per vertex | Hard constraint |
-| Self-intersection count | Triangle-triangle intersection testing | Reward penalty |
-| Rigid foldability | Kinematic simulation pass/fail | Gate reward |
-
-## Compactness / Efficiency
-
-| Metric | Formula | Use |
-|--------|---------|-----|
-| **Deployment ratio** | `area_folded / area_unfolded` | Primary reward signal |
-| Volume compaction | `bbox_folded / bbox_unfolded` | Secondary reward |
-| Fold count | Count of M + V edges | Efficiency penalty |
-| Folding efficiency | `compaction_ratio / fold_count` | Combined metric |
-| Packing efficiency | `material_volume / bbox_volume` | How well it fills space |
-
-## Structural / Stress
-
-| Metric | Formula | Use |
-|--------|---------|-----|
-| Cauchy strain | Per-vertex avg deviation of edge lengths | Reward penalty |
-| Max strain | `max(strain_per_vertex)` | Must stay below material limit |
-| Structural energy | Sum of constraint violation energies | Lower = more stable |
-
-## Shape Similarity (for target-matching tasks)
-
-| Metric | Formula | Use |
-|--------|---------|-----|
-| Chamfer distance | Avg nearest-point distance between shapes | Primary shape reward |
-| Hausdorff distance | Max distance between shapes | Worst-case shape error |
-| IoU (3D) | Voxelized intersection over union | Alternative shape reward |
-
-## Foldability Quality
-
-| Metric | Formula | Use |
-|--------|---------|-----|
-| Flat-foldability score | Sum of angular deviations from target | For flat-fold tasks |
-| Deployability | Reverse fold simulation collision check | Engineering reward |
-| Crease pattern complexity | Entropy of M/V assignments | Simplicity bonus |
-
-## Composite Reward Function
-
-```python
-reward = (
-    w1 * deployment_ratio          # How compact is the fold?
-    - w2 * total_strain            # Physical validity
-    - w3 * self_intersections      # No paper penetration
-    - w4 * kawasaki_violation      # Angle consistency
-    - w5 * fold_count_penalty      # Fewer folds = better
-    + w6 * deployability_score     # Can it unfold cleanly?
-    + w7 * shape_similarity        # If targeting a specific shape
-)
-```

research 2/origami/origami_simulator_code.md

@@ -1,1030 +0,0 @@
-# OrigamiSimulator Source Code Analysis & FOLD Format in Practice
-
-> Deep analysis of Amanda Ghassaei's OrigamiSimulator codebase and real FOLD file examples.
-> Source: https://github.com/amandaghassaei/OrigamiSimulator (MIT License, JS/WebGL)
-> FOLD spec: https://github.com/edemaine/fold
-
----
-
-## Table of Contents
-
-1. [Repository Structure](#1-repository-structure)
-2. [FOLD Format Parsing — How the Simulator Loads Files](#2-fold-format-parsing)
-3. [Mesh & Geometry Representation](#3-mesh--geometry-representation)
-4. [Triangulation — How Faces Are Split](#4-triangulation)
-5. [The Simulation Model — GPU-Accelerated Bar-and-Hinge](#5-the-simulation-model)
-6. [Strain Computation & Visualization](#6-strain-computation--visualization)
-7. [Real FOLD File Examples](#7-real-fold-file-examples)
-8. [Minimal FOLD Representation for Our RL Environment](#8-minimal-fold-representation)
-
----
-
-## 1. Repository Structure
-
-The OrigamiSimulator repo (the browser-based version at origamisimulator.org) has this structure:
-
-```
-OrigamiSimulator/
-├── index.html
-├── js/
-│   ├── globals.js           # Global constants, stiffness params, simulation settings
-│   ├── model.js             # Main model class — orchestrates everything
-│   ├── fold.js              # FOLD format import/export
-│   ├── pattern.js           # Built-in crease patterns (bird base, Miura-ori, etc.)
-│   ├── SVGimport.js         # SVG import (converts SVG crease patterns to FOLD)
-│   ├── triangulate.js       # Ear-clipping triangulation of polygon faces
-│   ├── gpuMath.js           # WebGL compute abstraction (textures as data arrays)
-│   ├── solver.js            # The GPU constraint solver (velocity Verlet integration)
-│   ├── node.js              # Vertex/node class
-│   ├── edge.js              # Edge class (with assignment: M/V/B/F/U)
-│   ├── face.js              # Face/triangle class
-│   ├── beam.js              # Beam (bar) constraint — axial spring
-│   ├── crease.js            # Crease constraint — fold/facet hinge
-│   ├── threeView.js         # Three.js 3D rendering
-│   └── UI/                  # User interface code
-├── assets/
-│   ├── fold/                # Example .fold files (crane, bird, Miura-ori, etc.)
-│   └── svg/                 # Example SVG crease patterns
-└── shaders/
-    ├── positionCalcShader.frag    # Position update (Verlet integration)
-    ├── velocityCalcShader.frag    # Velocity calculation with damping
-    ├── thetaCalcShader.frag       # Dihedral angle computation
-    ├── normalCalcShader.frag      # Face normal computation
-    └── strainCalcShader.frag      # Strain visualization
-```
-
----
-
-## 2. FOLD Format Parsing — How the Simulator Loads Files
-
-### The Core Import Logic (`fold.js`)
-
-The simulator's FOLD import is in `js/fold.js`. Here is the essential parsing logic:
-
-```javascript
-// fold.js — FOLD import (reconstructed from source)
-
-function parseFOLD(foldData) {
-    // foldData is the parsed JSON object from a .fold file
-
-    var vertices = foldData.vertices_coords;      // [[x,y], [x,y,z], ...]
-    var edges = foldData.edges_vertices;           // [[v0,v1], [v0,v1], ...]
-    var assignments = foldData.edges_assignment;   // ["M","V","B","F","U",...]
-    var foldAngles = foldData.edges_foldAngle;     // [angle, angle, ...] (degrees)
-    var faces = foldData.faces_vertices;           // [[v0,v1,v2,...], ...]
-
-    // If vertices are 2D, add z=0
-    for (var i = 0; i < vertices.length; i++) {
-        if (vertices[i].length === 2) {
-            vertices[i].push(0);
-        }
-    }
-
-    // If edges_assignment is missing, infer from edges_foldAngle
-    if (!assignments && foldAngles) {
-        assignments = [];
-        for (var i = 0; i < foldAngles.length; i++) {
-            if (foldAngles[i] === 0) assignments.push("F");
-            else if (foldAngles[i] < 0) assignments.push("M");
-            else if (foldAngles[i] > 0) assignments.push("V");
-            else assignments.push("U");
-        }
-    }
-
-    // If edges_foldAngle is missing, infer from edges_assignment
-    if (!foldAngles && assignments) {
-        foldAngles = [];
-        for (var i = 0; i < assignments.length; i++) {
-            if (assignments[i] === "M") foldAngles.push(-Math.PI);
-            else if (assignments[i] === "V") foldAngles.push(Math.PI);
-            else foldAngles.push(0);
-        }
-    }
-
-    // If faces_vertices is missing, reconstruct from edges
-    if (!faces) {
-        faces = FOLD.convert.edges_vertices_to_faces_vertices(
-            vertices, edges
-        );
-    }
-
-    return {
-        vertices: vertices,
-        edges: edges,
-        assignments: assignments,
-        foldAngles: foldAngles,
-        faces: faces
-    };
-}
-```
-
-### Key FOLD Fields Actually Used by the Simulator
-
-| FOLD Field | Required? | How It's Used |
-|-----------|-----------|---------------|
-| `vertices_coords` | **YES** | Node positions (2D or 3D). 2D gets z=0 appended. |
-| `edges_vertices` | **YES** | Defines connectivity. Each edge is a pair `[v_i, v_j]`. |
-| `edges_assignment` | Recommended | `"M"`, `"V"`, `"B"`, `"F"`, `"U"` — determines fold behavior. |
-| `edges_foldAngle` | Optional | Target fold angle in radians (some files use degrees). The simulator converts. Positive = valley, negative = mountain. |
-| `faces_vertices` | Recommended | Polygon faces as ordered vertex lists. If missing, reconstructed from edges. |
-| `file_spec` | Ignored | FOLD spec version |
-| `file_creator` | Ignored | Metadata |
-| `frame_classes` | Checked | `"creasePattern"` vs `"foldedForm"` — affects initial state |
-| `frame_attributes` | Checked | `"2D"` vs `"3D"` |
-| `faceOrders` | **NOT USED** | Layer ordering is not needed for physics simulation |
-| `vertices_vertices` | **NOT USED** | Adjacency — recomputed internally |
-| `edges_faces` | **NOT USED** | Recomputed internally |
-| `faces_edges` | **NOT USED** | Recomputed internally |
-
-### Critical Insight: What the Simulator Does NOT Use
-
-The simulator ignores `faceOrders` (layer ordering) entirely. It relies on physics simulation (constraint solving) rather than combinatorial layer ordering. Self-intersection is handled implicitly by the energy-based solver — faces naturally avoid each other if the stiffness parameters are set correctly.
-
-### Assignment-to-Angle Mapping
-
-```javascript
-// How assignments map to target fold angles:
-// "M" (mountain): target angle = -PI radians (fold to -180 degrees)
-// "V" (valley):   target angle = +PI radians (fold to +180 degrees)
-// "F" (flat):     target angle = 0 (no fold)
-// "B" (boundary): no fold constraint (boundary edge)
-// "U" (unassigned): target angle = 0 (treated as flat)
-
-// The fold angle convention:
-// 0     = flat (faces coplanar)
-// +PI   = valley fold (paper folds toward you)
-// -PI   = mountain fold (paper folds away from you)
-// The actual simulation interpolates: target = foldAngle * foldPercent
-// where foldPercent goes from 0.0 (flat) to 1.0 (fully folded)
-```
-
----
-
-## 3. Mesh & Geometry Representation
-
-### Internal Data Structures
-
-The simulator converts the FOLD data into internal arrays optimized for GPU computation:
-
-```javascript
-// model.js — Internal representation (reconstructed)
-
-// NODES: stored as flat Float32Arrays for GPU textures
-// Position texture: [x0, y0, z0, w0, x1, y1, z1, w1, ...]
-// where w is unused (padding for RGBA texture format)
-var numNodes;
-var originalPosition;  // Float32Array — rest positions (flat state)
-var position;          // Float32Array — current positions (deformed state)
-var velocity;          // Float32Array — current velocities
-var lastPosition;      // Float32Array — previous positions (for Verlet)
-var externalForces;    // Float32Array — applied external forces
-var mass;              // Float32Array — per-node mass (usually uniform)
-
-// BEAMS (bars): axial spring constraints along every edge
-var numBeams;
-var beamMeta;  // Int32Array — [nodeA_index, nodeB_index] per beam
-var beamK;     // Float32Array — axial stiffness per beam
-
-// CREASES: rotational spring constraints (both fold and facet hinges)
-var numCreases;
-var creaseMeta;      // Int32Array — [node1, node2, node3, node4] per crease
-                     // node1-node2 is the hinge edge
-                     // node3, node4 are the opposite vertices of the two triangles
-var creaseAngles;    // Float32Array — target dihedral angle per crease
-var creaseStiffness; // Float32Array — torsional stiffness per crease
-var creaseType;      // Int32Array — 0=fold crease, 1=facet crease, 2=boundary
-
-// The four-node crease geometry:
-//        node3
-//       / | \
-//      /  |  \
-//   node1-+--node2  (hinge edge)
-//      \  |  /
-//       \ | /
-//        node4
-```
-
-### How Vertices, Edges, Faces Map to GPU Textures
-
-The simulator packs all data into WebGL textures (RGBA float textures) because WebGL fragment shaders operate on textures:
-
-```javascript
-// gpuMath.js — texture packing (conceptual)
-
-// Each vertex gets one pixel in a position texture:
-//   pixel[i] = vec4(x_i, y_i, z_i, 0.0)
-//
-// Texture dimensions: ceil(sqrt(numNodes)) x ceil(sqrt(numNodes))
-// So 100 nodes -> 10x10 texture
-//
-// Beams packed into beam meta texture:
-//   pixel[i] = vec4(nodeA_index, nodeB_index, restLength, stiffness)
-//
-// Creases packed into crease meta texture:
-//   pixel[i] = vec4(node1_index, node2_index, node3_index, node4_index)
-//   (target angle and stiffness in a separate texture)
-
-function initTextureFromArray(width, height, data, type) {
-    var gl = this.gl;
-    var texture = gl.createTexture();
-    gl.bindTexture(gl.TEXTURE_2D, texture);
-    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA,
-                  width, height, 0, gl.RGBA, type, data);
-    // NEAREST filtering — no interpolation (we want exact values)
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-    return texture;
-}
-```
-
----
-
-## 4. Triangulation — How Faces Are Split
-
-### Why Triangulate?
-
-FOLD files can have polygon faces (quads, pentagons, etc.). The bar-and-hinge model requires triangulated faces because:
-1. Triangles are always planar (3 points define a plane).
-2. Non-triangular faces need "facet hinges" to penalize bending — but you need triangles to define a dihedral angle.
-3. GPU rendering works with triangles.
-
-### The Triangulation Algorithm
-
-The simulator uses **ear-clipping triangulation** for each polygon face:
-
-```javascript
-// triangulate.js (reconstructed from source)
-
-function triangulateFace(face, vertices) {
-    // face = [v0, v1, v2, v3, ...] (vertex indices, CCW order)
-    // vertices = [[x,y,z], ...] (all vertex positions)
-
-    if (face.length === 3) return [face]; // already a triangle
-
-    var triangles = [];
-    var remaining = face.slice(); // copy
-
-    while (remaining.length > 3) {
-        // Find an "ear" — a vertex whose triangle doesn't contain other vertices
-        for (var i = 0; i < remaining.length; i++) {
-            var prev = remaining[(i - 1 + remaining.length) % remaining.length];
-            var curr = remaining[i];
-            var next = remaining[(i + 1) % remaining.length];
-
-            // Check if triangle (prev, curr, next) is an ear
-            if (isEar(prev, curr, next, remaining, vertices)) {
-                triangles.push([prev, curr, next]);
-                remaining.splice(i, 1); // remove the ear vertex
-                break;
-            }
-        }
-    }
-    triangles.push(remaining); // last 3 vertices form final triangle
-    return triangles;
-}
-
-function isEar(a, b, c, polygon, vertices) {
-    // 1. Triangle must be convex (CCW winding)
-    var cross = crossProduct2D(
-        sub(vertices[b], vertices[a]),
-        sub(vertices[c], vertices[a])
-    );
-    if (cross <= 0) return false; // concave, not an ear
-
-    // 2. No other polygon vertex inside the triangle
-    for (var i = 0; i < polygon.length; i++) {
-        var v = polygon[i];
-        if (v === a || v === b || v === c) continue;
-        if (pointInTriangle(vertices[v], vertices[a], vertices[b], vertices[c])) {
-            return false;
-        }
-    }
-    return true;
-}
-```
-
-### What Triangulation Creates
-
-For a quad face `[v0, v1, v2, v3]`, triangulation produces two triangles `[v0, v1, v2]` and `[v0, v2, v3]`. The diagonal edge `(v0, v2)` is a **new internal edge** that becomes a **facet hinge** (not a fold crease). This facet hinge has:
-- Target angle = PI (flat, 180 degrees)
-- High stiffness (penalizes face bending)
-
-```
-Original quad face:          After triangulation:
-v0 ------- v1              v0 ------- v1
-|          |               | \        |
-|          |    --->       |   \      |
-|          |               |     \    |
-v3 ------- v2              v3 ------\ v2
-
-The diagonal v0-v2 becomes a facet hinge.
-```
-
-### Edge Classification After Triangulation
-
-Every edge in the triangulated mesh is one of three types:
-
-| Edge Type | Source | Target Angle | Stiffness | Purpose |
-|-----------|--------|--------------|-----------|---------|
-| **Fold crease** | Original crease edge (M/V) | From `edges_foldAngle` | `k_fold` (user-adjustable) | Drives folding |
-| **Facet hinge** | Triangulation diagonal OR original flat edge | PI (flat) | `k_facet` (high) | Prevents face bending |
-| **Boundary** | Original boundary edge (B) | None | N/A | No rotational constraint |
-
----
-
-## 5. The Simulation Model — GPU-Accelerated Bar-and-Hinge
-
-### Overview of the Algorithm
-
-The simulator uses **velocity Verlet integration** with three types of constraints, all computed in GPU fragment shaders:
-
-```
-For each simulation step:
-  1. Compute all forces on each node
-     a. Beam forces (axial springs — prevent stretching)
-     b. Crease forces (rotational springs — drive folding / prevent face bending)
-  2. Update velocities (with damping)
-  3. Update positions (Verlet integration)
-  4. Repeat until convergence or user stops
-```
-
-### The Three Constraint Types
-
-#### Constraint 1: Beam (Bar) — Axial Spring
-
-Each edge of the triangulated mesh is a bar that resists stretching/compression:
-
-```glsl
-// Conceptual beam force computation (from solver shaders)
-// For a beam between nodes A and B:
-
-vec3 posA = getPosition(nodeA_index);  // current position of node A
-vec3 posB = getPosition(nodeB_index);  // current position of node B
-
-vec3 delta = posB - posA;
-float currentLength = length(delta);
-float restLength = getRestLength(beam_index);
-
-// Engineering strain
-float strain = (currentLength - restLength) / restLength;
-
-// Hooke's law: F = k * strain * restLength (force magnitude)
-float forceMagnitude = beamStiffness * strain * restLength;
-
-// Force direction: along the beam
-vec3 forceDirection = delta / currentLength;
-
-// Force on node A: pulls toward B if stretched, pushes away if compressed
-vec3 forceOnA = forceMagnitude * forceDirection;
-// Force on node B: equal and opposite
-vec3 forceOnB = -forceMagnitude * forceDirection;
-```
-
-The axial stiffness parameter:
-```javascript
-// globals.js
-var axialStiffness = 70;  // default value — high to prevent stretching
-// This maps to: k_beam = axialStiffness * E * t / L0
-// where E = Young's modulus, t = thickness, L0 = rest length
-```
-
-#### Constraint 2: Crease — Rotational Spring (Fold Hinge)
-
-For each crease (fold line), a rotational spring drives the dihedral angle toward the target:
-
-```glsl
-// Conceptual crease force computation
-// A crease spans 4 nodes: node1, node2 (hinge edge), node3, node4 (wing tips)
-//
-//        node3
-//       / | \
-//      /  |  \         dihedral angle theta is measured between
-//   node1----node2     the planes (node1,node2,node3) and (node1,node2,node4)
-//      \  |  /
-//       \ | /
-//        node4
-
-vec3 p1 = getPosition(node1);
-vec3 p2 = getPosition(node2);
-vec3 p3 = getPosition(node3);
-vec3 p4 = getPosition(node4);
-
-// Compute face normals
-vec3 e = p2 - p1;           // hinge edge vector
-vec3 n1 = cross(p3 - p1, e);  // normal of triangle (p1, p2, p3)
-vec3 n2 = cross(e, p4 - p1);  // normal of triangle (p1, p2, p4)
-n1 = normalize(n1);
-n2 = normalize(n2);
-
-// Current dihedral angle
-float cosTheta = dot(n1, n2);
-float sinTheta = dot(cross(n1, n2), normalize(e));
-float theta = atan(sinTheta, cosTheta);  // current dihedral angle
-
-// Target angle (interpolated by fold percent)
-float targetAngle = getTargetAngle(crease_index) * foldPercent;
-
-// Angular deviation
-float deltaTheta = theta - targetAngle;
-
-// Torque magnitude: tau = k_crease * edgeLength * deltaTheta
-float torque = creaseStiffness * edgeLength * deltaTheta;
-
-// Convert torque to forces on the 4 nodes
-// The force on node3 is perpendicular to the hinge and the arm (p3 - hinge)
-// The force on node4 is perpendicular to the hinge and the arm (p4 - hinge)
-// Forces on node1 and node2 balance the torque
-
-vec3 arm3 = p3 - project_onto_hinge(p3, p1, p2);
-vec3 arm4 = p4 - project_onto_hinge(p4, p1, p2);
-
-float dist3 = length(arm3);
-float dist4 = length(arm4);
-
-// Force on wing nodes (perpendicular to arm, in the fold direction)
-vec3 force3 = torque / dist3 * cross(normalize(e), normalize(arm3));
-vec3 force4 = -torque / dist4 * cross(normalize(e), normalize(arm4));
-
-// Forces on hinge nodes balance: -(force3 + force4) split proportionally
-```
-
-#### Constraint 3: Facet Hinge — Keeps Faces Flat
-
-Facet hinges are identical in implementation to fold creases, but with:
-- **Target angle = PI** (flat / 180 degrees)
-- **Much higher stiffness** than fold creases
-
-```javascript
-// Typical stiffness hierarchy:
-var foldStiffness = 0.7;   // fold creases — relatively soft, drives folding
-var facetStiffness = 0.2;  // facet hinges — moderate, keeps faces flat
-var axialStiffness = 70;   // bars — very stiff, prevents stretching
-
-// The facet stiffness is lower than you might expect because the
-// bar constraints already handle most of the face rigidity.
-// The facet hinge just needs to prevent out-of-plane bending.
-```
-
-### The GPU Solver (Verlet Integration)
-
-The position update shader implements velocity Verlet integration:
-
-```glsl
-// positionCalcShader.frag (reconstructed)
-precision highp float;
-
-uniform sampler2D u_position;      // current positions
-uniform sampler2D u_lastPosition;  // previous positions
-uniform sampler2D u_velocity;      // current velocities
-uniform sampler2D u_force;         // total force on each node
-uniform float u_dt;                // timestep
-uniform float u_damping;           // damping coefficient [0, 1]
-
-void main() {
-    vec2 fragCoord = gl_FragCoord.xy / u_textureDim;
-
-    vec4 pos = texture2D(u_position, fragCoord);
-    vec4 lastPos = texture2D(u_lastPosition, fragCoord);
-    vec4 force = texture2D(u_force, fragCoord);
-
-    // Velocity Verlet integration:
-    // new_pos = 2 * pos - lastPos + force * dt^2 / mass
-    // With damping: new_pos = pos + (1 - damping) * (pos - lastPos) + force * dt^2
-
-    vec4 newPos = pos + (1.0 - u_damping) * (pos - lastPos)
-                  + force * u_dt * u_dt;
-
-    gl_FragColor = newPos;
-}
-```
-
-```glsl
-// velocityCalcShader.frag (reconstructed)
-// Velocity is derived from position difference (for damping/output)
-
-void main() {
-    vec2 fragCoord = gl_FragCoord.xy / u_textureDim;
-    vec4 pos = texture2D(u_position, fragCoord);
-    vec4 lastPos = texture2D(u_lastPosition, fragCoord);
-
-    vec4 velocity = (pos - lastPos) / u_dt;
-
-    gl_FragColor = velocity;
-}
-```
-
-### Solver Parameters
-
-```javascript
-// globals.js — simulation parameters
-var numStepsPerFrame = 100;    // solver iterations per render frame
-var dt = 0.02;                  // timestep
-var damping = 0.1;              // velocity damping [0=no damping, 1=fully damped]
-
-// Stiffness parameters (user-adjustable via UI sliders)
-var axialStiffness = 70;        // bar stiffness — prevents stretching
-var foldStiffness = 0.7;        // fold crease stiffness — drives folding
-var facetStiffness = 0.2;       // facet hinge stiffness — prevents bending
-var foldPercent = 0.0;          // fold amount [0=flat, 1=fully folded]
-
-// The solver runs until:
-//   1. Kinetic energy drops below a threshold (converged), or
-//   2. The user changes a parameter (re-triggers), or
-//   3. Max iterations reached
-```
-
-### Complete Solver Loop (Per Frame)
-
-```javascript
-// solver.js — main loop (reconstructed)
-
-function solveStep() {
-    for (var i = 0; i < numStepsPerFrame; i++) {
-        // Step 1: Zero out force accumulators
-        gpuMath.clearTexture("u_force");
-
-        // Step 2: Compute beam forces
-        //   For each beam, compute axial spring force
-        //   Accumulate forces on both endpoint nodes
-        gpuMath.runProgram("beamForceCalc", {
-            u_position: positionTexture,
-            u_beamMeta: beamMetaTexture,  // [nodeA, nodeB, restLen, stiffness]
-        }, forceTexture);  // accumulates into force texture
-
-        // Step 3: Compute crease/hinge forces
-        //   For each crease (fold + facet), compute rotational spring force
-        //   Accumulate forces on all 4 nodes
-        gpuMath.runProgram("creaseForceCalc", {
-            u_position: positionTexture,
-            u_creaseMeta: creaseMetaTexture,  // [n1, n2, n3, n4]
-            u_creaseAngles: creaseAngleTexture,
-            u_foldPercent: foldPercent,
-        }, forceTexture);  // accumulates
-
-        // Step 4: Update positions via Verlet integration
-        gpuMath.runProgram("positionCalc", {
-            u_position: positionTexture,
-            u_lastPosition: lastPositionTexture,
-            u_force: forceTexture,
-            u_dt: dt,
-            u_damping: damping,
-        }, newPositionTexture);
-
-        // Step 5: Swap position buffers
-        var temp = lastPositionTexture;
-        lastPositionTexture = positionTexture;
-        positionTexture = newPositionTexture;
-        newPositionTexture = temp;
-    }
-
-    // Read back positions for rendering
-    gpuMath.readTexture(positionTexture, positionArray);
-    updateThreeJsGeometry(positionArray);
-}
-```
-
----
-
-## 6. Strain Computation & Visualization
-
-### How Strain Is Calculated
-
-Strain is computed per-beam (edge) as engineering strain, then averaged per-face for visualization:
-
-```glsl
-// strainCalcShader.frag (reconstructed)
-
-// Per beam: engineering strain
-float strain_beam = abs(currentLength - restLength) / restLength;
-
-// Per face: average strain of the face's three edges
-float faceStrain = (strain_e0 + strain_e1 + strain_e2) / 3.0;
-```
-
-```javascript
-// In the main code, strain per face:
-function computeFaceStrain(faceIndex) {
-    var edges = getFaceEdges(faceIndex);
-    var totalStrain = 0;
-    for (var i = 0; i < edges.length; i++) {
-        var beam = edges[i];
-        var nodeA = position[beam.nodeA];
-        var nodeB = position[beam.nodeB];
-        var currentLen = distance(nodeA, nodeB);
-        var restLen = beam.restLength;
-        totalStrain += Math.abs(currentLen - restLen) / restLen;
-    }
-    return totalStrain / edges.length;
-}
-```
-
-### Strain-to-Color Mapping
-
-```javascript
-// Strain visualization color mapping:
-// strain = 0.0   -->  blue   (no strain, faces undistorted)
-// strain = max    -->  red    (maximum strain, faces stretched/compressed)
-//
-// The mapping uses a HSL gradient:
-//   hue:        240 (blue) to 0 (red)
-//   saturation: 1.0 (fully saturated)
-//   lightness:  0.5
-
-function strainToColor(strain, maxStrain) {
-    var normalizedStrain = Math.min(strain / maxStrain, 1.0);
-
-    // HSL interpolation: blue (240) -> red (0)
-    var hue = (1.0 - normalizedStrain) * 240;
-
-    return hslToRgb(hue / 360, 1.0, 0.5);
-}
-
-// In the shader version (for GPU rendering):
-// vec3 color = vec3(strain, 0.0, 1.0 - strain);  // simplified R/B interpolation
-```
-
-### What Strain Tells You
-
-- **Zero strain**: The mesh is in its rest configuration — no edges are stretched or compressed. This is the ideal state for rigid origami.
-- **Low strain** (blue): The fold is progressing well with minimal face distortion. The crease pattern is compatible.
-- **High strain** (red): Faces are being stretched/compressed. This means either:
-  - The crease pattern is not rigidly foldable (faces MUST deform to accommodate the fold)
-  - The stiffness parameters are imbalanced
-  - Self-intersection is occurring
-
-**For RL reward signals**: Strain is an excellent reward component. Low global strain = good crease pattern. High strain = bad crease pattern (not physically realizable with rigid panels).
-
----
-
-## 7. Real FOLD File Examples
-
-### Example 1: Simple Blintz Base from OrigamiSimulator
-
-The `assets/fold/` directory contains several example FOLD files. Here is what a blintz-base crease pattern looks like:
-
-```json
-{
-    "file_spec": 1.1,
-    "file_creator": "Origami Simulator",
-    "file_classes": ["singleModel"],
-    "frame_title": "Blintz Base",
-    "frame_classes": ["creasePattern"],
-    "frame_attributes": ["2D"],
-    "vertices_coords": [
-        [0, 0],
-        [1, 0],
-        [1, 1],
-        [0, 1],
-        [0.5, 0.5],
-        [0.5, 0],
-        [1, 0.5],
-        [0.5, 1],
-        [0, 0.5]
-    ],
-    "edges_vertices": [
-        [0, 5], [5, 1], [1, 6], [6, 2],
-        [2, 7], [7, 3], [3, 8], [8, 0],
-        [0, 4], [1, 4], [2, 4], [3, 4],
-        [5, 4], [6, 4], [7, 4], [8, 4]
-    ],
-    "edges_assignment": [
-        "B", "B", "B", "B",
-        "B", "B", "B", "B",
-        "M", "V", "M", "V",
-        "V", "M", "V", "M"
-    ],
-    "edges_foldAngle": [
-        0, 0, 0, 0,
-        0, 0, 0, 0,
-        -180, 180, -180, 180,
-        180, -180, 180, -180
-    ],
-    "faces_vertices": [
-        [0, 5, 4], [5, 1, 4], [1, 6, 4], [6, 2, 4],
-        [2, 7, 4], [7, 3, 4], [3, 8, 4], [8, 0, 4]
-    ]
-}
-```
-
-**Statistics**: 9 vertices, 16 edges, 8 faces. This is a simplified bird base (blintz base).
-
-### Example 2: Miura-ori (3x3 grid) from OrigamiSimulator
-
-A Miura-ori pattern is a parametric tessellation. The simulator generates these programmatically:
-
-```json
-{
-    "file_spec": 1.1,
-    "file_creator": "Origami Simulator",
-    "frame_classes": ["creasePattern"],
-    "frame_attributes": ["2D"],
-    "vertices_coords": [
-        [0.0, 0.0], [1.0, 0.1], [2.0, 0.0], [3.0, 0.1],
-        [0.0, 1.0], [1.0, 0.9], [2.0, 1.0], [3.0, 0.9],
-        [0.0, 2.0], [1.0, 2.1], [2.0, 2.0], [3.0, 2.1],
-        [0.0, 3.0], [1.0, 2.9], [2.0, 3.0], [3.0, 2.9]
-    ],
-    "edges_vertices": [
-        [0,1],[1,2],[2,3],
-        [4,5],[5,6],[6,7],
-        [8,9],[9,10],[10,11],
-        [12,13],[13,14],[14,15],
-        [0,4],[4,8],[8,12],
-        [1,5],[5,9],[9,13],
-        [2,6],[6,10],[10,14],
-        [3,7],[7,11],[11,15],
-        [1,4],[2,5],[3,6],
-        [5,8],[6,9],[7,10],
-        [9,12],[10,13],[11,14]
-    ],
-    "edges_assignment": [
-        "B","B","B",
-        "M","M","M",
-        "V","V","V",
-        "B","B","B",
-        "B","M","V","B",
-        "V","M","V","M",
-        "V","M","V","M",
-        "V","V","V",
-        "V","V","V"
-    ],
-    "faces_vertices": [
-        [0,1,5,4],[1,2,6,5],[2,3,7,6],
-        [4,5,9,8],[5,6,10,9],[6,7,11,10],
-        [8,9,13,12],[9,10,14,13],[10,11,15,14]
-    ]
-}
-```
-
-**Statistics**: 16 vertices, ~30 edges, 9 quad faces (which triangulate to 18 triangles). The zigzag y-offsets (+0.1, -0.1) are the Miura-ori angle parameter.
-
-### Example 3: Waterbomb Base
-
-```json
-{
-    "file_spec": 1.1,
-    "frame_classes": ["creasePattern"],
-    "vertices_coords": [
-        [0, 0], [0.5, 0], [1, 0],
-        [0, 0.5], [0.5, 0.5], [1, 0.5],
-        [0, 1], [0.5, 1], [1, 1]
-    ],
-    "edges_vertices": [
-        [0,1],[1,2],[2,5],[5,8],[8,7],[7,6],[6,3],[3,0],
-        [0,4],[2,4],[8,4],[6,4],
-        [1,4],[5,4],[7,4],[3,4]
-    ],
-    "edges_assignment": [
-        "B","B","B","B","B","B","B","B",
-        "V","V","V","V",
-        "M","M","M","M"
-    ],
-    "faces_vertices": [
-        [0,1,4],[1,2,4],[2,5,4],[5,8,4],
-        [8,7,4],[7,6,4],[6,3,4],[3,0,4]
-    ]
-}
-```
-
-**Statistics**: 9 vertices, 16 edges, 8 triangular faces. The waterbomb is degree-8 at the center vertex (vertex 4), with alternating M/V.
-
-### Example 4: From the edemaine/fold Repository
-
-The `edemaine/fold` repo (`examples/` directory) contains several example files including:
-
-- `crane.fold` — traditional crane crease pattern
-- `square-twist.fold` — twist fold tessellation
-- Various test patterns for the FOLD spec
-
-A typical crane crease pattern from ORIPA/FOLD tools:
-
-```json
-{
-    "file_spec": 1.1,
-    "file_creator": "ORIPA",
-    "file_classes": ["singleModel"],
-    "frame_title": "Crane",
-    "frame_classes": ["creasePattern"],
-    "frame_attributes": ["2D"],
-    "vertices_coords": [
-        [0, 0], [200, 0], [400, 0],
-        [0, 200], [200, 200], [400, 200],
-        [0, 400], [200, 400], [400, 400]
-    ],
-    "edges_vertices": [[0,1],[1,2],[3,4],[4,5],[6,7],[7,8],
-                        [0,3],[3,6],[1,4],[4,7],[2,5],[5,8],
-                        [0,4],[4,8],[2,4],[4,6]],
-    "edges_assignment": ["B","B","B","M","B","B",
-                          "B","B","V","V","B","B",
-                          "M","M","V","V"],
-    "faces_vertices": [[0,1,4,3],[1,2,5,4],[3,4,7,6],[4,5,8,7]]
-}
-```
-
-### Typical Model Complexity in Practice
-
-| Model | Vertices | Edges | Faces | Triangulated Faces |
-|-------|----------|-------|-------|--------------------|
-| Simple base (blintz) | 9 | 16 | 8 | 8 |
-| Waterbomb base | 9 | 16 | 8 | 8 |
-| Traditional crane | 50-80 | 100-150 | 60-100 | 120-200 |
-| Miura-ori 3x3 | 16 | ~30 | 9 | 18 |
-| Miura-ori 10x10 | 121 | ~340 | 100 | 200 |
-| Complex tessellation | 200-500 | 500-1500 | 300-1000 | 600-2000 |
-| Extreme models | 1000+ | 3000+ | 2000+ | 4000+ |
-
-**Key insight**: Even complex origami models rarely exceed a few thousand vertices. The GPU solver handles up to ~10,000 nodes at interactive rates.
-
----
-
-## 8. Minimal FOLD Representation for Our RL Environment
-
-### What We Actually Need
-
-Based on how OrigamiSimulator uses FOLD, here is the minimal representation:
-
-```python
-# Minimal FOLD state for RL environment
-minimal_fold = {
-    # REQUIRED - the geometry
-    "vertices_coords": [[x, y], ...],        # 2D coords (flat crease pattern)
-    "edges_vertices": [[v_i, v_j], ...],      # edge connectivity
-    "edges_assignment": ["M", "V", "B", ...], # fold type per edge
-
-    # RECOMMENDED - explicit angle targets
-    "edges_foldAngle": [-180, 180, 0, ...],   # target fold angles (degrees)
-
-    # RECOMMENDED - explicit faces
-    "faces_vertices": [[v0, v1, v2, ...], ...], # face polygons (CCW)
-
-    # METADATA
-    "frame_classes": ["creasePattern"],
-    "frame_attributes": ["2D"],
-}
-```
-
-### What We Can Skip
-
-| Field | Skip? | Reason |
-|-------|-------|--------|
-| `faceOrders` | YES | Physics simulation handles layer ordering |
-| `vertices_vertices` | YES | Recomputed from edges |
-| `edges_faces` | YES | Recomputed from edges + faces |
-| `faces_edges` | YES | Recomputed from faces + edges |
-| `vertices_edges` | YES | Recomputed |
-| `file_spec`, `file_creator` | YES | Metadata only |
-
-### Python Data Structure for RL State
-
-```python
-import numpy as np
-from dataclasses import dataclass
-from typing import List, Optional
-
-@dataclass
-class OrigamiFOLDState:
-    """Minimal FOLD state for RL environment."""
-
-    # Core geometry
-    vertices_coords: np.ndarray      # shape (num_vertices, 2) or (num_vertices, 3)
-    edges_vertices: np.ndarray       # shape (num_edges, 2), dtype int
-    edges_assignment: List[str]      # length num_edges, values in {"M","V","B","F","U"}
-
-    # Optional but recommended
-    edges_foldAngle: Optional[np.ndarray] = None  # shape (num_edges,), degrees
-    faces_vertices: Optional[List[List[int]]] = None  # ragged list of vertex indices
-
-    def to_fold_json(self) -> dict:
-        """Export as FOLD JSON dict."""
-        fold = {
-            "file_spec": 1.1,
-            "frame_classes": ["creasePattern"],
-            "frame_attributes": ["2D"],
-            "vertices_coords": self.vertices_coords.tolist(),
-            "edges_vertices": self.edges_vertices.tolist(),
-            "edges_assignment": self.edges_assignment,
-        }
-        if self.edges_foldAngle is not None:
-            fold["edges_foldAngle"] = self.edges_foldAngle.tolist()
-        if self.faces_vertices is not None:
-            fold["faces_vertices"] = self.faces_vertices
-        return fold
-
-    @classmethod
-    def from_fold_json(cls, data: dict) -> "OrigamiFOLDState":
-        """Import from FOLD JSON dict."""
-        coords = np.array(data["vertices_coords"], dtype=np.float64)
-        if coords.shape[1] == 2:
-            coords = np.hstack([coords, np.zeros((len(coords), 1))])
-        edges = np.array(data["edges_vertices"], dtype=np.int32)
-        assignments = data.get("edges_assignment", ["U"] * len(edges))
-        fold_angles = None
-        if "edges_foldAngle" in data:
-            fold_angles = np.array(data["edges_foldAngle"], dtype=np.float64)
-        faces = data.get("faces_vertices", None)
-        return cls(
-            vertices_coords=coords,
-            edges_vertices=edges,
-            edges_assignment=assignments,
-            edges_foldAngle=fold_angles,
-            faces_vertices=faces,
-        )
-
-    @property
-    def num_vertices(self) -> int:
-        return len(self.vertices_coords)
-
-    @property
-    def num_edges(self) -> int:
-        return len(self.edges_vertices)
-
-    @property
-    def num_mountain(self) -> int:
-        return self.edges_assignment.count("M")
-
-    @property
-    def num_valley(self) -> int:
-        return self.edges_assignment.count("V")
-
-    @property
-    def num_boundary(self) -> int:
-        return self.edges_assignment.count("B")
-```
-
-### Observation Space Encoding for RL
-
-```python
-# How to encode FOLD state as a fixed-size observation for RL:
-
-# Option 1: Adjacency + feature matrix (for GNN-based policies)
-# Node features: [x, y, z, is_boundary, is_interior, degree]
-# Edge features: [assignment_onehot(5), fold_angle, edge_length]
-
-# Option 2: Flattened fixed-size grid (for MLP/CNN policies)
-# Discretize the unit square into an NxN grid
-# Each cell stores: [has_vertex, has_M_edge, has_V_edge, has_B_edge]
-
-# Option 3: Variable-length sequence (for transformer policies)
-# Sequence of edge tokens: [v_i, v_j, assignment, fold_angle]
-```
-
----
-
-## 9. Summary: How the Simulator Actually Works (End-to-End)
-
-1. **Load FOLD file** -> parse `vertices_coords`, `edges_vertices`, `edges_assignment`, `faces_vertices`
-2. **Triangulate** non-triangular faces via ear-clipping -> creates new internal edges
-3. **Classify edges** -> fold creases (M/V with target angles), facet hinges (flat target, high stiffness), boundary (no constraint)
-4. **Build GPU textures** -> pack node positions, beam params, crease params into RGBA float textures
-5. **Run solver loop** (per frame, ~100 iterations):
-   - Compute beam forces (axial springs prevent stretching)
-   - Compute crease forces (rotational springs drive folding / enforce flatness)
-   - Verlet integration with damping to update positions
-6. **Compute strain** -> per-edge engineering strain = |L - L0| / L0, averaged per face
-7. **Render** -> Three.js mesh colored by strain (blue=zero, red=max)
-8. **User adjusts `foldPercent`** (0 to 1) -> target angles scale linearly -> solver re-converges
-
-### Key Numerical Details
-
-- **Timestep**: dt = 0.02 (small for stability)
-- **Damping**: 0.1 (overdamped to reach equilibrium quickly)
-- **Iterations per frame**: 100 (enough for incremental convergence)
-- **Stiffness ratio**: axial >> facet > fold (prevents stretching while allowing controlled folding)
-- **Convergence criterion**: total kinetic energy < threshold
-
-### For Our RL Environment
-
-The critical takeaway: **we do NOT need GPU shaders**. For an RL training loop, a NumPy/JAX port of the bar-and-hinge solver is sufficient:
-
-```python
-# Pseudocode for our NumPy port:
-
-def simulate_fold(fold_state, fold_percent, n_steps=1000):
-    """Simulate folding and return final positions + strain."""
-    pos = fold_state.vertices_coords.copy()  # (N, 3)
-    last_pos = pos.copy()
-    dt = 0.02
-    damping = 0.1
-
-    for step in range(n_steps):
-        forces = np.zeros_like(pos)
-
-        # Beam forces (vectorized over all edges)
-        forces += compute_beam_forces(pos, edges, rest_lengths, k_axial)
-
-        # Crease forces (vectorized over all creases)
-        forces += compute_crease_forces(pos, creases, target_angles * fold_percent,
-                                         k_fold, k_facet)
-
-        # Verlet integration
-        new_pos = pos + (1 - damping) * (pos - last_pos) + forces * dt**2
-        last_pos = pos
-        pos = new_pos
-
-    strain = compute_strain(pos, edges, rest_lengths)
-    return pos, strain
-```
-
-This gives us the same physics as OrigamiSimulator but in Python, suitable for vectorized RL training with JAX/NumPy.

research 2/origami/physics.md

@@ -1,37 +0,0 @@
-# Physics of Paper Folding
-
-## Fundamental Theorems
-
-### Kawasaki's Theorem (Angles)
-- At a single vertex, flat-foldable iff alternating angle sums = 180 on each side
-- **Necessary but not sufficient** for global flat-foldability
-- Use as: reward penalty for violation
-
-### Maekawa's Theorem (Mountain/Valley Count)
-- At any flat-fold vertex: `|M - V| = 2`
-- Total creases at a vertex must be **even**
-- Use as: hard constraint in action validation
-
-### Global Flat-Foldability
-- **NP-complete** (Bern & Hayes, 1996)
-- Hardness comes from determining valid **layer ordering**
-- Local conditions (Kawasaki + Maekawa) necessary but not sufficient
-- Use as: approximate via constraint satisfaction for reward
-
-### Rigid Foldability
-- Can it fold from flat to folded state with rigid panels (no face bending)?
-- Critical for engineering: metal, plastic panels must be rigid
-- Checked via: triangle-triangle intersection + rigid body constraints
-- Use as: pass/fail validation check
-
-## Layer Ordering
-- When paper folds flat, layers stack — which face is above which?
-- Must satisfy: no face penetration
-- FOLD format: `faceOrders` triples `[f, g, s]`
-- This is the NP-hard part — approximate for RL
-
-## Simulation Approaches (Ranked for RL Use)
-
-1. **Bar-and-hinge** (Ghassaei) — edges as bars, rotational springs at hinges. Fast. Best for RL.
-2. **Rigid body + compliant creases** — rigid panels, torsional spring creases. Good middle ground.
-3. **FEM** — full stress/strain tensor. Accurate but too slow for RL training loop.

research 2/origami/python_tools.md

@@ -1,45 +0,0 @@
-# Python Libraries for Origami RL
-
-## Origami-Specific
-
-### rigid-origami (TOP PICK)
-- **GitHub**: https://github.com/belalugaX/rigid-origami
-- Gym environment for origami design as board game
-- Has: PPO, MCTS, evolutionary, BFS, DFS agents
-- Has: triangle-triangle intersection + kinematic validation
-- Has: action masking, symmetry enforcement
-- Output: PNG patterns, OBJ models, GIF animations
-- Install: conda env + `pip install gym-rori`
-
-### PyOri
-- `pip3 install pyori`
-- Graph-based crease pattern generation
-- Huzita-Justin axiom implementation
-- Flat-foldability checks
-- FOLD + SVG export
-- Dependencies: numpy, matplotlib, scipy
-
-### FoldZ
-- https://github.com/generic-github-user/FoldZ
-- Early development, ambitious scope, not production-ready
-
-## Supporting Libraries
-
-| Library | What We Use It For |
-|---------|-------------------|
-| **numpy** | Core geometry, linear algebra |
-| **scipy** | Constraint solving, optimization, spatial queries |
-| **trimesh** | Mesh ops, collision detection, STL/OBJ I/O |
-| **matplotlib** | 2D crease pattern visualization |
-| **plotly** | 3D interactive visualization (Gradio-compatible) |
-| **networkx** | Crease pattern graph analysis |
-| **shapely** | 2D polygon operations, area calculations |
-| **gymnasium** | RL environment API standard |
-
-## Key Sources
-
-- [Ghassaei Simulator](https://github.com/amandaghassaei/OrigamiSimulator) — MIT, JS/WebGL
-- [FOLD format](https://github.com/edemaine/fold) — JSON standard
-- [TreeMaker](https://langorigami.com/article/treemaker/) — crease pattern from tree diagrams
-- [SWOMPS](https://github.com/zzhuyii/OrigamiSimulator) — MATLAB multi-physics reference
-- [Tachi's tools](https://origami.c.u-tokyo.ac.jp/~tachi/software/) — foundational algorithms

research 2/origami/rendering_research.md

@@ -1,863 +0,0 @@
-# Origami Rendering & Visualization Research
-
-## 1. Existing Open-Source Origami Renderers
-
-### 1.1 Amanda Ghassaei's Origami Simulator (Best-in-Class)
-
-- **GitHub**: https://github.com/amandaghassaei/OrigamiSimulator
-- **Live demo**: https://origamisimulator.org/
-- **License**: MIT
-- **Tech stack**: Three.js (rendering), GPU fragment shaders (simulation), FOLD format (data)
-- **Paper**: "Fast, Interactive Origami Simulation using GPU Computation" (7OSME)
-
-**How the simulation works:**
-- Folds all creases simultaneously (not sequential folding)
-- Iteratively solves for small displacements due to forces from creases
-- Three constraint types: distance (no stretch/compress), face (no shear), angular (fold/flatten)
-- Each constraint weighted by stiffness parameter
-- All computation in GPU fragment shaders for real-time performance
-- Target fold angle per crease: [-180, 180] degrees (positive=valley, negative=mountain)
-
-**Strain visualization:**
-- Maps strain to vertex colors: blue (no strain) to red (max strain)
-- Strain = average percent deviation of distance constraints (Cauchy/engineering strain)
-
-**I/O formats**: SVG, FOLD input; FOLD, STL, OBJ export
-
-**Embedding in React:**
-- Not published as an npm package; no React component wrapper exists
-- Would need to fork and extract the core simulation + Three.js rendering
-- The Three.js scene setup is tightly coupled to the app's DOM/UI
-- **Best approach**: extract the GPU solver + mesh rendering and wrap in R3F
-
-**External libraries used:**
-- svgpath + path-data-polyfill (SVG parsing)
-- FOLD library (internal data structure)
-- Earcut (triangulation)
-- Three.js (rendering)
-
-### 1.2 OrigamiOdyssey (React + R3F -- Closest to What We Need)
-
-- **GitHub**: https://github.com/robbwdoering/origamiodyssey
-- **Tech stack**: React SPA, Three.js via react-three-fiber, hierarchical instructions
-- **What it does**: Teaches origami via 3D simulations, step-through instructions, free rotation
-- **Key relevance**: Proves that origami can be rendered well with R3F
-- Already uses react-three-fiber to render a mesh representing paper
-- Supports step-through fold sequences with 3D rotation
-
-### 1.3 georgiee/origami (Three.js Origami Builder)
-
-- **GitHub**: https://github.com/georgiee/origami
-- **Demo**: https://georgiee.github.io/origami/
-- **What it does**: Runtime origami folding rendered in Three.js
-- Has an editor mode and view mode
-- Not React-based, but demonstrates the mesh-folding-along-crease approach
-
-### 1.4 flat-folder (Jason S. Ku -- Computation Tool)
-
-- **GitHub**: https://github.com/origamimagiro/flat-folder
-- **What it does**: Computes and analyzes valid flat-foldable states
-- Renders three simultaneous views: crease pattern, x-ray overlap, folded state
-- Supports FOLD, SVG, OPX, CP input formats
-- Highlights Maekawa/Kawasaki violations with red circles
-- **Not a library** -- standalone web app, not embeddable
-- Useful as a reference for rendering conventions
-
-### 1.5 Crease Pattern Editor (mwalczyk/crease)
-
-- **GitHub**: https://github.com/mwalczyk/crease
-- Vector-based SVG line drawing tool for crease patterns
-- Geometric operations for diagramming
-- Returns lists of changed nodes/edges for SVG element updates
-
-### 1.6 Other Notable Projects
-
-| Project | URL | Notes |
-|---------|-----|-------|
-| OriDomi | http://oridomi.com/ | CSS/DOM paper folding effects, not 3D simulation |
-| paperfold.js | https://github.com/mrflix/paperfold | CSS3 transitions for paper fold UI effects |
-| Origami3D | https://github.com/mariusGundersen/Origami3D | Simple 3D engine using 2D canvas, minimal |
-| CurvedCreases | https://github.com/amandaghassaei/CurvedCreases | Amanda Ghassaei's curved crease simulator |
-
----
-
-## 2. Three.js in React
-
-### 2.1 @react-three/fiber (R3F)
-
-- **GitHub**: https://github.com/pmndrs/react-three-fiber
-- **Docs**: https://r3f.docs.pmnd.rs/
-- The standard way to use Three.js in React
-- Declarative scene graph via JSX
-- `useFrame` hook for per-frame updates (animation, simulation stepping)
-- `useThree` hook for accessing renderer, scene, camera
-- Full Three.js API available through refs
-
-**Key pattern for origami:**
-```jsx
-<Canvas gl={{ preserveDrawingBuffer: true }}>
-  <PerspectiveCamera makeDefault position={[0, 5, 10]} />
-  <OrbitControls />
-  <mesh ref={paperMeshRef}>
-    <bufferGeometry>
-      <bufferAttribute attach="attributes-position" ... />
-      <bufferAttribute attach="attributes-color" ... />
-    </bufferGeometry>
-    <meshStandardMaterial vertexColors side={DoubleSide} />
-  </mesh>
-</Canvas>
-```
-
-### 2.2 @react-three/drei
-
-- **GitHub**: https://github.com/pmndrs/drei
-- **Docs**: https://drei.docs.pmnd.rs/
-- Provides: `OrbitControls`, `PerspectiveCamera`, `Html`, `Line`, `Text`, `Grid`, `Environment`
-- `OrbitControls` -- rotate, zoom, pan the 3D view (essential for our rotatable viewer)
-- `Line` / `meshline` -- for rendering crease lines in 3D
-
-### 2.3 Rendering a Foldable Mesh
-
-**Approach: Vertex manipulation on BufferGeometry**
-
-The paper mesh is a `BufferGeometry` with a position attribute. To simulate folding:
-
-1. Define crease lines as edges in the mesh
-2. For each fold operation, identify vertices on one side of the crease
-3. Apply a rotation (quaternion) to those vertices around the crease line axis
-4. Update the position buffer: `geometry.attributes.position.needsUpdate = true`
-
-**Implementation pattern:**
-```javascript
-// For a fold along a crease line from point A to point B:
-const axis = new THREE.Vector3().subVectors(B, A).normalize();
-const quaternion = new THREE.Quaternion().setFromAxisAngle(axis, foldAngle);
-
-for (let i = 0; i < vertexCount; i++) {
-  if (isOnFoldSide(vertices[i], creaseLine)) {
-    const v = new THREE.Vector3(positions[i*3], positions[i*3+1], positions[i*3+2]);
-    v.sub(A);  // translate to crease origin
-    v.applyQuaternion(quaternion);  // rotate
-    v.add(A);  // translate back
-    positions[i*3] = v.x;
-    positions[i*3+1] = v.y;
-    positions[i*3+2] = v.z;
-  }
-}
-geometry.attributes.position.needsUpdate = true;
-```
-
-**For simultaneous folding (Ghassaei approach):**
-- Use a spring/constraint solver running per-frame in `useFrame`
-- Each crease exerts angular force toward its target fold angle
-- Distance constraints prevent stretch, face constraints prevent shear
-- This is more physically accurate but computationally heavier
-- Could be done in a Web Worker or WASM for performance
-
-### 2.4 Color-Coding Strain with Vertex Colors
-
-**Three.js Lut (Lookup Table) class:**
-- Import: `import { Lut } from 'three/addons/math/Lut.js'`
-- Built-in colormaps: `rainbow`, `cooltowarm`, `blackbody`, `grayscale`
-- For strain: use `cooltowarm` (blue to red) or create custom colormap
-
-**Implementation:**
-```javascript
-const lut = new Lut('cooltowarm', 512);
-lut.setMin(0);    // no strain
-lut.setMax(maxStrain);
-
-// For each vertex, compute strain and get color
-const colors = new Float32Array(vertexCount * 3);
-for (let i = 0; i < vertexCount; i++) {
-  const strain = computeVertexStrain(i);
-  const color = lut.getColor(strain);
-  colors[i * 3] = color.r;
-  colors[i * 3 + 1] = color.g;
-  colors[i * 3 + 2] = color.b;
-}
-
-geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
-// Material must have vertexColors: true
-```
-
-**In R3F JSX:**
-```jsx
-<mesh>
-  <bufferGeometry>
-    <bufferAttribute
-      attach="attributes-position"
-      array={positions}
-      count={vertexCount}
-      itemSize={3}
-    />
-    <bufferAttribute
-      attach="attributes-color"
-      array={colors}
-      count={vertexCount}
-      itemSize={3}
-    />
-  </bufferGeometry>
-  <meshStandardMaterial vertexColors side={THREE.DoubleSide} />
-</mesh>
-```
-
-**Alternative: Shader-based heatmap**
-- Custom `ShaderMaterial` with a uniform for strain data
-- Map strain to color in fragment shader
-- More performant for large meshes, but more complex to implement
-
----
-
-## 3. Lightweight Rendering Approach for RL
-
-### 3.1 What We Need
-
-| Requirement | Priority | Approach |
-|-------------|----------|----------|
-| Live view of current fold state | High | Client-side R3F in Gradio |
-| Periodic screenshots for training logs | High | `canvas.toDataURL()` or server-side matplotlib |
-| Recording folding animation | Medium | CCapture.js / MediaRecorder API |
-| Strain heatmap overlay | High | Vertex colors with Lut |
-| Crease pattern 2D view | High | SVG (inline or via React component) |
-
-### 3.2 Server-Side Rendering Options
-
-**Option A: matplotlib 3D (Simplest, Recommended for RL Training)**
-- `mpl_toolkits.mplot3d` for basic 3D wireframe/surface plots
-- Good enough for training logs and periodic state snapshots
-- `fig.savefig()` for PNG export
-- Works headlessly on any server
-- No GPU required
-
-**Option B: Plotly 3D**
-- `plotly.graph_objects.Mesh3d` for 3D mesh rendering
-- Interactive HTML output embeddable in Gradio
-- `fig.write_image()` for static export (requires kaleido)
-- Better looking than matplotlib, still no GPU needed
-
-**Option C: Headless Three.js (Node.js)**
-- Uses `headless-gl` library for offscreen WebGL
-- Full Three.js rendering fidelity
-- Significant caveats:
-  - Most servers lack GPU, so rendering uses CPU (slow)
-  - `headless-gl` has compatibility issues with newer Three.js
-  - Requires JSDOM or `three-universal` for DOM mocking
-  - Complex setup for questionable benefit
-- **Not recommended** unless visual fidelity is critical server-side
-
-**Option D: trimesh + pyrender (Python)**
-- `trimesh` for mesh manipulation, `pyrender` for offscreen rendering
-- Better 3D quality than matplotlib
-- Supports headless via EGL or osmesa
-- Good middle ground
-
-**Recommendation: matplotlib for training, Plotly/R3F for demo UI**
-
-### 3.3 Client-Side Rendering (Primary for Demo)
-
-**React + Three.js via R3F:**
-- Best visual quality, real-time interactivity
-- OrbitControls for rotation, zoom, pan
-- Vertex colors for strain heatmap
-- Runs in user's browser (GPU-accelerated)
-
-### 3.4 Screenshots from Three.js
-
-**Configuration:**
-```jsx
-<Canvas gl={{ preserveDrawingBuffer: true, antialias: true, alpha: true }}>
-```
-
-**Capture method:**
-```javascript
-// Inside a component with access to useThree()
-const { gl, scene, camera } = useThree();
-
-function captureScreenshot() {
-  gl.render(scene, camera);
-  const dataURL = gl.domElement.toDataURL('image/png');
-  // Send to server or download
-  return dataURL;
-}
-```
-
-**Important:** `toDataURL()` must be called before exiting the current event/frame. The `preserveDrawingBuffer: true` flag is required or you get a black image. Keeping it enabled has minor performance cost.
-
-**High-resolution capture:**
-```javascript
-// Temporarily increase pixel ratio for hi-res screenshot
-const originalPixelRatio = gl.getPixelRatio();
-gl.setPixelRatio(window.devicePixelRatio * 2);
-gl.setSize(width * 2, height * 2);
-gl.render(scene, camera);
-const dataURL = gl.domElement.toDataURL('image/png');
-gl.setPixelRatio(originalPixelRatio);
-gl.setSize(width, height);
-```
-
-### 3.5 Recording Folding Animation
-
-**Option A: CCapture.js (Best for frame-perfect capture)**
-- **GitHub**: https://github.com/spite/ccapture.js
-- Hooks into `requestAnimationFrame`, `Date.now()`, `setTimeout`
-- Forces constant time step for stutter-free recording
-- Supports WebM, PNG/JPEG tar, GIF
-- Usage:
-  ```javascript
-  const capturer = new CCapture({ format: 'webm', framerate: 30, quality: 95 });
-  capturer.start();
-  // In render loop:
-  capturer.capture(canvas);
-  // When done:
-  capturer.stop();
-  capturer.save(); // triggers download
-  ```
-
-**Option B: use-capture (R3F wrapper for CCapture.js)**
-- **GitHub**: https://github.com/gsimone/use-capture
-- npm: `use-capture`
-- Hook-based API for R3F
-- Note: GIF export reportedly broken; WebM works
-- Usage:
-  ```javascript
-  const [bind, startRecording] = useCapture({ duration: 4, fps: 30 });
-  // <Canvas {...bind} gl={{ preserveDrawingBuffer: true }}>
-  ```
-
-**Option C: MediaRecorder API (Browser-native)**
-- No library needed
-- `canvas.captureStream(30)` + `MediaRecorder`
-- Outputs WebM or MP4 (codec support varies by browser)
-- Less control over frame timing than CCapture.js
-- Usage:
-  ```javascript
-  const stream = canvas.captureStream(30);
-  const recorder = new MediaRecorder(stream, { mimeType: 'video/webm' });
-  recorder.start();
-  // Later:
-  recorder.stop();
-  recorder.ondataavailable = (e) => { /* save e.data blob */ };
-  ```
-
-**Option D: Server-side GIF from matplotlib frames**
-- Generate PNG frames server-side with matplotlib
-- Assemble with `imageio` or `PIL` into GIF
-- Lower quality but works without browser
-- Good for training log animations
-
----
-
-## 4. Gradio + React in HuggingFace Spaces
-
-### 4.1 Gradio gr.HTML with Custom JavaScript (Recommended for Hackathon)
-
-Gradio 6 introduced powerful `gr.HTML` customization. This is the fastest path to embedding Three.js in a Gradio app.
-
-**How it works:**
-- `html_template`: Handlebars (`{{}}`) or JS expression (`${}`) syntax
-- `css_template`: Scoped CSS for the component
-- `js_on_load`: JavaScript that runs when the component loads
-- `server_functions`: Python functions callable from JS via `await server.func_name()`
-- `@children`: Placeholder for embedding other Gradio components
-
-**Three.js in gr.HTML pattern:**
-```python
-import gradio as gr
-
-class OrigamiViewer(gr.HTML):
-    def __init__(self, **kwargs):
-        super().__init__(
-            html_template="""
-                <div id="origami-3d" style="width:100%; height:500px;"></div>
-            """,
-            js_on_load="""
-                // Load Three.js from CDN
-                const script = document.createElement('script');
-                script.src = 'https://unpkg.com/three@0.160.0/build/three.module.js';
-                script.type = 'module';
-                // ... set up scene, camera, renderer, mesh
-                // Access props.value for fold state data from Python
-            """,
-            css_template="""
-                #origami-3d { border: 1px solid #ccc; border-radius: 8px; }
-            """,
-            server_functions=[get_fold_state],
-            **kwargs
-        )
-```
-
-**Data flow:**
-- Python sets `props.value` with fold state data (JSON)
-- JS reads `props.value` and updates the Three.js scene
-- JS can call `await server.func_name(args)` to invoke Python functions
-- JS can set `props.value = newData` and call `trigger()` to send data back
-
-### 4.2 Gradio Custom Components (Full npm Package)
-
-For a more polished, reusable component:
-
-```bash
-gradio cc create OrigamiViewer --template SimpleTextbox
-```
-
-This creates:
-```
-origami_viewer/
-  backend/            # Python component code
-  frontend/           # Svelte/JS component (can include React/Three.js)
-  demo/               # Example app
-  pyproject.toml
-```
-
-- Frontend is Svelte by default but can import any JS library
-- Can include React + R3F as dependencies in the frontend build
-- Published to PyPI, installable with `pip install`
-- More work but produces a proper reusable component
-
-### 4.3 Gradio Model3D Component (Built-in but Limited)
-
-Gradio has a built-in `gr.Model3D` component:
-```python
-gr.Model3D(value="model.glb", label="3D View")
-```
-- Supports GLB, GLTF, OBJ, STL
-- Has built-in viewer with rotation/zoom
-- **Limitations**: No custom vertex colors, no animation, no strain overlay
-- Could work for static final-state display only
-
-### 4.4 Alternative: Static React App + FastAPI Backend
-
-**Architecture:**
-```
-origami-space/
-  Dockerfile
-  backend/
-    app.py            # FastAPI server (OpenEnv + API endpoints)
-  frontend/
-    src/
-      App.tsx         # React app with R3F
-    dist/             # Built static files
-```
-
-**FastAPI serves both:**
-```python
-from fastapi.staticfiles import StaticFiles
-app.mount("/", StaticFiles(directory="frontend/dist", html=True), name="frontend")
-```
-
-**Pros:**
-- Full React + R3F with all features (OrbitControls, vertex colors, animation)
-- Complete control over UI layout
-- No Gradio limitations
-
-**Cons:**
-- Doesn't use Gradio (may not match hackathon expectations)
-- More setup work
-- Need to handle WebSocket connection to OpenEnv manually
-
-### 4.5 Alternative: Streamlit + Custom Component
-
-- `streamlit.components.v1.components.html()` can embed HTML/JS
-- `streamlit-stl` component exists for 3D model display
-- Three.js can be embedded via HTML string injection
-- Less mature than Gradio for HF Spaces
-- **Not recommended** unless Gradio proves insufficient
-
-### 4.6 Deployment on HuggingFace Spaces
-
-**Docker Space (most flexible):**
-```yaml
-# README.md header
----
-title: Origami RL
-sdk: docker
-app_port: 7860
----
-```
-
-**Static Space (for React-only frontend):**
-```yaml
----
-title: Origami Viewer
-sdk: static
----
-```
-- Supports build steps: `npm run build`
-- Serves built files directly
-
-**Recommended approach**: Docker Space with FastAPI serving both the OpenEnv server and a Gradio UI that uses `gr.HTML` for the Three.js viewer.
-
----
-
-## 5. Crease Pattern 2D Rendering
-
-### 5.1 Standard Origami Conventions
-
-| Edge Type | Color | Line Style | FOLD Assignment |
-|-----------|-------|------------|-----------------|
-| Mountain fold | Red | Dashed (dash-dot-dot) | "M" |
-| Valley fold | Blue | Dashed | "V" |
-| Boundary | Black | Solid | "B" |
-| Unassigned | Gray | Dotted | "U" |
-| Flat/crease | Gray | Solid thin | "F" |
-
-**Note:** There is no universally standardized convention. The above is the most common in computational origami tools. Ghassaei's simulator uses: red=mountain, blue=valley, black=boundary. Flat-folder uses the same convention for SVG import.
-
-**FOLD format edge assignments:**
-- `edges_assignment`: Array of "M", "V", "B", "U", "F"
-- `edges_foldAngle`: Array of numbers in [-180, 180] (positive=valley, negative=mountain, 0=flat/boundary)
-
-### 5.2 SVG Rendering (Recommended for 2D View)
-
-**Direct SVG in React:**
-```jsx
-function CreasePatternSVG({ vertices, edges, assignments }) {
-  const getEdgeStyle = (assignment) => {
-    switch (assignment) {
-      case 'M': return { stroke: '#e74c3c', strokeDasharray: '8,3,2,3', strokeWidth: 2 };
-      case 'V': return { stroke: '#3498db', strokeDasharray: '6,3', strokeWidth: 2 };
-      case 'B': return { stroke: '#2c3e50', strokeDasharray: 'none', strokeWidth: 2.5 };
-      case 'U': return { stroke: '#95a5a6', strokeDasharray: '2,4', strokeWidth: 1 };
-      case 'F': return { stroke: '#bdc3c7', strokeDasharray: 'none', strokeWidth: 0.5 };
-    }
-  };
-
-  return (
-    <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
-      {edges.map(([v1, v2], i) => {
-        const style = getEdgeStyle(assignments[i]);
-        return (
-          <line
-            key={i}
-            x1={vertices[v1][0]} y1={vertices[v1][1]}
-            x2={vertices[v2][0]} y2={vertices[v2][1]}
-            {...style}
-          />
-        );
-      })}
-      {vertices.map(([x, y], i) => (
-        <circle key={i} cx={x} cy={y} r={0.5} fill="#333" />
-      ))}
-    </svg>
-  );
-}
-```
-
-### 5.3 SVG in Python (Server-Side, for matplotlib/Gradio)
-
-```python
-import svgwrite
-
-def render_crease_pattern_svg(fold_data: dict) -> str:
-    """Render FOLD data as SVG string."""
-    vertices = fold_data['vertices_coords']
-    edges = fold_data['edges_vertices']
-    assignments = fold_data.get('edges_assignment', ['U'] * len(edges))
-
-    STYLES = {
-        'M': {'stroke': 'red', 'stroke_dasharray': '8,3,2,3', 'stroke_width': 2},
-        'V': {'stroke': 'blue', 'stroke_dasharray': '6,3', 'stroke_width': 2},
-        'B': {'stroke': 'black', 'stroke_dasharray': 'none', 'stroke_width': 2.5},
-        'U': {'stroke': 'gray', 'stroke_dasharray': '2,4', 'stroke_width': 1},
-        'F': {'stroke': 'lightgray', 'stroke_dasharray': 'none', 'stroke_width': 0.5},
-    }
-
-    dwg = svgwrite.Drawing(size=('400px', '400px'), viewBox='0 0 1 1')
-    for (v1, v2), asgn in zip(edges, assignments):
-        style = STYLES.get(asgn, STYLES['U'])
-        dwg.add(dwg.line(
-            start=vertices[v1], end=vertices[v2],
-            **style
-        ))
-    return dwg.tostring()
-```
-
-### 5.4 matplotlib for 2D Crease Pattern (Quickest Python Path)
-
-```python
-import matplotlib.pyplot as plt
-import matplotlib.lines as mlines
-
-def plot_crease_pattern(fold_data, ax=None):
-    if ax is None:
-        fig, ax = plt.subplots(1, 1, figsize=(6, 6))
-
-    vertices = fold_data['vertices_coords']
-    edges = fold_data['edges_vertices']
-    assignments = fold_data.get('edges_assignment', ['U'] * len(edges))
-
-    STYLES = {
-        'M': dict(color='red', linestyle='--', linewidth=2),
-        'V': dict(color='blue', linestyle='-.', linewidth=2),
-        'B': dict(color='black', linestyle='-', linewidth=2.5),
-        'U': dict(color='gray', linestyle=':', linewidth=1),
-        'F': dict(color='lightgray', linestyle='-', linewidth=0.5),
-    }
-
-    for (v1, v2), asgn in zip(edges, assignments):
-        p1, p2 = vertices[v1], vertices[v2]
-        style = STYLES.get(asgn, STYLES['U'])
-        ax.plot([p1[0], p2[0]], [p1[1], p2[1]], **style)
-
-    ax.set_aspect('equal')
-    ax.set_title('Crease Pattern')
-    return ax
-```
-
-### 5.5 D3.js Option (Overkill for Our Needs)
-
-D3.js could render crease patterns with full interactivity (hover tooltips, click-to-fold, zoom/pan), but:
-- Adds another large dependency
-- SVG-in-React is simpler and sufficient
-- D3 is better for complex data visualization, not needed for line drawings
-- **Skip D3 unless we need interactive editing of crease patterns**
-
----
-
-## 6. UI Layout & Component Architecture
-
-### 6.1 Proposed Layout
-
-```
-+------------------------------------------------------------------+
-|  ORIGAMI RL ENVIRONMENT                          [Material: ▼]   |
-+------------------------------------------------------------------+
-|                          |                                        |
-|   CREASE PATTERN (2D)   |          FOLDED STATE (3D)             |
-|                          |                                        |
-|   [SVG View]             |    [Three.js R3F Canvas]              |
-|   Mountain = red ---     |    OrbitControls (rotate/zoom)        |
-|   Valley  = blue -.-     |    Vertex colors = strain heatmap    |
-|   Border  = black ___    |    DoubleSide material               |
-|                          |                                        |
-|   Scale: 1m x 1m         |    Camera: perspective, 45deg        |
-|                          |                                        |
-+------------------------------------------------------------------+
-|                                                                    |
-|   FOLD SEQUENCE                 METRICS DASHBOARD                 |
-|   [Step 1] [Step 2] ...        Compactness: 0.85                 |
-|   [Play] [Pause] [Reset]       Fold count: 12                    |
-|   Progress: ████░░ 4/8         Max strain: 0.03                  |
-|                                 Validity: PASS                    |
-|                                 Deploy ratio: 15.2x              |
-|                                                                    |
-+------------------------------------------------------------------+
-```
-
-### 6.2 Component Breakdown
-
-**For Gradio + gr.HTML approach:**
-
-| Component | Implementation | Data Source |
-|-----------|---------------|-------------|
-| 2D Crease Pattern | SVG via `gr.HTML` or `gr.Plot` (matplotlib) | `vertices_coords`, `edges_vertices`, `edges_assignment` from FOLD |
-| 3D Folded State | Three.js via `gr.HTML` with `js_on_load` | Vertex positions (3D), face indices, strain values |
-| Strain Heatmap | Vertex colors on 3D mesh (Lut colormap) | Per-vertex strain from physics engine |
-| Fold Sequence | `gr.Slider` + `gr.Button` controls | Fold step index, triggers re-render |
-| Metrics Dashboard | `gr.Dataframe` or `gr.JSON` | Dict of metric name -> value |
-| Material Selector | `gr.Dropdown` | Enum of material presets |
-
-**For standalone React approach:**
-
-| Component | Library | Notes |
-|-----------|---------|-------|
-| `<CreasePatternView>` | React SVG | Inline SVG, responsive |
-| `<FoldedStateView>` | R3F + drei | Canvas with OrbitControls, BufferGeometry |
-| `<StrainOverlay>` | Three.js Lut | Vertex color attribute on mesh |
-| `<FoldSequencePlayer>` | React state + R3F useFrame | Timeline slider, play/pause |
-| `<MetricsDashboard>` | React (plain HTML/CSS) | Cards with numeric values |
-| `<MaterialSelector>` | React select | Updates physics constants |
-
-### 6.3 Data Flow
-
-```
-Python Backend (OpenEnv)
-    |
-    | WebSocket / REST API
-    | Sends: { vertices_coords, edges_vertices, edges_assignment,
-    |          fold_angles, strain_per_vertex, metrics }
-    v
-Frontend (Gradio gr.HTML or React App)
-    |
-    +-- 2D View: vertices_coords[:, :2] + edges -> SVG lines
-    |
-    +-- 3D View: vertices_coords[:, :3] -> BufferGeometry positions
-    |            faces_vertices -> index buffer
-    |            strain_per_vertex -> Lut -> vertex colors
-    |
-    +-- Metrics: metrics dict -> dashboard display
-    |
-    +-- Animation: fold_angles array per step -> interpolate in useFrame
-```
-
----
-
-## 7. FOLD Format Integration
-
-### 7.1 FOLD JavaScript Library
-
-- **GitHub**: https://github.com/edemaine/fold
-- **npm**: `npm install fold`
-- **CDN**: Available via unpkg
-- **Spec**: https://edemaine.github.io/fold/doc/spec.html
-
-**Key data fields we need:**
-```json
-{
-  "vertices_coords": [[0,0], [1,0], [1,1], [0,1]],
-  "edges_vertices": [[0,1], [1,2], [2,3], [3,0], [0,2]],
-  "edges_assignment": ["B", "B", "B", "B", "M"],
-  "edges_foldAngle": [0, 0, 0, 0, -180],
-  "faces_vertices": [[0,1,2], [0,2,3]]
-}
-```
-
-**Parsing in Python:**
-```python
-import json
-
-def load_fold(filepath):
-    with open(filepath) as f:
-        return json.load(f)
-    # It's just JSON!
-```
-
-**Parsing in JavaScript:**
-```javascript
-// It's just JSON
-const foldData = JSON.parse(fileContents);
-// Or use the FOLD library for manipulation:
-import FOLD from 'fold';
-FOLD.filter.collapseNearbyVertices(foldData, epsilon);
-```
-
-### 7.2 Converting Between Python Backend and JS Frontend
-
-The FOLD format is JSON-native, making Python-to-JS data transfer trivial:
-- Python: `json.dumps(fold_data)` -> send via WebSocket/API
-- JavaScript: `JSON.parse(message)` -> use directly with Three.js
-
----
-
-## 8. Recommended Implementation Plan
-
-### Phase 1: Minimum Viable Rendering (Day 1)
-
-1. **Python-side 2D crease pattern** with matplotlib
-   - `plot_crease_pattern(fold_data)` function
-   - Display in Gradio via `gr.Plot`
-   - Mountain=red dashed, Valley=blue dash-dot, Boundary=black solid
-
-2. **Python-side 3D wireframe** with matplotlib mplot3d
-   - `plot_folded_state(fold_data)` function
-   - Basic wireframe of folded vertices
-   - Display in Gradio via `gr.Plot`
-
-3. **Metrics as gr.JSON or gr.Dataframe**
-
-### Phase 2: Interactive 3D Viewer (Day 2)
-
-4. **Three.js viewer via gr.HTML**
-   - Load Three.js + OrbitControls from CDN in `js_on_load`
-   - Receive fold state as `props.value` (JSON)
-   - Render mesh with vertex colors for strain
-   - OrbitControls for rotation/zoom
-
-5. **SVG crease pattern via gr.HTML**
-   - Render 2D crease pattern as inline SVG
-   - Update when fold state changes
-
-### Phase 3: Animation & Polish (Day 3)
-
-6. **Fold sequence animation**
-   - Slider to step through fold sequence
-   - Animate fold angle interpolation
-   - Play/pause controls
-
-7. **Screenshot/recording**
-   - `canvas.toDataURL()` for screenshots
-   - MediaRecorder API for video (simpler than CCapture.js)
-
-8. **Material visual differentiation**
-   - Different colors/textures for paper vs mylar vs aluminum
-   - Opacity/shininess changes based on material
-
----
-
-## 9. Key Technical Risks & Mitigations
-
-| Risk | Mitigation |
-|------|------------|
-| Three.js in gr.HTML is janky | Fall back to Plotly 3D mesh or static React app |
-| Vertex manipulation perf for large meshes | Limit mesh resolution (100x100 grid max), use Web Worker |
-| FOLD format conversion errors | Use FOLD JS library for validation, test with known patterns |
-| HF Spaces doesn't support WebGL | All modern browsers support WebGL; provide matplotlib fallback |
-| Animation recording in Gradio | Use server-side GIF generation with imageio as fallback |
-| OrbitControls conflict with Gradio events | Isolate Three.js canvas, prevent event propagation |
-
----
-
-## 10. Key Dependencies
-
-### Python (Backend)
-```
-numpy          # Mesh computation
-matplotlib     # 2D/3D fallback rendering
-svgwrite       # SVG crease pattern generation (optional)
-imageio        # GIF export from frames
-plotly         # Interactive 3D (optional fallback)
-trimesh        # Mesh utilities (optional)
-```
-
-### JavaScript (Frontend, loaded via CDN or npm)
-```
-three          # 3D rendering engine
-@react-three/fiber   # React wrapper (if standalone React app)
-@react-three/drei    # Helpers (OrbitControls, etc.)
-fold           # FOLD format manipulation
-ccapture.js    # Animation recording (optional)
-```
-
-### For Gradio gr.HTML approach (no npm needed)
-```html
-<!-- Load from CDN in js_on_load -->
-<script src="https://unpkg.com/three@0.160.0/build/three.module.js" type="module"></script>
-<script src="https://unpkg.com/three@0.160.0/examples/jsm/controls/OrbitControls.js" type="module"></script>
-```
-
----
-
-## Sources
-
-- [Origami Simulator - GitHub](https://github.com/amandaghassaei/OrigamiSimulator)
-- [Origami Simulator - Live Demo](https://origamisimulator.org/)
-- [OrigamiOdyssey - React + R3F Origami App](https://github.com/robbwdoering/origamiodyssey)
-- [georgiee/origami - Three.js Origami Builder](https://github.com/georgiee/origami)
-- [flat-folder - Flat-Foldable State Computation](https://github.com/origamimagiro/flat-folder)
-- [crease - SVG Crease Pattern Editor](https://github.com/mwalczyk/crease)
-- [FOLD File Format - GitHub](https://github.com/edemaine/fold)
-- [FOLD Specification](https://edemaine.github.io/fold/doc/spec.html)
-- [FOLD npm package](https://www.npmjs.com/package/fold)
-- [react-three-fiber - GitHub](https://github.com/pmndrs/react-three-fiber)
-- [drei - R3F Helpers](https://github.com/pmndrs/drei)
-- [R3F Basic Animations Tutorial](https://r3f.docs.pmnd.rs/tutorials/basic-animations)
-- [Three.js Lut Documentation](https://threejs.org/docs/examples/en/math/Lut.html)
-- [Three.js Vertex Colors Lookup Table Example](https://threejs.org/examples/webgl_geometry_colors_lookuptable.html)
-- [Three.js Heatmap on 3D Model - Forum](https://discourse.threejs.org/t/how-to-creating-heatmap-over-3d-model/52744)
-- [Three.js Vertex Color BufferGeometry](https://dustinpfister.github.io/2023/01/20/threejs-buffer-geometry-attributes-color/)
-- [Three.js Mesh Modifiers (Bend/Twist)](https://github.com/drawcall/threejs-mesh-modifiers)
-- [CCapture.js - Canvas Animation Capture](https://github.com/spite/ccapture.js/)
-- [use-capture - R3F Recording Hook](https://github.com/gsimone/use-capture)
-- [Videos and GIFs with Three.js](https://janakiev.com/blog/videos-and-gifs-with-threejs/)
-- [R3F Screenshot Discussion](https://github.com/pmndrs/react-three-fiber/discussions/2054)
-- [Headless Three.js Rendering - Forum](https://discourse.threejs.org/t/headless-rendering/14401)
-- [Gradio Custom HTML Components Guide](https://www.gradio.app/guides/custom-HTML-components)
-- [Gradio Custom Components in Five Minutes](https://www.gradio.app/guides/custom-components-in-five-minutes)
-- [Gradio gr.HTML One-Shot Apps](https://huggingface.co/blog/gradio-html-one-shot-apps)
-- [Gradio Model3D Component](https://www.gradio.app/docs/gradio/model3d)
-- [HuggingFace Static HTML Spaces](https://huggingface.co/docs/hub/spaces-sdks-static)
-- [Create Static HF Space with React](https://blog.rednegra.net/2024/10/14/create-a-static-huggingface-space-with-react)
-- [Streamlit + R3F Discussion](https://discuss.streamlit.io/t/streamlit-components-wrap-around-react-three-fiber/4749)
-- [OriDomi - CSS Paper Folding](http://oridomi.com/)
-- [Fast, Interactive Origami Simulation using GPU Computation (Paper)](https://erikdemaine.org/papers/OrigamiSimulator_Origami7/paper.pdf)

research 2/origami/simulation_engines.md

@@ -1,65 +0,0 @@
-# Origami Simulation Engines
-
-## Ghassaei's Origami Simulator (Top Pick)
-
-- **URL**: https://origamisimulator.org/ | [GitHub](https://github.com/amandaghassaei/OrigamiSimulator)
-- **License**: MIT | **Language**: JavaScript/WebGL
-
-**Physics model (truss model):**
-- Folds all creases simultaneously via iterative constraint solving
-- Three constraint types:
-  - **Distance** — prevent stretching/compressing
-  - **Face** — prevent shearing
-  - **Angular** — fold or flatten the sheet
-- Each constraint has a **stiffness parameter** (higher = more rigid)
-- All computation runs in **GPU fragment shaders** for real-time
-
-**Strain visualization:**
-- Blue (no strain) → Red (max strain)
-- Strain = avg percent deviation of distance constraints (Cauchy/engineering strain)
-
-**I/O**: SVG, FOLD → FOLD, STL, OBJ
-
-**For us**: Port the truss model physics to NumPy. The constraint system maps directly to our reward signal.
-
----
-
-## rigid-origami (Existing RL Gym Environment)
-
-- **GitHub**: https://github.com/belalugaX/rigid-origami
-- **Paper**: IJCAI 2023 — "Automating Rigid Origami Design"
-
-Already has Gym API, PPO, MCTS, evolutionary agents. Formulates origami as a board game on a grid. Validation via triangle-triangle intersection + kinematic checks.
-
-**For us**: Study the validation logic. The grid-based vertex placement can be our starting point.
-
----
-
-## SWOMPS (Multi-Physics, MATLAB)
-
-- **GitHub**: https://github.com/zzhuyii/OrigamiSimulator
-- Large deformation + heat transfer + contact detection
-- Five different solvers
-- Companion dataset generator: https://github.com/zzhuyii/GenerateOrigamiDataSet
-
-**For us**: Reference for stress/contact physics only. Not directly usable (MATLAB).
-
----
-
-## Tachi's Software (Foundational, Proprietary)
-
-- Rigid Origami Simulator, Freeform Origami, Origamizer
-- **Origamizer**: universal — can fold ANY 3D polyhedral surface
-- Windows-only, proprietary
-
-**For us**: Algorithms are key references. Origamizer algorithm (Tachi & Demaine, SoCG 2017) proves universality.
-
----
-
-## Others (Low Priority)
-
-| Tool | Language | Notes |
-|------|----------|-------|
-| Origami Editor 3D | Java | GUI editor |
-| Oriedita | Java | Crease pattern editor, FOLD I/O |
-| VPython Origami | Python | Minimal, unmaintained |

research 2/plan/architecture.md

@@ -1,474 +0,0 @@
-# Origami RL Environment — Final Architecture
-
-## The Idea
-
-An OpenEnv environment where an LLM learns to design optimal fold patterns for real-world folding problems — solar panel packing, medical stent deployment, shelter construction. The LLM generates a `fold_strategy()` function (code-as-policy, same as the 2048 pattern), which is executed against our origami simulation engine.
-
----
-
-## 1. Action Space
-
-Based on the Huzita-Justin axioms and fold type research, we use a **named-fold-level** action space (not raw axioms — too low-level for LLM code generation).
-
-### Fold Operations Available to the Agent
-
-```python
-class FoldAction:
-    fold_type: str        # "valley", "mountain", "reverse_inside", "reverse_outside",
-                          # "squash", "petal", "pleat", "crimp"
-    fold_line: FoldLine   # Defined by two points OR angle + offset from edge
-    fold_angle: float     # 0-180 degrees (how far to fold)
-    layer_select: str     # "top", "all", "specific" (which layers to fold)
-```
-
-### Simplified Action Space (Start Here)
-
-For the **code-as-policy** approach, the LLM writes a function that returns a list of fold instructions:
-
-```python
-def fold_strategy(paper_state: dict) -> list[dict]:
-    """
-    paper_state = {
-        "width": 1.0, "height": 1.0,
-        "material": {"name": "mylar", "thickness_mm": 0.05, "youngs_modulus_gpa": 4.0},
-        "vertices": [[x,y,z], ...],
-        "edges": [[v1,v2], ...],
-        "assignments": ["B","B",...],  # current M/V/B assignments
-        "fold_angles": [0, 0, ...],    # current fold angles in degrees
-        "num_layers_at_center": 1,
-        "bounding_box": {"x": 1.0, "y": 1.0, "z": 0.0},
-    }
-
-    Returns list of fold operations:
-    [
-        {"type": "valley", "line": {"start": [0,0.5], "end": [1,0.5]}, "angle": 180},
-        {"type": "mountain", "line": {"start": [0.5,0], "end": [0.5,0.5]}, "angle": 180},
-        ...
-    ]
-    """
-```
-
-### Why This Works
-
-- LLM can reason about geometry in natural language / code
-- Fold operations map directly to the simulation engine
-- The strategy function is self-contained (sandbox-safe)
-- Same pattern as 2048 — proven with GRPO training
-
----
-
-## 2. State Representation
-
-Based on FOLD format (the standard) + bar-and-hinge physics model.
-
-### Internal State (Simulation Engine)
-
-```python
-@dataclass
-class PaperState:
-    # Geometry (FOLD format compatible)
-    vertices: np.ndarray          # (N, 3) vertex positions
-    edges: np.ndarray             # (E, 2) edge vertex indices
-    faces: list[list[int]]        # face vertex indices
-    assignments: list[str]        # ["M","V","B","F"] per edge
-    fold_angles: np.ndarray       # (E,) current fold angle per edge, degrees
-
-    # Physics
-    rest_lengths: np.ndarray      # (E,) original edge lengths
-    strain: np.ndarray            # (N,) per-vertex Cauchy strain
-    energy: float                 # total elastic energy
-
-    # Layer tracking
-    face_orders: list[tuple]      # [(f1, f2, +1/-1), ...] layer ordering
-    num_layers: int               # max layer count
-
-    # Material
-    material: Material            # thickness, Young's modulus, max_strain
-
-    # Metrics (computed after each fold)
-    bounding_box: np.ndarray      # (3,) folded bounding box dimensions
-    deployment_ratio: float       # folded_area / unfolded_area
-    is_valid: bool                # no self-intersections, theorems satisfied
-    kawasaki_violation: float     # sum of angle violations
-    maekawa_violation: float      # sum of M-V violations
-    self_intersections: int       # count of face-face penetrations
-```
-
-### Observation (What the LLM Sees via Prompt)
-
-```python
-class OrigamiObservation(Observation):
-    paper_state: dict             # Serialized PaperState (simplified)
-    task: dict                    # What to optimize
-    metrics: dict                 # Current scores
-    fold_history: list[dict]      # Previous folds applied
-    error: str | None             # If last fold was invalid, why
-```
-
-### Text Prompt Format
-
-```
-TASK: Fold a 1m x 1m Mylar sheet to minimize packed volume while maintaining deployability.
-
-MATERIAL:
-  - Name: Mylar (space-grade)
-  - Thickness: 0.05mm
-  - Young's modulus: 4 GPa
-  - Max strain before failure: 3%
-
-CONSTRAINTS:
-  - Must pack into bounding box <= 15cm x 15cm x 5cm
-  - Must deploy to >= 0.8m^2 area when unfolded
-  - Maximum 20 fold operations
-  - No self-intersections allowed
-
-CURRENT STATE:
-  - Sheet: 1.0m x 1.0m, flat (0 folds applied)
-  - Bounding box: 1.0m x 1.0m x 0.0m
-  - Deployment ratio: 1.0 (fully deployed)
-  - Strain: 0.0 (no stress)
-
-Write a fold_strategy(paper_state) function that returns a list of fold operations.
-Each fold: {"type": "valley"|"mountain", "line": {"start": [x,y], "end": [x,y]}, "angle": 0-180}
-```
-
----
-
-## 3. Physics Engine
-
-Based on the bar-and-hinge model (Ghassaei's approach, ported to NumPy).
-
-### Module Layout
-
-```
-engine/
-  paper.py          -> Paper data structure, FOLD I/O
-  fold_engine.py    -> Apply fold operations to paper geometry
-  physics.py        -> Bar-and-hinge energy computation, strain calculation
-  validation.py     -> Kawasaki, Maekawa, self-intersection checks
-  metrics.py        -> Deployment ratio, compactness, shape similarity
-  materials.py      -> Material definitions (paper, mylar, aluminum, etc.)
-```
-
-### Fold Execution Pipeline
-
-```
-Input: FoldAction (type, line, angle)
-  |
-  +-- 1. Validate fold line (does it intersect the paper?)
-  +-- 2. Determine affected vertices (which side of fold line)
-  +-- 3. Apply rotation to affected vertices
-  |       - Rotate around fold line by fold_angle
-  |       - Using quaternion rotation for numerical stability
-  +-- 4. Update edge assignments (M/V based on fold type)
-  +-- 5. Update fold angles array
-  +-- 6. Compute new face topology (split faces at fold line if needed)
-  +-- 7. Run physics step
-  |       - Compute bar energies (stretching)
-  |       - Compute facet hinge energies (panel bending)
-  |       - Compute fold hinge energies (crease folding)
-  |       - Iterative solver: minimize total energy
-  +-- 8. Compute strain per vertex
-  +-- 9. Check validity
-  |       - Kawasaki theorem at all vertices
-  |       - Maekawa theorem at all vertices
-  |       - Self-intersection detection (triangle-triangle)
-  +-- 10. Update metrics
-  |       - Bounding box, deployment ratio, layer count
-  |
-  Output: Updated PaperState + validity report
-```
-
-### Energy Formulation (from research)
-
-```python
-# Bar-and-hinge model: three energy components
-E_total = E_bar + E_facet + E_fold
-
-E_bar   = sum_bars   (1/2) * k_axial * (L - L0)^2     # stretching
-E_facet = sum_facets (1/2) * k_facet * l * (theta - pi)^2  # panel bending
-E_fold  = sum_folds  (1/2) * k_fold  * l * (rho - rho_target)^2  # crease folding
-
-# Stiffness parameters (from material properties)
-k_axial = E * t * w / L0
-k_facet = E * t^3 / (12 * (1 - nu^2))
-k_fold  = kappa  # crease torsional stiffness
-```
-
-### Strain Computation (Ghassaei's formula)
-
-```python
-def compute_strain(vertices, edges, rest_lengths):
-    """Per-vertex Cauchy strain = avg percent deviation of edge lengths."""
-    strain = np.zeros(len(vertices))
-    for v_idx in range(len(vertices)):
-        neighbor_edges = get_edges_at_vertex(v_idx, edges)
-        deviations = []
-        for e_idx in neighbor_edges:
-            v1, v2 = edges[e_idx]
-            L = np.linalg.norm(vertices[v1] - vertices[v2])
-            L0 = rest_lengths[e_idx]
-            deviations.append(abs(L - L0) / L0)
-        strain[v_idx] = np.mean(deviations) if deviations else 0.0
-    return strain
-```
-
----
-
-## 4. Reward Functions
-
-Three reward functions (same pattern as 2048):
-
-### Reward 1: `code_valid(completions)`
-
-Does the LLM output compile and produce valid fold instructions?
-
-| Condition | Score |
-|-----------|-------|
-| Valid function returning fold list | +1.0 |
-| Correct structure but exec fails | -0.5 |
-| No function / syntax error | -2.0 |
-| Non-stdlib imports | -20.0 |
-
-### Reward 2: `physically_valid(completions)`
-
-Are the folds physically possible?
-
-| Condition | Score |
-|-----------|-------|
-| All folds valid, no violations | +1.0 |
-| Per Kawasaki violation | -2.0 each |
-| Per Maekawa violation | -2.0 each |
-| Any self-intersection | -5.0 |
-| Strain exceeds material limit | -1.0 |
-| Function broken / can't run | 0.0 |
-
-### Reward 3: `fold_quality(completions)`
-
-How good is the folding solution?
-
-| Condition | Score |
-|-----------|-------|
-| Compactness (1 - deployment_ratio) | +20.0 * compactness |
-| Meets volume constraint (fits in target box) | +10.0 bonus |
-| Deployable (can unfold cleanly) | +5.0 bonus |
-| Per fold (efficiency penalty) | -0.5 each |
-| High strain (material stress) | -3.0 * (max_strain / limit) |
-| Timeout (>5 sec) | -1.0 |
-| Exception during execution | -3.0 |
-
----
-
-## 5. OpenEnv Integration
-
-### Server: OrigamiEnvironment
-
-```python
-class OrigamiEnvironment(Environment[OrigamiAction, OrigamiObservation, OrigamiState]):
-
-    def reset(self, seed=None, episode_id=None, **kwargs):
-        task = self._sample_task()
-        self._paper = create_flat_sheet(task["width"], task["height"], task["material"])
-        self._task = task
-        self._fold_history = []
-        return self._make_observation()
-
-    def step(self, action: OrigamiAction, **kwargs):
-        # Extract and sandbox the fold strategy code
-        strategy_fn = sandbox_execute(action.fold_code)
-        folds = strategy_fn(self._paper.to_dict())
-
-        # Apply each fold
-        for fold in folds:
-            result = self._engine.apply_fold(self._paper, fold)
-            if not result.valid:
-                return self._make_observation(error=result.error, done=True, reward=-5.0)
-            self._paper = result.new_state
-            self._fold_history.append(fold)
-
-        # Compute final metrics and reward
-        metrics = self._compute_metrics()
-        reward = self._compute_reward(metrics)
-        return self._make_observation(done=True, reward=reward)
-```
-
-### Task Pool (Curriculum)
-
-```python
-TASK_POOL = [
-    # Level 1: Simple folds
-    {"name": "half_fold", "width": 1.0, "height": 1.0,
-     "material": "paper", "target_ratio": 0.5, "max_folds": 3},
-
-    # Level 2: Multi-fold packing
-    {"name": "letter_fold", "width": 1.0, "height": 1.0,
-     "material": "paper", "target_ratio": 0.33, "max_folds": 5},
-
-    # Level 3: Miura-ori discovery
-    {"name": "solar_panel", "width": 1.0, "height": 1.0,
-     "material": "mylar", "target_ratio": 0.05, "max_folds": 20,
-     "must_deploy": True, "target_box": [0.15, 0.15, 0.05]},
-
-    # Level 4: Constrained engineering
-    {"name": "stent_fold", "width": 0.1, "height": 0.03,
-     "material": "nitinol", "target_shape": "cylinder",
-     "deployed_diameter": 0.01, "compressed_diameter": 0.003},
-]
-```
-
----
-
-## 6. Rendering Pipeline
-
-### Training Time (Server-Side, Headless)
-
-```python
-# matplotlib — fast, no GPU needed
-def render_crease_pattern_2d(state) -> Image:
-    """M=red dashed, V=blue dash-dot, B=black solid"""
-
-def render_folded_3d(state) -> Image:
-    """3D wireframe with strain colors (blue->red)"""
-```
-
-### Demo Time (Client-Side, React + Three.js)
-
-```
-React App (Docker Space on HF)
-+-- CreasePatternPanel (SVG, left)
-|   +-- Edges colored by M/V/B assignment
-+-- FoldedView3D (@react-three/fiber, right)
-|   +-- BufferGeometry with vertex colors (strain heatmap)
-|   +-- OrbitControls for rotation
-|   +-- Animation: step through fold sequence
-+-- MetricsDashboard (bottom)
-|   +-- Compactness, fold count, strain, validity
-+-- MaterialSelector (sidebar)
-    +-- Paper, Mylar, Aluminum, Nitinol
-```
-
-### Tech Stack
-
-| Component | Library |
-|-----------|---------|
-| 3D scene | @react-three/fiber |
-| Controls | @react-three/drei |
-| Strain heatmap | Three.js Lut + vertex colors |
-| 2D crease pattern | Inline SVG |
-| Screenshots | canvas.toDataURL() |
-| Recording | CCapture.js / MediaRecorder |
-| HF Spaces | Docker Space (FastAPI + static React build) |
-
----
-
-## 7. Project Structure
-
-```
-origami/
-  research/                      # All research docs
-    research.md                  # Index
-    openenv/                     # OpenEnv framework research
-    origami/                     # Domain research
-    plan/                        # Architecture docs
-
-  engine/                        # Core simulation (numpy/scipy only)
-    __init__.py
-    paper.py                     # Paper data structure, FOLD I/O
-    fold_engine.py               # Apply folds (quaternion rotation)
-    physics.py                   # Bar-and-hinge energy, strain
-    validation.py                # Kawasaki, Maekawa, self-intersection
-    metrics.py                   # Deployment ratio, compactness
-    materials.py                 # Material definitions
-
-  environment/                   # OpenEnv server
-    __init__.py
-    models.py                    # Action, Observation, State
-    origami_environment.py       # Environment (reset/step/state)
-    tasks.py                     # Task pool / curriculum
-    app.py                       # create_app()
-    Dockerfile
-    requirements.txt
-
-  client/                        # OpenEnv client + training bridge
-    __init__.py
-    client.py                    # EnvClient subclass
-    reward_functions.py          # code_valid, physically_valid, fold_quality
-
-  renderer/                      # Visualization
-    server_render.py             # matplotlib headless
-    web/                         # React app
-      package.json
-      src/
-        App.tsx
-        CreasePattern.tsx        # 2D SVG view
-        FoldedView3D.tsx         # R3F 3D view
-        StrainHeatmap.tsx        # Vertex color mapping
-        FoldAnimation.tsx        # Step-through animation
-        MetricsDashboard.tsx     # Scores display
-
-  training/                      # Colab notebook
-    train_origami.ipynb          # GRPO training (Unsloth + TRL)
-    prompts.py                   # LLM prompt templates
-
-  openenv.yaml                   # Manifest
-  pyproject.toml
-  README.md
-```
-
----
-
-## 8. Implementation Order
-
-### Phase 1: Engine (first)
-1. `paper.py` — Paper class, flat sheet creation, FOLD JSON serialize
-2. `fold_engine.py` — Valley/mountain folds via quaternion rotation
-3. `validation.py` — Kawasaki check, Maekawa check, basic self-intersection
-4. `metrics.py` — Bounding box, deployment ratio, fold count
-5. Test: fold a sheet in half, verify metrics
-
-### Phase 2: OpenEnv Server
-1. `models.py` — Pydantic models
-2. `origami_environment.py` — reset/step
-3. `app.py` + `Dockerfile`
-4. `tasks.py` — 3-4 tasks
-5. Test: curl the server, verify reset/step
-
-### Phase 3: Reward + Training
-1. `reward_functions.py` — three reward functions
-2. `prompts.py` — prompt template
-3. `train_origami.ipynb` — Colab GRPO notebook
-4. Test: few training steps, verify rewards
-
-### Phase 4: Rendering + Demo
-1. `server_render.py` — matplotlib 2D + 3D
-2. React app scaffold — R3F + SVG
-3. Docker Space deployment
-4. Record 1-minute demo video
-
----
-
-## 9. Decisions (Locked)
-
-| Decision | Choice | Why |
-|----------|--------|-----|
-| LLM interaction | Code-as-policy | Proven with 2048, hackathon expects it |
-| Action space | Named fold ops + line + angle | Right level for LLM code gen |
-| State format | FOLD-compatible JSON | Industry standard |
-| Physics | Bar-and-hinge (NumPy) | Fast for RL, captures strain |
-| Validation | Kawasaki + Maekawa + tri-tri intersection | Sound, polynomial time |
-| Primary task | Solar panel packing | Unique, real-world, great demo |
-| Training render | matplotlib headless | No GPU needed |
-| Demo render | React + @react-three/fiber | Interactive, strain heatmap |
-| Training | GRPO via TRL + Unsloth | Required by hackathon |
-| Deployment | Docker Space on HF | Full control |
-
----
-
-## 10. Why This Wins
-
-1. **Unique** — nobody else doing origami RL
-2. **Real-world** — NASA solar panels, medical stents, deployable shelters
-3. **Demoable** — visual folding animation, strain heatmap, 1-min video
-4. **Technically deep** — bar-and-hinge physics, Kawasaki/Maekawa math, material science
-5. **Scalable** — FOLD format standard, material system, task curriculum
-6. **Multi-statement** — Statement 2 (long-horizon planning) + Statement 3.1 (world modeling) + Statement 4 (self-improvement via curriculum)

research 2/plan/openenv_arch.md

@@ -1,1523 +0,0 @@
-# OpenEnv Environment Architecture — Origami RL
-
-> Complete blueprint. Everything lives inside the environment.
-> Engine, physics, rendering, recording — all one deployable unit.
-
----
-
-## 1. Overview
-
-One Docker container on HF Spaces. Serves the OpenEnv API (WebSocket/REST) AND the React demo UI. Contains the full origami simulation engine, physics solver, validator, renderer, and metric system.
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                  HF Space (Docker)                       │
-│                                                          │
-│  ┌────────────────────────────────────────────────────┐  │
-│  │              FastAPI (app.py)                       │  │
-│  │                                                    │  │
-│  │  /ws, /reset, /step, /state   →  OpenEnv API       │  │
-│  │  /                            →  React build       │  │
-│  │  /renders/*                   →  Screenshots/GIFs  │  │
-│  │  /export/*                    →  FOLD JSON export  │  │
-│  └─────────────────┬──────────────────────────────────┘  │
-│                    │                                      │
-│  ┌─────────────────▼──────────────────────────────────┐  │
-│  │         OrigamiEnvironment                          │  │
-│  │         reset() / step() / state                    │  │
-│  │                                                     │  │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │  │
-│  │  │  Engine   │  │ Renderer │  │  Task System     │  │  │
-│  │  │          │  │          │  │                  │  │  │
-│  │  │ paper    │  │ render2d │  │ task pool       │  │  │
-│  │  │ fold     │  │ render3d │  │ materials       │  │  │
-│  │  │ physics  │  │ capture  │  │ curriculum      │  │  │
-│  │  │ validate │  │ record   │  │                  │  │  │
-│  │  │ metrics  │  │ export   │  │                  │  │  │
-│  │  │ material │  │          │  │                  │  │  │
-│  │  └──────────┘  └──────────┘  └──────────────────┘  │  │
-│  └─────────────────────────────────────────────────────┘  │
-│                                                          │
-│  ┌────────────────────────────────────────────────────┐  │
-│  │         React Frontend (static build)               │  │
-│  │  CreasePattern(SVG) + FoldedView3D(R3F) + Metrics  │  │
-│  │  FoldAnimation + StrainHeatmap + MaterialSelector  │  │
-│  │  ScreenshotButton + RecordButton                   │  │
-│  └────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## 2. Repository Structure
-
-```
-origami_env/                             # THE deliverable — one package
-│
-├── server/                              # Python backend (everything)
-│   │
-│   ├── engine/                          # Origami simulation core
-│   │   ├── __init__.py
-│   │   ├── paper.py                     # PaperState dataclass, FOLD I/O, create_flat_sheet()
-│   │   ├── fold.py                      # apply_fold() — quaternion rotation, face splitting
-│   │   ├── physics.py                   # Bar-and-hinge Verlet solver, strain computation
-│   │   ├── validation.py               # Kawasaki, Maekawa, self-intersection detection
-│   │   ├── metrics.py                   # ALL metrics — compactness, strain, shape, deployability
-│   │   └── materials.py                 # Material presets + stiffness parameter derivation
-│   │
-│   ├── renderer/                        # All visualization
-│   │   ├── __init__.py
-│   │   ├── render_2d.py                 # matplotlib: crease pattern SVG/PNG (M=red, V=blue, B=black)
-│   │   ├── render_3d.py                 # matplotlib: 3D wireframe + strain heatmap
-│   │   ├── screenshots.py              # Per-step PNG capture, episode summary grid
-│   │   ├── recorder.py                 # GIF assembly from frames (imageio), fold animation
-│   │   └── exporter.py                 # FOLD JSON export, OBJ/STL export for 3D printing
-│   │
-│   ├── models.py                        # Pydantic: OrigamiAction, OrigamiObservation, OrigamiState
-│   ├── origami_environment.py           # Environment class — reset/step/state (calls engine + renderer)
-│   ├── tasks.py                         # Task pool, curriculum levels, difficulty sampling
-│   ├── app.py                           # FastAPI: OpenEnv API + static React + render serving
-│   ├── requirements.txt                 # numpy, scipy, matplotlib, imageio, pydantic, openenv-core
-│   └── Dockerfile                       # Build React + run FastAPI
-│
-├── web/                                 # React frontend
-│   ├── package.json
-│   ├── tsconfig.json
-│   ├── vite.config.ts
-│   └── src/
-│       ├── App.tsx                      # Main layout: 2D + 3D + metrics + controls
-│       ├── components/
-│       │   ├── CreasePattern.tsx         # SVG: edges colored by M/V/B/F/U assignment
-│       │   ├── FoldedView3D.tsx         # R3F: BufferGeometry + OrbitControls + DoubleSide
-│       │   ├── StrainHeatmap.tsx        # Three.js Lut: vertex colors blue→red
-│       │   ├── FoldAnimation.tsx        # Timeline slider, play/pause, fold interpolation
-│       │   ├── MetricsDashboard.tsx     # Cards: all metrics with live updates
-│       │   ├── MaterialSelector.tsx     # Dropdown: paper/mylar/aluminum/nitinol
-│       │   ├── TaskSelector.tsx         # Pick task from curriculum
-│       │   └── CaptureControls.tsx      # Screenshot (canvas.toDataURL) + Record (MediaRecorder)
-│       ├── hooks/
-│       │   └── useEnvironment.ts        # WebSocket connection to OpenEnv server
-│       └── types.ts                     # TypeScript interfaces matching server models
-│
-├── client/                              # OpenEnv client (for remote connection + training)
-│   ├── __init__.py
-│   ├── client.py                        # OrigamiEnvClient (EnvClient subclass)
-│   └── reward_functions.py              # code_valid, no_cheating, fold_quality
-│
-├── openenv.yaml                         # Manifest
-├── pyproject.toml
-└── README.md
-```
-
----
-
-## 3. Pydantic Models (`server/models.py`)
-
-### OrigamiAction
-
-One fold per step. Multi-step episodes (like 2048 where each step = one move).
-
-```python
-class OrigamiAction(Action):
-    """One fold operation."""
-    # metadata: Dict[str, Any]  (inherited)
-
-    fold_type: str                    # "valley" | "mountain" | "pleat" | "crimp" | "stop"
-    fold_line: Dict[str, List[float]] # {"start": [x,y], "end": [x,y]}  (normalized 0-1)
-    fold_angle: float = 180.0         # degrees, 0-180 (180 = fully folded)
-    layer_select: str = "all"         # "all" | "top" | "bottom"
-```
-
-`"stop"` action ends the episode and triggers final metrics + reward.
-
-### OrigamiObservation
-
-Everything the frontend AND the LLM need. Returned by both `reset()` and `step()`.
-
-```python
-class OrigamiObservation(Observation):
-    # done: bool           (inherited)
-    # reward: float|None   (inherited)
-    # metadata: Dict       (inherited)
-
-    # ── Task ──────────────────────────────────────────
-    task: Dict[str, Any] = Field(default_factory=dict)
-    # {
-    #   "name": "solar_panel",
-    #   "description": "Pack a 1m x 1m Mylar solar panel...",
-    #   "width": 1.0, "height": 1.0,
-    #   "material": {"name": "mylar", "thickness_mm": 0.05, "youngs_modulus_gpa": 4.0, "max_strain": 0.03},
-    #   "target_ratio": 0.05,
-    #   "max_folds": 20,
-    #   "target_box": [0.15, 0.15, 0.05],
-    #   "must_deploy": True,
-    #   "difficulty": 3,
-    # }
-
-    # ── Paper State (FOLD-compatible) ─────────────────
-    paper_state: Dict[str, Any] = Field(default_factory=dict)
-    # {
-    #   "vertices_coords": [[x,y,z], ...],          # (N,3) current 3D positions
-    #   "edges_vertices": [[v1,v2], ...],            # (E,2) edge connectivity
-    #   "faces_vertices": [[v0,v1,v2,...], ...],     # face polygons (CCW)
-    #   "edges_assignment": ["M","V","B","F",...],   # per-edge type
-    #   "edges_foldAngle": [-180, 180, 0, ...],     # per-edge target angle (degrees)
-    #   "num_vertices": 25,
-    #   "num_edges": 48,
-    #   "num_faces": 24,
-    #   "bounding_box": [0.15, 0.15, 0.05],         # folded dimensions
-    #   "num_layers": 8,
-    #   "material": {"name": "mylar", ...},
-    #
-    #   # Physics state
-    #   "strain_per_vertex": [0.01, 0.005, ...],    # per-vertex Cauchy strain
-    #   "energy": {
-    #     "total": 0.34,
-    #     "bar": 0.12,                               # stretching energy
-    #     "facet": 0.08,                              # panel bending energy
-    #     "fold": 0.14,                               # crease folding energy
-    #   },
-    # }
-
-    # ── Metrics ───────────────────────────────────────
-    metrics: Dict[str, Any] = Field(default_factory=dict)
-    # {
-    #   ## Validity
-    #   "is_valid": True,
-    #   "kawasaki_violations": 0,                     # count of vertices violating Kawasaki
-    #   "kawasaki_total_error": 0.0,                  # sum of |alt_angle_sum - 180| degrees
-    #   "maekawa_violations": 0,                      # count of vertices violating |M-V|=2
-    #   "self_intersections": 0,                      # count of face-face penetrations
-    #   "strain_exceeded": False,                     # any vertex > material.max_strain?
-    #
-    #   ## Compactness
-    #   "deployment_ratio": 0.05,                     # folded_area / original_area
-    #   "compactness": 0.95,                          # 1 - deployment_ratio
-    #   "volume_compaction": 0.001,                   # bbox_folded / bbox_original
-    #   "packing_efficiency": 0.72,                   # material_volume / bbox_volume
-    #   "fits_target_box": True,                      # fits inside task.target_box?
-    #
-    #   ## Structural
-    #   "max_strain": 0.02,                           # max per-vertex strain
-    #   "mean_strain": 0.008,                         # mean per-vertex strain
-    #   "total_energy": 0.34,                         # total elastic energy
-    #   "energy_bar": 0.12,
-    #   "energy_facet": 0.08,
-    #   "energy_fold": 0.14,
-    #
-    #   ## Efficiency
-    #   "fold_count": 8,                              # number of folds applied
-    #   "folding_efficiency": 0.119,                  # compactness / fold_count
-    #   "crease_complexity": 0.85,                    # entropy of M/V assignment distribution
-    #
-    #   ## Deployability
-    #   "is_deployable": True,                        # reverse fold simulation passed?
-    #   "deployment_force_estimate": 0.45,            # Newtons (from energy gradient)
-    #
-    #   ## Shape similarity (if task has target_shape)
-    #   "chamfer_distance": null,                     # avg nearest-point distance
-    #   "hausdorff_distance": null,                   # max distance
-    # }
-
-    # ── Fold History ──────────────────────────────────
-    fold_history: List[Dict[str, Any]] = Field(default_factory=list)
-    # [ {"type":"valley", "line":{"start":[0,0.5],"end":[1,0.5]}, "angle":180, "step":1}, ... ]
-
-    # ── Error ─────────────────────────────────────────
-    error: Optional[str] = None
-    # "Fold line does not intersect paper boundary"
-    # "Self-intersection detected after fold 3"
-    # etc.
-
-    # ── Render URLs ───────────────────────────────────
-    render_urls: Dict[str, str] = Field(default_factory=dict)
-    # {
-    #   "crease_2d": "/renders/ep_abc123/crease_step_4.png",
-    #   "folded_3d": "/renders/ep_abc123/folded_step_4.png",
-    #   "strain_heatmap": "/renders/ep_abc123/strain_step_4.png",
-    #   "episode_gif": "/renders/ep_abc123/animation.gif",    # only when done=True
-    #   "fold_json": "/export/ep_abc123/state.fold",          # FOLD format export
-    # }
-```
-
-### OrigamiState
-
-Server-side episode tracking.
-
-```python
-class OrigamiState(State):
-    # episode_id: Optional[str]  (inherited)
-    # step_count: int            (inherited)
-
-    task_name: str = ""
-    num_folds_applied: int = 0
-    is_valid: bool = True
-    total_reward: float = 0.0
-    current_fold_percent: float = 1.0     # for animation: how far current fold has progressed
-```
-
----
-
-## 4. Engine (`server/engine/`)
-
-### 4.1 Paper State (`paper.py`)
-
-The core data structure. FOLD-format compatible.
-
-```python
-@dataclass
-class PaperState:
-    # ── Geometry (FOLD format) ────────────────────────
-    vertices_coords: np.ndarray       # (N, 3) vertex positions (3D)
-    edges_vertices: np.ndarray        # (E, 2) edge connectivity, dtype int
-    faces_vertices: list[list[int]]   # ragged: face polygons as vertex index lists (CCW)
-    edges_assignment: list[str]       # (E,) "M" | "V" | "B" | "F" | "U" per edge
-    edges_foldAngle: np.ndarray       # (E,) target fold angle in degrees per edge
-
-    # ── Physics ─────────────────────────���─────────────
-    rest_lengths: np.ndarray          # (E,) original edge lengths (set at creation)
-    rest_positions: np.ndarray        # (N, 3) original flat positions (for strain reference)
-    strain_per_vertex: np.ndarray     # (N,) per-vertex Cauchy strain
-    energy: dict                      # {"total": float, "bar": float, "facet": float, "fold": float}
-
-    # ── Layers ────────────────────────────────────────
-    face_orders: list[tuple]          # [(face_i, face_j, +1/-1), ...] layer ordering
-    num_layers: int                   # max stacking depth
-
-    # ── Material ──────────────────────────────────────
-    material: Material                # thickness_mm, youngs_modulus_gpa, max_strain, poisson_ratio
-
-    # ── Metadata ──────────────────────────────────────
-    width: float                      # original sheet width (meters)
-    height: float                     # original sheet height (meters)
-    fold_count: int                   # number of folds applied so far
-```
-
-**Key methods:**
-
-```python
-create_flat_sheet(width, height, material) -> PaperState
-    # Creates a rectangular sheet: 4 vertices, 4 boundary edges, 1 face
-    # (or subdivided grid for higher resolution physics)
-
-PaperState.to_fold_json() -> dict
-    # Exports FOLD-format JSON (vertices_coords, edges_vertices, edges_assignment, etc.)
-
-PaperState.from_fold_json(data: dict) -> PaperState
-    # Imports from FOLD JSON
-
-PaperState.to_observation_dict() -> dict
-    # Simplified dict for the Observation (includes strain, energy, bounding_box)
-
-PaperState.bounding_box -> np.ndarray  # (3,) min bounding box dimensions
-
-PaperState.triangulated_faces -> list[list[int]]
-    # Ear-clipping triangulation of polygon faces (needed for physics + rendering)
-```
-
-### 4.2 Fold Operations (`fold.py`)
-
-Applies one fold to the paper. Returns new PaperState.
-
-```python
-def apply_fold(paper: PaperState, fold: dict) -> PaperState:
-    """
-    fold = {
-        "type": "valley" | "mountain" | "pleat" | "crimp",
-        "line": {"start": [x, y], "end": [x, y]},
-        "angle": 0-180,
-        "layer_select": "all" | "top" | "bottom",
-    }
-    """
-```
-
-**The 10-step fold pipeline:**
-
-```
-Step 1:  VALIDATE fold line
-         - Does line intersect the paper boundary at 2+ points?
-         - Is angle in valid range?
-         - Raise FoldError if invalid
-
-Step 2:  SPLIT FACES at fold line
-         - Find all faces intersected by the fold line
-         - Split each intersected face into sub-faces
-         - Add new vertices at intersection points
-         - Add new edges along the fold line
-         - Update faces_vertices, edges_vertices, edges_assignment
-
-Step 3:  CLASSIFY VERTICES
-         - For each vertex, determine which side of fold line it's on
-         - Use signed distance: d = (point - line_start) x line_direction
-         - Positive side = moving side, negative side = fixed side
-         - Vertices ON the line (|d| < epsilon) are hinge vertices
-
-Step 4:  APPLY ROTATION (quaternion)
-         - Rotation axis = fold line direction vector (normalized)
-         - Rotation angle = fold_angle (valley=positive, mountain=negative)
-         - For each moving vertex:
-           translate to fold line origin → apply quaternion → translate back
-         - Quaternion rotation for numerical stability (no gimbal lock)
-
-Step 5:  UPDATE EDGE ASSIGNMENTS
-         - New edges along fold line: "M" or "V" based on fold_type
-         - Valley fold → "V" (positive fold angle, paper toward you)
-         - Mountain fold → "M" (negative fold angle, paper away)
-
-Step 6:  UPDATE FOLD ANGLES
-         - New crease edges: set target angle (±180 for full fold, ±fold_angle otherwise)
-         - Existing assignments unchanged
-
-Step 7:  UPDATE FACE TOPOLOGY
-         - Recompute faces_vertices after split
-         - Recompute face_orders (layer ordering) based on rotation
-
-Step 8:  COMPUTE REST LENGTHS for new edges
-         - rest_length = euclidean distance in the FLAT (unfolded) configuration
-         - This is the reference for strain computation
-
-Step 9:  INCREMENT fold_count
-
-Step 10: RETURN new PaperState
-         - Physics and validation run SEPARATELY (called by environment)
-         - This keeps fold.py focused on geometry only
-```
-
-**Pleat and crimp are compound folds:**
-
-```python
-def apply_pleat(paper, line1, line2, angle):
-    """Two parallel folds: valley at line1, mountain at line2."""
-    paper = apply_fold(paper, {"type": "valley", "line": line1, "angle": angle})
-    paper = apply_fold(paper, {"type": "mountain", "line": line2, "angle": angle})
-    return paper
-
-def apply_crimp(paper, line1, line2, angle):
-    """Two parallel folds: mountain at line1, valley at line2 (reverse of pleat)."""
-    paper = apply_fold(paper, {"type": "mountain", "line": line1, "angle": angle})
-    paper = apply_fold(paper, {"type": "valley", "line": line2, "angle": angle})
-    return paper
-```
-
-### 4.3 Physics Solver (`physics.py`)
-
-Bar-and-hinge model. NumPy port of Ghassaei's GPU solver.
-
-**Three constraint types (energy components):**
-
-```python
-# E_total = E_bar + E_facet + E_fold
-
-# 1. BAR (axial spring) — every edge resists stretching/compression
-#    E_bar = Σ (1/2) * k_axial * (L - L0)²
-#    k_axial = E * t * w / L0
-#    Where: E = Young's modulus, t = thickness, w = tributary width, L0 = rest length
-
-# 2. FACET HINGE — triangulation diagonals keep faces flat
-#    E_facet = Σ (1/2) * k_facet * l * (θ - π)²
-#    k_facet = E * t³ / (12 * (1 - ν²))
-#    Target angle = π (flat), high stiffness
-#    l = hinge edge length
-
-# 3. FOLD HINGE — crease edges drive toward target fold angle
-#    E_fold = Σ (1/2) * k_fold * l * (ρ - ρ_target)²
-#    k_fold = κ (crease torsional stiffness, user-adjustable)
-#    ρ_target from edges_foldAngle * fold_percent
-```
-
-**Stiffness hierarchy:**
-
-```python
-# Prevents stretching while allowing controlled folding:
-k_axial  = 70.0    # very stiff — bars don't stretch
-k_facet  = 0.2     # moderate — faces stay flat but can flex slightly
-k_fold   = 0.7     # soft — drives folding motion
-```
-
-**Verlet integration solver:**
-
-```python
-def simulate(paper: PaperState, fold_percent: float = 1.0, n_steps: int = 500,
-             dt: float = 0.02, damping: float = 0.1) -> PaperState:
-    """
-    Run bar-and-hinge physics simulation.
-    Updates vertex positions to satisfy fold constraints while minimizing energy.
-    Computes strain per vertex and total energy.
-    """
-    pos = paper.vertices_coords.copy()          # (N, 3) current positions
-    last_pos = pos.copy()                        # (N, 3) previous positions
-
-    # Precompute topology
-    beams = build_beam_list(paper)               # [(node_a, node_b, rest_len, k), ...]
-    creases = build_crease_list(paper)           # [(n1, n2, n3, n4, target_angle, k, type), ...]
-
-    for step in range(n_steps):
-        forces = np.zeros_like(pos)              # (N, 3)
-
-        # ── Beam forces (vectorized) ─────────────────
-        for (a, b, L0, k) in beams:
-            delta = pos[b] - pos[a]
-            L = np.linalg.norm(delta)
-            if L < 1e-12: continue
-            strain = (L - L0) / L0
-            F_mag = k * strain * L0
-            F_dir = delta / L
-            forces[a] += F_mag * F_dir
-            forces[b] -= F_mag * F_dir
-
-        # ── Crease forces (dihedral angle springs) ───
-        for (n1, n2, n3, n4, target, k, ctype) in creases:
-            actual_target = target * fold_percent if ctype == "fold" else target
-            theta = compute_dihedral_angle(pos[n1], pos[n2], pos[n3], pos[n4])
-            delta_theta = theta - actual_target
-            torque = k * edge_length(pos[n1], pos[n2]) * delta_theta
-
-            # Convert torque to forces on the 4 nodes
-            f3, f4, f1, f2 = torque_to_forces(
-                pos[n1], pos[n2], pos[n3], pos[n4], torque
-            )
-            forces[n1] += f1
-            forces[n2] += f2
-            forces[n3] += f3
-            forces[n4] += f4
-
-        # ── Verlet integration ───────────────────────
-        new_pos = pos + (1.0 - damping) * (pos - last_pos) + forces * dt * dt
-        last_pos = pos
-        pos = new_pos
-
-        # ── Convergence check ────────────────────────
-        kinetic_energy = np.sum((pos - last_pos) ** 2)
-        if kinetic_energy < 1e-10:
-            break
-
-    # ── Compute strain ───────────────────────────────
-    paper.vertices_coords = pos
-    paper.strain_per_vertex = compute_strain(pos, paper.edges_vertices, paper.rest_lengths)
-
-    # ── Compute energy breakdown ─────────────────────
-    paper.energy = {
-        "total": compute_total_energy(pos, beams, creases, fold_percent),
-        "bar": compute_bar_energy(pos, beams),
-        "facet": compute_facet_energy(pos, creases, fold_percent),
-        "fold": compute_fold_energy(pos, creases, fold_percent),
-    }
-
-    return paper
-```
-
-**Strain computation (Ghassaei's formula):**
-
-```python
-def compute_strain(vertices, edges, rest_lengths) -> np.ndarray:
-    """Per-vertex Cauchy strain = average percent deviation of incident edge lengths."""
-    strain = np.zeros(len(vertices))
-    counts = np.zeros(len(vertices))
-
-    for e_idx, (v1, v2) in enumerate(edges):
-        L = np.linalg.norm(vertices[v1] - vertices[v2])
-        L0 = rest_lengths[e_idx]
-        edge_strain = abs(L - L0) / L0
-
-        strain[v1] += edge_strain
-        strain[v2] += edge_strain
-        counts[v1] += 1
-        counts[v2] += 1
-
-    counts[counts == 0] = 1  # avoid division by zero
-    return strain / counts
-```
-
-**Dihedral angle computation:**
-
-```python
-def compute_dihedral_angle(p1, p2, p3, p4) -> float:
-    """
-    Dihedral angle between planes (p1,p2,p3) and (p1,p2,p4).
-    p1-p2 is the hinge edge. p3 and p4 are wing tips.
-
-         p3
-        / | \
-       /  |  \
-    p1----+----p2   (hinge edge)
-       \  |  /
-        \ | /
-         p4
-
-    Returns angle in radians. 0 = flat, π = folded 180°.
-    """
-    e = p2 - p1                        # hinge edge vector
-    n1 = np.cross(p3 - p1, e)         # normal of face 1
-    n2 = np.cross(e, p4 - p1)         # normal of face 2
-    n1 = n1 / np.linalg.norm(n1)
-    n2 = n2 / np.linalg.norm(n2)
-
-    cos_theta = np.clip(np.dot(n1, n2), -1, 1)
-    sin_theta = np.dot(np.cross(n1, n2), e / np.linalg.norm(e))
-    return np.arctan2(sin_theta, cos_theta)
-```
-
-### 4.4 Validation (`validation.py`)
-
-```python
-def validate_state(paper: PaperState) -> dict:
-    """Run all validation checks. Returns violation report."""
-    return {
-        # ── Kawasaki-Justin theorem ───────────────────
-        # At each interior vertex: alternating angle sum = 180°
-        "kawasaki_violations": count_kawasaki_violations(paper),
-        "kawasaki_total_error": sum_kawasaki_error(paper),  # degrees
-
-        # ── Maekawa-Justin theorem ────────────────────
-        # At each interior vertex: |M - V| = 2
-        "maekawa_violations": count_maekawa_violations(paper),
-
-        # ── Self-intersection ─────────────────────────
-        # Triangle-triangle intersection test on all non-adjacent face pairs
-        "self_intersections": count_self_intersections(paper),
-
-        # ── Material limits ───────────────────────────
-        # Is max strain within material tolerance?
-        "strain_exceeded": bool(np.max(paper.strain_per_vertex) > paper.material.max_strain),
-        "max_strain_ratio": float(np.max(paper.strain_per_vertex) / paper.material.max_strain),
-
-        # ── Summary ───────────────────────────────────
-        "is_valid": (
-            count_kawasaki_violations(paper) == 0 and
-            count_maekawa_violations(paper) == 0 and
-            count_self_intersections(paper) == 0 and
-            np.max(paper.strain_per_vertex) <= paper.material.max_strain
-        ),
-    }
-```
-
-**Kawasaki check:**
-
-```python
-def check_kawasaki_at_vertex(paper, vertex_idx) -> float:
-    """Returns angular error in degrees. 0 = valid."""
-    # Get all crease edges incident on this vertex, sorted by angle
-    angles = get_sorted_crease_angles(paper, vertex_idx)
-    if len(angles) < 2:
-        return 0.0
-    # Alternating sum: a1 - a2 + a3 - a4 + ... should = 0
-    alternating = sum(a * (-1)**i for i, a in enumerate(angles))
-    return abs(alternating)
-```
-
-**Self-intersection detection:**
-
-```python
-def count_self_intersections(paper) -> int:
-    """Triangle-triangle intersection test. O(F²) but F is small for our models."""
-    triangles = paper.triangulated_faces
-    count = 0
-    for i in range(len(triangles)):
-        for j in range(i + 2, len(triangles)):  # skip adjacent faces
-            if not faces_share_edge(triangles[i], triangles[j]):
-                if triangles_intersect(
-                    paper.vertices_coords[triangles[i]],
-                    paper.vertices_coords[triangles[j]]
-                ):
-                    count += 1
-    return count
-```
-
-### 4.5 Metrics (`metrics.py`)
-
-All metrics computed from PaperState + task. Returns flat dict for the Observation.
-
-```python
-def compute_all_metrics(paper: PaperState, task: dict, validation: dict) -> dict:
-    """Compute every metric. Called after physics + validation."""
-
-    original_area = paper.width * paper.height
-    bb = paper.bounding_box  # (3,) array
-    original_bbox_vol = paper.width * paper.height * paper.material.thickness_mm / 1000
-    folded_bbox_vol = bb[0] * bb[1] * bb[2]
-
-    return {
-        # ── Validity (from validation) ────────────────
-        "is_valid": validation["is_valid"],
-        "kawasaki_violations": validation["kawasaki_violations"],
-        "kawasaki_total_error": validation["kawasaki_total_error"],
-        "maekawa_violations": validation["maekawa_violations"],
-        "self_intersections": validation["self_intersections"],
-        "strain_exceeded": validation["strain_exceeded"],
-
-        # ── Compactness ──────────────────────────────
-        "deployment_ratio": folded_area(paper) / original_area,
-        "compactness": 1.0 - (folded_area(paper) / original_area),
-        "volume_compaction": folded_bbox_vol / original_bbox_vol if original_bbox_vol > 0 else 0,
-        "packing_efficiency": material_volume(paper) / folded_bbox_vol if folded_bbox_vol > 0 else 0,
-        "fits_target_box": fits_in_box(bb, task.get("target_box")),
-        "bounding_box": bb.tolist(),
-
-        # ── Structural ───────────────────────────────
-        "max_strain": float(np.max(paper.strain_per_vertex)),
-        "mean_strain": float(np.mean(paper.strain_per_vertex)),
-        "total_energy": paper.energy["total"],
-        "energy_bar": paper.energy["bar"],
-        "energy_facet": paper.energy["facet"],
-        "energy_fold": paper.energy["fold"],
-
-        # ── Efficiency ───────────────────────────────
-        "fold_count": paper.fold_count,
-        "folding_efficiency": (1.0 - folded_area(paper) / original_area) / max(paper.fold_count, 1),
-        "crease_complexity": assignment_entropy(paper.edges_assignment),
-
-        # ── Deployability ────────────────────────────
-        "is_deployable": check_deployability(paper) if task.get("must_deploy") else None,
-        "deployment_force_estimate": estimate_deployment_force(paper),
-
-        # ── Shape similarity (if target given) ───────
-        "chamfer_distance": (
-            compute_chamfer_distance(paper, task["target_shape"])
-            if "target_shape" in task else None
-        ),
-        "hausdorff_distance": (
-            compute_hausdorff_distance(paper, task["target_shape"])
-            if "target_shape" in task else None
-        ),
-    }
-```
-
-### 4.6 Materials (`materials.py`)
-
-```python
-@dataclass
-class Material:
-    name: str
-    thickness_mm: float          # mm
-    youngs_modulus_gpa: float    # GPa
-    max_strain: float            # fraction (0.05 = 5%)
-    poisson_ratio: float = 0.3
-    density_kg_m3: float = 1000.0
-
-    # Derived stiffness parameters (for physics solver)
-    @property
-    def k_axial(self) -> float:
-        """Axial stiffness coefficient."""
-        return self.youngs_modulus_gpa * 1e9 * (self.thickness_mm / 1000)
-
-    @property
-    def k_facet(self) -> float:
-        """Facet bending stiffness."""
-        t = self.thickness_mm / 1000
-        E = self.youngs_modulus_gpa * 1e9
-        nu = self.poisson_ratio
-        return E * t**3 / (12 * (1 - nu**2))
-
-MATERIALS = {
-    "paper": Material(
-        name="paper",
-        thickness_mm=0.1,
-        youngs_modulus_gpa=3.0,
-        max_strain=0.05,          # 5% — paper is forgiving
-        poisson_ratio=0.3,
-        density_kg_m3=700,
-    ),
-    "mylar": Material(
-        name="mylar",
-        thickness_mm=0.05,
-        youngs_modulus_gpa=4.0,
-        max_strain=0.03,          # 3% — space-grade film
-        poisson_ratio=0.38,
-        density_kg_m3=1390,
-    ),
-    "aluminum": Material(
-        name="aluminum",
-        thickness_mm=0.2,
-        youngs_modulus_gpa=70.0,
-        max_strain=0.01,          # 1% — rigid, cracks easily at creases
-        poisson_ratio=0.33,
-        density_kg_m3=2700,
-    ),
-    "nitinol": Material(
-        name="nitinol",
-        thickness_mm=0.15,
-        youngs_modulus_gpa=75.0,
-        max_strain=0.08,          # 8% — superelastic shape memory alloy
-        poisson_ratio=0.33,
-        density_kg_m3=6450,
-    ),
-}
-```
-
----
-
-## 5. Renderer (`server/renderer/`)
-
-### 5.1 2D Crease Pattern (`render_2d.py`)
-
-```python
-def render_crease_pattern(paper: PaperState, output_path: str = None) -> Image:
-    """
-    matplotlib: crease pattern with standard origami colors.
-
-    Edge colors:
-      M (mountain) = red, dashed (dash-dot-dot)
-      V (valley)   = blue, dash-dot
-      B (boundary)  = black, solid
-      F (flat)     = lightgray, solid thin
-      U (unassigned) = gray, dotted
-
-    Also renders:
-      - Vertex dots (gray)
-      - Fold angle labels (optional)
-      - Sheet dimensions annotation
-    """
-
-def render_crease_pattern_svg(paper: PaperState) -> str:
-    """Returns inline SVG string (for React frontend fallback)."""
-```
-
-### 5.2 3D Folded View (`render_3d.py`)
-
-```python
-def render_folded_state(paper: PaperState, output_path: str = None,
-                        view_angle: tuple = (30, 45)) -> Image:
-    """
-    matplotlib mplot3d: wireframe + face shading with strain colors.
-
-    - Faces colored by strain: blue (0) → yellow → red (max)
-    - Edges drawn: M=red, V=blue, B=black
-    - Colorbar showing strain scale
-    - Bounding box wireframe overlay
-    """
-
-def render_strain_heatmap(paper: PaperState, output_path: str = None) -> Image:
-    """
-    Top-down view of strain distribution.
-    Uses matplotlib tricontourf for smooth interpolation.
-    Colorbar: blue (0 strain) → red (max strain).
-    Material limit marked as dashed line on colorbar.
-    """
-
-def render_side_by_side(paper: PaperState, output_path: str = None) -> Image:
-    """
-    Combined figure:
-    Left: 2D crease pattern
-    Right: 3D folded state with strain colors
-    Bottom: metrics text summary
-    """
-```
-
-### 5.3 Screenshots (`screenshots.py`)
-
-```python
-def capture_step(paper: PaperState, step_num: int,
-                 episode_dir: str) -> dict:
-    """
-    Save renders for one step. Returns dict of file paths.
-    Creates:
-      - {episode_dir}/crease_step_{N}.png       (2D crease pattern)
-      - {episode_dir}/folded_step_{N}.png       (3D folded state)
-      - {episode_dir}/strain_step_{N}.png       (strain heatmap)
-      - {episode_dir}/state_step_{N}.fold       (FOLD JSON snapshot)
-    """
-
-def capture_episode_summary(paper: PaperState, fold_history: list,
-                            task: dict, metrics: dict,
-                            episode_dir: str) -> str:
-    """
-    Grid summary of entire episode. Returns path.
-    Creates: {episode_dir}/summary.png
-
-    Layout:
-    ┌──────┬──────┬──────┬──────┐
-    │Step 0│Step 1│Step 2│Step 3│   (crease patterns)
-    ├──────┼──────┼──────┼──────┤
-    │Step 0│Step 1│Step 2│Step 3│   (3D folded states)
-    ├──────┴──────┴──────┴──────┤
-    │  Final metrics + task     │
-    └───────────────────────────┘
-    """
-```
-
-### 5.4 Recording (`recorder.py`)
-
-```python
-def record_fold_animation(paper_initial: PaperState, fold_history: list,
-                          output_path: str, fps: int = 15,
-                          frames_per_fold: int = 10) -> str:
-    """
-    Generate animated GIF of the folding sequence.
-
-    For each fold in history:
-      - Interpolate fold_percent from 0.0 to 1.0 over frames_per_fold frames
-      - Run physics at each fold_percent
-      - Render 3D frame via matplotlib
-    Assemble frames into GIF via imageio.
-
-    Returns path to GIF.
-    """
-
-def record_strain_evolution(paper_initial: PaperState, fold_history: list,
-                            output_path: str) -> str:
-    """
-    GIF showing how strain develops through the fold sequence.
-    Useful for understanding which folds cause the most stress.
-    """
-```
-
-### 5.5 Exporter (`exporter.py`)
-
-```python
-def export_fold_json(paper: PaperState, fold_history: list) -> dict:
-    """
-    Full FOLD JSON with multi-frame animation data.
-    Can be loaded by OrigamiSimulator or our React frontend.
-
-    Includes:
-      - file_spec, file_creator, file_classes
-      - frame_classes: ["creasePattern"]
-      - All vertex/edge/face data
-      - fold_history as custom metadata
-    """
-
-def export_obj(paper: PaperState) -> str:
-    """Wavefront OBJ format for 3D printing / external renderers."""
-
-def export_stl(paper: PaperState) -> bytes:
-    """STL binary format for 3D printing."""
-```
-
----
-
-## 6. Environment (`server/origami_environment.py`)
-
-The OpenEnv wrapper. Calls engine + renderer. Does NOT contain origami logic.
-
-```python
-class OrigamiEnvironment(Environment[OrigamiAction, OrigamiObservation, OrigamiState]):
-    SUPPORTS_CONCURRENT_SESSIONS = False
-
-    def __init__(self):
-        self._paper = None
-        self._task = None
-        self._fold_history = []
-        self._metrics = {}
-        self._validation = {}
-        self._error = None
-        self._episode_id = None
-        self._step_count = 0
-        self._episode_dir = None       # for renders
-
-    # ── reset ─────────────────────────────────────────
-
-    def reset(self, seed=None, episode_id=None, **kwargs) -> OrigamiObservation:
-        self._episode_id = episode_id or str(uuid.uuid4())
-        self._step_count = 0
-        self._fold_history = []
-        self._error = None
-
-        # Create episode render directory
-        self._episode_dir = f"renders/ep_{self._episode_id[:8]}"
-        os.makedirs(self._episode_dir, exist_ok=True)
-
-        # Sample task
-        self._task = kwargs.get("task") or sample_task(seed=seed)
-
-        # Create flat sheet
-        self._paper = create_flat_sheet(
-            self._task["width"], self._task["height"],
-            MATERIALS[self._task["material"]] if isinstance(self._task["material"], str)
-            else self._task["material"]
-        )
-
-        # Initial metrics + validation
-        self._validation = validate_state(self._paper)
-        self._metrics = compute_all_metrics(self._paper, self._task, self._validation)
-
-        # Render initial state
-        render_urls = capture_step(self._paper, 0, self._episode_dir)
-
-        return self._make_observation(done=False, reward=None, render_urls=render_urls)
-
-    # ── step ──────────────────────────────────────────
-
-    def step(self, action: OrigamiAction, timeout_s=None, **kwargs) -> OrigamiObservation:
-        self._step_count += 1
-        self._error = None
-
-        # ── Handle "stop" action ──────────────────────
-        if action.fold_type == "stop":
-            return self._finalize_episode()
-
-        # ── Apply fold ────────────────────────────────
-        fold_dict = {
-            "type": action.fold_type,
-            "line": action.fold_line,
-            "angle": action.fold_angle,
-            "layer_select": action.layer_select,
-        }
-
-        try:
-            self._paper = apply_fold(self._paper, fold_dict)
-            self._fold_history.append({**fold_dict, "step": self._step_count})
-        except FoldError as e:
-            self._error = str(e)
-            return self._make_observation(done=True, reward=-5.0, render_urls={})
-
-        # ── Run physics ───────────────────────────────
-        try:
-            self._paper = simulate(self._paper, fold_percent=1.0)
-        except Exception as e:
-            self._error = f"Physics failed: {e}"
-
-        # ── Validate ──────────────────────────────────
-        self._validation = validate_state(self._paper)
-
-        # ── Compute metrics ───────────────────────────
-        self._metrics = compute_all_metrics(self._paper, self._task, self._validation)
-
-        # ── Render this step ──────────────────────────
-        render_urls = capture_step(self._paper, self._step_count, self._episode_dir)
-
-        # ── Check if episode should end ───────────────
-        done = False
-        reward = None
-
-        # Auto-end on max folds
-        if self._step_count >= self._task.get("max_folds", 50):
-            done = True
-
-        # Auto-end on critical failure
-        if self._validation["self_intersections"] > 0:
-            done = True
-            self._error = "Self-intersection detected"
-
-        if done:
-            return self._finalize_episode()
-
-        return self._make_observation(done=False, reward=None, render_urls=render_urls)
-
-    # ── finalize ──────────────────────────────────────
-
-    def _finalize_episode(self) -> OrigamiObservation:
-        """End episode: compute final reward, generate animation GIF, export FOLD."""
-        reward = self._compute_reward()
-
-        render_urls = capture_step(self._paper, self._step_count, self._episode_dir)
-
-        # Episode summary image
-        summary_path = capture_episode_summary(
-            self._paper, self._fold_history, self._task, self._metrics, self._episode_dir
-        )
-        render_urls["episode_summary"] = summary_path
-
-        # Fold animation GIF
-        try:
-            gif_path = record_fold_animation(
-                create_flat_sheet(self._task["width"], self._task["height"], self._task["material"]),
-                self._fold_history,
-                f"{self._episode_dir}/animation.gif"
-            )
-            render_urls["episode_gif"] = gif_path
-        except Exception:
-            pass  # non-critical
-
-        # FOLD JSON export
-        fold_json = export_fold_json(self._paper, self._fold_history)
-        fold_path = f"{self._episode_dir}/state.fold"
-        with open(fold_path, "w") as f:
-            json.dump(fold_json, f)
-        render_urls["fold_json"] = fold_path
-
-        return self._make_observation(done=True, reward=reward, render_urls=render_urls)
-
-    # ── state ─────────────────────────────────────────
-
-    @property
-    def state(self) -> OrigamiState:
-        return OrigamiState(
-            episode_id=self._episode_id,
-            step_count=self._step_count,
-            task_name=self._task["name"] if self._task else "",
-            num_folds_applied=len(self._fold_history),
-            is_valid=self._metrics.get("is_valid", True),
-            total_reward=0.0,
-        )
-
-    # ── helpers ───────────────────────────────────────
-
-    def _make_observation(self, done, reward, render_urls) -> OrigamiObservation:
-        return OrigamiObservation(
-            done=done,
-            reward=reward,
-            task=self._task or {},
-            paper_state=self._paper.to_observation_dict() if self._paper else {},
-            metrics=self._metrics,
-            fold_history=self._fold_history,
-            error=self._error,
-            render_urls=render_urls,
-        )
-
-    def _compute_reward(self) -> float:
-        m = self._metrics
-        reward = 0.0
-        reward += m.get("compactness", 0) * 20.0
-        if m.get("fits_target_box", False): reward += 10.0
-        if m.get("is_deployable", False): reward += 5.0
-        reward -= m.get("kawasaki_violations", 0) * 2.0
-        reward -= m.get("maekawa_violations", 0) * 2.0
-        reward -= m.get("self_intersections", 0) * 5.0
-        reward -= m.get("fold_count", 0) * 0.5
-        max_strain = m.get("max_strain", 0)
-        limit = self._paper.material.max_strain if self._paper else 0.05
-        if max_strain > limit: reward -= 3.0 * (max_strain / limit)
-        return reward
-```
-
----
-
-## 7. App + Docker (`server/app.py` + `server/Dockerfile`)
-
-### `app.py`
-
-```python
-"""FastAPI entry point — serves OpenEnv API + React frontend + renders."""
-from fastapi import FastAPI
-from fastapi.staticfiles import StaticFiles
-from openenv.core.env_server.http_server import create_app
-
-from models import OrigamiAction, OrigamiObservation
-from origami_environment import OrigamiEnvironment
-
-# OpenEnv app (handles /ws, /reset, /step, /state, /health)
-app = create_app(
-    OrigamiEnvironment,
-    OrigamiAction,
-    OrigamiObservation,
-    env_name="origami_env",
-)
-
-# Serve rendered images/GIFs/FOLD exports
-app.mount("/renders", StaticFiles(directory="renders"), name="renders")
-app.mount("/export", StaticFiles(directory="renders"), name="export")
-
-# Serve React frontend (built at Docker build time)
-app.mount("/", StaticFiles(directory="../web/dist", html=True), name="frontend")
-```
-
-### `Dockerfile`
-
-```dockerfile
-FROM ghcr.io/meta-pytorch/openenv-base:latest
-
-# ── Install Node.js for React build ──────────────────
-RUN apt-get update && apt-get install -y nodejs npm && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-
-# ── Python dependencies ──────────────────────────────
-COPY server/requirements.txt ./server/
-RUN pip install --no-cache-dir -r server/requirements.txt
-
-# ── Build React frontend ─────────────────────────────
-COPY web/ ./web/
-RUN cd web && npm install && npm run build
-
-# ── Copy server code ─────────────────────────────────
-COPY server/ ./server/
-
-# ── Create renders directory ──────────────────────────
-RUN mkdir -p /app/server/renders
-
-WORKDIR /app/server
-
-EXPOSE 8000
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
-```
-
-### `requirements.txt`
-
-```
-openenv-core[core]>=0.2.1
-numpy>=1.24
-scipy>=1.10
-pydantic>=2.0
-matplotlib>=3.7
-imageio>=2.31
-Pillow>=10.0
-```
-
-### `openenv.yaml`
-
-```yaml
-spec_version: 1
-name: origami_env
-type: space
-runtime: fastapi
-app: server.app:app
-port: 8000
-```
-
----
-
-## 8. React Frontend (`web/`)
-
-### Layout
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  ORIGAMI RL ENVIRONMENT        [Task: ▼] [Material: ▼]     │
-├──────────────────────────┬──────────────────────────────────┤
-│                          │                                   │
-│   CREASE PATTERN (2D)    │      FOLDED STATE (3D)           │
-│                          │                                   │
-│   SVG                    │    R3F Canvas                     │
-│   M = red dashed         │    OrbitControls (rotate/zoom)    │
-│   V = blue dash-dot      │    Vertex colors = strain         │
-│   B = black solid        │    DoubleSide material            │
-│                          │    Ambient + directional light    │
-│                          │                                   │
-├──────────────────────────┴──────────────────────────────────┤
-│  [|<] [<] [>] [>|]  ████████░░░░ Step 4 / 8                │
-│                      [Play] [Pause]   Speed: [1x ▼]        │
-├─────────────────────────────────────────────────────────────┤
-│  METRICS                                                     │
-│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │
-│  │Compactness│ │Max Strain │ │Fold Count │ │  Validity   │ │
-│  │   85.0%   │ │  0.021    │ │     8     │ │   VALID     │ │
-│  └───────────┘ └───────────┘ └───────────┘ └────────��────┘ │
-│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │
-│  │Deploy Rat.│ │  Energy   │ │Pack Eff.  │ │Fits Target  │ │
-│  │   15.2x   │ │   0.34    │ │   72%     │ │     YES     │ │
-│  └───────────┘ └───────────┘ └───────────┘ └─────────────┘ │
-├─────────────────────────────────────────────────────────────┤
-│  [Screenshot PNG]  [Record GIF]  [Export FOLD]  [Export OBJ]│
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Data Flow
-
-```
-React App
-  │
-  ├── useEnvironment() hook
-  │     │
-  │     ├── WebSocket connect to /ws
-  │     ├── reset() → receives OrigamiObservation
-  │     ├── step(action) → receives OrigamiObservation
-  │     └── Parses: paper_state, metrics, fold_history, render_urls
-  │
-  ├── CreasePattern.tsx
-  │     └── Reads: paper_state.vertices_coords[:, :2], edges_vertices, edges_assignment
-  │         Renders: SVG <line> elements with color/dash per assignment
-  │
-  ├── FoldedView3D.tsx
-  │     └── Reads: paper_state.vertices_coords[:, :3], faces_vertices, strain_per_vertex
-  │         Renders: R3F <mesh> with BufferGeometry
-  │           positions → Float32Array from vertices_coords
-  │           index → Uint16Array from triangulated faces_vertices
-  │           colors → Float32Array from Lut(strain_per_vertex) blue→red
-  │
-  ├── FoldAnimation.tsx
-  │     └── Reads: fold_history, paper_state per step
-  │         Controls: step slider, play/pause, speed
-  │         Interpolates fold_percent 0→1 via useFrame
-  │
-  ├── MetricsDashboard.tsx
-  │     └── Reads: metrics dict → renders cards
-  │
-  └── CaptureControls.tsx
-        ├── Screenshot: gl.domElement.toDataURL('image/png') (preserveDrawingBuffer=true)
-        └── Record: canvas.captureStream(30) + MediaRecorder → WebM blob → download
-```
-
-### Key R3F Pattern
-
-```tsx
-// FoldedView3D.tsx — core rendering
-<Canvas gl={{ preserveDrawingBuffer: true, antialias: true }}>
-  <PerspectiveCamera makeDefault position={[0, 2, 3]} />
-  <OrbitControls />
-  <ambientLight intensity={0.4} />
-  <directionalLight position={[5, 5, 5]} intensity={0.8} />
-
-  <mesh>
-    <bufferGeometry>
-      <bufferAttribute attach="attributes-position"
-        array={positionsFloat32} count={vertexCount} itemSize={3} />
-      <bufferAttribute attach="attributes-color"
-        array={strainColorsFloat32} count={vertexCount} itemSize={3} />
-      <bufferAttribute attach="index"
-        array={indicesUint16} count={indexCount} itemSize={1} />
-    </bufferGeometry>
-    <meshStandardMaterial vertexColors side={DoubleSide} />
-  </mesh>
-
-  {/* Crease lines in 3D */}
-  {edges.map((edge, i) => (
-    <Line key={i}
-      points={[vertices[edge[0]], vertices[edge[1]]]}
-      color={assignmentColor(assignments[i])}
-      lineWidth={assignments[i] === 'B' ? 2 : 1}
-      dashed={assignments[i] === 'M' || assignments[i] === 'V'}
-    />
-  ))}
-</Canvas>
-```
-
----
-
-## 9. Client (`client/`)
-
-### `client.py`
-
-```python
-class OrigamiEnvClient(EnvClient[OrigamiAction, OrigamiObservation, OrigamiState]):
-
-    def _step_payload(self, action: OrigamiAction) -> Dict:
-        return {
-            "fold_type": action.fold_type,
-            "fold_line": action.fold_line,
-            "fold_angle": action.fold_angle,
-            "layer_select": action.layer_select,
-            "metadata": action.metadata,
-        }
-
-    def _parse_result(self, payload: Dict) -> StepResult[OrigamiObservation]:
-        obs = OrigamiObservation(**payload.get("observation", payload))
-        return StepResult(observation=obs, reward=obs.reward)
-
-    def _parse_state(self, payload: Dict) -> OrigamiState:
-        return OrigamiState(**payload)
-```
-
-### `reward_functions.py`
-
-Three reward functions for GRPO training. These run on the Colab client side, NOT on the server.
-
-The strategy function extracted from LLM output calls `step()` in a loop (same pattern as 2048):
-
-```python
-def _execute_strategy(strategy_fn, openenv_process):
-    """
-    Execute a fold_strategy against the environment.
-    strategy_fn takes paper_state dict, returns one fold dict or None (stop).
-    Loops until done or strategy returns None.
-    """
-    result = openenv_process.reset()
-    obs = result.observation
-
-    while not obs.done:
-        paper_state = obs.paper_state
-        fold = strategy_fn(paper_state)
-
-        if fold is None:
-            # Strategy says stop
-            action = OrigamiAction(fold_type="stop", fold_line={"start":[0,0],"end":[0,0]})
-        else:
-            action = OrigamiAction(
-                fold_type=fold.get("type", "valley"),
-                fold_line=fold.get("line", {"start":[0,0.5],"end":[1,0.5]}),
-                fold_angle=fold.get("angle", 180),
-            )
-
-        result = openenv_process.step(action)
-        obs = result.observation
-
-    return obs
-```
-
-Reward functions: `code_valid`, `no_cheating`, `fold_quality` — same structure as 2048 (extract function, sandbox, execute, score from metrics).
-
----
-
-## 10. Task System (`server/tasks.py`)
-
-### Curriculum (4 difficulty levels)
-
-| Level | Task | Material | Target Ratio | Max Folds | Key Challenge |
-|-------|------|----------|-------------|-----------|---------------|
-| 1 | half_fold | paper | 0.50 | 3 | Learn the format |
-| 1 | quarter_fold | paper | 0.25 | 5 | Two perpendicular folds |
-| 2 | letter_fold | paper | 0.33 | 5 | Tri-fold, parallel lines |
-| 2 | map_fold | paper | 0.125 | 8 | Grid fold, must deploy |
-| 3 | solar_panel | mylar | 0.05 | 20 | Miura-ori discovery, deployability |
-| 3 | shelter_wall | aluminum | 0.10 | 15 | Rigid material, strain limits |
-| 4 | stent | nitinol | 0.09 | 25 | Cylindrical target shape, superelastic |
-
-### How Tasks Drive Reward
-
-- **target_ratio** → compactness reward signal
-- **target_box** → fits_target_box bonus (+10.0)
-- **must_deploy** → deployability bonus (+5.0)
-- **material.max_strain** → strain penalty threshold
-- **max_folds** → episode length limit
-- **target_shape** → shape similarity metrics (chamfer/hausdorff)
-
----
-
-## 11. API Reference
-
-### Endpoints (provided by OpenEnv + our extensions)
-
-| Endpoint | Method | Purpose |
-|----------|--------|---------|
-| `/health` | GET | `{"status": "ok", "env_name": "origami_env"}` |
-| `/ws` | WebSocket | Main OpenEnv communication channel |
-| `/reset` | POST | Reset environment, get initial observation |
-| `/step` | POST | Send action, get observation |
-| `/state` | GET | Get current OrigamiState |
-| `/renders/{episode_id}/*` | GET | Serve screenshots, GIFs, FOLD exports |
-| `/` | GET | React frontend (static) |
-
-### WebSocket Message Format
-
-```json
-// Client → Server (step)
-{
-  "type": "step",
-  "action": {
-    "fold_type": "valley",
-    "fold_line": {"start": [0, 0.5], "end": [1, 0.5]},
-    "fold_angle": 180,
-    "layer_select": "all"
-  }
-}
-
-// Server → Client (observation)
-{
-  "type": "observation",
-  "observation": {
-    "done": false,
-    "reward": null,
-    "task": {...},
-    "paper_state": {...},
-    "metrics": {...},
-    "fold_history": [...],
-    "error": null,
-    "render_urls": {
-      "crease_2d": "/renders/ep_abc123/crease_step_1.png",
-      "folded_3d": "/renders/ep_abc123/folded_step_1.png",
-      "strain_heatmap": "/renders/ep_abc123/strain_step_1.png"
-    }
-  }
-}
-```
-
----
-
-## 12. Deployment
-
-### Push to HF Spaces
-
-```bash
-cd origami_env/
-openenv push --repo-id <username>/origami-env
-```
-
-### Or manually via Docker
-
-```bash
-# Build
-docker build -t origami-env -f server/Dockerfile .
-
-# Run locally
-docker run -p 8000:8000 origami-env
-
-# Test
-curl http://localhost:8000/health
-```
-
-### HF Space README header
-
-```yaml
----
-title: Origami RL Environment
-emoji: 🔬
-colorFrom: blue
-colorTo: red
-sdk: docker
-app_port: 8000
-pinned: true
----
-```
-
----
-
-## 13. Testing Checklist
-
-```bash
-# 1. Engine standalone
-python -c "
-from server.engine.paper import create_flat_sheet
-from server.engine.materials import MATERIALS
-p = create_flat_sheet(1.0, 1.0, MATERIALS['paper'])
-print(f'Vertices: {p.vertices_coords.shape}, Edges: {p.edges_vertices.shape}')
-"
-
-# 2. Fold works
-python -c "
-from server.engine.paper import create_flat_sheet
-from server.engine.fold import apply_fold
-from server.engine.materials import MATERIALS
-p = create_flat_sheet(1.0, 1.0, MATERIALS['paper'])
-p = apply_fold(p, {'type':'valley','line':{'start':[0,0.5],'end':[1,0.5]},'angle':180})
-print(f'After fold: {p.vertices_coords.shape[0]} vertices, fold_count={p.fold_count}')
-"
-
-# 3. Physics runs
-python -c "
-from server.engine.paper import create_flat_sheet
-from server.engine.fold import apply_fold
-from server.engine.physics import simulate
-from server.engine.materials import MATERIALS
-p = create_flat_sheet(1.0, 1.0, MATERIALS['paper'])
-p = apply_fold(p, {'type':'valley','line':{'start':[0,0.5],'end':[1,0.5]},'angle':180})
-p = simulate(p)
-print(f'Max strain: {p.strain_per_vertex.max():.6f}, Energy: {p.energy}')
-"
-
-# 4. Validation works
-python -c "
-from server.engine.validation import validate_state
-# ... create + fold paper ...
-report = validate_state(p)
-print(f'Valid: {report[\"is_valid\"]}, Kawasaki: {report[\"kawasaki_violations\"]}')
-"
-
-# 5. Metrics computed
-python -c "
-from server.engine.metrics import compute_all_metrics
-# ... create + fold + validate paper ...
-m = compute_all_metrics(p, task, validation)
-print(f'Compactness: {m[\"compactness\"]:.3f}, Fits box: {m[\"fits_target_box\"]}')
-"
-
-# 6. Renderer works
-python -c "
-from server.renderer.render_2d import render_crease_pattern
-from server.renderer.render_3d import render_folded_state
-# ... create + fold paper ...
-render_crease_pattern(p, 'test_crease.png')
-render_folded_state(p, 'test_folded.png')
-print('Renders saved')
-"
-
-# 7. Server starts
-cd server && uvicorn app:app --port 8000 &
-curl http://localhost:8000/health
-
-# 8. Reset + step via API
-python -c "
-from client.client import OrigamiEnvClient
-c = OrigamiEnvClient('ws://localhost:8000')
-obs = c.reset()
-print(f'Task: {obs.task[\"name\"]}, Sheet: {obs.paper_state[\"num_vertices\"]} vertices')
-"
-
-# 9. React frontend builds
-cd web && npm install && npm run build
-# Check web/dist/index.html exists
-
-# 10. Docker builds and runs
-docker build -t origami-env -f server/Dockerfile .
-docker run -p 8000:8000 origami-env
-curl http://localhost:8000/health
-# Open http://localhost:8000 in browser — see React UI
-```

research 2/research.md

@@ -1,74 +0,0 @@
-# Origami RL Environment — Research Index
-
-## What We're Building
-An OpenEnv environment where an LLM learns to design optimal origami fold patterns — solar panel packing, deployable structures, medical stents. LLM generates a `fold_strategy()` function (code-as-policy), executed against a bar-and-hinge physics simulation.
-
----
-
-## Architecture (START HERE)
-
-| File | What's In It |
-|------|-------------|
-| **[plan/architecture.md](plan/architecture.md)** | **Full architecture: action space, state, physics, rewards, rendering, project structure, implementation order** |
-| **[plan/openenv_arch.md](plan/openenv_arch.md)** | **Complete OpenEnv environment: repo structure, Pydantic models, engine (paper/fold/physics/validation/metrics/materials), renderer (2D/3D/screenshots/GIF recording/export), environment class, React frontend, app+Docker, client, task system, API reference, deployment, testing** |
-
-### Decisions (Locked)
-
-| Decision | Choice |
-|----------|--------|
-| LLM interaction | Code-as-policy (LLM writes `fold_strategy()` function) |
-| Action space | Named fold ops (valley/mountain + fold line + angle) |
-| State format | FOLD-compatible JSON |
-| Physics engine | Bar-and-hinge model (NumPy port of Ghassaei) |
-| Validation | Kawasaki + Maekawa + triangle-triangle intersection |
-| Primary task | Solar panel packing (Miura-ori discovery) |
-| Training render | matplotlib headless |
-| Demo render | React + @react-three/fiber |
-| Training | GRPO via TRL + Unsloth on Colab |
-| Deployment | Docker Space on HF Spaces |
-
----
-
-## OpenEnv (The Framework)
-
-| File | What's In It |
-|------|-------------|
-| [openenv/overview.md](openenv/overview.md) | OpenEnv architecture, API, types, project structure, deployment |
-| [openenv/2048_pattern.md](openenv/2048_pattern.md) | Code-as-policy pattern, reward functions, GRPO training |
-| [openenv/2048_example.py](openenv/2048_example.py) | Full extracted code from Unsloth 2048 Colab (636 lines) |
-
----
-
-## Origami Domain Knowledge
-
-### Quick Reference
-| File | What's In It |
-|------|-------------|
-| [origami/fold_types_deep.md](origami/fold_types_deep.md) | **All fold operations**, Huzita-Justin axioms, crane step-by-step (31 steps), compression patterns (Miura-ori, Kresling, flasher), complexity scaling |
-| [origami/math_physics_deep.md](origami/math_physics_deep.md) | **Kawasaki/Maekawa theorems** with code, bar-and-hinge model, energy formulas, strain computation, rigid foldability, computational complexity table |
-| [origami/rendering_research.md](origami/rendering_research.md) | **Rendering options**: Ghassaei simulator, OrigamiOdyssey (R3F), Three.js in React, Gradio integration, recording |
-| [origami/applications_deep.md](origami/applications_deep.md) | **Real-world apps**: NASA solar panels, JWST, stents, self-folding robots, metamaterials |
-
-### Earlier Research (Summaries)
-| File | What's In It |
-|------|-------------|
-| [origami/simulation_engines.md](origami/simulation_engines.md) | Ghassaei, rigid-origami Gym env, SWOMPS, Tachi |
-| [origami/fold_format.md](origami/fold_format.md) | FOLD file format — JSON standard for crease patterns |
-| [origami/physics.md](origami/physics.md) | Physics summary (Kawasaki, Maekawa, simulation approaches) |
-| [origami/materials.md](origami/materials.md) | Material properties (paper, mylar, aluminum), stress viz |
-| [origami/metrics.md](origami/metrics.md) | All metrics: validity, compactness, stress, shape similarity |
-| [origami/existing_work.md](origami/existing_work.md) | Prior work: IJCAI 2023, Nature 2022, UCLA robotics |
-| [origami/python_tools.md](origami/python_tools.md) | Libraries: rigid-origami, PyOri, numpy, trimesh |
-
----
-
-## Deliverables Checklist
-
-- [ ] Engine: paper.py, fold_engine.py, physics.py, validation.py, metrics.py
-- [ ] OpenEnv server: models.py, origami_environment.py, app.py, Dockerfile
-- [ ] Reward functions: code_valid, physically_valid, fold_quality
-- [ ] Training notebook: Colab with GRPO + Unsloth/TRL
-- [ ] Rendering: matplotlib (training) + React/R3F (demo)
-- [ ] Deploy to HF Spaces
-- [ ] 1-minute demo video on YouTube
-- [ ] Public GitHub repo