Demands Input Data format (XML)

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

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

Demands are specified in trips between zones for a given modality (mode) and for a given duration (time period).

Units: trips are always in veh/h, regardless of the duration specified. So, if you would specify ‘100’ veh/h between two points, while the duration of the time is 10 hours. Then, the total number of trips equates to 10*100=1000.

Demands are always provided in the mode they represent. PLANit will internally convert these numbers into pcu/h when appropriate by utilising the pcu conversion value set on the mode at hand.

You can provide trips in different ways, to maximise flexibility and potentially minimise overhead in the XML:

• cell-by-cell matrix, ideal for very sparse matrices
• row based matrix, ideal for matrices where many zones do not produce any trips, each row is in CSV format
• raw matrix, ideal for large matrices with few zero entries, i.e., matrix in CSV format within a single XML element

PLANit will assume that the referenced zones are compatible with the zoning structure that is adopted in the simulation

<macroscopicdemand>

The demands structure can be described in a stand alone XML file - only providing the demands structure - or it can be provided as part of a PLANit XML file describing all input components. Either way, all the demands structure specific information is enclosed within the XML root element <macroscopicdemand>. 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">
	...
	<macroscopicdemand>
		...
	</macroscopicdemand>
	...
</PLANit>

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

<macroscopicdemand
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"									
	 xsi:noNamespaceSchemaLocation="../schema/macroscopicdemandinput.xsd">
...	
</macroscopicdemand>

This root element can contain 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.

Demands defaults

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

Default Traveller type

When no <travellertypes> are defined, a single default traveller type is created and assumed to be applied to all user classes (implicitly). No explicit references to traveller types are to be made in other XML elements with optional traveller type attributes.

The Default Traveller Type has the following characteristics:

Default User class

When no <userclasses> are defined, a single default user class is created. No explicit references to user classes are to be made in other XML elements with optional user class attributes.

With respect to the mode the default user class adopts:

• When no modes are defined: Adopt the Default Mode,
• When a single mode is defined: Adopt the single defined mode,
• When multiple modes are defined: Not allowed

With respect to the traveller type the default user class adopts:

• When no traveller types are defined: Adopt the Default Traveller Type,
• When a single traveller type is defined: adopt the single defined traveller type,
• When multiple travller types are defined: Not allowed

The **Default User Class ** has the following characteristics:

XML Elements

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

<demandconfiguration>

The demand configuration allows you to define the time periods, traveller types, and user classes. A user class is a combination of a traveller type and mode, e.g., if you want to differentiate between commuters and leisure drivers, you would have two traveller types, but both could be driving a car, so they can have the same mode. In that case, there would be two user classes.

You can omit the user classes and traveller types in which case PLANit will inject a default entry for both, see Demands defaults. However, you must at least specify a single time period.

This element has the following sub-elements:

<> <travellertypes>

Traveller types represent different types of travellers that for the sake of modelling are grouped together based on some common characteristics. When this element is absent, a single default traveller type will be generated by PLANit.

If the default traveller type approach is adopted, no references to traveller types are to be made in any forthcoming elements as there is nothing to refer to explicitly, i.e., no (external) ids of traveller types are present so they cannot be referenced.

This element has the following sub-elements:

<><> <travellertype>

A Traveller type represents travellers that for the sake of modelling are grouped together based on some common characteristics. When not a single entry of this element is present, a default traveller type will be generated by PLANit.

If the default traveller type approach is adopted, no references to traveller types are to be made in any forthcoming elements as there is nothing to refer to explicitly, i.e., no (external) ids of traveller types are present so they cannot be referenced.

Each traveller type has a unique (external) id that is provided as an attribute.

This element has the following simple-elements:

<> <userclasses>

User classes represent different combinations of traveller types and modalities (modes). When this element is absent, a single default user class will be generated by PLANit.

If the default user class approach is adopted, no references to user classes are to be made in any forthcoming elements as there is nothing to refer to explicitly, i.e., no (external) ids of user classes are present so they cannot be referenced.

This element has the following sub-elements:

<><> <userclass>

A user class represents a combination of a traveller type and modality (mode). When not a single user class element is present, the default user class will be generated by PLANit.

When <moderef> is absent, the default mode or the single defined mode is assumed to be used. In this case the user must not have specified more than one mode in the network.

When <travellertyperef> is absent, the default traveller type or the single defined traveller type is assumed to be used. In this case the user must not have specified more than one traveller type in the network.

Each user class has a unique (external) id that is provided as an attribute.

This element has the following simple-elements:

<> <timeperiods>

Time periods are used to define the duration and description of this duration for travel demand. At least a single time period must be explicitly defined.

This element has the following sub-elements:

<><> <timeperiod>

A time period is used to define the duration and description of some travel demand. At least a single time period must be explicitly defined. You can define the start time which should follow the XSD schema format of xs:time which is simply a combination of numbers and colons following the predefined format of hh:mm:ss.

Each user class has a unique (external) id that is provided as an attribute.

This element has the following simple-elements:

This element has the following sub-elements:

<><><> <duration>

The duration of a time period in the unit of preference (hour, minute, or second). When absent, seconds (s) are assumed. A duration cannot exceed a day, i.e., 86400 seconds, or 24 hours.

Each duration can specify its unit as an attribute.

<> <oddemands>

