Output examples

Examples on how to configure PLANit project outputs

Here we provide you with a number of examples to set-up your PLANit project outputs. There are two different aspects to configuring your output:

the output format
The output configuration

The output format determines how your results are persisted whereas the configuration drives what outputs are actually activated. In this section we provide examples for both

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 set up a traffic assignment, otherwise see Setting up a traffic assignment

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.

Below you will find examples regarding the output format

Example	Name	Description
1	Default output formatter	Simplest example of setting up your own output formatter
2	Multiple output formatters	Setting up multiple output formatters
3	Memory output formatter	Setting up and using a memory output formatter

Below you will find examples regarding the output configuration (independent of what output format is configured)

Example	Name	Description
4	General output configuration	Example of changing some general configuration options regarding output persistence
5	Output type configuration	Example of (de-)activating output types and configuring output properties on them

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

project: CustomPlanItProject
inputs: default PLANit XML input format
assignment: traditional static assignment

Minimum output format

Whenever you use a PlanItSimpleProject or a PlanItProject, the default PLANit output formatter is activated for you without any need for you to explicitly do so yourself.

The output format requires an OutputFormatter to be registered on the assignment. Output formatters can be created on the project level and then passed on to the assignments that want to use them. It is even possible to register more than one output formatter on any traffic assignment. In that case multiple copies of the output are generated in the different formats. If none are activated, the assignment will run but will not generate any output. In this basic example, we create the PLANit default output formatter on the project and activate it on the assignment.

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

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

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

Multiple output formatters

