Physical Network Input Data format (XML)

In this section of the manual we discuss the physical network’s XML input format used by PLANit.

• If you are only interested to see an example file, jump to the Expanded Example.
• XML Schema of macroscopic network https://planitmanual.github.io/version//xsd/macroscopicnetworkinput.xsd

<macroscopicnetwork>

Physical Network can be described in a stand alone XML file - only describing the network characteristics - or as part of a PLANit XML file describing all input components. Either way, all physical transport network infrastructure is enclosed within the XML root element <macroscopicnetwork>.

This root element can contain only two sub-elements and an id element:

The configuration deals with overall configuration options across all infrastructure layers. Each infrastructure layer within the infrastructure layers element defines physical infrastructure for one or more of network modes.

In the remainder of this page, we discuss each of the eligible XML elements in order of expected appearance in detail. We explore their attributes, sub-elements, or simple elements (elements without sub-elements). At the bottom of the page an expanded example is provided highlighting all the available options explicitly.

Before we do so, we discuss the default values for (optional) element(s). These defaults are only relevant when you do not explicitly configure the related elements explicitly in the XML input file. Only then, PLANit will revert to these defaults.

Lastly, PLANit comes with a number of predefined modes. When these modes are activated in the network file, the user only needs to specify their name, in that case, their properties, e.g., pcu value, features, will be populated based on the mode’s defaults automatically.

Available predefined modes

A predefined mode can be activated by creating a new mode under the modes element and set its name to the name outlined for the predefined mode. PLANit provides the following predefined modes “out of the box”.

Predefined mode names are protected, meaning that if you attempt to define your own mode with its own attributes but use a predefined mode’s name (id). PLANit will overwrite your settings with the defaults.

Bicycle:

Bus:

Car:

Car high-occupancy:

Car ride-share:

Goods:

Heavy goods:

Large heavy goods:

Light-rail:

Motor bike:

Pedestrian:

Subway:

Train:

Tram:

Ferry:

Network defaults

Each network entity/element’s defaults are listed below.

Default Mode

When no modes are specified under the <configuration> the single predefined mode of type car is created to represent all modes, see predefined modes.

• No explicit references to modes are to be made in other XML elements with optional mode attributes because there is no mode to explicitly refer to.
• It is assumed that all link segments are accessible to the default mode and that all demand utilises this default mode of travel.

Default Link Segment Type

When no link segment types are specified under any <layerconfiguration> a single default link segment type is created that is applied to all link segments. In that case, the default link segment type accepts all available modes.

The Default Link Segment Type has the following characteristics:

Note that the default for capacity is only used if the adopted assignment does not adopt a fundamental diagram or if the adopted fundamental diagram cannot infer a better estimate of the capacity based on the free flow speed, maximum density per lane and default backward wave speed.

Default Link Segment Type Mode Access Properties

When one or more mode specific properties are not specified for a mode when configuring the <linksegmenttype><access> element under <layerconfiguration>, then, default values will be applied. It is not advisable to leave this out for anything else but testing purposes, since it is unlikely that the defaults accurately reflect the true conditions.

The Default Link Segment Type Mode Access Properties has the following characteristics:

XML Elements

This section discusses the XML elements under the <macroscopicnetwork> root element in expected order of appearance.

<configuration>

Optional configuration of the physical road network. When not specified, the default mode will be activated. This element has the following sub-elements:

<> <modes>

Modes available in this project. When absent the default mode is created. This element has the following sub-elements:

<><> <mode>

A user can specify a mode either by referring to an existing predefined PLANit mode by simply referencing it’s name and leave out all other attributes because these will be auto-populated.

Alternatively, you can create your own custom mode, in which case you should not use one of the predefined mode’s protected names. If you do, the other attributes that you specify will be ignored and the predefined mode’s defaults will be applied instead. When you create a custom mode, simply choose an appropriate name and provide all attributes so that PLANit knows how to populate the mode’s fields.

The mode’s (XML) identifier is set through an attribute

Each mode can have a description(name) and pcu value. These are configured via simple elements:

In addition there are some features of a mode captured based on their physical and usage, namely

<><><> <physicalfeatures>

A mode is characterised by a number of physical features. In PLANit we distinguish three main physical features, each of which has various options.

• Vehicular type: is the mode represented by a vehicle or not
• Motorisation type: does the mode have a motor or not
• track type: does the mode use the road, rail, or water to propagate

<><><> <usabilityfeatures>

How a mode is used is defined by this element. Currently, the usability features comprise of

• usedTo type: how is this mode used

<infrastructurelayers>

The infrastructure layers element contains all the physical network infrastructure (layers) available. It consists of one or more layers, each containing for example nodes, links, and link segments. Each layer supports one or more modes that use this layer. Each mode can only be supported on one layer. Therefore, multi-modal trips require transfers between layers, which is dealt with through transfers(zones). An optional Spatial Reference System (SRS) SRID string can be provided across all layers here to identify how to interpret the geo-spatial location information embedded in the elements via GML.

