PLANit Default Input Data format (XML)

In this section of the manual we discuss the Default XML input format used by PLANit.

Here we only focus on the structure of the data formats . If the reader wants to know how to set up an assignment using input/output files of a specific format, we refer to the reference documentation on the Java and Python API for more detailed information.

Outline

Each major input has a dedicated section that details its structure and use:

Physical Network XML Input format, i.e., <macroscopicnetwork> element
Zoning Structure XML Input format, i.e., <macroscopiczoning> element
Demands XML Input format, i.e., <macroscopicdemand> element

Before diving into these sections however, it is advisable to quickly get acquainted with some basic concepts regarding XML and how PLANit, utilises this data format. At least have a quick look at the Basics section detailing overall structure in a PLANit context and discussing the main features. A small example input file is also provided to get you started.

Basics

PLANit project, one file or multiple input files?

The user can construct each major input (network, demands, zoning) separately in its own XML file, e.g.,

my_network.xml,
my_zoning.xml,
my_demands.xml,

or decide to store all inputs in the same file, e.g.

my_planit_input.xml

The former is useful if you have a large project, where you - for example - have multiple zoning systems that you want to apply to the same network, or you have multiple networks that you want to test with the same demands. If however, you just want to run a single traffic assignment run with one network, one set of demands, and one zoning structure, it is probably easiest to just construct your inputs in a single file.

In practice, there is no difference in how the inputs are constructed. Each major input is identified with a particular XML element signature by PLANit. As long as there is an XML file - with any name - in the directory that contains the required XML element signature, PLANit will attempt to parse it accordingly.

<PLANit>

For a single input file, the root element is <PLANit> and each of the three major input components (<macroscopicnetwork>, <macroscopiczoning>, <macroscopicdemand>) are its sub-elements, resulting in a file that looks something like the following:

<?xml version="1.0" encoding="ISO-8859-1"?>
<PLANit	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:gml="http://www.opengis.net/gml"											
		xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/macroscopicinput.xsd">
	<macroscopicnetwork>						
		...
	</macroscopicnetwork>
	<macroscopiczoning>
		...
	</macroscopiczoning>	
	<macroscopicdemand>					
		...
	</macroscopicdemand>	
</PLANit>

If multiple files exist in the same directory, with the same root element, PLANit, will simply parse the first one it encounters.

We refer the reader to the dedicated documentation pages for each of the major input components as provided in the Outline.

XML and XSD, what now?

XML files can contain any kind of markup elements. Therefore, you need a mechanism for a parser to find out what elements are valid and which ones are not. To do so, XML Schemas’ exist. An XML schema definition prescribes what a valid XML document looks like for some application. You then include a reference to your schema in the header of the XML file to let any parsers and/or human readers of the file know that the XML is expected to conform to this schema.

For example, when constructing the inputs in a single XML file, you should ideally reference the macroscopicinput.xsd for this reason.

By default PLANit will NOT verify the inputs actively and instead just parse the contents to maximise performance. Leaving out the schema reference will therefore not result in issues as long as your input is valid PLANit XML conforming to the XSD.

<PLANit xmlns:gml="http://www.opengis.net/gml"
	xmlns:xml="http://www.w3.org/XML/1998/namespace"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/macroscopicinput.xsd">
	
	<!-- Do things conform XSD Schema macroscopicinput.xsd -->
	
</PLANit>

Below you will find which schema definition goes with what input file configuration.

Single XML input file:

macroscopicinput.xsd

Separate XML input files:

Schema definitions are also defined in XML, but are stored in files with the .xsd extension. PLANit has XSD files for each of the major input components as well as the output meta-data XML.

In this manual we provide you with a user friendly description of the specification laid-out in the PLANit XSD files as well a references to the files themselves for the more technically inclined readers.

Geo-spatial XML = GML

Geospatial information is becoming more and more common in transport models. In the default XML input format for PLANit, this feature is supported by incorporating elements of the Geography Markup Language (GML). GML is a standard to represent all kinds of geo spatial data in XML. In PLANit, many elements of the network and zoning have a spatial aspect to them. for those components we allow optional GML elements to be specified to embed geospatial information in your models.

