Non-live attributes in Python (and cpp-mode wrapper)

[toruseo]

Background

Follow-up to #350 / #352. Since #352, cpp-mode wrapper parameters are live read/write properties backed by the C++ engine ("C++ is the single source of truth"). Some attributes intentionally remain Python-side, and are documented here so the design decision (and its caveats) is visible.

Inert bookkeeping attributes on Link

free_flow_speed, jam_density, jam_density_per_lane, q_star, and k_star are plain Python attributes on the cpp-mode wrapper: snapshots taken at construction and refreshed only by change_free_flow_speed() / change_jam_density().

This exactly mirrors the Python backend, where the simulation reads u, kappa, tau, w, capacity, delta, delta_per_lane and treats the above attributes as records. Consequently, in both backends:

• link.free_flow_speed = 30 after construction is silently inert (the simulation keeps using u), while link.u = 30 takes effect — an assignment-is-silently-ignored trap of the same flavor as cpp=True: assigning Node.flow_capacity after construction is silently ignored (inconsistent with Python backend) #350, though backend-consistent
• after link.u = 30, reading link.free_flow_speed returns the stale old value; likewise q_star/k_star are stale after change_free_flow_speed() (they are only set in __init__)

Possible resolutions (any of these; applies to both backends to keep 1:1 semantics):

• make free_flow_speed/jam_density read-only aliases (properties) of u/kappa, and q_star/k_star computed properties, or
• make assigning them delegate to change_free_flow_speed()/change_jam_density(), or
• keep the current semantics and document that u/kappa and the change_*() methods are the authoritative interface

Suggested action

Primarily a documentation/design-decision issue rather than a bug: all of the above is backend-consistent today. Opening this to decide whether to (a) document the authoritative interfaces, or (b) tighten the semantics in both backends as sketched above.