Feedback from Bolin-Z/ChargingGame

[toruseo]

I found that @Bolin-Z did extensive application of UXsim (and UXsimpp) for their work and obtained many insights on UXsim (and UXsimpp) itself. Thank you very much!

Summary (curated by AI (Claude Code))

• [Bug][High] A1 Ensure unique Vehicle naming in adddemand by adding a global counter or equivalent mechanism to prevent name collisions under same OD and timestep
  • this is on uxsimpp
• [Bug][Low] A2 Correct misleading comment in route_search_all (currently states Floyd-Warshall, actual implementation uses Dijkstra)
  • this is on uxsimpp
• [API][Medium] B1 Remove side effect in Analyzer.__init__ that automatically creates output directories; implement lazy directory creation upon result export
• [API][Low] B2 Clarify semantics of Link.actual_travel_time(t) in documentation, or consider renaming to estimated_travel_time to reflect that it returns an updated estimate, not a future prediction
• [API][Medium] B3-B4 Explicitly document time units (seconds vs timestep) for all time-related attributes, including log_t_link, arrival_time, departure_time, and departure_time_in_second
• [Documentation][High] C1 Add warning that large deltan values may systematically truncate low-flow OD demand; optionally emit warning when residual cumulative flow remains below deltan at simulation end
• [Documentation][Medium] C2 Clarify risks when using self-loop links (node -> node), including potential infinite reselection under DUO and ambiguity in link exit detection; recommend predefined routes or emit warnings on creation
• [Documentation][Medium] C3 Explicitly explain the overwrite-based update strategy of traveltime_actual and its importance for UE-DTA convergence
• [UE-DTA][High] D1-D6 Improve convergence mechanism and criteria, including gap-sensitive and time-decaying switching probability, completed ratio threshold, stability condition on recent GM variance, and immediate termination upon convergence detection
  • this is intentional
• [Performance][Reference] E1 Address simulation core bottleneck (approximately 77 percent runtime share); consider low-level implementation (C, C++, Rust) for performance-critical components

[toruseo]

Below is an AI-curated summary (sorry, in Japanese for my convenience) of possible improvements for UXsim. (folded as it is too long)

Click to see

UXsim へのフィードバック知見

本文書は、UXsimを利用した大規模プロジェクト（交通ネットワーク上のゲーム理論的分析）の開発過程で発見された、UXsim汎用交通流シミュレータとしての改善可能な点をまとめたものである。EV充電や強化学習に特有の内容は除外し、UXsimの一般ユーザに影響しうる知見に限定している。

---

A. バグ・不具合

A1. Vehicle命名の一意性が保証されない

深刻度: 高

adddemand の車両自動命名は f"{origin}-{destination}-{t}" 形式だが、同一ODペア・同一タイムステップで複数Vehicle（deltanにより累積流量がdeltanの倍数に達した場合等）が生成されると同名のVehicleが複数作成される。

# adddemandの命名ロジック
veh_name = f"{origin}-{destination}-{t}"
# → 同一OD・同一タイムステップで複数台生成 → 名前が衝突

影響:

• W.VEHICLES を辞書として走査（items()等）すると、同名Vehicleが上書きされ一部が暗黙的にスキップされる
• 実験では6601台中469件の重複名称があり、342台のVehicleが辞書変換時に消失した
• 車両数統計・完了率計算が不正確になる

再現条件: 低deltan＋高需要のODペアがある任意のネットワークで発生しうる。

修正案: 命名にグローバルカウンタを付与する（例: f"{origin}-{destination}-{t}-{counter}"）。

---

A2. route_search_all のコメント誤り

深刻度: 低

route_search_all メソッドのソースコードコメントに「Floyd-Warshall」と記述されているが、実際の実装は Dijkstra法である。

---

B. API設計の改善提案

B1. Analyzerの初期化時の副作用（ディレクトリ自動作成）

問題: Analyzer.__init__ が初期化時に os.makedirs(f"out{W.name}", exist_ok=True) を実行する。シミュレーションを可視化や結果保存なしで実行する場合でも、不要なディレクトリが作成される。

影響: ヘッドレスサーバ環境やバッチ実行で不要なI/Oが発生。シミュレーションを繰り返し実行するユースケース（例: パラメータスイープで数百回実行）で多数の空ディレクトリが残る。

提案: ディレクトリ作成を結果保存メソッドの呼び出し時に遅延させる（lazy initialization）。

---

