Physical Network Input Data format (XML)

In this section of the manual we discuss the Physical Network infrastructure’s XML input format used by PLANit.

If you are only interested to see an example file, jump to the Expanded Example.

<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>. When part of a larger (single) PLANit input file, the structure should resemble something like the following:

<PLANit	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:gml="http://www.opengis.net/gml"											
		xsi:noNamespaceSchemaLocation="../schema/macroscopicinput.xsd">
	<macroscopicnetwork>
		...
	</macroscopicnetwork>
	...
</PLANit>

Whereas if, it is a stand-alone file, it should look something like

<macroscopicnetwork
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xmlns:gml="http://www.opengis.net/gml"											
	 xsi:noNamespaceSchemaLocation="../schema/macroscopicnetworkinput.xsd">
...	
</macroscopicnetwork>

This root element can contain only two sub-elements:

In the remainder of this page, we discuss each of the eligible XML elements in order of expected appearance, its attributes and 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.

Lastly, we provide 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.

Network defaults

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

Default Mode

When no modes are specified under the <linkconfiguration> a single default mode is created to represent all 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.

The Default Mode has the following characteristics:

Default Link Segment Type

When no link segment types are specified under the <linkconfiguration> 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:

Default Link Segment Type Mode Properties

When one or more mode specific properties are not specified for a mode when configuring the <linksegmenttype> element under <linkconfiguration> default values will be applied

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

XML Elements

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

<linkconfiguration>

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

<> <modes>

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

<><> <mode>

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

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

<> <linksegmenttypes>

Link segment types define the different types of link segment properties that can be attributed to links, 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.

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.

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

This element has the following simple-elements:

This element has the following sub-elements:

<><><> <modes>

Modes allowed for the link segment type. For each specified mode, dedicated properties for this link segment type can be specified. When absent, all available 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.

This element has the following sub-elements:

<><><><> <mode>

Mode allowed for the link segment type. Dedicated properties for this link segment type are specified here.

If you want to assign the same properties to all available modes, use the “0” reference to indicate this applies to all modes. In that case only a single mode element is allowed because it prescribes the properties for all modes.

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

This element has the following simple-elements:

When any of the simple-elemants are absent, they take on the minimum of the default value and the mode’s maximum speed defined under <linkconfiguration><modes><mode>.

When the link segment is assigned a link segment type it can (but shouldn’t) happen that the link (segment’s) physical maximum speed is smaller than the link segment’s type maximum and/or critical speed. In that special case, the mode’s speed is restricted to the link (segment’s) physical maximum speed. In other words, PLANit, will always adopt the most restrictive speed that is defined.

<infrastructure>

The infrastructure element contains all the physical network infrastructure available. It consists of nodes, links, and an optional Spatial Reference System (SRS) SRID string for the case where the nodes have geo-spatial location information embedded in them via GML.

The SRS identifier is set through an attribute. When absent Cartesian system is assumed with 0,0 to be the top left

Currently, if a Cartesian system is used, 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:

<> <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 inter-connect links. It can have a name and unique geo-location based on its SRS. It also must have a unique identifier (external id) available as an attribute:

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., (external) 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 (external) 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:LinkString>, 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., (external) 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">
	<configuration>																		
		<modes>																			
			<mode id="1">																
				<name>car</name>														
				<pcu>1</pcu>																				
			</mode>										
		</modes>		
		<linksegmenttypes>																
			<linksegmenttype id="1">													
				<name>local road</name>													
				<maxdensitylane>180</maxdensitylane>									
				<capacitylane>2000</capacitylane>										
				<modes>
					<mode ref="1">															
						<maxspeed>40</maxspeed>											
						<critspeed>35</critspeed>										
					</mode>				
				</modes>
			</linksegmenttype>
		</linksegmenttypes>			
	</configuration>
	<infrastructure srsname="EPSG:4326">												
		<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>
	</infrastructure>
</macroscopicnetwork>