Input Builder examples

Examples on how to configure PLANit project inputs

Here we provide you with a number of examples to set-up your PLANit project by explicitly choosing a particular InputBuilder. the input builder is responsible for parsing project inputs (network, zoning, demands) in a particular format and provide them to PLANit as a valid PLANit memory model.

For each input format that is supported an InputBuilder implementation is required. Each input format has its own configuration options exposed on the InputBuilder instance.

The default InputBuilder compatible with the PLANit input data format is the PlanitInputBuilder. Other InputBuilder implementations - and therefore data formats - might either be supported by third parties, your own implementation, or the PLANit project itself. For example, we have an experimental InputBuilder for the TNTP format as an example here.

Prerequisites:

It is assumed you know how to set up a PLANit project, otherwise see Setting up a project
It is assumed you know how to configure outputs, otherwise see Setting up a outputs

Note that the required Java imports are not listed in these examples as it is expected that the user has access to an IDE (like Eclipse), where this is added to the Java file automatically upon usage.

Example	Name	Description
1	PLANit input format	Example of setting up a PLANit project by explicitly setting the PLANit input format
2	TNTP input format	Example of setting up a PLANit project while adopting a TNTP input format (experimental)

For all examples we adopt the following defaults, and/or settings regarding other components, unless indicated otherwise:

Project: CustomPlanItProject
Outputs: default PLANit XML/CSV output format
Assignment: Traditional static assignment

PLANit input format

In this example we explicitly define the PLANit input format to be used. This will trigger the parser to look for XML input files in the PLANit XML input format in the designated project directory. Also, because we have access to the builder we can configure it or use some of its features if we want to beyond the basic input of the project path. For example by validating some of our XML files with an XSD schema before passing it on to PLANit.

The input format is defined by providing an InputBuilder. The InputBuilder expects a particular input format for the input files. The default input format of PLANit itself, i.e., PlanitInputBuilder, is used here. We explicitly set this as the input builder. When you have access to an alternative implementation of input builder, for example because you implemented your own for your own data format, you must use the CusomPlanItProject to be able to use it.

Note that when you use a PlanitSimpleProject or PlanitProject, PLANit will automatically create the PLANitInputbuilder for you.


final String projectPath = "<insert the project path here>";

try {
  
  // *NEW*
  PlanItInputBuilder inputBuilder = new PlanItInputBuilder("<insert the project path here>");
  inputBuilder.validateXmlInputFile("<insert xml file location>","<insert xml schema location>");
  
  // *NEW*
  final CustomPlanItProject project = new CustomPlanItProject(inputBuilder);
  
  MacroscopicNetwork network = (MacroscopicNetwork)
    project.createAndRegisterInfrastructureNetwork(Network.MACROSCOPIC_NETWORK);
  Zoning zoning = project.createAndRegisterZoning(network);
  Demands demands = project.createAndRegisterDemands(zoning, network);
  OutputFormatter outputFormatter = project.createAndRegisterOutputFormatter(OutputFormatter.PLANIT_OUTPUT_FORMATTER);

  TraditionalStaticAssignmentConfigurator ta = (TraditionalStaticAssignmentConfigurator)
    project.createAndRegisterTrafficAssignment(
      TrafficAssignment.TRADITIONAL_STATIC_ASSIGNMENT, demands, zoning, network);
 
  taBuilder.registerOutputFormatter(outputFormatter); 

  project.executeAllTrafficAssignments();
} catch (final Exception e) {
  // do something
}

TNTP input format

The TNTP input format is not officially supported. A skeleton implementation is available, see Github. Note that because the TNTP format is not unambiguous and therefore extensive user configuration on the TNTPInputBuilder is required to make it work for any project. In some cases will require actual coding to make it work or alternatively change the input format data itself.

Disclaimer: The current implementation is only tested on the Chicago sketch network as a demonstration. No guarantees can be given on it working for TNTP inputs deviating from this particular example.


try {

   // * NEW * explicitly provide mapping for column contents
   final Map<NetworkFileColumns, Integer> networkFileColumns = new HashMap<NetworkFileColumns, Integer>();
   networkFileColumns.put(NetworkFileColumns.UPSTREAM_NODE_ID, 0);
   networkFileColumns.put(NetworkFileColumns.DOWNSTREAM_NODE_ID, 1);
   networkFileColumns.put(NetworkFileColumns.CAPACITY_PER_LANE, 2);
   networkFileColumns.put(NetworkFileColumns.LENGTH, 3);
   networkFileColumns.put(NetworkFileColumns.FREE_FLOW_TRAVEL_TIME, 4);
   networkFileColumns.put(NetworkFileColumns.B, 5);
   networkFileColumns.put(NetworkFileColumns.POWER, 6);
   networkFileColumns.put(NetworkFileColumns.MAXIMUM_SPEED, 7);
   networkFileColumns.put(NetworkFileColumns.TOLL, 8);
   networkFileColumns.put(NetworkFileColumns.LINK_TYPE, 9);

   // * NEW * units
   final SpeedUnits speedUnits = SpeedUnits.MILES_H;
   final LengthUnits lengthUnits = LengthUnits.MILES;
   final CapacityPeriod capacityPeriod = CapacityPeriod.HOUR;
   final double defaultMaximumSpeed = 25.0 // in speed units

   // * NEW *
   final TntpInputBuilder tntpBuilder = new TntpInputBuilder(
   	"<network file location">, 
   	"<demand file location">, 
   	"<node coordinate file location - optional - >",
   	networkFileColumns, 
   	speedUnits, 
   	lengthUnits, 
   	capacityPeriod, 
   	defaultMaximumSpeed);
     
   // *NEW*
   final CustomPlanItProject project = new CustomPlanItProject(tntpBuilder);
  
   MacroscopicNetwork network = (MacroscopicNetwork) 
    project.createAndRegisterInfrastructureNetwork(Network.MACROSCOPIC_NETWORK);
   Zoning zoning = project.createAndRegisterZoning(network);
   Demands demands = project.createAndRegisterDemands(zoning, network);
   OutputFormatter outputFormatter = project.createAndRegisterOutputFormatter(OutputFormatter.PLANIT_OUTPUT_FORMATTER);

   TraditionalStaticAssignmentConfigurator ta = (TraditionalStaticAssignmentConfigurator) 
    project.createAndRegisterTrafficAssignment(
      TrafficAssignment.TRADITIONAL_STATIC_ASSIGNMENT, demands, zoning, network);
 
   ta.registerOutputFormatter(outputFormatter); 

   project.executeAllTrafficAssignments();
} catch (final Exception e) {
  // do something
}

Last modified January 1, 0001