B2. actual_travel_time の命名の紛らわしさ

問題: Link.actual_travel_time(t) は「実績旅行時間」を返す印象を与えるが、実際には過去の実測値で上書きされた推定配列からの値を返す。初期値は自由流旅行時間であり、車両が通過するたびに上書きされていく。

提案: ドキュメントに「これは過去に通過した車両の実績に基づく推定値であり、将来の正確な予測値ではない」旨を明記する。あるいはestimated_travel_time等の命名も検討。

---

B3. log_t_link の時間単位の明文化

問題: log_t_link は秒単位（timestep * delta_t）で格納されるが、UXsim内部ではタイムステップ数で管理される部分もある。ドキュメントにこの点が明記されていない。

実際に発生した問題: C++移植時に時間単位の不統一に気づかず、traveled_route() のタイムスタンプが不正確になり、UE-DTAの収束指標（GM/P90/P95）が全て0になるバグが発生。

提案: APIドキュメントに各属性の時間単位（秒 or タイムステップ数）を明記する。

---

B4. departure_time と departure_time_in_second の二重管理

問題: Vehicle.arrival_time はタイムステップ表記、departure_time もタイムステップ表記だが、departure_time_in_second という別名プロパティが存在する。単位が混在しており、ユーザに混乱を与える。

提案: 全ての時間関連プロパティの単位をドキュメントで統一的に明示する。

---

C. 設計上の注意点（ドキュメント改善の候補）

C1. deltan による低流量OD需要の暗黙的切り捨て

問題: adddemand の車両生成ロジックは、累積流量が deltan に達した時点で初めてVehicleオブジェクトを生成する。低流量のODペアでは、シミュレーション全期間を通じて累積流量が deltan に達せず、1台もVehicleが生成されないことがある。

例: flow=0.001 veh/s, DELTAT=5s, deltan=5
毎ステップ累積 = 0.001 × 5 = 0.005台
4800秒間の総累積 = 0.005 × 960 = 4.8台 < deltan(5)
→ Vehicle 0台（需要が完全に無視される）

実験データ: 1056個のODペアのうち848個（80%）でこの問題が発生し、理論上の車両の52.5%が失われた。

提案: ドキュメントに「deltanを大きくすると低流量ODの需要が系統的に切り捨てられる」旨の注意を記載。あるいは、シミュレーション終了時に残余累積流量がdeltan未満のODペアについて警告を出す機能の追加。

---

C2. 自己ループリンク（node → node）使用時の注意

問題: UXsimでは同一ノード間の自己ループリンクを作成可能だが、標準の経路選択ロジック（DUO）との組み合わせで想定外の動作をする。

• 車両がリンク端部に到達すると route_next_link_choice() が呼ばれるが、自己ループの端ノードは出発ノードと同一のため、自己ループを再選択して無限ループに陥るリスクがある
• 標準の specified_route メカニズムでは、自己ループリンクにおける車両の「リンク離脱」判定が曖昧

提案: 自己ループリンクを使用する場合は、予定経路（predefined_route）による明示的制御が必要である旨をドキュメントに記載。または、自己ループリンクの作成時に警告を出す。

---

C3. traveltime_actual の「上書き式更新」戦略の重要性

発見: UXsimの traveltime_actual は、車両がリンクを離脱した時点で、その車両の進入時刻から配列末尾まで全て上書きするという戦略を採用している。

# Node.transfer() (uxsim.py:287)
inlink.traveltime_actual[int(veh.link_arrival_time/s.W.DELTAT):] = actual_travel_time

この設計は一見奇妙だが、UE-DTA収束に決定的に重要である。C++移植時に「現在タイムステップのみ更新」に変更した結果、UE-DTAのGap Metricが約5%で停滞し、1%の収束閾値に到達できなかった。上書き式に修正後、GM=0.85%に収束。

提案: この更新戦略の設計意図をソースコードのコメントまたはドキュメントに明記する。UXsimを拡張・移植する開発者にとって、この仕組みの理解は不可欠である。

---

D. UE-DTA（動的交通配分）に関する知見

D1. 固定確率ルート切り替えの振動問題

UXsimの公式サンプル uedta.py を参照した実装において、固定確率（例: 5%）でのルート切り替え機構は、反復後期でも一定確率で切り替えが継続するため、均衡点付近で解が振動し続ける。

実験データ:

