002_MatSIM开始使用

image.png

本章介绍如何设置和运行MATSim，并描述构建基本场景的要求。更新信息可从http://matsim.org，尤其是http://matsim.org/docs。
将源代码导入不同的计算环境并通过API（应用程序编程接口）扩展MATSim在第二部分第45章中进行了描述。

2.1 设置和运行MATSim

2.1.1 设置MATSim

要运行MATSim，必须安装符合相应MATSim版本的java SE（Java标准版）。此时，这是JavaSE11。

GitHub上的MATSim示例项目您可以在GitHub上派生或克隆一个所谓的示例项目，请参见https://github.com/matsim-org/matsim-example-project。

这个版本的目标是那些精通IDE（集成开发环境）（例如Eclipse、IntelliJ）和Java的程序员，以及那些希望使用MATSim编程的程序员。该方法将自动下载MATSim（作为所谓的Maven articfact），允许您浏览源代码，并让您随时了解最新版本或快照。它不允许您修改现有的MATSim代码，在大多数情况下，这也是不必要的：在这种情况下，您最好与开发人员联系，我们将尝试帮助或实现缺少的扩展点。

GitHub上所谓的代码示例项目中提供了一些Java程序，如第3.1.1.3节所述，请参见https://github.com/matsim-org/matsim-code-examples。

Standalone

“单机版”面向那些对IDE（例如Eclipse）和Java不熟练的用户，希望通过编辑输入文件来使用MATSim，包括 config.xml. 提供了一个基本的GUI（图形用户界面）。

您将需要正式的MATSim发行版，一个zip文件（通常用版本号MATSim指定）-yy.yy.yy年.zip），包括运行它所需的所有内容。它可以下载以下相应的链接下http://matsim.org/downloads。在MATSim目录树中解压缩结果。

Maven

可以将MATSim用作Maven插件；发布版本和快照都可用。可在下列网站，查询更多信息：http://matsim.org/downloads。

同样，GitHub上所谓的代码示例项目中提供了一些Java程序，如第3.1.1.3节所述，请参见https://github.com/matsim-org/matsim-code-examples。

浏览源代码

如果您只想查看代码而不下载和安装zip文件：在GitHub上，MATSim目录树的根位于https://github.com/matsim-org/matsim-libs。 或者，如果您已经用Maven安装了MATSim示例项目，那么MATSim源代码将自动在IDE中可用。

其他选择
http://matsim.org/downloads 描述其他选项，包括如何获取较旧或较新版本或如何添加扩展。

2.1.2 启动MATSim

从版本0.8.x开始，可以通过双击MATSim JAR（Java存档）文件来启动MATSim。在IDE（例如Eclipse）中，可以通过运行Gui类（org.matsim.run.gui）。打开GUI并运行MATSim，

1. 配置——通过选择“choose”按钮指示的配置文件进行配置
2. 开始——点击“Start MATSim”

如果输出目录（如配置文件中定义的，见下文）已经存在，则需要将其删除，然后才能成功启动运行；可通过点击“Delete”按钮进行删除。

运行成功完成后，可以点击“open”按钮在文件浏览器中打开输出目录。输出文件，例如output_network.xml.gz 和 output_events.xml.gz，可通过将文件拖放进 VIA 可视化软件，并回放模拟交通。

2.1.3 配置MATSim

MATSim在配置文件中配置。它在用户和MATSim之间建立连接，并包含影响模拟行为的设置列表。

所有配置参数都是参数名和参数值的简单对应。参数被分为多个逻辑组；一个组具有与控制器相关的设置，如迭代次数，另一个组具有mobsim的设置，如mobsim的结束时间。如第3章所示，许多MATSim模块可以添加到MATSim中，并通过指定相应的配置文件部分进行配置。

Minimal MATSim GUI

可用参数和有效参数值的列表可能因版本而异。要查看与您使用的版本相关的所有可用设置的列表，请在MATSim GUI工具中运行“Create Default config. xml“配置文件 ，见图2.2.2。这将创建一个新的配置文件，其中包含所有可用的参数，以及它们的默认值，通常还有一个解释性注释，从而更容易查看可用的设置。针对要模拟的场景，需要使用和修改特定的设置，可以将带有相应参数的行复制到配置文件中，并且在该文件中修改参数值。

