Short Term Configuration - smart-fm/simmobility-prod GitHub Wiki

simrun_ShortTerm.xml is a configuration file specific to short-term. Users should supply the following settings in this file:

• Database/File from which the network/tripchain(agent) is loaded
• The road network configuration
• The order in which the agents are loaded from each sources (database/file/...)
• Communication settings information
• Path for the road network schema files
• Configuration parameters specific to different controllers (bus/amod/fmod)
• List of workgroups (thread types) and their properties
• List of vehicle types and their properties
• Settings for different sensors (loop detectors/segment travel time) and its outputs

This file consists of multiple sections:

This section contains the configuration for loading the road network and trip chains (agent data) from the database. The user can define multiple road network/trip chain configurations. Each configuration is grouped in a proc_map tag and given an ID.

<db_proc_groups>          
     <proc_map id="<proc_map_id>" format="<network_format>" >   
       <mapping name="<mapping_name>" procedure="<stored_procedure_name>" />      
     </proc_map>         
     ...      
     ...
</db_proc_groups>    

Under the proc_map tag, mappings related to the road network and agent data is defined. The agent data will be loaded from stored procedure with mapping name 'trip_chains'.

 <mapping name="trip_chains" procedure="get_trip_chains"/>

The stored procedure mappings for road network is explained here

This section contains configuration for different system properties.

The aura_manager_impl is used to specify the data structure used for aura manager. AuraManager is a SimMobility Short-Term component (spatial tree) which keeps track of the positions of agents during each frame tick.

<aura_manager_impl value="packing-tree"/>

SimMobility currently supports the following options:

1. rstar (R* Tree)
2. rdu (Used for benchmarking/research purposes)
3. simtree (SimTree)
4. packing-tree (R* Tree implementation from boost library which gives better performance)

The default value is rstar. If the boost version installed is > 1.56, packing-tree option should be used to get better performance

The load_agents is used to specify the order in which the agents are loaded.

 <load_agents order="database,drivers"/>

Following are options which can be specified in a comma separated list.

1. database: Load the agents from database through trip_chain stored procedure specified in proc_map section
2. drivers: Load the agents from XML files specified in tripFiles section

CommSim is an interface between a network simulator set-up and SimMobility Short-Term. The network simulator is built with ns-3 and android emulators.

 <commsim enabled="false">
      <min_clients value="1"/>
      <io_threads value="2"/>
      <hold_tick value="500"/>
      <use_ns3 value="true"/>
 </commsim>

• commsim: The settings related to the CommSim is enclosed with in this tag. To enable/disable CommSim specify true/false in the enabled tag
• min_clients: Minimum number of clients (android emulators) required to be connected before the simulation begins
• io_threads: Number of threads (parallel processes) for reading from android emulators
• hold_tick: The offset tick where the minimum number of client is checked
• use_ns3: Option to enable/disable ns-3 for communication between android emulators and SimMobility. If the option is false the messages will be transferred instantly between emulators and SimMobility, otherwise there will be a latency involved (which is more realistic)

The partitioning_solution_id is a property for SimMobility-MPI.

The network specifies the location from where the road network is loaded.

  <network>
       <network_source value="database"/>
       <network_xml_file_input value=""/>
       <network_xml_file_output value=""/>
       <network_database database="<db_id_from_databases_section>" credentials="<cred_id_from_credentials_section>" proc_map="<proc_map_id_from_db_proc_groups_section>"/>
  </network>

• network_source: Specify whether the road network is loaded from database or xml in value tag
• network_xml_file_input: If the network is loaded from xml, specify the path of road network input file in the value tag
• network_xml_file_output: If the network is loaded from xml, specify the file path where the network output is written in the value tag
• network_database: If the network is loaded from database, specify the database connection id, login credential id and procedure mappings id in database, credentials and proc_map tags respectively

This section is defined to quickly add configuration for small features.

  <generic_props>
        <property key="<key_name>" value="<value>"/>
        ...
        ...
  </generic_props>

Following are the settings added in this section

• buses_per_stop: Number of buses that can be accommodated in a bus stop

• intersection_driving_model: Specify the driving-model used in non-signalized intersection. Currently SimMobility supports two models, slot-based and conflict-based

  NOTE: Both, slot-based and conflict-based require the stored procedures for turnings and conflicts. If these are not specified, there is no intersection driving behaviour i.e. vehicles collide with each other in the intersection

This section contains the properties of different workgroups created in SimMobility. The settings are defined in the following format.

   <<workgroup_name> count="<number_of_workers>" granularity="<step_size_of_workgroup>"/>

• count: Specify the number of workers (threads) in this tag
• granularity: Step size at which the workgroup is processed. This should be multiple of base_granularity defined in simulation.xml

<workers>
     <person count="2" granularity="100 ms"/>
     <signal count="1" granularity="1 second"/>
     <intersection_manager count="0" granularity="500 ms"/>
     <communication count="0" granularity="100 ms"/>
</workers>

• person: Workgroup for processing person agents with roles (e.g. driver) and activities (e.g. wait)
• signal: Workgroup for processing traffic signals
• intersection_manager: Workgroup for processing intersection managers
• communication: Workgroup for processing communication simulator

This section helps specify the location of the lua scripts. It also allows one to specify the file that defines the model required by the simulator. The format for this section is as shown below

<model_scripts path="<relative_path_from_the_Basic_folder>" format="lua">
     <script name="logit" file="<file_defining_the_logit_model>"/> <!--The main logit code for multinomial and nested logit models-->
     <script name="pvtrc" file="<file_defining_the_route_choice_model>"/> <!--private traffic route choice-->	
     <script name="ptrc" file="<file_defining_the_public_transit_route_choice_model>"/> <!--public transit route choice-->
</model_scripts>