ネットワーク	100轮GM	200轮GM	300轮GM	傾向
Berlin (191ノード)	4.96%	4.17%	4.68%	振動
Anaheim (416ノード)	3.12%	2.85%	3.09%	振動

200轮時点の方が300轮時点より良いという逆転現象が起こり、「反復を増やせば収束する」前提は成立しない。

有効な改善策: Gap感応＋時間減衰の切り替え確率を導入。

$$P_{switch}(n) = \min(1, \gamma \cdot gap_{rel}) \cdot \frac{1}{1 + \alpha \cdot n}$$

導入後、Sioux Falls 22轮、Berlin 25轮で安定的に収束。

---

D2. ネットワーク規模と最適パラメータの関係

パラメータスイープ実験から得られた最適値:

ネットワーク規模	γ（Gap感応度）	α（減衰率）	収束轮数
小規模（24ノード）	5	0.08	22轮
中規模（191ノード）	10	0.05	25轮
大規模（416ノード）	15	0.08	82轮

• 小規模ネットワークでは低γが必要（過度な切り替えによる振動防止）
• αは0.05〜0.08が汎用的に有効

---

D3. 収束判定における completed_ratio の重要性

GMのみの収束判定では「虚偽収束」を見逃す。大量の車両がシミュレーション時間内に行程を完了できず、完了車両のみでGapを計算すると見かけ上の収束が起こる。

完了率: 60% ← 40%の車両が未完了で統計から除外
GM: 0.6%   ← 完了した60%の車両だけで計算すると低い
→ GMだけ見ると「収束」だが、実態は「虚偽収束」

提案: 収束判定に completed_ratio ≥ 95% の条件を加えることを推奨。uedta.py サンプルにこの注意点を追記する価値がある。

---

D4. simulation_time の適正設定ガイドライン

車両完了率に直結するsimulation_timeの適正値:

$$\text{必要なsimulation_time} \geq \text{需要終了時刻} + \text{最長自由流旅行時間} \times \text{遅延倍率}$$

高需要条件では、シミュレーション時間を需要発生時間の3倍以上に設定する必要がある。

設定	完了率
7200s（2時間）	avg 37%
9000s（2.5時間）	avg 44%
10800s（3時間）	avg 78%、収束後100%

---

D5. 収束判定の安定性条件

GM閾値のみでは不十分。以下の安定性条件の追加を推奨:

$$\text{converged} = (GM < \theta) \land (\sigma_{GM,\text{last }k} < \epsilon)$$

GMが閾値以下であり、かつ直近k轮のGMの標準偏差が十分に小さい（振動していない）ことを要求する。

さらに、収束点を超えて反復を継続するとGMが逆に上昇することが確認されており（Berlin: 2.75% → 3.75%）、収束検知後は直ちに反復を停止すべき。

---

D6. OD級別MSA（逐次平均法）の不適用性

UXsimのDTAでは操作対象が離散的な個別Vehicleであり、各Vehicleが出発時刻に応じて異なる道路状況に直面する。従来のOD対レベルのMSA（連続的な流量比率の操作）は、DTA的の時変特性を破壊するため不適切。個別Vehicle単位の意思決定を維持しつつ、切り替え確率の設計を改善するのが正しいアプローチ。

---

E. パフォーマンスに関する知見

E1. シミュレーション実行が全体の約77%を占める

Sioux Falls ネットワーク（24ノード、80リンク、6601 Vehicle、tmax=9600s）のプロファイリング結果:

工程	時間	全体に占める割合
シミュレーション実行	22,317 ms	77.3%
経路計算（NetworkX）	6,035 ms	20.9%
交通需要読込	494 ms	1.7%

C++移植により、シミュレーション実行部分は59〜98倍に高速化された。将来的にUXsimのコア部分をC/C++/Rust等で実装するボトルネック解消の余地がある。

---

まとめ

分類	項目	優先度
バグ	A1: Vehicle命名の一意性	高
バグ	A2: コメント誤り（Floyd-Warshall→Dijkstra）	低
API改善	B1: Analyzerの副作用	中
API改善	B2: actual_travel_timeの命名	低
API改善	B3-B4: 時間単位の明文化	中
ドキュメント	C1: deltanの需要切り捨て注意	高
ドキュメント	C2: 自己ループリンクの注意	中
ドキュメント	C3: traveltime上書き戦略の明文化	中
UE-DTA改善	D1-D6: 収束手法・判定基準	高
性能	E1: コア仿真のボトルネック	参考