MatSIM GUI Tools

配置文件包含以下信息：

"/>



"/>

示例可进入如下网址，进行查看：

• https://github.com/matsim-org/matsim-code-examples/blob/12.x/scenarios/equil/config.xml
• https://github.com/matsim-org/matsim-example-project/tree/master/scenarios/equil/config.xml

请注意，自版本0.9.x以来，大多数文件名都与配置文件保持相对路径。因此输入文件名也可以用url（统一资源定位器）表示。

在本例中，供应由“道路网络”提供，需求由“计划”文件提供。第2.2.1节描述了典型的输入数据。第一次和最后一次的迭代数值相同，意味着不需要执行需求的重规划。首先执行的是mobsim（图1.1），然后是每个执行计划的绩效评分。为了发挥作用，计分需要从配置文件中知道计划中使用的所有活动类型以及每个活动类型的典型持续时间。
第4章描述了进一步的配置可能性。

MatSIM loop, sometimes called the MATSim cycle

2.2 构建和运行基本场景

本节提供用于测试MATSim的输入数据文件以及输出的标准文件信息。第一，本节从典型的输入和输出数据开始。第二，它将涉及到MATSim中使用的单位、约定和坐标系。第三，本节将描述一个示例场景。第四，关于实际数据需求的提示。最后，以开始测试数据为结束，即使用免费提供的场景输入数据。

2.2.1 典型输入数据

MATSim最少需要如下文件：

• config.xml，包含MATSim的配置选项，见上文第2.1.3节。
• network.xml，包含（道路）网络的描述。
• population.xml，提供有关交通需求的信息，即个体人列表及其每日计划。

因此，population.xml 以及 network.xml可能会变得很大。为了节省磁盘空间，MATSim支持以压缩格式读写数据。MATSim使用GZIP压缩。因此，许多文件名都有附加后缀.gz，如 population.xml.gz. MATSim根据文件名识别文件是否为压缩的。
如下会更详细地阐述关于道路和人口文件的设置要求；有关配置文件，请参阅上面的第2.1.3节。

2.2.1.1 network.xml

道路网络是个体（或车辆）可以在其上移动的基础设施。道路由节点和链接（在图论中，也称为顶点和边）组成。MATSim的XML（可扩展标记语言）数据格式的简单网络描述可以包含大约以下信息：

有关工作示例，请进入以下网址进行查看：

• https://github.com/matsim-org/matsim-code-examples/tree/12.x/scenarios/equil
• https://github.com/matsim-org/matsim-example-project/tree/master/scenarios/equil

每个元素都有一个标识符id。Node由x和y坐标值描述（另见第2.2.3.3节和第17.1节）。Link具有更多功能；from和to属性引用节点并描述网络几何体。其他可用于描述交通道路的属性如下：

• Length：连接的长度，通常以米为单位（见第2.2.3节）。
• Capacity：连接的通行能力，即穿过连接的车辆数量，通常以每小时车辆数为单位。
• FreeSpped：自由速度是允许车辆沿连接线行驶的最大速度，通常以米/秒为单位。
• Perlanes：在“起”和“终”节点指定的方向上可用的车道数（永久车道）。
• Modes：链路上允许的模式列表。这是一个逗号分隔的列表，例如modes=“car，bike，taxi”。

所有链接都是单向的。如果一条路可以双向行驶，则必须使用“反向到”和“从”属性定义两个链接（请参见上面列表中id为2和3的链接）。

2.2.1.2 population.xml
File Format MATSim 交通需求由个体人的每日计划来进行描述。整个个体集合也称为人口量，因此该文件名为population.xml / plans.xml，因为人口文件基本上包含一个每日计划列表。

Population 中包含基于层次结构的数据，如下例所示。这个例子阐述了内部所包含的数据结构；最小的输入文件，对应着只需要较少的信息，之后会做阐述。

    
        
            
            
                123
            

            
            
                31
            

            
        
    


    
        
            ...
        
    

有关工作示例，请进入以下网址进行查看：

