Skip to content

docs: explain graph memoization and independent node state - #790

Draft
pengpengyi92 wants to merge 1 commit into
Point72:mainfrom
pengpengyi92:codex/document-graph-memoization
Draft

pengpengyi92 wants to merge 1 commit into
Point72:mainfrom
pengpengyi92:codex/document-graph-memoization

Conversation

@pengpengyi92

Copy link
Copy Markdown

Summary

Fixes #391.

Add a Graph Memoization section and TOC entry to the graph concepts page:

  • distinguish wiring-time sharing from caching values on each tick;
  • explain node/graph memoize=False, scoped csp.memoize(False), and the
    important non-recursive graph opt-out behavior;
  • describe state sharing, normal cache/run lifetime, force_memoize and factory
    object considerations;
  • include a self-contained example that checks shared versus independent wiring
    and actually runs both counters.

Scope: one documentation file, 57 additions. No runtime, API, dependency or
native-code change. This is independent of the configured-realtime docs in #788.

Validation

  • Exact new Markdown example extracted and executed in a fresh Python process.
  • Local memoization contract probes: 13 passed. These include wiring identity,
    runtime node start counts, per-node/scoped opt-out, non-recursive graph opt-out,
    force_memoize, fresh state across runs/reused graph structure, helper-object
    sharing and unhashable-argument fallback. The extra probes are local verification,
    not new upstream test files.
  • Existing tests before and after the doc change:
    python -m pytest csp/tests/test_graph_mem_cache.py csp/tests/impl/wiring csp/tests/test_engine.py::TestEngine::test_realtime_flag -q -rs
    -> 28 passed, 2 skipped (Numba unavailable).
  • python -m mdformat --check docs/wiki/concepts/CSP-Graph.md -> passed.
  • python -m codespell_lib docs/wiki/concepts/CSP-Graph.md -> passed.
  • git diff --check -> passed.

Windows / Python 3.12.14; checked-out Python sources with official CSP 0.19.1
Windows wheel native libraries. No C++ rebuild, Linux/macOS matrix, full
service-dependent suite or performance benchmark was run. Local evidence does
not imply upstream CI success or maintainer acceptance.

Draft for maintainer scope/wording review; no engine behavior change proposed.

Signed-off-by: Pengyi Peng <74917296+pengpengyi92@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[wiki] Add section on memoization

1 participant