[Bolin-Z]

Hi @toruseo, thank you for taking the time to look into my repository and for compiling such a thorough and well-organized issue. I truly appreciate it. UXsim has been an essential component of my research, and I'd like to share some context about how I've been using it, along with my thoughts on several points you raised.

About My Work

My research focuses on pricing games among competing EV charging station operators, formulated as a bilevel game-theoretic framework:

• Upper level: Multiple charging station operators simultaneously determine price schedules across predefined time periods (time-of-use pricing), forming a Nash game. This is solved using Multi-Agent Deep Reinforcement Learning (MADRL).
• Lower level: Users (a mixed flow of charging and non-charging vehicles) respond by choosing routes that minimize their generalized cost (monetized travel time + charging cost), modeled as an ε-Restricted Dynamic User Equilibrium (ε-Restricted DUE) solved via day-to-day simulation iterations.

UXsim serves as the mesoscopic traffic simulation engine at the lower level. Since charging demand flow cannot be expressed analytically — it emerges from complex vehicle-following and queuing dynamics — UXsim is the core component that evaluates how users respond to pricing strategies.

Customization Details

The UXsim integration in my project is a customized version based on UXsim v1.8.2 and UXsimpp, adapted to my specific research needs. I want to be transparent about a few things:

• Initial implementation: I started with the Python version of UXsim v1.8.2, adding a monkey-patch layer (patch.py) to support predefined route following and self-loop charging links.
• C++ migration: To improve simulation speed, I later referenced UXsimpp to build a C++ simulation core, with modifications to align its behavior with UXsim v1.8.2 and to support my project-specific features (predefined routes, transfer confirmation mechanism, batch route assignment, etc.).
• UE-DTA solver: The DUE solving procedure references UXsim's restricted DUE approach based on a fixed route set, with an adjusted route switching probability formula (detailed below in D1-D6).
• AI-assisted development: The code modifications were implemented with the assistance of Claude Code (an AI coding assistant). While the results have been validated through experiments, the generated code quality should be treated with appropriate caution.
• A note on the doc/ directory: The markdown files in doc/ are working documents created during the AI-assisted development process and have not been finalized. Data referenced in those documents may be outdated, though the design ideas described therein are generally consistent with the current implementation.

Paper Submission

I have organized the above work into a conference paper, which has been submitted and is currently under review. The paper cites UXsim.

Comments on Specific Points

A1: Vehicle Naming Uniqueness

I encountered this issue in my project. When multiple vehicles are generated for the same OD pair at the same timestep (due to cumulative flow reaching multiples of deltan), name collisions occur. I resolved this in my customized version by introducing a global counter to ensure unique naming. I agree with the proposed fix.

A2, B1–B4

I agree with these observations. Regarding B1 (Analyzer side effect), I made the same modification in my patch — commenting out the os.makedirs call in Analyzer.__init__ to avoid unnecessary directory creation during headless batch runs.

C2: Self-Loop Links

In my project, I use self-loop links (node → node) to model charging time — the charging duration is controlled via the link's length and free-flow speed parameters. However, this only works reliably when combined with predefined routes, which prevents the infinite reselection problem under DUO that the issue describes.

Additionally, supporting self-loop links with predefined routes required modifications to the core vehicle transfer logic. I implemented a transfer confirmation mechanism: the vehicle only increments its route index after confirming it has actually entered the target link (by checking route_next_link == current_link). Without this, the vehicle could prematurely advance its route index at a self-loop's end node, since the start and end nodes are identical.

C3: traveltime_actual Overwrite Strategy

When building the C++ simulation core based on UXsimpp, I noticed that UXsimpp's traveltime_real update behavior differed from UXsim v1.8.2. UXsimpp did not fully replicate the overwrite-from-entry-to-end strategy. After aligning the C++ implementation with UXsim v1.8.2's approach — overwriting traveltime_real from the vehicle's link entry timestep to the end of the array — the UE-DTA convergence behavior became consistent with expectations. This experience confirms that this design choice is critical for convergence and deserves explicit documentation.

D1–D6: UE-DTA Convergence

These findings resonate strongly with my development experience. A few observations from my work:

Route switching probability: I also found that fixed-probability switching causes oscillation in later iterations. The gap-sensitive and time-decaying formula I adopted is:

$$P_{switch}(n) = \frac{\min(1,\ \gamma \cdot gap_{rel})}{1 + \alpha \cdot n}$$