• https://github.com/matsim-org/matsim-code-examples/tree/12.x/scenarios/equil
• https://github.com/matsim-org/matsim-example-project/tree/master/scenarios/equil

Population 中包含人员列表，每个人员包含各自的计划列表，每个计划中包含 acitives 和 leg 列表。

每个人只有一个计划会被标记为选中。每个个体人所选择的计划由mobSIM执行。在重新规划阶段，可能会选择不同的计划。一个计划可以包含一个分数作为属性。在计分阶段，通过mobSIM计算计分，并在计分执行后将计分存储在计划中。

每个计划中的 activities 和 legs 列表描述了每个个体人的出行活动。

Activities：活动被分配了一个类型，通常包括了一个定义的结束时间，这部分中将日常计划中的最后一个活动排除。有些例外情况是，活动有持续时间而不是结束时间。这类活动通常是由路程匹配算法自动生成的，本书中没有描述。为了描述活动发生的位置，可以通过为活动指定一个x和y属性值来为其指定一个坐标，或者为其指定一个道路id，描述活动可以从哪条道路到达。因为模拟需要一个道路属性，所以当道路属性丢失时，Controler会为给定的坐标计算最近的道路。

Leg：描述 个体人 如何计划从一个位置到下一个位置；每个 leg 必须分配一个传输模式。leg 可以选择是否带有 trav_time属性，用于描述 leg 的预期行程时间。对于需要模拟的leg，它必须包含一条路线。路线的行进方式取决于leg定义好的模式。对于car leg来说，个体人必须按照给定顺序遍历所有链接，而对于 transit leg，则存储有关站点位置和预期公交服务的信息。MATSim会自动为不包含初始路线的初始计划 计算初始路线。

个体人在上一个activity（或leg）结束后直接启动leg。mobsim中个体人的处理取决于其选择的模式。默认情况下，mobsim很好地支持car leg 和 transit leg。 如果mobsim遇到一个它不知道的模式，它默认为远距离传输模式。在这种情况下，个体人将从模拟现实中移除，并在 leg 的预期行程时间过去后重新插入到其目标位置。

A Minimal Population File：人口数据格式是MATSim中最核心的数据结构之一，一开始可能显得有点过于繁杂。幸运的是，目前需要知道的只是一小部分。Population.xml 文件大约只需要以下信息：

    
        
            
            
            
            
            
        
    

    
    ...
    

可在 plans-minimal.xml in matsim-code-examples 查询相关示例。

以下项目可用于最简方式来进行描述：

• 每个人不需要一个以上的计划。
• 该计划不必选择或评分。
• 活动可通过其坐标定位。
• 活动应该有一个合理的结束时间。
• leg 只包含一个模式，没有路线。

当模拟开始时，MATSim Controler 将加载这样一个文件，然后为每个活动分配最近道路，为每个leg计算合适的行进路线，然后开始进行迭代模拟。

2.2.2 典型输出数据

MATSim创建可用于分析结果以及监视当前模拟设置进度的输出数据。一些文件总结了一个完整的MATSim运行，而另一些文件仅为特定的迭代创建。第一类文件直接进入输出文件夹的顶层，可以在配置文件的controler部分中指定。其他文件存储在 ITERS/it. {iteration number} 的iteration specific文件夹中，这些文件夹在output文件夹中连续创建。对于某些文件（通常是大型文件，如population），可以在配置文件中指定输出频率。然后它们只转到相应的迭代文件夹。总结整个MATSim运行的文件是“动态”构建的，即在每次迭代之后，存储当前计算的迭代值，允许对运行进行连续监视。一些文件是默认创建的（例如分数统计文件）；其他文件需要由相应的配置文件部分触发（例如计数数据文件）。

以下输出文件是连续构建的，以总结整个运行。

Log File：在MATSim运行期间，会打印一个日志文件，其中包含您以后可能需要的分析信息，或者运行崩溃时的记录。

Warnings and Errors Log File：有时，MATSim会识别仿真或其配置中的问题；然后会将警告和错误消息写入日志文件。由于日志文件包含的信息太多，因此可以忽略这些警告。在运行输出的目录中会生成一个单独的日志文件，其中只包含警告和错误消息。在运行期间/之后检查此文件以查找可能的问题非常重要。