Origin-Destination (OD) demands represent the trip based travel demands in veh/h. You can provide the travel demand in various matrix formats, depending on what best suits your application (cell-by-cell, row based, raw (csv only)). The choice is a trade-off between readability vs bloatedness of the file.

Demands are always provided in the mode they represent. PLANit will internally convert these numbers into pcu/h when appropriate by utilising the pcu conversion value set on the mode at hand.

This element has the following sub-elements:

<><> <odcellbycellmatrix>

Most readable of the travel demand matrix formats, but also the most bloated. Each cell is individually set. When a matrix is very sparse, this might be a good choice, since unspecified cells will default to zero demand.

All referenced origins/destinations must be available as zones in the zoning structure that is adopted.

Each <odcellbycellmatrix\> has the following attributes.

^* It is compulsory if more than one user class is specified, otherwise leaving it out will assume the one available user class is adopted (default or specified)

This element has the following sub-elements:

<><><> <o>

Origin row placeholder in the odcellbycellmatrix. When it is provided without a reference to a specific origin, all <o> elements are assumed to be provided in ascending order, one for each zone, without exception. In that case, none of the <o> alements should reference a particular origin zone. Alternatively, all <o> elements provide an explicit reference to an origin zone in incremental order. This way it is possible to omit origin zones from the definition resulting in a sparse matrix.

Each <o\> origin zone element has the following attributes.

This element has the following sub-elements:

<><><><> <d>

Destination row placeholder in the odcellbycellmatrix. When it is provided without a reference to a specific destination, all <d> elements are assumed to be provided in ascending order, one for each zone, without exception. In that case, none of the <d> alements should reference a particular destination zone. Alternatively, all <d> elements provide an explicit reference to a destination zone in incremental order. This way it is possible to omit destination zones from the definition resulting in a sparse matrix.

Each <d\> destination zone element has the following attributes.

<><> <odrowmatrix>

Travel demand matrix format, where you provide the demand on a row-by-row basis. Each row is provided as a comma separated list. When particular destinations do not have any travel demand, they must still be included with explicit 0 values.

All referenced origin rows must be available as zones in the zoning structure that is adopted.

Each <odrowmatrix\> has the following attributes.

^* It is compulsory if more than one user class is specified, otherwise leaving it out will assume the one available user class is adopted (default or specified)

This element has the following sub-elements:

<><><> <odrow>

Origin row placeholder in the odrowmatrix. When it is provided without a reference to a specific origin, all <odrow> elements are assumed to be provided in ascending order, one for each zone, without exception. In that case, none of the <odrow> alements should reference a particular origin zone. Alternatively, all <odrow> elements provide an explicit reference to an origin zone in incremental order. This way it is possible to omit origin zone rows from the definition resulting in a sparse(r) matrix.

Each <odrow\> origin zone element has the following attributes.

The value of the element should be configured as:

<><> <odrawmatrix>

Travel demand matrix format, where you provide the entire Origin-Demand travel demand matrix in a single elements in CSV format. You are required to provide all values for all Origin-Destination combinations in this case. As a user you can configure what separators you use for origin rows and destination values.

The number of values in the CSV string must match exactly: ZONES X ZONES. Also see zoning structure that is adopted.

Each <odrawmatrix\> has the following attributes.

^* It is compulsory if more than one user class is specified, otherwise leaving it out will assume the one available user class is adopted (default or specified)

This element has the following sub-elements:

<><><><> <values>

Contains the values for an od raw matrix as a CSV string.

CSV value string should be configured as:

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 demand 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"?>
<macroscopicdemand
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"								
	 xsi:noNamespaceSchemaLocation="<path_to>/macroscopicdemandinput.xsd">			
	<demandconfiguration>																	
		<travellertypes>															
			<travellertype id="1">
				<name>default</name>
			</travellertype>
		</travellertypes>
		<userclasses>																
			<userclass id="1" moderef="1" travellertyperef="1">
				<name>regular car user</name>
			</userclass>
		</userclasses>
		<timeperiods>																
			<timeperiod id="1">
				<name>Afternoon 2PM-4PM</name>
				<starttime>14:00:00</starttime>
				<duration unit="s">7200</duration>
			</timeperiod>
			<timeperiod id="2">
				<name>Afternoon 4PM-5PM</name>
				<starttime>16:00:00</starttime>
				<duration unit="h">1</duration>
			</timeperiod>
			<timeperiod id="3">
				<name>Afternoon 5PM-6PM</name>
				<starttime>17:00:00</starttime>
				<duration unit="h">1</duration>
			</timeperiod>						
		</timeperiods>
	</demandconfiguration>
	<oddemands>																		
		<odcellbycellmatrix timeperiodref="1" userclassref="1">
			<o ref="1">																
				<d ref="1">0.0</d>													
				<d ref="2">150.0</d> 
			</o>
			<o ref="2">
				<d ref="1">300</d>
			</o>
		</odcellbycellmatrix>
		<odrowmatrix timeperiodref="2" userclassref="1" ds=",">
			<odrow ref="1">0.0,150.0</odrow>																														
			<odrow ref="2">300.0,0.0</odrow>
		</odrowmatrix>
		<odrawmatrix timeperiodref="3" userclassref="1">
			<values os=" " ds=",">0.0,150.0 300.0,0.0</values>
		</odrawmatrix>
	</oddemands>
</macroscopicdemand>