The SRS identifier is set through an attribute.

Geolocation information can be left out, but in that case, it is expected the user explicitly sets the lengths on all link (segments) since they cannot be computed based on the SRS.

This element has the following sub-elements:

<layer>

Each infrastructure layer uniquely defines the physical environment supporting one or more modes. Each layer has its own configuration regarding for example the link segment types it supports.

The modes attributes should reference one or more of the modes defined under <configuration> in a comma separated fashion, e.g., modes="car,bus". A mode supported can only be supported by one layer and one layer only. In case the modes attribute is absent, it is assumed only a single layer is present an all modes are supported by this layer by default.

<> <layerconfiguration>

The optional layer configuration allows one to define the link segment types available to this layer, where a link segment type outlines how the various mode behave on a link segment that utilises it. The types defined under this configuration can only reference modes supported by the layer at hand. When not specified, the default link segment type will be activated. This element has the following sub-elements:

<> <linksegmenttypes>

Link segment types define the different types of link segment properties that can be attributed to links on the layer, including mode specific attributes.This is useful to attach a set of common properties to multiple links by referring to the same link segment type.

When absent a default link segments type is created and applied to all link segments in the network (layer).

This element has the following sub-elements:

<><> <linksegmenttype>

Link segment type defines a set of properties that can be attached to one or more link segments on the layer.

The Link segment type’s (XML) identifier is set through an attribute

This element has the following simple-elements:

Note that if capacity is absent, the default is only used if the adopted assignment does not support a fundamental diagram able to infer a better estimate for the capacity based on the free flow speed, maximum density per lane, and default backward wave speed.

This element has the following sub-element that defines the mode access to this type:

<><><> <access>

Here we define the groups of modes that are allowed access for links with this segment type. For each groupaccess entry one or more modes can be attached which will inherit the dedicated properties set within this group, most notably the maximum speed.

When absent, all available road based modes are assumed to be allowed based on their properties, (possibly dynamically constrained by the physical link properties). when present, at least a single mode sub-element must be present.

link segment types that represent rail, typically only allow a single rail based mode and typically do not allow road based modes. Therefore, we expect the user to explicitly include rail based modes at all times. When no modes are defined, rail based modes are not allowed, in contrast to road based modes.

In the special case a link segment allows both rail and road based modes, e.g., trams and cars, then, all modes that are allowed must be specified, not only the rail based modes.

This element has the following sub-elements:

<><><><> <accessgroup>

Group of properties to be applied to the referenced modes that are allowed access for links with this segment type.

The maximum speed that is eventually applied to a mode on a link segment of this type is the minimum of the three available maximum speeds: (i) the physical speed limit on the link segment, (ii) the mode’s maximum speed identified on the global definition for the mode, (iii) the maximum speed imposed via these mode properties specific to the link segment type applied to the link segment.

The Link segment type’s mode reference (XML) identifier is set through an attribute:

When the moderefs attribute is left out, then only a single accessgroup for road modes can be defined, otherwise modes would be included in multiple access groups which is not allowed.

This element has the following simple-elements:

When the max or critical speed is absent it takes on the mode’s maximum speed restricted by the link segment’s free speed on whatever link segment the type is applied.

<> <nodes>

Nodes represent the locations where links (roads) intersect and traffic interacts with each other. This container holds all the node specifications for the network

This element has the following sub-elements:

<><> <node>

A node represents a point location in space, used to represent the end or start point of connected links. It can have a name and unique geolocation based on its SRS. It also must have a unique identifier (XML id) available as an attribute. When sourced from a different data format, e.g., OSM, the external-id attribute will relfect the original identifier from the third party source.

This element has the following simple-elements:

This element has the following sub-elements:

In its simplest form the <gml:Point> element has a single sub-element <gml:pos> containing two doubles separated by a space, see example below. For a detailed description of the gml:point element, please consult the latest official GML documentation

In PLANit, we do not allow separate SRS definitions per <gml:Point>, even though the specification of GML allows this. Therefore, make sure you do not define the srsName= attribute on any <gml:Point> embedded in PLANit XML files.

<!--  example of node with basic gml:point and gml:pos location information -->
<node id="1"> 																
	<name>George Street roundabout</name> 							
    <gml:Point> 															
        <gml:pos>150.512796 -34.900145</gml:pos>
    </gml:Point>														
</node>

<> <links>

Links are non-directional connections between two nodes. Each link can hold two link segments, where each link segment has a single (opposing) direction.

This element has the following sub-elements:

<><> <link>

A links is a non-directional connection between two nodes (node a and node b). A link can hold two link segments, where each link segment has a single (opposing) direction. IT can also hold a geometry in the form of a gml:LineString. This geometry (if present) is used in combination with the SRS to extract the link length which is applied to the link and its two link segments. Alternatively, a length can be provided directly, overruling the geo-spatial length.