Score Statistics：分数统计以图片形式提供(scorestats.png)，以及文本文件(scorestats.txt文件). 它们显示了每个迭代中所有个体人的平均、最佳、最差、已执行和总体平均值。图1.2显示了一个得分图示例。

Leg Travel Distance Statistics：leg 行程距离统计（文件：traveldistancestats.png 以及traveldistancestats.txt 文件)与得分统计数据相当，但相反，以旅行距离为主体进行绘制。

StopWatch：StopWatch (StopWatch.txt) 包含每次迭代的重新规划或mobsim执行操作的计算机时间（所谓的挂钟时间）。这些数据有助于计算性能分析，例如，与 mobsim 相比，重新规划需要多长时间？

为特定迭代创建以下输出文件：

Events：模拟中的每一个动作都被记录为一个MATSim事件，无论是活动开始还是路网道路线的改变，见图2.3。每个事件都拥有一个或多个属性。默认情况下，包含事件发生的时间。此外，还可以包括触发事件的个体人ID或发生事件的道路ID等信息。事件文件是后期分析的重要基础，就像可视化工具一样。第45.5节详细讨论了事件。

Mobsim events.png

Plan：在可配置的迭代中，打印当前的总体状态以及个体人的计划。最终迭代的计划也在 输出 文件夹中可以找到。

Leg Histogram：在每次迭代中，绘制 Leg 直方图。Leg 直方图描述了每个时间单位到达、离开或途中的个体人数量。为每个运输模式和所有运输模式的总和创建直方图。每个文件以迭代编号开始，以传输模式结束（例如，1.legHistogram_car.png or 1.legHistogram_all.png). 还创建了一个文本文件（例如，1. legHistogram.txt)，包含所有传输模式的数据。

Trip Durations：对于每个迭代，一个行程持续时间文件（例如，1. tripdurations.txt)，列出每个活动对的出行次数及其持续时间（例如，从工作到家或从家到购物）。

Link Stats：在每个迭代中，打印一个道路统计文件，其中包含每个网络链接上的每小时计数值和出行时间。如第6.3节所述，道路统计对于与真实世界的计数数据进行比较尤其重要。

2.2.3 单位、约定、坐标系统

2.2.3.1 单位

MATSim 试图对实际单位做一些假设，但有时对某些估计是必要的。一般来说，MATSim希望类似类型的变量（例如，所有距离）无论在哪里使用都在同一个单位中。在下面的简短概述中，列出了最重要的（预期的）单元。

Distance：例如，在道路的长度中使用距离单位。它们应该与坐标系使用相同的单位，从而允许MATSim计算直线距离。由于常用的UTM（通用横轴墨卡托）投影坐标系（见第2.2.3.3节）使用米作为距离单位，这是MATSim中最常用的距离单位。

Time：MATSim在某些特定场景里可以支持 时：钟：秒。但在内部，它使用秒作为默认的时间单位。例如，这意味着道路速度必须以每秒距离（通常为米每秒）来指定。这个规则的一个显著的例外是评分参数，MATSim期望每小时的值。

Money：该数值本身无单位。单位隐含地由货币的边际效用给出（参见下面的等式（5.5））。因此，当一个人从德国搬到瑞士时，参数 m 必须从“每欧元效用”改为“每瑞士法郎效用”。

2.2.3.2 约定

MATSim使用ID进行描述。这些标识符可以是任意字符串，但有以下例外：ID不应包含任何空格字符（包括制表符、新行等）或逗号、分号等，因为这些字符通常用于在ID列表上区分不同的ID。

2.2.3.3 坐标系统

在适当的坐标系中准备数据：在多个输入文件中，需要指定坐标，例如道路节点的坐标。目前，我们强烈建议不要使用WGS84坐标（即GPS（全球定位系统）坐标）或任何其他球坐标（东西方向的坐标范围为−180 至+180，南北方向的坐标范围为−90 至+90）。MATSim必须在部分代码中计算两点之间的距离。球坐标之间距离的计算非常复杂，而且可能很慢。相反，MATSim使用简单的毕达哥拉斯定理，但这需要笛卡尔坐标系。因此，我们强烈建议使用笛卡尔坐标系，最好是距离单位对应于一米的坐标系。

