[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-LucasAlegre--sumo-rl":3,"tool-LucasAlegre--sumo-rl":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",145895,2,"2026-04-08T11:32:59",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108111,"2026-04-08T11:23:26",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":87,"forks":88,"last_commit_at":89,"license":90,"difficulty_score":10,"env_os":91,"env_gpu":92,"env_ram":92,"env_deps":93,"category_tags":102,"github_topics":103,"view_count":32,"oss_zip_url":112,"oss_zip_packed_at":112,"status":17,"created_at":113,"updated_at":114,"faqs":115,"releases":144},5588,"LucasAlegre\u002Fsumo-rl","sumo-rl","Reinforcement Learning environments for Traffic Signal Control with SUMO. Compatible with Gymnasium, PettingZoo, and popular RL libraries.","sumo-rl 是一个专为交通信号控制设计的开源强化学习环境库。它基于著名的交通仿真软件 SUMO，旨在帮助开发者和研究人员轻松构建、训练和测试智能交通信号灯算法。在传统交通管理中，固定或简单的感应式信号灯难以应对复杂多变的实时车流，而 sumo-rl 通过引入强化学习技术，让信号灯能够根据实时路况自主优化配时方案，从而有效缓解拥堵、提升通行效率。\n\n这款工具特别适合人工智能研究者、交通工程专家以及强化学习开发者使用。其核心亮点在于极高的兼容性与灵活性：它不仅完美支持 Gymnasium 和 PettingZoo 接口，还能无缝对接 Stable-Baselines3、RLlib 等主流强化学习框架。用户既可以快速上手单智能体实验，也能轻松拓展至多智能体协作场景。此外，sumo-rl 允许用户自由定制状态观测空间（如车道密度、排队长度）和奖励函数，无需深入底层代码即可验证各种创新算法。无论是用于学术研究还是原型系统开发，sumo-rl 都提供了一个稳定且高效的实验平台。","\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_8837cd6fc360.png\" align=\"right\" width=\"30%\"\u002F>\n\n[![DOI](https:\u002F\u002Fzenodo.org\u002Fbadge\u002F161216111.svg)](https:\u002F\u002Fzenodo.org\u002Fdoi\u002F10.5281\u002Fzenodo.10869789)\n[![tests](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Factions\u002Fworkflows\u002Flinux-test.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Factions\u002Fworkflows\u002Flinux-test.yml)\n[![PyPI version](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Fsumo-rl.svg)](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Fsumo-rl)\n[![pre-commit](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https:\u002F\u002Fpre-commit.com\u002F)\n[![Code style: black](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcode%20style-black-000000.svg)](https:\u002F\u002Fgithub.com\u002Fpsf\u002Fblack)\n[![License](http:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-brightgreen.svg?style=flat)](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002FLICENSE)\n\n# SUMO-RL\n\n\u003C!-- start intro -->\n\nSUMO-RL provides a simple interface to instantiate Reinforcement Learning (RL) environments with [SUMO](https:\u002F\u002Fgithub.com\u002Feclipse\u002Fsumo) for Traffic Signal Control.\n\nGoals of this repository:\n- Provide a simple interface to work with Reinforcement Learning for Traffic Signal Control using SUMO\n- Support Multiagent RL\n- Compatibility with gymnasium.Env and popular RL libraries such as [stable-baselines3](https:\u002F\u002Fgithub.com\u002FDLR-RM\u002Fstable-baselines3) and [RLlib](https:\u002F\u002Fdocs.ray.io\u002Fen\u002Fmain\u002Frllib.html)\n- Easy customisation: state and reward definitions are easily modifiable\n\nThe main class is [SumoEnvironment](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py).\nIf instantiated with parameter 'single-agent=True', it behaves like a regular [Gymnasium Env](https:\u002F\u002Fgithub.com\u002FFarama-Foundation\u002FGymnasium).\nFor multiagent environments, use [env](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py) or [parallel_env](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py) to instantiate a [PettingZoo](https:\u002F\u002Fgithub.com\u002FPettingZoo-Team\u002FPettingZoo) environment with AEC or Parallel API, respectively.\n[TrafficSignal](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Ftraffic_signal.py) is responsible for retrieving information and actuating on traffic lights using [TraCI](https:\u002F\u002Fsumo.dlr.de\u002Fwiki\u002FTraCI) API.\n\nFor more details, check the [documentation online](https:\u002F\u002Flucasalegre.github.io\u002Fsumo-rl\u002F).\n\n\u003C!-- end intro -->\n\n## Install\n\n\u003C!-- start install -->\n\n### Install SUMO latest version:\n\n```bash\nsudo add-apt-repository ppa:sumo\u002Fstable\nsudo apt-get update\nsudo apt-get install sumo sumo-tools sumo-doc\n```\nDon't forget to set SUMO_HOME variable (default sumo installation path is \u002Fusr\u002Fshare\u002Fsumo)\n```bash\necho 'export SUMO_HOME=\"\u002Fusr\u002Fshare\u002Fsumo\"' >> ~\u002F.bashrc\nsource ~\u002F.bashrc\n```\nImportant: for a huge performance boost (~8x) with Libsumo, you can declare the variable:\n```bash\nexport LIBSUMO_AS_TRACI=1\n```\nNotice that you will not be able to run with sumo-gui or with multiple simulations in parallel if this is active ([more details](https:\u002F\u002Fsumo.dlr.de\u002Fdocs\u002FLibsumo.html)).\n\n### Install SUMO-RL\n\nStable release version is available through pip\n```bash\npip install sumo-rl\n```\n\nAlternatively, you can install using the latest (unreleased) version\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\ncd sumo-rl\npip install -e .\n```\n\n\u003C!-- end install -->\n\n## MDP - Observations, Actions and Rewards\n\n### Observation\n\n\u003C!-- start observation -->\n\nThe default observation for each traffic signal agent is a vector:\n```python\n    obs = [phase_one_hot, min_green, lane_1_density,...,lane_n_density, lane_1_queue,...,lane_n_queue]\n```\n- ```phase_one_hot``` is a one-hot encoded vector indicating the current active green phase\n- ```min_green``` is a binary variable indicating whether min_green seconds have already passed in the current phase\n- ```lane_i_density``` is the number of vehicles in incoming lane i dividided by the total capacity of the lane\n- ```lane_i_queue```is the number of queued (speed below 0.1 m\u002Fs) vehicles in incoming lane i divided by the total capacity of the lane\n\nYou can define your own observation by implementing a class that inherits from [ObservationFunction](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fobservations.py) and passing it to the environment constructor.\n\n\u003C!-- end observation -->\n\n### Action\n\n\u003C!-- start action -->\n\nThe action space is discrete.\nEvery 'delta_time' seconds, each traffic signal agent can choose the next green phase configuration.\n\nE.g.: In the [2-way single intersection](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fexperiments\u002Fdqn_2way-single-intersection.py) there are |A| = 4 discrete actions, corresponding to the following green phase configurations:\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_d932847f1250.png\" align=\"center\" width=\"75%\"\u002F>\n\u003C\u002Fp>\n\nImportant: every time a phase change occurs, the next phase is preeceded by a yellow phase lasting ```yellow_time``` seconds.\n\n\u003C!-- end action -->\n\n### Rewards\n\n\u003C!-- start reward -->\n\nThe default reward function is the change in cumulative vehicle delay:\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_290f640e04ed.png\" align=\"center\" width=\"25%\"\u002F>\n\u003C\u002Fp>\n\nThat is, the reward is how much the total delay (sum of the waiting times of all approaching vehicles) changed in relation to the previous time-step.\n\nYou can choose a different reward function (see the ones implemented in [TrafficSignal](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Ftraffic_signal.py)) with the parameter `reward_fn` in the [SumoEnvironment](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py) constructor.\n\nIt is also possible to implement your own reward function:\n\n```python\ndef my_reward_fn(traffic_signal):\n    return traffic_signal.get_average_speed()\n\nenv = SumoEnvironment(..., reward_fn=my_reward_fn)\n```\n\n\u003C!-- end reward -->\n\n## API's (Gymnasium and PettingZoo)\n\n### Gymnasium Single-Agent API\n\n\u003C!-- start gymnasium -->\n\nIf your network only has ONE traffic light, then you can instantiate a standard Gymnasium env (see [Gymnasium API](https:\u002F\u002Fgymnasium.farama.org\u002Fapi\u002Fenv\u002F)):\n```python\nimport gymnasium as gym\nimport sumo_rl\nenv = gym.make('sumo-rl-v0',\n                net_file='path_to_your_network.net.xml',\n                route_file='path_to_your_routefile.rou.xml',\n                out_csv_name='path_to_output.csv',\n                use_gui=True,\n                num_seconds=100000)\nobs, info = env.reset()\ndone = False\nwhile not done:\n    next_obs, reward, terminated, truncated, info = env.step(env.action_space.sample())\n    done = terminated or truncated\n```\n\n\u003C!-- end gymnasium -->\n\n### PettingZoo Multi-Agent API\n\n\u003C!-- start pettingzoo -->\n\nFor multi-agent environments, you can use the PettingZoo API (see [Petting Zoo API](https:\u002F\u002Fpettingzoo.farama.org\u002Fapi\u002Fparallel\u002F)):\n\n```python\nimport sumo_rl\nenv = sumo_rl.parallel_env(net_file='nets\u002FRESCO\u002Fgrid4x4\u002Fgrid4x4.net.xml',\n                  route_file='nets\u002FRESCO\u002Fgrid4x4\u002Fgrid4x4_1.rou.xml',\n                  use_gui=True,\n                  num_seconds=3600)\nobservations = env.reset()\nwhile env.agents:\n    actions = {agent: env.action_space(agent).sample() for agent in env.agents}  # this is where you would insert your policy\n    observations, rewards, terminations, truncations, infos = env.step(actions)\n```\n\n\u003C!-- end pettingzoo -->\n\n### RESCO Benchmarks\n\nIn the folder [nets\u002FRESCO](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Ftree\u002Fmain\u002Fsumo_rl\u002Fnets\u002FRESCO) you can find the network and route files from [RESCO](https:\u002F\u002Fgithub.com\u002Fjault\u002FRESCO) (Reinforcement Learning Benchmarks for Traffic Signal Control), which was built on top of SUMO-RL. See their [paper](https:\u002F\u002Fpeople.engr.tamu.edu\u002Fguni\u002FPapers\u002FNeurIPS-signals.pdf) for results.\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_953480430ed7.png\" align=\"center\" width=\"60%\"\u002F>\n\u003C\u002Fp>\n\n### Experiments\n\nCheck [experiments](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Ftree\u002Fmain\u002Fexperiments) for examples on how to instantiate an environment and train your RL agent.\n\n### [Q-learning](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fagents\u002Fql_agent.py) in a one-way single intersection:\n```bash\npython experiments\u002Fql_single-intersection.py\n```\n\n### [RLlib PPO](https:\u002F\u002Fdocs.ray.io\u002Fen\u002Flatest\u002F_modules\u002Fray\u002Frllib\u002Falgorithms\u002Fppo\u002Fppo.html) multiagent in a 4x4 grid:\n```bash\npython experiments\u002Fppo_4x4grid.py\n```\n\n### [stable-baselines3 DQN](https:\u002F\u002Fgithub.com\u002FDLR-RM\u002Fstable-baselines3\u002Fblob\u002Fmaster\u002Fstable_baselines3\u002Fdqn\u002Fdqn.py) in a 2-way single intersection:\nObs: you need to install stable-baselines3 with ```pip install \"stable_baselines3[extra]>=2.0.0a9\"``` for [Gymnasium compatibility](https:\u002F\u002Fstable-baselines3.readthedocs.io\u002Fen\u002Fmaster\u002Fguide\u002Finstall.html).\n```bash\npython experiments\u002Fdqn_2way-single-intersection.py\n```\n\n### Plotting results:\n```bash\npython outputs\u002Fplot.py -f outputs\u002F4x4grid\u002Fppo_conn0_ep2\n```\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_cf1db8698011.png\" align=\"center\" width=\"50%\"\u002F>\n\u003C\u002Fp>\n\n## Citing\n\n\u003C!-- start citation -->\n\nIf you use this repository in your research, please cite:\n```bibtex\n@misc{sumorl,\n    author = {Lucas N. Alegre},\n    title = {{SUMO-RL}},\n    year = {2019},\n    publisher = {GitHub},\n    journal = {GitHub repository},\n    howpublished = {\\url{https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl}},\n}\n```\n\n\u003C!-- end citation -->\n\n\u003C!-- start list of publications -->\n\nList of publications that use SUMO-RL (please open a pull request to add missing entries):\n- [Quantifying the impact of non-stationarity in reinforcement learning-based traffic signal control (Alegre et al., 2021)](https:\u002F\u002Fpeerj.com\u002Farticles\u002Fcs-575\u002F)\n- [Information-Theoretic State Space Model for Multi-View Reinforcement Learning (Hwang et al., 2023)](https:\u002F\u002Fopenreview.net\u002Fforum?id=jwy77xkyPt)\n- [A citywide TD-learning based intelligent traffic signal control for autonomous vehicles: Performance evaluation using SUMO (Reza et al., 2023)](https:\u002F\u002Fonlinelibrary.wiley.com\u002Fdoi\u002Ffull\u002F10.1111\u002Fexsy.13301)\n- [Handling uncertainty in self-adaptive systems: an ontology-based reinforcement learning model (Ghanadbashi et al., 2023)](https:\u002F\u002Flink.springer.com\u002Farticle\u002F10.1007\u002Fs40860-022-00198-x)\n- [Multiagent Reinforcement Learning for Traffic Signal Control: a k-Nearest Neighbors Based Approach (Almeida et al., 2022)](https:\u002F\u002Fceur-ws.org\u002FVol-3173\u002F3.pdf)\n- [From Local to Global: A Curriculum Learning Approach for Reinforcement Learning-based Traffic Signal Control (Zheng et al., 2022)](https:\u002F\u002Fieeexplore.ieee.org\u002Fabstract\u002Fdocument\u002F9832372)\n- [Poster: Reliable On-Ramp Merging via Multimodal Reinforcement Learning (Bagwe et al., 2022)](https:\u002F\u002Fieeexplore.ieee.org\u002Fabstract\u002Fdocument\u002F9996639)\n- [Using ontology to guide reinforcement learning agents in unseen situations (Ghanadbashi & Golpayegani, 2022)](https:\u002F\u002Flink.springer.com\u002Farticle\u002F10.1007\u002Fs10489-021-02449-5)\n- [Information upwards, recommendation downwards: reinforcement learning with hierarchy for traffic signal control (Antes et al., 2022)](https:\u002F\u002Fwww.sciencedirect.com\u002Fscience\u002Farticle\u002Fpii\u002FS1877050922004185)\n- [A Comparative Study of Algorithms for Intelligent Traffic Signal Control (Chaudhuri et al., 2022)](https:\u002F\u002Flink.springer.com\u002Fchapter\u002F10.1007\u002F978-981-16-7996-4_19)\n- [An Ontology-Based Intelligent Traffic Signal Control Model (Ghanadbashi & Golpayegani, 2021)](https:\u002F\u002Fieeexplore.ieee.org\u002Fabstract\u002Fdocument\u002F9564962)\n- [Reinforcement Learning Benchmarks for Traffic Signal Control (Ault & Sharon, 2021)](https:\u002F\u002Fopenreview.net\u002Fforum?id=LqRSh6V0vR)\n- [EcoLight: Reward Shaping in Deep Reinforcement Learning for Ergonomic Traffic Signal Control (Agand et al., 2021)](https:\u002F\u002Fs3.us-east-1.amazonaws.com\u002Fclimate-change-ai\u002Fpapers\u002Fneurips2021\u002F43\u002Fpaper.pdf)\n\n\u003C!-- end list of publications -->\n","\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_8837cd6fc360.png\" align=\"right\" width=\"30%\"\u002F>\n\n[![DOI](https:\u002F\u002Fzenodo.org\u002Fbadge\u002F161216111.svg)](https:\u002F\u002Fzenodo.org\u002Fdoi\u002F10.5281\u002Fzenodo.10869789)\n[![tests](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Factions\u002Fworkflows\u002Flinux-test.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Factions\u002Fworkflows\u002Flinux-test.yml)\n[![PyPI version](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Fsumo-rl.svg)](https:\u002F\u002Fbadge.fury.io\u002Fpy\u002Fsumo-rl)\n[![pre-commit](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https:\u002F\u002Fpre-commit.com\u002F)\n[![Code style: black](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcode%20style-black-000000.svg)](https:\u002F\u002Fgithub.com\u002Fpsf\u002Fblack)\n[![License](http:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-brightgreen.svg?style=flat)](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002FLICENSE)\n\n# SUMO-RL\n\n\u003C!-- start intro -->\n\nSUMO-RL 提供了一个简单的接口，用于使用 [SUMO](https:\u002F\u002Fgithub.com\u002Feclipse\u002Fsumo) 为交通信号控制实例化强化学习 (RL) 环境。\n\n本仓库的目标：\n- 提供一个简单易用的接口，利用 SUMO 进行交通信号控制的强化学习\n- 支持多智能体强化学习\n- 兼容 gymnasium.Env 和流行的 RL 库，如 [stable-baselines3](https:\u002F\u002Fgithub.com\u002FDLR-RM\u002Fstable-baselines3) 和 [RLlib](https:\u002F\u002Fdocs.ray.io\u002Fen\u002Fmain\u002Frllib.html)\n- 易于自定义：状态和奖励的定义可以轻松修改\n\n主类是 [SumoEnvironment](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py)。\n如果实例化时设置参数 'single-agent=True'，它将表现得像一个标准的 [Gymnasium Env](https:\u002F\u002Fgithub.com\u002FFarama-Foundation\u002FGymnasium)。\n对于多智能体环境，请使用 [env](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py) 或 [parallel_env](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py) 来分别以 AEC 或 Parallel API 实例化一个 [PettingZoo](https:\u002F\u002Fgithub.com\u002FPettingZoo-Team\u002FPettingZoo) 环境。\n[TrafficSignal](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Ftraffic_signal.py) 负责通过 [TraCI](https:\u002F\u002Fsumo.dlr.de\u002Fwiki\u002FTraCI) API 获取信息并控制交通信号灯。\n\n更多详情，请查看 [在线文档](https:\u002F\u002Flucasalegre.github.io\u002Fsumo-rl\u002F)。\n\n\u003C!-- end intro -->\n\n## 安装\n\n\u003C!-- start install -->\n\n### 安装 SUMO 最新版本：\n\n```bash\nsudo add-apt-repository ppa:sumo\u002Fstable\nsudo apt-get update\nsudo apt-get install sumo sumo-tools sumo-doc\n```\n别忘了设置 SUMO_HOME 变量（SUMO 的默认安装路径是 \u002Fusr\u002Fshare\u002Fsumo）：\n```bash\necho 'export SUMO_HOME=\"\u002Fusr\u002Fshare\u002Fsumo\"' >> ~\u002F.bashrc\nsource ~\u002F.bashrc\n```\n重要提示：为了获得巨大的性能提升（约 8 倍），可以启用 Libsumo，并声明变量：\n```bash\nexport LIBSUMO_AS_TRACI=1\n```\n请注意，如果此选项启用，则无法使用 sumo-gui 或同时运行多个模拟（[更多详情](https:\u002F\u002Fsumo.dlr.de\u002Fdocs\u002FLibsumo.html))。\n\n### 安装 SUMO-RL\n\n稳定版可通过 pip 安装：\n```bash\npip install sumo-rl\n```\n\n或者，您也可以安装最新的未发布版本：\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\ncd sumo-rl\npip install -e .\n```\n\n\u003C!-- end install -->\n\n## MDP - 观测、动作与奖励\n\n### 观测\n\n\u003C!-- start observation -->\n\n每个交通信号代理的默认观测是一个向量：\n```python\n    obs = [phase_one_hot, min_green, lane_1_density,...,lane_n_density, lane_1_queue,...,lane_n_queue]\n```\n- ```phase_one_hot``` 是一个独热编码向量，表示当前激活的绿灯相位\n- ```min_green``` 是一个二进制变量，指示当前相位是否已超过最小绿灯时间\n- ```lane_i_density``` 是进入车道 i 中的车辆数除以该车道的总容量\n- ```lane_i_queue``` 是进入车道 i 中排队（速度低于 0.1 m\u002Fs）的车辆数除以该车道的总容量\n\n您可以定义自己的观测，方法是实现一个继承自 [ObservationFunction](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fobservations.py) 的类，并将其传递给环境构造函数。\n\n\u003C!-- end observation -->\n\n### 动作\n\n\u003C!-- start action -->\n\n动作空间是离散的。\n每隔 `delta_time` 秒，每个交通信号代理可以选择下一个绿灯相位配置。\n\n例如，在 [双路单交叉口](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fexperiments\u002Fdqn_2way-single-intersection.py) 中，有 |A| = 4 个离散动作，对应以下绿灯相位配置：\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_d932847f1250.png\" align=\"center\" width=\"75%\"\u002F>\n\u003C\u002Fp>\n\n重要提示：每次相位切换时，下一个相位之前都会有一个持续 `yellow_time` 秒的黄灯阶段。\n\n\u003C!-- end action -->\n\n### 奖励\n\n\u003C!-- start reward -->\n\n默认的奖励函数是累计车辆延误的变化：\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_290f640e04ed.png\" align=\"center\" width=\"25%\"\u002F>\n\u003C\u002Fp>\n\n也就是说，奖励是总延误（所有驶入车辆等待时间之和）相对于上一时间步的变化量。\n\n您可以通过在 [SumoEnvironment](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Fenv.py) 构造函数中使用参数 `reward_fn` 来选择不同的奖励函数（参见 [TrafficSignal](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fsumo_rl\u002Fenvironment\u002Ftraffic_signal.py) 中实现的奖励函数）。\n\n也可以实现您自己的奖励函数：\n\n```python\ndef my_reward_fn(traffic_signal):\n    return traffic_signal.get_average_speed()\n\nenv = SumoEnvironment(..., reward_fn=my_reward_fn)\n```\n\n\u003C!-- end reward -->\n\n## API（Gymnasium 和 PettingZoo）\n\n### Gymnasium 单智能体 API\n\n\u003C!-- start gymnasium -->\n\n如果您的网络中只有一盏交通信号灯，那么您可以实例化一个标准的 Gymnasium 环境（参见 [Gymnasium API](https:\u002F\u002Fgymnasium.farama.org\u002Fapi\u002Fenv\u002F))：\n```python\nimport gymnasium as gym\nimport sumo_rl\nenv = gym.make('sumo-rl-v0',\n                net_file='path_to_your_network.net.xml',\n                route_file='path_to_your_routefile.rou.xml',\n                out_csv_name='path_to_output.csv',\n                use_gui=True,\n                num_seconds=100000)\nobs, info = env.reset()\ndone = False\nwhile not done:\n    next_obs, reward, terminated, truncated, info = env.step(env.action_space.sample())\n    done = terminated or truncated\n```\n\n\u003C!-- end gymnasium -->\n\n### PettingZoo 多智能体 API\n\n\u003C!-- start pettingzoo -->\n\n对于多智能体环境，您可以使用 PettingZoo API（参见 [Petting Zoo API](https:\u002F\u002Fpettingzoo.farama.org\u002Fapi\u002Fparallel\u002F)）：\n\n```python\nimport sumo_rl\nenv = sumo_rl.parallel_env(net_file='nets\u002FRESCO\u002Fgrid4x4\u002Fgrid4x4.net.xml',\n                  route_file='nets\u002FRESCO\u002Fgrid4x4\u002Fgrid4x4_1.rou.xml',\n                  use_gui=True,\n                  num_seconds=3600)\nobservations = env.reset()\nwhile env.agents:\n    actions = {agent: env.action_space(agent).sample() for agent in env.agents}  # 这里可以插入您的策略\n    observations, rewards, terminations, truncations, infos = env.step(actions)\n```\n\n\u003C!-- end pettingzoo -->\n\n### RESCO 基准测试\n\n在 [nets\u002FRESCO](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Ftree\u002Fmain\u002Fsumo_rl\u002Fnets\u002FRESCO) 文件夹中，您可以找到来自 [RESCO](https:\u002F\u002Fgithub.com\u002Fjault\u002FRESCO)（交通信号控制强化学习基准测试）的网络和路由文件。RESCO 是基于 SUMO-RL 构建的。有关结果，请参阅他们的 [论文](https:\u002F\u002Fpeople.engr.tamu.edu\u002Fguni\u002FPapers\u002FNeurIPS-signals.pdf)。\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_953480430ed7.png\" align=\"center\" width=\"60%\"\u002F>\n\u003C\u002Fp>\n\n### 实验\n\n请查看 [experiments](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Ftree\u002Fmain\u002Fexperiments)，了解如何实例化环境并训练您的强化学习智能体的示例。\n\n### 在单向单交叉路口使用 [Q-learning](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fblob\u002Fmain\u002Fagents\u002Fql_agent.py)：\n```bash\npython experiments\u002Fql_single-intersection.py\n```\n\n### 在 4×4 网格中使用 [RLlib PPO](https:\u002F\u002Fdocs.ray.io\u002Fen\u002Flatest\u002F_modules\u002Fray\u002Frllib\u002Falgorithms\u002Fppo\u002Fppo.html) 多智能体：\n```bash\npython experiments\u002Fppo_4x4grid.py\n```\n\n### 在双向单交叉路口使用 [stable-baselines3 DQN](https:\u002F\u002Fgithub.com\u002FDLR-RM\u002Fstable-baselines3\u002Fblob\u002Fmaster\u002Fstable_baselines3\u002Fdqn\u002Fdqn.py)：\n注意：您需要使用 ```pip install \"stable_baselines3[extra]>=2.0.0a9\"``` 安装 stable-baselines3，以实现与 [Gymnasium 的兼容性](https:\u002F\u002Fstable-baselines3.readthedocs.io\u002Fen\u002Fmaster\u002Fguide\u002Finstall.html)。\n```bash\npython experiments\u002Fdqn_2way-single-intersection.py\n```\n\n### 绘制结果：\n```bash\npython outputs\u002Fplot.py -f outputs\u002F4x4grid\u002Fppo_conn0_ep2\n```\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_readme_cf1db8698011.png\" align=\"center\" width=\"50%\"\u002F>\n\u003C\u002Fp>\n\n## 引用\n\n\u003C!-- start citation -->\n\n如果您在研究中使用了本仓库，请引用：\n```bibtex\n@misc{sumorl,\n    author = {Lucas N. Alegre},\n    title = {{SUMO-RL}},\n    year = {2019},\n    publisher = {GitHub},\n    journal = {GitHub repository},\n    howpublished = {\\url{https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl}},\n}\n```\n\n\u003C!-- end citation -->\n\n\u003C!-- start list of publications -->\n\n使用 SUMO-RL 的出版物列表（请提交拉取请求以添加缺失条目）：\n- [量化基于强化学习的交通信号控制中非平稳性的影响（Alegre 等，2021）](https:\u002F\u002Fpeerj.com\u002Farticles\u002Fcs-575\u002F)\n- [用于多视角强化学习的信息论状态空间模型（Hwang 等，2023）](https:\u002F\u002Fopenreview.net\u002Fforum?id=jwy77xkyPt)\n- [面向自动驾驶车辆的城市级基于 TD 学习的智能交通信号控制：使用 SUMO 进行性能评估（Reza 等，2023）](https:\u002F\u002Fonlinelibrary.wiley.com\u002Fdoi\u002Ffull\u002F10.1111\u002Fexsy.13301)\n- [处理自适应系统中的不确定性：基于本体的强化学习模型（Ghanadbashi 等，2023）](https:\u002F\u002Flink.springer.com\u002Farticle\u002F10.1007\u002Fs40860-022-00198-x)\n- [用于交通信号控制的多智能体强化学习：基于 k 最近邻的方法（Almeida 等，2022）](https:\u002F\u002Fceur-ws.org\u002FVol-3173\u002F3.pdf)\n- [从局部到全局：基于课程学习的强化学习交通信号控制方法（Zheng 等，2022）](https:\u002F\u002Fieeexplore.ieee.org\u002Fabstract\u002Fdocument\u002F9832372)\n- [海报：通过多模态强化学习实现可靠的匝道汇入（Bagwe 等，2022）](https:\u002F\u002Fieeexplore.ieee.org\u002Fabstract\u002Fdocument\u002F9996639)\n- [利用本体指导强化学习智能体应对未见情境（Ghanadbashi & Golpayegani，2022）](https:\u002F\u002Flink.springer.com\u002Farticle\u002F10.1007\u002Fs10489-021-02449-5)\n- [信息向上、建议向下：用于交通信号控制的分层强化学习（Antes 等，2022）](https:\u002F\u002Fwww.sciencedirect.com\u002Fscience\u002Farticle\u002Fpii\u002FS1877050922004185)\n- [智能交通信号控制算法比较研究（Chaudhuri 等，2022）](https:\u002F\u002Flink.springer.com\u002Fchapter\u002F10.1007\u002F978-981-16-7996-4_19)\n- [基于本体的智能交通信号控制模型（Ghanadbashi & Golpayegani，2021）](https:\u002F\u002Fieeexplore.ieee.org\u002Fabstract\u002Fdocument\u002F9564962)\n- [交通信号控制强化学习基准测试（Ault & Sharon，2021）](https:\u002F\u002Fopenreview.net\u002Fforum?id=LqRSh6V0vR)\n- [EcoLight：用于符合人体工学的交通信号控制的深度强化学习奖励塑造（Agand 等，2021）](https:\u002F\u002Fs3.us-east-1.amazonaws.com\u002Fclimate-change-ai\u002Fpapers\u002Fneurips2021\u002F43\u002Fpaper.pdf)\n\n\u003C!-- end list of publications -->","# SUMO-RL 快速上手指南\n\nSUMO-RL 是一个用于交通信号控制强化学习（RL）的简洁接口，基于 [SUMO](https:\u002F\u002Fgithub.com\u002Feclipse\u002Fsumo) 仿真器构建。它支持单智能体和多智能体 RL，并兼容 `gymnasium`、`stable-baselines3` 和 `RLlib` 等主流库。\n\n## 1. 环境准备\n\n### 系统要求\n- **操作系统**: Linux (推荐 Ubuntu\u002FDebian)\n- **Python**: 3.8+\n- **SUMO**: 交通仿真软件\n\n### 前置依赖\n在安装 Python 包之前，必须先安装 SUMO 及其工具集。\n\n**安装 SUMO (Ubuntu\u002FDebian):**\n```bash\nsudo add-apt-repository ppa:sumo\u002Fstable\nsudo apt-get update\nsudo apt-get install sumo sumo-tools sumo-doc\n```\n\n**配置环境变量:**\n设置 `SUMO_HOME` 变量（默认安装路径为 `\u002Fusr\u002Fshare\u002Fsumo`）：\n```bash\necho 'export SUMO_HOME=\"\u002Fusr\u002Fshare\u002Fsumo\"' >> ~\u002F.bashrc\nsource ~\u002F.bashrc\n```\n\n**可选性能优化:**\n若需大幅提升性能（约 8 倍），可启用 `Libsumo`。**注意**：启用后将无法使用图形界面 (`sumo-gui`) 或并行运行多个仿真。\n```bash\nexport LIBSUMO_AS_TRACI=1\n```\n\n## 2. 安装步骤\n\n### 方式一：通过 Pip 安装（稳定版）\n```bash\npip install sumo-rl\n```\n> **国内加速建议**：如遇下载缓慢，可使用清华源：\n> `pip install sumo-rl -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple`\n\n### 方式二：从源码安装（最新版）\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\ncd sumo-rl\npip install -e .\n```\n\n## 3. 基本使用\n\nSUMO-RL 提供两种主要 API：**Gymnasium**（适用于单路口\u002F单智能体）和 **PettingZoo**（适用于多路口\u002F多智能体）。\n\n### 场景 A：单智能体环境 (Gymnasium API)\n适用于只有一个交通信号灯的路网。\n\n```python\nimport gymnasium as gym\nimport sumo_rl\n\n# 创建环境\nenv = gym.make('sumo-rl-v0',\n                net_file='path_to_your_network.net.xml',      # 路网文件\n                route_file='path_to_your_routefile.rou.xml',  # 交通流文件\n                out_csv_name='path_to_output.csv',            # 输出结果路径\n                use_gui=True,                                 # 是否开启图形界面\n                num_seconds=100000)                           # 仿真时长\n\n# 重置环境\nobs, info = env.reset()\n\ndone = False\nwhile not done:\n    # 采样随机动作（实际使用时替换为你的策略）\n    action = env.action_space.sample()\n    \n    # 执行一步\n    next_obs, reward, terminated, truncated, info = env.step(action)\n    \n    done = terminated or truncated\n\nenv.close()\n```\n\n### 场景 B：多智能体环境 (PettingZoo API)\n适用于包含多个交通信号灯的复杂路网。\n\n```python\nimport sumo_rl\n\n# 创建并行多智能体环境\nenv = sumo_rl.parallel_env(net_file='nets\u002FRESCO\u002Fgrid4x4\u002Fgrid4x4.net.xml',\n                  route_file='nets\u002FRESCO\u002Fgrid4x4\u002Fgrid4x4_1.rou.xml',\n                  use_gui=True,\n                  num_seconds=3600)\n\n# 重置环境，获取初始观测\nobservations = env.reset()\n\n# 仿真循环\nwhile env.agents:\n    # 为每个智能体生成动作 (此处为随机策略)\n    actions = {agent: env.action_space(agent).sample() for agent in env.agents}\n    \n    # 执行一步\n    observations, rewards, terminations, truncations, infos = env.step(actions)\n\nenv.close()\n```\n\n### 关键概念说明\n- **观测 (Observation)**: 默认包含当前相位独热编码、最小绿灯时间标志、各车道密度及排队长度。\n- **动作 (Action)**: 离散空间，代表下一个绿灯相位配置。每次切换相位前会自动插入黄灯时间。\n- **奖励 (Reward)**: 默认为累积车辆延误的变化量（即总等待时间的减少量）。可通过 `reward_fn` 参数自定义。","某智慧交通研发团队正在为一线城市复杂十字路口开发自适应信号灯控制系统，旨在通过强化学习动态优化通行效率。\n\n### 没有 sumo-rl 时\n- **环境搭建繁琐**：开发人员需手动编写大量代码连接 SUMO 仿真器与 RL 算法，处理 TraCI 接口通信极易出错，耗时数周仅能跑通基础流程。\n- **多智能体协同困难**：面对区域路网多个路口联动需求，缺乏标准的并行环境接口，难以实现路口间的协同决策训练。\n- **状态定义僵化**：自定义车道密度、排队长度等观测指标需要修改底层逻辑，每次调整奖励函数或观测空间都涉及复杂的代码重构。\n- **算法兼容性差**：主流强化学习库（如 Stable-Baselines3 或 RLlib）无法直接调用仿真环境，团队需花费大量精力开发适配中间件。\n\n### 使用 sumo-rl 后\n- **一键实例化环境**：通过 `SumoEnvironment` 类即可快速加载 SUMO 路网，原生兼容 Gymnasium 和 PettingZoo 标准接口，将环境部署时间从数周缩短至几小时。\n- **原生支持多智能体**：利用 `parallel_env` 接口轻松构建多路口协同场景，直接对接多智能体强化学习算法，高效解决区域交通拥堵联动问题。\n- **灵活定制观测奖励**：只需简单配置即可自定义包含相位独热编码、最小绿灯时间及车道排队率的状态向量，快速验证不同控制策略的效果。\n- **无缝集成主流库**：无需额外适配层，直接将环境接入 Stable-Baselines3 或 RLlib 进行模型训练，让团队能专注于算法优化而非工程对接。\n\nsumo-rl 通过标准化的接口屏蔽了底层仿真复杂度，让交通信号控制算法的研发从“造轮子”转向真正的“核心创新”。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FLucasAlegre_sumo-rl_8837cd6f.png","LucasAlegre","Lucas Alegre","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FLucasAlegre_194e78b4.jpg","Institute of Informatics - UFRGS. Project Manager @Farama-Foundation.","Institute of Informatics - UFRGS","Porto Alegre","lucasnale@gmail.com","lnalegre","inf.ufrgs.br\u002F~lnalegre","https:\u002F\u002Fgithub.com\u002FLucasAlegre",[83],{"name":84,"color":85,"percentage":86},"Python","#3572A5",100,1019,255,"2026-04-07T17:03:38","MIT","Linux","未说明",{"notes":94,"python":92,"dependencies":95},"1. 必须安装 SUMO 交通仿真软件（推荐通过 PPA 在 Linux 上安装），并设置 SUMO_HOME 环境变量。\n2. 可选配置 LIBSUMO_AS_TRACI=1 以获得约 8 倍性能提升，但启用后将无法使用 sumo-gui 图形界面或并行运行多个仿真。\n3. 支持单智能体（Gymnasium API）和多智能体（PettingZoo API）模式。\n4. 若使用 stable-baselines3，需安装版本 >=2.0.0a9 以兼容 Gymnasium。",[96,97,98,99,100,101],"sumo","sumo-tools","gymnasium","pettingzoo","stable-baselines3 (可选)","rllib (可选)",[14],[96,104,105,106,107,108,99,109,110,111,98],"rl-algorithms","reinforcement-learning","gym","traffic-signal-control","gym-env","machine-learning","deep-reinforcement-learning","python",null,"2026-03-27T02:49:30.150509","2026-04-09T00:56:47.146357",[116,121,126,131,135,139],{"id":117,"question_zh":118,"answer_zh":119,"source_url":120},25353,"在多智能体环境中训练时，为什么奖励总是负数或等待时间持续增加？","这通常是因为交通流量过大导致网络拥堵，车辆无法完全疏散。默认奖励函数是等待时间的差值（W_t - W_t+1），如果拥堵加剧，奖励即为负数。解决方案包括：1. 减少随机生成车辆的频率（例如在使用 randomTrips.py 时将参数 -p 设置为 20 或更高，以减少单位时间内的车辆数）；2. 确保训练步数足够长（例如在多智能体环境下可能需要训练 1000 个 episode 以上才能看到收敛趋势）；3. 检查是否所有路口都能有效服务进入的车辆，避免队列无限堆积。","https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fissues\u002F173",{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},25354,"使用 multi_agent=True (single_agent=False) 时出现 'TypeError: can't convert np.ndarray of type numpy.object_' 错误怎么办？","该错误通常发生在环境返回的观测值（observation）格式不被 Stable Baselines3 支持时。在多智能体模式下，环境的 step() 方法返回的是字典（dictionary），其中每个键值对对应不同路口的状态和奖励，而不是单一的 numpy 数组。你需要确保模型能够处理这种字典结构的输入，或者编写自定义的环境包装器（wrapper）将多智能体的观测值转换为模型支持的张量格式。此外，需确认是否正确使用了 PettingZoo 提供的多智能体接口。","https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fissues\u002F88",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},25355,"渲染大规模交通场景时程序崩溃或内存溢出（Memory Leak）如何解决？","当渲染高分辨率（如 4000x4000）视频时，如果将所有帧保存在内存列表中再生成 GIF，会导致内存耗尽。解决方案是不要将所有帧保留在 RAM 中，而是将每一帧直接保存到磁盘，然后在另一个进程中读取这些图片生成 GIF。这样可以确保内存中同一时间只存储一帧数据，从而避免内存溢出崩溃。","https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fissues\u002F67",{"id":132,"question_zh":133,"answer_zh":134,"source_url":130},25356,"如何在 SUMO GUI 中放大视图以看清大型地图中的微小车辆？","在大型地图（如 Ingolstadt7 或 grid4x4）中，默认分辨率下车辆可能显得非常小。虽然调整渲染分辨率有帮助，但在 GUI 中可以通过缩放功能来改善视觉效果。维护者建议参考相关视频教程（如 YouTube 视频链接中 8:00 处所示），通过缩放操作使车辆在视图中显示得更大，以便于观察交通流细节。",{"id":136,"question_zh":137,"answer_zh":138,"source_url":125},25357,"CSV 文件中保存的奖励值为 0 或不符合预期是什么原因？","如果在 RESCO 地图等特定场景下发现 CSV 中的奖励始终为 0，可能是由于计算逻辑或数据聚合方式的问题。首先确认是否对所有路口的奖励进行了正确的累加或平均。默认奖励基于等待时间的变化量，如果交通状态稳定或车辆未离开路口，奖励可能接近 0。建议对比不同 episode 或运行结果的趋势，而不是仅看单次的绝对值。同时检查是否正确配置了 out_csv_name 参数以及环境是否在每一步都正确返回了奖励字典。",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},25358,"如何在自定义的 SUMO 网络文件中定义交通信号灯的相位逻辑？","在 .net 文件或额外的 .add.xml 文件中，可以使用 \u003CtlLogic> 标签定义静态信号灯逻辑。例如，设置 id 为路口 ID，programID 为程序名，type 为 static。在 \u003Cphase> 标签中定义 duration（持续时间）和 state（状态，如 'r'代表红，'g'代表绿，'y'代表黄）。Python 代码中的 TrafficSignal 类通常假设相位顺序为 [绿灯，黄灯，绿灯，黄灯...]。确保 XML 定义的相位顺序与代码逻辑一致，以便 Traci API 能正确检索和控制相位切换。","https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fissues\u002F157",[145,150,155,160,165,170,175,180,185,189],{"id":146,"version":147,"summary_zh":148,"released_at":149},162677,"v1.4.5","* 将 nets 文件夹添加到 PyPI 包\n* [为 pettingzoo 环境添加 fixed_time 选项](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcommit\u002F0e741e3422437605b2809b1ea36e8f73fddd26ad)\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.4.4...v1.4.5","2024-05-07T14:50:39",{"id":151,"version":152,"summary_zh":153,"released_at":154},162678,"v1.4.4","## 变更内容\n* 修复：如果不存在，则设置 traci 默认视图，由 @KevynKelso 在 https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fpull\u002F191 中完成\n* [将 info 字典的副本添加到指标中](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcommit\u002F596b7c63c6d98e2a38785146b75f40ed0f7f456e)\n* [将系统信息添加到 pettingzoo API 中](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcommit\u002F13102e216634b3e7dba8fe0b95b96a0863c98e7b)\n* [将 num_seconds 设置为模拟的持续时间，而不是完成时间](https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcommit\u002F896f1767cb09c1b7d358a33e03ec84b28d2f9481)\n\n## 新贡献者\n* @KevynKelso 在 https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fpull\u002F191 中做出了首次贡献\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.4.3...v1.4.4","2024-03-25T15:53:44",{"id":156,"version":157,"summary_zh":158,"released_at":159},162679,"v1.4.3","## 变更内容\n* @LucasAlegre 在 https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fpull\u002F143 中更新了使用 sb3 和 rllib 的实验\n* 将分支 `master` 重命名为 `main`\n* 在使用 pettingzoo API 时计算 info 字典\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.4.2...v1.4.3","2023-06-15T14:08:29",{"id":161,"version":162,"summary_zh":163,"released_at":164},162680,"v1.4.2","## 变更内容\n* @firemankoxd 在 https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fpull\u002F133 中添加了对自定义观测的支持（包括观测函数和观测空间）\n* 更新了 Pydoc 文档\n* 在代码中添加了 pre-commit、black 和 isort\n* 更新了文档\n* 将输出的 .csv 文件中的“run”字段重命名为“episode”\n\n## 错误修复\n* 修复了“pressure”奖励函数的符号问题\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.4.1...v1.4.2","2023-02-26T20:07:51",{"id":166,"version":167,"summary_zh":168,"released_at":169},162681,"v1.4.1","## 变更内容\n* 在 [lucasalegre.github.io\u002Fsumo-rl](https:\u002F\u002Flucasalegre.github.io\u002Fsumo-rl) 添加文档页面\n* 当 sim_step 达到或超过 sim_max_time 时，将 truncated 设置为 True（之前是 >）\n* 修复了因空车辆列表求均值而引发的 NumPy 警告\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.4.0...v1.4.1","2023-02-22T09:26:55",{"id":171,"version":172,"summary_zh":173,"released_at":174},162682,"v1.4.0","## 变更内容\n* 将 Gym 替换为 Gymnasium\n\n## 新贡献者\n* @firemankoxd 在 https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fpull\u002F119 中做出了首次贡献\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.3...v1.4.0","2022-12-13T11:41:27",{"id":176,"version":177,"summary_zh":178,"released_at":179},162683,"v1.3","**完整更新日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.2...v1.3","2022-08-24T10:19:23",{"id":181,"version":182,"summary_zh":183,"released_at":184},162684,"v1.2","## 变更内容\n* 兼容最新版本的 gym。\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FLucasAlegre\u002Fsumo-rl\u002Fcompare\u002Fv1.1...v1.2","2022-03-21T15:21:42",{"id":186,"version":187,"summary_zh":112,"released_at":188},162685,"v1.1","2021-10-17T19:01:34",{"id":190,"version":191,"summary_zh":112,"released_at":192},162686,"v1.0","2020-12-08T01:59:46"]