Make cpp-mode parameters writable after construction (fix #350)

[toruseoagent]

Summary

Fixes #350.

With the C++ backend, assigning node.flow_capacity (or most other Node/Link/Vehicle/World parameters) after construction was silently ignored: the assignment only rebound a Python attribute on the wrapper object and never reached the C++ engine. This PR makes the wrapper parameters live read/write properties that forward to the C++ engine, so post-construction assignment behaves consistently with the Python backend.

Design

Two small descriptors in uxsim_cpp_wrapper.py remove the need for per-attribute getter/setter boilerplate:

• CppProperty: one-line declaration of a write-through attribute forwarding to the underlying C++ object (e.g. u = CppProperty('vmax'))
• CppWorldProperty: same for CppWorld parameters that must also work before the C++ world is created (value lives in a Python backing attribute until then)

Parameters with Python-mode-specific semantics remain explicit properties, so the special cases are visible at a glance.

Now readable/writable after construction

Object	Parameters
Node	x, y, signal_offset, flow_capacity, flow_capacity_remain, number_of_lanes (in addition to existing signal, signal_phase, signal_t)
Link	u, kappa, tau, w, capacity, delta, delta_per_lane, merge_priority, number_of_lanes, signal_group, length (in addition to existing capacity_in/out(_remain))
Vehicle	orig, dest (accept Node object or name string)
World	DUO_UPDATE_TIME, DUO_UPDATE_WEIGHT, DUO_NOISE (read dynamically by the C++ engine, matching Python's runtime use)

Python-mode compatibility details:

• node.flow_capacity = v alone is sufficient: it also (re)initializes flow_capacity_remain and derives number_of_lanes when unset, mirroring Node.__init__ (as suggested in the issue)
• Unset node.flow_capacity / node.number_of_lanes now read as None as in Python mode (previously -1.0 / 0)
• free_flow_speed, jam_density, jam_density_per_lane, q_star, k_star remain inert bookkeeping attributes, exactly as in Python mode (use u/kappa or change_free_flow_speed()/change_jam_density() to affect the simulation)

No C++ side changes (all needed fields were already exposed via def_rw).

Tests

• 7 new tests in tests/test_cpp_mode.py: the issue cpp=True: assigning Node.flow_capacity after construction is silently ignored (inconsistent with Python backend) #350 reproduction (post-hoc == at-construction, and cross-mode consistency with the Python backend), read/write round-trips for Node/Link parameters, and effectiveness checks for post-hoc Link.u, Link.merge_priority, World.DUO_UPDATE_WEIGHT, and Vehicle.dest
• Full C++ mode suite: 224 passed

Validation

• Simulation results are bit-identical to the pre-change wrapper on a 10x10 grid scenario (~48k trips, 5 seeds): same TTT to the last digit in every run
• Cross-mode check (Python vs C++, 5 seeds): completed trips identical in all seeds; TTT ratio mean 1.027 with no statistically significant difference (seed-level variation from differing route-choice RNG streams, unchanged by this PR)

Benchmark

1 thread (OMP_NUM_THREADS=1), 10x10 grid, ~9.5k platoons, 1080 timesteps, includes scenario build + simulation + basic analysis:

• Interleaved A/B vs pre-change wrapper (12 alternating rounds, same seed): median 0.745 s (old) vs 0.726 s (new) — no measurable overhead (difference within VM noise). An initial hot-loop regression in init_after_tmax_fix (~780k property reads) was found by profiling and fixed in the second commit.
• C++ mode vs Python mode on the same scenario (5 seeds): median 0.83 s vs 12.4 s — ~15x speedup, unchanged by this PR.

🤖 Generated with Claude Code