In this example we demonstrate that you can register multiple (different) output formatters on the same assignment. In this case we register the default output formatter as well as the memory based output formatter. The latter collects all results in memory for the user to access directly within their application

    try {
      final CustomPlanItProject project = new CustomPlanItProject(new PlanItInputBuilder("<insert the project path here>"));
     
      InfrastructureNetwork network =  
        project.createAndRegisterInfrastructureNetwork(Network.MACROSCOPIC_NETWORK);
      Zoning zoning = project.createAndRegisterZoning(network);
      Demands demands = project.createAndRegisterDemands(zoning, network);
      
      // *NEW*
      OutputFormatter defaultOutputFormatter = project.createAndRegisterOutputFormatter(OutputFormatter.PLANIT_OUTPUT_FORMATTER);
      OutputFormatter memoryOutputFormatter = project.createAndRegisterOutputFormatter(OutputFormatter.MEMORY_OUTPUT_FORMATTER);

      TraditionalStaticAssignmentConfigurator ta = (TraditionalStaticAssignmentConfigurator) 
        project.createAndRegisterTrafficAssignment(
          TrafficAssignment.TRADITIONAL_STATIC_ASSIGNMENT, demands, zoning, network);
      
      // *NEW*
      ta.registerOutputFormatter(defaultOutputFormatter);
      ta.registerOutputFormatter(memoryOutputFormatter); 

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

Memory output formatter

In this example we show how to use the memory output formatter. Results can be accessed after the assignment is complete and require the knowledge of the location of the various output properties that are assumed to be present (see output configuration examples on how to (de-)activate output properties). Since the output is highly configurable, collecting it requires a few additional steps to locate the correct entries:

Construct an iterator that iterates over the results for a particular mode, time period, iteration, and output type (here link)
Collect the position of the keys and values that you want to extract from the iterator position (here id (key), flow (value), and cost (value)
Loop over the entries and extract and cast the keys and values in the locations based on the unit/type of the output properties

Not we choose link as output type because it is activated by default. For other examples of other output types and their related output properties, please consult the examples reagrding the output configuration or the JavaDoc.

    try {
      final CustomPlanItProject project = new CustomPlanItProject(new PlanItInputBuilder("<insert the project path here>"));
     
      InfrastructureNetwork network =  
        project.createAndRegisterInfrastructureNetwork(Network.MACROSCOPIC_NETWORK);
      Zoning zoning = project.createAndRegisterZoning(network);
      Demands demands = project.createAndRegisterDemands(zoning, network);
      
      MemoryOutputFormatter memoryOutputFormatter = (MemoryOutputFormatter) project.createAndRegisterOutputFormatter(OutputFormatter.MEMORY_OUTPUT_FORMATTER);

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

      project.executeAllTrafficAssignments();
      
      // * NEW *
      MemoryOutputIterator outputIterator = memoryOutputFormatter.getIterator(
          network.modes.getFirst(), 
          demands.timePeriods.getFirst(), 
          memoryOutputFormatter.getLastIteration(), 
          OutputType.LINK);
      
      // * NEW *
      int idPosition = memoryOutputFormatter.getPositionOfOutputKeyProperty(OutputType.LINK, OutputProperty.LINK_SEGMENT_XML_ID);
      int flowPosition = memoryOutputFormatter.getPositionOfOutputValueProperty(OutputType.LINK, OutputProperty.FLOW);
      int linkSegmentCostPosition = memoryOutputFormatter.getPositionOfOutputValueProperty(OutputType.LINK, OutputProperty.LINK_COST);
      
      // * NEW *
      while(outputIterator.hasNext()) {
        outputIterator.next();
        long linkSegmentXmlId = (long)outputIterator.getKeys()[idPosition];
        Object[] values = outputIterator.getValues();        
        double linkSegmentFlow = (double)values[flowPosition];
        double linkSegmentCost = (double)values[linkSegmentCostPosition];
        LOGGER.info(String.format("link: %d with flow: %f and cost: %f", linkSegmentXmlId, linkSegmentFlow, linkSegmentCost));
      }
      
    } catch (final Exception e) {
      // do something
    }

General output configuration

The output configuration allows you to configure what outputs are persisted independently of how they are persisted. We distinguish between general configuration options provided via Outputconfiguration and more specific output configuration options that are grouped by type, e.g., link, od, path, etc.

In this example, we focus on the former, where change some basic configuration options across all outputs for a particular assignment

    try {
      final CustomPlanItProject project = new CustomPlanItProject(new PlanItInputBuilder("<insert the project path here>"));
     
      InfrastructureNetwork network =  
        project.createAndRegisterInfrastructureNetwork(Network.MACROSCOPIC_NETWORK);
      Zoning zoning = project.createAndRegisterZoning(network);
      Demands demands = project.createAndRegisterDemands(zoning, network);
      
      TraditionalStaticAssignmentConfigurator ta = (TraditionalStaticAssignmentConfigurator) 
        project.createAndRegisterTrafficAssignment(
          TrafficAssignment.TRADITIONAL_STATIC_ASSIGNMENT, demands, zoning, network);
                  
      ta.registerOutputFormatter(project.createAndRegisterOutputFormatter(OutputFormatter.PLANIT_OUTPUT_FORMATTER));
           
      // * NEW *
      ta.getOutputConfiguration().setPersistOnlyFinalIteration(false);
      ta.getOutputConfiguration().setPersistZeroFlow(true);
      
      project.executeAllTrafficAssignments();
    } catch (final Exception e) {
      // do something
    }

Output type configuration

The output configuration allows you to configure WHAT outputs are persisted independently from HOW they are persisted. We distinguish between general configuration options provided via Outputconfiguration and more specific output configuration options that are grouped by type, e.g., link, od, path, etc.

In this example, we explicitly de-activate the link outputs and then activate path outputs instead. We then add an output property to be included in the results for each path, namely its external mode id. This means that in the resulting CSV an additional column is included showing for each path the related mode’s external id (if any).

You can freely add and remove output properties, i.e., output columns, this way. Have a look at the JavaDocs to see which output properties are added by default for each output type.

Note: you can remove output columns, but it must remain possible to identify each result row uniquely. PLANit will verify this before running and if there is no option for a unique identification anymore an exception will be thrown

    try {
      final CustomPlanItProject project = new CustomPlanItProject(new PlanItInputBuilder("<insert the project path here>"));
     
      InfrastructureNetwork network =
        project.createAndRegisterInfrastructureNetwork(Network.MACROSCOPIC_NETWORK);
      Zoning zoning = project.createAndRegisterZoning(network);
      Demands demands = project.createAndRegisterDemands(zoning, network);
      
      TraditionalStaticAssignmentConfigurator ta = (TraditionalStaticAssignmentConfigurator) 
        project.createAndRegisterTrafficAssignment(
          TrafficAssignment.TRADITIONAL_STATIC_ASSIGNMENT, demands, zoning, network);
                  
      ta.registerOutputFormatter(project.createAndRegisterOutputFormatter(OutputFormatter.PLANIT_OUTPUT_FORMATTER));
      
      // * NEW *
      ta.deactivateOutput(OutputType.LINK);
      
      // * NEW *
      PathOutputTypeConfiguration pathOutputConfiguration = (PathOutputTypeConfiguration) ta.activateOutput(OutputType.PATH);
      
      // * NEW *
      pathOutputConfiguration.removeProperty(OutputProperty.RUN_ID);
      pathOutputConfiguration.addProperty(OutputProperty.MODE_EXTERNAL_ID);

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

Last modified January 1, 0001