许多国家和地区都定义了自定义坐标系，并针对本地使用进行了优化。最好向您感兴趣地区的GIS（地理信息系统）专家咨询最常用的坐标系，并将其用于您的数据。

如果您没有关于您所在地区使用的坐标系的信息，则最好使用UTM坐标系。这个系统将世界划分为多个波段，每个波段宽6度，分为北部和南部，称为UTM区。对于每个分区，定义了一个优化的坐标系。为您所在的地区选择UTM区域（Wikipedia有一个很好的显示区域的地图；更好的选择是https://www.geoplaner.com/)使用它的坐标系。

如果对坐标系有具体需求的话，需要在录入数据的时候，将坐标系也录入到MATSim中。在以下案例中，可能某些分析可能需要输出到 GoogleEarth或QGIS 中做可视化。因此，可以在配置文件中指定MATSim需要使用的坐标系：

有多种方法可以指定所使用的坐标系。最简单的方法是使用 “EPSG代码”。大多数常用的坐标系已经标准化和编号。EPSG代码标识坐标系，可直接由MATSim使用。要为您的坐标系找到正确的EPSG代码（例如，其中一个UTM区域），请访问网站 http://www.spatialreference.org 有用。在本网站上搜索您的坐标系，例如“WGS 84/UTM Zone 8N”（用于北半球UTM Zone 8），以查找匹配坐标系及其EPSG代码的列表（在本例中）EPSG:32608)。另外，MATSim还可以解析 WKT 格式的坐标系描述。

从0.8.x版本开始，MATSim接受不同于内部坐标系的坐标系中的输入数据。这是通过类型的设置进行实现。

...

这也适用于其他输入文件，例如，plans 文件。然后，在输入过程中，该文件中的所有坐标将转换为配置的全局部分中给定的坐标系。

第三个选项是直接在相应的文件中指定坐标系。语法大约是

...

    
        EPSG:31468
        
    
...

输出文件通常包含这样一个条目，因此可以在那里进行检查。这也适用于坐标系与上述全局坐标系不同的输入文件，并且它提供与配置文件中的 inputCRS 条目相同的功能。

2.2.4 示例场景

MATSim发行版附带了一个名为equil的示例场景，位于examples/scenarios/equil文件夹中，其中包含以下文件：config.xml, network.xml, plans100.xml，plans2000.xml.gz，分别有100人和2000人的每日计划，只使用汽车模式。此外，还提供了一个只有两个人的小群体（plans2.xml），一个使用公共交通工具，另一个使用汽车模式。在文件夹（counts100.xml）中还可以找到计数数据的示例。

场景中的道路如图2.4所示。

Equil scenario network.png

下面几行通过讨论配置文件中最重要的部分，来解释 config.xml。

config.xml 文件的 “strategy” 部分：如下面的配置文件所示，此场景使用了重新规划。在每一次迭代中，10%的个体人重新选择他们的出行计划（模块：重新选择）。剩下的90%选择他们的最高分数计划在当前迭代中重新执行（模块：最高分）。如果代理的内存已满（由max Agent Plan Memory Size定义），需要从该内存中删除计划。默认情况下，得分最低的计划会被删除；该部分也具有可配置性，目前正在研究中。

config.xml 文件的 “planCalcScore” 部分：planCalcScore部分定义了用于评分的参数，如第5章所述。如示例中所示，指定了两种活动类型：h（home）和w（work）。population 文件（参见第2.2.1.2节）中包含的所有活动类型必须在配置文件的 planCalcScore 中定义。

config.xml 文件的 “controler” 部分：场景进行10次迭代，将文件输出到 ./output/equil（第2.2.2节），并使用QSim作为mobsim的计算内核（第1.3、4.4和7节中有更多关于mobsim的内容）。

Visualization 仿真结果可以通过Via可视化（第？？？章）或OTFVis（章节？？）。

2.2.5 数据需求

2.2.5.1 人口和活动时间表