Embedding GML in PLANit is entirely optional. It is equally possible to provide for example lengths for links and leave out geo spatial information on nodes, and zones.

Like the PLANit schemas, GML has its own XML schemas to ensure GML elements are used properly. In PLANit, we prefix all GML elements with the “namespace” gml. In the example above this can be seen when including the schema definition for GML

<PLANit xmlns:gml="http://www.opengis.net/gml" ...

Whenever you encounter an element in the PLANit input XML files that is prefixed with gml it pertains to a GML element. For example a node can have a geo location identified by a gml:point like the following:

<infrastructurelayers srsname="EPSG:4326">
	<layer id="roadlayer">												
		<nodes>
			<node id="1"> 																
				<name>George Street roundabout</name> 							
                <gml:Point> 														
                    <gml:pos>150.512796 -34.900145</gml:pos>
                </gml:Point>														
			</node>
		...

The srsname attribute identifies what Coordinate Reference System is used. This signals how the software should interpret the coordinates provided. As you can see, the GML elements are prefixed with gml to distinguish them from the regular PLANit elements.

Features

The PLANit native input format has the following key features:

Full XSD schema support, i.e., validity of input file can always be verified during parsing, or before parsing
Flexible input file arrangement, i.e., all components can be in one file, or separate files per component can be offered
Extensive use of default arguments (optional elements) to minimise user configuration
Flexible GIS support for optional location information via GML embedding and SRS support

In its simplest form, the user provides a single xml file containing all mandatory components; network, demand, and zoning. See Minimum Example. Alternatively, these three main components can be provided separately.

Example

Below you will find an example of a single XML file describing a simple - yet complete - set of inputs. The network contains:

One link having two directions, so
Two link segments, and
Two nodes (on either end of the link)

Basic zoning structure:

Two zones, each with one centroid, so
Two centroids,
Two connectoids, i.e., references to nodes that allow access/egress to/from a zone

Basic demands:

1 time period with a duration of 1 hour (3600s)
1 trip between zone 1 and zone 2

<PLANit xmlns:gml="http://www.opengis.net/gml"
	xmlns:xml="http://www.w3.org/XML/1998/namespace"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="<path_to>/macroscopicinput.xsd">
	
	<!-- Demand component -->
	<macroscopicdemand>
		<demandconfiguration>
			<timeperiods>
				<timeperiod id="1">
					<duration>3600</duration>
				</timeperiod>
			</timeperiods>
		</demandconfiguration>
		<oddemands>
			<odcellbycellmatrix timeperiodref="0">
				<o ref="1">
					<d ref="2">1</d>
				</o>
			</odcellbycellmatrix>
		</oddemands>
	</macroscopicdemand>
	
	<!-- Physical network component -->
	<macroscopicnetwork>
		<infrastructurelayers>
			<layer id="1">
				<nodes>
					<node id="1" />
					<node id="2" />
				</nodes>
				<links>
					<link nodearef="1" nodebref="2">
						<linksegment id="1" dir="a_b" />
						<linksegment id="2" dir="b_a" />
						<length>10</length>
					</link>
				</links>
			</layer>
		</infrastructurelayers>
	</macroscopicnetwork>
	
	<!-- zoning structure component -->
	<macroscopiczoning>
		<zones>
			<zone id="1">
				<centroid>
					<gml:Point>									
						<gml:pos>45.256 -110.45</gml:pos>
					</gml:Point>
				</centroid>
				<connectoids>
					<connectoid noderef="1" />
				</connectoids>
			</zone>
			<zone id="2">
				<centroid>
					<name>2</name>
					<gml:Point>
						<gml:pos>45.256 -110.45</gml:pos>
					</gml:Point>
				</centroid>
				<connectoids>
					<connectoid noderef="2" />
				</connectoids>
			</zone>
		</zones>
	</macroscopiczoning>
</PLANit>