where $\gamma$ is the gap sensitivity coefficient, $\alpha$ is the time decay rate, and $n$ is the current iteration number. The parameters $\gamma$ and $\alpha$ need to be tuned per network, which aligns with the findings in D2.

Relative cost gap: Since my model involves mixed traffic (charging and non-charging vehicles) with generalized costs of different magnitudes, I use relative cost gap rather than absolute gap:

$$gap_{rel} = \frac{cost_{current} - cost_{best}}{cost_{current}}$$

This normalization avoids bias from vehicles with inherently different cost scales.

Convergence metrics: I use Global Mean (GM) of relative gaps as the primary convergence indicator, with P90 and P95 as auxiliary metrics to monitor the distribution of extreme values. In practice, I found that GM, P90, and P95 tend to follow similar trends.

Convergence criteria: My implementation requires three conditions to be satisfied simultaneously:

1. GM ≤ threshold (user-configurable)
2. Completion ratio ≥ 95% (user-configurable, addressing the false convergence issue described in D3)
3. Both conditions hold for N consecutive rounds (stability check)

Additionally, a maximum iteration limit is necessary as a safeguard, since there are cases where convergence may not be achieved within a reasonable number of iterations.

I fully agree with D3 regarding the importance of completed_ratio. Relying solely on GM can produce misleading results when a significant portion of vehicles fail to complete their trips.

E1: Performance

My experience confirms that the simulation core is the dominant bottleneck. After migrating the core simulation to C++, the speedup was substantial.

However, after resolving the core simulation bottleneck, frequent Python–C++ boundary crossings became the new performance bottleneck. Each access to C++ objects from Python (e.g., reading traveltime_real vectors via pybind11) involves data copying overhead. To address this, I implemented several caching mechanisms:

• Travel time cache: Pre-cache the entire traveltime_real array after each simulation run, avoiding repeated pybind11 vector copies during route cost evaluation.
• Batch route assignment: Queue route assignments and flush them in a single C++ call, reducing boundary crossings significantly.
• Object reference caching: Maintain Python-side caches for Vehicle and Link objects to preserve dynamic attributes across pybind11 boundary crossings.

Beyond the single-simulation performance, I see two deeper challenges for scaling up:

1. Serialization: UXsim's simulation environment objects (network structure, demand data, vehicle states) may not support efficient serialization/deserialization, making it difficult to rapidly clone pre-configured environments for parallel training scenarios.
2. GPU simulation: For large-scale parallel training (e.g., thousands of concurrent simulations for MADRL), GPU-based traffic simulation could be a game-changing solution. However, traffic microsimulation involves complex conditional logic (vehicle following, lane changing, node transfer), and I am not sure about the feasibility of mapping these operations to GPU architectures. I would be curious to hear your thoughts on this.

In my current setup, I work around the parallelization challenge using a simple master-worker asynchronous architecture, where the master dispatches simulation tasks (with price vectors as parameters) to worker processes that execute the simulations independently.

---

Thank you again for your attention to my work and for maintaining UXsim. I hope these observations from a downstream user's perspective are helpful.

---

Note: This reply was collaboratively drafted with Claude Code. I provided the overall structure and specific technical experiences, while Claude Code helped refine the content by exploring the project repository and asking clarifying questions.

[toruseo]

@Bolin-Z Thanks for the detailed folloup! It is really interesting to see people using my code in creative ways. I will keep update this issue thread as I improve the code, though it may take some time.

Note: This reply was collaboratively drafted with Claude Code. I provided the overall structure and specific technical experiences, while Claude Code helped refine the content by exploring the project repository and asking clarifying questions.

Actually I have prepared the original post by using Claude Code in a similar manner :) I cannot guarantee 100% accuracy too, but it is quite useful.

---

I think the "UE-DTA Convergence" issue need some additional explanation from my side. In fact, this behavior, in which the day-to-day process does not converge to some deterministic state, is intentional. This is because the UE considered in this problem is a kind of stochastic UE. Simply speaking, an assignment result of a day after a sufficiently large iterations can be considered as a sample from stochastic UE distribution.

FYI, there is a quite complicated theoretical basis about this (very difficult to read without prior knowledge!). Using technical terminology, this can be stated as follows: the stochastic UE corresponds to the stationary distribution of a Markov chain.

I agree that your approach to derive a deterministic state by modifying the update process could be a practically reasonable way to determine a kind of "representative state" from the stochastic UE.