需求估计是MATSim的重要组成部分。这意味着，在理论上，只需要向MATSim提供从一个模拟平均工作日到下一个工作日不变的需求组件。例如：人口及其居住和工作地点。然而，在实践中，MATSim还没有准备好对完整的出行需求进行内生建模。例如，必须提供活动的顺序和持续时间作为输入。MATSim未涵盖的所有出行需求选择都必须进行外部估算。

对于人口生成，存在两种可能性：简单的方法是直接使用完整的人口普查；更严格的方法是根据抽样或结构调查生成一个合成人口（例如，Guo和Bhat，2007）。对于MATSim，这两种方法都已经被瑞士联邦统计局（BFS）（2000）和Müller（2011）使用。

出行需求通常来源于调查：对于瑞士，来源于Microcesus（瑞士联邦统计局（BFS），2006年）。也可以使用较新的数据源，如GPS或智能手机出行日记（例如，Zilske和Nagel，2015）

需求和人口生成的一个关键部分是工作场所的分配，因为通勤交通仍然是交通模拟的主要问题，特别是在高峰时间。瑞士的全面普查工作地点是在市一级进行调查的。然而，这样优质的数据库并不多见。

在得到了研究区域的居住人口之后，可能需要额外的需求组成部分，例如跨境和货运。由于这些组件通常无法进行内部自主建模，MATSim提供了以不同方式处理不同子种群的功能（第4.6节）。
例如，可以规定过境个体人不得在研究区域内选择目的地，或者货运个体人不得将其送货活动改为休闲活动。

2.2.5.2 道路

在模拟实践中，使用了两种不同的网络类型：规划网络和导航网络（比较瑞士图2.4（a）和图2.4（b）中的例子，以了解苏黎世地区）。前者更精简，通常用于初步探索性模拟运行，而后者通常用于策略运行，通常提供更多的细节，如自行车，甚至行人连接。数据可从联邦办公室等官方来源、OSM（OpenStreetMap）等免费来源以及包括导航网络提供商在内的商业来源获得。

Zurich networks.png

2.2.6 打开场景输入数据

下面是一些示例场景

https://github.com/matsim-org/matsim-code-examples/tree/12.x/scenerios。

在以下网址可以找到更多方案

http://matsim.org/open-scenario-data。

2.3 MATSim 生存指南

MATSim有很多选择和可能性，找到这些选择和可能性可能是一项艰巨的任务。基于我们自己的经验总结，有以下几个建议：

1. 自版本0.9.x以来，配置文件中的大多数文件路径都是相对于配置文件的目录的。 一般来说，这会使文件路径的处理比过去容易得多。但是，旧的配置文件可能不再工作。 有些出乎意料的是，在大多数情况下，url可以用作输入路径。

2. 总是从一个小例子开始测试。

3. 总是先测试大型场景的1%数据量（例如，随机抽取的初始需求的子样本）。MATSimGUI（图2.1）允许使用命令工具 …Create sample Population 创建样本人口。

   如第4.4节所述，这需要调整一些参数，特别是mobsim的flowCapacityFactor和storageCapacityFactor。如第二部分第6.3节所示，示例场景还要求对计数数据进行参数调整。

4. 如果您的设置不再工作，请立即返回到工作版本，并从那里开始小步操作。

5. 检查logFileWarningErrors.log日志.

6. 检查附加到配置文件选项的注释。

   检查output_config.xml.gz 文件 或 logfile.log。

7. 尝试设置尽可能少的配置文件选项。

   带来两个优点：

   （i）除了必须设置的选项外，您的模拟将随着更新的MATSim默认值而改变，因此也会随着社区当前认为的最佳配置而改变。

   （ii）只要配置文件语法的更改与您自己的设置不同，您就不会受到影响。

   输出目录包含输出 output_config_reduced.xml，这是这种“最简化”配置文件的起点。

8. 文档：http://matsim.org/javadoc（或者使用IDE提供的javadoc文档）。

9. 最新教程：http://matsim.org/docs。

10. 最初运行更复杂的模式作为传送。 以后可以将它们添加为“真实”模式。

11. 最初运行时，先不要使用扩展程序。 对于扩展程序的功能，应该清楚其功能并逐步添加。