Using this, the user can define the types of vehicles to be used in the simulation. Following format should be used while defining the vehicles.

<vehicleTypes>
     <vehicleType name="<vehicle_type_name>" length="<length_in_meters>" width="<width_in_meters>" capacity="<num_capacity>"/>
     ...
     ...
</vehicleTypes>

SimMobility users can input the trip chains through xml files; these input files should be specified in this section.

<tripFiles>
    <tripFile name="<tripchains_name>" filename="<file_location>"/>
    ...
</tripFiles>

The trip chain files should be formatted as below:

<trips>  
    <trip>  
         <subTrip mode="<vehicle_type_name>" originNode="<origin_node_location>" destNode="<desitination_node_location>" time="<time_offset_in_ms_from_start_of_simulation>"/>
    </trip>
</trips>

This section contains the bus boarding/alighting characteristics and the walking speed of persons in different age group.

<person_characteristics>
     <person lowerAge="<from_age>" upperAge="<to_age>" lowerSecs="<min_time_taken>" upperSecs="<max_time_taken>" walkSpeed_kmph="walking_speed_in_kmph"/>
     ...
</person_characteristics>

The simulator takes a uniform distribution between lowerSecs and upperSecs, then assigns it as boarding/alighting time for the agents in lowerAge to upperAge age group.

Settings related to bus controller are defined in this section.

  <busController enabled="true" busline_control_type="headway_based"/>

• enabled: Enable/Disable the bus controller. If disabled buses will not be operated in simulation. If enabled, stored procedures pt_bus_dispatch_freq, pt_bus_routes and pt_bus_stops should be defined in the proc_map section

• busline_control_type: It is the control strategy for buses. This is used to control or avoid bus bunching where multiple buses were scheduled in same route around same time. Following are the options currently supported by SimMobility:

  1. headway_based
  2. evenheadway_based
  3. hybrid_based
  4. no_control

  The value headway_based is commonly used as the consecutive buses of the same line maintain a specific headway, hence avoiding bus bunching.

Defines the maximum number of passengers that a bus can contain at any given time.

<bus_default_capacity value="100"/>

Defines whether public transit is enabled. This means that a given person can complete their trip using public transportation such as bus or train. It can be enabled as shown below.

<public_transit enabled="true"/>  

If enabled, stored procedures required for public transit route choice must be defined as shown here

The configurations related to path choice/path set are defined in a separate configuration file. The path of this file is defined in this section

 <path-set-config-file value=<file-path> />

SimMobility uses historical travel time (link travel time) to compute the route choice during simulation. The average of time taken by vehicles crossing a link during the given interval is computed and stored in a file.

<travel_time_update interval= "300" alpha= "0.5" />

• interval: Travel time update interval. The unit is seconds
• alpha: Bias given to current simulation travel time vs the data already stored in database. The scale is from 0 to 1.

Settings to enable/disable AMOD (Autonomous Mobility On Demand) module while running the simulation

 <amodcontroller enabled="<true/false>"/>

###output_statistics: This section helps toggle the collection of certain outputs. It also allows the user to specify the location at which the output file must be saved. It contains the following sections:

Specifies the output file for information on the arrival times, dwell times and occupancy for every bus/train line for every stop in its route

<journey_time file="<file_name>"/>

Specifies the output file for information on the amount of time each person agent has waited at a particular bus stop or train station.

<waiting_time file="<file_name>"/>

Specifies the output file for information on the number of passengers waiting at each PT stop in every update interval.

<waiting_count file="<file_name>"/>

Specifies the output file for information on the travel time for each person for each public transit trip. It also includes the waiting time for Public Transit.

<travel_time file="<file_name>"/>

Specifies the output file for information on the PT statistics collected for every 5 minute interval of the simulation. This output is meant to be fed back into the supply.pt_stop_stats table to guide the route choices of subsequent simulations.

<pt_stop_stats file="<file_name>"/>

Loop detectors are the sensors that are placed in every signalized intersection to count the vehicles crossing an intersection. Settings related to these sensors are defined in this section

<loop-detector_counts frequency="900000" outputEnabled="true" file-name="VehicleCounts.csv"/>

• frequency: Interval at which the counter is reset. The unit is milli-seconds
• outputEnabled: If set true, the SimMobility will produce vehicle counts output for the signalized intersections
• file-name: File path where the output should be produced

This section contains the settings for measuring the road segment density (veh/km/lane)

<segment_density updateInterval="<user_defined_value>" outputEnabled="<true/false>" file-name="<file-path>"/>

• updateInterval: Interval at which the measurement is reset. The unit is milli-seconds
• outputEnabled: If set true, the SimMobility will produce the segment density outputs
• file-name: File path where the output should be produced

Settings related to assignment matrix generation is defined in this section

<assignment_matrix enabled="<true/false>" file-name="<file_path>"/>

• enabled: Set true to generate assignment matrix, otherwise set false
• file-name: File path where the assignment matrix output to be generated

SimMobility produces average travel time taken for a Origin-Destination pair. Settings related to this feature is defined in this section. The travel times are grouped based on the start time of the trip

<od_travel_time enabled="<true/false>" file-name="<file_path>" interval="<time_interval_in_ms>"/>

• enabled: Set true to generate OD travel time, otherwise set false
• file-name: File path where the OD travel time output to be generated
• interval: Interval at which the average time is calculated. The unit is milli-seconds

SimMobility produces average travel time taken for a vehicle to cross a road segment. Settings related to this feature is defined in this section

<segment_travel_time enabled="<true/false>" file-name="<file_path>" interval="<time_interval_in_ms>"/>

• enabled: Set true to generate segment travel time, otherwise set false
• file-name: File path where the segment travel time output to be generated
• interval: Interval at which the average time is calculated. The unit is milli-seconds