In case the end and start coordinates of the geometry do not match the node locations, the node locations are added as additional locations at the start/end of the line string during the parsing process to ensure a valid connected network geometry.

It has a unique user defined identifier, i.e., (XML) id that is set via an attribute, the same goes for the referencing of the a and b nodes that must refer to an existing node (XML) id:

This element has the following simple-elements:

This element has the following sub-elements:

In its simplest form the <gml:LineString> element has a single sub-element <gml:coordinates>, see example below. For a detailed description of the gml:LineString element, please consult the latest official GML documentation

In PLANit, we do not allow separate SRS definitions per <gml:LineString>, even though the specification of GML allows this. Therefore, make sure you do not define the srsName= attribute on any <gml:gml:LineString> embedded in PLANit XML files.

<!--  Example of link with gml:LineString and gml:coordinates location information 
	Note: You define a separator within a pair that represent a single point on the line with "ts" (tuple separator) and
	the separator between tuples via cs, here a comma for tuples and a space between tuples are used.
-->
<link id="1" nodearef="1" nodebref="2">
	<name>Broadway</name>			
	<linksegment id="1" dir="a_b" typeref="1">	
		<numberoflanes>2</numberoflanes>								
	</linksegment>
	<linksegment id="2" dir="b_a" typeref="1">
		<numberoflanes>1</numberoflanes>
	</linksegment>					
	<gml:LineString>
		<gml:coordinates cs=" " ts=",">100,200 150,300</gml:coordinates>
	</gml:LineString>									
</link>

<><><> <linksegment>

A link segment is a directional connection between two nodes (node a and node b). This direction can be from a to b, or b to a depending on the configuration. There can however only be a single link segment in either direction for each link. In addition, a physical maximum speed can be defined as well as the number of lanes available. Lastly, each link segment can have exactly one link segment type, this type must be present, unless no link segment types have been defined on the network at all. In that case it can be omitted and the auto-generated default link segment type will automatically be attached to it.

The direction is specified as an attribute, and each link segment has a unique user defined identifier, i.e., (XML) id that is set via an attribute:

^* Compulsory, unless no link segment types are defined, in that case it must be omitted

This element has the following simple-elements:

If the maximum speed limit is larger than the respective maximum speed for a mode on the referenced link segment type, the most restrictive speed is used as the maximum speed for the link segment for that mode, i.e., in this case the link segment type’s speed limit. This to prevent inconsistencies during the model run.

Expanded Example

Below you will find an expanded example where all elements and attributes are explicitly set, to give you an idea of the overall structure of the macroscopic network XML. This example does not make sense as an actual input file, it is purely meant to show off all aspects of the file, rather than be used as a practically feasible input file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<macroscopicnetwork
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xmlns:gml="http://www.opengis.net/gml"											
	 xsi:noNamespaceSchemaLocation="<path_to_schema>/macroscopicnetworkinput.xsd">
	<id>n1</id>
	<configuration>																		
		<modes>																			
			<mode id="car">																
				<name>car mode</name>														
				<pcu>1</pcu>																				
			</mode>										
		</modes>					
	</configuration>
	<infrastructurelayers srsname="EPSG:4326">
		<layer id="road" modes="car">
			<layerconfiguration>
				<linksegmenttypes>																
					<linksegmenttype id="1">													
						<name>local road</name>													
						<maxdensitylane>180</maxdensitylane>									
						<capacitylane>2000</capacitylane>										
						<access>
							<mode ref="1">															
								<maxspeed>40</maxspeed>											
								<critspeed>35</critspeed>										
							</mode>				
						</access>
					</linksegmenttype>
				</linksegmenttypes>
			</layerconfiguration>												
			<nodes>
				<node id="1"> 																
					<name>George Street roundabout</name>
					<gml:Point>
						<gml:pos>150.512796 -34.900145</gml:pos>
					</gml:Point>														
				</node>
				<node id="2"> 
					<name>Broadway intersection</name>
					<gml:Point>
						<gml:pos>150.512527 -34.900319</gml:pos>
					</gml:Point> 					
				</node>				
			</nodes>		
			<links>
				<link id="1" nodearef="1" nodebref="2">							
					<name>Broadway</name>												
					<linksegment id="1" dir="a_b" typeref="1">	
						<numberoflanes>2</numberoflanes>			
						<maxspeed>50</maxspeed>												
					</linksegment>
					<linksegment id="2" dir="b_a" typeref="1">
						<numberoflanes>1</numberoflanes>
						<maxspeed>50</maxspeed>
					</linksegment>					
					<gml:LineString>									
						<gml:coordinates cs=" " ts=",">100,200 150,300</gml:coordinates>
					</gml:LineString>	
					<length unit="km">1.33</length>									
				</link>
			</links>
		</layer>
	</infrastructurelayers>
</macroscopicnetwork>