perf(cache): cheaper shape restore, no private values, compressed geometry

Adding a child no longer refreshes the subtree's tag cache unless a tag can
pass down; restore indexes entities by position and refreshes tag caches once;
the cell cache stores no underscore names' values; BinTools bytes are zlib'd.
Desktop-arm benchmark: no-change run 23.6s -> 7.0s.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-10-20 23:18:40 +08:00
parent 19381d86fd
commit 999439d939
8 changed files with 495 additions and 11 deletions
+6
View File
@@ -8,6 +8,12 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
### Changed
- Cache and pickling: restoring a cached shape is about 40% faster (adding a child to a
shape no longer refreshes its whole subtree's tag cache unless a tag can pass down; the
restore finds entities by position instead of scanning, and refreshes each tag cache
once). The cache no longer stores a cell's private (`_name`) variables, and the geometry
bytes in a pickle are compressed (zlib, level 1); entries written before are still read.
On the desktop-arm benchmark a no-change run drops from 23.6 s to 7.0 s.
- Cache: a cell that does `from lib.dims import A` now depends on the definition of `A` (and
what it reads, across local modules), not on the whole file. Editing another name of
`lib/dims.py`, a comment, or the formatting leaves the cell cached. A module the analysis
+68 -10
View File
@@ -19,6 +19,7 @@ from __future__ import annotations
import io
import re
import zlib
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Set, Tuple
@@ -93,6 +94,20 @@ def _write_shape(shape: TopoDS_Shape) -> bytes:
return stream.getvalue()
_PACKED = b"SCZ1"
"""Starts a payload stored compressed; entries written before it was
introduced hold the BinTools bytes as they are, and are still read."""
def _pack(raw: bytes) -> bytes:
# BinTools is bit-exact doubles: level 1 gets most of the ~10x for little time.
return _PACKED + zlib.compress(raw, 1)
def _unpack(payload: bytes) -> bytes:
return zlib.decompress(payload[len(_PACKED) :]) if payload.startswith(_PACKED) else payload
def _read_shape(payload: bytes) -> TopoDS_Shape:
shape = TopoDS_Shape()
BinTools.Read_s(shape, io.BytesIO(payload))
@@ -156,15 +171,55 @@ def _capture_states(wrapper: "AnyShape") -> Tuple[_EntityState, ...]:
return tuple(states)
def _find_entity(
cache: "_TopologyEntityCache", kind: str, shape: TopoDS_Shape
) -> "_TopoEntity | None":
"""Look an entity up without creating one (``cache.get`` would)."""
def _entities_by_position(
cache: "_TopologyEntityCache", kind: str, shapes: TopTools_IndexedMapOfShape
) -> Dict[int, "_TopoEntity"]:
"""The entity of each position in *shapes* (``FindIndex`` is ``IsSame``),
found in one pass rather than one scan per position."""
found: Dict[int, "_TopoEntity"] = {}
for entity in cache.entities(kind):
if entity.representative.IsSame(shape):
return entity
return None
position = shapes.FindIndex(entity.representative)
if position > 0:
found.setdefault(position, entity)
return found
def _refresh_restored_tags(wrapper: "AnyShape") -> None:
"""Rebuild the tag cache of every wrapper under *wrapper*, once each.
The restored tree has no ancestors above *wrapper*. When none of its
bindings is passed downward, an entity's effective tags are its own
(local and legacy) and need no walk up through its parents; otherwise
the general refresh runs.
"""
from ..core import TaggedMixin, TopologyPropagation
members: List[Any] = []
seen: Set[int] = set()
stack: List[Any] = [wrapper]
while stack:
item = stack.pop()
if id(item) in seen:
continue
seen.add(id(item))
members.append(item)
stack.extend(item.get_children())
tagged = [item for item in members if isinstance(item, TaggedMixin)]
if any(
binding.propagation.topology == TopologyPropagation.DOWNWARD
for item in tagged
for binding in item._local_tag_bindings()
):
wrapper._refresh_tag_cache(recursive=True)
return
for item in tagged:
item._tag_cache.clear()
item._tag_cache.update(
binding.tag
for binding in (*item._local_tag_bindings(), *item._legacy_effective_bindings())
)
_TOPO_ID_RE = re.compile(r"^(?P<kind>[a-z]+)_(?P<index>\d+)$")
@@ -195,16 +250,18 @@ def _renumber(cache: "_TopologyEntityCache", restored: Set[int]) -> None:
def _apply_states(wrapper: "AnyShape", states: Tuple[_EntityState, ...]) -> None:
cache = wrapper._topology_cache
maps: Dict[str, TopTools_IndexedMapOfShape] = {}
by_index: Dict[str, Dict[int, "_TopoEntity"]] = {}
restored: Set[int] = set()
for state in states:
shapes = maps.get(state.kind)
if shapes is None:
shapes = maps[state.kind] = _index_map(wrapper.wrapped, state.kind)
by_index[state.kind] = _entities_by_position(cache, state.kind, shapes)
if state.index > shapes.Extent():
raise ValueError(
f"pickled {state.kind} #{state.index} is outside the restored shape"
)
entity = _find_entity(cache, state.kind, shapes.FindKey(state.index))
entity = by_index[state.kind].get(state.index)
if entity is None:
continue
entity.topo_id = state.topo_id
@@ -228,13 +285,13 @@ def _apply_states(wrapper: "AnyShape", states: Tuple[_EntityState, ...]) -> None
entity.incident_edge_ids.update(state.incident_edge_ids)
restored.add(id(entity))
_renumber(cache, restored)
wrapper._refresh_tag_cache(recursive=True)
_refresh_restored_tags(wrapper)
def reduce_shape(wrapper: "AnyShape") -> Tuple[Any, Tuple[Any, ...]]:
"""``__reduce__`` implementation shared by every topology wrapper."""
payload = source_bytes(wrapper) or _write_shape(wrapper.wrapped)
payload = _pack(source_bytes(wrapper) or _write_shape(wrapper.wrapped))
return (restore_shape, (type(wrapper).__name__, payload, _capture_states(wrapper)))
@@ -246,6 +303,7 @@ def restore_shape(
from .. import core
wrapper_type = getattr(core, class_name)
payload = _unpack(payload)
wrapper = wrapper_type(_read_shape(payload))
remember_source_bytes(wrapper, payload)
_apply_states(wrapper, states)
+20 -1
View File
@@ -940,9 +940,28 @@ class TopoMixein:
if child not in self.children:
self.children.append(child)
child.set_parent(self.self_shape_ref)
if isinstance(child, TaggedMixin):
if isinstance(child, TaggedMixin) and self._may_pass_tags_down():
child._refresh_tag_cache(recursive=True)
def _may_pass_tags_down(self) -> bool:
"""Whether a new child of this entity can inherit any tag from it.
A child's effective tags are its own plus what its ancestors pass
down; an entity that holds no downward binding, and has no ancestor
that does, adds nothing, and the child's tag cache stays right. A
shape being built (or restored) has no ancestors yet, so this spares
refreshing the whole subtree for every child added.
"""
if not isinstance(self, TaggedMixin):
return True
if any(
binding.propagation.topology == TopologyPropagation.DOWNWARD
for binding in self._local_tag_bindings()
):
return True
return bool(self._inherited_tag_bindings_with_paths())
def get_children(self) -> List["AnyShape"]:
return self.children
+12
View File
@@ -186,6 +186,18 @@ class CellCache(CachedLifecycle):
if loader is None:
return
self._loader = loader
# A name that starts with an underscore belongs to its cell: no other
# cell reads it, so storing its value only costs disk and restore time
# (a cell that builds an assembly in `_a` stored it twice). marimo
# insists that an entry has a value for every name the cell defines,
# so the name stays, with nothing in it.
attempt = self._attempts.get(cell.cell_id)
if attempt is not None and not attempt.hit:
glbls = {**glbls}
for name in attempt.defs:
if name.startswith("_"):
glbls[name] = None
glbls[f"_cell_{cell.cell_id}_{name[1:]}"] = None
super().teardown(cell, glbls, run_result)
def _invalidate(self, cell_id: CellId_t) -> None:
+28
View File
@@ -9,6 +9,7 @@ analysis cannot prove falls back to the whole file.
from __future__ import annotations
from simplecadapi.runtime import run_notebook
from simplecadapi.runtime.deps import state_dir
from simplecadapi.runtime.names import definition_digest
from test_notebook_runtime import NotebookTestCase, cell, notebook_text
@@ -117,3 +118,30 @@ class TestVariableLevelCache(NotebookTestCase):
run_notebook(self.nb, cache=False).definition.content_hash,
text,
)
class TestWhatTheCacheStores(NotebookTestCase):
"""A cell's private (underscore) names are invisible to every other cell:
storing them only costs disk and restore time."""
def test_private_names_are_not_stored_and_the_cell_is_still_restored(self) -> None:
text = notebook_text(
cell(
"""
_scratch = scad.make_box_rsolid(30.0, 30.0, 30.0)
width = 20.0
""",
returns="width",
),
cell("block = scad.make_box_rsolid(width, 4.0, 4.0)", reads="width", returns="block"),
cell("part = scad.Part(part_id='priv', body=block)", reads="block", returns="part"),
table='id = "priv"',
)
path = self.write("priv.py", text)
first = run_notebook(path)
stored = {item.stem for item in (state_dir(first.config) / "cache").rglob("*.pickle")}
self.assertIn("block", stored)
self.assertNotIn("_scratch", stored)
second = run_notebook(path)
self.assertEqual(self.statuses(second), ["ran", "cached", "cached", "cached"])
self.assertEqual(first.definition.content_hash, second.definition.content_hash)
+107
View File
@@ -0,0 +1,107 @@
"""Restoring a pickled shape: same tags as before, in time linear in its size.
A cell's value is stored as a pickle (the cell cache), and restoring it is the
main cost of a cached run. The tag cache of every entity is rebuilt on the
way; it must be rebuilt once per entity, not once per entity per ancestor.
"""
from __future__ import annotations
import pickle
import unittest
import simplecadapi as scad
from simplecadapi.core import TaggedMixin, TagScope
def entities(root):
"""Every wrapper below *root* (and *root*), once."""
seen, order, stack = set(), [], [root]
while stack:
item = stack.pop()
if id(item) in seen:
continue
seen.add(id(item))
order.append(item)
stack.extend(item.get_children())
return order
def effective_tags(root):
return {item.topo_id: frozenset(item._list_tags(TagScope.EFFECTIVE)) for item in entities(root)}
def tagged_box():
box = scad.make_box_rsolid(
20.0, 10.0, 5.0, tag_prefix="t.box", result_tag="part.box"
)
cut = scad.cut_rsolid(
box, scad.make_cylinder_rsolid(radius=2.0, height=20.0, bottom_face_center=(10.0, 5.0, -5.0))
)
cut._apply_tag("inherited.down", propagate=True)
return cut
class TestShapeRestore(unittest.TestCase):
def test_every_entity_keeps_its_effective_tags(self) -> None:
shape = tagged_box()
before = effective_tags(shape)
self.assertTrue(any("inherited.down" in tags for tags in before.values()))
restored = pickle.loads(pickle.dumps(shape))
self.assertEqual(effective_tags(restored), before)
def test_the_tag_cache_is_rebuilt_a_bounded_number_of_times(self) -> None:
shape = tagged_box()
payload = pickle.dumps(shape)
count = len(entities(shape))
calls = 0
original = TaggedMixin._refresh_tag_cache
def counted(self, *args, **kwargs):
nonlocal calls
calls += 1
return original(self, *args, **kwargs)
TaggedMixin._refresh_tag_cache = counted
try:
pickle.loads(payload)
finally:
TaggedMixin._refresh_tag_cache = original
self.assertLessEqual(calls, 3 * count, f"{calls} refreshes for {count} entities")
if __name__ == "__main__":
unittest.main()
def drilled_plate():
plate = scad.make_box_rsolid(60.0, 40.0, 6.0)
for index in range(24):
hole = scad.make_cylinder_rsolid(radius=1.5, height=20.0, bottom_face_center=(5.0 + index % 6 * 9, 5.0 + index // 6 * 9, -5.0))
plate = scad.cut_rsolid(plate, hole)
return plate
class TestShapePayload(unittest.TestCase):
def test_the_stored_geometry_is_compressed(self) -> None:
from simplecadapi._internal.shape_pickle import _write_shape
shape = drilled_plate()
raw = _write_shape(shape.wrapped)
self.assertGreater(len(raw), 10_000) # something to compress
payload = shape.__reduce__()[1][1]
self.assertLess(len(payload), len(raw) // 2)
def test_an_entry_stored_before_compression_is_still_read(self) -> None:
from simplecadapi._internal.shape_pickle import _write_shape, restore_shape
shape = drilled_plate()
before = effective_tags(shape)
name, payload, states = shape.__reduce__()[1]
raw = _write_shape(shape.wrapped)
self.assertEqual(name, type(shape).__name__)
legacy = restore_shape(name, raw, states)
self.assertEqual(effective_tags(legacy), before)
self.assertAlmostEqual(legacy.get_volume(), shape.get_volume(), places=6)
+52
View File
@@ -0,0 +1,52 @@
"""Benchmark: the desktop 6-DOF arm (sandbox-envs/desktop_arm_sources/arm6.py).
Copies the case to a temporary directory (the source stays clean), then runs
the top notebook headlessly through a series of edits and prints the tree of
nested notebook runs with wall seconds and ran/cached cell counts.
uv run python tools/profile_arm6.py [--keep DIR]
Baseline before cache work (2026-10-20, 8-core Apple silicon): cold 80.5s,
warm (no change) 23.6s, J1 edit 18.2s, UPPER_LENGTH edit 35.1s, BASE_D edit
22.8s, OPEN_STROKE edit 10.1s; cache directory 1.7 GB.
"""
from __future__ import annotations
import argparse
import shutil
import sys
import tempfile
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))
import profile_use_cascade as P # noqa: E402
CASE = Path(__file__).resolve().parent.parent / "sandbox-envs" / "desktop_arm_sources"
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--keep", type=Path, help="copy the case here and keep it")
args = parser.parse_args()
temporary = None if args.keep else tempfile.TemporaryDirectory()
root = (args.keep or Path(temporary.name)).resolve() / "arm" # type: ignore[union-attr]
shutil.copytree(CASE, root, ignore=shutil.ignore_patterns("__marimo__", "__pycache__", "out"))
top = root / "arm6.py"
P.install_probe()
P.scenario("cold", top)
P.scenario("warm (nothing changed)", top)
P.edit(top, 'J1=scad.var("j1", 0.0,unit="deg")', 'J1=scad.var("j1", 15.0,unit="deg")')
P.scenario("edit J1 0->15 (solve only)", top)
P.edit(top, 'upper_length", 90.0', 'upper_length", 95.0')
P.scenario("edit UPPER_LENGTH 90->95", top)
P.edit(root / "yaw_base.py", "default=90.0", "default=92.0")
P.scenario("edit yaw_base BASE_D", top)
P.edit(top, 'open_stroke", 3.0', 'open_stroke", 4.0')
P.scenario("edit OPEN_STROKE (gripper)", top)
if temporary is not None:
temporary.cleanup()
if __name__ == "__main__":
main()
+202
View File
@@ -0,0 +1,202 @@
"""Profile what one edit makes the notebook runtime rebuild, in a nested-assembly project.
The project: a top assembly ``use``s assemblies A, B, C; each of those ``use``s
three parts (A also a "giant" part, whose one big cell builds two independent
things). Every part has parameters ``p`` and ``q``. Ideally changing ``p``
of one part rebuilds that part's cells, the ``use`` of it, and what reads it
in the assembly above, and nothing else.
uv run python tools/profile_use_cascade.py [--holes N] [--keep DIR]
Each scenario edits the project, runs the top notebook headlessly, and prints
the tree of notebook runs: wall seconds (inclusive of children) and how many
of the notebook's cells ran / were restored. Every run uses the cache.
"""
from __future__ import annotations
import argparse
import re
import tempfile
import textwrap
import threading
import time
from pathlib import Path
HEADER = '# /// script\n# [tool.simplecadapi]\n# id = "{id}"\n# ///\nimport marimo\n\napp = marimo.App()\n\nwith app.setup:\n import simplecadapi as scad\n\n\n'
FOOTER = '\nif __name__ == "__main__":\n app.run()\n'
def heavy(var: str, size: str, holes: int) -> str:
return textwrap.dedent(
f"""\
_s = scad.make_box_rsolid({size}, 20.0, 20.0)
for _i in range({holes}):
_c = scad.make_cylinder_rsolid(1.5, 30.0)
_s = scad.cut_rsolid(_s, scad.translate_shape(_c, (_i % 6 * 3 + 1, _i // 6 * 3 + 1, -5.0)))
{var} = _s
"""
)
def cell(reads: str, body: str, returns: str) -> str:
code = textwrap.indent(textwrap.dedent(body).strip(), " ")
return f"@app.cell\ndef _({reads}):\n{code}\n return ({returns},)\n\n\n"
def part(name: str, holes: int) -> str:
return (
HEADER.format(id=name)
+ cell("", "# ---- params ----\np = 40.0\nq = 3.0", "p, q")
+ cell("p", heavy("body", "p", holes), "body")
+ cell("q, body", "rim = scad.cut_rsolid(body, scad.make_cylinder_rsolid(q, 50.0))", "rim")
+ cell("rim", f"part = scad.Part(part_id='{name}', body=rim)", "part")
+ FOOTER
)
def giant(name: str, holes: int) -> str:
"""One big cell that reads both p and q and builds two independent things."""
body = heavy("a", "p", holes) + "\n" + heavy("b", "q * 10.0", holes) + "\nbody = scad.union_rsolid(a, scad.translate_shape(b, (0.0, 20.0, 0.0)))\n"
return (
HEADER.format(id=name)
+ cell("", "# ---- params ----\np = 40.0\nq = 3.0", "p, q")
+ cell("p, q", body, "body")
+ cell("body", f"part = scad.Part(part_id='{name}', body=body)", "part")
+ FOOTER
)
def assembly(name: str, children: list[tuple[str, str]]) -> str:
"""*children*: (variable, relative path)."""
uses = "".join(cell("", f'{var} = scad.use("{path}")', var) for var, path in children)
lines = [
"_identity = scad.identity_placement_rplacement()",
f'_assembly = scad.make_assembly_rassembly(assembly_id="{name}", name="{name}")',
]
for var, _ in children:
lines.append(
f'_assembly = scad.add_component_rassembly(assembly=_assembly, item={var}, component_id="{var}", placement=_identity)'
)
lines.append(f"{name} = _assembly")
return (
HEADER.format(id=name)
+ uses
+ cell(", ".join(var for var, _ in children), "\n".join(lines), name)
+ FOOTER
)
def build_project(root: Path, holes: int) -> Path:
parts = root / "parts"
asm = root / "asm"
parts.mkdir(parents=True)
asm.mkdir()
layout = {"a": ["a1", "a2", "a3", "giant"], "b": ["b1", "b2", "b3"], "c": ["c1", "c2", "c3"]}
for names in layout.values():
for name in names:
text = giant(name, holes) if name == "giant" else part(name, holes)
(parts / f"{name}.py").write_text(text, encoding="utf-8")
for key, names in layout.items():
(asm / f"asm_{key}.py").write_text(
assembly(f"asm_{key}", [(name, f"../parts/{name}.py") for name in names]), encoding="utf-8"
)
top = root / "top.py"
top.write_text(assembly("top", [(f"asm_{k}", f"asm/asm_{k}.py") for k in layout]), encoding="utf-8")
return top
# ---------------------------------------------------------------------------
# Probe
# ---------------------------------------------------------------------------
_depth = 0
_lock = threading.Lock()
_rows: list[tuple[int, str, float, int, int]] = []
def install_probe() -> None:
from simplecadapi.runtime import runner
original = runner.run_notebook
def probed(path, *args, **kwargs): # type: ignore[no-untyped-def]
global _depth
with _lock:
depth = _depth
_depth += 1
slot = len(_rows)
_rows.append((depth, Path(path).name, 0.0, 0, 0))
start = time.perf_counter()
try:
run = original(path, *args, **kwargs)
finally:
with _lock:
_depth -= 1
ran = sum(1 for c in run.cells if c.status == "ran" and c.name != "setup")
cached = sum(1 for c in run.cells if c.status == "cached")
with _lock:
_rows[slot] = (depth, Path(path).name, time.perf_counter() - start, ran, cached)
return run
runner.run_notebook = probed
def scenario(title: str, top: Path) -> float:
from simplecadapi.runtime import runner
_rows.clear()
start = time.perf_counter()
runner.run_notebook(top)
total = time.perf_counter() - start
print(f"\n== {title}: {total:.2f}s")
for depth, name, seconds, ran, cached in _rows:
mark = "" if ran == 0 else f" <- {ran} cell(s) ran"
print(f" {' ' * depth}{name:<14} {seconds:6.2f}s ran {ran:>2} cached {cached:>2}{mark}")
return total
def edit(path: Path, old: str, new: str) -> None:
text = path.read_text(encoding="utf-8")
assert old in text, (path, old)
path.write_text(text.replace(old, new, 1), encoding="utf-8")
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--holes", type=int, default=30, help="cuts per heavy build (cost knob)")
parser.add_argument("--keep", type=Path, help="build the project here and keep it")
args = parser.parse_args()
temporary = None
if args.keep:
root = args.keep.resolve()
else:
temporary = tempfile.TemporaryDirectory()
root = Path(temporary.name).resolve() / "project"
top = build_project(root, args.holes)
print(f"project: {root}")
install_probe()
parts = root / "parts"
scenario("cold", top)
scenario("warm (nothing changed)", top)
edit(parts / "a1.py", "p = 40.0", "p = 41.0")
scenario("edit p of a1 (a leaf under asm_a)", top)
edit(parts / "a1.py", "p = 41.0", "p = 41.0 # a comment")
scenario("comment only in a1", top)
edit(parts / "giant.py", "q = 3.0", "q = 4.0")
scenario("edit q of giant (one big cell, two independent builds)", top)
edit(parts / "b2.py", "q = 3.0", "q = 3.5")
scenario("edit q of b2 (a leaf under asm_b)", top)
edit(parts / "a1.py", "p = 41.0 # a comment", "p = 40.0")
scenario("revert p of a1", top)
if temporary is not None:
temporary.cleanup()
if __name__ == "__main__":
main()